@pareto4/pp-core 1.5.0

package/scripts/issue-version-gate.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+'use strict';
+
+const { PACKAGE_NAME } = require('../pp-core/bin/lib/package-identity.cjs');
+
+/**
+ * Version gate for bug-report issues.
+ *
+ * GitHub Issue Forms enforce `required: true` only in the web form; issues
+ * filed via the REST API, `gh issue create`, or automated/AI reporters can
+ * omit the GSD Version field entirely. This module provides the pure logic
+ * for detecting bug reports missing a usable version so a workflow can
+ * auto-close them. See .github/workflows/version-gate.yml.
+ */
+
+const BUG_LABEL = 'bug';
+const NEEDS_VERSION_LABEL = 'needs-version';
+const VERSION_GATE_MARKER = '<!-- gsd-version-gate -->';
+
+// Labels that opt an issue out of the version gate.
+const EXEMPT_LABELS = ['version-exempt'];
+
+// Heading GitHub renders for the bug template's `label: GSD Version` field.
+// Issue Forms render input labels as `### <label>`; matches the exact heading
+// `### GSD Version` (any heading level) — bare `### Version` is NOT matched.
+const VERSION_HEADING_RE = /^#{1,6}\s*GSD\s+Version\s*$/i;
+
+// GitHub's placeholder for an empty optional form field.
+const NO_RESPONSE_RE = /^_no response_$/i;
+
+// A value "looks like a version" if it contains a semver-ish token
+// (1.18, v1.4.1, 1.18.0-dev) or a git commit SHA (7-40 hex chars).
+const SEMVER_TOKEN_RE = /\bv?\d+\.\d+(?:\.\d+)?(?:[-+.][0-9A-Za-z.-]+)?\b/;
+const SHA_TOKEN_RE = /\b[0-9a-f]{7,40}\b/i;
+
+function normalizeLabels(labels) {
+  if (!Array.isArray(labels)) return [];
+  return labels
+    .map((l) => (typeof l === 'string' ? l : l && l.name))
+    .filter(Boolean)
+    .map((l) => String(l).toLowerCase());
+}
+
+function hasExemptLabel(labels) {
+  const names = normalizeLabels(labels);
+  return names.some((l) => EXEMPT_LABELS.includes(l));
+}
+
+function isBugReport({ labels, body } = {}) {
+  const names = normalizeLabels(labels);
+  if (names.includes(BUG_LABEL)) return true;
+  // Labels are authoritative: if any label was applied and it isn't `bug`,
+  // this is not a bug report (e.g. an `enhancement`-labeled issue that happens
+  // to contain a version heading must not be gated). Only fall back to the
+  // bug-template's `### GSD Version` heading for fully unlabeled submissions
+  // (bare REST API / `gh issue create`).
+  if (names.length > 0) return false;
+  return hasVersionHeading(body);
+}
+
+function hasVersionHeading(body) {
+  if (!body) return false;
+  return String(body)
+    .split(/\r?\n/)
+    .some((line) => VERSION_HEADING_RE.test(line));
+}
+
+/**
+ * Extract the value beneath the "GSD Version" heading. Returns null when the
+ * section is absent, '' when the section is present but empty.
+ */
+function extractVersion(body) {
+  if (!body) return null;
+  const lines = String(body).split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (VERSION_HEADING_RE.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  const collected = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,6}\s/.test(lines[i])) break; // next section heading
+    collected.push(lines[i]);
+  }
+  return collected.join('\n').trim();
+}
+
+function isValidVersion(value) {
+  if (value == null) return false;
+  const v = String(value).trim();
+  if (!v) return false;
+  if (NO_RESPONSE_RE.test(v)) return false;
+  return SEMVER_TOKEN_RE.test(v) || SHA_TOKEN_RE.test(v);
+}
+
+/**
+ * Decide what to do with an issue. Returns { action: 'skip'|'close', reason }.
+ */
+function evaluateVersionGate({ labels, body } = {}) {
+  if (hasExemptLabel(labels)) return { action: 'skip', reason: 'exempt-label' };
+  if (!isBugReport({ labels, body })) return { action: 'skip', reason: 'not-a-bug' };
+  const version = extractVersion(body);
+  if (isValidVersion(version)) return { action: 'skip', reason: 'valid-version' };
+  const reason = version == null ? 'missing-version' : 'invalid-version';
+  return { action: 'close', reason };
+}
+
+function renderCloseComment() {
+  return [
+    VERSION_GATE_MARKER,
+    'Closing automatically — this bug report does not include a valid **GSD Version**.',
+    '',
+    'A version is required to reproduce and triage bugs. Grab it with one of:',
+    '',
+    '```',
+    `npm list -g ${PACKAGE_NAME}`,
+    `npx ${PACKAGE_NAME} --version`,
+    '```',
+    '',
+    'Then **edit this issue to add the version (e.g. `1.18.0`) and reopen it**, or comment with the version and a maintainer will reopen it. If a version genuinely does not apply, a maintainer can add the `version-exempt` label.',
+  ].join('\n');
+}
+
+module.exports = {
+  BUG_LABEL,
+  NEEDS_VERSION_LABEL,
+  VERSION_GATE_MARKER,
+  EXEMPT_LABELS,
+  normalizeLabels,
+  hasExemptLabel,
+  isBugReport,
+  hasVersionHeading,
+  extractVersion,
+  isValidVersion,
+  evaluateVersionGate,
+  renderCloseComment,
+};

