Skip to content

Commit b3d8a75

Browse files
feat(docs-audit): state where every emitted anchor came from (#13738)
Each row of the docs-drift advisory now names the declaration that minted its anchor, so a reader can judge the row instead of guessing: organizationId (symbol, a field of interface MetaOverlayCacheKey) userActions (symbol, a field of const object ObjectSchemaBase) Those two are the same syntactic form — `name:` inside an object or interface — and that is the finding this implements: one is the noisiest anchor the tool mints, the other the most valuable, and no syntactic or per-package test separates them. The declaring container does, and no row printed it before. Publication only. No guard, no threshold and no bridge hop reads the new field; the emitted anchor set is byte-identical before and after, with only the rendering differing. `--self-test` pins the provenance key set as exactly the anchor set in both directions, so a later change cannot start deciding with it without going red. Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 parent 5604c44 commit b3d8a75

2 files changed

Lines changed: 303 additions & 17 deletions

File tree

scripts/docs-audit/README.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,51 @@ false positive: `const singular = request.type;` inside a method body is not an
6363
longer listed. A `const` object **is** a container (its keys are metadata property names,
6464
which docs do name); a function body is not.
6565

66+
### Every row says WHERE its anchor came from (#12824)
67+
68+
A row used to read `organizationId (symbol)`, and a reader had no way to tell the single
69+
most on-target anchor the tool mints from pure noise. Now it reads:
70+
71+
```
72+
- `content/docs/deployment/seed-tenancy-repair.mdx` _(via organizationId (symbol, a field of interface MetaOverlayCacheKey))_
73+
- `content/docs/data-modeling/objects.mdx` _(via userActions (symbol, a field of const object ObjectSchemaBase))_
74+
```
75+
76+
Those two are **the same syntactic form**`name:` inside an object or interface — and
77+
that is the point. One is a field of an internal cache struct and lands 10 pages that
78+
document an unrelated `organizationId`; the other is the canonical authorable key, and its
79+
row is the best one this tool produces. No syntactic test separates them (measured: the
80+
declaring *package* does not either — `schemaMode` is authorable and lives in
81+
`packages/objectql`). The **declaring container** does, and it is the field no row printed
82+
before.
83+
84+
Each anchor kind names its own origin, from the same field the JSON publishes as
85+
`anchors[].from` — one derivation, never a second spelling:
86+
87+
| kind | the clause |
88+
|:--|:--|
89+
| `symbol` | `a field of interface MetaOverlayCacheKey` · `a method of class RestServer` · `a top-level function` |
90+
| `route` | `a path literal in RestServer` · `bridged from symbol enforceEnvironmentOwnership — its registrar handler names it` |
91+
| `sdk` | `the route ledger binds it to GET /api/v1/ui/view/:object/:type` |
92+
| `literal` | `a string literal in cacheKeyOf` |
93+
| `command` | `read off packages/cli/src/commands/environments/bind.ts` |
94+
| `rule` | `a @docs-rule block in packages/objectql/src/engine.ts` |
95+
96+
The bridge clauses are load-bearing for the same reason: an `sdk` row on a diff that never
97+
came near that route is the amplification this machinery is measured to produce, and it is
98+
only judgeable when the row names the hop it rode.
99+
100+
**This is publication, not discrimination, and the difference is the ruling.** The
101+
maintainer's decision of 2026-08-31 took this (option C) and ruled OUT filtering on it
102+
(option B): dropping data-property anchors buys a 17.9% shorter list and pays in the
103+
`userActions``data-modeling/objects.mdx` and `schemaMode``data-modeling/drivers.mdx`
104+
rows. A false positive costs a reader a minute; a false negative ships a falsified page.
105+
So no guard, no threshold and no bridge hop reads `from``--self-test` pins that the
106+
provenance key set is exactly the anchor set, in both directions, so a future change
107+
cannot start deciding with it without going red. Container-qualified *discrimination*
108+
lives on #13712 (the spec half) and #13713 (the docs-audit half), and needs a TS-name →
109+
spec-name mapping this does not have.
110+
66111
### Two guards, and both publish what they removed
67112

68113
The first build of this derivation was, on some PRs, *noisier* than the proxy it replaced

0 commit comments

Comments
 (0)