diff --git a/scripts/invoked-as.mjs b/scripts/invoked-as.mjs index 8f1b4afd8d..0c133e9027 100644 --- a/scripts/invoked-as.mjs +++ b/scripts/invoked-as.mjs @@ -13,10 +13,10 @@ * reached ELEVEN distinct spellings across 33 files -- measured, not estimated * -- and nine of the eleven were wrong, in a direction nothing in CI can see. * - * THIS repository has not been swept, and no gate here enforces the rule. Read - * "## Nothing here enforces this yet" below before concluding otherwise: every - * path this header names outside `scripts/` is objectstack's, and several under - * `scripts/` are too. + * THIS repository has since been swept, and a gate here enforces the rule. Read + * "## What enforces this, and what it took to get here" below for the numbers + * and the commit they were taken on. Two paths this header names are + * objectstack's and do not exist here; each is labelled where it appears. * * ## The bug every hand-typed spelling had * @@ -36,8 +36,10 @@ * * Same tree, same defect, same gate -- reached through a symlink it reports the * clean answer, and a wrapper holding `result.status` cannot tell that apart - * from a pass. `check-skills-paths.mjs` carries the no-realpath spelling, as do - * 27 of its neighbours; see below. + * from a pass. `check-skills-paths.mjs` CARRIED the no-realpath spelling when + * that was measured, as did 27 of its neighbours; every one of them routes + * through `isEntrypoint` now -- see below for what closed them, and what keeps + * them shut. * * The same measurement in objectstack, where this module came from, lands on a * gate whose exit codes make it worse still: `scripts/pm/check-governed-merges.mjs` @@ -81,33 +83,54 @@ * it, exported so the predicate is pinned by cases rather than trusted by * reading. * - * ## Nothing here enforces this yet -- the rule is a CONVENTION - * - * An earlier version of this paragraph said `scripts/check-entry-guard.mjs` - * enforces the rule -- that a `process.argv[1]` in an entry-guard position - * anywhere in `scripts/**` outside this module is a failure. It does not. That - * file has never existed in this repository. It exists in objectstack, wired - * there as `check:entry-guard`; the port (#5984) brought this module and its - * prose, and neither the gate nor the sweep the prose describes. Measured on - * `7c96c9420`: - * - * git grep -n 'check-entry-guard' -> ONE hit: this paragraph - * git grep -l 'isEntrypoint' -- scripts -> this file, and ONE adopter - * git grep -l 'process.argv\[1\]' -- scripts -> 30 files - * - * The one adopter is `scripts/pm/check-half-states.mjs`, which arrived in the - * same PR. The 30 files are this one plus TWENTY-NINE hand-typed guards: 28 - * `.mjs`, in NINE textually distinct spellings and not one carrying a realpath - * leg -- including the exact percent-encoding spelling this header warns about - * above, still in `check-node-esm-load.mjs:847` -- and `scripts/shadcn-sync.js`, - * the only hand-typed guard here that does carry the realpath leg. - * - * A gate is still the right answer: without one, converting those 29 is a - * one-time sweep that starts rotting the day it merges, because nothing stops a - * THIRTIETH spelling from being typed next week. Both halves -- the gate and - * the sweep -- are tracked in #6092. Until that lands, `isEntrypoint` here is a - * convention: reach for it in new scripts, and do not read this file as - * evidence that the tree already has. + * ## What enforces this, and what it took to get here + * + * `scripts/check-entry-guard.mjs` enforces the rule: a `process.argv[1]` in an + * entry-guard position anywhere in `scripts/**` outside this module is a + * failure. It is wired in `package.json` as `check:entry-guard` and run by + * `.github/workflows/lint.yml` BEFORE `pnpm install`, so an install failure + * cannot take the gate down with it. `scripts/__tests__/entry-guard-wiring.test.ts` + * pins that wiring rather than the numbers, because a gate nobody runs is + * indistinguishable from a gate that passes. + * + * Measured on `2dc4aa709`. Naming the commit is the point: these are a + * SNAPSHOT, and an older snapshot left standing in the present tense is exactly + * what this section had to be rewritten to fix. + * + * pnpm check:entry-guard -> 47 scripts/ files scanned, no + * guard outside the baseline; + * 0 still hand-type one + * (SHRINK-ONLY); 42 export + * bindings, 42 inert on import + * git grep -l 'isEntrypoint' -- scripts -> 40 files + * git grep -l 'process.argv\[1\]' -- scripts -> 3 files + * + * Those three are this module -- the one place allowed to read `argv[1]` -- and + * `check-entry-guard.mjs` and `js-comment-mask.mjs`, which carry the broken + * spellings as FIXTURE data rather than as guards; the gate's comment/string + * masking is what tells those apart from the real thing. + * + * The history, because the figures above only mean something against it. This + * module arrived from objectstack (#5984) with prose describing OBJECTSTACK'S + * tree: it named a gate that did not exist here and a sweep that had not + * happened here. Measured then, on `7c96c9420`: `check-entry-guard` appeared in + * exactly ONE place, the paragraph claiming it; `isEntrypoint` had a single + * adopter (`scripts/pm/check-half-states.mjs`); and 29 hand-typed guards stood + * in NINE textually distinct spellings, 28 of them with no realpath leg -- + * including the exact percent-encoding spelling this header warns about above, + * then still in `check-node-esm-load.mjs`. objectui#6092 closed both halves: + * the gate landed (#6133), the 29 call sites were converted (#6145), and the + * second rule's baseline reached zero (#6156). + * + * The gate, not the sweep, is what holds. A one-time sweep starts rotting the + * day it merges, because nothing stops a THIRTIETH spelling from being typed + * next week; `KNOWN_HAND_TYPED_GUARDS` is empty and SHRINK-ONLY, so typing one + * is now RED rather than a convention politely ignored. + * + * When these numbers move, re-take them and re-name the commit -- do not edit + * the figures in place under the old one. A refreshed count under a stale + * commit is a measurement nobody can reproduce, and that is the failure this + * whole section records. * * ## The siblings, and why the duplication is deliberate *