package/scripts/lib/allowlist-ratchet.cjs

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * @file allowlist-ratchet.cjs
+ *
+ * Reusable "better than a count ratchet" primitives for CI guards.
+ *
+ * ## Motivation (issue #597)
+ *
+ * A count ratchet (`assert(offenders.length <= N)`) has a masking blind spot:
+ * fixing one offender and introducing a new one keeps the count constant, so a
+ * novel defect slips through green.  These helpers enforce on IDENTITY instead,
+ * making every individual offender visible and requiring monotonic progress
+ * toward zero.
+ *
+ * ## Design
+ *
+ * Both functions are pure (no I/O, no global state).  The `fail` callback is
+ * injected by the caller so the same logic can be used with `node:assert.fail`,
+ * a custom throw, or a message-collector in unit tests.
+ */
+
+/**
+ * Assert that `current` offenders are all within the known allowlist, and that
+ * every entry in the allowlist still offends (forcing the allowlist to shrink
+ * as defects are fixed).
+ *
+ * Fails when:
+ * - Any id in `current` is NOT in `known` → novel offender introduced.
+ * - Any id in `known` is NOT in `current` → stale allowlist entry must be
+ *   pruned so the guard ratchets toward zero (the ratchet-DOWN direction).
+ *
+ * ## Masking blind spot this prevents (issue #597)
+ *
+ * A count ratchet (`assert(count <= N)`) allows one offender to be silently
+ * replaced by another while the count stays at N.  By asserting on identity
+ * instead, every new offender is caught by name, and every fixed offender
+ * forces the allowlist to shrink.
+ *
+ * @param {object} opts
+ * @param {string}   opts.label      - Human-readable name for the guard (used
+ *                                     in failure messages).
+ * @param {Iterable<string>} opts.current - The offending ids found in the
+ *                                     current run.
+ * @param {Iterable<string>} opts.known   - The allowlisted ids (baseline).
+ * @param {function(string): void} opts.fail - Callback invoked with a
+ *                                     descriptive message on any violation.
+ *                                     Pass `require('node:assert').fail`, a
+ *                                     custom thrower, or a collector.  The
+ *                                     function is NOT imported here so callers
+ *                                     control the failure mode.
+ * @param {string}  [opts.pruneHint] - Optional hint appended to the stale-
+ *                                     entry failure message (e.g. the name of
+ *                                     the allowlist file to edit).
+ * @returns {{ novel: string[], stale: string[] }} Sorted arrays of novel ids
+ *   (in current but not known) and stale ids (in known but not current).
+ */
+function assertWithinAllowlist({ label, current, known, fail, pruneHint }) {
+  const currentSet = new Set(current);
+  const knownSet = new Set(known);
+
+  const novel = [...currentSet].filter((id) => !knownSet.has(id)).sort();
+  const stale = [...knownSet].filter((id) => !currentSet.has(id)).sort();
+
+  if (novel.length > 0) {
+    const list = novel.map((id) => `  - ${id}`).join('\n');
+    fail(
+      `[${label}] ${novel.length} NEW offender(s) introduced — fix at the source; do not just add to the allowlist.\n${list}`
+    );
+  }
+
+  if (stale.length > 0) {
+    const list = stale.map((id) => `  - ${id}`).join('\n');
+    const hint = pruneHint ? `\n(${pruneHint})` : '';
+    fail(
+      `[${label}] ${stale.length} allowlisted id(s) no longer offend and MUST be pruned so the guard ratchets toward zero.${hint}\n${list}`
+    );
+  }
+
+  return { novel, stale };
+}
+
+/**
+ * Assert that an artifact's measured maximum stays within a declared ceiling,
+ * and that the ceiling itself does not creep above the high-water mark (budgets
+ * may only decrease, not increase over time).
+ *
+ * Fails when:
+ * - `actualMax > ceiling`           → regression: artifact exceeds budget.
+ * - `ceiling - actualMax > grace`   → ceiling sits too far above the measured
+ *                                     value; tighten it toward `actualMax`.
+ *
+ * ## Masking blind spot this prevents (issue #597)
+ *
+ * A plain `assert(size <= ceiling)` with a ceiling set generously high allows
+ * the artifact to grow unchecked as long as it stays under the ceiling.  The
+ * `grace` band forces the ceiling to stay close to the high-water mark,
+ * ensuring that any upward creep is immediately visible.
+ *
+ * @param {object} opts
+ * @param {string}   opts.label     - Human-readable name for the guard (used
+ *                                    in failure messages).
+ * @param {number}   opts.actualMax - The measured value (e.g. bundle size in
+ *                                    bytes, line count).
+ * @param {number}   opts.ceiling   - The declared budget ceiling.
+ * @param {number}   opts.grace     - Maximum allowed slack (`ceiling -
+ *                                    actualMax`) before the ceiling is
+ *                                    considered too loose.
+ * @param {function(string): void} opts.fail - Callback invoked with a
+ *                                    descriptive message on any violation.
+ * @returns {{ ok: boolean, slack: number }} Whether both checks passed and the
+ *   current slack value.
+ */
+function assertTightCeiling({ label, actualMax, ceiling, grace, fail }) {
+  const slack = ceiling - actualMax;
+  let ok = true;
+
+  if (actualMax > ceiling) {
+    ok = false;
+    fail(
+      `[${label}] Regression: artifact value ${actualMax} exceeds budget ceiling ${ceiling}. ` +
+        `Raise the ceiling to at most ${actualMax} only if the increase is justified.`
+    );
+  } else if (slack > grace) {
+    ok = false;
+    fail(
+      `[${label}] Ceiling ${ceiling} sits too far above the high-water mark ${actualMax} ` +
+        `(slack ${slack} > grace ${grace}). Tighten the ceiling toward ${actualMax}. ` +
+        `Budgets may only decrease.`
+    );
+  }
+
+  return { ok, slack };
+}
+
+/**
+ * Assert that each artifact's measured size matches a committed per-file
+ * baseline snapshot.  Growth, shrinkage, additions, and removals are each
+ * surfaced by name — there is no aggregate "max" that can mask one file's
+ * growth behind another file's size.
+ *
+ * Fails when, for the union of `current` and `baseline` keys:
+ * - `current[name] > baseline[name]` → GROWTH: the file grew past its recorded
+ *   size.  Regenerate the baseline and justify the growth in the PR (or extract
+ *   the content lazily).  This is the headline guard.
+ * - `current[name] < baseline[name]` → STALE: the file shrank but the baseline
+ *   still records the old (larger) size.  Regenerate to auto-tighten — the
+ *   per-file analogue of `assertWithinAllowlist`'s stale-entry rule, so the
+ *   snapshot can only ratchet downward.
+ * - name in `current` but not `baseline` → ADDED: a new artifact with no
+ *   recorded baseline.  Regenerate to record it.
+ * - name in `baseline` but not `current` → REMOVED: an orphaned baseline entry
+ *   whose artifact no longer exists.  Regenerate to drop it.
+ *
+ * ## Why per-file, not a tier max (issue #1074)
+ *
+ * A `max(group) within grace` ceiling only binds the single largest file in the
+ * group; every other file inherits that ceiling and can grow silently beneath
+ * it.  Recording each file's exact size removes the masking blind spot — the
+ * same reason `assertWithinAllowlist` enforces on identity rather than a count
+ * (issue #597).
+ *
+ * @param {object} opts
+ * @param {string} opts.label   - Human-readable guard name (used in messages).
+ * @param {Object<string, number>} opts.current  - Measured sizes by name.
+ * @param {Object<string, number>} opts.baseline - Committed sizes by name.
+ * @param {function(string): void} opts.fail - Callback invoked once per
+ *                                    non-empty violation category with a
+ *                                    descriptive message.  Injected so callers
+ *                                    control the failure mode (assert.fail, a
+ *                                    thrower, or a collector in unit tests).
+ * @param {string} [opts.updateHint] - Optional remediation hint appended to
+ *                                    every failure message (e.g. the regen
+ *                                    command).
+ * @returns {{ grown: Array<{name:string,from:number,to:number,delta:number}>,
+ *             shrunk: Array<{name:string,from:number,to:number,delta:number}>,
+ *             added: string[], removed: string[] }}
+ *   Sorted-by-name breakdown of every difference.
+ */
+function assertFileBaseline({ label, current, baseline, fail, updateHint }) {
+  const currentNames = new Set(Object.keys(current));
+  const baselineNames = new Set(Object.keys(baseline));
+
+  const added = [...currentNames].filter((n) => !baselineNames.has(n)).sort();
+  const removed = [...baselineNames].filter((n) => !currentNames.has(n)).sort();
+
+  const grown = [];
+  const shrunk = [];
+  const shared = [...currentNames].filter((n) => baselineNames.has(n)).sort();
+  for (const name of shared) {
+    const from = baseline[name];
+    const to = current[name];
+    if (to > from) grown.push({ name, from, to, delta: to - from });
+    else if (to < from) shrunk.push({ name, from, to, delta: from - to });
+  }
+
+  const hint = updateHint ? `\n${updateHint}` : '';
+
+  if (grown.length > 0) {
+    const list = grown
+      .map((g) => `  - ${g.name}: ${g.from} → ${g.to} (+${g.delta})`)
+      .join('\n');
+    fail(
+      `[${label}] ${grown.length} file(s) grew past the committed baseline. ` +
+        `Regenerate the baseline and justify the growth in your PR, or extract the content lazily.\n${list}${hint}`
+    );
+  }
+
+  if (shrunk.length > 0) {
+    const list = shrunk
+      .map((s) => `  - ${s.name}: ${s.from} → ${s.to} (-${s.delta})`)
+      .join('\n');
+    fail(
+      `[${label}] ${shrunk.length} file(s) are SMALLER than the baseline — the snapshot is stale ` +
+        `and MUST be regenerated so the budget ratchets downward.\n${list}${hint}`
+    );
+  }
+
+  if (added.length > 0) {
+    const list = added.map((n) => `  - ${n}`).join('\n');
+    fail(
+      `[${label}] ${added.length} file(s) are not in the baseline — regenerate to record them.\n${list}${hint}`
+    );
+  }
+
+  if (removed.length > 0) {
+    const list = removed.map((n) => `  - ${n}`).join('\n');
+    fail(
+      `[${label}] ${removed.length} baseline entry(ies) no longer exist — regenerate to drop them.\n${list}${hint}`
+    );
+  }
+
+  return { grown, shrunk, added, removed };
+}
+
+module.exports = { assertWithinAllowlist, assertTightCeiling, assertFileBaseline };

