@boyingliu01/xp-gate 0.31.1 → 0.31.3

package/lib/__tests__/doctor-hook-signatures.test.js

@@ -0,0 +1,65 @@
+/**
+ * @test REQ-2 xp-gate doctor
+ * @intent Prove that the SHIPPED hook files still carry the exact signature
+ *         strings doctor uses to decide "this file is an xp-gate hook".
+ * @covers AC-05, AC-10
+ *
+ * Why this exists (#599): doctor identifies an installed hook by substring
+ * (`SIGNATURES`). The signatures are prose taken from each hook's own banner, so
+ * an innocuous editorial change to a banner line — replacing the em dash in
+ * `# Pre-push Hook — 8 gates:` with an ASCII hyphen, say — silently makes every
+ * installed pre-push hook unrecognisable. doctor then reports
+ * `Hooks: pre-push: Missing or not xp-gate` on a perfectly healthy install and
+ * `--fix` cannot clear it, because there is nothing wrong to fix.
+ *
+ * That is exactly what happened while rewriting the CRLF self-check in #546: the
+ * banner was retyped, the dash changed, and 9 doctor `--fix` cases went red with
+ * "expected 1 to be +0" — an assertion far from the actual cause. This test
+ * turns that class of failure into a one-line diagnostic naming the file and the
+ * missing string.
+ */
+const fs = require('fs');
+const path = require('path');
+
+describe('shipped hooks carry doctor SIGNATURES', () => {
+  const repoRoot = path.resolve(__dirname, '../../../..');
+  const { SIGNATURES } = require('../doctor');
+
+  // The hook files that this repository actually ships, in both mirrors.
+  const SHIPPED_HOOKS = [
+    { sig: 'pre-commit', file: 'githooks/pre-commit' },
+    { sig: 'pre-commit', file: 'src/npm-package/hooks/pre-commit' },
+    { sig: 'pre-push', file: 'githooks/pre-push' },
+    { sig: 'pre-push', file: 'src/npm-package/hooks/pre-push' },
+  ];
+
+  for (const { sig, file } of SHIPPED_HOOKS) {
+    it(`${file} contains SIGNATURES['${sig}']`, () => {
+      const abs = path.join(repoRoot, file);
+      expect(fs.existsSync(abs), `${file} does not exist`).toBe(true);
+      const content = fs.readFileSync(abs, 'utf8');
+
+      expect(
+        content.includes(SIGNATURES[sig]),
+        `${file} does not contain ${JSON.stringify(SIGNATURES[sig])}.\n`
+          + 'doctor identifies an xp-gate hook by this exact substring, so an '
+          + 'edit to the banner line silently makes every installed hook look '
+          + 'foreign. Restore the string, or update SIGNATURES in doctor.js in '
+          + 'the same commit (and keep the mirrors byte-identical).'
+      ).toBe(true);
+    });
+  }
+
+  it('the two hook mirrors are byte-identical', () => {
+    for (const name of ['pre-commit', 'pre-push']) {
+      const a = path.join(repoRoot, 'githooks', name);
+      const b = path.join(repoRoot, 'src/npm-package/hooks', name);
+      expect(fs.existsSync(a), a).toBe(true);
+      expect(fs.existsSync(b), b).toBe(true);
+      expect(
+        fs.readFileSync(a, 'utf8') === fs.readFileSync(b, 'utf8'),
+        `githooks/${name} and src/npm-package/hooks/${name} differ`
+      ).toBe(true);
+    }
+  });
+});

package/lib/__tests__/doctor-path-equivalence.test.js

