@pareto4/pp-core 1.11.0 → 1.12.0

package/scripts/lint-neutrality-names.cjs

@@ -0,0 +1,694 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-neutrality-names.cjs — TEN-09 CI name scan.
+ *
+ * Design (D-11..D-13, .planning/phases/38-tenant-neutrality-planning-records-guards/38-CONTEXT.md):
+ *
+ *   D-12 The list lives ONLY in the `PP_NEUTRALITY_NAMES_B64` CI variable — base64 of a
+ *        newline-separated `role:value` list — and is deliberately MASKED, not PROTECTED.
+ *        A protected variable is only exposed to pipelines on protected branches/tags, so an
+ *        ordinary-branch merge-request pipeline would never see it and D-13's fail-closed rule
+ *        would redden every normal MR. The list needs to stay out of the repository, not secret
+ *        from project members; masking only keeps it out of job logs.
+ *
+ *   D-13 Fail-closed and local-skip semantics: in CI (`process.env.CI === 'true'`) a missing,
+ *        empty or invalid list fails closed (exit 1) — covering merge-request, protected-branch
+ *        and every other pipeline context, because the variable is deliberately unprotected
+ *        (D-12). Locally, with no list supplied, the scan skips with a loud stderr notice and
+ *        exits 0; with a list supplied locally it still scans (the D-15 local proof leg). Output
+ *        discipline: every report line shows only a masked path, a line number (when the hit is
+ *        in content) and a category — never a list value, never the decoded list, never a
+ *        matched literal. Even the masked, base64-encoded variable is not secret from project
+ *        members — masking only keeps it out of CI job logs. A v* tag pipeline (the publish
+ *        path) reports `context=tag` (IN-11); it is a CI run like any other and fails closed the
+ *        same way.
+ *
+ *   List format (CR-03, T-38-20): the variable is canonical base64 (no truncation or
+ *   corruption) of UTF-8 text. The first non-blank line must be exactly
+ *   `# pp-neutrality-list entries=<N>`, with N from 1 and no leading zero, and exactly N entries
+ *   must then parse; a missing or malformed header, or a count that differs, is a config error.
+ *   A leading BOM and CRLF line endings are accepted. Every later line is blank, a `#` comment
+ *   on its own line, or one `role:value` entry, where `role` is one of ROLES (`client`,
+ *   `partner`, `person`, `canary`, `other`), matched case-insensitively, immediately followed by
+ *   a colon with no whitespace before it; whitespace after the colon is allowed. `canary` marks
+ *   a planted proof-of-life value (D-15's throwaway pipeline leg) so a real hit can be told
+ *   apart from an intentional drill in the report summary's category counts.
+ *
+ *   Accepted values (the claim, round 3): an unknown or malformed role prefix (including
+ *   whitespace before the colon), an empty value and a value under 4 characters are config
+ *   errors (exit 1, local or CI), never taken whole as an `other` value. Beyond that a value is
+ *   accepted only if (1) every code point is in alphabet A: the ASCII digits, U+0020, the five
+ *   joiners (hyphen, dot, ampersand, ASCII apostrophe, U+2019) and the letters that are both
+ *   \p{L} and \p{Script=Latin} and not \p{Default_Ignorable_Code_Point}; (2) it equals its own
+ *   NFKC normalisation; and (3) grammar G generates it: words of letters and digits, a joiner
+ *   only between two letters or digits, an optional leading apostrophe and one optional trailing
+ *   dot or apostrophe on a word, words separated by exactly one plain space or by space,
+ *   ampersand, space, and not a value that starts and ends with an apostrophe (that is a quoted
+ *   value). The claim is that no accepted value can be a dead entry because of an invisible,
+ *   non-standard-space, other-script, compatibility-form, combining-mark or symbol character,
+ *   punctuation other than the five joiners, or malformed spacing. It is proven in
+ *   tests/lint-neutrality-names.test.cjs by an exhaustive sweep of every single code point and by
+ *   fast-check properties; it rests only on strict decode, the header count, the role prefix, the
+ *   minimum length and checks (1)-(3). The operator-UX pre-checks (a second role prefix, an
+ *   inline ` #` comment, a quoted value, a value that is itself canonical base64 of printable
+ *   text) only name the likelier cause of a bad line and no guarantee rests on them; the
+ *   encoded-value check requires a canonical round-trip AND a decode to printable UTF-8, so the
+ *   canary shape (`ppcanary` plus hex) is never flagged. A control, format or separator character
+ *   in a comment line is rejected as well (a hidden entry break). Errors cite fixed reason words,
+ *   a 1-based line number (blank and comment lines count, so it matches the raw decoded text) and
+ *   counts only, never decoded content, never the offending character. Matching is a literal,
+ *   case-insensitive substring match, so a name whose distinctive part needs a character outside
+ *   A is listed by an in-alphabet part and the full name in the tree still matches.
+ *
+ *   Scope (IN-07): the scan covers the tracked tree at HEAD only. Git history, commit messages,
+ *   branch and tag names, and merge-request titles are outside it.
+ *
+ *   Known residuals (named, not claimed away; each is pinned by a `residual (x)` characterization
+ *   test under the delete-don't-weaken convention, and tracked in
+ *   `.planning/todos/pending/neutrality-guard-review-deferred-findings.md`):
+ *   (a) an in-alphabet substitution, deletion or look-alike letter inside a value (a typo, or
+ *       in-transit corruption that stays inside A): the count still matches; the per-entry
+ *       checksum is the deferred fix and would be an outward, approval-gated variable update;
+ *   (b) a well-formed but wrong value: the operator's semantic check is the per-category counts
+ *       on the `ok` line;
+ *   (c) tree-side spelling variants: tree text using a different apostrophe, space or hyphen
+ *       variant than the list is not a hit (matching is literal; the deferred WR-02);
+ *   (d) names whose distinctive part needs characters outside A: list an in-alphabet part;
+ *   (e) encoded values that stay inside A and escape the canonical-base64 heuristic (base64url
+ *       with a hyphen, or under 8 characters).
+ *
+ * Exit codes:
+ *   0 — local run with nothing to check, or a scan with 0 hits
+ *   1 — CI run with a missing/empty/invalid list, or a scan with 1+ hits
+ *
+ * Usage:
+ *   node scripts/lint-neutrality-names.cjs
+ *
+ * Env:
+ *   PP_NEUTRALITY_NAMES_B64     — base64 of the headered, newline-separated role:value list (D-12)
+ *   NEUTRALITY_SCAN_REPO_ROOT   — redirect the whole-tree scan to a temp git repo (tests only)
+ *
+ * Exports:
+ *   VARIABLE_NAME, EXEMPT_PATHS, ROLES, parseList, resolveContext, runScan, cliMain
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// D-12 working name, kept.
+const VARIABLE_NAME = 'PP_NEUTRALITY_NAMES_B64';
+
+// D-11: the single, explicitly listed exemption — a prefix match on tracked paths.
+const EXEMPT_PATHS = Object.freeze(['.planning/milestones/']);
+
+const ROLES = ['client', 'partner', 'person', 'canary', 'other'];
+
+// NEUTRALITY_SCAN_REPO_ROOT lets tests redirect the guard to a temporary git repo without
+// touching the real working tree (mirrors RENAME_GUARD_REPO_ROOT in verify-rename-guard.cjs).
+const REPO_ROOT = process.env.NEUTRALITY_SCAN_REPO_ROOT
+  ? path.resolve(process.env.NEUTRALITY_SCAN_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/**
+ * ListError — thrown by parseList() on an unusable list. The message cites only an entry
+ * index or a count, never any decoded content (D-13 output discipline).
+ */
+class ListError extends Error {}
+
+/**
+ * escapeRegExp(str) — literal-match escape for building a combined RegExp from list values.
+ * Copied verbatim from scripts/sync-runtime-launcher.cjs's escapeRegExp().
+ */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const ROLE_PREFIX_RE = new RegExp(`^(${ROLES.join('|')}):`, 'i');
+
+// CR-03: the required first non-blank list line, declaring the exact entry count.
+const HEADER_RE = /^# pp-neutrality-list entries=([1-9][0-9]{0,5})$/;
+// Any control, format, line-separator or paragraph-separator character (covers CR, NUL, tab,
+// NEL, U+2028/2029 and zero-width characters — every way to hide an entry break). Applied to
+// comment lines, and used to pick the reason word for an entry-value character outside A.
+const CONTROL_OR_FORMAT_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+// Reason classes only (they choose the reason word for a character already outside alphabet A).
+const NONSTANDARD_SPACE_RE = /\p{Zs}/u;
+const INVISIBLE_RE = /\p{Default_Ignorable_Code_Point}/u;
+
+// -- Operator-UX pre-checks: they only name a likelier cause; no guarantee rests on them. --
+// A second `role:` inside a value: the role at the start or after a non-alphanumeric character.
+const EMBEDDED_ROLE_RE = new RegExp(`(?:^|[^\\p{L}\\p{N}])(?:${ROLES.join('|')})\\s*:`, 'iu');
+const INLINE_COMMENT_RE = /\s#/;
+// A value with a quote or backtick at an edge: ASCII double quote, backtick, U+201C, U+201D,
+// guillemets U+00AB, U+00BB, U+2039, U+203A at either edge, and U+201E at the start (WR-12).
+const QUOTE_EDGE_RE =
+  /^["`\u{201C}\u{201D}\u{00AB}\u{00BB}\u{2039}\u{203A}\u{201E}]|["`\u{201C}\u{201D}\u{00AB}\u{00BB}\u{2039}\u{203A}]$/u;
+// A value wrapped in single quotes: starts with an apostrophe-like quote AND ends with one. A
+// single apostrophe at one edge is a name (WR-13: 't, 's-, possessives), not a quote.
+const QUOTE_PAIR_RE = /^['\u{2018}\u{2019}\u{201A}][\s\S]*['\u{2018}\u{2019}]$/u;
+const PRINTABLE_TEXT_RE = /^[\p{L}\p{N}\p{Zs}\p{P}\p{S}]{4,}$/u;
+
+// -- The security checks (CR-04, T-38-74): closed alphabet A, NFKC stability, grammar G. --
+// Every non-ASCII character is a \u{...} escape; in a v-mode class the hyphen and the ampersand
+// must be escaped, and outside a class the ampersand is written bare.
+const NAME_LETTER_OR_DIGIT =
+  '[0-9[[\\p{L}&&\\p{Script=Latin}]--\\p{Default_Ignorable_Code_Point}]]';
+const NAME_APOSTROPHE = "['\\u{2019}]";
+const NAME_JOINER = "[\\-.\\&'\\u{2019}]";
+// Alphabet A = letters/digits, U+0020 and the five joiners; OUTSIDE_ALPHABET_RE is its negation.
+const OUTSIDE_ALPHABET_RE = new RegExp(
+  "[^0-9[[\\p{L}&&\\p{Script=Latin}]--\\p{Default_Ignorable_Code_Point}]\\u{20}\\-.\\&'\\u{2019}]",
+  'v'
+);
+// Grammar G: a word is an optional leading apostrophe, letters/digits, then (one joiner, more
+// letters/digits) repeated, then one optional trailing dot or apostrophe. A value is words
+// separated by one space, optionally with a bare `&` and one more space; a value starting and
+// ending with an apostrophe is a quoted value, not a name.
+const NAME_WORD =
+  `${NAME_APOSTROPHE}?${NAME_LETTER_OR_DIGIT}+(?:${NAME_JOINER}${NAME_LETTER_OR_DIGIT}+)*(?:\\.|${NAME_APOSTROPHE})?`;
+const NAME_GRAMMAR_RE = new RegExp(
+  `^(?!${NAME_APOSTROPHE}.*${NAME_APOSTROPHE}$)${NAME_WORD}(?:\\u{20}(?:& )?${NAME_WORD})*$`,
+  'v'
+);
+
+/**
+ * looksLikeEncodedValue(v) — true when a value is itself canonical base64 of printable UTF-8
+ * text (an operator encoded each value instead of the whole list). Requires a canonical
+ * round-trip AND a decode to printable text, so the live canary shape (`ppcanary` + hex, whose
+ * first decoded byte 0xA6 is never a valid UTF-8 lead byte) is never flagged.
+ *
+ * @param {string} v
+ * @returns {boolean}
+ */
+function looksLikeEncodedValue(v) {
+  if (v.length < 8 || v.length % 4 !== 0 || !BASE64_RE.test(v)) return false;
+  const bytes = Buffer.from(v, 'base64');
+  if (bytes.toString('base64') !== v) return false;
+  let text;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return false;
+  }
+  return PRINTABLE_TEXT_RE.test(text);
+}
+
+/**
+ * decodeStrict(trimmed) — canonical-base64 and valid-UTF-8 decode (parser contract steps 1-3).
+ * Never a lenient decode: a truncated or corrupted value must fail here, not decode to garbage.
+ *
+ * @param {string} trimmed
+ * @returns {string} the decoded text
+ * @throws {ListError} `not valid base64` | `not canonical base64 (truncated or corrupted value)`
+ *   | `decoded list is not valid UTF-8`
+ */
+function decodeStrict(trimmed) {
+  if (!BASE64_RE.test(trimmed)) {
+    throw new ListError('not valid base64');
+  }
+
+  if (trimmed.length % 4 !== 0 || Buffer.from(trimmed, 'base64').toString('base64') !== trimmed) {
+    throw new ListError('not canonical base64 (truncated or corrupted value)');
+  }
+
+  const bytes = Buffer.from(trimmed, 'base64');
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw new ListError('decoded list is not valid UTF-8');
+  }
+}
+
+/**
+ * parseEntryLine(line, lineNo) — validate and categorise one non-blank, non-comment decoded
+ * line (parser contract steps 5-6). The role prefix must match exactly (case-insensitively),
+ * immediately followed by a colon — no trimming of the prefix, so whitespace before the colon is
+ * rejected. The unrecognised prefix text is never included in the thrown message: it may be part
+ * of a name (D-13 output discipline).
+ *
+ * @param {string} line
+ * @param {number} lineNo  1-based source line number (counts blank/comment lines, IN-03)
+ * @returns {{category: string, value: string}}
+ * @throws {ListError} `line <n> has no recognised role prefix (...)` |
+ *   `line <n> has an empty value after its role prefix` | `line <n> is too short (min 4 characters)` |
+ *   operator-UX pre-checks: `line <n> contains a second role prefix (...)` |
+ *   `line <n> has an inline comment (...)` | `line <n> is quoted (...)` |
+ *   `line <n> looks base64-encoded (...)` |
+ *   security checks, in order: `line <n> contains a control or format character` |
+ *   `line <n> contains a space other than a plain space (...)` |
+ *   `line <n> contains an invisible character (...)` |
+ *   `line <n> contains a character outside the allowed alphabet (...)` (alphabet A; the reason
+ *   word is chosen by the class of the first offending character, which is never interpolated) |
+ *   `line <n> is not NFKC-normalised (...)` | `line <n> is not a well-formed name (...)` (grammar G)
+ */
+function parseEntryLine(line, lineNo) {
+  const colonIdx = line.indexOf(':');
+  const prefix = colonIdx >= 0 ? line.slice(0, colonIdx).toLowerCase() : null;
+  if (colonIdx < 0 || !ROLE_PREFIX_RE.test(line)) {
+    throw new ListError(
+      `line ${lineNo} has no recognised role prefix (expected one of ${ROLES.join(', ')}, followed directly by a colon)`
+    );
+  }
+
+  const value = line.slice(colonIdx + 1).trim();
+  if (value.length === 0) {
+    throw new ListError(`line ${lineNo} has an empty value after its role prefix`);
+  }
+  if (value.length < 4) {
+    throw new ListError(`line ${lineNo} is too short (min 4 characters)`);
+  }
+
+  // Operator-UX pre-checks (reason words only; the security checks below do not depend on them).
+  if (EMBEDDED_ROLE_RE.test(value)) {
+    throw new ListError(
+      `line ${lineNo} contains a second role prefix (entries must be newline-separated)`
+    );
+  }
+  if (INLINE_COMMENT_RE.test(value)) {
+    throw new ListError(`line ${lineNo} has an inline comment (put comments on their own line)`);
+  }
+  if (QUOTE_EDGE_RE.test(value) || QUOTE_PAIR_RE.test(value)) {
+    throw new ListError(`line ${lineNo} is quoted (write the value bare)`);
+  }
+  if (looksLikeEncodedValue(value)) {
+    throw new ListError(
+      `line ${lineNo} looks base64-encoded (encode the whole list once, not each value)`
+    );
+  }
+
+  // Security checks: alphabet A, then NFKC stability, then grammar G. The reason word for an
+  // alphabet failure comes from the class of the first offending character; the character
+  // itself, its code point and any fragment of the value are never put in the message.
+  const outside = OUTSIDE_ALPHABET_RE.exec(value);
+  if (outside) {
+    const ch = outside[0];
+    if (CONTROL_OR_FORMAT_RE.test(ch)) {
+      throw new ListError(`line ${lineNo} contains a control or format character`);
+    }
+    if (NONSTANDARD_SPACE_RE.test(ch)) {
+      throw new ListError(
+        `line ${lineNo} contains a space other than a plain space (retype it as a plain space)`
+      );
+    }
+    if (INVISIBLE_RE.test(ch)) {
+      throw new ListError(`line ${lineNo} contains an invisible character (retype the value)`);
+    }
+    throw new ListError(
+      `line ${lineNo} contains a character outside the allowed alphabet (Latin letters, digits, plain spaces, hyphens, dots, ampersands and apostrophes; list an in-alphabet part of the name)`
+    );
+  }
+  if (value !== value.normalize('NFKC')) {
+    throw new ListError(
+      `line ${lineNo} is not NFKC-normalised (retype compatibility or look-alike letter forms as plain letters)`
+    );
+  }
+  if (!NAME_GRAMMAR_RE.test(value)) {
+    throw new ListError(
+      `line ${lineNo} is not a well-formed name (single plain spaces between words; hyphens, dots, ampersands and apostrophes only between letters or digits)`
+    );
+  }
+
+  return { category: prefix, value };
+}
+
+/**
+ * parseList(b64) — decode and strictly validate the headered base64 role:value list (CR-03).
+ * Order: strict decode; required `# pp-neutrality-list entries=<N>` header on the first
+ * non-blank line; comment lines (control/format check, then skip); entry validation by
+ * parseEntryLine (prefix, length, operator-UX pre-checks, then alphabet / NFKC / grammar);
+ * zero-entry check; exact entry-count check.
+ *
+ * @param {string} b64
+ * @returns {Array<{category: string, value: string}>}
+ * @throws {ListError} on invalid or non-canonical base64, non-UTF-8 decoded bytes, a missing or
+ *   malformed header, a control or format character in a comment line, an unrecognised or
+ *   malformed role prefix, an empty or too-short value, a value rejected by the operator-UX
+ *   pre-checks (second role prefix, inline comment, quoted, base64-encoded) or by the alphabet,
+ *   NFKC or grammar checks (see parseEntryLine), zero usable entries, or an entry count that
+ *   differs from the header.
+ */
+function parseList(b64) {
+  const trimmed = typeof b64 === 'string' ? b64.trim() : '';
+  const decoded = decodeStrict(trimmed);
+
+  const rawLines = decoded.split('\n');
+  const entries = [];
+  let declared = null;
+  for (let i = 0; i < rawLines.length; i++) {
+    const line = rawLines[i].trim();
+    if (line.length === 0) continue;
+    const lineNo = i + 1;
+
+    if (declared === null) {
+      const m = HEADER_RE.exec(line);
+      if (m) {
+        declared = Number(m[1]);
+        continue;
+      }
+      if (line.startsWith('#') && /pp-neutrality-list/i.test(line)) {
+        throw new ListError(
+          `line ${lineNo} has a malformed list header (expected "# pp-neutrality-list entries=<N>")`
+        );
+      }
+      throw new ListError(
+        'missing list header (the first non-blank line must be "# pp-neutrality-list entries=<N>")'
+      );
+    }
+
+    // IN-15: the control/format check exists once per line kind. A comment line gets it here
+    // (hidden entry-break protection); an entry value gets it only as one reason class of the
+    // alphabet check inside parseEntryLine.
+    if (line.startsWith('#')) {
+      if (CONTROL_OR_FORMAT_RE.test(line)) {
+        throw new ListError(`line ${lineNo} contains a control or format character`);
+      }
+      continue;
+    }
+    entries.push(parseEntryLine(line, lineNo));
+  }
+
+  if (declared === null) {
+    throw new ListError(
+      'missing list header (the first non-blank line must be "# pp-neutrality-list entries=<N>")'
+    );
+  }
+  if (entries.length === 0) {
+    throw new ListError('0 usable entries');
+  }
+  if (entries.length !== declared) {
+    throw new ListError(
+      `entry count mismatch (header declares ${declared}, parsed ${entries.length})`
+    );
+  }
+
+  return entries;
+}
+
+/**
+ * resolveContext(env) — classify the run context from CI predefined variables.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {'local'|'merge_request_event'|'tag'|'protected'|'branch'}
+ */
+function resolveContext(env) {
+  if (env.CI !== 'true') return 'local';
+  if (env.CI_PIPELINE_SOURCE === 'merge_request_event') return 'merge_request_event';
+  if (env.CI_COMMIT_TAG) return 'tag';
+  if (env.CI_COMMIT_REF_PROTECTED === 'true') return 'protected';
+  return 'branch';
+}
+
+/**
+ * maskText(text, entries) — replace every list value, case-insensitively, with `<category>`.
+ * Used for every path printed, so a value that happens to appear in a tracked path never
+ * reaches a report line verbatim.
+ *
+ * CR-05: masking is one pass over the ORIGINAL text. Every occurrence of every value is found
+ * first (overlapping occurrences included, each entry searched independently), the covered
+ * character ranges are merged, and each merged run is replaced once. So no character that
+ * belongs to any occurrence of any value survives — not the tail of a longer value that
+ * contains a shorter one, not a value that overlaps another at a different offset — and a
+ * value that happens to spell part of a category word cannot split a marker, because markers
+ * are never re-scanned. A merged run covering several categories prints them all, sorted and
+ * `|`-joined.
+ *
+ * @param {string} text
+ * @param {Array<{category: string, value: string}>} entries
+ * @returns {string}
+ */
+function maskText(text, entries) {
+  const spans = [];
+  for (const { category, value } of entries) {
+    const re = new RegExp(escapeRegExp(value), 'gi');
+    let m = re.exec(text);
+    while (m !== null) {
+      spans.push({ start: m.index, end: m.index + m[0].length, category });
+      re.lastIndex = m.index + 1; // overlapping occurrences of the same value
+      m = re.exec(text);
+    }
+  }
+  if (spans.length === 0) return text;
+
+  spans.sort((x, y) => x.start - y.start || y.end - x.end);
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    if (last && span.start < last.end) {
+      last.end = Math.max(last.end, span.end);
+      last.categories.add(span.category);
+    } else {
+      merged.push({ start: span.start, end: span.end, categories: new Set([span.category]) });
+    }
+  }
+
+  let out = '';
+  let cursor = 0;
+  for (const run of merged) {
+    out += text.slice(cursor, run.start) + `<${[...run.categories].sort().join('|')}>`;
+    cursor = run.end;
+  }
+  return out + text.slice(cursor);
+}
+
+/**
+ * isBinary(fullPath) — NUL-byte probe on the first 8 KiB.
+ *
+ * @param {string} fullPath
+ * @returns {boolean}
+ */
+function isBinary(fullPath) {
+  let fd;
+  try {
+    fd = fs.openSync(fullPath, 'r');
+    const buf = Buffer.allocUnsafe(8192);
+    const bytesRead = fs.readSync(fd, buf, 0, 8192, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } catch {
+    return false;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/**
+ * listTrackedFiles(repoRoot) — `git ls-files -z`, split on NUL (handles unusual filenames).
+ *
+ * @param {string} repoRoot
+ * @returns {string[]}
+ */
+function listTrackedFiles(repoRoot) {
+  let raw;
+  try {
+    raw = execFileSync('git', ['ls-files', '-z'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (err) {
+    throw new ExitError(1, 'ERROR lint-neutrality-names: git ls-files failed: ' + err.message);
+  }
+  return raw.split('\u0000').filter(Boolean);
+}
+
+/**
+ * matchCategories(text, combinedSource, lookup) — run one combined case-insensitive RegExp
+ * (built from every escaped list value) against `text` and map each distinct match back to
+ * its category via `lookup` (value.toLowerCase() -> category).
+ *
+ * @param {string} text
+ * @param {string} combinedSource  RegExp source, values already escaped and `|`-joined,
+ *   longest-value-first so an entry never shadows a longer one that contains it.
+ * @param {Map<string, string>} lookup
+ * @returns {Set<string>} distinct categories matched in `text`
+ */
+function matchCategories(text, combinedSource, lookup) {
+  const found = new Set();
+  const re = new RegExp(combinedSource, 'gi');
+  let m = re.exec(text);
+  while (m !== null) {
+    const category = lookup.get(m[0].toLowerCase());
+    if (category) found.add(category);
+    if (m.index === re.lastIndex) re.lastIndex += 1; // guard against a zero-length match loop
+    m = re.exec(text);
+  }
+  return found;
+}
+
+/**
+ * scanTree(repoRoot, entries) — whole-tracked-tree scan with the single named exemption
+ * (D-11), reusing the git ls-files walk / binary skip / per-line test shape from
+ * scripts/verify-rename-guard.cjs's collectHits().
+ *
+ * @param {string} repoRoot
+ * @param {Array<{category: string, value: string}>} entries
+ * @returns {{ hits: Array<{file: string, line: number|null, category: string, where: 'content'|'path'}>, fileCount: number }}
+ */
+function scanTree(repoRoot, entries) {
+  const files = listTrackedFiles(repoRoot).filter(
+    (relPath) => !EXEMPT_PATHS.some((exempt) => relPath.startsWith(exempt))
+  );
+
+  const lookup = new Map();
+  for (const { category, value } of entries) lookup.set(value.toLowerCase(), category);
+
+  // Longest value first so, at a shared match position, a longer entry that contains a
+  // shorter one wins the alternation.
+  const combinedSource = [...entries]
+    .sort((a, b) => b.value.length - a.value.length)
+    .map((entry) => escapeRegExp(entry.value))
+    .join('|');
+
+  const hits = [];
+  for (const relPath of files) {
+    const fullPath = path.join(repoRoot, relPath);
+    const maskedPath = maskText(relPath, entries);
+
+    for (const category of matchCategories(relPath, combinedSource, lookup)) {
+      hits.push({ file: maskedPath, line: null, category, where: 'path' });
+    }
+
+    if (isBinary(fullPath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      continue; // unreadable file (permissions, race with deletion) — skip silently
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      for (const category of matchCategories(lines[i], combinedSource, lookup)) {
+        hits.push({ file: maskedPath, line: i + 1, category, where: 'content' });
+      }
+    }
+  }
+
+  return { hits, fileCount: files.length };
+}
+
+/**
+ * runScan(opts?) — pure scan entry point (no process.exit, no stdout/stderr writes).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]  defaults to the module-level REPO_ROOT
+ * @param {NodeJS.ProcessEnv} [opts.env]  defaults to process.env
+ * @returns {{
+ *   status: 'skipped'|'failed-closed'|'invalid'|'clean'|'violations',
+ *   context: 'local'|'merge_request_event'|'tag'|'protected'|'branch',
+ *   hits: Array<{file: string, line: number|null, category: string, where: 'content'|'path'}>,
+ *   fileCount: number,
+ *   entryCounts: Object<string, number>,
+ *   message?: string,
+ * }}
+ */
+function runScan(opts) {
+  const env = (opts && opts.env) || process.env;
+  const repoRoot = (opts && opts.repoRoot) || REPO_ROOT;
+  const context = resolveContext(env);
+  const rawList = env[VARIABLE_NAME];
+
+  if (!rawList) {
+    return {
+      status: context === 'local' ? 'skipped' : 'failed-closed',
+      context,
+      hits: [],
+      fileCount: 0,
+      entryCounts: {},
+    };
+  }
+
+  let entries;
+  try {
+    entries = parseList(rawList);
+  } catch (err) {
+    if (err instanceof ListError) {
+      return {
+        status: 'invalid',
+        context,
+        hits: [],
+        fileCount: 0,
+        entryCounts: {},
+        message: err.message,
+      };
+    }
+    throw err;
+  }
+
+  const entryCounts = {};
+  for (const { category } of entries) entryCounts[category] = (entryCounts[category] || 0) + 1;
+
+  const { hits, fileCount } = scanTree(repoRoot, entries);
+
+  return {
+    status: hits.length === 0 ? 'clean' : 'violations',
+    context,
+    hits,
+    fileCount,
+    entryCounts,
+  };
+}
+
+// ── CLI entry ────────────────────────────────────────────────────────────────
+
+function cliMain() {
+  const result = runScan();
+  const { status, context, hits, fileCount, entryCounts, message } = result;
+
+  if (status === 'skipped') {
+    process.stderr.write(
+      `NOTICE lint-neutrality-names: SKIPPED — ${VARIABLE_NAME} is not set and this is not a CI run; the name scan did not run.\n`
+    );
+    return 0;
+  }
+
+  if (status === 'failed-closed') {
+    throw new ExitError(
+      1,
+      `FAIL lint-neutrality-names: ${VARIABLE_NAME} is not set in CI (context=${context}); failing closed.`
+    );
+  }
+
+  if (status === 'invalid') {
+    throw new ExitError(1, `FAIL lint-neutrality-names: list invalid — ${message} (context=${context})`);
+  }
+
+  if (status === 'clean') {
+    const entryTotal = Object.values(entryCounts).reduce((sum, n) => sum + n, 0);
+    const catSummary = Object.keys(entryCounts).sort()
+      .map((category) => `${category}=${entryCounts[category]}`)
+      .join(', ');
+    process.stdout.write(
+      `ok lint-neutrality-names: ${fileCount} tracked files scanned against ${entryTotal} list entries (${catSummary}), 0 hits, context=${context}\n`
+    );
+    return 0;
+  }
+
+  // violations
+  process.stderr.write(`FAIL lint-neutrality-names: ${hits.length} hit(s) (context=${context})\n`);
+  for (const hit of hits) {
+    if (hit.where === 'content') {
+      process.stderr.write(`  ${hit.file}:${hit.line} — category=${hit.category}\n`);
+    } else {
+      process.stderr.write(`  ${hit.file} — category=${hit.category} (in path)\n`);
+    }
+  }
+  process.stderr.write('reword by role; the list lives only in the masked CI variable\n');
+
+  throw new ExitError(1);
+}
+
+module.exports = { VARIABLE_NAME, EXEMPT_PATHS, ROLES, parseList, resolveContext, runScan, cliMain };
+
+if (require.main === module) {
+  runMain(cliMain);
+}