testguard-cli 0.1.3__tar.gz → 0.2.0__tar.gz

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/.github/scripts/install-smoke.mjs

@@ -30,6 +30,8 @@ try {
   const bin = join(consumer, 'node_modules', '.bin', process.platform === 'win32' ? 'testguard.cmd' : 'testguard');
   const version = run(bin, ['--version'], consumer).trim();
   const claims = run(bin, ['claims', '.'], consumer);
+  const draft = JSON.parse(run(bin, ['scaffold', 'src/redact.mjs', '--json'], consumer));
+  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}`);
   const deps = Object.keys(JSON.parse(run(npm, ['ls', '--omit=dev', '--json', '--depth=0'], consumer)).dependencies ?? {});

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/AGENTS.md

@@ -19,6 +19,7 @@ npm run test:spec      # conformance suite only
 npm run self:probe     # TestGuard probes its own claims; must exit 0
 npm run test:install   # the packed tarball must run with production deps only
 node cli/testguard.mjs claims fixtures/known-answer
+node cli/testguard.mjs scaffold src/probe/classify.mjs --json   # what the producers propose for a file
 ```
 
 ## Key files
@@ -29,6 +30,7 @@ node cli/testguard.mjs claims fixtures/known-answer
 - `src/probe/probe.mjs` — orchestrator: isolation → baseline (cached per defender set) → apply → probe → escalate → restore → classify → rank.
 - `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.
 
 ## Rules
 

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-17
+
+### Added
+
+- **`testguard scaffold <file>`** — mechanical fault producer (#6). Proposes
+  the five shapes both field reports found behind ~80% of hand-written
+  faults: guard forced false, single-line guard or state change removed,
+  `return <check>` → `return true`, security literal weakened, check call
+  removed. Every proposal is an exact-line anchor with `expectHits` and
+  `occurrence` computed from the file (verifiable by construction; anything
+  `locate()` would reject is never emitted), `producedBy: derived`,
+  `defendedBy` prefilled from the tests that import the module, grouped
+  under a preceding `@claim` annotation or by enclosing function.
+  Statements are `TODO:` placeholders; the output is a draft under
+  `.testguard/`, never the claims file. `--claim <ID>` puts everything under
+  one claim and copies it if it exists; `--json` prints instead.
+- Self-claim `TG-SCAFFOLD-ANCHORS-HIT`; install smoke exercises `scaffold`.
+
 ## [0.1.3] - 2026-09-17
 
 From a second field report on a real codebase (456 tests, 27 claims, 35

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.1.3
+Version: 0.2.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.1.3` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.2.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
@@ -90,6 +90,7 @@ npx testguard-cli claims      # what does this project claim, and is every claim
 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
+npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to keep or drop
 ```
 
 1. **Claims** live in `testguard.claims.json` (editors validate it against
@@ -159,6 +160,34 @@ npx testguard-cli brief       # tell the agent where the suite is blind, before
    `--text` prints only, and exits 0 silently when there is no evidence yet,
    so the hook can never break a session.
 
+### Authoring faults mechanically
+
+Writing faults by hand means reading the code to find exact anchors. Two
+field reports found that ~80% of hand-written faults are one of five shapes,
+so `scaffold` proposes them for you:
+
+```bash
+npx testguard-cli scaffold src/auth.ts          # → .testguard/scaffold-auth.json (a draft, never your claims file)
+npx testguard-cli scaffold src/auth.ts --claim AUTH-ADMIN   # every proposal under one claim; copies it if it exists
+```
+
+| Shape | What it proposes |
+|---|---|
+| `condition-forced` | `if (<guard>) {` → `if (false) {` — a guard is a `!…` condition or one whose body returns, throws or 4xx-es |
+| `statement-deleted` | a single-line guard (`if (…) return …;`) or a state change (`x = …;`) removed |
+| `return-altered` | `return <check>;` (`===`, `.includes(`, `&&`, …) → `return true;` |
+| `literal-changed` | `httpOnly`/`secure` flipped, `sameSite` → `none`, a cost/rounds → `1`, a ttl/tolerance/window/limit ×1000 |
+| `call-removed` | a bare `verify…()` / `validate…()` / `check…()` / `authorize…()` call removed |
+
+Every proposal's `find` is the exact line with `expectHits`/`occurrence`
+computed from the file, so it is verifiable by construction; provenance is
+`producer: derived`; `defendedBy` is prefilled from the tests that import
+the module; proposals are grouped under a preceding `@claim <ID>` annotation
+or by enclosing function. Statements are `TODO:` placeholders — a proposal
+becomes a claim only when a human states what it defends. Deterministic
+heuristics, no AST, no LLM; a proposal the tool cannot anchor is never
+emitted.
+
 **Commit `.testguard/baseline.json`; ignore `evidence.json` and `brief.json`.**
 The baseline is the frozen contract; the other two are regenerated per run.
 
@@ -184,13 +213,14 @@ through every verdict.
 
 ## Status
 
-**v0.1.** Four commands, vitest runner, hand-authored faults. The contract
+**v0.2.** Five commands, vitest runner, hand-authored faults plus a
+mechanical scaffold for the five common shapes. 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,
-mechanical fault producers, and calibration of fault classes against real
-escaped bugs. Each is designed for; none is claimed.
+AST-aware producers, and calibration of fault classes against real escaped
+bugs. Each is designed for; none is claimed.
 
 ## Licence
 

{testguard_cli-0.1.3 → testguard_cli-0.2.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.1.3` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.2.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
@@ -66,6 +66,7 @@ npx testguard-cli claims      # what does this project claim, and is every claim
 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
+npx testguard-cli scaffold src/x.ts   # propose faults for a file, as a draft to keep or drop
 ```
 
 1. **Claims** live in `testguard.claims.json` (editors validate it against
@@ -135,6 +136,34 @@ npx testguard-cli brief       # tell the agent where the suite is blind, before
    `--text` prints only, and exits 0 silently when there is no evidence yet,
    so the hook can never break a session.
 
+### Authoring faults mechanically
+
+Writing faults by hand means reading the code to find exact anchors. Two
+field reports found that ~80% of hand-written faults are one of five shapes,
+so `scaffold` proposes them for you:
+
+```bash
+npx testguard-cli scaffold src/auth.ts          # → .testguard/scaffold-auth.json (a draft, never your claims file)
+npx testguard-cli scaffold src/auth.ts --claim AUTH-ADMIN   # every proposal under one claim; copies it if it exists
+```
+
+| Shape | What it proposes |
+|---|---|
+| `condition-forced` | `if (<guard>) {` → `if (false) {` — a guard is a `!…` condition or one whose body returns, throws or 4xx-es |
+| `statement-deleted` | a single-line guard (`if (…) return …;`) or a state change (`x = …;`) removed |
+| `return-altered` | `return <check>;` (`===`, `.includes(`, `&&`, …) → `return true;` |
+| `literal-changed` | `httpOnly`/`secure` flipped, `sameSite` → `none`, a cost/rounds → `1`, a ttl/tolerance/window/limit ×1000 |
+| `call-removed` | a bare `verify…()` / `validate…()` / `check…()` / `authorize…()` call removed |
+
+Every proposal's `find` is the exact line with `expectHits`/`occurrence`
+computed from the file, so it is verifiable by construction; provenance is
+`producer: derived`; `defendedBy` is prefilled from the tests that import
+the module; proposals are grouped under a preceding `@claim <ID>` annotation
+or by enclosing function. Statements are `TODO:` placeholders — a proposal
+becomes a claim only when a human states what it defends. Deterministic
+heuristics, no AST, no LLM; a proposal the tool cannot anchor is never
+emitted.
+
 **Commit `.testguard/baseline.json`; ignore `evidence.json` and `brief.json`.**
 The baseline is the frozen contract; the other two are regenerated per run.
 
@@ -160,13 +189,14 @@ through every verdict.
 
 ## Status
 
-**v0.1.** Four commands, vitest runner, hand-authored faults. The contract
+**v0.2.** Five commands, vitest runner, hand-authored faults plus a
+mechanical scaffold for the five common shapes. 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,
-mechanical fault producers, and calibration of fault classes against real
-escaped bugs. Each is designed for; none is claimed.
+AST-aware producers, and calibration of fault classes against real escaped
+bugs. Each is designed for; none is claimed.
 
 ## Licence
 

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/action.yml

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

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/package-lock.json

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

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Proves a test suite defends the claims a project makes: injects the faults those claims forbid and reports every one the tests fail to detect.",
   "type": "module",
   "license": "MIT",

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/packaging/homebrew/testguard.rb

@@ -13,7 +13,7 @@
 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.1.3.tgz"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.2.0.tgz"
   sha256 "385d69f9d3c153b934d9c1cb6a2c754eb9b221b0a8c0ba8b805858384d2d4678"
   license "MIT"
 

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.1.3"
+version = "0.2.0"
 description = "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+)."
 readme = "README.md"
 license = { text = "MIT" }

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/src/cli.mjs

@@ -10,6 +10,7 @@ import { probeCommand } from './commands/probe.mjs';
 import { claimsCommand } from './commands/claims.mjs';
 import { baselineCommand } from './commands/baseline.mjs';
 import { briefCommand } from './commands/brief.mjs';
+import { scaffoldCommand } from './commands/scaffold.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 
@@ -19,6 +20,7 @@ const USAGE = `testguard ${VERSION} — proves a test suite defends the claims a
   testguard probe [dir]      inject each claim's faults, run its defenders, report what survived
   testguard baseline [dir]   freeze today's unproven findings so only new ones gate
   testguard brief [dir]      emit the blind-spot block for an agent's session-start context
+  testguard scaffold <file>  propose faults mechanically for one source file, as a draft claims document
 
 probe
   --claims <path>      claims file             (default: <dir>/testguard.claims.json)
@@ -38,6 +40,9 @@ probe
   --no-reuse           re-probe claims whose inputs have not changed
   --quiet              suppress the per-fault stream and ranked block; print only the summary and evidence path
 
+scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
+           shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
+                   · security flag/window/cost literal weakened · verify/validate/check call removed
 claims     --json
 baseline   --evidence <path>  --out <path>
 brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only; safe for hooks)
@@ -45,7 +50,7 @@ brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only;
 exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift) · 2 precondition failed · 3 usage
 `;
 
-const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand };
+const COMMANDS = { probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -104,7 +109,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     return 3;
   }
   try {
-    return await handler({ projectDir: resolve(dirArg ?? '.'), values, version: VERSION }, io);
+    const projectDir = command === 'scaffold' ? resolve('.') : resolve(dirArg ?? '.');
+    return await handler({ projectDir, file: dirArg, values, version: VERSION }, io);
   } catch (e) {
     if (e instanceof ClaimsError || e instanceof PreconditionError || e instanceof GitError || e instanceof SpecDocError) {
       io.err(`error: ${e.message}`);

testguard_cli-0.2.0/src/commands/scaffold.mjs

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs';
+import { join, resolve, relative, basename, extname } from 'node:path';
+import { scaffoldFile } from '../scaffold/scaffold.mjs';
+import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+import { PreconditionError } from '../probe/worktree.mjs';
+
+export async function scaffoldCommand({ projectDir, file, values, version }, io) {
+  if (!file) {
+    io.err('usage: testguard scaffold <source-file> [--claim <ID>] [--out <path>] [--json]');
+    return 3;
+  }
+  const abs = resolve(file);
+  if (!existsSync(abs)) throw new PreconditionError(`no such file: ${file}`);
+  const rel = relative(projectDir, abs);
+  if (rel.startsWith('..')) throw new PreconditionError(`${file} is outside the project directory ${projectDir}`);
+
+  const claimsPath = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
+  const existingClaims = existsSync(claimsPath) ? loadClaims(claimsPath) : undefined;
+  const { doc, stats } = scaffoldFile({ projectDir, file: rel, claimId: values.claim, existingClaims, toolVersion: version });
+
+  if (values.json) {
+    io.out(JSON.stringify(doc, null, 2));
+    return 0;
+  }
+  const outPath = values.out ? resolve(values.out) : join(projectDir, '.testguard', `scaffold-${basename(rel, extname(rel))}.json`);
+  writeSpecDoc('claims', outPath, doc);
+  const shapes = Object.entries(stats.byClass).map(([k, v]) => `${v} ${k}`).join(', ');
+  io.out(`${stats.proposals} proposed fault${stats.proposals === 1 ? '' : 's'} in ${stats.claims} draft claim${stats.claims === 1 ? '' : 's'} for ${rel}${shapes ? ` — ${shapes}` : ''}`);
+  io.out(stats.defendedBy.length ? `defendedBy prefilled from imports: ${stats.defendedBy.join(', ')}` : 'no test file imports this module; probing the draft as-is will report NOCOVER');
+  io.out(`draft: ${outPath}`);
+  io.out('Next: replace each TODO statement, drop proposals that are not claims, then move the claims into testguard.claims.json.');
+  return 0;
+}

testguard_cli-0.2.0/src/scaffold/producers.mjs

@@ -0,0 +1,85 @@
+/**
+ * Mechanical fault producers. Deterministic, line-oriented, no AST, no LLM.
+ *
+ * Two independent field reports found that ~80% of hand-written faults are
+ * one of these shapes. Each producer looks at one line (plus a little
+ * context) and proposes a fault whose `find` is the exact line, so the anchor
+ * hits by construction. A human keeps or drops every proposal.
+ */
+
+const COMMENT = /^\s*(\/\/|\*|\/\*)/;
+const GUARD_BODY = /\b(return|throw)\b|\.status\(\s*4\d\d|\bredirect\(|\bfalse\b|\bnull\b/;
+const IF_LINE = /^(\s*)(?:\}\s*)?(?:else\s+)?if\s*\((.+)\)\s*(\{\s*|(?:return|throw)\b.*;\s*)?$/;
+const RETURN_CHECK = /^\s*return\s+(.+);\s*$/;
+const CHECK_EXPR = /(===|!==|\.includes\(|\.has\(|\.some\(|\.every\(|\.test\(|\.startsWith\(|\.endsWith\(|\binstanceof\b|&&|\|\||^!)/;
+const CHECK_CALL = /^\s*(?:await\s+)?(?:[\w$]+\.)*(verify|validate|assert|check|require|ensure|authoriz|authentic|rateLimit|throttle|enforce|guard)\w*\s*\(.*\)\s*;\s*$/i;
+const MUTATION = /^\s*(?!(?:const|let|var|return|if|for|while|else|switch|case|import|export|throw)\b)[\w$]+(?:[.\[][\w$'"\]]+)*\s*(=|\+=|-=|\|\|=|&&=|\?\?=)\s*(?!=)[^;]*;\s*$/;
+const FLAG_TRUE = /\b(httpOnly|secure|signed|requireTLS|rejectUnauthorized|strict)\s*:\s*true\b/;
+const SAME_SITE = /\bsameSite\s*:\s*(['"])(strict|lax)\1/i;
+const COST_NUM = /\b(\w*(?:cost|rounds|iterations)\w*)\s*([:=])\s*(\d+)\b/i;
+const WINDOW_NUM = /\b(\w*(?:ttl|expir|tolerance|window|maxAge|max_age|timeout|limit|attempts|length|minLength|clockSkew|skew)\w*)\s*([:=])\s*(\d+)\b/i;
+const FUNCTION_HEAD = [
+  /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([\w$]+)\s*\(/,
+  /^\s*(?:export\s+)?(?:const|let|var)\s+([\w$]+)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[\w$]+)\s*=>/,
+  /^\s*(?:export\s+)?(?:const|let|var)\s+([\w$]+)\s*=\s*(?:async\s+)?function\b/,
+  /^\s*(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:async\s+)?([\w$]+)\s*\([^)]*\)\s*(?::\s*[\w<>\[\]| ]+)?\s*\{\s*$/,
+];
+const NOT_A_FUNCTION = new Set(['if', 'for', 'while', 'switch', 'catch', 'else', 'return', 'function', 'constructor']);
+
+/** Name of the function whose head is on this line, or null. */
+export function functionHead(line) {
+  for (const re of FUNCTION_HEAD) {
+    const m = re.exec(line);
+    if (m && !NOT_A_FUNCTION.has(m[1])) return m[1];
+  }
+  return null;
+}
+
+function isGuard(cond, lines, i) {
+  if (/^\s*!/.test(cond)) return true;
+  const tail = lines.slice(i, i + 4).join('\n');
+  return GUARD_BODY.test(tail);
+}
+
+/** Proposals for one line. Each: { faultClass, description, replace } where find is the line itself. */
+export function proposalsForLine(lines, i) {
+  const line = lines[i];
+  const out = [];
+  if (!line.trim() || COMMENT.test(line)) return out;
+
+  const ifm = IF_LINE.exec(line);
+  if (ifm && isGuard(ifm[2], lines, i)) {
+    const singleLine = ifm[3] && /^(return|throw)\b/.test(ifm[3].trim());
+    if (singleLine) {
+      out.push({ faultClass: 'statement-deleted', description: `Guard removed: \`${line.trim()}\` no longer runs.`, replace: '' });
+    } else {
+      out.push({ faultClass: 'condition-forced', description: `Guard never triggers: \`if (${ifm[2].trim()})\` becomes \`if (false)\`.`, replace: line.replace(`(${ifm[2]})`, '(false)') });
+    }
+    return out; // an `if` line is not also a mutation/return/call
+  }
+
+  const rm = RETURN_CHECK.exec(line);
+  if (rm && CHECK_EXPR.test(rm[1]) && !/^(new|await)\b/.test(rm[1].trim())) {
+    out.push({ faultClass: 'return-altered', description: `Check always passes: \`return ${rm[1].trim()}\` becomes \`return true\`.`, replace: line.replace(/return\s+.+;/, 'return true;') });
+  }
+
+  if (CHECK_CALL.test(line)) {
+    out.push({ faultClass: 'call-removed', description: `Check call removed: \`${line.trim()}\` no longer runs.`, replace: '' });
+  } else if (MUTATION.test(line)) {
+    out.push({ faultClass: 'statement-deleted', description: `State change removed: \`${line.trim()}\` no longer runs.`, replace: '' });
+  }
+
+  let m;
+  if ((m = FLAG_TRUE.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Security flag flipped: \`${m[1]}: true\` becomes \`${m[1]}: false\`.`, replace: line.replace(m[0], `${m[1]}: false`) });
+  }
+  if ((m = SAME_SITE.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `sameSite weakened: \`${m[2]}\` becomes \`none\`.`, replace: line.replace(m[0], `sameSite: ${m[1]}none${m[1]}`) });
+  }
+  if ((m = COST_NUM.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Work factor collapsed: \`${m[1]}\` ${m[3]} becomes 1.`, replace: line.replace(m[0], `${m[1]}${m[2] === ':' ? ': ' : ' = '}1`) });
+  } else if ((m = WINDOW_NUM.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Window widened ×1000: \`${m[1]}\` ${m[3]} becomes ${Number(m[3]) * 1000}.`, replace: line.replace(m[0], `${m[1]}${m[2] === ':' ? ': ' : ' = '}${Number(m[3]) * 1000}`) });
+  }
+  return out;
+}

