Skip to content

docs(apps/docs): fix stale docblock in page.tsx breadcrumb walk - #14537

Merged
baozhoutao merged 2 commits into
mainfrom
claude/issue-13949-page-docblock
Sep 2, 2026
Merged

docs(apps/docs): fix stale docblock in page.tsx breadcrumb walk#14537
baozhoutao merged 2 commits into
mainfrom
claude/issue-13949-page-docblock

Conversation

@baozhoutao

Copy link
Copy Markdown
Contributor

Fixes #13949

What

apps/docs/app/[lang]/docs/[[...slug]]/page.tsx's docsTrail() docblock carried two
errors, both fixed in this one edit, one file, prose only:

  1. Stale census. The paragraph claimed "8 short trails remain … its meta.json
    still lists "index". The condition is therefore live, just rare." That went false
    when PR docs(nav): stop listing "index" in content/docs/releases/meta.json #13946 removed "index" from content/docs/releases/meta.json — today,
    zero meta.json under content/docs lists "index" in pages
    (git grep -c '"index"' HEAD -- 'content/docs/**/meta.json' → no hits). Per the
    triage's measured lesson (a count that rotted within a day), the paragraph is
    rewritten to the mechanism only: how a URL-less ancestor arises, that docs site: 172 of 403 doc pages get a breadcrumb that skips its section — meta.json listing "index" detaches the folder index #12352
    and docs(nav): stop listing "index" in content/docs/releases/meta.json #13946 fixed every known instance, and that the condition is structural and
    can recur — no new count written in its place.
  2. Misattribution, independent of docs(nav): stop listing "index" in content/docs/releases/meta.json #13946 and wrong on origin/main today:
    the docblock said the walk "drops" the un-linkable ancestor. getBreadcrumbItems()
    does not drop it — it emits the ancestor with url: undefined. The drop is local:
    docsTrail()'s own loop guard, if (typeof item.name !== 'string' || !item.url) continue;, is what skips it.

No behavior change: docsTrail()'s logic, the breadcrumb loop, and the "the missing
URL is deliberately not reconstructed here" rule paragraph (unaffected per the triage)
are untouched. git diff --stat on this branch touches exactly one file.

Why this needed its own PR

Per the issue: content/docs/releases/** is fenced unconditionally in PR #13946's
dispatch, whose legality rested on "one file, nothing else" — apps/docs/** would
have been a second file. The fence that made #13946 possible is what prevented it
from carrying this correction; this PR is the follow-on the triage said was needed.

Tests

  • pnpm --filter @objectstack/docs typecheck (fumadocs-mdx && next typegen && tsc --noEmit) — PASS, both before opening (on the pre-merge tree) and again after
    merging origin/main into this branch.
  • node scripts/check-docs-nav-label.mjs — PASS (9-clause battery, the gate this
    docblock's neighboring includePage flip is pinned by).
  • node scripts/check-docs-nav-label.mjs --self-test — PASS (25 assertions).
  • pnpm exec eslint --no-inline-config --format json narrowed to the one edited file
    — PASS, 0 errors/warnings (repo ESLint has no type-aware linting anywhere, so this
    narrowing moves no untouched file's judgment).
  • The 9 gate families node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived for this diff — all PASS (check:docs-locale-catch-all,
    check:logger-receiver-detach, check:page-declaration-shape, check:published-files,
    check:test-source-alias, check:type-source-resolution, plus the two
    check-docs-nav-label.mjs invocations above and check-undeclared-dep-imports.mjs).

All of the above were re-derived and re-run against the merged tree
(origin/main fetched and merged, no conflicts) at head 75749de5c.

Changeset

apps/docs is "private": true — this PR publishes nothing from any package. The
changeset gate's own counting logic (git diff --name-only --diff-filter=A $(git merge-base origin/main HEAD) HEAD -- '.changeset/*.md') was simulated locally
and returns 0 added changesets, so this PR needs the skip-changeset label — applied
via the additive labels endpoint right after opening, with a read-back to confirm.


Generated by Claude Code

The census paragraph on origin/main still claimed "8 short trails
remain" and that content/docs/releases/meta.json "still lists
index" — both went false when PR #13946 removed "index" from that
meta.json (0 hits repo-wide now under content/docs/**/meta.json).
Rewrite it to the mechanism only (how a URL-less ancestor arises,
that #12352/#13946 fixed every known instance, and that the
condition is structural and can recur) rather than a count that
rotted within a day.

Also fixes an independent misattribution in the same paragraph:
getBreadcrumbItems() does not drop the URL-less ancestor itself —
it emits it with url: undefined. The drop is local, in docsTrail()'s
own loop guard (`if (... || !item.url) continue;`).

No behavior change: docsTrail(), the breadcrumb loop, and the
"missing URL is deliberately not reconstructed" rule paragraph are
untouched.
@claude claude Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Sep 2, 2026
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation labels Sep 2, 2026
@baozhoutao
baozhoutao marked this pull request as ready for review September 2, 2026 11:00
@baozhoutao
baozhoutao enabled auto-merge September 2, 2026 11:00
@baozhoutao
baozhoutao added this pull request to the merge queue Sep 2, 2026
Merged via the queue into main with commit 7da4cc2 Sep 2, 2026
31 checks passed
@baozhoutao
baozhoutao deleted the claude/issue-13949-page-docblock branch September 2, 2026 11:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants