Uh oh!
There was an error while loading. Please reload this page.
docs(links): scan the app READMEs and the rest of the repo root (#4148) - #4173
Merged
Conversation
`apps/console/README.md` linked twice to `./CONSOLE_ROADMAP.md`, a file that left that directory in c988277 (renamed to a root ROADMAP_CONSOLE.md) and was folded into the root ROADMAP.md by 3e814e0. Both links sat dead for about six months while `pnpm docs:check-links` reported green on every push, because `apps/` matched no SCAN_ROOTS row. Two rows, both `disk`, both surfaces the script's own header had been DOCUMENTING as unscanned: - one README per directory under `apps/` — objectui#3622's package-README purchase one directory over, and `@object-ui/console` is itself a published package, so its README is read on npm and GitHub in exactly the same two places. A wildcard row, so the next app is scanned on arrival. - the rest of the root-level markdown (AGENTS.md, CHANGELOG.md, CLAUDE.md, LICENSE-THIRD-PARTY.md, QUICK_REFERENCE.md), joining README.md, CONTRIBUTING.md and ROADMAP.md. Per-file rows: the root has no glob spelling, since `expandWildcard()` expands a whole path segment and never `*.md`. Price: 2 dead links from the apps row (the CONSOLE_ROADMAP pair, repointed at the root ROADMAP.md — the content moved there, so repointing is an answer rather than a guess), and zero from the root row. The header no longer documents the gap it used to; the stale forward-references to that list, and a positional "scan roots 1 and 7" in doc-version-claims, go with it. Deletes objectui#4149's in-test link check (`scripts/__tests__/quick-reference-commands-4149.test.ts`), which was written as an explicit stopgap for one page "to be deleted when a SCAN_ROOTS row makes it redundant". The `QUICK_REFERENCE.md` row above is that replacement, and it judges the page under the same rule as every other GitHub-read file. The self-test gains the new rows' red/green plus a reverse assertion that every TRACKED root-level markdown file has a row — so the surface this card reopened cannot silently close again. Fixes#4148 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Qqyix2QcnpUC9XeYVDzx3
The latest updates on your projects. Learn more about Vercel for GitHub. |
Contributor
✅ Console Performance Budget
📦 Bundle Size Report
Size Limits
|
yinlianghui
marked this pull request as ready for review
August 10, 2026 15:58
Uh oh!
There was an error while loading. Please reload this page.
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Fixes#4148
Ordering
PR #4159 (which owns
scripts/__tests__/quick-reference-commands-4149.test.ts, edited here) merged as521a37bd0before this started, so this branches offmainrather than stacking onclaude/issue-4149-quick-reference-dead-commands.Premise: valid, with one correction that decides the fix
Both dead links reproduce at the tip, and so does the blind spot:
The card's second half is the one that changed. It states "the roadmap content is gone, not moved — there is no successor path to repoint at", and that is where its two links-vs-delete options came from. The history says otherwise:
c988277ffapps/console/CONSOLE_ROADMAP.mdrenamed to a rootROADMAP_CONSOLE.md(a pure rename,git show --statreports it as such)3e814e07aROADMAP_CONSOLE.md,ROADMAP_DESIGNER.mdandROADMAP_SPEC.mdfolded intoROADMAP.mdToday's
ROADMAP.mdstill carries the Console work as its own phases (P1.2 Console — Forms & Data Collection,P1.3 Console — Import/Export Excellence,P1.4,P1.5,P1.6,P1.7, and more). So there IS a successor, both links are repointed at it, and the delete-versus-repoint decision the card deliberately left open does not need a judgement call — it needs the rename history. The links were dead for about six months.1. Two
SCAN_ROOTSrowsBoth
disk, because both surfaces are read on GitHub and never served by the site.One README per directory under
apps/. objectui#3622's package-README purchase one directory over, and the rule choice is stronger here than "same shape":@object-ui/consoledeclares noprivate, so it is a published package and its README is read on npm and on GitHub in exactly the two places a package README is. A wildcard row for the same reason as the package one — the surface is one file per directory rather than a tree — which also means the next app to land is scanned on arrival with no row to remember.The rest of the root-level markdown:
AGENTS.md,CHANGELOG.md,CLAUDE.md,LICENSE-THIRD-PARTY.md,QUICK_REFERENCE.md, joining theREADME.md/CONTRIBUTING.md/ROADMAP.mdalready in the table. Per-file rows, not a glob —expandWildcard()expands a whole path SEGMENT by design, so*.mdis not a spelling this table has and would throw.LICENSE-THIRD-PARTY.mdwas not on the header's list of four and is bought anyway. That is the point: it makes the root complete, which converts a list of names (a thing that goes stale the next time someone adds a page) into an invariant a test can hold. See the reverse assertion below.2. What the rows cost — measured before landing
The 2 are the
CONSOLE_ROADMAP.mdpair, repaired in this PR, so the rows land green — the objectui#3572 shape (a check arriving with its backlog already paid), not the #3479/#3490 shape.Two of the five root files carry nothing to judge today:
AGENTS.mdhas no markdown links at all (its paths are code spans, whichstripCode()blanks) and both ofCHANGELOG.md's are external. They are bought regardless — a row over a file with no decidable links is the row that judges the FIRST dead link written into it, and buying a surface while it is empty is the cheapest this ever gets.3. The #4159 stopgap, deleted
scripts/__tests__/quick-reference-commands-4149.test.tsresolved that one page's links itself, and said so in its own words: a stopgap for one file, "it should be deleted when aSCAN_ROOTSrow makes it redundant, rather than left as a second implementation". TheQUICK_REFERENCE.mdrow is that replacement, so the block and its header claim both go. Two implementations of one check is one more than gets maintained.4. Stale counts swept (the #3212 family)
The header did not merely omit these surfaces — it documented them as unscanned, so the prose had to move with the rows:
#3622"Still not bought" list (those four root files) now records that apps/console/README.md links twice to CONSOLE_ROADMAP.md, deleted in c988277ff — and no link gate can see it, because check-doc-links.mjs does not scan apps/** #4148 bought them, and the#3490forward-reference to it stops claiming "those four are still on it";example-relativehint enumerated the disk surfaces and no longer omits the new ones;doc-version-claims.test.tsreferred to check-doc-links' "scan roots 1 and 7" positionally. Positions survive an append by luck; the roots are now named.The success line was already
SCAN_ROOTS.length, so it needed nothing — it reads13 scan rootson its own.Reverse verification — predicted first, three directions
Direction 1 (the point of the card): the widened scan on the pre-fix tree. Predicted red naming exactly the two roadmap links and nothing else, since the root rows were measured at zero. Measured:
Direction 2: delete the apps row from the repaired tree. Predicted 5 red — the two whole-table pins plus the three app fixtures — and the repo-wide scan staying GREEN, because the README is fixed by then and its links resolve whether or not anything looks at them. That last part is the interesting half: it is precisely why a fixture pair is needed and a repo scan is not sufficient evidence that a row exists. Measured
Tests 5 failed | 82 passed (87), exactly those five.Direction 3: delete one root-file row. The self-extending assertion, which no fixture can prove:
It names the file, and it is derived from
git ls-filesrather thanreaddiron purpose: an untracked stray at the root — a scratch note, or a generatedAGENTS.mdof the kind #4159 caughtnext devwriting intoapps/site/— is not this gate's business and must not redden the suite.Both mutations reverted from a patch file. Never
git stash— that stack is shared across worktrees (objectui#3430).Gates
Changed files were also swept for control characters beyond the gate's scan surface: clean.
Changeset
None owed, arbitrated by the script rather than by judgement:
No
skip-changesetlabel: it is decorative in this repo (objectui#3724 deleted.github/WORKFLOWS.mdfor documenting, among other phantoms, "a changeset gate skippable with askip-changesetlabel; neither the workflow nor the label was ever real").Out-of-scope findings
None new. The one thing worth flagging for whoever reads the card: its "two decisions, deliberately not made here" are both made here, and the first was made by the rename history rather than by a judgement call — the option set in the card ("deleting both links, or repointing them at the root
ROADMAP.md") had assumed repointing "asserts something about content nobody has checked". Someone has now checked: the content is literally the same document, moved twice.Generated by Claude Code