compat-eslint: KnownEstreeType union — compile-time gate against phantom types

[johnsoncodehk]

Why

The bug class fixed by PR #88 — phantom ESTree types like 'TSJsxAttributes' slipping through hand-written subclasses — was caught by runtime tests. PRs #88 and #89 reduced the surface but the test gate remained the only line of defence: any future subclass could still declare readonly type = 'X' as const for an X that doesn't exist in typescript-estree's spec, and it'd compile fine.

This PR closes that hole at the type level. Every concrete LazyNode subclass's type literal must now be a member of KnownEstreeType — a string-literal union enumerating the ~135 ESTree types lazy-estree is allowed to produce. Adding a new shape requires editing the union first (explicit, reviewable). Phantom types are now a compile error, not a silent runtime bug.

The gate caught one already

When the constraint was added on the existing codebase, TypeScript immediately flagged AccessorProperty on PropertyDefinitionNode's type union — exactly the kind of "obscure type literal not in spec" that the gate exists to catch. (Turned out to be a real ESTree type; added it to the union.) Validates the design: had this gate existed before PR #88, the original 'TSJsxAttributes' regression would have failed at pnpm build instead of needing a runtime parity test to surface.

What's constrained

abstract class LazyNode {
  abstract readonly type: KnownEstreeType;  // ← was: string
  ...
}

interface ShapeDef<TsT extends ts.Node = ts.Node> {
  type: KnownEstreeType;  // ← was: string
  ...
}

class TypeKeywordNode extends LazyNode {
  readonly type: TypeKeyword;  // ← was: string; 13-entry subset
  constructor(type: TypeKeyword, ...);
}

KnownEstreeType is built from typescript-estree's published node-type list:

• 70 core ESTree (Identifier, BlockStatement, …)
• 15 JSX (JSXAttribute, JSXOpeningElement, …)
• 50 TS-prefixed composite (TSAsExpression, TSTypeReference, …)
• 13 TS keyword (TSAnyKeyword, TSStringKeyword, …)

GenericTSNode is the deliberate phantom-output safety valve. Its type is dynamic ('TS' + ts.SyntaxKind[kind]) and casts as KnownEstreeType — most produced types ARE in the union (TSEnumDeclaration, TSImportType, etc.), but some (TSJsxAttributes, TSEndOfFileToken) are not. The runtime phantom-types invariant in lazy-estree.test (already in master) asserts these never reach a position rules can observe — they exist only as transient walk-up objects before being shadowed by a real subclass. The compile-time gate + runtime invariant together cover the whole drift surface.

Bug class status after this PR

Bug	Surface
Subclass declares phantom type literal	compile fail ✓
Factory defineShape declares phantom type	compile fail ✓
TypeKeywordNode constructed with non-keyword	compile fail ✓
GenericTSNode produces phantom transiently	runtime invariant test catches downstream observability ✓
Subclass introduces synthetic intermediate without registering in navigation tables	runtime parity sweep catches (not yet compile-time — Phase 3)

What's NOT in this PR

• Phase 3 (synthetic-intermediate registry) — would extend the gate so even GenericTSNode-style dynamic types must be enumerated, AND every synthetic-creating hand-written subclass declares its synthetics in a registry that the navigation tables auto-derive from. Separate branch.
• More shape migrations — none here. The phase 2 plan included "conditional getter via callback that reads this" + "range mutation hook" capabilities, but the audit showed the marginal class is increasingly complex; pivoted this branch to the higher-leverage architectural gate. Future migrations land as separate small PRs as needed.

Test plan

• pnpm build clean (compile-time gate active)
• All 6 compat-eslint suites pass: predicate-coverage 152/152, scope-compat 24/24, lazy-estree (incl. bottom-up parity sweep + phantom-types invariant + 5 new whenAbsent / generic-typed migration tests from compat-eslint: factory DSL phase 1 — defaults / via-callback / whenAbsent + 16 shape migrations #89), ts-ast-scan, selector-analysis, compat-pipeline
• Self-lint clean: 6 packages × 51 files × 0 messages
• No new runtime cost — KnownEstreeType is a TS-only construct, erased at compile time