@pareto4/pp-core 1.21.1 → 1.23.1

package/scripts/run-tests.cjs

@@ -33,6 +33,7 @@ const { readdirSync } = require('fs');
 const { join, basename } = require('path');
 const { execFileSync, spawnSync } = require('child_process');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { prepareSuiteEnv } = require('./test-env.cjs');
 
 const SUITES = ['all', 'unit', 'integration', 'install', 'security', 'slow'];
 
@@ -459,142 +460,160 @@ function main() {
   // exports GSD_WORKSTREAM, which would redirect fixture STATE.md reads away from
   // each <tmp>/.planning and silently diverge from the clean CI/Docker env. Strip
   // them so the local runner matches CI; tests that need them set them explicitly.
-  delete process.env.GSD_PROJECT;
-  delete process.env.GSD_WORKSTREAM;
-  delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-
-  // Log selected files to stderr for CI / harness-test visibility.
-  // node:test default reporter doesn't echo filenames, so this gives
-  // operators a single stable line they can grep.
-  console.error(
-    `run-tests: suite="${suite || 'all'}" files=${selected.length}: ${selected
-      .map(f => f.split(/[\\/]/).pop())
-      .join(' ')}`,
-  );
-
-  // Default concurrency: 4 on Linux/macOS, 2 on Windows.
-  //
-  // Windows has significantly higher per-subprocess overhead than Linux/macOS:
-  //   - Windows Defender scans each spawned process on first execution, adding
-  //     latency proportional to the number of concurrent spawns.
-  //   - NTFS has higher file-system latency under concurrent access compared to
-  //     ext4/APFS, which amplifies contention when multiple test chunks run in
-  //     parallel and all read/write the same fixture directories.
-  // Reducing to 2 halves the peak concurrent subprocess count on Windows and
-  // keeps per-chunk wall-clock time well within the 20m CI job cap.
-  //
-  // Operator override via TEST_CONCURRENCY env var for local debugging.
-  const defaultConcurrency = process.platform === 'win32' ? 2 : 4;
-  const concurrency = process.env.TEST_CONCURRENCY
-    ? `--test-concurrency=${process.env.TEST_CONCURRENCY}`
-    : `--test-concurrency=${defaultConcurrency}`;
-
-  // Windows `CreateProcess` caps the full command line at 32,767 chars
-  // (lpCommandLine). With 500+ test paths the spawn fails instantly with no
-  // test output. Linux/macOS allow ~2 MB (ARG_MAX) so unchunked spawns are
-  // fine there. Split into chunks sized for the tightest target so behavior
-  // is identical across platforms. (#3597)
-  // Operator override (also used by tests to force chunking with short paths).
-  const MAX_CMDLINE_CHARS = process.env.RUN_TESTS_MAX_CMDLINE_CHARS
-    ? Number(process.env.RUN_TESTS_MAX_CMDLINE_CHARS)
-    : 28000; // headroom below the 32,767 Windows ceiling
-  const MAX_FILES_PER_CHUNK = process.env.RUN_TESTS_MAX_FILES_PER_CHUNK
-    ? Number(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK)
-    : 180;
-
-  // node:test does not exit until the event loop drains. A unit test that leaks
-  // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)
-  // makes a chunk's `node --test` child hang ~150s on Windows AFTER its last test
-  // prints; two such stalls push the windows full lane past its 20m cap and the
-  // job is CANCELLED with no failed step — a false-negative gate (#1051, recurrence
-  // of #869). --test-force-exit (Node >=22; engines requires >=22.0.0) exits the
-  // runner once all tests finish regardless of lingering handles. The leaking
-  // tests are also fixed at the source; this is the defensive backstop.
-  // RUN_TESTS_NO_FORCE_EXIT=1 disables it (used by the harness regression test to
-  // observe the pre-fix hang).
-  const nodeMajor = Number(process.versions.node.split('.')[0]);
-  const forceExit = nodeMajor >= 22 && !process.env.RUN_TESTS_NO_FORCE_EXIT;
-
-  const FIXED_OVERHEAD = process.execPath.length + '--test'.length + concurrency.length + (forceExit ? '--test-force-exit'.length + 1 : 0) + 8;
-  const chunks = [];
-  let current = [];
-  let currentLen = FIXED_OVERHEAD;
-  for (const file of selected) {
-    const add = file.length + 1; // +1 for the inter-arg separator
-    if (
-      current.length > 0 &&
-      (currentLen + add > MAX_CMDLINE_CHARS || current.length >= MAX_FILES_PER_CHUNK)
-    ) {
-      chunks.push(current);
-      current = [];
-      currentLen = FIXED_OVERHEAD;
-    }
-    current.push(file);
-    currentLen += add;
-  }
-  if (current.length > 0) chunks.push(current);
-
-  // A chunk that still hangs (a leak the backstop somehow misses, or a wedged
-  // subprocess) must fail loudly rather than silently burn the job's wall-clock
-  // budget until the CI runner cancels the whole job. Default 10 min per chunk:
-  // well above a healthy chunk (~4-5 min on the windows lane) but below the 20m
-  // job cap. Operator/test override via RUN_TESTS_CHUNK_TIMEOUT_MS.
-  const chunkTimeoutMs = process.env.RUN_TESTS_CHUNK_TIMEOUT_MS
-    ? Number(process.env.RUN_TESTS_CHUNK_TIMEOUT_MS)
-    : 600000;
-
-  let firstFailureExit = 0;
-  for (let i = 0; i < chunks.length; i++) {
-    if (chunks.length > 1) {
-      console.error(`run-tests: chunk ${i + 1}/${chunks.length} — ${chunks[i].length} files`);
-    }
-    const chunkFiles = chunks[i].map(f => f.split(/[\\/]/).pop()).join(' ');
-    // stdout is captured, not inherited, so the chunk's node:test summary can be
-    // checked; it is written through unchanged once the chunk ends. stderr stays
-    // live. A chunk can exit 0 with its output cut off and no summary — on CI
-    // (2026-10-28) two of five chunks did, and ~1,000 tests never reported while
-    // the job stayed green — so a missing summary fails the run.
-    const result = spawnSync(
-      process.execPath,
-      ['--test', ...(forceExit ? ['--test-force-exit'] : []), concurrency, ...chunks[i]],
-      {
-        stdio: ['inherit', 'pipe', 'inherit'],
-        env: { ...process.env },
-        timeout: chunkTimeoutMs,
-        maxBuffer: 1024 * 1024 * 1024,
-      },
+  // The same goes for the person's audience setting (AUD-04): PP_AUDIENCE and the
+  // person file (`~/.gsd/person.json`, rooted at GSD_HOME || home) are stripped /
+  // redirected so a developer whose own audience is business gets CI's results.
+  // Tests that need a setting pass their own GSD_HOME / PP_AUDIENCE.
+  // The same preparation backs `npm run test:affected` (scripts/test-env.cjs).
+  const suiteEnv = prepareSuiteEnv(process.env);
+
+  try {
+    // Log selected files to stderr for CI / harness-test visibility.
+    // node:test default reporter doesn't echo filenames, so this gives
+    // operators a single stable line they can grep.
+    console.error(
+      `run-tests: suite="${suite || 'all'}" files=${selected.length}: ${selected
+        .map(f => f.split(/[\\/]/).pop())
+        .join(' ')}`,
     );
-    if (result.stdout && result.stdout.length > 0) process.stdout.write(result.stdout);
-    // When the per-chunk timeout fires, spawnSync kills the child and reports
-    // error.code === 'ETIMEDOUT' (POSIX) and/or a kill signal (platform-dependent).
-    // Check both so detection holds on Windows and POSIX.
-    const timedOut = (result.error && result.error.code === 'ETIMEDOUT') ||
-      (result.signal !== null && result.status === null && !result.error);
-    let code = result.status === null ? 1 : result.status;
-    if (result.error && result.error.code === 'ETIMEDOUT') code = 1;
-    if (timedOut) {
-      console.error(
-        `run-tests: chunk ${i + 1}/${chunks.length} exceeded the per-chunk timeout ` +
-          `of ${chunkTimeoutMs}ms and was killed — a test in this chunk is likely leaking ` +
-          `an open handle (un-terminated Worker, un-killed child process, or ref'd timer) ` +
-          `so node --test never exits. Files: ${chunkFiles}`,
-      );
-    } else if (result.error) {
-      console.error(`run-tests: chunk ${i + 1}/${chunks.length} could not run: ${result.error.message}`);
-      code = 1;
-    } else if (code === 0 && !hasTestSummary(result.stdout)) {
-      console.error(
-        `run-tests: chunk ${i + 1}/${chunks.length} exited without a test summary ` +
-          `(no "ℹ tests N" / "ℹ fail N" lines) — its output was cut off, so some of its ` +
-          `tests never reported. Files: ${chunkFiles}`,
+
+    // Default concurrency: 4 on Linux/macOS, 2 on Windows.
+    //
+    // Windows has significantly higher per-subprocess overhead than Linux/macOS:
+    //   - Windows Defender scans each spawned process on first execution, adding
+    //     latency proportional to the number of concurrent spawns.
+    //   - NTFS has higher file-system latency under concurrent access compared to
+    //     ext4/APFS, which amplifies contention when multiple test chunks run in
+    //     parallel and all read/write the same fixture directories.
+    // Reducing to 2 halves the peak concurrent subprocess count on Windows and
+    // keeps per-chunk wall-clock time well within the 20m CI job cap.
+    //
+    // Operator override via TEST_CONCURRENCY env var for local debugging.
+    const defaultConcurrency = process.platform === 'win32' ? 2 : 4;
+    const concurrency = process.env.TEST_CONCURRENCY
+      ? `--test-concurrency=${process.env.TEST_CONCURRENCY}`
+      : `--test-concurrency=${defaultConcurrency}`;
+
+    // Windows `CreateProcess` caps the full command line at 32,767 chars
+    // (lpCommandLine). With 500+ test paths the spawn fails instantly with no
+    // test output. Linux/macOS allow ~2 MB (ARG_MAX) so unchunked spawns are
+    // fine there. Split into chunks sized for the tightest target so behavior
+    // is identical across platforms. (#3597)
+    // Operator override (also used by tests to force chunking with short paths).
+    const MAX_CMDLINE_CHARS = process.env.RUN_TESTS_MAX_CMDLINE_CHARS
+      ? Number(process.env.RUN_TESTS_MAX_CMDLINE_CHARS)
+      : 28000; // headroom below the 32,767 Windows ceiling
+    const MAX_FILES_PER_CHUNK = process.env.RUN_TESTS_MAX_FILES_PER_CHUNK
+      ? Number(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK)
+      : 180;
+
+    // node:test does not exit until the event loop drains. A unit test that leaks
+    // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)
+    // makes a chunk's `node --test` child hang ~150s on Windows AFTER its last test
+    // prints; two such stalls push the windows full lane past its 20m cap and the
+    // job is CANCELLED with no failed step — a false-negative gate (#1051, recurrence
+    // of #869). --test-force-exit (Node >=22) exits the runner once all tests
+    // finish regardless of lingering handles — but it exits before the reporter has
+    // written everything, so it DROPS reported tests: a 180-file chunk reported
+    // 4,688 / 4,726 / 4,705 tests with it and 4,759 every time without it (Linux,
+    // 1.5 CPUs, 2026-11-10), and on GitHub runners it cut whole chunk summaries
+    // (PR #31/#32). The leaking tests were fixed at the source and no CI lane runs
+    // Windows any more, so it is now OPT-IN: RUN_TESTS_FORCE_EXIT=1. The per-chunk
+    // timeout below still bounds a genuine hang, loudly.
+    const nodeMajor = Number(process.versions.node.split('.')[0]);
+    const forceExit = nodeMajor >= 22 && process.env.RUN_TESTS_FORCE_EXIT === '1';
+
+    const FIXED_OVERHEAD = process.execPath.length + '--test'.length + concurrency.length + (forceExit ? '--test-force-exit'.length + 1 : 0) + 8;
+    const chunks = [];
+    let current = [];
+    let currentLen = FIXED_OVERHEAD;
+    for (const file of selected) {
+      const add = file.length + 1; // +1 for the inter-arg separator
+      if (
+        current.length > 0 &&
+        (currentLen + add > MAX_CMDLINE_CHARS || current.length >= MAX_FILES_PER_CHUNK)
+      ) {
+        chunks.push(current);
+        current = [];
+        currentLen = FIXED_OVERHEAD;
+      }
+      current.push(file);
+      currentLen += add;
+    }
+    if (current.length > 0) chunks.push(current);
+
+    // A chunk that still hangs (a leak the backstop somehow misses, or a wedged
+    // subprocess) must fail loudly rather than silently burn the job's wall-clock
+    // budget until the CI runner cancels the whole job. Default 10 min per chunk:
+    // well above a healthy chunk (~4-5 min on the windows lane) but below the 20m
+    // job cap. Operator/test override via RUN_TESTS_CHUNK_TIMEOUT_MS.
+    const chunkTimeoutMs = process.env.RUN_TESTS_CHUNK_TIMEOUT_MS
+      ? Number(process.env.RUN_TESTS_CHUNK_TIMEOUT_MS)
+      : 600000;
+
+    let firstFailureExit = 0;
+    for (let i = 0; i < chunks.length; i++) {
+      if (chunks.length > 1) {
+        console.error(`run-tests: chunk ${i + 1}/${chunks.length} — ${chunks[i].length} files`);
+      }
+      const chunkFiles = chunks[i].map(f => f.split(/[\\/]/).pop()).join(' ');
+      // stdout is captured, not inherited, so the chunk's node:test summary can be
+      // checked; it is written through unchanged once the chunk ends. stderr stays
+      // live. A chunk can exit 0 with its output cut off and no summary — on CI
+      // (2026-10-28) two of five chunks did, and ~1,000 tests never reported while
+      // the job stayed green — so a missing summary fails the run.
+      const result = spawnSync(
+        process.execPath,
+        ['--test', ...(forceExit ? ['--test-force-exit'] : []), concurrency, ...chunks[i]],
+        {
+          stdio: ['inherit', 'pipe', 'inherit'],
+          env: { ...process.env },
+          timeout: chunkTimeoutMs,
+          maxBuffer: 1024 * 1024 * 1024,
+        },
       );
-      code = 1;
+      if (result.stdout && result.stdout.length > 0) process.stdout.write(result.stdout);
+      // When the per-chunk timeout fires, spawnSync kills the child and reports
+      // error.code === 'ETIMEDOUT' (POSIX) and/or a kill signal (platform-dependent).
+      // Check both so detection holds on Windows and POSIX.
+      const timedOut = (result.error && result.error.code === 'ETIMEDOUT') ||
+        (result.signal !== null && result.status === null && !result.error);
+      let code = result.status === null ? 1 : result.status;
+      if (result.error && result.error.code === 'ETIMEDOUT') code = 1;
+      if (timedOut) {
+        console.error(
+          `run-tests: chunk ${i + 1}/${chunks.length} exceeded the per-chunk timeout ` +
+            `of ${chunkTimeoutMs}ms and was killed — a test in this chunk is likely leaking ` +
+            `an open handle (un-terminated Worker, un-killed child process, or ref'd timer) ` +
+            `so node --test never exits. Files: ${chunkFiles}`,
+        );
+      } else if (result.error) {
+        console.error(`run-tests: chunk ${i + 1}/${chunks.length} could not run: ${result.error.message}`);
+        code = 1;
+      } else if (code === 0 && !hasTestSummary(result.stdout)) {
+        console.error(
+          `run-tests: chunk ${i + 1}/${chunks.length} exited without a test summary ` +
+            `(no "ℹ tests N" / "ℹ fail N" lines) — its output was cut off, so some of its ` +
+            `tests never reported. Files: ${chunkFiles}`,
+        );
+        code = 1;
+      }
+      // Run every chunk so the operator sees all failures in one pass; report
+      // the first non-zero exit at the end.
+      if (code !== 0 && firstFailureExit === 0) firstFailureExit = code;
+    }
+
+    // A test that wrote the shared suite person file would poison every file that
+    // runs after it, so it fails the run loudly instead of causing flakiness.
+    const leak = suiteEnv.leakMessage();
+    if (leak) {
+      console.error(`run-tests: ${leak}`);
+      return firstFailureExit !== 0 ? firstFailureExit : 1;
     }
-    // Run every chunk so the operator sees all failures in one pass; report
-    // the first non-zero exit at the end.
-    if (code !== 0 && firstFailureExit === 0) firstFailureExit = code;
+    if (firstFailureExit !== 0) return firstFailureExit;
+  } finally {
+    suiteEnv.cleanup();
   }
-  if (firstFailureExit !== 0) return firstFailureExit;
 }
 
 /**

package/scripts/test-env.cjs

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * Shared test-suite environment preparation (Phase 39 D-16, WR-04).
+ *
+ * Both entry points that spawn `node --test` — `scripts/run-tests.cjs`
+ * (`npm test`) and `scripts/affected-tests-lib.cjs#runNodeTestFiles`
+ * (`npm run test:affected`) — call this, so a developer's own shell never
+ * changes what the suite sees:
+ *
+ *   - GSD_PROJECT / GSD_WORKSTREAM would redirect fixture `.planning` reads;
+ *   - CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS changes agent dispatch;
+ *   - PP_AUDIENCE and the person file (`~/.gsd/person.json`, rooted at
+ *     GSD_HOME || home) would change the resolved audience (AUD-04).
+ *
+ * The person file's home is redirected to a fresh throwaway directory for the
+ * whole run. A test that writes the person file there would poison every file
+ * that runs after it, so `leakMessage()` reports it and the caller fails the
+ * run. Tests that need a setting pass their own GSD_HOME / PP_AUDIENCE.
+ *
+ * Kept out of `scripts/lib/` on purpose: the installer copies every file in
+ * `scripts/lib/` into each user's config dir, and this is a dev-only helper.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const STRIPPED_VARS = Object.freeze([
+  'GSD_PROJECT',
+  'GSD_WORKSTREAM',
+  'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS',
+  'PP_AUDIENCE',
+]);
+
+/**
+ * Strip the session variables from `env` (mutated in place) and point its
+ * GSD_HOME at a new temporary suite home.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {{ env: NodeJS.ProcessEnv, home: string, leakMessage: () => string|null, cleanup: () => void }}
+ */
+function prepareSuiteEnv(env = process.env) {
+  for (const name of STRIPPED_VARS) delete env[name];
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'pp-suite-home-'));
+  env.GSD_HOME = home;
+  const personFile = path.join(home, '.gsd', 'person.json');
+  return {
+    env,
+    home,
+    leakMessage() {
+      if (!fs.existsSync(personFile)) return null;
+      return (
+        `a test wrote the person file in the shared suite home (${personFile}) — ` +
+        'every test that runs audience set/answer or installs with --audience must pass its own GSD_HOME'
+      );
+    },
+    cleanup() {
+      fs.rmSync(home, { recursive: true, force: true });
+    },
+  };
+}
+
+module.exports = { prepareSuiteEnv, STRIPPED_VARS };