Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
baozhoutao merged 1 commit into from
Sep 1, 2026
+184 −8
Merged

Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps #14231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 141 additions & 2 deletions scripts/check-ratchet-remedy-authority.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
* The two extensions the corpus walk admits, as ONE constant rather than two
* `endsWith` calls inline — so the declaration below can be held against the
* thing the sweep really filters on instead of against a second copy of it.
* The `.mts` half is the #8538 blind spot and is not decoration: see the header.
*/
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
* The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
* -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
* hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
* holds that spelling for every declarer in the tree).
*
* ## Why this gate declared NOTHING, and what that cost (#13813)
*
* `extractWatchHints` scans the module body for path-shaped literals. This file
* builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
* string naming that population appeared only in the failure text, in the
* `--list` banner and in the header comment -- never as a literal the scanner
* could read. So the derivation read no population here and made no claim, and
* the family landed in the residue's `undetermined` bucket: not matched, not
* known-irrelevant, and absent from the `matched` list a dispatch brief prints.
*
* That is not a theoretical gap. A PR touching three `scripts/**` files ran its
* whole derived family locally, green, and CI reddened on THIS gate -- both
* readings true, of the same tree. Eight families matched those same three
* paths, every one of them at `gate source 'scripts/**'`, because their
* populations are spelled where the derivation can read them.
*
* ## Why the spelling is the flat-directory glob and NOT `scripts/**`
*
* `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
* reads the top level of `scripts/` only -- never `scripts/pm/`,
* `scripts/docs-audit/` or any other nested directory -- and only the two
* extensions above. `scripts/**` would be the easy spelling and it would be
* FALSE: it pastes this gate onto every card touching any nested script, for
* files this gate never opens, which is the costlier error `hintCovers`' own
* docblock prices above a missing declaration.
*
* The two hints here are 100% precise AND complete against this tree, set-equal
* in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
* tracked files under the bare root -- and the self-test below re-measures that
* rather than trusting this sentence.
*
* ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
* the failure text, which both spell the corpus that way for a human reader.
* `hintCovers` has no brace expansion, so that one string reaches NOTHING --
* a dead declaration, printed as the same silence as declaring nothing at all.
* One hint per extension is the spelling that is live, and a self-test case
* pins the brace form as dead so the tidier spelling cannot quietly land.
*
* ## Why this spelling exists at all today
*
* `scripts/pm/bare-root-worklist.mjs` recorded this population as
* REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
* spelling". That was TRUE when it was written: `collapseHint` deleted the glob
* and spliced the remainder inside the final segment, so this hint collapsed to
* `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
* exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
* MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
* the refusal became false of the tree without anything reddening. That row is
* re-decided alongside this declaration, in the file that owns it.
*/
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
return readdirSync(SCRIPTS_DIR)
.filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
.filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
.sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
+ 'control is a declaration registry, and its offer-shaped quotes live in comments)',
results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

// ── (20) The declared population, held to the walk in BOTH directions (#13813)
//
// ⛔ Checked with a LOCAL matcher rather than by importing
// `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
// literal in this file's source, so the derivation would hand this gate that
// module's declared population as if it were this gate's own — a fabricated
// watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
// The liveness of these hints in `hintCovers`' own terms is pinned where
// `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
//
// Both directions, because either alone passes against the defect this closes.
// "The declaration is non-empty" was true of every gate that ever went silent;
// "it names the root" is true of `scripts/**`, which is the FALSE spelling
// here. What is asserted is that the hints are a function of the two constants
// the walk is a function of — move the read and this reds, in this file.
const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
+ `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
+ `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
&& CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

// ⛔ The subtree spelling is the one this declaration must never take. The walk
// is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
// nested script it never opens, which is the costlier error the idiom prices
// above a missing declaration.
expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
+ 'ends in a subtree glob and none collapses back to the bare root',
!ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

