@toolbaux/guardian 0.1.17 → 0.1.18

package/dist/adapters/csharp-adapter.js

@@ -3,6 +3,80 @@ import Parser from "tree-sitter";
 function text(node) {
     return node ? node.text : "";
 }
+// ── Function-level intelligence ───────────────────────────────────────────
+const CS_FUNC_QUERY = `
+  (method_declaration      name: (identifier) @name) @fn
+  (constructor_declaration name: (identifier) @name) @fn
+`;
+function walkBody(body, visitor) {
+    const stack = [body];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        visitor(n);
+        for (let i = n.namedChildCount - 1; i >= 0; i--) {
+            const c = n.namedChild(i);
+            if (c)
+                stack.push(c);
+        }
+    }
+}
+function collectCSharpBodyIntel(body) {
+    const strings = new Set();
+    const calls = new Set();
+    walkBody(body, (n) => {
+        if (n.type === "string_literal" || n.type === "verbatim_string_literal") {
+            const raw = n.text.replace(/^@?"/, "").replace(/"$/, "");
+            if (raw.length > 0 && raw.length < 300)
+                strings.add(raw);
+        }
+        else if (n.type === "interpolated_string_expression") {
+            const raw = n.text.replace(/^\$"/, "").replace(/"$/, "");
+            if (raw.length > 0 && raw.length < 300)
+                strings.add(raw);
+        }
+        else if (n.type === "invocation_expression") {
+            const fn = n.childForFieldName("function");
+            if (fn)
+                calls.add(fn.text.split("\n")[0].trim());
+        }
+    });
+    return { stringLiterals: [...strings], regexPatterns: [], calls: [...calls] };
+}
+function extractCSharpFunctions(language, file, root) {
+    const records = [];
+    const query = new Parser.Query(language, CS_FUNC_QUERY);
+    for (const match of query.matches(root)) {
+        const fnNode = match.captures.find((c) => c.name === "fn")?.node;
+        const nameNode = match.captures.find((c) => c.name === "name")?.node;
+        if (!fnNode || !nameNode)
+            continue;
+        const funcName = text(nameNode);
+        // async: scan direct children for modifier — no full-tree walk needed
+        let isAsync = false;
+        for (const child of fnNode.children) {
+            if (child.type === "modifier" && child.text === "async") {
+                isAsync = true;
+                break;
+            }
+        }
+        const bodyNode = fnNode.childForFieldName("body");
+        const intel = bodyNode
+            ? collectCSharpBodyIntel(bodyNode)
+            : { stringLiterals: [], regexPatterns: [], calls: [] };
+        records.push({
+            id: `${file}#${funcName}:${fnNode.startPosition.row + 1}`,
+            name: funcName,
+            file,
+            lines: [fnNode.startPosition.row + 1, fnNode.endPosition.row + 1],
+            calls: intel.calls,
+            stringLiterals: intel.stringLiterals,
+            regexPatterns: intel.regexPatterns,
+            isAsync,
+            language: "csharp",
+        });
+    }
+    return records;
+}
 export const CSharpAdapter = {
     name: "C# ASP.NET Core Adapter",
     language: CSharp,
@@ -144,6 +218,7 @@ export const CSharpAdapter = {
                 }
             }
         }
-        return { endpoints, models, components, tests };
+        const functions = extractCSharpFunctions(this.language, file, root);
+        return { endpoints, models, components, tests, functions };
     }
 };

package/dist/adapters/go-adapter.js

@@ -5,6 +5,73 @@ const Go = require("tree-sitter-go");
 function text(node) {
     return node ? node.text : "";
 }
+// ── Function-level intelligence ───────────────────────────────────────────
+// Tree-sitter query — runs in C, fast regardless of file size.
+const GO_FUNC_QUERY = `
+  (function_declaration name: (identifier) @name) @fn
+  (method_declaration   name: (field_identifier) @name) @fn
+`;
+/** Walk a single node's subtree iteratively (stack-based, no recursion). */
+function walkBody(body, visitor) {
+    const stack = [body];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        visitor(n);
+        for (let i = n.namedChildCount - 1; i >= 0; i--) {
+            const c = n.namedChild(i);
+            if (c)
+                stack.push(c);
+        }
+    }
+}
+function collectGoBodyIntel(body) {
+    const strings = new Set();
+    const calls = new Set();
+    let isAsync = false;
+    walkBody(body, (n) => {
+        if (n.type === "interpreted_string_literal" || n.type === "raw_string_literal") {
+            const val = n.text.slice(1, -1);
+            if (val.length > 0 && val.length < 300)
+                strings.add(val);
+        }
+        else if (n.type === "call_expression") {
+            const fn = n.childForFieldName("function");
+            if (fn)
+                calls.add(fn.text.split("\n")[0].trim());
+        }
+        else if (n.type === "go_statement") {
+            isAsync = true;
+        }
+    });
+    return { stringLiterals: [...strings], regexPatterns: [], calls: [...calls], isAsync };
+}
+function extractGoFunctions(language, file, root) {
+    const records = [];
+    const query = new Parser.Query(language, GO_FUNC_QUERY);
+    for (const match of query.matches(root)) {
+        const fnNode = match.captures.find((c) => c.name === "fn")?.node;
+        const nameNode = match.captures.find((c) => c.name === "name")?.node;
+        if (!fnNode || !nameNode)
+            continue;
+        const funcName = nameNode.text;
+        const bodyNode = fnNode.childForFieldName("body");
+        const intel = bodyNode
+            ? collectGoBodyIntel(bodyNode)
+            : { stringLiterals: [], regexPatterns: [], calls: [], isAsync: false };
+        records.push({
+            id: `${file}#${funcName}:${fnNode.startPosition.row + 1}`,
+            name: funcName,
+            file,
+            lines: [fnNode.startPosition.row + 1, fnNode.endPosition.row + 1],
+            calls: intel.calls,
+            stringLiterals: intel.stringLiterals,
+            regexPatterns: intel.regexPatterns,
+            isAsync: intel.isAsync,
+            language: "go",
+        });
+    }
+    return records;
+}
 export const GoAdapter = {
     name: "Go Gin Adapter",
     language: Go,
@@ -91,6 +158,7 @@ export const GoAdapter = {
                 });
             }
         }
