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

package/dist/cli.js

@@ -7,7 +7,7 @@ import { Command, CommanderError, Option } from "commander";
 // package.json
 var package_default = {
   name: "ai-code-map",
-  version: "0.1.0-alpha.2",
+  version: "0.1.0-alpha.3",
   description: "Local, deterministic semantic code maps for AI coding agents",
   type: "module",
   sideEffects: false,
@@ -47,6 +47,8 @@ var package_default = {
     "docs",
     "examples",
     "README.md",
+    "AGENTS.md",
+    "skills",
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -64,6 +66,7 @@ var package_default = {
     "schema:check": "node --import tsx scripts/generate-schemas.ts --check",
     benchmark: "node --import tsx scripts/benchmark-parsers.ts",
     "benchmark:real-world": "node --import tsx scripts/benchmark-real-world.ts",
+    "benchmark:tokens": "node --import tsx scripts/benchmark-tokens.ts",
     prepack: "pnpm schema:check && pnpm build"
   },
   dependencies: {
@@ -1055,9 +1058,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);
 }
@@ -3351,8 +3354,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);
@@ -5203,11 +5206,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) {
@@ -6685,6 +6688,120 @@ function usesDefaultAnalysisPipeline(options) {
   return !options.analyzers && (!options.parser || isBuiltInTypeScriptParserAdapter(options.parser)) && !options.semanticResolver;
 }
 
+// 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/show.ts
 var KIND_ALIASES = {
   component: "react-component",
@@ -6747,7 +6864,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}]`,
@@ -6786,6 +6970,495 @@ function formatFactValue(value) {
   return String(value);
 }
 
+// src/read.ts
+import path16 from "path";
+
+// 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;
+}
+function formatReadNavigation(navigation) {
+  return [
+    `Map links: ${navigation.links.length} shown; ${navigation.omittedLinks} omitted. Read an ID only if needed.`,
+    ...navigation.links.map(
+      (link) => `  ${link.direction === "outgoing" ? "->" : "<-"} ${link.type} ${link.id} [lines ${link.startLine}-${link.endLine}; ${link.classification}]`
+    ),
+    `Test call sites: ${navigation.tests.length} shown; ${navigation.omittedTests} omitted (path-based; not a coverage claim).`,
+    ...navigation.tests.map((site) => `  ${site.file}:${site.line}`)
+  ];
+}
+
+// src/read.ts
+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 = path16.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/context.ts
+import path17 from "path";
+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, path17.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;
+  }
+  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");
+    }
+    for (const site of nav.tests) tests.set(`${site.file}:${site.line}`, site);
+  }
+  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 });
+  }
+  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)
+    );
+  }
+  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)
+    );
+  }
+  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
+  );
+  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)
+    );
+  }
+  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 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 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");
+}
+
+// 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 };
+  });
+  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/cli.ts
 async function runCli(argv = process.argv) {
   const program = createProgram();
@@ -6841,20 +7514,112 @@ ${result.wrote ? `Updated ${result.outputDir}.` : "Map was already current; no a
     if (!result.current) exitCode = 2;
   });
   addCommonOptions(checkCommand);
-  const showCommand = program.command("show").description("Show one indexed symbol by stable ID, kind:name, path, or exact name").argument("<symbol>", "symbol selector").addOption(new Option("--json", "print machine-readable output")).action(async (selector, _options, command) => {
+  const mapCommand = program.command("map").description("Check freshness and print the complete structural map in one call").option("--json", "print all nodes and grouped relations as JSON").action(async (_options, command) => {
     const common = collectOptions(command);
-    const map = await loadCodeMap(loadOptions(common));
-    const result = showSymbol(map, selector);
-    if (result.matches.length === 0) {
-      throw new CodeMapError(
-        "SYMBOL_NOT_FOUND",
-        `No indexed symbol matches ${selector}. Run ai-code-map scan, then use an exact name or stable ID.`
-      );
+    const inspection = await inspectFreshness(loadOptions(common));
+    if (!inspection.result.current || !inspection.map) {
+      if (common.json) printJson(inspection.result);
+      else
+        process.stdout.write(
+          `Map unavailable: ${inspection.result.reasons.join(" ")} Run ai-code-map scan.
+`
+        );
+      exitCode = 2;
+      return;
     }
-    if (common.json) printJson(result);
-    else process.stdout.write(`${formatShowResult(result)}
+    const view = buildProjectMap(inspection.map);
+    if (common.json) printJson(view);
+    else process.stdout.write(`${formatProjectMap(view)}
 `);
   });
