brainblast 0.3.0 → 0.4.1

package/README.md

@@ -11,10 +11,52 @@ parses your code statically and runs offline.
 npx brainblast .            # scan the repo, write .agent-research/report.json
 npx brainblast . --ci       # exit 1 if a confirmed FAIL remains
 npx brainblast . --ci --strict   # also fail on CANT_TELL (can't statically prove)
+npx brainblast . --since origin/main   # diff-aware: only audit what changed
 ```
 
 Exit codes: **0** clean · **1** a confirmed FAIL · CANT_TELL is a warning by
-default (a red build always means a real, confirmed problem).
+default (a red build always means a real, confirmed problem). `2` means
+`--since <ref>` could not run `git diff` (bad ref, or not a git work tree).
+
+### Diff-aware scanning (`--since <ref>`)
+
+`--since <ref>` audits only what's changed relative to `<ref>` (any git
+revision: a branch, `HEAD~1`, a commit SHA): TS/Rust functions whose line
+range overlaps `git diff <ref>`, and config/env files that changed at all.
+This makes brainblast fast enough to run on every commit or PR instead of a
+full-repo scan:
+
+```sh
+npx brainblast . --since origin/main   # CI: only the PR's diff
+npx brainblast . --since HEAD          # pre-commit/save hook: working tree changes
+```
+
+Living-memory precedents (see below) are still looked up and shown in
+`--since` mode, but the memory snapshot itself is only written on full
+(non-`--since`) runs — a partial diff-scan never overwrites the full picture.
+
+### Watch mode (`brainblast watch`)
+
+```sh
+npx brainblast watch .
+```
+
+Runs as a daemon: every time a file is saved, brainblast re-scans only the
+working-tree changes (uncommitted edits vs `HEAD`, plus untracked files —
+the "what did I just save?" view) and emits one **NDJSON event per line** on
+stdout:
+
+```json
+{"type":"watch_started","targetDir":"."}
+{"type":"finding","ruleId":"stripe-webhook-raw-body-verification","severity":"critical","result":"fail","file":"src/webhook.ts","line":3,"detail":"...","fix":{...}}
+{"type":"scan_complete","filesChanged":1,"findings":1,"durationMs":62}
+```
+
+Event types: `watch_started`, `finding` (one per FAIL/CANT_TELL), `scan_complete`
+(per debounced save, even if nothing changed), and `scan_error` (e.g. not a
+git work tree). This is the integration point for an agent daemon — tail
+stdout for structured findings instead of polling `.agent-research/report.json`.
+Exit with Ctrl-C / SIGTERM.
 
 ## What it catches
 
@@ -34,6 +76,12 @@ default (a red build always means a real, confirmed problem).
 | `metaplex-metadata-immutable` | `createV1` / `createNft` omits `isMutable: false` | Metadata defaults to mutable; any update authority can change the token's name, image, or attributes after launch |
 | `anchor-init-if-needed-guarded` | Anchor instruction uses `init_if_needed` without a re-initialization guard | Any user can reinitialize another user's account, overwriting its state |
 
+### Config / env
+
+| Rule | What's wrong | Consequence |
+|------|--------------|-------------|
+| `env-secrets-committed` | A `.env*` file (not `.env.example`/`.sample`/`.template`) is tracked by git and contains a secret-shaped key (`SECRET`, `*_PRIVATE_KEY`, `*_API_KEY`, `*_TOKEN`, `*_PASSWORD`, etc.) with a real-looking (non-placeholder) value | Anyone with read access to the repo — including forks of a public repo — can read the live credential |
+
 Each finding lands in `.agent-research/report.json` (stable `schemaVersion: "1.0"`)
 with a `checks[]` array a CI gate can read. Each confirmed FAIL ships a
 generated behavioral test (RED on vulnerable, GREEN on fixed).
@@ -116,7 +164,7 @@ All types are exported: `Rule`, `CheckResult`, `CostReport`, `AccountFlow`,
 
 ```sh
 npm install
-npm test         # unit suite (135 tests)
+npm test         # unit suite (164 tests)
 npm run prove    # end-to-end: generated tests RED on vulnerable, GREEN on fixed
 npm run build    # produce dist/ (the published artifact)
 ```

package/dist/{chunk-BZVZ3WAU.js → chunk-P7K7NRVN.js}

@@ -4,9 +4,10 @@ import { Project, SyntaxKind } from "ts-morph";
 // src/walk.ts
 import { readdirSync, statSync } from "fs";
 import { join } from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".gen", "dist", ".next", ".agent-research"]);
 function walk(dir, out = []) {
   for (const entry of readdirSync(dir)) {
-    if (entry === "node_modules" || entry === ".git" || entry === ".gen") continue;
+    if (SKIP_DIRS.has(entry)) continue;
     const p = join(dir, entry);
     const st = statSync(p);
     if (st.isDirectory()) walk(p, out);
@@ -14,6 +15,16 @@ function walk(dir, out = []) {
   }
   return out;
 }
+function walkAllFiles(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const p = join(dir, entry);
+    const st = statSync(p);
+    if (st.isDirectory()) walkAllFiles(p, out);
+    else out.push(p);
+  }
+  return out;
+}
 
 // src/finder.ts
 function bodyCallsAnyOf(fn, names) {
@@ -38,7 +49,13 @@ function findCandidates(targetDir, rule) {
     const sf = project.addSourceFileAtPath(file);
     const importsModule = sf.getImportDeclarations().some((d) => modules.has(d.getModuleSpecifierValue()));
     const consider = (fn, name) => {
-      if (!(importsModule || name && nameRe.test(name) || bodyCallsAnyOf(fn, triggers))) return;
+      const hasName = !!(name && nameRe.test(name));
+      const hasTrigger = bodyCallsAnyOf(fn, triggers);
+      if (rule.detect.requiresImport) {
+        if (!(importsModule && (hasName || hasTrigger))) return;
+      } else {
+        if (!(hasName || hasTrigger)) return;
+      }
       out.push({
         filePath: file,
         fnName: name || "(anonymous)",
@@ -55,6 +72,42 @@ function findCandidates(targetDir, rule) {
   return out;
 }
 
+// src/configFinder.ts
+import { execFileSync } from "child_process";
+import { readFileSync } from "fs";
+import { relative, sep } from "path";
+function isGitIgnored(targetDir, rel) {
+  try {
+    execFileSync("git", ["check-ignore", "-q", "--", rel], { cwd: targetDir, stdio: "ignore" });
+    return true;
+  } catch (e) {
+    if (typeof e?.status === "number") return false;
+    return false;
+  }
+}
+function findConfigCandidates(targetDir, rule) {
+  const patterns = (rule.detect.filePatterns ?? []).map((p) => new RegExp(p));
+  if (patterns.length === 0) return [];
+  const files = walkAllFiles(targetDir);
+  const out = [];
+  for (const file of files) {
+    const rel = relative(targetDir, file).split(sep).join("/");
+    if (!patterns.some((re) => re.test(rel))) continue;
+    let content;
+    try {
+      content = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    out.push({
+      filePath: file,
+      content,
+      tracked: !isGitIgnored(targetDir, rel)
+    });
+  }
+  return out;
+}
+
 // src/checkers/positionalArgIdentity.ts
 import { SyntaxKind as SyntaxKind2 } from "ts-morph";
 var positionalArgIdentity = (c, p) => {
@@ -62,7 +115,20 @@ var positionalArgIdentity = (c, p) => {
     const exp = call.getExpression();
     return exp.getKind() === SyntaxKind2.PropertyAccessExpression && exp.asKind(SyntaxKind2.PropertyAccessExpression).getName() === p.call;
   });
-  if (calls.length === 0) return { result: "fail", detail: p.absentDetail };
+  if (calls.length === 0) {
+    const sf = c.fn.getSourceFile();
+    const existsInFile = sf.getDescendantsOfKind(SyntaxKind2.CallExpression).some((call) => {
+      const exp = call.getExpression();
+      return exp.getKind() === SyntaxKind2.PropertyAccessExpression && exp.asKind(SyntaxKind2.PropertyAccessExpression).getName() === p.call;
+    });
+    if (existsInFile) {
+      return {
+        result: "cant_tell",
+        detail: `${p.call} is called elsewhere in this file; unable to confirm this function's delegation path statically.`
+      };
+    }
+    return { result: "fail", detail: p.absentDetail };
+  }
   const arg = calls[0].getArguments()[p.argIndex];
   const wantParam = c.params[p.paramIndex];
   if (arg && wantParam && arg.getKind() === SyntaxKind2.Identifier && arg.getText() === wantParam) {
@@ -391,6 +457,36 @@ function anchorInitIfNeededGuarded(c, p) {
   };
 }
 
