@davmash/bygone 0.5.2 → 0.7.0

package/out/changeTour.js

@@ -0,0 +1,1901 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/changeTour.ts
+var changeTour_exports = {};
+__export(changeTour_exports, {
+  buildChangeInventory: () => buildChangeInventory,
+  buildChangeTourContext: () => buildChangeTourContext,
+  buildChangeTourManifest: () => buildChangeTourManifest,
+  buildDeconstructedScene: () => buildDeconstructedScene,
+  compileDeconstructedScene: () => compileDeconstructedScene,
+  materializeChangeUnits: () => materializeChangeUnits,
+  parseChangeTourManifest: () => parseChangeTourManifest,
+  parseChangeTourSource: () => parseChangeTourSource,
+  parseChangeTourStory: () => parseChangeTourStory
+});
+module.exports = __toCommonJS(changeTour_exports);
+var import_child_process4 = require("child_process");
+
+// src/gitComparison.ts
+var import_child_process = require("child_process");
+var fs = __toESM(require("fs"));
+var DEFAULT_GIT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+function createGitRunner(maxBuffer = readGitMaxBuffer()) {
+  return (args, cwd) => (0, import_child_process.execFileSync)("git", [...args], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer,
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trimEnd();
+}
+function resolveBranchReviewRange(startPath, headRef = "HEAD", requestedBaseRef, runGit3 = createGitRunner()) {
+  const repoRoot = fs.realpathSync(runGit3(["rev-parse", "--show-toplevel"], startPath));
+  const currentBranch = tryRunGit(runGit3, ["symbolic-ref", "--quiet", "--short", "HEAD"], repoRoot);
+  const baseRef = requestedBaseRef || detectDefaultBaseRef(repoRoot, headRef, runGit3);
+  const headOid = verifyCommit(repoRoot, headRef, runGit3);
+  const baseOid = verifyCommit(repoRoot, baseRef, runGit3);
+  const mergeBaseOids = runGit3(["merge-base", "--all", baseOid, headOid], repoRoot).split("\n").filter(Boolean);
+  if (mergeBaseOids.length === 0) {
+    throw new Error(`No merge base exists between ${baseRef} and ${headRef}.`);
+  }
+  if (mergeBaseOids.length > 1) {
+    throw new Error(
+      `Multiple merge bases exist between ${baseRef} and ${headRef}: ${mergeBaseOids.map((oid) => oid.slice(0, 7)).join(", ")}. Pass one merge-base commit explicitly with --base.`
+    );
+  }
+  const mergeBaseOid = mergeBaseOids[0];
+  return {
+    repoRoot,
+    baseRef,
+    headRef,
+    baseOid,
+    headOid,
+    mergeBaseOid,
+    currentBranch: currentBranch || void 0,
+    dirty: runGit3(["status", "--porcelain=v1", "--untracked-files=normal"], repoRoot).length > 0,
+    changedPaths: listChangedPaths(repoRoot, mergeBaseOid, headOid, runGit3),
+    commits: listBranchCommits(repoRoot, mergeBaseOid, headOid, runGit3)
+  };
+}
+function detectDefaultBaseRef(repoRoot, headRef = "HEAD", runGit3 = createGitRunner()) {
+  const remoteDefault = tryRunGit(
+    runGit3,
+    ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"],
+    repoRoot
+  );
+  const candidates = [remoteDefault, "main", "master"].filter((candidate) => Boolean(candidate)).filter((candidate, index, all) => all.indexOf(candidate) === index);
+  for (const candidate of candidates) {
+    if (candidate !== headRef && canResolveCommit(repoRoot, candidate, runGit3)) {
+      return candidate;
+    }
+  }
+  throw new Error("Could not detect a base branch. Pass --base <ref>.");
+}
+function listChangedPaths(repoRoot, baseOid, headOid, runGit3 = createGitRunner()) {
+  const output = runGit3([
+    "diff",
+    "--name-status",
+    "-z",
+    "--find-renames",
+    "--find-copies",
+    baseOid,
+    headOid,
+    "--"
+  ], repoRoot);
+  return parseNameStatusZ(output);
+}
+function parseNameStatusZ(output) {
+  const fields = output.split("\0");
+  if (fields[fields.length - 1] === "") {
+    fields.pop();
+  }
+  const changedPaths = [];
+  for (let index = 0; index < fields.length; ) {
+    const status = fields[index++];
+    if (!status) {
+      continue;
+    }
+    const code = status[0];
+    const similarityText = status.slice(1);
+    const similarity = similarityText ? Number.parseInt(similarityText, 10) : void 0;
+    if (code === "R" || code === "C") {
+      const previousPath = fields[index++];
+      const nextPath = fields[index++];
+      if (previousPath && nextPath) {
+        changedPaths.push({
+          kind: code === "R" ? "renamed" : "copied",
+          path: nextPath,
+          previousPath,
+          similarity: Number.isFinite(similarity) ? similarity : void 0
+        });
+      }
+      continue;
+    }
+    const changedPath = fields[index++];
+    if (!changedPath) {
+      continue;
+    }
+    changedPaths.push({
+      kind: changeKindForStatus(code),
+      path: changedPath
+    });
+  }
+  return changedPaths;
+}
+function listBranchCommits(repoRoot, mergeBaseOid, headOid, runGit3 = createGitRunner()) {
+  const output = runGit3([
+    "log",
+    "--reverse",
+    "--topo-order",
+    "--format=%H%x00%h%x00%cI%x00%s%x00%P%x1e",
+    `${mergeBaseOid}..${headOid}`
+  ], repoRoot);
+  return output.split("").map((record) => record.replace(/^\n+|\n+$/g, "")).filter(Boolean).map((record) => {
+    const [oid = "", shortOid = "", timestamp = "", summary = "", parents = ""] = record.split("\0");
+    return {
+      oid,
+      shortOid,
+      timestamp,
+      summary,
+      parentOids: parents.split(" ").filter(Boolean)
+    };
+  }).filter((commit) => Boolean(commit.oid));
+}
+function resolveReviewPathPair(changedPaths, selectedPath) {
+  const changedPath = changedPaths.find((candidate) => candidate.path === selectedPath || candidate.previousPath === selectedPath);
+  if (!changedPath) {
+    return void 0;
+  }
+  const relatesDistinctPaths = (changedPath.kind === "renamed" || changedPath.kind === "copied") && Boolean(changedPath.previousPath);
+  const leftPath = changedPath.kind === "added" ? null : relatesDistinctPaths ? changedPath.previousPath ?? null : changedPath.path;
+  const rightPath = changedPath.kind === "deleted" ? null : changedPath.path;
+  const relationVerb = changedPath.kind === "renamed" ? "Renamed" : changedPath.kind === "copied" ? "Copied" : null;
+  return {
+    key: changedPath.path,
+    leftPath,
+    rightPath,
+    kind: changedPath.kind,
+    similarity: changedPath.similarity,
+    summary: relationVerb && changedPath.previousPath ? `${relationVerb} ${changedPath.previousPath} \u2192 ${changedPath.path}` + (changedPath.similarity === void 0 ? "" : ` \xB7 ${changedPath.similarity}% similarity`) : void 0
+  };
+}
+function verifyCommit(repoRoot, ref, runGit3) {
+  try {
+    return runGit3(["rev-parse", "--verify", `${ref}^{commit}`], repoRoot);
+  } catch {
+    throw new Error(`Could not resolve git ref "${ref}".`);
+  }
+}
+function canResolveCommit(repoRoot, ref, runGit3) {
+  try {
+    verifyCommit(repoRoot, ref, runGit3);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function tryRunGit(runGit3, args, cwd) {
+  try {
+    return runGit3(args, cwd);
+  } catch {
+    return "";
+  }
+}
+function changeKindForStatus(code) {
+  if (code === "A") {
+    return "added";
+  }
+  if (code === "D") {
+    return "deleted";
+  }
+  if (code === "M") {
+    return "modified";
+  }
+  if (code === "T") {
+    return "type-changed";
+  }
+  if (code === "U") {
+    return "unmerged";
+  }
+  return "unknown";
+}
+function readGitMaxBuffer() {
+  const parsed = Number.parseInt(process.env.BYGONE_GIT_MAX_BUFFER_BYTES ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_GIT_MAX_BUFFER_BYTES;
+}
+
+// src/changeTourManifest.ts
+var CHANGE_TOUR_MANIFEST_VERSION = 1;
+function parseChangeTourManifest(value) {
+  if (!isRecord(value) || value.version !== CHANGE_TOUR_MANIFEST_VERSION) {
+    throw new Error(`Unsupported or missing change-tour manifest version.`);
+  }
+  requireString(value.title, "title");
+  requireString(value.generatedAt, "generatedAt");
+  if (value.sourceUrl !== void 0) {
+    requireString(value.sourceUrl, "sourceUrl");
+  }
+  if (!isRecord(value.range)) {
+    throw new Error("Change-tour manifest range must be an object.");
+  }
+  for (const key of ["baseRef", "headRef", "mergeBaseOid", "headOid"]) {
+    requireString(value.range[key], `range.${key}`);
+  }
+  if (!isRecord(value.summary)) {
+    throw new Error("Change-tour manifest summary must be an object.");
+  }
+  for (const key of ["changedFiles", "includedScenes", "additions", "deletions", "commitCount"]) {
+    requireNonNegativeInteger(value.summary[key], `summary.${key}`);
+  }
+  requireStringArray(value.summary.omittedFiles, "summary.omittedFiles");
+  if (!Array.isArray(value.commits) || !Array.isArray(value.chapters) || !Array.isArray(value.scenes)) {
+    throw new Error("Change-tour manifest commits, chapters, and scenes must be arrays.");
+  }
+  if (value.files !== void 0 && !Array.isArray(value.files)) {
+    throw new Error("Change-tour manifest files must be an array.");
+  }
+  const sceneIds = /* @__PURE__ */ new Set();
+  for (const [index, candidate] of value.scenes.entries()) {
+    validateScene(candidate, index);
+    if (sceneIds.has(candidate.id)) {
+      throw new Error(`Duplicate change-tour scene id: ${candidate.id}`);
+    }
+    sceneIds.add(candidate.id);
+  }
+  for (const [index, candidate] of value.chapters.entries()) {
+    if (!isRecord(candidate)) {
+      throw new Error(`chapters[${index}] must be an object.`);
+    }
+    requireString(candidate.id, `chapters[${index}].id`);
+    requireString(candidate.title, `chapters[${index}].title`);
+    requireStringArray(candidate.sceneIds, `chapters[${index}].sceneIds`);
+    for (const sceneId of candidate.sceneIds) {
+      if (!sceneIds.has(sceneId)) {
+        throw new Error(`Chapter references unknown scene id: ${sceneId}`);
+      }
+    }
+  }
+  if (value.summary.includedScenes !== value.scenes.length) {
+    throw new Error("summary.includedScenes must match the number of scenes.");
+  }
+  const files = value.files === void 0 ? collectLegacyTourFiles(value.scenes) : value.files.map((candidate, index) => {
+    validateTourFile(candidate, index);
+    return candidate;
+  });
+  if (value.files !== void 0 && value.summary.changedFiles !== files.length) {
+    throw new Error("summary.changedFiles must match the number of files.");
+  }
+  return { ...value, files };
+}
+function parseChangeTourStory(value) {
+  if (!isRecord(value) || !Array.isArray(value.scenes)) {
+    throw new Error("Change-tour story must contain a scenes array.");
+  }
+  if (value.title !== void 0) {
+    requireString(value.title, "title");
+  }
+  if (value.sourceUrl !== void 0) {
+    requireString(value.sourceUrl, "sourceUrl");
+  }
+  for (const [index, scene] of value.scenes.entries()) {
+    if (!isRecord(scene) || scene.kind !== "discussion" && scene.kind !== "file") {
+      throw new Error(`story.scenes[${index}] must be a discussion or file scene.`);
+    }
+    requireString(scene.chapterId, `story.scenes[${index}].chapterId`);
+    requireString(scene.chapterTitle, `story.scenes[${index}].chapterTitle`);
+    validateNarrative(scene, `story.scenes[${index}]`);
+    if (scene.kind === "discussion") {
+      requireString(scene.title, `story.scenes[${index}].title`);
+    } else {
+      requireString(scene.path, `story.scenes[${index}].path`);
+      if (scene.title !== void 0) {
+        requireString(scene.title, `story.scenes[${index}].title`);
+      }
+      if (scene.focusChangeIndex !== void 0) {
+        requireNonNegativeInteger(scene.focusChangeIndex, `story.scenes[${index}].focusChangeIndex`);
+      }
+    }
+  }
+  return value;
+}
+function validateScene(value, index) {
+  if (!isRecord(value) || !["text-diff", "discussion", "walkthrough", "stacked-diff", "deconstructed-diff"].includes(String(value.kind))) {
+    throw new Error(`scenes[${index}] must be a text-diff, discussion, walkthrough, stacked-diff, or deconstructed-diff scene.`);
+  }
+  for (const key of ["id", "title"]) {
+    requireString(value[key], `scenes[${index}].${key}`);
+  }
+  validateNarrative(value, `scenes[${index}]`);
+  if (value.kind === "discussion") {
+    return;
+  }
+  if (value.kind === "walkthrough") {
+    if (!Array.isArray(value.steps) || value.steps.length === 0) {
+      throw new Error(`scenes[${index}].steps must be a non-empty array.`);
+    }
+    for (const [stepIndex, step] of value.steps.entries()) {
+      const path = `scenes[${index}].steps[${stepIndex}]`;
+      if (!isRecord(step) || !isRecord(step.focus) || !isRecord(step.diff)) {
+        throw new Error(`${path} must contain focus and diff objects.`);
+      }
+      for (const key of ["id", "title", "body"]) requireString(step[key], `${path}.${key}`);
+      if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
+        throw new Error(`${path}.depth must be mentioned, explained, or contextualized.`);
+      }
+      validateResolvedAnchor(step.focus, `${path}.focus`);
+      validateScene(step.diff, index);
+      if (step.diff.kind !== "text-diff") throw new Error(`${path}.diff must be a text-diff scene.`);
+      if (step.connection !== void 0) {
+        if (!isRecord(step.connection)) throw new Error(`${path}.connection must be an object.`);
+        requireString(step.connection.id, `${path}.connection.id`);
+        requireString(step.connection.label, `${path}.connection.label`);
+        validateResolvedAnchor(step.connection.from, `${path}.connection.from`);
+        validateResolvedAnchor(step.connection.to, `${path}.connection.to`);
+      }
+    }
+    return;
+  }
+  if (value.kind === "stacked-diff") {
+    validateStackedScene(value, index);
+    return;
+  }
+  if (value.kind === "deconstructed-diff") {
+    validateDeconstructedScene(value, index);
+    return;
+  }
+  for (const key of ["path", "leftLabel", "rightLabel", "leftContent", "rightContent"]) {
+    requireString(value[key], `scenes[${index}].${key}`);
+  }
+  if (value.previousPath !== void 0) {
+    requireString(value.previousPath, `scenes[${index}].previousPath`);
+  }
+  requireString(value.changeKind, `scenes[${index}].changeKind`);
+  requireNonNegativeInteger(value.additions, `scenes[${index}].additions`);
+  requireNonNegativeInteger(value.deletions, `scenes[${index}].deletions`);
+  if (value.focusChangeIndex !== void 0) {
+    requireNonNegativeInteger(value.focusChangeIndex, `scenes[${index}].focusChangeIndex`);
+  }
+}
+function validateStackedScene(value, index) {
+  if (!Array.isArray(value.stack) || value.stack.length < 3 || value.stack.length > 6) {
+    throw new Error(`scenes[${index}].stack must contain between 3 and 6 revisions.`);
+  }
+  for (const [panelIndex, panel] of value.stack.entries()) {
+    if (!isRecord(panel)) throw new Error(`scenes[${index}].stack[${panelIndex}] must be an object.`);
+    for (const key of ["id", "ref", "oid", "label"]) requireString(panel[key], `scenes[${index}].stack[${panelIndex}].${key}`);
+  }
+  validateMultiPanelFiles(value.files, value.stack.length, index);
+  validateMultiPanelSteps(value.steps, value.stack.length, index, false);
+}
+function validateDeconstructedScene(value, index) {
+  if (value.stageLabel !== "Explanation stages") {
+    throw new Error(`scenes[${index}].stageLabel must be Explanation stages.`);
+  }
+  if (!isRecord(value.realRange)) throw new Error(`scenes[${index}].realRange must be an object.`);
+  for (const key of ["baseRef", "targetRef", "baseOid", "targetOid"]) {
+    requireString(value.realRange[key], `scenes[${index}].realRange.${key}`);
+  }
+  if (!Array.isArray(value.panels) || value.panels.length < 2 || value.panels.length > 13) {
+    throw new Error(`scenes[${index}].panels must contain a baseline and between 1 and 12 stages.`);
+  }
+  const panels = value.panels;
+  for (const [panelIndex, panel] of panels.entries()) {
+    if (!isRecord(panel)) throw new Error(`scenes[${index}].panels[${panelIndex}] must be an object.`);
+    for (const key of ["id", "label", "role"]) requireString(panel[key], `scenes[${index}].panels[${panelIndex}].${key}`);
+    const expectedRole = panelIndex === 0 ? "baseline" : "stage";
+    if (panel.role !== expectedRole) throw new Error(`scenes[${index}].panels[${panelIndex}].role must be ${expectedRole}.`);
+    if (panelIndex > 0) requireString(panel.stageId, `scenes[${index}].panels[${panelIndex}].stageId`);
+  }
+  validateMultiPanelFiles(value.files, panels.length, index);
+  validateMultiPanelSteps(value.steps, panels.length, index, true);
+  if (Array.isArray(value.steps) && value.steps.length !== panels.length - 1) {
+    throw new Error(`scenes[${index}].steps must match the number of explanation stages.`);
+  }
+  if (Array.isArray(value.steps)) {
+    value.steps.forEach((step, stepIndex) => {
+      const panel = panels[stepIndex + 1];
+      if (!isRecord(step) || !isRecord(panel) || panel.stageId !== step.id) {
+        throw new Error(`scenes[${index}].panels must align with explanation stage ids.`);
+      }
+    });
+  }
+}
+function validateMultiPanelFiles(value, panelCount, index) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`scenes[${index}].files must be non-empty.`);
+  for (const [fileIndex, file] of value.entries()) {
+    if (!isRecord(file)) throw new Error(`scenes[${index}].files[${fileIndex}] must be an object.`);
+    requireString(file.path, `scenes[${index}].files[${fileIndex}].path`);
+    if (!Array.isArray(file.panels) || file.panels.length !== panelCount) {
+      throw new Error(`scenes[${index}].files[${fileIndex}].panels must match panel count.`);
+    }
+    for (const [panelIndex, panel] of file.panels.entries()) {
+      if (!isRecord(panel)) throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}] must be an object.`);
+      for (const key of ["id", "label", "content"]) requireString(panel[key], `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].${key}`);
+      if (panel.path !== void 0) requireString(panel.path, `scenes[${index}].files[${fileIndex}].panels[${panelIndex}].path`);
+      if (typeof panel.exists !== "boolean") throw new Error(`scenes[${index}].files[${fileIndex}].panels[${panelIndex}].exists must be boolean.`);
+    }
+  }
+}
+function validateMultiPanelSteps(value, panelCount, index, deconstructed) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`scenes[${index}].steps must be non-empty.`);
+  for (const [stepIndex, step] of value.entries()) {
+    if (!isRecord(step)) throw new Error(`scenes[${index}].steps[${stepIndex}] must be an object.`);
+    for (const key of ["id", "title", "body", "file", "side"]) requireString(step[key], `scenes[${index}].steps[${stepIndex}].${key}`);
+    requireNonNegativeInteger(step.pairIndex, `scenes[${index}].steps[${stepIndex}].pairIndex`);
+    if (Number(step.pairIndex) >= panelCount - 1) throw new Error(`scenes[${index}].steps[${stepIndex}].pairIndex is outside the panels.`);
+    if (deconstructed) {
+      requireStringArray(step.introducedHunks, `scenes[${index}].steps[${stepIndex}].introducedHunks`);
+      if (step.introducedHunks.length === 0) throw new Error(`scenes[${index}].steps[${stepIndex}].introducedHunks must be non-empty.`);
+      if (Number(step.pairIndex) !== stepIndex) throw new Error(`scenes[${index}].steps[${stepIndex}].pairIndex must match its explanation stage.`);
+    }
+    if (step.side !== "left" && step.side !== "right") throw new Error(`scenes[${index}].steps[${stepIndex}].side must be left or right.`);
+    if (step.startLine !== void 0) requirePositiveInteger(step.startLine, `scenes[${index}].steps[${stepIndex}].startLine`);
+    if (step.endLine !== void 0) requirePositiveInteger(step.endLine, `scenes[${index}].steps[${stepIndex}].endLine`);
+  }
+}
+function validateTourFile(value, index) {
+  if (!isRecord(value)) throw new Error(`files[${index}] must be an object.`);
+  if (value.kind === "text-diff") {
+    validateScene(value, index);
+    return;
+  }
+  if (value.kind !== "omitted") {
+    throw new Error(`files[${index}].kind must be text-diff or omitted.`);
+  }
+  for (const key of ["id", "title", "path", "changeKind", "reason"]) {
+    requireString(value[key], `files[${index}].${key}`);
+  }
+  if (value.previousPath !== void 0) requireString(value.previousPath, `files[${index}].previousPath`);
+  requireNonNegativeInteger(value.additions, `files[${index}].additions`);
+  requireNonNegativeInteger(value.deletions, `files[${index}].deletions`);
+}
+function collectLegacyTourFiles(scenes) {
+  const files = /* @__PURE__ */ new Map();
+  for (const scene of scenes) {
+    if (scene.kind === "text-diff") {
+      if (!files.has(scene.path)) files.set(scene.path, scene);
+      continue;
+    }
+    if (scene.kind === "walkthrough") {
+      for (const step of scene.steps) {
+        if (!files.has(step.diff.path)) files.set(step.diff.path, step.diff);
+      }
+    }
+  }
+  return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+function validateResolvedAnchor(value, path) {
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  for (const key of ["id", "path", "revision", "excerpt"]) requireString(value[key], `${path}.${key}`);
+  if (value.revision !== "base" && value.revision !== "head") throw new Error(`${path}.revision must be base or head.`);
+  requirePositiveInteger(value.startLine, `${path}.startLine`);
+  requirePositiveInteger(value.endLine, `${path}.endLine`);
+  if (Number(value.endLine) < Number(value.startLine)) throw new Error(`${path}.endLine must not precede startLine.`);
+}
+function validateNarrative(value, path) {
+  requireString(value.summary, `${path}.summary`);
+  requireStringArray(value.bullets, `${path}.bullets`);
+  requireStringArray(value.tags, `${path}.tags`);
+  requireString(value.takeaway, `${path}.takeaway`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, path) {
+  if (typeof value !== "string") {
+    throw new Error(`${path} must be a string.`);
+  }
+}
+function requireStringArray(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${path} must be an array of strings.`);
+  }
+}
+function requireNonNegativeInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 0) {
+    throw new Error(`${path} must be a non-negative integer.`);
+  }
+}
+function requirePositiveInteger(value, path) {
+  if (!Number.isInteger(value) || Number(value) < 1) throw new Error(`${path} must be a positive integer.`);
+}
+
+// src/changeTourSource.ts
+var CHANGE_TOUR_SOURCE_VERSION = 1;
+function parseChangeTourSource(value) {
+  if (!isRecord2(value) || value.version !== CHANGE_TOUR_SOURCE_VERSION) {
+    throw new Error("Unsupported or missing change-tour source version.");
+  }
+  requireOnlyKeys(value, ["version", "title", "sourceUrl", "range", "anchors", "connections", "chapters", "coverage"], "source");
+  optionalString(value.title, "title");
+  optionalString(value.sourceUrl, "sourceUrl");
+  if (value.range !== void 0) {
+    if (!isRecord2(value.range)) throw new Error("range must be an object.");
+    requireOnlyKeys(value.range, ["base", "head"], "range");
+    requireString2(value.range.base, "range.base");
+    requireString2(value.range.head, "range.head");
+  }
+  if (value.coverage !== void 0) {
+    if (!isRecord2(value.coverage) || !Array.isArray(value.coverage.exclusions)) {
+      throw new Error("coverage must contain an exclusions array.");
+    }
+    requireOnlyKeys(value.coverage, ["exclusions"], "coverage");
+    for (const [index, exclusion] of value.coverage.exclusions.entries()) {
+      const exclusionPath = `coverage.exclusions[${index}]`;
+      if (!isRecord2(exclusion)) throw new Error(`${exclusionPath} must be an object.`);
+      requireOnlyKeys(exclusion, ["path", "hunks", "reason"], exclusionPath);
+      requireString2(exclusion.path, `${exclusionPath}.path`);
+      requireString2(exclusion.reason, `${exclusionPath}.reason`);
+      if (exclusion.hunks !== void 0) requireStringArray2(exclusion.hunks, `${exclusionPath}.hunks`);
+    }
+  }
+  if (!isRecord2(value.anchors)) {
+    throw new Error("anchors must be an object.");
+  }
+  for (const [id, anchor] of Object.entries(value.anchors)) {
+    if (!isRecord2(anchor)) {
+      throw new Error(`anchors.${id} must be an object.`);
+    }
+    requireOnlyKeys(anchor, ["file", "revision", "contains", "occurrence"], `anchors.${id}`);
+    requireString2(anchor.file, `anchors.${id}.file`);
+    if (anchor.revision !== "base" && anchor.revision !== "head") {
+      throw new Error(`anchors.${id}.revision must be base or head.`);
+    }
+    requireString2(anchor.contains, `anchors.${id}.contains`);
+    if (anchor.occurrence !== void 0 && (!Number.isInteger(anchor.occurrence) || Number(anchor.occurrence) < 1)) {
+      throw new Error(`anchors.${id}.occurrence must be a positive integer.`);
+    }
+  }
+  const rawConnections = Array.isArray(value.connections) ? value.connections : isRecord2(value.connections) ? Object.entries(value.connections).map(([id, connection]) => isRecord2(connection) ? { id, ...connection } : connection) : null;
+  if (!rawConnections || !Array.isArray(value.chapters) || value.chapters.length === 0) {
+    throw new Error("connections must be an array or object, and chapters must be a non-empty array.");
+  }
+  const connectionIds = /* @__PURE__ */ new Set();
+  for (const [index, connection] of rawConnections.entries()) {
+    if (!isRecord2(connection)) {
+      throw new Error(`connections[${index}] must be an object.`);
+    }
+    requireOnlyKeys(connection, ["id", "from", "to", "label"], `connections[${index}]`);
+    requireString2(connection.id, `connections[${index}].id`);
+    requireString2(connection.from, `connections[${index}].from`);
+    requireString2(connection.to, `connections[${index}].to`);
+    requireString2(connection.label, `connections[${index}].label`);
+    const { id, from, to } = connection;
+    if (!value.anchors[from] || !value.anchors[to]) {
+      throw new Error(`Connection ${id} references an unknown anchor.`);
+    }
+    if (connectionIds.has(id)) {
+      throw new Error(`Duplicate connection id: ${id}`);
+    }
+    connectionIds.add(id);
+  }
+  const chapterIds = /* @__PURE__ */ new Set();
+  const sceneIds = /* @__PURE__ */ new Set();
+  for (const [chapterIndex, chapter] of value.chapters.entries()) {
+    if (!isRecord2(chapter) || !Array.isArray(chapter.scenes) || chapter.scenes.length === 0) {
+      throw new Error(`chapters[${chapterIndex}] must contain a non-empty scenes array.`);
+    }
+    requireString2(chapter.id, `chapters[${chapterIndex}].id`);
+    requireString2(chapter.title, `chapters[${chapterIndex}].title`);
+    requireOnlyKeys(chapter, ["id", "title", "scenes"], `chapters[${chapterIndex}]`);
+    if (chapterIds.has(chapter.id)) throw new Error(`Duplicate chapter id: ${chapter.id}`);
+    chapterIds.add(chapter.id);
+    for (const [sceneIndex, scene] of chapter.scenes.entries()) {
+      const path = `chapters[${chapterIndex}].scenes[${sceneIndex}]`;
+      if (!isRecord2(scene)) throw new Error(`${path} must be an object.`);
+      requireString2(scene.id, `${path}.id`);
+      requireString2(scene.title, `${path}.title`);
+      if (sceneIds.has(scene.id)) throw new Error(`Duplicate scene id: ${scene.id}`);
+      sceneIds.add(scene.id);
+      validateNarrative2(scene, path);
+      if (scene.kind === "deconstructed-diff") {
+        validateDeconstructedScene2(scene, path);
+        continue;
+      }
+      if (!Array.isArray(scene.steps) || scene.steps.length === 0) {
+        throw new Error(`${path} must contain a non-empty steps array.`);
+      }
+      if (scene.kind === "stacked-diff") {
+        validateStackedScene2(scene, path);
+        continue;
+      }
+      if (scene.kind !== void 0 && scene.kind !== "walkthrough") {
+        throw new Error(`${path}.kind must be walkthrough, stacked-diff, or deconstructed-diff.`);
+      }
+      requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "steps"], path);
+      const stepIds = /* @__PURE__ */ new Set();
+      for (const [stepIndex, step] of scene.steps.entries()) {
+        const stepPath = `${path}.steps[${stepIndex}]`;
+        if (!isRecord2(step)) {
+          throw new Error(`${stepPath} must be an object.`);
+        }
+        requireString2(step.id, `${stepPath}.id`);
+        requireString2(step.title, `${stepPath}.title`);
+        requireString2(step.body, `${stepPath}.body`);
+        requireString2(step.focus, `${stepPath}.focus`);
+        requireOnlyKeys(step, ["id", "title", "body", "focus", "connection", "depth"], stepPath);
+        if (step.depth !== void 0 && !["mentioned", "explained", "contextualized"].includes(String(step.depth))) {
+          throw new Error(`${stepPath}.depth must be mentioned, explained, or contextualized.`);
+        }
+        if (stepIds.has(step.id)) throw new Error(`Duplicate step id in scene ${scene.id}: ${step.id}`);
+        stepIds.add(step.id);
+        const focus = step.focus;
+        if (!value.anchors[focus]) {
+          throw new Error(`${stepPath} references unknown anchor ${focus}.`);
+        }
+        optionalString(step.connection, `${stepPath}.connection`);
+        const connection = step.connection;
+        if (typeof connection === "string" && !connectionIds.has(connection)) {
+          throw new Error(`${stepPath} references unknown connection ${connection}.`);
+        }
+      }
+    }
+  }
+  return { ...value, connections: rawConnections };
+}
+function validateDeconstructedScene2(scene, path) {
+  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "base", "target", "stages", "exclusions"], path);
+  optionalString(scene.base, `${path}.base`);
+  optionalString(scene.target, `${path}.target`);
+  if (!Array.isArray(scene.stages) || scene.stages.length === 0 || scene.stages.length > 12) {
+    throw new Error(`${path}.stages must contain between 1 and 12 stages.`);
+  }
+  const stageIds = /* @__PURE__ */ new Set();
+  for (const [stageIndex, stage] of scene.stages.entries()) {
+    const stagePath = `${path}.stages[${stageIndex}]`;
+    if (!isRecord2(stage)) throw new Error(`${stagePath} must be an object.`);
+    requireOnlyKeys(stage, ["id", "title", "narration", "changes"], stagePath);
+    requireString2(stage.id, `${stagePath}.id`);
+    requireString2(stage.title, `${stagePath}.title`);
+    requireString2(stage.narration, `${stagePath}.narration`);
+    if (!Array.isArray(stage.changes) || stage.changes.length === 0) {
+      throw new Error(`${stagePath}.changes must be a non-empty array.`);
+    }
+    if (stageIds.has(stage.id)) throw new Error(`Duplicate deconstructed stage id: ${stage.id}`);
+    stageIds.add(stage.id);
+    stage.changes.forEach((change, changeIndex) => validateDeconstructedSelection(
+      change,
+      `${stagePath}.changes[${changeIndex}]`,
+      false
+    ));
+  }
+  if (scene.exclusions !== void 0) {
+    if (!Array.isArray(scene.exclusions)) throw new Error(`${path}.exclusions must be an array.`);
+    scene.exclusions.forEach((exclusion, exclusionIndex) => validateDeconstructedSelection(
+      exclusion,
+      `${path}.exclusions[${exclusionIndex}]`,
+      true
+    ));
+  }
+}
+function validateDeconstructedSelection(value, path, requiresReason) {
+  if (!isRecord2(value)) throw new Error(`${path} must be an object.`);
+  requireOnlyKeys(value, requiresReason ? ["file", "hunks", "reason"] : ["file", "hunks"], path);
+  requireString2(value.file, `${path}.file`);
+  if (!requiresReason || value.hunks !== void 0) {
+    requireStringArray2(value.hunks, `${path}.hunks`);
+    if (value.hunks.length === 0) throw new Error(`${path}.hunks must not be empty.`);
+  }
+  if (requiresReason) requireString2(value.reason, `${path}.reason`);
+}
+function validateStackedScene2(scene, path) {
+  requireOnlyKeys(scene, ["id", "kind", "title", "summary", "bullets", "tags", "takeaway", "stack", "files", "steps"], path);
+  if (!Array.isArray(scene.stack) || scene.stack.length < 3 || scene.stack.length > 6) {
+    throw new Error(`${path}.stack must contain between 3 and 6 revisions.`);
+  }
+  const stackIds = /* @__PURE__ */ new Set();
+  for (const [index, entry] of scene.stack.entries()) {
+    const entryPath = `${path}.stack[${index}]`;
+    if (!isRecord2(entry)) throw new Error(`${entryPath} must be an object.`);
+    requireOnlyKeys(entry, ["id", "ref", "label"], entryPath);
+    requireString2(entry.id, `${entryPath}.id`);
+    requireString2(entry.ref, `${entryPath}.ref`);
+    optionalString(entry.label, `${entryPath}.label`);
+    if (stackIds.has(entry.id)) throw new Error(`Duplicate stack entry id: ${entry.id}`);
+    stackIds.add(entry.id);
+  }
+  if (scene.files !== void 0) requireStringArray2(scene.files, `${path}.files`);
+  if (!Array.isArray(scene.steps) || scene.steps.length === 0) throw new Error(`${path}.steps must be a non-empty array.`);
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const [index, step] of scene.steps.entries()) {
+    const stepPath = `${path}.steps[${index}]`;
+    if (!isRecord2(step)) throw new Error(`${stepPath} must be an object.`);
+    requireOnlyKeys(step, ["id", "title", "body", "file", "pair", "side", "lines"], stepPath);
+    requireString2(step.id, `${stepPath}.id`);
+    requireString2(step.title, `${stepPath}.title`);
+    requireString2(step.body, `${stepPath}.body`);
+    requireString2(step.file, `${stepPath}.file`);
+    const stepId = step.id;
+    if (stepIds.has(stepId)) throw new Error(`Duplicate step id in scene ${scene.id}: ${stepId}`);
+    stepIds.add(stepId);
+    if (!Array.isArray(step.pair) || step.pair.length !== 2 || step.pair.some((id) => typeof id !== "string")) {
+      throw new Error(`${stepPath}.pair must contain two stack entry ids.`);
+    }
+    const pair = step.pair;
+    const leftIndex = scene.stack.findIndex((entry) => isRecord2(entry) && entry.id === pair[0]);
+    const rightIndex = scene.stack.findIndex((entry) => isRecord2(entry) && entry.id === pair[1]);
+    if (leftIndex < 0 || rightIndex !== leftIndex + 1) throw new Error(`${stepPath}.pair must reference adjacent stack entries in order.`);
+    if (step.side !== void 0 && step.side !== "left" && step.side !== "right") throw new Error(`${stepPath}.side must be left or right.`);
+    if (step.lines !== void 0 && (!Array.isArray(step.lines) || step.lines.length !== 2 || step.lines.some((line) => !Number.isInteger(line) || Number(line) < 1) || Number(step.lines[1]) < Number(step.lines[0]))) {
+      throw new Error(`${stepPath}.lines must contain an ordered positive line range.`);
+    }
+  }
+}
+function validateNarrative2(value, path) {
+  requireString2(value.summary, `${path}.summary`);
+  requireStringArray2(value.bullets, `${path}.bullets`);
+  requireStringArray2(value.tags, `${path}.tags`);
+  requireString2(value.takeaway, `${path}.takeaway`);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString2(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function optionalString(value, path) {
+  if (value !== void 0) {
+    requireString2(value, path);
+  }
+}
+function requireStringArray2(value, path) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${path} must be an array of strings.`);
+  }
+}
+function requireOnlyKeys(value, allowed, path) {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0) {
+    throw new Error(`${path} contains unknown field${unexpected.length === 1 ? "" : "s"}: ${unexpected.join(", ")}`);
+  }
+}
+
+// src/changeInventory.ts
+var import_crypto = require("crypto");
+var import_child_process2 = require("child_process");
+var CHANGE_INVENTORY_VERSION = 2;
+function buildChangeInventory(startPath, options = {}) {
+  const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
+  const files = range.changedPaths.map((changedPath) => buildInventoryFile(
+    range.repoRoot,
+    range.mergeBaseOid,
+    range.headOid,
+    changedPath
+  ));
+  return {
+    version: CHANGE_INVENTORY_VERSION,
+    range: {
+      repoRoot: range.repoRoot,
+      baseRef: range.baseRef,
+      headRef: range.headRef,
+      baseOid: range.mergeBaseOid,
+      headOid: range.headOid
+    },
+    summary: {
+      changedFiles: files.length,
+      textualFiles: files.filter((file) => file.material === "text").length,
+      binaryFiles: files.filter((file) => file.material === "binary").length,
+      changeUnits: files.reduce((total, file) => total + file.units.length, 0),
+      additions: files.reduce((total, file) => total + (file.additions ?? 0), 0),
+      deletions: files.reduce((total, file) => total + (file.deletions ?? 0), 0)
+    },
+    files
+  };
+}
+function buildInventoryFile(repoRoot, baseOid, headOid, changedPath) {
+  const paths = [...new Set([changedPath.previousPath, changedPath.path].filter(Boolean))];
+  const numstat = runGit(repoRoot, ["diff", "--numstat", "--find-renames", baseOid, headOid, "--", ...paths]);
+  const [added = "0", deleted = "0"] = numstat.trim().split(/\s+/, 3);
+  const basePath = changedPath.kind === "added" ? void 0 : changedPath.previousPath || changedPath.path;
+  const headPath = changedPath.kind === "deleted" ? void 0 : changedPath.path;
+  const baseBlob = readGitBlob(repoRoot, baseOid, basePath);
+  const headBlob = readGitBlob(repoRoot, headOid, headPath);
+  if (!baseBlob || !headBlob) {
+    return {
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      material: "unsupported",
+      additions: Number.parseInt(added, 10) || 0,
+      deletions: Number.parseInt(deleted, 10) || 0,
+      units: []
+    };
+  }
+  const binary = added === "-" || deleted === "-" || !isLosslessTextBlob(baseBlob) || !isLosslessTextBlob(headBlob);
+  if (binary) {
+    return {
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      material: "binary",
+      additions: null,
+      deletions: null,
+      units: []
+    };
+  }
+  let patch;
+  try {
+    patch = runGit(repoRoot, [
+      "diff",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--no-color",
+      "--find-renames=20%",
+      "--diff-algorithm=default",
+      "--unified=0",
+      "--inter-hunk-context=0",
+      baseOid,
+      headOid,
+      "--",
+      ...paths
+    ]);
+  } catch {
+    return {
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      material: "unsupported",
+      additions: Number.parseInt(added, 10) || 0,
+      deletions: Number.parseInt(deleted, 10) || 0,
+      units: []
+    };
+  }
+  const units = parsePatchUnits(patch, changedPath);
+  return {
+    path: changedPath.path,
+    previousPath: changedPath.previousPath,
+    changeKind: changedPath.kind,
+    material: "text",
+    additions: Number.parseInt(added, 10) || 0,
+    deletions: Number.parseInt(deleted, 10) || 0,
+    units,
+    baseContent: baseBlob.toString("utf8"),
+    headContent: headBlob.toString("utf8")
+  };
+}
+function parsePatchUnits(patch, changedPath) {
+  const lines = patch.split("\n");
+  const units = [];
+  const seenIds = /* @__PURE__ */ new Map();
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (!match) continue;
+    const body = [];
+    for (index += 1; index < lines.length && !lines[index].startsWith("@@ ") && !lines[index].startsWith("diff --git "); index += 1) {
+      body.push(lines[index]);
+    }
+    index -= 1;
+    const { oldText, newText } = parseHunkText(body);
+    const contextHash = (0, import_crypto.createHash)("sha256").update(JSON.stringify([oldText, newText])).digest("hex").slice(0, 16);
+    const baseId = `hunk-${(0, import_crypto.createHash)("sha256").update(JSON.stringify([
+      changedPath.previousPath || changedPath.path,
+      changedPath.path,
+      oldText,
+      newText
+    ])).digest("hex").slice(0, 12)}`;
+    const occurrence = (seenIds.get(baseId) || 0) + 1;
+    seenIds.set(baseId, occurrence);
+    units.push({
+      id: occurrence === 1 ? baseId : `${baseId}-${occurrence}`,
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      baseStart: Number.parseInt(match[1], 10),
+      baseCount: match[2] === void 0 ? 1 : Number.parseInt(match[2], 10),
+      headStart: Number.parseInt(match[3], 10),
+      headCount: match[4] === void 0 ? 1 : Number.parseInt(match[4], 10),
+      additions: body.filter((line) => line.startsWith("+") && !line.startsWith("+++")).length,
+      deletions: body.filter((line) => line.startsWith("-") && !line.startsWith("---")).length,
+      contextHash,
+      oldText,
+      newText
+    });
+  }
+  return units;
+}
+function materializeChangeUnits(baseContent, units, selectedUnitIds) {
+  const selected = new Set(selectedUnitIds);
+  const knownIds = new Set(units.map((unit) => unit.id));
+  for (const id of selected) {
+    if (!knownIds.has(id)) {
+      throw new Error(`Unknown change unit: ${id}`);
+    }
+  }
+  const offsets = buildLineBoundaryOffsets(baseContent);
+  const ordered = [...units].sort((left, right) => {
+    const leftRange = resolveBaseRange(left, offsets, baseContent.length);
+    const rightRange = resolveBaseRange(right, offsets, baseContent.length);
+    return leftRange.start - rightRange.start || leftRange.end - rightRange.end;
+  });
+  const chunks = [];
+  let cursor = 0;
+  let previousEnd = 0;
+  for (const unit of ordered) {
+    const range = resolveBaseRange(unit, offsets, baseContent.length);
+    if (range.start < previousEnd) {
+      throw new Error(`Overlapping change units cannot be materialized independently: ${unit.id}`);
+    }
+    if (baseContent.slice(range.start, range.end) !== unit.oldText) {
+      throw new Error(`Change unit ${unit.id} no longer matches its base content.`);
+    }
+    if (selected.has(unit.id)) {
+      chunks.push(baseContent.slice(cursor, range.start), unit.newText);
+      cursor = range.end;
+    }
+    previousEnd = Math.max(previousEnd, range.end);
+  }
+  chunks.push(baseContent.slice(cursor));
+  return chunks.join("");
+}
+function parseHunkText(body) {
+  let oldText = "";
+  let newText = "";
+  let previousPrefix = "";
+  for (const line of body) {
+    if (line === "\") {
+      if (previousPrefix === "-" || previousPrefix === " ") oldText = removeFinalNewline(oldText);
+      if (previousPrefix === "+" || previousPrefix === " ") newText = removeFinalNewline(newText);
+      continue;
+    }
+    const prefix = line[0];
+    const content = line.slice(1);
+    if (prefix === "-" || prefix === " ") oldText += `${content}
+`;
+    if (prefix === "+" || prefix === " ") newText += `${content}
+`;
+    previousPrefix = prefix;
+  }
+  return { oldText, newText };
+}
+function removeFinalNewline(value) {
+  return value.endsWith("\n") ? value.slice(0, -1) : value;
+}
+function buildLineBoundaryOffsets(content) {
+  const offsets = [0];
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] === "\n") offsets.push(index + 1);
+  }
+  if (offsets[offsets.length - 1] !== content.length) offsets.push(content.length);
+  return offsets;
+}
+function resolveBaseRange(unit, offsets, contentLength) {
+  const startIndex = unit.baseCount === 0 ? unit.baseStart : unit.baseStart - 1;
+  const endIndex = unit.baseCount === 0 ? startIndex : startIndex + unit.baseCount;
+  const start = offsets[startIndex];
+  const end = offsets[endIndex];
+  if (start === void 0 || end === void 0 || start > contentLength || end > contentLength) {
+    throw new Error(`Change unit ${unit.id} has an invalid base range.`);
+  }
+  return { start, end };
+}
+function isLosslessTextBlob(content) {
+  if (content.includes(0)) return false;
+  const decoded = content.toString("utf8");
+  return Buffer.from(decoded, "utf8").equals(content);
+}
+function readGitBlob(repoRoot, oid, relativePath) {
+  if (!relativePath) return Buffer.alloc(0);
+  try {
+    return (0, import_child_process2.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
+      cwd: repoRoot,
+      encoding: "buffer",
+      maxBuffer: 16 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch {
+    return null;
+  }
+}
+function runGit(repoRoot, args) {
+  return (0, import_child_process2.execFileSync)("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+
+// src/deconstructedChange.ts
+function buildDeconstructedScene(startPath, scene, options = {}) {
+  return compileDeconstructedScene(buildChangeInventory(startPath, {
+    headRef: options.headRef || scene.target,
+    baseRef: options.baseRef || scene.base
+  }), scene);
+}
+function compileDeconstructedScene(inventory, scene) {
+  const ownership = /* @__PURE__ */ new Map();
+  const excludedByFile = /* @__PURE__ */ new Map();
+  const cumulativeByFile = /* @__PURE__ */ new Map();
+  const wholeFileExclusions = /* @__PURE__ */ new Map();
+  const excludedFiles = [];
+  for (const exclusion of scene.exclusions || []) {
+    const file = requireInventoryFile(inventory, exclusion.file, "Exclusion");
+    if (!exclusion.hunks) {
+      if (wholeFileExclusions.has(file)) {
+        throw new Error(`File is excluded more than once: ${exclusion.file}`);
+      }
+      wholeFileExclusions.set(file, exclusion.reason);
+      excludedFiles.push({ path: file.path, reason: exclusion.reason });
+    }
+    const ids = exclusion.hunks || file.units.map((unit) => unit.id);
+    if (file.material !== "text" && exclusion.hunks) {
+      throw new Error(`Unsupported file ${exclusion.file} must be excluded as a whole file.`);
+    }
+    claimHunks(file, ids, `exclusion for ${exclusion.file}`, ownership);
+    const excluded = excludedByFile.get(file) || /* @__PURE__ */ new Set();
+    ids.forEach((id) => excluded.add(id));
+    excludedByFile.set(file, excluded);
+  }
+  const stageClaims = scene.stages.map((stage) => {
+    const claims = [];
+    for (const change of stage.changes) {
+      const file = requireInventoryFile(inventory, change.file, `Stage ${stage.id}`);
+      if (file.material !== "text") {
+        throw new Error(`Stage ${stage.id} cannot assign unsupported file: ${change.file}`);
+      }
+      if (file.changeKind === "renamed") {
+        throw new Error(`Stage ${stage.id} cannot assign renamed file ${change.file} until path-transition units are supported.`);
+      }
+      claimHunks(file, change.hunks, `stage ${stage.id}`, ownership);
+      claims.push({ file, ids: [...change.hunks] });
+    }
+    return { stage, claims };
+  });
+  for (const file of inventory.files) {
+    const wholeFileExcluded = wholeFileExclusions.has(file);
+    if (file.material !== "text" || file.changeKind === "renamed" || file.units.length === 0) {
+      if (!wholeFileExcluded) {
+        const reason = file.changeKind === "renamed" ? "rename path transitions are not supported yet" : file.material !== "text" ? `${file.material} content cannot be materialized` : "the change has no textual hunks";
+        throw new Error(`Deconstructed scene ${scene.id} must exclude ${file.path} as a whole file because ${reason}.`);
+      }
+      continue;
+    }
+    for (const unit of file.units) {
+      if (!ownership.has(unitKey(file, unit.id))) {
+        throw new Error(`Unassigned change unit in ${file.path}: ${unit.id}`);
+      }
+    }
+  }
+  for (const file of inventory.files) {
+    cumulativeByFile.set(file, new Set(excludedByFile.get(file) || []));
+  }
+  const materializableFiles = inventory.files.filter((file) => file.material === "text" && file.changeKind !== "renamed" && file.baseContent !== void 0 && file.headContent !== void 0);
+  const baselineFiles = materializableFiles.map((file) => buildFileState(
+    file,
+    cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
+    wholeFileExclusions.has(file)
+  ));
+  const stages = [];
+  for (const { stage, claims } of stageClaims) {
+    const introducedHunks = [];
+    const introducedFiles = [];
+    for (const claim of claims) {
+      const cumulative = cumulativeByFile.get(claim.file) || /* @__PURE__ */ new Set();
+      claim.ids.forEach((id) => {
+        cumulative.add(id);
+        introducedHunks.push(id);
+      });
+      cumulativeByFile.set(claim.file, cumulative);
+      if (!introducedFiles.includes(claim.file.path)) introducedFiles.push(claim.file.path);
+    }
+    stages.push({
+      id: stage.id,
+      title: stage.title,
+      narration: stage.narration,
+      introducedHunks,
+      introducedFiles,
+      cumulativeHunks: [...cumulativeByFile.values()].flatMap((ids) => [...ids]),
+      files: materializableFiles.map((file) => buildFileState(
+        file,
+        cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
+        wholeFileExclusions.has(file)
+      ))
+    });
+  }
+  for (const file of materializableFiles) {
+    const finalState = buildFileState(
+      file,
+      cumulativeByFile.get(file) || /* @__PURE__ */ new Set(),
+      wholeFileExclusions.has(file)
+    );
+    const expectedExists = file.changeKind !== "deleted";
+    if (finalState.exists !== expectedExists || finalState.content !== file.headContent) {
+      throw new Error(`Final deconstructed state does not match the target for ${file.path}.`);
+    }
+  }
+  return {
+    id: scene.id,
+    title: scene.title,
+    baseOid: inventory.range.baseOid,
+    targetOid: inventory.range.headOid,
+    baselineFiles,
+    excludedHunks: [...excludedByFile.values()].flatMap((ids) => [...ids]),
+    excludedFiles,
+    stages
+  };
+}
+function requireInventoryFile(inventory, path, owner) {
+  const matches = inventory.files.filter((file) => file.path === path || file.previousPath === path);
+  if (matches.length === 0) throw new Error(`${owner} references a file outside the change inventory: ${path}`);
+  if (matches.length > 1) throw new Error(`${owner} references an ambiguous changed path: ${path}`);
+  return matches[0];
+}
+function claimHunks(file, ids, owner, ownership) {
+  const known = new Set(file.units.map((unit) => unit.id));
+  for (const id of ids) {
+    if (!known.has(id)) throw new Error(`${owner} references an unknown hunk in ${file.path}: ${id}`);
+    const key = unitKey(file, id);
+    const previousOwner = ownership.get(key);
+    if (previousOwner) throw new Error(`Change unit ${id} in ${file.path} is assigned to both ${previousOwner} and ${owner}.`);
+    ownership.set(key, owner);
+  }
+}
+function unitKey(file, id) {
+  return `${file.previousPath || ""}\0${file.path}\0${id}`;
+}
+function buildFileState(file, selected, wholeFileExcluded) {
+  if (file.baseContent === void 0) throw new Error(`Missing base content for ${file.path}.`);
+  const content = materializeChangeUnits(file.baseContent, file.units, selected);
+  let exists = true;
+  if (file.changeKind === "added") exists = wholeFileExcluded || selected.size > 0;
+  if (file.changeKind === "deleted") exists = !(wholeFileExcluded || selected.size === file.units.length);
+  return {
+    path: file.path,
+    previousPath: file.previousPath,
+    changeKind: file.changeKind,
+    exists,
+    content: exists ? content : "",
+    appliedHunks: [...selected]
+  };
+}
+
+// src/changeTourContext.ts
+var import_child_process3 = require("child_process");
+var CHANGE_TOUR_CONTEXT_VERSION = 1;
+var DEFAULT_MAX_PATCH_BYTES = 128 * 1024;
+var DEFAULT_MAX_TOTAL_PATCH_BYTES = 2 * 1024 * 1024;
+var MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
+var MAX_SYMBOL_SOURCE_BYTES = 1024 * 1024;
+function buildChangeTourContext(startPath, options = {}) {
+  const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
+  const maxPatchBytes = options.maxPatchBytes ?? DEFAULT_MAX_PATCH_BYTES;
+  const maxTotalPatchBytes = options.maxTotalPatchBytes ?? DEFAULT_MAX_TOTAL_PATCH_BYTES;
+  requirePositiveInteger2(maxPatchBytes, "maxPatchBytes");
+  requirePositiveInteger2(maxTotalPatchBytes, "maxTotalPatchBytes");
+  const files = range.changedPaths.map((changedPath) => buildContextFile(
+    range.repoRoot,
+    range.mergeBaseOid,
+    range.headOid,
+    changedPath,
+    maxPatchBytes
+  ));
+  applyTotalPatchBudget(files, maxTotalPatchBytes);
+  const filesByRole = {
+    production: 0,
+    test: 0,
+    documentation: 0,
+    dependency: 0,
+    generated: 0
+  };
+  for (const file of files) filesByRole[file.role] += 1;
+  return {
+    version: CHANGE_TOUR_CONTEXT_VERSION,
+    generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
+    range: {
+      baseRef: range.baseRef,
+      headRef: range.headRef,
+      mergeBaseOid: range.mergeBaseOid,
+      headOid: range.headOid,
+      dirtyWorkingTreeExcluded: range.dirty
+    },
+    limits: { maxPatchBytes, maxTotalPatchBytes },
+    summary: {
+      changedFiles: files.length,
+      commitCount: range.commits.length,
+      additions: files.reduce((total, file) => total + (file.additions ?? 0), 0),
+      deletions: files.reduce((total, file) => total + (file.deletions ?? 0), 0),
+      binaryFiles: files.filter((file) => file.binary).length,
+      omittedPatches: files.filter((file) => file.patchOmittedReason).length,
+      includedPatchBytes: files.reduce((total, file) => total + (file.patch ? file.patchBytes : 0), 0),
+      filesByRole
+    },
+    commits: range.commits,
+    files
+  };
+}
+function applyTotalPatchBudget(files, maxBytes) {
+  let includedBytes = 0;
+  for (const file of files) {
+    if (!file.patch) continue;
+    if (includedBytes + file.patchBytes <= maxBytes) {
+      includedBytes += file.patchBytes;
+      continue;
+    }
+    file.patch = void 0;
+    file.patchOmittedReason = "total-budget";
+  }
+}
+function buildContextFile(repoRoot, baseOid, headOid, changedPath, maxPatchBytes) {
+  const paths = [changedPath.previousPath, changedPath.path].filter((candidate) => Boolean(candidate));
+  const stats = readLineStats(repoRoot, baseOid, headOid, paths);
+  const patchResult = readPatch(repoRoot, baseOid, headOid, paths, stats.binary, maxPatchBytes);
+  const changedRanges = patchResult.content ? parseChangedRanges(patchResult.content) : [];
+  const pair = resolveReviewPathPair([changedPath], changedPath.path);
+  const headContent = (pair == null ? void 0 : pair.rightPath) && !stats.binary ? readGitText(repoRoot, headOid, pair.rightPath, MAX_SYMBOL_SOURCE_BYTES) : void 0;
+  return {
+    path: changedPath.path,
+    previousPath: changedPath.previousPath,
+    changeKind: changedPath.kind,
+    role: classifyFileRole(changedPath.path),
+    additions: stats.additions,
+    deletions: stats.deletions,
+    binary: stats.binary,
+    patch: patchResult.included ? patchResult.content : void 0,
+    patchBytes: patchResult.bytes,
+    patchOmittedReason: patchResult.reason,
+    changedRanges,
+    symbolHints: headContent ? findSymbolHints(headContent, changedRanges) : []
+  };
+}
+function readLineStats(repoRoot, baseOid, headOid, paths) {
+  const output = runGit2(repoRoot, ["diff", "--numstat", "--find-renames", baseOid, headOid, "--", ...paths]);
+  const [additions = "0", deletions = "0"] = output.trim().split(/\s+/, 3);
+  const binary = additions === "-" || deletions === "-";
+  return {
+    additions: binary ? null : Number.parseInt(additions, 10) || 0,
+    deletions: binary ? null : Number.parseInt(deletions, 10) || 0,
+    binary
+  };
+}
+function readPatch(repoRoot, baseOid, headOid, paths, binary, maxPatchBytes) {
+  if (binary) return { included: false, content: "", bytes: 0, reason: "binary" };
+  try {
+    const buffer = (0, import_child_process3.execFileSync)("git", [
+      "diff",
+      "--no-ext-diff",
+      "--no-color",
+      "--find-renames",
+      "--unified=3",
+      baseOid,
+      headOid,
+      "--",
+      ...paths
+    ], {
+      cwd: repoRoot,
+      encoding: "buffer",
+      maxBuffer: MAX_CAPTURE_BYTES,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const content = buffer.toString("utf8");
+    if (buffer.length > maxPatchBytes) {
+      return { included: false, content, bytes: buffer.length, reason: "too-large" };
+    }
+    return { included: true, content, bytes: buffer.length };
+  } catch {
+    return { included: false, content: "", bytes: 0, reason: "unavailable" };
+  }
+}
+function parseChangedRanges(patch) {
+  const ranges = [];
+  const pattern = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm;
+  let match;
+  while (match = pattern.exec(patch)) {
+    ranges.push({
+      baseStart: Number.parseInt(match[1], 10),
+      baseCount: match[2] === void 0 ? 1 : Number.parseInt(match[2], 10),
+      headStart: Number.parseInt(match[3], 10),
+      headCount: match[4] === void 0 ? 1 : Number.parseInt(match[4], 10)
+    });
+  }
+  return ranges;
+}
+function findSymbolHints(content, ranges) {
+  const declarations = [];
+  content.split("\n").forEach((line, index) => {
+    const python = line.match(/^\s*(?:async\s+)?(class|def)\s+([A-Za-z_]\w*)/);
+    const typed = line.match(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(function|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/);
+    const match = python || typed;
+    if (match) declarations.push({ kind: match[1], name: match[2], line: index + 1 });
+  });
+  const selected = /* @__PURE__ */ new Map();
+  for (const range of ranges) {
+    const start = range.headStart;
+    const end = start + Math.max(0, range.headCount - 1);
+    const enclosing = [...declarations].reverse().find((candidate) => candidate.line <= start);
+    if (enclosing) selected.set(`${enclosing.kind}:${enclosing.name}:${enclosing.line}`, enclosing);
+    for (const symbol of declarations.filter((candidate) => candidate.line >= start && candidate.line <= end)) {
+      selected.set(`${symbol.kind}:${symbol.name}:${symbol.line}`, symbol);
+    }
+  }
+  return [...selected.values()].slice(0, 25);
+}
+function readGitText(repoRoot, oid, relativePath, maxBytes) {
+  try {
+    const content = (0, import_child_process3.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
+      cwd: repoRoot,
+      encoding: "buffer",
+      maxBuffer: maxBytes + 1,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (content.length > maxBytes || content.includes(0)) return void 0;
+    return content.toString("utf8");
+  } catch {
+    return void 0;
+  }
+}
+function classifyFileRole(filePath) {
+  const lower = filePath.toLowerCase();
+  const fileName = lower.split("/").pop() || lower;
+  if (/(^|\/)(tests?|__tests__)(\/|$)/.test(lower) || /(^|\/)test_[^/]+$/.test(lower) || /\.(test|spec)\.[^/]+$/.test(lower)) return "test";
+  if (lower.startsWith("docs/") || fileName === "readme.md" || /\.(md|mdx|rst)$/.test(lower)) return "documentation";
+  if (/(^|\/)(package-lock\.json|.*\.lock|pyproject\.toml|package\.json|go\.mod|cargo\.toml)$/.test(lower)) return "dependency";
+  if (/(^|\/)(dist|build|generated|vendor)(\/|$)/.test(lower) || /\.(min\.js|map)$/.test(lower)) return "generated";
+  return "production";
+}
+function runGit2(repoRoot, args) {
+  return (0, import_child_process3.execFileSync)("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: MAX_CAPTURE_BYTES,
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trimEnd();
+}
+function requirePositiveInteger2(value, name) {
+  if (!Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer.`);
+}
+
+// src/changeTour.ts
+var DEFAULT_MAX_TOUR_FILE_BYTES = 2 * 1024 * 1024;
+var DEFAULT_MAX_TOUR_LINE_BYTES = 64 * 1024;
+var DEFAULT_MAX_STACK_CONTENT_BYTES = 8 * 1024 * 1024;
+var CHAPTERS = {
+  context: { id: "context", title: "Context and architecture", priority: 0 },
+  contracts: { id: "contracts", title: "Data model and contracts", priority: 1 },
+  behavior: { id: "behavior", title: "Behavior and integration", priority: 2 },
+  proof: { id: "proof", title: "Proof and coverage", priority: 3 },
+  packaging: { id: "packaging", title: "Packaging and dependencies", priority: 4 }
+};
+function buildChangeTourManifest(startPath, options = {}) {
+  var _a, _b, _c, _d;
+  const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
+  const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_TOUR_FILE_BYTES;
+  const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_TOUR_LINE_BYTES;
+  const omittedFiles = [];
+  const files = [];
+  const sceneRecords = [];
+  let totalAdditions = 0;
+  let totalDeletions = 0;
+  for (const changedPath of range.changedPaths) {
+    const { additions, deletions } = readGitLineStats(
+      range.repoRoot,
+      range.mergeBaseOid,
+      range.headOid,
+      changedPath.path,
+      changedPath.previousPath
+    );
+    totalAdditions += additions;
+    totalDeletions += deletions;
+    const pair = resolveReviewPathPair(range.changedPaths, changedPath.path);
+    if (!pair) {
+      omittedFiles.push(changedPath.path);
+      files.push(buildOmittedFile(changedPath, additions, deletions, "Git endpoints could not be resolved."));
+      continue;
+    }
+    const left = readGitText2(range.repoRoot, range.mergeBaseOid, pair.leftPath, maxFileBytes, maxLineBytes);
+    const right = readGitText2(range.repoRoot, range.headOid, pair.rightPath, maxFileBytes, maxLineBytes);
+    if (left.kind !== "text" || right.kind !== "text") {
+      omittedFiles.push(changedPath.path);
+      files.push(buildOmittedFile(changedPath, additions, deletions, "Binary, oversized, or contains an oversized line."));
+      continue;
+    }
+    const chapter = chapterForPath(changedPath.path);
+    const scene = {
+      id: `file-${files.length + 1}`,
+      kind: "text-diff",
+      title: changedPath.path.split("/").pop() || changedPath.path,
+      summary: `${formatChangeKind(changedPath.kind)} ${changedPath.path}.`,
+      bullets: [],
+      tags: [changedPath.kind, `+${additions}`, `\u2212${deletions}`],
+      takeaway: buildSceneNote(changedPath.kind, additions, deletions, changedPath.previousPath),
+      path: changedPath.path,
+      previousPath: changedPath.previousPath,
+      changeKind: changedPath.kind,
+      leftLabel: pair.leftPath ? `${pair.leftPath} @ ${range.mergeBaseOid.slice(0, 7)}` : `${changedPath.path} (absent)`,
+      rightLabel: pair.rightPath ? `${pair.rightPath} @ ${range.headOid.slice(0, 7)}` : `${changedPath.path} (absent)`,
+      leftContent: left.content,
+      rightContent: right.content,
+      additions,
+      deletions
+    };
+    files.push(scene);
+    sceneRecords.push({
+      chapter,
+      scene
+    });
+  }
+  files.sort((left, right) => left.path.localeCompare(right.path));
+  sceneRecords.sort((left, right) => left.chapter.priority - right.chapter.priority || left.scene.path.localeCompare(right.scene.path));
+  const defaultScenes = sceneRecords.map(({ scene }, index) => ({ ...scene, id: `file-${index + 1}` }));
+  if (options.story && options.source) {
+    throw new Error("A change tour can use either a legacy story or a source file, not both.");
+  }
+  const authored = options.source ? applySource(parseChangeTourSource(options.source), defaultScenes, range.repoRoot) : options.story ? applyStory(options.story, defaultScenes) : {
+    scenes: defaultScenes,
+    chapters: buildChapters(sceneRecords, new Map(defaultScenes.map((scene) => [scene.path, scene.id])))
+  };
+  const scenes = authored.scenes;
+  const chapters = authored.chapters;
+  const manifest = {
+    version: CHANGE_TOUR_MANIFEST_VERSION,
+    title: ((_a = options.source) == null ? void 0 : _a.title) || ((_b = options.story) == null ? void 0 : _b.title) || options.title || `${range.headRef} against ${range.baseRef}`,
+    sourceUrl: ((_c = options.source) == null ? void 0 : _c.sourceUrl) || ((_d = options.story) == null ? void 0 : _d.sourceUrl) || options.sourceUrl,
+    generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
+    range: {
+      baseRef: range.baseRef,
+      headRef: range.headRef,
+      mergeBaseOid: range.mergeBaseOid,
+      headOid: range.headOid
+    },
+    summary: {
+      changedFiles: range.changedPaths.length,
+      includedScenes: scenes.length,
+      additions: totalAdditions,
+      deletions: totalDeletions,
+      commitCount: range.commits.length,
+      omittedFiles
+    },
+    commits: range.commits,
+    files,
+    chapters,
+    scenes
+  };
+  return parseChangeTourManifest(manifest);
+}
+function applySource(source, defaultScenes, repoRoot) {
+  var _a, _b;
+  const available = new Map(defaultScenes.map((scene) => [scene.path, scene]));
+  const resolvedAnchors = /* @__PURE__ */ new Map();
+  for (const [id, anchor] of Object.entries(source.anchors)) {
+    const file = available.get(anchor.file);
+    if (!file) {
+      throw new Error(`Anchor ${id} references a file outside the text change range: ${anchor.file}`);
+    }
+    const content = anchor.revision === "base" ? file.leftContent : file.rightContent;
+    resolvedAnchors.set(id, resolveAnchor(id, anchor.file, anchor.revision, content, anchor.contains, anchor.occurrence));
+  }
+  const connections = new Map(source.connections.map((connection) => [connection.id, {
+    id: connection.id,
+    label: connection.label,
+    from: requireResolvedAnchor(resolvedAnchors, connection.from),
+    to: requireResolvedAnchor(resolvedAnchors, connection.to)
+  }]));
+  const scenes = [];
+  const chapters = [];
+  for (const chapter of source.chapters) {
+    const sceneIds = [];
+    for (const authoredScene of chapter.scenes) {
+      if (authoredScene.kind === "deconstructed-diff") {
+        const deconstructedScene = buildDeconstructedManifestScene(
+          repoRoot,
+          authoredScene,
+          authoredScene.base || ((_a = source.range) == null ? void 0 : _a.base),
+          authoredScene.target || ((_b = source.range) == null ? void 0 : _b.head)
+        );
+        scenes.push(deconstructedScene);
+        sceneIds.push(deconstructedScene.id);
+        continue;
+      }
+      if (authoredScene.kind === "stacked-diff") {
+        const stackedScene = buildStackedScene(repoRoot, authoredScene);
+        scenes.push(stackedScene);
+        sceneIds.push(stackedScene.id);
+        continue;
+      }
+      const scene = {
+        id: authoredScene.id,
+        kind: "walkthrough",
+        title: authoredScene.title,
+        summary: authoredScene.summary,
+        bullets: authoredScene.bullets,
+        tags: authoredScene.tags,
+        takeaway: authoredScene.takeaway,
+        steps: authoredScene.steps.map((step) => {
+          const focus = requireResolvedAnchor(resolvedAnchors, step.focus);
+          const diff = available.get(focus.path);
+          if (!diff) throw new Error(`Step ${step.id} has no text diff for ${focus.path}.`);
+          return {
+            id: step.id,
+            title: step.title,
+            body: step.body,
+            depth: step.depth,
+            focus,
+            connection: step.connection ? connections.get(step.connection) : void 0,
+            diff: { ...diff, id: `${authoredScene.id}-${step.id}` }
+          };
+        })
+      };
+      scenes.push(scene);
+      sceneIds.push(scene.id);
+    }
+    chapters.push({ id: chapter.id, title: chapter.title, sceneIds });
+  }
+  return { scenes, chapters };
+}
+function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef) {
+  const compiled = buildDeconstructedScene(repoRoot, source, { baseRef, headRef: targetRef });
+  const panels = [{
+    id: "explanation-baseline",
+    label: "Explanation baseline",
+    role: "baseline"
+  }, ...compiled.stages.map((stage, index) => ({
+    id: `explanation-stage-${stage.id}`,
+    label: `Stage ${index + 1}: ${stage.title}`,
+    role: "stage",
+    stageId: stage.id
+  }))];
+  const includedPaths = [...new Set(compiled.stages.flatMap((stage) => stage.introducedFiles))];
+  let totalContentBytes = 0;
+  const files = includedPaths.map((filePath) => {
+    const states = [
+      compiled.baselineFiles.find((file) => file.path === filePath),
+      ...compiled.stages.map((stage) => stage.files.find((file) => file.path === filePath))
+    ];
+    if (states.some((state) => !state)) {
+      throw new Error(`Deconstructed scene ${source.id} is missing virtual state for ${filePath}.`);
+    }
+    return {
+      path: filePath,
+      panels: states.map((state, index) => {
+        if (!state) throw new Error(`Missing virtual state for ${filePath}.`);
+        const content = Buffer.from(state.content, "utf8");
+        if (content.length > DEFAULT_MAX_TOUR_FILE_BYTES || hasLineLongerThan(content, DEFAULT_MAX_TOUR_LINE_BYTES)) {
+          throw new Error(`Deconstructed tour file is too large to present: ${filePath}`);
+        }
+        totalContentBytes += content.length;
+        if (totalContentBytes > DEFAULT_MAX_STACK_CONTENT_BYTES) {
+          throw new Error(`Deconstructed tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
+        }
+        return {
+          id: panels[index].id,
+          label: `${panels[index].label} / ${filePath}${state.exists ? "" : " (absent)"}`,
+          path: state.exists ? filePath : void 0,
+          content: state.content,
+          exists: state.exists
+        };
+      })
+    };
+  });
+  if (files.length === 0) throw new Error(`Deconstructed scene ${source.id} has no staged files.`);
+  return {
+    id: source.id,
+    kind: "deconstructed-diff",
+    title: source.title,
+    summary: source.summary,
+    bullets: source.bullets,
+    tags: source.tags,
+    takeaway: source.takeaway,
+    stageLabel: "Explanation stages",
+    realRange: {
+      baseRef: baseRef || compiled.baseOid,
+      targetRef: targetRef || compiled.targetOid,
+      baseOid: compiled.baseOid,
+      targetOid: compiled.targetOid
+    },
+    panels,
+    files,
+    steps: compiled.stages.map((stage, index) => ({
+      id: stage.id,
+      title: stage.title,
+      body: stage.narration,
+      file: stage.introducedFiles[0],
+      pairIndex: index,
+      side: "right",
+      introducedHunks: stage.introducedHunks
+    }))
+  };
+}
+function buildStackedScene(repoRoot, source) {
+  var _a;
+  const stack = source.stack.map((entry) => ({
+    id: entry.id,
+    ref: entry.ref,
+    oid: runGitText(repoRoot, ["rev-parse", "--verify", `${entry.ref}^{commit}`]),
+    label: entry.label || entry.ref
+  }));
+  const adjacentChanges = stack.slice(0, -1).map((entry, index) => parseNameStatusZ((0, import_child_process4.execFileSync)("git", [
+    "diff",
+    "--name-status",
+    "-z",
+    "--find-renames=20%",
+    entry.oid,
+    stack[index + 1].oid
+  ], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  })));
+  const renamedPreviousPaths = new Set(adjacentChanges.flatMap((changes) => changes.map((change) => change.previousPath).filter((candidate) => Boolean(candidate))));
+  const changedFiles = [...new Set(adjacentChanges.flatMap((changes) => changes.map((change) => change.path)))].filter((filePath) => !renamedPreviousPaths.has(filePath)).sort();
+  const filePaths = ((_a = source.files) == null ? void 0 : _a.length) ? [...new Set(source.files)] : changedFiles;
+  for (const step of source.steps) {
+    if (!filePaths.includes(step.file)) throw new Error(`Stacked step ${step.id} references undeclared file ${step.file}.`);
+  }
+  if (filePaths.length === 0) throw new Error(`Stacked scene ${source.id} has no changed files.`);
+  let totalContentBytes = 0;
+  const files = filePaths.map((filePath) => {
+    const aliases = /* @__PURE__ */ new Set([filePath]);
+    for (const changes of adjacentChanges) {
+      for (const change of changes) {
+        if (aliases.has(change.path) || change.previousPath && aliases.has(change.previousPath)) {
+          aliases.add(change.path);
+          if (change.previousPath) aliases.add(change.previousPath);
+        }
+      }
+    }
+    const panels = stack.map((entry) => {
+      const resolvedPath = [...aliases].find((candidate) => gitBlobExists(repoRoot, entry.oid, candidate));
+      if (!resolvedPath) {
+        return { id: entry.id, label: `${entry.label} / ${filePath} (missing)`, content: "", exists: false };
+      }
+      const content = readGitText2(repoRoot, entry.oid, resolvedPath, DEFAULT_MAX_TOUR_FILE_BYTES, DEFAULT_MAX_TOUR_LINE_BYTES);
+      if (content.kind !== "text") throw new Error(`Stacked tour file is binary or too large: ${resolvedPath}`);
+      totalContentBytes += Buffer.byteLength(content.content);
+      if (totalContentBytes > DEFAULT_MAX_STACK_CONTENT_BYTES) {
+        throw new Error(`Stacked tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
+      }
+      return {
+        id: entry.id,
+        label: `${entry.label} / ${resolvedPath}`,
+        path: resolvedPath,
+        content: content.content,
+        exists: true
+      };
+    });
+    return { path: filePath, panels };
+  });
+  const stackIds = stack.map((entry) => entry.id);
+  return {
+    id: source.id,
+    kind: "stacked-diff",
+    title: source.title,
+    summary: source.summary,
+    bullets: source.bullets,
+    tags: source.tags,
+    takeaway: source.takeaway,
+    stack,
+    files,
+    steps: source.steps.map((step) => {
+      var _a2, _b;
+      return {
+        id: step.id,
+        title: step.title,
+        body: step.body,
+        file: step.file,
+        pairIndex: stackIds.indexOf(step.pair[0]),
+        side: step.side || "right",
+        startLine: (_a2 = step.lines) == null ? void 0 : _a2[0],
+        endLine: (_b = step.lines) == null ? void 0 : _b[1]
+      };
+    })
+  };
+}
+function gitBlobExists(repoRoot, oid, relativePath) {
+  try {
+    (0, import_child_process4.execFileSync)("git", ["cat-file", "-e", `${oid}:${relativePath}`], {
+      cwd: repoRoot,
+      stdio: ["ignore", "ignore", "ignore"]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function runGitText(repoRoot, args) {
+  return (0, import_child_process4.execFileSync)("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function resolveAnchor(id, file, revision, content, needle, occurrence) {
+  const offsets = [];
+  let offset = content.indexOf(needle);
+  while (offset >= 0) {
+    offsets.push(offset);
+    offset = content.indexOf(needle, offset + Math.max(needle.length, 1));
+  }
+  if (offsets.length === 0) throw new Error(`Anchor ${id} did not match ${file} at ${revision}.`);
+  if (occurrence === void 0 && offsets.length > 1) {
+    throw new Error(`Anchor ${id} matched ${offsets.length} places in ${file}; add occurrence to disambiguate it.`);
+  }
+  const selected = offsets[(occurrence || 1) - 1];
+  if (selected === void 0) throw new Error(`Anchor ${id} occurrence ${occurrence} does not exist in ${file}.`);
+  const startLine = content.slice(0, selected).split("\n").length;
+  const endLine = startLine + needle.split("\n").length - 1;
+  return { id, path: file, revision, startLine, endLine, excerpt: needle };
+}
+function requireResolvedAnchor(anchors, id) {
+  const anchor = anchors.get(id);
+  if (!anchor) throw new Error(`Unknown resolved anchor: ${id}`);
+  return anchor;
+}
+function applyStory(story, defaultScenes) {
+  const available = new Map(defaultScenes.map((scene) => [scene.path, scene]));
+  const scenes = [];
+  const chapterRecords = [];
+  const chaptersById = /* @__PURE__ */ new Map();
+  const addScene = (chapterId, chapterTitle, scene) => {
+    let chapter = chaptersById.get(chapterId);
+    if (!chapter) {
+      chapter = { id: chapterId, title: chapterTitle, sceneIds: [] };
+      chaptersById.set(chapterId, chapter);
+      chapterRecords.push(chapter);
+    }
+    scenes.push(scene);
+    chapter.sceneIds.push(scene.id);
+  };
+  for (const storyScene of story.scenes) {
+    const id = `scene-${scenes.length + 1}`;
+    if (storyScene.kind === "discussion") {
+      addScene(storyScene.chapterId, storyScene.chapterTitle, {
+        id,
+        kind: "discussion",
+        title: storyScene.title,
+        summary: storyScene.summary,
+        bullets: storyScene.bullets,
+        tags: storyScene.tags,
+        takeaway: storyScene.takeaway
+      });
+      continue;
+    }
+    const baseScene = available.get(storyScene.path);
+    if (!baseScene) {
+      throw new Error(`Story references a file outside the change range: ${storyScene.path}`);
+    }
+    available.delete(storyScene.path);
+    addScene(storyScene.chapterId, storyScene.chapterTitle, {
+      ...baseScene,
+      id,
+      title: storyScene.title || baseScene.title,
+      summary: storyScene.summary,
+      bullets: storyScene.bullets,
+      tags: storyScene.tags,
+      takeaway: storyScene.takeaway,
+      focusChangeIndex: storyScene.focusChangeIndex
+    });
+  }
+  return { scenes, chapters: chapterRecords };
+}
+function buildChapters(records, sceneIdByPath) {
+  const definitions = [...new Map(records.map(({ chapter }) => [chapter.id, chapter])).values()].sort((left, right) => left.priority - right.priority);
+  return definitions.map((definition) => ({
+    id: definition.id,
+    title: definition.title,
+    sceneIds: records.filter(({ chapter }) => chapter.id === definition.id).map(({ scene }) => sceneIdByPath.get(scene.path)).filter((sceneId) => Boolean(sceneId))
+  }));
+}
+function chapterForPath(filePath) {
+  const lower = filePath.toLowerCase();
+  const fileName = lower.split("/").pop() || lower;
+  if (lower.startsWith("docs/") || fileName === "readme.md" || fileName.includes("architecture")) {
+    return CHAPTERS.context;
+  }
+  if (/(^|\/)(tests?|__tests__)(\/|$)/.test(lower) || /(^|\/)test_[^/]+$/.test(lower)) {
+    return CHAPTERS.proof;
+  }
+  if (/(^|\/)(models?|schema|types?|contracts?)\.[^/]+$/.test(lower)) {
+    return CHAPTERS.contracts;
+  }
+  if (/(^|\/)(package-lock\.json|.*\.lock|pyproject\.toml|package\.json)$/.test(lower)) {
+    return CHAPTERS.packaging;
+  }
+  return CHAPTERS.behavior;
+}
+function buildSceneNote(kind, additions, deletions, previousPath) {
+  const label = formatChangeKind(kind);
+  const rename = previousPath ? ` from ${previousPath}` : "";
+  return `${label}${rename} \xB7 +${additions} \u2212${deletions}`;
+}
+function buildOmittedFile(changedPath, additions, deletions, reason) {
+  return {
+    id: `file-${changedPath.path}`,
+    kind: "omitted",
+    title: changedPath.path.split("/").pop() || changedPath.path,
+    path: changedPath.path,
+    previousPath: changedPath.previousPath,
+    changeKind: changedPath.kind,
+    additions,
+    deletions,
+    reason
+  };
+}
+function formatChangeKind(kind) {
+  return kind.replace("-", " ").replace(/^./, (letter) => letter.toUpperCase());
+}
+function readGitText2(repoRoot, oid, relativePath, maxBytes, maxLineBytes) {
+  if (!relativePath) {
+    return { kind: "text", content: "" };
+  }
+  const content = (0, import_child_process4.execFileSync)("git", ["show", `${oid}:${relativePath}`], {
+    cwd: repoRoot,
+    encoding: "buffer",
+    maxBuffer: Math.max(maxBytes + 1, DEFAULT_MAX_TOUR_FILE_BYTES + 1),
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (content.length > maxBytes || content.includes(0) || hasLineLongerThan(content, maxLineBytes)) {
+    return { kind: "binary-or-large", content: "" };
+  }
+  return { kind: "text", content: content.toString("utf8") };
+}
+function hasLineLongerThan(content, maxLineBytes) {
+  let lineStart = 0;
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] !== 10) continue;
+    if (index - lineStart > maxLineBytes) return true;
+    lineStart = index + 1;
+  }
+  return content.length - lineStart > maxLineBytes;
+}
+function readGitLineStats(repoRoot, baseOid, headOid, filePath, previousPath) {
+  const output = (0, import_child_process4.execFileSync)("git", [
+    "diff",
+    "--numstat",
+    "--find-renames",
+    baseOid,
+    headOid,
+    "--",
+    ...[previousPath, filePath].filter((candidate) => Boolean(candidate))
+  ], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const [additionsText = "0", deletionsText = "0"] = output.trim().split(/\s+/, 3);
+  return {
+    additions: Number.parseInt(additionsText, 10) || 0,
+    deletions: Number.parseInt(deletionsText, 10) || 0
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildChangeInventory,
+  buildChangeTourContext,
+  buildChangeTourManifest,
+  buildDeconstructedScene,
+  compileDeconstructedScene,
+  materializeChangeUnits,
+  parseChangeTourManifest,
+  parseChangeTourSource,
+  parseChangeTourStory
+});
+//# sourceMappingURL=changeTour.js.map