Docs/quirks register cleanup - #68
Merged
Merged
Conversation
…gister
An audit of the planning trackers found the quirk records disagreeing with the
code in both directions: entries documented as open had been fixed by a
different stream, and one entry documented as fixed was not. The cause is
structural — three registers with no cross-links (the Q-series, the D-series,
and each package's README §quirks-open), so an item logged in one and fixed via
another was never updated.
The planning side now has a single live register (`.claude/plans/quirks-open.md`,
with the historical ones archived); this is the repo side of the same cleanup.
schema/README.md — two entries verified fixed, moved to §quirks-resolved:
- "Named-strfmt + swagger:model" claimed a field/definition mismatch
({string, format} at the field, a struct walk at the definition). The golden
enhancements_named_struct_tags-ref.json now shows PhoneNumber as
{type: string, format: phone} with Contact.phone a $ref to it. Fixed by the
F-series pass (8e20d2f, F1) — not by the attempt the entry described, which
was reverted, hence nobody updated it.
- "Cross-package definition-name collisions silently overwrite" was fixed by
the name-identity work: definitions are keyed by a compiler-unique DefKey
while building and deconflicted by the reduce stage, with a
scan.renamed-definition Hint. Goldens show AWidget/BWidget deconfliction.
The third entry — a field-level `enum:` override discarding the type's
x-go-enum-desc — is real and still present (probed: no diagnostic fires for the
override case; only the no-consts case warns). It is condensed here and its
design question moved to the feature that owns it, since whether the per-value
docs should be filtered through or dropped with a Hint depends on what an
override is meant to mean. features/enum-richer-values.md §1.2b now carries it,
correcting that plan's own claim that the quirk was closed with "nothing
remains to do" — half of it was (the desc is no longer left stale), half was not
(the strip is silent and lossy).
routebody/README.md — the "no column tracking" caveat now names the feature that
owns it (column-precision-unicode, an LSP prerequisite) rather than sitting
loose; the two column issues touch the same Line.Pos contract and want doing
together.
Each §quirks-open section gains a pointer to the project-wide register, so a
reader knows the package caveats are not the whole picture.
Also: repoint the five references to quirks-F-series-fix.md at its archived
path, and drop a stale warning in docs/examples/shaping/aliases/aliases.go which
still told readers that swagger:model type aliases "currently hang the scanner —
until F9 is fixed". F9 was fixed and is locked by TestQuirk_AliasModelNoHang
across all three alias modes; the example keeps using the dissolve case, but no
longer implies the other modes are unsafe.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…g them The "Alias rendering" how-to described the first-class-alias modes in prose and sent the reader to a fixture directory for the actual shapes, because the witness could not exercise them: annotating a Go type alias with swagger:model used to hang the scanner (quirk F9). That was fixed and locked (TestQuirk_AliasModelNoHang, all three alias modes), so the guide can now show real output. New witness docs/examples/shaping/aliases-firstclass: one package (Amount, the annotated alias Fee = Amount, and Receipt referencing the alias) scanned three times, once per mode, each emitting the whole definitions map as a golden. The guide compares default vs RefAliases side by side and shows TransparentAliases below, so what the reader sees is what the scanner produced. Writing it against real output corrected the page. It said TransparentAliases makes "aliases dissolve to their target everywhere, overriding the per-declaration annotation" — only half true. The option governs USE SITES: with ScanModels, a swagger:model-annotated alias is still published as its own definition, and merely stops being referenced by anything. The page now says so, and points at PruneUnusedModels for dropping the orphan. The test locks that behaviour rather than the summary of it. Also adds the guidance the old page lacked: prefer RefAliases over the default when the alias is genuinely a synonym, since the default emits a copy of the target that drifts as soon as the target changes. The dissolve example keeps its own witness (shaping/aliases), whose package doc now points at its new sibling rather than explaining which modes it avoids. Verified with a full hugo build: 106 pages, no warnings, both shortcodes resolve their files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #68 +/- ##
=======================================
Coverage 81.80% 81.80%
=======================================
Files 86 86
Lines 8789 8789
=======================================
Hits 7190 7190
Misses 1168 1168
Partials 431 431 ☔ View full report in Codecov by Harness. |
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
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Change type
Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update
Short description
Fixes
Full description
Checklist