testguard-cli 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.2] - 2026-10-02
+
+Automated weekly release — everything merged since `v0.18.1`.
+
+### Changed
+
+- perf: use one fresh process for single-entry native probes (#200)
+- perf: focus gate annotation and claim selection defenders (#198)
+- chore(homebrew): sha256 for v0.18.1 (#197)
+
+
+### Performance
+
+- Eligible single-file native Node confirmations use one fresh process, avoiding a second process launch while preserving real CLI entry identity, ordinary tests beside `.only`, import and late-error refusals, budgets, and process cleanup. Discovery, multiple files and older runtimes keep the existing isolated route.
+- Focus gate coverage, repeated claim selection and annotation ID bounds defenders on their relevant checks, retaining all original assertions in the mandatory acceptance suite and all fault recipes.
+
+## [0.18.1] - 2026-10-01
+
+Automated weekly release — everything merged since `v0.18.0`.
+
+### Changed
+
+- test: consolidate native runtime acceptance checks
+- perf: isolate native admission mutation defenders
+- perf: size bounded report buffers to observed files
+- chore(homebrew): sha256 for v0.18.0 (#194)
+
+
+### Changed
+
+- Runner report and discovery-config reads reserve memory for the observed
+  file size instead of the maximum allowed size, retaining the hard byte
+  ceiling and checking file growth before parsing.
+- Native-runner admission self-probes use focused defenders, preserving the
+  fault recipes and full runner acceptance coverage while avoiding unrelated
+  timeout and process-cleanup checks for each admission confirmation.
+
 ## [0.18.0] - 2026-10-01
 
 Automated weekly release — everything merged since `v0.17.0`.

package/README.md

@@ -127,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.18.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.18.2` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.18.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.18.2/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -785,12 +785,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.18.0
+- uses: raccioly/testguard@v0.18.2
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.18.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.18.2/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -321,7 +321,21 @@ Rules that follow from the table:
    supports plain JavaScript under Node's default collection, without custom
    loaders, `NODE_OPTIONS` or `NODE_PATH`; it is never selected by `auto`.
    Each confirmation uses fresh, isolated Node test processes under the
-   existing worker ceiling. Reports count executed test results, not individual
+   existing worker ceiling. On Node22.8+, Node24 and Node26, a single selected
+   entry can run inside one fresh process through a reporting preload and the
+   public in-process API; Node evaluates the actual CLI entry, preserving
+   CommonJS `require.main`, ESM `import.meta.main` and argv identity. This process
+   serves no other entry or confirmation. Discovery, multiple
+   entries and other runtime families retain the isolated controller/worker
+   route. Single-entry execution preserves ordinary tests beside `.only`,
+   records entry provenance before evaluation, monitors entry-load failures
+   after test registration, and publishes only at process exit when no
+   out-of-test failure or incompatible exit code occurred. A complete stream
+   cannot turn a later exception, rejection or retained-handle timeout into a
+   kill. Report and entry destinations are captured before project evaluation;
+   project environment edits cannot redirect these owned outputs. Both routes
+   bind their implementation to native discovery identity.
+   Reports count executed test results, not individual
    assertion calls: suite and file-container summaries are not extra tests,
    and skipped/TODO results cannot establish a green defender by themselves.
    A test-body failure counts as a rejection; a load error, hook failure,

package/src/probe/runners/discovery.mjs

@@ -130,12 +130,21 @@ const readBoundedFile = (path, maxBytes, label, { optional = false } = {}) => {
     const stat = fstatSync(descriptor);
     if (!stat.isFile()) throw new DiscoveryError(`${label} is not a regular file`);
     if (stat.size > maxBytes) throw new DiscoveryError(`${label} exceeded ${maxBytes} bytes`);
-    const bytes = Buffer.alloc(maxBytes + 1);
+    // Reserve the observed file size, not the allowance for the largest report.
+    // The extra byte detects growth; a full buffer grows within the same hard
+    // ceiling so a concurrently appended suffix can never be silently dropped.
+    let bytes = Buffer.alloc(stat.size + 1);
     let length = 0;
     while (length < bytes.length) {
       const read = readSync(descriptor, bytes, length, bytes.length - length, null);
       if (read === 0) break;
       length += read;
+      if (length > maxBytes) throw new DiscoveryError(`${label} exceeded ${maxBytes} bytes`);
+      if (length === bytes.length) {
+        const grown = Buffer.alloc(Math.min(maxBytes + 1, Math.max(4096, bytes.length * 2)));
+        bytes.copy(grown, 0, 0, length);
+        bytes = grown;
+      }
     }
     if (length > maxBytes) throw new DiscoveryError(`${label} exceeded ${maxBytes} bytes`);
     return bytes.subarray(0, length);

package/src/probe/runners/node/direct.mjs

@@ -0,0 +1,55 @@
+import { appendFileSync, writeFileSync } from 'node:fs';
+import { readBoundedJsonFile } from '../discovery.mjs';
+import { createReport } from './report.mjs';
+
+// This preload returns before Node evaluates its actual CLI entry. Running the
+// file as the entry preserves require.main, import.meta.main and process.argv.
+const file = process.argv[1];
+if (!file) throw new Error('direct node-test requires an entry');
+const entriesFile = process.env.TESTGUARD_NODE_ENTRIES;
+const reportFile = process.env.TESTGUARD_NODE_REPORT;
+const diagnosticFile = `${entriesFile}.error`;
+const report = createReport({ projectDir: process.cwd(), version: process.versions.node });
+let document;
+let outsideFailure = false;
+process.on('uncaughtExceptionMonitor', (error) => {
+  outsideFailure = true;
+  writeFileSync(diagnosticFile, JSON.stringify({ name: String(error?.name ?? 'Error').slice(0, 100), message: String(error?.message ?? error).slice(0, 1000) }), { mode: 0o600 });
+});
+process.on('unhandledRejection', () => { outsideFailure = true; process.exitCode = 1; });
+// A complete stream is insufficient: a retained timer can fail or hang later.
+// Publish only at process exit, after CLI loading and out-of-test failures settle.
+process.on('exit', (code) => {
+  if (!document || outsideFailure || code !== (document.failed ? 1 : 0)) return;
+  const text = JSON.stringify(document);
+  if (Buffer.byteLength(text) > 16 * 1024 * 1024) return;
+  writeFileSync(reportFile, text, { mode: 0o600 });
+});
+const receipt = JSON.stringify({ file, pid: process.pid, version: process.versions.node });
+if (Buffer.byteLength(receipt) > 8192) throw new Error('node-test entry receipt exceeded its byte bound');
+appendFileSync(entriesFile, `${receipt},`);
+
+// Node24+ otherwise enables implicit .only filtering for isolation:none,
+// even with run({only:false}). Preserve isolated-worker filtering semantics.
+process.env.NODE_TEST_CONTEXT = 'child-v8';
+const { run } = await import('node:test');
+const stream = run({ files: [], isolation: 'none', only: false, setup: () => new Promise((resolve) => {
+  // Keep the public root open until Node has loaded the real CLI entry. An
+  // awaited stream here would block entry evaluation; the drain runs below.
+  process.once('beforeExit', resolve);
+}) });
+(async () => {
+  try {
+    for await (const event of stream) report.accept(event);
+    appendFileSync(entriesFile, 'null]}');
+    const entries = readBoundedJsonFile(entriesFile).entries;
+    if (!Array.isArray(entries) || entries.length !== 2 || entries.pop() !== null) throw new Error('incomplete direct node-test entry receipt');
+    document = report.finish(entries);
+    if (document.failed) process.exitCode = 1;
+  } catch (error) {
+    outsideFailure = true;
+    stream.destroy();
+    process.stderr.write(`node-test reporter failed: ${String(error.message ?? error).slice(0, 1000)}\n`);
+    process.exitCode = 1;
+  }
+})();

package/src/probe/runners/node/entry.mjs

@@ -9,3 +9,9 @@ if (process.env.NODE_TEST_CONTEXT?.startsWith('child')) {
   }
   appendFileSync(process.env.TESTGUARD_NODE_ENTRIES, `${receipt},`);
 }
+
+// A fresh single-entry process initializes reporting before its real CLI
+// entry. Inherited child context must not bootstrap a second reporter in a fork.
+if (process.env.TESTGUARD_NODE_DIRECT === '1' && process.env.NODE_TEST_CONTEXT === '') {
+  await import('./direct.mjs');
+}

package/src/probe/runners/node-test.mjs

@@ -1,10 +1,10 @@
-import { closeSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { runProcess } from './shared.mjs';
-import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, runDiscoveryProcess } from './discovery.mjs';
+import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, readBoundedJsonFile, runDiscoveryProcess } from './discovery.mjs';
 
 export const name = 'node-test';
 export const testGlobs = []; // Native collection is authoritative; never guess from globs.
@@ -12,6 +12,11 @@ const HERE = join(dirname(fileURLToPath(import.meta.url)), 'node');
 const RUNNER = join(HERE, 'runner.mjs');
 const ENTRY = join(HERE, 'entry.mjs');
 const VERSION = process.versions.node;
+/** Admit only maintained runtime families with the in-process public API. */
+export function supportsSingleProcess(version = VERSION) {
+  const [major, minor] = version.split('.').map(Number);
+  return major === 22 && minor >= 8 || major === 24 || major === 26;
+}
 const strategyHash = () => {
   const digest = createHash('sha256');
   const descriptor = openSync(process.execPath, 'r');
@@ -20,7 +25,7 @@ const strategyHash = () => {
     let length;
     while ((length = readSync(descriptor, bytes, 0, bytes.length, null)) > 0) digest.update(bytes.subarray(0, length));
   } finally { closeSync(descriptor); }
-  for (const file of [fileURLToPath(import.meta.url), ...['runner.mjs', 'entry.mjs', 'report.mjs'].map((file) => join(HERE, file)), ...['shared.mjs', 'discovery.mjs', 'lifecycle.mjs'].map((file) => join(HERE, '..', file))]) digest.update(readFileSync(file));
+  for (const file of [fileURLToPath(import.meta.url), ...['runner.mjs', 'direct.mjs', 'entry.mjs', 'report.mjs'].map((file) => join(HERE, file)), ...['shared.mjs', 'discovery.mjs', 'lifecycle.mjs'].map((file) => join(HERE, '..', file))]) digest.update(readFileSync(file));
   return digest.digest('hex');
 };
 const admissionError = () => Number(VERSION.split('.')[0]) < 20 ? 'node-test requires Node20 or newer'
@@ -37,15 +42,16 @@ const receipts = () => {
   writeFileSync(file, '{"entries":[', { mode: 0o600 });
   return { dir, file };
 };
-const environment = (file, collect, workers) => ({
+const environment = (file, collect, workers, direct = false) => ({
   TESTGUARD_NODE_ENTRIES: file,
   TESTGUARD_NODE_COLLECT: collect ? '1' : '0',
   TESTGUARD_NODE_WORKERS: String(workers),
   TESTGUARD_NODE_REPORT: '{out}',
+  TESTGUARD_NODE_DIRECT: direct ? '1' : '0',
   NODE_TEST_CONTEXT: '',
   NODE_DISABLE_COMPILE_CACHE: '1',
 });
-export const argvFor = (projectDir, files) => [process.execPath, `--import=${ENTRY}`, RUNNER, ...files.map((file) => resolve(realpathSync(projectDir), file))];
+export const argvFor = (projectDir, files, { direct = false } = {}) => [process.execPath, `--import=${ENTRY}`, ...(!direct ? [RUNNER] : []), ...files.map((file) => resolve(realpathSync(projectDir), file))];
 
 /** Reject unsupported/incomplete envelopes before deriving any verdict inputs. */
 export function validateReport(report) {
@@ -120,11 +126,19 @@ export async function run(opts) {
   const files = normalizeDiscoveredFiles(opts.projectDir, opts.files);
   const spool = receipts();
   try {
-    return await runProcess({ ...opts, files, cleanupOnClose: true, env: environment(spool.file, false, opts.serial ? 1 : opts.workers ?? 1), argv: (selected) => argvFor(opts.projectDir, selected), parse: (report, durationMs) => {
+    const direct = files.length === 1 && supportsSingleProcess();
+    const result = await runProcess({ ...opts, files, cleanupOnClose: true, env: environment(spool.file, false, opts.serial ? 1 : opts.workers ?? 1, direct), argv: (selected) => argvFor(opts.projectDir, selected, { direct }), parse: (report, durationMs) => {
       validateReport(report);
       const entries = normalizeDiscoveredFiles(opts.projectDir, report.entries.map((entry) => entry.file));
       if (entries.length !== report.entries.length || JSON.stringify(entries) !== JSON.stringify(files)) throw new DiscoveryError('node-test did not execute every selected entry exactly');
       return parseReport(report, durationMs);
     } });
+    // CLI loading can fail before a complete stream exists. Keep the actual
+    // bounded exception identity rather than Node's trailing version banner.
+    if (result.run.outcome === 'error' && existsSync(`${spool.file}.error`)) {
+      const diagnostic = readBoundedJsonFile(`${spool.file}.error`, 8192);
+      if (typeof diagnostic.name === 'string' && diagnostic.name.length <= 100 && typeof diagnostic.message === 'string' && diagnostic.message.length <= 1000) result.loadMessage = `${diagnostic.name}: ${diagnostic.message}`;
+    }
+    return result;
   } finally { rmSync(spool.dir, { recursive: true, force: true }); }
 }