project-librarian 0.2.1 → 0.4.0

package/dist/code-index-file-policy.js

@@ -33,20 +33,28 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maxIndexedBytes = exports.ignoredDirectories = void 0;
+exports.SMALL_REPO_FILE_THRESHOLD = exports.maxIndexedBytes = exports.ignoredDirectories = exports.codeEvidenceDirectory = void 0;
 exports.fileLanguage = fileLanguage;
 exports.isJavaScriptLike = isJavaScriptLike;
 exports.shouldIndexFile = shouldIndexFile;
 exports.isIgnoredCodePath = isIgnoredCodePath;
+exports.discoverCodeFiles = discoverCodeFiles;
+exports.smallRepoCodeIndexGate = smallRepoCodeIndexGate;
+const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const workspace_1 = require("./workspace");
+// Single source of truth for the disposable code-evidence directory name. Both
+// the heavy code-index module and the light bootstrap path (hooks.ts) key off
+// this; keeping it here avoids loading typescript/node:sqlite during bootstrap.
+exports.codeEvidenceDirectory = ".project-wiki";
 exports.ignoredDirectories = new Set([
     ".git",
     ".codex",
     ".claude",
     ".cursor",
     ".gemini",
-    ".project-wiki",
+    exports.codeEvidenceDirectory,
     "node_modules",
     ".next",
     "dist",
@@ -120,3 +128,98 @@ function isIgnoredCodePath(relativePath) {
         .filter(Boolean)
         .some((part) => exports.ignoredDirectories.has(part));
 }
+// Mirrors normalizeProjectRelative in code-index.ts for git ls-files output, but
+// throws instead of exiting so the light bootstrap path can use discovery too.
+// Git emits repo-relative paths, so the escape branch is unreachable for real
+// output; it stays as a loud guard, not a recovery path.
+function normalizeGitIndexedFile(input) {
+    const raw = input.trim() || ".";
+    const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(workspace_1.root, raw);
+    const rootResolved = path.resolve(workspace_1.root);
+    if (resolved !== rootResolved && !resolved.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`git-indexed file must stay inside the project root: ${input}`);
+    }
+    return (0, workspace_1.normalizePath)(path.relative(rootResolved, resolved)) || ".";
+}
+function walkCodeFiles(relativePath, files = []) {
+    if (isIgnoredCodePath(relativePath))
+        return files.sort();
+    const target = (0, workspace_1.abs)(relativePath);
+    if (!fs.existsSync(target))
+        return files;
+    const stat = fs.statSync(target);
+    if (stat.isFile()) {
+        if (stat.size <= exports.maxIndexedBytes && shouldIndexFile(relativePath))
+            files.push(relativePath);
+        return files.sort();
+    }
+    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+        const child = (0, workspace_1.normalizePath)(path.join(relativePath, entry.name));
+        if (entry.isDirectory()) {
+            if (!exports.ignoredDirectories.has(entry.name))
+                walkCodeFiles(child, files);
+        }
+        else if (entry.isFile() && shouldIndexFile(child)) {
+            const childStat = fs.statSync((0, workspace_1.abs)(child));
+            if (childStat.size <= exports.maxIndexedBytes)
+                files.push(child);
+        }
+    }
+    return files.sort();
+}
+function gitTrackedAndUnignoredFiles(scopes) {
+    try {
+        const output = childProcess.execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...scopes], {
+            cwd: workspace_1.root,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return output.toString("utf8").split("\0").filter(Boolean).map((file) => normalizeGitIndexedFile(file));
+    }
+    catch {
+        return null;
+    }
+}
+function discoverCodeFiles(scopes) {
+    const gitFiles = gitTrackedAndUnignoredFiles(scopes);
+    const candidates = gitFiles ?? scopes.flatMap((scope) => walkCodeFiles(scope));
+    return Array.from(new Set(candidates))
+        .filter((file) => !isIgnoredCodePath(file))
+        .filter((file) => fs.existsSync((0, workspace_1.abs)(file)))
+        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).isFile())
+        .filter((file) => shouldIndexFile(file))
+        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).size <= exports.maxIndexedBytes)
+        .sort();
+}
+// --- Scale-aware code-evidence gate ------------------------------------------
+//
+// Threshold in indexable files (the discoverCodeFiles count) below which the
+// code-evidence surfaces warn (--code-index) or skip by default (bootstrap MCP
+// auto-registration). Evidence: stageR1 real-corpus run, 2026-06-12
+// (benchmarks/reports/llm/stageR1-real.md) — the ~1.2k-file repo LOST every
+// measured question (impact_trace +116.9%, workspace_graph +106.5% cost-weighted
+// tokens vs direct reads) while the ~11.8k-file repo still lost the cheap
+// ownership lookup (+99.0%) and won only the expensive traversal questions
+// (impact_trace -27.7%, workspace_graph -2.6%); stage2d synthetic scales
+// (benchmarks/reports/llm/stage2d-codegraph.md) lost across the board. 5000 sits
+// between the two real measured points: an n=2 extrapolation (1.2k all-loss /
+// 11.8k partial win), explicitly subject to revision as more scales are measured.
+exports.SMALL_REPO_FILE_THRESHOLD = 5000;
+// Decision for the --code-index scale gate: below the threshold the build halts
+// with an evidence-citing warning unless the caller explicitly acknowledged the
+// measured cost. Consent is honored, never refused (2026-06-12 decision: defaults
+// follow the evidence, explicit requests get warning + consent).
+function smallRepoCodeIndexGate(indexableFileCount, acknowledged) {
+    if (acknowledged || indexableFileCount >= exports.SMALL_REPO_FILE_THRESHOLD)
+        return { proceed: true, warning: "" };
+    return {
+        proceed: false,
+        warning: [
+            `--code-index halted: ${indexableFileCount} indexable files is below the ${exports.SMALL_REPO_FILE_THRESHOLD}-file scale threshold.`,
+            "Measured evidence (real-corpus stageR1): on a ~1.2k-file repo the code-evidence track cost MORE on every measured question (impact_trace +116.9%, workspace_graph +106.5% cost-weighted tokens vs direct reads), and even on a ~11.8k-file repo ownership-style cheap lookups lost (+99.0%); only expensive traversal questions won there (impact_trace -27.7%).",
+            "Reports: benchmarks/reports/llm/stageR1-real.md and benchmarks/reports/llm/stage2d-codegraph.md in the project-librarian repo (threshold is an n=2 extrapolation, subject to revision).",
+            "Not measured, so not disproven: human-facing report value (--code-report) and answer accuracy/grounding value. This gate reflects measured LLM token cost only.",
+            "To build the index anyway, re-run with --acknowledge-small-repo.",
+        ].join("\n"),
+    };
+}