-        return { endpoints, models, components, tests };
+        const functions = extractGoFunctions(this.language, file, root);
+        return { endpoints, models, components, tests, functions };
     }
 };

package/dist/adapters/index.js

@@ -3,9 +3,10 @@ import { TypeScriptAdapter } from "./typescript-adapter.js";
 import { JavaAdapter } from "./java-adapter.js";
 import { GoAdapter } from "./go-adapter.js";
 import { CSharpAdapter } from "./csharp-adapter.js";
+import { Lean4Adapter } from "./lean4-adapter.js";
 import { runAdapter } from "./runner.js";
-export { PythonAdapter, TypeScriptAdapter, JavaAdapter, GoAdapter, CSharpAdapter, runAdapter };
-export const ADAPTERS = [PythonAdapter, TypeScriptAdapter, JavaAdapter, GoAdapter, CSharpAdapter];
+export { PythonAdapter, TypeScriptAdapter, JavaAdapter, GoAdapter, CSharpAdapter, Lean4Adapter, runAdapter };
+export const ADAPTERS = [PythonAdapter, TypeScriptAdapter, JavaAdapter, GoAdapter, CSharpAdapter, Lean4Adapter];
 export function getAdapterForFile(file) {
     for (const adapter of ADAPTERS) {
         if (adapter.fileExtensions.some(ext => file.endsWith(ext))) {

package/dist/adapters/java-adapter.js

@@ -3,6 +3,77 @@ import Parser from "tree-sitter";
 function text(node) {
     return node ? node.text : "";
 }
+// ── Function-level intelligence ───────────────────────────────────────────
+const JAVA_FUNC_QUERY = `
+  (method_declaration      name: (identifier) @name) @fn
+  (constructor_declaration name: (identifier) @name) @fn
+`;
+function walkBody(body, visitor) {
+    const stack = [body];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        visitor(n);
+        for (let i = n.namedChildCount - 1; i >= 0; i--) {
+            const c = n.namedChild(i);
+            if (c)
+                stack.push(c);
+        }
+    }
+}
+function collectJavaBodyIntel(body) {
+    const strings = new Set();
+    const calls = new Set();
+    walkBody(body, (n) => {
+        if (n.type === "string_literal") {
+            const raw = n.text.replace(/^"/, "").replace(/"$/, "");
+            if (raw.length > 0 && raw.length < 300)
+                strings.add(raw);
+        }
+        else if (n.type === "text_block") {
+            const raw = n.text.replace(/^"""/, "").replace(/"""$/, "").trim();
+            if (raw.length > 0 && raw.length < 300)
+                strings.add(raw);
+        }
+        else if (n.type === "method_invocation") {
+            const nameNode = n.childForFieldName("name");
+            const objNode = n.childForFieldName("object");
+            if (nameNode) {
+                const call = objNode ? `${text(objNode)}.${text(nameNode)}` : text(nameNode);
+                calls.add(call.split("\n")[0].trim());
+            }
+        }
+    });
+    return { stringLiterals: [...strings], regexPatterns: [], calls: [...calls] };
+}
+function extractJavaFunctions(language, file, root) {
+    const records = [];
+    const query = new Parser.Query(language, JAVA_FUNC_QUERY);
+    for (const match of query.matches(root)) {
+        const fnNode = match.captures.find((c) => c.name === "fn")?.node;
+        const nameNode = match.captures.find((c) => c.name === "name")?.node;
+        if (!fnNode || !nameNode)
+            continue;
+        const funcName = text(nameNode);
+        const bodyNode = fnNode.childForFieldName("body");
+        const intel = bodyNode
+            ? collectJavaBodyIntel(bodyNode)
+            : { stringLiterals: [], regexPatterns: [], calls: [] };
+        const typeNode = fnNode.childForFieldName("type");
+        const isAsync = /CompletableFuture|Mono|Flux|Future/.test(text(typeNode));
+        records.push({
+            id: `${file}#${funcName}:${fnNode.startPosition.row + 1}`,
+            name: funcName,
+            file,
+            lines: [fnNode.startPosition.row + 1, fnNode.endPosition.row + 1],
+            calls: intel.calls,
+            stringLiterals: intel.stringLiterals,
+            regexPatterns: intel.regexPatterns,
+            isAsync,
+            language: "java",
+        });
+    }
+    return records;
+}
 export const JavaAdapter = {
     name: "Java Spring Boot Adapter",
     language: Java,
@@ -117,6 +188,7 @@ export const JavaAdapter = {
                 });
             }
         }
-        return { endpoints, models, components, tests };
+        const functions = extractJavaFunctions(this.language, file, root);
+        return { endpoints, models, components, tests, functions };
     }
 };

package/dist/adapters/lean4-adapter.js

