Skip to content

Commit 417ba79

Browse files
committed
gate(checklist): bind the platform-checklist corpus to the ONE symbol resolver (#16898)
`scripts/check-platform-checklist.mjs` resolved symbol anchors with a rule of its own -- mask comments, then ask whether the bare token appears anywhere in the file -- in the place `scripts/symbol-anchors.mjs` states the #13556 ruling it implements: "One resolver." The private rule was the LOOSER of the two, so it resolved anchors the shared resolver refuses and the checklist reported coverage it did not have; a second resolver that is greener than the shared one is never the one anybody points at. `absentAnchorSegments` now delegates every segment to `symbol-anchors.mjs#symbolResolutionClass` and holds no matcher at all. The per-segment split stays -- that is this corpus's anchor grammar, not a rule about what "present" means -- and a self-test assertion reads this file's own source to pin the body against re-forking. Withdrawing the permissive match is the deliverable, not a regression: 56 of 633 anchor occurrences stopped resolving (577 resolve -- 516 declaration, 61 literal). All 56 are carried in `SHARED_RESOLVER_RESIDUAL`, one closed row per (family file, anchor), each with the shape that used to resolve it and a verdict: 47 bad-citation, 8 accept-set. Every row must fire (a stale row reds), an unlisted failure is an ordinary red, and a grow-never ceiling sits beside it -- so the ledger is a closed list that shrinks by repair, never a rule. No floor is lowered and the maintainer-only baseline is untouched. `scripts/symbol-anchors.mjs` is untouched too: widening the shared core to keep this ledger green would export the looser reading to the ADR, `scripts/**`, spec-docblock and system-context corpora. Two self-test assertions that pinned the permissive behaviour are RE-JUDGED in place with the reason recorded, never deleted: P3 (an inline object-literal member) and P5 (a `.json` value). The directions they really covered are kept as P3b and P5b on shapes the shared rule accepts. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU
1 parent 66e34d1 commit 417ba79

2 files changed

Lines changed: 344 additions & 51 deletions

File tree

docs/qa/platform-checklist/README.md

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -173,13 +173,31 @@ Why this shape:
173173
```
174174

175175
`check:platform-checklist` resolves every anchor: the file must be in this repo and the
176-
symbol must still be in it, **comments masked** — a symbol surviving only in a docblock
177-
is ABSENT, because prose about a symbol is not a symbol. A symbol inside a string
178-
literal counts as present: much of what this ledger cites *is* a string (capability
179-
names, error codes, `sys_*` machine names). Dotted anchors resolve segment by segment.
180-
This is presence-in-code, not a declaration analysis — what it catches is the rename or
181-
deletion that leaves the pointer naming nothing, which is exactly the rot the line
182-
numbers used to carry.
176+
symbol must still be **declared** in it. ⭐ The rule is **not this gate's** and not this
177+
paragraph's — it is the one shared resolver every anchor corpus in this tree uses
178+
(`scripts/symbol-anchors.mjs#symbolResolutionClass`), and that module's own
179+
`THE RESOLUTION RULE` block is the authority. What an author needs from it:
180+
181+
- **comments are stripped first** — a symbol surviving only in a docblock is ABSENT,
182+
because prose about a symbol is not a symbol;
183+
- a **declaration site** resolves (a `function` / `class` / `interface` / `type` /
184+
`const` / `let` / `var`, a member or object-literal key written **at the start of a
185+
line**, a named re-export). For a `.json` target that means a **key**, never a value;
186+
- a **complete quoted string token** resolves — `'sys_metadata'` — which is what keeps
187+
the machine names this ledger is full of anchorable (capability names, error codes,
188+
`sys_*` object and field names);
189+
- ⚠️ and nothing else does. A **call site**, an **import**, a **member access on some
190+
other object**, a **local parameter**, or the symbol appearing only as a **substring
191+
of a longer string** (`saveItem` inside `'meta.saveItem'`, `:shareId` inside a route
192+
pattern) is **NOT** resolution. If that is all the cited file has, the citation is
193+
naming the file that *uses* the symbol, not the file that *declares* it — re-point
194+
it, or cite the file bare.
195+
196+
Dotted anchors resolve segment by segment. ⛔ An anchor the shared resolver refuses is
197+
either a bad citation or a case for widening that shared core, and the second is its
198+
own card against that module — ⛔ never a local rule here: the core is shared with the
199+
ADR, `scripts/**`, spec-docblock and system-context corpora, and widening it to suit
200+
this ledger would export the looser reading to all four (#16898).
183201
- **A citation the gate cannot resolve stays BARE — that is honest, not a gap.** Anchors
184202
are only for extensions the gate reads symbols out of (`.ts .tsx .mts .cts .js .mjs
185203
.cjs .json`); an anchor on a `.md` or a `.yml` is an ERROR rather than a silent skip,

0 commit comments

Comments
 (0)