objectstack-ai
diff --git a/‎scripts/check-i18n-coverage.mjs‎
Lines changed: 224 additions & 16 deletions b/‎scripts/check-i18n-coverage.mjs‎
Lines changed: 224 additions & 16 deletions
diff --git a/‎scripts/pm/bare-root-worklist.mjs‎
Lines changed: 9 additions & 0 deletions b/‎scripts/pm/bare-root-worklist.mjs‎
Lines changed: 9 additions & 0 deletions
@@ -89,9 +89,37 @@
 // converse, and one discipline serves both: measure EVERY config, then report every
 // DISTINCT cause once, with the configs it covers. A config that cannot be linted is
 // now collected (`measureI18nIssues` returns a failure), never thrown.
+//
+// Both of those are about a config that could not be MEASURED. #10907 is about
+// the population itself, and it is the failure this gate could not report at all:
+// every path here was resolved CWD-RELATIVELY — `examples`, `packages`, the
+// baseline, the CLI stub — so run from anywhere but the repo root the gate found
+// no configs, compared nothing, and printed
+//
+//     check-i18n-coverage: OK (0 config(s), 0 baselined untranslated string(s), none new).
+//     exit 0
+//
+// — the same sentence, and the same exit code, a real pass uses. What makes that
+// silent rather than merely wrong is an INTERLOCK: this is a two-sided ratchet, so
+// a config that vanishes is normally caught by the DOWN direction ("baselined
+// config is gone"). But the population and the baseline were resolved the same
+// way, so a wrong root emptied them TOGETHER and left the comparison with nothing
+// to disagree about. Anchoring one side alone would not have been a fix — it would
+// have turned the silence into twelve spurious errors.
+//
+// Two halves, and the file keeps both. (1) Every read is anchored to a root
+// derived from `import.meta.url`, as `check-skills-token-ratchet.mjs` and
+// `check-ratchet-remedy-authority.mjs` do; the repo-relative spellings stay, since
+// they are the committed baseline's KEYS and the text a reader acts on, and `at()`
+// is the one seam between the two. (2) An empty population is REFUSED rather than
+// returned — zero is a broken scan, not a repo with nothing to translate (#4690),
+// the same rule `trackedFiles` states in `scripts/pm/dispatch-gates.mjs`. Half 1
+// makes the off-root run correct; half 2 is what keeps "green over nothing"
+// unreachable by the routes half 1 does not know about.
 import { execFileSync } from 'node:child_process';
 import { readdirSync, readFileSync, writeFileSync, existsSync, openSync, closeSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import {
@@ -102,9 +130,33 @@ import {
   resolveCliCommandFile,
 } from './cli-build-prerequisite.mjs';
 
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** This script lives in `scripts/`, so the repo root is one level up (#10907). */
+const REPO_ROOT = resolve(HERE, '..');
+
+// Repo-relative ON PURPOSE — these spellings are the committed baseline's KEYS,
+// the paths in every error message, and the commands `rerunFix` tells a reader to
+// run. Making them absolute would silently re-key all twelve baseline entries.
+// `at()` below is the ONE seam that turns a repo-relative path into a path on
+// disk, so the vocabulary stays relative while every READ is anchored (#10907).
 // NOTE: covers both `examples/*` and every package with an extract config.
 const EXAMPLES_DIR = 'examples';
+const PACKAGES_DIR = 'packages';
 const BASELINE_PATH = 'scripts/i18n-coverage-baseline.json';
+
+// ⛔ Neither root above is declared to the dispatch derivation, and that is a
+// recorded REFUSAL rather than an omission. Both populations are FILENAME
+// filters — one `objectstack.config.ts` per example directory (3 of 240), and
+// files named `i18n-extract.config.ts` beneath a `scripts` segment (9 of 5035).
+// The `ROOT_DIR_WATCH_HINTS` idiom can only name a whole subtree, so the only
+// spellable claim here would name this gate for 5035 files to reach 9 — the
+// costlier error, per `hintCovers`. Both verdicts are recorded as
+// REFUSE-UNSPELLABLE in the triage that `scripts/pm/bare-root-worklist.mjs`
+// self-tests on every PR; giving `PACKAGES_DIR` a population-constant name is
+// what made this root visible to that sweep at all.
+
+/** A repo-relative path, resolved against the module-derived root. */
+const at = (rel) => join(REPO_ROOT, rel);
 /** The one command this gate invokes per config, as oclif topic/command parts. */
 const LINT_COMMAND_ID = ['lint'];
 
@@ -120,13 +172,13 @@ const INSTALL_THEN_BUILD_FIX = 'pnpm install && pnpm build';
 
 const update = process.argv.includes('--update');
 
-/** Every bundled example that has a stack config. */
+/** Every bundled example that has a stack config. Root-anchored, repo-relative out. */
 function discoverExamples() {
-  if (!existsSync(EXAMPLES_DIR)) return [];
-  return readdirSync(EXAMPLES_DIR, { withFileTypes: true })
+  if (!existsSync(at(EXAMPLES_DIR))) return [];
+  return readdirSync(at(EXAMPLES_DIR), { withFileTypes: true })
     .filter((e) => e.isDirectory())
     .map((e) => join(EXAMPLES_DIR, e.name, 'objectstack.config.ts'))
-    .filter((p) => existsSync(p))
+    .filter((p) => existsSync(at(p)))
     .sort();
 }
 
@@ -139,9 +191,9 @@ function discoverExamples() {
  * Studio. Covering only `examples/` is how `platform-objects` sat on 77
  * untranslated navigation and widget labels per locale without anything saying so.
  */
-function discoverPackages(dir = 'packages', out = []) {
-  if (!existsSync(dir)) return out;
-  for (const e of readdirSync(dir, { withFileTypes: true })) {
+function discoverPackages(dir = PACKAGES_DIR, out = []) {
+  if (!existsSync(at(dir))) return out;
+  for (const e of readdirSync(at(dir), { withFileTypes: true })) {
     if (e.name === 'node_modules' || e.name === 'dist' || e.name.startsWith('.')) continue;
     const p = join(dir, e.name);
     if (e.isDirectory()) discoverPackages(p, out);
@@ -241,6 +293,47 @@ function packageNameFromSpecifier(specifier) {
   return name.endsWith('.mjs') || name.endsWith('.js') || name.endsWith('.ts') ? '' : name;
 }
 
+/**
+ * The POPULATION classifier (#10907): is there anything to judge at all?
+ *
+ * Pure — list in, verdict out — so `--self-test` drives both directions. That
+ * matters more here than for any other classifier in this file: an empty
+ * population is the one failure that RENDERS AS A PASS, so a gate that had only
+ * ever observed its own green path could not tell the two apart. That is #4690
+ * exactly, and `trackedFiles` in `scripts/pm/dispatch-gates.mjs` refuses an empty
+ * listing on the same grounds — "zero is a broken scan, not a clean repo".
+ *
+ * Judged on the UNION, deliberately, not per half. A single vanished config is
+ * already this gate's business: the two-sided ratchet reports it as a DOWN and
+ * tells the reader to `--update`. Refusing on an empty HALF would preempt that
+ * legitimate path — the last example being retired is a real event, not a broken
+ * scan. Only a total wipe is indistinguishable from a scan that read nothing, and
+ * only a total wipe is refused here.
+ *
+ * @param {string[]} configPaths the discovered population, repo-relative
+ * @returns {{ headline: string, detail: string[] } | null} null when there is work to do
+ */
+function emptyPopulationVerdict(configPaths) {
+  if (configPaths.length > 0) return null;
+  return {
+    headline: 'the config population came back EMPTY — there is nothing to measure',
+    detail: [
+      `Neither \`${EXAMPLES_DIR}/*/objectstack.config.ts\` nor any`,
+      `\`${PACKAGES_DIR}/**/scripts/i18n-extract.config.ts\` was found under the root this`,
+      `script derives from its own location:`,
+      ``,
+      `  ${REPO_ROOT}`,
+      ``,
+      `Zero is a broken scan, not a repo with nothing to translate (#4690). Note what`,
+      `an empty population costs THIS gate specifically: it is a two-sided ratchet, so`,
+      `a config that really did vanish is caught by the DOWN direction — but the`,
+      `population and the baseline are read the same way, so a tree this script cannot`,
+      `read empties BOTH, leaving the comparison with nothing to disagree about and a`,
+      `verdict identical to a real pass. Refusing rather than reporting OK over nothing.`,
+    ],
+  };
+}
+
 /**
  * Distinct CAUSES, each carrying the configs it explains. Keyed on the CONCLUSION
  * (reason + fix) rather than the raw reading, because one unbuilt package produces
@@ -284,7 +377,13 @@ function measureI18nIssues(configPath) {
   try {
     let stderr = '';
     try {
+      // `CLI` and `configPath` are both REPO-RELATIVE, so the child's cwd is what
+      // resolves them — anchoring it here is what makes an off-root run measure the
+      // real population instead of failing twelve times (#10907). It also keeps
+      // `os lint`'s own workspace resolution pointed at the repo, not at wherever
+      // the caller happened to stand.
       execFileSync(process.execPath, [CLI, 'lint', configPath, '--json'], {
+        cwd: REPO_ROOT,
         stdio: ['ignore', fd, 'pipe'],
       });
     } catch (err) {
@@ -553,12 +652,84 @@ function selfTest() {
   expect('#6033 one cause is stated once', sharedCause.length === 1, `got ${sharedCause.length} cause(s) for one missing package`);
   expect('#6033 …carrying every config it covers', sharedCause[0]?.configPaths.length === 3, `got ${JSON.stringify(sharedCause[0]?.configPaths)}`);
 
+  // -------------------------------------------------------------------------
+  // Root anchoring and the population classifier (#10907). These are the only
+  // assertions in this file that can fail over a CORRECT tree in a WRONG place,
+  // and that is the whole point: every other classifier here is proven red with a
+  // recorded string, but "did this gate look at anything at all?" can only be
+  // proven by looking.
+  // -------------------------------------------------------------------------
+
+  // The derivation must land on THIS repo's root — one level off would still find
+  // a `scripts/` directory, so pin files only the root has, this gate's own two
+  // included.
+  expect(
+    '#10907 derives the repo root',
+    existsSync(at('package.json')) && existsSync(at(BASELINE_PATH)) && existsSync(at('scripts/check-i18n-coverage.mjs')),
+    `REPO_ROOT does not look like this repo's root: ${REPO_ROOT}`,
+  );
+
+  // The anchoring itself, proven the only way that means anything: from a cwd that
+  // is NOT the repo root. This single assertion is the #10907 defect — before the
+  // fix both discoveries read a bare `examples` / `packages`, came back empty from
+  // anywhere else, and the gate printed `OK (0 config(s))` and exited 0. cwd is
+  // restored in a `finally`: it is process-global state, and a self-test that
+  // leaves it moved would corrupt every measurement after it.
+  const cwdBefore = process.cwd();
+  let offRoot;
+  try {
+    process.chdir(tmpdir());
+    offRoot = [...discoverExamples(), ...discoverPackages()];
+  } finally {
+    process.chdir(cwdBefore);
+  }
+  const onRoot = [...discoverExamples(), ...discoverPackages()];
+  expect(
+    '#10907 discovery is CWD-independent',
+    offRoot.length > 0,
+    `discovery from ${tmpdir()} found ${offRoot.length} config(s) — the population is still resolved CWD-relatively, ` +
+      'which is the whole defect: an empty population renders as a pass',
+  );
+  expect(
+    '#10907 …and finds exactly the population the root does',
+    offRoot.join('\n') === onRoot.join('\n'),
+    `off-root found ${offRoot.length} config(s), on-root ${onRoot.length} — anchoring must not change WHAT is scanned`,
+  );
+  expect(
+    '#10907 …spelled repo-relative, as the baseline keys are',
+    offRoot.every((p) => !p.startsWith('/') && !p.includes(REPO_ROOT)),
+    `absolute paths would silently re-key every baseline entry; got ${JSON.stringify(offRoot.slice(0, 2))}`,
+  );
+
+  // Anti-#4690 on the population itself. Red on nothing is the assertion that
+  // matters — this is the one verdict whose failure mode is a green line.
+  expect('#10907 an empty population is refused', !!emptyPopulationVerdict([]), 'zero configs must never be a pass');
+  expect(
+    '#10907 …with a complete verdict',
+    !!emptyPopulationVerdict([])?.headline && (emptyPopulationVerdict([])?.detail?.length ?? 0) > 0,
+    `a refusal with no reading under it is not auditable; got ${JSON.stringify(emptyPopulationVerdict([]))}`,
+  );
+  expect(
+    '#10907 a real population is not refused',
+    emptyPopulationVerdict(['examples/app-crm/objectstack.config.ts']) === null,
+    'one config is work to do, not a broken scan — refusing it would preempt the ratchet-DOWN path',
+  );
+  expect(
+    '#10907 the live population is not refused',
+    emptyPopulationVerdict(onRoot) === null,
+    `the real tree resolved to ${onRoot.length} config(s) and must be judged, not refused`,
+  );
+
   if (failures.length) {
     console.error(`✗ check:i18n-coverage --self-test — ${failures.length} failure(s)\n`);
     for (const f of failures) console.error(`  ${f}`);
     process.exit(1);
   }
-  console.log('✓ check:i18n-coverage --self-test — the missing-CLI-build, i18n-rule and per-config-failure classifiers all go red, stay distinct, and a failing config does not end the round.');
+  console.log(
+    `✓ check:i18n-coverage --self-test — the missing-CLI-build, i18n-rule and per-config-failure classifiers all go red, ` +
+      `stay distinct, and a failing config does not end the round; the population resolves to ${onRoot.length} config(s) ` +
+      `from outside the repo root as well as inside it, and an empty one is refused rather than reported OK.`,
+  );
 }
 
 if (process.argv.includes('--self-test')) {
@@ -654,6 +825,35 @@ function reportUnmeasuredConfigs(failures, measuredCount) {
   process.exit(1);
 }
 
+/**
+ * The refusal for an empty population (#10907) — reached before a single CLI is
+ * spawned and before `--update` can write, which is the point on both counts.
+ *
+ * `--update` is the sharper of the two: it runs BEFORE any comparison, so over an
+ * empty population it would write `{}` and ratchet all twelve baselined configs
+ * out of existence — real, frozen debt discarded by a command whose whole purpose
+ * is to record it. Same invariant the two reports above state, and for the same
+ * reason: nothing measured, nothing written.
+ *
+ * Exits 1, the code every other verdict here uses.
+ *
+ * @param {{ headline: string, detail: string[] }} verdict
+ */
+function reportEmptyPopulation(verdict) {
+  console.error(
+    `\ncheck-i18n-coverage: POPULATION EMPTY — ${verdict.headline}\n\n` +
+      verdict.detail.map((l) => (l ? `  ${l}` : '')).join('\n') +
+      `\n\n  Fix:  run this gate from a complete checkout of the repo. \`pnpm check:i18n-coverage\`\n` +
+      `        is the invocation CI uses, and pnpm runs it from the repo root.\n\n` +
+      `  Nothing was measured: no config was linted and no count was compared, so this\n` +
+      `  result says NOTHING about whether any declared label went untranslated — and\n` +
+      `  the baseline was left exactly as committed (\`--update\` included).\n` +
+      `  (Exit code 1 — but piping this gate reports the PIPE's status, so\n` +
+      `  \`pnpm check:i18n-coverage | tail -4\` reads green either way. Use \`echo "EXIT=$?"\`.)`,
+  );
+  process.exit(1);
+}
+
 /**
  * Answered once, before the per-config loop — so a missing build costs one
  * verdict instead of an exception thrown from inside the first example, and
@@ -676,7 +876,12 @@ function checkCliBuildPrerequisite() {
     console.error(`check-i18n-coverage: ${resolved.unknown} — build prerequisite not pre-checked`);
     return;
   }
-  if (existsSync(resolved.file)) return;
+  // `resolved.file` is repo-relative (`packages/cli/dist/commands/lint.js`), so it
+  // needs the same anchoring as everything else — unanchored, an off-root run that
+  // got this far would report "the workspace CLI is not built" about a CLI that is
+  // built, which is the #5862 defect (a confident diagnosis pointing somewhere
+  // innocent) rebuilt one layer down.
+  if (existsSync(at(resolved.file))) return;
   reportPrerequisiteNotMet('the workspace CLI is not built', [
     `This gate counts what \`os lint\` reports, and it runs the BUILT CLI.`,
     `${CLI} is only a source stub that hands off to oclif, which`,
@@ -689,21 +894,24 @@ function checkCliBuildPrerequisite() {
 
 checkCliBuildPrerequisite();
 
-const { current, failures: unmeasured } = measureAllConfigs(
-  [...discoverExamples(), ...discoverPackages()],
-  measureI18nIssues,
-);
+const configPaths = [...discoverExamples(), ...discoverPackages()];
+// Before a single CLI is spawned, and before `--update` can write: a round with no
+// population has no verdict to give and no baseline to rewrite (#10907).
+const emptyPopulation = emptyPopulationVerdict(configPaths);
+if (emptyPopulation) reportEmptyPopulation(emptyPopulation);
+
+const { current, failures: unmeasured } = measureAllConfigs(configPaths, measureI18nIssues);
 // Before `--update` writes anything, and before any comparison: a round that could
 // not measure every config has no verdict to give and no baseline to rewrite.
 if (unmeasured.length) reportUnmeasuredConfigs(unmeasured, Object.keys(current).length);
 
 if (update) {
-  writeFileSync(BASELINE_PATH, JSON.stringify(current, null, 2) + '\n');
+  writeFileSync(at(BASELINE_PATH), JSON.stringify(current, null, 2) + '\n');
   console.log(`i18n coverage baseline updated: ${Object.keys(current).length} config(s).`);
   process.exit(0);
 }
 
-const baseline = existsSync(BASELINE_PATH) ? JSON.parse(readFileSync(BASELINE_PATH, 'utf8')) : {};
+const baseline = existsSync(at(BASELINE_PATH)) ? JSON.parse(readFileSync(at(BASELINE_PATH), 'utf8')) : {};
 
 const errors = [];
 for (const [file, count] of Object.entries(current)) {
 
@@ -210,6 +210,15 @@ const TRIAGE = new Map([
     verdict: 'REFUSE-UNSPELLABLE',
     why: 'one named config file per child directory — 3 of 238 (1.3%)',
   }],
+  ['check:i18n-coverage PACKAGES_DIR packages', {
+    verdict: 'REFUSE-UNSPELLABLE',
+    why: 'files named i18n-extract.config.ts beneath a scripts segment — 9 of 5035 (0.18%), the '
+      + 'narrowest row on this list. Same filename-filter shape as its EXAMPLES_DIR sibling above, '
+      + 'and refused with it rather than split: a subtree hint would name this gate for 5035 files '
+      + 'to reach 9. The root was ALWAYS this invisible — it reached the sweep only once the fix '
+      + 'for #10907 gave the literal a population-constant name, so this row records a population '
+      + 'that was previously unnameable rather than one the fix introduced',
+  }],
   ['scripts/check-skills-token-ratchet.mjs SKILLS_DIR skills', {
     verdict: 'REFUSE-UNSPELLABLE',
     why: 'one named file per child directory, 11 of 50 (22%). It already reaches its own cards '