fullstack-critic 1.0.0

package/src/rules.js

@@ -0,0 +1,182 @@
+'use strict';
+/* critic-ignore-file — this file *defines* detection regexes; scanning it would match its own patterns. */
+/**
+ * Line- and file-level heuristic rules mapped to the 12 CRITIC.md dimensions.
+ * Every rule is universal (no framework assumptions) and carries an action
+ * category: fix | optimize | delete | add.
+ */
+
+// Words that mark an obviously fake / placeholder credential (avoid noisy secret alerts).
+const PLACEHOLDER = /(example|placeholder|your[_-]|xxx+|<[^>]+>|changeme|change_me|dummy|redacted|dummy|sample|todo|process\.env|os\.environ|getenv|env\[|secrets\.|vault|\{\{|\$\{)/i;
+
+const LINE_RULES = [
+  // ---- Security -----------------------------------------------------------
+  {
+    id: 'hardcoded-secret', severity: 'CRITICAL', category: 'fix', dimension: 'Security',
+    title: 'Possible hardcoded credential',
+    test: /\b(api[_-]?key|apikey|secret|passwd|password|access[_-]?token|auth[_-]?token|private[_-]?key|access[_-]?key[_-]?id)\b["']?\s*[:=]\s*["'][^"'\s]{12,}["']/i,
+    skipIf: (line) => PLACEHOLDER.test(line),
+    problem: 'A secret appears to be committed in source.',
+    impact: 'Anyone with repo read access obtains the credential; git history keeps it after deletion.',
+    fix: 'Move to a secret manager / runtime env var and rotate the exposed value.',
+    verify: 'grep confirms no literal remains; service accepts the rotated secret.',
+  },
+  {
+    id: 'aws-access-key', severity: 'CRITICAL', category: 'fix', dimension: 'Security',
+    title: 'AWS access key ID pattern',
+    test: /\bAKIA[0-9A-Z]{16}\b/,
+    problem: 'String matches the AWS access-key-id format.',
+    impact: 'Cloud account compromise if paired with a secret key.',
+    fix: 'Rotate immediately; load credentials from the environment or an instance role.',
+    verify: 'aws sts get-caller-identity with the old key fails.',
+  },
+  {
+    id: 'private-key', severity: 'CRITICAL', category: 'fix', dimension: 'Security',
+    title: 'Private key material committed',
+    test: /-----BEGIN (RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----/,
+    problem: 'A private key block is embedded in a tracked file.',
+    impact: 'Full loss of the key trust boundary.',
+    fix: 'Remove from source, rotate the keypair, add the file to .gitignore.',
+    verify: 'openssl pkey -in <file> fails / file untracked.',
+  },
+  {
+    id: 'code-eval', severity: 'HIGH', category: 'fix', dimension: 'Security',
+    title: 'Dynamic code evaluation',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.jsx', '.py', '.rb', '.php'],
+    test: /(^|[^.\w])(eval|Function)\s*\(|\bexec\s*\(\s*f["']/,
+    problem: 'eval/Function executes arbitrary runtime-constructed code.',
+    impact: 'Remote code execution if any input reaches the evaluated string.',
+    fix: 'Replace with a lookup table, JSON.parse, or an AST-restricted evaluator.',
+    verify: 'no eval/Function call sites remain on untrusted input.',
+  },
+  {
+    id: 'command-injection', severity: 'HIGH', category: 'fix', dimension: 'Security',
+    title: 'Shell command built from string',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.rb', '.go', '.php'],
+    test: /(execSync|exec|spawn|child_process\.exec|os\.system|subprocess\.(run|call|Popen|check_output)|Runtime\.getRuntime\(\)\.exec)\s*\([^)]*(\$\{|%|["']\s*\+|f["']|shell\s*=\s*True)/,
+    problem: 'A shell command interpolates variables — classic command-injection vector.',
+    impact: 'Attacker-controlled input runs arbitrary shell commands.',
+    fix: 'Pass an argument array and never a shell string; validate against an allowlist.',
+    verify: 'injection payload in the input is treated as a literal argument.',
+  },
+  {
+    id: 'sql-injection', severity: 'HIGH', category: 'fix', dimension: 'Security',
+    title: 'SQL string built by concatenation/interpolation',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.rb', '.php', '.java', '.go'],
+    test: /\b(SELECT|INSERT\s+INTO|UPDATE|DELETE\s+FROM|WHERE)\b[^;]*\b\$\{|\+\s*\w+\s*\+\s*["'][^"']*["']|["'][^"']*\bWHERE\b[^"']*["']\s*%|f["'][^"']*\b(SELECT|WHERE)\b/i,
+    skipIf: (line) => /placeholder|\?\?|\$1|\bparams\b/i.test(line),
+    problem: 'Query text is assembled from variables instead of bound parameters.',
+    impact: 'SQL injection — data exfiltration or destruction.',
+    fix: 'Use parameterised queries / ORM bind params.',
+    verify: "quote-injection payload is bound as a value, not executed.",
+  },
+  {
+    id: 'xss-sink', severity: 'HIGH', category: 'fix', dimension: 'Security',
+    title: 'Untrusted HTML injection sink',
+    ext: ['.js', '.jsx', '.ts', '.tsx', '.html', '.vue', '.svelte'],
+    test: /(\.innerHTML\s*=|dangerouslySetInnerHTML|document\.write\(|\{\{\{.*\}\}\}|v-html=|\.html\()/,
+    problem: 'Markup is written from a value that may be user-controlled.',
+    impact: 'Cross-site scripting / DOM-based XSS.',
+    fix: 'Sanitise with a vetted library or render as text / auto-escaping template.',
+    verify: '<script> payload renders inert.',
+  },
+  {
+    id: 'jwt-verify-off', severity: 'HIGH', category: 'fix', dimension: 'Security',
+    title: 'JWT signature verification disabled or alg:none',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.go', '.java'],
+    test: /(verify\s*:\s*false|algorithms\s*[:=]\s*\[?\s*["']none["']|\.decode\([^,)]*\)\s*;?|jwt\.decode\([^)]*verify\s*=\s*False)/i,
+    problem: 'Token is decoded without verifying its signature.',
+    impact: 'Anyone can forge an accepted token — full auth bypass.',
+    fix: 'Verify signature with a fixed algorithm allowlist before trusting claims.',
+    verify: 'a token with alg:none is rejected.',
+  },
+  {
+    id: 'cors-wildcard', severity: 'MEDIUM', category: 'fix', dimension: 'Security',
+    title: 'CORS wildcard with credentials',
+    ext: ['.js', '.ts', '.py', '.go', '.java', '.rb'],
+    test: /(access[_-]?control[_-]?allow[_-]?origin["']?\s*[:,=]\s*["']\*["']|origin\s*:\s*["']\*["'][\s\S]{0,40}credentials\s*:\s*true|cors\(\s*\*?\s*\))/i,
+    problem: 'Either reflects all origins or pairs "*" with credentialed requests.',
+    impact: 'Cross-origin credentialed reads by any site.',
+    fix: 'Allowlist exact origins; never combine "*" with credentials.',
+    verify: 'request from a non-allowlisted origin gets no ACAO header.',
+  },
+
+  // ---- Correctness --------------------------------------------------------
+  {
+    id: 'swallowed-error', severity: 'HIGH', category: 'fix', dimension: 'Correctness',
+    title: 'Empty / no-op error handler (error swallowed)',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx', '.java', '.cs', '.php', '.go', '.py', '.rb'],
+    test: /catch\s*(\([^)]*\))?\s*\{[\s\t]*\}|except[^:]*:\s*(pass|\.\.\.)\s*$|except\s*:\s*pass/,
+    problem: 'A caught error is discarded with no handling or logging.',
+    impact: 'Failures vanish silently; data corruption goes unnoticed.',
+    fix: 'Handle, log with context, or rethrow. Never leave an empty catch.',
+    verify: 'triggering the error path surfaces a log/rethrow.',
+  },
+  {
+    id: 'loose-equality', severity: 'LOW', category: 'optimize', dimension: 'Correctness',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx'],
+    title: 'Loose equality (==) can coerce unexpectedly',
+    test: /[^=!<>]==[^=]|!=[^=]/,
+    skipIf: (line) => /=>|===|!==|==\s*null|!=\s*null/.test(line),
+    problem: '== / != apply type coercion.',
+    impact: 'Subtle logic bugs comparing 0, "", false, null.',
+    fix: 'Prefer === / !==.',
+    verify: 'strict comparison keeps behaviour for the intended operands.',
+  },
+
+  // ---- Code quality / cleanliness ----------------------------------------
+  {
+    id: 'todo-comment', severity: 'INFO', category: 'delete', dimension: 'Code quality',
+    title: 'Unresolved TODO/FIXME/HACK',
+    test: /\b(TODO|FIXME|HACK|XXX)\b[:\s]/,
+    problem: 'Undated, unassigned work marker left in code.',
+    impact: 'Known debt silently accumulates.',
+    fix: 'Resolve it or track it in the issue tracker and remove the marker.',
+    verify: 'marker gone or linked to a tracked issue.',
+  },
+  {
+    id: 'debug-leftover', severity: 'LOW', category: 'delete', dimension: 'Code quality',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx'],
+    title: 'debugger statement left in code',
+    test: /^\s*debugger\s*;?\s*$/,
+    problem: 'A debugger breakpoint ships to source.',
+    impact: 'Halts execution when devtools are open.',
+    fix: 'Delete it.',
+    verify: 'grep -n debugger returns nothing.',
+  },
+  {
+    id: 'console-log', severity: 'INFO', category: 'delete', dimension: 'Code quality',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx', '.py'],
+    title: 'Debug logging (console.log / print) in source',
+    test: /(^|[^.\w])(console\.(log|debug)|print|System\.out\.print)\s*\(/,
+    skipIf: (line) => /^\s*(#|\/\/|\*)/.test(line),
+    problem: 'Ad-hoc debug output left in committed code.',
+    impact: 'Noisy logs; can leak sensitive values to stdout.',
+    fix: 'Use the structured logger at the right level, or remove.',
+    verify: 'no console.log/print debug calls remain.',
+  },
+
+  // ---- Database -----------------------------------------------------------
+  {
+    id: 'select-star', severity: 'LOW', category: 'optimize', dimension: 'Database',
+    title: 'SELECT * fetches all columns',
+    test: /\bSELECT\s+\*\s+FROM\b/i,
+    problem: 'Reads every column regardless of need.',
+    impact: 'Wasted I/O and memory; breaks when schema adds columns.',
+    fix: 'Select only required columns; ensure covering indexes for hot queries.',
+    verify: 'query lists explicit columns.',
+  },
+  {
+    id: 'unbounded-query', severity: 'MEDIUM', category: 'optimize', dimension: 'Database',
+    title: 'Collection query without LIMIT/pagination',
+    ext: ['.js', '.ts', '.py', '.rb', '.go', '.java', '.php', '.sql'],
+    test: /\.(find|getAll|all|select|list)\s*\(\s*\)|\bSELECT\b[^;]*\bFROM\b(?![^;]*\b(LIMIT|TOP|fetch)\b)/i,
+    skipIf: (line) => /\b(count|exists|where|limit|id\s*=|primarykey)\b/i.test(line),
+    problem: 'A whole-collection read has no upper bound.',
+    impact: 'Memory/latency blowup as the table grows.',
+    fix: 'Add keyset/cursor pagination or an explicit LIMIT.',
+    verify: 'endpoint returns a bounded page size.',
+  },
+];
+
+module.exports = { LINE_RULES, PLACEHOLDER };

package/src/util.js

@@ -0,0 +1,99 @@
+'use strict';
+/**
+ * Shared filesystem helpers for the critic.
+ * Design goal: touch 100% of the project's resources — never silently skip a file.
+ * Every skipped file is counted and the reason is recorded so the report can prove coverage.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// Directories that are never first-party source. Skipped, but counted + reported.
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.hg', '.svn', 'dist', 'build', '.next', '.nuxt',
+  'out', 'coverage', '.nyc_output', 'vendor', '__pycache__', '.venv', 'venv',
+  '.tox', 'target', '.gradle', '.serverless', '.turbo', '.cache',
+  '.critic', '.critic-memory',
+]);
+
+// Extensions that are definitely not scannable text.
+const BINARY_EXT = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.bmp', '.tiff', '.pdf',
+  '.zip', '.gz', '.tar', '.tgz', '.bz2', '.7z', '.rar', '.jar', '.war',
+  '.woff', '.woff2', '.ttf', '.eot', '.otf', '.mp3', '.mp4', '.wav', '.avi',
+  '.mov', '.webm', '.so', '.dylib', '.dll', '.exe', '.bin', '.obj', '.o', '.a',
+  '.class', '.pyc', '.pyo', '.lockb', '.wasm', '.pdb', '.dat',
+]);
+
+const MAX_FILE_BYTES = 1024 * 1024; // 1 MB — larger files are counted, not line-scanned.
+
+function isBinaryExt(ext) {
+  return BINARY_EXT.has(ext.toLowerCase());
+}
+
+/**
+ * Recursively walk a project. Returns { files, skipped }.
+ * files:  [{ abs, rel, ext, size }]  — every non-ignored, non-binary file (100% of scannable resources)
+ * skipped:[{ rel, reason }]          — every resource deliberately not line-scanned (proof of coverage)
+ */
+function walk(root) {
+  const files = [];
+  const skipped = [];
+
+  function recurse(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      skipped.push({ rel: path.relative(root, dir) || '.', reason: `unreadable directory (${e.code})` });
+      return;
+    }
+    for (const ent of entries) {
+      const abs = path.join(dir, ent.name);
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) {
+          skipped.push({ rel: rel + '/', reason: `dependency / build / VCS directory (${ent.name})` });
+          continue;
+        }
+        recurse(abs);
+        continue;
+      }
+      if (ent.isSymbolicLink && ent.isSymbolicLink()) {
+        skipped.push({ rel, reason: 'symbolic link (not followed)' });
+        continue;
+      }
+      let st;
+      try { st = fs.statSync(abs); } catch (e) { skipped.push({ rel, reason: `stat failed (${e.code})` }); continue; }
+      const ext = path.extname(ent.name).toLowerCase();
+      if (isBinaryExt(ext)) {
+        skipped.push({ rel, reason: `binary asset (${ext})` });
+        continue;
+      }
+      if (st.size > MAX_FILE_BYTES) {
+        skipped.push({ rel, reason: `file larger than ${MAX_FILE_BYTES} bytes (counted, not line-scanned)` });
+        continue;
+      }
+      files.push({ abs, rel, ext, size: st.size });
+    }
+  }
+
+  recurse(root);
+  return { files, skipped };
+}
+
+function readText(abs) {
+  try {
+    const buf = fs.readFileSync(abs);
+    // A NUL byte in the first 800 bytes is the classic binary signature.
+    if (buf.subarray(0, 800).includes(0)) return null;
+    return buf.toString('utf8');
+  } catch (e) {
+    return null;
+  }
+}
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+module.exports = { walk, readText, exists, SKIP_DIRS, MAX_FILE_BYTES };

package/src/watcher.js

@@ -0,0 +1,127 @@
+'use strict';
+/**
+ * Watch mode: attach to an in-progress workflow and keep reviewing in the background.
+ * On every change batch it re-runs the analyzer, diffs findings against the last pass,
+ * prints concise feedback (what appeared / what got resolved), and rewrites the report file.
+ * Cross-platform: watches each directory individually (no reliance on recursive:true).
+ */
+const fs = require('fs');
+const path = require('path');
+const { analyze } = require('./analyzer');
+const { renderConsole, renderMarkdown } = require('./report');
+const { SKIP_DIRS } = require('./util');
+
+const IGNORED_OUTPUT = new Set(['.critic-report.md', '.critic-review.json', 'RUN_STATE.md', 'REVIEW_HISTORY.md']);
+
+function listDirs(root) {
+  const dirs = [root];
+  const stack = [root];
+  while (stack.length) {
+    const d = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(d, e.name);
+      dirs.push(full);
+      stack.push(full);
+    }
+  }
+  return dirs;
+}
+
+function keyOf(f) {
+  // Key on rule + file + evidence text (NOT line) so inserting/deleting lines elsewhere
+  // does not make every shifted finding look simultaneously new and fixed.
+  return `${f.file}::${f.ruleId}::${(f.evidence || '').slice(0, 120)}`;
+}
+
+function watch(root, opts = {}) {
+  const debounceMs = opts.debounceMs || 400;
+  let last = new Map(); // key -> finding
+  let first = true;
+  let timer = null;
+  const pending = new Set();
+  const watchers = new Map();
+
+  function runPass() {
+    const result = analyze(root);
+    const current = new Map(result.findings.map((f) => [keyOf(f), f]));
+
+    if (first) {
+      process.stdout.write(renderConsole(result) + '\n');
+      first = false;
+    } else {
+      const added = [...current.values()].filter((f) => !last.has(keyOf(f)));
+      const resolved = [...last.values()].filter((f) => !current.has(keyOf(f)));
+      const time = new Date().toLocaleTimeString();
+      if (!added.length && !resolved.length) {
+        process.stdout.write(`\x1b[90m[${time}] no change in findings (${result.findings.length} total).\x1b[0m\n`);
+      } else {
+        process.stdout.write(`\x1b[36m[${time}] critic feedback\x1b[0m — ${result.findings.length} total\n`);
+        for (const f of added.slice(0, 15)) {
+          process.stdout.write(`  \x1b[31m+ NEW ${f.severity}\x1b[0m ${f.file}:${f.line}  ${f.title}\n`);
+        }
+        for (const f of resolved.slice(0, 15)) {
+          process.stdout.write(`  \x1b[32m- FIXED\x1b[0m ${f.file}:${f.line}  ${f.title}\n`);
+        }
+        if (added.length > 15) process.stdout.write(`  … ${added.length - 15} more new\n`);
+      }
+    }
+    last = current;
+
+    if (opts.report) {
+      try { fs.writeFileSync(opts.report, renderMarkdown(result)); }
+      catch (e) { process.stderr.write(`could not write report ${opts.report}: ${e.message}\n`); }
+    }
+    if (opts.json) {
+      try { fs.writeFileSync(opts.json, JSON.stringify(result, null, 2)); }
+      catch (e) { process.stderr.write(`could not write json ${opts.json}: ${e.message}\n`); }
+    }
+  }
+
+  function schedule(file) {
+    if (file && IGNORED_OUTPUT.has(path.basename(file))) return; // ignore our own writes
+    pending.add(file || '.');
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      pending.clear();
+      try { runPass(); } catch (e) { process.stderr.write(`critic watch error: ${e.message}\n`); }
+    }, debounceMs);
+  }
+
+  function addWatcher(dir) {
+    if (watchers.has(dir)) return;
+    try {
+      const w = fs.watch(dir, { persistent: true }, (_event, filename) => {
+        // A new subdirectory appearing: start watching it too.
+        if (filename) {
+          const maybe = path.join(dir, filename);
+          try { if (fs.statSync(maybe).isDirectory() && !SKIP_DIRS.has(filename)) addWatcher(maybe); } catch { /* path vanished mid-edit */ }
+        }
+        schedule(filename);
+      });
+      w.on('error', () => { /* dir removed while watching */ });
+      watchers.set(dir, w);
+    } catch { /* directory unreadable — skip watching it */ }
+  }
+
+  for (const d of listDirs(root)) addWatcher(d);
+  runPass();
+
+  process.stdout.write(
+    `\n\x1b[90mWatching ${path.resolve(root)} for changes — ${watchers.size} dir(s). ` +
+    `Report: ${opts.report || 'stdout only'}. Ctrl+C to stop.\x1b[0m\n`
+  );
+
+  return {
+    close() {
+      for (const w of watchers.values()) { try { w.close(); } catch { /* already closed */ } }
+      watchers.clear();
+      if (timer) clearTimeout(timer);
+    },
+  };
+}
+
+module.exports = { watch };

package/tests/critic.test.js

@@ -0,0 +1,95 @@
+'use strict';
+/* critic-ignore-file — contains intentionally vulnerable fixture strings used to prove detection works. */
+/**
+ * Critic self-tests (zero-dependency, runs on `node --test`).
+ * These prove the tool's own behaviour and satisfy its "add tests" finding for itself.
+ */
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { analyze } = require('../src/analyzer');
+const { renderMarkdown, renderConsole } = require('../src/report');
+const { analyzeDeps } = require('../src/deps');
+const { walk } = require('../src/util');
+
+function fixtureDir(files) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'critic-test-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  return dir;
+}
+
+test('walk counts every non-ignored file (100% coverage proof)', () => {
+  const dir = fixtureDir({
+    'a.js': 'const x = 1;\n',
+    'src/b.py': 'print(1)\n',
+    'node_modules/pkg/c.js': 'ignored\n',
+  });
+  const { files, skipped } = walk(dir);
+  const rels = files.map((f) => f.rel).sort();
+  assert.deepStrictEqual(rels, ['a.js', 'src/b.py']);
+  assert.ok(skipped.some((s) => s.rel.startsWith('node_modules/')), 'node_modules is counted as skipped, not silently dropped');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('analyzer detects the core vulnerability classes', () => {
+  const dir = fixtureDir({
+    'app.js': [
+      'const api_key = "sk-live-aaaaaaaaaaaaaaaaaaaaaa";',   // hardcoded secret (CRITICAL)
+      'require("child_process").execSync("ls " + user);',    // command injection (HIGH)
+      'try { f(); } catch (e) {}',                           // swallowed error (HIGH)
+      'return "SELECT * FROM t WHERE id=" + id;',            // sql concat + select star
+    ].join('\n'),
+  });
+  const r = analyze(dir);
+  const ids = new Set(r.findings.map((f) => f.ruleId));
+  assert.ok(ids.has('hardcoded-secret'), 'detects secret');
+  assert.ok(ids.has('command-injection'), 'detects command injection');
+  assert.ok(ids.has('swallowed-error'), 'detects swallowed error');
+  assert.ok(r.counts.CRITICAL >= 1, 'a CRITICAL is present');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('dependency analysis flags missing lockfile and unpinned ranges', () => {
+  const dir = fixtureDir({
+    'package.json': JSON.stringify({ name: 'x', version: '1.0.0', dependencies: { leftpad: '*', express: '^4.0.0' } }),
+  });
+  const { ecosystems, findings } = analyzeDeps(dir);
+  assert.strictEqual(ecosystems[0].name, 'npm');
+  assert.strictEqual(ecosystems[0].lock, null, 'no lockfile detected');
+  assert.ok(findings.some((f) => /no lock file/i.test(f.title)), 'missing-lock finding raised');
+  assert.ok(findings.some((f) => /Unpinned dependency "leftpad"/.test(f.title)), 'unpinned * flagged');
+  assert.ok(!findings.some((f) => /Unpinned dependency "express"/.test(f.title)), 'caret range not flagged');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('report groups the action plan into fix / optimize / delete / add', () => {
+  const dir = fixtureDir({ 'app.js': 'try { f(); } catch (e) {}\n// TODO: x\nreturn "SELECT * FROM t";\n' });
+  const r = analyze(dir);
+  const md = renderMarkdown(r);
+  assert.match(md, /## Prioritised Action Plan/);
+  assert.match(md, /### FIX —/);
+  assert.match(md, /### DELETE —/);
+  assert.match(md, /### OPTIMIZE —/);
+  assert.match(md, /## Coverage \(100% of resources/);
+  for (const line of renderConsole(r).split('\n')) assert.ok(typeof line === 'string');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('findings always carry an exact location', () => {
+  const dir = fixtureDir({ 'app.js': 'const api_key = "sk-live-aaaaaaaaaaaaaaaaaaaaaa";\n' });
+  const r = analyze(dir);
+  assert.ok(r.findings.length > 0);
+  for (const f of r.findings) {
+    assert.ok(typeof f.file === 'string' && f.file.length > 0, 'finding has a file');
+    assert.ok(Number.isInteger(f.line) && f.line >= 1, 'finding has a line number');
+    assert.ok(['fix', 'optimize', 'delete', 'add'].includes(f.category), 'finding has a valid category');
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+});