TL;DR — Resolves JSON Schema 2020-12 $dynamicRef / $dynamicAnchor in the OpenAPI 3.1 parser so recursive trees and generic pagination templates produce concrete types instead of unknown. The fix is purely additive — it only triggers when $dynamicRef is present.

Key changes

• Add dynamicScope to SchemaState — anchor name → resolved $ref map, propagated through the parser per JSON Schema dynamic-scope rules.
• buildDynamicScope() — scans the current schema's own $dynamicAnchor and its $defs for anchor bindings.
• $dynamicRef dispatch in schemaToIrSchema — resolves the anchor through the active scope to a synthetic $ref, falling back to unknown when unresolved.
• materializeDynamicRefBinding() — when a schema has both $ref and a $defs binding, the referenced template is inlined with the caller's scope so the resulting type isn't a stale alias.
• $dynamicAnchor-aware inlining inside parseRef — when the referenced component declares a matching $dynamicAnchor, its body is re-parsed under the caller's scope rather than emitted as a name ref.
• 6 fixtures + snapshots covering recursive trees, generic pagination (named and inline-route), nested workspace resources, scope isolation, external refs, and non-identifier component keys.

_{Summary ｜ 25 files ｜ 4 commits ｜ base: main ← feat/dynamicref-support}

Inline $defs bindings without $ref are silently dropped

Before: an unsupported, undocumented edge case.
After: still unsupported, but the dropping is silent — buildDynamicScope only records bindings whose value is {$dynamicAnchor, $ref}. Inline schemas ({$dynamicAnchor: itemType, type: object, properties: {...}}) are valid JSON Schema 2020-12 bindings but won't enter the scope.

This is a real-world pattern (you don't always factor your bound schema out into components.schemas). Either widen the binding shape to accept inline schemas (materialize them as anonymous IR schemas), or document the limitation alongside the existing inline-route caveat.

packages/shared/src/openApi/3.1.x/parser/schema.ts

PR description has drifted from the implementation

Before: description advertises "Sibling scope — unique anchor" with BaseFolder.shortcuts → Array<BaseResource> and says the inline paginated-response fixture still produces unknown items.
After: commit cb35873 (fix: avoid sibling dynamic ref bindings) removed sibling-scope resolution, so the nested-workspace-resources snapshot now shows shortcuts: Array<unknown>. Meanwhile, the paginated-response snapshot DOES resolve inline-route bindings (the 200 response is a concrete object with items: Array<User>), so the "Limitations" bullet about it is stale too.

Worth syncing the PR body and the supported-patterns table with what actually ships — otherwise reviewers and downstream users will be misled about which patterns work.

$dynamicRef anchor parsing is permissive

Before: N/A (new code).
After: schema.$dynamicRef.startsWith('#') ? slice(1) : full string. For a JSON-pointer-form dynamic ref like #/defs/x, the slice yields /defs/x which never matches a scope key and falls through to unknown. Functionally fine, but the heuristic conflates plain-name anchors with JSON pointers.

Tightening to "starts with # and contains no /" would make the intent explicit and the failure mode (e.g. logging an unsupported form) easier to diagnose later.

packages/shared/src/openApi/3.1.x/parser/schema.ts

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

TL;DR — Adds resolution for JSON Schema 2020-12 $dynamicRef / $dynamicAnchor in the OpenAPI 3.1 parser, with the resolution happening in the IR before any plugin runs. Recursive $dynamicRef, generic templates via $defs bindings, and scope isolation between sibling schemas are all covered by integration snapshots, and the new helpers in dynamicRef.ts are unit-tested.

Key changes

• Extend SchemaState with dynamicScope — new field carrying the active anchor-to-$ref map through recursion, with the parent circularReferenceTracker Set intentionally shared and dynamicScope always cloned per call.
• New dynamicRef.ts parser module — buildDynamicScope, buildCurrentDynamicScope, resolveDynamicRef, materializeDynamicRefBinding, shouldInlineDynamicRefTarget cleanly separate the dynamic-scope logic from schema.ts.
• schemaToIrSchema dispatch — handles $dynamicRef by rewriting it to a synthetic $ref (when resolvable) or falling back to unknown; materializes {$ref, $defs} template instantiations inline so generic wrappers emit concrete types.
• parseRef inlining — when a target component carries $dynamicAnchor and the caller's scope binds it elsewhere, the target is parsed inline rather than emitted as a named alias.
• Spec-types — adds $defs, $dynamicAnchor, $dynamicRef to the 2020-12 JSON Schema definitions.
• Specs, snapshots, docs, changeset — 6 new spec fixtures + snapshots covering recursive, generic binding, paginated, scope isolation, external ref, and non-identifier keys; user-facing docs under the TypeScript plugin page.

_{Summary ｜ 29 files ｜ 6 commits ｜ base: main ← feat/dynamicref-support}

Resolution model: IR-level rewrite, no plugin changes

Before: $dynamicRef was unknown to the parser; downstream plugins saw unknown or stale type aliases.
After: Dynamic scope is computed and consumed entirely in the 3.1 parser, emitting either a synthetic $ref, an inline materialization, or unknown — plugins are unaffected.

The dispatch order in schemaToIrSchema is materializeDynamicRefBinding → $ref → $dynamicRef → other keywords. Materialization fires only when all four guards hold (top-level component target, $ref + $defs, $defs carries an anchor+$ref binding), and unresolved $dynamicRef falls back to parseUnknown rather than leaking the raw keyword.

packages/shared/src/openApi/3.1.x/parser/schema.ts · packages/shared/src/openApi/3.1.x/parser/dynamicRef.ts

Scope shape and shared mutable state

Before: schemaToIrSchema mutated the caller's state directly, with $ref stashed/restored around recursive calls.
After: Every entry into schemaToIrSchema constructs a fresh currentState (spread of parent + freshly merged dynamicScope), but the circularReferenceTracker Set is shared by reference so cycle detection still spans the whole tree.

The split — clone dynamicScope per call, share circularReferenceTracker by identity — is the right call: dynamic scope is lexically inherited (children inherit, siblings do not), while cycle detection is structurally global. The existing state.$ref and state.inAllOf mutate/restore patterns in parseRef and parseAllOf remain balanced because the wrapping is shallow and stash-restore happens on the same object that was mutated.

packages/shared/src/openApi/shared/types/schema.ts

Test and snapshot coverage

Before: No $dynamicRef fixtures; recursive schemas degraded to Array<unknown> and generic templates degraded to type aliases.
After: 6 integration fixtures plus a 500-line unit-test file exercise each helper independently and assert the snapshot shape end-to-end.

The scope-isolation snapshot (unboundItem: unknown alongside boundItems: Array<User>) is the most important one — it proves the per-call dynamicScope clone does its job. The recursive-category snapshot confirms BaseCategory.children: Array<BaseCategory> resolves through shouldInlineDynamicRefTarget's self-reference guard. The BaseResource = Document | unknown and BaseFolder.shortcuts: Array<unknown> outputs in the nested-workspace snapshot are the expected "ambiguous anchor → unknown" fallback documented in the plugin page.

packages/shared/src/openApi/3.1.x/parser/__tests__/dynamicRef.test.ts · packages/openapi-ts-tests/main/test/3.1.x.test.ts

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}