@@ -0,0 +1,358 @@
+/**
+ * Lean4 / Mathlib adapter for guardian.
+ *
+ * Uses deterministic regex-based extraction (no tree-sitter-lean4 dependency).
+ * Captures: theorems, lemmas, defs, structures, classes, instances, `sorry`
+ * locations, tactic usage, and Mathlib import dependencies.
+ *
+ * Implements SpecGuardAdapter with `language: null` — runner.ts calls
+ * extract() directly without a tree-sitter parse step.
+ */
+// ── Constants ─────────────────────────────────────────────────────────────
+/**
+ * Well-known Lean4 tactic names. Checked as whole words in the proof body.
+ * Kept in alphabetical order for maintainability.
+ */
+const KNOWN_TACTICS = [
+    "Abel",
+    "aesop",
+    "all_goals",
+    "any_goals",
+    "apply",
+    "apply?",
+    "assumption",
+    "by_cases",
+    "by_contra",
+    "calc",
+    "cases",
+    "change",
+    "clear",
+    "congr",
+    "constructor",
+    "contrapose",
+    "conv",
+    "decide",
+    "dsimp",
+    "exact",
+    "exact?",
+    "ext",
+    "field_simp",
+    "fin_cases",
+    "first",
+    "funext",
+    "gcongr",
+    "group",
+    "have",
+    "induction",
+    "interval_cases",
+    "intro",
+    "intros",
+    "linarith",
+    "linear_combination",
+    "module_cast",
+    "native_decide",
+    "nlinarith",
+    "norm_cast",
+    "norm_num",
+    "norm_num?",
+    "nth_rw",
+    "obtain",
+    "omega",
+    "polyrith",
+    "positivity",
+    "push_cast",
+    "push_neg",
+    "rcases",
+    "refine",
+    "rename",
+    "repeat",
+    "revert",
+    "rfl",
+    "ring",
+    "rw",
+    "rw?",
+    "set",
+    "show",
+    "simp",
+    "simp?",
+    "skip",
+    "split",
+    "suffices",
+    "swap",
+    "symm",
+    "tauto",
+    "trans",
+    "trivial",
+    "try",
+    "unfold",
+    "use",
+];
+// ── Regex patterns ────────────────────────────────────────────────────────
+/**
+ * Matches theorem/lemma/def/abbrev declarations (including noncomputable variants).
+ * Group 1: keyword (e.g. "theorem", "noncomputable def")
+ * Group 2: declaration name
+ */
+const THEOREM_RE = /^(?:[ \t]*(?:@\[[^\]]*\][ \t]*\n?[ \t]*)*)(?:private[ \t]+|protected[ \t]+)?(?:(noncomputable[ \t]+def|noncomputable[ \t]+abbrev|theorem|lemma|def|abbrev|example))(?:[ \t]+([^\s(:{\[]+))?/gm;
+/**
+ * Matches structure/class/inductive/instance declarations.
+ * Group 1: keyword, Group 2: name (optional for anonymous instances)
+ */
+const STRUCT_RE = /^(?:[ \t]*(?:@\[[^\]]*\][ \t]*\n?[ \t]*)*)(?:private[ \t]+|protected[ \t]+)?(structure|class|inductive|instance|mutual)(?:[ \t]+([^\s(:{\[]+))?/gm;
+/** Matches import statements. Group 1: module path */
+const IMPORT_RE = /^import[ \t]+([\w.]+)/gm;
+/** Matches namespace declarations. Group 1: namespace name */
+const NS_OPEN_RE = /^namespace[ \t]+([\w.]+)/gm;
+/** Matches end-of-namespace. Group 1: namespace name */
+const NS_END_RE = /^end[ \t]+([\w.]+)/gm;
+/** `sorry` as a standalone term or tactic */
+const SORRY_RE = /\bsorry\b/g;
+/** `:=` with optional trailing whitespace — used in proof body and statement extraction */
+const ASSIGN_RE = /:=\s*/g;
+// ── Helpers ───────────────────────────────────────────────────────────────
+/**
+ * Build a sorted array of newline offsets for O(log n) line lookups.
+ * Index i holds the character offset of the start of line i+1 (0-based array, 1-based lines).
+ */
+function buildLineIndex(source) {
+    const starts = [0]; // line 1 starts at offset 0
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === "\n")
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 1-based line number for a character offset, using precomputed line index. */
+function lineOfFast(lineIndex, offset) {
+    let lo = 0, hi = lineIndex.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineIndex[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1; // 1-based
+}
+/** Extract all Lean4 import paths from source. */
+function extractImports(source) {
+    const imports = [];
+    IMPORT_RE.lastIndex = 0;
+    let m;
+    while ((m = IMPORT_RE.exec(source)) !== null) {
+        imports.push(m[1]);
+    }
+    return imports;
+}
+/**
+ * Scan the entire source once and return a sorted list of namespace open/end
+ * events. Pass this to activeNamespaceAtFast() — O(1) amortised per declaration
+ * when declarations are processed left-to-right (which THEOREM_RE guarantees).
+ */
+function buildNsEvents(source) {
+    const events = [];
+    let m;
+    NS_OPEN_RE.lastIndex = 0;
+    while ((m = NS_OPEN_RE.exec(source)) !== null) {
+        events.push({ idx: m.index, name: m[1], kind: "open" });
+    }
+    NS_END_RE.lastIndex = 0;
+    while ((m = NS_END_RE.exec(source)) !== null) {
+        events.push({ idx: m.index, name: m[1], kind: "end" });
+    }
+    return events.sort((a, b) => a.idx - b.idx);
+}
+/**
+ * Return the active namespace at `offset` using precomputed events.
+ * Call this in declaration order (ascending offset) and pass the same
+ * `eventIdx` cursor — the cursor advances monotonically, making this O(n)
+ * total across all declarations rather than O(n²).
+ */
+function activeNamespaceAtFast(events, offset, cursor, stack) {
+    // Advance cursor through all events that precede `offset`
+    while (cursor.i < events.length && events[cursor.i].idx < offset) {
+        const ev = events[cursor.i++];
+        if (ev.kind === "open") {
+            stack.push(ev.name);
+        }
+        else {
+            const idx = stack.lastIndexOf(ev.name);
+            if (idx >= 0)
+                stack.splice(idx, 1);
+        }
+    }
+    return stack.join(".");
+}
+/**
+ * Extract the proof/definition body that follows a declaration's `:=` (or `by`).
+ * Works directly on `source` from `startOffset` to avoid repeated string slicing.
+ * Returns the raw text of the body, capped at 4000 chars to limit memory use.
+ */
+function extractProofBody(source, startOffset) {
+    // Search for := starting at startOffset without slicing the full source
+    ASSIGN_RE.lastIndex = startOffset;
+    const assignMatch = ASSIGN_RE.exec(source);
+    if (!assignMatch)
+        return "";
+    const bodyStart = assignMatch.index + assignMatch[0].length;
+    const bodyText = source.slice(bodyStart, bodyStart + 4000);
+    // Stop at the next top-level declaration (unindented keyword)
+    const stopRe = /\n(?=(?:theorem|lemma|def|abbrev|noncomputable|structure|class|inductive|instance|example|namespace|end|#|import)\b)/;
+    const stopIdx = bodyText.search(stopRe);
+    return stopIdx >= 0 ? bodyText.slice(0, stopIdx) : bodyText;
+}
+/**
+ * Single combined regex that matches any known tactic in one pass.
+ * Tactics with `?` (apply?, exact?, etc.) need the `?` escaped in the regex.
+ * Using a non-global RegExp for the initial "does body contain any tactic?" check,
+ * then a global one for collecting all matches.
+ */
+const TACTIC_COMBINED_RE = new RegExp(`\\b(${KNOWN_TACTICS.map((t) => t.replace(/[?]/g, "\\?")).join("|")})\\b`, "g");
+/** Extract which known tactics appear in a proof body — single-pass scan. */
+function extractTactics(body) {
+    TACTIC_COMBINED_RE.lastIndex = 0;
+    const found = new Set();
+    let m;
+    while ((m = TACTIC_COMBINED_RE.exec(body)) !== null) {
+        found.add(m[1]);
+    }
+    TACTIC_COMBINED_RE.lastIndex = 0;
+    return [...found].sort();
+}
+/** Return true if the body text contains `sorry`. Resets lastIndex after test. */
+function containsSorry(body) {
+    SORRY_RE.lastIndex = 0;
+    const result = SORRY_RE.test(body);
+    SORRY_RE.lastIndex = 0;
+    return result;
+}
+/** Estimate end line from start line + body newlines. */
+function estimateEndLine(startLine, body) {
+    return startLine + (body.split("\n").length - 1);
+}
+// ── Adapter ───────────────────────────────────────────────────────────────
+export const Lean4Adapter = {
+    name: "lean4",
+    /**
+     * No tree-sitter grammar — runner.ts calls extract() directly when
+     * `language` is falsy. All extraction is done via regex on the source text.
+     */
+    language: null,
+    fileExtensions: [".lean"],
+    queries: {},
+    extract(file, source, _root) {
+        const endpoints = [];
+        const models = [];
+        const components = [];
+        const tests = [];
+        const functions = [];
+        const imports = extractImports(source);
+        const mathlibDeps = imports.filter((i) => i.startsWith("Mathlib"));
+        // ── Precompute indices — O(n) each, amortises all per-declaration lookups ──
+        const lineIndex = buildLineIndex(source);
+        const nsEvents = buildNsEvents(source);
+        const nsCursor = { i: 0 };
+        const nsStack = [];
+        // ── Theorems / Lemmas / Defs ──────────────────────────────────────────
+        THEOREM_RE.lastIndex = 0;
+        let m;
+        while ((m = THEOREM_RE.exec(source)) !== null) {
+            const rawKind = m[1]?.trim().replace(/\s+/g, "_") ?? "def";
+            const name = m[2] ?? "(anonymous)";
+            const offset = m.index;
+            const startLine = lineOfFast(lineIndex, offset);
+            const namespace = activeNamespaceAtFast(nsEvents, offset, nsCursor, nsStack);
+            // Extract statement: text between end of match and :=
+            const matchEnd = offset + m[0].length;
+            ASSIGN_RE.lastIndex = matchEnd;
+            const stmtMatch = ASSIGN_RE.exec(source);
+            const statement = (stmtMatch
+                ? source.slice(matchEnd, stmtMatch.index)
+                : "").trim().slice(0, 500);
+            const body = extractProofBody(source, offset + m[0].length);
+            const hasSorry = containsSorry(body);
+            const tactics = extractTactics(body);
+            const endLine = estimateEndLine(startLine, body);
+            const kindMap = {
+                theorem: "theorem",
+                lemma: "lemma",
+                def: "def",
+                noncomputable_def: "noncomputable_def",
+                abbrev: "abbrev",
+                noncomputable_abbrev: "abbrev",
+                example: "example",
+                inductive: "inductive",
+            };
+            const kind = kindMap[rawKind] ?? "def";
+            const record = {
+                id: `${file}#${name}:${startLine}`,
+                name,
+                file,
+                lines: [startLine, endLine],
+                calls: [],
+                // Push domain concepts into stringLiterals so the generic literal_index
+                // can surface them — no language knowledge needed outside the adapter.
+                stringLiterals: [
+                    ...(hasSorry ? ["sorry"] : []), // `guardian search --query sorry`
+                    ...tactics.map((t) => `tactic:${t}`), // `guardian search --query simp`
+                ],
+                regexPatterns: [],
+                isAsync: false,
+                language: "lean4",
+                kind,
+                namespace,
+                statement,
+                hasSorry,
+                tactics,
+                mathlibDeps,
+            };
+            functions.push(record);
+        }
+        // ── Structures / Classes / Instances ─────────────────────────────────
+        // Fresh cursor for STRUCT_RE pass — offsets may interleave with THEOREM_RE
+        const nsCursor2 = { i: 0 };
+        const nsStack2 = [];
+        STRUCT_RE.lastIndex = 0;
+        while ((m = STRUCT_RE.exec(source)) !== null) {
+            const structKind = m[1];
+            const name = m[2];
+            if (!name)
+                continue; // anonymous instance — skip for models
+            models.push({
+                name,
+                file,
+                framework: structKind,
+                fields: [],
+                relationships: [],
+            });
+            // Also emit a FunctionRecord so it appears in function search
+            const startLine = lineOfFast(lineIndex, m.index);
+            const kindMap = {
+                structure: "structure",
+                class: "class",
+                instance: "instance",
+                inductive: "inductive",
+                mutual: "def",
+            };
+            const record = {
+                id: `${file}#${name}:${startLine}`,
+                name,
+                file,
+                lines: [startLine, startLine],
+                calls: [],
+                stringLiterals: [],
+                regexPatterns: [],
+                isAsync: false,
+                language: "lean4",
+                kind: kindMap[structKind] ?? "structure",
+                namespace: activeNamespaceAtFast(nsEvents, m.index, nsCursor2, nsStack2),
+                statement: "",
+                hasSorry: false,
+                tactics: [],
+                mathlibDeps,
+            };
+            functions.push(record);
+        }
+        return { endpoints, models, components, tests, functions };
+    },
+};

package/dist/adapters/python-adapter.js

@@ -10,6 +10,95 @@ function findChildren(node, type) {
     }
     return results;
 }
+// ── Function-level intelligence helpers ──────────────────────────────────
+/** re.* functions whose first argument is a regex pattern string */
+const RE_FUNCS = new Set(["compile", "sub", "subn", "match", "search", "fullmatch", "findall", "finditer", "split"]);
+/**
+ * Collect string literals, regex patterns (strings passed to re.*), and call
+ * targets from a Python function body subtree.
+ */
+function collectPythonBodyIntel(body, getText) {
+    const strings = new Set();
+    const regexes = new Set();
+    const calls = new Set();
+    function walk(n) {
+        if (n.type === "string") {
+            // Python string: "text", 'text', """text""", r"pattern"
+            const raw = getText(n);
+            // Strip leading r/b/f/u prefix and quote chars
+            const stripped = raw.replace(/^[rRbBuUfF]*/u, "").replace(/^'''|^"""|^'|^"/u, "").replace(/'''$|"""$|'$|"$/u, "");
+            if (stripped.length > 0 && stripped.length < 300) {
+                strings.add(stripped);
+                // Is this string the first argument to a re.* call?
+                const parent = n.parent;
+                if (parent?.type === "argument_list") {
+                    const callNode = parent.parent;
+                    if (callNode?.type === "call") {
+                        const funcNode = callNode.childForFieldName("function");
+                        if (funcNode) {
+                            const fnText = getText(funcNode);
+                            // re.sub, re.compile, re.match, …
+                            const simple = fnText.split(".").pop() ?? "";
+                            if (fnText.startsWith("re.") && RE_FUNCS.has(simple)) {
+                                regexes.add(stripped);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else if (n.type === "call") {
+            const funcNode = n.childForFieldName("function");
+            if (funcNode) {
+                calls.add(getText(funcNode).trim());
+            }
+        }
+        for (const child of n.namedChildren)
+            walk(child);
+    }
+    walk(body);
+    return {
+        stringLiterals: [...strings],
+        regexPatterns: [...regexes],
+        calls: [...calls],
+    };
+}
+/**
+ * Recursively extract FunctionRecord entries from a Python AST node.
+ * Handles top-level functions, methods inside classes, and nested functions.
+ */
+function extractPyFunctions(file, source, node) {
+    const records = [];
+    const getText = (n) => source.substring(n.startIndex, n.endIndex);
+    function process(n) {
+        if (n.type === "function_definition") {
+            const nameN = n.childForFieldName("name");
+            const bodyN = n.childForFieldName("body");
+            if (nameN && bodyN) {
+                const funcName = getText(nameN);
+                // Detect async: check if "async" keyword precedes the def
+                const srcBefore = source.substring(n.startIndex, nameN.startIndex);
+                const isAsync = /\basync\b/.test(srcBefore);
+                const intel = collectPythonBodyIntel(bodyN, getText);
+                records.push({
+                    id: `${file}#${funcName}:${n.startPosition.row + 1}`,
+                    name: funcName,
+                    file,
+                    lines: [n.startPosition.row + 1, n.endPosition.row + 1],
+                    calls: intel.calls,
+                    stringLiterals: intel.stringLiterals,
+                    regexPatterns: intel.regexPatterns,
+                    isAsync,
+                    language: "python",
+                });
+            }
+        }
+        for (const child of n.namedChildren)
+            process(child);
+    }
+    process(node);
+    return records;
+}
 export const PythonAdapter = {
     name: "python",
     language: Python,
@@ -178,6 +267,7 @@ export const PythonAdapter = {
                 relationships
             });
         }
-        return { endpoints, models, components, tests };
+        const functions = extractPyFunctions(file, source, root);
+        return { endpoints, models, components, tests, functions };
     }
 };

package/dist/adapters/runner.js

@@ -1,10 +1,37 @@
 import Parser from "tree-sitter";
 export function runAdapter(adapter, file, source) {
+    // Text-based adapters (e.g. Lean4) set language to null and rely entirely on
+    // their extract() implementation — no tree-sitter parse step needed.
+    if (!adapter.language) {
+        if (adapter.extract) {
+            const result = adapter.extract(file, source, null);
+            return {
+                endpoints: result.endpoints,
+                models: result.models,
+                components: result.components,
+                tests: result.tests,
+                functions: result.functions ?? [],
+            };
+        }
+        return { endpoints: [], models: [], components: [], tests: [], functions: [] };
+    }
+    // tree-sitter native binding throws "Invalid argument" for very large files.
+    // Skip files over 1 MB to avoid silent crashes; they are rare in practice.
+    if (source.length > 1_000_000) {
+        return { endpoints: [], models: [], components: [], tests: [], functions: [] };
+    }
     const parser = new Parser();
     parser.setLanguage(adapter.language);
     const tree = parser.parse(source);
     if (adapter.extract) {
-        return adapter.extract(file, source, tree.rootNode);
+        const result = adapter.extract(file, source, tree.rootNode);
+        return {
+            endpoints: result.endpoints,
+            models: result.models,
+            components: result.components,
+            tests: result.tests,
+            functions: result.functions ?? [],
+        };
     }
     const endpoints = [];
     const models = [];
@@ -65,5 +92,5 @@ export function runAdapter(adapter, file, source) {
             }
         }
     }
-    return { endpoints, models, components, tests };
+    return { endpoints, models, components, tests, functions: [] };
 }

package/dist/adapters/typescript-adapter.js

@@ -11,6 +11,115 @@ function findChildren(node, type) {
     }
     return results;
 }
+// ── Function-level intelligence helpers ──────────────────────────────────
+/** Walk all descendants depth-first. */
+function* walkAll(node) {
+    yield node;
+    for (const child of node.namedChildren)
+        yield* walkAll(child);
+}
+/**
+ * Collect string literals, regex patterns, and call targets from a subtree.
+ * Scoped to the function body so we don't bleed into nested function records.
+ */
+function collectBodyIntel(body, getText) {
+    const strings = new Set();
+    const regexes = new Set();
+    const calls = new Set();
+    for (const n of walkAll(body)) {
+        if (n.type === "string") {
+            const frag = n.namedChildren.find((c) => c.type === "string_fragment");
+            if (frag) {
+                const val = getText(frag);
+                if (val.length > 0 && val.length < 300)
+                    strings.add(val);
+            }
+        }
+        else if (n.type === "template_string") {
+            // Strip backticks; include template string content
+            const raw = getText(n).slice(1, -1);
+            if (raw.length > 0 && raw.length < 300)
+                strings.add(raw);
+        }
+        else if (n.type === "regex") {
+            const raw = getText(n);
+            // /pattern/flags → extract pattern
+            const m = raw.match(/^\/(.+)\/[gimsuy]*$/s);
+            if (m)
+                regexes.add(m[1]);
+        }
+        else if (n.type === "call_expression") {
+            const fn = n.childForFieldName("function");
+            if (fn) {
+                const name = getText(fn).split("\n")[0].trim();
+                calls.add(name);
+            }
+        }
+    }
+    return {
+        stringLiterals: [...strings],
+        regexPatterns: [...regexes],
+        calls: [...calls],
+    };
+}
+/**
+ * Recursively extract FunctionRecord entries from a TypeScript/TSX AST node.
+ * Handles: function declarations, method definitions, arrow functions assigned
+ * to variables (const foo = () => {}), and class method definitions.
+ */
+function extractTsFunctions(file, source, node) {
+    const records = [];
+    const getText = (n) => source.substring(n.startIndex, n.endIndex);
+    function process(n) {
+        let funcName = null;
+        let bodyNode = null;
+        let isAsync = false;
+        if (n.type === "function_declaration") {
+            const nameN = n.childForFieldName("name");
+            if (nameN)
+                funcName = getText(nameN);
+            bodyNode = n.childForFieldName("body");
+            isAsync = n.children.some((c) => c.type === "async");
+        }
+        else if (n.type === "method_definition") {
+            const nameN = n.childForFieldName("name");
+            if (nameN)
+                funcName = getText(nameN);
+            bodyNode = n.childForFieldName("body");
+            isAsync = n.children.some((c) => c.type === "async");
+        }
+        else if (n.type === "variable_declarator") {
+            const valN = n.childForFieldName("value");
+            if (valN && (valN.type === "arrow_function" || valN.type === "function")) {
+                const nameN = n.childForFieldName("name");
+                if (nameN)
+                    funcName = getText(nameN);
+                bodyNode = valN.childForFieldName("body") ?? valN;
+                isAsync = valN.children.some((c) => c.type === "async");
+            }
+        }
+        if (funcName && bodyNode) {
+            const intel = collectBodyIntel(bodyNode, getText);
+            records.push({
+                id: `${file}#${funcName}:${n.startPosition.row + 1}`,
+                name: funcName,
+                file,
+                lines: [n.startPosition.row + 1, n.endPosition.row + 1],
+                calls: intel.calls,
+                stringLiterals: intel.stringLiterals,
+                regexPatterns: intel.regexPatterns,
+                isAsync,
+                language: "typescript",
+            });
+        }
+        // Recurse into all children (nested functions become their own records)
+        for (const child of n.namedChildren) {
+            process(child);
+        }
+    }
+    process(node);
+    return records;
+}
 export const TypeScriptAdapter = {
     name: "typescript",
     language: TypeScript.tsx, // We use the TSX grammar to capture both TS and TSX seamlessly
@@ -174,6 +283,7 @@ export const TypeScriptAdapter = {
                 }
             }
         }
-        return { endpoints, models, components, tests };
+        const functions = extractTsFunctions(file, source, root);
+        return { endpoints, models, components, tests, functions };
     }
 };

package/dist/cli.js

@@ -350,7 +350,21 @@ program
         quiet: options.quiet,
     });
 });
-program.parseAsync().catch((error) => {
+program
+    .parseAsync()
+    .then(() => {
+    // Force exit after one-shot commands complete.
+    // Tree-sitter native bindings keep a libuv ref alive, preventing natural
+    // process exit. mcp-serve is excluded: it sets up readline and returns
+    // immediately (before any messages are processed), so calling process.exit()
+    // here would kill it before it processes any input. mcp-serve manages its
+    // own lifecycle via process.exit(0) inside rl.on("close").
+    const subCommand = process.argv[2];
+    if (subCommand !== "mcp-serve") {
+        process.exit(process.exitCode ?? 0);
+    }
+})
+    .catch((error) => {
     console.error(error);
-    process.exitCode = 1;
+    process.exit(1);
 });

package/dist/commands/search.js

@@ -2,19 +2,22 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import yaml from "js-yaml";
 import { loadHeatmap } from "../extract/compress.js";
+import { loadFunctionIntelligence, } from "../extract/function-intel.js";
 import { resolveMachineInputDir } from "../output-layout.js";
 import { DEFAULT_SPECS_DIR } from "../config.js";
 export async function runSearch(options) {
     const inputDir = await resolveMachineInputDir(options.input || DEFAULT_SPECS_DIR);
     const { architecture, ux } = await loadSnapshots(inputDir);
     const heatmap = await loadHeatmap(inputDir);
+    const funcIntel = await loadFunctionIntelligence(inputDir);
     const types = normalizeTypes(options.types);
     const matches = searchSnapshots({
         architecture,
         ux,
         query: options.query,
         types,
-        heatmap
+        heatmap,
+        funcIntel,
     });
     const content = renderSearchMarkdown(options.query, matches);
     if (options.output) {
@@ -66,7 +69,7 @@ function normalizeTypes(types) {
     }
     return normalized.size > 0
         ? normalized
-        : new Set(["models", "endpoints", "components", "modules", "tasks"]);
+        : new Set(["models", "endpoints", "components", "modules", "tasks", "functions"]);
 }
 function tokenize(value) {
     return value
@@ -110,7 +113,7 @@ function scoreItem(queryTokens, item) {
     return Math.min(1, total / queryTokens.length);
 }
 function searchSnapshots(params) {
-    const { architecture, ux, query, types, heatmap } = params;
+    const { architecture, ux, query, types, heatmap, funcIntel } = params;
     const queryTokens = tokenize(query);
     const matches = [];
     const pageUsage = buildComponentPageUsage(ux);
@@ -238,6 +241,65 @@ function searchSnapshots(params) {
             });
         }
     }
+    if (types.has("functions") && funcIntel) {
+        const queryTokens = tokenize(query);
+        // 1. Name match — function / theorem name contains a query token
+        for (const fn of funcIntel.functions) {
+            const score = scoreItem(queryTokens, {
+                name: fn.name,
+                file: fn.file,
+                text: [...fn.stringLiterals, ...fn.regexPatterns, ...fn.calls, fn.language],
+            });
+            if (score <= 0)
+                continue;
+            const lineRange = `${fn.lines[0]}–${fn.lines[1]}`;
+            const detail = [];
+            if (fn.stringLiterals.length > 0) {
+                detail.push(`Literals: ${formatList(fn.stringLiterals.slice(0, 3).map((l) => `"${l.slice(0, 60)}"`), 3)}`);
+            }
+            if (fn.regexPatterns.length > 0) {
+                detail.push(`Patterns: ${formatList(fn.regexPatterns.slice(0, 3).map((p) => `/${p.slice(0, 60)}/`), 3)}`);
+            }
+            if (fn.calls.length > 0) {
+                detail.push(`Calls: ${formatList(fn.calls, 5)}`);
+            }
+            matches.push({
+                type: "functions",
+                name: `${fn.name} (${fn.language})`,
+                score,
+                markdown: [
+                    `**${fn.name}** · ${fn.file}:${lineRange} · ${fn.language}${fn.isAsync ? " · async" : ""}`,
+                    ...detail,
+                ],
+            });
+        }
+        // 2. Literal index match — query token appears in a function's string/regex literals
+        // (additive: surfaces functions whose body contains the queried literal even if
+        // the function name itself doesn't match)
+        for (const tok of queryTokens) {
+            const hits = funcIntel.literal_index[tok.toLowerCase()];
+            if (!hits)
+                continue;
+            for (const hit of hits) {
+                // Skip if we already emitted this function via name match above
+                if (matches.some((m) => m.type === "functions" && m.name.startsWith(hit.function + " ("))) {
+                    continue;
+                }
+                const fn = funcIntel.functions.find((f) => f.file === hit.file && f.name === hit.function);
+                if (!fn)
+                    continue;
+                matches.push({
+                    type: "functions",
+                    name: `${fn.name} (${fn.language})`,
+                    score: 0.6,
+                    markdown: [
+                        `**${fn.name}** · ${fn.file}:${fn.lines[0]}–${fn.lines[1]} · ${fn.language}`,
+                        `Matched literal/pattern containing "${tok}"`,
+                    ],
+                });
+            }
+        }
+    }
     return matches.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
 }
 function buildComponentPageUsage(ux) {
@@ -290,7 +352,8 @@ function renderSearchMarkdown(query, matches) {
         ["endpoints", "Endpoints"],
         ["components", "Components"],
         ["modules", "Modules"],
-        ["tasks", "Tasks"]
+        ["tasks", "Tasks"],
+        ["functions", "Functions"],
     ];
     const lines = [];
     lines.push(`# Search: "${query}" - ${matches.length} matches`);

package/dist/extract/function-intel.js

@@ -0,0 +1,209 @@
+/**
+ * Function-level intelligence extraction and persistence.
+ *
+ * Produces `function-intelligence.json` in the guardian machine output dir.
+ * Contains:
+ *  - Full FunctionRecord list (all languages)
+ *  - Call graph: name → { calls, called_by }
+ *  - Literal index: token → [{ file, function, line }]  ← drives `guardian search --types functions`
+ *
+ * This is a second-pass scan that runs after the main extraction.
+ * It re-uses the adapter pipeline on the same files; results are not fed
+ * back into the architecture snapshot (additive, non-breaking).
+ *
+ * Language-specific domain concepts (e.g. Lean4 `sorry`, Python re.* patterns)
+ * are surfaced entirely by each adapter — this module has zero language knowledge.
+ * Adapters encode domain specifics into `stringLiterals`, making them searchable
+ * through the generic literal_index.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAdapterForFile, runAdapter } from "../adapters/index.js";
+// ── Token helpers ─────────────────────────────────────────────────────────
+/** Split text into lowercase alphanumeric tokens (min 3 chars). */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length >= 3);
+}
+// ── Core build ────────────────────────────────────────────────────────────
+/**
+ * Given a flat list of FunctionRecord entries (from all files / all adapters),
+ * build the call graph and literal index.
+ */
+export function buildFunctionIntelligence(allFunctions) {
+    // ── Call graph ──
+    const callGraph = Object.create(null);
+    for (const fn of allFunctions) {
+        if (!Object.prototype.hasOwnProperty.call(callGraph, fn.name))
+            callGraph[fn.name] = { calls: [], called_by: [] };
+        callGraph[fn.name].calls = [...new Set(fn.calls)];
+    }
+    // Invert: for each callee name, record who calls it
+    for (const fn of allFunctions) {
+        for (const callee of fn.calls) {
+            if (!Object.prototype.hasOwnProperty.call(callGraph, callee))
+                callGraph[callee] = { calls: [], called_by: [] };
+            const entry = callGraph[callee];
+            if (!entry.called_by.includes(fn.name)) {
+                entry.called_by.push(fn.name);
+            }
+        }
+    }
+    // ── Literal index ──
+    // Object.create(null) avoids prototype property collisions (e.g. "constructor",
+    // "toString") that would cause `existing.some is not a function` errors when
+    // source tokens match built-in Object property names.
+    const literalIndex = Object.create(null);
+    function addHit(token, fn) {
+        const key = token.toLowerCase().trim();
+        if (!key)
+            return;
+        if (!Object.prototype.hasOwnProperty.call(literalIndex, key))
+            literalIndex[key] = [];
+        const existing = literalIndex[key];
+        // One hit per function per token — no duplicates
+        if (!existing.some((h) => h.file === fn.file && h.function === fn.name)) {
+            existing.push({ file: fn.file, function: fn.name, line: fn.lines[0] });
+        }
+    }
+    for (const fn of allFunctions) {
+        for (const lit of fn.stringLiterals) {
+            const full = lit.slice(0, 100);
+            if (full.length >= 3)
+                addHit(full, fn);
+            for (const tok of tokenize(lit))
+                addHit(tok, fn);
+        }
+        for (const pat of fn.regexPatterns) {
+            const full = pat.slice(0, 100);
+            if (full.length >= 3)
+                addHit(full, fn);
+            for (const tok of tokenize(pat))
+                addHit(tok, fn);
+        }
+    }
+    return {
+        version: "0.1",
+        generated_at: new Date().toISOString(),
+        total_functions: allFunctions.length,
+        functions: allFunctions,
+        call_graph: callGraph,
+        literal_index: literalIndex,
+    };
+}
+// ── File scanning ─────────────────────────────────────────────────────────
+const DEFAULT_IGNORE_DIRS = new Set([
+    // Version control
+    ".git",
+    // Lean4 / Lake package manager (contains Mathlib — thousands of .lean files)
+    ".lake",
+    // JS/TS
+    "node_modules",
+    "dist",
+    ".next",
+    ".nuxt",
+    "coverage",
+    // Python
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    // Java/Kotlin (Maven + Gradle build output + generated sources)
+    "target",
+    ".gradle",
+    "generated",
+    "generated-sources",
+    // Go
+    "vendor",
+    // .NET
+    "obj",
+    "bin",
+    // Generic
+    "build",
+    ".specs",
+    ".cache",
+]);
+async function listSourceFiles(dir, config, results = []) {
+    const ignoreDirs = new Set([
+        ...DEFAULT_IGNORE_DIRS,
+        ...(config.ignore?.directories ?? []),
+    ]);
+    const ignorePaths = config.ignore?.paths ?? [];
+    let entries;
+    try {
+        // encoding: "utf8" ensures entry.name is always string, not Buffer
+        entries = await fs.readdir(dir, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const name = entry.name;
+        const fullPath = path.join(dir, name);
+        if (entry.isDirectory()) {
+            if (!ignoreDirs.has(name) && !ignorePaths.some((p) => fullPath.includes(p))) {
+                await listSourceFiles(fullPath, config, results);
+            }
+        }
+        else if (entry.isFile()) {
+            if (getAdapterForFile(name)) {
+                results.push(fullPath);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Scan one or more project roots, run adapters on every source file, and
+ * return the aggregated FunctionIntelligence index.
+ */
+export async function buildFunctionIntelligenceFromRoots(roots, config) {
+    const allFunctions = [];
+    for (const root of roots) {
+        const files = await listSourceFiles(root, config);
+        await Promise.all(files.map(async (filePath) => {
+            const adapter = getAdapterForFile(path.basename(filePath));
+            if (!adapter)
+                return;
+            let source;
+            try {
+                source = await fs.readFile(filePath, "utf8");
+            }
+            catch {
+                return;
+            }
+            try {
+                const result = runAdapter(adapter, filePath, source);
+                allFunctions.push(...result.functions);
+            }
+            catch {
+                // Skip files that fail to parse (malformed source, encoding issues)
+            }
+        }));
+    }
+    return buildFunctionIntelligence(allFunctions);
+}
+// ── Write ─────────────────────────────────────────────────────────────────
+/** Persist function-intelligence.json to the guardian machine output dir. */
+export async function writeFunctionIntelligence(outputDir, intel) {
+    const filePath = path.join(outputDir, "function-intelligence.json");
+    await fs.mkdir(outputDir, { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(intel, null, 2), "utf8");
+    console.log(`Wrote ${filePath}`);
+    return filePath;
+}
+// ── Load ──────────────────────────────────────────────────────────────────
+/** Load function-intelligence.json if it exists; returns null if absent. */
+export async function loadFunctionIntelligence(machineDir) {
+    const filePath = path.join(machineDir, "function-intelligence.json");
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/extract/index.js

@@ -13,6 +13,7 @@ import { validateArchitectureSnapshot, validateUxSnapshot } from "../schema/inde
 import { getOutputLayout } from "../output-layout.js";
 import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
 import { analyzeDepth } from "./analyzers/depth.js";
+import { buildFunctionIntelligenceFromRoots, writeFunctionIntelligence, } from "./function-intel.js";
 export async function buildSnapshots(options) {
     const startedAt = Date.now();
     const includeFileGraph = options.includeFileGraph ?? false;
@@ -187,6 +188,17 @@ export async function extractProject(options) {
         await fs.writeFile(siPath, JSON.stringify(siReports, null, 2), "utf8");
         console.log(`Wrote ${siPath}`);
     }
+    // Generate Function Intelligence — call graph, literal index across all languages.
+    // Runs as an additive second pass; never modifies the architecture snapshot.
+    try {
+        const allRoots = (architecture.project.roots ?? [projectRoot]).map((r) => path.isAbsolute(r) ? r : path.join(projectRoot, r));
+        const funcIntel = await buildFunctionIntelligenceFromRoots(allRoots, config);
+        await writeFunctionIntelligence(layout.machineDir, funcIntel);
+    }
+    catch (err) {
+        // Non-fatal — function intel is additive; don't block the main extract
+        console.warn(`Function intelligence skipped: ${err.message}`);
+    }
     return result;
 }
 async function generateStructuralIntelligenceReports(architecture) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolbaux/guardian",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "type": "module",
   "description": "Architectural intelligence for codebases. Verify that AI-generated code matches your architectural intent.",
   "keywords": [