@clear-capabilities/agentic-security-scanner 0.80.0 → 0.86.0

package/src/posture/cross-repo-memory.js

@@ -0,0 +1,180 @@
+// Cross-repo intelligence — a per-developer store of fix patterns and
+// triage decisions that span every repo this developer has used the
+// plugin against.
+//
+// Location: ~/.claude/agentic-security/cross-repo/
+//   patterns.jsonl    — append-only log of "developer fixed family X
+//                       in repo Y at commit Z using pattern P"
+//   triage.jsonl      — append-only log of "developer marked family X
+//                       in repo Y wont-fix with reason R"
+//
+// When a finding lands in the current repo, surface matching patterns
+// and triage decisions from sibling repos — "you fixed this exact shape
+// in repo-A last week; same fix here?"
+//
+// Privacy:
+//   - All data stored locally under the developer's $HOME
+//   - Nothing transmitted; no network calls
+//   - Repo identifiers are git-remote-derived SHA fingerprints, not
+//     bare names — so the store doesn't accidentally reveal repo names
+//     to anyone reading the local file
+//   - Opt-out: AGENTIC_SECURITY_NO_CROSS_REPO=1
+
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+
+// Lazy — process.env.HOME may be mutated mid-process (e.g. tests isolating).
+function _storeDir() {
+  const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
+  return path.join(HOME, '.claude', 'agentic-security', 'cross-repo');
+}
+function _patternsFile() { return path.join(_storeDir(), 'patterns.jsonl'); }
+function _triageFile()   { return path.join(_storeDir(), 'triage.jsonl'); }
+const MAX_LINES  = 5000;
+
+function _ensureDir() { try { fs.mkdirSync(_storeDir(), { recursive: true }); } catch {} }
+
+/**
+ * Stable, privacy-preserving repo fingerprint: SHA-256 of the git remote
+ * URL (or scan-root absolute path if no remote). Truncated to 12 chars.
+ */
+export function repoFingerprint(scanRoot) {
+  let source = String(scanRoot || '');
+  try {
+    const remote = cp.execFileSync('git', ['remote', 'get-url', 'origin'],
+      { cwd: scanRoot, encoding: 'utf8', timeout: 800, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (remote) source = remote;
+  } catch {}
+  return crypto.createHash('sha256').update(source).digest('hex').slice(0, 12);
+}
+
+function _appendLine(fp, obj) {
+  if (process.env.AGENTIC_SECURITY_NO_CROSS_REPO === '1') return;
+  _ensureDir();
+  try { fs.appendFileSync(fp, JSON.stringify(obj) + '\n'); } catch {}
+  _rotateIfNeeded(fp);
+}
+
+function _rotateIfNeeded(fp) {
+  try {
+    const stat = fs.statSync(fp);
+    if (stat.size < 1_000_000) return;
+    const lines = fs.readFileSync(fp, 'utf8').split('\n').filter(Boolean);
+    if (lines.length <= MAX_LINES) return;
+    fs.writeFileSync(fp, lines.slice(-MAX_LINES).join('\n') + '\n');
+  } catch {}
+}
+
+function _readAll(fp) {
+  if (process.env.AGENTIC_SECURITY_NO_CROSS_REPO === '1') return [];
+  try {
+    return fs.readFileSync(fp, 'utf8')
+      .split('\n').filter(Boolean)
+      .map(ln => { try { return JSON.parse(ln); } catch { return null; } })
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * Record that a finding was fixed. Caller passes the finding object +
+ * a short description of the fix pattern (often extracted from the
+ * synthesize_fix replacement text).
+ */
+export function recordFix({ scanRoot, finding, fixPattern, commitSha }) {
+  if (!finding || !finding.family) return null;
+  const entry = {
+    at: new Date().toISOString(),
+    kind: 'fix',
+    repo: repoFingerprint(scanRoot),
+    family: finding.family,
+    severity: finding.severity || null,
+    cwe: finding.cwe || null,
+    vuln: String(finding.vuln || '').slice(0, 160),
+    fixPattern: String(fixPattern || '').slice(0, 280),
+    commitSha: commitSha || null,
+  };
+  _appendLine(_patternsFile(), entry);
+  return entry;
+}
+
+/**
+ * Record a triage decision into the cross-repo store as well. (The
+ * existing posture/triage-memory.js handles the per-repo case; this
+ * mirrors it cross-repo so sibling repos benefit too.)
+ */
+export function recordTriage({ scanRoot, finding, decision, reason }) {
+  if (!finding || !decision) return null;
+  if (!['wont-fix', 'false-positive'].includes(decision)) return null;
+  const entry = {
+    at: new Date().toISOString(),
+    kind: 'triage',
+    repo: repoFingerprint(scanRoot),
+    family: finding.family || null,
+    cwe: finding.cwe || null,
+    vuln: String(finding.vuln || '').slice(0, 160),
+    decision,
+    reason: String(reason || '').slice(0, 280),
+  };
+  _appendLine(_triageFile(), entry);
+  return entry;
+}
+
+/**
+ * Look up cross-repo signals matching a new finding. Returns:
+ *   { siblingFixes: [], siblingTriage: [] }
+ *
+ * Matching is family + (cwe optional). Same-repo entries are excluded
+ * so the result is genuinely cross-repo learning.
+ */
+export function findSiblingSignals(scanRoot, finding) {
+  if (!finding || !finding.family) return { siblingFixes: [], siblingTriage: [] };
+  const here = repoFingerprint(scanRoot);
+  const fam = finding.family;
+  const fixes  = _readAll(_patternsFile()).filter(e => e.repo !== here && e.family === fam);
+  const triage = _readAll(_triageFile())  .filter(e => e.repo !== here && e.family === fam);
+  return {
+    siblingFixes:  fixes.slice(-5).reverse(),  // most recent 5
+    siblingTriage: triage.slice(-5).reverse(),
+  };
+}
+
+/**
+ * Render a short Markdown note suitable for surfacing on a finding card.
+ */
+export function renderSiblingNote(signals) {
+  if (!signals || (!signals.siblingFixes.length && !signals.siblingTriage.length)) return '';
+  const lines = [];
+  lines.push('### Cross-repo signal');
+  lines.push('');
+  if (signals.siblingFixes.length) {
+    lines.push(`Past fixes for this family in other repos:`);
+    for (const f of signals.siblingFixes) {
+      const ago = _ago(f.at);
+      lines.push(`- \`${f.repo}\` ${ago} — ${f.fixPattern || '(no pattern recorded)'}`);
+    }
+    lines.push('');
+  }
+  if (signals.siblingTriage.length) {
+    lines.push(`Past triage for this family in other repos:`);
+    for (const t of signals.siblingTriage) {
+      const ago = _ago(t.at);
+      lines.push(`- \`${t.repo}\` ${ago} — ${t.decision} (${t.reason || 'no reason'})`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function _ago(iso) {
+  if (!iso) return '';
+  const ms = Date.now() - new Date(iso).getTime();
+  const d  = Math.floor(ms / 86_400_000);
+  if (d <= 1) return 'today';
+  if (d < 7) return `${d}d ago`;
+  if (d < 30) return `${Math.floor(d / 7)}w ago`;
+  if (d < 365) return `${Math.floor(d / 30)}mo ago`;
+  return `${Math.floor(d / 365)}y ago`;
+}
+
+export const _internals = { _storeDir, _ensureDir, _ago };

package/src/posture/dep-add-guard.js

@@ -0,0 +1,197 @@
+// Dep-add interception — validate a package about to be installed before
+// it lands in node_modules / site-packages / etc.
+//
+// Checks:
+//   1. Is the package known-malicious? (OSV malicious-packages catalog)
+//   2. Is the package yanked / unpublished / withdrawn?
+//   3. Was it published in the last 7 days? (typosquat-attack indicator)
+//   4. Does the name closely match a popular package? (Levenshtein ≤ 2
+//      against a curated top-1000 list — typosquat risk)
+//   5. Is the package on the project's SCA-policy.yml deny list?
+//
+// Backed by ~/.claude/agentic-security/osv-cache/ (already populated by
+// the engine's SCA pass) plus a bundled top-popular-packages list
+// from sca/popular-packages.json.
+//
+// Intended caller: hooks/pre-bash-guard.js when it spots `npm install <pkg>`,
+// `yarn add`, `pnpm add`, `pip install`, `cargo add`, `gem install` etc.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const CACHE = path.join(process.env.HOME || '/tmp', '.claude', 'agentic-security', 'osv-cache');
+const TYPOSQUAT_LEVENSHTEIN = 2;
+const NEW_PACKAGE_WINDOW_DAYS = 7;
+
+function _osvLookup(ecosystem, name) {
+  const fp = path.join(CACHE, ecosystem, `${name}.json`);
+  if (!fs.existsSync(fp)) return null;
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+
+function _levenshtein(a, b) {
+  if (a === b) return 0;
+  const al = a.length, bl = b.length;
+  if (!al || !bl) return Math.max(al, bl);
+  const v0 = new Array(bl + 1);
+  for (let i = 0; i <= bl; i++) v0[i] = i;
+  for (let i = 0; i < al; i++) {
+    let v1 = i + 1;
+    for (let j = 0; j < bl; j++) {
+      const cost = a[i] === b[j] ? 0 : 1;
+      const ins = v1 + 1;
+      const del = v0[j + 1] + 1;
+      const sub = v0[j] + cost;
+      const next = Math.min(ins, del, sub);
+      v0[j] = v1;
+      v1 = next;
+    }
+    v0[bl] = v1;
+  }
+  return v0[bl];
+}
+
+function _loadPopular(ecosystem) {
+  try {
+    const here = path.dirname(new URL(import.meta.url).pathname);
+    const fp = path.resolve(here, '..', 'sca', 'popular-packages.json');
+    const all = JSON.parse(fs.readFileSync(fp, 'utf8'));
+    return all[ecosystem] || [];
+  } catch { return []; }
+}
+
+function _loadPolicy(scanRoot) {
+  const fp = path.join(scanRoot, '.agentic-security', 'sca-policy.yml');
+  if (!fs.existsSync(fp)) return { deny: [] };
+  try {
+    const body = fs.readFileSync(fp, 'utf8');
+    const names = [];
+    const lines = body.split('\n');
+    let inBlock = false;
+    let blockIndent = -1;
+    for (const ln of lines) {
+      if (/^deny\s*:/.test(ln)) { inBlock = true; blockIndent = -1; continue; }
+      if (!inBlock) continue;
+      if (!ln.trim()) continue;
+      const m = ln.match(/^(\s+)-\s+(.*)$/);
+      if (!m) {
+        if (!/^\s+/.test(ln)) inBlock = false;
+        continue;
+      }
+      const indent = m[1].length;
+      if (blockIndent < 0) blockIndent = indent;
+      if (indent < blockIndent) { inBlock = false; continue; }
+      const val = m[2].trim();
+      // Two shapes:  - name: foo   OR   - foo
+      const nameMatch = val.match(/^name\s*:\s*['"]?([^'"#\s]+)/);
+      if (nameMatch) names.push(nameMatch[1]);
+      else if (!/:/.test(val)) names.push(val.replace(/^['"]|['"]$/g, ''));
+    }
+    return { deny: names };
+  } catch { return { deny: [] }; }
+}
+
+/**
+ * Inspect a single package before install. Returns
+ *   { decision: 'allow' | 'review' | 'deny', reasons: [...] }
+ */
+export function inspectPackage({ ecosystem, name, scanRoot }) {
+  const reasons = [];
+  let decision = 'allow';
+
+  // 1. Project deny list.
+  if (scanRoot) {
+    const policy = _loadPolicy(scanRoot);
+    if (policy.deny.includes(name)) {
+      reasons.push(`Project sca-policy.yml lists ${name} in deny`);
+      decision = 'deny';
+    }
+  }
+
+  // 2. OSV malicious / yanked status from the disk cache.
+  const osv = _osvLookup(ecosystem, name);
+  if (osv) {
+    if (Array.isArray(osv.vulns)) {
+      const mal = osv.vulns.filter(v => /malicious/i.test(JSON.stringify(v.aliases || []).concat(JSON.stringify(v.id || ''))) ||
+                                        /MAL-/.test(v.id || ''));
+      if (mal.length) {
+        reasons.push(`OSV catalog marks ${name} as malicious (${mal.map(v => v.id).join(', ')})`);
+        decision = 'deny';
+      }
+    }
+    if (osv.withdrawn || osv.yanked) {
+      reasons.push(`${name} is withdrawn / yanked from registry`);
+      if (decision === 'allow') decision = 'review';
+    }
+  }
+
+  // 3. New package (potential typosquat).
+  if (osv && osv.published) {
+    const ageMs = Date.now() - new Date(osv.published).getTime();
+    const ageDays = ageMs / 86400000;
+    if (ageDays < NEW_PACKAGE_WINDOW_DAYS) {
+      reasons.push(`${name} published ${Math.round(ageDays)} day(s) ago — fresh-package risk`);
+      if (decision === 'allow') decision = 'review';
+    }
+  }
+
+  // 4. Typosquat distance.
+  const popular = _loadPopular(ecosystem);
+  if (popular.length) {
+    const closest = popular
+      .map(p => ({ p, d: _levenshtein(name.toLowerCase(), p.toLowerCase()) }))
+      .filter(x => x.d > 0 && x.d <= TYPOSQUAT_LEVENSHTEIN)
+      .sort((a, b) => a.d - b.d)[0];
+    if (closest) {
+      reasons.push(`Name is ${closest.d} edit(s) from popular package "${closest.p}" — typosquat risk`);
+      if (decision === 'allow') decision = 'review';
+    }
+  }
+
+  return { decision, reasons };
+}
+
+/**
+ * Parse a shell command line to extract install requests. Returns
+ *   [{ ecosystem, name }, ...] for every package that would be installed.
+ */
+export function parseInstallCommand(cmdline) {
+  if (!cmdline) return [];
+  const reqs = [];
+  // npm / yarn / pnpm
+  const npm = cmdline.match(/\b(?:npm\s+install|yarn\s+add|pnpm\s+add)\s+([^\s|;&]+(?:\s+[^\s|;&]+)*)/);
+  if (npm) {
+    for (const tok of npm[1].split(/\s+/)) {
+      if (tok.startsWith('-')) continue;          // flags
+      if (tok.startsWith('@types/')) continue;    // type defs are low risk
+      const name = tok.replace(/@[\d.^~*<>=].*$/, '').replace(/@latest$/, '');
+      if (name) reqs.push({ ecosystem: 'npm', name });
+    }
+  }
+  // pip
+  const pip = cmdline.match(/\bpip\s+install\s+([^\s|;&]+(?:\s+[^\s|;&]+)*)/);
+  if (pip) {
+    for (const tok of pip[1].split(/\s+/)) {
+      if (tok.startsWith('-') || tok.startsWith('git+') || tok.startsWith('http')) continue;
+      const name = tok.replace(/[<>=!~].*$/, '');
+      if (name && name !== '.') reqs.push({ ecosystem: 'pypi', name });
+    }
+  }
+  // gem install
+  const gem = cmdline.match(/\bgem\s+install\s+([^\s|;&]+(?:\s+[^\s|;&]+)*)/);
+  if (gem) {
+    for (const tok of gem[1].split(/\s+/)) {
+      if (tok.startsWith('-')) continue;
+      reqs.push({ ecosystem: 'rubygems', name: tok });
+    }
+  }
+  // cargo add
+  const cargo = cmdline.match(/\bcargo\s+add\s+([^\s|;&]+)/);
+  if (cargo) reqs.push({ ecosystem: 'cargo', name: cargo[1].split('@')[0] });
+  // go get
+  const goget = cmdline.match(/\bgo\s+get\s+([^\s|;&]+)/);
+  if (goget) reqs.push({ ecosystem: 'golang', name: goget[1].split('@')[0] });
+  return reqs;
+}
+
+export const _internals = { _levenshtein, _osvLookup, _loadPopular, _loadPolicy };

package/src/posture/findings-memory.js

@@ -0,0 +1,152 @@
+// Findings memory — natural-language Q&A over the institutional knowledge
+// the scanner has accumulated. Backs the MCP query_findings_memory tool.
+//
+// Sources searched, in this order:
+//
+//   1. .agentic-security/last-scan.json          current findings
+//   2. .agentic-security/triage-memory.jsonl     past wont-fix / FP decisions
+//   3. .agentic-security/scan-history/*.json     prior scans
+//   4. .agentic-security/AGENTS.md               continual-learning narrative
+//
+// Naive keyword matching for v1. Each match has a `score` (count of query
+// terms matched) and a `source` ('finding' | 'triage' | 'history' |
+// 'agents-md'). Returns top-10 by score.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE = '.agentic-security';
+
+function _read(scanRoot, name) {
+  try { return fs.readFileSync(path.join(scanRoot, STATE, name), 'utf8'); } catch { return null; }
+}
+
+function _readJson(scanRoot, name) {
+  const raw = _read(scanRoot, name);
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+function _terms(query) {
+  return String(query || '').toLowerCase().split(/\s+/).filter(t => t.length >= 2);
+}
+
+function _score(haystack, terms) {
+  const lower = String(haystack || '').toLowerCase();
+  let s = 0;
+  for (const t of terms) if (lower.includes(t)) s++;
+  return s;
+}
+
+function _findingHaystack(f) {
+  return [f.vuln, f.family, f.file, f.severity, f.description, f.cwe, f.id]
+    .filter(Boolean).join(' | ');
+}
+
+function _truncate(s, n = 160) {
+  return String(s || '').replace(/\s+/g, ' ').slice(0, n);
+}
+
+/**
+ * Run a natural-language query over the scanner's accumulated memory.
+ */
+export function queryFindingsMemory(scanRoot, query) {
+  const terms = _terms(query);
+  if (!terms.length) return { results: [], count: 0 };
+
+  const results = [];
+
+  // 1. Current findings.
+  const scan = _readJson(scanRoot, 'last-scan.json');
+  if (scan && Array.isArray(scan.findings)) {
+    for (const f of scan.findings) {
+      const hay = _findingHaystack(f);
+      const score = _score(hay, terms);
+      if (!score) continue;
+      results.push({
+        source: 'finding',
+        score,
+        finding_id: f.id || null,
+        severity: f.severity,
+        family: f.family,
+        file: f.file,
+        line: f.line,
+        snippet: _truncate(f.vuln || f.description || f.family),
+      });
+    }
+  }
+
+  // 2. Triage memory (past decisions).
+  const triageRaw = _read(scanRoot, 'triage-memory.jsonl');
+  if (triageRaw) {
+    const lines = triageRaw.split('\n').filter(Boolean);
+    for (const ln of lines) {
+      let entry; try { entry = JSON.parse(ln); } catch { continue; }
+      const hay = [entry.decision, entry.reason, entry.family, entry.vuln, entry.file].join(' ');
+      const score = _score(hay, terms);
+      if (!score) continue;
+      results.push({
+        source: 'triage',
+        score,
+        decision: entry.decision,
+        at: entry.at,
+        family: entry.family,
+        snippet: _truncate(entry.reason || entry.vuln),
+        bucket: entry.bucket,
+      });
+    }
+  }
+
+  // 3. Scan history.
+  try {
+    const histDir = path.join(scanRoot, STATE, 'scan-history');
+    if (fs.existsSync(histDir)) {
+      const files = fs.readdirSync(histDir).filter(f => f.endsWith('.json')).slice(-10);
+      for (const f of files) {
+        try {
+          const hist = JSON.parse(fs.readFileSync(path.join(histDir, f), 'utf8'));
+          if (!Array.isArray(hist.findings)) continue;
+          for (const x of hist.findings.slice(0, 50)) {
+            const hay = _findingHaystack(x);
+            const score = _score(hay, terms);
+            if (!score) continue;
+            results.push({
+              source: 'history',
+              score,
+              from: f.replace(/\.json$/, ''),
+              severity: x.severity,
+              family: x.family,
+              file: x.file,
+              snippet: _truncate(x.vuln || x.description),
+            });
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+
+  // 4. AGENTS.md narrative.
+  const agents = _read(scanRoot, 'AGENTS.md');
+  if (agents) {
+    const sections = agents.split(/^##\s+/m);
+    for (const sec of sections) {
+      const score = _score(sec, terms);
+      if (!score) continue;
+      const title = sec.split('\n')[0] || '';
+      results.push({
+        source: 'agents-md',
+        score,
+        title: _truncate(title, 80),
+        snippet: _truncate(sec.replace(title, ''), 200),
+      });
+    }
+  }
+
+  // Top-10 by score, ties broken by source priority (finding > triage >
+  // history > agents-md so live data wins).
+  const PRI = { finding: 4, triage: 3, history: 2, 'agents-md': 1 };
+  results.sort((a, b) => (b.score - a.score) || (PRI[b.source] - PRI[a.source]));
+  return { results: results.slice(0, 10), count: results.length };
+}
+
+export const _internals = { _terms, _score, _findingHaystack };

package/src/posture/fix-style-mirror.js

@@ -0,0 +1,118 @@
+// Fix style mirror — find existing fix patterns in the repo for the
+// security-fixer agent to mirror, so remediation matches house style
+// rather than producing canned generic replacements.
+//
+// Strategy: for a given finding (family + file), look at sibling files
+// in the same directory tree for instances of the canonical safe pattern
+// for that family (e.g. parameterized queries for sqli). Return up to 5
+// real examples the agent can reference.
+//
+// Cheap implementation — grep-style search via fs.readdirSync. No regex
+// engine deps. v1 covers the canonical fix patterns for the 8 most-
+// common families.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const SAFE_PATTERNS = {
+  'sqli':              ['\\.query\\([^,)]+,\\s*\\[', '\\.prepare\\(', '\\.execute\\([^,)]+,\\s*\\['],
+  'sql-injection':     ['\\.query\\([^,)]+,\\s*\\[', '\\.prepare\\(', '\\.execute\\([^,)]+,\\s*\\['],
+  'xss':               ['escapeHtml\\(', 'sanitize\\(', 'DOMPurify\\.', '\\bencodeHTML\\b'],
+  'command-injection': ['\\bexecFile\\(', '\\bspawn\\([^,)]+,\\s*\\['],
+  'path-traversal':    ['path\\.resolve\\(', 'path\\.normalize\\(', 'startsWith\\(.*path\\.sep'],
+  'ssrf':              ['allowlist\\.includes\\(', 'url\\.hostname'],
+  'crypto-weak-cipher':['createCipheriv\\(\\s*[\'"`]aes-256-gcm', 'createCipheriv\\(\\s*[\'"`]chacha20'],
+  'crypto-weak-hash':  ['createHash\\(\\s*[\'"`]sha-?256', 'createHash\\(\\s*[\'"`]sha-?512', 'createHash\\(\\s*[\'"`]blake'],
+  'hardcoded-secret':  ['process\\.env\\.[A-Z_]+', 'config\\.[a-z_]+'],
+};
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.bench-cache', 'dist', 'build', 'coverage', '.next']);
+const MAX_FILES = 200;
+const MAX_EXAMPLES = 5;
+const MAX_FILE_SIZE = 100_000;
+
+function _siblings(scanRoot, file, maxDepth = 3) {
+  if (!file) return [];
+  const abs = path.isAbsolute(file) ? file : path.join(scanRoot, file);
+  const baseDir = path.dirname(abs);
+  // Walk upward maxDepth levels and collect files of the same extension.
+  const ext = path.extname(abs);
+  if (!ext) return [];
+  const candidates = [];
+  let cur = baseDir;
+  for (let d = 0; d < maxDepth; d++) {
+    if (!fs.existsSync(cur)) break;
+    _walkUp(cur, ext, candidates);
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return candidates.slice(0, MAX_FILES).filter(p => p !== abs);
+}
+
+function _walkUp(dir, ext, out) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      // Stop one level deep here; outer loop walks upward.
+      try {
+        const childEntries = fs.readdirSync(p, { withFileTypes: true });
+        for (const ce of childEntries) {
+          if (ce.isFile() && ce.name.endsWith(ext)) {
+            out.push(path.join(p, ce.name));
+            if (out.length >= MAX_FILES) return;
+          }
+        }
+      } catch {}
+      continue;
+    }
+    if (e.isFile() && e.name.endsWith(ext)) {
+      out.push(p);
+      if (out.length >= MAX_FILES) return;
+    }
+  }
+}
+
+/**
+ * Returns up to 5 style-mirror examples for a finding's family. Each
+ * example is `{ file, line, snippet }`. The agent can quote these as
+ * "here's how this codebase already does it."
+ */
+export function findStyleExamples(scanRoot, finding) {
+  if (!finding || !finding.family) return [];
+  const patterns = SAFE_PATTERNS[finding.family] ||
+                   SAFE_PATTERNS[String(finding.family).toLowerCase()] || null;
+  if (!patterns) return [];
+  const files = _siblings(scanRoot, finding.file || '');
+  const examples = [];
+  const patternRes = patterns.map(p => new RegExp(p));
+
+  for (const fp of files) {
+    if (examples.length >= MAX_EXAMPLES) break;
+    let content;
+    try {
+      const stat = fs.statSync(fp);
+      if (stat.size > MAX_FILE_SIZE) continue;
+      content = fs.readFileSync(fp, 'utf8');
+    } catch { continue; }
+    for (const re of patternRes) {
+      const m = re.exec(content);
+      if (!m) continue;
+      const line = content.slice(0, m.index).split('\n').length;
+      const lines = content.split('\n');
+      const snippet = lines.slice(Math.max(0, line - 2), Math.min(lines.length, line + 1)).join('\n').trim();
+      examples.push({
+        file: path.relative(scanRoot, fp),
+        line,
+        snippet: snippet.slice(0, 240),
+      });
+      break;
+    }
+  }
+  return examples;
+}
+
+export const _internals = { SAFE_PATTERNS, _siblings };