@@ -50,10 +50,21 @@ describe('doctor path equivalence (#496)', () => {
     );
     // The two comparison sites that made the Windows call fail must both route
     // through the equivalence check rather than a byte comparison.
+    //
+    // #599: this used to match the literal `pathsEquivalent(hooksPath,
+    // GLOBAL_HOOKS_DIR)`. GLOBAL_HOOKS_DIR became a function when the path
+    // constants stopped being captured at require() time (they follow
+    // process.env.HOME now), so the call site reads `GLOBAL_HOOKS_DIR()`. A
+    // literal match made that a test failure instead of a grammar change.
+    // The invariant is "the hooksPath comparison goes through pathsEquivalent
+    // and passes the global hooks dir to it" — match that, not its spelling.
     const callSites = source
       .split('\n')
       .filter((line) => /hooksPath\s*!==\s*GLOBAL_HOOKS_DIR/.test(line));
     expect(callSites).toHaveProperty('length', 0);
-    expect(source).toMatch(/pathsEquivalent\(hooksPath, GLOBAL_HOOKS_DIR\)/);
+
+    expect(source).toMatch(
+      /pathsEquivalent\(\s*hooksPath\s*,\s*GLOBAL_HOOKS_DIR(?:\(\))?\s*\)/
+    );
   });
 });

package/lib/__tests__/doctor.test.js

