vemora 0.1.0-alpha.15

package/dist/commands/context.js

@@ -0,0 +1,794 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContext = runContext;
+exports.generateContextString = generateContextString;
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+const ora_1 = __importDefault(require("ora"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const git_1 = require("../utils/git");
+const factory_1 = require("../embeddings/factory");
+const deps_1 = require("../indexer/deps");
+const tests_1 = require("../indexer/tests");
+const bm25_1 = require("../search/bm25");
+const hybrid_1 = require("../search/hybrid");
+const merge_1 = require("../search/merge");
+const mmr_1 = require("../search/mmr");
+const rerank_1 = require("../search/rerank");
+const formatter_1 = require("../search/formatter");
+const signature_1 = require("../search/signature");
+const vector_1 = require("../search/vector");
+const cache_1 = require("../storage/cache");
+const knowledge_1 = require("../storage/knowledge");
+const repository_1 = require("../storage/repository");
+const session_1 = require("../storage/session");
+const usage_1 = require("../storage/usage");
+const summaries_1 = require("../storage/summaries");
+const tokenizer_1 = require("../utils/tokenizer");
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function runContext(rootDir, options = {}) {
+    const config = (0, config_1.loadConfig)(rootDir);
+    const repo = new repository_1.RepositoryStorage(rootDir);
+    const cacheStorage = new cache_1.EmbeddingCacheStorage(config.projectId);
+    const summaryStorage = new summaries_1.SummaryStorage(rootDir);
+    const topK = options.topK ?? 5;
+    // Apply config.display.format as default if no explicit format was passed.
+    const resolvedOptions = {
+        ...options,
+        format: options.format ?? config.display?.format ?? "markdown",
+    };
+    let chunks = repo.loadChunks();
+    const symbols = repo.loadSymbols();
+    const depGraph = repo.loadDeps();
+    const callGraph = repo.loadCallGraph();
+    const fileSummaries = summaryStorage.hasFileSummaries()
+        ? summaryStorage.loadFileSummaries()
+        : {};
+    const projectSummary = summaryStorage.loadProjectSummary();
+    const knowledgeEntries = (0, knowledge_1.filterValidAt)(new knowledge_1.KnowledgeStorage(rootDir).load());
+    if (options.since) {
+        const changedFiles = new Set((0, git_1.getChangedFiles)(options.since, rootDir));
+        if (changedFiles.size === 0) {
+            console.log(chalk_1.default.yellow(`No changed files since ${options.since}.`));
+            return;
+        }
+        chunks = chunks.filter((c) => changedFiles.has(c.file));
+        if (chunks.length === 0) {
+            console.log(chalk_1.default.yellow(`No indexed chunks in the diff since ${options.since}.`));
+            return;
+        }
+        console.log(chalk_1.default.gray(`  Scope: ${changedFiles.size} changed file(s) since ${options.since}\n`));
+    }
+    if (chunks.length === 0) {
+        console.error(chalk_1.default.red("No index found. Run `vemora index` first."));
+        process.exit(1);
+    }
+    if (!options.query && !options.file) {
+        console.error(chalk_1.default.red("Provide --query <text> and/or --file <path>."));
+        process.exit(1);
+    }
+    let results = [];
+    let searchType = "none";
+    let tokensSavedSession = 0;
+    let tokensSavedDedup = 0;
+    let tokensSavedBudget = 0;
+    const usageStart = Date.now();
+    if (typeof options.query === "string" && options.query.length > 0) {
+        const useKeyword = options.keyword || config.embedding.provider === "none";
+        const useHybrid = options.hybrid;
+        // Symbol-aware routing: direct lookup for precise identifier queries.
+        const symbolHits = !useHybrid && !useKeyword
+            ? (0, vector_1.symbolLookup)(options.query, chunks, symbols)
+            : [];
+        if (symbolHits.length > 0) {
+            results = symbolHits;
+            searchType = "symbol";
+        }
+        else if (useKeyword) {
+            const spinner = (0, ora_1.default)("Performing hybrid search...").start();
+            try {
+                const cache = cacheStorage.load();
+                if (!cache ||
+                    (cache.chunkIds?.length === 0 &&
+                        Object.keys(cache.embeddings ?? {}).length === 0)) {
+                    spinner.warn("No embeddings — falling back to BM25.");
+                    results = (0, bm25_1.computeBM25Scores)(options.query, chunks, symbols, topK);
+                    searchType = "bm25";
+                }
+                else {
+                    const provider = (0, factory_1.createEmbeddingProvider)(config.embedding);
+                    const [queryEmbedding] = await provider.embed([options.query]);
+                    spinner.succeed("Embedded");
+                    results = await (0, hybrid_1.hybridSearch)(options.query, queryEmbedding, chunks, cache, symbols, {
+                        alpha: options.alpha,
+                        topK,
+                    });
+                    searchType = "hybrid";
+                }
+            }
+            catch (err) {
+                spinner.fail(`Hybrid search failed: ${err.message}`);
+                results = (0, bm25_1.computeBM25Scores)(options.query, chunks, symbols, topK);
+                searchType = "bm25";
+            }
+        }
+        else {
+            const spinner = (0, ora_1.default)("Generating query embedding...").start();
+            try {
+                const cache = cacheStorage.load();
+                const cachedCount = cache
+                    ? cache.chunkIds
+                        ? cache.chunkIds.length
+                        : Object.keys(cache.embeddings ?? {}).length
+                    : 0;
+                if (!cache || cachedCount === 0) {
+                    spinner.warn("No embeddings — falling back to BM25.");
+                    results = (0, bm25_1.computeBM25Scores)(options.query, chunks, symbols, topK);
+                    searchType = "bm25";
+                }
+                else {
+                    const provider = (0, factory_1.createEmbeddingProvider)(config.embedding);
+                    const [queryEmbedding] = await provider.embed([options.query]);
+                    spinner.succeed("Embedded");
+                    results = (0, vector_1.vectorSearch)(queryEmbedding, chunks, cache, symbols, topK);
+                    searchType = "vector";
+                    if (results.length === 0) {
+                        results = (0, bm25_1.computeBM25Scores)(options.query, chunks, symbols, topK);
+                        searchType = "bm25";
+                    }
+                }
+            }
+            catch (err) {
+                spinner.fail(`Embedding failed: ${err.message}`);
+                results = (0, bm25_1.computeBM25Scores)(options.query, chunks, symbols, topK);
+                searchType = "bm25";
+            }
+        }
+        // ── Reranking (optional) ──────────────────────────────────────────────
+        if (options.rerank && results.length > 0) {
+            results = await (0, rerank_1.rerankResults)(options.query, results, topK, config.reranker, config.summarization?.model);
+        }
+        // ── MMR deduplication (optional) ─────────────────────────────────────
+        if (options.mmr && results.length > 1) {
+            const cache = cacheStorage.load();
+            results = (0, mmr_1.applyMMR)(results, cache, topK, options.lambda ?? 0.5);
+        }
+        // ── Adjacent chunk merge (optional) ──────────────────────────────────
+        if (options.merge && results.length > 1) {
+            results = (0, merge_1.mergeAdjacentChunks)(results, options.mergeGap);
+        }
+        // ── Session filter (optional) ─────────────────────────────────────────
+        const sessionStorage = new session_1.SessionStorage(config.projectId);
+        if (options.fresh)
+            sessionStorage.reset();
+        if ((options.session || options.fresh) && results.length > 0) {
+            const seenIds = sessionStorage.getSeenIds();
+            if (seenIds.size > 0) {
+                const tBefore = (0, tokenizer_1.sumResultTokens)(results);
+                const unseen = results.filter((r) => !seenIds.has(r.chunk.id));
+                results = unseen.length > 0 ? unseen : results.slice(0, 1);
+                tokensSavedSession = tBefore - (0, tokenizer_1.sumResultTokens)(results);
+            }
+        }
+        // ── Semantic deduplication (always-on) ───────────────────────────────
+        if (results.length > 1) {
+            const tBefore = (0, tokenizer_1.sumResultTokens)(results);
+            const cache = cacheStorage.load();
+            results = (0, merge_1.deduplicateBySimilarity)(results, cache);
+            tokensSavedDedup = tBefore - (0, tokenizer_1.sumResultTokens)(results);
+        }
+        // ── Token budget (optional) ───────────────────────────────────────────
+        if (options.budget && options.budget > 0) {
+            const tBefore = (0, tokenizer_1.sumResultTokens)(results);
+            results = (0, tokenizer_1.applyTokenBudget)(results, options.budget);
+            tokensSavedBudget = tBefore - (0, tokenizer_1.sumResultTokens)(results);
+        }
+        // ── Persist session ───────────────────────────────────────────────────
+        if ((options.session || options.fresh) && results.length > 0) {
+            sessionStorage.markSeen(results.map((r) => r.chunk.id));
+        }
+        // ── Record usage event ──────────────────────────────────────────────
+        try {
+            new usage_1.UsageStorage(config.projectId).append({
+                ts: new Date().toISOString(),
+                command: "context",
+                query: options.query?.slice(0, 120),
+                searchType,
+                format: options.format,
+                topK,
+                resultsReturned: results.length,
+                tokensReturned: (0, tokenizer_1.sumResultTokens)(results),
+                tokensSavedDedup,
+                tokensSavedSession,
+                tokensSavedBudget,
+                durationMs: Date.now() - usageStart,
+                topFiles: [...new Set(results.map((r) => r.chunk.file))].slice(0, 3),
+            });
+        }
+        catch {
+            // usage tracking is best-effort — never block the main output
+        }
+    }
+    const contextStr = generateContextString(config, results, depGraph, callGraph, fileSummaries, projectSummary ? projectSummary.overview : null, resolvedOptions, rootDir, chunks, knowledgeEntries);
+    console.log(contextStr);
+}
+/**
+ * Procedural function to build the actual context string.
+ * This is separated from runContext to allow for benchmarking and testing.
+ *
+ * When `options.structured` is true and results are available, delegates to
+ * `generateStructuredContextString` which organises output by semantic role
+ * (Entry Point → Direct Dependencies → Called By → Types & Interfaces → Related Patterns)
+ * instead of a flat ranked list.
+ *
+ * @param allChunks - Full chunk corpus, required for structured mode dep resolution.
+ *                    Optional for backward compatibility with bench.ts.
+ */
+function generateContextString(config, results, depGraph, callGraph, fileSummaries, projectOverview, options, rootDir, allChunks = [], knowledgeEntries = []) {
+    if (options.structured && results.length > 0) {
+        return generateStructuredContextString(config, results, depGraph, callGraph, fileSummaries, projectOverview, options, rootDir, allChunks, knowledgeEntries);
+    }
+    if (options.format === "terse") {
+        const lines = [];
+        lines.push(`# ${config.projectName}`);
+        lines.push("");
+        const relevant = rankKnowledgeEntries(options.query, results, knowledgeEntries);
+        for (const entry of relevant) {
+            lines.push(`[${entry.category}] ${entry.title}: ${entry.body}`);
+        }
+        if (relevant.length > 0)
+            lines.push("");
+        lines.push((0, formatter_1.formatTerse)(results, {}));
+        return lines.join("\n");
+    }
+    const fmt = options.format ?? "markdown";
+    const lines = [];
+    const hr = fmt === "markdown" ? "---" : "=".repeat(60);
+    const importedByMap = (0, deps_1.computeImportedBy)(depGraph);
+    // ── Section: Project overview ──────────────────────────────────────────────
+    lines.push(fmt === "markdown"
+        ? `# AI Context — ${config.projectName}`
+        : `=== AI CONTEXT BLOCK — ${config.projectName.toUpperCase()} ===`);
+    lines.push("");
+    if (projectOverview) {
+        lines.push(fmt === "markdown" ? "## Project Overview" : "[Project Overview]");
+        lines.push("");
+        lines.push(projectOverview);
+        lines.push("");
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Section: Knowledge entries ────────────────────────────────────────────
+    const relevantKnowledge = rankKnowledgeEntries(options.query, results, knowledgeEntries);
+    if (relevantKnowledge.length > 0) {
+        lines.push(fmt === "markdown" ? "## Knowledge" : "[Knowledge]");
+        lines.push("");
+        for (const entry of relevantKnowledge) {
+            const badge = fmt === "markdown" ? `\`${entry.category}\`` : entry.category;
+            lines.push(fmt === "markdown"
+                ? `**${entry.title}** ${badge}`
+                : `${entry.title} [${entry.category}]`);
+            lines.push(entry.body);
+            if (entry.relatedFiles?.length) {
+                lines.push(fmt === "markdown"
+                    ? `_Files: ${entry.relatedFiles.map((f) => `\`${f}\``).join(", ")}_`
+                    : `Files: ${entry.relatedFiles.join(", ")}`);
+            }
+            lines.push("");
+        }
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Section: Specific file context ────────────────────────────────────────
+    if (options.file) {
+        const relFile = resolveRelPath(rootDir, options.file);
+        lines.push(fmt === "markdown" ? "## File Context" : "[File Context]");
+        lines.push("");
+        lines.push(fmt === "markdown" ? `**File:** \`${relFile}\`` : `File: ${relFile}`);
+        lines.push("");
+        // Full file content
+        const absPath = path_1.default.join(rootDir, relFile);
+        if (fs_1.default.existsSync(absPath)) {
+            // Resolve symlinks before reading to prevent traversal via symlinks
+            const realRoot = fs_1.default.realpathSync(path_1.default.resolve(rootDir));
+            const realPath = fs_1.default.realpathSync(absPath);
+            if (!realPath.startsWith(realRoot + path_1.default.sep) && realPath !== realRoot) {
+                throw new Error(`File path escapes project root via symlink: ${options.file}`);
+            }
+            const content = fs_1.default.readFileSync(realPath, "utf-8");
+            const ext = relFile.split(".").pop() ?? "";
+            if (fmt === "markdown") {
+                lines.push(`\`\`\`${ext}`);
+                lines.push(content);
+                lines.push("```");
+            }
+            else {
+                lines.push(content);
+            }
+            lines.push("");
+        }
+        else {
+            lines.push(fmt === "markdown" ? "_File not found._" : "(file not found)");
+            lines.push("");
+        }
+        // Imports and used-by for the file
+        const fileDeps = depGraph[relFile];
+        const usedBy = importedByMap.get(relFile) ?? [];
+        if (fileDeps?.imports.length) {
+            lines.push(fmt === "markdown"
+                ? "**Imports from project:**"
+                : "Imports from project:");
+            for (const imp of fileDeps.imports) {
+                const syms = imp.symbols.length > 0 ? ` (${imp.symbols.join(", ")})` : "";
+                lines.push(fmt === "markdown"
+                    ? `- \`${imp.file}\`${syms}`
+                    : `  - ${imp.file}${syms}`);
+            }
+            lines.push("");
+        }
+        if (usedBy.length > 0) {
+            lines.push(fmt === "markdown" ? "**Used by:**" : "Used by:");
+            for (const caller of usedBy) {
+                lines.push(fmt === "markdown" ? `- \`${caller}\`` : `  - ${caller}`);
+            }
+            lines.push("");
+        }
+        // Git commit history for this file
+        const commits = (0, git_1.getFileGitHistory)(rootDir, relFile);
+        if (commits.length > 0) {
+            lines.push(fmt === "markdown" ? "**Recent commits:**" : "Recent commits:");
+            for (const c of commits) {
+                lines.push(fmt === "markdown"
+                    ? `- \`${c.sha}\` ${c.message} _(${c.author}, ${c.date})_`
+                    : `  - ${c.sha} ${c.message} (${c.author}, ${c.date})`);
+            }
+            lines.push("");
+        }
+        // TODOs / FIXMEs in this file
+        const fileTodos = new repository_1.RepositoryStorage(rootDir).loadTodos().filter((t) => t.file === relFile);
+        if (fileTodos.length > 0) {
+            lines.push(fmt === "markdown" ? "**TODOs / FIXMEs:**" : "TODOs / FIXMEs:");
+            for (const t of fileTodos) {
+                lines.push(fmt === "markdown"
+                    ? `- **${t.type}** (line ${t.line}): ${t.text}`
+                    : `  - ${t.type} (line ${t.line}): ${t.text}`);
+            }
+            lines.push("");
+        }
+        // Test files linked to this source file
+        const allFileKeys = [...new Set(allChunks.map((c) => c.file))];
+        const testFiles = (0, tests_1.findTestFiles)(relFile, allFileKeys, importedByMap);
+        if (testFiles.length > 0) {
+            lines.push(fmt === "markdown" ? "**Test files:**" : "Test files:");
+            for (const tf of testFiles) {
+                lines.push(fmt === "markdown" ? `- \`${tf}\`` : `  - ${tf}`);
+            }
+            lines.push("");
+        }
+        // Caller context: symbols exported by this file and who calls them
+        const fileSymbols = [
+            ...new Set(allChunks
+                .filter((c) => c.file === relFile && c.symbol)
+                .map((c) => c.symbol)),
+        ];
+        const callerRows = [];
+        for (const sym of fileSymbols) {
+            const callInfo = callGraph[`${relFile}:${sym}`];
+            if (callInfo?.calledBy.length) {
+                const callers = callInfo.calledBy.slice(0, 5);
+                const rest = callInfo.calledBy.length - callers.length;
+                const callerList = fmt === "markdown"
+                    ? callers.map((c) => `\`${c}\``).join(", ") +
+                        (rest > 0 ? ` _+${rest} more_` : "")
+                    : callers.join(", ") + (rest > 0 ? ` +${rest} more` : "");
+                callerRows.push(fmt === "markdown"
+                    ? `- \`${sym}\` ← ${callerList}`
+                    : `  - ${sym} <- ${callerList}`);
+            }
+        }
+        if (callerRows.length > 0) {
+            lines.push(fmt === "markdown" ? "**Symbol callers:**" : "Symbol callers:");
+            lines.push(...callerRows);
+            lines.push("");
+        }
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Section: Relevant code via query ──────────────────────────────────────
+    if (options.query) {
+        lines.push(fmt === "markdown" ? "## Relevant Code" : "[Relevant Code]");
+        lines.push("");
+        if (results.length === 0) {
+            lines.push("_No relevant results found._");
+        }
+        else {
+            const seen = new Set();
+            for (const { chunk, score, symbol } of results) {
+                if (seen.has(chunk.id))
+                    continue;
+                seen.add(chunk.id);
+                const ext = chunk.file.split(".").pop() ?? "";
+                const symLabel = chunk.symbol
+                    ? ` — ${symbol?.type ?? "symbol"} \`${chunk.symbol}\``
+                    : "";
+                if (fmt === "markdown") {
+                    lines.push(`### \`${chunk.file}\`${symLabel}`);
+                    lines.push(`Lines ${chunk.start}–${chunk.end} · Score: ${score.toFixed(4)}`);
+                }
+                else {
+                    lines.push(`[${chunk.file}${symLabel}]`);
+                    lines.push(`lines ${chunk.start}–${chunk.end}  score: ${score.toFixed(4)}`);
+                }
+                lines.push("");
+                // Deps context (only if graph available)
+                const fileDeps = depGraph[chunk.file];
+                const usedBy = importedByMap.get(chunk.file) ?? [];
+                if (fileDeps?.imports.length) {
+                    lines.push(fmt === "markdown" ? "**Imports:**" : "Imports:");
+                    for (const imp of fileDeps.imports.slice(0, 5)) {
+                        const syms = imp.symbols.length > 0
+                            ? ` (${imp.symbols.slice(0, 4).join(", ")})`
+                            : "";
+                        lines.push(fmt === "markdown"
+                            ? `- \`${imp.file}\`${syms}`
+                            : `  - ${imp.file}${syms}`);
+                    }
+                    lines.push("");
+                }
+                if (usedBy.length > 0) {
+                    lines.push(fmt === "markdown" ? "**Used by:**" : "Used by:");
+                    for (const caller of usedBy.slice(0, 3)) {
+                        lines.push(fmt === "markdown" ? `- \`${caller}\`` : `  - ${caller}`);
+                    }
+                    lines.push("");
+                }
+                // Call Graph context
+                const symbolId = chunk.symbol ? `${chunk.file}:${chunk.symbol}` : null;
+                const callInfo = symbolId ? callGraph[symbolId] : null;
+                if (callInfo) {
+                    if (callInfo.calls.length > 0) {
+                        lines.push(fmt === "markdown" ? "**Calls:**" : "Calls:");
+                        for (const call of callInfo.calls.slice(0, 5)) {
+                            const loc = call.file ? ` (in \`${call.file}\`)` : "";
+                            lines.push(fmt === "markdown"
+                                ? `- \`${call.name}\`${loc}`
+                                : `  - ${call.name}${loc}`);
+                        }
+                        lines.push("");
+                    }
+                    if (callInfo.calledBy.length > 0) {
+                        lines.push(fmt === "markdown" ? "**Called by:**" : "Called by:");
+                        for (const callerId of callInfo.calledBy.slice(0, 5)) {
+                            lines.push(fmt === "markdown" ? `- \`${callerId}\`` : `  - ${callerId}`);
+                        }
+                        lines.push("");
+                    }
+                }
+                // Code
+                const codeLines = chunk.content.split("\n");
+                const limit = options.showCode ? codeLines.length : signature_1.HIGH_CODE_LINES;
+                const preview = codeLines.slice(0, limit).join("\n");
+                const truncated = codeLines.length > limit;
+                if (fmt === "markdown") {
+                    lines.push(`\`\`\`${ext}`);
+                    lines.push(preview);
+                    if (truncated)
+                        lines.push(`// … (${codeLines.length - limit} more lines)`);
+                    lines.push("```");
+                }
+                else {
+                    lines.push(preview);
+                    if (truncated)
+                        lines.push(`... (${codeLines.length - limit} more lines)`);
+                }
+                lines.push("");
+                lines.push(hr);
+                lines.push("");
+            }
+        }
+    }
+    // ── Footer ────────────────────────────────────────────────────────────────
+    lines.push(fmt === "markdown"
+        ? `_Generated by \`vemora context\` — ${new Date().toISOString()}_`
+        : `=== END AI CONTEXT BLOCK — ${new Date().toISOString()} ===`);
+    return lines.join("\n");
+}
+// ─── Knowledge ranking ────────────────────────────────────────────────────────
+/**
+ * Ranks knowledge entries by relevance to the current query and result set.
+ *
+ * Scoring (higher = more relevant):
+ *  +10  relatedFiles overlaps with result files
+ *  +8   relatedSymbols overlaps with result symbols
+ *  +2   per query term found in title+body
+ *  +4/3/2/1  category weight: gotcha > pattern > decision > glossary
+ *  +1   confidence === 'high'
+ *
+ * Only entries with score > 0 are returned (max 5, sorted descending).
+ */
+function rankKnowledgeEntries(query, results, entries, maxEntries = 5) {
+    if (entries.length === 0)
+        return [];
+    const resultFiles = new Set(results.map((r) => r.chunk.file));
+    const resultSymbols = new Set(results.flatMap((r) => (r.chunk.symbol ? [r.chunk.symbol] : [])));
+    const categoryWeight = {
+        gotcha: 4,
+        pattern: 3,
+        decision: 2,
+        glossary: 1,
+    };
+    const queryTerms = query
+        ? new Set(query
+            .toLowerCase()
+            .split(/[\s\W]+/)
+            .filter((t) => t.length >= 2))
+        : new Set();
+    const scored = entries.map((entry) => {
+        let score = 0;
+        if (entry.relatedFiles?.some((f) => resultFiles.has(f)))
+            score += 10;
+        if (entry.relatedSymbols?.some((s) => resultSymbols.has(s)))
+            score += 8;
+        if (queryTerms.size > 0) {
+            const text = `${entry.title} ${entry.body}`.toLowerCase();
+            for (const term of queryTerms) {
+                if (text.includes(term))
+                    score += 2;
+            }
+        }
+        score += categoryWeight[entry.category] ?? 1;
+        if (entry.confidence === "high")
+            score += 1;
+        return { entry, score };
+    });
+    return scored
+        .filter((s) => s.score > (categoryWeight[s.entry.category] ?? 1)) // exclude pure category-weight matches
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxEntries)
+        .map((s) => s.entry);
+}
+// ─── Structured context renderer ─────────────────────────────────────────────
+/**
+ * Renders a structured context block organised by semantic role:
+ *
+ *   ## Entry Point         — top-ranked chunk, full code
+ *   ## Direct Dependencies — signatures of functions called by the entry point (call graph depth-1)
+ *   ## Called By           — callers of the entry point (contract context)
+ *   ## Types & Interfaces  — interface/type chunks from the result set
+ *   ## Related Patterns    — remaining result chunks (signatures to save tokens)
+ *
+ * This layout reduces token usage by ~20-35% compared to the flat list and
+ * helps LLMs navigate the codebase more effectively because the relationships
+ * are explicit rather than implied by rank.
+ */
+function generateStructuredContextString(config, results, depGraph, callGraph, fileSummaries, projectOverview, options, _rootDir, allChunks, knowledgeEntries = []) {
+    const fmt = options.format ?? "markdown";
+    const hr = fmt === "markdown" ? "---" : "=".repeat(60);
+    const lines = [];
+    // ── Header ────────────────────────────────────────────────────────────────
+    lines.push(fmt === "markdown"
+        ? `# AI Context — ${config.projectName}`
+        : `=== AI CONTEXT BLOCK — ${config.projectName.toUpperCase()} ===`);
+    if (options.query) {
+        lines.push("");
+        lines.push(fmt === "markdown"
+            ? `> **Query:** ${options.query}`
+            : `Query: ${options.query}`);
+    }
+    lines.push("");
+    if (projectOverview) {
+        lines.push(fmt === "markdown" ? "## Project Overview" : "[Project Overview]");
+        lines.push("");
+        lines.push(projectOverview);
+        lines.push("");
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Section: Knowledge entries ────────────────────────────────────────────
+    const relevantKnowledge = rankKnowledgeEntries(options.query, results, knowledgeEntries);
+    if (relevantKnowledge.length > 0) {
+        lines.push(fmt === "markdown" ? "## Knowledge" : "[Knowledge]");
+        lines.push("");
+        for (const entry of relevantKnowledge) {
+            const badge = fmt === "markdown" ? `\`${entry.category}\`` : entry.category;
+            lines.push(fmt === "markdown"
+                ? `**${entry.title}** ${badge}`
+                : `${entry.title} [${entry.category}]`);
+            lines.push(entry.body);
+            if (entry.relatedFiles?.length) {
+                lines.push(fmt === "markdown"
+                    ? `_Files: ${entry.relatedFiles.map((f) => `\`${f}\``).join(", ")}_`
+                    : `Files: ${entry.relatedFiles.join(", ")}`);
+            }
+            lines.push("");
+        }
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Partition results ─────────────────────────────────────────────────────
+    const seen = new Set();
+    const dedupedResults = results.filter((r) => {
+        if (seen.has(r.chunk.id))
+            return false;
+        seen.add(r.chunk.id);
+        return true;
+    });
+    const topResult = dedupedResults[0];
+    const typeResults = dedupedResults
+        .slice(1)
+        .filter((r) => r.symbol?.type === "interface" || r.symbol?.type === "type");
+    const relatedResults = dedupedResults
+        .slice(1)
+        .filter((r) => r.symbol?.type !== "interface" && r.symbol?.type !== "type");
+    // ── Section 1: Entry Point ────────────────────────────────────────────────
+    lines.push(fmt === "markdown" ? "## Entry Point" : "[Entry Point]");
+    lines.push("");
+    {
+        const { chunk, score, symbol } = topResult;
+        const ext = chunk.file.split(".").pop() ?? "";
+        const symLabel = chunk.symbol
+            ? ` — ${symbol?.type ?? "symbol"} \`${chunk.symbol}\``
+            : "";
+        lines.push(fmt === "markdown"
+            ? `**\`${chunk.file}\`**${symLabel}`
+            : `${chunk.file}${symLabel}`);
+        lines.push(`Lines ${chunk.start}–${chunk.end} · Score: ${score.toFixed(4)}`);
+        lines.push("");
+        const codeLines = chunk.content.split("\n");
+        const limit = options.showCode ? codeLines.length : signature_1.HIGH_CODE_LINES;
+        const preview = codeLines.slice(0, limit).join("\n");
+        lines.push(fmt === "markdown" ? `\`\`\`${ext}` : "");
+        lines.push(preview);
+        if (codeLines.length > limit) {
+            lines.push(`// … (${codeLines.length - limit} more lines — use --show-code to expand)`);
+        }
+        if (fmt === "markdown")
+            lines.push("```");
+        lines.push("");
+    }
+    lines.push(hr);
+    lines.push("");
+    // ── Section 2: Direct Dependencies (call graph depth-1) ───────────────────
+    const topSymbolId = topResult.chunk.symbol
+        ? `${topResult.chunk.file}:${topResult.chunk.symbol}`
+        : null;
+    const callInfo = topSymbolId ? callGraph[topSymbolId] : null;
+    if (callInfo?.calls.length) {
+        lines.push(fmt === "markdown" ? "## Direct Dependencies" : "[Direct Dependencies]");
+        lines.push("");
+        let depCount = 0;
+        for (const call of callInfo.calls.slice(0, 8)) {
+            // Look up a matching chunk (prefer same file if provided)
+            const matching = allChunks.find((c) => c.symbol === call.name && (!call.file || c.file === call.file)) ?? allChunks.find((c) => c.symbol === call.name);
+            const chunkFile = matching?.file ?? call.file ?? "(external)";
+            const ext = chunkFile.split(".").pop() ?? "";
+            const sig = matching
+                ? (0, signature_1.extractSignature)(matching.content)
+                : `// ${call.name} — not found in index`;
+            lines.push(fmt === "markdown"
+                ? `**\`${chunkFile}\`** — \`${call.name}\``
+                : `${chunkFile} — ${call.name}`);
+            lines.push("");
+            lines.push(fmt === "markdown" ? `\`\`\`${ext}` : "");
+            lines.push(sig);
+            if (fmt === "markdown")
+                lines.push("```");
+            lines.push("");
+            depCount++;
+        }
+        const hiddenDeps = callInfo.calls.length - Math.min(callInfo.calls.length, 8);
+        if (hiddenDeps > 0) {
+            lines.push(fmt === "markdown"
+                ? `_…and ${hiddenDeps} more calls (see call graph)_`
+                : `...and ${hiddenDeps} more calls`);
+            lines.push("");
+        }
+        if (depCount > 0) {
+            lines.push(hr);
+            lines.push("");
+        }
+    }
+    // ── Section 3: Called By ──────────────────────────────────────────────────
+    if (callInfo?.calledBy.length) {
+        lines.push(fmt === "markdown" ? "## Called By" : "[Called By]");
+        lines.push("");
+        for (const callerId of callInfo.calledBy.slice(0, 6)) {
+            lines.push(fmt === "markdown" ? `- \`${callerId}\`` : `  - ${callerId}`);
+        }
+        if (callInfo.calledBy.length > 6) {
+            lines.push(fmt === "markdown"
+                ? `- _…and ${callInfo.calledBy.length - 6} more_`
+                : `  ...and ${callInfo.calledBy.length - 6} more`);
+        }
+        lines.push("");
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Section 4: Types & Interfaces ────────────────────────────────────────
+    if (typeResults.length > 0) {
+        lines.push(fmt === "markdown" ? "## Types & Interfaces" : "[Types & Interfaces]");
+        lines.push("");
+        for (const { chunk } of typeResults) {
+            const ext = chunk.file.split(".").pop() ?? "";
+            lines.push(fmt === "markdown"
+                ? `**\`${chunk.file}\`** — \`${chunk.symbol}\``
+                : `${chunk.file} — ${chunk.symbol}`);
+            lines.push("");
+            lines.push(fmt === "markdown" ? `\`\`\`${ext}` : "");
+            lines.push((0, signature_1.extractSignature)(chunk.content));
+            if (fmt === "markdown")
+                lines.push("```");
+            lines.push("");
+        }
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Section 5: Related Patterns ───────────────────────────────────────────
+    if (relatedResults.length > 0) {
+        lines.push(fmt === "markdown" ? "## Related Patterns" : "[Related Patterns]");
+        lines.push("");
+        for (const { chunk, score, symbol } of relatedResults) {
+            const ext = chunk.file.split(".").pop() ?? "";
+            const symLabel = chunk.symbol
+                ? ` — ${symbol?.type ?? "symbol"} \`${chunk.symbol}\``
+                : "";
+            lines.push(fmt === "markdown"
+                ? `### \`${chunk.file}\`${symLabel}`
+                : `${chunk.file}${symLabel}`);
+            lines.push(`Score: ${score.toFixed(4)}`);
+            lines.push("");
+            // Use signature to keep tokens low for secondary results
+            const display = chunk.symbol
+                ? (0, signature_1.extractSignature)(chunk.content)
+                : chunk.content.split("\n").slice(0, 10).join("\n") +
+                    (chunk.content.split("\n").length > 10 ? "\n// …" : "");
+            lines.push(fmt === "markdown" ? `\`\`\`${ext}` : "");
+            lines.push(display);
+            if (fmt === "markdown")
+                lines.push("```");
+            lines.push("");
+        }
+        lines.push(hr);
+        lines.push("");
+    }
+    // ── Footer ────────────────────────────────────────────────────────────────
+    lines.push(fmt === "markdown"
+        ? `_Generated by \`vemora context --structured\` — ${new Date().toISOString()}_`
+        : `=== END AI CONTEXT BLOCK — ${new Date().toISOString()} ===`);
+    return lines.join("\n");
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Resolve a file argument to a project-relative path.
+ *
+ * Accepts:
+ *   - Absolute paths                         → relativised against rootDir
+ *   - Paths already relative to rootDir      → used as-is if the file exists
+ *   - Paths relative to cwd                  → resolved to absolute, then relativised
+ */
+function resolveRelPath(rootDir, filePath) {
+    const resolvedRoot = path_1.default.resolve(rootDir);
+    let absPath;
+    if (path_1.default.isAbsolute(filePath)) {
+        absPath = filePath;
+    }
+    else {
+        // Try relative to rootDir first, then fall back to cwd
+        const fromRoot = path_1.default.join(resolvedRoot, filePath);
+        absPath = fs_1.default.existsSync(fromRoot)
+            ? fromRoot
+            : path_1.default.resolve(process.cwd(), filePath);
+    }
+    // Guard: reject paths that escape the project root (path traversal)
+    const normalised = path_1.default.resolve(absPath);
+    if (!normalised.startsWith(resolvedRoot + path_1.default.sep) &&
+        normalised !== resolvedRoot) {
+        throw new Error(`File path escapes project root: ${filePath}`);
+    }
+    return path_1.default.relative(resolvedRoot, normalised);
+}
+//# sourceMappingURL=context.js.map