testguard-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{testguard_cli-0.3.0 → testguard_cli-0.4.0}/.github/workflows/ci.yml

@@ -102,6 +102,26 @@ jobs:
             console.log('fixture verdicts match expected.json:', ev.records.length);
           "
 
+      - name: probe the jest fixture (through the bin, --runner jest)
+        shell: bash
+        run: |
+          S=$(mktemp -d)
+          cp -R fixtures/known-answer-jest/. "$S/"
+          rm -rf "$S/node_modules" "$S/.flake-counter" "$S/.testguard"
+          ln -s "$GITHUB_WORKSPACE/node_modules" "$S/node_modules"
+          git -C "$S" init -q && git -C "$S" -c user.email=ci@example.invalid -c user.name=ci add -A && git -C "$S" -c user.email=ci@example.invalid -c user.name=ci commit -qm fixture
+          status=0; node cli/testguard.mjs probe "$S" --runner jest --budget 60000 --quiet --no-escalate || status=$?
+          [ "$status" -eq 1 ] || { echo "::error::expected exit 1, got $status"; exit 1; }
+          node --input-type=module -e "
+            import { readFileSync } from 'node:fs';
+            const ev = JSON.parse(readFileSync('$S/.testguard/evidence.json','utf8'));
+            const exp = JSON.parse(readFileSync('fixtures/known-answer-jest/expected.json','utf8')).expected;
+            if (ev.run.runner.name !== 'jest') { console.error('runner was', ev.run.runner.name); process.exit(1); }
+            const bad = ev.records.filter(r => exp[r.claim.id+'/'+r.subject.id].verdict !== r.verdict);
+            if (bad.length) { console.error('MISMATCH', bad.map(r => r.claim.id+'/'+r.subject.id+':'+r.verdict)); process.exit(1); }
+            console.log('jest fixture verdicts match expected.json:', ev.records.length);
+          "
+
       # ── Self-verification: TestGuard is governed by the standard it defines.
       #    testguard.claims.json states invariants of the tool itself; every
       #    fault must be killed by the tool's own tests. Exit 0 = all defended. ──

testguard_cli-0.4.0/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+coverage/
+.DS_Store
+*.log
+# TestGuard: baseline.json and status.json ARE committed (the frozen contract and its snapshot); the rest is regenerated per run
+.testguard/evidence.json
+.testguard/evidence-provisional.json
+.testguard/evidence-partial.json
+.testguard/brief.json
+.testguard/scaffold-*.json
+# Local agent tooling — not part of the public project
+.wolf/
+.claude/
+CLAUDE.local.md
+graphify-out/
+.vitest/
+# Python build artefacts
+dist/
+build/
+*.egg-info/
+__pycache__/

testguard_cli-0.4.0/.testguard/baseline.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.3.0"
+  },
+  "createdAt": "2026-09-17T15:24:13.597Z",
+  "head": "ac32ce504fc42f9b50389a5a8092a0e2ca1c5c9d",
+  "dirty": true,
+  "fingerprints": {}
+}

testguard_cli-0.4.0/.testguard/status.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "testguard",
+    "version": "0.3.0"
+  },
+  "generatedAt": "2026-09-17T15:24:13.654Z",
+  "state": "clean",
+  "next": {
+    "action": "none",
+    "command": "testguard probe",
+    "why": "Every claim is defended. Re-probe after changing code, tests or claims; add a claim for every new invariant."
+  },
+  "provisional": false,
+  "counts": {
+    "claims": 12,
+    "faults": 12,
+    "byVerdict": {
+      "killed": 12
+    },
+    "new": 0,
+    "baselined": 0
+  },
+  "stale": [],
+  "changedFaults": [],
+  "findings": [],
+  "paths": {
+    "claims": "testguard.claims.json",
+    "evidence": ".testguard/evidence.json",
+    "baseline": ".testguard/baseline.json"
+  }
+}

{testguard_cli-0.3.0 → testguard_cli-0.4.0}/AGENTS.md

@@ -31,6 +31,7 @@ node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the produ
 - `fixtures/known-answer/expected.json` — the oracle. Never edit it to match output.
 - `testguard.claims.json` — claims about this codebase, probed in CI.
 - `src/scaffold/producers.mjs` — the five fault shapes. Deterministic line heuristics; no AST, no LLM. A new shape needs a synthetic-file test and a README row.
+- `src/probe/runners/` — one module per runner (`name`, `testGlobs`, `check`, `tests`, `run`) over `shared.mjs` (jest-compatible report parsing, budgeted process runner). A new runner needs its own fixture copy with the same `expected.json`.
 - `src/status/status.mjs` — the state machine every rendering derives from. A new state or action is a spec change (`status.schema.json`) and a skill-template change (`src/init/templates/SKILL.md`) in the same PR.
 
 ## Rules