// The local matcher for `<root>/*<ext>`: one directory level, one extension.
const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
return Boolean(m) && p.startsWith(`${m[1]}/`)
&& !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
});
const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
const unnamed = corpusPaths.filter((p) => !declaresPath(p));
expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
+ `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
+ `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
corpusPaths.length > 0 && unnamed.length === 0);
expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

// PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
// taken from the tree rather than spelled: a nested script, and a top-level
// file at an extension the walk does not admit. Non-vacuous by construction —
// the assertion fails if the tree stops carrying an example of either.
const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
const nested = topLevel
.filter((e) => e.isDirectory())
.flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
.filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
.map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
+ `extensions (${nested.length}) and the declaration names NONE of them`,
nested.length > 0 && !nested.some(declaresPath));
const otherExt = topLevel
.filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
.map((e) => `${CORPUS_ROOT}/${e.name}`);
expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
+ `not admit (${otherExt.length}) and the declaration names NONE of them`,
otherExt.length > 0 && !otherExt.some(declaresPath));

// ⚠️ The brace form is what the header, the `--list` banner and the OK line all
// spell for a human reader, and it is DEAD as a hint — no brace expansion in
// the matcher, so it would reach nothing while reading like a declaration.
// Pinned so the tidier-looking spelling cannot quietly replace the live one.
expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
+ 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
!ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

