ai-code-map 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/index.js

@@ -1,40 +1,5 @@
-// src/constants.ts
-var SCHEMA_VERSION = 4;
-var CONFIG_VERSION = 1;
-var ANALYZER_VERSION = "0.4.0";
-var DEFAULT_SYNTAX_PARSER = "typescript-compiler-syntax";
-var DEFAULT_SEMANTIC_RESOLVER = "typescript-program";
-var DEFAULT_ANALYZER_NAMES = ["typescript-node", "react"];
-var DEFAULT_PRODUCER_ID = "ai-code-map/default-pipeline";
-var CUSTOM_PRODUCER_ID = "ai-code-map/custom-pipeline";
-var PRODUCER_CONTRACT_VERSION = 1;
-var DEFAULT_OUTPUT = ".ai/code-map";
-var DEFAULT_INCLUDE = [
-  "src/**/*",
-  "app/**/*",
-  "pages/**/*",
-  "lib/**/*",
-  "server/**/*",
-  "*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"
-];
-var DEFAULT_EXCLUDE = [
-  "**/node_modules/**",
-  "**/.next/**",
-  "**/dist/**",
-  "**/build/**",
-  "**/coverage/**",
-  "**/.git/**",
-  "**/.ai/**",
-  "**/*.generated.*"
-];
-var MAP_COMPANION_ARTIFACTS = [
-  "overview.md",
-  "project.json",
-  "files.jsonl",
-  "symbols.jsonl",
-  "relations.jsonl",
-  "diagnostics.json"
-];
+// src/context.ts
+import path3 from "path";
 
 // src/errors.ts
 var CodeMapError = class extends Error {
@@ -49,20 +14,266 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-// src/config.ts
-import { promises as fs3 } from "fs";
-import path4 from "path";
+// src/utils/stable.ts
+import { promises as fs } from "fs";
+import path from "path";
+function compareText(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function safeRecordEntry(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => safeRecordEntry(entry));
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    const next = {};
+    for (const key of Object.keys(record).sort(compareText)) {
+      const child = record[key];
+      if (child !== void 0) {
+        next[key] = safeRecordEntry(child);
+      }
+    }
+    return next;
+  }
+  return value;
+}
+function stableValue(value) {
+  if (Array.isArray(value)) {
+    return safeRecordEntry(value);
+  }
+  if (value !== null && typeof value === "object") {
+    return safeRecordEntry(value);
+  }
+  return value;
+}
+function stableJson(value, pretty = false) {
+  return `${JSON.stringify(stableValue(value), null, pretty ? 2 : void 0)}
+`;
+}
+function stableJsonLine(value) {
+  return JSON.stringify(stableValue(value));
+}
+async function atomicWriteIfChanged(filePath, content) {
+  const canonicalBytes = Buffer.from(content, "utf8");
+  try {
+    if ((await fs.readFile(filePath)).equals(canonicalBytes)) return false;
+  } catch (error) {
+    if (!isNotFound(error) && !isPermissionDenied(error)) throw error;
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const temporary = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`
+  );
+  try {
+    await fs.writeFile(temporary, canonicalBytes, { mode: 420 });
+    await fs.rename(temporary, filePath);
+  } catch (error) {
+    await fs.rm(temporary, { force: true }).catch(() => void 0);
+    throw error;
+  }
+  return true;
+}
+function isNotFound(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isPermissionDenied(error) {
+  return error instanceof Error && "code" in error && (error.code === "EACCES" || error.code === "EPERM");
+}
+async function mapLimit(values, limit, operation) {
+  const results = new Array(values.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(Math.max(1, limit), values.length) }, async () => {
+    while (cursor < values.length) {
+      const index = cursor++;
+      const value = values[index];
+      if (value === void 0) return;
+      results[index] = await operation(value, index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
 
-// src/schemas.ts
-import path3 from "path";
-import { z } from "zod";
+// src/search.ts
+var DEFAULT_LIMIT = 10;
+var MAX_LIMIT = 50;
+function findSymbols(map, query, options = {}) {
+  const normalized = query.trim();
+  if (!normalized) throw new Error("Symbol search query must not be empty.");
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new RangeError(`Symbol search limit must be an integer from 1 to ${MAX_LIMIT}.`);
+  }
+  const qualified = splitQualifiedSelector(normalized);
+  const queryWords = [...new Set(words(normalized))];
+  const ranked = map.symbols.map((symbol) => {
+    const nameWords = new Set(words(symbol.name));
+    const symbolWords = /* @__PURE__ */ new Set([...nameWords, ...words(symbol.file)]);
+    const unmatchedTerms = queryWords.filter((word) => !symbolWords.has(word));
+    const matched = queryWords.length - unmatchedTerms.length;
+    const nameMatches = queryWords.filter((word) => nameWords.has(word)).length;
+    let rank = matchRank(
+      symbol,
+      normalized,
+      qualified,
+      queryWords.length > 0 && unmatchedTerms.length === 0
+    );
+    if (rank === void 0 && !qualified && /\s/.test(normalized) && queryWords.length >= 3 && matched >= Math.max(2, Math.ceil(queryWords.length / 2)) && nameMatches > 0)
+      rank = 9;
+    return rank === void 0 ? void 0 : { symbol, rank, matched, nameMatches, unmatchedTerms };
+  }).filter((candidate) => candidate !== void 0).sort(
+    (left, right) => left.rank - right.rank || right.matched - left.matched || right.nameMatches - left.nameMatches || compareText(left.symbol.id, right.symbol.id)
+  );
+  const matches = ranked.slice(0, limit).map(({ symbol, rank, unmatchedTerms }) => ({
+    ...toMatch(symbol),
+    ...rank === 9 ? { unmatchedTerms } : {}
+  }));
+  return {
+    query: normalized,
+    total: ranked.length,
+    truncated: ranked.length > matches.length,
+    matches
+  };
+}
+function matchRank(symbol, query, qualified, allWordsMatch) {
+  if (symbol.id === query) return 0;
+  if (symbol.name === query) return 1;
+  const lowerQuery = query.toLowerCase();
+  if (qualified) {
+    if (symbol.file !== qualified.file) return void 0;
+    const terminalName = qualified.member.split(".").at(-1) ?? qualified.member;
+    if (symbol.name === qualified.member || symbol.name === terminalName) return 2;
+    if (symbol.name.toLowerCase() === qualified.member.toLowerCase() || symbol.name.toLowerCase() === terminalName.toLowerCase()) {
+      return 3;
+    }
+    return void 0;
+  }
+  const lowerName = symbol.name.toLowerCase();
+  const lowerFile = symbol.file.toLowerCase();
+  if (lowerName === lowerQuery) return 3;
+  if (lowerName.startsWith(lowerQuery)) return 4;
+  if (lowerName.includes(lowerQuery)) return 5;
+  if (lowerFile.includes(lowerQuery)) return 6;
+  if (allWordsMatch) return 7;
+  if (/^[a-z0-9]+$/i.test(query)) {
+    const compactQuery = compact(query);
+    const compactName = compact(symbol.name);
+    if (compactQuery.length >= 4 && compactQuery.length <= 128 && compactName.length >= 4 && compactName.length <= 128 && editDistance(compactQuery, compactName) <= (compactQuery.length >= 8 ? 2 : 1)) {
+      return 8;
+    }
+  }
+  return void 0;
+}
+function splitQualifiedSelector(value) {
+  const index = value.indexOf("#");
+  if (index <= 0 || index === value.length - 1) return void 0;
+  return { file: value.slice(0, index), member: value.slice(index + 1) };
+}
+function words(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map((word) => {
+    if (word.length > 4 && word.endsWith("ies")) return `${word.slice(0, -3)}y`;
+    if (word.length > 3 && word.endsWith("s") && !/(ss|us|is)$/.test(word))
+      return word.slice(0, -1);
+    return word;
+  });
+}
+function compact(value) {
+  return value.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+function editDistance(left, right) {
+  if (Math.abs(left.length - right.length) > 2) return 3;
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    let diagonal = previous[0] ?? 0;
+    previous[0] = leftIndex;
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const above = previous[rightIndex] ?? 0;
+      previous[rightIndex] = Math.min(
+        (previous[rightIndex - 1] ?? 0) + 1,
+        above + 1,
+        diagonal + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1)
+      );
+      diagonal = above;
+    }
+  }
+  return previous[right.length] ?? 0;
+}
+function toMatch(symbol) {
+  return {
+    id: symbol.id,
+    name: symbol.name,
+    kind: symbol.kind,
+    file: symbol.file,
+    range: symbol.range
+  };
+}
+
+// src/read-navigation.ts
+function buildReadNavigation(map, id) {
+  const symbols = new Map(map.symbols.map((symbol) => [symbol.id, symbol]));
+  const candidates = [];
+  const tests = /* @__PURE__ */ new Map();
+  for (const relation2 of map.relations) {
+    if (relation2.from !== id && relation2.to !== id) continue;
+    const classification = relation2.origin.classification;
+    if (classification !== "exact" && classification !== "framework-derived") continue;
+    if (["contains", "exports", "used-by"].includes(relation2.type)) continue;
+    const outgoing = relation2.from === id;
+    const target = outgoing ? relation2.to : relation2.from;
+    if (target === id) continue;
+    if (!outgoing && relation2.type === "calls" && classification === "exact" && /(?:^|\/)__tests__\/|\.(?:test|spec)\.[^/]+$/.test(relation2.origin.file)) {
+      const site = { file: relation2.origin.file, line: relation2.origin.line };
+      tests.set(`${site.file}:${site.line}`, site);
+      continue;
+    }
+    const symbol = symbols.get(target);
+    if (!symbol) continue;
+    candidates.push({
+      direction: outgoing ? "outgoing" : "incoming",
+      type: relation2.type,
+      id: symbol.id,
+      file: symbol.file,
+      startLine: symbol.range.startLine,
+      endLine: symbol.range.endLine,
+      classification
+    });
+  }
+  candidates.sort(
+    (a, b) => Number(a.type === "references") - Number(b.type === "references") || Number(a.direction === "incoming") - Number(b.direction === "incoming") || Number(a.classification !== "exact") - Number(b.classification !== "exact") || compareText(`${a.type}:${a.id}`, `${b.type}:${b.id}`)
+  );
+  const links = /* @__PURE__ */ new Map();
+  for (const link of candidates) {
+    const key = `${link.direction}:${link.id}`;
+    if (!links.has(key)) links.set(key, link);
+  }
+  const result = { links: [], tests: [], omittedLinks: 0, omittedTests: 0 };
+  let remaining = 3600;
+  for (const site of [...tests.values()].sort(
+    (a, b) => compareText(a.file, b.file) || a.line - b.line
+  )) {
+    const size = JSON.stringify(site).length;
+    if (result.tests.length < 4 && size <= Math.min(remaining, 900)) {
+      result.tests.push(site);
+      remaining -= size;
+    } else result.omittedTests++;
+  }
+  for (const link of links.values()) {
+    const size = JSON.stringify(link).length;
+    if (result.links.length < 8 && size <= remaining) {
+      result.links.push(link);
+      remaining -= size;
+    } else result.omittedLinks++;
+  }
+  return result;
+}
 
 // src/utils/path.ts
-import { promises as fs } from "fs";
-import path from "path";
+import { promises as fs2 } from "fs";
+import path2 from "path";
 function isAbsolutePath(value) {
   const normalized = toPosixPath(value);
-  return path.posix.isAbsolute(normalized) || /^[a-zA-Z]:[\\/]/.test(normalized) || normalized.startsWith("//");
+  return path2.posix.isAbsolute(normalized) || /^[a-zA-Z]:[\\/]/.test(normalized) || normalized.startsWith("//");
 }
 function isFileSystemUri(value) {
   return /^file:(?:\/\/|\/)/i.test(value.trim());
@@ -92,7 +303,7 @@ function looksLikeHostFilePath(value, root) {
   }
   const normalized = toPosixPath(trimmed);
   if (root) {
-    const normalizedRoot = toPosixPath(path.resolve(root));
+    const normalizedRoot = toPosixPath(path2.resolve(root));
     if (normalized === normalizedRoot || normalized.startsWith(`${normalizedRoot}/`) || normalized.includes(normalizedRoot))
       return true;
   }
@@ -110,7 +321,7 @@ function relativePosix(root, absolutePath) {
       `Path ${absolutePath} is outside project root ${root}.`
     );
   }
-  const relative = path.relative(root, absolutePath);
+  const relative = path2.relative(root, absolutePath);
   if (relative === "" || isRelativeInside(relative)) {
     return toPosixPath(relative || ".");
   }
@@ -120,31 +331,31 @@ function relativePosix(root, absolutePath) {
   );
 }
 function isPathInside(root, candidate) {
-  if (isAbsolutePath(candidate) && !path.isAbsolute(candidate)) return false;
-  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  if (isAbsolutePath(candidate) && !path2.isAbsolute(candidate)) return false;
+  const relative = path2.relative(path2.resolve(root), path2.resolve(candidate));
   return relative === "" || isRelativeInside(relative);
 }
 async function isSafeRegularFile(root, candidate) {
-  const absolute = path.resolve(candidate);
+  const absolute = path2.resolve(candidate);
   if (!isPathInside(root, absolute)) return false;
   try {
-    const stat = await fs.lstat(absolute);
+    const stat = await fs2.lstat(absolute);
     if (stat.isSymbolicLink() || !stat.isFile()) return false;
-    const [realRoot, realFile] = await Promise.all([fs.realpath(root), fs.realpath(absolute)]);
+    const [realRoot, realFile] = await Promise.all([fs2.realpath(root), fs2.realpath(absolute)]);
     return isPathInside(realRoot, realFile);
   } catch {
     return false;
   }
 }
 async function readFileInsideRoot(root, candidate) {
-  const absolute = path.resolve(candidate);
+  const absolute = path2.resolve(candidate);
   if (!await isSafeRegularFile(root, absolute)) {
     throw new CodeMapError(
       "PATH_OUTSIDE_ROOT",
       `Refusing to read an unavailable, symbolic, or out-of-root file at ${absolute}.`
     );
   }
-  return fs.readFile(absolute);
+  return fs2.readFile(absolute);
 }
 function isRelativeInside(relative) {
   const normalized = toPosixPath(relative);
@@ -153,13 +364,13 @@ function isRelativeInside(relative) {
   return normalized !== ".." && !normalized.startsWith("../") && !normalized.startsWith("..\\");
 }
 function redactAbsolutePathsInText(message, root) {
-  const normalizedRoot = path.resolve(root);
+  const normalizedRoot = path2.resolve(root);
   const redact = (candidate) => {
     const trimmed = candidate.replace(/[)\].,;:]+$/, "");
     if (!isAbsolutePath(trimmed) && !isFileSystemUri(trimmed)) return candidate;
     if (isFileSystemUri(trimmed)) return "<outside-root>";
-    const foreignWindowsPath = path.win32.isAbsolute(trimmed) && !path.posix.isAbsolute(trimmed);
-    if (foreignWindowsPath && path.posix.isAbsolute(normalizedRoot)) return "<outside-root>";
+    const foreignWindowsPath = path2.win32.isAbsolute(trimmed) && !path2.posix.isAbsolute(trimmed);
+    if (foreignWindowsPath && path2.posix.isAbsolute(normalizedRoot)) return "<outside-root>";
     try {
       if (isPathInside(normalizedRoot, trimmed)) {
         return relativePosix(normalizedRoot, trimmed);
@@ -188,95 +399,481 @@ function redactAbsolutePathsInText(message, root) {
   ).join("");
 }
 function normalizeStoredPath(value) {
-  const normalized = path.posix.normalize(toPosixPath(value));
+  const normalized = path2.posix.normalize(toPosixPath(value));
   return normalized.startsWith("./") ? normalized.slice(2) : normalized;
 }
 function sanitizeModuleSpecifier(value) {
   return isAbsolutePath(value) || isFileSystemUri(value) || hasEmbeddedAbsolutePath(value) ? "<absolute-import>" : value;
 }
 
-// src/utils/stable.ts
-import { promises as fs2 } from "fs";
-import path2 from "path";
-function compareText(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
+// src/utils/hash.ts
+import { createHash } from "crypto";
+function hashText(value) {
+  return createHash("sha256").update(value).digest("hex");
 }
-function safeRecordEntry(value) {
-  if (Array.isArray(value)) {
-    return value.map((entry) => safeRecordEntry(entry));
+
+// src/context.ts
+var behavior = /* @__PURE__ */ new Set(["function", "method", "react-hook", "react-component", "class"]);
+function budget(value, min, max, name) {
+  if (!Number.isInteger(value) || value < min || value > max)
+    throw new RangeError(`${name} must be an integer between ${min} and ${max}`);
+  return value;
+}
+async function buildSourceContext(map, query, options) {
+  const maxLines = budget(options.maxLines ?? 800, 1, 2e3, "context maxLines");
+  const maxChars = budget(options.maxChars ?? 32e3, 256, 64e3, "context maxChars");
+  const seeds = budget(options.seeds ?? 3, 1, 5, "context seeds");
+  const files = /* @__PURE__ */ new Map();
+  const indexedFiles = new Map(map.files.map((f) => [f.path, f]));
+  const sourceFile = async (symbol) => {
+    let file = files.get(symbol.file);
+    if (!file) {
+      const indexed = indexedFiles.get(symbol.file);
+      if (!indexed) throw new CodeMapError("SOURCE_NOT_FOUND", `No indexed file for ${symbol.id}`);
+      const bytes = await readFileInsideRoot(options.root, path3.resolve(options.root, symbol.file));
+      if (hashText(bytes) !== indexed.hash)
+        throw new CodeMapError(
+          "STALE_SOURCE",
+          `Source ${symbol.file} changed. Run ai-code-map scan.`
+        );
+      const lines = bytes.toString("utf8").split(/\r\n|\n|\r/);
+      if (lines.at(-1) === "") lines.pop();
+      file = { lines, included: /* @__PURE__ */ new Set() };
+      files.set(symbol.file, file);
+    }
+    validateRange(symbol, file.lines.length);
+    return file;
+  };
+  const found = findSymbols(map, query, { limit: 50 });
+  const exact = found.matches.filter((s) => s.id === query.trim() || s.name === query.trim());
+  let ranked = exact.length ? exact : [...found.matches].sort(
+    (a, b) => (a.unmatchedTerms?.length ?? 0) - (b.unmatchedTerms?.length ?? 0) || Number(!behavior.has(a.kind)) - Number(!behavior.has(b.kind))
+  );
+  const missing = ranked[0]?.unmatchedTerms?.length ?? 0;
+  if (!exact.length && missing > 0) {
+    let best = 0;
+    let promoted = [];
+    for (const match of ranked) {
+      if (!behavior.has(match.kind) || match.kind === "class" || match.unmatchedTerms?.length !== missing)
+        continue;
+      const file = await sourceFile(match);
+      const body = file.lines.slice(match.range.startLine - 1, match.range.endLine).join("\n").toLowerCase();
+      let score = 0;
+      for (const term of match.unmatchedTerms) {
+        let hits = 0;
+        for (let at = body.indexOf(term); at >= 0 && hits < 3; at = body.indexOf(term, at + term.length))
+          hits++;
+        if (hits) score += 10 + hits;
+      }
+      if (score > best) {
+        best = score;
+        promoted = [];
+      }
+      if (score === best) promoted.push(match);
+    }
+    if (best > 0) ranked = promoted;
   }
-  if (value !== null && typeof value === "object") {
-    const record = value;
-    const next = {};
-    for (const key of Object.keys(record).sort(compareText)) {
-      const child = record[key];
-      if (child !== void 0) {
-        next[key] = safeRecordEntry(child);
+  const matches = ranked.slice(0, seeds);
+  const result = {
+    query,
+    matches,
+    moreMatches: found.total - matches.length,
+    selected: [],
+    snippets: [],
+    omitted: [],
+    fileReferences: [],
+    tests: [],
+    omittedNavigation: 0,
+    usedLines: 0,
+    usedChars: 0,
+    limits: { maxLines, maxChars, seeds }
+  };
+  const byId = new Map(map.symbols.map((s) => [s.id, s]));
+  const selected = new Map(matches.map((s) => [s.id, "match"]));
+  const outgoingNeighbors = /* @__PURE__ */ new Set();
+  const tests = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    const nav = buildReadNavigation(map, match.id);
+    result.omittedNavigation += nav.omittedLinks + nav.omittedTests;
+    for (const link of nav.links) {
+      if (link.direction === "outgoing") outgoingNeighbors.add(link.id);
+      if (selected.has(link.id)) continue;
+      if (link.type === "references" && byId.get(link.id)?.kind === "class") {
+        result.omittedNavigation++;
+        continue;
       }
+      selected.set(link.id, "neighbor");
     }
-    return next;
+    for (const site of nav.tests) tests.set(`${site.file}:${site.line}`, site);
   }
-  return value;
-}
-function stableValue(value) {
-  if (Array.isArray(value)) {
-    return safeRecordEntry(value);
+  const testSites = [...tests.values()].sort(
+    (a, b) => compareText(a.file, b.file) || a.line - b.line
+  );
+  result.tests = testSites.slice(0, 8);
+  result.omittedNavigation += Math.max(0, testSites.length - result.tests.length);
+  const roots = new Set(matches.map((match) => match.id));
+  const filesById = new Map(map.files.map((file) => [file.id, file]));
+  const references = /* @__PURE__ */ new Map();
+  for (const relation2 of map.relations) {
+    if (!roots.has(relation2.to) || !["calls", "references"].includes(relation2.type)) continue;
+    const origin = relation2.origin;
+    if (!["exact", "framework-derived"].includes(origin.classification)) continue;
+    const file = filesById.get(relation2.from);
+    if (!file || file.path !== origin.file || /(?:^|\/)__tests__\/|\.(?:test|spec)\.[^/]+$/.test(file.path))
+      continue;
+    references.set(`${file.path}:${origin.line}`, { file: file.path, line: origin.line });
   }
-  if (value !== null && typeof value === "object") {
-    return safeRecordEntry(value);
+  const fileSites = [...references.values()].sort(
+    (a, b) => compareText(a.file, b.file) || a.line - b.line
+  );
+  result.fileReferences = fileSites.slice(0, 4);
+  result.omittedNavigation += Math.max(0, fileSites.length - result.fileReferences.length);
+  const requested = [];
+  const includeWindow = (id, name, file, first, last) => {
+    requested.push({ id, file: name, startLine: first, endLine: last });
+    for (let line = first; line <= last; line++) {
+      if (file.included.has(line)) continue;
+      const chars = (file.lines[line - 1]?.length ?? 0) + 1;
+      if (result.usedLines >= maxLines || result.usedChars + chars > maxChars) break;
+      file.included.add(line);
+      result.usedLines++;
+      result.usedChars += chars;
+    }
+  };
+  for (const [id] of selected) {
+    const symbol = byId.get(id);
+    if (!symbol) throw new CodeMapError("SYMBOL_NOT_FOUND", `Missing context symbol: ${id}`);
+    const file = await sourceFile(symbol);
+    includeWindow(
+      id,
+      symbol.file,
+      file,
+      Math.max(1, symbol.range.startLine - 2),
+      Math.min(file.lines.length, symbol.range.endLine + 2)
+    );
   }
-  return value;
-}
-function stableJson(value, pretty = false) {
-  return `${JSON.stringify(stableValue(value), null, pretty ? 2 : void 0)}
-`;
-}
-function stableJsonLine(value) {
-  return JSON.stringify(stableValue(value));
-}
-async function atomicWriteIfChanged(filePath, content) {
-  const canonicalBytes = Buffer.from(content, "utf8");
-  try {
-    if ((await fs2.readFile(filePath)).equals(canonicalBytes)) return false;
-  } catch (error) {
-    if (!isNotFound(error) && !isPermissionDenied(error)) throw error;
+  for (const site of result.fileReferences) {
+    const indexed = indexedFiles.get(site.file);
+    if (!indexed) throw new CodeMapError("SOURCE_NOT_FOUND", `No indexed file for ${site.file}`);
+    const file = await sourceFile({
+      id: indexed.id,
+      file: site.file,
+      range: { startLine: site.line, endLine: site.line, startColumn: 1, endColumn: 1 }
+    });
+    const small2 = file.lines.length <= 80;
+    includeWindow(
+      indexed.id,
+      site.file,
+      file,
+      small2 ? 1 : Math.max(1, site.line - 8),
+      small2 ? file.lines.length : Math.min(file.lines.length, site.line + 8)
+    );
   }
-  await fs2.mkdir(path2.dirname(filePath), { recursive: true });
-  const temporary = path2.join(
-    path2.dirname(filePath),
-    `.${path2.basename(filePath)}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`
+  const dependencies = /* @__PURE__ */ new Map();
+  for (const relation2 of map.relations) {
+    if (!outgoingNeighbors.has(relation2.from) || selected.get(relation2.from) !== "neighbor" || selected.has(relation2.to) || !["calls", "references"].includes(relation2.type) || !["exact", "framework-derived"].includes(relation2.origin.classification))
+      continue;
+    const symbol = byId.get(relation2.to);
+    if (!symbol || symbol.kind === "class" || !behavior.has(symbol.kind) && symbol.kind !== "variable")
+      continue;
+    const call = relation2.type === "calls";
+    if (!dependencies.has(symbol.id) || call) dependencies.set(symbol.id, { symbol, call });
+  }
+  const small = [...dependencies.values()].filter(
+    ({ symbol }) => symbol.range.endLine - symbol.range.startLine + 1 <= 80
   );
-  try {
-    await fs2.writeFile(temporary, canonicalBytes, { mode: 420 });
-    await fs2.rename(temporary, filePath);
-  } catch (error) {
-    await fs2.rm(temporary, { force: true }).catch(() => void 0);
-    throw error;
+  small.sort((a, b) => Number(b.call) - Number(a.call) || compareText(a.symbol.id, b.symbol.id));
+  result.omittedNavigation += dependencies.size - Math.min(small.length, 4);
+  for (const { symbol } of small.slice(0, 4)) {
+    const file = await sourceFile(symbol);
+    selected.set(symbol.id, "neighbor");
+    includeWindow(
+      symbol.id,
+      symbol.file,
+      file,
+      Math.max(1, symbol.range.startLine - 2),
+      Math.min(file.lines.length, symbol.range.endLine + 2)
+    );
   }
-  return true;
+  result.selected = [...selected].map(([id, role]) => ({ id, role }));
+  for (const request of requested) {
+    const file = files.get(request.file);
+    if (!file) continue;
+    const last = request.endLine;
+    let missingStart;
+    for (let line = request.startLine; line <= last + 1; line++) {
+      const missing2 = line <= last && !file.included.has(line);
+      if (missing2 && missingStart === void 0) missingStart = line;
+      if (!missing2 && missingStart !== void 0) {
+        result.omitted.push({ ...request, startLine: missingStart, endLine: line - 1 });
+        missingStart = void 0;
+      }
+    }
+  }
+  for (const [name, file] of files) {
+    const lines = [...file.included].sort((a, b) => a - b);
+    let start, end = 0;
+    const append = () => {
+      if (start === void 0) return;
+      result.snippets.push({
+        file: name,
+        startLine: start,
+        endLine: end,
+        source: file.lines.slice(start - 1, end).join("\n")
+      });
+    };
+    for (const line of lines) {
+      if (start === void 0 || line !== end + 1) {
+        append();
+        start = line;
+      }
+      end = line;
+    }
+    append();
+  }
+  return result;
 }
-function isNotFound(error) {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
+function validateRange(symbol, length) {
+  const { startLine, endLine } = symbol.range;
+  if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine || endLine > length)
+    throw new CodeMapError(
+      "INVALID_SOURCE_RANGE",
+      `Mapped range is outside ${symbol.file}. Run ai-code-map scan.`
+    );
 }
-function isPermissionDenied(error) {
-  return error instanceof Error && "code" in error && (error.code === "EACCES" || error.code === "EPERM");
+function formatSourceContext(result) {
+  if (!result.matches.length)
+    return "No indexed matches. Include action and subject words, or use find/targeted rg. No source was read.";
+  const lines = [
+    `Context: ${result.selected.length} selected symbols, ${result.usedLines}/${result.limits.maxLines} source lines; ${result.usedChars}/${result.limits.maxChars} source characters.`,
+    `Matches: ${result.matches.map((m) => `${m.name}${m.unmatchedTerms?.length ? ` (unmatched: ${m.unmatchedTerms.join(", ")})` : ""}`).join(", ")}.`,
+    "Scope: matches, direct exact/framework-derived neighbors, file-level reference sites and up to four small outgoing dependencies; reference-only classes are not expanded. Source determines behavior."
+  ];
+  if (result.fileReferences.length)
+    lines.push(
+      `File reference sites: ${result.fileReferences.map((site) => `${site.file}:${site.line}`).join(", ")}.`
+    );
+  for (const snippet of result.snippets) {
+    lines.push(`
+${snippet.file}:${snippet.startLine}-${snippet.endLine}`);
+    lines.push(...snippet.source.split("\n").map((line, i) => `${snippet.startLine + i}: ${line}`));
+  }
+  if (result.tests.length)
+    lines.push(
+      "\nTest call sites (navigation hints, not coverage):",
+      ...result.tests.map((s) => `${s.file}:${s.line}`)
+    );
+  if (result.omitted.length)
+    lines.push(
+      "\nBudget omitted source; read only a needed missing range:",
+      ...result.omitted.slice(0, 12).map((o) => `${o.file}:${o.startLine}-${o.endLine} (${o.id})`),
+      ...result.omitted.length > 12 ? [`${result.omitted.length - 12} further omitted ranges; use --json for all.`] : []
+    );
+  lines.push(
+    `
+Other search matches: ${result.moreMatches}; navigation entries omitted: ${result.omittedNavigation}. Follow up only for a missing fact; reuse source already returned.`
+  );
+  return lines.join("\n");
 }
-async function mapLimit(values, limit, operation) {
-  const results = new Array(values.length);
-  let cursor = 0;
-  const workers = Array.from({ length: Math.min(Math.max(1, limit), values.length) }, async () => {
-    while (cursor < values.length) {
-      const index = cursor++;
-      const value = values[index];
-      if (value === void 0) return;
-      results[index] = await operation(value, index);
-    }
+
+// src/read.ts
+import path4 from "path";
+async function readSymbolSource(map, id, options) {
+  const limit = options.limit ?? 80;
+  const offset = options.offset ?? 0;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+    throw new RangeError("read limit must be an integer between 1 and 200");
+  if (!Number.isSafeInteger(offset) || offset < 0)
+    throw new RangeError("read offset must be a nonnegative safe integer");
+  const symbol = map.symbols.find((item) => item.id === id);
+  if (!symbol)
+    throw new CodeMapError(
+      "SYMBOL_NOT_FOUND",
+      "Use an exact symbol ID returned by ai-code-map find."
+    );
+  const file = map.files.find((item) => item.path === symbol.file);
+  const absolute = path4.resolve(options.root, symbol.file);
+  if (!file)
+    throw new CodeMapError("SOURCE_NOT_FOUND", "Symbol has no indexed file. Run ai-code-map scan.");
+  const bytes = await readFileInsideRoot(options.root, absolute);
+  if (hashText(bytes) !== file.hash)
+    throw new CodeMapError(
+      "STALE_SOURCE",
+      `Source ${symbol.file} changed. Run ai-code-map scan before reading its mapped range.`
+    );
+  const lines = bytes.toString("utf8").split(/\r\n|\n|\r/);
+  if (lines.at(-1) === "") lines.pop();
+  const first = Math.max(1, symbol.range.startLine - 2);
+  const last = Math.min(lines.length, symbol.range.endLine + 2);
+  if (symbol.range.startLine < 1 || symbol.range.endLine > lines.length || first > last)
+    throw new CodeMapError(
+      "INVALID_SOURCE_RANGE",
+      "Mapped range is outside the source. Run ai-code-map scan."
+    );
+  if (offset >= last - first + 1) throw new RangeError("read offset is outside the symbol window");
+  const startLine = first + offset;
+  const endLine = Math.min(last, startLine + limit - 1);
+  const source = lines.slice(startLine - 1, endLine).join("\n");
+  if (source.length > 12e3)
+    throw new CodeMapError(
+      "SOURCE_WINDOW_TOO_LARGE",
+      "Source window exceeds 12000 characters. Reduce --limit; for a single oversized line use targeted source search."
+    );
+  const truncated = endLine < last;
+  return {
+    id: symbol.id,
+    file: symbol.file,
+    symbolRange: symbol.range,
+    startLine,
+    endLine,
+    source,
+    truncated,
+    ...truncated ? { nextOffset: offset + endLine - startLine + 1 } : {},
+    ...offset === 0 ? { navigation: buildReadNavigation(map, id) } : {}
+  };
+}
+
+// src/project-map.ts
+function buildProjectMap(map) {
+  const refs = /* @__PURE__ */ new Map();
+  const ref = (id) => {
+    const value = refs.get(id);
+    if (!value) throw new Error(`Unknown map endpoint: ${id}`);
+    return value;
+  };
+  const files = [...map.files].sort((a, b) => compareText(a.path, b.path)).map((file, index) => {
+    const key = `f${index + 1}`;
+    refs.set(file.id, key);
+    return { ref: key, id: file.id, path: file.path };
   });
-  await Promise.all(workers);
-  return results;
+  const symbols = [...map.symbols].sort((a, b) => compareText(a.id, b.id)).map((symbol, index) => {
+    const key = `s${index + 1}`;
+    refs.set(symbol.id, key);
+    return {
+      ref: key,
+      id: symbol.id,
+      name: symbol.name,
+      kind: symbol.kind,
+      file: ref(`file:${symbol.file}`),
+      range: { ...symbol.range }
+    };
+  });
+  const otherIds = /* @__PURE__ */ new Set();
+  for (const relation2 of map.relations) {
+    if (!refs.has(relation2.from)) otherIds.add(relation2.from);
+    if (!refs.has(relation2.to)) otherIds.add(relation2.to);
+  }
+  const endpoints = [...otherIds].sort(compareText).map((id, index) => {
+    const key = `e${index + 1}`;
+    refs.set(id, key);
+    return { ref: key, id };
+  });
+  const groups = /* @__PURE__ */ new Map();
+  for (const relation2 of map.relations) {
+    const from = ref(relation2.from);
+    const to = ref(relation2.to);
+    const classification = relation2.origin.classification;
+    const key = JSON.stringify([from, relation2.type, classification]);
+    let group = groups.get(key);
+    if (!group) {
+      group = { from, type: relation2.type, classification, targets: /* @__PURE__ */ new Map() };
+      groups.set(key, group);
+    }
+    group.targets.set(to, (group.targets.get(to) ?? 0) + 1);
+  }
+  const relations = [...groups.entries()].sort(([a], [b]) => compareText(a, b)).map(([, group]) => ({
+    ...group,
+    targets: [...group.targets.entries()].sort(([a], [b]) => compareText(a, b)).map(([ref2, count]) => ({ ref: ref2, count }))
+  }));
+  return {
+    project: map.project.name,
+    counts: {
+      files: files.length,
+      symbols: symbols.length,
+      endpoints: endpoints.length,
+      relationGroups: relations.length,
+      relationRecords: map.relations.length
+    },
+    files,
+    symbols,
+    endpoints,
+    relations
+  };
 }
+function formatProjectMap(map) {
+  const { counts } = map;
+  return [
+    `Complete structural map: ${map.project}`,
+    `${counts.files} files; ${counts.symbols} symbols; ${counts.endpoints} other endpoints; ${counts.relationRecords} relation records in ${counts.relationGroups} adjacency groups.`,
+    "All indexed nodes and relations included. No source, signatures, facts or per-occurrence evidence.",
+    "f/s/e refs are local to this output. Read source using a symbol's stable ID, not its short ref.",
+    "Relations: FROM TYPE [evidence classification] -> TARGET[*occurrences]. Heuristic/derived links are not exact calls.",
+    "",
+    "Files (ref path)",
+    ...map.files.map((file) => `${file.ref} ${file.path}`),
+    "",
+    "Symbols (ref file:start-end kind stable-ID)",
+    ...map.symbols.map(
+      (symbol) => `${symbol.ref} ${symbol.file}:${symbol.range.startLine}-${symbol.range.endLine} ${symbol.kind} ${symbol.id}`
+    ),
+    "",
+    "Other endpoints (ref ID)",
+    ...map.endpoints.map((endpoint) => `${endpoint.ref} ${endpoint.id}`),
+    "",
+    "Relations",
+    ...map.relations.map(
+      (group) => `${group.from} ${group.type} [${group.classification}] -> ${group.targets.map((target) => `${target.ref}${target.count > 1 ? `*${target.count}` : ""}`).join(",")}`
+    ),
+    "",
+    "End of map. If this marker is missing, the calling tool may have truncated the output."
+  ].join("\n");
+}
+
+// src/constants.ts
+var SCHEMA_VERSION = 4;
+var CONFIG_VERSION = 1;
+var ANALYZER_VERSION = "0.4.0";
+var DEFAULT_SYNTAX_PARSER = "typescript-compiler-syntax";
+var DEFAULT_SEMANTIC_RESOLVER = "typescript-program";
+var DEFAULT_ANALYZER_NAMES = ["typescript-node", "react"];
+var DEFAULT_PRODUCER_ID = "ai-code-map/default-pipeline";
+var CUSTOM_PRODUCER_ID = "ai-code-map/custom-pipeline";
+var PRODUCER_CONTRACT_VERSION = 1;
+var DEFAULT_OUTPUT = ".ai/code-map";
+var DEFAULT_INCLUDE = [
+  "src/**/*",
+  "app/**/*",
+  "pages/**/*",
+  "lib/**/*",
+  "server/**/*",
+  "*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"
+];
+var DEFAULT_EXCLUDE = [
+  "**/node_modules/**",
+  "**/.next/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/.git/**",
+  "**/.ai/**",
+  "**/*.generated.*"
+];
+var MAP_COMPANION_ARTIFACTS = [
+  "overview.md",
+  "project.json",
+  "files.jsonl",
+  "symbols.jsonl",
+  "relations.jsonl",
+  "diagnostics.json"
+];
+
+// src/config.ts
+import { promises as fs3 } from "fs";
+import path6 from "path";
 
 // src/schemas.ts
+import path5 from "path";
+import { z } from "zod";
 var JsonValueSchema = z.json();
 var LanguageSchema = z.enum(["ts", "tsx", "js", "jsx", "mts", "cts", "mjs", "cjs"]);
 var FrameworkSchema = z.enum(["typescript", "node", "react", "nextjs", "nestjs"]);
@@ -637,7 +1234,7 @@ var CodeMapSchema = CodeMapShapeSchema.superRefine((map, context) => {
           message: "configured compiler-unit ID must be derived from its config path"
         });
       }
-      if (unit.root !== normalizeStoredPath(path3.posix.dirname(unit.config))) {
+      if (unit.root !== normalizeStoredPath(path5.posix.dirname(unit.config))) {
         context.addIssue({
           code: "custom",
           path: ["project", "compilerUnits", index, "root"],
@@ -966,9 +1563,9 @@ var CodeMapSchema = CodeMapShapeSchema.superRefine((map, context) => {
     }
   }
 });
-function addDuplicateIssue(context, seen, value, path16) {
+function addDuplicateIssue(context, seen, value, path18) {
   if (seen.has(value)) {
-    context.addIssue({ code: "custom", path: path16, message: `duplicate value ${value}` });
+    context.addIssue({ code: "custom", path: path18, message: `duplicate value ${value}` });
   }
   seen.add(value);
 }
@@ -1006,9 +1603,9 @@ function endpointSourceFile(endpoint, files, symbols) {
 
 // src/config.ts
 function createDefaultConfig(root, configPath, output) {
-  const configDirectory = path4.dirname(configPath);
-  const relativeRoot = toPosixPath(path4.relative(configDirectory, root) || ".");
-  const outputValue = output ? path4.isAbsolute(output) ? toPosixPath(path4.relative(root, output)) : toPosixPath(output) : DEFAULT_OUTPUT;
+  const configDirectory = path6.dirname(configPath);
+  const relativeRoot = toPosixPath(path6.relative(configDirectory, root) || ".");
+  const outputValue = output ? path6.isAbsolute(output) ? toPosixPath(path6.relative(root, output)) : toPosixPath(output) : DEFAULT_OUTPUT;
   return {
     version: CONFIG_VERSION,
     root: relativeRoot,
@@ -1021,36 +1618,36 @@ function createDefaultConfig(root, configPath, output) {
   };
 }
 async function findProjectRoot(start = process.cwd()) {
-  let current = path4.resolve(start);
+  let current = path6.resolve(start);
   try {
-    if (!(await fs3.stat(current)).isDirectory()) current = path4.dirname(current);
+    if (!(await fs3.stat(current)).isDirectory()) current = path6.dirname(current);
   } catch (error) {
     throw new CodeMapError("ROOT_NOT_FOUND", `Cannot access project root candidate ${current}.`, {
       cause: error
     });
   }
-  while (current !== path4.dirname(current)) {
-    const packagePath = path4.join(current, "package.json");
+  while (current !== path6.dirname(current)) {
+    const packagePath = path6.join(current, "package.json");
     if (await isSafeRegularFile(current, packagePath)) {
       return await fs3.realpath(current);
     }
-    const parent = path4.dirname(current);
+    const parent = path6.dirname(current);
     current = parent;
   }
   throw new CodeMapError(
     "PROJECT_NOT_FOUND",
-    `No package.json was found at or above ${path4.resolve(start)}. Pass --root explicitly.`
+    `No package.json was found at or above ${path6.resolve(start)}. Pass --root explicitly.`
   );
 }
 function resolveConfigArgument(base, config) {
-  if (!config) return path4.join(base, DEFAULT_OUTPUT, "config.json");
-  return path4.resolve(base, config);
+  if (!config) return path6.join(base, DEFAULT_OUTPUT, "config.json");
+  return path6.resolve(base, config);
 }
 async function resolveConfiguration(options = {}) {
-  const requestedStart = path4.resolve(options.root ?? process.cwd());
+  const requestedStart = path6.resolve(options.root ?? process.cwd());
   const discoveredRoot = await findProjectRoot(requestedStart);
-  const configPath = options.config ? resolveConfigArgument(requestedStart, options.config) : path4.join(
-    options.output ? path4.resolve(discoveredRoot, options.output) : path4.join(discoveredRoot, DEFAULT_OUTPUT),
+  const configPath = options.config ? resolveConfigArgument(requestedStart, options.config) : path6.join(
+    options.output ? path6.resolve(discoveredRoot, options.output) : path6.join(discoveredRoot, DEFAULT_OUTPUT),
     "config.json"
   );
   let parsed;
@@ -1076,7 +1673,7 @@ async function resolveConfiguration(options = {}) {
       throw error;
     }
   }
-  const configuredRoot = configExists ? path4.resolve(path4.dirname(configPath), parsed.root) : discoveredRoot;
+  const configuredRoot = configExists ? path6.resolve(path6.dirname(configPath), parsed.root) : discoveredRoot;
   let root;
   try {
     root = await fs3.realpath(configuredRoot);
@@ -1088,14 +1685,14 @@ async function resolveConfiguration(options = {}) {
     );
   }
   const outputValue = options.output ?? parsed.output;
-  const outputDir = path4.isAbsolute(outputValue) ? path4.normalize(outputValue) : path4.resolve(root, outputValue);
+  const outputDir = path6.isAbsolute(outputValue) ? path6.normalize(outputValue) : path6.resolve(root, outputValue);
   return { root, outputDir, configPath, config: parsed, configExists };
 }
 async function initProject(options = {}) {
-  const requestedStart = path4.resolve(options.root ?? process.cwd());
+  const requestedStart = path6.resolve(options.root ?? process.cwd());
   const root = await findProjectRoot(requestedStart);
-  const defaultOutputDir = options.output ? path4.resolve(root, options.output) : path4.join(root, DEFAULT_OUTPUT);
-  const configPath = options.config ? path4.resolve(requestedStart, options.config) : path4.join(defaultOutputDir, "config.json");
+  const defaultOutputDir = options.output ? path6.resolve(root, options.output) : path6.join(root, DEFAULT_OUTPUT);
+  const configPath = options.config ? path6.resolve(requestedStart, options.config) : path6.join(defaultOutputDir, "config.json");
   try {
     await fs3.access(configPath);
     if (!options.force) return { root, configPath, created: false };
@@ -1121,7 +1718,7 @@ import { performance } from "perf_hooks";
 
 // src/analyze.ts
 import { promises as fs9 } from "fs";
-import path15 from "path";
+import path17 from "path";
 import ts10 from "typescript";
 
 // src/ids.ts
@@ -1172,15 +1769,9 @@ function symbolPrefix(kind) {
   }
 }
 
-// src/utils/hash.ts
-import { createHash } from "crypto";
-function hashText(value) {
-  return createHash("sha256").update(value).digest("hex");
-}
-
 // src/analyzers/core.ts
 import { isBuiltin } from "module";
-import path5 from "path";
+import path7 from "path";
 import ts2 from "typescript";
 
 // src/analyzers/helpers.ts
@@ -1305,8 +1896,8 @@ function makeSymbol(context, node, kind, options = {}) {
   };
 }
 function compactText(value, maxLength = 500) {
-  const compact = value.replace(/\s+/g, " ").trim();
-  return compact.length > maxLength ? `${compact.slice(0, maxLength - 1)}\u2026` : compact;
+  const compact2 = value.replace(/\s+/g, " ").trim();
+  return compact2.length > maxLength ? `${compact2.slice(0, maxLength - 1)}\u2026` : compact2;
 }
 function visit(node, callback) {
   callback(node);
@@ -1617,13 +2208,13 @@ function resolveImportedExpressionTarget(context, expression) {
   const binding = importedExpressionBinding(context, expression, true);
   if (!binding?.resolved) return void 0;
   if (ts2.isIdentifier(expression)) {
-    const sourceFile2 = context.program.getSourceFile(path5.resolve(context.root, binding.resolved));
+    const sourceFile2 = context.program.getSourceFile(path7.resolve(context.root, binding.resolved));
     if (!sourceFile2) return void 0;
     const declaration2 = findExportedDeclaration(sourceFile2, binding.imported);
     return declaration2 ? declarationToId(declaration2, binding.resolved) : void 0;
   }
   if (!ts2.isPropertyAccessExpression(expression)) return void 0;
-  const sourceFile = context.program.getSourceFile(path5.resolve(context.root, binding.resolved));
+  const sourceFile = context.program.getSourceFile(path7.resolve(context.root, binding.resolved));
   if (!sourceFile) return void 0;
   const declaration = findExportedDeclaration(sourceFile, expression.name.text);
   return declaration ? declarationToId(declaration, binding.resolved) : void 0;
@@ -2569,7 +3160,7 @@ function relativeFromRoot(context, absolutePath) {
 }
 
 // src/analyzers/nextjs.ts
-import path6 from "path";
+import path8 from "path";
 import ts4 from "typescript";
 var ROUTE_GROUP_SEGMENT = /^\(.*\)$/;
 var ROUTE_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
@@ -2582,7 +3173,7 @@ var NextJsAnalyzer = class {
     registeredNextJsAnalyzers.add(this);
   }
   supports(context) {
-    if (!APP_FILES_EXTENSIONS.has(path6.extname(context.relativePath).toLowerCase())) return false;
+    if (!APP_FILES_EXTENSIONS.has(path8.extname(context.relativePath).toLowerCase())) return false;
     return context.relativePath.startsWith("app/") || context.relativePath.startsWith("pages/") || context.relativePath === "middleware.ts";
   }
   analyze(context) {
@@ -2829,7 +3420,7 @@ function collectContainingAppLayouts(relativePath, context) {
   return candidates;
 }
 function programContainsSourceFile(context, candidateRelative) {
-  const absolute = path6.resolve(context.root, candidateRelative);
+  const absolute = path8.resolve(context.root, candidateRelative);
   return context.program.getSourceFiles().some((source) => normalizeSourcePath(source.fileName) === normalizeSourcePath(absolute));
 }
 function normalizeSourcePath(value) {
@@ -2867,7 +3458,7 @@ function makeRelation2(from, type, to, context, node, confidence, explanation) {
 }
 
 // src/analyzers/react.ts
-import path7 from "path";
+import path9 from "path";
 import ts5 from "typescript";
 var REACT_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
 var REACT_BUILTIN_HOOKS = /* @__PURE__ */ new Set([
@@ -2884,7 +3475,7 @@ var ReactAnalyzer = class {
   name = "react";
   version = ANALYZER_VERSION;
   supports(context) {
-    const extension = path7.extname(context.relativePath).toLowerCase();
+    const extension = path9.extname(context.relativePath).toLowerCase();
     if (!REACT_EXTENSIONS.has(extension)) return false;
     return hasDirective2(context.sourceFile, "use client") || hasDirective2(context.sourceFile, "use server") || hasReactImport(context.sourceFile) || hasAnyJsx(context.sourceFile);
   }
@@ -3157,11 +3748,11 @@ function collectComponentFacts(context, name, parameters, body, profile) {
   if (props.length > 0) {
     facts.props = `${name.toLowerCase()}props:${props.join(",")}`;
   }
-  const behavior = collectComponentBehavior(context, body, profile);
-  if (behavior.state.length > 0) facts.state = behavior.state.join(",");
-  if (behavior.memo.length > 0) facts.memo = behavior.memo.join(",");
-  if (behavior.effects.length > 0) facts.effects = behavior.effects.join(",");
-  if (behavior.customHooks.length > 0) facts.hooks = behavior.customHooks.join(",");
+  const behavior2 = collectComponentBehavior(context, body, profile);
+  if (behavior2.state.length > 0) facts.state = behavior2.state.join(",");
+  if (behavior2.memo.length > 0) facts.memo = behavior2.memo.join(",");
+  if (behavior2.effects.length > 0) facts.effects = behavior2.effects.join(",");
+  if (behavior2.customHooks.length > 0) facts.hooks = behavior2.customHooks.join(",");
   return facts;
 }
 function collectProps(context, parameter) {
@@ -3264,11 +3855,11 @@ function resolveReactCandidateWithChecker(context, candidate, kind) {
   const sourceFile = declaration.getSourceFile();
   let relative;
   try {
-    relative = path7.relative(context.root, sourceFile.fileName).split(path7.sep).join("/");
+    relative = path9.relative(context.root, sourceFile.fileName).split(path9.sep).join("/");
   } catch {
     return void 0;
   }
-  if (relative === "" || relative === ".." || relative.startsWith("../") || path7.isAbsolute(relative) || context.indexedSourcePaths && !context.indexedSourcePaths.has(relative)) {
+  if (relative === "" || relative === ".." || relative.startsWith("../") || path9.isAbsolute(relative) || context.indexedSourcePaths && !context.indexedSourcePaths.has(relative)) {
     return void 0;
   }
   return symbolId(kind, relative, declarationToSymbolName(declaration) ?? symbol.getName());
@@ -3288,8 +3879,8 @@ function resolveImportedReactSymbol(context, profile, importedName, kind) {
     if (actualName) return symbolId(kind, relative2, actualName);
     return symbolId(kind, relative2, source.imported);
   }
-  const relative = path7.posix.normalize(
-    path7.posix.join(path7.posix.dirname(context.relativePath), source.source)
+  const relative = path9.posix.normalize(
+    path9.posix.join(path9.posix.dirname(context.relativePath), source.source)
   );
   const candidates = [
     relative,
@@ -3304,7 +3895,7 @@ function resolveImportedReactSymbol(context, profile, importedName, kind) {
     `${relative}/index.jsx`
   ];
   for (const candidate of candidates) {
-    const absolute = path7.resolve(context.root, candidate);
+    const absolute = path9.resolve(context.root, candidate);
     const imported = context.program.getSourceFile(absolute);
     if (imported) {
       const declaration = findExportedDeclaration2(imported, source.imported);
@@ -3468,12 +4059,12 @@ function makeRelation3(from, type, to, context, node, confidence, explanation) {
 
 // src/freshness.ts
 import { promises as fs8 } from "fs";
-import path14 from "path";
+import path16 from "path";
 import ts8 from "typescript";
 
 // src/compiler-units.ts
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "fs";
-import path8 from "path";
+import path10 from "path";
 import fg from "fast-glob";
 import ts6 from "typescript";
 var CONFIG_PATTERNS = ["**/tsconfig.json", "**/jsconfig.json", "**/tsconfig.*.json"];
@@ -3500,7 +4091,7 @@ async function buildCompilerUnitGraph(root, config, sources, workspaces) {
     if (!candidate) continue;
     const logical = normalizeStoredPath(candidate);
     if (parsedByPath.has(logical)) continue;
-    const absolute = path8.resolve(realRoot, logical);
+    const absolute = path10.resolve(realRoot, logical);
     const node = parseConfigNode(realRoot, absolute, fileSystem, diagnostics);
     if (!node) continue;
     parsedByPath.set(node.relativePath, node);
@@ -3522,11 +4113,11 @@ async function buildCompilerUnitGraph(root, config, sources, workspaces) {
   const extendedDependencies = new Set([...parsedByPath.values()].flatMap((node) => node.extends));
   const referenceTargets = new Set([...parsedByPath.values()].flatMap((node) => node.references));
   for (const node of parsedByPath.values()) {
-    const directory = normalizeStoredPath(path8.posix.dirname(node.relativePath));
+    const directory = normalizeStoredPath(path10.posix.dirname(node.relativePath));
     const atBoundary = boundaryPaths.includes(directory);
     const intersects = [...node.sourceFileKeys].some((file) => indexedKeys.has(file));
     const conventional = ["tsconfig.json", "jsconfig.json"].includes(
-      path8.posix.basename(node.relativePath)
+      path10.posix.basename(node.relativePath)
     );
     const extendsOnlyBase = extendedDependencies.has(node.relativePath) && !node.hasOwnFileSelection && !conventional && !referenceTargets.has(node.relativePath) && configured !== node.relativePath;
     if (!extendsOnlyBase && (atBoundary || intersects)) seedPaths.add(node.relativePath);
@@ -3558,10 +4149,10 @@ async function buildCompilerUnitGraph(root, config, sources, workspaces) {
     if (jsSource && !owner && !jsFallbackWarnings.has(source.relativePath)) {
       jsFallbackWarnings.add(source.relativePath);
       const underDisallowingConfig = nodes.some(
-        (node) => !node.allowJs && isPathInside(path8.dirname(node.absolutePath), source.absolutePath)
+        (node) => !node.allowJs && isPathInside(path10.dirname(node.absolutePath), source.absolutePath)
       );
       const underAllowingConfig = nodes.some(
-        (node) => node.allowJs && isPathInside(path8.dirname(node.absolutePath), source.absolutePath)
+        (node) => node.allowJs && isPathInside(path10.dirname(node.absolutePath), source.absolutePath)
       );
       const reason = selected.length > 0 || underDisallowingConfig ? "the applicable configuration does not allow JavaScript" : underAllowingConfig ? "the nearby JavaScript-enabled configuration does not include the file" : "no eligible configuration includes the file";
       diagnostics.push({
@@ -3579,7 +4170,7 @@ async function buildCompilerUnitGraph(root, config, sources, workspaces) {
     ownedByUnit.set(ownerId, owned);
   }
   const units = nodes.map((node) => {
-    const rootPath = normalizeStoredPath(path8.posix.dirname(node.relativePath));
+    const rootPath = normalizeStoredPath(path10.posix.dirname(node.relativePath));
     const id = configuredCompilerUnitId(node.relativePath);
     return {
       record: {
@@ -3635,11 +4226,11 @@ async function discoverConfigCandidates(root, config, diagnostics) {
     const configured = configuredTsconfigPath(root, config.tsconfig, diagnostics);
     if (configured) candidates.add(configured);
   }
-  return [...candidates].filter((candidate) => safeRegularFile(root, path8.resolve(root, candidate))).sort(compareText);
+  return [...candidates].filter((candidate) => safeRegularFile(root, path10.resolve(root, candidate))).sort(compareText);
 }
 function configuredTsconfigPath(root, configured, diagnostics) {
   if (!configured) return void 0;
-  const absolute = path8.resolve(root, configured);
+  const absolute = path10.resolve(root, configured);
   if (!isPathInside(root, absolute) || !safeRegularFile(root, absolute)) {
     diagnostics.push(
       graphDiagnostic("The configured TypeScript project is unavailable or unsafe.")
@@ -3663,13 +4254,13 @@ function parseConfigNode(root, absolutePath, fileSystem, diagnostics) {
     );
     return void 0;
   }
-  const host = fileSystem.parseHost(path8.dirname(absolutePath));
+  const host = fileSystem.parseHost(path10.dirname(absolutePath));
   let parsed;
   try {
     parsed = ts6.parseJsonSourceFileConfigFileContent(
       source,
       host,
-      path8.dirname(absolutePath),
+      path10.dirname(absolutePath),
       void 0,
       absolutePath,
       void 0,
@@ -3682,7 +4273,7 @@ function parseConfigNode(root, absolutePath, fileSystem, diagnostics) {
     );
     return void 0;
   }
-  const optionSafety = sanitizeCompilerOptions(parsed.options, root, path8.dirname(absolutePath));
+  const optionSafety = sanitizeCompilerOptions(parsed.options, root, path10.dirname(absolutePath));
   if (!optionSafety.valid) {
     diagnostics.push(
       graphDiagnostic("A TypeScript configuration option escaped the selected root.", relativePath)
@@ -3734,7 +4325,7 @@ function parseConfigNode(root, absolutePath, fileSystem, diagnostics) {
     sourceFileKeys: new Set(parsedSourceFiles.map(canonicalPath)),
     references: [...new Set(references)].sort(compareText),
     extends: extended,
-    pathAliases: normalizePathAliases(root, path8.dirname(absolutePath), parsed.options),
+    pathAliases: normalizePathAliases(root, path10.dirname(absolutePath), parsed.options),
     hasOwnFileSelection: Boolean(
       rawConfig && (Object.prototype.hasOwnProperty.call(rawConfig, "files") || Object.prototype.hasOwnProperty.call(rawConfig, "include"))
     ),
@@ -3746,7 +4337,7 @@ function sanitizeCompilerOptions(options, root, unitDirectory) {
   let valid = true;
   const validatePath = (value) => {
     if (!value) return value;
-    const absolute = path8.resolve(value);
+    const absolute = path10.resolve(value);
     if (!isPathInside(root, absolute)) {
       valid = false;
       return void 0;
@@ -3768,7 +4359,7 @@ function sanitizeCompilerOptions(options, root, unitDirectory) {
     options.typeRoots = boundedTypeRoots(root, unitDirectory);
   }
   sanitizeCompilerPathAliases(options);
-  options.configFilePath = options.configFilePath ?? path8.join(unitDirectory, "tsconfig.json");
+  options.configFilePath = options.configFilePath ?? path10.join(unitDirectory, "tsconfig.json");
   return { valid };
 }
 function sanitizeCompilerPathAliases(options) {
@@ -3785,11 +4376,11 @@ function sanitizeCompilerPathAliases(options) {
 }
 function boundedTypeRoots(root, start) {
   const values = [];
-  let current = path8.resolve(start);
+  let current = path10.resolve(start);
   while (isPathInside(root, current)) {
-    values.push(path8.join(current, "node_modules", "@types"));
-    if (current === path8.resolve(root)) break;
-    const parent = path8.dirname(current);
+    values.push(path10.join(current, "node_modules", "@types"));
+    if (current === path10.resolve(root)) break;
+    const parent = path10.dirname(current);
     if (parent === current) break;
     current = parent;
   }
@@ -3804,7 +4395,7 @@ function normalizePathAliases(root, configDirectory, options) {
     const normalized = [];
     for (const target of targets) {
       if (!isSafeRelativePathPattern(target)) continue;
-      const absolute = path8.resolve(base, target);
+      const absolute = path10.resolve(base, target);
       if (!isPathInside(root, absolute)) continue;
       normalized.push(relativePosix(root, absolute));
     }
@@ -3817,8 +4408,8 @@ function chooseOwner(eligible, sourceFile, root, boundaries) {
     const packageDepthA = deepestSharedBoundaryDepth(a.absolutePath, sourceFile, root, boundaries);
     const packageDepthB = deepestSharedBoundaryDepth(b.absolutePath, sourceFile, root, boundaries);
     if (packageDepthA !== packageDepthB) return packageDepthB - packageDepthA;
-    const directoryDepthA = ancestorDepth(path8.dirname(a.absolutePath), sourceFile, root);
-    const directoryDepthB = ancestorDepth(path8.dirname(b.absolutePath), sourceFile, root);
+    const directoryDepthA = ancestorDepth(path10.dirname(a.absolutePath), sourceFile, root);
+    const directoryDepthB = ancestorDepth(path10.dirname(b.absolutePath), sourceFile, root);
     if (directoryDepthA !== directoryDepthB) return directoryDepthB - directoryDepthA;
     return compareText(a.relativePath, b.relativePath);
   })[0];
@@ -3826,7 +4417,7 @@ function chooseOwner(eligible, sourceFile, root, boundaries) {
 function deepestSharedBoundaryDepth(configPath, sourcePath, root, boundaries) {
   let depth = -1;
   for (const boundary of boundaries) {
-    const absolute = path8.resolve(root, boundary);
+    const absolute = path10.resolve(root, boundary);
     if (isPathInside(absolute, configPath) && isPathInside(absolute, sourcePath)) {
       depth = Math.max(depth, pathDepth(relativePosix(root, absolute)));
     }
@@ -3840,12 +4431,12 @@ function pathDepth(value) {
   return value === "." ? 0 : value.split("/").length;
 }
 function isJavaScriptSourceFile(filePath) {
-  const extension = path8.extname(filePath).toLowerCase();
+  const extension = path10.extname(filePath).toLowerCase();
   return extension === ".js" || extension === ".jsx" || extension === ".mjs" || extension === ".cjs";
 }
 function safeRegularFile(root, candidate) {
   try {
-    const absolute = path8.resolve(candidate);
+    const absolute = path10.resolve(candidate);
     if (!isPathInside(root, absolute)) return false;
     if (lstatSync(absolute).isSymbolicLink() || !statSync(absolute).isFile()) return false;
     return isPathInside(realpathSync(root), realpathSync(absolute));
@@ -3858,7 +4449,7 @@ function canonicalPath(fileName) {
     const real = realpathSync(fileName);
     return ts6.sys.useCaseSensitiveFileNames ? real : real.toLowerCase();
   } catch {
-    const absolute = path8.resolve(fileName);
+    const absolute = path10.resolve(fileName);
     return ts6.sys.useCaseSensitiveFileNames ? absolute : absolute.toLowerCase();
   }
 }
@@ -3885,7 +4476,7 @@ var BoundedTypeScriptFileSystem = class {
   observedInputs = /* @__PURE__ */ new Map();
   constructor(root) {
     this.root = realpathSync(root);
-    this.typeScriptLib = realpathSync(path8.dirname(ts6.getDefaultLibFilePath({})));
+    this.typeScriptLib = realpathSync(path10.dirname(ts6.getDefaultLibFilePath({})));
   }
   fileExists = (fileName) => {
     const absolute = this.absolute(fileName);
@@ -3933,14 +4524,14 @@ var BoundedTypeScriptFileSystem = class {
     const absolute = this.absolute(directory);
     if (!this.isPermitted(absolute)) return [];
     if (!this.directoryExists(absolute)) return [];
-    const directories = ts6.sys.getDirectories(absolute).filter((entry) => this.isPermitted(path8.resolve(absolute, entry))).sort(compareText);
+    const directories = ts6.sys.getDirectories(absolute).filter((entry) => this.isPermitted(path10.resolve(absolute, entry))).sort(compareText);
     this.recordDirectoryListing(absolute, directories);
     return directories;
   };
   readDirectory = (rootDir, extensions, excludes, includes, depth) => {
     const absolute = this.absolute(rootDir);
     if (!this.isPermitted(absolute)) return [];
-    return ts6.sys.readDirectory(absolute, extensions, excludes, includes, depth).filter((entry) => this.isPermitted(path8.resolve(absolute, entry))).sort(compareText);
+    return ts6.sys.readDirectory(absolute, extensions, excludes, includes, depth).filter((entry) => this.isPermitted(path10.resolve(absolute, entry))).sort(compareText);
   };
   realpath = (candidate) => {
     const absolute = this.absolute(candidate);
@@ -4069,11 +4660,11 @@ var BoundedTypeScriptFileSystem = class {
     }
   }
   absolute(candidate) {
-    return path8.isAbsolute(candidate) ? path8.resolve(candidate) : path8.resolve(this.root, candidate);
+    return path10.isAbsolute(candidate) ? path10.resolve(candidate) : path10.resolve(this.root, candidate);
   }
 };
 function semanticDirectoryListingHash(directory, entries) {
-  const normalized = entries.map((entry) => normalizeStoredPath(path8.relative(directory, path8.resolve(directory, entry)))).sort(compareText);
+  const normalized = entries.map((entry) => normalizeStoredPath(path10.relative(directory, path10.resolve(directory, entry)))).sort(compareText);
   return hashText(Buffer.from(normalized.join("\0"), "utf8"));
 }
 function semanticObservationKey(observation) {
@@ -4090,14 +4681,14 @@ function fallbackCompilerOptions(root) {
     skipLibCheck: true,
     jsx: ts6.JsxEmit.Preserve,
     experimentalDecorators: true,
-    configFilePath: path8.join(root, "tsconfig.fallback.json"),
+    configFilePath: path10.join(root, "tsconfig.fallback.json"),
     typeRoots: boundedTypeRoots(root, root)
   };
 }
 
 // src/discovery.ts
 import { promises as fs6 } from "fs";
-import path11 from "path";
+import path13 from "path";
 import fg3 from "fast-glob";
 
 // src/package-metadata.ts
@@ -4132,7 +4723,7 @@ function isSafeStoredPath(value) {
 
 // src/workspaces.ts
 import { promises as fs4 } from "fs";
-import path9 from "path";
+import path11 from "path";
 import { getPackages } from "@manypkg/get-packages";
 var ManypkgWorkspaceDiscovery = class {
   name = "manypkg";
@@ -4151,14 +4742,14 @@ var ManypkgWorkspaceDiscovery = class {
       for (const workspace of discovered.packages) {
         const realDirectory = await fs4.realpath(workspace.dir);
         if (realDirectory === selectedRoot || !isPathInside(selectedRoot, realDirectory)) continue;
-        const manifestPath = path9.join(realDirectory, "package.json");
+        const manifestPath = path11.join(realDirectory, "package.json");
         if (!await isSafeRegularFile(selectedRoot, manifestPath)) continue;
         const manifest = JSON.parse(
           (await readFileInsideRoot(selectedRoot, manifestPath)).toString("utf8")
         );
         packages.push({
-          name: typeof manifest.name === "string" ? manifest.name : path9.basename(realDirectory),
-          path: normalizeStoredPath(path9.relative(selectedRoot, realDirectory)),
+          name: typeof manifest.name === "string" ? manifest.name : path11.basename(realDirectory),
+          path: normalizeStoredPath(path11.relative(selectedRoot, realDirectory)),
           entryPoints: packageEntryPoints(manifest)
         });
       }
@@ -4174,11 +4765,11 @@ function createWorkspaceDiscovery() {
 }
 async function isWorkspaceRoot(root) {
   for (const marker of ["pnpm-workspace.yaml", "pnpm-workspace.yml", "lerna.json", "rush.json"]) {
-    if (await isSafeRegularFile(root, path9.join(root, marker))) return true;
+    if (await isSafeRegularFile(root, path11.join(root, marker))) return true;
   }
   try {
     const packageJson = JSON.parse(
-      (await readFileInsideRoot(root, path9.join(root, "package.json"))).toString("utf8")
+      (await readFileInsideRoot(root, path11.join(root, "package.json"))).toString("utf8")
     );
     return Array.isArray(packageJson.workspaces) || Boolean(
       packageJson.workspaces && typeof packageJson.workspaces === "object" && "packages" in packageJson.workspaces
@@ -4190,7 +4781,7 @@ async function isWorkspaceRoot(root) {
 
 // src/ignore.ts
 import { promises as fs5 } from "fs";
-import path10 from "path";
+import path12 from "path";
 import fg2 from "fast-glob";
 import createIgnore from "ignore";
 var GitIgnoreAdapter = class {
@@ -4215,9 +4806,9 @@ async function loadIgnoreRules(root) {
   const rules = [];
   for (const relative of ignoreFiles.sort(compareIgnoreFiles)) {
     const normalizedRelative = normalizeStoredPath(relative);
-    const directory = normalizeStoredPath(path10.posix.dirname(normalizedRelative));
+    const directory = normalizeStoredPath(path12.posix.dirname(normalizedRelative));
     if (directory !== "." && isIgnoredDirectory(directory, rules)) continue;
-    const absolute = path10.resolve(root, relative);
+    const absolute = path12.resolve(root, relative);
     const stat = await fs5.lstat(absolute);
     if (stat.isSymbolicLink() || !stat.isFile()) continue;
     const real = await fs5.realpath(absolute);
@@ -4268,7 +4859,7 @@ function isSafeRelativePath(value) {
 var SOURCE_EXTENSION = /\.(?:[cm]?[jt]sx?)$/i;
 async function readPackageMetadata(root) {
   const raw = JSON.parse(
-    (await readFileInsideRoot(root, path11.join(root, "package.json"))).toString("utf8")
+    (await readFileInsideRoot(root, path13.join(root, "package.json"))).toString("utf8")
   );
   const workspaceDiscovery = await createWorkspaceDiscovery().discover(root);
   const dependencies = /* @__PURE__ */ new Set();
@@ -4277,7 +4868,7 @@ async function readPackageMetadata(root) {
     try {
       manifests.push(
         JSON.parse(
-          (await readFileInsideRoot(root, path11.join(root, workspace.path, "package.json"))).toString("utf8")
+          (await readFileInsideRoot(root, path13.join(root, workspace.path, "package.json"))).toString("utf8")
         )
       );
     } catch {
@@ -4329,7 +4920,7 @@ async function discoverSourceFiles(root, config) {
   });
   const permitted = new Set(await createGitIgnoreAdapter().filter(root, matches));
   const candidates = matches.filter((relative) => permitted.has(normalizeStoredPath(relative))).filter((relative) => SOURCE_EXTENSION.test(relative)).map((relative) => ({
-    absolutePath: path11.resolve(root, relative),
+    absolutePath: path13.resolve(root, relative),
     relativePath: normalizeStoredPath(relative),
     language: languageFromPath(relative)
   })).sort((a, b) => compareText(a.relativePath, b.relativePath));
@@ -4349,12 +4940,12 @@ function prefixGlob(directory, pattern) {
   return `${normalizeStoredPath(directory)}/${normalized}`;
 }
 function languageFromPath(filePath) {
-  const extension = path11.extname(filePath).slice(1).toLowerCase();
+  const extension = path13.extname(filePath).slice(1).toLowerCase();
   return extension;
 }
 
 // src/semantic.ts
-import path12 from "path";
+import path14 from "path";
 import ts7 from "typescript";
 var TYPESCRIPT_SEMANTIC_VERSION = `compiler-units-v4+typescript-${ts7.version}`;
 var TypeScriptSemanticResolver = class {
@@ -4366,7 +4957,7 @@ var TypeScriptSemanticResolver = class {
   version = TYPESCRIPT_SEMANTIC_VERSION;
   resolve(input) {
     const compiler = loadCompilerConfiguration(input.root, input.tsconfig);
-    const currentDirectory = input.tsconfig ? path12.dirname(path12.resolve(input.root, input.tsconfig)) : input.root;
+    const currentDirectory = input.tsconfig ? path14.dirname(path14.resolve(input.root, input.tsconfig)) : input.root;
     const fileSystem = compiler.fileSystem;
     const host = createBoundedCompilerHost(
       input.root,
@@ -4401,7 +4992,7 @@ var TypeScriptSemanticResolver = class {
       const resolvedModule = resolveModule(literal.text, containingFile);
       return { resolvedModule };
     });
-    const rootNames = [...new Set(input.sourceFiles.map((file) => path12.resolve(file)))].sort(
+    const rootNames = [...new Set(input.sourceFiles.map((file) => path14.resolve(file)))].sort(
       compareText
     );
     const program = ts7.createProgram({
@@ -4437,8 +5028,8 @@ function createProjectReferenceModuleResolver(root, references, fileSystem, pars
     if (!isPathInside(root, configPath)) continue;
     const parsed = parseCommand(root, configPath, fileSystem, parsedCommands);
     if (!parsed) continue;
-    const packageRoot = path12.dirname(configPath);
-    const packageJsonPath = path12.join(packageRoot, "package.json");
+    const packageRoot = path14.dirname(configPath);
+    const packageJsonPath = path14.join(packageRoot, "package.json");
     const raw = fileSystem.readFile(packageJsonPath);
     if (!raw) continue;
     try {
@@ -4468,22 +5059,22 @@ function referencedPackageSource(referenced, subpath, fileSystem) {
   const { parsed, root: packageRoot, manifest } = referenced;
   const rootDir = parsed.options.rootDir ?? packageRoot;
   if (!isPathInside(packageRoot, rootDir)) return void 0;
-  const owned = new Set(parsed.fileNames.map((fileName) => path12.resolve(fileName)));
+  const owned = new Set(parsed.fileNames.map((fileName) => path14.resolve(fileName)));
   const requestedTargets = packageEntryTargets(manifest, subpath);
   const bases = [];
   for (const target of requestedTargets) {
-    const absoluteTarget = path12.resolve(packageRoot, target);
+    const absoluteTarget = path14.resolve(packageRoot, target);
     if (!isPathInside(packageRoot, absoluteTarget)) continue;
     const outDir = parsed.options.outDir;
     if (outDir && isPathInside(outDir, absoluteTarget)) {
-      bases.push(path12.resolve(rootDir, path12.relative(outDir, absoluteTarget)));
+      bases.push(path14.resolve(rootDir, path14.relative(outDir, absoluteTarget)));
     }
     bases.push(absoluteTarget);
   }
-  bases.push(path12.resolve(rootDir, subpath || "index"));
+  bases.push(path14.resolve(rootDir, subpath || "index"));
   for (const base of bases) {
     for (const candidate of sourceModuleCandidates(base)) {
-      const absolute = path12.resolve(candidate);
+      const absolute = path14.resolve(candidate);
       if (isPathInside(packageRoot, absolute) && owned.has(absolute) && fileSystem.fileExists(absolute)) {
         return fileSystem.realpath(absolute);
       }
@@ -4539,7 +5130,7 @@ function sourceModuleCandidates(value) {
   return [
     value,
     ...extensions.map((extension) => `${stem}${extension}`),
-    ...extensions.map((extension) => path12.join(stem, `index${extension}`))
+    ...extensions.map((extension) => path14.join(stem, `index${extension}`))
   ];
 }
 function normalizeModuleStem(value) {
@@ -4601,7 +5192,7 @@ function loadCompilerConfiguration(root, tsconfig) {
       parsedCommands: /* @__PURE__ */ new Map()
     };
   }
-  const absolute = path12.resolve(root, tsconfig);
+  const absolute = path14.resolve(root, tsconfig);
   if (!isPathInside(root, absolute) || !fileSystem.fileExists(absolute)) {
     const diagnostic = {
       schemaVersion: SCHEMA_VERSION,
@@ -4644,11 +5235,11 @@ function loadCompilerConfiguration(root, tsconfig) {
     return isPathInside(root, target) && fileSystem.fileExists(target);
   });
   const options = parsed.options;
-  anchorCompilerOptions(root, path12.dirname(absolute), options);
+  anchorCompilerOptions(root, path14.dirname(absolute), options);
   return {
     options,
     ...projectReferences.length > 0 ? { projectReferences } : {},
-    pathAliases: pathAliases(root, path12.dirname(absolute), options),
+    pathAliases: pathAliases(root, path14.dirname(absolute), options),
     diagnostics: parsed.errors.map((diagnostic) => compilerDiagnostic(diagnostic, root)),
     rawDiagnostics: parsed.errors,
     fileSystem,
@@ -4656,7 +5247,7 @@ function loadCompilerConfiguration(root, tsconfig) {
   };
 }
 function parseCommand(root, configPath, fileSystem, cache) {
-  const absolute = path12.resolve(configPath);
+  const absolute = path14.resolve(configPath);
   const cached = cache.get(absolute);
   if (cached) return cached;
   if (!isPathInside(root, absolute) || !fileSystem.fileExists(absolute)) return void 0;
@@ -4664,8 +5255,8 @@ function parseCommand(root, configPath, fileSystem, cache) {
     const source = ts7.readJsonConfigFile(absolute, fileSystem.readFile);
     const parsed = ts7.parseJsonSourceFileConfigFileContent(
       source,
-      fileSystem.parseHost(path12.dirname(absolute)),
-      path12.dirname(absolute),
+      fileSystem.parseHost(path14.dirname(absolute)),
+      path14.dirname(absolute),
       void 0,
       absolute,
       void 0,
@@ -4676,7 +5267,7 @@ function parseCommand(root, configPath, fileSystem, cache) {
       const target = ts7.resolveProjectReferencePath(reference);
       return isPathInside(root, target) && fileSystem.fileExists(target);
     });
-    anchorCompilerOptions(root, path12.dirname(absolute), parsed.options);
+    anchorCompilerOptions(root, path14.dirname(absolute), parsed.options);
     cache.set(absolute, parsed);
     return parsed;
   } catch {
@@ -4701,7 +5292,7 @@ function createBoundedCompilerHost(root, currentDirectory, options, fileSystem,
   return host;
 }
 function anchorCompilerOptions(root, unitDirectory, options) {
-  options.configFilePath = options.configFilePath ?? path12.join(unitDirectory, "tsconfig.json");
+  options.configFilePath = options.configFilePath ?? path14.join(unitDirectory, "tsconfig.json");
   if (!options.typeRoots) options.typeRoots = boundedTypeRoots2(root, unitDirectory);
   else options.typeRoots = options.typeRoots.filter((entry) => isPathInside(root, entry));
   if (options.baseUrl && !isPathInside(root, options.baseUrl)) options.baseUrl = void 0;
@@ -4711,11 +5302,11 @@ function anchorCompilerOptions(root, unitDirectory, options) {
 }
 function boundedTypeRoots2(root, start) {
   const values = [];
-  let current = path12.resolve(start);
+  let current = path14.resolve(start);
   while (isPathInside(root, current)) {
-    values.push(path12.join(current, "node_modules", "@types"));
-    if (current === path12.resolve(root)) break;
-    const parent = path12.dirname(current);
+    values.push(path14.join(current, "node_modules", "@types"));
+    if (current === path14.resolve(root)) break;
+    const parent = path14.dirname(current);
     if (parent === current) break;
     current = parent;
   }
@@ -4727,7 +5318,7 @@ function pathAliases(root, configDirectory, options) {
   return Object.fromEntries(
     Object.entries(paths).filter(([alias]) => isSafeRelativePathPattern(alias)).sort(([a], [b]) => compareText(a, b)).map(([alias, values]) => [
       alias,
-      values.filter(isSafeRelativePathPattern).map((value) => path12.resolve(base, value)).filter((value) => isPathInside(root, value)).map((value) => normalizeStoredPath(relativePosix(root, value))).filter((value, index, entries) => entries.indexOf(value) === index).sort(compareText)
+      values.filter(isSafeRelativePathPattern).map((value) => path14.resolve(base, value)).filter((value) => isPathInside(root, value)).map((value) => normalizeStoredPath(relativePosix(root, value))).filter((value, index, entries) => entries.indexOf(value) === index).sort(compareText)
     ])
   );
 }
@@ -4760,7 +5351,7 @@ function sanitizeCompilerMessage(message, root) {
 
 // src/storage.ts
 import { promises as fs7 } from "fs";
-import path13 from "path";
+import path15 from "path";
 import { z as z2 } from "zod";
 async function writeCodeMap(resolved, map) {
   const validated = finalizeCodeMap(map);
@@ -4768,7 +5359,7 @@ async function writeCodeMap(resolved, map) {
   await fs7.mkdir(resolved.outputDir, { recursive: true });
   let wrote = false;
   const write = async (name, content) => {
-    wrote = await atomicWriteIfChanged(path13.join(resolved.outputDir, name), content) || wrote;
+    wrote = await atomicWriteIfChanged(path15.join(resolved.outputDir, name), content) || wrote;
   };
   for (const name of MAP_COMPANION_ARTIFACTS) await write(name, contents[name]);
   await write("manifest.json", stableJson(validated.manifest, true));
@@ -4832,14 +5423,14 @@ async function loadCodeMap(options = {}) {
 async function loadCodeMapFrom(outputDir) {
   try {
     const manifest = await readJson(
-      path13.join(outputDir, "manifest.json"),
+      path15.join(outputDir, "manifest.json"),
       "manifest",
       ManifestRecordSchema
     );
     verifyManifestIntegrity(manifest, outputDir);
     const rawEntries = await Promise.all(
       MAP_COMPANION_ARTIFACTS.map(
-        async (name) => [name, await fs7.readFile(path13.join(outputDir, name))]
+        async (name) => [name, await fs7.readFile(path15.join(outputDir, name))]
       )
     );
     const raw = Object.fromEntries(rawEntries);
@@ -4935,7 +5526,7 @@ function verifyManifestIntegrity(manifest, outputDir) {
 async function loadManifestFrom(outputDir) {
   try {
     const manifest = await readJson(
-      path13.join(outputDir, "manifest.json"),
+      path15.join(outputDir, "manifest.json"),
       "manifest",
       ManifestRecordSchema
     );
@@ -5240,9 +5831,9 @@ function semanticPackageInputs(workspaces) {
 async function hashExistingInputs(root, relativePaths) {
   const output = [];
   for (const relative of [...new Set(relativePaths.map(normalizeStoredPath))].sort(compareText)) {
-    const absolute = path14.resolve(root, relative);
-    const candidate = path14.relative(root, absolute);
-    if (candidate === ".." || candidate.startsWith(`..${path14.sep}`) || path14.isAbsolute(candidate)) {
+    const absolute = path16.resolve(root, relative);
+    const candidate = path16.relative(root, absolute);
+    if (candidate === ".." || candidate.startsWith(`..${path16.sep}`) || path16.isAbsolute(candidate)) {
       continue;
     }
     try {
@@ -5297,7 +5888,7 @@ async function hashDiscoveredSources(files, concurrency) {
 }
 async function compareSemanticInputs(root, before, concurrency) {
   const realRoot = await fs8.realpath(root);
-  const toolchainRoot = await fs8.realpath(path14.dirname(ts8.getDefaultLibFilePath({})));
+  const toolchainRoot = await fs8.realpath(path16.dirname(ts8.getDefaultLibFilePath({})));
   const current = await mapLimit(before, concurrency, async (input) => {
     let changed;
     switch (input.kind) {
@@ -5335,7 +5926,7 @@ async function compareSemanticInputs(root, before, concurrency) {
   return current.filter((input) => input.changed).map((input) => input.path).sort(compareText);
 }
 async function hashSemanticFileInput(root, realRoot, relative) {
-  const absolute = path14.resolve(root, relative);
+  const absolute = path16.resolve(root, relative);
   if (!isPathInside(root, absolute)) return null;
   try {
     const realInput = await fs8.realpath(absolute);
@@ -5348,7 +5939,7 @@ async function hashSemanticFileInput(root, realRoot, relative) {
   }
 }
 async function semanticProbeState(root, realRoot, relative, targetKind) {
-  const absolute = path14.resolve(root, relative);
+  const absolute = path16.resolve(root, relative);
   if (!isPathInside(root, absolute)) return false;
   try {
     const realInput = await fs8.realpath(absolute);
@@ -5365,7 +5956,7 @@ async function semanticProbeState(root, realRoot, relative, targetKind) {
   }
 }
 async function hashSemanticDirectoryInput(root, realRoot, relative) {
-  const absolute = path14.resolve(root, relative);
+  const absolute = path16.resolve(root, relative);
   if (!isPathInside(root, absolute)) return null;
   try {
     const realInput = await fs8.realpath(absolute);
@@ -5375,7 +5966,7 @@ async function hashSemanticDirectoryInput(root, realRoot, relative) {
     const permitted = [];
     for (const candidate of candidates) {
       try {
-        const resolved = path14.resolve(absolute, candidate);
+        const resolved = path16.resolve(absolute, candidate);
         const realCandidate = await fs8.realpath(resolved);
         if (isPathInside(realRoot, realCandidate)) permitted.push(candidate);
       } catch {
@@ -5387,7 +5978,7 @@ async function hashSemanticDirectoryInput(root, realRoot, relative) {
   }
 }
 async function semanticSymlinkTarget(root, realRoot, relative) {
-  const absolute = path14.resolve(root, relative);
+  const absolute = path16.resolve(root, relative);
   if (!isPathInside(root, absolute)) return null;
   try {
     const realInput = await fs8.realpath(absolute);
@@ -5399,8 +5990,8 @@ async function semanticSymlinkTarget(root, realRoot, relative) {
 }
 async function hashToolchainFileInput(relative) {
   try {
-    const libraryRoot = await fs8.realpath(path14.dirname(ts8.getDefaultLibFilePath({})));
-    const absolute = path14.resolve(libraryRoot, relative);
+    const libraryRoot = await fs8.realpath(path16.dirname(ts8.getDefaultLibFilePath({})));
+    const absolute = path16.resolve(libraryRoot, relative);
     if (!isPathInside(libraryRoot, absolute)) return null;
     const realInput = await fs8.realpath(absolute);
     if (!isPathInside(libraryRoot, realInput) || !(await fs8.stat(realInput)).isFile()) return null;
@@ -5736,7 +6327,7 @@ async function analyzeProject(options) {
       const result = await runCompilerUnitWorker(unitInput);
       contribution = result.contribution;
       for (const file of result.files) {
-        const source = preparedByAbsolute.get(path15.resolve(resolved.root, file.path));
+        const source = preparedByAbsolute.get(path17.resolve(resolved.root, file.path));
         if (source) source.file = file;
       }
     } else {
@@ -5849,7 +6440,7 @@ async function analyzeCompilerUnit(options) {
   const { program, checker } = semantic;
   const resolveModule = semantic.resolveModule ?? createBoundedModuleResolver(
     options.root,
-    path15.resolve(options.root, unit.record.root),
+    path17.resolve(options.root, unit.record.root),
     program.getCompilerOptions()
   );
   const diagnostics = [...semantic.diagnostics];
@@ -6679,7 +7270,74 @@ function showSymbol(map, selector) {
     }).filter((match) => match !== void 0)
   };
 }
-function formatShowResult(result) {
+function formatShowResult(result, options = {}) {
+  const limit = options.limit ?? 12;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+    throw new RangeError("show limit must be an integer between 1 and 50");
+  }
+  if (options.full) return formatFullShowResult(result);
+  let remaining = limit;
+  const matches = result.matches.slice(0, 5);
+  const blocks = matches.map(({ symbol, inbound, outbound }) => {
+    const { startLine, startColumn, endLine, endColumn } = symbol.range;
+    const lines = [
+      `${symbol.name} [${symbol.kind}]`,
+      `id: ${symbol.id}`,
+      `path: ${symbol.file}:${startLine}:${startColumn}-${endLine}:${endColumn}`
+    ];
+    if (symbol.signature) {
+      const signature = symbol.signature.replace(/\s+/g, " ");
+      lines.push(
+        `signature: ${signature.length > 240 ? `${signature.slice(0, 240)}\u2026 [truncated]` : signature}`
+      );
+    }
+    const entries = [
+      ...outbound.map((relation2) => ({ relation: relation2, direction: "->", target: relation2.to })),
+      ...inbound.map((relation2) => ({ relation: relation2, direction: "<-", target: relation2.from }))
+    ];
+    const eligible = entries.filter(
+      ({ relation: relation2, target }) => !["heuristic", "derived"].includes(relation2.origin.classification) && !["contains", "exports", "used-by"].includes(relation2.type) && !target.startsWith("unresolved:")
+    );
+    const actionable = new Set(
+      eligible.filter(({ relation: relation2 }) => relation2.type !== "references").map(({ direction, target }) => `${direction}:${target}`)
+    );
+    const groups = /* @__PURE__ */ new Map();
+    let filtered = entries.length - eligible.length;
+    for (const { relation: relation2, direction, target } of eligible) {
+      if (relation2.type === "references" && actionable.has(`${direction}:${target}`)) {
+        filtered++;
+        continue;
+      }
+      const key = `${direction}:${relation2.type}:${target}`;
+      const group = groups.get(key);
+      if (group) group.count++;
+      else groups.set(key, { direction, target, type: relation2.type, count: 1 });
+    }
+    const ranked = [...groups.values()].sort(
+      (a, b) => Number(a.target.startsWith("external:")) - Number(b.target.startsWith("external:")) || Number(a.type === "references") - Number(b.type === "references") || compareText(`${a.direction}:${a.type}:${a.target}`, `${b.direction}:${b.type}:${b.target}`)
+    );
+    const shown = ranked.slice(0, remaining);
+    remaining -= shown.length;
+    lines.push(
+      `relations: ${shown.length}/${ranked.length} groups shown; ${ranked.length - shown.length} omitted; ${filtered} records filtered`
+    );
+    lines.push(
+      ...shown.map(
+        ({ direction, type, target, count }) => `  ${direction} ${type} ${direction} ${target}${count > 1 ? ` (${count} occurrences)` : ""}`
+      )
+    );
+    return lines.join("\n");
+  });
+  if (matches.length < result.matches.length) {
+    blocks.push(
+      `Symbols: ${matches.length}/${result.matches.length} shown; ${result.matches.length - matches.length} omitted. Use an exact ID to narrow the selector.`
+    );
+  }
+  if (matches.length)
+    blocks.push("Compact view; use --full or --json for all details and evidence.");
+  return blocks.join("\n\n");
+}
+function formatFullShowResult(result) {
   return result.matches.map(({ symbol, inbound, outbound }) => {
     const lines = [
       `${symbol.name} [${symbol.kind}]`,
@@ -6744,6 +7402,8 @@ export {
   TypeScriptParserAdapter,
   TypeScriptSemanticResolver,
   buildOverview,
+  buildProjectMap,
+  buildSourceContext,
   checkFreshness,
   computeManifestIntegrityHash,
   createAnalyzer,
@@ -6753,9 +7413,13 @@ export {
   createTypeScriptSemanticResolver,
   createWorkspaceDiscovery,
   findProjectRoot,
+  findSymbols,
+  formatProjectMap,
   formatShowResult,
+  formatSourceContext,
   initProject,
   loadCodeMap,
+  readSymbolSource,
   scanProject,
   showSymbol
 };