@@ -56,3 +57,12 @@ node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the produ
 Dependabot minor/patch PRs and automated release PRs auto-merge when the exact
 CI run is green on all three Node legs. Majors and anything else wait for a
 human. Release publishing is OIDC-only; there are no tokens in this repo.
+
+<!-- testguard:begin -->
+## TestGuard
+
+This project's tests are verified by [TestGuard](https://github.com/raccioly/testguard).
+Before writing or changing tests, run `testguard status --json` and follow `next`.
+The full operating loop and the verdict table are in `.claude/skills/testguard/SKILL.md`.
+Never make a fault die by editing `testguard.claims.json`; write the test. Claim edits are recorded in the evidence.
+<!-- testguard:end -->

{testguard_cli-0.3.0 → testguard_cli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-17
+
+### Added
+
+- **jest runner.** `--runner vitest|jest|auto` (default `auto`: the first
+  that resolves in the project). jest runs with `--ci --json --runTestsByPath`
+  so file arguments are exact paths, not regexes; its `Exceeded timeout`
+  wording is recognised as a timeout, never a kill; `__tests__/` files are
+  collected for escalation. `run.runner.name` records which runner produced
+  the evidence.
+- A CommonJS edition of the known-answer fixture (`fixtures/known-answer-jest`)
+  with the same claims and the same expected verdicts; the acceptance suite
+  and CI prove jest against it exactly as vitest is proven against the ESM
+  one.
+
+### Changed
+
+- Runners are now modules behind one interface (`src/probe/runners/`); the
+  vitest path is unchanged and still reproduces its oracle.
+
+## [0.3.1] - 2026-09-17
+
+Dogfooding `init` and `status` on this repository.
+
+### Fixed
+
+- `init` no longer adds per-file `.gitignore` lines to a project that already
+  ignores `.testguard/` wholesale; it notes instead that `baseline.json` is
+  meant to be committed.
+- The brief no longer says "everything is new" when nothing is unproven.
+
+### Changed
+
+- This repository now carries its own `AGENTS.md` TestGuard section, written
+  by `testguard init`.
+
 ## [0.3.0] - 2026-09-17
 
 The agent operating layer. TestGuard is meant to be run by AI agents; this

{testguard_cli-0.3.0 → testguard_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Proves a test suite actually defends the claims a project makes: injects the faults those claims forbid and reports every one the tests miss. Python wrapper for 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
@@ -76,7 +76,7 @@ tests were written against the survivors, 39/39 were killed.
 | 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.3.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.4.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
@@ -135,6 +135,11 @@ npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to
    files that import the fault's target, by relative path or resolved alias.
    `NOCOVER` then means exactly "no test file imports this source".
 
+   Runners: **vitest** and **jest** (`--runner auto` picks the first that
+   resolves; both read the same jest-compatible JSON report). Anything else
+   goes through `--runner-cmd`. Each runner is proven against its own copy
+   of the known-answer fixture.
+
    Practical loop: first pass `--no-escalate` (escalation re-runs the whole
    suite N times per survivor); iterate on one claim with `--claim <ID>` and
    either `--include-dirty` or `--in-place` (only fault target files must be
@@ -239,14 +244,14 @@ through every verdict.
 
 ## Status
 
-**v0.3.** Seven commands, vitest runner, hand-authored faults plus a
-mechanical scaffold, and an agent operating layer (`status`, `init`). The contract
+**v0.4.** Seven commands, vitest and jest runners, hand-authored faults plus
+a mechanical scaffold, and an agent operating layer (`status`, `init`). The contract
 spine — six JSON Schemas shared with the other Guard tools — is under
 [`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 
-Not yet: test generation (the two-gate acceptance loop), other runners,
-AST-aware producers, and calibration of fault classes against real escaped
-bugs. Each is designed for; none is claimed.
+Not yet: test generation (the two-gate acceptance loop), runners beyond
+vitest and jest, AST-aware producers, and calibration of fault classes
+against real escaped bugs. Each is designed for; none is claimed.
 
 ## Licence
 

{testguard_cli-0.3.0 → testguard_cli-0.4.0}/README.md

@@ -52,7 +52,7 @@ tests were written against the survivors, 39/39 were killed.
 | 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.3.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.4.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
@@ -111,6 +111,11 @@ npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to
    files that import the fault's target, by relative path or resolved alias.
    `NOCOVER` then means exactly "no test file imports this source".
 
+   Runners: **vitest** and **jest** (`--runner auto` picks the first that
+   resolves; both read the same jest-compatible JSON report). Anything else
+   goes through `--runner-cmd`. Each runner is proven against its own copy
+   of the known-answer fixture.
+
    Practical loop: first pass `--no-escalate` (escalation re-runs the whole
    suite N times per survivor); iterate on one claim with `--claim <ID>` and
    either `--include-dirty` or `--in-place` (only fault target files must be
@@ -215,14 +220,14 @@ through every verdict.
 
 ## Status
 
-**v0.3.** Seven commands, vitest runner, hand-authored faults plus a
-mechanical scaffold, and an agent operating layer (`status`, `init`). The contract
+**v0.4.** Seven commands, vitest and jest runners, hand-authored faults plus
+a mechanical scaffold, and an agent operating layer (`status`, `init`). The contract
 spine — six JSON Schemas shared with the other Guard tools — is under
 [`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 
-Not yet: test generation (the two-gate acceptance loop), other runners,
-AST-aware producers, and calibration of fault classes against real escaped
-bugs. Each is designed for; none is claimed.
+Not yet: test generation (the two-gate acceptance loop), runners beyond
+vitest and jest, AST-aware producers, and calibration of fault classes
+against real escaped bugs. Each is designed for; none is claimed.
 
 ## Licence
 

{testguard_cli-0.3.0 → testguard_cli-0.4.0}/action.yml

@@ -38,7 +38,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.3.0'
+    default: '0.4.0'
   node-version:
     description: 'Node.js version (20+)'
     required: false

testguard_cli-0.4.0/fixtures/known-answer-jest/.gitignore

@@ -0,0 +1,2 @@
+.flake-counter
+node_modules/

testguard_cli-0.4.0/fixtures/known-answer-jest/README.md

@@ -0,0 +1,7 @@
+# Known-answer fixture — jest edition
+
+The same nine claims and eleven faults as [`../known-answer`](../known-answer), in
+CommonJS, run by **jest** (`jest.config.js`: `testTimeout: 1000`). Every verdict in
+`expected.json` is the same. Its test suite is flaky by design (`test/flaky.test.js`).
+
+It proves the jest runner adapter reproduces the oracle; the ESM fixture proves vitest.

testguard_cli-0.4.0/fixtures/known-answer-jest/expected.json

@@ -0,0 +1,54 @@
+{
+  "confirmRuns": 3,
+  "expected": {
+    "REDACT-001/F1": {
+      "verdict": "survived",
+      "why": "The audit-row test asserts with objectContaining and omits `content`; a row carrying the raw input passes."
+    },
+    "REDACT-001/F2": {
+      "verdict": "killed",
+      "why": "The masked-output test asserts the secret is absent."
+    },
+    "REDACT-002/F1": {
+      "verdict": "killed",
+      "why": "The invalid-rule test asserts compileRules does not throw."
+    },
+    "REDACT-003/F1": {
+      "verdict": "survived",
+      "why": "No test exercises a missing scope; the fail-closed guard is undefended."
+    },
+    "REDACT-004/F1": {
+      "verdict": "timeout",
+      "why": "Tests awaiting redact() hit the 1s jest testTimeout; a timeout is not an assertion failure and is not a kill."
+    },
+    "REDACT-005/F1": {
+      "verdict": "unverifiable",
+      "reason": "anchor-missing",
+      "why": "The find string is not present in the source."
+    },
+    "REDACT-005/F2": {
+      "verdict": "unverifiable",
+      "reason": "anchor-ambiguous",
+      "why": "`return null;` occurs twice; expectHits is 1."
+    },
+    "REDACT-006/F1": {
+      "verdict": "fault-invalid",
+      "reason": "replacement-does-not-compile",
+      "why": "The replacement introduces a syntax error; the suite cannot load."
+    },
+    "EXPORT-001/F1": {
+      "verdict": "nocover",
+      "why": "test/export.test.js does not exist; no defender resolves."
+    },
+    "FLAKY-001/F1": {
+      "verdict": "flaky-defender",
+      "reason": "defenders-not-green",
+      "why": "test/flaky.test.js fails every other run; the baseline is not green N/N."
+    },
+    "DISCOVER-001/F1": {
+      "verdict": "killed",
+      "why": "No defendedBy; test/redact.test.js is discovered because it imports src/redact.js, and its masked-output test fails."
+    }
+  },
+  "runner": "jest"
+}

testguard_cli-0.4.0/fixtures/known-answer-jest/jest.config.js

@@ -0,0 +1 @@
+module.exports = { testEnvironment: 'node', testTimeout: 1000, testMatch: ['**/test/**/*.test.js'] };

testguard_cli-0.4.0/fixtures/known-answer-jest/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "testguard-known-answer-fixture-jest",
+  "private": true,
+  "version": "0.0.0",
+  "description": "The known-answer fixture in CommonJS for jest. Same claims, same expected verdicts. FLAKY BY DESIGN (test/flaky.test.js).",
+  "scripts": { "test": "jest" }
+}

testguard_cli-0.4.0/fixtures/known-answer-jest/src/export.js

@@ -0,0 +1,5 @@
+// Export of audit rows. No test file imports this module — on purpose (the `nocover` case).
+function exportRows(rows) {
+  return rows.map(({ content, ...rest }) => rest);
+}
+module.exports = { exportRows };

testguard_cli-0.4.0/fixtures/known-answer-jest/src/redact.js

@@ -0,0 +1,62 @@
+// Redaction engine for the known-answer fixture (CommonJS, for jest).
+// Every claim in ../testguard.claims.json is about this file.
+
+/** Compile a rule's pattern; an invalid pattern yields null and is skipped. */
+function safeRegex(pattern) {
+  try {
+    return new RegExp(pattern, 'g');
+  } catch {
+    return null;
+  }
+}
+
+/** Find a rule by id. */
+function findRule(rules, id) {
+  for (const rule of rules) {
+    if (rule.id === id) return rule;
+  }
+  return null;
+}
+
+/** Compile all rules. An invalid pattern is skipped; it never aborts the scan. */
+function compileRules(rules) {
+  const compiled = [];
+  for (const rule of rules) {
+    const re = safeRegex(rule.pattern);
+    if (re === null) continue;
+    compiled.push({ ...rule, re });
+  }
+  return compiled;
+}
+
+/** Replace every match of every rule with asterisks of equal length. */
+function mask(input, rules) {
+  let out = input;
+  for (const rule of compileRules(rules)) {
+    out = out.replace(rule.re, (m) => '*'.repeat(m.length));
+  }
+  return out;
+}
+
+/**
+ * Redact a message and write an audit row when anything was masked.
+ * @claim REDACT-003 Fails closed: a missing scope is an error, never an unscoped scan.
+ * The audit row must never carry the original input.
+ */
+async function redact(input, rules, ctx, store) {
+  if (!ctx || !ctx.scope) {
+    throw new Error('redact: scope is required');
+  }
+  const redacted = mask(input, rules);
+  if (redacted !== input) {
+    await store.writeAudit({
+      action: 'MASK',
+      scope: ctx.scope,
+      ruleCount: rules.length,
+      content: redacted,
+    });
+  }
+  return redacted;
+}
+
+module.exports = { findRule, compileRules, mask, redact };

testguard_cli-0.4.0/fixtures/known-answer-jest/test/flaky.test.js

@@ -0,0 +1,13 @@
+const { readFileSync, writeFileSync } = require('node:fs');
+const path = require('node:path');
+
+// Deterministically flaky: fails on odd-numbered runs (the `flaky-defender` case).
+const counterFile = path.join(__dirname, '..', '.flake-counter');
+
+it('is flaky by design (fails every other run)', () => {
+  let n = 0;
+  try { n = Number(readFileSync(counterFile, 'utf8')) || 0; } catch {}
+  n += 1;
+  writeFileSync(counterFile, String(n));
+  expect(n % 2).toBe(0);
+});

testguard_cli-0.4.0/fixtures/known-answer-jest/test/redact.test.js

@@ -0,0 +1,35 @@
+const { mask, redact, compileRules } = require('../src/redact');
+
+const SECRET = 'FIXTURE_SECRET_7731';
+const RULES = [{ id: 'r1', pattern: 'FIXTURE_SECRET_\\d+' }];
+const CTX = { scope: 'g1' };
+
+describe('redaction', () => {
+  it('masks the secret out of the returned text', () => {
+    const out = mask(`hello ${SECRET} bye`, RULES);
+    expect(out).not.toContain(SECRET);
+    expect(out).toBe('hello ******************* bye');
+  });
+
+  it('skips a rule whose pattern is invalid without throwing', () => {
+    const rules = [{ id: 'bad', pattern: '(' }, ...RULES];
+    expect(() => compileRules(rules)).not.toThrow();
+    expect(compileRules(rules)).toHaveLength(1);
+    expect(mask(SECRET, rules)).not.toContain(SECRET);
+  });
+
+  it('writes an audit row when something was masked', async () => {
+    const store = { writeAudit: jest.fn().mockResolvedValue(undefined) };
+    await redact(`hello ${SECRET}`, RULES, CTX, store);
+    // THE BLIND SPOT: objectContaining ignores unlisted keys, and `content` is not listed.
+    expect(store.writeAudit).toHaveBeenCalledTimes(1);
+    expect(store.writeAudit).toHaveBeenCalledWith(expect.objectContaining({ action: 'MASK', scope: 'g1', ruleCount: 1 }));
+  });
+
+  it('does not write an audit row when nothing matched', async () => {
+    const store = { writeAudit: jest.fn() };
+    const out = await redact('nothing here', RULES, CTX, store);
+    expect(out).toBe('nothing here');
+    expect(store.writeAudit).not.toHaveBeenCalled();
+  });
+});