compat-eslint: factory DSL phase 1 — defaults / via-callback / whenAbsent + 16 shape migrations

[johnsoncodehk]

Why

Phase 1 of the 4-phase plan toward A3 root-cause termination. Extends the defineShape factory's DSL with capabilities that unlock medium-complexity LazyNode subclasses, then migrates a meaningful batch.

Each migrated shape moves from "hand-written subclass + switch case in convertChildInner (two places to keep in sync)" to "one declarative table entry — top-down getter and bottom-up dispatch read the same source". For these kinds, drift is structurally impossible.

What's here

Factory DSL extensions

Three new ShapeDef options:

Option	Use case	Replaces hand-written
defaults: Record<string, unknown>	Static field values that don't depend on the TS node (e.g. UnaryExpression.operator: 'void', ObjectPattern.decorators: EMPTY_ARRAY)	readonly x = '...' class fields
ShapeSlotDef.via: function	Custom converter for slots that route through helpers (convertTypeAnnotation, convertTypeArguments, convertTypeParameters) instead of the stock convertChild family	t ? convertX(t, this) : ... getter bodies
ShapeSlotDef.whenAbsent: 'null' | 'undefined'	Per-slot null-vs-undefined choice. Type-position slots (returnType, typeAnnotation) use 'undefined'; value slots default to 'null'	The : undefined arm of t ? ... : undefined

Backed by a SHAPE_UNSET sentinel so the cache distinguishes "not yet computed" from "computed and got null/undefined" — the existing ??= pattern in hand-written getters conflates the two.

16 new migrations

8 mechanical-with-defaults:

• AsExpression → TSAsExpression
• ExpressionStatement (with directive default)
• TypeQuery → TSTypeQuery
• NamespaceImport → ImportNamespaceSpecifier
• ObjectBindingPattern → ObjectPattern
• VoidExpression → UnaryExpression(void)
• DeleteExpression → UnaryExpression(delete)
• TypeOfExpression → UnaryExpression(typeof)

8 with type-position slots via custom converter:

• TypeReference (typeArguments via convertTypeArguments)
• ConstructorType (abstract from modifiers + 3 type slots)
• ModuleDeclaration (declare/global/kind from flags)
• EnumMember (computed from name kind)
• TypeAliasDeclaration (declare from modifiers)
• ImportEqualsDeclaration (importKind from isTypeOnly)
• IndexSignature (readonly/static from modifiers)
• PropertyAssignment (kind/method/optional/shorthand defaults + computed)

Each replaces a 5-30-line hand-written class + a switch case in convertChildInner with one defineShape({ ... }) entry.

Status

	Before this PR	After
SHAPES entries	30	46
Hand-written LazyNode subclasses	122	107
lib/lazy-estree.ts lines	~4900	~4700

15 net subclasses migrated this PR (one was an existing in-place edit that didn't move counts). Phase 1's target was 30-50 — falling short because most remaining hand-written classes need factory capabilities not yet added (synthetic intermediates, conditional getters, range mutation hooks, multi-field-to-single-slot mappings). Those are Phase 2/3.

What's NOT migratable yet

For the curious — what's blocking each remaining class category:

• Synthetic intermediates (JSX self-closing's openingElement, ChainExpression wrapping, ExportNamed/DefaultWrapping, TSTypeAnnotation, BindingAssignmentPattern): need a defineSynthetic registry. Phase 3.
• Conditional getter logic (Block.body's directive handling, MethodDefinition's value computation): need a via callback that can also read this (current via is pure (tsValue, parent) → result). Phase 2.
• Range mutation in constructor (some classes set range to include synthetic positions): need a constructor hook. Phase 2.
• Multi-field source (one ESTree slot computed from multiple TS fields): need source callback. Phase 2.
• Special-case dispatch (LiteralType's null special case, ObjectLiteralExpression's pattern-aware dispatch, ExportAssignment's helper): can't move to SHAPES because dispatch isn't pure-kind. Stay hand-written but get auto-registered in SYNTHETICS table in Phase 3.

Test plan

• pnpm build clean
• All 6 compat-eslint suites pass — predicate-coverage 152/152, scope-compat 24/24, lazy-estree (incl. bottom-up parity sweep + phantom-types invariant), ts-ast-scan, selector-analysis, compat-pipeline
• Self-lint clean: 6 packages, 0 messages