@toolbaux/guardian 0.1.17 → 0.1.19

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/mcp-serve.js

@@ -98,6 +98,26 @@ async function loadIntel() {
     }
     return intel;
 }
+// ── Function intelligence loader ──
+let funcIntel = null;
+let funcIntelPath = "";
+let funcIntelLoadTime = 0;
+async function loadFuncIntel() {
+    if (!funcIntelPath)
+        return null;
+    const now = Date.now();
+    if (funcIntel && now - funcIntelLoadTime < 5000)
+        return funcIntel;
+    try {
+        const raw = await fs.readFile(funcIntelPath, "utf8");
+        funcIntel = JSON.parse(raw);
+        funcIntelLoadTime = now;
+    }
+    catch {
+        // File may not exist yet — not an error
+    }
+    return funcIntel;
+}
 // ── Helpers ──
 const SKIP_SERVICES = new Set(["str", "dict", "int", "len", "float", "max", "join", "getattr", "lower", "open", "params.append", "updates.append"]);
 function compact(obj) {
@@ -291,11 +311,38 @@ async function search(args) {
     // Frontend pages: match path or component
     const pages = (d.frontend_pages || []).filter((p) => p.path?.toLowerCase().includes(q) || p.component?.toLowerCase().includes(q) ||
         p.api_calls?.some((c) => c.toLowerCase().includes(q))).slice(0, 5).map((p) => `${p.path} → ${p.component}`);
+    // Functions: search literal_index (tactic:simp, sorry, string patterns) + function names
+    const fnHits = [];
+    const fi = await loadFuncIntel();
+    if (fi) {
+        // Literal index: exact key match + partial key match
+        const litIndex = fi.literal_index ?? {};
+        for (const [key, hits] of Object.entries(litIndex)) {
+            if (key.includes(q)) {
+                for (const h of hits.slice(0, 3)) {
+                    fnHits.push(`${h.function} [${h.file}:${h.line}] (lit:${key})`);
+                }
+            }
+            if (fnHits.length >= 10)
+                break;
+        }
+        // Function names: match by name
+        if (fnHits.length < 10) {
+            for (const fn of (fi.functions ?? [])) {
+                if (fn.name?.toLowerCase().includes(q)) {
+                    fnHits.push(`${fn.name} [${fn.file}:${fn.lines?.[0]}]`);
+                    if (fnHits.length >= 10)
+                        break;
+                }
+            }
+        }
+    }
     return compact({
         ep: eps, mod: models, m: mods,
         exports: exports.slice(0, 10),
         files: files.slice(0, 8),
         enums, tasks, pages,
+        ...(fnHits.length > 0 ? { fns: fnHits } : {}),
     });
 }
 async function model(args) {
@@ -458,8 +505,10 @@ export async function runMcpServe(options) {
     const specsDir = path.resolve(options.specs);
     const quiet = options.quiet ?? false;
     intelPath = path.join(specsDir, "machine", "codebase-intelligence.json");
+    funcIntelPath = path.join(specsDir, "machine", "function-intelligence.json");
     // Pre-load intelligence
     await loadIntel();
+    await loadFuncIntel();
     // Log to stderr (stdout is for MCP protocol)
     if (!quiet) {
         process.stderr.write(`Guardian MCP server started. Intelligence: ${intelPath}\n`);

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`);