codebase-onboarder 0.1.0

package/shared/analyzer/scan.js

@@ -0,0 +1,473 @@
+// The scanner: walks a FileSource, dispatches per-language analyzers,
+// resolves imports into edges, and hands back one big plain-data result.
+//
+// FileSource interface (both adapters implement it):
+//   list(dir) -> [{ name, path, type: 'file'|'dir' }]
+//   read(path) -> string
+// Paths are repo-relative, POSIX style ('' is the root).
+
+import { languageFor } from './languages/index.js';
+import { dirOf, baseName, extOf } from './pathUtil.js';
+import { codeStats, complexityOf } from './metrics.js';
+import { analyzeSecurityFile } from './security.js';
+import { analyzeLicenses } from './licenses.js';
+import { analyzeWorkflows } from './workflows.js';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out', '.next',
+  '.nuxt', 'target', 'vendor', '__pycache__', '.venv', 'venv', 'env',
+  '.idea', '.vscode', 'coverage', '.cache', '.turbo', 'tmp', 'temp',
+  'DerivedData', 'Pods', '.gradle', 'bin', 'obj',
+]);
+
+const SKIP_FILES = new Set([
+  'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'composer.lock',
+  'Gemfile.lock', 'Cargo.lock', 'poetry.lock', '.DS_Store',
+]);
+
+const SKIP_EXTS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.icns', '.svg',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot', '.mp4', '.mov', '.mp3',
+  '.wav', '.zip', '.gz', '.tar', '.rar', '.7z', '.pdf', '.jar', '.war',
+  '.class', '.o', '.a', '.so', '.dylib', '.dll', '.exe', '.pyc', '.wasm',
+  '.min.js', '.min.css', '.map', '.lock', '.bin', '.db', '.sqlite',
+]);
+
+export const DEFAULT_LIMITS = { maxFiles: 4000, maxFileSize: 200 * 1024 };
+
+function shouldSkipFile(name) {
+  if (SKIP_FILES.has(name)) return true;
+  if (SKIP_EXTS.has(extOf(name))) return true;
+  // extOf() only sees the final suffix, so name the common bundle shapes here.
+  return /\.min\.(js|css)$/i.test(name);
+}
+
+export async function scanRepo(source, options = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...options };
+  const onProgress = options.onProgress || (() => {});
+  const startedAt = Date.now();
+
+  const ignore = await buildIgnoreMatcher(source);
+
+  // Every way a file or directory can drop out of the scan, counted apart.
+  // One integer for all of them hid the difference between "we ignored a
+  // lockfile" and "we could not read your source" — and only one of those is
+  // something the reader needs to know about.
+  const skips = {
+    ignored: 0, // matched a .gitignore rule
+    vendorDir: 0, // node_modules, dist, .git, any dotfolder
+    notSource: 0, // images, lockfiles, minified bundles
+    listFailed: 0, // the directory would not list
+    notCode: 0, // no analyzer for this extension (README.md, .yml, …)
+    readFailed: 0, // the file would not read
+    tooLarge: 0, // over maxFileSize
+    analyzeFailed: 0, // the language analyzer threw
+  };
+
+  // ---- Walk --------------------------------------------------------------
+  const allFiles = [];
+  let truncated = null;
+  const queue = [''];
+  walk: while (queue.length) {
+    const dir = queue.shift();
+    let entries;
+    try {
+      entries = await source.list(dir);
+    } catch {
+      skips.listFailed++;
+      continue;
+    }
+    for (const entry of entries) {
+      if (allFiles.length >= limits.maxFiles) {
+        // Stop the entire walk, not just this directory. A plain `break` here
+        // left every already-queued directory to be listed anyway, so the cap
+        // was both slower and less predictable than it looked.
+        truncated = { atFiles: allFiles.length, dirsQueued: queue.length };
+        break walk;
+      }
+      if (ignore(entry.path)) {
+        skips.ignored++;
+        continue;
+      }
+      if (entry.type === 'dir') {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+          skips.vendorDir++;
+          continue;
+        }
+        queue.push(entry.path);
+      } else {
+        if (shouldSkipFile(entry.name)) {
+          skips.notSource++;
+          continue;
+        }
+        allFiles.push(entry.path);
+      }
+    }
+    onProgress({ phase: 'walk', found: allFiles.length });
+  }
+  allFiles.sort();
+
+  const fileSet = new Set(allFiles);
+  const dirSet = new Set(['']);
+  for (const p of allFiles) {
+    let d = dirOf(p);
+    while (true) {
+      if (dirSet.has(d)) break;
+      dirSet.add(d);
+      d = dirOf(d);
+    }
+  }
+  const has = (p) => fileSet.has(p);
+  const hasDir = (d) => dirSet.has(d);
+  const nameIndex = new Map();
+  for (const p of allFiles) {
+    const n = baseName(p);
+    if (!nameIndex.has(n)) nameIndex.set(n, p);
+  }
+  const findByName = (n) => nameIndex.get(n) || null;
+
+  const context = {
+    hasDir,
+    findByName,
+    modulePath: await readModulePath(source),
+    tsPaths: await readTsConfigPaths(source),
+  };
+
+  // ---- Parse ---------------------------------------------------------------
+  // Reads run a window ahead of the analysis; the analysis stays strictly in
+  // path order. Waiting for one `read` to land before starting the next was the
+  // largest wall-clock cost of a scan and the one with the least to show for
+  // it — every adapter behind `FileSource` is I/O, and neither `node:fs` nor the
+  // File System Access API cares how many requests are outstanding.
+  //
+  // Order matters more than it looks: `files`, `edges` and every skip count
+  // have to come out identical no matter how the reads interleave, or two scans
+  // of one repo would disagree. So the window only prefetches — the loop below
+  // consumes it one file at a time, in the order `allFiles` was sorted into.
+  //
+  // The language is resolved here and kept. The resolve phase needs the same
+  // answer per file and used to ask `languageFor` for it a second time.
+  const files = [];
+  const langOf = new Map();
+  let parsed = 0;
+  const codeFiles = [];
+  for (const path of allFiles) {
+    const lang = languageFor(path);
+    if (!lang) {
+      skips.notCode++;
+      continue;
+    }
+    langOf.set(path, lang);
+    codeFiles.push(path);
+  }
+
+  for await (const { path, text, failed } of readAhead(source, codeFiles)) {
+    if (failed) {
+      skips.readFailed++;
+      continue;
+    }
+    if (text.length > limits.maxFileSize) {
+      skips.tooLarge++;
+      continue;
+    }
+    const lang = langOf.get(path);
+    let analysis;
+    try {
+      analysis = lang.analyze(text, path);
+    } catch {
+      skips.analyzeFailed++;
+      continue;
+    }
+    const cs = codeStats(text, lang.id);
+    const findings = analyzeSecurityFile(text, lang.id);
+    const docRatio = cs.code + cs.comment > 0 ? Math.round((cs.comment / (cs.code + cs.comment)) * 100) : 0;
+    files.push({
+      path,
+      dir: dirOf(path),
+      name: baseName(path),
+      ext: extOf(path),
+      lang: lang.id,
+      size: text.length,
+      loc: cs.code,
+      comment: cs.comment,
+      blank: cs.blank,
+      lines: cs.lines,
+      docRatio,
+      complexity: complexityOf(text, lang.id),
+      findings: findings.length ? findings : undefined,
+      ...analysis,
+    });
+    parsed++;
+    if (parsed % 25 === 0) onProgress({ phase: 'parse', done: parsed });
+  }
+  onProgress({ phase: 'parse', done: parsed });
+  // ---- Resolve imports into edges -------------------------------------------
+  const edges = [];
+  const edgeKeys = new Map(); // key -> edge
+  const externals = new Map(); // package name -> Set of files
+
+  // What share of the imports we found did we manage to place? A regex-based
+  // analyzer owes its reader this number more than any other: it is the
+  // engine's own estimate of how much of the graph is missing.
+  const tally = { total: 0, internal: 0, external: 0, unresolved: 0 };
+  const unresolvedSpecs = new Map(); // spec -> { count, from }
+
+  // Go resolves an import to a *directory*, and every .go file in it is a
+  // target. Indexed once here rather than scanned per import — a Go repo with
+  // 1,000 files and 8,000 imports was doing eight million comparisons for it.
+  const goFilesByDir = new Map();
+  for (const f of files) {
+    if (f.lang !== 'go') continue;
+    const bucket = goFilesByDir.get(f.dir);
+    if (bucket) bucket.push(f.path);
+    else goFilesByDir.set(f.dir, [f.path]);
+  }
+
+  for (const file of files) {
+    const lang = langOf.get(file.path);
+    for (const imp of file.imports) {
+      tally.total++;
+      const res = lang.resolveImport(imp.spec, file.path, has, context, imp);
+      if (res.path) {
+        tally.internal++;
+        addEdge(edges, edgeKeys, file.path, res.path, 'imports', imp.symbols);
+      } else if (res.packageDir) {
+        tally.internal++;
+        for (const target of goFilesByDir.get(res.packageDir) || []) {
+          addEdge(edges, edgeKeys, file.path, target, 'imports', imp.symbols);
+        }
+      } else if (res.external) {
+        tally.external++;
+        if (!externals.has(res.external)) externals.set(res.external, new Set());
+        externals.get(res.external).add(file.path);
+      } else {
+        // Every resolver ends with `return { unresolved: spec }`. This branch
+        // is where that used to disappear for want of an `else` — the import
+        // was counted nowhere and the graph simply came up short in silence.
+        tally.unresolved++;
+        const spec = res.unresolved || imp.spec;
+        const seen = unresolvedSpecs.get(spec);
+        if (seen) seen.count++;
+        else unresolvedSpecs.set(spec, { spec, count: 1, from: file.path });
+      }
+    }
+  }
+
+  // Resolved-or-correctly-external over everything we saw. An external package
+  // counts as a success: the resolver knew what it was looking at.
+  const confidence = tally.total
+    ? Math.round(((tally.internal + tally.external) / tally.total) * 100)
+    : 100;
+  const worstUnresolved = [...unresolvedSpecs.values()]
+    .sort((a, b) => b.count - a.count || a.spec.localeCompare(b.spec))
+    .slice(0, 12);
+
+  const externalList = [...externals.entries()]
+    .map(([name, usedBySet]) => ({ name, usedBy: [...usedBySet].sort() }))
+    .sort((a, b) => b.usedBy.length - a.usedBy.length || a.name.localeCompare(b.name));
+
+  // Folder rollups with full size/LOC/documentation breakdown
+  const filesPerDir = new Map();
+  const folderData = new Map();
+  for (const p of allFiles) {
+    const d = dirOf(p);
+    filesPerDir.set(d, (filesPerDir.get(d) || 0) + 1);
+  }
+  for (const path of dirSet) {
+    if (!path) continue;
+    folderData.set(path, {
+      path,
+      name: baseName(path),
+      depth: path.split('/').length,
+      fileCount: filesPerDir.get(path) || 0,
+      loc: 0,
+      comment: 0,
+      blank: 0,
+      size: 0,
+      langs: {},
+      hasReadme: false,
+    });
+  }
+  for (const p of allFiles) {
+    const d = dirOf(p);
+    const bn = baseName(p).toLowerCase();
+    if (bn.startsWith('readme.') || bn === 'readme') {
+      const entry = folderData.get(d);
+      if (entry) entry.hasReadme = true;
+    }
+  }
+  for (const f of files) {
+    const entry = folderData.get(f.dir);
+    if (entry) {
+      entry.loc += f.loc || 0;
+      entry.comment += f.comment || 0;
+      entry.blank += f.blank || 0;
+      entry.size += f.size || 0;
+      entry.langs[f.lang] = (entry.langs[f.lang] || 0) + (f.loc || 0);
+    }
+  }
+  const folders = [...folderData.values()]
+    .map((f) => ({
+      ...f,
+      docRatio: f.loc + f.comment > 0 ? Math.round((f.comment / (f.loc + f.comment)) * 100) : 0,
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+
+  const skippedTotal = Object.values(skips).reduce((a, b) => a + b, 0);
+
+  const stats = {
+    filesTotal: allFiles.length,
+    filesParsed: parsed,
+    skipped: skippedTotal,
+    skips,
+    truncated,
+    edgeCount: edges.length,
+    imports: {
+      total: tally.total,
+      internal: tally.internal,
+      external: tally.external,
+      unresolved: tally.unresolved,
+      confidence,
+      worst: worstUnresolved,
+    },
+    tookMs: Date.now() - startedAt,
+    languages: countBy(files, (f) => f.lang),
+    languageLoc: files.reduce((acc, f) => {
+      acc[f.lang] = (acc[f.lang] || 0) + (f.loc || 0);
+      return acc;
+    }, {}),
+  };
+
+  const [workflows, licenseReport] = await Promise.all([
+    analyzeWorkflows(source).catch(() => []),
+    analyzeLicenses(source, context.manifest || {}).catch(() => null),
+  ]);
+
+  return {
+    root: source.root || '(unknown)',
+    name: source.name || baseName(source.root || '') || 'repo',
+    scannedAt: new Date().toISOString(),
+    stats,
+    allFiles,
+    files,
+    edges,
+    externals: externalList,
+    folders,
+    workflows: workflows || [],
+    sbom: licenseReport?.sbom || [],
+    license: licenseReport?.projectLicense || { id: 'UNKNOWN', name: 'Unknown' },
+    licenseReport: licenseReport || undefined,
+  };
+}
+
+function addEdge(edges, edgeKeys, from, to, kind, symbols = []) {
+  if (from === to) return;
+  const key = from + '->' + to;
+  const existing = edgeKeys.get(key);
+  if (existing) {
+    if (symbols && symbols.length) {
+      existing.symbols = Array.from(new Set([...(existing.symbols || []), ...symbols]));
+    }
+    return;
+  }
+  const edge = { from, to, kind, symbols: symbols ? symbols.slice() : [] };
+  edgeKeys.set(key, edge);
+  edges.push(edge);
+}
+
+// How many reads may be in flight at once. Small on purpose: a file is read
+// whole before its size can be checked (a `FileSource` has no `stat`), so this
+// is also a multiplier on peak memory. Eight is enough to keep a disk or the
+// browser's file layer busy without holding a heap of large files at once.
+const READ_AHEAD = 8;
+
+// Yields `{ path, text, failed }` for each path, in the order given, while
+// keeping up to READ_AHEAD reads in flight. Failures are yielded rather than
+// thrown so the caller can count them and keep going — one unreadable file
+// should not end a scan.
+async function* readAhead(source, paths, width = READ_AHEAD) {
+  const read = (path) =>
+    Promise.resolve()
+      .then(() => source.read(path))
+      .then((text) => ({ path, text, failed: false }), () => ({ path, text: '', failed: true }));
+
+  const inFlight = [];
+  let next = 0;
+  while (next < paths.length && inFlight.length < width) inFlight.push(read(paths[next++]));
+
+  while (inFlight.length) {
+    // shift() before the await: the slot is refilled immediately, so the next
+    // read starts while this file is being analyzed rather than after it.
+    const settled = inFlight.shift();
+    if (next < paths.length) inFlight.push(read(paths[next++]));
+    yield await settled;
+  }
+}
+
+function countBy(items, fn) {
+  const out = {};
+  for (const item of items) {
+    const k = fn(item);
+    out[k] = (out[k] || 0) + 1;
+  }
+  return out;
+}
+
+async function readModulePath(source) {
+  try {
+    const text = await source.read('go.mod');
+    const m = text.match(/^module\s+(\S+)/m);
+    return m ? m[1] : '';
+  } catch {
+    return '';
+  }
+}
+
+// Simplified .gitignore: plain names, dir/, *.ext, /anchored. No negation —
+// documented limitation.
+async function buildIgnoreMatcher(source) {
+  let text = '';
+  try {
+    text = await source.read('.gitignore');
+  } catch {
+    return () => false;
+  }
+  const rules = [];
+  for (let line of text.split('\n')) {
+    line = line.trim();
+    if (!line || line.startsWith('#') || line.startsWith('!')) continue;
+    const anchored = line.startsWith('/');
+    const pattern = line.replace(/^\//, '').replace(/\/$/, '');
+    if (!pattern) continue;
+    const re = new RegExp(
+      (anchored ? '^' : '(^|/)') +
+        pattern.split(/(\*\*|\*)/).map((part) =>
+          part === '**' ? '.*' : part === '*' ? '[^/]*' : escapeRe(part)
+        ).join('') +
+        '($|/)'
+    );
+    rules.push({ re });
+  }
+  return (path) => rules.some((r) => r.re.test(path));
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function readTsConfigPaths(source) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    try {
+      const text = await source.read(name);
+      const clean = text.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '');
+      const json = JSON.parse(clean);
+      const compilerOptions = json.compilerOptions || {};
+      const baseUrl = compilerOptions.baseUrl ? compilerOptions.baseUrl.replace(/^\.?\//, '').replace(/\/$/, '') : '';
+      const paths = compilerOptions.paths || {};
+      if (Object.keys(paths).length || baseUrl) {
+        return { baseUrl, paths };
+      }
+    } catch {}
+  }
+  return null;
+}

package/shared/analyzer/security.js

@@ -0,0 +1,187 @@
+// A built-in vulnerability & code-quality rule engine — a Semgrep-lite that
+// runs entirely locally, no external binary. Rules are regex/line based,
+// language-scoped, each with a severity and a category. Per-file findings are
+// attached during the scan; summarizeSecurity rolls them into a repo grade.
+
+import { lineCounter } from './util.js';
+
+export const SEVERITIES = ['info', 'low', 'medium', 'high', 'critical'];
+export const sevRank = (s) => SEVERITIES.indexOf(s);
+
+// Each rule: id, severity, category, message, rx. `byLine` rules test each
+// line (and report the line number); others test the whole source once.
+const RULES = [
+  { id: 'hardcoded-secret', severity: 'critical', category: 'secret',
+    message: 'Hardcoded credential — move it to env/config.',
+    rx: /\b(api[_-]?key|apikey|secret|client[_-]?secret|password|passwd|access[_-]?token|auth[_-]?token|private[_-]?key)\b\s*[:=]\s*['"`][^'"`\s]{8,}['"`]/i, byLine: true },
+  { id: 'aws-key', severity: 'critical', category: 'secret',
+    message: 'Looks like an AWS access key id.',
+    rx: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/, byLine: true },
+  { id: 'private-key-block', severity: 'critical', category: 'secret',
+    message: 'A private key is committed to the source.',
+    rx: /-----BEGIN (RSA|EC|DSA|OPENSSH|PGP) PRIVATE KEY-----/ },
+  { id: 'eval', severity: 'high', category: 'injection', langs: ['javascript'],
+    message: 'eval() executes strings as code — classic injection sink.',
+    rx: /\beval\s*\(/, byLine: true },
+  { id: 'new-function', severity: 'high', category: 'injection', langs: ['javascript'],
+    message: 'new Function() is eval in a trench coat.',
+    rx: /\bnew Function\s*\(/, byLine: true },
+  { id: 'child-exec', severity: 'high', category: 'injection', langs: ['javascript'],
+    message: 'Shelling out — if any argument is user input, this is command injection.',
+    rx: /\b(child_process\.(exec|spawn)|execSync|spawnSync)\s*\(/, byLine: true },
+  { id: 'os-system', severity: 'high', category: 'injection', langs: ['python'],
+    message: 'os.system / shell=True runs a shell — sanitize any input reaching it.',
+    rx: /\bos\.system\s*\(|shell\s*=\s*True/, byLine: true },
+  { id: 'sql-concat', severity: 'high', category: 'injection',
+    message: 'SQL built by string concatenation/formatting — use parameterized queries.',
+    rx: /\b(execute|query|exec|raw)\s*\(\s*[^)]*(\+|\$\{|\.format\(|f["'])/, byLine: true },
+  { id: 'innerhtml', severity: 'medium', category: 'xss', langs: ['javascript'],
+    message: 'Writing raw HTML — if the value is user-controlled, this is XSS.',
+    rx: /\b(innerHTML|outerHTML)\s*=|dangerouslySetInnerHTML|document\.write\s*\(/, byLine: true,
+    ignore: /\b(innerHTML|outerHTML)\s*=\s*(['"`])\2\s*;?\s*$/ },
+  { id: 'weak-hash', severity: 'medium', category: 'crypto',
+    message: 'MD5/SHA-1 are broken — use SHA-256+, and bcrypt/argon2 for passwords.',
+    rx: /\b(md5|sha1)\s*\(|createHash\(\s*['"](md5|sha1)['"]/, byLine: true },
+  { id: 'math-random', severity: 'low', category: 'crypto', langs: ['javascript'],
+    message: 'Math.random() is not cryptographically secure.',
+    rx: /\bMath\.random\s*\(/, byLine: true },
+  { id: 'insecure-deser', severity: 'high', category: 'deserialization',
+    message: 'Insecure deserialization — untrusted data here is remote code execution.',
+    rx: /\b(pickle\.loads?|yaml\.load\s*\((?![^)]*SafeLoader)|unserialize\s*\(|ObjectInputStream)/, byLine: true },
+  { id: 'open-redirect', severity: 'medium', category: 'redirect',
+    message: 'Redirect target comes from the request — open-redirect risk.',
+    rx: /\b(res\.redirect|redirect)\s*\(\s*(req\.|request\.)/, byLine: true },
+  { id: 'localhost-url', severity: 'low', category: 'config',
+    message: 'Hardcoded localhost/127.0.0.1 — will break outside this machine.',
+    rx: /['"`](https?:\/\/(localhost|127\.0\.0\.1)|localhost:\d|127\.0\.0\.1)/, byLine: true },
+  { id: 'debugger', severity: 'low', category: 'debug', langs: ['javascript'],
+    message: 'A debugger statement is left in.',
+    rx: /\bdebugger\s*;?/, byLine: true },
+  { id: 'console-log', severity: 'info', category: 'debug', langs: ['javascript'],
+    message: 'console.log — fine locally, noise in production.',
+    rx: /\bconsole\.(log|debug|info)\s*\(/, byLine: true },
+  { id: 'print-stmt', severity: 'info', category: 'debug', langs: ['python'],
+    message: 'print() — use the logger in production code.',
+    rx: /^\s*print\s*\(/, byLine: true },
+  { id: 'todo', severity: 'info', category: 'quality',
+    message: 'TODO/FIXME left in the source.',
+    rx: /\b(TODO|FIXME|XXX|HACK)\b/, byLine: true },
+  { id: 'loose-eq', severity: 'low', category: 'quality', langs: ['javascript'],
+    message: 'Loose equality (==) coerces types — prefer ===.',
+    rx: /[^=!<>]==[^=]/, byLine: true },
+  { id: 'var-keyword', severity: 'low', category: 'quality', langs: ['javascript'],
+    message: 'var is function-scoped and hoisted — prefer let/const.',
+    rx: /\bvar\s+[A-Za-z_$]/, byLine: true },
+  { id: 'empty-catch', severity: 'medium', category: 'quality',
+    message: 'Swallowed exception — errors vanish silently here.',
+    rx: /(catch\s*\([^)]*\)\s*\{\s*\}|except\s*\w*\s*:\s*pass\b)/, byLine: true },
+  // JSON Web Tokens start with a base64-encoded header that is always
+  // `eyJ…` ("{"). A line that contains one and treats it as a literal
+  // string — rather than reading it from a vault — is the same shape of
+  // mistake as a hardcoded API key. Three base64 segments separated by
+  // dots is the JWT signature; we only require the first segment to keep
+  // the rule cheap.
+  { id: 'jwt-secret', severity: 'critical', category: 'secret',
+    message: 'Looks like a hardcoded JWT — treat it like a credential, not a string.',
+    rx: /['"`](eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,})['"`]/, byLine: true },
+  // The `os-system` rule already catches `os.system` and `shell=True` on
+  // subprocess calls, but `subprocess.Popen(..., shell=True)` and
+  // `subprocess.run(..., shell=True)` are the modern Python way to do
+  // the same thing, and a regex on `shell=True` alone matches both
+  // without the false-positive rate. A separate rule for Popen keeps the
+  // message specific and the langs filter honest.
+  { id: 'subprocess-shell', severity: 'high', category: 'injection', langs: ['python'],
+    message: 'subprocess.* with shell=True runs a shell — sanitize any input reaching it.',
+    rx: /\bsubprocess\.(Popen|run|call|check_output|check_call)\s*\([^)]*shell\s*=\s*True/, byLine: true },
+  // Go's `http.ListenAndServe` defaults to binding all interfaces when
+  // given a `":port"` address (the colon makes it a wildcard), and a
+  // literal `0.0.0.0` does the same. That is fine inside a container with
+  // a tight network policy and a bug everywhere else: the dev box, the
+  // staging cluster, the CI runner, the laptop on coffee-shop Wi-Fi. The
+  // rule does not distinguish "0.0.0.0" from "127.0.0.1" because the
+  // safer pattern is always `127.0.0.1:<port>`, so the finding is a
+  // nudge rather than an alarm.
+  { id: 'go-public-listen', severity: 'medium', category: 'config', langs: ['go'],
+    message: 'Go listener binds all interfaces (":port" or "0.0.0.0") — bind 127.0.0.1 explicitly.',
+    rx: /(ListenAndServe|Listen|TLS\s*\.\s*Listen|ListenAndServeTLS)\s*\(\s*["'](:[0-9]+|0\.0\.0\.0(?::[0-9]+)?|::)["']/, byLine: true },
+];
+
+// Findings for one file, run at scan time while the source is in hand.
+export function analyzeSecurityFile(source, lang) {
+  const findings = [];
+  const text = String(source);
+  const lines = text.split('\n');
+  // Whole-file rules report a byte offset and need it as a line number. Built
+  // once and lazily: most files trip none of these rules and never build it.
+  const lineAt = lineCounter(text);
+  for (const rule of RULES) {
+    if (rule.langs && !rule.langs.includes(lang)) continue;
+    if (rule.byLine) {
+      for (let i = 0; i < lines.length; i++) {
+        if (rule.ignore && rule.ignore.test(lines[i])) continue;
+        const m = lines[i].match(rule.rx);
+        if (m) {
+          findings.push({ rule: rule.id, severity: rule.severity, category: rule.category, message: rule.message, line: i + 1, excerpt: lines[i].trim().slice(0, 90) });
+        }
+      }
+    } else {
+      const m = text.match(rule.rx);
+      if (m) {
+        findings.push({ rule: rule.id, severity: rule.severity, category: rule.category, message: rule.message, line: lineAt(m.index), excerpt: (m[0] || '').slice(0, 90) });
+      }
+    }
+  }
+  return findings;
+}
+
+// Repo-level roll-up: counts by severity and category, the files carrying
+// findings (worst-first), and a 0–100 score + grade.
+export function summarizeSecurity(scan) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  const byCat = {};
+  const files = [];
+  for (const f of scan.files) {
+    const finds = f.findings || [];
+    if (!finds.length) continue;
+    let worst = 'info';
+    for (const x of finds) {
+      counts[x.severity]++;
+      byCat[x.category] = (byCat[x.category] || 0) + 1;
+      if (sevRank(x.severity) > sevRank(worst)) worst = x.severity;
+    }
+    files.push({ path: f.path, name: f.name, findings: finds, worst, count: finds.length });
+  }
+  files.sort((a, b) => sevRank(b.worst) - sevRank(a.worst) || b.count - a.count);
+
+  let score = 100;
+  score -= counts.critical * 15;
+  score -= counts.high * 6;
+  score -= counts.medium * 2;
+  score -= Math.min(10, counts.low);
+  score = Math.max(0, Math.round(score));
+  const grade = score >= 90 ? 'A' : score >= 75 ? 'B' : score >= 60 ? 'C' : score >= 45 ? 'D' : 'F';
+
+  return { counts, byCat, files, score, grade, total: files.reduce((s, f) => s + f.count, 0) };
+}
+
+// Fold an external engine's findings into the scan, in place, so the security
+// view — which reads `scan.files[].findings` and re-summarizes — sees one list.
+// Dedup is on (path, line, rule): two engines flagging the same line for the
+// same reason are one problem. This is the shared, pure half of the merge; the
+// fetching and spawning live on the server.
+export function mergeFindingsIntoScan(scan, external) {
+  if (!scan || !Array.isArray(external) || !external.length) return 0;
+  const byPath = new Map(scan.files.map((f) => [f.path, f]));
+  let added = 0;
+  for (const finding of external) {
+    const file = byPath.get(finding.path);
+    if (!file) continue; // a path the scanner never accepted is not ours to show
+    const list = file.findings || (file.findings = []);
+    const dupe = list.some((x) => x.line === finding.line && x.rule === finding.rule);
+    if (dupe) continue;
+    list.push(finding);
+    added++;
+  }
+  return added;
+}
+