@toolbaux/guardian 0.1.22 → 0.2.0

package/dist/commands/search.js

@@ -7,6 +7,56 @@ 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);
+    // ── SQLite/FTS5 backend: BM25-ranked search via guardian.db ──────────────
+    // SQLite is primary for ALL formats when guardian.db exists.
+    // File-based search is only a fallback for backward compatibility.
+    if ((options.backend === "sqlite" || options.backend === "auto") && options.query) {
+        if (options.format === "json") {
+            // For JSON output (used by MCP): merge BM25-ranked files into querySearch output
+            const sqliteResult = await getSqliteFileList(options.input || DEFAULT_SPECS_DIR, options.query, options.topN ?? 20, options.backend);
+            if (sqliteResult !== null) {
+                const base = JSON.parse(await querySearch(inputDir, options.query));
+                base.files = sqliteResult.files;
+                base.symbols = sqliteResult.symbols;
+                base.search_signal = sqliteResult.signal;
+                console.log(JSON.stringify(base));
+                return;
+            }
+            // No guardian.db — fall through to file-based querySearch below
+        }
+        else {
+            const handled = await runSearchSqlite(options.input || DEFAULT_SPECS_DIR, options.query, options.topN ?? 20, options.backend);
+            if (handled)
+                return; // false = no guardian.db, fall through to file search
+        }
+    }
+    // ── Mode dispatch: intel-based lookups ──
+    if (options.orient) {
+        console.log(await queryOrient(inputDir));
+        return;
+    }
+    if (options.file) {
+        console.log(await queryFile(inputDir, options.file));
+        return;
+    }
+    if (options.model) {
+        console.log(await queryModel(inputDir, options.model));
+        return;
+    }
+    if (options.impact) {
+        console.log(await queryImpact(inputDir, options.impact));
+        return;
+    }
+    // ── Semantic search ──
+    if (!options.query) {
+        console.error("Error: --query is required for semantic search (or use --orient / --file / --model / --impact)");
+        process.exit(1);
+    }
+    if (options.format === "json") {
+        // Fallback: file-based categorical search (no guardian.db available)
+        console.log(await querySearch(inputDir, options.query));
+        return;
+    }
     const { architecture, ux } = await loadSnapshots(inputDir);
     const heatmap = await loadHeatmap(inputDir);
     const funcIntel = await loadFunctionIntelligence(inputDir);
@@ -22,7 +72,9 @@ export async function runSearch(options) {
         projectRoot,
         topN: options.topN ?? 10,
     });
-    const content = renderSearchMarkdown(options.query, matches);
+    const content = options.verbose
+        ? renderSearchMarkdownVerbose(options.query, matches)
+        : renderSearchMarkdown(options.query, matches);
     if (options.output) {
         const outputPath = path.resolve(options.output);
         await fs.mkdir(path.dirname(outputPath), { recursive: true });
@@ -32,6 +84,146 @@ export async function runSearch(options) {
     }
     console.log(content);
 }
