token-goat 2.8.4 → 2.9.1

package/dist/{token-goat-chunk-RE7S7H26.mjs → token-goat-chunk-SXSWQMNP.mjs}

@@ -23,10 +23,13 @@ import {
   extractPdfMeta,
   extractPdfOutline,
   extractPdfText,
+  fenceUntrusted,
   fenceUntrustedContent,
   formatCsvProfile,
   formatCsvTable,
+  getEmbeddingCoverage,
   getFileEntry,
+  getTrackedFiles,
   indexFileSync,
   isAvailable,
   isBlobStale,
@@ -49,7 +52,7 @@ import {
   queryRefs,
   queryRefsByContext,
   querySymbols,
-  scanForInjectionPatterns,
+  scanAndRecord,
   searchEvidenceSemantically,
   searchSemantic,
   searchSymbolsFts,
@@ -64,7 +67,7 @@ import {
   walkProject,
   yamlLineClosesQuote,
   yamlOpenQuoteAfter
-} from "./token-goat-chunk-4OTIB7SB.mjs";
+} from "./token-goat-chunk-FDXINYK4.mjs";
 import {
   Database,
   PER_FILE_COUNTERFACTUAL_CEILING,
@@ -118,36 +121,11 @@ import {
   unsupportedLanguageName,
   windowsCmdQuoteArg,
   withExtension
-} from "./token-goat-chunk-E76UNTVK.mjs";
+} from "./token-goat-chunk-4ZDRTNGV.mjs";
 import {
   registerReset
 } from "./token-goat-chunk-AO2QD2AG.mjs";
 
-// src/repomap.ts
-import * as fs from "fs";
-import * as path from "path";
-function getTrackedFiles(cwd = process.cwd()) {
-  try {
-    let dir = cwd;
-    let onlyFile = "";
-    try {
-      if (fs.statSync(cwd).isFile()) {
-        dir = path.dirname(cwd);
-        onlyFile = path.basename(cwd);
-      }
-    } catch {
-    }
-    const args = onlyFile === "" ? ["ls-files"] : ["ls-files", "--error-unmatch", "--", onlyFile];
-    const result = runGit(args, { cwd: dir });
-    if (result.exitCode !== 0 || !result.stdout) {
-      return [];
-    }
-    return result.stdout.split("\n").filter((line) => line.trim().length > 0).map((rel) => path.join(dir, rel));
-  } catch {
-    return [];
-  }
-}
-
 // src/section_reader.ts
 import { readFileSync } from "node:fs";
 function parseHeadingSpec(spec, headers) {
@@ -475,8 +453,8 @@ import { execFileSync, spawnSync as spawnSync2 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 
 // src/read_commands.ts
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs4 from "node:fs";
+import * as path4 from "node:path";
 
 // src/json_query.ts
 function jsonType(value) {
@@ -3442,11 +3420,11 @@ var CHOMPING_STRIP = CHOMPING_MODE.STRIP;
 var CHOMPING_KEEP = CHOMPING_MODE.KEEP;
 
 // src/openapi_query.ts
-import * as path2 from "node:path";
+import * as path from "node:path";
 var HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
 function parseOpenApiSpec(text, filePath) {
   text = stripBom(text);
-  const ext = path2.extname(filePath).toLowerCase();
+  const ext = path.extname(filePath).toLowerCase();
   if (ext === ".yaml" || ext === ".yml") return load(text);
   if (ext === ".json") return JSON.parse(text);
   try {
@@ -3800,24 +3778,24 @@ ${c.body}`).join("\n\n");
 }
 
 // src/sqlite_query.ts
-import * as fs2 from "node:fs";
+import * as fs from "node:fs";
 var SQLITE_QUERY_ROW_CAP = 5e3;
 var SQLITE_MAGIC = Buffer.from([83, 81, 76, 105, 116, 101, 32, 102, 111, 114, 109, 97, 116, 32, 51, 0]);
 function readMagicBytes(filePath) {
   let fd;
   try {
-    fd = fs2.openSync(filePath, "r");
+    fd = fs.openSync(filePath, "r");
   } catch {
     return null;
   }
   try {
     const buf = Buffer.alloc(SQLITE_MAGIC.length);
-    const bytesRead = fs2.readSync(fd, buf, 0, buf.length, 0);
+    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
     return bytesRead === buf.length ? buf : null;
   } catch {
     return null;
   } finally {
-    fs2.closeSync(fd);
+    fs.closeSync(fd);
   }
 }
 function isSqliteFile(filePath) {
@@ -3825,7 +3803,7 @@ function isSqliteFile(filePath) {
   return magic !== null && magic.equals(SQLITE_MAGIC);
 }
 function openReadonlySqlite(filePath) {
-  if (!fs2.existsSync(filePath)) {
+  if (!fs.existsSync(filePath)) {
     throw new Error(`file not found: ${filePath}`);
   }
   if (!isSqliteFile(filePath)) {
@@ -4528,8 +4506,8 @@ function formatConflictSummaries(summaries) {
 
 // src/screenshot.ts
 import dns from "node:dns/promises";
-import fs3 from "node:fs";
-import path3 from "node:path";
+import fs2 from "node:fs";
+import path2 from "node:path";
 var loadPuppeteer = createLazyModuleLoader(
   async () => await import("puppeteer-core"),
   "screenshot disabled (puppeteer-core unavailable)"
@@ -4538,7 +4516,7 @@ var PLAYWRIGHT_CHROME_SUBDIRS = ["chrome-win64", "chrome-win"];
 function findPlaywrightChromium(msPlaywrightDir) {
   let entries;
   try {
-    entries = fs3.readdirSync(msPlaywrightDir);
+    entries = fs2.readdirSync(msPlaywrightDir);
   } catch {
     return [];
   }
@@ -4546,7 +4524,7 @@ function findPlaywrightChromium(msPlaywrightDir) {
   const candidates = [];
   for (const m of versioned) {
     for (const sub of PLAYWRIGHT_CHROME_SUBDIRS) {
-      candidates.push(path3.join(msPlaywrightDir, m[0], sub, "chrome.exe"));
+      candidates.push(path2.join(msPlaywrightDir, m[0], sub, "chrome.exe"));
     }
   }
   return candidates;
@@ -4557,33 +4535,33 @@ function platformCandidatePaths() {
     const programFiles = process.env["PROGRAMFILES"];
     const programFilesX86 = process.env["PROGRAMFILES(X86)"];
     const localAppData = process.env["LOCALAPPDATA"];
-    if (programFiles) candidates2.push(path3.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"));
-    if (programFilesX86) candidates2.push(path3.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"));
+    if (programFiles) candidates2.push(path2.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"));
+    if (programFilesX86) candidates2.push(path2.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"));
     if (localAppData) {
-      candidates2.push(path3.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"));
-      candidates2.push(...findPlaywrightChromium(path3.join(localAppData, "ms-playwright")));
+      candidates2.push(path2.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"));
+      candidates2.push(...findPlaywrightChromium(path2.join(localAppData, "ms-playwright")));
     }
     return candidates2;
   }
   if (process.platform === "darwin") {
     const home2 = process.env["HOME"];
     const candidates2 = ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"];
-    if (home2) candidates2.push(...findPlaywrightChromium(path3.join(home2, "Library", "Caches", "ms-playwright")));
+    if (home2) candidates2.push(...findPlaywrightChromium(path2.join(home2, "Library", "Caches", "ms-playwright")));
     return candidates2;
   }
   const home = process.env["HOME"];
   const candidates = ["/usr/bin/google-chrome-stable", "/usr/bin/google-chrome", "/usr/bin/chromium-browser", "/usr/bin/chromium"];
-  if (home) candidates.push(...findPlaywrightChromium(path3.join(home, ".cache", "ms-playwright")));
+  if (home) candidates.push(...findPlaywrightChromium(path2.join(home, ".cache", "ms-playwright")));
   return candidates;
 }
 function resolveBrowserExecutablePath(explicit) {
-  if (explicit && fs3.existsSync(explicit)) return explicit;
+  if (explicit && fs2.existsSync(explicit)) return explicit;
   const cfgPath = loadConfig().screenshot.chrome_path;
-  if (cfgPath && fs3.existsSync(cfgPath)) return cfgPath;
+  if (cfgPath && fs2.existsSync(cfgPath)) return cfgPath;
   const envPath = process.env["TOKEN_GOAT_CHROME_PATH"];
-  if (envPath && fs3.existsSync(envPath)) return envPath;
+  if (envPath && fs2.existsSync(envPath)) return envPath;
   for (const candidate of platformCandidatePaths()) {
-    if (fs3.existsSync(candidate)) return candidate;
+    if (fs2.existsSync(candidate)) return candidate;
   }
   return null;
 }
@@ -4890,7 +4868,7 @@ async function takeScreenshot(url, destPath, opts) {
 }
 
 // src/notes.ts
-import * as fs4 from "node:fs";
+import * as fs3 from "node:fs";
 var WHOLE_FILE_NOTE_SYMBOL = "";
 function toNoteRow(row) {
   return {
@@ -4915,7 +4893,7 @@ function resolveSymbolMatch(filePath, symbolName, dbPath = globalDbPath()) {
 }
 function bodyFromSource(entry) {
   try {
-    return fs4.readFileSync(entry.filePath, "utf8").split(/\r?\n/).slice(Math.max(0, entry.lineStart - 1), entry.lineEnd).join("\n");
+    return fs3.readFileSync(entry.filePath, "utf8").split(/\r?\n/).slice(Math.max(0, entry.lineStart - 1), entry.lineEnd).join("\n");
   } catch {
     return "";
   }
@@ -4966,7 +4944,7 @@ function isNoteStale(note, dbPath = globalDbPath()) {
 
 // src/ts_refs.ts
 import { createRequire } from "node:module";
-import * as path4 from "node:path";
+import * as path3 from "node:path";
 var _require = createRequire(import.meta.url);
 var MAX_CANDIDATE_FILES = 50;
 var _ts = null;
@@ -4997,7 +4975,7 @@ registerReset(() => {
 var TS_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts"]);
 var TS_JS_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
 function isTsPath(filePath) {
-  return TS_EXTENSIONS.has(path4.extname(filePath).toLowerCase());
+  return TS_EXTENSIONS.has(path3.extname(filePath).toLowerCase());
 }
 function resolveTypedRefs(input) {
   const ts = loadTs();
@@ -5027,7 +5005,7 @@ function resolveTypedRefs(input) {
   if (defSymbol === null) return null;
   const out = [];
   for (const ref of input.candidates) {
-    if (!TS_JS_EXTENSIONS.has(path4.extname(ref.filePath).toLowerCase())) {
+    if (!TS_JS_EXTENSIONS.has(path3.extname(ref.filePath).toLowerCase())) {
       out.push(ref);
       continue;
     }
@@ -5053,12 +5031,12 @@ function buildScopedProgram(ts, rootNames, searchFrom) {
     resolveJsonModule: true,
     esModuleInterop: true
   };
-  const configPath = ts.findConfigFile(path4.dirname(searchFrom), ts.sys.fileExists, "tsconfig.json");
+  const configPath = ts.findConfigFile(path3.dirname(searchFrom), ts.sys.fileExists, "tsconfig.json");
   if (configPath !== void 0) {
     try {
       const raw = ts.readConfigFile(configPath, ts.sys.readFile);
       if (raw.error === void 0) {
-        const parsed = ts.parseJsonConfigFileContent(raw.config, ts.sys, path4.dirname(configPath));
+        const parsed = ts.parseJsonConfigFileContent(raw.config, ts.sys, path3.dirname(configPath));
         Object.assign(options, parsed.options);
       }
     } catch {
@@ -5162,7 +5140,7 @@ var STRUCTURED_MISS_MAX_NODES = 2e4;
 var REFS_TOP_SCAN_LIMIT = 2e4;
 function fileExists(p) {
   try {
-    fs5.statSync(p);
+    fs4.statSync(p);
     return true;
   } catch {
     return false;
@@ -5193,30 +5171,30 @@ function withPinnedReads(pins, fn) {
   }
 }
 function readPinnedBytes(p, pinned) {
-  const fd = fs5.openSync(p, fs5.constants.O_RDONLY);
+  const fd = fs4.openSync(p, fs4.constants.O_RDONLY);
   try {
-    const actual = fileIdentity(fs5.fstatSync(fd, { bigint: true }));
+    const actual = fileIdentity(fs4.fstatSync(fd, { bigint: true }));
     if (actual !== pinned) {
       throw new ConfinementIdentityError(
         `refused: "${p}" changed identity between validation and read (validated ${pinned}, opened ${actual}). The file was replaced or redirected after the confinement check, so the read was not performed.`
       );
     }
-    return fs5.readFileSync(fd);
+    return fs4.readFileSync(fd);
   } finally {
-    fs5.closeSync(fd);
+    fs4.closeSync(fd);
   }
 }
 function verifyPinnedIdentity(p, pinned) {
-  const fd = fs5.openSync(p, fs5.constants.O_RDONLY);
+  const fd = fs4.openSync(p, fs4.constants.O_RDONLY);
   try {
-    const actual = fileIdentity(fs5.fstatSync(fd, { bigint: true }));
+    const actual = fileIdentity(fs4.fstatSync(fd, { bigint: true }));
     if (actual !== pinned) {
       throw new ConfinementIdentityError(
         `refused: "${p}" changed identity between validation and read (validated ${pinned}, opened ${actual}). The file was replaced or redirected after the confinement check, so the read was not performed.`
       );
     }
   } finally {
-    fs5.closeSync(fd);
+    fs4.closeSync(fd);
   }
 }
 function verifyStillAbsent(p) {
@@ -5234,7 +5212,7 @@ function verifyPin(p, pinned) {
   verifyPinnedIdentity(p, pinned);
 }
 function indexFileSyncPinned(resolvedPath, dbPath) {
-  const pinned = activePins?.get(pinKey(path5.resolve(resolvedPath)));
+  const pinned = activePins?.get(pinKey(path4.resolve(resolvedPath)));
   if (pinned === void 0) {
     indexFileSync(resolvedPath, dbPath);
     return;
@@ -5256,21 +5234,21 @@ function indexFileSyncPinned(resolvedPath, dbPath) {
   indexFileSync(resolvedPath, dbPath, bytes);
 }
 function readFileText(p) {
-  const pinned = activePins?.get(pinKey(path5.resolve(p)));
+  const pinned = activePins?.get(pinKey(path4.resolve(p)));
   try {
     if (pinned === ABSENT_PIN) {
       verifyStillAbsent(p);
       return null;
     }
     if (pinned !== void 0) return redactIfDotenv(p, decodeSource(readPinnedBytes(p, pinned)));
-    return redactIfDotenv(p, decodeSource(fs5.readFileSync(p)));
+    return redactIfDotenv(p, decodeSource(fs4.readFileSync(p)));
   } catch (err) {
     if (err instanceof ConfinementIdentityError) throw err;
     return null;
   }
 }
 function readFileBytes(p) {
-  const pinned = activePins?.get(pinKey(path5.resolve(p)));
+  const pinned = activePins?.get(pinKey(path4.resolve(p)));
   try {
     if (pinned === ABSENT_PIN) {
       verifyStillAbsent(p);
@@ -5281,9 +5259,9 @@ function readFileBytes(p) {
       if (bytes.length > MAX_ZIP_INPUT_BYTES) throw new ZipInputTooLargeError(p, bytes.length, MAX_ZIP_INPUT_BYTES);
       return bytes;
     }
-    const stat = fs5.statSync(p);
+    const stat = fs4.statSync(p);
     if (stat.size > MAX_ZIP_INPUT_BYTES) throw new ZipInputTooLargeError(p, stat.size, MAX_ZIP_INPUT_BYTES);
-    return fs5.readFileSync(p);
+    return fs4.readFileSync(p);
   } catch (err) {
     if (err instanceof ConfinementIdentityError || err instanceof ZipInputTooLargeError) throw err;
     return null;
@@ -5302,7 +5280,7 @@ var STALE_WARNING = "\u26A0 STALE: index is older than the file on disk (worker
 var DELETED_WARNING = "\u26A0 DELETED: this file is no longer on disk \u2014 what follows is what the index last saw of it";
 var DELETED_TAG = "\u26A0 DELETED: file no longer on disk";
 function fileIsGone(absPath) {
-  if (!path5.isAbsolute(absPath)) return false;
+  if (!path4.isAbsolute(absPath)) return false;
   return fileIsAbsent(absPath);
 }
 function staleWarning(resolvedPath) {
@@ -5353,15 +5331,12 @@ function guardText(text, command) {
   const cfg = loadConfig();
   return cfg.overflow_guard.enabled ? trimToBudget(text, cfg.overflow_guard.max_tokens, command) : text;
 }
-function fenceGithubTextIfMatched(text) {
-  let matches = [];
-  try {
-    if (loadConfig().injection.enabled) matches = scanForInjectionPatterns(text);
-  } catch {
-    matches = [];
-  }
+function fenceGithubText(text) {
+  return fenceUntrusted(text, UNTRUSTED_GITHUB_TAG);
+}
+function fenceGithubFieldIfMatched(text) {
+  const matches = scanAndRecord(text);
   if (matches.length === 0) return text;
-  recordStat("injection_detected", 0, 0, void 0, matches.join(","));
   return fenceUntrustedContent(text, matches, UNTRUSTED_GITHUB_TAG);
 }
 function guardJsonRows(items) {
@@ -5373,12 +5348,18 @@ function sumFileSizes(filePaths) {
   let total = 0;
   for (const fp of new Set(filePaths)) {
     try {
-      total += Math.min(fs5.statSync(fp).size, PER_FILE_COUNTERFACTUAL_CEILING);
+      total += Math.min(fs4.statSync(fp).size, PER_FILE_COUNTERFACTUAL_CEILING);
     } catch {
     }
   }
   return total;
 }
+function refsSearchBaselineBytes(rows) {
+  let total = 0;
+  for (const ref of rows) total += Buffer.byteLength(`${refsDisplayPath(ref.filePath)}:${ref.line}: ${ref.context}
+`, "utf8");
+  return total;
+}
 function recordReadStat(kind, fullSourceBytes, emittedText, detail) {
   const emittedBytes = Buffer.byteLength(emittedText, "utf8");
   const bytesSaved = Math.max(1, fullSourceBytes - emittedBytes);
@@ -5551,7 +5532,7 @@ function findStructuredKeyPath(name, filePaths) {
     if (!isYaml && !lower.endsWith(".json")) continue;
     let size;
     try {
-      size = fs5.statSync(filePath).size;
+      size = fs4.statSync(filePath).size;
     } catch {
       continue;
     }
@@ -6089,7 +6070,7 @@ ${sub.text}`);
   return { text, code: 1 };
 }
 function resolveAgainstProjectRoot(file, projectRoot) {
-  return projectRoot !== void 0 && !path5.isAbsolute(file) ? path5.resolve(projectRoot, file) : file;
+  return projectRoot !== void 0 && !path4.isAbsolute(file) ? path4.resolve(projectRoot, file) : file;
 }
 function literalHeadingExists(filePath, heading) {
   const ordinalMatch = /^([^#\r\n]+)#(\d+)$/.exec(heading);
@@ -6113,7 +6094,7 @@ function runSection(opts) {
   }
   const result = readSection(filePath, heading, readFileText);
   if (result === null) {
-    if (!fs5.existsSync(filePath)) {
+    if (!fs4.existsSync(filePath)) {
       return { text: `File not found: '${filePath}'`, code: 1 };
     }
     const ordSpec = /^(.*?)#(\d+)$/.exec(heading);
@@ -6200,7 +6181,7 @@ function runSectionCrossFile(pairs, opts) {
     textBlocks.push(`${key}:
 ${sub.text}`);
   }
-  const resolvePath = (f) => opts.projectRoot !== void 0 && !path5.isAbsolute(f) ? path5.resolve(opts.projectRoot, f) : f;
+  const resolvePath = (f) => opts.projectRoot !== void 0 && !path4.isAbsolute(f) ? path4.resolve(opts.projectRoot, f) : f;
   const text = opts.json === true ? JSON.stringify(jsonOut, null, 2) : textBlocks.join("\n\n");
   if (anyFound) {
     const fullSourceBytes = sumFileSizes(Array.from(distinctFiles, resolvePath));
@@ -6273,7 +6254,7 @@ function renderRefsTargets(targets, opts, {
   const jsonOut = {};
   let anyFound = false;
   const lines = [];
-  const refFilePaths = [];
+  const refRows = [];
   for (const { file, symbol, key } of targets) {
     const queryOpts = { name: symbol };
     if (opts.excludeTests === true || opts.grep !== void 0) queryOpts.limit = REFS_TOP_SCAN_LIMIT;
@@ -6299,7 +6280,7 @@ function renderRefsTargets(targets, opts, {
       results = results.slice(0, opts.limit ?? 100);
     }
     if (results.length > 0) anyFound = true;
-    refFilePaths.push(...results.map((r) => r.filePath));
+    refRows.push(...results);
     if (opts.json === true) {
       const hiddenByGrep = matchesGrep !== void 0 ? preGrepCount - (filteredTotal ?? results.length) : 0;
       const withHidden = (payload) => ({ ...payload, ...annotateHiddenByGrep && hiddenByGrep > 0 ? { hiddenByGrep } : {} });
@@ -6341,7 +6322,7 @@ function renderRefsTargets(targets, opts, {
       if (notice !== null) lines.push(`  token-goat: ${notice}`);
     }
   }
-  const fullSourceBytes = sumFileSizes(refFilePaths);
+  const fullSourceBytes = refsSearchBaselineBytes(refRows);
   if (opts.json === true) {
     const text2 = JSON.stringify(jsonOut, null, 2);
     emit(text2);
@@ -6450,7 +6431,7 @@ function runRefsSingle(opts) {
     }
     return 1;
   }
-  const fullSourceBytes = sumFileSizes(results.map((r) => r.filePath));
+  const fullSourceBytes = refsSearchBaselineBytes(results);
   if (opts.json === true) {
     let payload;
     if (opts.top !== void 0) {
@@ -6523,7 +6504,7 @@ function renderCallerGroups(refs, contextLines = 0) {
   return lines;
 }
 function noSymbolsMessage(displayPath, resolvedPath) {
-  if (!fs5.existsSync(resolvedPath)) {
+  if (!fs4.existsSync(resolvedPath)) {
     return `Could not read: ${displayPath}`;
   }
   const lang = unsupportedLanguageName(resolvedPath);
@@ -7217,11 +7198,11 @@ function runPrSlice(opts) {
         }
         const fullSourceBytes = Buffer.byteLength(diffText, "utf8");
         if (opts.json === true) {
-          const jsonText = JSON.stringify({ path: parsed.path, diff: fenceGithubTextIfMatched(fileDiff) });
+          const jsonText = JSON.stringify({ path: parsed.path, diff: fenceGithubFieldIfMatched(fileDiff) });
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} diff:${parsed.path}`);
         } else {
-          emitGuarded(fenceGithubTextIfMatched(fileDiff), "pr-slice");
+          emitGuarded(fenceGithubText(fileDiff), "pr-slice");
           recordReadStat("pr_slice", fullSourceBytes, fileDiff, `${repo}#${opts.pr} diff:${parsed.path}`);
         }
         return 0;
@@ -7230,14 +7211,14 @@ function runPrSlice(opts) {
         const comments = fetchPrComments(opts.pr, repo);
         const fullSourceBytes = Buffer.byteLength(JSON.stringify(comments), "utf8");
         if (opts.json === true) {
-          const fencedComments = comments.map((c) => ({ ...c, body: fenceGithubTextIfMatched(c.body) }));
+          const fencedComments = comments.map((c) => ({ ...c, body: fenceGithubFieldIfMatched(c.body) }));
           const capped = guardJsonRows(fencedComments);
           const jsonText = JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount });
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} comments`);
         } else {
           const text = formatCommentsSlice(comments);
-          emitGuarded(fenceGithubTextIfMatched(text), "pr-slice");
+          emitGuarded(fenceGithubText(text), "pr-slice");
           recordReadStat("pr_slice", fullSourceBytes, text, `${repo}#${opts.pr} comments`);
         }
         return 0;
@@ -7248,15 +7229,15 @@ function runPrSlice(opts) {
         if (opts.json === true) {
           const fencedDesc = {
             ...desc,
-            title: fenceGithubTextIfMatched(desc.title),
-            body: desc.body !== null ? fenceGithubTextIfMatched(desc.body) : null
+            title: fenceGithubFieldIfMatched(desc.title),
+            body: desc.body !== null ? fenceGithubFieldIfMatched(desc.body) : null
           };
           const jsonText = JSON.stringify(fencedDesc);
           emit(jsonText);
           recordReadStat("pr_slice", fullSourceBytes, jsonText, `${repo}#${opts.pr} description`);
         } else {
           const text = formatDescriptionSlice(desc);
-          emitGuarded(fenceGithubTextIfMatched(text), "pr-slice");
+          emitGuarded(fenceGithubText(text), "pr-slice");
           recordReadStat("pr_slice", fullSourceBytes, text, `${repo}#${opts.pr} description`);
         }
         return 0;
@@ -7362,10 +7343,10 @@ function runConflicts(opts) {
   if (opts.path === void 0) {
     files = walkProject(process.cwd()).files;
   } else {
-    const abs = path5.resolve(opts.path);
+    const abs = path4.resolve(opts.path);
     let stat;
     try {
-      stat = fs5.statSync(abs);
+      stat = fs4.statSync(abs);
     } catch {
       emitErr(`Could not read: ${opts.path}`);
       return 1;
@@ -7400,7 +7381,7 @@ async function runPdfExtractText(file, pagesSpec, layout = false) {
   if (!fileExists(file)) {
     throw new Error(`Could not read: ${file}`);
   }
-  const data = fs5.readFileSync(file);
+  const data = fs4.readFileSync(file);
   const result = await extractPdfText(new Uint8Array(data), pagesSpec, layout);
   return result.text;
 }
@@ -7408,21 +7389,21 @@ async function runPdfOutline(file) {
   if (!fileExists(file)) {
     throw new Error(`Could not read: ${file}`);
   }
-  const data = fs5.readFileSync(file);
+  const data = fs4.readFileSync(file);
   return extractPdfOutline(new Uint8Array(data));
 }
 async function runPdfMeta(file) {
   if (!fileExists(file)) {
     throw new Error(`Could not read: ${file}`);
   }
-  const data = fs5.readFileSync(file);
+  const data = fs4.readFileSync(file);
   return extractPdfMeta(new Uint8Array(data));
 }
 async function runPdfLocate(file, pattern, opts) {
   if (!fileExists(file)) {
     throw new Error(`Could not read: ${file}`);
   }
-  const data = fs5.readFileSync(file);
+  const data = fs4.readFileSync(file);
   return locatePdfPages(new Uint8Array(data), pattern, opts);
 }
 async function runImageMeta(file) {
@@ -7432,7 +7413,7 @@ async function runImageMeta(file) {
   if (!isImagePath(file)) {
     throw new Error(`Not an image file: ${file}`);
   }
-  const data = fs5.readFileSync(file);
+  const data = fs4.readFileSync(file);
   const bytes = data.length;
   let probe;
   try {
@@ -7464,7 +7445,7 @@ async function runImageText(file) {
   if (!isImagePath(file)) {
     throw new Error(`Not an image file: ${file}`);
   }
-  const data = fs5.readFileSync(file);
+  const data = fs4.readFileSync(file);
   const ocr = await ocrImage(data);
   if (ocr === null) {
     if (ocrIntegrityFailed()) {
@@ -7673,7 +7654,7 @@ function runFind(opts) {
   }
   if (opts.json === true) {
     const fuzzyPayload = fuzzyNames.length > 0 ? { fuzzy: true, matchedNames: fuzzyNames } : {};
-    emit(JSON.stringify({ files, truncated, ...fuzzyPayload }, null, 2));
+    emit(JSON.stringify({ files, truncated, totalCount: allFiles.length, ...fuzzyPayload }, null, 2));
     return 0;
   }
   if (fuzzyNames.length > 0) {
@@ -8168,7 +8149,7 @@ function runGrep(opts) {
     if (activePins !== null) {
       let realDir;
       try {
-        realDir = foldRealpath(fs5.realpathSync(dir));
+        realDir = foldRealpath(fs4.realpathSync(dir));
       } catch {
         return;
       }
@@ -8177,12 +8158,12 @@ function runGrep(opts) {
       visitedRealDirs.add(realDir);
     }
     try {
-      for (const entry of fs5.readdirSync(dir)) {
+      for (const entry of fs4.readdirSync(dir)) {
         if (entry.startsWith(".")) continue;
-        const full = path5.join(dir, entry);
+        const full = path4.join(dir, entry);
         let lst;
         try {
-          lst = fs5.lstatSync(full);
+          lst = fs4.lstatSync(full);
         } catch {
           continue;
         }
@@ -8190,7 +8171,7 @@ function runGrep(opts) {
         if (lst.isSymbolicLink()) {
           let real;
           try {
-            real = fs5.realpathSync(full);
+            real = fs4.realpathSync(full);
           } catch {
             continue;
           }
@@ -8199,7 +8180,7 @@ function runGrep(opts) {
         }
         let stat;
         try {
-          stat = fs5.statSync(target);
+          stat = fs4.statSync(target);
         } catch {
           continue;
         }
@@ -8219,16 +8200,16 @@ function runGrep(opts) {
       emitErr(`Path not found: ${searchPath}`);
       return 1;
     }
-    const stat = fs5.statSync(searchPath);
+    const stat = fs4.statSync(searchPath);
     if (stat.isDirectory()) {
-      const pinned = activePins?.get(pinKey(path5.resolve(searchPath)));
+      const pinned = activePins?.get(pinKey(path4.resolve(searchPath)));
       if (pinned !== void 0) verifyPin(searchPath, pinned);
       let boundaryReal;
       try {
-        boundaryReal = fs5.realpathSync(searchPath);
+        boundaryReal = fs4.realpathSync(searchPath);
       } catch (err) {
         if (pinned === void 0) {
-          boundaryReal = path5.resolve(searchPath);
+          boundaryReal = path4.resolve(searchPath);
         } else {
           throw new ConfinementIdentityError(
             `refused: "${searchPath}" could not be resolved after validation (${String(err)}). The path may have been replaced or redirected after the confinement check, so the search was not performed.`
@@ -8359,7 +8340,7 @@ function runConfigGet(opts) {
     emit(value);
     return 0;
   }
-  const ext = path5.extname(opts.file).toLowerCase();
+  const ext = path4.extname(opts.file).toLowerCase();
   if (ext === ".json") {
     try {
       let obj = JSON.parse(text);
@@ -8482,7 +8463,7 @@ function runExports(opts) {
       names.push(s.name);
     }
   }
-  const ext = path5.extname(opts.file).toLowerCase();
+  const ext = path4.extname(opts.file).toLowerCase();
   const text = readFileText(diskPath);
   if (text === null && symbols.length === 0) {
     emitErr(`Could not read: ${opts.file}`);
@@ -8819,9 +8800,9 @@ function extractImports(text, ext) {
   return found;
 }
 function importsExtensionFor(filePath) {
-  const base = path5.basename(filePath).toLowerCase();
+  const base = path4.basename(filePath).toLowerCase();
   if (base === "makefile" || base === "gnumakefile" || base === "bsdmakefile") return ".mk";
-  return path5.extname(filePath);
+  return path4.extname(filePath);
 }
 function runImports(opts) {
   const multiFiles = parseMultiFileSpec(opts.file);
@@ -8913,7 +8894,7 @@ async function runSemantic(query, opts) {
   }
   const n = opts.limit !== void 0 && Number.isFinite(opts.limit) ? opts.limit : 20;
   if (opts.projectRoot !== void 0) {
-    if (!path5.isAbsolute(opts.projectRoot) || !fs5.existsSync(opts.projectRoot) || !fs5.statSync(opts.projectRoot).isDirectory()) {
+    if (!path4.isAbsolute(opts.projectRoot) || !fs4.existsSync(opts.projectRoot) || !fs4.statSync(opts.projectRoot).isDirectory()) {
       const message = `token-goat: projectRoot must be an absolute, existing directory, got '${opts.projectRoot}'`;
       if (opts.json === true) {
         return { text: JSON.stringify({ error: message }, null, 2), code: 1 };
@@ -8943,6 +8924,18 @@ async function runSemantic(query, opts) {
       `Matching on meaning is off (${extractErrorMessage(e)}); these results come from keyword search alone.`
     );
   }
+  if (rawHits.length === 0 && isAvailable()) {
+    try {
+      const enabled = loadConfig().indexing.embeddings_enabled;
+      const { indexedFiles, embeddedFiles } = enabled ? getEmbeddingCoverage(globalDbPath(), rootDir) : { indexedFiles: 0, embeddedFiles: 0 };
+      if (indexedFiles > 0 && embeddedFiles < indexedFiles) {
+        console.warn(
+          `Matching on meaning found nothing, and only ${embeddedFiles} of ${indexedFiles} indexed file(s) in this project have embeddings \u2014 these results come from keyword search alone. Run 'token-goat doctor' for why.`
+        );
+      }
+    } catch {
+    }
+  }
   const mergedHits = mergeNearbyHits(rawHits);
   const overFetchFts = Math.min(MAX_OVER_FETCH, n * OVER_FETCH_FACTOR);
   const ftsRows = searchSymbolsFts(query, overFetchFts, void 0, rootDir);
@@ -8989,7 +8982,9 @@ async function runSemantic(query, opts) {
   const anyFilter = matchesGrep !== void 0 || opts.excludeTests === true;
   const filteredHits = anyFilter ? fusedHits.filter(keepHit) : fusedHits;
   const suppressedTotal = opts.excludeTests === true ? fusedHits.filter((h) => (matchesGrep === void 0 || matchesGrep(toDisplayPath(rootDir, h.filePath))) && isTestFile(h.filePath)).length : 0;
+  const eligibleCount = filteredHits.length;
   const hits = filteredHits.slice(0, n);
+  const candidatesClipped = rawHits.length >= overFetchForMerge || ftsRows.length >= overFetchFts;
   const hadDense = mergedHits.length > 0;
   const hadFts = ftsRows.length > 0;
   const source = hadDense && hadFts ? "hybrid" : hadDense ? "embeddings" : "fts";
@@ -9005,7 +9000,8 @@ async function runSemantic(query, opts) {
         preview: previewLines(h.previewText, 3)
       }));
       const capped = guardJsonRows(items);
-      const text3 = JSON.stringify({ source, ...capped }, null, 2);
+      const limitTruncated = hits.length < eligibleCount;
+      const text3 = JSON.stringify({ source, ...capped, truncated: capped.truncated || limitTruncated, totalCount: eligibleCount, ...candidatesClipped ? { totalCountIsFloor: true } : {} }, null, 2);
       recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text3, query);
       return { text: text3, code: 0 };
     }
@@ -9019,6 +9015,9 @@ ${previewLines(h.previewText, 3)}`;
 ${previewLines(h.previewText, 3)}`;
     });
     const text2 = guardText(blocks.join("\n\n"), "semantic");
+    if (hits.length < eligibleCount) {
+      emitErr(`Showing ${hits.length} of ${candidatesClipped ? "at least " : ""}${countNoun(eligibleCount, "match", "matches")} (raise --limit to see the rest).`);
+    }
     recordReadStat("semantic_search", sumFileSizes(hits.map((h) => h.filePath)), text2, query);
     return { text: text2, code: 0 };
   }
@@ -9133,6 +9132,318 @@ function runNoteList(opts = {}) {
   return { text: lines.join("\n"), code: 0 };
 }
 
+// src/import_graph.ts
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
+var DIRECT_PROBE_EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cjs", ".cts", ".py"];
+var INDEX_PROBE_EXTENSIONS = [".ts", ".js", ".tsx", ".jsx", ".mts", ".cts"];
+function buildImportGraph(cwd) {
+  const files = getTrackedFiles(cwd);
+  const filesByFoldedPath = /* @__PURE__ */ new Map();
+  for (const f of files) filesByFoldedPath.set(foldPath(f), f);
+  const resolve5 = (fromFile, spec) => {
+    if (!spec.startsWith(".")) return null;
+    const dir = path5.dirname(fromFile);
+    const strippedSpec = spec.replace(/\.(m?js|cjs)$/, "");
+    const base = path5.resolve(dir, strippedSpec);
+    for (const ext of DIRECT_PROBE_EXTENSIONS) {
+      const match = filesByFoldedPath.get(foldPath(base + ext));
+      if (match !== void 0) return match;
+    }
+    const idx = path5.join(base, "index");
+    for (const ext of INDEX_PROBE_EXTENSIONS) {
+      const match = filesByFoldedPath.get(foldPath(idx + ext));
+      if (match !== void 0) return match;
+    }
+    return null;
+  };
+  const graph = /* @__PURE__ */ new Map();
+  const importedBy = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    let text;
+    try {
+      text = fs5.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const internal = [];
+    for (const spec of extractImports(text, importsExtensionFor(file))) {
+      const resolved = resolve5(file, spec);
+      if (resolved === null) continue;
+      internal.push(resolved);
+      let importers = importedBy.get(resolved);
+      if (importers === void 0) {
+        importers = /* @__PURE__ */ new Set();
+        importedBy.set(resolved, importers);
+      }
+      importers.add(file);
+    }
+    graph.set(file, internal);
+  }
+  return { files, graph, importedBy, resolve: resolve5 };
+}
+
+// src/modules.ts
+var WEAK_MODULARITY = 0.3;
+var MAX_PASSES = 32;
+var GAIN_EPSILON = 1e-12;
+function emptyGraph(n) {
+  return { n, adj: Array.from({ length: n }, () => /* @__PURE__ */ new Map()), degree: new Array(n).fill(0), m: 0 };
+}
+function addEdge(g, a, b, w) {
+  if (a === b) {
+    g.adj[a].set(a, (g.adj[a].get(a) ?? 0) + w);
+    g.degree[a] += 2 * w;
+  } else {
+    g.adj[a].set(b, (g.adj[a].get(b) ?? 0) + w);
+    g.adj[b].set(a, (g.adj[b].get(a) ?? 0) + w);
+    g.degree[a] += w;
+    g.degree[b] += w;
+  }
+  g.m += w;
+}
+function localMoving(g) {
+  const community = Array.from({ length: g.n }, (_, i) => i);
+  const tot = g.degree.slice();
+  const twoM = 2 * g.m;
+  let movedEver = false;
+  if (twoM === 0) return { community, moved: false };
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    let improved = false;
+    for (let i = 0; i < g.n; i++) {
+      const ki = g.degree[i];
+      const ci = community[i];
+      const links = /* @__PURE__ */ new Map();
+      for (const [j, w] of g.adj[i]) {
+        if (j === i) continue;
+        const cj = community[j];
+        links.set(cj, (links.get(cj) ?? 0) + w);
+      }
+      tot[ci] = tot[ci] - ki;
+      let bestC = ci;
+      let bestGain = (links.get(ci) ?? 0) - tot[ci] * ki / twoM;
+      for (const c of [...links.keys()].sort((a, b) => a - b)) {
+        if (c === ci) continue;
+        const gain = links.get(c) - tot[c] * ki / twoM;
+        if (gain > bestGain + GAIN_EPSILON) {
+          bestGain = gain;
+          bestC = c;
+        }
+      }
+      tot[bestC] = tot[bestC] + ki;
+      community[i] = bestC;
+      if (bestC !== ci) {
+        improved = true;
+        movedEver = true;
+      }
+    }
+    if (!improved) break;
+  }
+  return { community, moved: movedEver };
+}
+function densify(community) {
+  const firstMember = /* @__PURE__ */ new Map();
+  for (let i = 0; i < community.length; i++) {
+    const c = community[i];
+    if (!firstMember.has(c)) firstMember.set(c, i);
+  }
+  const ordered = [...firstMember.entries()].sort((a, b) => a[1] - b[1]).map(([c]) => c);
+  const remap = /* @__PURE__ */ new Map();
+  ordered.forEach((c, idx) => remap.set(c, idx));
+  return { dense: community.map((c) => remap.get(c)), count: ordered.length };
+}
+function modularityOf(g, partition) {
+  const twoM = 2 * g.m;
+  if (twoM === 0) return null;
+  const internal = /* @__PURE__ */ new Map();
+  const tot = /* @__PURE__ */ new Map();
+  for (let i = 0; i < g.n; i++) {
+    const ci = partition[i];
+    tot.set(ci, (tot.get(ci) ?? 0) + g.degree[i]);
+    for (const [j, w] of g.adj[i]) {
+      if (j < i) continue;
+      if (partition[j] === ci) internal.set(ci, (internal.get(ci) ?? 0) + w);
+    }
+  }
+  let q = 0;
+  for (const [c, t] of tot) {
+    q += 2 * (internal.get(c) ?? 0) / twoM - (t / twoM) ** 2;
+  }
+  return q;
+}
+function louvain(g) {
+  let current = g;
+  let mapping = Array.from({ length: g.n }, (_, i) => i);
+  for (let level = 0; level < MAX_PASSES; level++) {
+    const { community, moved } = localMoving(current);
+    const { dense, count } = densify(community);
+    mapping = mapping.map((c) => dense[c]);
+    if (!moved || count === current.n) break;
+    const next = emptyGraph(count);
+    for (let i = 0; i < current.n; i++) {
+      for (const [j, w] of current.adj[i]) {
+        if (j < i) continue;
+        addEdge(next, dense[i], dense[j], w);
+      }
+    }
+    current = next;
+  }
+  return mapping;
+}
+function commonDirLabel(files) {
+  const dirs = new Set(files.map(dirOf));
+  if (dirs.size === 1) {
+    const only = [...dirs][0];
+    return only === "." ? "." : `${only}/`;
+  }
+  const segmentLists = files.map((f) => {
+    const parts = f.split("/");
+    parts.pop();
+    return parts;
+  });
+  const first = segmentLists[0];
+  if (first === void 0) return null;
+  const prefix = [];
+  for (let i = 0; i < first.length; i++) {
+    const seg = first[i];
+    if (!segmentLists.every((s) => s[i] === seg)) break;
+    prefix.push(seg);
+  }
+  return prefix.length === 0 ? null : `${prefix.join("/")}/`;
+}
+function dirOf(file) {
+  const idx = file.lastIndexOf("/");
+  return idx === -1 ? "." : file.slice(0, idx);
+}
+function detectModules(imports, cwd, top) {
+  const { files, graph } = imports;
+  const root = getDisplayRoot(cwd);
+  const degreeOf = /* @__PURE__ */ new Map();
+  const bump = (f) => {
+    degreeOf.set(f, (degreeOf.get(f) ?? 0) + 1);
+  };
+  for (const [from, targets] of graph) {
+    for (const to of targets) {
+      if (from === to) continue;
+      bump(from);
+      bump(to);
+    }
+  }
+  const connected = files.filter((f) => (degreeOf.get(f) ?? 0) > 0);
+  const isolatedCount = files.length - connected.length;
+  if (connected.length === 0) {
+    return { modules: [], modulesTotal: 0, modularity: null, isolatedCount, crossImports: [], crossImportsTotal: 0, noEdges: true };
+  }
+  const ordered = [...connected].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  const idOf = /* @__PURE__ */ new Map();
+  ordered.forEach((f, i) => idOf.set(f, i));
+  const g = emptyGraph(ordered.length);
+  const pairWeight = /* @__PURE__ */ new Map();
+  for (const [from, targets] of graph) {
+    const a = idOf.get(from);
+    if (a === void 0) continue;
+    for (const to of targets) {
+      const b = idOf.get(to);
+      if (b === void 0 || a === b) continue;
+      const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+      pairWeight.set(key, (pairWeight.get(key) ?? 0) + 1);
+    }
+  }
+  for (const key of [...pairWeight.keys()].sort()) {
+    const [a, b] = key.split(":").map(Number);
+    addEdge(g, a, b, pairWeight.get(key));
+  }
+  const partition = louvain(g);
+  const modularity = modularityOf(g, partition);
+  const membersOf = /* @__PURE__ */ new Map();
+  for (let i = 0; i < ordered.length; i++) {
+    const c = partition[i];
+    const list = membersOf.get(c);
+    if (list === void 0) membersOf.set(c, [ordered[i]]);
+    else list.push(ordered[i]);
+  }
+  const inModuleDegree = /* @__PURE__ */ new Map();
+  for (const [from, targets] of graph) {
+    const a = idOf.get(from);
+    if (a === void 0) continue;
+    for (const to of targets) {
+      const b = idOf.get(to);
+      if (b === void 0 || a === b || partition[a] !== partition[b]) continue;
+      inModuleDegree.set(from, (inModuleDegree.get(from) ?? 0) + 1);
+      inModuleDegree.set(to, (inModuleDegree.get(to) ?? 0) + 1);
+    }
+  }
+  const built = [...membersOf.entries()].map(([c, absFiles]) => {
+    const display = absFiles.map((f) => toDisplayPath(root, f)).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    const coreAbs = [...absFiles].sort((a, b) => (inModuleDegree.get(b) ?? 0) - (inModuleDegree.get(a) ?? 0) || (a < b ? -1 : a > b ? 1 : 0))[0];
+    return { community: c, core: toDisplayPath(root, coreAbs), commonDir: commonDirLabel(display), files: display, directories: new Set(display.map(dirOf)).size };
+  }).sort((a, b) => b.files.length - a.files.length || (a.core < b.core ? -1 : a.core > b.core ? 1 : 0) || (a.files[0] < b.files[0] ? -1 : 1));
+  const indexOfCommunity = /* @__PURE__ */ new Map();
+  built.forEach((m, i) => indexOfCommunity.set(m.community, i + 1));
+  const coreOfIndex = /* @__PURE__ */ new Map();
+  built.forEach((m, i) => coreOfIndex.set(i + 1, m.core));
+  const crossCount = /* @__PURE__ */ new Map();
+  for (const [from, targets] of graph) {
+    const a = idOf.get(from);
+    if (a === void 0) continue;
+    const ca = indexOfCommunity.get(partition[a]);
+    if (ca === void 0) continue;
+    for (const to of targets) {
+      const b = idOf.get(to);
+      if (b === void 0) continue;
+      const cb = indexOfCommunity.get(partition[b]);
+      if (cb === void 0 || ca === cb) continue;
+      const key = `${ca}:${cb}`;
+      crossCount.set(key, (crossCount.get(key) ?? 0) + 1);
+    }
+  }
+  const allCross = [...crossCount.entries()].map(([key, imports2]) => {
+    const [fromIndex, toIndex] = key.split(":").map(Number);
+    return { fromIndex, toIndex, fromCore: coreOfIndex.get(fromIndex), toCore: coreOfIndex.get(toIndex), imports: imports2 };
+  }).sort((a, b) => b.imports - a.imports || a.fromIndex - b.fromIndex || a.toIndex - b.toIndex);
+  const modules = built.slice(0, top).map((m, i) => ({ index: i + 1, core: m.core, commonDir: m.commonDir, files: m.files, size: m.files.length, directories: m.directories }));
+  return {
+    modules,
+    modulesTotal: built.length,
+    modularity,
+    isolatedCount,
+    crossImports: allCross.slice(0, top),
+    crossImportsTotal: allCross.length,
+    noEdges: false
+  };
+}
+function renderModules(result, top) {
+  const lines = [];
+  if (result.noEdges) {
+    lines.push(`modules: none. No file in this project imports another by a relative path, so there is nothing to group (${countNoun(result.isolatedCount, "file")} checked).`);
+    return lines;
+  }
+  const q = result.modularity;
+  const strength = q === null ? "" : q < WEAK_MODULARITY ? `, modularity ${q.toFixed(2)} -- weak, so treat this grouping as a hint rather than a finding` : `, modularity ${q.toFixed(2)}`;
+  lines.push(result.modules.length < result.modulesTotal ? `modules (top ${result.modules.length} of ${result.modulesTotal}${strength}):` : `modules (${result.modulesTotal} found${strength}):`);
+  for (const m of result.modules) {
+    const where = m.commonDir === null ? `across ${m.directories} directories` : m.commonDir === "." ? "all in the repository root" : `all in ${m.commonDir}`;
+    lines.push(`  #${m.index} ${m.size} files	${m.core}	(${where})`);
+  }
+  if (result.isolatedCount > 0) {
+    lines.push(`  ${result.isolatedCount} files are in no module (they neither import nor are imported within the project).`);
+  }
+  if (result.crossImportsTotal === 0) {
+    lines.push("cross-module imports: none. Every import stays inside its own module.");
+  } else {
+    lines.push(
+      result.crossImports.length < result.crossImportsTotal ? `cross-module imports (top ${result.crossImports.length} of ${result.crossImportsTotal} pairs):` : `cross-module imports (${result.crossImportsTotal} pairs):`
+    );
+    for (const c of result.crossImports) {
+      lines.push(`  ${c.imports} imports	#${c.fromIndex} ${c.fromCore} -> #${c.toIndex} ${c.toCore}`);
+    }
+  }
+  if (result.modules.length < result.modulesTotal && result.crossImports.some((c) => c.fromIndex > top || c.toIndex > top)) {
+    lines.push(`  (a #N above ${top} refers to a module the --top cap left out; raise --top to see it.)`);
+  }
+  return lines;
+}
+
 // src/graph_commands.ts
 var DEFAULT_REF_QUERY_LIMIT = 500;
 var ALL_SYMBOLS_IN_FILE_LIMIT = 1e4;
@@ -9819,7 +10130,7 @@ var TYPE_KINDS = [
 var CORE_SYMBOL_KINDS = [
   .../* @__PURE__ */ new Set([...GENERIC_SYMBOL_KINDS, ...TYPE_KINDS, ...OTHER_ADAPTER_SYMBOL_KINDS])
 ];
-var TYPES_EXCLUDE_TESTS_SCAN_LIMIT = 5e3;
+var TYPES_SCAN_LIMIT = 5e3;
 function runTypes(opts) {
   if (opts.limit !== void 0 && opts.limit <= 0) {
     emitErr2(`--limit must be a positive number, got: ${opts.limit}`);
@@ -9832,34 +10143,25 @@ function runTypes(opts) {
   const rootDir = resolveProjectRoot({ project: process.cwd() });
   const results = [];
   let suppressed = 0;
-  const queryLimit = excludeTests ? TYPES_EXCLUDE_TESTS_SCAN_LIMIT : limit;
   for (const k of TYPE_KINDS) {
-    const syms = querySymbols({ kind: k, ...fpOpt, limit: queryLimit, rootDir });
-    if (!excludeTests) {
-      results.push(...syms);
-      continue;
-    }
-    const kept = [];
+    const syms = querySymbols({ kind: k, ...fpOpt, limit: TYPES_SCAN_LIMIT, rootDir });
     for (const sym of syms) {
-      if (isTestFile(sym.filePath)) {
+      if (excludeTests && isTestFile(sym.filePath)) {
         suppressed += 1;
         continue;
       }
-      kept.push(sym);
+      results.push(sym);
     }
-    results.push(...kept.slice(0, limit));
   }
-  const classes = querySymbols({ kind: "class", ...fpOpt, limit: queryLimit, rootDir });
-  const typeClasses = [];
+  const classes = querySymbols({ kind: "class", ...fpOpt, limit: TYPES_SCAN_LIMIT, rootDir });
   for (const cls of classes) {
     if (!looksLikeTypeClass(cls.body)) continue;
     if (excludeTests && isTestFile(cls.filePath)) {
       suppressed += 1;
       continue;
     }
-    typeClasses.push(cls);
+    results.push(cls);
   }
-  results.push(...excludeTests ? typeClasses.slice(0, limit) : typeClasses);
   results.sort(
     // Pin the locale: an unlocaled localeCompare() sorts differently across
     // Node's small-icu vs full-icu builds and different system default
@@ -9886,7 +10188,16 @@ function runTypes(opts) {
   }
   const preFilterCount = results.length;
   const matchesGrep = opts.grep !== void 0 ? compileGrepMatcher(opts.grep) : void 0;
-  const filtered = matchesGrep !== void 0 ? results.filter((r) => matchesGrep(r.name)) : results;
+  const matched = matchesGrep !== void 0 ? results.filter((r) => matchesGrep(r.name)) : results;
+  const eligibleCount = matched.length;
+  const perKindShown = /* @__PURE__ */ new Map();
+  const filtered = matched.filter((r) => {
+    const seen = perKindShown.get(r.kind) ?? 0;
+    if (seen >= limit) return false;
+    perKindShown.set(r.kind, seen + 1);
+    return true;
+  });
+  const cappedOut = eligibleCount - filtered.length;
   if (filtered.length === 0) {
     if (opts.json === true) {
       emit2(JSON.stringify({ items: [], truncated: false, totalCount: 0, hiddenByGrep: preFilterCount }, null, 2));
@@ -9897,8 +10208,8 @@ function runTypes(opts) {
   }
   if (opts.json === true) {
     const capped = guardJsonRows(filtered.map((r) => ({ ...r, filePath: toDisplayPath(rootDir, r.filePath) })));
-    const hiddenByGrep = preFilterCount - filtered.length;
-    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated, totalCount: capped.totalCount, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...excludeTests && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
+    const hiddenByGrep = preFilterCount - eligibleCount;
+    emit2(JSON.stringify({ items: capped.items, truncated: capped.truncated || cappedOut > 0, totalCount: eligibleCount, ...hiddenByGrep > 0 ? { hiddenByGrep } : {}, ...excludeTests && suppressed > 0 ? { hiddenByExcludeTests: suppressed } : {} }, null, 2));
     return 0;
   }
   if (excludeTests && suppressed > 0) {
@@ -9907,6 +10218,9 @@ function runTypes(opts) {
   for (const r of filtered) {
     emit2(`${r.name}	${r.kind}	${toDisplayPath(rootDir, r.filePath)}:${r.lineStart}`);
   }
+  if (cappedOut > 0) {
+    emitErr2(`Showing ${filtered.length} of ${eligibleCount} type declarations (--limit is per kind; raise it to see the rest).`);
+  }
   return 0;
 }
 function runScope(opts) {
@@ -9922,7 +10236,7 @@ function runScope(opts) {
     return 1;
   }
   const line = Number.parseInt(lineStr, 10);
-  if (!Number.isFinite(line) || line < 1) {
+  if (!Number.isSafeInteger(line) || line < 1) {
     emitErr2(`Invalid line number: ${lineStr}`);
     return 1;
   }
@@ -9932,25 +10246,32 @@ function runScope(opts) {
     return 1;
   }
   const filePath = resolveIndexPath(file);
-  const syms = querySymbols({ filePath, limit: ALL_SYMBOLS_IN_FILE_LIMIT });
-  const enclosing = syms.filter((s) => s.lineStart <= line && line <= s.lineEnd).sort((a, b) => b.lineStart - a.lineStart || a.lineEnd - b.lineEnd || a.name.localeCompare(b.name, "en"));
-  if (syms.length === 0) {
-    if (!fs6.existsSync(filePath)) {
-      emitErr2(`Could not read: ${file}`);
+  const enclosing = querySymbols({ filePath, enclosingLine: line, limit: ALL_SYMBOLS_IN_FILE_LIMIT }).sort((a, b) => b.lineStart - a.lineStart || a.lineEnd - b.lineEnd || a.name.localeCompare(b.name, "en"));
+  if (enclosing.length === 0) {
+    if (querySymbols({ filePath, limit: 1 }).length === 0) {
+      if (!fs6.existsSync(filePath)) {
+        emitErr2(`Could not read: ${file}`);
+        return 1;
+      }
+      emitErr2(
+        `No indexed symbols in '${file}' \u2014 the file exists but nothing is indexed for it, so every line looks empty`
+      );
       return 1;
     }
-    emitErr2(`No indexed symbols in '${file}' \u2014 the file exists but nothing is indexed for it, so every line looks empty`);
-    return 1;
-  }
-  if (enclosing.length === 0) {
     emitErr2(`No symbols enclosing line ${line} in '${file}'`);
     return 1;
   }
+  const scopeDisplayRoot = getDisplayRoot();
   if (opts.json === true) {
-    emit2(JSON.stringify(enclosing, null, 2));
+    emit2(
+      JSON.stringify(
+        enclosing.map((s) => ({ ...s, filePath: toDisplayPath(scopeDisplayRoot, s.filePath) })),
+        null,
+        2
+      )
+    );
     return 0;
   }
-  const scopeDisplayRoot = getDisplayRoot();
   for (const s of enclosing) {
     emit2(`${s.name}	${s.kind}	${toDisplayPath(scopeDisplayRoot, s.filePath)}:${s.lineStart}-${s.lineEnd}`);
   }
@@ -10075,8 +10396,12 @@ function runSimilar(opts) {
   const words = [anchor.name, ...(anchor.docstring ?? "").split(/\s+/).filter((w) => w.length > 4)];
   const query = words.slice(0, 8).join(" ");
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const hits = searchSymbolsFts(query, top + 1, void 0, rootDir);
-  const results = hits.filter((h) => !(h.filePath === anchor.filePath && h.name === anchor.name)).slice(0, top);
+  const hits = searchSymbolsFts(query, UNBOUNDED_REF_LIMIT, void 0, rootDir);
+  const matches = hits.filter((h) => !(h.filePath === anchor.filePath && h.name === anchor.name));
+  const results = matches.slice(0, top);
+  if (matches.length > results.length) {
+    emitErr2(`Showing top ${results.length} of ${matches.length} similar symbols (raise --top to see the rest).`);
+  }
   if (opts.json === true) {
     emit2(JSON.stringify(results.map((h) => ({ name: h.name, kind: h.kind, file: h.filePath, line: h.lineStart })), null, 2));
     return 0;
@@ -10092,7 +10417,9 @@ function runContextFor(opts) {
   const top = opts.top ?? 12;
   const budget = opts.budget;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const hits = searchSymbolsFts(opts.task, top, void 0, rootDir);
+  const fetched = searchSymbolsFts(opts.task, top + 1, void 0, rootDir);
+  const moreBeyondTop = fetched.length > top;
+  const hits = fetched.slice(0, top);
   if (hits.length === 0) {
     emitErr2(`No matches found for '${opts.task}'`);
     return 1;
@@ -10105,6 +10432,15 @@ function runContextFor(opts) {
     tokensSoFar += bodyTokens;
     entries.push({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` });
   }
+  const skippedByBudget = hits.length - entries.length;
+  const notices = [];
+  if (skippedByBudget > 0) {
+    notices.push(
+      entries.length === 0 ? `All ${countNoun(skippedByBudget, "matching symbol")} were larger than --budget ${String(opts.budget)} tokens, so none are shown. Raise --budget.` : `Showing ${entries.length} of ${countNoun(hits.length, "matching symbol")}; ${skippedByBudget} did not fit --budget ${String(opts.budget)} tokens.`
+    );
+  }
+  if (moreBeyondTop) notices.push(`More matches exist beyond --top ${top} (raise it to see them).`);
+  for (const n of notices) emitErr2(n);
   if (opts.json === true) {
     emit2(JSON.stringify(entries, null, 2));
     return 0;
@@ -10195,66 +10531,31 @@ function runArch(opts) {
   }
   const cwd = opts.cwd ?? process.cwd();
   const top = opts.top ?? 10;
-  const files = getTrackedFiles(cwd);
+  const { files, graph, importedBy, resolve: resolve5 } = buildImportGraph(cwd);
   if (files.length === 0 && opts.json !== true) {
     emit2(`no tracked files found under '${toDisplayPath(getDisplayRoot(cwd), cwd)}' (is it a git repo?). Nothing to analyse.`);
     return 0;
   }
-  const filesByFoldedPath = /* @__PURE__ */ new Map();
-  for (const f of files) filesByFoldedPath.set(foldPath(f), f);
-  const graph = /* @__PURE__ */ new Map();
-  const importedBy = /* @__PURE__ */ new Map();
-  const resolveRelImport = (fromFile, spec) => {
-    if (!spec.startsWith(".")) return null;
-    const dir = path6.dirname(fromFile);
-    const strippedSpec = spec.replace(/\.(m?js|cjs)$/, "");
-    const base = path6.resolve(dir, strippedSpec);
-    for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cjs", ".cts", ".py"]) {
-      const candidate = base + ext;
-      const match = filesByFoldedPath.get(foldPath(candidate));
-      if (match !== void 0) return match;
-    }
-    const idx = path6.join(base, "index");
-    for (const ext of [".ts", ".js", ".tsx", ".jsx", ".mts", ".cts"]) {
-      const candidate = idx + ext;
-      const match = filesByFoldedPath.get(foldPath(candidate));
-      if (match !== void 0) return match;
-    }
-    return null;
-  };
-  for (const file of files) {
-    let text;
-    try {
-      text = fs6.readFileSync(file, "utf8");
-    } catch {
-      continue;
-    }
-    const ext = importsExtensionFor(file);
-    const rawImports = extractImports(text, ext);
-    const internal = [];
-    for (const spec of rawImports) {
-      const resolved = resolveRelImport(file, spec);
-      if (resolved !== null) {
-        internal.push(resolved);
-        if (!importedBy.has(resolved)) importedBy.set(resolved, /* @__PURE__ */ new Set());
-        importedBy.get(resolved).add(file);
-      }
-    }
-    graph.set(file, internal);
-  }
-  const hubs = [...importedBy.entries()].sort((a, b) => b[1].size - a[1].size).slice(0, top).map(([f, importers]) => ({ file: f, importedBy: importers.size }));
-  const entryPoints = files.filter((f) => !importedBy.has(f) && (graph.get(f) ?? []).length > 0).slice(0, top).map((f) => ({ file: f }));
+  const allHubs = [...importedBy.entries()].sort((a, b) => b[1].size - a[1].size).map(([f, importers]) => ({ file: f, importedBy: importers.size }));
+  const hubsTotal = allHubs.length;
+  const hubs = allHubs.slice(0, top);
+  const allEntryPoints = files.filter((f) => !importedBy.has(f) && (graph.get(f) ?? []).length > 0).map((f) => ({ file: f }));
+  const entryPointsTotal = allEntryPoints.length;
+  const entryPoints = allEntryPoints.slice(0, top);
   const { cycles, truncated: cyclesTruncated } = findCyclesCapped(graph);
+  const moduleResult = opts.modules === true ? detectModules({ files, graph, importedBy, resolve: resolve5 }, cwd, top) : null;
   if (opts.json === true) {
-    emit2(JSON.stringify({ hubs, entryPoints, cycles, ...cyclesTruncated ? { cyclesTruncated: true } : {} }, null, 2));
+    const modulePayload = moduleResult === null ? {} : { modules: moduleResult.modules, modulesTotal: moduleResult.modulesTotal, modulesTruncated: moduleResult.modules.length < moduleResult.modulesTotal, modularity: moduleResult.modularity, isolatedCount: moduleResult.isolatedCount, crossImports: moduleResult.crossImports, crossImportsTotal: moduleResult.crossImportsTotal, crossImportsTruncated: moduleResult.crossImports.length < moduleResult.crossImportsTotal, noImportEdges: moduleResult.noEdges };
+    emit2(JSON.stringify({ hubs, hubsTotal, hubsTruncated: hubs.length < hubsTotal, entryPoints, entryPointsTotal, entryPointsTruncated: entryPoints.length < entryPointsTotal, cycles, ...cyclesTruncated ? { cyclesTruncated: true } : {}, ...modulePayload }, null, 2));
     return 0;
   }
-  emit2(`hubs (top ${top} most-imported):`);
+  emit2(hubs.length < hubsTotal ? `hubs (top ${hubs.length} of ${hubsTotal} most-imported):` : `hubs (${hubsTotal} most-imported):`);
   for (const h of hubs) emit2(`  ${h.importedBy} importers	${toDisplayPath(getDisplayRoot(opts.cwd), h.file)}`);
-  emit2(`entry points (imported by nobody, top ${top}):`);
+  emit2(entryPoints.length < entryPointsTotal ? `entry points (imported by nobody, top ${entryPoints.length} of ${entryPointsTotal}):` : `entry points (imported by nobody, ${entryPointsTotal} found):`);
   for (const e of entryPoints) emit2(`  ${toDisplayPath(getDisplayRoot(opts.cwd), e.file)}`);
   emit2(cyclesTruncated ? `cycles (first ${cycles.length}, truncated at the ${MAX_CYCLES}-cycle enumeration limit: more cycles exist):` : `cycles (${cycles.length} found):`);
   for (const c of cycles) emit2(`  ${c.map((f) => toDisplayPath(getDisplayRoot(opts.cwd), f)).join(" -> ")}`);
+  if (moduleResult !== null) for (const line of renderModules(moduleResult, top)) emit2(line);
   return 0;
 }
 function runBlame(opts) {
@@ -10301,7 +10602,12 @@ function runAsk(opts) {
   }
   const top = opts.top ?? 8;
   const rootDir = resolveProjectRoot({ project: process.cwd() });
-  const hits = searchSymbolsFts(opts.question, top, void 0, rootDir);
+  const fetched = searchSymbolsFts(opts.question, top + 1, void 0, rootDir);
+  const moreBeyondTop = fetched.length > top;
+  const hits = fetched.slice(0, top);
+  if (moreBeyondTop) {
+    emitErr2(`Answer is grounded in the top ${countNoun(top, "match", "matches")}; more matched (raise --top to widen the evidence).`);
+  }
   const BACKEND_ENV = "TOKEN_GOAT_ASK_BACKEND";
   const backendLabel = process.env[BACKEND_ENV] ?? "";
   const entries = hits.map((h) => ({ file: h.filePath, symbol: h.name, kind: h.kind, line: h.lineStart, readCmd: `token-goat read "${h.filePath}::${h.name}@${h.lineStart}"` }));
@@ -10505,10 +10811,10 @@ function resolveHandoff(name, opts = {}) {
 }
 
 export {
-  getTrackedFiles,
   extractSection,
   readSection,
   listSections,
+  buildImportGraph,
   ALL_SYMBOLS_IN_FILE_LIMIT,
   enclosingSymbol,
   runCallers,