package/scripts/lib/cli-exit.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Error that carries a process exit code. CLI logic throws this instead of
+ * calling process.exit() (banned by n/no-process-exit); runMain() translates it
+ * into process.exitCode at the entrypoint.
+ *
+ * @param {number} code  exit code (default 1)
+ * @param {string} [message]  optional human message; when set and code != 0 it is
+ *   written to stderr by runMain before the process exits.
+ */
+class ExitError extends Error {
+  constructor(code = 1, message) {
+    super(message === undefined ? `process exit ${code}` : message);
+    this.name = 'ExitError';
+    this.code = code;
+    // Whether runMain should print this.message to stderr (only when a real
+    // message was provided, not the synthetic default).
+    this.hasUserMessage = message !== undefined;
+  }
+}
+
+/**
+ * Run a CLI main function and translate its outcome into process.exitCode
+ * (never process.exit(), so n/no-process-exit stays satisfied). Supports sync or
+ * async main.
+ *   - main returns a number  -> process.exitCode = that number
+ *   - main throws/rejects ExitError -> process.exitCode = err.code, and if
+ *       err.hasUserMessage && err.code !== 0, err.message is written to stderr
+ *   - main throws/rejects anything else -> the stack is written to stderr and
+ *       process.exitCode = 1
+ * Letting the event loop drain (vs process.exit) means buffered stdout/stderr is
+ * flushed and process.on('exit') cleanup handlers still fire.
+ *
+ * @param {() => (number|void|Promise<number|void>)} main
+ */
+function runMain(main) {
+  Promise.resolve()
+    .then(() => main())
+    .then((code) => {
+      if (typeof code === 'number') process.exitCode = code;
+    })
+    .catch((err) => {
+      if (err instanceof ExitError) {
+        if (err.hasUserMessage && err.code !== 0) {
+          process.stderr.write(`${err.message}\n`);
+        }
+        process.exitCode = err.code;
+        return;
+      }
+      process.stderr.write(`${err && err.stack ? err.stack : String(err)}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { ExitError, runMain };