brainblast 0.4.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-WVHGN2HR.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) {
@@ -61,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) => {
@@ -410,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,
@@ -417,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];
@@ -426,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);
@@ -513,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);
@@ -744,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,
@@ -760,7 +932,10 @@ 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 {
@@ -775,8 +950,8 @@ function auditWithRule(targetDir, rule) {
     };
   });
 }
-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 };
 }
@@ -1055,6 +1230,11 @@ 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 registry3 = {
   "stripe-webhook-signature": stripeWebhookSignature,
@@ -1062,7 +1242,8 @@ var registry3 = {
   "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) {
@@ -1076,8 +1257,8 @@ function renderTest(kind, opts) {
 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) {
@@ -1089,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 {
@@ -1110,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);
   }
@@ -1119,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)) {
@@ -1151,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) {
@@ -1173,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`);
   }
@@ -1244,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: {} };
@@ -1260,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();
     }
@@ -1779,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,
@@ -1808,5 +2063,7 @@ export {
   rentExemptMinimum,
   lamportsToSol,
   analyzeCosts,
-  renderCostReportMd
+  renderCostReportMd,
+  runIncrementalScan,
+  startWatch
 };

package/dist/cli.js

@@ -5,12 +5,14 @@ import {
   buildTrustGraph,
   cacheSize,
   defaultCachePath,
+  getChangedRanges,
   isValidSolanaAddress,
   loadProgramCache,
   renderCostReportMd,
   renderTrustGraphMd,
-  resolveRules
-} from "./chunk-WVHGN2HR.js";
+  resolveRules,
+  startWatch
+} from "./chunk-P7K7NRVN.js";
 
 // src/cli.ts
 import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
@@ -37,16 +39,16 @@ function loadMemory(targetDir2) {
     return { ...EMPTY_MEMORY, lastRun: [], fixHistory: [] };
   }
 }
-function saveMemory(targetDir2, memory2) {
+function saveMemory(targetDir2, memory) {
   mkdirSync(join(targetDir2, ".agent-research"), { recursive: true });
-  writeFileSync(memoryPath(targetDir2), JSON.stringify(memory2, null, 2));
+  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(memory2, checks2, now = /* @__PURE__ */ new Date()) {
-  const prevByKey = new Map(memory2.lastRun.map((e) => [snapshotKey(e), e]));
+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) {
@@ -61,15 +63,15 @@ function updateMemory(memory2, checks2, now = /* @__PURE__ */ new Date()) {
       });
     }
   }
-  const fixHistory = [...memory2.fixHistory, ...newFixEvents];
-  const precedents2 = /* @__PURE__ */ new Map();
+  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 (precedents2.has(pk)) continue;
+    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]) {
-      precedents2.set(pk, {
+      precedents.set(pk, {
         file: matches[0].file,
         exportName: matches[0].exportName,
         fixedAt: matches[0].fixedAt,
@@ -84,7 +86,7 @@ function updateMemory(memory2, checks2, now = /* @__PURE__ */ new Date()) {
     result: c.result,
     detail: c.detail
   }));
-  return { memory: { schemaVersion: "1.0", lastRun, fixHistory }, precedents: precedents2 };
+  return { memory: { schemaVersion: "1.0", lastRun, fixHistory }, precedents };
 }
 
 // src/cli.ts
@@ -93,22 +95,58 @@ 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 memory = loadMemory(targetDir);
-var { memory: nextMemory, precedents } = updateMemory(memory, checks);
-for (const c of checks) {
-  const p = precedents.get(precedentKey(c));
-  if (p) c.precedent = p;
+var changedRanges;
+if (since) {
+  try {
+    changedRanges = getChangedRanges(targetDir, since);
+  } catch (e) {
+    console.error(e.message ?? String(e));
+    process.exit(2);
+  }
 }
-for (const rc of report.checks) {
-  const p = precedents.get(precedentKey(rc));
-  if (p) rc.precedent = p;
+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;
+  }
 }
-saveMemory(targetDir, nextMemory);
 var costReport = analyzeCosts(targetDir);
 report.costAnalysis = costReport;
 var outDir = join2(targetDir, ".agent-research");

package/dist/index.d.ts

@@ -74,6 +74,14 @@ 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;
@@ -115,8 +123,17 @@ 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
@@ -140,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;
@@ -213,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 {
@@ -347,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-WVHGN2HR.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainblast",
-  "version": "0.4.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": [