Skip to content

docs(readme): make the "count it yourself" line-count and package-directory count agree with what they describe - #11012

Merged
os-elon merged 1 commit into
mainfrom
claude/issue-10320-readme-count-it-yourself
Aug 22, 2026
Merged

docs(readme): make the "count it yourself" line-count and package-directory count agree with what they describe#11012
os-elon merged 1 commit into
mainfrom
claude/issue-10320-readme-count-it-yourself

Conversation

@os-elon

@os-elonos-elon commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

Fixes#10320

The three figures, observed at 1b5a279942 (branch point 490879ad0f)

Claim 1 — examples/app-crm size blurb (README.md:143-150).

README saidCommand's actual output
Files3131 (matches)
Lines1,7921,930 (README was wrong by +138)

Re-ran the README's own command verbatim: find examples/app-crm/src -name '*.ts' -not -name '*.test.ts' | xargs cat | wc -l1930.

Claim 2 — Package Directory summary (README.md:265).

ClaimValue
README's summary said"72 published packages"
Table's actual row count (`grep -c '^['` over the section)
Non-private package.json files repo-wide (packages/, apps/, examples/)69

72 matched neither the table it introduces nor the repo's real publishable-package count.

Source of truth, and why

Claim 1: the shell command is the source of truth. It's executable and reproducible by any reader in one line; the prose sentence is a restatement that can drift the moment anyone edits examples/app-crm/src without touching README.md — which is exactly how it went stale (the file count still matched; only the line count had moved). No CI wiring in this repo currently re-runs that command against the README's number, and adding one is out of scope for this card (filed as a devx finding, see below) — so instead of re-hardcoding a fresh point-in-time number that will silently drift again at the next unrelated merge, the sentence now says so explicitly: it states its numbers "as of this writing" and tells the reader in as many words that the command below it, not the sentence, is authoritative. A future drift is now a declared, expected snapshot rather than a broken promise.

Claim 2: the table is the source of truth for its own count. The table is a curated set of highlights across the monorepo's categories (Core, Engine, Drivers, …), not a literal enumeration of every published package — three of its own rows (the example apps) are "private": true and were never published at all, so "published packages" was never quite the right noun for what it lists either way. The summary's count is now the table's actual row count (45), and the summary states that the table itself is the source of truth for that number — so expanding it can never again disagree with what it claims about itself. The real total (69) isn't asserted anywhere in this string any more, since nothing in this section claims to enumerate every published package.

Family / scope note

Per the dispatch note, this is cluster A (root README.md) of the #10264 family, run SERIAL — #10319 (also root README.md) stayed unclaimed while this ran, untouched here. #10322/#10324/#10325 (cluster B, blank template) are also untouched.

One factual correction for the record: the dispatch note said root README.md "has since taken #10881, #10929 and #10968" since the card's figures were measured (08-20). Checked git log --oneline -- README.md at this branch's point — the last actual edit to root README.md was #9293/#9304, well before those three. #10881/#10929/#10968 (and the visible commits eee2b65018/65c4a1305e) touched packages/cli/README.md instead. Doesn't change this PR's fix — both README figures were re-measured directly against the live tree rather than trusted from any prior report — but flagging it since it's a premise the dispatch note asserted.

Reverse verification

Does not apply — this is a prose/count correction, not a behavioral fix with a code path to ablate. What was run instead: the README's own verification command, and a literal row count over the Package Directory table (both shown above, both reproduced against the final commit).

Out of scope, filed not built

The card's "should this be a gate" question is filed as #11011 (finding, domain:cli, unassigned, no pm:queue) — labels verified landed after create. Not built here, per the card's explicit instruction not to widen this PR with a new gate.

Gate verdicts (derived via node scripts/pm/dispatch-gates.mjs, no paths, at 1b5a279942)

Diff surface: README.md, .changeset/readme-count-it-yourself.md. Six local gates were derived for that surface, all run through scripts/pm/os-verify-lock.sh, all green:

  • pnpm check:doc-anchors✅ check-doc-anchors: 279 internal #fragment link(s) across 407 source file(s) all resolve to a real heading
  • node scripts/check-empty-changeset.mjs --base origin/main✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added).
  • pnpm check:objectui-changeset → both self-tests (objectui-changeset-digest, objectui-range) pass
  • pnpm check:changeset-gate-self-tests → all three constituent self-tests pass
  • node scripts/check-adr-0087-registration.mjs --base 490879ad0f✓ check-adr-0087-registration: this PR adds no declared-breaking changeset (1 non-breaking changeset(s) seen).
  • node scripts/check-changeset-no-major.mjs --base 490879ad0f✓ This diff introduces no 'major' bump.

Check Documentation Links (named in-scope by the dispatch brief): its ADR-cross-link half is reproducible locally with zero dependencies and was run — node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs✅ check-adr-links: 551 relative link destination(s) under docs/adr/ resolve. Its other half (lychee, checking README.md among other files) runs via a pinned binary this container doesn't have installed and isn't wired into any package.json script for local reproduction; it's also advisory (not in the required set) and this diff adds/removes/edits zero markdown links, so it's inert to this change either way. CI will run it regardless.

node scripts/check-nul-bytes.mjs also run clean over the whole tree (this diff touches only ASCII prose).

No package build/typecheck was needed — this diff has no code surface (README.md + a changeset only).


Generated by Claude Code

…-directory count agree with what they describe
The examples/app-crm size blurb hard-coded 31 files, 1,792 lines, roughly 16k
tokens and invited the reader to verify it with the find | wc -l command
printed right below — running that command against origin/main returns 1,930
lines, not 1,792. The Package Directory summary claimed 72 published
packages; the table beneath it actually lists 45 rows (a curated subset, not
every package — three of those rows are private, unpublished example apps),
against a true count of 69 non-private package.json files repo-wide.
Both passages now name their own source of truth explicitly instead of
re-asserting a competing hand-typed figure that drifts again at the next
merge: the CRM blurb states its numbers "as of this writing" and says the
command below it is authoritative, not the sentence; the package-directory
summary's count is now the table's actual row count and says the table is
the source of truth for it.
Fixes#10320
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 32559900963 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Console Pin Gate — 失败步骤: Build the Console SPA at the pinned objectui SHA

    ✗ Build failed in 4.23s
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

跨 PR 相同签名(24h,按失败测试文件聚合):

  • ⚠️本次没有可用的聚合签名(日志里没有能解析出测试文件名的 FAIL 行)—— 这不是「没有同签名的其他 PR」,是这一轮没测到。跨 PR 聚合本次不可用,请手工比对其他 PR 的同类评论。
  • ⚠️ 24h 评论账本没读完(超过 5 页仍未读到窗口尽头),所以上面的「不同 PR 数」是下界,不是全量。

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 85 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Merged via the queue into main with commit 15ea214Aug 22, 2026
27 checks passed
@os-elon
os-elon deleted the claude/issue-10320-readme-count-it-yourself branch August 22, 2026 07:44
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/stooling

Projects

None yet

2 participants

@os-elon@claude