Skip to content

fix(ref-resolver): isolate concurrent root back-references - #3054

Open
QinXi-ai wants to merge 1 commit into
stoplightio:developfrom
QinXi-ai:fix-2640-deterministic-external-refs
Open

QinXi-ai wants to merge 1 commit into
stoplightio:developfrom
QinXi-ai:fix-2640-deterministic-external-refs

Conversation

@QinXi-ai

Copy link
Copy Markdown

Fixes #2640.

Summary

  • isolate cached root runners when external documents reference the root document concurrently
  • retain the shared URI cache and dependency graph for external-document de-duplication and source attribution
  • add deterministic file-system regression coverage plus browser-compatible HTTP coverage for repeated multi-file root back-references

The archived json-ref-resolver dependency stores the mutable depth-zero root runner directly in its shared URI cache. External documents that point back into the root retrieve that same runner, and Promise.all then re-enters resolve on it concurrently. Those calls overwrite the runner source nondeterministically, leaving raw $ref objects in random path documents. The new cache snapshots the original root source and returns an isolated runner only for this direct root cache hit; ordinary memoized external lookups remain unchanged.

Checklist

  • Tests added / updated
  • Docs added / updated (not applicable; no user-facing API or configuration change)

Does this PR introduce a breaking change?

  • Yes
  • No

Validation

  • corepack yarn build
  • corepack yarn lint: 0 errors; 40 existing warnings
  • full Jest run: 202 suites passed, 1992 tests passed, 1 skipped
  • focused Edge/Karma regression: 1 passed
  • linked reproduction with the locally built CLI: 100/100 runs produced only the expected oas3-api-servers warning

Full Edge/Karma execution reached 1824 passing tests; 60 existing ruleset-migrator cases failed because their shared memfs fixture directories were absent. The new regression passed independently. The standalone binary build could not fetch the pkg Node 24 base binary or Node source archive in this environment, so the binary-backed harness was not available.

@QinXi-ai
QinXi-ai requested a review from a team as a code owner August 29, 2026 08:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Lots of $ref to other files leads to random errors due to unprocessed $ref targets

1 participant