@toolbaux/guardian 0.1.16 → 0.1.18

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/@toolbaux/guardian.svg)](https://www.npmjs.com/package/@toolbaux/guardian)
 [![license](https://img.shields.io/npm/l/@toolbaux/guardian.svg)](./LICENSE)
 
+> **Beta Release** — Guardian is under active development. Core features (extract, context, drift, MCP server) are stable and used daily across multiple projects, but you may encounter minor issues with edge cases in framework detection or config handling. Bug reports and feedback welcome via [GitHub Issues](https://github.com/idocoding/guardian/issues).
+
 Architectural intelligence for codebases. One command turns your repo into compact, machine-readable context that AI coding tools can reason about without hallucinating.
 
 ```bash
@@ -53,7 +55,7 @@ After `guardian init`, your project gets:
 - `.specs/` directory with architecture snapshots
 - `CLAUDE.md` with auto-injected context (refreshed on every save and commit)
 - Pre-commit hook that keeps context fresh automatically
-- `guardian.config.json` with auto-detected backend/frontend roots
+- `guardian.config.json` for project settings (roots auto-detected at runtime)
 
 ## Claude Code / Cursor Integration
 
@@ -96,9 +98,8 @@ Guardian includes an MCP server that Claude Code and Cursor connect to automatic
 
 All responses are compact JSON — no pretty-printing, no verbose keys. Repeated calls are cached (30s TTL). Usage metrics tracked per session.
 
-**Manual setup** (if the extension doesn't auto-configure):
+**Setup:** `guardian init` and the VSCode extension auto-create `.mcp.json` at your project root. If you need to create it manually:
 
-Create `.mcp.json` at your project root:
 ```json
 {
   "mcpServers": {
@@ -110,6 +111,8 @@ Create `.mcp.json` at your project root:
 }
 ```
 
+> **Note:** After `.mcp.json` is created or modified, you must **restart your Claude Code / Cursor session** (or reload the VSCode window) for the MCP server to connect. MCP config is only read at session start.
+
 ## VSCode Extension
 
 Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=toolbaux.toolbaux-guardian):
@@ -276,14 +279,14 @@ guardian feature-context --spec feature-specs/billing.yaml
 <details>
 <summary><strong>Configuration</strong></summary>
 
-`guardian.config.json` at project root (auto-created by `guardian init`):
+`guardian.config.json` at project root (auto-created by `guardian init`). Backend and frontend roots are auto-detected at runtime — only set them if auto-detection picks the wrong directory:
 
 ```json
 {
   "project": {
+    "description": "Short product description for generated docs",
     "backendRoot": "./backend",
-    "frontendRoot": "./frontend",
-    "description": "Short product description for generated docs"
+    "frontendRoot": "./frontend"
   },
   "frontend": {
     "routeDirs": ["app"],

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 };
+    },
+};