dravix-agent 0.1.0

package/dist/index/joern.js

@@ -0,0 +1,782 @@
+/**
+ * Joern CPG (Code Property Graph) — Phase 2 P1 deep-semantic engine.
+ *
+ * Joern parses the project into a CPG (AST + CFG + PDG fused) and lets us
+ * query data-flow / call-graph / control-flow facts that no regex or
+ * type-checker can answer. Per the research (Macroscope 2026; arxiv
+ * 2603.24837 codebadger), CPG-backed reachability is the only OSS path to
+ * detecting cross-function dataflow bugs without a paid SAST.
+ *
+ * **Architecture: batch + cache, not realtime.**
+ * Joern's CPG build takes 10-30 s for a medium project plus ~5 s JVM
+ * cold-start per query. That's too slow for an inline gate (<1 s budget).
+ * We split the cost:
+ *
+ *   `aegis index --joern`     → invoke this module's ``buildJoernCpg``.
+ *                               Builds CPG via ``joern-parse``, runs the
+ *                               CPGQL security+logic query via ``joern --script``,
+ *                               writes ``findings.jsonl`` into the per-project
+ *                               cache dir. Slow (10-60 s) but once-per-edit.
+ *   ``JoernEngine`` (realtime) → reads ``findings.jsonl``, filters to the
+ *                               current file, returns instantly.
+ *
+ * **Cache layout:** ``~/.aegis/joern/<sha256(root)[:16]>/``
+ *   - ``cpg.bin``         the binary CPG (large)
+ *   - ``findings.jsonl``  one JSON Finding per line
+ *   - ``info.json``       {built_at, joern_path, jdk_path, n_findings, query_version}
+ *
+ * **JDK version constraint:** Joern's Scala scripting breaks on JDK 22+ —
+ * we explicitly look for 11/17/21 even if the host's default ``java`` is
+ * newer. ``AEGIS_JOERN_JDK`` env overrides discovery.
+ *
+ * **Joern binary discovery order:**
+ *   1. ``AEGIS_JOERN_DIR`` env (path to ``joern-cli/`` directory)
+ *   2. ``~/.aegis/joern/joern-cli/`` (where ``aegis install joern`` would land)
+ *   3. ``~/.argus/joern/joern-cli/`` (re-use the existing argus install if present)
+ *
+ * **CPGQL query strategy** (mirrors argus's proven pattern in
+ * ``argus/engines/joern.py``): each detector is wrapped in its own try/catch
+ * so a language-frontend missing a particular feature never aborts the rest.
+ * Output is tab-separated lines prefixed with ``AEGIS_SINK`` / ``AEGIS_LOGIC``,
+ * parsed line-by-line.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+import { FindingSchema, makeFindingId } from "../findings.js";
+import { getLogger } from "../util/logger.js";
+import { run as spawnRun } from "../util/subprocess.js";
+const log = getLogger("aegis.joern");
+// Bump this when the CPGQL query changes — invalidates every cached findings file.
+// v2: added race detectors (asyncio.create_task fire-and-forget, JS .then() without .catch())
+const QUERY_VERSION = "v2";
+// Joern CPG build can be slow on large projects; allow up to 10 min.
+const DEFAULT_CPG_BUILD_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_QUERY_TIMEOUT_MS = 5 * 60 * 1000;
+// JDK candidates — must be 11..21 inclusive. argus uses the same list; we
+// add more Corretto roots since both Adoptium and Corretto are installed
+// side-by-side on this dev box.
+const JDK_CANDIDATES_WINDOWS = [
+    String.raw `C:\Program Files\Eclipse Adoptium\jdk-21.0.6.7-hotspot`,
+    String.raw `C:\Program Files\Amazon Corretto\jdk21.0.6_7`,
+    String.raw `C:\Program Files\Eclipse Adoptium\jdk-17.0.14.7-hotspot`,
+    String.raw `C:\Program Files\Amazon Corretto\jdk17.0.14_7`,
+    String.raw `C:\Program Files\Eclipse Adoptium\jdk-11.0.26.4-hotspot`,
+    String.raw `C:\Program Files\Amazon Corretto\jdk11.0.26_4`,
+    String.raw `C:\Program Files\Eclipse Adoptium\jdk-21.0.5.11-hotspot`,
+    String.raw `C:\Program Files\Amazon Corretto\jdk21.0.5_11`,
+];
+const JDK_CANDIDATES_POSIX = [
+    "/usr/lib/jvm/java-21-openjdk",
+    "/usr/lib/jvm/java-17-openjdk",
+    "/usr/lib/jvm/java-11-openjdk",
+    "/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home",
+    "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home",
+];
+const JOERN_DIR_CANDIDATES_RELATIVE = [
+    ".aegis/joern/joern-cli",
+    ".argus/joern/joern-cli", // graceful re-use of an existing argus install
+];
+// ── Discovery ─────────────────────────────────────────────────────────────
+function expandHome(p) {
+    if (!p.startsWith("~"))
+        return p;
+    return resolvePath(homedir(), p.slice(2));
+}
+/** Locate the joern-cli directory containing ``joern-parse`` + ``joern``. */
+export function findJoernDir() {
+    const env = process.env.AEGIS_JOERN_DIR;
+    if (env && env.trim()) {
+        const e = expandHome(env.trim());
+        if (existsSync(join(e, "bin", "joern-parse")) || existsSync(join(e, "bin", "joern-parse.bat"))) {
+            return e;
+        }
+        log.warn("AEGIS_JOERN_DIR set but no joern-parse inside", { value: env });
+    }
+    for (const rel of JOERN_DIR_CANDIDATES_RELATIVE) {
+        const p = join(homedir(), rel);
+        const has = existsSync(join(p, "bin", "joern-parse")) || existsSync(join(p, "bin", "joern-parse.bat"));
+        if (has)
+            return p;
+    }
+    return null;
+}
+function joernBinSuffix() {
+    return process.platform === "win32" ? ".bat" : "";
+}
+/** Locate the joern REPL launcher.
+ *
+ * Modern Joern ships ``joern-cli/joern{.bat}`` at the root of the joern-cli
+ * dir (alongside ``bin/``). Some distros (older argus-bundled installs)
+ * also drop a ``bin/joern-cli`` wrapper. We check both layouts; the REPL
+ * we actually want exposes ``--script <value>`` (verified via ``--help``). */
+function findJoernReplBin(joernDir) {
+    const suffix = joernBinSuffix();
+    const candidates = [
+        // Canonical layout: joern-cli/joern{.bat}
+        join(joernDir, "joern" + suffix),
+        // Some installs put the launcher under bin/
+        join(joernDir, "bin", "joern" + suffix),
+        // Legacy / partial argus install
+        join(joernDir, "bin", "joern-cli" + suffix),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** Locate a JDK in the 11..21 range. ``AEGIS_JOERN_JDK`` env wins. */
+export function findJoernJdk() {
+    const env = process.env.AEGIS_JOERN_JDK;
+    if (env && env.trim()) {
+        const e = expandHome(env.trim());
+        if (existsSync(join(e, "bin", process.platform === "win32" ? "java.exe" : "java"))) {
+            return e;
+        }
+        log.warn("AEGIS_JOERN_JDK set but no java inside", { value: env });
+    }
+    const candidates = process.platform === "win32" ? JDK_CANDIDATES_WINDOWS : JDK_CANDIDATES_POSIX;
+    for (const c of candidates) {
+        const javaBin = join(c, "bin", process.platform === "win32" ? "java.exe" : "java");
+        if (existsSync(javaBin))
+            return c;
+    }
+    return null;
+}
+// ── Cache layout ─────────────────────────────────────────────────────────-
+function aegisHome() {
+    return process.env.AEGIS_HOME ?? resolvePath(homedir(), ".aegis");
+}
+function cacheDirFor(projectRoot) {
+    const h = createHash("sha256").update(resolvePath(projectRoot)).digest("hex").slice(0, 16);
+    return join(aegisHome(), "joern", h);
+}
+export function joernFindingsPath(projectRoot) {
+    return join(cacheDirFor(projectRoot), "findings.jsonl");
+}
+export function joernInfoPath(projectRoot) {
+    return join(cacheDirFor(projectRoot), "info.json");
+}
+/** Read the Joern info.json — returns null if missing / unreadable. */
+export function readJoernInfo(projectRoot) {
+    const p = joernInfoPath(projectRoot);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Read cached findings as Finding[]. Returns [] on missing / unreadable. */
+export function readJoernFindings(projectRoot) {
+    const p = joernFindingsPath(projectRoot);
+    if (!existsSync(p))
+        return [];
+    try {
+        const out = [];
+        const lines = readFileSync(p, "utf8").split(/\r?\n/);
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            const obj = JSON.parse(line);
+            const parsed = FindingSchema.safeParse(obj);
+            if (parsed.success)
+                out.push(parsed.data);
+        }
+        return out;
+    }
+    catch (err) {
+        log.warn("joern findings cache unreadable", { err: String(err) });
+        return [];
+    }
+}
+const SINKS = {
+    eval: { cwe: "CWE-95", severity: "high", title: "Code injection via eval" },
+    exec: { cwe: "CWE-95", severity: "high", title: "Code injection via exec" },
+    compile: { cwe: "CWE-95", severity: "medium", title: "Dynamic code compilation" },
+    system: { cwe: "CWE-78", severity: "high", title: "OS command injection via system()" },
+    popen: { cwe: "CWE-78", severity: "high", title: "OS command injection via popen" },
+    Popen: { cwe: "CWE-78", severity: "high", title: "OS command injection via Popen" },
+    check_output: { cwe: "CWE-78", severity: "high", title: "OS command injection via check_output" },
+    check_call: { cwe: "CWE-78", severity: "high", title: "OS command injection via check_call" },
+    execute: { cwe: "CWE-89", severity: "high", title: "SQL injection via execute()" },
+    executemany: { cwe: "CWE-89", severity: "high", title: "SQL injection via executemany()" },
+    raw: { cwe: "CWE-89", severity: "medium", title: "Raw SQL query" },
+    loads: { cwe: "CWE-502", severity: "medium", title: "Unsafe deserialization" },
+};
+const SINK_NAMES = Object.keys(SINKS);
+const LOGIC = {
+    empty_catch: { cwe: "CWE-703", severity: "medium", title: "Swallowed exception (empty catch)" },
+    assign_in_condition: {
+        cwe: "CWE-481",
+        severity: "high",
+        title: "Assignment in conditional (= instead of ==)",
+    },
+};
+const RACES = {
+    // Python: ``asyncio.create_task(...)`` whose result is neither awaited,
+    // assigned, nor returned — fire-and-forget pattern. The task object is
+    // garbage-collected as soon as the local scope exits, and its side
+    // effects can race with whatever the caller does next. The Python docs
+    // explicitly warn about this since 3.7.
+    fire_and_forget_task: {
+        cwe: "CWE-362",
+        severity: "medium",
+        title: "Fire-and-forget asyncio.create_task — race + GC hazard",
+    },
+    // JS/TS: ``foo.then(handler)`` not followed by ``.catch`` in the same
+    // chain AND not awaited. An unhandled rejection on Node 15+ terminates
+    // the process; in older Node it silently swallows the error AND lets
+    // the caller's next line execute before the promise settles → race.
+    floating_then: {
+        cwe: "CWE-755",
+        severity: "medium",
+        title: "Floating Promise — unhandled rejection / sequencing race",
+    },
+};
+function buildCpgqlScript(cpgPath) {
+    const cpgFwd = cpgPath.replace(/\\/g, "/");
+    const names = SINK_NAMES.sort().join("|");
+    // Each detector wrapped in try/catch so a language-frontend missing a
+    // construct can never abort the others. Output: tab-separated lines.
+    return [
+        `importCpg("${cpgFwd}")`,
+        // --- security sinks fed by non-literal (potentially tainted) data ---
+        "try {",
+        `  cpg.call.name("${names}").foreach { c =>`,
+        "    val nonLiteralArgs = c.argument.argumentIndexGt(0).isLiteral.size < c.argument.argumentIndexGt(0).size",
+        '    val file = c.file.name.headOption.getOrElse("?")',
+        '    val line = c.lineNumber.map(_.toString).getOrElse("0")',
+        '    val code = c.code.replace("\\n"," ").replace("\\t"," ").take(200)',
+        '    println(s"AEGIS_SINK\\t${c.name}\\t${nonLiteralArgs}\\t$file\\t$line\\t$code")',
+        "  }",
+        "} catch { case _: Throwable => }",
+        // --- swallowed exceptions: a catch block containing no statements ---
+        "try {",
+        '  cpg.controlStructure.controlStructureType("CATCH").foreach { cs =>',
+        "    if (cs.ast.isCall.size == 0 && cs.ast.isControlStructure.size <= 1) {",
+        '      val file = cs.file.name.headOption.getOrElse("?")',
+        '      val line = cs.lineNumber.map(_.toString).getOrElse("0")',
+        '      val code = cs.code.replace("\\n"," ").replace("\\t"," ").take(120)',
+        '      println(s"AEGIS_LOGIC\\tempty_catch\\t$file\\t$line\\t$code")',
+        "    }",
+        "  }",
+        "} catch { case _: Throwable => }",
+        // --- assignment used inside an if-condition (= instead of ==) ---
+        "try {",
+        '  cpg.controlStructure.controlStructureType("IF").condition.isCall.name("<operator>.assignment").foreach { a =>',
+        '    val file = a.file.name.headOption.getOrElse("?")',
+        '    val line = a.lineNumber.map(_.toString).getOrElse("0")',
+        '    val code = a.code.replace("\\n"," ").replace("\\t"," ").take(120)',
+        '    println(s"AEGIS_LOGIC\\tassign_in_condition\\t$file\\t$line\\t$code")',
+        "  }",
+        "} catch { case _: Throwable => }",
+        // --- RACE #1: Python asyncio.create_task whose AST parent is the
+        //     method body (BLOCK) — i.e. statement-position call, neither
+        //     assigned (CALL <operator>.assignment) nor returned (RETURN)
+        //     nor passed as an arg (CALL). This is the canonical
+        //     "fire-and-forget" signature. The Python docs explicitly warn
+        //     about this since 3.7 — the task object can be GC'd before
+        //     completion AND its side effects race with the next statement. ---
+        "try {",
+        '  cpg.call.name("create_task").foreach { c =>',
+        '    if (c.astParent.label == "BLOCK") {',
+        '      val file = c.file.name.headOption.getOrElse("?")',
+        '      val line = c.lineNumber.map(_.toString).getOrElse("0")',
+        '      val code = c.code.replace("\\n"," ").replace("\\t"," ").take(160)',
+        '      println(s"AEGIS_RACE\\tfire_and_forget_task\\t$file\\t$line\\t$code")',
+        "    }",
+        "  }",
+        "} catch { case _: Throwable => }",
+        // --- RACE #2: JS/TS ``foo.then(handler)`` call whose AST parent is
+        //     the method body AND no ``.catch`` appears in the same source
+        //     line (cheap proxy for chain inspection — exact CPG chain walk
+        //     would need extra Joern API). Floating promise → unhandled
+        //     rejection on Node 15+ + sequencing race vs the next statement. ---
+        "try {",
+        '  cpg.call.code(".*\\\\.then\\\\(.*").foreach { t =>',
+        '    val parentLabel = t.astParent.label',
+        '    val lineCode = t.code',
+        '    val hasCatchInChain = lineCode.contains(".catch(")',
+        '    if (parentLabel == "BLOCK" && !hasCatchInChain) {',
+        '      val file = t.file.name.headOption.getOrElse("?")',
+        '      val line = t.lineNumber.map(_.toString).getOrElse("0")',
+        '      val code = lineCode.replace("\\n"," ").replace("\\t"," ").take(160)',
+        '      println(s"AEGIS_RACE\\tfloating_then\\t$file\\t$line\\t$code")',
+        "    }",
+        "  }",
+        "} catch { case _: Throwable => }",
+    ].join("\n");
+}
+// ── Output parsing ────────────────────────────────────────────────────────
+/** Convert a Joern stdout dump to deduped Finding[]. */
+function parseJoernOutput(stdout, projectRoot) {
+    const out = [];
+    const seen = new Set();
+    for (const rawLine of stdout.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.startsWith("AEGIS_SINK\t")) {
+            const f = parseSinkLine(line, projectRoot, seen);
+            if (f)
+                out.push(f);
+        }
+        else if (line.startsWith("AEGIS_LOGIC\t")) {
+            const f = parseLogicLine(line, projectRoot, seen);
+            if (f)
+                out.push(f);
+        }
+        else if (line.startsWith("AEGIS_RACE\t")) {
+            const f = parseRaceLine(line, projectRoot, seen);
+            if (f)
+                out.push(f);
+        }
+    }
+    return out;
+}
+function toRelPosix(absPath, projectRoot) {
+    try {
+        const root = resolvePath(projectRoot);
+        const abs = resolvePath(absPath);
+        if (abs.startsWith(root)) {
+            let rel = abs.slice(root.length).replace(/^[\\/]+/, "");
+            rel = rel.replace(/\\/g, "/");
+            return rel;
+        }
+        return absPath.replace(/\\/g, "/");
+    }
+    catch {
+        return absPath.replace(/\\/g, "/");
+    }
+}
+function parseSinkLine(line, projectRoot, seen) {
+    const parts = line.split("\t");
+    if (parts.length < 6)
+        return null;
+    const [, name, tainted, file, lineNo, code] = parts;
+    const meta = SINKS[name];
+    if (!meta)
+        return null;
+    if (tainted.trim().toLowerCase() !== "true")
+        return null;
+    const rel = toRelPosix(file, projectRoot);
+    const ln = parseInt(lineNo, 10);
+    const safeLine = Number.isFinite(ln) && ln > 0 ? ln : undefined;
+    const dedupKey = `${rel}::${safeLine ?? "?"}::${meta.cwe}::${name}`;
+    if (seen.has(dedupKey))
+        return null;
+    seen.add(dedupKey);
+    const ruleId = `joern.${name}`;
+    const finding = {
+        id: makeFindingId({ engine: "joern", file: rel, ...(safeLine !== undefined ? { line: safeLine } : {}), rule_id: ruleId }),
+        engine: "joern",
+        file: rel,
+        ...(safeLine !== undefined ? { line: safeLine } : {}),
+        rule_id: ruleId,
+        cwe: meta.cwe,
+        severity: meta.severity,
+        message: `${meta.title}: call to \`${name}\` with non-literal (potentially tainted) argument. ${code.trim().slice(0, 300)}`,
+        confidence: 0.7, // CPG reachability is a signal, not proof; critic refines
+        source: "dataflow",
+        evidence: {
+            snippet: code.trim().slice(0, 400) || undefined,
+        },
+    };
+    const parsed = FindingSchema.safeParse(finding);
+    return parsed.success ? parsed.data : null;
+}
+function parseLogicLine(line, projectRoot, seen) {
+    const parts = line.split("\t");
+    if (parts.length < 5)
+        return null;
+    const [, kind, file, lineNo, code] = parts;
+    const meta = LOGIC[kind];
+    if (!meta)
+        return null;
+    const rel = toRelPosix(file, projectRoot);
+    const ln = parseInt(lineNo, 10);
+    const safeLine = Number.isFinite(ln) && ln > 0 ? ln : undefined;
+    const dedupKey = `${rel}::${safeLine ?? "?"}::${meta.cwe}::${kind}`;
+    if (seen.has(dedupKey))
+        return null;
+    seen.add(dedupKey);
+    const ruleId = `joern.${kind}`;
+    const finding = {
+        id: makeFindingId({ engine: "joern", file: rel, ...(safeLine !== undefined ? { line: safeLine } : {}), rule_id: ruleId }),
+        engine: "joern",
+        file: rel,
+        ...(safeLine !== undefined ? { line: safeLine } : {}),
+        rule_id: ruleId,
+        cwe: meta.cwe,
+        severity: meta.severity,
+        message: `${meta.title}. ${code.trim().slice(0, 300)}`,
+        confidence: 0.6,
+        source: "dataflow",
+        evidence: { snippet: code.trim().slice(0, 400) || undefined },
+    };
+    const parsed = FindingSchema.safeParse(finding);
+    return parsed.success ? parsed.data : null;
+}
+function parseRaceLine(line, projectRoot, seen) {
+    const parts = line.split("\t");
+    if (parts.length < 5)
+        return null;
+    const [, kind, file, lineNo, code] = parts;
+    const meta = RACES[kind];
+    if (!meta)
+        return null;
+    const rel = toRelPosix(file, projectRoot);
+    const ln = parseInt(lineNo, 10);
+    const safeLine = Number.isFinite(ln) && ln > 0 ? ln : undefined;
+    const dedupKey = `${rel}::${safeLine ?? "?"}::${meta.cwe}::${kind}`;
+    if (seen.has(dedupKey))
+        return null;
+    seen.add(dedupKey);
+    const ruleId = `joern.race.${kind}`;
+    const finding = {
+        id: makeFindingId({ engine: "joern", file: rel, ...(safeLine !== undefined ? { line: safeLine } : {}), rule_id: ruleId }),
+        engine: "joern",
+        file: rel,
+        ...(safeLine !== undefined ? { line: safeLine } : {}),
+        rule_id: ruleId,
+        cwe: meta.cwe,
+        severity: meta.severity,
+        // Race signals are heuristic (CPGQL pattern, not full lattice-based
+        // RacerD), so confidence is intentionally lower than a clean sink hit.
+        // The critic refines: confirms real races, drops FPs like "Promise
+        // returned to a framework that handles rejection internally".
+        confidence: 0.55,
+        source: "dataflow",
+        message: `${meta.title}. ${code.trim().slice(0, 300)}`,
+        evidence: { snippet: code.trim().slice(0, 400) || undefined },
+    };
+    const parsed = FindingSchema.safeParse(finding);
+    return parsed.success ? parsed.data : null;
+}
+// ── Builder (one-shot) ────────────────────────────────────────────────────
+/** Detect which Joern frontends to run for this project.
+ *
+ * Joern's CPG is single-language-per-build, so on a multi-language project
+ * (e.g. TS app with embedded Python scripts, or a backend repo with both
+ * Python and Go) we MUST build a CPG per language and merge findings —
+ * otherwise the frontend Joern picks via heuristics scans only one
+ * language and silently drops the rest.
+ *
+ * Returns an ordered list of (languageHint, suffix) pairs. The suffix is
+ * appended to ``cpg.bin`` so per-language artifacts don't clobber each
+ * other in the cache.
+ *
+ * The detection is cheap: top-level markers (package.json, pyproject.toml,
+ * go.mod, Cargo.toml) PLUS a shallow scan for files in ``tests/`` /
+ * ``src/`` etc. so a TS app with a Python smoke fixture still gets both
+ * passes. The whole walk is bounded to ~200 dir-entries to keep cold cost
+ * negligible.
+ */
+function detectJoernLanguages(root) {
+    const langs = [];
+    const hasPy = hasMarkerOrFile(root, "pyproject.toml", /\.py$/, 200);
+    const hasJsTs = hasMarkerOrFile(root, "package.json", /\.(?:ts|tsx|js|jsx|mjs|cjs)$/, 200);
+    const hasGo = existsSync(join(root, "go.mod"));
+    const hasRust = existsSync(join(root, "Cargo.toml"));
+    if (hasPy)
+        langs.push({ lang: "python", suffix: ".py" });
+    if (hasJsTs)
+        langs.push({ lang: "javascript", suffix: ".js" });
+    if (hasGo)
+        langs.push({ lang: "go", suffix: ".go" });
+    if (hasRust)
+        langs.push({ lang: "rust", suffix: ".rs" });
+    // No marker matched? Single pass with no hint — Joern's auto-detect picks.
+    if (langs.length === 0)
+        langs.push({ lang: "", suffix: "" });
+    return langs;
+}
+/** True iff ``root`` has the named marker file OR any file matching ``ext``
+ * within a shallow recursive walk (depth 2, capped at ``cap`` entries). */
+function hasMarkerOrFile(root, marker, ext, cap) {
+    if (existsSync(join(root, marker)))
+        return true;
+    // Shallow walk: root, root/*, root/*/*
+    let count = 0;
+    function walk(dir, depth) {
+        if (depth > 2 || count > cap)
+            return false;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return false;
+        }
+        for (const e of entries) {
+            count++;
+            if (count > cap)
+                return false;
+            // Skip known noise / heavyweight dirs.
+            if (e === "node_modules" || e === ".git" || e === ".aegis" ||
+                e === "dist" || e === "build" || e === "venv" || e === ".venv" ||
+                e === "__pycache__" || e.startsWith(".")) {
+                continue;
+            }
+            const full = join(dir, e);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isFile()) {
+                if (ext.test(e))
+                    return true;
+            }
+            else if (st.isDirectory()) {
+                if (walk(full, depth + 1))
+                    return true;
+            }
+        }
+        return false;
+    }
+    return walk(root, 0);
+}
+/** Build the CPG for a project, run the security+logic query, write the
+ * findings cache. Returns a structured report. Never throws — failures
+ * produce ``{ok:false, reason}``. */
+export async function buildJoernCpg(projectRoot, opts) {
+    const t0 = Date.now();
+    const dir = cacheDirFor(projectRoot);
+    const cpgPath = join(dir, "cpg.bin");
+    const findingsPath = joernFindingsPath(projectRoot);
+    const infoPath = joernInfoPath(projectRoot);
+    const force = opts?.force ?? false;
+    const joernDir = findJoernDir();
+    if (!joernDir) {
+        return {
+            ok: false,
+            cacheDir: dir,
+            findingsPath,
+            findingsCount: 0,
+            durationMs: Date.now() - t0,
+            reason: "joern not installed — set AEGIS_JOERN_DIR or extract joern-cli to ~/.aegis/joern/joern-cli/",
+        };
+    }
+    const jdk = findJoernJdk();
+    if (!jdk) {
+        return {
+            ok: false,
+            cacheDir: dir,
+            findingsPath,
+            findingsCount: 0,
+            durationMs: Date.now() - t0,
+            reason: "no JDK 11..21 found (Joern's Scala scripting breaks on JDK 22+). Install Temurin/Corretto 21 or set AEGIS_JOERN_JDK.",
+        };
+    }
+    // Cache freshness: if the info file is newer than every top-level source
+    // file and query version matches, reuse. Force always rebuilds.
+    if (!force && existsSync(infoPath) && existsSync(findingsPath)) {
+        try {
+            const info = JSON.parse(readFileSync(infoPath, "utf8"));
+            if (info.query_version === QUERY_VERSION) {
+                const count = (readFileSync(findingsPath, "utf8").match(/\n/g) ?? []).length;
+                log.info("joern cache hit", { dir, age_ms: Date.now() - info.built_at, n: count });
+                return {
+                    ok: true,
+                    cacheDir: dir,
+                    findingsPath,
+                    findingsCount: count,
+                    durationMs: Date.now() - t0,
+                };
+            }
+        }
+        catch {
+            // fall through to rebuild
+        }
+    }
+    mkdirSync(dir, { recursive: true });
+    const env = {
+        JAVA_HOME: jdk,
+        PATH: `${join(jdk, "bin")}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`,
+    };
+    const joernReplBin = findJoernReplBin(joernDir);
+    if (!joernReplBin) {
+        return {
+            ok: false,
+            cacheDir: dir,
+            findingsPath,
+            findingsCount: 0,
+            durationMs: Date.now() - t0,
+            reason: `joern REPL binary not found in ${joernDir} (looked for joern, joern-cli; check install with joern --help)`,
+        };
+    }
+    const joernParseBin = join(joernDir, "bin", `joern-parse${joernBinSuffix()}`);
+    if (!existsSync(joernParseBin)) {
+        return {
+            ok: false,
+            cacheDir: dir,
+            findingsPath,
+            findingsCount: 0,
+            durationMs: Date.now() - t0,
+            reason: `joern-parse not found at ${joernParseBin}`,
+        };
+    }
+    // Per-language passes: Joern's CPG is single-language-per-build, so we
+    // build N CPGs (one per detected language) and aggregate findings. This
+    // is what catches a Python smoke fixture inside a TS app — otherwise
+    // joern-parse's frontend heuristic picks one language and silently
+    // skips the rest.
+    const languages = detectJoernLanguages(projectRoot);
+    log.info("joern: detected languages", { languages: languages.map((l) => l.lang || "auto") });
+    const allFindings = [];
+    let totalParseMs = 0;
+    let totalQueryMs = 0;
+    const passDiagnostics = [];
+    for (const { lang, suffix: langSuffix } of languages) {
+        const perLangCpg = join(dir, `cpg${langSuffix}.bin`);
+        // Joern's Python path through joern-parse is broken on Windows (it
+        // hardcodes `py2cpg.sh` instead of using pysrc2cpg(.bat) — verified
+        // empirically 2026-05-25). Workaround: invoke pysrc2cpg directly,
+        // which produces an equivalent CPG that joern --script can load.
+        const isPythonOnWindows = lang === "python" && process.platform === "win32";
+        const directPyBin = isPythonOnWindows
+            ? join(joernDir, `pysrc2cpg${joernBinSuffix()}`)
+            : null;
+        const useDirectPyFrontend = directPyBin !== null && existsSync(directPyBin);
+        let parseRes;
+        if (useDirectPyFrontend && directPyBin) {
+            log.info("joern: building CPG via pysrc2cpg (Windows workaround)", {
+                lang, cpg: perLangCpg,
+            });
+            parseRes = await spawnRun(directPyBin, {
+                args: [resolvePath(projectRoot), "--output", perLangCpg],
+                env,
+                timeoutMs: opts?.timeoutMs ?? DEFAULT_CPG_BUILD_TIMEOUT_MS,
+            });
+        }
+        else {
+            const parseArgs = [resolvePath(projectRoot), "--output", perLangCpg];
+            if (lang)
+                parseArgs.push("--language", lang);
+            log.info("joern: building CPG", { lang: lang || "auto", cpg: perLangCpg });
+            parseRes = await spawnRun(joernParseBin, {
+                args: parseArgs,
+                env,
+                timeoutMs: opts?.timeoutMs ?? DEFAULT_CPG_BUILD_TIMEOUT_MS,
+            });
+        }
+        totalParseMs += parseRes.durationMs;
+        if (parseRes.timedOut || parseRes.exitCode !== 0 || !existsSync(perLangCpg)) {
+            // Don't abort the whole build — record the failure and continue with
+            // the other languages. A broken Python frontend should not prevent
+            // a working JS scan from emitting findings.
+            log.warn("joern-parse failed for lang", {
+                lang: lang || "auto",
+                rc: parseRes.exitCode,
+                stderr_tail: parseRes.stderr.slice(-300),
+            });
+            passDiagnostics.push({
+                lang: lang || "auto",
+                ok: false,
+                parse_ms: parseRes.durationMs,
+                reason: `parse rc=${parseRes.exitCode}`,
+            });
+            continue;
+        }
+        // Write the per-language query script and run it.
+        const queryPath = join(dir, `query${langSuffix}.sc`);
+        writeFileSync(queryPath, buildCpgqlScript(perLangCpg), "utf8");
+        const queryRes = await spawnRun(joernReplBin, {
+            args: ["--script", queryPath],
+            env,
+            cwd: dir,
+            timeoutMs: opts?.timeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
+            maxBufferBytes: 50 * 1024 * 1024,
+        });
+        totalQueryMs += queryRes.durationMs;
+        if (queryRes.timedOut || queryRes.exitCode !== 0) {
+            log.warn("joern --script failed for lang", {
+                lang: lang || "auto",
+                rc: queryRes.exitCode,
+                stderr_tail: queryRes.stderr.slice(-300),
+            });
+            passDiagnostics.push({
+                lang: lang || "auto",
+                ok: false,
+                query_ms: queryRes.durationMs,
+                reason: `query rc=${queryRes.exitCode}`,
+            });
+            continue;
+        }
+        const passFindings = parseJoernOutput(queryRes.stdout, projectRoot);
+        allFindings.push(...passFindings);
+        passDiagnostics.push({
+            lang: lang || "auto",
+            ok: true,
+            parse_ms: parseRes.durationMs,
+            query_ms: queryRes.durationMs,
+            findings: passFindings.length,
+        });
+    }
+    // Dedup across languages — when a file is picked up by multiple frontends
+    // (rare but possible), the same Finding id would otherwise duplicate.
+    const seen = new Set();
+    const dedupedFindings = [];
+    for (const f of allFindings) {
+        if (seen.has(f.id))
+            continue;
+        seen.add(f.id);
+        dedupedFindings.push(f);
+    }
+    // Also write a symlink-ish copy at cpg.bin → the largest per-lang CPG, so
+    // external tools that expect the canonical name still work. We just copy
+    // by writing a tiny pointer file; the real CPGs stay where they are.
+    // (No-op if no pass produced a CPG.)
+    try {
+        if (passDiagnostics.some((d) => d.ok === true)) {
+            writeFileSync(join(dir, "cpg.bin.pointer"), JSON.stringify(passDiagnostics, null, 2), "utf8");
+        }
+    }
+    catch {
+        // ignore
+    }
+    writeFileSync(findingsPath, dedupedFindings.map((f) => JSON.stringify(f)).join("\n") +
+        (dedupedFindings.length ? "\n" : ""), "utf8");
+    const filesIndexed = new Set(dedupedFindings.map((f) => f.file)).size;
+    const info = {
+        built_at: Date.now(),
+        query_version: QUERY_VERSION,
+        joern_path: joernDir,
+        jdk_path: jdk,
+        n_findings: dedupedFindings.length,
+        files_indexed: filesIndexed,
+    };
+    writeFileSync(infoPath, JSON.stringify(info, null, 2), "utf8");
+    log.info("joern: query done", {
+        findings: dedupedFindings.length,
+        parse_ms: totalParseMs,
+        query_ms: totalQueryMs,
+        total_ms: Date.now() - t0,
+        passes: passDiagnostics,
+    });
+    const findings = dedupedFindings;
+    return {
+        ok: true,
+        cacheDir: dir,
+        findingsPath,
+        findingsCount: findings.length,
+        durationMs: Date.now() - t0,
+    };
+}
+// Test-friendly exports
+export const _testing = {
+    buildCpgqlScript,
+    parseJoernOutput,
+    toRelPosix,
+    SINKS,
+    LOGIC,
+    RACES,
+    QUERY_VERSION,
+};
+//# sourceMappingURL=joern.js.map