fix(check-watch-hint-literal): red on a declared watch-hint literal the extractor drops at admission (#16799)

* wip(check-watch-hint-literal): known-positive self-test case, run against the unfixed implementation

Records acceptance item 1's first half: with the case present and the finding
class absent, the self-test reports the case as failing -- the drop is not
reported by the unfixed checker.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P58euzUXCVJNwmhuPC9DXY

* fix(check-watch-hint-literal): red on a declared literal the hint extractor drops

A watch-hint declaration can be a perfect literal array and still contribute
nothing: extractWatchHints admits a literal only when it starts with a word
character, a dot or an @, so one opening with a glob never becomes a hint and
places its gate on no card. Four instruments passed that drop because each
asked its own question and none asked whether the literals were admissible.

The sweep now asks the second question, of the extractor rather than of a copy
of its rule, one literal at a time -- a whole-module diff falsely accuses a
literal spelled inside a self-test the extractor blanks, and one written
module-relative whose extracted hint is the resolved path. The remedy names the
dropped literal, prescribes the enumerable root-prefixed spelling, and carries
the +139084-pair measurement behind the refusal so widening admission does not
read as the obvious repair.

The admission rule itself is untouched. The manifest gate's docblock stops
calling this drop silent, because it no longer is.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P58euzUXCVJNwmhuPC9DXY

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

scripts/check-manifest-repository-directory.mjs

@@ -306,10 +306,17 @@ const EXIT_PREREQ = 3;
  * retries it: `**\/package.json` is judged correctly by `hintCovers` and is
  * never SEEN, because `extractWatchHints` admits a literal only if it starts
  * with a word character, a dot or an `@`. A leading glob is dropped at
- * admission, so that declaration extracts to zero hints -- the exact silent
- * drop `check:watch-hint-literal` exists for, arrived at through the value
- * rather than through the spelling. Measured while writing this gate: the
- * one-line form extracted `[]`; the four below extract all four.
+ * admission, so that declaration extracts to zero hints -- the exact drop
+ * `check:watch-hint-literal` exists for, arrived at through the value rather
+ * than through the spelling. Measured while writing this gate: the one-line
+ * form extracted `[]`; the four below extract all four.
+ *
+ * ⚠️ That drop was SILENT when this gate was written, and is not any more:
+ * `check:watch-hint-literal` now puts every declared literal through the
+ * extractor and reds on one that yields no hint, naming this remedy. So the
+ * one-line form is refused loudly rather than dropped quietly -- retry it and
+ * a gate tells you to enumerate, which is the only part of the cost this
+ * enumeration ever paid twice.
  *
  * ⛔ NOT the workspace-root spelling `check-published-files.mjs` uses
  * (`packages/*`, `apps/*`, …). That declaration is honest THERE -- it walks

scripts/check-watch-hint-literal.mjs

@@ -107,13 +107,69 @@
  * masked before the statement is located, through the repo's one comment
  * scanner (`scripts/js-comment-mask.mjs`).
  *
+ * ## The SECOND way a declaration is invisible: the VALUE, not the spelling
+ *
+ * Everything above is about the SPELLING -- a declaration computed instead of
+ * written out. A declaration can be a perfect literal array and STILL
+ * contribute nothing, because `scripts/pm/dispatch-gates.mjs#extractWatchHints`
+ * admits a literal only when it STARTS with a word character, a dot or an `@`.
+ * A literal opening with a glob never reaches the resolve step, never becomes a
+ * hint, and places its gate on NO card:
+ *
+ *     ['scripts/**']          -> ["scripts/**"]
+ *     ['**\/package.json']    -> []            <- literal, and dropped anyway
+ *
+ * Four instruments passed that drop, because each asked its own question and
+ * none asked whether the literals were ADMISSIBLE: this gate saw a literal
+ * array, the gate's own self-test saw its own constant,
+ * `check:declared-population-live` was satisfied by nothing (a family
+ * declaring zero literals "declares nothing", a legitimate state), and it scored
+ * `undetermined` or `silent` for every card in the tree. A declaring-zero gate
+ * and a declared-but-eaten gate are the same colour on all of them.
+ *
+ * So the sweep asks the second question too, and it asks it OF THE EXTRACTOR
+ * rather than of a copy of its rule -- a second copy of an admission regex is
+ * a thing that drifts, and the drift would be silent in the same direction.
+ * Each declared literal is put through `extractWatchHints` on its own, and a
+ * literal that yields NO hint is the finding.
+ *
+ * ⛔ Admission is NOT widened to accept a leading glob, and this gate exists
+ * BECAUSE it is not: that refusal is measured (the admission comment inside
+ * `extractWatchHints` prices bare-top-level-word admission at +139084
+ * fabricated pairs, and records a re-measured refusal of the resolved-form
+ * widening), and relaxing it is a change to every gate in the farm rather than
+ * a repair to one declaration. The remedy this gate prints is therefore the
+ * enumerable root-prefixed spelling, never a request to change the rule.
+ *
+ * ⭐ What this buys is NOT cheaper enumeration -- the author of a file-kind
+ * population still has to name every root that holds the kind, and still has to
+ * pin that enumeration against the gate's own scan. It solves the other half:
+ * it does not solve the trouble of enumerating, it solves not knowing that you
+ * need to enumerate.
+ *
+ * ## Why ONE literal at a time, and never the module's whole extraction
+ *
+ * The tempting spelling is to extract the whole module and diff the declared
+ * literals against the result. Measured on this tree, that spelling is wrong in
+ * both directions. It FALSELY accuses: `scripts/pm/dispatch-gates.mjs` spells a
+ * rostered declaration inside its own self-test as a fixture string, which
+ * `extractWatchHints` blanks along with the rest of the self-test, so a
+ * perfectly admissible literal is absent from that module's extraction. And it
+ * would falsely accuse again on any declaration written module-relative, whose
+ * extracted hint is the RESOLVED path and not the literal as spelled. Probing
+ * one literal at a time asks exactly the question the finding is about -- does
+ * this literal produce a hint at all -- and neither residue reaches it.
+ *
  * ## What is asserted, and what is deliberately NOT
  *
  * Asserted: the right-hand side of the declaration is an ARRAY OF QUOTED STRING
- * LITERALS and nothing else. That is stronger than "each declared hint appears
- * quoted inside the statement", and it needs no runtime value, so this gate
- * never imports the files it judges -- a gate that imported 14 modules to read
- * one constant would run their module bodies to do it.
+ * LITERALS and nothing else, and every literal in it is one the hint extractor
+ * admits. The first is stronger than "each declared hint appears quoted inside
+ * the statement"; neither needs a runtime value, so this gate never imports the
+ * files it judges -- a gate that imported 14 modules to read one constant would
+ * run their module bodies to do it. The extractor itself IS imported, and that
+ * is the opposite case: it is the authority being consulted, not a subject
+ * being read, and it is a pure string function with no module-scope work.
  *
  * NOT asserted: that a declaration is CORRECT -- that it names the roots the
  * gate really walks, and only those. That claim is local to each gate and each
@@ -147,6 +203,7 @@ import { fileURLToPath } from 'node:url';
 
 import { isEntrypoint } from './invoked-as.mjs';
 import { maskComments } from './js-comment-mask.mjs';
+import { extractWatchHints } from './pm/dispatch-gates.mjs';
 
 // ── The self-test's own battery roster and floor (#13489) ──────────────────
 //
@@ -181,7 +238,8 @@ const SELF_TEST_BATTERIES = Object.freeze({
   'the per-name floor': 5,
   'discovery of an UNROSTERED spelling of the idiom': 5,
   'the empty population is refused, not passed': 1,
-  'the live tree': 14,
+  "literals the extractor's admission DROPS": 14,
+  'the live tree': 15,
 });
 
 // DELETING an entry silences that battery's floor exactly as effectively as
@@ -396,6 +454,57 @@ export function literalHints(rhs) {
   return rest.trim() === '' ? hints : null;
 }
 
+/**
+ * The hints `extractWatchHints` builds from ONE declared literal, standing
+ * alone under `name`.
+ *
+ * The probe source is a declaration and not a bare string on purpose: the
+ * extractor's exclusion channel keys on the DECLARATION NAME, so a future
+ * rostered name that happened to read as an exclusion would drop its literals
+ * here and be reported LOUDLY rather than judged under a rule that does not
+ * apply to it.
+ *
+ * A literal carrying both quote characters cannot be delimited, and the
+ * extractor cannot read such a span out of the real source either -- so it
+ * yields nothing here, which is the same verdict for the same reason.
+ */
+function admittedHints(name, literal) {
+  const quote = literal.includes("'") ? (literal.includes('"') ? null : '"') : "'";
+  if (quote === null) return [];
+  return extractWatchHints(`const ${name} = [${quote}${literal}${quote}];\n`);
+}
+
+/**
+ * The declared literals that produce NO hint at all -- the value-side drop.
+ *
+ * Pure over the list, and split out of `auditSourceName` for the same reason
+ * `missingNames` is split out of `main`: the self-test drives it directly, and
+ * the shape it guards against is one a healthy live tree cannot exhibit.
+ */
+export function droppedByAdmission(name, hints) {
+  return hints.filter((h) => admittedHints(name, h).length === 0);
+}
+
+/**
+ * What a dropped literal's author is told: what happened, what to write
+ * instead, and why the rule that dropped it is not the thing being changed.
+ */
+function admissionRemedy(name, dropped) {
+  return `the ${name} declaration is a literal array, and ${dropped.length} of its literal(s) build NO `
+    + `hint at all: ${dropped.map((h) => JSON.stringify(h)).join(', ')}. The hint extractor admits a `
+    + 'literal only when it STARTS with a word character, a dot or an @, so one opening with a glob '
+    + 'never reaches the resolve step, never becomes a hint, and places this gate on NO card -- the '
+    + 'same silent drop this gate exists for, arrived at through the VALUE instead of the spelling. '
+    + 'Remedy: spell the population as one enumerable root-prefixed entry per root that holds the '
+    + 'kind, and pin that enumeration against the walk this gate really performs so it cannot go '
+    + 'stale quietly. Admission is deliberately NOT widened to accept a leading glob: see the '
+    + 'admission comment inside extractWatchHints, which prices bare-top-level-word admission at '
+    + '+139084 fabricated pairs and records a re-measured refusal of the resolved-form widening -- '
+    + 'relaxing it is a change to every gate in the farm, not a repair to one declaration. This '
+    + 'finding does not solve the trouble of enumerating; it solves not knowing that you need to '
+    + 'enumerate.';
+}
+
 /**
  * One file's verdict for ONE rostered name. `null` means the file does not
  * declare that name at all -- it mentions it in prose, or reads someone else's.
@@ -426,6 +535,13 @@ export function auditSourceName(rel, source, name) {
   if (hints.length === 0) {
     return { rel, name, ok: false, why: `the ${name} declaration is EMPTY -- it names no subtree at all` };
   }
+  // The value-side question, asked only once the spelling-side one has passed:
+  // an empty or computed declaration has no literals to judge, and naming the
+  // same declaration under two remedies would leave its author choosing.
+  const dropped = droppedByAdmission(name, hints);
+  if (dropped.length > 0) {
+    return { rel, name, ok: false, why: admissionRemedy(name, dropped) };
+  }
   return { rel, name, ok: true, hints };
 }
 
@@ -530,18 +646,21 @@ function main() {
   if (bad.length) {
     console.error(
       `✗ check-watch-hint-literal: ${bad.length} of ${rows.length} declaration(s) are not readable `
-      + 'as literals. Spell the hints inside the declaration statement.',
+      + 'by the hint extractor. Spell the hints inside the declaration statement, and spell each one '
+      + 'so the extractor admits it.',
     );
     return 1;
   }
 
   const perName = DECL_NAMES
     .map((n) => `${n} ${rows.filter((r) => r.name === n).length}`)
     .join(', ');
+  const literals = rows.reduce((n, r) => n + r.hints.length, 0);
   console.log(
     `✓ check-watch-hint-literal: ${rows.length} declaration(s) across ${DECL_NAMES.length} rostered `
-    + `name(s) -- ${perName} -- every one an array of quoted literals inside its own statement, `
-    + 'every rostered name non-empty, and no unrostered spelling of the idiom in the tree.',
+    + `name(s) -- ${perName} -- every one an array of quoted literals inside its own statement, all `
+    + `${literals} of those literals admitted by the hint extractor, every rostered name non-empty, `
+    + 'and no unrostered spelling of the idiom in the tree.',
   );
   return 0;
 }
@@ -686,6 +805,60 @@ export function selfTest() {
   t('an empty file list produces no rows, which the floor above refuses',
     audit([]).rows.length === 0 && missingNames(audit([]).rows).length === DECL_NAMES.length);
 
+  // -- literals the extractor's admission DROPS ------------------------------
+  // ⭐ The value-side drop. Every case here declares a perfect literal array,
+  // so every one of them passes the spelling-side question above; what
+  // separates them is whether the hint extractor can make a hint out of what
+  // is inside it.
+  battery("literals the extractor's admission DROPS");
+  const KIND_ONE_LINER = "['**/package.json']";
+  t('a declaration whose only literal opens with a glob is rejected',
+    rejected(decl(KIND_ONE_LINER)));
+  t('...and it is rejected on the VALUE, not on the spelling -- the declaration IS a literal array',
+    literalHints(KIND_ONE_LINER) !== null && literalHints(KIND_ONE_LINER).length === 1);
+  const globWhy = verdict(decl(KIND_ONE_LINER))?.why ?? '';
+  t('the remedy names the literal that was dropped', globWhy.includes('**/package.json'));
+  t('the remedy states the admission rule that dropped it',
+    globWhy.includes('STARTS with a word character, a dot or an @'));
+  t('the remedy prescribes the enumerable root-prefixed spelling rather than only refusing',
+    globWhy.includes('enumerable root-prefixed entry per root that holds the kind'));
+  t('the remedy carries the measurement behind the refusal, so widening admission is not the obvious read',
+    globWhy.includes('+139084') && globWhy.includes('every gate in the farm'));
+  t('the remedy says what the finding is actually for',
+    globWhy.includes('it solves not knowing that you need to enumerate'));
+
+  // The negatives PR #16446 shipped: the same population, enumerated.
+  const ADMISSIBLE_KIND = [
+    'packages/**/package.json',
+    'apps/**/package.json',
+    'examples/**/package.json',
+    'package.json/**',
+  ];
+  t('the enumerated spelling of the same population is accepted',
+    accepted(decl(`[${ADMISSIBLE_KIND.map((h) => `'${h}'`).join(', ')}]`)),
+    ADMISSIBLE_KIND.join(' · '));
+  t('...and every one of those literals is admitted individually',
+    droppedByAdmission(DIR_NAME, ADMISSIBLE_KIND).length === 0);
+  t('one dropped literal among admissible ones still fails, and only it is named',
+    rejected(decl(`['scripts/**', '**/package.json']`))
+      && droppedByAdmission(DIR_NAME, ['scripts/**', '**/package.json']).join() === '**/package.json');
+
+  // ⭐ The false positive a whole-MODULE diff would produce, which is why the
+  // probe is per literal: `scripts/pm/dispatch-gates.mjs` spells a rostered
+  // declaration inside its own self-test, and the extractor blanks self-tests --
+  // so that literal is absent from that module's extraction while being
+  // perfectly admissible.
+  t('a literal is judged on its own admissibility, not on whether its module extraction carries it',
+    droppedByAdmission(DIR_NAME, ['packages/drivers/**']).length === 0);
+  t('...and a module-relative literal, whose extracted hint is the RESOLVED path, is not accused either',
+    droppedByAdmission(DIR_NAME, ['../../packages/spec/**']).length === 0);
+
+  // The two states that must keep their OWN remedy rather than acquiring this one.
+  t('an EMPTY declaration keeps the empty-population remedy, not the admission one',
+    (verdict(decl('[]'))?.why ?? '').includes('names no subtree at all'));
+  t('a COMPUTED declaration keeps the computed remedy, not the admission one',
+    (verdict(decl('[`${SCAN_ROOT}/**`]'))?.why ?? '').includes('is COMPUTED, not a literal array'));
+
   // -- the live tree ---------------------------------------------------------
   battery('the live tree');
   const { rows: live, strays } = audit(walk(REPO_ROOT));
@@ -694,6 +867,10 @@ export function selfTest() {
     `${live.length} declaration(s)`);
   t('every live declaration is a literal', live.every((r) => r.ok),
     live.filter((r) => !r.ok).map((r) => `${r.rel}:${r.name}`).join(' · '));
+  t('and every literal in every live declaration is one the hint extractor admits',
+    live.every((r) => !r.ok || droppedByAdmission(r.name, r.hints).length === 0),
+    live.flatMap((r) => (r.ok ? droppedByAdmission(r.name, r.hints)
+      .map((h) => `${r.rel}:${r.name}:${h}`) : [])).join(' · '));
   t('EVERY rostered name has a live declarer -- the floor is armed, not merely coded',
     missingNames(live).length === 0, `missing: ${missingNames(live).join(', ') || 'none'}`);
   for (const name of DECL_NAMES) {
@@ -737,7 +914,8 @@ export function selfTest() {
     + 'spellings rejected, the statement-scoped search proved against runtime and comment copies of '
     + `the literal beside it, all ${DECL_NAMES.length} rostered names judged for both spellings, the `
     + 'per-name floor proved against a population that is healthy on every name but one, unrostered '
-    + 'spellings of the idiom discovered, and the live repo-wide population judged.',
+    + 'spellings of the idiom discovered, the value-side drop proved on a literal array the extractor '
+    + 'admits nothing out of, and the live repo-wide population judged on both questions.',
   );
   selfTestReachedVerdict = true;
   return 0;