fix: exclude paths before resolving references

[jonluca]

Closes #429

Alternative implementation to #430.

Summary

• adds resolveExcludedPathMatcher(path, value) so callers can leave literal $ref data untouched before resolution fetches it
• evaluates root-relative logical occurrences independently across external fragments, internal aliases, canonical $id aliases, shared documents, cycles, and extended-reference merges
• reads each physical external document once while preserving the historical full-document $Refs inventory
• passes the current value to bundle/dereference matchers and checks direct children before accessing or transforming them
• retains the existing resolution path byte-for-byte when no resolution matcher is configured

API placement

The issue sketch places the callback at resolve.excludedPathMatcher. The resolve object is also an open string-keyed map of custom resolver plugins, so adding a function there widens every resolver entry to accept bare functions and weakens existing narrowing. TypeScript cannot subtract one literal key from a string index signature.

This implementation therefore uses the top-level resolveExcludedPathMatcher option. Passing the nested form at runtime throws an actionable error instead of being silently treated as a resolver plugin. The exported ExcludedPathMatcher type is shared by resolution, bundling, and dereferencing.

Verification

• pnpm build
• pnpm typecheck (library plus consumer-facing option fixtures)
• pnpm lint
• Node suite: 78 files, 557 passed, 6 skipped
• Browser suite: 75 passed, 3 skipped files; 518 passed, 20 skipped
• focused exclusion suite: 32 passed
• pnpm exec oxfmt --check "**/*.{js,jsx,ts,tsx,har,json,css,md}"
• git diff --check

The typecheck is also added to CI so the resolver-map regression remains covered.

[coveralls]

Coverage Report for CI Build 32931149273

Coverage decreased (-0.4%) to 89.447%

Details

• Coverage decreased (-0.4%) from the base build.
• Patch coverage: 24 uncovered changes across 1 file (271 of 295 lines covered, 91.86%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
lib/resolve-external/with-matcher.ts	273	249	91.21%
Total (6 files)	295	271	91.86%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1803
Covered Lines:	1648
Line Coverage:	91.4%
Relevant Branches:	1504
Covered Branches:	1310
Branch Coverage:	87.1%
Branches in Coverage %:	Yes
Coverage Strength:	156565.95 hits per line

---

💛 - Coveralls