+// src/checkers/envSecretsCommitted.ts
+var envSecretsCommitted = (c, p) => {
+  if (!c.tracked) {
+    return {
+      result: "pass",
+      detail: p.ignoredDetail ?? "File is git-ignored; not committed to source control."
+    };
+  }
+  const keyRe = new RegExp(p.secretKeyPattern, "i");
+  const placeholderRe = new RegExp(p.placeholderPattern, "i");
+  const offenders = [];
+  for (const rawLine of c.content.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!m) continue;
+    const [, key, rawValue] = m;
+    if (!keyRe.test(key)) continue;
+    const value = (rawValue ?? "").trim().replace(/^["']|["']$/g, "");
+    if (!value) continue;
+    if (placeholderRe.test(value)) continue;
+    offenders.push(key);
+  }
+  if (offenders.length > 0) {
+    const prefix = p.failDetailPrefix ?? "This file is tracked by git and contains secret-looking values";
+    return { result: "fail", detail: `${prefix}: ${offenders.join(", ")}.` };
+  }
+  return { result: "pass", detail: p.passDetail ?? "No committed secret-looking values found." };
+};
+
 // src/checkers/index.ts
 var registry = {
   "positional-arg-identity": positionalArgIdentity,
@@ -398,7 +494,8 @@ var registry = {
   "fee-allocation-shape": feeAllocationShape,
   "arg-equals-constant-identifier": argEqualsConstantIdentifier,
   "object-arg-property-literal-equals": objectArgPropertyLiteralEquals,
-  "anchor-init-if-needed-guarded": anchorInitIfNeededGuarded
+  "anchor-init-if-needed-guarded": anchorInitIfNeededGuarded,
+  "env-secrets-committed": envSecretsCommitted
 };
 function runChecker(kind, c, params) {
   const fn = registry[kind];
@@ -407,14 +504,89 @@ function runChecker(kind, c, params) {
 }
 var checkerKinds = Object.keys(registry);
 
-// src/rustFinder.ts
-import { readFileSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+// src/gitDiff.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
+function getChangedRanges(targetDir, ref) {
+  let out;
+  try {
+    out = execFileSync2(
+      "git",
+      ["diff", "--unified=0", "--no-color", "--no-renames", "--diff-filter=ACMR", "--relative", ref, "--"],
+      { cwd: targetDir, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }
+    );
+  } catch (e) {
+    const stderr = e?.stderr?.toString?.() ?? e?.message ?? String(e);
+    throw new Error(`brainblast: 'git diff ${ref}' failed: ${stderr.trim()}`);
+  }
+  const ranges = /* @__PURE__ */ new Map();
+  let currentFile = null;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("+++ ")) {
+      const raw = line.slice(4).trim();
+      if (raw === "/dev/null") {
+        currentFile = null;
+        continue;
+      }
+      const rel = raw.startsWith("b/") ? raw.slice(2) : raw;
+      currentFile = join2(targetDir, rel);
+      continue;
+    }
+    if (line.startsWith("@@") && currentFile) {
+      const m = line.match(/\+(\d+)(?:,(\d+))?/);
+      if (!m) continue;
+      const start = parseInt(m[1], 10);
+      const count = m[2] !== void 0 ? parseInt(m[2], 10) : 1;
+      if (count === 0) continue;
+      const end = start + count - 1;
+      const arr = ranges.get(currentFile) ?? [];
+      arr.push([start, end]);
+      ranges.set(currentFile, arr);
+    }
+  }
+  return ranges;
+}
+function getWorkingTreeChanges(targetDir) {
+  const ranges = getChangedRanges(targetDir, "HEAD");
+  let untracked;
+  try {
+    untracked = execFileSync2("git", ["ls-files", "--others", "--exclude-standard", "--", "."], {
+      cwd: targetDir,
+      encoding: "utf8"
+    });
+  } catch {
+    return ranges;
+  }
+  for (const rel of untracked.split("\n").map((s) => s.trim()).filter(Boolean)) {
+    const abs = join2(targetDir, rel);
+    let lineCount = 1;
+    try {
+      lineCount = readFileSync2(abs, "utf8").split("\n").length;
+    } catch {
+      continue;
+    }
+    ranges.set(abs, [[1, lineCount]]);
+  }
+  return ranges;
+}
+function fileChanged(ranges, file) {
+  return ranges.has(file);
+}
+function rangeChanged(ranges, file, startLine, endLine) {
+  const fileRanges = ranges.get(file);
+  if (!fileRanges) return false;
+  return fileRanges.some(([s, e]) => startLine <= e && endLine >= s);
+}
+
+// src/rustFinder.ts
+import { readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join3 } from "path";
 import { createRequire } from "module";
 function walkRust(dir, out = []) {
   for (const entry of readdirSync2(dir)) {
     if (entry === "node_modules" || entry === ".git" || entry === "target") continue;
-    const p = join2(dir, entry);
+    const p = join3(dir, entry);
     const st = statSync2(p);
     if (st.isDirectory()) walkRust(p, out);
     else if (p.endsWith(".rs")) out.push(p);
@@ -494,7 +666,7 @@ function findRustCandidates(targetDir, rule) {
   const out = [];
   for (const file of walkRust(targetDir)) {
     if (!file.endsWith(".rs")) continue;
-    const src = readFileSync(file, "utf8");
+    const src = readFileSync3(file, "utf8");
     const tree = parser.parse(src);
     const structMap = /* @__PURE__ */ new Map();
     const topPairs = itemsWithAttrs(tree.rootNode);
@@ -538,6 +710,136 @@ function findRustCandidates(targetDir, rule) {
   return out;
 }
 
+// src/fixers/positionalArgIdentity.ts
+import { SyntaxKind as SyntaxKind7 } from "ts-morph";
+
+// src/fixers/diffUtil.ts
+function buildDiff(node, replacement) {
+  const sf = node.getSourceFile();
+  const filePath = sf.getFilePath();
+  const fullText = sf.getFullText();
+  const start = node.getStart();
+  const end = node.getEnd();
+  const startPos = sf.getLineAndColumnAtPos(start);
+  const endPos = sf.getLineAndColumnAtPos(end);
+  const lines = fullText.split("\n");
+  const oldMiddle = lines.slice(startPos.line - 1, endPos.line);
+  const oldFirst = oldMiddle[0].slice(0, startPos.column - 1);
+  const oldLast = oldMiddle[oldMiddle.length - 1].slice(endPos.column - 1);
+  const newMiddle = (oldFirst + replacement + oldLast).split("\n");
+  const removed = oldMiddle.map((l) => `-${l}`);
+  const added = newMiddle.map((l) => `+${l}`);
+  const hunkHeader = `@@ -${startPos.line},${oldMiddle.length} +${startPos.line},${newMiddle.length} @@`;
+  return [`--- a${filePath}`, `+++ b${filePath}`, hunkHeader, ...removed, ...added].join("\n");
+}
+
+// src/fixers/positionalArgIdentity.ts
+var fixPositionalArgIdentity = (c, p, outcome) => {
+  if (outcome.result !== "fail") return void 0;
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind7.CallExpression).filter((call) => {
+    const exp = call.getExpression();
+    return exp.getKind() === SyntaxKind7.PropertyAccessExpression && exp.asKind(SyntaxKind7.PropertyAccessExpression).getName() === p.call;
+  });
+  if (calls.length === 0) {
+    const wantParam2 = c.params[p.paramIndex] ?? "<rawBodyParam>";
+    return {
+      summary: `Add a ${p.call} call that verifies the raw request body`,
+      suggestion: `No '${p.call}' call was found in this handler. Verify the signature against the raw, unparsed request body \u2014 parameter '${wantParam2}' \u2014 before trusting the event, e.g.:
+
+  const event = stripe.webhooks.constructEvent(${wantParam2}, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+
+Do not call JSON.parse() on the body before this verification step.`
+    };
+  }
+  const arg = calls[0].getArguments()[p.argIndex];
+  const wantParam = c.params[p.paramIndex];
+  if (arg && wantParam && arg.getKind() === SyntaxKind7.CallExpression) {
+    return {
+      summary: `Pass the raw body parameter '${wantParam}' to ${p.call} instead of a parsed value`,
+      diff: buildDiff(arg, wantParam)
+    };
+  }
+  return void 0;
+};
+
+// src/fixers/requiredCallWithOptions.ts
+import { SyntaxKind as SyntaxKind8 } from "ts-morph";
+function callName4(call) {
+  const exp = call.getExpression();
+  if (exp.getKind() === SyntaxKind8.Identifier) return exp.getText();
+  if (exp.getKind() === SyntaxKind8.PropertyAccessExpression) {
+    return exp.asKind(SyntaxKind8.PropertyAccessExpression).getName();
+  }
+  return "";
+}
+function placeholderFor(propName) {
+  switch (propName) {
+    case "audience":
+    case "aud":
+      return `audience: process.env.PRIVY_APP_ID`;
+    case "issuer":
+    case "iss":
+      return `issuer: "https://privy.io"`;
+    default:
+      return `${propName}: undefined /* TODO: brainblast could not infer this value */`;
+  }
+}
+var fixRequiredCallWithOptions = (c, p, outcome) => {
+  if (outcome.result !== "fail") return void 0;
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind8.CallExpression);
+  const verify = calls.filter((x) => p.verifyCalls.includes(callName4(x)));
+  if (verify.length > 0) {
+    const call = verify[0];
+    const args = call.getArguments();
+    const lastArg = args[args.length - 1];
+    const obj = lastArg?.asKind(SyntaxKind8.ObjectLiteralExpression);
+    const presentNames = obj ? obj.getProperties().map((pr) => {
+      const pa = pr.asKind(SyntaxKind8.PropertyAssignment) ?? pr.asKind(SyntaxKind8.ShorthandPropertyAssignment);
+      return pa?.getName() ?? "";
+    }) : [];
+    const missingGroups = p.requiredProps.filter(
+      (g) => !g.some((n) => presentNames.includes(n))
+    );
+    if (missingGroups.length === 0) return void 0;
+    const newProps = missingGroups.map((g) => placeholderFor(g[0])).join(", ");
+    const summary = `Add ${missingGroups.map((g) => g[0]).join(" and ")} to the ${callName4(call)} call`;
+    if (obj) {
+      const inner = obj.getText().slice(1, -1).trim();
+      const newText = inner.length > 0 ? `{ ${inner}, ${newProps} }` : `{ ${newProps} }`;
+      return { summary, diff: buildDiff(obj, newText) };
+    }
+    if (lastArg) {
+      const newText = `${lastArg.getText()}, { ${newProps} }`;
+      return { summary, diff: buildDiff(lastArg, newText) };
+    }
+    return {
+      summary,
+      suggestion: `Add an options object ({ ${newProps} }) as an argument to ${callName4(call)}.`
+    };
+  }
+  return {
+    summary: "Replace the decode-only call with a verified call",
+    suggestion: `This token is decoded without verifying its signature, accepting any forged token. Replace the decode call with a verifying call that asserts audience and issuer, e.g.:
+
+  const { payload } = await jwtVerify(token, JWKS, { audience: process.env.PRIVY_APP_ID, issuer: "https://privy.io" });
+
+JWKS must come from Privy's published JWKS endpoint for your app.`
+  };
+};
+
+// src/fixers/index.ts
+var registry2 = {
+  "positional-arg-identity": fixPositionalArgIdentity,
+  "required-call-with-options": fixRequiredCallWithOptions
+};
+function runFixer(kind, c, params, outcome) {
+  if (outcome.result !== "fail") return void 0;
+  const fn = registry2[kind];
+  if (!fn) return void 0;
+  return fn(c, params, outcome);
+}
+var fixerKinds = Object.keys(registry2);
+
 // src/emit.ts
 function buildReport(target, checks, rules2, costReport) {
   const byId = new Map(rules2.map((r) => [r.id, r]));
@@ -584,7 +886,9 @@ function buildReport(target, checks, rules2, costReport) {
       file: c.file,
       line: c.line,
       title: c.title,
-      detail: c.detail
+      detail: c.detail,
+      ...c.fix ? { fix: c.fix } : {},
+      ...c.precedent ? { precedent: c.precedent } : {}
     })),
     checkTotals,
     openQuestions: [],
@@ -593,9 +897,28 @@ function buildReport(target, checks, rules2, costReport) {
 }
 
 // src/audit.ts
-function auditWithRule(targetDir, rule) {
+function auditWithRule(targetDir, rule, changedRanges) {
+  if (rule.detect.lang === "config") {
+    return findConfigCandidates(targetDir, rule).filter((c) => !changedRanges || fileChanged(changedRanges, c.filePath)).map((c) => {
+      const outcome = runChecker(rule.check.kind, c, rule.check.params);
+      return {
+        ruleId: rule.id,
+        severity: rule.severity,
+        title: rule.title,
+        file: c.filePath,
+        line: 1,
+        exportName: c.filePath,
+        ...outcome
+      };
+    });
+  }
   if (rule.detect.lang === "rust") {
-    return findRustCandidates(targetDir, rule).map((c) => {
+    return findRustCandidates(targetDir, rule).filter((c) => {
+      if (!changedRanges) return true;
+      const start = (c.fnBodyNode?.startPosition?.row ?? 0) + 1;
+      const end = (c.fnBodyNode?.endPosition?.row ?? start - 1) + 1;
+      return rangeChanged(changedRanges, c.filePath, start, end);
+    }).map((c) => {
       const outcome = runChecker(rule.check.kind, c, rule.check.params);
       return {
         ruleId: rule.id,
@@ -609,8 +932,12 @@ function auditWithRule(targetDir, rule) {
       };
     });
   }
-  return findCandidates(targetDir, rule).map((c) => {
+  return findCandidates(targetDir, rule).filter((c) => {
+    if (!changedRanges) return true;
+    return rangeChanged(changedRanges, c.filePath, c.fn.getStartLineNumber(), c.fn.getEndLineNumber());
+  }).map((c) => {
     const outcome = runChecker(rule.check.kind, c, rule.check.params);
+    const fix = runFixer(rule.check.kind, c, rule.check.params, outcome);
     return {
       ruleId: rule.id,
       severity: rule.severity,
@@ -618,12 +945,13 @@ function auditWithRule(targetDir, rule) {
       file: c.filePath,
       line: c.fn.getStartLineNumber(),
       exportName: c.fnName,
-      ...outcome
+      ...outcome,
+      ...fix ? { fix } : {}
     };
   });
 }
-function audit(targetDir, rules2) {
-  const checks = rules2.flatMap((r) => auditWithRule(targetDir, r));
+function audit(targetDir, rules2, changedRanges) {
+  const checks = rules2.flatMap((r) => auditWithRule(targetDir, r, changedRanges));
   const report = buildReport(targetDir, checks, rules2);
   return { checks, report };
 }
@@ -902,29 +1230,35 @@ mod brainblast_reinit_guard_test {
 }
 `;
 
+// src/testTemplates/none.ts
+var none = (opts) => `// No behavioral contract test applies to this rule.
+// Finding: ${opts.handlerExport} (${opts.handlerImportPath})
+`;
+
 // src/testTemplates/index.ts
-var registry2 = {
+var registry3 = {
   "stripe-webhook-signature": stripeWebhookSignature,
   "privy-jwt-claims": privyJwtClaims,
   "bags-fee-share": bagsFeeShare,
   "token-program-consistency": tokenProgramConsistency,
   "metaplex-immutable-metadata": metaplexImmutableMetadata,
-  "anchor-program-test": anchorProgramTest
+  "anchor-program-test": anchorProgramTest,
+  none
 };
 var JS_IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 function renderTest(kind, opts) {
-  const tpl = registry2[kind];
+  const tpl = registry3[kind];
   if (!tpl) throw new Error(`Unknown test template kind '${kind}'.`);
   if (!JS_IDENTIFIER.test(opts.handlerExport)) {
     throw new Error(`Unsafe handler export name '${opts.handlerExport}' (not a JS identifier).`);
   }
   return tpl(opts);
 }
-var testKinds = Object.keys(registry2);
+var testKinds = Object.keys(registry3);
 
 // src/loadRules.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
 import { parse } from "yaml";
 var SEVERITIES = ["critical", "high", "medium", "low"];
 function validateRule(r, file) {
@@ -936,7 +1270,19 @@ function validateRule(r, file) {
   if (!SEVERITIES.includes(r.severity)) errs.push(`bad severity '${r.severity}'`);
   if (!r.title || typeof r.title !== "string") errs.push("missing title");
   if (!r.component || !r.component.name || !r.component.type) errs.push("missing component.name/type");
-  if (!r.detect || !Array.isArray(r.detect.modules) || typeof r.detect.nameRegex !== "string" || !Array.isArray(r.detect.triggerCalls)) {
+  if (r.detect?.lang === "config") {
+    if (!Array.isArray(r.detect.filePatterns) || r.detect.filePatterns.length === 0) {
+      errs.push("detect.filePatterns must be a non-empty array when detect.lang is 'config'");
+    } else {
+      for (const pat of r.detect.filePatterns) {
+        try {
+          new RegExp(pat);
+        } catch {
+          errs.push(`detect.filePatterns contains an invalid regex: ${pat}`);
+        }
+      }
+    }
+  } else if (!r.detect || !Array.isArray(r.detect.modules) || typeof r.detect.nameRegex !== "string" || !Array.isArray(r.detect.triggerCalls)) {
     errs.push("detect must have modules[], nameRegex (string), triggerCalls[]");
   } else {
     try {
@@ -957,7 +1303,7 @@ function loadRules(dir) {
   const files = readdirSync3(dir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).sort();
   const rules2 = [];
   for (const f of files) {
-    const raw = parse(readFileSync2(join3(dir, f), "utf8"));
+    const raw = parse(readFileSync4(join4(dir, f), "utf8"));
     validateRule(raw, f);
     rules2.push(raw);
   }
@@ -966,23 +1312,23 @@ function loadRules(dir) {
 
 // rules/index.ts
 import { existsSync } from "fs";
-import { dirname, join as join4 } from "path";
+import { dirname, join as join5 } from "path";
 import { fileURLToPath } from "url";
 function bundledRulesDir() {
   const here = dirname(fileURLToPath(import.meta.url));
-  if (existsSync(join4(here, "stripe-webhook-raw-body.yaml"))) return here;
-  const sub = join4(here, "rules");
-  if (existsSync(join4(sub, "stripe-webhook-raw-body.yaml"))) return sub;
+  if (existsSync(join5(here, "stripe-webhook-raw-body.yaml"))) return here;
+  const sub = join5(here, "rules");
+  if (existsSync(join5(sub, "stripe-webhook-raw-body.yaml"))) return sub;
   return here;
 }
 var rules = loadRules(bundledRulesDir());
 
 // src/resolveRules.ts
 import { existsSync as existsSync2 } from "fs";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 function resolveRules(targetDir) {
   const all = [...rules];
-  const projDir = join5(targetDir, ".agent-research", "rules");
+  const projDir = join6(targetDir, ".agent-research", "rules");
   if (existsSync2(projDir)) {
     const seen = new Set(all.map((r) => r.id));
     for (const r of loadRules(projDir)) {
@@ -998,19 +1344,19 @@ function resolveRules(targetDir) {
 }
 
 // src/trustGraph/directory.ts
-import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
+import { readFileSync as readFileSync5, existsSync as existsSync3 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { parse as parse2 } from "yaml";
 var cache = null;
 function bundledPath() {
   const here = fileURLToPath2(new URL(".", import.meta.url));
   const candidates = [
-    join6(here, "programs", "directory.yaml"),
+    join7(here, "programs", "directory.yaml"),
     // dist/programs/directory.yaml
-    join6(here, "..", "..", "programs", "directory.yaml"),
+    join7(here, "..", "..", "programs", "directory.yaml"),
     // src/../../programs/
-    join6(here, "..", "programs", "directory.yaml")
+    join7(here, "..", "programs", "directory.yaml")
     // fallback
   ];
   for (const c of candidates) {
@@ -1020,7 +1366,7 @@ function bundledPath() {
 }
 function loadDirectory(path = bundledPath()) {
   if (cache && path === bundledPath()) return cache;
-  const raw = parse2(readFileSync3(path, "utf8"));
+  const raw = parse2(readFileSync5(path, "utf8"));
   if (!raw || !Array.isArray(raw.programs)) {
     throw new Error(`invalid program directory at ${path}: missing 'programs' array`);
   }
@@ -1091,14 +1437,14 @@ function isValidSolanaAddress(s) {
 }
 
 // src/trustGraph/programCache.ts
-import { readFileSync as readFileSync4, writeFileSync, mkdirSync, existsSync as existsSync4 } from "fs";
-import { join as join7, dirname as dirname2 } from "path";
+import { readFileSync as readFileSync6, writeFileSync, mkdirSync, existsSync as existsSync4 } from "fs";
+import { join as join8, dirname as dirname2 } from "path";
 import { homedir } from "os";
 var DEFAULT_TTL_HOURS = 168;
 var SCHEMA_VERSION = "1.0";
 function defaultCachePath() {
   const envOverride = process.env["BRAINBLAST_CACHE_PATH"];
-  return envOverride ?? join7(homedir(), ".brainblast", "program-cache.json");
+  return envOverride ?? join8(homedir(), ".brainblast", "program-cache.json");
 }
 function emptyCache() {
   return { schemaVersion: SCHEMA_VERSION, entries: {} };
@@ -1107,7 +1453,7 @@ function loadProgramCache(cachePath) {
   const path = cachePath ?? defaultCachePath();
   if (!existsSync4(path)) return emptyCache();
   try {
-    const raw = JSON.parse(readFileSync4(path, "utf8"));
+    const raw = JSON.parse(readFileSync6(path, "utf8"));
     if (raw?.schemaVersion !== SCHEMA_VERSION) {
       return emptyCache();
     }
@@ -1384,7 +1730,7 @@ function renderTrustGraphMd(g) {
 }
 
 // src/costAnalysis.ts
-import { Project as Project2, SyntaxKind as SyntaxKind7 } from "ts-morph";
+import { Project as Project2, SyntaxKind as SyntaxKind9 } from "ts-morph";
 var LAMPORTS_PER_BYTE_YEAR = 3480;
 var EXEMPTION_THRESHOLD = 2;
 var OVERHEAD_BYTES = 128;
@@ -1465,11 +1811,11 @@ var KNOWN_FLOWS = [
   }
 ];
 var LOOP_NODE_KINDS = /* @__PURE__ */ new Set([
-  SyntaxKind7.ForStatement,
-  SyntaxKind7.ForOfStatement,
-  SyntaxKind7.ForInStatement,
-  SyntaxKind7.WhileStatement,
-  SyntaxKind7.DoStatement
+  SyntaxKind9.ForStatement,
+  SyntaxKind9.ForOfStatement,
+  SyntaxKind9.ForInStatement,
+  SyntaxKind9.WhileStatement,
+  SyntaxKind9.DoStatement
 ]);
 var ARRAY_METHOD_LOOPS = /* @__PURE__ */ new Set(["map", "forEach", "flatMap", "reduce", "filter"]);
 function isInsideLoop(node) {
@@ -1477,12 +1823,12 @@ function isInsideLoop(node) {
   while (cur) {
     const k = cur.getKind?.();
     if (k !== void 0 && LOOP_NODE_KINDS.has(k)) {
-      return { scalable: true, note: `call is inside a ${SyntaxKind7[k]} \u2014 cost scales with loop iterations` };
+      return { scalable: true, note: `call is inside a ${SyntaxKind9[k]} \u2014 cost scales with loop iterations` };
     }
-    if (k === SyntaxKind7.CallExpression) {
+    if (k === SyntaxKind9.CallExpression) {
       const expr = cur.getExpression?.();
-      if (expr?.getKind?.() === SyntaxKind7.PropertyAccessExpression) {
-        const name = expr.asKind?.(SyntaxKind7.PropertyAccessExpression)?.getName?.();
+      if (expr?.getKind?.() === SyntaxKind9.PropertyAccessExpression) {
+        const name = expr.asKind?.(SyntaxKind9.PropertyAccessExpression)?.getName?.();
         if (name && ARRAY_METHOD_LOOPS.has(name)) {
           return { scalable: true, note: `call is inside .${name}() \u2014 cost scales with array length` };
         }
@@ -1496,7 +1842,7 @@ function detectPriorityFee(targetDir) {
   const project = new Project2({ skipAddingFilesFromTsConfig: true });
   for (const file of walk(targetDir)) {
     const sf = project.addSourceFileAtPath(file);
-    const calls = sf.getDescendantsOfKind(SyntaxKind7.CallExpression);
+    const calls = sf.getDescendantsOfKind(SyntaxKind9.CallExpression);
     for (const ce of calls) {
       const expr = ce.getExpression();
       const text = expr.getText();
@@ -1524,22 +1870,22 @@ function detectAccountFlows(targetDir) {
     const importedModules = new Set(
       sf.getImportDeclarations().map((d) => d.getModuleSpecifierValue())
     );
-    for (const ce of sf.getDescendantsOfKind(SyntaxKind7.CallExpression)) {
+    for (const ce of sf.getDescendantsOfKind(SyntaxKind9.CallExpression)) {
       const expr = ce.getExpression();
-      let callName4 = null;
-      if (expr.getKind() === SyntaxKind7.Identifier) {
-        callName4 = expr.getText();
-      } else if (expr.getKind() === SyntaxKind7.PropertyAccessExpression) {
-        callName4 = expr.asKind(SyntaxKind7.PropertyAccessExpression).getName();
+      let callName5 = null;
+      if (expr.getKind() === SyntaxKind9.Identifier) {
+        callName5 = expr.getText();
+      } else if (expr.getKind() === SyntaxKind9.PropertyAccessExpression) {
+        callName5 = expr.asKind(SyntaxKind9.PropertyAccessExpression).getName();
       }
-      if (!callName4) continue;
-      const known = callIndex.get(callName4);
+      if (!callName5) continue;
+      const known = callIndex.get(callName5);
       if (!known) continue;
       if (!importedModules.has(known.module)) continue;
       const lamports = rentExemptMinimum(known.dataLen);
       const { scalable, note } = isInsideLoop(ce);
       flows.push({
-        call: callName4,
+        call: callName5,
         module: known.module,
         accountType: known.accountType,
         file,
@@ -1626,10 +1972,72 @@ function renderCostReportMd(r) {
   return lines.join("\n");
 }
 
+// src/watch.ts
+import { watch as fsWatch } from "fs";
+function runIncrementalScan(targetDir, rules2, emit) {
+  const start = Date.now();
+  let changedRanges;
+  try {
+    changedRanges = getWorkingTreeChanges(targetDir);
+  } catch (e) {
+    emit({ type: "scan_error", message: e?.message ?? String(e) });
+    return;
+  }
+  if (changedRanges.size === 0) {
+    emit({ type: "scan_complete", filesChanged: 0, findings: 0, durationMs: Date.now() - start });
+    return;
+  }
+  const { checks } = audit(targetDir, rules2, changedRanges);
+  let findings = 0;
+  for (const c of checks) {
+    if (c.result === "pass") continue;
+    findings++;
+    emit({
+      type: "finding",
+      ruleId: c.ruleId,
+      severity: c.severity,
+      result: c.result,
+      file: c.file,
+      line: c.line,
+      detail: c.detail,
+      ...c.fix ? { fix: c.fix } : {}
+    });
+  }
+  emit({ type: "scan_complete", filesChanged: changedRanges.size, findings, durationMs: Date.now() - start });
+}
+function startWatch(targetDir, opts = {}) {
+  const debounceMs = opts.debounceMs ?? 300;
+  const emit = opts.emit ?? ((e) => process.stdout.write(JSON.stringify(e) + "\n"));
+  const rules2 = resolveRules(targetDir);
+  let timer;
+  const scheduleScan = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => runIncrementalScan(targetDir, rules2, emit), debounceMs);
+  };
+  const watcher = fsWatch(targetDir, { recursive: true }, (_event, filename) => {
+    if (!filename) return;
+    const parts = filename.split(/[\\/]/);
+    if (parts.some((p) => SKIP_DIRS.has(p))) return;
+    scheduleScan();
+  });
+  emit({ type: "watch_started", targetDir });
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
 export {
   findCandidates,
+  findConfigCandidates,
   runChecker,
   checkerKinds,
+  getChangedRanges,
+  getWorkingTreeChanges,
+  fileChanged,
+  rangeChanged,
   auditWithRule,
   audit,
   renderTest,
@@ -1655,5 +2063,7 @@ export {
   rentExemptMinimum,
   lamportsToSol,
   analyzeCosts,
-  renderCostReportMd
+  renderCostReportMd,
+  runIncrementalScan,
+  startWatch
 };

package/dist/cli.js

@@ -5,40 +5,176 @@ import {
   buildTrustGraph,
   cacheSize,
   defaultCachePath,
+  getChangedRanges,
   isValidSolanaAddress,
   loadProgramCache,
   renderCostReportMd,
   renderTrustGraphMd,
-  resolveRules
-} from "./chunk-BZVZ3WAU.js";
+  resolveRules,
+  startWatch
+} from "./chunk-P7K7NRVN.js";
 
 // src/cli.ts
-import { writeFileSync, mkdirSync } from "fs";
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/memory.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
+var EMPTY_MEMORY = { schemaVersion: "1.0", lastRun: [], fixHistory: [] };
+function memoryPath(targetDir2) {
+  return join(targetDir2, ".agent-research", "memory.json");
+}
+function loadMemory(targetDir2) {
+  const p = memoryPath(targetDir2);
+  if (!existsSync(p)) return { ...EMPTY_MEMORY, lastRun: [], fixHistory: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf8"));
+    return {
+      schemaVersion: parsed.schemaVersion ?? "1.0",
+      lastRun: Array.isArray(parsed.lastRun) ? parsed.lastRun : [],
+      fixHistory: Array.isArray(parsed.fixHistory) ? parsed.fixHistory : []
+    };
+  } catch {
+    return { ...EMPTY_MEMORY, lastRun: [], fixHistory: [] };
+  }
+}
+function saveMemory(targetDir2, memory) {
+  mkdirSync(join(targetDir2, ".agent-research"), { recursive: true });
+  writeFileSync(memoryPath(targetDir2), JSON.stringify(memory, null, 2));
+}
+var snapshotKey = (e) => `${e.ruleId}::${e.file}::${e.exportName}`;
+function precedentKey(c) {
+  return `${c.ruleId}::${c.file}`;
+}
+function updateMemory(memory, checks2, now = /* @__PURE__ */ new Date()) {
+  const prevByKey = new Map(memory.lastRun.map((e) => [snapshotKey(e), e]));
+  const fixedAt = now.toISOString().slice(0, 10);
+  const newFixEvents = [];
+  for (const c of checks2) {
+    const prev = prevByKey.get(snapshotKey(c));
+    if (prev?.result === "fail" && c.result !== "fail") {
+      newFixEvents.push({
+        ruleId: c.ruleId,
+        file: c.file,
+        exportName: c.exportName,
+        fixedAt,
+        detail: prev.detail
+      });
+    }
+  }
+  const fixHistory = [...memory.fixHistory, ...newFixEvents];
+  const precedents = /* @__PURE__ */ new Map();
+  for (const c of checks2) {
+    if (c.result !== "fail") continue;
+    const pk = precedentKey(c);
+    if (precedents.has(pk)) continue;
+    const matches = fixHistory.filter((e) => e.ruleId === c.ruleId && e.file !== c.file).sort((a, b) => a.fixedAt < b.fixedAt ? 1 : a.fixedAt > b.fixedAt ? -1 : 0);
+    if (matches[0]) {
+      precedents.set(pk, {
+        file: matches[0].file,
+        exportName: matches[0].exportName,
+        fixedAt: matches[0].fixedAt,
+        detail: matches[0].detail
+      });
+    }
+  }
+  const lastRun = checks2.map((c) => ({
+    ruleId: c.ruleId,
+    file: c.file,
+    exportName: c.exportName,
+    result: c.result,
+    detail: c.detail
+  }));
+  return { memory: { schemaVersion: "1.0", lastRun, fixHistory }, precedents };
+}
+
+// src/cli.ts
 var args = process.argv.slice(2);
 if (args[0] === "trust-graph") {
   await runTrustGraph(args.slice(1));
   process.exit(0);
 }
+if (args[0] === "watch") {
+  const watchDir = args.find((a, i) => i > 0 && !a.startsWith("--")) ?? process.cwd();
+  startWatch(watchDir);
+  process.on("SIGINT", () => process.exit(0));
+  process.on("SIGTERM", () => process.exit(0));
+  await new Promise(() => {
+  });
+}
 var ci = args.includes("--ci");
 var strict = args.includes("--strict");
-var targetDir = args.find((a) => !a.startsWith("--")) ?? process.cwd();
+var sinceIdx = args.indexOf("--since");
+var since = sinceIdx >= 0 ? args[sinceIdx + 1] : void 0;
+var targetDir = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--since") ?? process.cwd();
+if (sinceIdx >= 0 && !since) {
+  console.error("error: --since requires a <ref> argument, e.g. --since origin/main");
+  process.exit(2);
+}
 var rules = resolveRules(targetDir);
-var { checks, report } = audit(targetDir, rules);
+var changedRanges;
+if (since) {
+  try {
+    changedRanges = getChangedRanges(targetDir, since);
+  } catch (e) {
+    console.error(e.message ?? String(e));
+    process.exit(2);
+  }
+}
+var { checks, report } = audit(targetDir, rules, changedRanges);
+if (!changedRanges) {
+  const memory = loadMemory(targetDir);
+  const { memory: nextMemory, precedents } = updateMemory(memory, checks);
+  for (const c of checks) {
+    const p = precedents.get(precedentKey(c));
+    if (p) c.precedent = p;
+  }
+  for (const rc of report.checks) {
+    const p = precedents.get(precedentKey(rc));
+    if (p) rc.precedent = p;
+  }
+  saveMemory(targetDir, nextMemory);
+} else {
+  const memory = loadMemory(targetDir);
+  const { precedents } = updateMemory(memory, checks);
+  for (const c of checks) {
+    const p = precedents.get(precedentKey(c));
+    if (p) c.precedent = p;
+  }
+  for (const rc of report.checks) {
+    const p = precedents.get(precedentKey(rc));
+    if (p) rc.precedent = p;
+  }
+}
 var costReport = analyzeCosts(targetDir);
 report.costAnalysis = costReport;
-var outDir = join(targetDir, ".agent-research");
-mkdirSync(outDir, { recursive: true });
-var reportPath = join(outDir, "report.json");
-writeFileSync(reportPath, JSON.stringify(report, null, 2));
-var costMdPath = join(outDir, "cost-analysis.md");
-writeFileSync(costMdPath, renderCostReportMd(costReport));
+var outDir = join2(targetDir, ".agent-research");
+mkdirSync2(outDir, { recursive: true });
+var reportPath = join2(outDir, "report.json");
+writeFileSync2(reportPath, JSON.stringify(report, null, 2));
+var costMdPath = join2(outDir, "cost-analysis.md");
+writeFileSync2(costMdPath, renderCostReportMd(costReport));
 console.log(`brainblast: scanned ${targetDir} with ${rules.length} rule(s)`);
 if (checks.length === 0) console.log("  (no catastrophic components detected)");
 for (const c of checks) {
   const tag = c.result === "pass" ? "PASS " : c.result === "fail" ? "FAIL " : "WARN ";
   console.log(`  [${tag}] ${c.ruleId}  ${c.file}:${c.line}`);
   console.log(`          ${c.detail}`);
+  if (c.precedent) {
+    console.log(
+      `          memory: same issue (${c.ruleId}) was fixed in ${c.precedent.file} on ${c.precedent.fixedAt}`
+    );
+  }
+  if (c.fix) {
+    console.log(`          fix: ${c.fix.summary}`);
+    if (c.fix.diff) {
+      for (const line of c.fix.diff.split("\n")) console.log(`            ${line}`);
+    }
+    if (c.fix.suggestion) {
+      for (const line of c.fix.suggestion.split("\n")) console.log(`            ${line}`);
+    }
+  }
 }
 var fails = checks.filter((c) => c.result === "fail").length;
 var cantTell = checks.filter((c) => c.result === "cant_tell").length;

package/dist/index.d.ts

@@ -74,10 +74,29 @@ interface RustCandidate {
     /** tree-sitter SyntaxNode for the function body — available for precise queries */
     fnBodyNode: any;
 }
+interface ConfigCandidate {
+    /** Source file (absolute path) */
+    filePath: string;
+    /** Raw file contents */
+    content: string;
+    /** Whether this file is tracked by git / not covered by .gitignore */
+    tracked: boolean;
+}
 interface CheckOutcome {
     result: CheckResultKind;
     detail: string;
 }
+interface Fix {
+    summary: string;
+    diff?: string;
+    suggestion?: string;
+}
+interface Precedent {
+    file: string;
+    exportName: string;
+    fixedAt: string;
+    detail: string;
+}
 interface CheckResult extends CheckOutcome {
     ruleId: string;
     severity: Severity;
@@ -85,6 +104,10 @@ interface CheckResult extends CheckOutcome {
     file: string;
     line: number;
     exportName: string;
+    /** Present when result === "fail" and a vetted fixer for check.kind produced one. */
+    fix?: Fix;
+    /** Present when result === "fail" and the same rule was previously fixed elsewhere. */
+    precedent?: Precedent;
 }
 interface Rule {
     id: string;
@@ -100,8 +123,30 @@ interface Rule {
         modules: string[];
         nameRegex: string;
         triggerCalls: string[];
-        /** Defaults to "typescript". Set to "rust" for Anchor/Rust checker kinds. */
-        lang?: "typescript" | "rust";
+        /**
+         * Defaults to "typescript". Set to "rust" for Anchor/Rust checker kinds,
+         * or "config" for whole-file config/env audits (see `filePatterns`).
+         */
+        lang?: "typescript" | "rust" | "config";
+        /**
+         * Required when `lang: "config"`. Regexes (matched against the file path
+         * relative to the scan root) selecting which files this rule audits,
+         * e.g. `["(^|/)\\.env(\\.[^/]+)?$"]`. Ignored for "typescript"/"rust".
+         */
+        filePatterns?: string[];
+        /**
+         * When true, a module import from `modules` is a REQUIRED condition for
+         * detection: a candidate must be in a file that imports one of the listed
+         * modules, AND either its name matches nameRegex or its body calls a
+         * triggerCall.  This prevents generic name-only matches (e.g. a Fastify
+         * middleware named "verifyJwt" that calls `request.jwtVerify()`) from
+         * triggering jose-specific rules.
+         *
+         * When false or omitted (default), detection is: nameRegex match OR
+         * triggerCall in body.  Module import is not required, so rules like
+         * stripe-webhook can still catch handlers that don't import stripe directly.
+         */
+        requiresImport?: boolean;
     };
     check: {
         kind: string;
@@ -112,9 +157,18 @@ interface Rule {
         params?: Record<string, any>;
     };
 }
+type Checker = (candidate: Candidate, params: any) => CheckOutcome;
+type RustChecker = (candidate: RustCandidate, params: any) => CheckOutcome;
+type ConfigChecker = (candidate: ConfigCandidate, params: any) => CheckOutcome;
+
+type ChangedRanges = Map<string, Array<[number, number]>>;
+declare function getChangedRanges(targetDir: string, ref: string): ChangedRanges;
+declare function getWorkingTreeChanges(targetDir: string): ChangedRanges;
+declare function fileChanged(ranges: ChangedRanges, file: string): boolean;
+declare function rangeChanged(ranges: ChangedRanges, file: string, startLine: number, endLine: number): boolean;
 
-declare function auditWithRule(targetDir: string, rule: Rule): CheckResult[];
-declare function audit(targetDir: string, rules: Rule[]): {
+declare function auditWithRule(targetDir: string, rule: Rule, changedRanges?: ChangedRanges): CheckResult[];
+declare function audit(targetDir: string, rules: Rule[], changedRanges?: ChangedRanges): {
     checks: CheckResult[];
     report: {
         schemaVersion: string;
@@ -150,6 +204,8 @@ declare function audit(targetDir: string, rules: Rule[]): {
             low: number;
         };
         checks: {
+            precedent?: Precedent | undefined;
+            fix?: Fix | undefined;
             ruleId: string;
             severity: Severity;
             result: CheckResultKind;
@@ -183,11 +239,43 @@ declare function renderTest(kind: string, opts: {
 }): string;
 declare const testKinds: string[];
 
-declare function runChecker(kind: string, c: Candidate | RustCandidate, params: any): CheckOutcome;
+declare function runChecker(kind: string, c: Candidate | RustCandidate | ConfigCandidate, params: any): CheckOutcome;
 declare const checkerKinds: string[];
 
 declare function findCandidates(targetDir: string, rule: Rule): Candidate[];
 
+declare function findConfigCandidates(targetDir: string, rule: Rule): ConfigCandidate[];
+
+type WatchEvent = {
+    type: "watch_started";
+    targetDir: string;
+} | {
+    type: "scan_error";
+    message: string;
+} | {
+    type: "finding";
+    ruleId: string;
+    severity: string;
+    result: "fail" | "cant_tell";
+    file: string;
+    line: number;
+    detail: string;
+    fix?: unknown;
+} | {
+    type: "scan_complete";
+    filesChanged: number;
+    findings: number;
+    durationMs: number;
+};
+interface WatchOptions {
+    debounceMs?: number;
+    emit?: (event: WatchEvent) => void;
+}
+declare function runIncrementalScan(targetDir: string, rules: Rule[], emit: (e: WatchEvent) => void): void;
+declare function startWatch(targetDir: string, opts?: WatchOptions): {
+    close: () => void;
+};
+
 type UpgradeAuthorityKind = "renounced" | "single-key" | "multisig" | "dao" | "unknown";
 type UpgradeAuthoritySource = "directory" | "rpc" | "research";
 interface UpgradeAuthority {
@@ -317,4 +405,4 @@ declare function isEntryExpired(entry: ProgramCacheEntry, ttlHoursOverride?: num
  */
 declare function cacheSize(cache: ProgramCache, ttlHoursOverride?: number): number;
 
-export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type CheckOutcome, type CheckResult, type CheckResultKind, type CostReport, DEFAULT_TTL_HOURS, type OnChainProgram, type ParityNote, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type Severity, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, analyzeCosts, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, findCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, isEntryExpired, isValidSolanaAddress, lamportsToSol, loadDirectory, loadProgramCache, loadRules, putCacheEntry, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, saveProgramCache, testKinds };
+export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type ChangedRanges, type CheckOutcome, type CheckResult, type CheckResultKind, type Checker, type ConfigCandidate, type ConfigChecker, type CostReport, DEFAULT_TTL_HOURS, type OnChainProgram, type ParityNote, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type RustChecker, type Severity, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, type WatchEvent, type WatchOptions, analyzeCosts, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, fileChanged, findCandidates, findConfigCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, getChangedRanges, getWorkingTreeChanges, isEntryExpired, isValidSolanaAddress, lamportsToSol, loadDirectory, loadProgramCache, loadRules, putCacheEntry, rangeChanged, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, runIncrementalScan, saveProgramCache, startWatch, testKinds };

package/dist/index.js

@@ -9,9 +9,13 @@ import {
   cacheSize,
   checkerKinds,
   defaultCachePath,
+  fileChanged,
   findCandidates,
+  findConfigCandidates,
   getCacheEntry,
   getCacheEntryMeta,
+  getChangedRanges,
+  getWorkingTreeChanges,
   isEntryExpired,
   isValidSolanaAddress,
   lamportsToSol,
@@ -19,6 +23,7 @@ import {
   loadProgramCache,
   loadRules,
   putCacheEntry,
+  rangeChanged,
   renderCostReportMd,
   renderTest,
   renderTrustGraphMd,
@@ -26,9 +31,11 @@ import {
   resolveRules,
   rules,
   runChecker,
+  runIncrementalScan,
   saveProgramCache,
+  startWatch,
   testKinds
-} from "./chunk-BZVZ3WAU.js";
+} from "./chunk-P7K7NRVN.js";
 
 // src/generate.ts
 import { writeFileSync, mkdirSync } from "fs";
@@ -55,10 +62,14 @@ export {
   cacheSize,
   checkerKinds,
   defaultCachePath,
+  fileChanged,
   findCandidates,
+  findConfigCandidates,
   generateTestForResult,
   getCacheEntry,
   getCacheEntryMeta,
+  getChangedRanges,
+  getWorkingTreeChanges,
   isEntryExpired,
   isValidSolanaAddress,
   lamportsToSol,
@@ -66,12 +77,15 @@ export {
   loadProgramCache,
   loadRules,
   putCacheEntry,
+  rangeChanged,
   renderCostReportMd,
   renderTest,
   renderTrustGraphMd,
   rentExemptMinimum,
   resolveRules,
   runChecker,
+  runIncrementalScan,
   saveProgramCache,
+  startWatch,
   testKinds
 };

package/dist/rules/env-secrets-committed.yaml

@@ -0,0 +1,32 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+id: env-secrets-committed
+severity: critical
+title: Secret-looking values are not committed to source control
+component:
+  name: Environment configuration
+  type: Config
+  version: unversioned
+  sourceUrl: https://12factor.net/config
+detect:
+  lang: config
+  # .env, .env.local, .env.production, etc. — but not .env.example/.sample/.template,
+  # which are meant to be committed and document expected keys with placeholders.
+  filePatterns:
+    - "(^|/)\\.env(\\.(?!example$|sample$|template$)[^/]+)?$"
+check:
+  kind: env-secrets-committed
+  params:
+    # Key names that typically hold credentials/secrets.
+    secretKeyPattern: "(SECRET|PRIVATE_KEY|API_KEY|ACCESS_KEY|TOKEN|PASSWORD|CREDENTIAL)"
+    # Values that look like placeholders, not real secrets — these are fine to commit.
+    placeholderPattern: "^(your[_-]|xxx|changeme|change[_-]?me|replace|example|<|sk_test_|pk_test_|test[_-]|dummy|placeholder|\\*+$|\\.\\.\\.$)"
+    ignoredDetail: >-
+      File is git-ignored and not committed to source control.
+    passDetail: >-
+      File is tracked but contains no secret-looking values (placeholders only).
+    failDetailPrefix: >-
+      This file is committed to source control and contains what look like real
+      secret values. Anyone with read access to the repo (including forks) can
+      read these credentials
+test:
+  kind: none

package/dist/rules/privy-jwt-verification.yaml

@@ -14,7 +14,19 @@ detect:
   # Privy handlers are still picked up by the @privy-io/* / jose / jsonwebtoken
   # imports, and by triggerCalls like decodeJwt / jwtVerify.
   nameRegex: "privy|jwt"
-  triggerCalls: [decodeJwt, jwtVerify, verify, decode]
+  # Only decodeJwt triggers detection; it's specific to jose and unambiguously
+  # indicates a decode-only pattern.  jwtVerify/verify/decode were removed because:
+  #   - "verify" matches Node.js crypto.verify(), jsonwebtoken jwt.verify(), etc.
+  #   - "decode" matches bs58.decode() (Solana), Buffer.from(), etc.
+  #   - "jwtVerify" matches Fastify's request.jwtVerify() plugin method, which is
+  #     not a jose-based call and requires no audience/issuer options.
+  # Functions that import jose/@privy-io/* and are named with "privy|jwt" are still
+  # detected via requiresImport + (importsModule && hasName), the primary detection path.
+  triggerCalls: [decodeJwt]
+  # A module import is REQUIRED to be a candidate.  Without this guard, a Fastify
+  # middleware named "verifyJwt" (which calls request.jwtVerify(), a completely
+  # different library) would match the nameRegex and be flagged as missing aud/iss.
+  requiresImport: true
 check:
   kind: required-call-with-options
   params:

package/dist/rules/stripe-webhook-raw-body.yaml

@@ -11,6 +11,11 @@ detect:
   modules: [stripe]
   nameRegex: webhook
   triggerCalls: [constructEvent]
+  # Require the file to import stripe.  Without this guard, any function whose
+  # name contains "webhook" — even LemonSqueezy, Polar, or Sendgrid handlers —
+  # is flagged for missing stripe.webhooks.constructEvent, producing false
+  # positives on non-Stripe payment integrations.
+  requiresImport: true
 check:
   kind: positional-arg-identity
   params:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainblast",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Deterministic auditor for catastrophic AI-integration bugs: scan a repo, find the silent money/auth traps, and generate the behavioral test that proves they're fixed.",
   "keywords": [