@pareto4/pp-core 1.8.2 → 1.9.0

package/scripts/verify-rename-guard.cjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-rename-guard.cjs — REBR-04 rename-integrity ratchet guard.
+ *
+ * The gsd → pp rename is functionally finished (Phase 15/16/17); this guard
+ * is a CI ratchet that stops it from regressing — it is explicitly NOT a
+ * cosmetic sweep of the ~1,186 files that still legitimately contain `gsd`
+ * (runtime contracts, historical corpora, migration provenance, etc.).
+ *
+ * Design (D-01..D-11, .planning/phases/18-rename-integrity-guard/18-CONTEXT.md):
+ *   D-01 Baseline ratchet: a committed baseline captures existing gsd hits;
+ *        CI fails only on a NEW (novel) hit, never on the existing debt.
+ *   D-02 Line-fingerprint precision: baseline keys on (file, normalized line
+ *        content), not (file, line NUMBER) — see Pitfall 1 below.
+ *   D-03 Case-insensitive substring match: RENAME_RE = /gsd/i, deliberately
+ *        broad; carve-outs and keep-tokens do the narrowing.
+ *   D-04 Growth-only enforcement: shrinking/removing a baselined gsd
+ *        reference NEVER fails the guard — it is a harmless upper bound.
+ *   D-07 Whole tracked tree: scans every git-tracked text file (skip
+ *        binaries), not a curated subset.
+ *   D-09 Single-source allowlist authority: tests/fixtures/gsd-keep-tokens.cjs
+ *        (isFrozen/isAttribution for whole-file carve-outs, isKeepTokenLine
+ *        for per-line exemptions). Never fork a parallel token list here.
+ *   D-10 Whole-file/dir carve-outs (installer-migrations, .changeset/archived,
+ *        the fixture itself) live in gsd-keep-tokens.cjs's FROZEN_PATHS.
+ *
+ * This plan (18-03) does NOT generate/commit the real-tree baseline — that is
+ * plan 04 (wave 2), once the tree reflects REBR-05's functional fixes. A
+ * missing baseline file here is treated as an EMPTY baseline, which lets the
+ * subprocess test wrapper fully control the baseline via env-var redirection.
+ *
+ * Exit codes:
+ *   0 — no novel gsd reference found (or --update-baseline succeeded)
+ *   1 — one or more novel gsd references found outside the baseline
+ *
+ * Usage:
+ *   node scripts/verify-rename-guard.cjs
+ *   node scripts/verify-rename-guard.cjs --update-baseline
+ *
+ * Env overrides (test-only, mirrors GSD_LINT_LEGACY_REPO_ROOT in
+ * scripts/lint-legacy-dir-name.cjs):
+ *   RENAME_GUARD_REPO_ROOT      — redirect the whole-tree scan to a temp git repo
+ *   RENAME_GUARD_BASELINE_PATH  — redirect the baseline file to a temp path
+ *
+ * Exports:
+ *   runScan(opts?) → { byFile, hitList, baseline, novel, fileCount, repoRoot, baselinePath }
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const keepTokens = require('../tests/fixtures/gsd-keep-tokens.cjs');
+
+// D-03: deliberately broad case-insensitive substring match — carve-outs and
+// keep-tokens (not a narrower pattern) do the exemption work.
+const RENAME_RE = /gsd/i;
+
+// RENAME_GUARD_REPO_ROOT lets tests redirect the guard to a temporary git repo
+// without touching the real working tree (mirrors GSD_LINT_LEGACY_REPO_ROOT).
+const REPO_ROOT = process.env.RENAME_GUARD_REPO_ROOT
+  ? path.resolve(process.env.RENAME_GUARD_REPO_ROOT)
+  : path.resolve(__dirname, '..');
+
+// RENAME_GUARD_BASELINE_PATH lets tests redirect the baseline file to a
+// temporary path. The real default lives under tests/ but is NOT committed
+// by this plan (18-03) — plan 04 generates and commits it against the final
+// post-REBR-05 tree. A missing file is treated as an empty baseline.
+const DEFAULT_BASELINE_PATH = path.join(__dirname, '..', 'tests', 'rename-guard-baseline.json');
+const BASELINE_PATH = process.env.RENAME_GUARD_BASELINE_PATH
+  ? path.resolve(process.env.RENAME_GUARD_BASELINE_PATH)
+  : DEFAULT_BASELINE_PATH;
+
+// A NUL byte between the relative path and the normalized line text — cannot
+// occur in either half of a text-file scan, so it is a safe composite-key
+// separator for the Set-diff below.
+const KEY_SEP = '\u0000';
+
+/**
+ * isBinary(fullPath) — NUL-byte probe on the first 512 bytes.
+ * Copied verbatim from scripts/lint-legacy-dir-name.cjs's isBinary().
+ *
+ * @param {string} fullPath  absolute path to probe
+ * @returns {boolean}
+ */
+function isBinary(fullPath) {
+  let fd;
+  try {
+    fd = fs.openSync(fullPath, 'r');
+    const buf = Buffer.allocUnsafe(512);
+    const bytesRead = fs.readSync(fd, buf, 0, 512, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } catch {
+    return false;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
+/**
+ * normalizeLine(line) — content-key normalization (D-02, Pitfall 4).
+ *
+ * `String.prototype.trimEnd()` strips trailing whitespace AND trailing line
+ * terminators (including a lone `\r` left behind when a CRLF file is split
+ * on `\n`), so a single trimEnd() call both trims trailing whitespace and
+ * neutralizes the CRLF/LF cross-platform baseline-desync pitfall documented
+ * in tests/workflow-size-budget.test.cjs's #683 regression.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+function normalizeLine(line) {
+  return line.trimEnd();
+}
+
+/**
+ * collectHits(repoRoot) — enumerate the whole tracked tree and collect every
+ * RENAME_RE hit not exempted by a whole-file carve-out (isFrozen/isAttribution)
+ * or a per-line keep-token (isKeepTokenLine).
+ *
+ * @param {string} repoRoot  absolute path to scan (git ls-files cwd)
+ * @returns {{
+ *   byFile: Object<string, Set<string>>,
+ *   hitList: Array<{file: string, line: number, text: string}>,
+ *   fileCount: number,
+ * }}
+ */
+function collectHits(repoRoot) {
+  let trackedFiles;
+  try {
+    trackedFiles = execFileSync('git', ['ls-files'], { cwd: repoRoot, encoding: 'utf8' })
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch (err) {
+    throw new ExitError(1, 'ERROR verify-rename-guard: git ls-files failed: ' + err.message);
+  }
+
+  /** @type {Object<string, Set<string>>} */
+  const byFile = {};
+  /** @type {Array<{file: string, line: number, text: string}>} */
+  const hitList = [];
+
+  for (const relPath of trackedFiles) {
+    const fullPath = path.join(repoRoot, relPath);
+
+    // D-09/D-10 whole-file/dir carve-out layer — single-source authority.
+    if (keepTokens.isFrozen(fullPath) || keepTokens.isAttribution(fullPath)) continue;
+
+    if (isBinary(fullPath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Unreadable file (permissions, race with deletion, etc.) — skip silently.
+      continue;
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const raw = lines[i];
+      if (!RENAME_RE.test(raw)) continue;
+
+      // D-09 per-line exemption — single-source authority.
+      if (keepTokens.isKeepTokenLine(raw)) continue;
+
+      const normalized = normalizeLine(raw);
+      if (!byFile[relPath]) byFile[relPath] = new Set();
+      // Pitfall 3 (accepted limitation): two identical-content gsd lines in the
+      // same file collapse to one Set entry — occurrence count is not tracked.
+      // This is an intentional D-02 trade-off, not a bug — do not "fix" it into
+      // a fragile per-occurrence counter.
+      byFile[relPath].add(normalized);
+      hitList.push({ file: relPath, line: i + 1, text: normalized });
+    }
+  }
+
+  return { byFile, hitList, fileCount: trackedFiles.length };
+}
+
+/**
+ * loadBaseline(baselinePath) — read the committed baseline JSON.
+ * A missing or unreadable/invalid file is treated as an EMPTY baseline (this
+ * plan does not commit a real-tree baseline; plan 04 does).
+ *
+ * @param {string} baselinePath
+ * @returns {Object<string, string[]>}
+ */
+function loadBaseline(baselinePath) {
+  try {
+    const raw = fs.readFileSync(baselinePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * serializeBaseline(byFile) — stable sorted serializer for --update-baseline.
+ * Mirrors scripts/update-size-baseline.cjs's serializeBaseline() shape:
+ * sorted file keys, sorted per-file line arrays, 2-space indent, trailing \n.
+ *
+ * @param {Object<string, Set<string>|string[]>} byFile
+ * @returns {string}
+ */
+function serializeBaseline(byFile) {
+  const sorted = {};
+  for (const key of Object.keys(byFile).sort()) {
+    sorted[key] = [...byFile[key]].sort();
+  }
+  return JSON.stringify(sorted, null, 2) + '\n';
+}
+
+/**
+ * computeNovel(byFile, baseline) — D-04 growth-only Set-diff.
+ *
+ * Returns ONLY current-minus-known (novel) composite keys — NEVER
+ * known-minus-current (stale/shrink), because shrinking or removing a
+ * baselined gsd reference is always safe (D-04). This deliberately does NOT
+ * reuse scripts/lib/allowlist-ratchet.cjs's assertWithinAllowlist() unmodified,
+ * since that helper also fails on stale entries (see Pitfall 2 in RESEARCH.md).
+ *
+ * @param {Object<string, Set<string>>} byFile     current scan result
+ * @param {Object<string, string[]>}    baseline   loaded baseline
+ * @returns {string[]} sorted array of "relPath normalizedLine" keys
+ */
+function computeNovel(byFile, baseline) {
+  const currentKeys = new Set();
+  for (const [file, lines] of Object.entries(byFile)) {
+    for (const line of lines) currentKeys.add(file + KEY_SEP + line);
+  }
+
+  const knownKeys = new Set();
+  for (const [file, lines] of Object.entries(baseline)) {
+    for (const line of lines) knownKeys.add(file + KEY_SEP + line);
+  }
+
+  return [...currentKeys].filter((k) => !knownKeys.has(k)).sort();
+}
+
+/**
+ * runScan(opts?) — pure scan entry point (no process.exit, no stdout/stderr
+ * writes). Consumed by the CLI wrapper (cliMain) and directly by tests.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]      defaults to the module-level REPO_ROOT
+ * @param {string} [opts.baselinePath]  defaults to the module-level BASELINE_PATH
+ * @returns {{
+ *   byFile: Object<string, Set<string>>,
+ *   hitList: Array<{file: string, line: number, text: string}>,
+ *   baseline: Object<string, string[]>,
+ *   novel: string[],
+ *   fileCount: number,
+ *   repoRoot: string,
+ *   baselinePath: string,
+ * }}
+ */
+function runScan(opts) {
+  const repoRoot = (opts && opts.repoRoot) || REPO_ROOT;
+  const baselinePath = (opts && opts.baselinePath) || BASELINE_PATH;
+
+  const { byFile, hitList, fileCount } = collectHits(repoRoot);
+  const baseline = loadBaseline(baselinePath);
+  const novel = computeNovel(byFile, baseline);
+
+  return { byFile, hitList, baseline, novel, fileCount, repoRoot, baselinePath };
+}
+
+/**
+ * splitKey(key) — inverse of the KEY_SEP composite key used by computeNovel().
+ * @param {string} key
+ * @returns {{file: string, text: string}}
+ */
+function splitKey(key) {
+  const idx = key.indexOf(KEY_SEP);
+  return { file: key.slice(0, idx), text: key.slice(idx + 1) };
+}
+
+// ── CLI entry ────────────────────────────────────────────────────────────────
+
+function cliMain() {
+  if (process.argv.includes('--update-baseline')) {
+    const { byFile, fileCount } = collectHits(REPO_ROOT);
+    fs.writeFileSync(BASELINE_PATH, serializeBaseline(byFile));
+    process.stdout.write(
+      'ok verify-rename-guard: baseline updated at ' +
+        path.relative(REPO_ROOT, BASELINE_PATH) +
+        ' (' + fileCount + ' tracked file(s) scanned, ' +
+        Object.keys(byFile).length + ' file(s) with gsd reference(s))\n'
+    );
+    return 0;
+  }
+
+  const { novel, hitList, fileCount } = runScan();
+
+  if (novel.length === 0) {
+    process.stdout.write(
+      'ok verify-rename-guard: ' + fileCount + ' tracked file(s) checked, 0 novel gsd reference(s)\n'
+    );
+    return 0;
+  }
+
+  process.stderr.write(
+    '\nERROR verify-rename-guard: ' + novel.length +
+      ' novel gsd reference(s) found (not in the committed baseline)\n\n'
+  );
+  for (const key of novel) {
+    const { file, text } = splitKey(key);
+    const hit = hitList.find((h) => h.file === file && h.text === text);
+    const lineNo = hit ? hit.line : '?';
+    process.stderr.write('  ' + file + ':' + lineNo + ' — ' + JSON.stringify(text) + '\n');
+  }
+  process.stderr.write('\n');
+  process.stderr.write(
+    'Fix at the source, add the `gsd-allow-legacy-name` marker on the line if the\n' +
+      'use is intentional, or run `node scripts/verify-rename-guard.cjs --update-baseline`\n' +
+      'if the reference is legitimately grandfathered.\n\n'
+  );
+
+  throw new ExitError(1);
+}
+
+module.exports = { runScan, RENAME_RE, serializeBaseline, collectHits, loadBaseline, computeNovel };
+
+if (require.main === module) {
+  runMain(cliMain);
+}