testguard-cli 0.1.0__py3-none-any.whl

testguard_cli/__init__.py

@@ -0,0 +1 @@
+"""TestGuard CLI — Python wrapper around the Node.js `testguard-cli` package."""

testguard_cli/wrapper.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+TestGuard CLI — Python wrapper.
+
+Runs the Node.js TestGuard CLI so Python-centric teams can `pip install
+testguard-cli` and use `testguard` without touching npm directly.
+Node.js 20+ is required.
+
+Resolution order:
+  1. A locally installed `node_modules/testguard-cli/cli/testguard.mjs`,
+     searched upward from the current directory — so a project that pins the
+     package runs the PINNED version, offline and reproducibly.
+  2. `npx -y testguard-cli@latest`.
+
+Usage:
+    pip install testguard-cli
+    testguard claims
+    testguard probe
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+
+NODE_FLOOR = 20
+
+
+def find_node():
+    """Find a usable Node.js binary (>= NODE_FLOOR)."""
+    for cmd in ("node", "node22", "node20"):
+        path = shutil.which(cmd)
+        if not path:
+            continue
+        try:
+            version = subprocess.check_output(
+                [path, "--version"], text=True, stderr=subprocess.DEVNULL
+            ).strip()
+            if int(version.lstrip("v").split(".")[0]) >= NODE_FLOOR:
+                return path
+        except (subprocess.CalledProcessError, ValueError):
+            continue
+    return None
+
+
+def find_local_cli():
+    """Resolve a locally installed CLI entry, walking up from cwd."""
+    directory = os.getcwd()
+    while True:
+        entry = os.path.join(directory, "node_modules", "testguard-cli", "cli", "testguard.mjs")
+        if os.path.isfile(entry):
+            return entry
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            return None
+        directory = parent
+
+
+def main():
+    """Entry point for the `testguard` command."""
+    args = sys.argv[1:]
+    node = find_node()
+    if not node:
+        print(
+            f"Error: Node.js {NODE_FLOOR}+ is required but not found.\n"
+            "Install from https://nodejs.org/ or via nvm: nvm install 22",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    local_cli = find_local_cli()
+    npx = shutil.which("npx")
+    if local_cli:
+        cmd = [node, local_cli] + args
+    elif npx:
+        cmd = [npx, "-y", "testguard-cli@latest"] + args
+    else:
+        print("Error: npx not found. Install Node.js 20+, which includes npm/npx.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        sys.exit(subprocess.run(cmd, check=False).returncode)
+    except FileNotFoundError:
+        print(f"Error: could not execute: {' '.join(cmd)}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

testguard_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: testguard-cli
+Version: 0.1.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
+Project-URL: Repository, https://github.com/raccioly/testguard
+Project-URL: Issues, https://github.com/raccioly/testguard/issues
+Author-email: Ricardo Accioly <raccioly@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claims,fault-injection,mutation-testing,quality-assurance,test-quality,testing,verification,vitest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# TestGuard
+
+[![CI](https://github.com/raccioly/testguard/actions/workflows/ci.yml/badge.svg)](https://github.com/raccioly/testguard/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/testguard-cli.svg)](https://www.npmjs.com/package/testguard-cli)
+[![PyPI](https://img.shields.io/pypi/v/testguard-cli.svg)](https://pypi.org/project/testguard-cli/)
+[![node](https://img.shields.io/node/v/testguard-cli.svg)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](./package.json)
+
+> Proves that a test suite actually defends the claims a project makes — by
+> injecting the faults those claims say cannot happen, and reporting every
+> fault the tests fail to detect.
+
+**Not a test generator. A claim verifier.** Test generation is what happens
+after a claim turns out to be unfalsifiable.
+
+Third tool following the Guard pattern, alongside
+[`docguard-cli`](https://www.npmjs.com/package/docguard-cli) (docs ↔ code) and
+[`websec-validator`](https://pypi.org/project/websec-validator/) (attack
+surface ↔ code). All three run one loop:
+
+> declare what must be true → try mechanically to falsify it → freeze a
+> baseline → gate only the delta → brief the agent before it writes code.
+
+## Why
+
+Coverage cannot tell a test that pins *correct* behaviour from one that pins
+a *defect*. An agent that writes both the code and its tests encodes whatever
+it believed — including its bugs — and the suite goes green.
+
+Measured on a real, entirely AI-authored production codebase with ~4,900
+disciplined tests (no snapshots, 0.4% zero-assertion): **8 of 9 real
+historical bugs were invisible to the suite**, worst case 2,451 tests green
+on known-broken code. The largest gap was a compliance-critical path with
+100% coverage, where the one assertion that mattered used
+`expect.objectContaining({...})` and omitted the field carrying the data.
+
+## Install
+
+| How | Command |
+|---|---|
+| npx (no install) | `npx testguard-cli probe` |
+| 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.1.0` — see [`action.yml`](./action.yml) |
+| pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
+
+## How it works
+
+```bash
+npx testguard-cli claims      # what does this project claim, and is every claim probeable?
+npx testguard-cli probe       # try to falsify each claim; report what the tests missed
+npx testguard-cli baseline    # freeze today's unproven findings; from now on only new ones gate
+npx testguard-cli brief       # tell the agent where the suite is blind, before it writes
+```
+
+1. **Claims** live in `testguard.claims.json`: a statement, where it comes
+   from, which tests supposedly defend it, and one or more *faults* — each a
+   deterministic source change that would make the statement false. Every
+   claim and every fault records who produced it. `testguard claims`
+   validates the file and reports drift against `@claim <ID>` annotations in
+   source.
+2. **Probe** confirms the defenders are green N times unmodified, applies
+   each fault in a scratch git worktree (your tree is never touched), runs
+   the defenders N times, re-runs survivors against the whole suite with
+   N-run attribution, restores, and classifies. Verdicts are a closed set:
+
+   | Verdict | Meaning |
+   |---|---|
+   | `killed` | a test body rejected the behaviour, N/N — the only pass |
+   | `SURVIVED` | the defenders stayed green while the claim was false |
+   | `NOCOVER` | no test file defends the claim at all |
+   | `UNVERIFIABLE` | the fault's anchor is missing or ambiguous — loud, never a skip |
+   | `TIMEOUT` | the defenders hung; a hang is not a detection |
+   | `FAULT-INVALID` | the replacement does not load — a bad fault, not a finding |
+   | `FLAKY-DEFENDER` | the defenders are not reliably green, or disagreed across runs |
+
+   Never a single score. Findings are ranked by severity, claim provenance
+   and blast radius, and written to `.testguard/evidence.json` — validated
+   against the spec before it is written.
+3. **Baseline** freezes every non-passing fingerprint. Later probes suppress
+   what was already known and exit non-zero only on what is new. Claims whose
+   source and defenders are unchanged reuse their prior verdict, so a probe
+   in CI costs only what changed.
+4. **Brief** turns evidence plus baseline into a ranked, capped
+   `## TEST BLINDSPOT CONTEXT` block. Wire it into an agent's session start
+   — for Claude Code, in `.claude/settings.json`:
+
+   ```json
+   { "hooks": { "SessionStart": [ { "hooks": [
+     { "type": "command", "command": "npx testguard-cli brief --text" }
+   ] } ] } }
+   ```
+
+   `--text` prints only, and exits 0 silently when there is no evidence yet,
+   so the hook can never break a session.
+
+**Commit `.testguard/baseline.json`; ignore `evidence.json` and `brief.json`.**
+The baseline is the frozen contract; the other two are regenerated per run.
+
+The fault model is the auditable artifact. You never reach 100% of
+correctness; you reach **100% of stated claims verified**, and the statement
+of claims is what an assessor reads. A claims file is code — its `replace`
+strings run under your test runner — so review it like code.
+
+## Try it
+
+The repository ships a known-answer fixture with a real blind spot:
+
+```bash
+git clone <this repo> && cd testguard && npm install
+npm test                                  # includes probing the fixture end to end
+```
+
+`fixtures/known-answer/` is a tiny project whose audit-row test asserts with
+`expect.objectContaining({...})` and omits the `content` key. Swap the
+redacted text for the raw input and the test stays green. `probe` reports it
+as `SURVIVED`; the fixture's [README](fixtures/known-answer/README.md) walks
+through every verdict.
+
+## Status
+
+**v0.1.** Four commands, vitest runner, hand-authored faults. The contract
+spine — six JSON Schemas shared with the other Guard tools — is under
+[`spec/`](spec/). Zero runtime dependencies; Node ≥ 20.
+
+Not yet: test generation (the two-gate acceptance loop), other runners,
+mechanical fault producers, and calibration of fault classes against real
+escaped bugs. Each is designed for; none is claimed.
+
+## Licence
+
+MIT.

testguard_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+testguard_cli/__init__.py,sha256=8sGzMplmVqpmyu5Q1OrgDrs-AUUBVLqVEqCyXBoV_3k,83
+testguard_cli/wrapper.py,sha256=24oBMXAiHuFz9K32ggrD1tk_8oq1iBLcWXIdjrLowbk,2581
+testguard_cli-0.1.0.dist-info/METADATA,sha256=cC5fZuV1VwmO--67BY5S2CRs_DwJGh1eDSS6bx1LeCk,7716
+testguard_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+testguard_cli-0.1.0.dist-info/entry_points.txt,sha256=b-DAHthznWkLRH9h5URsjvAJNFlyqbNENKAwVun81IY,57
+testguard_cli-0.1.0.dist-info/licenses/LICENSE,sha256=gQ9PJNsgxXTDVYfhspPfwlj1ba3MeDnbL8G0dqN2jLE,1072
+testguard_cli-0.1.0.dist-info/RECORD,,

testguard_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

testguard_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+testguard = testguard_cli.wrapper:main

testguard_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Accioly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.