codebase-snapshot 0.9.9 → 0.9.14

package/dist/{chunk-HQBEQ67K.js → chunk-J4W74N4Y.js}

@@ -1,6 +1,6 @@
-import { GENERATOR_VERSION, MIN_MAX_PART_BYTES, SCHEMA_VERSION, GENERATOR_NAME, ARTIFACT_NAMES, PRESETS, generateSnapshot, validateSnapshot, explainPath, renderExplainText, describeManifestShapeProblem, loadConfigFileDetailed, parseByteSize, resolveConfig } from './chunk-KUVFTJHK.js';
+import { GENERATOR_VERSION, anchorForPath, displayPath, MIN_MAX_PART_BYTES, SCHEMA_VERSION, GENERATOR_NAME, ARTIFACT_NAMES, PRESETS, generateSnapshot, generateInWorker, validateSnapshot, buildImportResolver, resolveSpecifier, truncateToBytes, explainPath, renderExplainText, describeManifestShapeProblem, loadConfigFileDetailed, parseByteSize, resolveConfig } from './chunk-DUZK5VL2.js';
 import * as fs from 'fs';
-import * as path2 from 'path';
+import * as path from 'path';
 
 // src/mcp/protocol.ts
 var LEGACY_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
@@ -520,6 +520,8 @@ function createMcpServer(options) {
 // src/mcp/part.ts
 var FILE_HEADING = "### FILE: ";
 var CONTENT_MARKERS = /* @__PURE__ */ new Set(["#### Content", "#### Bounded Preview"]);
+var ANCHOR_LINE = /^<a id="([^"]+)"><\/a>$/;
+var INCLUSION_MODES = /* @__PURE__ */ new Set(["full", "preview", "signatures"]);
 function parsePartSections(partText) {
   const lines = partText.split("\n");
   const sections = [];
@@ -530,16 +532,26 @@ function parsePartSections(partText) {
       continue;
     }
     const heading = lines[index].slice(FILE_HEADING.length);
+    const anchorMatch = index > 0 ? ANCHOR_LINE.exec(lines[index - 1]) : null;
     let cursor = index + 1;
     let inclusion = null;
-    let sha256 = null;
     let includedLines = null;
     while (cursor < lines.length && !CONTENT_MARKERS.has(lines[cursor])) {
       const line = lines[cursor];
       if (line.startsWith(FILE_HEADING)) break;
-      if (line.startsWith("- Inclusion: ")) inclusion = line.slice("- Inclusion: ".length).trim();
-      else if (line.startsWith("- SHA-256: ")) sha256 = line.slice("- SHA-256: ".length).trim();
-      else if (line.startsWith("- Included Lines: ")) {
+      if (line.startsWith("- Meta: ")) {
+        for (const field of line.slice("- Meta: ".length).split("|")) {
+          const value = field.trim();
+          if (INCLUSION_MODES.has(value)) inclusion = value;
+        }
+        const counts = /(-?\d+) of (-?\d+) lines|(\d+) lines/.exec(line);
+        if (counts) {
+          const emitted = counts[1] ?? counts[3];
+          includedLines = Number.isFinite(Number(emitted)) ? Number(emitted) : null;
+        }
+      } else if (line.startsWith("- Inclusion: ")) {
+        inclusion = line.slice("- Inclusion: ".length).trim();
+      } else if (line.startsWith("- Included Lines: ")) {
         const value = Number(line.slice("- Included Lines: ".length).trim());
         includedLines = Number.isFinite(value) ? value : null;
       }
@@ -563,47 +575,49 @@ function parsePartSections(partText) {
       body.push(lines[bodyLine]);
       bodyLine += 1;
     }
-    sections.push({ path: heading, body: body.join("\n"), inclusion, sha256, includedLines });
+    sections.push({ path: heading, anchor: anchorMatch?.[1] ?? null, body: body.join("\n"), inclusion, includedLines });
     index = bodyLine + 1;
   }
   return sections;
 }
-function findSection(sections, relativePath, sha256) {
-  const exact = sections.find((section) => section.path === relativePath);
+function findSection(sections, relativePath) {
+  const anchor = anchorForPath(relativePath);
+  const byAnchor = sections.find((section) => section.anchor === anchor);
+  if (byAnchor) return byAnchor;
+  const rendered = displayPath(relativePath);
+  const samePath = (section) => section.path === relativePath || section.path === rendered;
+  const exact = sections.find(samePath);
   if (exact) return exact;
-  if (sha256) {
-    const byHash = sections.filter((section) => section.sha256 === sha256);
-    if (byHash.length === 1) return byHash[0];
-    if (byHash.length > 1) {
-      const byPath = byHash.find(
-        (section) => section.path.toLowerCase() === relativePath.toLowerCase()
-      );
-      if (byPath) return byPath;
-    }
-  }
-  const folded = sections.filter((section) => section.path.toLowerCase() === relativePath.toLowerCase());
+  const foldedPath = rendered.toLowerCase();
+  const folded = sections.filter((section) => {
+    const path4 = section.path.toLowerCase();
+    return path4 === relativePath.toLowerCase() || path4 === foldedPath;
+  });
   return folded.length === 1 ? folded[0] : null;
 }
 function windowText(body, fromLine, lineCount) {
   const lines = body.split("\n");
-  const total = lines.length;
-  const start = Math.min(Math.max(1, Math.trunc(fromLine)), Math.max(1, total));
+  const total = body.length === 0 ? 0 : lines.length;
+  const requested = Math.max(1, Math.trunc(fromLine));
+  const pastEnd = total > 0 && requested > total;
+  const start = pastEnd ? requested : Math.min(requested, Math.max(1, total));
   const end = Math.min(total, start + Math.max(1, Math.trunc(lineCount)) - 1);
-  const slice = lines.slice(start - 1, end);
+  const slice = pastEnd ? [] : lines.slice(start - 1, Math.max(start - 1, end));
   return {
     text: slice.join("\n"),
     fromLine: start,
     returnedLines: slice.length,
     totalLines: total,
-    truncated: end < total,
-    nextFromLine: end < total ? end + 1 : null
+    truncated: !pastEnd && end < total,
+    nextFromLine: !pastEnd && end < total ? end + 1 : null,
+    pastEnd
   };
 }
 function foldForComparison(value) {
   return process.platform === "win32" || process.platform === "darwin" ? value.toLowerCase() : value;
 }
 function canonicalPath(value) {
-  const absolute = path2.resolve(value);
+  const absolute = path.resolve(value);
   try {
     return fs.realpathSync(absolute);
   } catch {
@@ -613,14 +627,14 @@ function canonicalPath(value) {
 function isInside(parent, child) {
   const foldedParent = foldForComparison(parent);
   const foldedChild = foldForComparison(child);
-  return foldedChild === foldedParent || foldedChild.startsWith(`${foldedParent}${path2.sep}`);
+  return foldedChild === foldedParent || foldedChild.startsWith(`${foldedParent}${path.sep}`);
 }
 function resolveRoot(requested, context) {
   if (requested !== void 0 && (typeof requested !== "string" || requested.trim().length === 0)) {
     return { ok: false, message: '"root" must be a non-empty string when provided.' };
   }
   const wanted = typeof requested === "string" ? requested.trim() : context.cwd;
-  const absolute = path2.resolve(context.cwd, wanted);
+  const absolute = path.resolve(context.cwd, wanted);
   let stats;
   try {
     stats = fs.statSync(absolute);
@@ -659,26 +673,59 @@ async function openWorkspace(root, overrides = {}) {
     }
     cliOptions.maxPartBytes = parsed;
   }
+  if (overrides.maxPartTokens !== void 0) {
+    const parsed = parseByteSize(overrides.maxPartTokens);
+    if (parsed === void 0) {
+      return {
+        ok: false,
+        message: '"maxPartTokens" must be a token count, for example 32000 or "32k".'
+      };
+    }
+    cliOptions.maxPartTokens = parsed;
+  }
   if (overrides.outDir !== void 0) {
     if (typeof overrides.outDir !== "string" || overrides.outDir.trim().length === 0) {
       return { ok: false, message: '"outDir" must be a non-empty string.' };
     }
     cliOptions.outDir = overrides.outDir.trim();
   }
+  if (overrides.changedSince !== void 0) {
+    if (typeof overrides.changedSince !== "string" || overrides.changedSince.trim().length === 0) {
+      return {
+        ok: false,
+        message: '"changedSince" must be a git ref such as "main" or "HEAD~3".'
+      };
+    }
+    cliOptions.changedSince = overrides.changedSince.trim();
+  }
+  if (overrides.skeleton === true) cliOptions.skeleton = true;
+  if (overrides.sarif === true) cliOptions.sarif = true;
+  if (overrides.staged === true) cliOptions.staged = true;
+  if (overrides.withDependents === true) cliOptions.withDependents = true;
   try {
     const config = resolveConfig(loaded.config, cliOptions, root);
-    return { ok: true, workspace: { root, config, configFile: loaded.file } };
+    return { ok: true, workspace: { root, config, configFile: loaded.file, cliOptions } };
   } catch (error) {
     return { ok: false, message: error instanceof Error ? error.message : String(error) };
   }
 }
 var manifestCache = /* @__PURE__ */ new Map();
 function manifestPathFor(workspace) {
-  return path2.resolve(workspace.root, workspace.config.outDir, "manifest.json");
+  return path.resolve(workspace.root, workspace.config.outDir, "manifest.json");
+}
+function partPathFor(workspace, filename) {
+  if (filename.length === 0 || filename.includes("\0")) return null;
+  const partsDir = path.resolve(workspace.root, workspace.config.outDir, "parts");
+  const resolved = path.resolve(partsDir, filename);
+  const relative3 = path.relative(partsDir, resolved);
+  if (relative3.length === 0 || relative3.includes(path.sep) || relative3.includes("/") || relative3.includes("\\") || path.isAbsolute(relative3)) {
+    return null;
+  }
+  return resolved;
 }
 function readManifest(workspace) {
   const file = manifestPathFor(workspace);
-  const shown = path2.relative(workspace.root, file).split(path2.sep).join("/") || file;
+  const shown = path.relative(workspace.root, file).split(path.sep).join("/") || file;
   let stats;
   try {
     stats = fs.statSync(file);
@@ -741,6 +788,49 @@ var ROOT_PROPERTY = {
   type: "string",
   description: "Repository root. Defaults to the directory this server was started in."
 };
+var OUT_DIR_PROPERTY = {
+  type: "string",
+  description: "Snapshot directory, relative to the root. Defaults to the project configuration's outDir."
+};
+var outDirOverride = (args) => ({ outDir: args.outDir });
+var SCOPE_PROPERTIES = {
+  maxPartTokens: {
+    type: "string",
+    description: 'Token ceiling per part, for example 32000 or "32k". Narrower than maxPartBytes; it converts at four bytes per token.'
+  },
+  skeleton: {
+    type: "boolean",
+    description: "Replace every function body with `{ /* ... */ }`, keeping signatures, imports and exports. Applies to TypeScript, JavaScript and JSX."
+  },
+  sarif: {
+    type: "boolean",
+    description: "Also write reports/audit.sarif beside reports/audit.md, for CI code scanning."
+  },
+  changedSince: {
+    type: "string",
+    description: 'Only files changed since this git ref, for example "main" or "HEAD~3".'
+  },
+  staged: {
+    type: "boolean",
+    description: "Only files staged in the git index."
+  },
+  withDependents: {
+    type: "boolean",
+    description: "With staged or changedSince, also include the files that import the changed ones (one hop)."
+  }
+};
+function workspaceOverrides(args) {
+  return {
+    outDir: args.outDir,
+    maxPartBytes: args.maxPartBytes,
+    maxPartTokens: args.maxPartTokens,
+    skeleton: args.skeleton,
+    sarif: args.sarif,
+    changedSince: args.changedSince,
+    staged: args.staged,
+    withDependents: args.withDependents
+  };
+}
 function failure(message) {
   return { text: message, isError: true };
 }
@@ -753,7 +843,7 @@ function formatBytes(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 function relativeFor(workspace, absolute) {
-  return path2.relative(workspace.root, absolute).split(path2.sep).join("/");
+  return path.relative(workspace.root, absolute).split(path.sep).join("/");
 }
 function capped(values, limit = 20) {
   return { count: values.length, sample: values.slice(0, limit) };
@@ -771,19 +861,50 @@ function summarizeDrift(drift) {
 }
 function toRelativePath(root, value) {
   const cleaned = value.trim();
-  if (cleaned.length === 0) return null;
-  if (!path2.isAbsolute(cleaned)) {
-    return cleaned.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (cleaned.length === 0 || cleaned.includes("\0")) return null;
+  const resolvedRoot = path.resolve(root);
+  const absolute = path.resolve(resolvedRoot, cleaned);
+  const relative3 = path.relative(resolvedRoot, absolute);
+  if (relative3 === "" || relative3 === ".." || relative3.startsWith(`..${path.sep}`) || path.isAbsolute(relative3)) {
+    return null;
   }
-  const relative3 = path2.relative(root, cleaned);
-  if (relative3.startsWith("..") || path2.isAbsolute(relative3)) return null;
-  return relative3.split(path2.sep).join("/");
+  return relative3.split(path.sep).join("/");
 }
 function symbolsOf(entry) {
   const summary = entry.summary;
-  if (!summary || typeof summary !== "object" || !("exports" in summary)) return [];
-  const source = summary;
-  return [...source.exports, ...source.reactComponents, ...source.routeHandlers];
+  if (!summary || typeof summary !== "object") return [];
+  const names = [];
+  const collect = (value) => {
+    if (!Array.isArray(value)) return;
+    for (const item of value) {
+      if (typeof item === "string") names.push(item);
+    }
+  };
+  const record = summary;
+  for (const field of [
+    "exports",
+    "reactComponents",
+    "routeHandlers",
+    "functions",
+    "classes",
+    "interfaces",
+    "types",
+    "enums",
+    "hooks",
+    "headings",
+    // The rest of the same records. `variables` is where a `const`, a Python constant, a Go
+    // `var`, a Rust `mod`, a C `#define` and a Terraform `variable` block all land, so leaving it
+    // out made `snapshot_locate` miss most of what a non-JavaScript file declares; `directives`
+    // carries `"use client"`-style markers, and `frontmatterKeys`/`keys` are the headings and
+    // top-level names of a Markdown or JSON file.
+    "variables",
+    "directives",
+    "frontmatterKeys",
+    "keys"
+  ]) {
+    collect(record[field]);
+  }
+  return names;
 }
 async function prepare(args, context, overrides = {}) {
   const rootOutcome = resolveRoot(args.root, context);
@@ -798,7 +919,7 @@ var statusTool = {
   description: "Report whether a snapshot exists for this repository, when it was built, and what it covers. Reads the manifest rather than the repository, so it is cheap. Call it before deciding whether a snapshot needs to be generated.",
   inputSchema: {
     type: "object",
-    properties: { root: ROOT_PROPERTY },
+    properties: { root: ROOT_PROPERTY, outDir: OUT_DIR_PROPERTY },
     additionalProperties: false
   },
   outputSchema: {
@@ -819,7 +940,7 @@ var statusTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     const read = readManifest(workspace);
@@ -878,10 +999,12 @@ var planTool = {
     type: "object",
     properties: {
       root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY,
       maxPartBytes: {
         type: "string",
         description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
-      }
+      },
+      ...SCOPE_PROPERTIES
     },
     additionalProperties: false
   },
@@ -898,7 +1021,7 @@ var planTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context, { maxPartBytes: args.maxPartBytes });
+    const prepared = await prepare(args, context, workspaceOverrides(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     let manifest;
@@ -952,14 +1075,12 @@ var generateTool = {
     type: "object",
     properties: {
       root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY,
       maxPartBytes: {
         type: "string",
         description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
       },
-      outDir: {
-        type: "string",
-        description: "Output directory relative to the root. Defaults to the project configuration."
-      }
+      ...SCOPE_PROPERTIES
     },
     additionalProperties: false
   },
@@ -975,41 +1096,35 @@ var generateTool = {
   },
   annotations: WRITES,
   async handler(args, context) {
-    const prepared = await prepare(args, context, {
-      maxPartBytes: args.maxPartBytes,
-      outDir: args.outDir
-    });
+    const prepared = await prepare(args, context, workspaceOverrides(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
-    let manifest;
-    try {
-      manifest = generateSnapshot(workspace.config);
-    } catch (error) {
-      return failure(error instanceof Error ? error.message : String(error));
-    }
+    const result = await generateInWorker(workspace.root, workspace.cliOptions);
+    if (!result.ok) return failure(result.message);
+    const summary = result.summary;
     forgetManifest(manifestPathFor(workspace));
-    const written = relativeFor(workspace, path2.resolve(workspace.root, workspace.config.outDir));
+    const written = relativeFor(workspace, path.resolve(workspace.root, workspace.config.outDir));
     const lines = [
       `Wrote ${written}/`,
-      `Files: ${manifest.counts.totalFiles} included, ${manifest.counts.skippedCount} skipped, ${plural(manifest.counts.partsCount, "part")}`,
-      `Parts: ${manifest.parts.map((part) => `${part.filename} (${formatBytes(part.byteSize)})`).join(", ")}`,
-      `Fingerprint: ${manifest.fingerprint}`
+      `Files: ${summary.totalFiles} included, ${summary.skippedCount} skipped, ${plural(summary.partsCount, "part")}`,
+      `Parts: ${summary.parts.map((part) => `${part.filename} (${formatBytes(part.byteSize)})`).join(", ")}`,
+      `Fingerprint: ${summary.fingerprint}`
     ];
-    if (manifest.warnings.length > 0) {
-      lines.push(`Warnings (${manifest.warnings.length}):`);
-      for (const warning of manifest.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
+    if (summary.warnings.length > 0) {
+      lines.push(`Warnings (${summary.warnings.length}):`);
+      for (const warning of summary.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
     }
     return {
       text: lines.join("\n"),
       structured: {
-        fingerprint: manifest.fingerprint,
-        files: manifest.counts.totalFiles,
-        skipped: manifest.counts.skippedCount,
-        parts: manifest.counts.partsCount,
-        emittedBytes: manifest.totals.totalContentBytes,
+        fingerprint: summary.fingerprint,
+        files: summary.totalFiles,
+        skipped: summary.skippedCount,
+        parts: summary.partsCount,
+        emittedBytes: summary.totalContentBytes,
         outDir: written,
-        partFiles: manifest.parts.map((part) => part.filename),
-        warningCount: manifest.warnings.length
+        partFiles: summary.parts.map((part) => part.filename),
+        warningCount: summary.warnings.length
       }
     };
   }
@@ -1020,7 +1135,7 @@ var validateTool = {
   description: "Re-read the repository and report whether the snapshot on disk still matches it. Use it before trusting context that came from an earlier session, or after changing the config.",
   inputSchema: {
     type: "object",
-    properties: { root: ROOT_PROPERTY },
+    properties: { root: ROOT_PROPERTY, outDir: OUT_DIR_PROPERTY, ...SCOPE_PROPERTIES },
     additionalProperties: false
   },
   outputSchema: {
@@ -1032,7 +1147,7 @@ var validateTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, workspaceOverrides(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     let result;
@@ -1099,7 +1214,8 @@ var locateTool = {
         default: 20,
         description: "Maximum matches to return."
       },
-      root: ROOT_PROPERTY
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
     },
     required: ["query"],
     additionalProperties: false
@@ -1110,7 +1226,7 @@ var locateTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     const read = readManifest(workspace);
@@ -1145,12 +1261,13 @@ var locateTool = {
           continue;
         }
       }
-      if (wants("layer") && entry.layer.toLowerCase() === needle) add(entry, "layer");
-      else if (wants("kind") && entry.kind.toLowerCase() === needle) add(entry, "kind");
+      if (wants("layer") && entry.layer.toLowerCase().includes(needle)) add(entry, "layer");
+      else if (wants("kind") && entry.kind.toLowerCase().includes(needle)) add(entry, "kind");
     }
     if (wants("route")) {
       for (const route of manifest.indexes.routes) {
-        if (!route.path.toLowerCase().includes(needle)) continue;
+        const method = route.methods.find((name) => name.toLowerCase().includes(needle));
+        if (!route.path.toLowerCase().includes(needle) && method === void 0) continue;
         if (matches.some((match) => match.path === route.path)) continue;
         matches.push({
           path: route.path,
@@ -1185,6 +1302,127 @@ var locateTool = {
     };
   }
 };
+var dependentsTool = {
+  name: "snapshot_dependents",
+  title: "Follow the import graph",
+  description: 'For one file in the snapshot: what it imports, and which files import it. Answers "what breaks if I change this?" without reading the parts.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Snapshot-relative path, exactly as snapshot_locate or manifest.files[] reports it."
+      },
+      direction: {
+        type: "string",
+        enum: ["both", "imports", "imported-by"],
+        default: "both",
+        description: "Which edges to return."
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 200,
+        default: 50,
+        description: "Maximum entries per direction."
+      },
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      imports: { type: "array" },
+      importedBy: { type: "array" },
+      unresolved: { type: "array" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context, outDirOverride(args));
+    if (!prepared.ok) return prepared.outcome;
+    const read = readManifest(prepared.workspace);
+    if (!read.ok) return failure(read.message);
+    const manifest = read.manifest;
+    const requested = String(args.path ?? "").trim().replace(/\\/g, "/");
+    if (requested.length === 0) return failure('"path" must not be empty.');
+    const filesByPath = new Map(manifest.files.map((file) => [file.relativePath, file]));
+    const entry = filesByPath.get(requested) ?? manifest.files.find((file) => file.relativePath.toLowerCase() === requested.toLowerCase());
+    if (!entry) {
+      return failure(
+        `${requested} is not in the snapshot. Use snapshot_locate to find its path, or snapshot_explain to see whether it was excluded.`
+      );
+    }
+    const direction = args.direction === "imports" || args.direction === "imported-by" ? String(args.direction) : "both";
+    const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : 50;
+    const resolver = buildImportResolver(manifest.files);
+    const imports = [];
+    const unresolved = [];
+    if (direction !== "imported-by") {
+      const own = manifest.indexes.imports.byFile.find((file) => file.path === entry.relativePath);
+      for (const specifier of own?.imports ?? []) {
+        const resolved = resolveSpecifier(entry.relativePath, specifier, resolver);
+        if (resolved === null) {
+          unresolved.push(specifier);
+          continue;
+        }
+        const target = filesByPath.get(resolved);
+        if (target) imports.push({ path: resolved, specifier, part: target.part });
+      }
+    }
+    const importedBy = [];
+    if (direction !== "imports") {
+      for (const candidate of manifest.indexes.imports.byFile) {
+        if (candidate.path === entry.relativePath) continue;
+        const edge = candidate.imports.some(
+          (specifier) => resolveSpecifier(candidate.path, specifier, resolver) === entry.relativePath
+        );
+        if (!edge) continue;
+        const source = filesByPath.get(candidate.path);
+        importedBy.push({ path: candidate.path, part: source?.part ?? "" });
+      }
+    }
+    const shownImports = imports.slice(0, limit);
+    const shownImportedBy = importedBy.slice(0, limit);
+    const lines = [
+      `${entry.relativePath} \u2014 ${importedBy.length} importer(s), ${imports.length} import(s), ${unresolved.length} outside the snapshot.`
+    ];
+    if (direction !== "imports") {
+      lines.push("", "Imported by:");
+      if (shownImportedBy.length === 0) lines.push("  (nothing in the snapshot imports it)");
+      for (const item of shownImportedBy) lines.push(`  ${item.path}  [${item.part}]`);
+      if (importedBy.length > shownImportedBy.length) {
+        lines.push(`  \u2026 ${importedBy.length - shownImportedBy.length} more; raise \`limit\`.`);
+      }
+    }
+    if (direction !== "imported-by") {
+      lines.push("", "Imports:");
+      if (shownImports.length === 0) lines.push("  (none recorded for this file)");
+      for (const item of shownImports) {
+        lines.push(`  ${item.path}  (from "${item.specifier}")  [${item.part}]`);
+      }
+      if (imports.length > shownImports.length) {
+        lines.push(`  \u2026 ${imports.length - shownImports.length} more; raise \`limit\`.`);
+      }
+      if (unresolved.length > 0) {
+        lines.push("", `Outside the snapshot (${unresolved.length}): ${unresolved.join(", ")}`);
+      }
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        path: entry.relativePath,
+        imports: shownImports,
+        importedBy: shownImportedBy,
+        unresolved
+      }
+    };
+  }
+};
 var readTool = {
   name: "snapshot_read",
   title: "Read a file from the snapshot",
@@ -1209,7 +1447,8 @@ var readTool = {
         default: 200,
         description: "How many lines to return."
       },
-      root: ROOT_PROPERTY
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
     },
     required: ["path"],
     additionalProperties: false
@@ -1227,7 +1466,7 @@ var readTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     if (typeof args.path !== "string") return failure('"path" must be a string.');
@@ -1253,7 +1492,12 @@ var readTool = {
         `${relativePath} is not in the snapshot. Call snapshot_locate to find the path, or snapshot_explain to learn why it was excluded.`
       );
     }
-    const partPath = path2.resolve(workspace.root, workspace.config.outDir, "parts", entry.part);
+    const partPath = partPathFor(workspace, entry.part);
+    if (partPath === null) {
+      return failure(
+        `${entry.part} is not a part of this snapshot: its name leaves ${workspace.config.outDir}/parts. Run snapshot_generate to rebuild it.`
+      );
+    }
     let partText;
     try {
       partText = fs.readFileSync(partPath, "utf8");
@@ -1262,7 +1506,7 @@ var readTool = {
         `${entry.part} could not be read, so the snapshot is damaged. Run snapshot_generate to rebuild it.`
       );
     }
-    const section = findSection(parsePartSections(partText), entry.relativePath, entry.hashSha256);
+    const section = findSection(parsePartSections(partText), entry.relativePath);
     if (!section) {
       return failure(
         `${relativePath} is recorded in ${entry.part} but its section could not be located there. Run snapshot_generate to rebuild the snapshot.`
@@ -1274,16 +1518,28 @@ var readTool = {
     let body = window.text;
     let truncatedByBytes = false;
     if (Buffer.byteLength(body, "utf8") > MAX_RESULT_BYTES) {
-      body = body.slice(0, MAX_RESULT_BYTES);
+      const clipped = truncateToBytes(body, MAX_RESULT_BYTES);
+      body = clipped.content;
       const lastBreak = body.lastIndexOf("\n");
       body = lastBreak > 0 ? body.slice(0, lastBreak) : body;
       truncatedByBytes = true;
     }
     const returnedLines = body.length === 0 ? 0 : body.split("\n").length;
-    const moreRemain = window.truncated || truncatedByBytes;
+    const moreRemain = !window.pastEnd && (window.truncated || truncatedByBytes);
     const header = [
       `${entry.relativePath} \u2014 ${entry.part}, ${entry.layer}/${entry.kind}, ${entry.language}`,
-      section.inclusion === "preview" ? "Bounded preview: this source file is large, so the snapshot holds only its head and tail." : `Lines ${window.fromLine}\u2013${window.fromLine + returnedLines - 1} of ${window.totalLines}.`
+      // The line range is the answer to "where am I in this file", and it is computed from the
+      // body the window was taken from, so it is just as meaningful for a preview as for a full
+      // file. It used to be replaced — not augmented — by the preview note, so a 40-line window
+      // into a 300-line preview came back with no range at all and the caller could not tell
+      // where the window ended. Both facts are stated now, and `signatures` is no longer
+      // silently treated as a full file.
+      ...section.inclusion === "preview" ? [
+        "Bounded preview: the snapshot holds this file's head and tail only, so these line numbers count the preview, not the source."
+      ] : section.inclusion === "signatures" ? [
+        "Signatures: function and method bodies were replaced with `{ /* ... */ }` when the snapshot was generated."
+      ] : [],
+      window.totalLines === 0 ? "This file is empty." : window.pastEnd ? `This file has ${window.totalLines} line(s); fromLine=${window.fromLine} is past its end.` : `Lines ${window.fromLine}\u2013${window.fromLine + returnedLines - 1} of ${window.totalLines}.`
     ];
     const lines = [...header, "", body];
     if (moreRemain) {
@@ -1320,7 +1576,9 @@ var explainTool = {
         type: "string",
         description: "Path relative to the repository root. Directories are explained as a whole."
       },
-      root: ROOT_PROPERTY
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY,
+      ...SCOPE_PROPERTIES
     },
     required: ["path"],
     additionalProperties: false
@@ -1335,7 +1593,7 @@ var explainTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, workspaceOverrides(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     if (typeof args.path !== "string") return failure('"path" must be a string.');
@@ -1375,6 +1633,7 @@ function buildTools() {
     generateTool,
     validateTool,
     locateTool,
+    dependentsTool,
     readTool,
     explainTool
   ];
@@ -1446,9 +1705,15 @@ var RESOURCE_TEMPLATE_URIS = ["snapshot://parts/{index}"];
 
 // src/agent/option-scope.ts
 var VALIDATE_OPTIONS = [
+  "sarif",
+  "skeleton",
+  "changed-since",
+  "staged",
+  "with-dependents",
   "cwd",
   "out-dir",
   "max-part-bytes",
+  "max-part-tokens",
   "large-file-bytes",
   "max-monolith-bytes",
   "include-monolith",
@@ -1465,9 +1730,15 @@ var VALIDATE_OPTIONS = [
 ];
 var COMMAND_OPTION_SCOPE = {
   generate: [
+    "sarif",
+    "skeleton",
+    "changed-since",
+    "staged",
+    "with-dependents",
     "cwd",
     "out-dir",
     "max-part-bytes",
+    "max-part-tokens",
     "large-file-bytes",
     "max-monolith-bytes",
     "include-monolith",
@@ -1505,6 +1776,12 @@ var COMMAND_OPTION_SCOPE = {
     "version"
   ],
   explain: [
+    // The scope decides what `explain` says about a file, dependents included: without these,
+    // a file that is in the snapshot only because it imports a changed one was explained as
+    // `included: false, reason: "unchanged"`.
+    "changed-since",
+    "staged",
+    "with-dependents",
     "cwd",
     "out-dir",
     "max-part-bytes",
@@ -1525,6 +1802,7 @@ var COMMAND_OPTION_SCOPE = {
   diff: ["format", "mode", "no-config", "no-update-check", "help", "version"],
   describe: ["format", "mode", "help", "version"],
   init: [
+    "install-hook",
     "cwd",
     "out-dir",
     "max-part-bytes",
@@ -1547,13 +1825,29 @@ var COMMAND_OPTION_SCOPE = {
   // `mcp` reads the repository, so it takes --cwd. It has no --format: stdout carries JSON-RPC
   // messages, and there is no second shape to choose, so offering the flag would be a lie.
   mcp: ["cwd", "mode", "help", "version"],
+  // `setup` generates through the `generate` command, so every generation setting it can
+  // honour is in scope. Rejecting them made the one-command path unable to express a walk
+  // scan, a monolith or a different large-file threshold; the alternative was to run
+  // `setup` and then edit the config it had just written.
   setup: [
+    "install-hook",
     "cwd",
     "out-dir",
     "max-part-bytes",
+    // Persisted into the config `setup` writes, then forwarded to the generation it runs — so
+    // the snapshot it produces validates against the config beside it. Accepting a setting here
+    // without writing it down made `setup --large-file-bytes 100k` finish with a snapshot its
+    // own `validate` called drifted, on the first run of a brand-new project.
+    "max-part-tokens",
+    "skeleton",
+    "sarif",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
     "include-sensitive-files",
     "skip-artifacts",
     "only-artifacts",
+    "discovery",
     "preset",
     "include",
     "exclude",
@@ -1839,6 +2133,13 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("max-part-bytes"),
         summary: 'Byte budget per markdown part. Accepts "120k" / "1.5mb". Minimum 4096.'
       },
+      {
+        flag: "--max-part-tokens",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("max-part-tokens"),
+        summary: "Ceiling on a part expressed in tokens. Narrows --max-part-bytes instead of replacing it; the manifest records both units. Minimum 1024."
+      },
       {
         flag: "--large-file-bytes",
         type: "string",
@@ -1888,6 +2189,41 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("only-artifacts"),
         summary: "Write only these artifacts. Cannot be combined with --skip-artifacts."
       },
+      {
+        flag: "--skeleton",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("skeleton"),
+        summary: 'Replace function and method bodies with `{ /* ... */ }` in TypeScript/TSX files, keeping signatures and comments. The part records inclusionMode "signatures" for each file it touched.'
+      },
+      {
+        flag: "--sarif",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("sarif"),
+        summary: "Also write reports/audit.sarif (SARIF 2.1.0) so a CI security gate can read the redaction findings. The matched value is never included."
+      },
+      {
+        flag: "--changed-since",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("changed-since"),
+        summary: 'Snapshot only the files that differ from this git ref, plus untracked ones. Everything else is recorded in skipped[] with reason "unchanged". Requires a git checkout.'
+      },
+      {
+        flag: "--staged",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("staged"),
+        summary: "Snapshot only the files staged in the index. The pre-commit counterpart of --changed-since."
+      },
+      {
+        flag: "--with-dependents",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("with-dependents"),
+        summary: "Widen a changed-files scope by one hop: files that import a changed file are included too. Only meaningful with --changed-since or --staged."
+      },
       {
         flag: "--format",
         type: "string",
@@ -1995,6 +2331,13 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("no-install"),
         summary: "Skip installing the dependency before generating: `setup`, or `generate --autopilot` (CI, offline, or a lockfile you do not want a package manager to touch)."
       },
+      {
+        flag: "--install-hook",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("install-hook"),
+        summary: "After writing the config, install a pre-commit hook that runs `validate`. An existing hook this tool did not write is left alone."
+      },
       {
         flag: "--no-update-check",
         type: "boolean",
@@ -2031,6 +2374,12 @@ function buildAgentContract() {
         { key: "branch", type: "string", default: "main", summary: "Branch recorded when git cannot report one." },
         { key: "preset", type: "string", default: "detected", summary: "Force a preset. Unknown names are an error." },
         { key: "maxPartBytes", type: "number | string", default: 307200, summary: "Per-part byte budget." },
+        { key: "maxPartTokens", type: "number | string | null", default: null, summary: "Per-part token ceiling; narrows maxPartBytes. Minimum 1024." },
+        { key: "skeleton", type: "boolean", default: false, summary: "Collapse function bodies to `{ /* ... */ }` in TS, JS, TSX and JSX files." },
+        { key: "sarif", type: "boolean", default: false, summary: "Also write reports/audit.sarif." },
+        { key: "changedSince", type: "string | null", default: null, summary: "Snapshot only files that differ from this git ref." },
+        { key: "staged", type: "boolean", default: false, summary: "Snapshot only files staged in the index." },
+        { key: "withDependents", type: "boolean", default: false, summary: "With a changed-files scope, also include one hop of importers." },
         { key: "largeFileBytes", type: "number | string", default: 204800, summary: "Preview threshold for large files." },
         { key: "previewHeadLines", type: "number", default: 80, summary: "Lines kept from the head of a large file." },
         { key: "previewTailLines", type: "number", default: 40, summary: "Lines kept from the tail of a large file." },
@@ -2213,14 +2562,19 @@ do not assume the repository is broken.
    matches the files on disk. Exit 1 means drift \u2014 re-run step 5.
 
 7. **Read the output in this order:**
-   - \`snapshot/parts/part-*.md\` \u2014 the code itself, each file tagged with its layer, kind,
-     language and, when it fits the budget, a structural summary (imports, exports,
-     classes, functions). A dropped summary appears as a \`Summary: (omitted \u2026)\` line.
+   - \`snapshot/parts/part-*.md\` \u2014 the code itself. Each file carries one \`- Meta:\` line
+     (layer/kind, language, inclusion, size) and, only when the body is **not** the whole
+     file, a structural summary (imports, exports, classes, functions). A full file has no
+     summary line, because the summary would repeat the code three lines below it \u2014 read
+     \`manifest.json\` for it. A summary dropped to fit the budget appears as a
+     \`Summary: (omitted \u2026)\` line.
    - \`snapshot/manifest.json\` \u2014 the index. \`files[]\` has \`relativePath\`, \`layer\`,
-     \`kind\`, \`language\`, \`part\`, \`inclusionMode\` and \`hashSha256\`, plus \`encoding\`
-     when the file was not plain UTF-8. \`summary\` is **optional**: it is absent for
-     languages with no structural summary, and \`summaryOmitted: true\` marks one dropped
-     to fit the part budget \u2014 never assume it exists.
+     \`kind\`, \`language\`, \`part\`, \`inclusionMode\`, \`hashSha256\` and the structural
+     \`summary\`, plus \`encoding\` when the file was not plain UTF-8. \`summary\` is
+     **optional**: it is absent for languages with no structural summary, and
+     \`summaryOmitted: true\` marks one dropped to fit the part budget \u2014 never assume it
+     exists. The per-file \`hashSha256\` is only here and in the manifest; it is not printed
+     into the parts.
      \`skipped[]\` records every excluded file **and why**. Prefer querying this over
      re-reading the parts.
    - \`snapshot/reports/audit.md\` \u2014 secrets found, large files, parse diagnostics, git
@@ -2274,7 +2628,7 @@ diff, and the commit, are then yours.
 ## When the client speaks MCP
 
 If the agent runs inside an MCP client, \`npx ${PACKAGE_NAME2}@latest mcp\` serves this repository
-as seven tools over stdio instead of shelling out. Its reads come from the snapshot rather than
+as eight tools over stdio instead of shelling out. Its reads come from the snapshot rather than
 the working tree, so excluded files and redacted values never reach the context. Use
 \`snapshot_locate\` before \`snapshot_read\`, and \`snapshot_validate\` before trusting a snapshot
 from an earlier session.
@@ -2394,7 +2748,7 @@ function buildResourceProvider() {
       const report = REPORT_URIS.get(uri);
       if (report) {
         const text = readFileIfPresent(
-          path2.resolve(workspace.root, workspace.config.outDir, "reports", report.file)
+          path.resolve(workspace.root, workspace.config.outDir, "reports", report.file)
         );
         if (text === null) return null;
         return { uri, mimeType: "text/markdown", text: capUtf8(text, MAX_RESOURCE_BYTES).text };
@@ -2412,9 +2766,9 @@ function buildResourceProvider() {
         const index = Number(partMatch[1]);
         const part = read.manifest.parts.find((candidate) => candidate.index === index);
         if (!part) return null;
-        const text = readFileIfPresent(
-          path2.resolve(workspace.root, workspace.config.outDir, "parts", part.filename)
-        );
+        const partPath = partPathFor(workspace, part.filename);
+        if (partPath === null) return null;
+        const text = readFileIfPresent(partPath);
         if (text === null) return null;
         return { uri, mimeType: "text/markdown", text: capUtf8(text, MAX_RESOURCE_BYTES).text };
       }
@@ -2431,7 +2785,8 @@ var SERVER_INSTRUCTIONS = [
   "1. snapshot_status \u2014 is there a snapshot here, and has the tree moved since it was built?",
   "2. snapshot_locate \u2014 find which part holds the code you need.",
   "3. snapshot_read \u2014 read a window of one file. Never read a part end to end.",
-  "4. snapshot_validate \u2014 before trusting context that came from an earlier conversation.",
+  "4. snapshot_dependents \u2014 before changing a file, see what imports it.",
+  "5. snapshot_validate \u2014 before trusting context that came from an earlier conversation.",
   "",
   "Rules that matter:",
   "- Parts are budgeted, not small: a 12-part snapshot is hundreds of kilobytes. Use snapshot_locate first.",
@@ -2457,6 +2812,7 @@ function createWriter(output) {
 }
 function createLineReader(input, options) {
   let buffer = "";
+  let bufferBytes = 0;
   let discarding = false;
   let discardedBytes = 0;
   const deliver = (line) => {
@@ -2469,43 +2825,71 @@ function createLineReader(input, options) {
     if (trimmed.trim().length === 0) return;
     options.onLine(trimmed);
   };
+  const discardBuffered = () => {
+    discarding = true;
+    discardedBytes += bufferBytes;
+    buffer = "";
+    bufferBytes = 0;
+    options.onOverflow?.(discardedBytes);
+  };
   const drain = () => {
     let index = buffer.indexOf("\n");
     while (index >= 0) {
       const line = buffer.slice(0, index);
       buffer = buffer.slice(index + 1);
-      deliver(line);
+      if (discarding) {
+        deliver(line);
+      } else {
+        const lineBytes = Buffer.byteLength(line, "utf8");
+        if (lineBytes > MAX_LINE_BYTES) options.onOverflow?.(lineBytes);
+        else deliver(line);
+      }
       index = buffer.indexOf("\n");
     }
+    bufferBytes = Buffer.byteLength(buffer, "utf8");
+    if (!discarding && bufferBytes > MAX_LINE_BYTES) discardBuffered();
   };
   const onData = (chunk) => {
+    const chunkBytes = Buffer.byteLength(chunk, "utf8");
     if (discarding) {
       const index = chunk.indexOf("\n");
       if (index < 0) {
-        discardedBytes += chunk.length;
+        discardedBytes += chunkBytes;
         return;
       }
       buffer = chunk.slice(index + 1);
+      bufferBytes = Buffer.byteLength(buffer, "utf8");
       deliver("");
       drain();
       return;
     }
-    buffer += chunk;
-    if (buffer.length > MAX_LINE_BYTES && buffer.indexOf("\n") < 0) {
+    if (chunk.indexOf("\n") < 0 && bufferBytes + chunkBytes > MAX_LINE_BYTES) {
       discarding = true;
-      discardedBytes = buffer.length;
+      discardedBytes = bufferBytes + chunkBytes;
       buffer = "";
+      bufferBytes = 0;
       options.onOverflow?.(discardedBytes);
       return;
     }
+    buffer += chunk;
     drain();
   };
   const onEnd = () => {
-    if (buffer.length > 0) {
-      const rest = buffer;
-      buffer = "";
-      deliver(rest);
+    const rest = buffer;
+    const restBytes = bufferBytes || Buffer.byteLength(rest, "utf8");
+    buffer = "";
+    bufferBytes = 0;
+    if (rest.length === 0) return;
+    if (discarding) {
+      discarding = false;
+      discardedBytes = 0;
+      return;
+    }
+    if (restBytes > MAX_LINE_BYTES) {
+      options.onOverflow?.(restBytes);
+      return;
     }
+    deliver(rest);
   };
   input.setEncoding("utf8");
   input.on("data", onData);
@@ -2598,6 +2982,4 @@ async function runStdioServer(options) {
   return code;
 }
 
-export { COMMAND_OPTION_SCOPE, ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SKILL_NAME, SUPPORTED_PROTOCOL_VERSIONS, buildAgentContract, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, commandsForOption, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, renderContractText, renderSkill, runStdioServer, validateArguments };
-//# sourceMappingURL=chunk-HQBEQ67K.js.map
-//# sourceMappingURL=chunk-HQBEQ67K.js.map
+export { COMMAND_OPTION_SCOPE, ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SKILL_NAME, SUPPORTED_PROTOCOL_VERSIONS, buildAgentContract, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, commandsForOption, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, renderContractText, renderSkill, runStdioServer, validateArguments, windowText };