pan-wizard 3.13.1 → 3.15.0

package/scripts/release-check.js

@@ -3,15 +3,16 @@
  * release-check.js — Pre-publish validation gate.
  *
  * Wired into `prepublishOnly` so `npm publish` fails BEFORE upload if any
- * gate is red. Runs five checks in order; first failure aborts.
+ * gate is red. Runs seven checks in order; first failure aborts.
  *
  *   1. build:hooks      — hook scripts copy/build cleanly
  *   2. test:all         — full test suite (unit + scenario) passes
  *   3. npm audit        — no known vulnerabilities in production deps
- *                         (we have zero runtime deps, but esbuild dev-dep is checked)
+ *                         (we have zero runtime deps, but the dev-deps are checked)
  *   4. doc-lint counts  — no drift-prone count violations in user-facing docs
- *   5. npm pack dry-run — package builds; size is sane
- *   6. smoke install    — npm pack + install into temp dir + run pan-tools list
+ *   5. links validate   — doc↔code link graph resolves (no broken references)
+ *   6. npm pack dry-run — package builds; size is sane
+ *   7. smoke install    — npm pack + install into temp dir + run pan-tools list
  *                         catches "ships but doesn't actually work" failures
  *
  * Usage:
@@ -56,7 +57,7 @@ function run(cmd, args, opts = {}) {
 }
 
 // Gate 1: build:hooks