@@ -951,7 +951,13 @@ describe('doctor', () => {
 
   // === --fix TUI registration ===
 
-  it('--fix: diagnoses TUI not registered then re-diagnoses after fix', async () => {
+  // 15s, not vitest's 5s default (#588). This case runs the full `doctor(['--fix'])`
+  // pipeline over a real temp install: it writes hooks, adapters and tui.json and
+  // re-diagnoses. Measured in isolation it takes ~3.8s, which is already 76% of the
+  // default budget — so under the full suite (where 200 files share the machine) it
+  // crossed 5s and failed with "Test timed out in 5000ms". The work is legitimate;
+  // the budget was simply too tight for it. Similar cases in this file take 2-4s.
+  it('--fix: diagnoses TUI not registered then re-diagnoses after fix', { timeout: 15000 }, async () => {
     setupLocalInstall();
     seedVersionCache();
     mockExecSuccess();

package/lib/__tests__/hook-health-path.test.js

@@ -72,7 +72,15 @@ describe('bash -n path handling', () => {
     );
   });
 
-  test('AC-566-02: a healthy hook under a native Windows path is parseable', () => {
+  // Windows-only by construction: the assertion below requires path.join to
+  // produce a backslash path (`C:\...`), which only happens on win32. On Linux
+  // path.join yields `/tmp/...` and the test fails with
+  //   expected '/tmp/hook-posix-XiaI9b/pre-push' to contain '\'
+  // That is a platform premise, not a regression (#586). Skipping keeps the gap
+  // visible in the run summary instead of painting CI red on every build.
+  const onWindows = process.platform === 'win32';
+
+  test.skipIf(!onWindows)('AC-566-02: a healthy hook under a native Windows path is parseable', () => {
     // The defect, end to end. The path MUST come from path.join, not from a
     // string literal: path.join produces the single-backslash form that Node
     // hands to spawnSync, and that is the form bash mangles. A hand-written

package/lib/__tests__/issue-566-sync-hooks-backup.test.js

@@ -0,0 +1,221 @@
+/**
+ * @test REQ-599
+ * @intent #566 was a hook that existed on exactly one machine and in no commit:
+ *         the installed `~/.config/xp-gate/hooks/pre-push` carried a local
+ *         `_score()` helper plus `gates_skipped` that no branch had ever held,
+ *         and `xp-gate doctor --sync-hooks` replaced it without a word. The repo
+ *         side then looked correct and the only copy of that work was gone.
+ *
+ *         doctor already REFUSES to overwrite a file whose content diverges, and
+ *         says "there is no automatic backup ... nothing records the previous
+ *         version". That refusal covers divergence; it does not cover the
+ *         legitimate overwrites that also destroy a previous version -- `--force`,
+ *         and files that differ only in whitespace. So the loss #566 describes
+ *         was still possible after the refusal landed.
+ *
+ *         These cases assert that every overwrite keeps the previous version,
+ *         in a `backups/` directory beside the installed hooks (not in the user's
+ *         work tree), timestamped so a later sync cannot destroy an earlier
+ *         backup.
+ * @covers AC-599-13
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DESCRIBE_ID = String(Math.random().toString(36).slice(2, 8));
+
+describe('doctor --sync-hooks keeps the previous version (#566)', () => {
+  let tmpHome;
+  let originalHome;
+  let originalUserProfile;
+
+  beforeAll(() => {
+    originalHome = process.env.HOME;
+    originalUserProfile = process.env.USERPROFILE;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), `xp-gate-566-home-${DESCRIBE_ID}-`));
+    process.env.HOME = tmpHome;
+    process.env.USERPROFILE = tmpHome;
+  });
+
+  afterAll(() => {
+    process.env.HOME = originalHome;
+    process.env.USERPROFILE = originalUserProfile;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  function loadDoctor() {
+    return require('../doctor');
+  }
+
+  /**
+   * Build a repo-like githooks/ plus an installed hooks dir.
+   * @param {{installedPrePush?: string}} [opts] content for the installed pre-push
+   */
+  function makeLayout(opts = {}) {
+    const root = fs.mkdtempSync(path.join(tmpHome, `layout-${DESCRIBE_ID}-`));
+    const repoRoot = path.join(root, 'repo');
+    const repoHooks = path.join(repoRoot, 'githooks');
+    const installedHooks = path.join(root, 'installed-hooks');
+    fs.mkdirSync(repoHooks, { recursive: true });
+    fs.mkdirSync(installedHooks, { recursive: true });
+
+    // The canonical hook carries the xp-gate signature doctor looks for.
+    fs.writeFileSync(
+      path.join(repoHooks, 'pre-push'),
+      '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# Pre-push Hook — 8 gates: Gate 10\necho canonical\n',
+    );
+    if (opts.installedPrePush !== undefined) {
+      fs.writeFileSync(path.join(installedHooks, 'pre-push'), opts.installedPrePush);
+    }
+    return { root, repoRoot, repoHooks, installedHooks };
+  }
+
+  it('AC-599-13: overwriting an existing hook keeps a copy of the previous version', () => {
+    const { repoHooks, installedHooks } = makeLayout({
+      installedPrePush: '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# GHOST LOCAL EDIT\n',
+    });
+
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    const result = syncGlobalHooksFromRepo({ repoHooks, installedHooks });
+
+    expect(result.synced).toContain('pre-push');
+    expect(result.backups.length).toBeGreaterThan(0);
+
+    const backup = result.backups.find((b) => path.basename(b).startsWith('pre-push.'));
+    expect(backup).toBeTruthy();
+    expect(fs.readFileSync(backup, 'utf8')).toContain('GHOST LOCAL EDIT');
+  });
+
+  it('AC-599-13: the backup lives beside the installed hooks, not in a work tree', () => {
+    const { repoRoot, repoHooks, installedHooks } = makeLayout({
+      installedPrePush: '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# local only\n',
+    });
+
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    syncGlobalHooksFromRepo({ repoHooks, installedHooks });
+
+    const backupsDir = path.join(installedHooks, 'backups');
+    expect(fs.existsSync(backupsDir)).toBe(true);
+    // Nothing was written into the repository: a backup must not become the
+    // user's problem to clean out of `git status`.
+    const repoEntries = fs.readdirSync(repoRoot).sort();
+    expect(repoEntries).toEqual(['githooks']);
+  });
+
+  it('AC-599-13: installing into an empty hooks dir creates no backup', () => {
+    // Nothing was overwritten, so there is nothing to keep -- a backup directory
+    // of empty files would be noise that trains the operator to ignore it.
+    const { repoHooks, installedHooks } = makeLayout();
+
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    const result = syncGlobalHooksFromRepo({ repoHooks, installedHooks });
+
+    expect(result.synced).toContain('pre-push');
+    expect(result.backups).toEqual([]);
+    expect(fs.existsSync(path.join(installedHooks, 'backups'))).toBe(false);
+  });
+
+  it('AC-599-13: two successive overwrites keep both previous versions', () => {
+    // A timestamped name is the point: the second sync must not destroy the
+    // backup the first sync made, or the work it was protecting is lost anyway.
+    const { repoHooks, installedHooks } = makeLayout({
+      installedPrePush: '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# EDIT ONE\n',
+    });
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    syncGlobalHooksFromRepo({ repoHooks, installedHooks });
+
+    fs.writeFileSync(path.join(installedHooks, 'pre-push'), '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# EDIT TWO\n');
+    const second = syncGlobalHooksFromRepo({ repoHooks, installedHooks });
+
+    const backupsDir = path.join(installedHooks, 'backups');
+    const files = fs.readdirSync(backupsDir).filter((f) => f.startsWith('pre-push.'));
+    expect(files.length).toBe(2);
+    const contents = files.map((f) => fs.readFileSync(path.join(backupsDir, f), 'utf8'));
+    expect(contents.some((c) => c.includes('EDIT ONE'))).toBe(true);
+    expect(contents.some((c) => c.includes('EDIT TWO'))).toBe(true);
+    expect(second.backups.length).toBeGreaterThan(0);
+  });
+
+  it('AC-599-13: an identical file is not re-copied and leaves no backup', () => {
+    const canonical = '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# Pre-push Hook — 8 gates: Gate 10\necho canonical\n';
+    const { repoHooks, installedHooks } = makeLayout({ installedPrePush: canonical });
+
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    const result = syncGlobalHooksFromRepo({ repoHooks, installedHooks });
+
+    expect(result.synced).not.toContain('pre-push');
+    expect(result.skipped).toContain('pre-push');
+    expect(result.backups).toEqual([]);
+  });
+
+  it('AC-599-13: shared lib/ libraries are backed up before being replaced too', () => {
+    // The lib/ channel overwrites unconditionally unless it refuses, so it is the
+    // channel most likely to erase machine-only hardening.
+    const { repoRoot, repoHooks, installedHooks } = makeLayout();
+    fs.mkdirSync(path.join(repoHooks, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(repoHooks, 'lib', 'coverage-total.sh'), 'echo canonical-lib\n');
+    fs.mkdirSync(path.join(installedHooks, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(installedHooks, 'lib', 'coverage-total.sh'), 'echo LOCAL-LIB-EDIT\n');
+
+    // Force, because otherwise the divergence guard refuses before the overwrite.
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+    const result = syncGlobalHooksFromRepo({ repoRoot, repoHooks, installedHooks, force: true });
+
+    const backup = result.backups.find((b) => path.basename(b).startsWith('coverage-total.sh.'));
+    expect(backup).toBeTruthy();
+    expect(fs.readFileSync(backup, 'utf8')).toContain('LOCAL-LIB-EDIT');
+  });
+
+  it('AC-599-13: two syncs inside the same millisecond both keep their version', () => {
+    // The CI failure that motivated this case: "two successive overwrites keep
+    // both previous versions" passed locally and failed on a fast runner with
+    // `expected 1 to be 2`. The stamp has millisecond resolution, so when two
+    // syncs land in the SAME millisecond they compute the SAME backup name and
+    // the second copy silently destroys the first. Local runs usually straddled
+    // a millisecond boundary and never saw it.
+    //
+    // Pin Date so the collision is guaranteed rather than hoped for: asserting a
+    // bug that only appears under a timing race is how the suite went green while
+    // the defect shipped.
+    const { repoHooks, installedHooks } = makeLayout({
+      installedPrePush: '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# SAME-MS-ONE\n',
+    });
+    const { syncGlobalHooksFromRepo } = loadDoctor();
+
+    // Freeze ONLY the clock the stamp reads. Nothing else is replaced: an earlier
+    // draft overrode Date.prototype.toISOString, which made the backup helper
+    // recurse into itself and threw "Maximum call stack size exceeded" -- the
+    // case then appeared to fail for a reason that had nothing to do with backups.
+    const RealDate = Date;
+    const frozen = 1767225600123; // any instant; only that it never advances
+    global.Date = class extends RealDate {
+      constructor(...args) {
+        if (args.length === 0) super(frozen);
+        else super(...args);
+      }
+      static now() {
+        return frozen;
+      }
+    };
+    try {
+      syncGlobalHooksFromRepo({ repoHooks, installedHooks, force: true });
+
+      fs.writeFileSync(
+        path.join(installedHooks, 'pre-push'),
+        '#!/usr/bin/env bash\n# XP-Gate Pre-Push Hook\n# SAME-MS-TWO\n',
+      );
+      syncGlobalHooksFromRepo({ repoHooks, installedHooks, force: true });
+    } finally {
+      global.Date = RealDate;
+    }
+
+    const backupsDir = path.join(installedHooks, 'backups');
+    const files = fs.readdirSync(backupsDir).filter((f) => f.startsWith('pre-push.'));
+    expect(files.length).toBe(2);
+
+    const contents = files.map((f) => fs.readFileSync(path.join(backupsDir, f), 'utf8'));
+    expect(contents.some((c) => c.includes('SAME-MS-ONE'))).toBe(true);
+    expect(contents.some((c) => c.includes('SAME-MS-TWO'))).toBe(true);
+  });
+});

package/lib/__tests__/issue-583-hook-deploy-log.test.js

@@ -0,0 +1,121 @@
+/**
+ * @test REQ-604
+ * @intent A deploy that overwrites an installed hook must leave a record of what
+ *         it replaced and which version did it.
+ *
+ *         #583: `xp-gate doctor --sync-hooks` overwrote `~/.config/xp-gate/hooks/
+ *         pre-commit` three times in one day, each time silently. A downstream
+ *         that had hardened its hooks (and kept the vendored copy in sync, with a
+ *         consistency test guarding it) discovered it only by running its own
+ *         SHA256 comparison. The consequences were not cosmetic: one overwrite
+ *         reverted a fixed fail-open in Gate 5's coverage arm, so commits started
+ *         passing on unmeasurable coverage again — a defect that had already been
+ *         filed, fixed and tested.
+ *
+ *         #566 added the backup, which makes the damaged file recoverable. It
+ *         does not answer the question the downstream actually has: "was my patch
+ *         eaten, and by which version?" A directory of timestamped `.bak` files
+ *         can be read, but only by someone who already suspects an overwrite.
+ *
+ *         So the invariant here is narrow and provable without a network, a
+ *         registry, or a real install: when sync-hooks overwrites file X, one
+ *         line is appended to a deploy log naming X, the version that did it, and
+ *         the backup that holds the previous content. Nothing more.
+ *
+ *         Deliberately NOT in scope (the issue's option 2): refusing to overwrite
+ *         a locally-modified hook without `--force`. That changes the deploy
+ *         contract for every consumer and needs a product decision, not a bug fix.
+ * @covers AC-604-01, AC-604-02, AC-604-03
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { syncGlobalHooksFromRepo } = require('../doctor.js');
+
+function writeHook(dir, name, body) {
+  const p = path.join(dir, name);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, body, { mode: 0o755 });
+  } catch (err) {
+    // A fixture that cannot create its file must fail the case loudly, not leave
+    // a partially-built directory for the assertions to interpret (#583).
+    throw new Error(`fixture setup failed writing ${p}: ${err.message}`);
+  }
+  return p;
+}
+
+describe('REQ-604: sync-hooks leaves a deploy record', () => {
+  let tmp;
+  let repoHooks;
+  let installedHooks;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-deploy-log-'));
+    repoHooks = path.join(tmp, 'repo', 'githooks');
+    installedHooks = path.join(tmp, 'installed', 'hooks');
+    fs.mkdirSync(installedHooks, { recursive: true });
+    // The banner line is the signature doctor uses to recognise an xp-gate hook.
+    writeHook(repoHooks, 'pre-commit', '#!/bin/bash\n# XP-GATE QUALITY GATES v0.31.1.0\necho new\n');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('AC-604-01: an overwrite appends one line naming the file, the version and the backup', () => {
+    // The downstream's hardened copy: different from upstream, so it IS replaced.
+    writeHook(installedHooks, 'pre-commit', '#!/bin/bash\n# XP-GATE QUALITY GATES v0.30.0.0\n# downstream hardening\necho old\n');
+
+    const result = syncGlobalHooksFromRepo({ repoHooks, installedHooks, version: '0.31.1.0' });
+
+    expect(result.errors).toEqual([]);
+    expect(result.synced).toContain('pre-commit');
+
+    const logPath = path.join(installedHooks, 'deploy.log');
+    expect(fs.existsSync(logPath)).toBe(true);
+
+    const lines = fs.readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
+    const entry = lines.find((l) => l.includes('pre-commit'));
+    expect(entry, `deploy log must name pre-commit, got:\n${lines.join('\n')}`).toBeTruthy();
+
+    // The three facts the downstream needs, all in that one line: which file,
+    // which version replaced it, and where the previous content went.
+    expect(entry).toMatch(/pre-commit/);
+    expect(entry).toMatch(/0\.31\.1\.0/);
+    expect(entry, `names the backup holding the old content, got: ${entry}`).toMatch(/\.bak/);
+  });
+
+  it('AC-604-02: an unchanged file produces no deploy entry', () => {
+    // Identical content: sync skips it, so there is nothing to report. A log that
+    // records non-events is noise, and noise is what makes real overwrites
+    // invisible.
+    writeHook(installedHooks, 'pre-commit', '#!/bin/bash\n# XP-GATE QUALITY GATES v0.31.1.0\necho new\n');
+
+    const result = syncGlobalHooksFromRepo({ repoHooks, installedHooks, version: '0.31.1.0' });
+    expect(result.skipped).toContain('pre-commit');
+
+    const logPath = path.join(installedHooks, 'deploy.log');
+    if (fs.existsSync(logPath)) {
+      const content = fs.readFileSync(logPath, 'utf8');
+      expect(content).not.toContain('pre-commit');
+    }
+  });
+
+  it('AC-604-03: repeated overwrites accumulate rather than replacing history', () => {
+    // The whole point of the log is answering "how many times, and when" — one
+    // day saw three overwrites. Overwriting the log each run would destroy
+    // exactly the evidence the downstream needs.
+    writeHook(installedHooks, 'pre-commit', '#!/bin/bash\n# XP-GATE QUALITY GATES v0.30.0.0\necho v1\n');
+    syncGlobalHooksFromRepo({ repoHooks, installedHooks, version: '0.31.1.0' });
+
+    writeHook(installedHooks, 'pre-commit', '#!/bin/bash\n# XP-GATE QUALITY GATES v0.30.0.0\necho v1-patched-by-downstream\n');
+    syncGlobalHooksFromRepo({ repoHooks, installedHooks, version: '0.31.1.0' });
+
+    const logPath = path.join(installedHooks, 'deploy.log');
+    const lines = fs.readFileSync(logPath, 'utf8').trim().split('\n').filter((l) => l.includes('pre-commit'));
+    expect(lines).toHaveLength(2);
+  });
+});

package/lib/__tests__/issue-586-principles-cmdline.test.js

@@ -0,0 +1,183 @@
+/**
+ * @test REQ-613
+ * @intent `xp-gate check . --all` could never run Gate 4 on Windows:
+ *
+ *             Failed to run principles check: The command line is too long.
+ *
+ *         Two causes added together in `lib/principles.js`:
+ *
+ *           1. `shell: process.platform === 'win32'` routes through cmd.exe, whose
+ *              command line is capped at 8191 characters (CreateProcess allows
+ *              32767).
+ *           2. every path is joined into ONE argv element — `files.join(' ')` — so
+ *              the whole file list becomes part of that command line. Measured in
+ *              the issue: 135 Java files came to 12944 characters before the
+ *              `npx -y tsx <entry> --files --format json` prefix was added.
+ *
+ *         This is not "the occasional huge project"; it is a mid-sized project on
+ *         Windows, every time.
+ *
+ *         Splitting the argv was explicitly ruled out in the issue and the reasoning
+ *         holds: the bottleneck is total character count, not quoting, and `npx` on
+ *         Windows still needs `shell: true` to be found at all.
+ *
+ *         The other half of the issue is what the failure is CALLED. "Failed to run
+ *         principles check" reads like a principles violation. It is not — the tool
+ *         never ran. #596 fixed the same confusion in the shell toolchain
+ *         (`classify_tool_failure`); this pins it for the JS side.
+ * @covers AC-613-01, AC-613-02, AC-613-03
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const principles = require('../principles.js');
+
+// cmd.exe's command-line ceiling. Named rather than repeated: it is the number the
+// whole issue is about, and a bare 8191 in several places reads as unrelated facts.
+const CMD_EXE_LIMIT = 8191;
+
+// The measured case from the issue: 135 Java files => 12944 characters, which blocked
+// every `--all` run on Windows.
+const ISSUE_FILE_COUNT = 135;
+
+// Comfortably past the limit, used where the exact count does not matter — only that
+// the list is too long to inline.
+const LARGE_FILE_COUNT = 400;
+
+/** A path-only string of roughly `len` characters (the join() payload). */
+function longFileList(count) {
+  // Paths must be long enough that `count` of them realistically exceeds the
+  // Windows limit; the issue's own measurement was ~90 chars per path.
+  return Array.from(
+    { length: count },
+    (_, i) =>
+      `src/main/java/com/example/deeply/nested/module${i}/service/implementation/File${i}ImplementationImpl.java`
+  );
+}
+
+describe('REQ-613: Gate 4 must not blow the Windows command-line limit', () => {
+  it('AC-613-01: the command line for a mid-sized Java project stays under cmd.exe\\u2019s character limit', () => {
+    // The measured case from the issue: 135 files, 12944 characters, blocked.
+    const files = longFileList(ISSUE_FILE_COUNT);
+    const joined = files.join(' ');
+    expect(joined.length).toBeGreaterThan(CMD_EXE_LIMIT);
+
+    const plan = principles.buildPrinciplesInvocation(files, 'json');
+    // The contract: whatever is handed to the OS is a single argument list, and the
+    // total of that list's characters is what must fit. A plan that still carries the
+    // whole list in one argument has not solved anything.
+    const longest = Math.max(...plan.args.map((a) => String(a).length));
+    expect(longest, `longest single argument is ${longest} chars`).toBeLessThan(CMD_EXE_LIMIT);
+  });
+
+  it('AC-613-01: a large file list is passed by reference, not by value', () => {
+    // The fix that the issue recommends first: use the project's own tsx through
+    // node.exe (an absolute path, no shim, no shell) and keep the argv bounded. If a
+    // future change puts every path back on the command line, this fails.
+    const files = longFileList(LARGE_FILE_COUNT);
+    const plan = principles.buildPrinciplesInvocation(files, 'json');
+
+    const argvChars = plan.args.reduce((n, a) => n + String(a).length + 1, 0);
+    expect(argvChars, `argv carries ${argvChars} chars`).toBeLessThan(CMD_EXE_LIMIT);
+  });
+
+  it('AC-613-02: the invocation never opts into a shell on any platform', () => {
+    // `shell: true` is what routes through cmd.exe and its 8191 limit. It must not be
+    // requested at all: the correct target is node.exe, which needs no shim.
+    const plan = principles.buildPrinciplesInvocation(['a.ts'], 'json');
+    expect(plan.useShell).toBe(false);
+  });
+
+  it('AC-613-02: the plan names an executable that needs no shell shim', () => {
+    // Either node.exe (preferred — absolute, no shim) or a resolved tool path. A bare
+    // 'npx' string would force the caller back to shell:true on Windows.
+    const plan = principles.buildPrinciplesInvocation(['a.ts'], 'json');
+    expect(plan.command.length).toBeGreaterThan(0);
+    expect(plan.command).not.toBe('npx');
+  });
+
+  it('AC-613-03: a command-line-too-long failure is classified as a toolchain problem, not a finding', () => {
+    // The message used to be "Failed to run principles check", which reads as a code
+    // verdict. It never was one.
+    expect(principles.classifyPrinciplesFailure({ error: new Error('E2BIG') })).toBe('TOOLCHAIN');
+    expect(principles.classifyPrinciplesFailure({ error: new Error('spawn ENAMETOOLONG') })).toBe('TOOLCHAIN');
+    expect(
+      principles.classifyPrinciplesFailure({
+        stdout: 'The command line is too long.',
+        status: 1,
+      })
+    ).toBe('TOOLCHAIN');
+  });
+
+  it('AC-613-03: a real principles violation is still classified as a finding', () => {
+    // The control. If everything classified as TOOLCHAIN, Gate 4 could never block on
+    // an actual violation again — worse than the bug being fixed.
+    expect(principles.classifyPrinciplesFailure({ stdout: '1 violations total', status: 1 })).toBe('FINDING');
+    expect(principles.classifyPrinciplesFailure({ status: 1 })).toBe('FINDING');
+  });
+
+  it('AC-613-01: a file list that fits is still passed directly', () => {
+    // Small lists must not be needlessly diverted; the direct path is well tested and
+    // has different failure semantics.
+    const plan = principles.buildPrinciplesInvocation(['src/a.ts', 'src/b.ts'], 'json');
+    const flat = plan.args.join(' ');
+    expect(flat).toContain('src/a.ts');
+    expect(flat).toContain('src/b.ts');
+  });
+
+  it('AC-613-01: the by-reference handoff writes the list somewhere the child can read', () => {
+    // Sanity on the mechanism itself: if the plan says "by reference", the reference
+    // has to be a real file path the child will be given, not a placeholder.
+    const files = longFileList(LARGE_FILE_COUNT);
+    const plan = principles.buildPrinciplesInvocation(files, 'json');
+    const refArg = plan.args.find((a) => String(a).startsWith('@'));
+    expect(refArg, 'no @file argument in the plan').toBeTruthy();
+    const refPath = refArg.slice(1);
+    expect(path.isAbsolute(refPath) || refPath.includes('tmp') || refPath.includes('TEMP') || refPath.toLowerCase().includes('temp')).toBe(true);
+    // And the file must not be left behind by merely planning.
+    expect(fs.existsSync(refPath) && plan.cleanup === false).toBe(false);
+  });
+
+  it('AC-613-02: the WIRE test \u2014 the call site actually uses the plan it builds', () => {
+    // This case exists because the first version of this suite had a hole: every
+    // other case asserts on `buildPrinciplesInvocation`'s OUTPUT, and reverting the
+    // call site to the old `spawnSync('npx', [...files.join(' ') ...], { shell: true })`
+    // left all 8 green. A perfectly correct planner that nobody consults.
+    //
+    // Intercepting child_process.spawnSync does NOT work here: principles.js
+    // destructures `{ spawnSync }` at load time, so replacing the property afterwards
+    // never reaches the bound local. (I tried that first and the case failed with
+    // "spawnSync was never called" — which is itself a useful demonstration that an
+    // indirect assertion can fail for a reason unrelated to the defect.)
+    //
+    // So this asserts the wiring structurally, plus the one property that is cheap to
+    // check at runtime: the module must expose the planner, meaning the call site has
+    // something to consume.
+    const source = fs.readFileSync(path.join(__dirname, '..', 'principles.js'), 'utf8');
+
+    // The shell:true on the call site, verbatim.
+    expect(source, 'the shell:true spawn is back at the call site').not.toContain(
+      "shell: process.platform === 'win32'"
+    );
+
+    // The wiring: spawnSync must be fed the plan, and the plan must control the shell.
+    expect(source).toContain('spawnSync(plan.command, plan.args');
+    expect(source).toContain('shell: plan.useShell');
+
+    // The planner bounds the list; the join() is still allowed for SHORT lists inside
+    // buildPrinciplesInvocation (that is the correct path for small inputs), but it
+    // must never appear in the spawnSync argument position any more.
+    const spawnIdx = source.indexOf('spawnSync(plan.command, plan.args');
+    const joinAfterSpawn = source.indexOf('files.join(', spawnIdx);
+    expect(joinAfterSpawn, 'the spawn call still joins the whole list inline').toBe(-1);
+
+    // And the planner must really exist and be exported, so the call site cannot be
+    // referencing a name that only looks right.
+    expect(typeof principles.buildPrinciplesInvocation).toBe('function');
+  });
+});
+
+// Keep the imports referenced so linting does not flag them when the module grows.
+void os;