+// ── SQLite / FTS5 search path ────────────────────────────────────────────────
+/**
+ * Preprocess a user query before FTS5 matching.
+ * Strips commit-message noise (issue numbers, conventional commit prefixes, PR refs)
+ * and expands camelCase/snake_case identifiers so BM25 ranks them correctly.
+ */
+function preprocessSearchQuery(q) {
+    return q
+        // Remove PR/issue references: (#1234) or #1234
+        .replace(/\(#\d+\)/g, "")
+        .replace(/#\d+\s*/g, "")
+        // Remove conventional commit prefixes: "Fixed #37016 --", "Refs #28455 --"
+        .replace(/^(?:Fixed|Refs|Closes|Resolved)\s*(?:#\d+\s*)?--?\s*/i, "")
+        // Remove conventional commit types: "feat(deps)!:", "chore:", "docs:", etc.
+        .replace(/^(?:feat|fix|chore|docs|test|refactor|style|perf|ci|build)(?:\([^)]+\))?!?:\s*/i, "")
+        // Remove double dashes
+        .replace(/\s*--\s*/g, " ")
+        // Expand camelCase: getUserById → get user by id
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        // Expand snake_case: get_user_by_id → get user by id
+        .replace(/_/g, " ")
+        // Normalize whitespace
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Returns false if no guardian.db found and backend is "auto" (caller should fall through to file search).
+ * Exits the process if backend is "sqlite" and no db found.
+ */
+async function runSearchSqlite(specsInput, query, limit, backend = "sqlite") {
+    const { openSpecsStore } = await import("../db/index.js");
+    const { SqliteSpecsStore } = await import("../db/sqlite-specs-store.js");
+    const { getOutputLayout } = await import("../output-layout.js");
+    const layout = getOutputLayout(path.resolve(specsInput));
+    const store = await openSpecsStore(layout, { backend });
+    try {
+        if (!(store instanceof SqliteSpecsStore)) {
+            if (backend === "auto")
+                return false; // fall through to file search
+            console.error("guardian.db not found — run `guardian extract --backend sqlite` first.");
+            process.exit(1);
+        }
+        const cleaned = preprocessSearchQuery(query);
+        let results = store.searchWithGraph(cleaned, limit);
+        // If preprocessed query returns nothing, try the raw query as a fallback
+        if (results.length === 0 && cleaned !== query) {
+            results = store.searchWithGraph(query, limit);
+        }
+        if (results.length === 0) {
+            if (backend === "auto")
+                return false; // fall through to file-based search
+            console.log(`No FTS results for "${query}"`);
+            return true;
+        }
+        let queryVec;
+        try {
+            const { embedQuery } = await import("../db/embeddings.js");
+            const vec = await embedQuery(cleaned || query, process.env.OPENAI_API_KEY);
+            if (vec)
+                queryVec = vec;
+        }
+        catch { /* graceful degradation */ }
+        const symbols = store.searchSymbols(cleaned || query, Math.ceil(limit / 2), queryVec);
+        const lines = [`## FTS5 search: "${query}"\n`];
+        // Build a map of file → matching symbols for quick lookup
+        const symbolsByFile = new Map();
+        for (const s of symbols) {
+            if (!symbolsByFile.has(s.file_path))
+                symbolsByFile.set(s.file_path, []);
+            symbolsByFile.get(s.file_path).push({ name: s.name, line: s.line });
+        }
+        for (const r of results) {
+            const rank = Math.abs(r.rank).toFixed(3);
+            lines.push(`### \`${r.file_path}\`  (score: ${rank})`);
+            // Matching symbols from this file (snippet equivalent)
+            const fileSyms = symbolsByFile.get(r.file_path) ?? [];
+            const inlineSyms = r.matching_symbols.filter(s => !fileSyms.some(f => f.name === s));
+            if (fileSyms.length) {
+                for (const s of fileSyms)
+                    lines.push(`  → \`${s.name}\` :${s.line}`);
+            }
+            if (inlineSyms.length) {
+                lines.push(`  symbols: ${inlineSyms.join(", ")}`);
+            }
+            if (r.imports.length)
+                lines.push(`  imports: ${r.imports.join(", ")}`);
+            if (r.used_by.length)
+                lines.push(`  used by: ${r.used_by.join(", ")}`);
+            lines.push("");
+        }
+        console.log(lines.join("\n"));
+        return true;
+    }
+    finally {
+        await store.close();
+    }
+}
+async function getSqliteFileList(specsInput, query, limit, backend = "auto") {
+    const { openSpecsStore } = await import("../db/index.js");
+    const { SqliteSpecsStore } = await import("../db/sqlite-specs-store.js");
+    const { getOutputLayout } = await import("../output-layout.js");
+    const layout = getOutputLayout(path.resolve(specsInput));
+    const store = await openSpecsStore(layout, { backend });
+    try {
+        if (!(store instanceof SqliteSpecsStore)) {
+            return null; // no guardian.db — caller uses file-based fallback
+        }
+        const cleaned = preprocessSearchQuery(query);
+        let results = store.searchWithGraph(cleaned, limit);
+        // If preprocessed query returns nothing, try raw query
+        if (results.length === 0 && cleaned !== query) {
+            results = store.searchWithGraph(query, limit);
+        }
+        // Return null on 0 results so caller can fall back to querySearch()
+        if (results.length === 0)
+            return null;
+        const signal = store.querySignal(query);
+        // Hybrid symbol search: BM25 + call-graph authority + optional vector similarity.
+        // embedQuery uses local model (no API key) or OpenAI if OPENAI_API_KEY is set.
+        let queryVec;
+        try {
+            const { embedQuery } = await import("../db/embeddings.js");
+            const vec = await embedQuery(cleaned || query, process.env.OPENAI_API_KEY);
+            if (vec)
+                queryVec = vec;
+        }
+        catch { /* graceful degradation — vector unavailable */ }
+        const symbols = store.searchSymbols(cleaned || query, Math.ceil(limit / 2), queryVec);
+        return {
+            files: results.map((r) => r.file_path),
+            symbols: symbols.map((s) => ({ file: s.file_path, name: s.name, line: s.line })),
+            signal,
+        };
+    }
+    finally {
+        await store.close();
+    }
+}
+// ── File-based snapshots loader (original, unchanged) ────────────────────────
 async function loadSnapshots(inputDir) {
     const architecturePath = path.join(inputDir, "architecture.snapshot.yaml");
     const uxPath = path.join(inputDir, "ux.snapshot.yaml");
@@ -55,24 +247,21 @@ async function loadSnapshots(inputDir) {
     };
 }
 function normalizeTypes(types) {
+    const ALL_TYPES = ["models", "endpoints", "components", "modules", "tasks", "files"];
     if (!types || types.length === 0) {
-        return new Set(["models", "endpoints", "components", "modules", "tasks"]);
+        return new Set(ALL_TYPES);
     }
     const normalized = new Set();
     for (const entry of types) {
         for (const part of entry.split(",").map((value) => value.trim().toLowerCase())) {
-            if (part === "models" ||
-                part === "endpoints" ||
-                part === "components" ||
-                part === "modules" ||
-                part === "tasks") {
+            if (ALL_TYPES.includes(part) || part === "functions") {
                 normalized.add(part);
             }
         }
     }
     return normalized.size > 0
         ? normalized
-        : new Set(["models", "endpoints", "components", "modules", "tasks", "functions"]);
+        : new Set([...ALL_TYPES, "functions"]);
 }
 function tokenize(value) {
     return value
@@ -124,6 +313,31 @@ function searchSnapshots(params) {
         entry.id,
         entry.score
     ]));
+    // PageRank scores per file — prefer file-level heatmap, fall back to module-level
+    // (maps absolute or relative file path → pagerank score in [0,1])
+    const filePrFromFileLevel = new Map((heatmap?.levels.find((level) => level.level === "file")?.entries ?? []).map((entry) => [
+        entry.id,
+        entry.components.pagerank ?? 0
+    ]));
+    // Build file→module map so we can use module-level PR when file-level is unavailable
+    const fileToModuleId = new Map();
+    for (const mod of architecture.modules) {
+        for (const f of mod.files) {
+            fileToModuleId.set(f, mod.id);
+            fileToModuleId.set(path.join(projectRoot, f), mod.id);
+        }
+    }
+    const modulePrMap = new Map((heatmap?.levels.find((level) => level.level === "module")?.entries ?? []).map((entry) => [
+        entry.id,
+        entry.components.pagerank ?? 0
+    ]));
+    const getFilePr = (filePath) => {
+        const direct = filePrFromFileLevel.get(filePath);
+        if (direct !== undefined)
+            return direct;
+        const modId = fileToModuleId.get(filePath) ?? fileToModuleId.get(path.relative(projectRoot, filePath));
+        return modulePrMap.get(modId ?? "") ?? 0;
+    };
     if (types.has("models")) {
         for (const model of architecture.data_models) {
             const score = scoreItem(queryTokens, {
@@ -244,6 +458,57 @@ function searchSnapshots(params) {
             });
         }
     }
+    if (types.has("files")) {
+        const allFiles = new Map(); // keyed by normalized project-relative path
+        // Helper: normalize a path to project-relative form
+        const normalizePath = (rawPath, moduleId) => {
+            if (rawPath.startsWith("frontend/") || rawPath.startsWith("backend/"))
+                return rawPath;
+            // UX snapshot stores paths relative to frontend root (e.g. "app/parent/login.tsx")
+            if (moduleId.startsWith("frontend/"))
+                return `frontend/${rawPath}`;
+            return rawPath;
+        };
+        for (const mod of architecture.modules) {
+            for (const f of mod.files) {
+                const norm = normalizePath(f, mod.id);
+                const pr = getFilePr(f) || getFilePr(norm);
+                allFiles.set(norm, { filePath: norm, module: mod.id, pagerank: pr });
+            }
+        }
+        // Also collect ux component files (may not be in arch modules)
+        for (const comp of ux.components) {
+            if (!comp.file)
+                continue;
+            const norm = normalizePath(comp.file, "frontend/app");
+            if (!allFiles.has(norm)) {
+                allFiles.set(norm, { filePath: norm, module: "frontend/app", pagerank: getFilePr(norm) });
+            }
+        }
+        for (const { filePath, module: modId, pagerank } of allFiles.values()) {
+            const filename = path.basename(filePath);
+            const stem = filename.replace(/\.[^.]+$/, ""); // without extension
+            // Score: query overlap against path segments + filename stem
+            const pathSegments = filePath.split("/");
+            const queryScore = scoreItem(queryTokens, {
+                name: stem,
+                file: filePath,
+                text: pathSegments
+            });
+            if (queryScore <= 0)
+                continue;
+            // Blend query relevance + PageRank (architecturally important files surface higher)
+            const score = 0.7 * queryScore + 0.3 * pagerank;
+            matches.push({
+                type: "files",
+                name: filePath,
+                score,
+                markdown: [
+                    `${filePath} [${modId}]${pagerank > 0.5 ? " · high-pagerank" : ""}`
+                ]
+            });
+        }
+    }
     if (types.has("functions") && funcIntel) {
         const queryTokens = tokenize(query);
         const fnMatches = [];
@@ -282,13 +547,16 @@ function searchSnapshots(params) {
         };
         // 1. Name match — function / theorem name contains a query token
         for (const fn of funcIntel.functions) {
-            const score = scoreItem(queryTokens, {
+            const queryScore = scoreItem(queryTokens, {
                 name: fn.name,
                 file: fn.file,
                 text: [...fn.stringLiterals, ...fn.regexPatterns, ...fn.calls, fn.language],
             });
-            if (score <= 0)
+            if (queryScore <= 0)
                 continue;
+            // Blend: 70% query relevance + 30% file PageRank (importance of the file in the graph)
+            const pr = getFilePr(fn.file);
+            const score = 0.7 * queryScore + 0.3 * pr;
             const relFile = relativize(fn.file);
             const lineRange = `${fn.lines[0]}–${fn.lines[1]}`;
             const detail = buildDetail(fn, relFile);
@@ -316,17 +584,19 @@ function searchSnapshots(params) {
                 const fn = funcIntel.functions.find((f) => f.file === hit.file && f.name === hit.function);
                 if (!fn)
                     continue;
-                const score = scoreItem(queryTokens, {
+                const queryScore = scoreItem(queryTokens, {
                     name: fn.name,
                     file: fn.file,
                     text: [...fn.stringLiterals, ...fn.regexPatterns, ...fn.calls, fn.language],
                 });
+                const pr = getFilePr(fn.file);
+                const score = Math.max(0.7 * queryScore + 0.3 * pr, 0.2);
                 const relFile = relativize(fn.file);
                 const detail = buildDetail(fn, relFile);
                 fnMatches.push({
                     type: "functions",
                     name: `${fn.name} (${fn.language})`,
-                    score: Math.max(score, 0.2), // floor at 0.2 so literal hits still surface but rank below name matches
+                    score,
                     markdown: [
                         `**${fn.name}** · ${relFile}:${fn.lines[0]}–${fn.lines[1]} · ${fn.language}`,
                         `Matched literal/pattern containing "${tok}"`,
@@ -379,7 +649,92 @@ function formatProps(props) {
         .map((prop) => `${prop.name}${prop.optional ? "?" : ""}: ${prop.type}`)
         .join(", ");
 }
+/**
+ * Compact file-first renderer — the default for agent navigation.
+ *
+ * Deduplicates by file path and emits one line per file:
+ *   backend/service-auth/main.py  [create_child, PersonaCreateRequest, ...]
+ *
+ * Keeps total output small so LLMs can extract the answer without wading
+ * through hundreds of match lines. Capped at 15 files max.
+ */
 function renderSearchMarkdown(query, matches) {
+    if (matches.length === 0) {
+        return `# Search: "${query}"\n\n*No matches found.*`;
+    }
+    // Build a file → {score, symbols} map. Each match contributes its file path
+    // and a short symbol label extracted from the first markdown line.
+    const fileMap = new Map();
+    const extractFile = (md, matchType) => {
+        // Modules are collections — their path isn't a usable file path; skip them.
+        if (matchType === "modules")
+            return null;
+        const first = md[0] ?? "";
+        // Endpoint format: "POST /path → handler (file.py)"
+        let m = first.match(/\(([^)]+)\)\s*$/);
+        if (m)
+            return m[1].trim();
+        // Files type: bare path at start, no bold markdown — check before model format
+        // "path/to/file [module]" or "path/to/file [module] · high-pagerank"
+        m = first.match(/^([^\s[*]+)\s+\[/);
+        if (m)
+            return m[1].trim();
+        // Model/component/task/function: "**Name** · file.py ..."
+        m = first.match(/·\s+([^\s·:]+)\s*(?:·|$)/);
+        if (m)
+            return m[1].trim();
+        return null;
+    };
+    const extractSymbol = (md, matchType) => {
+        const first = md[0] ?? "";
+        if (matchType === "endpoints") {
+            // "POST /path → handler (file)" → extract "handler"
+            const m = first.match(/→\s+(\S+)\s+\(/);
+            return m ? m[1] : null;
+        }
+        if (matchType === "models" || matchType === "tasks" || matchType === "functions") {
+            // "**Name** · file" → extract "Name"
+            const m = first.match(/\*\*([^*]+)\*\*/);
+            return m ? m[1] : null;
+        }
+        if (matchType === "components") {
+            const m = first.match(/\*\*([^*]+)\*\*/);
+            return m ? m[1] : null;
+        }
+        return null;
+    };
+    for (const match of matches) {
+        const file = extractFile(match.markdown, match.type);
+        if (!file)
+            continue;
+        const existing = fileMap.get(file);
+        const symbol = extractSymbol(match.markdown, match.type);
+        if (existing) {
+            if (match.score > existing.score)
+                existing.score = match.score;
+            if (symbol && !existing.symbols.includes(symbol))
+                existing.symbols.push(symbol);
+        }
+        else {
+            fileMap.set(file, { score: match.score, symbols: symbol ? [symbol] : [] });
+        }
+    }
+    // Sort files by best score descending, cap at 15
+    const ranked = Array.from(fileMap.entries())
+        .sort(([, a], [, b]) => b.score - a.score)
+        .slice(0, 15);
+    const lines = [];
+    lines.push(`# Search: "${query}" — ${ranked.length} relevant files\n`);
+    for (const [file, { symbols }] of ranked) {
+        const sym = symbols.slice(0, 6).join(", ");
+        lines.push(sym ? `${file}  [${sym}]` : file);
+    }
+    return lines.join("\n").trimEnd();
+}
+/**
+ * Verbose grouped renderer — kept for human inspection (`--verbose`).
+ */
+function renderSearchMarkdownVerbose(query, matches) {
     const grouped = new Map();
     for (const match of matches) {
         const entry = grouped.get(match.type) ?? [];
@@ -392,6 +747,7 @@ function renderSearchMarkdown(query, matches) {
         ["components", "Components"],
         ["modules", "Modules"],
         ["tasks", "Tasks"],
+        ["files", "Files"],
         ["functions", "Functions"],
     ];
     const lines = [];
@@ -403,9 +759,8 @@ function renderSearchMarkdown(query, matches) {
     }
     for (const [type, label] of labels) {
         const entries = grouped.get(type) ?? [];
-        if (entries.length === 0) {
+        if (entries.length === 0)
             continue;
-        }
         lines.push(`## ${label} (${entries.length})`);
         lines.push("");
         for (const entry of entries.slice(0, 8)) {
@@ -415,3 +770,276 @@ function renderSearchMarkdown(query, matches) {
     }
     return lines.join("\n").trimEnd();
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Intel-based query functions
+// Read from pre-built intelligence files (written by VSCode plugin / guardian extract).
+// These are the authoritative implementations — MCP tools call the CLI which calls these.
+// ─────────────────────────────────────────────────────────────────────────────
+async function loadCodebaseIntel(inputDir) {
+    const intelPath = path.join(inputDir, "codebase-intelligence.json");
+    try {
+        const raw = await fs.readFile(intelPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { api_registry: {}, model_registry: {}, service_map: [], frontend_pages: [], enum_registry: {}, background_tasks: [], meta: {} };
+    }
+}
+async function loadFuncIntelRaw(inputDir) {
+    const fnPath = path.join(inputDir, "function-intelligence.json");
+    try {
+        const raw = await fs.readFile(fnPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Scoring (same algorithm as MCP, kept in sync) ──
+const SKIP_SERVICES = new Set(["str", "dict", "int", "len", "float", "max", "join", "getattr", "lower", "open", "params.append", "updates.append"]);
+function isGenericCall(s) {
+    if (SKIP_SERVICES.has(s))
+        return true;
+    const genericPrefixes = ["service.", "self.", "db.", "session.", "response.", "request.", "app.", "router.", "logger.", "config.", "os.", "json.", "re.", "datetime.", "uuid."];
+    return genericPrefixes.some(p => s.toLowerCase().startsWith(p));
+}
+function scoreQueryIntel(query, fields) {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    let best = 0;
+    for (const { value, weight } of fields) {
+        if (!value)
+            continue;
+        const low = value.toLowerCase();
+        if (low === query.toLowerCase()) {
+            best = Math.max(best, weight * 1.0);
+            continue;
+        }
+        if (low.includes(query.toLowerCase())) {
+            best = Math.max(best, weight * 0.8);
+            continue;
+        }
+        if (tokens.length > 1 && tokens.every(t => low.includes(t))) {
+            best = Math.max(best, weight * 0.6);
+            continue;
+        }
+        const matched = tokens.filter(t => t.length >= 3 && low.includes(t)).length;
+        if (matched > 0) {
+            best = Math.max(best, weight * (matched >= 2 ? 0.45 : 0.3));
+        }
+    }
+    return best;
+}
+function normalizeFilePath(p) {
+    return p.replace(/^\.\//, "").replace(/\/\//g, "/");
+}
+function findModuleForFile(data, file) {
+    const f = normalizeFilePath(file);
+    return data.service_map?.find((m) => {
+        const mp = normalizeFilePath(m.path || "");
+        return mp && (f.startsWith(mp + "/") || f === mp);
+    }) || data.service_map?.find((m) => {
+        const mid = normalizeFilePath(m.id || "");
+        return mid && f.includes(mid);
+    });
+}
+function findEndpointsInFile(data, file) {
+    const f = normalizeFilePath(file);
+    const basename = path.basename(f);
+    return Object.values(data.api_registry || {}).filter((ep) => {
+        const ef = normalizeFilePath(ep.file || "");
+        return ef && (f.includes(ef) || ef.includes(f) || ef.endsWith(basename));
+    });
+}
+function findModelsInFile(data, file) {
+    const f = normalizeFilePath(file);
+    const basename = path.basename(f);
+    return Object.values(data.model_registry || {}).filter((m) => {
+        const mf = normalizeFilePath(m.file || "");
+        return mf && (f.includes(mf) || mf.includes(f) || mf.endsWith(basename));
+    });
+}
+// ── orient: architecture-context.md as compact JSON ──
+export async function queryOrient(inputDir) {
+    const contextPath = path.join(inputDir, "architecture-context.md");
+    try {
+        const raw = await fs.readFile(contextPath, "utf8");
+        const match = raw.match(/<!-- guardian:context[^>]*-->([\s\S]*?)<!-- \/guardian:context -->/);
+        if (match) {
+            const lines = match[1].split("\n").map(l => l.trim()).filter(Boolean);
+            const desc = raw.match(/Description: (.+)/)?.[1]?.slice(0, 120) ?? "";
+            const map = lines.find(l => l.startsWith("**Backend:**")) ?? "";
+            const modules = lines
+                .filter(l => /^- \*\*[^*]+\*\*\s*\([^)]+\)/.test(l))
+                .map(l => { const m = l.match(/\*\*([^*]+)\*\*\s*\(([^)]+)\)/); return m ? `${m[1]} (${m[2]})` : null; })
+                .filter((x) => x !== null);
+            const deps = lines.filter(l => l.includes("→")).map(l => l.replace(/^- /, ""));
+            const coupling = lines.filter(l => /score \d/.test(l)).map(l => l.replace(/^- /, "")).slice(0, 5);
+            const modelEp = lines.filter(l => l.includes("endpoints) ->")).map(l => l.replace(/^- /, ""));
+            return JSON.stringify({ desc, map, modules, deps, coupling, modelEp });
+        }
+    }
+    catch { }
+    const d = await loadCodebaseIntel(inputDir);
+    const c = d.meta?.counts || {};
+    const pages = (d.frontend_pages || []).map((p) => p.path);
+    return JSON.stringify({ p: d.meta?.project, ep: c.endpoints, models: c.models, pg: c.pages, pages });
+}
+// ── file: per-file or per-endpoint context ──
+export async function queryFile(inputDir, target) {
+    const d = await loadCodebaseIntel(inputDir);
+    const epMatch = target.match(/^(GET|POST|PUT|DELETE|PATCH)\s+(.+)$/i);
+    if (epMatch) {
+        const ep = d.api_registry?.[`${epMatch[1].toUpperCase()} ${epMatch[2]}`]
+            || Object.values(d.api_registry || {}).find((e) => e.method === epMatch[1].toUpperCase() && e.path === epMatch[2]);
+        if (!ep)
+            return JSON.stringify({ err: "not found" });
+        const calls = (ep.service_calls || []).filter((s) => !SKIP_SERVICES.has(s));
+        return JSON.stringify({ ep: `${ep.method} ${ep.path}`, h: ep.handler, f: ep.file, m: ep.module, req: ep.request_schema, res: ep.response_schema, calls, ai: ep.ai_operations?.length || 0 });
+    }
+    const file = normalizeFilePath(target);
+    const mod = findModuleForFile(d, file);
+    const eps = findEndpointsInFile(d, file);
+    const models = findModelsInFile(d, file);
+    const fileName = path.basename(file, path.extname(file));
+    const calledBy = [];
+    for (const ep of Object.values(d.api_registry || {})) {
+        if (ep.service_calls?.some((s) => s.toLowerCase().includes(fileName.toLowerCase()))) {
+            calledBy.push(`${ep.method} ${ep.path}`);
+        }
+    }
+    const calls = eps.flatMap((ep) => (ep.service_calls || []).filter((s) => !SKIP_SERVICES.has(s)));
+    return JSON.stringify({ f: file, mod: mod ? [mod.id, mod.layer] : null, ep: eps.map((e) => `${e.method} ${e.path}`), models: models.map((m) => [m.name, m.fields?.length || 0]), calls: [...new Set(calls)], calledBy: calledBy.slice(0, 8) });
+}
+// ── model: model details + usage ──
+export async function queryModel(inputDir, name) {
+    const d = await loadCodebaseIntel(inputDir);
+    const m = d.model_registry?.[name];
+    if (!m)
+        return JSON.stringify({ err: "not found", name });
+    const usedBy = Object.values(d.api_registry || {})
+        .filter((ep) => ep.request_schema === name || ep.response_schema === name)
+        .map((ep) => `${ep.method} ${ep.path}`);
+    return JSON.stringify({ name: m.name, fw: m.framework, f: m.file, fields: m.fields, rels: m.relationships, usedBy });
+}
+// ── impact: what breaks if you change this file ──
+export async function queryImpact(inputDir, target) {
+    const d = await loadCodebaseIntel(inputDir);
+    const file = normalizeFilePath(target);
+    const eps = findEndpointsInFile(d, file);
+    const models = findModelsInFile(d, file);
+    const modelNames = new Set(models.map((m) => m.name));
+    const affectedEps = Object.values(d.api_registry || {}).filter((ep) => (ep.request_schema && modelNames.has(ep.request_schema)) ||
+        (ep.response_schema && modelNames.has(ep.response_schema)));
+    const mod = findModuleForFile(d, file);
+    const depMods = mod ? (d.service_map || []).filter((m) => m.imports?.includes(mod.id)) : [];
+    const affectedPages = (d.frontend_pages || []).filter((p) => p.api_calls?.some((call) => eps.some((ep) => call.includes(ep.path?.split("{")[0]))));
+    const total = eps.length + affectedEps.length + depMods.length + affectedPages.length;
+    return JSON.stringify({ f: file, risk: total > 5 ? "HIGH" : total > 2 ? "MED" : "LOW", ep: eps.map((e) => `${e.method} ${e.path}`), models: models.map((m) => m.name), affectedEp: affectedEps.map((e) => `${e.method} ${e.path}`), depMods: depMods.map((m) => m.id), pages: affectedPages.map((p) => p.path) });
+}
+// ── querySearch --format json: categorical search from codebase-intelligence.json ──
+export async function querySearch(inputDir, query) {
+    const d = await loadCodebaseIntel(inputDir);
+    const q = query;
+    const scoredEps = [];
+    for (const ep of Object.values(d.api_registry || {})) {
+        const score = scoreQueryIntel(q, [
+            { value: ep.path, weight: 1.0 }, { value: ep.handler, weight: 0.9 },
+            ...(ep.service_calls || []).filter((s) => !isGenericCall(s)).map((s) => ({ value: s, weight: 0.5 })),
+        ]);
+        if (score > 0)
+            scoredEps.push({ item: ep, score });
+    }
+    scoredEps.sort((a, b) => b.score - a.score);
+    const eps = scoredEps.slice(0, 8).map(({ item: ep }) => `${ep.method} ${ep.path} [${ep.module}]`);
+    const scoredModels = [];
+    for (const m of Object.values(d.model_registry || {})) {
+        const score = scoreQueryIntel(q, [{ value: m.name, weight: 1.0 }, ...(m.fields || []).map((f) => ({ value: f, weight: 0.6 }))]);
+        if (score > 0)
+            scoredModels.push({ item: m, score });
+    }
+    scoredModels.sort((a, b) => b.score - a.score);
+    const models = scoredModels.slice(0, 8).map(({ item: m }) => `${m.name}:${m.fields?.length}f`);
+    const mods = (d.service_map || []).filter((m) => scoreQueryIntel(q, [{ value: m.id, weight: 1.0 }, ...(m.imports || []).map((i) => ({ value: i, weight: 0.5 }))]) > 0).slice(0, 5).map((m) => `${m.id}:${m.file_count}files [${m.layer}]`);
+    const scoredExports = [];
+    for (const m of d.service_map || []) {
+        for (const sym of m.exports || []) {
+            const score = scoreQueryIntel(q, [{ value: sym, weight: 1.0 }]);
+            if (score > 0)
+                scoredExports.push({ item: `${sym} [${m.id}]`, score });
+        }
+    }
+    scoredExports.sort((a, b) => b.score - a.score);
+    const ASSET_EXTS = new Set([".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".css", ".scss", ".less", ".lock", ".map"]);
+    const isMigration = (f) => /alembic\/versions|migrations\/\d/.test(f);
+    const scoredFiles = [];
+    for (const m of d.service_map || []) {
+        for (const f of m.files || []) {
+            if (ASSET_EXTS.has(path.extname(f).toLowerCase()) || isMigration(f))
+                continue;
+            const score = scoreQueryIntel(q, [{ value: path.basename(f), weight: 1.0 }, { value: f, weight: 0.5 }]);
+            if (score > 0)
+                scoredFiles.push({ item: f, score });
+        }
+    }
+    scoredFiles.sort((a, b) => b.score - a.score);
+    const enums = Object.values(d.enum_registry || {}).filter((e) => scoreQueryIntel(q, [{ value: e.name, weight: 1.0 }, ...(e.values || []).map((v) => ({ value: v, weight: 0.6 }))]) > 0).slice(0, 5).map((e) => `${e.name} [${e.file}]`);
+    const tasks = (d.background_tasks || []).filter((t) => scoreQueryIntel(q, [{ value: t.name, weight: 1.0 }, { value: t.kind, weight: 0.6 }]) > 0).slice(0, 5).map((t) => `${t.name} [${t.kind}] ${t.file}`);
+    const pages = (d.frontend_pages || []).filter((p) => scoreQueryIntel(q, [
+        { value: p.path, weight: 1.0 },
+        { value: p.component, weight: 0.9 },
+        { value: p.file ?? "", weight: 0.8 },
+        ...(p.api_calls || []).map((c) => ({ value: c, weight: 0.5 })),
+        ...(p.components || []).map((c) => ({ value: c, weight: 0.4 })),
+    ]) > 0).slice(0, 5).map((p) => p.file ? `${p.path} [${p.file}]` : `${p.path} → ${p.component}`);
+    const fnHits = [];
+    const fi = await loadFuncIntelRaw(inputDir);
+    if (fi) {
+        const scored = [];
+        const seen = new Set();
+        for (const fn of (fi.functions ?? [])) {
+            const nameNorm = (fn.name ?? "").toLowerCase();
+            const fileNorm = (fn.file ?? "").toLowerCase();
+            const callsNorm = (fn.calls ?? []).map((c) => c.toLowerCase());
+            const litsNorm = [...(fn.stringLiterals ?? []), ...(fn.regexPatterns ?? [])].map((l) => l.toLowerCase());
+            let score = 0;
+            if (nameNorm === q)
+                score = 1.0;
+            else if (nameNorm.includes(q))
+                score = 0.7;
+            else if (callsNorm.some((c) => c.includes(q)))
+                score = 0.5;
+            else if (litsNorm.some((l) => l.includes(q)))
+                score = 0.3;
+            else if (fileNorm.includes(q))
+                score = 0.2;
+            if (score > 0) {
+                scored.push({ fn, score });
+                seen.add(`${fn.file}:${fn.name}`);
+            }
+        }
+        const litIndex = fi.literal_index ?? {};
+        for (const [key, hits] of Object.entries(litIndex)) {
+            if (!key.includes(q))
+                continue;
+            for (const h of hits) {
+                const uid = `${h.file}:${h.function}`;
+                if (seen.has(uid))
+                    continue;
+                seen.add(uid);
+                const fn = fi.functions.find((f) => f.file === h.file && f.name === h.function);
+                scored.push({ fn: fn ?? { name: h.function, file: h.file, lines: [h.line, h.line] }, score: 0.25 });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score);
+        for (const { fn } of scored.slice(0, 10)) {
+            fnHits.push(`${fn.name} [${fn.file}:${fn.lines?.[0]}]`);
+        }
+    }
+    return JSON.stringify({
+        ep: eps, mod: models, m: mods,
+        exports: scoredExports.slice(0, 10).map(e => e.item),
+        files: scoredFiles.slice(0, 8).map(f => f.item),
+        enums, tasks, pages,
+        ...(fnHits.length > 0 ? { fns: fnHits } : {}),
+    });
+}