package/dist/code-index.js

@@ -33,17 +33,32 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeEvidenceIndexUnavailableError = exports.codeContextPackTruncationNotice = exports.codeContextPackCharCap = void 0;
+exports.codeIndexStaleness = codeIndexStaleness;
+exports.codeownerRules = codeownerRules;
+exports.matchedCodeownerRules = matchedCodeownerRules;
+exports.ownershipContext = ownershipContext;
+exports.ownershipInfo = ownershipInfo;
+exports.evidenceCoverage = evidenceCoverage;
+exports.workspaceSummary = workspaceSummary;
+exports.workspaceDependencyGraph = workspaceDependencyGraph;
+exports.codeReportMetadata = codeReportMetadata;
+exports.searchSymbols = searchSymbols;
+exports.codeImpact = codeImpact;
+exports.codeContextPack = codeContextPack;
+exports.codeIndexSnapshot = codeIndexSnapshot;
+exports.openCodeEvidenceDatabaseForServing = openCodeEvidenceDatabaseForServing;
 exports.runCodeIndexMode = runCodeIndexMode;
 exports.runCodeQueryMode = runCodeQueryMode;
 exports.runCodeReportMode = runCodeReportMode;
 exports.runCodeStatusMode = runCodeStatusMode;
 exports.runCodeFilesMode = runCodeFilesMode;
 exports.runCodeImpactMode = runCodeImpactMode;
+exports.runCodeContextPackMode = runCodeContextPackMode;
 exports.runCodeSearchSymbolMode = runCodeSearchSymbolMode;
 exports.isCodeEvidenceMode = isCodeEvidenceMode;
 exports.isCodeEvidenceModeFor = isCodeEvidenceModeFor;
 const crypto = __importStar(require("node:crypto"));
-const childProcess = __importStar(require("node:child_process"));
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const ts = __importStar(require("typescript"));
@@ -52,7 +67,8 @@ const code_index_db_1 = require("./code-index-db");
 const code_index_file_policy_1 = require("./code-index-file-policy");
 const code_index_sql_1 = require("./code-index-sql");
 const workspace_1 = require("./workspace");
