fix: resolve dollar-ref chains and disambiguate component sections

[MaxMichel2]

Summary

Stacked on #126 (PR chain: #123 → #124 → #127 → #128 → #129 → #126 → this) — merge in order.

OpenApiParser.resolveRef keyed resolved $ref targets by a fragment's trailing name segment only, ignoring which components.<section> it actually named, and followed a $ref chain exactly one level deep (a resolved entry's own $ref, if any, was not followed further). Real specs' components sections cross-reference and chain more than this parser could handle — this is a prerequisite for #82/#84 (schema synthesis), which will need to resolve $ref chains through components.schemas the same way.

What changed

• OpenApiParser.resolveRef (private, inside ParseContext): now takes an explicit section parameter ("parameters"/"responses"/"examples"/"headers") and validates a fragment's declared section against it — a $ref naming an unexpected section is rejected with a clear error instead of being silently resolved against whatever map the call site happened to expect, so a same-named entry in a different section can never be conflated with the one actually referenced.
• Converted from a single lookup into a loop that keeps resolving as long as a resolved entry itself declares a $ref (via a new refOf parameter), until a non-ref entry is reached — a $ref chain is now followed to completion instead of stopping after one hop.
• Cycle guard: a visited: MutableSet<Pair<OpenApiDocument, String>> tracks every (document, fragment) hop; revisiting one throws a clear IllegalStateException instead of looping forever.
• Updated all four call sites (resolveParameter, and the response/example/header refs inside resolveResponseIndex/resolveHeaders) and the class-level KDoc's "Scope decisions" section to match.
• docs/modules/networkmock-core.md's "$ref resolution" section updated — it documented the now-fixed "one level deep" limitation.

Public API

None — the openapi package stays internal (see #73's pure-seam requirement). No api.txt diff.

Tests

Added to MockConfigRepositoryTest.kt, following the existing $ref test fixtures' style:

• `dollar-ref naming the wrong components section is rejected even if a same-named entry exists there` — a response $ref pointing at components/parameters/... instead of components/responses/..., with a same-named entry in both sections, now fails clearly instead of resolving against whichever map the call site expected.
• `local dollar-ref chain of two hops resolves to the final non-ref entry` — A → B → literal content.
• `cyclic dollar-ref chain fails clearly instead of hanging` — A → B → A.

Verification

.\gradlew.bat detektFull -Pandroidx.baselineprofile.skipgeneration
.\gradlew.bat testAndroidHostTest -Pandroidx.baselineprofile.skipgeneration
.\gradlew.bat :konsist:test -Pandroidx.baselineprofile.skipgeneration

All green, including a full repo-wide testAndroidHostTest run to confirm no fallout outside the networkmock modules.

🤖 Generated with GitHub Copilot

[Momik-jpg]

Reviewed the diff at 4666236. The new section check still only inspects the final two fragment segments. For example, a response ref #/not-components/responses/UserOk (or #/responses/UserOk) passes actualSection == "responses" and resolves components.responses["UserOk"], even though the pointer does not identify that location.

Could you validate the complete supported fragment shape components/<expected-section>/<name> before the lookup, and add a regression case using an invalid prefix with an existing same-named response? The current wrong-section test does not exercise this path.

CI checks are green at this head; this finding is from source inspection, not a local runtime reproduction.

[MaxMichel2]

Hey @Momik-jpg!

Thanks for taking the time to identify this. Indeed, the specification was not 100% respected... I've pushed a new commit that should hopefully fix this.

If not, what we'll do is merge the pending PRs and that should allow you to contribute a fix that fits your needs better :D

[Momik-jpg]

Thanks! I reviewed ead88d9: it fixes both malformed-fragment cases, and CI is green.

I found another issue with external reference chains: loadExternalDocument always uses the original spec’s baseDir.

For example, specs/api.json references ./shared/a.json#/components/responses/A. If A then references ./b.json#/components/responses/B, the parser loads specs/b.json instead of specs/shared/b.json.

Could you track each document’s source path, resolve each hop relative to that document, and add a regression test crossing directories?

This finding is from source inspection; I haven’t reproduced it locally.