@wkronmiller/lisa 0.1.0

package/src/spec/diff.ts

@@ -0,0 +1,791 @@
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, dirname, join, relative } from "path";
+
+import { resolveExtensionKindForPath } from "./extensions/registry";
+import { parseSpecDocument } from "./parser";
+import type {
+  ParsedMarkdownSection,
+  ParsedSpecDocument,
+  SpecArea,
+  SpecDelta,
+  SpecDiffReport,
+  SpecFileChange,
+  SpecKind,
+  SpecSectionChange,
+} from "./types";
+import { assertSafeLisaStorageWritePath, listEffectiveWorkspaceFiles, resolveWorkspaceLayout, resolveWorkspaceRoot, toLogicalPath } from "./workspace";
+
+export const DEFAULT_SPEC_DIFF_BASE_REF = "HEAD";
+export const WORKTREE_SPEC_DIFF_REF = "WORKTREE";
+export const EXTERNAL_SPEC_DIFF_BASE_REF = "SNAPSHOT";
+const EXTERNAL_SNAPSHOT_FILENAME = "effective-spec-tree.json";
+
+interface ExternalSpecSnapshot {
+  repoRevision?: string;
+  codePaths?: Record<string, { baselineHash: string; verifiedHash: string }>;
+  files: Record<string, string>;
+}
+
+const SPEC_DIFF_DIRECTORIES = [".specs/backend", ".specs/frontend"];
+const SECTION_CHANGE_TYPES: Record<string, string> = {
+  Frontmatter: "frontmatter_changed",
+  Summary: "summary_changed",
+  "Use Cases": "use_case_added_or_removed",
+  Invariants: "invariant_added_or_removed",
+  "Failure Modes": "failure_modes_changed",
+  "Acceptance Criteria": "acceptance_added_or_removed",
+  "Out of Scope": "out_of_scope_changed",
+  Scenario: "scenario_changed",
+  "Load Model": "load_model_changed",
+  Notes: "notes_changed",
+};
+const SECTION_ORDER = [
+  "Frontmatter",
+  "Summary",
+  "Use Cases",
+  "Invariants",
+  "Failure Modes",
+  "Acceptance Criteria",
+  "Out of Scope",
+  "Scenario",
+  "Load Model",
+  "Notes",
+];
+
+function decodeOutput(bytes: Uint8Array<ArrayBufferLike>): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function getExternalSnapshotPath(workspacePath: string): string {
+  return join(resolveWorkspaceLayout(workspacePath).snapshotRoot, EXTERNAL_SNAPSHOT_FILENAME);
+}
+
+function isExternalSnapshotCompatible(workspacePath: string, repoRevision: string | undefined): boolean {
+  if (!repoRevision) {
+    return true;
+  }
+
+  const currentHead = resolveWorkspaceHeadRevision(workspacePath);
+  if (!currentHead || currentHead === repoRevision) {
+    return true;
+  }
+
+  const result = runGitCommand(workspacePath, ["merge-base", "--is-ancestor", repoRevision, currentHead], { allowFailure: true });
+  return result.exitCode === 0;
+}
+
+function readExternalSnapshot(workspacePath: string): ExternalSpecSnapshot {
+  const snapshotPath = getExternalSnapshotPath(workspacePath);
+  if (!existsSync(snapshotPath)) {
+    return { files: {} };
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(snapshotPath, "utf8")) as {
+      repoRevision?: unknown;
+      codePaths?: Record<string, { baselineHash?: unknown; verifiedHash?: unknown }>;
+      files?: Record<string, string>;
+    };
+    if (!raw.files || typeof raw.files !== "object" || Array.isArray(raw.files)) {
+      return { files: {} };
+    }
+
+    const snapshot: ExternalSpecSnapshot = {
+      repoRevision: typeof raw.repoRevision === "string" && raw.repoRevision.trim().length > 0 ? raw.repoRevision.trim() : undefined,
+      codePaths: raw.codePaths && typeof raw.codePaths === "object" && !Array.isArray(raw.codePaths)
+        ? Object.fromEntries(
+          Object.entries(raw.codePaths).filter(
+            (entry): entry is [string, { baselineHash: string; verifiedHash: string }] => {
+              const value = entry[1];
+              return typeof value === "object"
+                && value !== null
+                && typeof value.baselineHash === "string"
+                && typeof value.verifiedHash === "string";
+            },
+          ),
+        )
+        : undefined,
+      files: Object.fromEntries(
+        Object.entries(raw.files).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+      ),
+    };
+
+    return isExternalSnapshotCompatible(workspacePath, snapshot.repoRevision) ? snapshot : { files: {} };
+  } catch {
+    return { files: {} };
+  }
+}
+
+export function readExternalSnapshotRepoRevision(cwd = process.cwd()): string | undefined {
+  return readExternalSnapshot(resolveWorkspaceRoot(cwd)).repoRevision;
+}
+
+export function readExternalSnapshotCodePaths(cwd = process.cwd()): Record<string, { baselineHash: string; verifiedHash: string }> {
+  return readExternalSnapshot(resolveWorkspaceRoot(cwd)).codePaths ?? {};
+}
+
+export function readExternalSpecSnapshot(cwd = process.cwd()): ExternalSpecSnapshot {
+  return readExternalSnapshot(resolveWorkspaceRoot(cwd));
+}
+
+function resolveWorkspaceHeadRevision(workspaceRoot: string): string | undefined {
+  const result = runGitCommand(workspaceRoot, ["rev-parse", "HEAD"], { allowFailure: true });
+  return result.exitCode === 0 ? result.stdout.trim() || undefined : undefined;
+}
+
+function normalizeCodePath(path: string): string {
+  return path.trim().split("\\").join("/");
+}
+
+function readRevisionCodeHash(workspaceRoot: string, revision: string | undefined, path: string): string {
+  if (!revision) {
+    return "__missing__";
+  }
+
+  const result = runGitCommand(workspaceRoot, ["show", `${revision}:${path}`], { allowFailure: true });
+  return result.exitCode === 0
+    ? createHash("sha1").update(result.stdout).digest("hex")
+    : "__missing__";
+}
+
+function listCurrentCodeSnapshotEntries(
+  workspaceRoot: string,
+  repoRevision: string | undefined,
+): Record<string, { baselineHash: string; verifiedHash: string }> {
+  const diffOutput = runGitCommand(workspaceRoot, ["diff", "--name-only", "HEAD", "--", "."], { allowFailure: true }).stdout;
+  const untrackedOutput = runGitCommand(workspaceRoot, ["ls-files", "--others", "--exclude-standard"], { allowFailure: true }).stdout;
+  const entries = new Map<string, { baselineHash: string; verifiedHash: string }>();
+
+  for (const source of [diffOutput, untrackedOutput]) {
+    for (const line of source.split("\n")) {
+      const path = normalizeCodePath(line);
+      if (!path || path.startsWith(".specs/") || path.startsWith(".git/") || path.startsWith(".lisa/")) {
+        continue;
+      }
+
+      const absolutePath = join(workspaceRoot, path);
+      const verifiedHash = existsSync(absolutePath)
+        ? createHash("sha1").update(readFileSync(absolutePath)).digest("hex")
+        : "__missing__";
+      entries.set(path, {
+        baselineHash: readRevisionCodeHash(workspaceRoot, repoRevision, path),
+        verifiedHash,
+      });
+    }
+  }
+
+  return Object.fromEntries(Array.from(entries.entries()).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+export function writeExternalSpecSnapshot(cwd = process.cwd()): string | undefined {
+  const layout = resolveWorkspaceLayout(cwd);
+  if (layout.storageMode !== "external") {
+    return undefined;
+  }
+
+  const files = buildExternalWorktreeFiles(layout);
+  const snapshotPath = getExternalSnapshotPath(layout.workspacePath);
+  const repoRevision = resolveWorkspaceHeadRevision(layout.workspacePath);
+  assertSafeLisaStorageWritePath(layout.snapshotRoot, snapshotPath, "Lisa spec snapshot");
+  mkdirSync(dirname(snapshotPath), { recursive: true });
+  writeFileSync(snapshotPath, `${JSON.stringify({
+    repoRevision,
+    codePaths: listCurrentCodeSnapshotEntries(layout.workspacePath, repoRevision),
+    files,
+  }, null, 2)}\n`);
+  return snapshotPath;
+}
+
+function toRepoRelativePath(workspaceRoot: string, filePath: string): string {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  return layout.storageMode === "external"
+    ? toLogicalPath(layout, filePath)
+    : relative(workspaceRoot, filePath).split("\\").join("/");
+}
+
+function buildExternalWorktreeFiles(layout: ReturnType<typeof resolveWorkspaceLayout>): Record<string, string> {
+  const effective = listEffectiveWorkspaceFiles(layout);
+  const files = new Map<string, string>();
+
+  for (const path of [...effective.documentPaths, ...effective.environmentPaths]) {
+    files.set(toLogicalPath(layout, path), readFileSync(path, "utf8"));
+  }
+
+  if (effective.configPath && existsSync(effective.configPath)) {
+    files.set(".specs/config.yaml", readFileSync(effective.configPath, "utf8"));
+  }
+
+  return Object.fromEntries(Array.from(files.entries()).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+function deriveSpecKind(path: string): SpecKind {
+  const extensionKind = resolveExtensionKindForPath(basename(path));
+  if (!extensionKind) {
+    return "base";
+  }
+
+  return extensionKind === "benchmark" ? "benchmark" : "extension";
+}
+
+function deriveSpecArea(path: string): SpecArea | undefined {
+  const normalized = path.split("\\").join("/");
+  const areaMatch = normalized.match(/\.specs\/(backend|frontend)\//);
+  return areaMatch?.[1] as SpecArea | undefined;
+}
+
+function deriveSpecIdFromPath(path: string): string {
+  const normalized = path.split("\\").join("/");
+  const areaMatch = normalized.match(/\.specs\/(backend|frontend)\//);
+  const filename = normalized.split("/").pop()?.replace(/\.md$/i, "") ?? normalized;
+  return areaMatch ? `${areaMatch[1]}.${filename}` : filename;
+}
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stableValue(entry));
+  }
+
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, stableValue(entryValue)]),
+    );
+  }
+
+  return value;
+}
+
+function stableSerialize(value: unknown): string {
+  return JSON.stringify(stableValue(value));
+}
+
+function normalizeSectionTitle(title: string): string {
+  return title.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function sectionSortKey(title: string): string {
+  const index = SECTION_ORDER.findIndex((entry) => normalizeSectionTitle(entry) === normalizeSectionTitle(title));
+  return `${String(index >= 0 ? index : SECTION_ORDER.length).padStart(4, "0")}:${title.toLowerCase()}`;
+}
+
+function mapSectionChangeType(title: string): string {
+  return SECTION_CHANGE_TYPES[title] ?? `${normalizeSectionTitle(title).replace(/[^a-z0-9]+/g, "_")}_changed`;
+}
+
+function asSectionMap(document?: ParsedSpecDocument): Map<string, ParsedMarkdownSection> {
+  const map = new Map<string, ParsedMarkdownSection>();
+  if (!document) {
+    return map;
+  }
+
+  for (const section of document.sections) {
+    map.set(normalizeSectionTitle(section.title), section);
+  }
+
+  return map;
+}
+
+function createFallbackDocument(filePath: string, logicalPath: string, content: string): ParsedSpecDocument {
+  return {
+    path: filePath,
+    filename: basename(logicalPath),
+    area: deriveSpecArea(logicalPath),
+    kind: deriveSpecKind(logicalPath),
+    id: deriveSpecIdFromPath(logicalPath),
+    status: undefined,
+    frontmatter: {},
+    body: content.trim(),
+    sections: [],
+  };
+}
+
+function parseDocumentForDiff(workspaceRoot: string, path: string, content?: string, actualPath?: string): ParsedSpecDocument | undefined {
+  if (content === undefined) {
+    return undefined;
+  }
+
+  const filePath = actualPath ?? join(workspaceRoot, path);
+  try {
+    return parseSpecDocument(filePath, content);
+  } catch {
+    return createFallbackDocument(filePath, path, content);
+  }
+}
+
+function runGitCommand(
+  workspaceRoot: string,
+  args: string[],
+  options: { allowFailure?: boolean } = {},
+): { stdout: string; stderr: string; exitCode: number } {
+  const proc = Bun.spawnSync({
+    cmd: ["git", ...args],
+    cwd: workspaceRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = decodeOutput(proc.stdout);
+  const stderr = decodeOutput(proc.stderr);
+
+  if (proc.exitCode !== 0 && !options.allowFailure) {
+    throw new Error(stderr.trim() || `git ${args.join(" ")} failed with exit code ${proc.exitCode}.`);
+  }
+
+  return { stdout, stderr, exitCode: proc.exitCode };
+}
+
+interface TrackedSpecChange {
+  path: string;
+  fileChange: SpecFileChange;
+  previousPath?: string;
+  nextPath?: string;
+}
+
+interface ExternalTrackedSpecChange extends TrackedSpecChange {
+  previousActualPath?: string;
+  nextActualPath?: string;
+}
+
+function listTrackedSpecChanges(workspaceRoot: string, baseRef: string, headRef?: string): TrackedSpecChange[] {
+  const args = [
+    "diff",
+    "--name-status",
+    "--find-renames",
+    ...(headRef ? [baseRef, headRef] : [baseRef]),
+    "--",
+    ...SPEC_DIFF_DIRECTORIES,
+  ];
+  const { stdout } = runGitCommand(workspaceRoot, args);
+  if (!stdout.trim()) {
+    return [];
+  }
+
+  const changes: TrackedSpecChange[] = [];
+
+  for (const line of stdout.split("\n").filter((entry) => entry.trim().length > 0)) {
+    const columns = line.split("\t");
+    const status = columns[0] ?? "";
+
+    if (status.startsWith("R") && columns[1] && columns[2]) {
+      changes.push({
+        path: columns[2],
+        fileChange: "modified",
+        previousPath: columns[1],
+        nextPath: columns[2],
+      });
+      continue;
+    }
+
+    const path = columns[1];
+    if (!path) {
+      continue;
+    }
+
+    if (status.startsWith("A")) {
+      changes.push({ path, fileChange: "added" });
+    } else if (status.startsWith("D")) {
+      changes.push({ path, fileChange: "deleted" });
+    } else {
+      changes.push({ path, fileChange: "modified" });
+    }
+  }
+
+  return changes;
+}
+
+function listUntrackedSpecFiles(workspaceRoot: string): string[] {
+  const { stdout } = runGitCommand(
+    workspaceRoot,
+    ["ls-files", "--others", "--exclude-standard", "--", ...SPEC_DIFF_DIRECTORIES],
+    { allowFailure: true },
+  );
+  return stdout
+    .split("\n")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function readWorktreeFile(workspaceRoot: string, path: string): string | undefined {
+  const absolutePath = join(workspaceRoot, path);
+  if (!existsSync(absolutePath)) {
+    return undefined;
+  }
+
+  return readFileSync(absolutePath, "utf8");
+}
+
+function readRevisionFile(workspaceRoot: string, ref: string, path: string): string | undefined {
+  const result = runGitCommand(workspaceRoot, ["show", `${ref}:${path}`], { allowFailure: true });
+  if (result.exitCode !== 0) {
+    return undefined;
+  }
+
+  return result.stdout;
+}
+
+function readDiffSide(workspaceRoot: string, ref: string, path: string): string | undefined {
+  return ref === WORKTREE_SPEC_DIFF_REF ? readWorktreeFile(workspaceRoot, path) : readRevisionFile(workspaceRoot, ref, path);
+}
+
+function listExternalTrackedChanges(layout: ReturnType<typeof resolveWorkspaceLayout>): ExternalTrackedSpecChange[] {
+  const previousFiles = readExternalSnapshot(layout.workspacePath).files;
+  const nextFiles = buildExternalWorktreeFiles(layout);
+  const logicalToActual = new Map<string, string>();
+  const effective = listEffectiveWorkspaceFiles(layout);
+  for (const path of [...effective.documentPaths, ...effective.environmentPaths]) {
+    logicalToActual.set(toLogicalPath(layout, path), path);
+  }
+
+  if (effective.configPath) {
+    logicalToActual.set(".specs/config.yaml", effective.configPath);
+  }
+
+  const keys = new Set<string>([...Object.keys(previousFiles), ...Object.keys(nextFiles)]);
+  const changes: ExternalTrackedSpecChange[] = [];
+
+  for (const key of Array.from(keys).sort()) {
+    const previous = previousFiles[key];
+    const next = nextFiles[key];
+    if (previous === next) {
+      continue;
+    }
+
+    changes.push({
+      path: key,
+      fileChange: previous === undefined ? "added" : next === undefined ? "deleted" : "modified",
+      previousPath: key,
+      nextPath: key,
+      nextActualPath: logicalToActual.get(key),
+    });
+  }
+
+  return changes.filter((change) => change.path.startsWith(".specs/backend/") || change.path.startsWith(".specs/frontend/"));
+}
+
+function buildSectionChanges(previousDocument?: ParsedSpecDocument, nextDocument?: ParsedSpecDocument): SpecSectionChange[] {
+  const changes: SpecSectionChange[] = [];
+  const previousFrontmatter = previousDocument ? stableSerialize(previousDocument.frontmatter) : undefined;
+  const nextFrontmatter = nextDocument ? stableSerialize(nextDocument.frontmatter) : undefined;
+
+  if (previousFrontmatter !== nextFrontmatter) {
+    changes.push({
+      section: "Frontmatter",
+      changeType: mapSectionChangeType("Frontmatter"),
+      oldText: previousDocument ? Bun.YAML.stringify(previousDocument.frontmatter).trim() : undefined,
+      newText: nextDocument ? Bun.YAML.stringify(nextDocument.frontmatter).trim() : undefined,
+    });
+  }
+
+  const previousSections = asSectionMap(previousDocument);
+  const nextSections = asSectionMap(nextDocument);
+  const titles = new Set<string>([
+    ...previousSections.keys(),
+    ...nextSections.keys(),
+  ]);
+
+  for (const key of Array.from(titles).sort((left, right) => sectionSortKey(left).localeCompare(sectionSortKey(right)))) {
+    const previousSection = previousSections.get(key);
+    const nextSection = nextSections.get(key);
+    const previousText = previousSection?.content.trim();
+    const nextText = nextSection?.content.trim();
+
+    if (previousText === nextText) {
+      continue;
+    }
+
+    const sectionTitle = nextSection?.title ?? previousSection?.title ?? key;
+    changes.push({
+      section: sectionTitle,
+      changeType: mapSectionChangeType(sectionTitle),
+      oldText: previousText && previousText.length > 0 ? previousText : undefined,
+      newText: nextText && nextText.length > 0 ? nextText : undefined,
+    });
+  }
+
+  return changes;
+}
+
+export interface CollectSpecDiffOptions {
+  baseRef?: string;
+  headRef?: string;
+}
+
+export function collectSpecDiff(cwd = process.cwd(), options: CollectSpecDiffOptions = {}): SpecDiffReport {
+  const workspacePath = resolveWorkspaceRoot(cwd);
+  const layout = resolveWorkspaceLayout(cwd);
+  const baseRef = options.baseRef ?? (layout.storageMode === "external" ? EXTERNAL_SPEC_DIFF_BASE_REF : DEFAULT_SPEC_DIFF_BASE_REF);
+  const headRef = options.headRef ?? WORKTREE_SPEC_DIFF_REF;
+
+  if (layout.storageMode === "external") {
+    const previousFiles = readExternalSnapshot(layout.workspacePath).files;
+    const nextFiles = buildExternalWorktreeFiles(layout);
+    const changes = listExternalTrackedChanges(layout);
+    const rawDeltas: SpecDelta[] = changes
+      .sort((left, right) => left.path.localeCompare(right.path))
+      .map((change) => {
+        const previousContent = change.fileChange === "added"
+          ? undefined
+          : previousFiles[change.path];
+        const nextContent = change.fileChange === "deleted"
+          ? undefined
+          : nextFiles[change.path];
+        const previousDocument = previousContent === undefined
+          ? undefined
+          : parseDocumentForDiff(workspacePath, change.path, previousContent);
+        const nextDocument = nextContent === undefined
+          ? undefined
+          : parseDocumentForDiff(workspacePath, change.path, nextContent, change.nextActualPath);
+        const document = nextDocument ?? previousDocument;
+        const kind = document?.kind ?? deriveSpecKind(change.path);
+        const specId = document?.id ?? deriveSpecIdFromPath(change.path);
+
+        return {
+          specId,
+          path: change.nextActualPath ?? join(workspacePath, change.path),
+          kind,
+          extensionKind: document?.extensionKind,
+          fileChange: change.fileChange,
+          sectionChanges: buildSectionChanges(previousDocument, nextDocument),
+          previousDocument,
+          nextDocument,
+          extendsSpecId: kind !== "base"
+            ? typeof (nextDocument ?? previousDocument)?.frontmatter.extends === "string"
+              ? ((nextDocument ?? previousDocument)?.frontmatter.extends as string)
+              : undefined
+            : undefined,
+        } satisfies SpecDelta;
+      });
+
+    const deltas: SpecDelta[] = [];
+    const consumed = new Set<number>();
+
+    for (const [index, delta] of rawDeltas.entries()) {
+      if (consumed.has(index)) {
+        continue;
+      }
+
+      if (delta.fileChange === "deleted") {
+        const addedIndex = rawDeltas.findIndex((candidate, candidateIndex) => (
+          !consumed.has(candidateIndex)
+          && candidate.fileChange === "added"
+          && candidate.specId === delta.specId
+          && candidate.kind === delta.kind
+        ));
+
+        if (addedIndex >= 0) {
+          const added = rawDeltas[addedIndex] as SpecDelta;
+          consumed.add(index);
+          consumed.add(addedIndex);
+          deltas.push({
+            specId: delta.specId,
+            path: added.path,
+            kind: added.kind,
+            extensionKind: added.extensionKind,
+            fileChange: "modified",
+            sectionChanges: buildSectionChanges(delta.previousDocument, added.nextDocument),
+            previousDocument: delta.previousDocument,
+            nextDocument: added.nextDocument,
+            extendsSpecId: added.extendsSpecId,
+          });
+          continue;
+        }
+      }
+
+      if (delta.fileChange === "added") {
+        const deletedIndex = rawDeltas.findIndex((candidate, candidateIndex) => (
+          !consumed.has(candidateIndex)
+          && candidate.fileChange === "deleted"
+          && candidate.specId === delta.specId
+          && candidate.kind === delta.kind
+        ));
+
+        if (deletedIndex >= 0) {
+          const deleted = rawDeltas[deletedIndex] as SpecDelta;
+          consumed.add(index);
+          consumed.add(deletedIndex);
+          deltas.push({
+            specId: delta.specId,
+            path: delta.path,
+            kind: delta.kind,
+            extensionKind: delta.extensionKind,
+            fileChange: "modified",
+            sectionChanges: buildSectionChanges(deleted.previousDocument, delta.nextDocument),
+            previousDocument: deleted.previousDocument,
+            nextDocument: delta.nextDocument,
+            extendsSpecId: delta.extendsSpecId,
+          });
+          continue;
+        }
+      }
+
+      deltas.push(delta);
+    }
+
+    return {
+      workspacePath,
+      baseRef,
+      headRef,
+      deltas,
+    };
+  }
+
+  const trackedChanges = listTrackedSpecChanges(
+    workspacePath,
+    baseRef,
+    options.headRef,
+  );
+  const changes = new Map<string, TrackedSpecChange>();
+
+  for (const change of trackedChanges) {
+    changes.set(change.path, change);
+  }
+
+  if (!options.headRef) {
+    for (const untrackedPath of listUntrackedSpecFiles(workspacePath)) {
+      if (!changes.has(untrackedPath)) {
+        changes.set(untrackedPath, { path: untrackedPath, fileChange: "added", nextPath: untrackedPath });
+      }
+    }
+  }
+
+  const candidates = Array.from(changes.values())
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .map((change) => {
+    const previousPath = change.previousPath ?? change.path;
+    const nextPath = change.nextPath ?? change.path;
+    const previousContent = change.fileChange === "added" ? undefined : readDiffSide(workspacePath, baseRef, previousPath);
+    const nextContent = change.fileChange === "deleted" ? undefined : readDiffSide(workspacePath, headRef, nextPath);
+    const previousDocument = parseDocumentForDiff(workspacePath, previousPath, previousContent);
+    const nextDocument = parseDocumentForDiff(workspacePath, nextPath, nextContent);
+
+    return {
+      change,
+      previousPath,
+      nextPath,
+      previousDocument,
+      nextDocument,
+    };
+  });
+  const deltas: SpecDelta[] = [];
+  const consumed = new Set<number>();
+
+  for (const [index, candidate] of candidates.entries()) {
+    if (consumed.has(index)) {
+      continue;
+    }
+
+    const { change, previousPath, nextPath, previousDocument, nextDocument } = candidate;
+    const tryMergeRename = (
+      matchingIndex: number,
+      previous: ParsedSpecDocument,
+      next: ParsedSpecDocument,
+      resolvedNextPath: string,
+    ): SpecDelta => ({
+      specId: next.id ?? deriveSpecIdFromPath(resolvedNextPath),
+      path: join(workspacePath, resolvedNextPath),
+      kind: next.kind,
+      extensionKind: next.extensionKind,
+      fileChange: "modified",
+      sectionChanges: buildSectionChanges(previous, next),
+      previousDocument: previous,
+      nextDocument: next,
+      extendsSpecId: next.kind !== "base" && typeof next.frontmatter.extends === "string"
+        ? next.frontmatter.extends
+        : undefined,
+    });
+
+    if (change.fileChange === "deleted" && previousDocument?.id) {
+      const addedIndex = candidates.findIndex((entry, entryIndex) => (
+        !consumed.has(entryIndex) &&
+        entry.change.fileChange === "added" &&
+        entry.nextDocument?.id === previousDocument.id &&
+        entry.nextDocument.kind === previousDocument.kind
+      ));
+
+      if (addedIndex >= 0) {
+        const added = candidates[addedIndex];
+        consumed.add(index);
+        consumed.add(addedIndex);
+        deltas.push(tryMergeRename(addedIndex, previousDocument, added.nextDocument as ParsedSpecDocument, added.nextPath));
+        continue;
+      }
+    }
+
+    if (change.fileChange === "added" && nextDocument?.id) {
+      const deletedIndex = candidates.findIndex((entry, entryIndex) => (
+        !consumed.has(entryIndex) &&
+        entry.change.fileChange === "deleted" &&
+        entry.previousDocument?.id === nextDocument.id &&
+        entry.previousDocument.kind === nextDocument.kind
+      ));
+
+      if (deletedIndex >= 0) {
+        const deleted = candidates[deletedIndex];
+        consumed.add(index);
+        consumed.add(deletedIndex);
+        deltas.push(tryMergeRename(deletedIndex, deleted.previousDocument as ParsedSpecDocument, nextDocument, nextPath));
+        continue;
+      }
+    }
+
+    if (change.previousPath && change.nextPath) {
+      const previousSpecId = previousDocument?.id ?? deriveSpecIdFromPath(previousPath);
+      const nextSpecId = nextDocument?.id ?? deriveSpecIdFromPath(nextPath);
+      if (previousSpecId !== nextSpecId) {
+        deltas.push({
+          specId: previousSpecId,
+          path: join(workspacePath, previousPath),
+          kind: previousDocument?.kind ?? deriveSpecKind(previousPath),
+          fileChange: "deleted",
+          sectionChanges: buildSectionChanges(previousDocument, undefined),
+          previousDocument,
+        });
+        deltas.push({
+          specId: nextSpecId,
+          path: join(workspacePath, nextPath),
+          kind: nextDocument?.kind ?? deriveSpecKind(nextPath),
+          extensionKind: nextDocument?.extensionKind,
+          fileChange: "added",
+          sectionChanges: buildSectionChanges(undefined, nextDocument),
+          nextDocument,
+          extendsSpecId: nextDocument?.kind !== "base" && typeof nextDocument.frontmatter.extends === "string"
+            ? nextDocument.frontmatter.extends
+            : undefined,
+        });
+        continue;
+      }
+    }
+
+    const document = nextDocument ?? previousDocument;
+    const kind = document?.kind ?? deriveSpecKind(change.path);
+    const specId = document?.id ?? deriveSpecIdFromPath(change.path);
+    deltas.push({
+      specId,
+      path: join(workspacePath, nextPath),
+      kind,
+      extensionKind: document?.extensionKind,
+      fileChange: change.fileChange,
+      sectionChanges: buildSectionChanges(previousDocument, nextDocument),
+      previousDocument,
+      nextDocument,
+      extendsSpecId: kind !== "base"
+        ? typeof (nextDocument ?? previousDocument)?.frontmatter.extends === "string"
+          ? ((nextDocument ?? previousDocument)?.frontmatter.extends as string)
+          : undefined
+        : undefined,
+    });
+  }
+
+  return {
+    workspacePath,
+    baseRef,
+    headRef,
+    deltas,
+  };
+}
+
+export function getSpecDiffRelativePath(diff: SpecDiffReport, path: string): string {
+  return toRepoRelativePath(diff.workspacePath, path);
+}