feat: add $dynamicRef / $dynamicAnchor schema resolution for OpenAPI 3.1

[aqeelat]

Closes #3886

What changed

• spec-types: Add $dynamicRef, $dynamicAnchor, $defs to JSON Schema 2020-12 type definitions
• IR types: Add typeParams and typeArgs fields to IRSchemaObject
• SchemaState: Add dynamicScope and typeParams fields for dynamic anchor → type ref propagation and template parameter tracking through the parser
• dynamicRef.ts module (new file):
  • buildDynamicScope() — builds dynamic scope from own $dynamicAnchor and $defs bindings
  • buildCurrentDynamicScope() — merges inherited + current scope; current scope wins on shadowing
  • getTemplateParams() — detects generic template schemas by finding $defs entries with $dynamicAnchor but no $ref
  • buildGenericRef() — constructs IR nodes with $ref + typeArgs for generic type references; preserves null from nullable schemas
  • anchorToParamName() — converts anchor names to valid TypeScript identifiers via toCase(anchor, 'PascalCase') + ID_Start/ID_Continue sanitization
  • materializeDynamicRefBinding() — materializes inline $dynamicRef bindings
  • resolveDynamicRef() — resolves a $dynamicRef string against the current dynamic scope
  • shouldInlineDynamicRefTarget() — determines when a $ref target should be inlined
• schema.ts: New $dynamicRef dispatch branch in schemaToIrSchema() — resolves through dynamic scope (recursive/concrete cases) or as a type parameter reference inside generic templates; parseRef() updated to inline dynamic ref targets when scope dictates
• TypeScript visitor: Updated intercept to handle #typeParam/ refs (type parameters) and $ref + typeArgs (generic references)
• TypeScript export: Updated exportAst to emit .generic() on type aliases with type parameters
• Tests: 815-line unit test suite for all dynamicRef.ts helpers + 3 integration test fixtures with snapshots (petstore showcase, external-ref, scope-isolation)

Supported patterns

Pattern	Result
Self-referential $dynamicAnchor (e.g. BaseCategory.children)	Recursive concrete type via materialization (was Array<unknown>)
Generic template via $defs (e.g. PaginatedTemplate<ItemType>)	Generic type alias with type parameters
Bound generic usage (e.g. PaginatedUserResponse)	Generic reference PaginatedTemplate<User>
Nullable bound generic (e.g. type: ['object', 'null'] + $defs)	Union with null preserved: PaginatedTemplate<User> | null
Recursive generic reference (e.g. ShelterFolder = ShelterFolderTemplate<ShelterFolder, ShelterResource>)	Circular generic reference preserved correctly
Inline route-response $dynamicRef bindings	Resolved with concrete types (was unknown)
Shadowed dynamic anchors (inner scope overrides outer)	Innermost binding wins per JSON Schema 2020-12 dynamic scope rules
Non-identifier anchor names (e.g. item-type)	Sanitized to valid TypeScript identifiers (ItemType)

Unsupported (falls back to unknown)

Pattern	Reason
External $dynamicRef (e.g. other.json#node)	The schema bundler only resolves $ref URIs — external files referenced by $dynamicRef are never fetched. #3902
Ambiguous $dynamicAnchor (multiple same-named anchors)	Static analysis cannot determine which schema

Limitations

• Shared component schemas with endpoint-specific bindings: Each schema in components.schemas is generated once with a single scope. If the same named component is referenced by multiple endpoints that each provide different $defs bindings, only one binding applies. The common pattern — putting $defs bindings on inline response schemas — works correctly.

Design

• Two-path resolution — recursive/concrete $dynamicRef patterns are resolved via dynamic scope materialization (no plugin changes needed). Generic/template $dynamicRef patterns are preserved as TypeScript generics through IR typeParams/typeArgs fields with TypeScript visitor support.
• No config flag — purely additive. Only triggers when $dynamicRef is present in the spec. Current behavior for such specs is unknown; any improvement is strictly better.
• Plain-name anchors only — $dynamicRef values containing / (JSON pointer fragments) are not resolved.
• type aliases for generics — Generic templates use type aliases (not interface) since ts-dsl already supports generics on aliases and no declaration merging is needed on generated types.
• Type parameter names — Derived from anchor names via toCase(anchor, 'PascalCase') and then sanitized against JavaScript ID_Start/ID_Continue rules to ensure valid TypeScript identifiers (e.g., item-type → ItemType, folderType → FolderType).
• Dynamic scope shadowing — Current/inner scope bindings override inherited/outer scope bindings, matching JSON Schema 2020-12 dynamic scope resolution semantics.