census: tell the reader where a DELIBERATE-LITERAL marker has to go (#2909)
A `DELIBERATE-LITERAL` marker in the wrong **position** is indistinguishable from no marker, and the miss is silent until CI. **Measured on #2883:** the marker sat inline in the middle of a conditional expression, so it attached to the wrong AST node and three reviewed literals scored as new debt (`self-healing.ts` 86 → 89). The message the tool printed at the time said *"record why at the site with a `DELIBERATE-LITERAL` marker"* — which I had done. Nothing in the output suggested placement was the problem. Two lines added to the failure message: - Markers are read from a node's **leading** comments, so put one on the declaration and hoist the literal into a named helper if needed. - **`pnpm lint` does not run this census** — CI's Lint job does. That is why the usual "lint passed locally, push" loop cannot catch either mistake, and why the tool itself is the only place a reader sees this in time. ## Verified, not assumed I induced a real failure (a temporary `t.column === "in-review"` guard in `self-healing.ts`) and read the printed output rather than trusting that the string lands in the right branch — the message has two branches and only one is the guard-count-rose path: ``` packages/engine/src/self-healing.ts: 89 -> 90 Resolve a lifecycle column from the task's own workflow (…) correct, record why at the site with a DELIBERATE-LITERAL marker. Put the DELIBERATE-LITERAL marker in the DECLARATION's leading comments, not inline in an expression: markers are read from a node's leading comments, so a mid-expression one attaches to the wrong node and is silently ignored. Hoist the literal into a named helper if you need to. Note that `pnpm lint` does NOT run this census — run it explicitly before pushing. ``` Guidance only — no scanner behaviour changes, so no counts move. ## Verification `pnpm test:gate` 161 + 487 + 13 + 71; `pnpm lint` and census `--strict` clean.
This commit is contained in:
@@ -545,7 +545,20 @@ if (regressions.length > 0) {
|
||||
" node scripts/lifecycle-column-census.mjs --strict --update-baseline\n"
|
||||
: "\nResolve a lifecycle column from the task's own workflow (resolveLifecycleColumns /\n" +
|
||||
"resolveTaskLifecycleColumns) instead of comparing its name. If the literal is genuinely\n" +
|
||||
`correct, record why at the site with a ${"DELIBERATE-LITERAL"} marker.\n`,
|
||||
`correct, record why at the site with a ${"DELIBERATE-LITERAL"} marker.\n` +
|
||||
/*
|
||||
FNXC:LifecycleColumnCensus 2026-07-31-09:10 (placement is the failure nobody sees):
|
||||
A marker in the wrong POSITION is indistinguishable from no marker, and the miss is silent until
|
||||
CI. Measured on #2883: the marker sat inline in the middle of a conditional expression, attached
|
||||
to the wrong node, and three reviewed literals scored as new debt (self-healing.ts 86 -> 89).
|
||||
|
||||
The second line is here because `pnpm lint` does NOT run this script — CI's Lint job does — so
|
||||
the usual "lint passed locally" loop cannot catch either mistake.
|
||||
*/
|
||||
`\nPut the ${"DELIBERATE-LITERAL"} marker in the DECLARATION's leading comments, not inline in an\n` +
|
||||
"expression: markers are read from a node's leading comments, so a mid-expression one attaches to\n" +
|
||||
"the wrong node and is silently ignored. Hoist the literal into a named helper if you need to.\n" +
|
||||
"Note that `pnpm lint` does NOT run this census — run it explicitly before pushing.\n",
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user