@opengsd/gsd-core 1.13.0 → 1.14.0

package/scripts/gen-platform-conformance-tier.cjs

@@ -0,0 +1,557 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates scripts/lib/platform-conformance-tier.generated.cjs — the list of
+ * test files under tests/**\/*.test.cjs whose CONTENT signals they exercise
+ * platform-specific behavior (Windows/macOS path quirks, raw child_process
+ * usage, chmod mode bits, etc.) and therefore need REAL-OS coverage rather
+ * than a Linux-only conformance lane (#4591).
+ *
+ * Only `unit`-suite test files (no suite suffix, per `scripts/run-tests.cjs`'s
+ * `suiteOf()`) are considered for the conformance tier. `install`-,
+ * `security`-, `slow`-, `integration`-, and `qa`-suffixed files are excluded
+ * entirely — never merely deprioritized — for three independent reasons: (1)
+ * `install`/`slow` are explicitly PR-excluded suites
+ * (`scripts/affected-tests-lib.cjs`'s `PR_EXCLUDED_SUITES`; "PRs must never
+ * select or run these"), and this generator's output feeds a `pull_request`-
+ * triggered job; (2) `integration`/`security` already run via their own
+ * separate, dedicated, unsharded, shard-1-only steps in the `test` job
+ * (.github/workflows/test.yml) — folding any of them into
+ * this job's generic `--files-from` + `--shard` invocation is unproven and,
+ * per the incident below, unsafe. (3) `qa` (loop-walk-suite files) already
+ * runs via its own separate, dedicated `qa-loop-walk` job
+ * (.github/workflows/test.yml) — the same rationale as (2): a purpose-built
+ * home already exists, so folding it into this job's generic invocation
+ * duplicates coverage without benefit. Real incident that surfaced this: a live
+ * CI run's `conformance test (windows-latest, shard 2/3)` job was killed with
+ * 11 tests in flight — including `tests/release-tarball-smoke.install.test.cjs`
+ * — because this generator had (wrongly) placed an `install`-suite file into
+ * the Linux-conformance candidate pool with no suite filtering at all.
+ *
+ * `classifyContent(content)` is the pure, exported classifier: it favors
+ * simple, auditable substring/regex matching over AST parsing, mirroring
+ * eslint-rules/lib/portability-vocab.cjs's own design stance (over-inclusion
+ * is the safe direction — a false positive costs one extra test running on a
+ * real OS; a false negative silently drops real-OS coverage).
+ *
+ * That stance is a correct per-file tiebreak, but proved wrong in aggregate
+ * (#4641): applied to two categories that matched the house test idiom
+ * rather than a genuine platform signal, it produced a Windows "tier" of
+ * 547 of 931 eligible unit-suite files (58.8%, measured 2026-09-11) — most
+ * of the suite. Measured per-category UNIQUE (sole-signal, i.e. the file
+ * would have been excluded without it) contribution as of that same
+ * measurement: `process-seam-subprocess` 118 files, `hardcoded-path-vs-
+ * path-call` 108 files, every other category 41 files COMBINED. Both were
+ * removed outright from CATEGORIES; the same-tree, same-day recount put
+ * the tier at 255 of 931 (27.4%) — exactly 292 entries removed from the
+ * committed list, none added. The macOS tier was unaffected by this change
+ * (a diff of macos-conformance-tier.generated.cjs across the same removal
+ * showed zero changed lines). None of these counts is asserted as a
+ * literal anywhere in the test suite: the ceilings this generator enforces
+ * are ratios against a live denominator (the current eligible-file count),
+ * and the committed lists are pinned by comparing against a fresh
+ * classification of the live tree, not against a hardcoded number —
+ * deliberately, since a hardcoded count in a test is a failure scheduled
+ * for the next time the suite grows. See
+ * docs/adr/4641-windows-selector-consolidation.md for the full rationale.
+ *
+ * KNOWN LIMIT, disclosed deliberately: this is a STATIC content classifier,
+ * not a real per-file, per-OS behavioral diff. Epic #4589's issue #4591 asked
+ * for the cutover to be validated by "running the existing full matrix one
+ * more time as a parity baseline, diffing pass/fail per file between the
+ * real-OS runs and the Linux run" before moving any file into the Linux-only
+ * bulk. That literal per-file diff was NOT performed — no historical
+ * per-file, per-OS pass/fail dataset exists to diff against (GitHub Actions
+ * publishes coverage/QA artifacts from CI runs, not per-file JUnit results).
+ * What stands in for it: (1) the most recent push-triggered run on `next`
+ * (unconditionally full-matrix) is green on every OS for every file in this
+ * classification, confirmed before this classifier was built; (2) the
+ * legacy full-matrix job ran the WHOLE suite on real Windows/macOS as a
+ * non-gating safety net for one release cycle (.github/workflows/test.yml)
+ * before it was retired (#4603) — a classifier miss during that cycle would
+ * have surfaced as a visible warning there, not a silent gap. This is the same
+ * static-analysis-substitutes-for-real-OS-execution stance ADR-1703's whole
+ * rule catalog already takes; it is a real, disclosed limit, not a silent
+ * substitution.
+ *
+ * Usage:
+ *   node scripts/gen-platform-conformance-tier.cjs                      # print summary to stdout
+ *   node scripts/gen-platform-conformance-tier.cjs --write              # write the generated file
+ *   node scripts/gen-platform-conformance-tier.cjs --check              # exit 1 if the committed file is stale
+ *   node scripts/gen-platform-conformance-tier.cjs --target macos ...   # same three modes, macOS-specific list (#4593)
+ *   node scripts/gen-platform-conformance-tier.cjs --tests-dir <path>   # override the tests/ root (tests only)
+ *   node scripts/gen-platform-conformance-tier.cjs --out <path>         # override the generated-file path (tests only)
+ *
+ * `--target` selects which of the two independent generated outputs this
+ * invocation targets: `windows` (default, the original #4591 behavior —
+ * omitting the flag is unchanged) or `macos` (#4593's narrower, macOS-
+ * specific list). Both write into the SAME committed-file conventions
+ * (`scripts/lib/platform-conformance-tier.generated.cjs` /
+ * `scripts/lib/macos-conformance-tier.generated.cjs`), so `package.json`'s
+ * `lint:generated-sync`/`regen:derived` chains invoke this script twice, once
+ * per target, rather than needing a second script file.
+ *
+ * `--tests-dir`/`--out` (or the TESTS_DIR/OUT_PATH env vars, flag takes
+ * precedence) exist solely so tests/platform-conformance-tier.test.cjs can
+ * point the CLI at a small temp fixture tree instead of this repo's real,
+ * 900+-file tests/ tree. Production usage (package.json's lint:generated-sync
+ * / regen:derived chains) passes no flags and gets the real repo paths.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { suiteOf } = require('./lib/suite-detection.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_TESTS_DIR = path.join(ROOT, 'tests');
+const DEFAULT_OUT_PATH = path.join(ROOT, 'scripts', 'lib', 'platform-conformance-tier.generated.cjs');
+const DEFAULT_MACOS_OUT_PATH = path.join(ROOT, 'scripts', 'lib', 'macos-conformance-tier.generated.cjs');
+
+const GENERATED_HEADER =
+  '// GENERATED FILE — do not hand-edit. Run `node scripts/gen-platform-conformance-tier.cjs --write` to regenerate.\n';
+
+const MACOS_GENERATED_HEADER =
+  '// GENERATED FILE — do not hand-edit. Run `node scripts/gen-platform-conformance-tier.cjs --target macos --write` to regenerate.\n' +
+  '// macOS-specific conformance tier (#4593), separate from and narrower than the general/\n' +
+  '// Windows-oriented tier in platform-conformance-tier.generated.cjs — see\n' +
+  '// docs/adr/4593-macos-conformance-tier-architecture.md for the full rationale.\n';
+
+/**
+ * Detection categories (#4591 design doc). Each entry's `test` receives the
+ * raw file content string and returns true when that category's signal is
+ * present. Order matches the design doc's enumeration; `signals` in
+ * `classifyContent`'s return value preserves this order.
+ */
+const CATEGORIES = [
+  {
+    name: 'process-platform',
+    test: (content) => /process\.platform/.test(content),
+  },
+  {
+    name: 'os-platform',
+    test: (content) => /os\.platform\(\)/.test(content),
+  },
+  {
+    name: 'win32-darwin-literal',
+    test: (content) => /\bwin32\b/.test(content) || /\bdarwin\b/.test(content),
+  },
+  {
+    name: 'chmod-mode-bit',
+    test: (content) => /chmodSync|chmod\(/.test(content) || /0o[0-7]{3,4}\b/.test(content),
+  },
+  {
+    name: 'windows-shell-token',
+    test: (content) => /cmd\.exe|powershell|pwsh|ComSpec/i.test(content),
+  },
+  {
+    name: 'windows-env-var',
+    test: (content) => /\bPATHEXT\b|\bUSERPROFILE\b|\bHOMEDRIVE\b|\bHOMEPATH\b/.test(content),
+  },
+  {
+    name: 'raw-child-process',
+    // Requires BOTH the child_process import/reference token AND one of the
+    // three call names in the same file — this is what keeps a same-named
+    // local identifier (e.g. a variable called `spawnResult`) from false-
+    // positiving: `spawnResult` never forms the substring `spawnSync(`.
+    test: (content) => {
+      if (/require\((['"])(?:node:)?child_process\1\)/.test(content)) return true;
+      if (!content.includes('child_process')) return false;
+      return /\bspawnSync\(|\bexecSync\(|\bexecFileSync\(/.test(content);
+    },
+  },
+  {
+    name: 'shell-interpreter-spawn',
+    // Added after an adversarial review (#4641) caught a REAL false negative
+    // introduced by removing 'process-seam-subprocess' above: that removal
+    // also dropped the only coverage for tests/execute-phase-worktree-guard.
+    // test.cjs, which calls tests/helpers/process-seam.cjs's `runHook(...,
+    // { interpreter: 'bash', ... })`. `runHook` spawns `options.interpreter`
+    // via a real `spawnSync`, so `interpreter: 'bash'` is a genuine real-shell
+    // invocation — bash availability, quoting, and git output parsing all
+    // differ across OSes. This is deliberately narrower than (and does not
+    // reintroduce) 'process-seam-subprocess': the rationale that going
+    // through the injected-`platform`-parameter seam in
+    // src/shell-command-projection.cts is NOT a platform signal (because the
+    // caller supplies `platform` itself) holds for THAT seam only — it does
+    // not hold for `runHook`'s `interpreter` option, which spawns a real
+    // interpreter binary rather than taking platform as injected data.
+    // Measured 2026-09-11: 33 eligible files match this pattern; 9 of them
+    // were outside the committed Windows tier and are added back by this
+    // change, taking the tier from 255 to 264 of 931 eligible files (27.4% ->
+    // 28.4%), still under the 33% ceiling. All 9 additions were verified by
+    // reading the matching source line: 0 false positives, every match is a
+    // live `interpreter:` option on a real `runHook`/`runHookSeam` call. As
+    // with all counts in this file, these are dated point-in-time
+    // measurements, not standing facts.
+    test: (content) => /interpreter:\s*['"`](bash|sh|zsh|dash|pwsh|powershell|cmd)['"`]/.test(content),
+  },
+  {
+    name: 'symlink-keyword',
+    // A leading `\b` with no trailing one, case-insensitive: this is
+    // deliberately NOT `/\bsymlink\b|\bSymlink\b/` (that literal pair would
+    // never match the dominant real-world call shape `symlinkSync(` /
+    // `readlinkSync(` — no word boundary exists between "symlink" and the
+    // immediately-following "Sync", both \w characters). The leading `\b`
+    // alone still excludes a mid-word embedding like "presymlink".
+    test: (content) => /\bsymlink/i.test(content),
+  },
+];
+
+// A CATEGORIES entry precise enough for TEST-file classification (this
+// module's own purpose) but too broad for SOURCE-file reachability
+// (scripts/ci-test-scope.cjs's #4592 use). This set used to hold a second
+// member, 'hardcoded-path-vs-path-call', alongside 'symlink-keyword'; that
+// category was removed outright from CATEGORIES (#4641 — measured to be the
+// single largest driver of Windows-tier over-inclusion, a universal Node
+// test-suite idiom rather than a platform signal), not merely exempted here,
+// because it was over-broad for BOTH consumers (this module's own Windows
+// tier AND source reachability), not source-reachability alone. Only
+// 'symlink-keyword' remains: still precise enough for test-file
+// classification but, per the same empirical pass described above, too noisy
+// for source reachability.
+const NOISY_FOR_SOURCE_REACHABILITY = new Set(['symlink-keyword']);
+
+/**
+ * Escape hatch, WINDOWS TIER ONLY (union'd into `classifyTree`, never into
+ * `classifyMacosTree`/`MACOS_CATEGORIES` — those stay untouched by this map).
+ *
+ * `classifyContent` above is a STATIC CONTENT classifier: it can only see
+ * text in the test file itself. Some files need real-OS coverage for a
+ * reason that lives in the CODE UNDER TEST, not in the test's own text — no
+ * regex over the test file can ever detect that, because the signal simply
+ * isn't there to find. Rather than chase that gap with ever-more-specific
+ * content heuristics (the exact failure mode #4641 measured and rolled
+ * back — see the header comment above), this map is the single, centrally-
+ * enumerated source of truth for those cases, matching ADR-1703's
+ * `portability-vocab.cjs` stance and epic #4589 Phase 2's explicit
+ * requirement that such overrides be "centrally-enumerated, not a naming
+ * convention". It is deliberately NOT a heuristic: it is a `Map` (path ->
+ * reason) precisely so every entry is forced to carry a recorded,
+ * human-reviewed reason at the call site — an entry without one is
+ * impossible by construction (there is no positional/array form that would
+ * let a path be added without a paired reason string).
+ *
+ * Adding an entry requires a recorded reason and should be rare: prefer
+ * fixing the classifier (a new CATEGORIES signal) when the real-OS need IS
+ * expressible as content; reach for this map only when it structurally is
+ * not.
+ *
+ * Current entries:
+ * - tests/external-descriptor-confinement.test.cjs: exercises `isPathConfined`
+ *   (src/external-descriptor-trust.cts:41-49), which calls the AMBIENT
+ *   `path` module directly — `path.resolve(root, target)` and `path.sep` —
+ *   with no platform/path injection seam. Its win32 semantics (drive
+ *   letters, UNC paths, `\` separator) are therefore only reachable by
+ *   actually running on Windows; the win32 branch is unreachable on Linux.
+ *   This is a security-relevant write-confinement gate, so a silent gap
+ *   here is a security regression, not a coverage nit (#4641).
+ */
+const ALWAYS_REAL_OS = new Map([
+  [
+    'tests/external-descriptor-confinement.test.cjs',
+    'Exercises isPathConfined (src/external-descriptor-trust.cts:41-49), which uses the ambient ' +
+      'path module (path.resolve/path.sep) with no platform injection; its win32 branch (drive ' +
+      'letters, UNC paths, \\ separator) is unreachable on Linux. Security-relevant write-confinement gate.',
+  ],
+]);
+
+/**
+ * macOS-specific detection categories (#4593, design doc
+ * .gsd/phase/chore-4593-macos-conformance-tier/40-design.md). Built new,
+ * rather than reusing CATEGORIES above minus its Windows-specific entries,
+ * because that naive exclusion barely narrows anything (measured: 546 -> 424
+ * files, 78%) — most files match multiple general-tier signals simultaneously
+ * and only need ONE surviving signal to stay in. `chmod-mode-bit` and
+ * `symlink-keyword` ARE deliberately duplicated verbatim from CATEGORIES:
+ * both are genuinely Unix-relevant (chmod bits and symlink semantics differ
+ * materially on macOS), not Windows-motivated the way the rest of CATEGORIES
+ * is. A standalone CRLF/`autocrlf` signal was considered and rejected: even
+ * narrowed to `/\bCRLF\b|autocrlf/i` it still hit 143/930 files (15%) — CRLF
+ * is primarily a Windows checkout concern in this codebase (ADR-1703's
+ * `no-crlf-fragile-split` files it under DEFECT.WINDOWS-TEST-PORTABILITY),
+ * so a CRLF signal pulls in Windows-relevant files already covered by the
+ * general tier, not a macOS-narrowing one.
+ */
+const MACOS_CATEGORIES = [
+  { name: 'darwin-literal', test: (content) => /\bdarwin\b/.test(content) },
+  { name: 'zsh-dispatch', test: (content) => /\bzsh\b/i.test(content) },
+  { name: 'case-sensitivity', test: (content) => /case.?insensitiv|case.?sensitiv/i.test(content) },
+  { name: 'chmod-mode-bit', test: (content) => /chmodSync|chmod\(/.test(content) || /0o[0-7]{3,4}\b/.test(content) },
+  { name: 'symlink-keyword', test: (content) => /\bsymlink/i.test(content) },
+];
+
+/**
+ * Pure classifier: given a test file's raw string content, returns which
+ * platform-conformance categories matched and whether the file needs real-OS
+ * coverage (true iff at least one category matched).
+ *
+ * @param {string} content
+ * @returns {{needsRealOs: boolean, signals: string[]}}
+ */
+function classifyContent(content) {
+  const text = typeof content === 'string' ? content : '';
+  const signals = [];
+  for (const category of CATEGORIES) {
+    if (category.test(text)) signals.push(category.name);
+  }
+  return { needsRealOs: signals.length > 0, signals };
+}
+
+/**
+ * Pure classifier, macOS-specific signal set (#4593). Same shape as
+ * classifyContent, against MACOS_CATEGORIES instead of CATEGORIES.
+ *
+ * @param {string} content
+ * @returns {{needsRealOs: boolean, signals: string[]}}
+ */
+function classifyMacosContent(content) {
+  const text = typeof content === 'string' ? content : '';
+  const signals = [];
+  for (const category of MACOS_CATEGORIES) {
+    if (category.test(text)) signals.push(category.name);
+  }
+  return { needsRealOs: signals.length > 0, signals };
+}
+
+/**
+ * Recursively collect every `*.test.cjs` file beneath `dir`.
+ * @param {string} dir
+ * @returns {string[]} absolute paths
+ */
+function walkTestFiles(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkTestFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.test.cjs')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Classify every test file under `testsDir`, returning `{ total, files }`
+ * where `files` is the SORTED array of `tests/<...>.test.cjs`-relative paths
+ * (POSIX-normalized, per RULESET.CONTENT-PATH-NORMALIZATION) whose content
+ * needs real-OS coverage.
+ *
+ * @param {string} testsDir
+ * @returns {{ total: number, files: string[] }}
+ */
+function classifyTree(testsDir) {
+  const absoluteFiles = walkTestFiles(testsDir);
+  // Only unit-suite files (no suite suffix) are eligible for the conformance
+  // tier — see the header doc-comment for why suite-tagged files are excluded
+  // entirely rather than merely deprioritized.
+  const unitFiles = absoluteFiles.filter((absPath) => suiteOf(absPath) === null);
+  const flagged = [];
+  for (const absPath of unitFiles) {
+    const rel = 'tests/' + path.relative(testsDir, absPath).replace(/\\/g, '/');
+    const content = fs.readFileSync(absPath, 'utf8');
+    const { needsRealOs } = classifyContent(content);
+    // The ALWAYS_REAL_OS escape hatch (Windows tier only — see its doc
+    // comment) is unioned in HERE, keyed off a file that this walk actually
+    // found, rather than blindly appended regardless of `testsDir` — that
+    // keeps the escape hatch from leaking a real-repo path into an unrelated
+    // temp-fixture-tree classification (e.g. this module's own tests).
+    if (needsRealOs || ALWAYS_REAL_OS.has(rel)) {
+      flagged.push(rel);
+    }
+  }
+  const result = [...new Set(flagged)].sort();
+  return { total: absoluteFiles.length, files: result };
+}
+
+/**
+ * Same walk/eligibility as classifyTree, classified with the macOS-specific
+ * signal set (#4593).
+ *
+ * @param {string} testsDir
+ * @returns {{ total: number, files: string[] }}
+ */
+function classifyMacosTree(testsDir) {
+  const absoluteFiles = walkTestFiles(testsDir);
+  const unitFiles = absoluteFiles.filter((absPath) => suiteOf(absPath) === null);
+  const flagged = [];
+  for (const absPath of unitFiles) {
+    const content = fs.readFileSync(absPath, 'utf8');
+    const { needsRealOs } = classifyMacosContent(content);
+    if (needsRealOs) {
+      const rel = path.relative(testsDir, absPath).replace(/\\/g, '/');
+      flagged.push('tests/' + rel);
+    }
+  }
+  flagged.sort();
+  return { total: absoluteFiles.length, files: flagged };
+}
+
+/**
+ * Render the generated `.cjs` module body — one array entry per line for a
+ * readable diff, matching scripts/lib/portability-vocab.cjs's array-literal
+ * style.
+ *
+ * @param {string[]} files - already sorted.
+ * @returns {string}
+ */
+function renderGeneratedFile(files) {
+  const lines = files.map((f) => `  ${JSON.stringify(f)},`).join('\n');
+  return (
+    GENERATED_HEADER +
+    "'use strict';\n\n" +
+    'module.exports = {\n' +
+    '  CONFORMANCE_TIER_FILES: [\n' +
+    (lines.length > 0 ? lines + '\n' : '') +
+    '  ],\n' +
+    '};\n'
+  );
+}
+
+/**
+ * Render scripts/lib/macos-conformance-tier.generated.cjs's module body,
+ * mirroring renderGeneratedFile exactly against the macOS export name.
+ *
+ * @param {string[]} files - already sorted.
+ * @returns {string}
+ */
+function renderMacosGeneratedFile(files) {
+  const lines = files.map((f) => `  ${JSON.stringify(f)},`).join('\n');
+  return (
+    MACOS_GENERATED_HEADER +
+    "'use strict';\n\n" +
+    'module.exports = {\n' +
+    '  MACOS_CONFORMANCE_TIER_FILES: [\n' +
+    (lines.length > 0 ? lines + '\n' : '') +
+    '  ],\n' +
+    '};\n'
+  );
+}
+
+/** Resolve the effective target/tests-dir/out-path from argv/env, flag beats env. */
+function resolveOverrides(argv) {
+  let target = 'windows';
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--target') {
+      const value = argv[i + 1];
+      if (value !== 'windows' && value !== 'macos') {
+        throw new ExitError(1, 'gen-platform-conformance-tier: --target requires "windows" or "macos"');
+      }
+      target = value;
+      i++;
+    }
+  }
+
+  const defaultOutPath = target === 'macos' ? DEFAULT_MACOS_OUT_PATH : DEFAULT_OUT_PATH;
+  let testsDir = process.env.TESTS_DIR || DEFAULT_TESTS_DIR;
+  let outPath = process.env.OUT_PATH || defaultOutPath;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--tests-dir') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new ExitError(1, 'gen-platform-conformance-tier: --tests-dir requires a path value');
+      }
+      testsDir = path.resolve(value);
+      i++;
+    } else if (argv[i] === '--out') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new ExitError(1, 'gen-platform-conformance-tier: --out requires a path value');
+      }
+      outPath = path.resolve(value);
+      i++;
+    }
+  }
+
+  return { target, testsDir: path.resolve(testsDir), outPath: path.resolve(outPath) };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const { target, testsDir, outPath } = resolveOverrides(argv);
+  const mode = argv.includes('--check') ? 'check' : argv.includes('--write') ? 'write' : 'print';
+
+  const isMacos = target === 'macos';
+  const label = isMacos ? 'gen-platform-conformance-tier --target macos' : 'gen-platform-conformance-tier';
+  const exportKey = isMacos ? 'MACOS_CONFORMANCE_TIER_FILES' : 'CONFORMANCE_TIER_FILES';
+  const { total, files } = isMacos ? classifyMacosTree(testsDir) : classifyTree(testsDir);
+
+  if (mode === 'write') {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, isMacos ? renderMacosGeneratedFile(files) : renderGeneratedFile(files));
+    process.stdout.write(`Wrote ${outPath} (${files.length} conformance-tier file(s))\n`);
+    return;
+  }
+
+  if (mode === 'check') {
+    // Never trust a stale require cache — the committed file may have been
+    // rewritten (by --write, or by hand) since this process started.
+    let committed;
+    try {
+      const resolved = require.resolve(outPath);
+      delete require.cache[resolved];
+      committed = require(resolved);
+    } catch (err) {
+      throw new ExitError(
+        1,
+        `${label}: could not load ${outPath} — run ` +
+          `\`node scripts/gen-platform-conformance-tier.cjs${isMacos ? ' --target macos' : ''} --write\` first ` +
+          `(${err && err.message ? err.message : err})`,
+      );
+    }
+    const committedFiles = Array.isArray(committed[exportKey]) ? committed[exportKey] : [];
+    const committedSet = new Set(committedFiles);
+    const liveSet = new Set(files);
+
+    const added = files.filter((f) => !committedSet.has(f));
+    const removed = committedFiles.filter((f) => !liveSet.has(f));
+
+    if (added.length > 0 || removed.length > 0) {
+      process.stderr.write(
+        `${path.relative(ROOT, outPath).replace(/\\/g, '/')} is stale. Run:\n` +
+          `  node scripts/gen-platform-conformance-tier.cjs${isMacos ? ' --target macos' : ''} --write\n\n`,
+      );
+      for (const f of added) process.stderr.write('  + ' + f + '\n');
+      for (const f of removed) process.stderr.write('  - ' + f + '\n');
+      throw new ExitError(1);
+    }
+
+    process.stdout.write(`ok ${label}: ${files.length} conformance-tier files, list matches\n`);
+    return;
+  }
+
+  // No flag: print a classification summary, write nothing.
+  process.stdout.write(
+    `${label}: ${total} file(s) scanned, ` +
+      `${files.length} need real OS, ${total - files.length} excluded (Linux-only conformance tier eligible)\n`,
+  );
+}
+
+/* c8 ignore next 3 -- CLI entry guard; this repo measures coverage with c8, which does not honor istanbul pragmas */
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  classifyContent,
+  CATEGORIES,
+  NOISY_FOR_SOURCE_REACHABILITY,
+  ALWAYS_REAL_OS,
+  walkTestFiles,
+  classifyTree,
+  renderGeneratedFile,
+  classifyMacosContent,
+  MACOS_CATEGORIES,
+  classifyMacosTree,
+  renderMacosGeneratedFile,
+};

package/scripts/lib/drift-scan.cjs

@@ -162,7 +162,7 @@ function readRegexLiteralAt(line, start) {
 // root + separator — a plain `startsWith(root)` would also accept a sibling
 // directory whose name merely starts with the root's name (`/repo-evil`).
 function isInsideRoot(realPath, realRoot) {
-  return realPath === realRoot || realPath.startsWith(realRoot + path.sep);
+  return realPath === realRoot || realPath.startsWith(realRoot + path.sep); // allow-handrolled-containment: lint:ci guard; runs before build:lib, compiled security.cjs may not exist
 }
 
 // True when `realPath` (already confirmed inside `realRoot` by `isInsideRoot`)