@pareto4/pp-core 1.8.1 → 1.9.0

package/scripts/release-channel.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * release-channel.cjs
+ *
+ * Pure decision logic mapping a git release tag to an npm dist-tag publish
+ * channel. Given a tag like `v1.9.0-rc.1` returns `'next'`; given a clean
+ * `v1.8.1` returns `'latest'`. Fails closed (returns `null` / CLI exits 1) on
+ * any unrecognized or malformed input instead of defaulting to `'latest'` —
+ * the production-facing channel (ASVS V5 tampering concern: `CI_COMMIT_TAG`
+ * is attacker-influenceable if a bad tag is pushed). Matching is exhaustive
+ * and full-string anchored: anything that isn't an exact `X.Y.Z` release or
+ * an exact `X.Y.Z-(rc|beta|alpha).N` prerelease returns null — no partial or
+ * heuristic match ever resolves to `'latest'`.
+ *
+ * Usage:
+ *   node scripts/release-channel.cjs "$CI_COMMIT_TAG"   # prints channel, exit 0
+ *   node scripts/release-channel.cjs                     # reads CI_COMMIT_TAG env
+ *   argv (process.argv[2]) is preferred over the CI_COMMIT_TAG env var so the
+ *   module is deterministic under its own tests even when CI_COMMIT_TAG is
+ *   set in the ambient environment (as it always is on a real GitLab tag
+ *   pipeline).
+ *   (unrecognized/empty tag) -> stderr message, exit 1, no stdout
+ */
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// Exact release version: no prerelease suffix, no build metadata, no trailing
+// garbage.
+const RELEASE_RE = /^\d+\.\d+\.\d+$/;
+
+// Exact prerelease version: matches upstream gsd-core's own prerelease convention: -rc.N / -beta.N / -alpha.N — gsd-allow-legacy-name
+const PRERELEASE_RE = /^\d+\.\d+\.\d+-(?:rc|beta|alpha)\.\d+$/;
+
+function channelForTag(tag) {
+  if (typeof tag !== 'string' || tag.length === 0) return null;
+  const version = tag.replace(/^v/, '');
+  if (RELEASE_RE.test(version)) return 'latest';
+  if (PRERELEASE_RE.test(version)) return 'next';
+  return null;
+}
+
+module.exports = { channelForTag, PRERELEASE_RE };
+
+function cliMain() {
+  const tag = process.argv[2] || process.env.CI_COMMIT_TAG || '';
+  const channel = channelForTag(tag);
+  if (!channel) {
+    throw new ExitError(1, `release-channel: unrecognized tag "${tag}"`);
+  }
+  process.stdout.write(channel + '\n');
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(cliMain);
+}

package/scripts/release-tarball-smoke.cjs

@@ -756,6 +756,10 @@ module.exports = {
   locateLegacyGsdProgress,
   driveInstaller,
   findInstallerBin,
+  // 20-02 Task 1: expose the installed pp-tools bin resolver so the
+  // REL-02 discuss->plan->execute smoke test can resolve it without
+  // re-implementing bin resolution (RESEARCH.md Don't-Hand-Roll).
+  findGsdToolsBin, // gsd-allow-legacy-name
 };
 
 if (require.main === module) {

package/scripts/verify-opengsd-sweep.cjs

@@ -41,6 +41,16 @@ const ROOT = path.resolve(__dirname, '..');
 /** Matches any recognised OpenGSD spelling in a line of text. */
 const OPENGSD_RE = /opengsd|open-gsd/i;
 
+/**
+ * MIT-attribution carve-out (line-level): the README's License & Attribution
+ * section must name the upstream project — the same D-07 class as
+ * LICENSE/NOTICE, but scoped to attribution lines only so the rest of the
+ * README stays on the scanned surface.
+ */
+const ATTRIBUTION_LINE_RE =
+  /hard fork of \[gsd-core\]\(https:\/\/github\.com\/open-gsd\/gsd-core\)/;
+const README_FILE = path.join(__dirname, '..', 'README.md');
+
 /**
  * Broader brand pattern for npm-facing manifest metadata (package.json
  * `description` / `author`). Catches the upstream product name ("GSD Core")
@@ -185,6 +195,8 @@ function scanFiles(files) {
     const lines = content.split('\n');
     for (let i = 0; i < lines.length; i++) {
       if (OPENGSD_RE.test(lines[i])) {
+        // README attribution line: MIT-required upstream credit (D-07 class).
+        if (abs === README_FILE && ATTRIBUTION_LINE_RE.test(lines[i])) continue;
         hits.push({
           file: path.relative(ROOT, abs),
           line: i + 1,

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);
+}