@boyingliu01/xp-gate 0.31.1 → 0.31.3

package/lib/gate-runner.js

@@ -3,6 +3,159 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+/**
+ * Source-file extensions the gate fragments know how to analyse.
+ *
+ * Shared by the `--all` scope resolver so a full-tree check and the adapters agree
+ * on what a "source file" is. Data and documentation formats are deliberately
+ * absent: handing a markdown file to lizard is not a check, it is noise.
+ */
+const SOURCE_FILE_EXTENSIONS = [
+  'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs',
+  'py', 'go', 'java', 'kt', 'kts', 'scala',
+  'c', 'cc', 'cpp', 'cxx', 'h', 'hpp',
+  'rs', 'php', 'dart', 'swift', 'm', 'mm',
+  'sh', 'bash', 'ps1', 'psm1', 'rb',
+];
+
+/**
+ * Every tracked source file in the repository, one per line.
+ *
+ * This is what `--all` must hand the gates that read CHANGED_FILES.
+ *
+ * #589: `check --all` was documented as a full-tree check but still built
+ * CHANGED_FILES from `git diff`, so on a clean tree — the normal state after a
+ * commit, and the state CI runs in — Gate 3 received an empty list and printed
+ *
+ *     ⏭️  SKIPPED - Complexity (no source files to check)
+ *
+ * `--all` therefore checked LESS than an ordinary commit, while reading like a
+ * pass. Gate 4 does not depend on CHANGED_FILES and worked fine under the same
+ * preamble, which is what proves the file SOURCE was the defect.
+ *
+ * @param {string} [cwd] repository directory
+ * @returns {string} newline-separated repo-relative paths, empty on any failure
+ */
+function resolveAllModeChangedFiles(cwd = process.cwd()) {
+  const pathspecs = SOURCE_FILE_EXTENSIONS.map((ext) => `*.${ext}`);
+  try {
+    const out = execFileSync('git', ['ls-files', ...pathspecs], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\n').filter(Boolean).join('\n');
+  } catch {
+    // Not a git repo, or git missing: an empty list is honest, and the caller's
+    // message distinguishes "empty diff" from "empty tree".
+    return '';
+  }
+}
+
+/**
+ * Explain an empty CHANGED_FILES honestly, given which scope produced it.
+ *
+ * The old wording ("no source files to check") described an empty PROJECT when
+ * the actual cause was an empty DIFF — and the natural reading of the old message
+ * is "this gate passed". #589's reporter worked around it by running lizard by
+ * hand, which is the cost of an ambiguous skip.
+ *
+ * @param {'diff'|'all'} scope which scope was used
+ * @param {number} count number of files in the list
+ * @returns {string} one line, no trailing newline
+ */
+function describeEmptyChangedFiles(scope, count) {
+  if (count > 0) {
+    return scope === 'all'
+      ? `${count} tracked source file(s) in scope (--all: whole tree)`
+      : `${count} changed source file(s) in scope`;
+  }
+  if (scope === 'all') {
+    return 'no tracked source files in this repository (--all already scanned the whole tree)';
+  }
+  // Name the real cause and the action that fixes it. Deliberately does NOT say
+  // "no source files": that describes the project, which is not what happened.
+  return 'no changed files in this run (0 staged, 0 vs HEAD) — run with `--all` to scan the whole tree';
+}
+
+/**
+ * Report which scope a gate actually used.
+ *
+ * A silent switch between diff and tree is the same defect one level up: the
+ * reader cannot tell what was inspected. Printed once per standalone run so
+ * "full check" cannot quietly mean "diff check".
+ *
+ * @param {'diff'|'all'} scope
+ * @param {number} count
+ * @returns {string}
+ */
+function describeChangedFilesScope(scope, count) {
+  const label = scope === 'all' ? 'all' : 'diff';
+  return `scope: ${label} (${count} file(s))`;
+}
+
+/**
+ * Which bash can run the gate fragments.
+ *
+ * On Windows, PATH may lead with the WSL System32 stub, which cannot run these
+ * hooks (Linux filesystem view, and `-c` scripts receive an empty $1 through it).
+ * checkBash probes for an MSYS/MINGW bash that round-trips argv correctly.
+ *
+ * @returns {string|null} the bash command, or null when only an unusable one exists
+ */
+function resolveBashForGates() {
+  if (process.platform !== 'win32') return 'bash';
+  const { checkBash } = require('./detect-deps.js');
+  const bash = checkBash();
+  return bash.ok ? bash.path : null;
+}
+
+/**
+ * The first candidate that exists on disk, or the empty string.
+ *
+ * The empty string (not a throw) is deliberate: the preamble tolerates a missing
+ * helper script and the fragment then fails the same way it does in the commit
+ * hook.
+ *
+ * @param {string[]} candidates paths to try in order
+ * @returns {string}
+ */
+function firstExisting(candidates) {
+  try {
+    return candidates.find(candidate => fs.existsSync(candidate)) || '';
+  } catch {
+    // existsSync only throws on a malformed path; treat that as "none".
+    return '';
+  }
+}
+
+/**
+ * The shell lines that populate CHANGED_FILES, chosen by scan scope.
+ *
+ * Extracted so `runGateAdapter` stays readable: the diff form is three lines of
+ * git plumbing and the tree form is a single assignment, and mixing them inline
+ * made the wrapper harder to follow than the thing it wraps.
+ *
+ * @param {boolean} allMode true for `--all` (whole tree)
+ * @param {string} allModeFiles pre-resolved file list for all mode
+ * @returns {string[]} shell lines
+ */
+function buildFileSourceLines(allMode, allModeFiles) {
+  if (allMode) {
+    return ['#589: --all scans the tracked tree, not the diff', `CHANGED_FILES=${JSON.stringify(allModeFiles)}`];
+  }
+  // The historical diff form, unchanged: staged first, then anything vs HEAD.
+  // Interpolating the literal `${CHANGED_FILES}` brace-by-brace would be torn apart
+  // by this file's own template literals, hence the split below.
+  const changedFilesParameter = ['$', '{CHANGED_FILES}'].join('');
+  return [
+    'CHANGED_FILES="$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)"',
+    `if [ -z "${changedFilesParameter}" ] && [ -n "$(git rev-parse HEAD 2>/dev/null)" ]; then`,
+    '  CHANGED_FILES="$(git diff HEAD --name-only --diff-filter=ACM 2>/dev/null || true)"',
+    'fi',
+  ];
+}
+
 /**
  * Run a gate adapter fragment standalone.
  *
@@ -16,75 +169,96 @@ const path = require('node:path');
  * the fragments fail with "command not found". This wrapper reconstructs the
  * same preamble the pre-commit hook sets up, then *sources* the fragment so it
  * behaves exactly as it does inside the commit hook.
+ *
+ * @param {string} scriptPath gate fragment to source
+ * @param {string} [cwd] project directory
+ * @param {{scope?: 'diff'|'all'}} [opts] `all` resolves CHANGED_FILES from the
+ *   tracked tree instead of the diff (#589)
  */
-function runGateAdapter(scriptPath, cwd = process.cwd()) {
-  let bashCommand = 'bash';
-  if (process.platform === 'win32') {
-    // PATH may lead with the WSL System32 stub, which cannot run these hooks
-    // (Linux filesystem view, and `-c` scripts receive an empty $1 through it).
-    // checkBash probes for an MSYS/MINGW bash that round-trips argv correctly.
-    const { checkBash } = require('./detect-deps.js');
-    const bash = checkBash();
-    if (!bash.ok) {
-      console.log('⚠️  This gate requires bash to run shell scripts.');
-      // No WSL suggestion: these hooks need Git Bash specifically — the WSL
-      // bash is rejected by the probe above (Linux filesystem view, dropped $1).
-      console.log('   On Windows, install Git for Windows (https://git-scm.com/download/win).');
-      console.log('   Alternatively, install the required tool directly and run the gate again.');
-      return;
-    }
-    bashCommand = bash.path;
+function runGateAdapter(scriptPath, cwd = process.cwd(), opts = {}) {
+  const bashCommand = resolveBashForGates();
+  if (!bashCommand) {
+    console.log('⚠️  This gate requires bash to run shell scripts.');
+    // No WSL suggestion: these hooks need Git Bash specifically — the WSL bash is
+    // rejected by the probe (Linux filesystem view, dropped $1).
+    console.log('   On Windows, install Git for Windows (https://git-scm.com/download/win).');
+    console.log('   Alternatively, install the required tool directly and run the gate again.');
+    return;
   }
   const scriptDir = path.dirname(scriptPath);
-  const commonScript = [
+  const commonScript = firstExisting([
     path.join(scriptDir, 'adapter-common.sh'),
     path.join(scriptDir, '..', 'adapter-common.sh'),
     path.join(cwd, 'githooks', 'adapter-common.sh'),
-  ].find(candidate => fs.existsSync(candidate)) || '';
-  const nowMsScript = [
+  ]);
+  const nowMsScript = firstExisting([
     path.join(scriptDir, 'lib', 'now-ms.sh'),
     path.join(scriptDir, '..', 'lib', 'now-ms.sh'),
     path.resolve(__dirname, '..', 'hooks', 'lib', 'now-ms.sh'),
-  ].find(candidate => fs.existsSync(candidate)) || '';
-  const changedFilesParameter = ['$', '{CHANGED_FILES}'].join('');
+  ]);
+  // #589: the scope determines the file SOURCE. Under `--all` the gates that read
+  // CHANGED_FILES must see the whole tree, not the diff — otherwise a full check
+  // scans less than an ordinary commit and reads like a pass.
+  const allMode = opts.scope === 'all';
+  const fileSourceLines = buildFileSourceLines(allMode, allMode ? resolveAllModeChangedFiles(cwd) : '');
+  const wrap = buildPreamble(allMode, fileSourceLines);
 
-  // Build the shell preamble the pre-commit hook would otherwise inject before
-  // sourcing the gate fragment, then source that fragment. Deliberately NOT
-  // set -u (the pre-commit hook does not use it), so fragments that reference
-  // a not-yet-defined variable fail the same way inside the commit hook.
-  const wrap = [
+  // execFileSync avoids an extra /bin/sh layer, so bash receives the script as a
+  // single argv arg (no shell-metacharacter injection through the path).
+  execFileSync(
+    bashCommand,
+    ['--noprofile', '--norc', '-c', wrap, 'xp-gate', commonScript, nowMsScript, scriptPath, process.execPath],
+    { stdio: 'inherit', cwd }
+  );
+}
+
+/**
+ * The shell preamble the pre-commit hook would otherwise inject before sourcing a
+ * gate fragment.
+ *
+ * Deliberately NOT `set -u` (the pre-commit hook does not use it), so fragments
+ * that reference a not-yet-defined variable fail the same way inside the commit
+ * hook.
+ *
+ * @param {boolean} allMode whether the run scope is the whole tree
+ * @param {string[]} fileSourceLines lines that populate CHANGED_FILES
+ * @returns {string} the script to hand bash with -c
+ */
+function buildPreamble(allMode, fileSourceLines) {
+  return [
     'if [ -n "$1" ] && [ -f "$1" ]; then source "$1"; fi',
     'if [ -n "$2" ] && [ -f "$2" ]; then source "$2"; fi',
     'if ! command -v now_ms >/dev/null 2>&1; then now_ms() { "$4" -e "console.log(Date.now())"; }; fi',
     'gate_start_ms() { now_ms; }',
     'record_gate_audit() { :; }',
     'PROJECT_LANG="$(detect_project_lang 2>/dev/null || echo unknown)"',
-    'CHANGED_FILES="$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)"',
-    `if [ -z "${changedFilesParameter}" ] && [ -n "$(git rev-parse HEAD 2>/dev/null)" ]; then`,
-    '  CHANGED_FILES="$(git diff HEAD --name-only --diff-filter=ACM 2>/dev/null || true)"',
-    'fi',
+    // #589: fragments need to know which scope produced the file list, so an empty
+    // list can say "empty diff" instead of "empty project".
+    `GATE_SCOPE=${JSON.stringify(allMode ? 'all' : 'diff')}`,
+    ...fileSourceLines,
     'source "$3"',
   ].join('\n');
-
-  // execFileSync avoids an extra /bin/sh layer, so bash receives the script as a
-  // single argv arg (no shell-metacharacter injection through the path).
-  execFileSync(
-    bashCommand,
-    ['--noprofile', '--norc', '-c', wrap, 'xp-gate', commonScript, nowMsScript, scriptPath, process.execPath],
-    { stdio: 'inherit', cwd }
-  );
 }
 
 // Gate metadata registry — maps gate IDs to names, descriptions, and how to run them.
 // Standalone gates (<gate-id>: { run }) are invokable via xp-gate gate-<id>.
 // Pre-commit-only gates (<gate-id>: { preCommitOnly: true }) run only in git commit context.
 
+/**
+ * Wall-clock budget for one TypeScript gate run.
+ *
+ * Generous on purpose: `gate-5-runner-error.test.ts` alone takes ~400s on CI, and a
+ * gate killed for being slow must be reported as "did not report a verdict", never
+ * silently counted as a pass.
+ */
+const TS_GATE_TIMEOUT_MS = 120000;
+
 /**
  * Run a TypeScript gate module via npx tsx.
  * Finds the .ts entry point, spawns tsx with --run flag.
  * Falls back to bash script if TypeScript module not found.
  */
-function runTsGate(gateModule, targetPath) {
+function runTsGate(gateModule, targetPath, opts = {}) {
   const targetCwd = targetPath ? path.resolve(targetPath) : process.cwd();
   const entry = findTsGateEntry(gateModule);
   if (!entry) {
@@ -92,7 +266,7 @@ function runTsGate(gateModule, targetPath) {
     const gateNum = gateModule.replace('gate-', '');
     const script = resolveGateScript(gateNum, targetCwd);
     if (script) {
-      runGateAdapter(script, targetCwd);
+      runGateAdapter(script, targetCwd, opts);
     } else {
       console.log(`Gate ${gateModule}: TypeScript module not found and no bash fallback available.`);
     }
@@ -102,14 +276,26 @@ function runTsGate(gateModule, targetPath) {
   const args = ['-y', 'tsx', entry, '--run'];
   if (targetPath) args.push('--cwd', targetPath);
 
-  const result = spawnSync('npx', args, {
-    stdio: 'inherit',
-    shell: process.platform === 'win32',
-    cwd: targetCwd,
-    timeout: 120000,
-  });
-
-  return result.status === null ? 1 : result.status;
+  // spawnSync reports a spawn failure (npx missing) on `error`, throws only on a
+  // malformed argv, and reports a killed child (timeout, signal) as a null status.
+  // All three mean "the gate did not report a verdict", which must not be read as
+  // success: a gate that never ran is not a gate that passed.
+  try {
+    const result = spawnSync('npx', args, {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      cwd: targetCwd,
+      timeout: TS_GATE_TIMEOUT_MS,
+    });
+    if (result.error) {
+      console.error(`Gate ${gateModule}: failed to run npx tsx: ${result.error.message}`);
+      return 1;
+    }
+    return result.status === null ? 1 : result.status;
+  } catch (err) {
+    console.error(`Gate ${gateModule}: could not spawn npx tsx: ${err.message}`);
+    return 1;
+  }
 }
 
 function findTsGateEntry(gateModule) {
@@ -159,8 +345,8 @@ const GATE_REGISTRY = {
     name: 'Cyclomatic Complexity',
     description: 'lizard cyclomatic complexity analysis',
     aliases: ['complexity', 'ccn', '3'],
-    run: (targetPath) => {
-      return runTsGate('gate-3', targetPath);
+    run: (targetPath, opts) => {
+      return runTsGate('gate-3', targetPath, opts);
     },
   },
   '4': {
@@ -295,6 +481,26 @@ function findConfig(basePath, fileName) {
   return null;
 }
 
+/**
+ * The basename of the first `gate-<num>-*.sh` in a directory, or null.
+ *
+ * A missing directory is the normal case (most projects have no `githooks/gates/`),
+ * so it returns null rather than throwing; a read error is also treated as "no
+ * match" because the caller falls through to the next candidate either way.
+ *
+ * @param {string} dir directory to list
+ * @param {string} gateNum gate number as a string
+ * @returns {string|null}
+ */
+function matchGateFileIn(dir, gateNum) {
+  try {
+    if (!fs.existsSync(dir)) return null;
+    return fs.readdirSync(dir).find(f => f.startsWith(`gate-${gateNum}-`) && f.endsWith('.sh')) || null;
+  } catch {
+    return null;
+  }
+}
+
 function resolveGateScript(gateNum, cwd = process.cwd()) {
   const candidates = [
     path.join(cwd, 'githooks', 'gates', `gate-${gateNum}-*.sh`),
@@ -305,10 +511,8 @@ function resolveGateScript(gateNum, cwd = process.cwd()) {
   for (const pattern of candidates) {
     if (pattern.includes('*')) {
       const dir = path.dirname(pattern);
-      if (fs.existsSync(dir)) {
-        const match = fs.readdirSync(dir).find(f => f.startsWith(`gate-${gateNum}-`) && f.endsWith('.sh'));
-        if (match) return path.join(dir, match);
-      }
+      const match = matchGateFileIn(dir, gateNum);
+      if (match) return path.join(dir, match);
     } else if (fs.existsSync(pattern)) {
       return pattern;
     }
@@ -337,7 +541,7 @@ function getAllGates() {
   }));
 }
 
-async function runGate(gateId, targetPath) {
+async function runGate(gateId, targetPath, opts = {}) {
   const gate = GATE_REGISTRY[String(gateId)];
   if (!gate) {
     console.error(`Unknown gate: ${gateId}`);
@@ -356,7 +560,10 @@ async function runGate(gateId, targetPath) {
   if (gate.run) {
     console.log(`━━━ Gate ${gateId}: ${gate.name} ━━━`);
     try {
-      const result = gate.run(targetPath);
+      // #589: pass the scope through so a handler that shells out to a fragment
+      // can resolve its file list from the tree under --all. Handlers that ignore
+      // the second argument are unaffected.
+      const result = gate.run(targetPath, opts);
       if (result && typeof result.then === 'function') {
         return await result;
       }
@@ -378,4 +585,4 @@ async function runGate(gateId, targetPath) {
   return 1;
 }
 
-module.exports = { GATE_REGISTRY, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript };
+module.exports = { GATE_REGISTRY, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-22T08:31:44.285Z",
+  "checked_at": "2026-10-26T05:44:50.695Z",
   "source": "network"
 }

package/lib/principles.js

@@ -2,8 +2,147 @@
 
 const { spawnSync } = require('child_process');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
+/**
+ * Above this many characters of argv, the file list is handed over by reference
+ * (a temp file with `@`) instead of on the command line.
+ *
+ * #586: on Windows, `shell: true` routes through cmd.exe, whose command line is
+ * capped at 8191 characters. Measure from the issue: 135 Java files came to 12944
+ * characters before the `npx -y tsx <entry> --files --format json` prefix. That is
+ * not an unusually large project — it is a mid-sized one, every time.
+ *
+ * 6000 leaves room for the executable, the entry path and the flags without
+ * reaching the limit on any plausible installation path.
+ */
+const ARGV_CHAR_BUDGET = 6000;
+
+/**
+ * Build the executable + argument list for one principles run.
+ *
+ * Two things this must guarantee, both from #586:
+ *
+ *   1. no shell. `shell: true` is what reaches cmd.exe's 8191-character ceiling, and
+ *      the fix is to not need a shell at all: prefer the project's own tsx run
+ *      through `process.execPath` (an absolute node.exe — no shim, so no shell).
+ *   2. bounded argv. Splitting `files.join(' ')` into many argv elements was
+ *      explicitly ruled out in the issue and it is right to rule it out: the
+ *      bottleneck is total characters, not quoting. So a long list is handed over by
+ *      reference through an `@file` argument, which the engine expands.
+ *
+ * @param {string[]} files source files to analyse
+ * @param {string} format 'json' or 'text'
+ * @returns {{command: string, args: string[], useShell: boolean, cleanup: string|null}}
+ */
+function buildPrinciplesInvocation(files, format) {
+  const entry = findPrinciplesEntry();
+  const listChars = files.reduce((n, f) => n + String(f).length + 1, 0);
+
+  // Preferred shape: node.exe + tsx's own CLI, so no shim and no shell are involved.
+  const tsxCli = [findLocalTsxCli(), path.resolve(__dirname, '..', 'node_modules', 'tsx', 'dist', 'cli.mjs')].find(
+    (candidate) => candidate && fs.existsSync(candidate)
+  );
+
+  const command = tsxCli ? process.execPath : 'npx';
+  const prefix = tsxCli ? [tsxCli, entry] : ['-y', 'tsx', entry];
+
+  if (listChars <= ARGV_CHAR_BUDGET) {
+    return {
+      command,
+      args: [...prefix, '--files', files.join(' '), '--format', format],
+      useShell: false,
+      cleanup: null,
+    };
+  }
+
+  // By reference: one short argument instead of thousands of characters.
+  return buildByReferenceInvocation(prefix, files, format, command);
+}
+
+/**
+ * The `@file` form, used when the list is too long to inline.
+ *
+ * Split out for two reasons: it keeps `buildPrinciplesInvocation` inside the
+ * long-function limit, and it gives the temp-file IO a place to fail with a message
+ * that names the actual cause. An unwritable temp dir would otherwise surface as an
+ * unhandled throw from deep inside a spawn helper.
+ *
+ * @param {string[]} prefix executable-adjacent arguments (tsx cli + entry)
+ * @param {string[]} files source files to analyse
+ * @param {string} format 'json' or 'text'
+ * @param {string} command executable to run
+ * @returns {{command: string, args: string[], useShell: boolean, cleanup: string|null}}
+ */
+function buildByReferenceInvocation(prefix, files, format, command) {
+  const listFile = path.join(os.tmpdir(), `xp-gate-principles-${process.pid}-${Date.now()}.txt`);
+  try {
+    fs.writeFileSync(listFile, files.join('\n'));
+  } catch (err) {
+    // No list file means no run. Throw with the cause named, rather than letting the
+    // spawn fail later on a path that never existed.
+    throw new Error(`xp-gate principles: cannot write the file list to ${listFile}: ${err.message}`);
+  }
+  return {
+    command,
+    // The @ prefix is the engine's own "read the list from this file" form.
+    args: [...prefix, '--files', `@${listFile}`, '--format', format],
+    useShell: false,
+    cleanup: listFile,
+  };
+}
+
+/**
+ * How far up from the working directory to look for a project-local tsx.
+ *
+ * Enough for a hoisted monorepo `node_modules` (a package three or four levels deep),
+ * bounded so a filesystem with a cycle cannot loop.
+ */
+const TSDX_SEARCH_DEPTH = 8;
+
+/**
+ * Path to the project's own tsx CLI, or null.
+ *
+ * Walks up from the working directory so a monorepo's hoisted node_modules is found.
+ *
+ * @returns {string|null}
+ */
+function findLocalTsxCli() {
+  let dir = process.cwd();
+  for (let depth = 0; depth < TSDX_SEARCH_DEPTH; depth += 1) {
+    const candidate = path.join(dir, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Was this failure the tool not running, or the code having problems?
+ *
+ * #586's last request, and #596's finding in the shell toolchain: a failure to
+ * LAUNCH the checker was reported as "Failed to run principles check", which reads
+ * like a principles verdict. It is not one — nothing was analysed, so nothing was
+ * found. Collapsing the two sends the reader to fix source code when the problem is
+ * the environment.
+ *
+ * @param {{error?: Error, stdout?: string, stderr?: string, status?: number|null}} result
+ * @returns {'TOOLCHAIN'|'FINDING'}
+ */
+function classifyPrinciplesFailure(result) {
+  const error = result && result.error;
+  if (error && ['E2BIG', 'ENAMETOOLONG', 'ENOENT'].includes(error.code)) return 'TOOLCHAIN';
+  const text = `${(result && result.stdout) || ''} ${(result && result.stderr) || ''} ${(error && error.message) || ''}`;
+  if (/command line is too long|argument list too long|ENAMETOOLONG|E2BIG/i.test(text)) return 'TOOLCHAIN';
+  // Everything else is a genuine verdict from a run that happened. Do NOT widen this
+  // to "any non-zero exit": that would make Gate 4 unable to block on a real
+  // violation, which is worse than the defect being fixed.
+  return 'FINDING';
+}
+
 // Resolves repo root for the installed xp-gate npm package, or the development
 // checkout when running from source. Walks up looking for either:
 //   - src/principles/index.ts (this repo / dev mode)
@@ -145,12 +284,95 @@ function principles(args) {
     return Promise.resolve(1);
   }
 
-  const result = spawnSync('npx', ['-y', 'tsx', entry, '--files', files.join(' '), '--format', format], {
-    stdio: 'inherit',
-    shell: process.platform === 'win32',
-  });
+  // #586: build before spawning so the Windows command-line limit is a planning
+  // concern, not a runtime explosion. See buildPrinciplesInvocation().
+  return Promise.resolve(runPrinciplesPlan(buildPrinciplesInvocation(files, format)));
+}
+
+/**
+ * Execute a plan and return the exit code.
+ *
+ * Split from `principles` so that function stays inside the long-function limit, and
+ * so the launch-failure handling lives in one place with a comment saying what it is
+ * worth. `spawnSync` normally reports failures via `result.error`; a throw here means
+ * the call itself was malformed. Either way nothing was analysed, which is the fact
+ * worth stating rather than letting a stack trace imply the code was judged.
+ *
+ * @param {{command: string, args: string[], useShell: boolean, cleanup: string|null}} plan
+ * @returns {number} process exit code
+ */
+function runPrinciplesPlan(plan) {
+  let result;
+  try {
+    result = spawnSync(plan.command, plan.args, {
+      stdio: 'inherit',
+      // Never a shell: `shell: true` is what reached cmd.exe's 8191-character ceiling.
+      shell: plan.useShell,
+    });
+  } catch (err) {
+    removeListFile(plan.cleanup);
+    console.error(`[xp-gate principles] TOOLCHAIN: could not launch the checker: ${err.message}`);
+    console.error('  This is an environment problem, not a principles violation - nothing was analysed.');
+    return 1;
+  }
+
+  removeListFile(plan.cleanup);
+  return reportPrinciplesResult(result);
+}
+
+/**
+ * Delete the by-reference list file, if one was written.
+ *
+ * Best effort: a leftover temp file is not worth failing a gate over, but swallowing
+ * the error silently is how temp directories fill up unnoticed, so it is named.
+ *
+ * @param {string|null} listFile path to remove, or null
+ */
+function removeListFile(listFile) {
+  if (!listFile) return;
+  try {
+    fs.unlinkSync(listFile);
+  } catch (err) {
+    // Expected when the child already consumed/removed it; only surprising otherwise.
+    if (err.code !== 'ENOENT') {
+      console.error(`[xp-gate principles] could not remove ${listFile}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Turn a spawn result into the exit code to return, printing which kind of failure it
+ * was when there is one.
+ *
+ * Split out of `principles` to keep that function inside the long-function limit, and
+ * because this is the one place that decides whether the caller is looking at a code
+ * verdict or an environment problem — worth being able to point at directly.
+ *
+ * @param {{error?: Error, status?: number|null}} result spawnSync result
+ * @returns {number} process exit code
+ */
+function reportPrinciplesResult(result) {
+  if (!result.error && result.status !== null) return result.status;
 
-  return Promise.resolve(result.status === null ? 1 : result.status);
+  // #586's last request: say which kind of failure this is. "Failed to run principles
+  // check" read like a principles verdict on a run where nothing was analysed. Same
+  // confusion #596 fixed in the shell toolchain.
+  const kind = classifyPrinciplesFailure(result);
+  const detail = result.error ? result.error.message : 'no exit status';
+  if (kind === 'TOOLCHAIN') {
+    console.error(`[xp-gate principles] TOOLCHAIN: the checker could not be run: ${detail}`);
+    console.error('  This is an environment problem, not a principles violation - nothing was analysed.');
+  } else {
+    console.error(`[xp-gate principles] checker failed: ${detail}`);
+  }
+  return 1;
 }
 
-module.exports = { principles, expandTargets, collectSourceFiles };
+module.exports = {
+  principles,
+  expandTargets,
+  collectSourceFiles,
+  buildPrinciplesInvocation,
+  classifyPrinciplesFailure,
+  ARGV_CHAR_BUDGET,
+};