-const codeEvidenceDirectory = ".project-wiki";
+exports.codeContextPackCharCap = 4000;
+exports.codeContextPackTruncationNotice = "[truncated - refine the query]";
 const codeIndexSchemaVersion = "3";
 const httpMethods = new Set(["all", "delete", "get", "patch", "post", "put"]);
 const treeSitterGrammarPackages = {
@@ -117,11 +133,11 @@ function normalizeProjectRelative(input, label) {
     return (0, workspace_1.normalizePath)(path.relative(rootResolved, resolved)) || ".";
 }
 function codeEvidenceDatabasePath() {
-    const raw = args_1.codeIndexOutput.trim() || `${codeEvidenceDirectory}/code-evidence.sqlite`;
+    const raw = args_1.codeIndexOutput.trim() || `${code_index_file_policy_1.codeEvidenceDirectory}/code-evidence.sqlite`;
     const absolutePath = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(workspace_1.root, raw);
-    const evidenceRoot = path.resolve(workspace_1.root, codeEvidenceDirectory);
+    const evidenceRoot = path.resolve(workspace_1.root, code_index_file_policy_1.codeEvidenceDirectory);
     if (absolutePath === evidenceRoot || !absolutePath.startsWith(`${evidenceRoot}${path.sep}`)) {
-        fail(`--code-index-out must stay inside ${codeEvidenceDirectory}/`);
+        fail(`--code-index-out must stay inside ${code_index_file_policy_1.codeEvidenceDirectory}/`);
     }
     return {
         absolutePath,
@@ -182,56 +198,6 @@ function extractionProfile(relativePath, parserMode) {
         return "config";
     return "inventory-only";
 }
-function walkCodeFiles(relativePath, files = []) {
-    if ((0, code_index_file_policy_1.isIgnoredCodePath)(relativePath))
-        return files.sort();
-    const target = (0, workspace_1.abs)(relativePath);
-    if (!fs.existsSync(target))
-        return files;
-    const stat = fs.statSync(target);
-    if (stat.isFile()) {
-        if (stat.size <= code_index_file_policy_1.maxIndexedBytes && (0, code_index_file_policy_1.shouldIndexFile)(relativePath))
-            files.push(relativePath);
-        return files.sort();
-    }
-    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
-        const child = (0, workspace_1.normalizePath)(path.join(relativePath, entry.name));
-        if (entry.isDirectory()) {
-            if (!code_index_file_policy_1.ignoredDirectories.has(entry.name))
-                walkCodeFiles(child, files);
-        }
-        else if (entry.isFile() && (0, code_index_file_policy_1.shouldIndexFile)(child)) {
-            const childStat = fs.statSync((0, workspace_1.abs)(child));
-            if (childStat.size <= code_index_file_policy_1.maxIndexedBytes)
-                files.push(child);
-        }
-    }
-    return files.sort();
-}
-function gitTrackedAndUnignoredFiles(scopes) {
-    try {
-        const output = childProcess.execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...scopes], {
-            cwd: workspace_1.root,
-            encoding: "buffer",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return output.toString("utf8").split("\0").filter(Boolean).map((file) => normalizeProjectRelative(file, "git-indexed file"));
-    }
-    catch {
-        return null;
-    }
-}
-function discoverCodeFiles(scopes) {
-    const gitFiles = gitTrackedAndUnignoredFiles(scopes);
-    const candidates = gitFiles ?? scopes.flatMap((scope) => walkCodeFiles(scope));
-    return Array.from(new Set(candidates))
-        .filter((file) => !(0, code_index_file_policy_1.isIgnoredCodePath)(file))
-        .filter((file) => fs.existsSync((0, workspace_1.abs)(file)))
-        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).isFile())
-        .filter((file) => (0, code_index_file_policy_1.shouldIndexFile)(file))
-        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).size <= code_index_file_policy_1.maxIndexedBytes)
-        .sort();
-}
 function readCodeFile(relativePath, parserMode = "default") {
     const text = fs.readFileSync((0, workspace_1.abs)(relativePath), "utf8");
     return {
@@ -1163,7 +1129,7 @@ function removeDatabaseFiles(databasePath) {
 function codeIndexStaleness(database) {
     const scopes = indexedScopes(database);
     const parserMode = indexedParserMode(database);
-    const current = new Map(discoverCodeFiles(scopes.length > 0 ? scopes : ["."]).map((file) => {
+    const current = new Map((0, code_index_file_policy_1.discoverCodeFiles)(scopes.length > 0 ? scopes : ["."]).map((file) => {
         const codeFile = readCodeFile(file, parserMode);
         return [codeFile.path, codeFile.hash];
     }));
@@ -1311,6 +1277,13 @@ function matchingCodeowners(filePath, rules) {
     const matches = rules.filter((rule) => codeownerPatternMatches(rule.pattern, filePath));
     return matches[matches.length - 1]?.owners ?? [];
 }
+// Return every CODEOWNERS rule that matches a path, in file order. The last entry
+// is the effective owner under last-match-wins; earlier entries are overridden.
+// Reuses the same matcher as matchingCodeowners so precedence answers stay
+// consistent with --code-report / --code-impact.
+function matchedCodeownerRules(filePath, rules) {
+    return rules.filter((rule) => codeownerPatternMatches(rule.pattern, filePath));
+}
 function ownershipContext() {
     return {
         codeownerRules: codeownerRules(),
@@ -1608,14 +1581,138 @@ function codeReportForRequestedSection(database) {
         data: codeReportSectionData(database, section),
     };
 }
+function escapeLikeTerm(term) {
+    return term.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+function containsLikePattern(term) {
+    return `%${escapeLikeTerm(term)}%`;
+}
+function prefixLikePattern(term) {
+    return `${escapeLikeTerm(term)}%`;
+}
+function ftsPrefixQuery(term) {
+    const tokens = Array.from(new Set(term.match(/[\p{L}\p{N}_]+/gu) ?? []));
+    return tokens.slice(0, 8).map((token) => `"${token.replace(/"/g, "\"\"")}"*`).join(" AND ");
+}
+function stringValue(row, key) {
+    const value = row[key];
+    return typeof value === "string" || typeof value === "number" ? String(value) : "";
+}
+function addRankedRow(rowsByKey, row, key, score) {
+    const current = rowsByKey.get(key);
+    if (!current || score > current.score)
+        rowsByKey.set(key, { row, score });
+}
+function rankedRows(rowsByKey, limit, stableKeys) {
+    return Array.from(rowsByKey.values())
+        .sort((left, right) => {
+        const scoreDelta = right.score - left.score;
+        if (scoreDelta !== 0)
+            return scoreDelta;
+        for (const key of stableKeys) {
+            const compared = stringValue(left.row, key).localeCompare(stringValue(right.row, key));
+            if (compared !== 0)
+                return compared;
+        }
+        return 0;
+    })
+        .slice(0, limit)
+        .map((ranked) => ranked.row);
+}
+function searchFiles(database, term, limit = 25) {
+    const normalized = term.trim();
+    if (!normalized)
+        return [];
+    const contains = containsLikePattern(normalized);
+    const prefix = prefixLikePattern(normalized);
+    const rowsByKey = new Map();
+    const exactRows = database.prepare("SELECT path, language, profile, lines, bytes FROM files WHERE path = ? ORDER BY path LIMIT ?").all(normalized, limit);
+    exactRows.forEach((row) => addRankedRow(rowsByKey, row, stringValue(row, "path"), 900));
+    const prefixRows = database.prepare("SELECT path, language, profile, lines, bytes FROM files WHERE path LIKE ? ESCAPE '\\' ORDER BY path LIMIT ?").all(prefix, limit);
+    prefixRows.forEach((row) => addRankedRow(rowsByKey, row, stringValue(row, "path"), 750));
+    const ftsQuery = ftsPrefixQuery(normalized);
+    if (ftsQuery) {
+        const ftsRows = database.prepare(`
+      SELECT files.path, files.language, files.profile, files.lines, files.bytes
+      FROM files_fts
+      JOIN files ON files.path = files_fts.path
+      WHERE files_fts MATCH ?
+      ORDER BY bm25(files_fts, 8.0, 1.0, 1.0, 0.25), files.path
+      LIMIT ?
+    `).all(ftsQuery, limit);
+        ftsRows.forEach((row, index) => addRankedRow(rowsByKey, row, stringValue(row, "path"), 650 - index));
+    }
+    const containsRows = database.prepare("SELECT path, language, profile, lines, bytes FROM files WHERE path LIKE ? ESCAPE '\\' ORDER BY path LIMIT ?").all(contains, limit);
+    containsRows.forEach((row) => addRankedRow(rowsByKey, row, stringValue(row, "path"), 500));
+    return rankedRows(rowsByKey, limit, ["path"]);
+}
+function symbolKey(row) {
+    return [
+        stringValue(row, "file_path"),
+        stringValue(row, "line"),
+        stringValue(row, "kind"),
+        stringValue(row, "name"),
+        stringValue(row, "signature"),
+    ].join("\u0000");
+}
+function searchSymbols(database, term, limit = 50) {
+    const normalized = term.trim();
+    if (!normalized)
+        return [];
+    const contains = containsLikePattern(normalized);
+    const prefix = prefixLikePattern(normalized);
+    const rowsByKey = new Map();
+    const exactRows = database.prepare(`
+    SELECT name, kind, file_path, line, signature
+    FROM symbols
+    WHERE name = ? OR signature = ?
+    ORDER BY file_path, line
+    LIMIT ?
+  `).all(normalized, normalized, limit);
+    exactRows.forEach((row) => addRankedRow(rowsByKey, row, symbolKey(row), 1000));
+    const prefixRows = database.prepare(`
+    SELECT name, kind, file_path, line, signature
+    FROM symbols
+    WHERE name LIKE ? ESCAPE '\\' OR signature LIKE ? ESCAPE '\\'
+    ORDER BY file_path, line
+    LIMIT ?
+  `).all(prefix, prefix, limit);
+    prefixRows.forEach((row) => addRankedRow(rowsByKey, row, symbolKey(row), 850));
+    const ftsQuery = ftsPrefixQuery(normalized);
+    if (ftsQuery) {
+        const ftsRows = database.prepare(`
+      SELECT symbols.name, symbols.kind, symbols.file_path, symbols.line, symbols.signature
+      FROM symbols_fts
+      JOIN symbols
+        ON symbols.name = symbols_fts.name
+       AND symbols.kind = symbols_fts.kind
+       AND symbols.file_path = symbols_fts.file_path
+       AND symbols.signature = symbols_fts.signature
+      WHERE symbols_fts MATCH ?
+      ORDER BY bm25(symbols_fts, 8.0, 1.0, 4.0, 2.0), symbols.file_path, symbols.line
+      LIMIT ?
+    `).all(ftsQuery, limit);
+        ftsRows.forEach((row, index) => addRankedRow(rowsByKey, row, symbolKey(row), 700 - index));
+    }
+    const containsRows = database.prepare(`
+    SELECT name, kind, file_path, line, signature
+    FROM symbols
+    WHERE name LIKE ? ESCAPE '\\' OR signature LIKE ? ESCAPE '\\' OR file_path LIKE ? ESCAPE '\\'
+    ORDER BY file_path, line
+    LIMIT ?
+  `).all(contains, contains, contains, limit);
+    containsRows.forEach((row) => addRankedRow(rowsByKey, row, symbolKey(row), 500));
+    return rankedRows(rowsByKey, limit, ["file_path", "line", "kind", "name", "signature"]);
+}
 function codeImpact(database, target) {
-    const like = `%${target}%`;
-    const fileMatches = database.prepare("SELECT path, language, profile, lines, bytes FROM files WHERE path LIKE ? ORDER BY path LIMIT 25").all(like);
-    const symbolMatches = database.prepare("SELECT name, kind, file_path, line, signature FROM symbols WHERE name LIKE ? OR signature LIKE ? OR file_path LIKE ? ORDER BY file_path, line LIMIT 50").all(like, like, like);
-    const routeMatches = database.prepare("SELECT method, route, file_path, line, handler FROM routes WHERE route LIKE ? OR handler LIKE ? OR file_path LIKE ? ORDER BY file_path, line LIMIT 50").all(like, like, like);
-    const importMatches = database.prepare("SELECT from_file, to_ref, imported, line, raw FROM imports WHERE from_file LIKE ? OR to_ref LIKE ? OR imported LIKE ? ORDER BY from_file, line LIMIT 75").all(like, like, like);
-    const outgoingEdges = database.prepare("SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE file_path LIKE ? OR source LIKE ? ORDER BY file_path, line LIMIT 100").all(like, like);
-    const incomingEdges = database.prepare("SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE target LIKE ? ORDER BY file_path, line LIMIT 100").all(like);
+    const normalized = target.trim();
+    const like = containsLikePattern(normalized);
+    const fileMatches = searchFiles(database, normalized, 25);
+    const symbolMatches = searchSymbols(database, normalized, 50);
+    const routeMatches = database.prepare("SELECT method, route, file_path, line, handler FROM routes WHERE route LIKE ? ESCAPE '\\' OR handler LIKE ? ESCAPE '\\' OR file_path LIKE ? ESCAPE '\\' ORDER BY file_path, line LIMIT 50").all(like, like, like);
+    const importMatches = database.prepare("SELECT from_file, to_ref, imported, line, raw FROM imports WHERE from_file LIKE ? ESCAPE '\\' OR to_ref LIKE ? ESCAPE '\\' OR imported LIKE ? ESCAPE '\\' ORDER BY from_file, line LIMIT 75").all(like, like, like);
+    const outgoingEdges = database.prepare("SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE file_path LIKE ? ESCAPE '\\' OR source LIKE ? ESCAPE '\\' ORDER BY file_path, line LIMIT 100").all(like, like);
+    const incomingEdges = database.prepare("SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE target LIKE ? ESCAPE '\\' ORDER BY file_path, line LIMIT 100").all(like);
     const routeTargets = routeMatches.map((row) => `${String(row.method)} ${String(row.route)}`);
     const routeEdges = routeTargets.length === 0 ? [] : database.prepare(`SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE source IN (${routeTargets.map(() => "?").join(", ")}) ORDER BY file_path, line LIMIT 100`).all(...routeTargets);
     const relatedFilePaths = Array.from(new Set([
@@ -1670,16 +1767,172 @@ function codeImpact(database, target) {
         })).sort((left, right) => right.files - left.files || left.owner.localeCompare(right.owner)),
     };
 }
+function sampleLines(items, limit, render) {
+    const lines = items.slice(0, limit).map(render);
+    if (items.length > limit)
+        lines.push(`  ...+${items.length - limit} more`);
+    return lines;
+}
+function pushBudgetedLine(lines, line) {
+    const candidate = [...lines, line].join("\n");
+    if (candidate.length > exports.codeContextPackCharCap)
+        return false;
+    lines.push(line);
+    return true;
+}
+function pushBudgetedSection(lines, title, items, limit, render) {
+    if (items.length === 0)
+        return;
+    if (!pushBudgetedLine(lines, title))
+        return;
+    for (const line of sampleLines(items, limit, render)) {
+        if (!pushBudgetedLine(lines, line)) {
+            pushBudgetedLine(lines, "  ...more omitted; refine the query");
+            return;
+        }
+    }
+}
+function finalizeCodeContextPack(body) {
+    if (body.length <= exports.codeContextPackCharCap)
+        return body;
+    const budget = exports.codeContextPackCharCap - exports.codeContextPackTruncationNotice.length - 1;
+    return `${body.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${exports.codeContextPackTruncationNotice}`;
+}
+function codeContextScaleLine(fileCount) {
+    return fileCount < code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD
+        ? `scale small (${fileCount} indexed files < ${code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD}); direct reads are usually cheaper for simple lookups`
+        : `scale large (${fileCount} indexed files >= ${code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD}); indexed traversal is useful for impact-style context`;
+}
+function structuralSignature(value) {
+    const signature = oneLine(String(value ?? ""));
+    const bodyStart = signature.indexOf("{");
+    return bodyStart >= 0 ? signature.slice(0, bodyStart).trimEnd() : signature;
+}
+function sortedUnique(values) {
+    return Array.from(new Set(values.filter(Boolean))).sort();
+}
+function codeContextPack(database, query) {
+    const normalized = query.trim();
+    if (!normalized)
+        return 'Code context pack: missing query; use --code-context-pack "path-or-symbol-or-route".';
+    const like = containsLikePattern(normalized);
+    const files = searchFiles(database, normalized, 12);
+    const symbols = searchSymbols(database, normalized, 20);
+    const routes = database.prepare("SELECT method, route, file_path, line, handler FROM routes WHERE route LIKE ? ESCAPE '\\' OR handler LIKE ? ESCAPE '\\' OR file_path LIKE ? ESCAPE '\\' ORDER BY file_path, line LIMIT 20").all(like, like, like);
+    const imports = database.prepare("SELECT from_file, to_ref, imported, line, raw FROM imports WHERE from_file LIKE ? ESCAPE '\\' OR to_ref LIKE ? ESCAPE '\\' OR imported LIKE ? ESCAPE '\\' ORDER BY from_file, line LIMIT 30").all(like, like, like);
+    const outgoingEdges = database.prepare("SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE file_path LIKE ? ESCAPE '\\' OR source LIKE ? ESCAPE '\\' OR evidence LIKE ? ESCAPE '\\' ORDER BY file_path, line LIMIT 30").all(like, like, like);
+    const incomingEdges = database.prepare("SELECT kind, source_kind, source, target_kind, target, file_path, line, evidence FROM edges WHERE target LIKE ? ESCAPE '\\' OR evidence LIKE ? ESCAPE '\\' ORDER BY file_path, line LIMIT 30").all(like, like);
+    const relatedFilePaths = sortedUnique([
+        ...files.map((row) => String(row.path ?? "")),
+        ...symbols.map((row) => String(row.file_path ?? "")),
+        ...routes.map((row) => String(row.file_path ?? "")),
+        ...imports.map((row) => String(row.from_file ?? "")),
+        ...outgoingEdges.map((row) => String(row.file_path ?? "")),
+        ...incomingEdges.map((row) => String(row.file_path ?? "")),
+    ]);
+    const ownership = ownershipContext();
+    const ownerRows = new Map();
+    for (const filePath of relatedFilePaths) {
+        const info = ownershipInfo(filePath, ownership);
+        const current = ownerRows.get(info.owner) ?? { files: 0, owner: info.owner, owner_source: info.owner_source, sample_files: [] };
+        current.files += 1;
+        if (current.sample_files.length < 4)
+            current.sample_files.push(filePath);
+        ownerRows.set(info.owner, current);
+    }
+    const owners = Array.from(ownerRows.values()).sort((left, right) => right.files - left.files || left.owner.localeCompare(right.owner));
+    const staleness = codeIndexStaleness(database);
+    const coverage = evidenceCoverage(database);
+    const staleLabel = staleness.stale
+        ? `STALE ${staleness.changed} changed, ${staleness.added} added, ${staleness.deleted} deleted`
+        : "fresh";
+    const lines = [
+        `Code context pack "${normalized}": ${files.length} file matches, ${symbols.length} symbols, ${routes.length} routes, ${imports.length} imports, ${incomingEdges.length} incoming / ${outgoingEdges.length} outgoing edges; index ${staleLabel}; ${codeContextScaleLine(Number(coverage.files ?? 0))}.`,
+        "Evidence is structural only: paths, lines, signatures, routes, imports, edges, and owners; no source snippets are included.",
+    ];
+    pushBudgetedSection(lines, "Files:", files, 8, (row) => `  file-match ${String(row.path)} (${String(row.language)}, ${String(row.profile)}, ${Number(row.lines ?? 0)} lines)`);
+    pushBudgetedSection(lines, "Symbols:", symbols, 12, (row) => `  symbol-match ${String(row.file_path)}:${String(row.line)} ${String(row.kind)} ${String(row.name)} - ${structuralSignature(row.signature)}`);
+    pushBudgetedSection(lines, "Routes:", routes, 8, (row) => `  route-match ${String(row.method)} ${String(row.route)} -> ${String(row.handler)} (${String(row.file_path)}:${String(row.line)})`);
+    pushBudgetedSection(lines, "Imports:", imports, 8, (row) => `  import-match ${String(row.from_file)}:${String(row.line)} -> ${String(row.to_ref)}${row.imported ? ` (${String(row.imported)})` : ""}`);
+    pushBudgetedSection(lines, "Incoming edges:", incomingEdges, 8, (row) => `  edge-in ${String(row.kind)} ${String(row.source)} -> ${String(row.target)} (${String(row.file_path)}:${String(row.line)})`);
+    pushBudgetedSection(lines, "Outgoing edges:", outgoingEdges, 8, (row) => `  edge-out ${String(row.kind)} ${String(row.source)} -> ${String(row.target)} (${String(row.file_path)}:${String(row.line)})`);
+    pushBudgetedSection(lines, "Owners:", owners, 6, (row) => `  owner ${row.owner} (${row.owner_source}, ${row.files} files): ${row.sample_files.join(", ")}`);
+    return finalizeCodeContextPack(lines.join("\n"));
+}
+function snapshotRows(database, sql) {
+    return database.prepare(sql).all().map((row) => {
+        const normalized = {};
+        for (const key of Object.keys(row).sort()) {
+            const value = row[key];
+            normalized[key] = typeof value === "string" || typeof value === "number" || value === null ? value : String(value);
+        }
+        return normalized;
+    });
+}
+function codeIndexSnapshot(database) {
+    return {
+        configs: snapshotRows(database, "SELECT file_path, line, key, value FROM configs ORDER BY file_path, line, key, value"),
+        edges: snapshotRows(database, "SELECT file_path, line, kind, source_kind, source, target_kind, target, evidence FROM edges ORDER BY file_path, line, kind, source, target, evidence"),
+        files: snapshotRows(database, "SELECT path, language, profile, kind, lines, bytes FROM files ORDER BY path"),
+        imports: snapshotRows(database, "SELECT from_file, line, to_ref, imported, raw FROM imports ORDER BY from_file, line, to_ref, imported, raw"),
+        routes: snapshotRows(database, "SELECT file_path, line, method, route, handler FROM routes ORDER BY file_path, line, method, route, handler"),
+        symbols: snapshotRows(database, "SELECT file_path, line, kind, name, signature FROM symbols ORDER BY file_path, line, kind, name, signature"),
+    };
+}
+// Error thrown when the code-evidence index is missing or schema-incompatible.
+// The MCP server catches this to return an isError tool result (tools/list still
+// works); CLI modes keep their own process.exit path via requireExistingIndex.
+class CodeEvidenceIndexUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CodeEvidenceIndexUnavailableError";
+    }
+}
+exports.CodeEvidenceIndexUnavailableError = CodeEvidenceIndexUnavailableError;
+// Open the existing .project-wiki code-evidence index READ-ONLY for serving:
+// validates existence and schema version, then pins PRAGMA query_only = ON. Uses
+// the same path resolution and schema constant as the indexer so the server and
+// the writer share one contract. Throws CodeEvidenceIndexUnavailableError (never
+// exits) so the MCP server can answer with guidance to run --code-index.
+function openCodeEvidenceDatabaseForServing() {
+    const databasePath = codeEvidenceDatabasePath();
+    if (!fs.existsSync(databasePath.absolutePath)) {
+        throw new CodeEvidenceIndexUnavailableError(`missing code evidence index: ${databasePath.relativePath}; run \`project-librarian --code-index\` first`);
+    }
+    const database = openDatabase(databasePath.absolutePath);
+    let schemaVersion = "";
+    try {
+        schemaVersion = readMetaValue(database, "schema_version");
+    }
+    catch (error) {
+        database.close();
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CodeEvidenceIndexUnavailableError(`code evidence index at ${databasePath.relativePath} is not readable; rebuild with \`project-librarian --code-index\`. Error: ${message}`);
+    }
+    if (schemaVersion !== codeIndexSchemaVersion) {
+        database.close();
+        throw new CodeEvidenceIndexUnavailableError(`code evidence index schema version ${schemaVersion || "(missing)"} is incompatible with ${codeIndexSchemaVersion}; rebuild with \`project-librarian --code-index\``);
+    }
+    database.exec("PRAGMA query_only = ON");
+    return { database, relativePath: databasePath.relativePath };
+}
 function prepareOutputPath() {
     const databasePath = codeEvidenceDatabasePath();
     (0, workspace_1.mkdirp)(path.dirname(databasePath.relativePath));
-    (0, workspace_1.mkdirp)(codeEvidenceDirectory);
-    fs.writeFileSync((0, workspace_1.abs)(`${codeEvidenceDirectory}/.gitignore`), "*\n!.gitignore\n");
+    (0, workspace_1.mkdirp)(code_index_file_policy_1.codeEvidenceDirectory);
+    fs.writeFileSync((0, workspace_1.abs)(`${code_index_file_policy_1.codeEvidenceDirectory}/.gitignore`), "*\n!.gitignore\n");
 }
 function runCodeIndexMode() {
     const databasePath = codeEvidenceDatabasePath();
     const scopes = codeScopes();
     const parserMode = selectedCodeParserMode();
+    // Scale gate before ANY write or database work: below the measured threshold
+    // the build halts with the evidence-citing warning unless --acknowledge-small-repo
+    // was passed (2026-06-12 scale-aware guidance decision).
+    const discoveredFiles = (0, code_index_file_policy_1.discoverCodeFiles)(scopes);
+    const scaleGate = (0, code_index_file_policy_1.smallRepoCodeIndexGate)(discoveredFiles.length, args_1.acknowledgeSmallRepoMode);
+    if (!scaleGate.proceed)
+        fail(scaleGate.warning);
     const existingIndex = fs.existsSync(databasePath.absolutePath);
     if (args_1.codeIndexIncrementalMode && !existingIndex) {
         fail(`--incremental requires an existing compatible code evidence index: ${databasePath.relativePath}`);
@@ -1706,7 +1959,7 @@ function runCodeIndexMode() {
         if (!incremental)
             setupDatabase(database);
         const statements = createIndexStatements(database);
-        const currentFiles = discoverCodeFiles(scopes).map((filePath) => readCodeFile(filePath, parserMode));
+        const currentFiles = discoveredFiles.map((filePath) => readCodeFile(filePath, parserMode));
         const currentByPath = new Map(currentFiles.map((file) => [file.path, file]));
         const indexed = incremental ? new Map(database.prepare("SELECT path, hash FROM files").all().map((row) => [String(row.path), String(row.hash)])) : new Map();
         const deletedPaths = incremental ? Array.from(indexed.keys()).filter((filePath) => !currentByPath.has(filePath)) : [];
@@ -1826,6 +2079,21 @@ function runCodeImpactMode() {
         database.close();
     }
 }
+function runCodeContextPackMode() {
+    if (!args_1.codeContextPackTarget.trim()) {
+        console.error("missing context pack query: use --code-context-pack \"path-or-symbol-or-route\"");
+        process.exit(1);
+    }
+    requireExistingIndex();
+    const database = openDatabase(codeEvidenceDatabasePath().absolutePath);
+    try {
+        warnIfCodeIndexStale(database);
+        console.log(codeContextPack(database, args_1.codeContextPackTarget.trim()));
+    }
+    finally {
+        database.close();
+    }
+}
 function runCodeSearchSymbolMode() {
     if (!args_1.codeSearchSymbol.trim()) {
         console.error("missing symbol search term: use --code-search-symbol \"term\"");
@@ -1835,18 +2103,18 @@ function runCodeSearchSymbolMode() {
     const database = openDatabase(codeEvidenceDatabasePath().absolutePath);
     try {
         warnIfCodeIndexStale(database);
-        const like = `%${args_1.codeSearchSymbol}%`;
-        printRows(database.prepare("SELECT name, kind, file_path, line, signature FROM symbols WHERE name LIKE ? OR signature LIKE ? ORDER BY file_path, line LIMIT 50").all(like, like));
+        printRows(searchSymbols(database, args_1.codeSearchSymbol.trim()));
     }
     finally {
         database.close();
     }
 }
 function isCodeEvidenceMode() {
-    return isCodeEvidenceModeFor({ codeFilesMode: args_1.codeFilesMode, codeImpactMode: args_1.codeImpactMode, codeIndexMode: args_1.codeIndexMode, codeQuerySql: args_1.codeQuerySql, codeReportMode: args_1.codeReportMode, codeSearchSymbol: args_1.codeSearchSymbol, codeStatusMode: args_1.codeStatusMode });
+    return isCodeEvidenceModeFor({ codeContextPackTarget: args_1.codeContextPackTarget, codeFilesMode: args_1.codeFilesMode, codeImpactMode: args_1.codeImpactMode, codeIndexMode: args_1.codeIndexMode, codeQuerySql: args_1.codeQuerySql, codeReportMode: args_1.codeReportMode, codeSearchSymbol: args_1.codeSearchSymbol, codeStatusMode: args_1.codeStatusMode });
 }
 function isCodeEvidenceModeFor(flags) {
-    return flags.codeIndexMode
+    return Boolean(flags.codeContextPackTarget)
+        || flags.codeIndexMode
         || Boolean(flags.codeQuerySql)
         || flags.codeReportMode
         || flags.codeStatusMode