testguard-cli 0.14.2__tar.gz → 0.15.1__tar.gz

testguard_cli-0.15.1/.github/scripts/install-smoke.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Prove the package works AS INSTALLED, not as checked out: pack it, install
+ * the tarball into a scratch project with production dependencies only, and
+ * run the CLI from there. This is the gate that would have caught 0.1.0,
+ * which shipped with its schema validator's dependency declared as a
+ * devDependency and crashed on startup for every npm/npx/pip/brew user.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, cpSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const root = resolve(process.argv[1], '..', '..', '..');
+const run = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] });
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+const scratch = mkdtempSync(join(tmpdir(), 'testguard-install-smoke-'));
+try {
+  const packDir = join(scratch, 'pack');
+  mkdirSync(packDir);
+  run(npm, ['pack', '--pack-destination', packDir, '--ignore-scripts'], root);
+  const tgz = join(packDir, readdirSync(packDir).find((f) => f.endsWith('.tgz')));
+
+  const consumer = join(scratch, 'consumer');
+  cpSync(join(root, 'fixtures', 'known-answer'), consumer, { recursive: true, filter: (s) => !/node_modules|\.flake-counter|\.testguard/.test(s) });
+  run(npm, ['init', '-y'], consumer);
+  run(npm, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', tgz], consumer);
+
+  const bin = join(consumer, 'node_modules', '.bin', process.platform === 'win32' ? 'testguard.cmd' : 'testguard');
+  const version = run(bin, ['--version'], consumer).trim();
+  const emptyProject = join(scratch, 'empty-adoption');
+  mkdirSync(emptyProject);
+  writeFileSync(join(emptyProject, 'testguard.claims.json'), JSON.stringify({ schemaVersion: 1, claims: [] }));
+  const emptyStatus = JSON.parse(run(bin, ['probe', emptyProject, '--allow-empty', '--json'], consumer));
+  if (emptyStatus.state !== 'no-claims' || emptyStatus.run || existsSync(join(emptyProject, '.testguard', 'evidence.json'))) throw new Error('installed empty-adoption probe invented verification evidence');
+  const replayHelp = run(bin, ['replay', '--help'], consumer);
+  if (!replayHelp.includes('--since') || replayHelp.includes('--node-modules')) throw new Error('installed command help is not command-specific');
+  writeFileSync(join(emptyProject, 'vite.config.mjs'), "export default { base: '/', plugins: [{ configureServer(s) { s.middlewares.use('/__rooms', () => {}); const parts = '/__room'.split('/'); } }] };\n");
+  const installedDiscovery = join(consumer, 'node_modules', 'testguard-cli', 'src', 'probe', 'runners', 'discovery.mjs');
+  run(process.execPath, ['--input-type=module', '-e',
+    "import { pathToFileURL } from 'node:url'; const { hashDiscoveryConfigs } = await import(pathToFileURL(process.argv[1])); hashDiscoveryConfigs(process.argv[2], ['vite.config.mjs']);",
+    installedDiscovery, emptyProject,
+  ], consumer);
+  const installedRunner = join(consumer, 'node_modules', 'testguard-cli', 'src', 'probe', 'runners', 'shared.mjs');
+  run(process.execPath, ['--input-type=module', '-e',
+    `import { pathToFileURL } from 'node:url'; const { parseReport } = await import(pathToFileURL(process.argv[1]));
+     const result = parseReport({ success: false, numTotalTests: 2, numFailedTests: 2, testResults: [{ name: 'test.mjs', status: 'failed', assertionResults: [
+       { status: 'failed', failureMessages: ['AssertionError: expected /specify timed out/'] },
+       { status: 'failed', failureMessages: ['Error: Test timed out in 1000ms.'] },
+     ] }] }, 1);
+     if (result.timeouts !== 1 || result.run.assertionFailures !== 1) throw new Error('installed runner confuses assertion text with timeout identity');`,
+    installedRunner,
+  ], consumer);
+  const claims = run(bin, ['claims', '.'], consumer);
+  const draft = JSON.parse(run(bin, ['scaffold', 'src/redact.mjs', '--json'], consumer));
+  const installedValidator = join(consumer, 'node_modules', 'testguard-cli', 'spec', 'lib', 'validate.mjs');
+  const candidateEvidence = join(root, 'spec', 'conformance', 'examples', 'evidence.json');
+  const validatesCandidateEvidence = run(process.execPath, [
+    '--input-type=module',
+    '-e',
+    `import { pathToFileURL } from 'node:url'; import { readFileSync } from 'node:fs';
+     const { validate } = await import(pathToFileURL(process.argv[1]));
+     const result = validate('evidence', JSON.parse(readFileSync(process.argv[2], 'utf8')));
+     if (!result.ok) throw new Error(result.errors.map((error) => \`${'${error.path}: ${error.message}'}\`).join('; '));
+     const gate = JSON.parse(readFileSync(process.argv[3], 'utf8'));
+     gate.nested = [{ project: 'backend', files: ['backend/src/guard.mjs'] }]; gate.changed++;
+     const nestedResult = validate('gate', gate);
+     if (!nestedResult.ok) throw new Error('installed package rejected the nested-project gate contract');
+     process.stdout.write('ok');`,
+    installedValidator,
+    candidateEvidence,
+    join(root, 'spec', 'conformance', 'examples', 'gate.json'),
+  ], consumer).trim();
+  if (!draft.claims?.length) throw new Error('scaffold produced no claims from the installed tarball');
+  if (!/^\d+\.\d+\.\d+/.test(version)) throw new Error(`unexpected --version output: ${version}`);
+  if (!/^\d+ claims in /.test(claims)) throw new Error(`claims did not list the fixture:\n${claims}`);
+  if (validatesCandidateEvidence !== 'ok') throw new Error('installed package did not validate candidate-format evidence');
+  const deps = Object.keys(JSON.parse(run(npm, ['ls', '--omit=dev', '--json', '--depth=0'], consumer)).dependencies ?? {});
+  console.log(`install smoke OK — testguard ${version} runs from the installed tarball; consumer deps: ${deps.join(', ')}`);
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.1] - 2026-09-30
+
+Automated weekly release — everything merged since `v0.15.0`.
+
+### Changed
+
+- fix: runner timeout identity and reported adoption regressions (#180)
+- chore(homebrew): sha256 for v0.15.0 (#177)
+
+
+### Fixed
+
+- Assertion messages quoting "timed out" no longer become runner timeouts.
+  Native timeout headers and structured timeout failures remain non-detections
+  (#179).
+- Configuration dependency hashing no longer rejects harmless absolute-looking
+  strings such as Vite URL bases, middleware routes, or `split('/')`. Existing
+  outside-project file dependencies and symlinks still fail closed (#178).
+- Discovery failures no longer assert that dependencies are missing when the
+  runner resolved successfully but its configuration could not be discovered.
+- Each subcommand's `--help` now shows its own options and an example; global
+  `--help` exits successfully and points to command-specific help (#120).
+- Parent gates, status change reports, and claimed-surface counts respect valid
+  nested TestGuard project boundaries. Delegated files are explicitly reported
+  and require a separate child gate; invalid or symlinked markers fail (#150).
+
+### Added
+
+- Explicit `probe --allow-empty` adoption mode, also available as an opt-in
+  GitHub Action input. A valid empty claims file skips verification without
+  writing evidence; JSON keeps the `no-claims` state. Default empty probes,
+  invalid claims, and explicit claim selections still fail (#176).
+
+## [0.15.0] - 2026-09-29
+
+Automated weekly release — everything merged since `v0.14.2`.
+
+### Changed
+
+- feat: harden discovery, replay, and command budgets (#174)
+- chore(homebrew): sha256 for v0.14.2 (#173)
+
+
+### Added
+
+- Runner-native test discovery for Vitest, Jest, and Playwright, with bounded
+  output, path validation, immutable universe manifests, exact mixed-runner
+  routing, and configuration-closure hashes (including workspace configs,
+  package helpers, setup files, and Python collection hooks) that prevent stale
+  evidence reuse.
+- Symbol-aware JavaScript/TypeScript defender discovery through named,
+  default, namespace, CommonJS, and barrel re-exports. Ambiguity and bounded
+  resolver exhaustion fail closed as `defender-discovery-indeterminate`.
+- `probe`, `sweep`, and `replay` accept `--command-budget <ms>` as a
+  cooperative measurement deadline distinct from the existing per-run
+  `--budget`. It caps asynchronous children and is checked at stage and write
+  boundaries; synchronous setup may overrun but cannot publish a partial
+  result, so an unattempted suffix can never be reported as clean.
+
+### Fixed
+
+- Runner timeouts now hard-kill the original process group and descendants
+  still attributable at timeout. Diagnostics explicitly say cleanup is
+  unverified because a previously reparented daemon requires external OS or
+  container containment.
+- Generated CommonJS export mutations and unresolved symbol/configuration
+  paths fail closed instead of allowing a false `nocover` result.
+- Dirty-tree preflight now resolves the same full primary-plus-owned runner
+  universe as measurement, including custom Playwright names and imported
+  configuration helpers; discovery failure blocks rather than hiding edits.
+
 ## [0.14.2] - 2026-09-28
 
 Automated weekly release — everything merged since `v0.14.1`.
@@ -15,7 +86,6 @@ Automated weekly release — everything merged since `v0.14.1`.
 
 - chore(homebrew): sha256 for v0.14.1 (#171)
 
-
 ## [0.14.1] - 2026-09-27
 
 Automated weekly release — everything merged since `v0.14.0`.

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.14.2
+Version: 0.15.1
 Summary: 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. Ships the Node.js CLI (requires Node.js 20+).
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -151,9 +151,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.14.2` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.15.1` — 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.14.2/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.15.1/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
@@ -431,6 +431,20 @@ is missing. TestGuard itself still makes no network calls.
 
 ### Starting from zero claims
 
+During gradual adoption, use `testguard probe --allow-empty` to skip a valid
+empty claims file without blocking a push. It explicitly reports that no
+verification was performed and writes no evidence; `--json` retains the
+`no-claims` state. Missing or invalid claims files still fail. Run `gate`
+separately to enforce changed-file coverage. For the pre-commit probe hook,
+set `args: [--allow-empty]`; for the GitHub Action, set `allow-empty: 'true'`.
+The default probe still exits 2 when no claims exist.
+
+In a monorepo, a valid nested `testguard.claims.json` marks a separate project.
+The parent gate reports its changed files as delegated and does not count them
+as parent coverage. Run `gate` in each child project as well; a passing parent
+gate does not establish that child coverage passed. Invalid child claims fail
+evaluation instead of hiding files.
+
 `gate` names the changed files that carry no claim, and stops there —
 correctly, because stating a claim is a human act. But a project adopting this
 tool reads that list, has nothing to compare it against, and closes the tab.
@@ -687,12 +701,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.14.2
+- uses: raccioly/testguard@v0.15.1
   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.14.2/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.15.1/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
 ```
 
@@ -718,6 +732,18 @@ talks to the network; only the job posts, and only when told to.
 - **Never optimistic.** A timeout, a load failure, a mixed N-run result, a
   flaky defender or a missing anchor is reported as unproven, never rounded
   toward green. The one pass is `killed`; everything else gates.
+- **Per-run and whole-command time are separate.** `--budget` limits each
+  runner invocation. `--command-budget` is a cooperative deadline for the
+  complete `probe`, `sweep`, or `replay` measurement: asynchronous children
+  receive only the remaining time, and stage/write boundaries re-check it.
+  Synchronous setup may overrun the nominal deadline, but once expiry is
+  observed TestGuard exits `2` and writes no new result document; a completed
+  prefix is not presented as though the unattempted suffix were clean.
+- **Configured discovery is evidence.** Vitest, Jest, and Playwright enumerate
+  their own configured files; TestGuard validates and hashes that immutable
+  universe instead of guessing with filename globs. Automatic JavaScript and
+  TypeScript discovery follows the imported symbol through barrels. Ambiguous
+  or unbounded resolution is `unverifiable`, never a flattering `nocover`.
 - **One exact-pinned runtime dependency** (`ajv`), Node ≥ 20, MIT.
 
 ### Prior art, and what was taken from where

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/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.14.2` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.15.1` — 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.14.2/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.15.1/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
@@ -407,6 +407,20 @@ is missing. TestGuard itself still makes no network calls.
 
 ### Starting from zero claims
 
+During gradual adoption, use `testguard probe --allow-empty` to skip a valid
+empty claims file without blocking a push. It explicitly reports that no
+verification was performed and writes no evidence; `--json` retains the
+`no-claims` state. Missing or invalid claims files still fail. Run `gate`
+separately to enforce changed-file coverage. For the pre-commit probe hook,
+set `args: [--allow-empty]`; for the GitHub Action, set `allow-empty: 'true'`.
+The default probe still exits 2 when no claims exist.
+
+In a monorepo, a valid nested `testguard.claims.json` marks a separate project.
+The parent gate reports its changed files as delegated and does not count them
+as parent coverage. Run `gate` in each child project as well; a passing parent
+gate does not establish that child coverage passed. Invalid child claims fail
+evaluation instead of hiding files.
+
 `gate` names the changed files that carry no claim, and stops there —
 correctly, because stating a claim is a human act. But a project adopting this
 tool reads that list, has nothing to compare it against, and closes the tab.
@@ -663,12 +677,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.14.2
+- uses: raccioly/testguard@v0.15.1
   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.14.2/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.15.1/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
 ```
 
@@ -694,6 +708,18 @@ talks to the network; only the job posts, and only when told to.
 - **Never optimistic.** A timeout, a load failure, a mixed N-run result, a
   flaky defender or a missing anchor is reported as unproven, never rounded
   toward green. The one pass is `killed`; everything else gates.
+- **Per-run and whole-command time are separate.** `--budget` limits each
+  runner invocation. `--command-budget` is a cooperative deadline for the
+  complete `probe`, `sweep`, or `replay` measurement: asynchronous children
+  receive only the remaining time, and stage/write boundaries re-check it.
+  Synchronous setup may overrun the nominal deadline, but once expiry is
+  observed TestGuard exits `2` and writes no new result document; a completed
+  prefix is not presented as though the unattempted suffix were clean.
+- **Configured discovery is evidence.** Vitest, Jest, and Playwright enumerate
+  their own configured files; TestGuard validates and hashes that immutable
+  universe instead of guessing with filename globs. Automatic JavaScript and
+  TypeScript discovery follows the imported symbol through barrels. Ambiguous
+  or unbounded resolution is `unverifiable`, never a flattering `nocover`.
 - **One exact-pinned runtime dependency** (`ajv`), Node ≥ 20, MIT.
 
 ### Prior art, and what was taken from where

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/action.yml

@@ -35,6 +35,10 @@ inputs:
     description: 'Skip re-running survivors against the whole suite'
     required: false
     default: 'false'
+  allow-empty:
+    description: 'probe only: explicitly skip a valid empty claims file during adoption; writes no evidence. Run gate separately.'
+    required: false
+    default: 'false'
   changed-ref:
     description: 'gate only: the reference the change is measured against (default: origin/<base branch> of the pull request). Check out with fetch-depth: 0 so it resolves.'
     required: false
@@ -46,7 +50,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.14.2'
+    default: '0.15.1'
   node-version:
     description: 'Node.js version (20+)'
     required: false
@@ -82,6 +86,7 @@ runs:
         if [ "${{ inputs.command }}" = "probe" ]; then
           ARGS+=(--severity "${{ inputs.severity }}" --confirm "${{ inputs.confirm }}" --budget "${{ inputs.budget }}")
           [ "${{ inputs.no-escalate }}" = "true" ] && ARGS+=(--no-escalate)
+          [ "${{ inputs.allow-empty }}" = "true" ] && ARGS+=(--allow-empty)
           [ "${{ inputs.runner }}" != "auto" ] && ARGS+=(--runner "${{ inputs.runner }}")
           [ -n "${{ inputs.python }}" ] && ARGS+=(--python "${{ inputs.python }}")
         fi

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/docs/testguard-explained.html

@@ -144,7 +144,7 @@
 <div class="page">
   <div class="masthead">
     <div class="wordmark">Test<span class="mark">Guard</span></div>
-    <div class="meta">Technical Brief · v0.14.2 · MIT</div>
+    <div class="meta">Technical Brief · v0.15.1 · MIT</div>
   </div>
 
   <h1>Your tests pass. That is not the same as your tests working.</h1>

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "testguard-cli",
-  "version": "0.14.2",
+  "version": "0.15.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "testguard-cli",
-      "version": "0.14.2",
+      "version": "0.15.1",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0"

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.14.2",
+  "version": "0.15.1",
   "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",

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/packaging/gitlab/testguard.gitlab-ci.yml

@@ -3,7 +3,7 @@
 # Include it from a project's .gitlab-ci.yml, pinned to a release:
 #
 #   include:
-#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.14.2/packaging/gitlab/testguard.gitlab-ci.yml'
+#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.15.1/packaging/gitlab/testguard.gitlab-ci.yml'
 #       inputs:
 #         dir: backend            # where testguard.claims.json lives (default ".")
 #         post_note: true         # post the brief as a merge-request note (needs TESTGUARD_GITLAB_TOKEN, api scope)
@@ -29,7 +29,7 @@ spec:
   inputs:
     version:
       description: testguard-cli version to run
-      default: "0.14.2"
+      default: "0.15.1"
     dir:
       description: directory whose test runner is invoked (where testguard.claims.json lives)
       default: "."

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/packaging/homebrew/testguard.rb

@@ -15,8 +15,8 @@
 class Testguard < Formula
   desc "Proves a test suite defends the claims a project makes"
   homepage "https://github.com/raccioly/testguard"
-  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.14.2.tgz"
-  sha256 "42651c054396fdf7506605ee19c198611713f698931755d3acf3656d7b96d8cb"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.15.1.tgz"
+  sha256 "357f37905e99bf2d1a7487374bc2fc2b97983fd8d355b2e77d72e03fb0f2f8c7"
   license "MIT"
 
   depends_on "node"

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.14.2"
+version = "0.15.1"
 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. Ships the Node.js CLI (requires Node.js 20+)."
 readme = "README.md"
 license = { text = "MIT" }

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/spec/GATE-SEMANTICS.md

@@ -12,7 +12,7 @@ The verdict set is closed. Only one value is a pass.
 | `killed` | Fault applied; every one of N probe runs failed with a genuine assertion failure, on a defender set that was green N/N unmodified. | no |
 | `survived` | Fault applied; every one of N probe runs passed. The claim is **unproven**. | **yes** |
 | `nocover` | No defending test exists: the declared globs resolve to nothing, or no test imports the subject. Worse than `survived` — nothing was even tried. | **yes** |
-| `unverifiable` | The claim could not be probed: the fault's anchor is missing or ambiguous, its defenders failed to load (`defenders-failed-to-load`), probing it threw (`probe-error`), or the defenders do not execute the subject at all (`subject-not-executed`). Carries a `reason`. A loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone fixes the fault or the defenders. Never confused with `flaky-defender`, which requires tests that *ran*. | **yes** |
+| `unverifiable` | The claim could not be probed: the fault's anchor is missing or ambiguous, configured or symbol-level defender discovery was indeterminate (`defender-discovery-indeterminate`), its defenders failed to load (`defenders-failed-to-load`), probing it threw (`probe-error`), or the defenders do not execute the subject at all (`subject-not-executed`). Carries a `reason`. A loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone fixes the fault or the defenders. Never confused with `flaky-defender`, which requires tests that *ran*. | **yes** |
 | `timeout` | Probe run exceeded its budget. Not counted as a kill; the pessimistic reading is the safe one because flakiness biases the metric optimistically. | **yes** |
 | `fault-invalid` | The replacement does not load or compile. A bad fault, not a detection. | **yes** |
 | `flaky-defender` | Defenders were not green N/N on unmodified source (`defenders-not-green`), or the N probe runs disagreed with each other (`inconsistent-probe`). Either way no verdict about the fault can be trusted; fix the defenders first. | **yes** |
@@ -36,7 +36,11 @@ Rules that follow from the table:
    that failed and then passed on retry (Playwright's `flaky`) is a
    **non-green run** even when the runner exits 0, and a test the runner
    reports as timed out (`timedOut`) is a timeout, never an assertion
-   failure. Python is read the same way: an `AssertionError` and any other
+   failure. Jest-compatible timeout messages are recognized by native runner
+   error headers or structured timeout identity, not by words quoted in an
+   assertion, stack frame, or source excerpt. Structured assertion identity
+   does not hide a separate timeout in the same failed test.
+   Python is read the same way: an `AssertionError` and any other
    exception raised by the test body both count, because both are the suite
    rejecting the behaviour; a collection error — a module that will not
    import, which is what a replacement that does not parse looks like from
@@ -151,7 +155,48 @@ Rules that follow from the table:
    can name the file the interpreter loaded) answers the same question more
    precisely for one language; where both are present they must agree.
 
-13. **Fault injection is one method, not the definition.** A claim declares
+13. **The configured runner defines the test universe.** For JavaScript and
+   TypeScript, defender discovery, baseline runs and escalation use the exact
+   file set returned by the resolved runner's native listing protocol. A
+   resolvable runner whose configuration cannot load, whose listing times out
+   or is malformed, or whose reported paths escape the project is a
+   precondition failure. It never falls back to built-in filename globs and
+   never becomes `nocover`. An explicitly selected runner that lists zero
+   files is also a precondition failure; `auto` may continue past a successful
+   empty listing, but must fail when every eligible runner is empty.
+   `inputs.testUniverseHash` binds the normalized file set, runner identity,
+   and hashed configuration dependencies. Those dependencies include absent
+   root candidates, nested workspace configs, Python collection hooks, and the
+   bounded static closure of local or package-imported config helpers and setup
+   files; creating or editing any of them forces remeasurement. Evidence that
+   predates this hash, or whose hash
+   changed, is readable but never reusable for a current native discovery run.
+   When several configured runners list defenders, exact manifest membership
+   assigns each file. An owned runner takes precedence over the project runner;
+   competing owned runners or a declared defender absent from every manifest
+   are precondition failures, never heuristic routing decisions.
+
+   Static string literals are conservative dependency candidates, not proof
+   of a filesystem dependency. Missing candidates and ordinary directories
+   (including `/` in URL bases and string separators) are ignored. An existing
+   candidate file outside the project, or a candidate symlink, is rejected.
+
+14. **Barrel resolution follows symbols, not module reachability.** Automatic
+   discovery may traverse a re-export chain only for the binding the test
+   actually imports. Importing an unrelated symbol from a broad barrel does
+   not defend every file the barrel exports. Renames, explicit exports and
+   star exports are resolved deterministically; type-only paths do not count.
+   Ambiguous origins, unsupported runtime-generated exports, graph-limit
+   exhaustion, and originless cycles are `unverifiable` with reason
+   `defender-discovery-indeterminate`, never `nocover`. A declared
+   `defendedBy` remains authoritative. `inputs.discoveryHashes` binds every
+   candidate test, intermediate barrel, and resolver-configuration file
+   consulted by automatic discovery. Negative candidates are dependencies too:
+   editing a previously unrelated test so it begins importing the target must
+   invalidate an earlier `nocover`. Absent or changed dependencies force
+   remeasurement.
+
+15. **Fault injection is one method, not the definition.** A claim declares
    what must be true; a probe declares how a tool would try to make it false,
    and `method` says which way. `fault-injection` — mutate the source, run the
    claim's defenders, confirm over N runs — is the only method specified in
@@ -184,6 +229,32 @@ Rules that follow from the table:
    The verdict set stays closed and shared. What each method may legitimately
    report is part of defining it.
 
+## Per-run and whole-command budgets are different
+
+`--budget` remains the wall-clock ceiling for one runner invocation. An
+optional `--command-budget` is a cooperative deadline for the complete
+`probe`, `sweep`, or `replay` measurement. Every asynchronous child runner and
+discovery process is given no more than the command's remaining time, and the
+deadline is checked again at stage boundaries and immediately before any
+result is written. Synchronous filesystem, Git, parsing, and cleanup work is
+not preemptible in portable Node.js and may finish after the nominal deadline;
+that overrun grants no authority to publish a result.
+
+Exhausting the whole-command budget is not a test verdict and is never a
+successful partial measurement. The command exits `2` and writes no new
+result document; any previous document remains untouched. Cleanup may finish
+after the deadline, but no record from the incomplete operation becomes
+evidence. This is deliberately stricter than a per-run timeout: publishing
+the completed prefix would let the unattempted suffix look clean.
+
+Timeout cleanup is best effort, not portable process containment. TestGuard
+hard-kills the runner's original process group and every descendant still
+attributable through the process table. A daemon that detached, reparented,
+and disappeared from that ancestry before timeout may survive, so timeout
+diagnostics state `cleanup-unverified`. Such a run remains a timeout and never
+becomes evidence of detection. Daemonizing or untrusted commands require an
+OS or container boundary that TestGuard does not claim to provide.
+
 ## Replay reports; it never gates
 
 A replayed bug is history. It escaped, by definition, which means the suite
@@ -198,7 +269,7 @@ Its verdicts mirror the probe's, for the same reasons:
 | `caught` | a remaining test failed **by assertion** on the reverted source, every run. The suite knew. |
 | `blind` | the suite stayed green on known-broken code. |
 | `nocover` | no test imports the reverted files, **and at least one test file remained to ask**. Worse than `blind`: nothing was even tried. |
-| `unverifiable` | the revert did not apply, the suite failed to load, it timed out, or removing the fix's own test left **no test file at all** (`the-fix-shipped-the-only-test-file`). Carries a `reason`. |
+| `unverifiable` | the revert did not apply, configured or symbol-level defender discovery was indeterminate (`defender-discovery-indeterminate`), the suite failed to load, it timed out, or removing the fix's own test left **no test file at all** (`the-fix-shipped-the-only-test-file`). Carries a `reason`. |
 | `flaky` | the runs disagreed. A flaky failure reads as "the suite caught it", so flakiness biases this metric **optimistically** — mixed runs are never `caught`. |
 
 Two rules that follow:
@@ -432,10 +503,22 @@ Rules:
    `unclaimed-changes` and its next action is to write the claim, before any
    `unproven` finding is surfaced. The brief renders them first. The claim is
    written before more code.
-
-Exit codes: `0` every changed source file is claimed or excused (or nothing
-changed); `1` at least one uncovered file (or strict mode over an
-all-excluded change); `2` the change cannot be evaluated (unresolvable
+7. **A descendant claims file defines a separate project.** The first
+   descendant directory on a changed file's path with a valid, regular,
+   non-symlinked `testguard.claims.json` owns that subtree. Invalid or unreadable
+   markers fail evaluation; they cannot hide unclaimed files. Parent gate and
+   status report the delegation as optional `nested` entries with project and
+   file paths relative to the parent, and instruct the operator to run that
+   project's gate. Delegation is not coverage, an ignore reliance, or proof
+   that the child passed. Parent source-surface counts omit these subtrees.
+   Removing the marker restores parent evaluation. The accounting identity is
+   `changed = evaluated + excluded.length + sum(nested[].files.length)`;
+   `--strict` still fails a non-empty change with zero parent evaluation.
+
+Exit codes: `0` every changed parent-owned source file is claimed or excused
+(or nothing changed); delegated projects still require separate child gates.
+`1` at least one uncovered file (or strict mode over an
+all-excluded or all-delegated change); `2` the change cannot be evaluated (unresolvable
 reference, invalid claims or ignore file, no repository); `3` no reference.
 
 ## Anchor preflight
@@ -486,3 +569,11 @@ evidence; they simply do not turn CI red.
 A tool must never exit `0` because it had nothing to check. If the claims
 file is empty or every claim is out of scope, that is reported explicitly and
 the exit code is `2`.
+
+`probe --allow-empty` is an explicit adoption exception for a valid claims
+file containing zero claims, with no `--claim` selection. It exits `0`, says
+that verification was skipped, and writes no evidence or baseline. Its JSON
+output is the existing `no-claims` status document, without run metadata;
+it never reports a clean measurement. Missing or invalid claims still fail,
+and selected claims cannot be silently skipped. Run `gate` separately to
+enforce coverage of changed files during adoption. Integrations must opt in.

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/spec/README.md

@@ -39,6 +39,13 @@ Shared definitions (verdicts, fault classes, provenance, annotations) live in
 which verdicts turn CI red, baseline and delta rules, exit codes — is in
 [`GATE-SEMANTICS.md`](GATE-SEMANTICS.md).
 
+Operational completeness is contractual too. `--budget` bounds one runner
+invocation; `--command-budget` is a cooperative deadline for a complete probe,
+sweep, or replay measurement. It caps asynchronous child processes, is checked
+at stage and write boundaries, and produces no document once observed expired.
+Synchronous setup may overrun but cannot authorize a partial result. The exact
+rule is in `GATE-SEMANTICS.md`.
+
 Schemas are JSON Schema 2020-12 and identified as `urn:claimspec:v1:<kind>`.
 
 ## Conformance

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/spec/conformance/examples/evidence.json

@@ -165,7 +165,9 @@
         "targetHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         "defenderHashes": {
           "test/redact.test.mjs": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
-        }
+        },
+        "testUniverseHash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+        "discoveryHashes": {}
       },
       "rank": {
         "score": 9.5,

{testguard_cli-0.14.2 → testguard_cli-0.15.1}/spec/conformance/schemas.test.mjs

@@ -13,6 +13,26 @@ const here = dirname(fileURLToPath(import.meta.url));
 const load = (dir, f) => JSON.parse(readFileSync(join(here, dir, f), 'utf8'));
 
 describe('claimspec v1 — conformance', () => {
+  it('accounts for descendant-project delegation without calling it coverage or double-counting it', () => {
+    const gate = load('examples', 'gate.json');
+    gate.nested = [{ project: 'backend', files: ['backend/src/guard.mjs'] }];
+    gate.changed++;
+    expect(validate('gate', gate).errors).toEqual([]);
+    gate.changed--;
+    expect(validate('gate', gate).errors.map((e) => e.path)).toContain('/changed');
+    gate.changed++;
+    gate.nested[0].files = ['src/guard.mjs'];
+    expect(validate('gate', gate).errors.map((e) => e.path)).toContain('/nested/0/files');
+    gate.nested[0].files = ['backend/src/guard.mjs'];
+    gate.covered.push({ file: 'backend/src/guard.mjs', by: 'fault', claimIds: ['C-1'] });
+    gate.evaluated++;
+    gate.changed++;
+    expect(validate('gate', gate).errors.map((e) => e.path)).toContain('/nested/0/files');
+    gate.covered.pop(); gate.evaluated--; gate.changed--;
+    gate.nested.push({ project: 'backend', files: ['backend/src/second.mjs'] });
+    gate.changed++;
+    expect(validate('gate', gate).errors.map((e) => e.path)).toContain('/nested/1/project');
+  });
   describe('every valid example passes', () => {
     for (const f of readdirSync(join(here, 'examples')).filter((f) => f.endsWith('.json'))) {
       const kind = KINDS.find((k) => f.startsWith(k));