testguard_cli-0.2.0/src/scaffold/scaffold.mjs

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { proposalsForLine, functionHead } from './producers.mjs';
+import { locate } from '../probe/inject.mjs';
+import { discoverDefenders } from '../probe/discover.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
+
+const ANNOTATION = /@claim\s+([A-Za-z0-9]+(?:[._]?[A-Za-z0-9]+)*-[A-Za-z0-9._-]*[A-Za-z0-9])\b/;
+
+const idPart = (s) => s.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').toUpperCase();
+
+/** How many times `find` occurs, and which occurrence the line at `offset` is. */
+function anchorFor(source, find, offset) {
+  let hits = 0;
+  let occurrence = 0;
+  let i = -1;
+  while ((i = source.indexOf(find, i + 1)) !== -1) {
+    hits++;
+    if (i === offset) occurrence = hits;
+  }
+  return { hits, occurrence };
+}
+
+/**
+ * Scan one source file and produce a DRAFT claims document: every proposal is
+ * an exact-line anchor that `locate()` accepts, grouped by enclosing function
+ * (or by a preceding `@claim <ID>` annotation, or entirely under `claimId`),
+ * with `producedBy: { producer: "derived" }` and TODO statements a human must
+ * replace. Never touches the real claims file.
+ */
+export function scaffoldFile({ projectDir, file, claimId, existingClaims, toolVersion = '0.0.0' }) {
+  const source = readFileSync(join(projectDir, file), 'utf8');
+  const lines = source.split('\n');
+  const stem = idPart(basename(file, extname(file)));
+  const producedBy = { producer: 'derived', by: `testguard scaffold ${toolVersion}` };
+
+  const groups = new Map(); // key → { id, proposals[] , annotated }
+  const groupFor = (key, id) => {
+    if (!groups.has(key)) groups.set(key, { id, proposals: [] });
+    return groups.get(key);
+  };
+
+  let offset = 0;
+  let fn = null;
+  let fnDepth = 0;
+  let depth = 0;
+  let pendingAnnotation = null;
+  const proposals = [];
+  lines.forEach((line, i) => {
+    const ann = ANNOTATION.exec(line);
+    if (ann && /^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = ann[1];
+
+    const head = functionHead(line);
+    if (head) {
+      fn = head;
+      fnDepth = depth;
+    }
+
+    for (const p of proposalsForLine(lines, i)) {
+      const find = line;
+      const { hits, occurrence } = anchorFor(source, find, offset);
+      const fault = { ...p, find, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
+      if (locate(source, fault).status !== 'ok') continue; // never propose an anchor that would be unverifiable
+      proposals.push(fault);
+    }
+
+    depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
+    if (fn && depth <= fnDepth && !head) fn = null;
+    if (pendingAnnotation && !ann && !head && line.trim() && !/^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = null;
+    offset += line.length + 1;
+  });
+
+  const existing = new Map((existingClaims?.claims ?? []).map((c) => [c.id, c]));
+  const usedIds = new Set();
+  for (const p of proposals) {
+    const key = claimId ? '__all__' : p.annotation ?? p.fn ?? '__file__';
+    let id = claimId ?? p.annotation ?? `${stem}-${p.fn ? idPart(p.fn) : 'FILE'}`;
+    groupFor(key, id).proposals.push(p);
+  }
+
+  const defendedBy = discoverDefenders(projectDir, file);
+  const claims = [];
+  for (const g of groups.values()) {
+    let id = g.id;
+    while (usedIds.has(id)) id += '-2';
+    usedIds.add(id);
+    const base = existing.get(id);
+    const fnLabel = g.proposals[0].fn ? `\`${g.proposals[0].fn}\`` : 'this file';
+    const claim = {
+      id,
+      statement: base?.statement ?? `TODO: state what ${fnLabel} in ${file} guarantees (${g.proposals.length} proposed fault${g.proposals.length === 1 ? '' : 's'}; keep or drop each)`,
+      source: base?.source ?? { kind: 'manual', ref: `testguard scaffold ${file}` },
+      severity: base?.severity ?? 'medium',
+      producedBy: base?.producedBy ?? producedBy,
+      ...(base?.defendedBy?.length ? { defendedBy: base.defendedBy } : defendedBy.length ? { defendedBy } : {}),
+      faults: g.proposals.map((p, n) => ({
+        id: `S${n + 1}`,
+        description: `[line ${p.line}] ${p.description}`,
+        faultClass: p.faultClass,
+        file,
+        find: p.find,
+        replace: p.replace,
+        ...(p.expectHits > 1 ? { expectHits: p.expectHits, occurrence: p.occurrence } : {}),
+        producedBy,
+      })),
+      ...(base?.tags ? { tags: base.tags } : {}),
+    };
+    claims.push(claim);
+  }
+
+  const doc = { $schema: './node_modules/testguard-cli/spec/schemas/claims.schema.json', schemaVersion: 1, claims };
+  const result = validate('claims', doc);
+  if (!result.ok) throw new Error(`scaffold produced a non-conforming draft:\n${result.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n')}`);
+
+  const byClass = {};
+  for (const p of proposals) byClass[p.faultClass] = (byClass[p.faultClass] ?? 0) + 1;
+  return { doc, stats: { proposals: proposals.length, claims: claims.length, byClass, defendedBy } };
+}

testguard_cli-0.2.0/test/scaffold.test.mjs

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scaffoldFile } from '../src/scaffold/scaffold.mjs';
+import { proposalsForLine, functionHead } from '../src/scaffold/producers.mjs';
+import { locate } from '../src/probe/inject.mjs';
+import { validate } from '../spec/lib/validate.mjs';
+import { main } from '../src/cli.mjs';
+
+const FIXTURE = join(dirname(fileURLToPath(import.meta.url)), '..', 'fixtures', 'known-answer');
+const capture = () => { const lines = { out: [], err: [] }; return { lines, io: { out: (s) => lines.out.push(s), err: (s) => lines.err.push(s) } }; };
+
+describe('scaffold on the known-answer fixture', () => {
+  const { doc, stats } = scaffoldFile({ projectDir: FIXTURE, file: 'src/redact.mjs', toolVersion: 'test' });
+  const all = doc.claims.flatMap((c) => c.faults.map((f) => ({ claim: c, ...f })));
+
+  it('produces a conforming draft whose every anchor locates exactly as declared', () => {
+    expect(validate('claims', doc).errors).toEqual([]);
+    const source = readFileSync(join(FIXTURE, 'src/redact.mjs'), 'utf8');
+    for (const f of all) expect(locate(source, f).status, f.description).toBe('ok');
+    expect(all.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('proposes the shape-expressible fixture faults by anchor: the fail-closed guard and the masking mutation', () => {
+    const guard = all.find((f) => f.find.includes('if (!ctx || !ctx.scope) {'));
+    expect(guard).toMatchObject({ faultClass: 'condition-forced' });
+    expect(guard.replace.trim()).toBe('if (false) {');
+    const mutation = all.find((f) => f.find.includes("out = out.replace(rule.re, (m) => '*'.repeat(m.length));"));
+    expect(mutation).toMatchObject({ faultClass: 'statement-deleted', replace: '' });
+  });
+
+  it('groups the guard under its @claim annotation and everything else by enclosing function', () => {
+    expect(doc.claims.map((c) => c.id).sort()).toEqual(['REDACT-003', 'REDACT-FINDRULE', 'REDACT-MASK']);
+    expect(doc.claims.find((c) => c.id === 'REDACT-MASK').statement).toMatch(/^TODO: state what `mask`/);
+  });
+
+  it('prefills defendedBy from discovery, marks provenance derived, never touches the claims file', () => {
+    for (const c of doc.claims) {
+      expect(c.defendedBy).toEqual(['test/redact.test.mjs']);
+      expect(c.producedBy.producer).toBe('derived');
+      for (const f of c.faults) expect(f.producedBy).toMatchObject({ producer: 'derived', by: 'testguard scaffold test' });
+    }
+    expect(stats.defendedBy).toEqual(['test/redact.test.mjs']);
+  });
+});
+
+describe('scaffold producers on a synthetic security module', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tg-scaffold-'));
+  mkdirSync(join(dir, 'src'));
+  mkdirSync(join(dir, 'test'));
+  writeFileSync(join(dir, 'src', 'auth.ts'), `import bcrypt from 'bcrypt';
+export const COOKIE = { httpOnly: true, secure: true, sameSite: 'strict', maxAge: 3600 };
+const BCRYPT_COST = 12;
+const tolerance = 300;
+export function isAdmin(user) {
+  return user.roles.includes('admin');
+}
+export async function handle(req, res) {
+  if (!req.user) return res.status(401).end();
+  if (!isAdmin(req.user)) {
+    return res.status(403).end();
+  }
+  await verifySignature(req);
+  req.session.touched = Date.now();
+  req.session.touched = Date.now();
+  return next();
+}
+`);
+  writeFileSync(join(dir, 'test', 'auth.test.ts'), "import { handle } from '../src/auth';\n");
+  writeFileSync(join(dir, 'testguard.claims.json'), JSON.stringify({ schemaVersion: 1, claims: [{ id: 'AUTH-ADMIN', statement: 'Only admins pass.', source: { kind: 'spec', ref: 'x' }, severity: 'critical', producedBy: { producer: 'human' }, defendedBy: ['test/auth.test.ts'], faults: [{ id: 'F1', description: 'd', faultClass: 'other', file: 'src/auth.ts', find: 'next()', replace: 'nope()', producedBy: { producer: 'human' } }] }] }));
+  const { doc } = scaffoldFile({ projectDir: dir, file: 'src/auth.ts', toolVersion: 'test' });
+  const all = doc.claims.flatMap((c) => c.faults);
+  const byClass = (k) => all.filter((f) => f.faultClass === k);
+
+  it('covers all five shapes', () => {
+    expect(byClass('literal-changed').map((f) => f.replace.trim())).toEqual(expect.arrayContaining([
+      expect.stringContaining('httpOnly: false'), expect.stringContaining("sameSite: 'none'"), expect.stringContaining('BCRYPT_COST = 1;'), expect.stringContaining('tolerance = 300000;'),
+    ]));
+    expect(byClass('return-altered')[0].replace.trim()).toBe('return true;');
+    expect(byClass('statement-deleted').map((f) => f.find.trim())).toEqual(expect.arrayContaining(['if (!req.user) return res.status(401).end();', 'req.session.touched = Date.now();']));
+    expect(byClass('condition-forced')[0].replace.trim()).toBe('if (false) {');
+    expect(byClass('call-removed')[0].find.trim()).toBe('await verifySignature(req);');
+  });
+
+  it('computes expectHits/occurrence for a duplicated line so both anchors locate', () => {
+    const dupes = all.filter((f) => f.find.trim() === 'req.session.touched = Date.now();');
+    expect(dupes.map((f) => [f.expectHits, f.occurrence])).toEqual([[2, 1], [2, 2]]);
+    const source = readFileSync(join(dir, 'src', 'auth.ts'), 'utf8');
+    for (const f of all) expect(locate(source, f).status).toBe('ok');
+    expect(validate('claims', doc).ok).toBe(true);
+  });
+
+  it('--claim puts everything under one claim and copies an existing claim\'s statement, severity and defenders', () => {
+    const existing = JSON.parse(readFileSync(join(dir, 'testguard.claims.json'), 'utf8'));
+    const { doc: one } = scaffoldFile({ projectDir: dir, file: 'src/auth.ts', claimId: 'AUTH-ADMIN', existingClaims: existing, toolVersion: 'test' });
+    expect(one.claims).toHaveLength(1);
+    expect(one.claims[0]).toMatchObject({ id: 'AUTH-ADMIN', statement: 'Only admins pass.', severity: 'critical', defendedBy: ['test/auth.test.ts'] });
+    expect(one.claims[0].faults.length).toBe(all.length);
+  });
+
+  it('CLI writes the draft beside the evidence, prints the shapes, and refuses a missing file', async () => {
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      const a = capture();
+      expect(await main(['scaffold', 'src/auth.ts'], a.io)).toBe(0);
+      expect(a.lines.out[0]).toMatch(/^\d+ proposed faults in \d+ draft claims for src\/auth\.ts — /);
+      expect(existsSync(join(dir, '.testguard', 'scaffold-auth.json'))).toBe(true);
+      expect(readFileSync(join(dir, 'testguard.claims.json'), 'utf8')).toContain('"AUTH-ADMIN"'); // untouched
+      const b = capture();
+      expect(await main(['scaffold', 'src/nope.ts'], b.io)).toBe(2);
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+});
+
+describe('producer edge cases', () => {
+  it('recognises function heads and ignores control keywords', () => {
+    expect(functionHead('export async function handle(req) {')).toBe('handle');
+    expect(functionHead('const isAdmin = (u) => u.admin;')).toBe('isAdmin');
+    expect(functionHead('  async verify(token) {')).toBe('verify');
+    expect(functionHead('  if (x) {')).toBeNull();
+    expect(functionHead('  } catch (e) {')).toBeNull();
+  });
+  it('does not treat a comparison or a declaration as a mutation, nor a non-guard if as a guard', () => {
+    expect(proposalsForLine(['  const a = b;'], 0)).toEqual([]);
+    expect(proposalsForLine(['  if (a === b) {', '    count++;', '  }'], 0)).toEqual([]);
+    expect(proposalsForLine(['  // if (!x) return;'], 0)).toEqual([]);
+  });
+});

{testguard_cli-0.1.3 → testguard_cli-0.2.0}/testguard.claims.json

@@ -311,6 +311,37 @@
           }
         }
       ]
+    },
+    {
+      "id": "TG-SCAFFOLD-ANCHORS-HIT",
+      "statement": "Every fault scaffold proposes carries an expectHits/occurrence computed from the real source, so the anchor is verifiable by construction even when the line is duplicated.",
+      "source": {
+        "kind": "spec",
+        "ref": "issue #6 acceptance"
+      },
+      "severity": "high",
+      "producedBy": {
+        "producer": "human",
+        "by": "maintainer",
+        "at": "2026-09-17T00:00:00Z"
+      },
+      "defendedBy": [
+        "test/scaffold.test.mjs"
+      ],
+      "faults": [
+        {
+          "id": "F1",
+          "description": "expectHits is always declared as 1; a duplicated line becomes anchor-ambiguous.",
+          "faultClass": "literal-changed",
+          "file": "src/scaffold/scaffold.mjs",
+          "find": "...(p.expectHits > 1 ? { expectHits: p.expectHits, occurrence: p.occurrence } : {}),",
+          "replace": "...{},",
+          "producedBy": {
+            "producer": "human",
+            "by": "maintainer"
+          }
+        }
+      ]
     }
   ]
 }