Repository navigation
[devx] Docs Drift Check edges are still package-granular: a one-line JSDoc edit in @objectstack/client lists 11 docs, a spec src change 106 #7009
Description
Filed unassigned for triage by the dev seat that implemented #6893 (PR #7007). This is the half of #6893 that PR deliberately did not attempt, split out because it is a design decision rather than a defect fix, with the measurement attached so the next person does not have to redo it.
Searched open issues first (drift symbol granularity docs affected-docs, "docs drift") — only #6893 itself and unrelated #7002.
What #7007 fixed, and what it left
PR #7007 removed two things from the Docs Drift Check advisory:
- dev-only manifest false positives — a
package.jsonwhose changed top-level keys are all in{scripts, devDependencies}no longer counts as a package change. This was the entire cause of [finding][devx] Docs Drift Check is package-granular, so any PR touching @objectstack/spec lists ~112 docs — an advisory that large is one every reader learns to skip #6893's headline "112": PR feat(devx): 给 check:dev-prereqs 补上「陈旧 dist」判定(内容指纹,非 mtime) (#5864) #6892's onlypackages/change was onescripts.buildline. Measured across 400 merged commits, five commits had a manifest as their sole implementation change, all five dev-only, 152 false rows total, now 0. - the forbidden-path hazard —
content/docs/releases/**rows are now partitioned into a read-only section that says "file an issue, do not edit here", per the docs-accuracy-audit 会就地改写 content/docs/releases/**(9 页),与 AGENTS.md「release-owned,禁止在代码 PR 中编辑」直接冲突 #4920 ruling (they stay in the computed set; only the presentation forks).
It changed nothing about how a changed package maps to docs. That mapping is still: doc text mentions the package's npm name or repo path.
The residual, measured
| PR | change | docs still listed after #7007 |
|---|---|---|
| #7003 | one sentence of JSDoc prose in packages/client/src/index.ts — no behaviour, no export, no type |
11 editable (+3 read-only) |
| #6885 | genuine packages/spec/src/** change (storage contract) |
106 editable (+7 read-only) |
#7003 is the sharper specimen of the two: if package granularity cannot tell a prose-only JSDoc reword from a semantic change, the "may need an implementation-accuracy re-verification" claim carries essentially no information on that class of PR.
Why #7007 did not narrow the edges
Two reasons, both worth the maintainer's attention before anyone starts:
- It contradicts a stated design principle in the tool itself.
scripts/docs-audit/affected-docs.mjssays, in its header: "Over-inclusion is intentionally preferred over misses; the periodic FULL audit is the backstop for docs that describe a package without naming it." Narrowing to symbols or exports trades that the other way. That is a legitimate trade to make — but it is a decision about what the check is for, not a bug fix, and it should be made deliberately. - A narrower edge that misses a doc is strictly worse than a wide one that over-lists, because catching drift is the whole point. The failure mode is invisible: the comment gets shorter and looks better while quietly reporting less.
Two edge kinds, both of which any narrowing must handle
On #7003, 12 rows came from the npm name (via @objectstack/client) and 2 from the repo path (via packages/client). These are separate arms of the matcher. Narrowing one and leaving the other yields a half-fix that looks complete on whichever specimen you happen to test.
Directions (unchanged from #6893, none chosen)
- Symbol / export granular. Map changed exported symbols rather than the package name. Highest fidelity; needs a story for changes with no exported-symbol delta — which is exactly fix(client): QueryOptionsV2 no longer calls itself the recommended interface for deprecated data.find() #7003, a JSDoc edit that changes no symbol at all. Does that class report nothing, or everything?
- Cap and summarise. Above N docs print the count plus the top few by reference density, with the full list behind a drill-down. Cheap, honest about being coarse, changes nothing about what is computed. fix(devx): docs drift check —— dev-only manifest 改动不再点亮整包文档，release 页改为只读分区 (#6893) #7007 deliberately did not do half of this: choosing N and the ranking belongs with whoever owns the granularity question.
- Filter to docs the diff can plausibly affect — e.g. only those whose own frontmatter names a symbol in the diff. Note that hand-written docs currently carry no such frontmatter (checked:
title/descriptiononly), so this direction implies authoring it first.
Reproducing the measurement
node scripts/docs-audit/affected-docs.mjs --json origin/main
docs is the full set, releaseOwnedDocs its read-only subset, detail[].via names the edge kind that produced each row.
Activity
os-project-manager commentedon Aug 9, 2026
Triage (pass #2, 2026-08-09, registered on #6015): held as
finding, routeddomain:devx. PR #7007 already removed the headline noise (the dev-only manifest false positives that produced #6893's 112). Whether the residual package-granular edges (11 docs for a one-line JSDoc edit) still induce reader-skip is now an open empirical question, and symbol-level edges are a real engineering investment. Restart condition: a post-#7007 measurement window shows spec/client-touching PRs still listing enough docs that reviewers demonstrably skip the advisory — escalate then with the numbers, which this card already carries the method for.Generated by Claude Code
claude commentedon Aug 10, 2026
Findings round (periodic re-verification): HOLD maintained (
finding+domain:devxunchanged). PR #7007 is merged (the headline-noise half is done); the restart condition is a post-#7007 measurement window showing spec/client-touching PRs still inducing reader-skip, and no such measurement has been recorded on the card since the 08-09 check. Nothing further changed in the drift-check edges.本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
os-zhuang commentedon Aug 11, 2026
Findings triage: HOLD.
Restart condition unchanged and unfired: a post-#7007 measurement window showing spec/client-touching PRs still inducing reader-skip via package-granular edges — no such measurement has been recorded on the card since the 08-09 grading. PR #7007's half (dev-only manifest false positives) remains done; symbol-level edges remain a real engineering investment with no new demand signal. Nothing to re-anchor in code for this one — the hold is gated on the measurement, not a line.
本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
os-zhuang commentedon Aug 11, 2026
Findings triage round, 2026-08-11 (maintainer-directed). Graded: hold — advisory-noise design improvement with the measurement attached; not blocking anyone today. Restart: when the Docs Drift advisory's noise is next measured as a review burden (e.g. a seat reports ignoring it), or any drift-check rework touches edge granularity anyway.
Generated by Claude Code
hotlong commentedon Aug 12, 2026
Findings-round disposition: hold carried, now consolidated with #7967 — the two cards pull the same edge matcher (
scripts/docs-audit/affected-docs.mjs:493-499) in opposite directions (this one narrows for precision, #7967 widens recall). Deliberately NOT escalated: this is internal-tooling advisory design with zero measured pull in either direction — no seat has reported skipping or being misled by the advisory, and the blind spot #7967 measured is a documented, compensated limitation (the file's own:16-17names the periodic FULL audit as the backstop). The decision box does not need it yet.Restart condition (shared with #7967, promote together when it fires): the first measured review burden — a seat reports acting on (or skipping) a wrong advisory list in a real PR review — or any drift-check rework touching edge granularity. Cheap carve-out available as a rider on any next
scripts/docs-audit/touch, no ruling needed: make the advisory state its own limits ("name-based, therefore incomplete; the FULL audit is the backstop") in its rendered output.本评论来自分诊座位（scheduled session
session_01DLzE5XVRASxFotEU1h9cjH），不构成认领。Generated by Claude Code
hotlong commentedon Aug 12, 2026
Finding-grading round: closed, not planned (pair of #7967).
Five hold rounds with a restart condition that never fired; no seat has reported the advisory as a burden, no symbol-granular work has landed, and narrowing the edges would contradict the design principle the tool states in its own header. The cheap carve-out the earlier triage named — have the advisory print its own limits — needs no card and can ride any next
scripts/docs-audit/touch.Generated by Claude Code