Skip to content

fix(docs): correct the getPageTree() claim in the llms LANG-pin comments - #206

Merged
hotlong merged 1 commit into
mainfrom
claude/issue-203-locale-pin-comment
Aug 26, 2026
Merged

hotlong merged 1 commit into
mainfrom
claude/issue-203-locale-pin-comment

Conversation

@hotlong

@hotlong hotlong commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Fixes #203

What

Both apps/docs/app/llms.txt/route.ts and apps/docs/app/llms-full.txt/route.ts pin LANG = i18n.defaultLanguage and justify the pin with a comment. Both comments claimed source.getPageTree() "list[s] every language when called without one" — a claim that is false, and had never been measured. The pin itself is correct and stays in both files; only the justification changes.

Comments only. No behavior change in either file.

Reproduction (done before writing the replacement text)

On this branch's base (3433803), against fumadocs-core 16.8.12:

  1. Baseline build (pnpm turbo run build --filter=@objectos/docs --force): apps/docs/.next/server/app/llms.txt.body sha256 883ebd3834fb1deb49f0c58cb153ed0a2eb06de16b854da592ce8e013ca85b1b.
  2. Dropped the argument from source.getPageTree(LANG) in llms.txt/route.ts. Confirmed on disk before building: grep -c "getPageTree(LANG)" went 1 to 0.
  3. Rebuilt with --force (turbo's cache is shared across worktrees in this container, so --force is not optional for this comparison). llms.txt.body sha256: 883ebd3834fb1deb49f0c58cb153ed0a2eb06de16b854da592ce8e013ca85b1b — byte-identical to step 1, and identical to the hash [finding] the locale-pin comment in llms.txt/route.ts names getPageTree() as a leaking call — measured, it is not #203's own card recorded on an earlier commit.
  4. Restored source.getPageTree(LANG) via git checkout HEAD -- apps/docs/app/llms.txt/route.ts; confirmed clean with git diff HEAD (empty).

getPageTree() called with no argument resolves to the default language on this fumadocs-core version. The historical leak both comments describe (335 pages across 7 locales, up to 4.6 MB) was source.getPages() called bare — that claim is correct in both files and unchanged by this PR. git show c243ad7 -- apps/docs/app/llms-full.txt/route.ts shows the original fix (#183) was solely about getPages(); the getPageTree() half of the claim was added later when that route was switched from getPages() to getPageTree() and the sibling file's comment text was carried across with the code.

What changed

Both comments now:

  • attribute the historical leak to source.getPages(), where it was and still is;
  • describe the getPageTree() argument as passed because the tree it returns is already per-locale and, while it currently happens to default to the default language, nothing in the API contract promises that — not as an observed leak.

The pin stays in both files: check-locale-surface.mjs (from #184) now asserts the built llms/llms-full output's locale composition regardless of which claim justifies the pin, so nothing regresses if the false half of the comment had simply been deleted instead — but leaving a wrong "why" in the only place either file explains itself is what let the claim propagate once already.

Verification after the edit

Re-measured post-edit (comment-only change, so bodies should be unaffected):

  • llms.txt.body sha256: 883ebd3834fb1deb49f0c58cb153ed0a2eb06de16b854da592ce8e013ca85b1b (unchanged from baseline).
  • llms-full.txt.body sha256: e84953ee1066becf3a6fae11099f7cd3c3179009ffe5435a2cd34f14c6cea310 (matches the digest recorded in the fix(docs): order llms-full.txt by the navigation tree #201 commit message for a post-fix build).

Gates, all run with --force against the merge base 3433803:

  • pnpm turbo run type-check --filter=@objectos/docs --force — Tasks: 1 successful, 1 total.
  • pnpm turbo run build --filter=@objectos/docs --force — Tasks: 1 successful, 1 total.
  • pnpm turbo run test --force — ✓ 3 self-test(s) passed, Tasks: 1 successful, 1 total (only @objectos/ci-scripts carries a test script in this repo; @objectos/docs has none).
  • node .github/scripts/check-locale-surface.mjs — ✓ every advertised URL has a source file and every source file is advertised; both llms bodies carry every en-only page title and none from the other locales.

No .changeset/ mechanism exists in this repo; not applicable regardless, since this is a comment-only change with no user-visible effect.


Generated by Claude Code

Both llms.txt/route.ts and llms-full.txt/route.ts justified the LANG pin by
claiming source.getPageTree() "lists every language when called without one" /
"filter[s] by locale only when a language is passed". Measured against
fumadocs-core 16.8.12 on this repo's content, dropping the argument from
source.getPageTree(LANG) in llms.txt/route.ts and rebuilding with
`pnpm turbo run build --force` produces a byte-identical llms.txt.body
(sha256 883ebd38...), both before and after the mutation. getPageTree()
resolves to the default language when called with none.

The historical leak both comments describe (335 pages across 7 locales / 4.6MB)
was source.getPages() called bare — true and unchanged. getPageTree() never
observably leaked; the claim propagated from llms.txt's comment into
llms-full.txt's when the route was switched from getPages() to getPageTree()
and the LANG-pin comment was carried across along with the code.

The pin stays in both files: nothing in the API contract promises
getPageTree() will keep defaulting to the default language, and the
check-locale-surface.mjs gate now asserts the built output either way. Only
the justification changes — getPageTree() is now described as "passes the
language because the tree is per-locale and the default is not contractual"
rather than as an observed leak.

Comments only; no behavior change. Confirmed by an unchanged llms.txt.body
sha256 (883ebd38...) and llms-full.txt.body sha256 (e84953ee...) before and
after the edit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G5zjYc2BoFV2NjKBBapC7C
@hotlong
hotlong marked this pull request as ready for review August 26, 2026 03:22
@hotlong
hotlong merged commit c5e7905 into main Aug 26, 2026
2 checks passed
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.

[finding] the locale-pin comment in llms.txt/route.ts names getPageTree() as a leaking call — measured, it is not

2 participants