-process.stderr.write('\n[release-check] Gate 1/6: build:hooks\n');
+process.stderr.write('\n[release-check] Gate 1/7: build:hooks\n');
 {
   const r = run('npm', ['run', 'build:hooks']);
   logGate('build:hooks', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
@@ -64,7 +65,7 @@ process.stderr.write('\n[release-check] Gate 1/6: build:hooks\n');
 }
 
 // Gate 2: test:all
-process.stderr.write('\n[release-check] Gate 2/6: test:all\n');
+process.stderr.write('\n[release-check] Gate 2/7: test:all\n');
 {
   const r = run('npm', ['run', 'test:all']);
   logGate('test:all', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
@@ -73,9 +74,9 @@ process.stderr.write('\n[release-check] Gate 2/6: test:all\n');
 
 // Gate 3: npm audit (production deps only)
 if (SKIP_AUDIT) {
-  process.stderr.write('\n[release-check] Gate 3/6: npm audit (SKIPPED)\n');
+  process.stderr.write('\n[release-check] Gate 3/7: npm audit (SKIPPED)\n');
 } else {
-  process.stderr.write('\n[release-check] Gate 3/6: npm audit --omit=dev\n');
+  process.stderr.write('\n[release-check] Gate 3/7: npm audit --omit=dev\n');
   const r = run('npm', ['audit', '--omit=dev', '--audit-level=high'], { capture: true });
   // npm audit exits non-zero on findings. We tolerate moderate; fail on high+.
   const ok = r.status === 0;
@@ -87,7 +88,7 @@ if (SKIP_AUDIT) {
 }
 
 // Gate 4: doc-lint counts on user-facing docs (count-SSoT enforcement)
-process.stderr.write('\n[release-check] Gate 4/6: doc-lint counts docs/\n');
+process.stderr.write('\n[release-check] Gate 4/7: doc-lint counts docs/\n');
 {
   const tools = path.join(REPO_ROOT, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
   const docsDir = path.join(REPO_ROOT, 'docs');
@@ -100,62 +101,67 @@ process.stderr.write('\n[release-check] Gate 4/6: doc-lint counts docs/\n');
   }
 }
 
-
-// npm runs lifecycle scripts (prepare) before pack; any of their stdout noise
-// lands ahead of the --json payload. npm pretty-prints the JSON array starting
-// on its own line — parse from there.
-function parseNpmJson(stdout) {
-  try { return JSON.parse(stdout); } catch { /* fall through to extraction */ }
-  const m = stdout.search(/^[[{]s*$/m);
-  if (m === -1) throw new Error('no JSON payload found in npm output');
-  return JSON.parse(stdout.slice(m));
+// Gate 5: doc↔code link graph resolves (anti-fake — a doc cannot reference a
+// code anchor that doesn't exist; deterministic, self-enforcing exit 1).
+process.stderr.write('\n[release-check] Gate 5/7: links validate\n');
+{
+  const tools = path.join(REPO_ROOT, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  const r = run('node', [tools, 'links', 'validate', '--raw'], { capture: true });
+  const ok = r.status === 0;
+  logGate('links validate', ok, ok ? 'doc↔code link graph resolves' : 'broken doc↔code references');
+  if (!ok) {
+    process.stderr.write((r.stdout || '') + '\n');
+    process.exit(1);
+  }
 }
 
-// Gate 5: npm pack dry-run
-process.stderr.write('\n[release-check] Gate 5/6: npm pack --dry-run\n');
+
+// NOTE: we deliberately do NOT parse `npm pack --json` stdout. Under
+// `npm publish` the runner routes the child pack's lifecycle-script output onto
+// stdout (foreground-scripts), and that noise can include a decoy JSON object —
+// any string heuristic then picks the wrong payload (Gate 7 crashed on
+// packJson[0].filename with "0 files"). Instead, pack into a temp dir and read
+// the .tgz npm actually wrote: a filesystem op that stdout noise cannot corrupt.
+
+// Gate 6: npm pack — produces a non-empty, sanely-sized tarball (read the file,
+// never parse stdout)
+process.stderr.write('\n[release-check] Gate 6/7: npm pack (size sanity)\n');
 {
-  const r = run('npm', ['pack', '--dry-run', '--json'], { capture: true });
-  if (r.status !== 0) {
-    logGate('npm pack dry-run', false, `exit ${r.status}`);
+  const tmp6 = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-pack-'));
+  const r = run('npm', ['pack', '--pack-destination', tmp6], { capture: true });
+  const tgz = r.status === 0 ? fs.readdirSync(tmp6).find(f => f.endsWith('.tgz')) : null;
+  const size = tgz ? fs.statSync(path.join(tmp6, tgz)).size : 0;
+  const sizeMB = (size / 1024 / 1024).toFixed(2);
+  // Sane = a non-empty tarball under 50MB (large for a zero-runtime-dep tool)
+  const ok = r.status === 0 && !!tgz && size > 0 && size < 50 * 1024 * 1024;
+  logGate('npm pack', ok, tgz ? `${sizeMB}MB tarball` : `no tarball (exit ${r.status})`);
+  fs.rmSync(tmp6, { recursive: true, force: true });
+  if (!ok) {
     process.stderr.write((r.stderr || '') + '\n');
     process.exit(1);
   }
-  // Parse the JSON output to check size
-  try {
-    const parsed = parseNpmJson(r.stdout);
-    const entry = Array.isArray(parsed) ? parsed[0] : parsed;
-    const size = entry.size || 0;
-    const fileCount = entry.files ? entry.files.length : 0;
-    const sizeMB = (size / 1024 / 1024).toFixed(2);
-    // Flag if pack size exceeds 50MB — large for a zero-runtime-dep tool
-    const ok = size < 50 * 1024 * 1024;
-    logGate('npm pack dry-run', ok, `${sizeMB}MB, ${fileCount} files`);
-    if (!ok) process.exit(1);
-  } catch (err) {
-    logGate('npm pack dry-run', false, 'JSON parse failed: ' + err.message);
-    process.exit(1);
-  }
 }
 
-// Gate 6: smoke install — pack and install into temp dir, run pan-tools
+// Gate 7: smoke install — pack and install into temp dir, run pan-tools
 if (SKIP_SMOKE) {
-  process.stderr.write('\n[release-check] Gate 6/6: smoke install (SKIPPED)\n');
+  process.stderr.write('\n[release-check] Gate 7/7: smoke install (SKIPPED)\n');
 } else {
-  process.stderr.write('\n[release-check] Gate 6/6: smoke install (npm pack + install + sanity)\n');
+  process.stderr.write('\n[release-check] Gate 7/7: smoke install (npm pack + install + sanity)\n');
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-smoke-'));
   try {
-    // Pack
-    const pack = run('npm', ['pack', '--pack-destination', tmpDir, '--json'], { capture: true });
+    // Pack — read the .tgz npm writes to tmpDir; never parse its stdout (see note).
+    const pack = run('npm', ['pack', '--pack-destination', tmpDir], { capture: true });
     if (pack.status !== 0) {
       logGate('smoke install (pack)', false, `exit ${pack.status}`);
+      process.stderr.write((pack.stderr || '') + '\n');
       process.exit(1);
     }
-    const packJson = parseNpmJson(pack.stdout);
-    const tarball = path.join(tmpDir, packJson[0].filename);
-    if (!fs.existsSync(tarball)) {
-      logGate('smoke install (pack)', false, `tarball not found at ${tarball}`);
+    const tgz = fs.readdirSync(tmpDir).find(f => f.endsWith('.tgz'));
+    if (!tgz) {
+      logGate('smoke install (pack)', false, `no .tgz produced in ${tmpDir}`);
       process.exit(1);
     }
+    const tarball = path.join(tmpDir, tgz);
     // Install into a separate fake project dir
     const installDir = path.join(tmpDir, 'install-target');
     fs.mkdirSync(installDir, { recursive: true });

package/scripts/run-tests.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Glob-free test runner. `node --test tests/*.test.cjs` relies on shell glob
+ * expansion: bash provides it (linux/macOS) and Node >=22 expands test-path
+ * globs itself, but Windows PowerShell does neither on Node 18/20 — the
+ * literal pattern "tests/*.test.cjs" matches no file and the run exits 1.
+ * This script expands the pattern deterministically on every platform.
+ *
+ * Usage: node scripts/run-tests.cjs <dir> [<dir> ...]
+ *   Runs every *.test.cjs DIRECTLY inside each listed directory (no recursion,
+ *   so `tests` and `tests/scenarios` stay separately addressable).
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const dirs = process.argv.slice(2);
+if (dirs.length === 0) {
+  console.error('Usage: node scripts/run-tests.cjs <dir> [<dir> ...]');
+  process.exit(1);
+}
+
+const files = [];
+for (const dir of dirs) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (e) {
+    console.error(`run-tests: cannot read directory ${dir}: ${e.message}`);
+    process.exit(1);
+  }
+  for (const name of entries.sort()) {
+    if (name.endsWith('.test.cjs')) files.push(path.join(dir, name));
+  }
+}
+
+if (files.length === 0) {
+  console.error(`run-tests: no *.test.cjs files found in: ${dirs.join(', ')}`);
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' });
+process.exit(result.status ?? 1);