if (failures.length > 0) {
for (const f of failures) console.error(` x self-test: ${f}`);
console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down
49 changes: 43 additions & 6 deletions scripts/pm/bare-root-worklist.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
* re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
* docblock forbids by name.
*
* ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
* sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
* Its refusal rested on the deletion-collapse too, in the variant that splices
* WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
* `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
* spelling" was true of the derivation that wrote it and false of this one.
* #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
* in its own docblock as "the same defect as the non-final case one level
* finer". So this is the identical retired mechanism, not a new licence, and it
* is a RE-DECISION rather than a repair for the same reason the eighteen before
* it were. Its consumer is #13813 and it is MEASURED: the family sat in the
* residue's undetermined bucket, outside the matched list a brief prints, and a
* PR that ran its whole derived family green locally lost a CI round to this
* gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
* NOT carried from the row they replace, which this docblock forbids by name.
*
* ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
* merely fresher digits: #12392 (PR #12423, `69d0e18`) made
* `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
+ 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
+ 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
}],
['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
verdict: 'DECLARED-NARROWER',
why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
+ 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
+ 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
+ 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
+ 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
+ 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
+ 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
+ 'refinement finer, and this row is re-decided under that authorisation sentence and no '
+ 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
+ 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
+ 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
+ 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
+ '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
+ 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
+ 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
+ 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
+ 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
+ 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
+ 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
+ 'the derivation placed this family in the residue undetermined bucket, absent from the '
+ 'matched list a brief prints, and a PR that ran its whole derived family green locally '
+ 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
+ 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
+ 'at any depth — which is what this verdict says and is correct, not outstanding debt',
}],
// ── Refused: the population is the whole root, and the root is saturated ──
['check:skill-identifier-liveness IMPL_ROOTS packages', {
verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
why: '162 of 238 (68%), refused with its packages half for the reason above',
}],
// ── Refused: the population is a filter the idiom cannot spell ────────────
['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
verdict: 'REFUSE-UNSPELLABLE',
why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
+ 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
+ 'non-recursive spelling: a subtree hint claims every nested directory too',
}],
['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
verdict: 'REFUSE-UNSPELLABLE',
why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps#14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

baozhoutao
merged 1 commit into

from

Sep 1, 2026

+184

−8

 Merged


Declare the non-recursive scripts population check:ratchet-remedy-authority really sweeps
#14231
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


143 changes: 141 additions & 2 deletions
scripts/check-ratchet-remedy-authority.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -104,7 +104,7 @@
// node scripts/check-ratchet-remedy-authority.mjs --self-test # the detector's own rules

import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { join, dirname, resolve, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import process from 'node:process';
import { isEntrypoint } from './invoked-as.mjs';
Expand All@@ -115,6 +115,72 @@ const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
const SELF_FILE = 'check-ratchet-remedy-authority.mjs';
const SELF = `scripts/${SELF_FILE}`;

/**
 * The two extensions the corpus walk admits, as ONE constant rather than two
 * `endsWith` calls inline — so the declaration below can be held against the
 * thing the sweep really filters on instead of against a second copy of it.
 * The `.mts` half is the #8538 blind spot and is not decoration: see the header.
 */
const CORPUS_EXTENSIONS = ['.mjs', '.mts'];

/**
 * The population this gate READS, declared for `scripts/pm/dispatch-gates.mjs`
 * -- the `ROOT_DIR_WATCH_HINTS` idiom, spelled as a literal array because the
 * hint extractor reads SOURCE TEXT (`scripts/check-watch-hint-literal.mjs`
 * holds that spelling for every declarer in the tree).
 *
 * ## Why this gate declared NOTHING, and what that cost (#13813)
 *
 * `extractWatchHints` scans the module body for path-shaped literals. This file
 * builds its population at RUNTIME from `readdirSync(SCRIPTS_DIR)`, and the
 * string naming that population appeared only in the failure text, in the
 * `--list` banner and in the header comment -- never as a literal the scanner
 * could read. So the derivation read no population here and made no claim, and
 * the family landed in the residue's `undetermined` bucket: not matched, not
 * known-irrelevant, and absent from the `matched` list a dispatch brief prints.
 *
 * That is not a theoretical gap. A PR touching three `scripts/**` files ran its
 * whole derived family locally, green, and CI reddened on THIS gate -- both
 * readings true, of the same tree. Eight families matched those same three
 * paths, every one of them at `gate source 'scripts/**'`, because their
 * populations are spelled where the derivation can read them.
 *
 * ## Why the spelling is the flat-directory glob and NOT `scripts/**`
 *
 * `corpusFiles()` is a NON-RECURSIVE `readdirSync` admitted by extension. It
 * reads the top level of `scripts/` only -- never `scripts/pm/`,
 * `scripts/docs-audit/` or any other nested directory -- and only the two
 * extensions above. `scripts/**` would be the easy spelling and it would be
 * FALSE: it pastes this gate onto every card touching any nested script, for
 * files this gate never opens, which is the costlier error `hintCovers`' own
 * docblock prices above a missing declaration.
 *
 * The two hints here are 100% precise AND complete against this tree, set-equal
 * in both directions to what `corpusFiles()` walks -- 183 of 183, against 310
 * tracked files under the bare root -- and the self-test below re-measures that
 * rather than trusting this sentence.
 *
 * ⚠️ NOT `scripts/*.{mjs,mts}`, however natural it looks beside the header and
 * the failure text, which both spell the corpus that way for a human reader.
 * `hintCovers` has no brace expansion, so that one string reaches NOTHING --
 * a dead declaration, printed as the same silence as declaring nothing at all.
 * One hint per extension is the spelling that is live, and a self-test case
 * pins the brace form as dead so the tidier spelling cannot quietly land.
 *
 * ## Why this spelling exists at all today
 *
 * `scripts/pm/bare-root-worklist.mjs` recorded this population as
 * REFUSE-UNSPELLABLE on the grounds that "the idiom has no non-recursive
 * spelling". That was TRUE when it was written: `collapseHint` deleted the glob
 * and spliced the remainder inside the final segment, so this hint collapsed to
 * `scripts/.mjs`, a string no tree can hold. #13448 retired that collapse for
 * exactly this shape -- a glob carrying a literal SUFFIX in the final segment is
 * MATCHED now, through `judgedAsPattern`/`triggerCovers`, not collapsed -- so
 * the refusal became false of the tree without anything reddening. That row is
 * re-decided alongside this declaration, in the file that owns it.
 */
const ROOT_DIR_WATCH_HINTS = ['scripts/*.mjs', 'scripts/*.mts'];

/** The compliance token. Byte-identical to every instrumented gate's const. */
const RATCHET_AUTHORITY_MARKER = '⛔ MAINTAINER-ONLY';

Expand DownExpand Up@@ -838,7 +904,7 @@ const CONTROL = {
/** @returns {string[]} corpus filenames, sorted. `*.{mjs,mts}` — never `*.mjs`. */
export function corpusFiles() {
 return readdirSync(SCRIPTS_DIR)
 .filter((f) => f.endsWith('.mjs') || f.endsWith('.mts'))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .sort();
}

Expand DownExpand Up@@ -1119,6 +1185,79 @@ function selfTest() {
 + 'control is a declaration registry, and its offer-shaped quotes live in comments)',
 results.get(SELF_FILE) !== undefined && results.get(SELF_FILE).verdict === 'excluded');

 // ── (20) The declared population, held to the walk in BOTH directions (#13813)
 //
 // ⛔ Checked with a LOCAL matcher rather than by importing
 // `scripts/pm/dispatch-gates.mjs`: the import specifier would itself be a path
 // literal in this file's source, so the derivation would hand this gate that
 // module's declared population as if it were this gate's own — a fabricated
 // watch surface. (The same refusal `check-logger-receiver-detach.mjs` records.)
 // The liveness of these hints in `hintCovers`' own terms is pinned where
 // `hintCovers` is already in scope: `scripts/pm/bare-root-worklist.mjs`.
 //
 // Both directions, because either alone passes against the defect this closes.
 // "The declaration is non-empty" was true of every gate that ever went silent;
 // "it names the root" is true of `scripts/**`, which is the FALSE spelling
 // here. What is asserted is that the hints are a function of the two constants
 // the walk is a function of — move the read and this reds, in this file.
 const CORPUS_ROOT = relative(REPO_ROOT, SCRIPTS_DIR).split('\\').join('/');
 expect('declaration — one hint per admitted extension, each the flat-directory glob under the '
 + `very root the walk reads from (declared: ${JSON.stringify(ROOT_DIR_WATCH_HINTS)}, root: `
 + `${CORPUS_ROOT}, extensions: ${CORPUS_EXTENSIONS.join(' ')})`,
 ROOT_DIR_WATCH_HINTS.length === CORPUS_EXTENSIONS.length
 && CORPUS_EXTENSIONS.every((ext) => ROOT_DIR_WATCH_HINTS.includes(`${CORPUS_ROOT}/*${ext}`)));

 // ⛔ The subtree spelling is the one this declaration must never take. The walk
 // is a NON-RECURSIVE readdir; `scripts/**` would name this gate for every
 // nested script it never opens, which is the costlier error the idiom prices
 // above a missing declaration.
 expect('declaration — the subtree spelling is refused: the walk is non-recursive, so no hint '
 + 'ends in a subtree glob and none collapses back to the bare root',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.endsWith('/**') || h.replace(/\/\*+$/, '') === CORPUS_ROOT));

 // The local matcher for `<root>/*<ext>`: one directory level, one extension.
 const declaresPath = (p) => ROOT_DIR_WATCH_HINTS.some((h) => {
 const m = /^([^/]+)\/\*(\.[a-z]+)$/.exec(h);
 return Boolean(m) && p.startsWith(`${m[1]}/`)
 && !p.slice(m[1].length + 1).includes('/') && p.endsWith(m[2]);
 });
 const corpusPaths = corpusFiles().map((f) => `${CORPUS_ROOT}/${f}`);
 const unnamed = corpusPaths.filter((p) => !declaresPath(p));
 expect('declaration — COMPLETE: every file the sweep opens is named by a declared hint '
 + `(${corpusPaths.length} swept, ${unnamed.length} unnamed`
 + `${unnamed.length ? `: ${unnamed.slice(0, 3).join(', ')}` : ''})`,
 corpusPaths.length > 0 && unnamed.length === 0);
 expect('declaration — no hint is DEAD: each one names at least one file this gate really reads',
 ROOT_DIR_WATCH_HINTS.every((h) => corpusPaths.some((p) => declaresPath(p) && p.endsWith(h.slice(h.indexOf('*') + 1)))));

 // PRECISE, against the two shapes `scripts/**` would wrongly sweep in, both
 // taken from the tree rather than spelled: a nested script, and a top-level
 // file at an extension the walk does not admit. Non-vacuous by construction —
 // the assertion fails if the tree stops carrying an example of either.
 const topLevel = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
 const nested = topLevel
 .filter((e) => e.isDirectory())
 .flatMap((d) => readdirSync(join(SCRIPTS_DIR, d.name))
 .filter((f) => CORPUS_EXTENSIONS.some((ext) => f.endsWith(ext)))
 .map((f) => `${CORPUS_ROOT}/${d.name}/${f}`));
 expect('declaration — PRECISE against depth: the tree carries nested scripts at the admitted '
 + `extensions (${nested.length}) and the declaration names NONE of them`,
 nested.length > 0 && !nested.some(declaresPath));
 const otherExt = topLevel
 .filter((e) => e.isFile() && !CORPUS_EXTENSIONS.some((ext) => e.name.endsWith(ext)))
 .map((e) => `${CORPUS_ROOT}/${e.name}`);
 expect('declaration — PRECISE against extension: the root carries top-level files the walk does '
 + `not admit (${otherExt.length}) and the declaration names NONE of them`,
 otherExt.length > 0 && !otherExt.some(declaresPath));

 // ⚠️ The brace form is what the header, the `--list` banner and the OK line all
 // spell for a human reader, and it is DEAD as a hint — no brace expansion in
 // the matcher, so it would reach nothing while reading like a declaration.
 // Pinned so the tidier-looking spelling cannot quietly replace the live one.
 expect('declaration — the brace form the messages spell is NOT what is declared (it reaches '
 + 'nothing, and a dead declaration prints as the same silence as declaring nothing)',
 !ROOT_DIR_WATCH_HINTS.some((h) => h.includes('{')));

 if (failures.length > 0) {
 for (const f of failures) console.error(` x self-test: ${f}`);
 console.error(`\ncheck-ratchet-remedy-authority --self-test: ${failures.length} failure(s).\n`);
Expand Down

49 changes: 43 additions & 6 deletions
scripts/pm/bare-root-worklist.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -202,6 +202,22 @@ const POPULATION_CONSTANT = /^(?:[A-Z0-9_]*_ROOTS?|[A-Z0-9_]*_DIRS?|POPULATION|[
 * re-measured on the 2026-08-29 tree and NOT carried from its sibling, which this
 * docblock forbids by name.
 *
 * ⭐ A NINETEENTH row was re-decided on 2026-09-01 under that same authorisation
 * sentence and no wider one: `check:ratchet-remedy-authority SCRIPTS_DIR scripts`.
 * Its refusal rested on the deletion-collapse too, in the variant that splices
 * WITHIN a final segment rather than across a separator — `scripts/*.mjs` became
 * `scripts/.mjs`, a string no tree can hold — so "the idiom has no non-recursive
 * spelling" was true of the derivation that wrote it and false of this one.
 * #13448 retired that collapse for the shape, which `dispatch-gates.mjs` states
 * in its own docblock as "the same defect as the non-final case one level
 * finer". So this is the identical retired mechanism, not a new licence, and it
 * is a RE-DECISION rather than a repair for the same reason the eighteen before
 * it were. Its consumer is #13813 and it is MEASURED: the family sat in the
 * residue's undetermined bucket, outside the matched list a brief prints, and a
 * PR that ran its whole derived family green locally lost a CI round to this
 * gate. ⛔ Its numbers are re-measured on the 2026-09-01 tree in BOTH terms and
 * NOT carried from the row they replace, which this docblock forbids by name.
 *
 * ⚠️ One row of that seventeen was re-measured into a DIFFERENT population, not
 * merely fresher digits: #12392 (PR #12423, `69d0e18`) made
 * `check-skills-token-ratchet`'s walk RECURSIVE over whole skill directories, so
Expand DownExpand Up@@ -393,6 +409,33 @@ const TRIAGE = new Map([
 + 'missed defect. The row STAYS in the sweep because the bare root is still not covered — '
 + 'no arbitrary file at the top of packages/ is reached — which is what this verdict says',
 }],
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'DECLARED-NARROWER',
 why: 'RE-DECIDED 2026-09-01 (#13813) from REFUSE-UNSPELLABLE, whose stated reason — "the idiom '
 + 'has no non-recursive spelling" — was TRUE when written and is FALSE of this tree. It '
 + 'rested on the deletion-collapse: a glob carrying a literal SUFFIX in the final segment '
 + 'was spliced WITHIN the segment, so the only non-recursive spelling reduced to a string no '
 + 'tree can hold and reached nothing. #13448 retired that collapse for exactly this shape — '
 + 'judgedAsPattern routes it to triggerCovers now — which is the same retired collapse the '
 + 'seventeen rows of 2026-08-26 and the eighteenth of 2026-08-29 were re-decided under, one '
 + 'refinement finer, and this row is re-decided under that authorisation sentence and no '
 + 'wider one. Both terms re-measured together on this tree, never refreshed apart: the gate '
 + 'own corpusFiles() walk admits 183 files, against 310 tracked under the bare root (59%). '
 + 'The gate now declares ONE hint per admitted extension beside SCRIPTS_DIR under the '
 + 'ROOT_DIR_WATCH_HINTS idiom, and the pair is SET-EQUAL to that walk in both directions — '
 + '183 of 183, nothing read left uncovered, nothing covered left unread — so 100% precise '
 + 'and complete. ⛔ NO `spelling` is recorded and that is deliberate, not an omission: '
 + 'SPELLINGS holds ONE hint per entry and this population needs one per extension, the same '
 + 'shape as the check:logger-receiver-detach and check:dual-build-cjs-loads rows above, so '
 + 'the liveness-and-precision coupling is held in the gate own --self-test, which pins the '
 + 'hints against SCRIPTS_DIR and CORPUS_EXTENSIONS and refuses both the subtree spelling and '
 + 'the brace form its own messages print. The consumer is MEASURED, not argued: before this, '
 + 'the derivation placed this family in the residue undetermined bucket, absent from the '
 + 'matched list a brief prints, and a PR that ran its whole derived family green locally '
 + 'lost a CI round to this gate. The row STAYS in the sweep because the bare root is still '
 + 'not covered — no arbitrary file at the top of the root is reached, and no nested script '
 + 'at any depth — which is what this verdict says and is correct, not outstanding debt',
 }],
 // ── Refused: the population is the whole root, and the root is saturated ──
 ['check:skill-identifier-liveness IMPL_ROOTS packages', {
 verdict: 'REFUSE-WIDE',
Expand DownExpand Up@@ -489,12 +532,6 @@ const TRIAGE = new Map([
 why: '162 of 238 (68%), refused with its packages half for the reason above',
 }],
 // ── Refused: the population is a filter the idiom cannot spell ────────────
 ['check:ratchet-remedy-authority SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'reads the TOP LEVEL of the root only, and only two extensions (`.mjs` and `.mts`) — 144 '
 + 'of 261 (55%), re-derived from the gate own corpusFiles() walk. The idiom has no '
 + 'non-recursive spelling: a subtree hint claims every nested directory too',
 }],
 ['scripts/check-declaration-mirrors.mjs SCRIPTS_DIR scripts', {
 verdict: 'REFUSE-UNSPELLABLE',
 why: 'a RECURSIVE walk admitted by EXTENSION — every `scripts/**/*.d.mts`, 2 of 261 (0.77%), '
Expand Down
Loading