Release Candidate Timeline

[shayanhabibi]

Reader/Encoder

• Create a series of tests to green-flag the capacity to read files without dangling references #9

It is difficult to create valuable tests without a generator; type keys are not guaranteed to be consistent between runs by the typescript compiler, even if they usually are (so long as no condition in the files changes).

We track diagnostic information on dangling references and absent values; this is satisfactory for the reader in isolation.

Decoder

• Provide public api configuration or documentation. #10

Generator

• Support overloads in the hashkey generation and tabulation
• Provide public api configuration or documentation. #10
• Relevant issues from Glutinum to be considered #6

---

Documentation can be lacking prior to a release candidate, but most be detailed in full prior to a release.

[shayanhabibi]

Status Report — Release Candidate Timeline

Completed since last update

#1 (Overload duplicate resolution) — Closed via #7. IOverloadable marker interface and TsOverloadableConstruct<'T> (NoOverloads | Overloaded Set) are now part of the schema. The reader's post-traversal pipeline merges overloadable duplicates (FunctionDeclaration, Method, Constructor, ConstructSignature, CallSignature) by TypeKey before conflict resolution runs. Priority ordering is DeclarationPosition > Symbol > AliasSymbol > Id.

#3 (TypeParameter identity loss) — Closed. TsTypeParameter is now emitted with its SelfKey: TypeKey inline, preserving identity for downstream references without losing structural equality.

#12 (Members silently dropped) — Closed via PR #12. mergeMembersIntoWinner now runs as a fourth pipeline phase (after sortResultGroups and mergeOverloads, before filterConflictDuplicatesOnly). For Interface/Class duplicate groups it appends all unique members from non-winner entries into the winner node. Root cause was an && result.Identity.IsDeclarationPosition guard that incorrectly excluded non-DeclarationPosition identities from member merging even when the nodes were structurally Interface/Class. Author correction: the root cause was due to resolveToMember conditionally pushing tags to the stack on a .IsVisited condition instead of .IsUnvisited

---

In progress / remaining

Reader / Encoder — #9 (Green-flag test suite)
A Fable/Mocha test harness now exists in tests/Xantham.Fable.Tests (npm test). Current fixtures cover member merging (merge.d.ts), single extension (extends.d.ts), and multiple extension of the same interface (multiple-extends.d.ts). The pipeline phases are exposed via an Internal module so tests can drive individual stages directly. Coverage is still shallow — overload variants, conditional types, and mapped types have no automated assertions yet.

Generator — Overload support in hash-key generation and tabulation
TsOverloadableConstruct<'T> is plumbed through the schema and decoder but the SimpleGenerator renderers have not been updated to enumerate overload variants when generating F# member signatures or computing hash keys. This needs to be addressed before the generator output is correct for any type that has overloads.

Generator — #6 (Glutinum issues)
Four items remain open:

• FunctionDeclaration overload with FunctionType as argument should mangled the generated delegate glutinum-org/cli#209
• Invalid F# code generated when extending Errors glutinum-org/cli#165
• Detect tagged type glutinum-org/cli#164
• Transform methods with union type as arguments to overloaded methods glutinum-org/cli#29

glutinum-org/cli#208 is already resolved.

Decoder / Generator — #10 (Public API and documentation)
No public API surface has been stabilised or documented. This is a pre-release blocker per the issue description.

---

Blockers / open questions

• The merge-overloads branch raises a question left in PR Merge overloadable constructs (Fix #1 ) #7: should overload merging be restricted to entries whose guards originate from a DeclarationFile identity? Currently it applies to all duplicate TypeKey groups regardless of how the identity was established. Worth resolving before the schema is considered stable.
• Heritage clause key generation is currently commented out in Reading/Prelude.fs to suppress [MISSREF] false positives. Heritage nodes that generate keys with no corresponding builder create noise in diagnostics. Need a clean suppression strategy (e.g. a dedicated heritageCache distinct from signalCache) before this can be re-enabled.
• Test coverage (Create a series of tests to green-flag the capacity to read files without dangling references #9) is growing but still far from comprehensive — the most significant confidence gap before a release candidate.

---

Authored by Claude Code