FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

flatten: document how recursion survives flattening by reuvenharrison · Pull Request #1244 · oasdiff/oasdiff · GitHub

flatten: document how recursion survives flattening - #1244

Open
reuvenharrison wants to merge 2 commits into
mainfrom
flatten-cycle-docs
Open

flatten: document how recursion survives flattening#1244
reuvenharrison wants to merge 2 commits into
mainfrom
flatten-cycle-docs

Conversation

Copy link
Copy Markdown
Collaborator

Docs-only follow-up to the #1233/#1240/#1243 sequence, closing the gap between what the code does and what its overviews say:

  • docs/ALLOF.md (user-facing): a "Recursive schemas" section explaining why flattened output can contain components the user did not declare (AllOfMergedN) and residual allOf entries around recursion points — both are how recursion, which only $ref can express, survives flattening. Written for a visitor reading cold; no internal vocabulary.
  • flatten/allof/doc.go: the package overview gains the invariant (every cycle-closing edge carries a $ref: kept, named, or hoisted, deterministically) and the Merge-vs-MergeSpec split (only the spec-level entry can name cycles, so only it guarantees marshalable output for recursive inputs).
  • MergeSpec's doc comment now states both halves of its job — merging and naming the anchored cycles.

The function-level comments from the sequence (anchored, splitInFlight/anchorInFlight, nameAnchoredCycles, the diff-side guard and cut-counter comments) were audited and already state the model correctly; no changes there.

The package doc and the public allOf guide now state the invariant the
merge maintains (every cycle-closing edge carries a $ref, kept, named
via a component, or hoisted as AllOfMergedN) and what a user may see in
flattened output (generated components, residual allOf around
recursion points). MergeSpec's doc says it names the anchored cycles,
which is the half of its job the comment omitted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QDvUFsg5nu1NBWQffErGDw

codecov-commenter commented Sep 13, 2026
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.27%. Comparing base (63632bf) to head (e33d1b3).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1244   +/-   ##
=======================================
  Coverage   92.27%   92.27%           
=======================================
  Files         345      345           
  Lines       14336    14336           
=======================================
  Hits        13229    13229           
  Misses       1107     1107           
Flag Coverage Δ
unittests 92.27% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
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.

2 participants


Back | FazBrowse Home | New Git URL