+  addCommonOptions(mapCommand);
+  const findCommand = program.command("find").description("Find indexed symbols by name, path, words, or a likely typo").argument("<query>", "search query (quote multiple words)").option("--limit <number>", "maximum matches, 1..50", parseLimit, 10).option("--json", "print machine-readable output").action(
+    async (query, options, command) => {
+      const map = await loadCodeMap(loadOptions(collectOptions(command)));
+      const result = findSymbols(map, query, { limit: options.limit });
+      if (options.json) printJson(result);
+      else process.stdout.write(`${formatSearchResult(result)}
+`);
+    }
+  );
+  addCommonOptions(findCommand);
+  const contextCommand = program.command("context").description(
+    "Collect bounded current source for lexical matches and their direct graph neighbors"
+  ).argument("<query>", "quoted search words or an exact symbol ID").option("--max-lines <number>", "shared source-line budget, 1..2000", Number, 800).option("--max-chars <number>", "shared source-character budget, 256..64000", Number, 32e3).option("--seeds <number>", "maximum matches to expand, 1..5", Number, 3).option("--json", "print structured context, budgets and omitted ranges").action(
+    async (query, options, command) => {
+      const common = collectOptions(command);
+      const inspection = await inspectFreshness(loadOptions(common));
+      if (!inspection.result.current || !inspection.map) {
+        if (common.json) printJson(inspection.result);
+        else
+          process.stdout.write(
+            `Map unavailable: ${inspection.result.reasons.join(" ")} Run ai-code-map scan.
+`
+          );
+        exitCode = 2;
+        return;
+      }
+      const result = await buildSourceContext(inspection.map, query, {
+        root: inspection.result.root,
+        maxLines: options.maxLines,
+        maxChars: options.maxChars,
+        seeds: options.seeds
+      });
+      if (common.json) printJson(result);
+      else process.stdout.write(`${formatSourceContext(result)}
+`);
+    }
+  );
+  addCommonOptions(contextCommand);
+  const readCommand = program.command("read").description("Read a bounded source range using an exact symbol ID from the map").argument("<id>", "exact stable symbol ID from find").option("--limit <number>", "maximum source lines, 1..200", Number, 80).option("--offset <number>", "line offset within the symbol window", Number, 0).option("--json", "print source and continuation metadata as JSON").action(
+    async (id, options, command) => {
+      const common = collectOptions(command);
+      const resolved = await resolveConfiguration(loadOptions(common));
+      const map = await loadCodeMapFrom(resolved.outputDir);
+      const result = await readSymbolSource(map, id, {
+        root: resolved.root,
+        limit: options.limit,
+        offset: options.offset
+      });
+      if (options.json) printJson(result);
+      else {
+        const location = ["root", "config", "output"];
+        const suffix = location.map((key) => {
+          const value = common[key];
+          return value ? ` --${key} ${shellQuote(value)}` : "";
+        }).join("");
+        const numbered = result.source.split("\n").map((line, index) => `${result.startLine + index}: ${line}`);
+        process.stdout.write(
+          [
+            `${result.id}
+${result.file}:${result.startLine}-${result.endLine}`,
+            ...numbered,
+            result.truncated ? `More source remains. Continue: ai-code-map read ${shellQuote(result.id)} --offset ${result.nextOffset} --limit ${options.limit}${suffix}` : "End of symbol window.",
+            ...result.navigation ? formatReadNavigation(result.navigation) : []
+          ].join("\n") + "\n"
+        );
+      }
+    }
+  );
+  addCommonOptions(readCommand);
+  const showCommand = program.command("show").description("Show one indexed symbol by stable ID, kind:name, path, or exact name").argument("<symbol>", "symbol selector").option("--full", "print verbose symbol details and relations").option("--limit <number>", "maximum relation groups in compact text, 1..50", parseLimit, 12).addOption(new Option("--json", "print machine-readable output")).action(
+    async (selector, options, command) => {
+      const common = collectOptions(command);
+      const map = await loadCodeMap(loadOptions(common));
+      const result = showSymbol(map, selector);
+      if (result.matches.length === 0) {
+        const suggestions = selector.trim() ? findSymbols(map, selector, { limit: 5 }) : void 0;
+        throw new CodeMapError(
+          "SYMBOL_NOT_FOUND",
+          `No indexed symbol matches ${selector}. ${suggestions?.matches.length ? `Did you mean:
+${formatSearchResult(suggestions)}` : 'Use ai-code-map find "words" to discover a selector, or rg if the symbol is not indexed.'}`
+        );
+      }
+      if (common.json) printJson(result);
+      else process.stdout.write(`${formatShowResult(result, { ...options })}
+`);
+    }
+  );
   addCommonOptions(showCommand);
   try {
     await program.parseAsync(argv);
@@ -6891,10 +7656,30 @@ function loadOptions(options) {
     ...options.output ? { output: options.output } : {}
   };
 }
+function shellQuote(value) {
+  return "'" + value.replaceAll("'", "'\\''") + "'";
+}
 function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
 }
+function parseLimit(value) {
+  const limit = Number(value);
+  if (!/^\d+$/.test(value) || !Number.isInteger(limit) || limit < 1 || limit > 50) {
+    throw new RangeError("limit must be an integer between 1 and 50");
+  }
+  return limit;
+}
+function formatSearchResult(result) {
+  return [
+    `Symbols: ${result.matches.length}/${result.total} shown${result.truncated ? "; refine the query for omitted matches" : ""}`,
+    ...result.matches.map(
+      ({ id, kind, file, range, unmatchedTerms }) => `${id} [${kind}]${unmatchedTerms?.length ? ` (partial; unmatched: ${unmatchedTerms.join(", ")})` : ""}
+  ${file}:${range.startLine}:${range.startColumn}-${range.endLine}:${range.endColumn}`
+    ),
+    result.matches.length ? "Use ai-code-map read '<id>' for bounded source; show '<id>' for relations." : "No matches. Try other words or use rg; only indexed symbols are searchable."
+  ].join("\n");
+}
 var invokedPath = process.argv[1] ? pathToFileURL2(process.argv[1]).href : void 0;
 if (invokedPath === import.meta.url) {
   process.exitCode = await runCli();