@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/shared/lib/fs/file-tree.test.ts

@@ -0,0 +1,183 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The tree edits that let a create and a rename skip a reload.
+ *
+ * Each rule here is a way the rendered tree would disagree with the disk:
+ *
+ * 1. **A nested entry brings the chain that leads to it.** `lib/parse.ts` names
+ *    a folder the tree does not carry yet; without the chain the row is placed
+ *    under a key no branch reaches and simply never renders.
+ * 2. **A collapsed folder is not guessed at.** Its children are not this
+ *    tree's knowledge, so an entry created inside one is deliberately NOT
+ *    inserted — expanding it reads the real directory, which by then holds the
+ *    new entry. Inserting into a guess would show a listing the server never
+ *    produced.
+ * 3. **A rename re-points every descendant.** A folder's children carry its
+ *    path as a prefix; moving the folder without rewriting them leaves rows
+ *    whose `path` no longer resolves and an expansion set keyed by names that
+ *    are gone.
+ * 4. **A rename never loses the moved entry's own loaded children.** Its cache
+ *    entry is rekeyed with it, so a folder renamed while open stays open with
+ *    its contents.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { FsNode } from '@/shared/types';
+import {
+  baseNameOf,
+  parentPathOf,
+  placeEntry,
+  rekeyCache,
+  rekeyExpansion,
+  renameEntryAt,
+  sortEntries,
+  takeEntry,
+} from '@/shared/lib/fs/file-tree';
+
+const file = (path: string): FsNode => ({ name: baseNameOf(path), path, type: 'file' });
+const folder = (path: string, children?: FsNode[]): FsNode =>
+  children ? { name: baseNameOf(path), path, type: 'folder', children } : { name: baseNameOf(path), path, type: 'folder' };
+
+describe('placeEntry', () => {
+  test('a top-level entry lands in the root, folders first', () => {
+    const placed = placeEntry([folder('src'), file('z.ts')], {}, file('a.ts'));
+
+    expect(placed.nodes.map((node) => node.path)).toEqual(['src', 'a.ts', 'z.ts']);
+    expect(placed.cache).toEqual({});
+  });
+
+  test('a nested entry creates the chain that leads to it', () => {
+    const placed = placeEntry([], {}, file('lib/deep/parse.ts'));
+
+    expect(placed.nodes.map((node) => node.path)).toEqual(['lib']);
+    expect(placed.cache.lib?.map((node) => node.path)).toEqual(['lib/deep']);
+    expect(placed.cache['lib/deep']?.map((node) => node.path)).toEqual(['lib/deep/parse.ts']);
+  });
+
+  test('an existing chain is extended, not duplicated', () => {
+    const placed = placeEntry([folder('lib')], { lib: [folder('lib/deep')], 'lib/deep': [] }, file('lib/deep/x.ts'));
+
+    expect(placed.nodes).toHaveLength(1);
+    expect(placed.cache['lib/deep']?.map((node) => node.path)).toEqual(['lib/deep/x.ts']);
+  });
+
+  test('an entry inside a COLLAPSED folder is not inserted', () => {
+    // `src` is listed with `children: null` — the tree has never read it, so
+    // there is nothing to place the entry into and no guess to make.
+    const tree = [folder('src')];
+    const placed = placeEntry(tree, {}, file('src/hidden.ts'));
+
+    expect(placed.nodes).toBe(tree);
+    expect(placed.cache).toEqual({});
+  });
+
+  test('an empty folder is LOADED, and can receive an entry', () => {
+    const placed = placeEntry([folder('src')], { src: [] }, file('src/new.ts'));
+
+    expect(placed.cache.src?.map((node) => node.path)).toEqual(['src/new.ts']);
+  });
+
+  test('a created folder is a folder in the cache too, so it can be expanded', () => {
+    const placed = placeEntry([], {}, folder('packages'));
+
+    expect(placed.nodes[0].type).toBe('folder');
+    expect(placed.nodes[0].children).toBeUndefined();
+  });
+});
+
+describe('takeEntry', () => {
+  test('removes a root entry and hands it back', () => {
+    const taken = takeEntry([file('a.ts'), file('b.ts')], {}, 'a.ts');
+
+    expect(taken.entry?.path).toBe('a.ts');
+    expect(taken.nodes.map((node) => node.path)).toEqual(['b.ts']);
+  });
+
+  test('removes a nested entry from its parent cache', () => {
+    const taken = takeEntry([folder('src')], { src: [file('src/a.ts'), file('src/b.ts')] }, 'src/a.ts');
+
+    expect(taken.entry?.path).toBe('src/a.ts');
+    expect(taken.cache.src?.map((node) => node.path)).toEqual(['src/b.ts']);
+  });
+
+  test('a path the tree does not carry reports no entry and changes nothing', () => {
+    const cache = { src: [file('src/a.ts')] };
+    const taken = takeEntry([folder('src')], cache, 'src/hidden.ts');
+
+    expect(taken.entry).toBeNull();
+    expect(taken.cache).toBe(cache);
+  });
+});
+
+describe('renameEntryAt', () => {
+  test('re-points the node and every descendant', () => {
+    const tree = [folder('src', [folder('src/lib', [file('src/lib/a.ts')])])];
+    const moved = renameEntryAt(tree, 'src', 'lib');
+
+    expect(moved[0].path).toBe('lib');
+    expect(moved[0].name).toBe('lib');
+    expect(moved[0].children?.[0].path).toBe('lib/lib');
+    expect(moved[0].children?.[0].children?.[0].path).toBe('lib/lib/a.ts');
+  });
+
+  test('a sibling whose path merely shares a prefix is left alone', () => {
+    const tree = [file('src.ts'), file('src/a.ts')];
+    const moved = renameEntryAt(tree, 'src', 'lib');
+
+    expect(moved[0]).toBe(tree[0]);
+    expect(moved[1].path).toBe('lib/a.ts');
+  });
+
+  test('a file rename updates its own name', () => {
+    const moved = renameEntryAt([file('a.ts')], 'a.ts', 'nested/b.ts');
+
+    expect(moved[0].path).toBe('nested/b.ts');
+    expect(moved[0].name).toBe('b.ts');
+  });
+});
+
+describe('rekeyCache', () => {
+  test('moves the folder key and every key beneath it', () => {
+    const cache = { src: [folder('src/lib')], 'src/lib': [file('src/lib/a.ts')], other: [file('other/x.ts')] };
+    const moved = rekeyCache(cache, 'src', 'app');
+
+    expect(Object.keys(moved).sort()).toEqual(['app', 'app/lib', 'other']);
+    expect(moved['app/lib']?.[0].path).toBe('app/lib/a.ts');
+    expect(moved.other).toBe(cache.other);
+  });
+});
+
+describe('rekeyExpansion', () => {
+  test('an open folder and its open children stay open under their new paths', () => {
+    const next = rekeyExpansion(new Set(['src', 'src/lib', 'docs']), 'src', 'app');
+
+    expect([...next].sort()).toEqual(['app', 'app/lib', 'docs']);
+  });
+
+  test('a path that only shares a prefix is untouched', () => {
+    const next = rekeyExpansion(new Set(['src.ts']), 'src', 'app');
+
+    expect([...next]).toEqual(['src.ts']);
+  });
+});
+
+describe('sortEntries', () => {
+  test('folders first, then by name — the server’s own order', () => {
+    const sorted = sortEntries([file('b.ts'), folder('z'), file('a.ts'), folder('a')]);
+
+    expect(sorted.map((node) => node.path)).toEqual(['a', 'z', 'a.ts', 'b.ts']);
+  });
+});
+
+describe('path helpers', () => {
+  test('parentPathOf and baseNameOf split a nested path', () => {
+    expect(parentPathOf('lib/deep/a.ts')).toBe('lib/deep');
+    expect(parentPathOf('a.ts')).toBe('.');
+    expect(baseNameOf('lib/deep/a.ts')).toBe('a.ts');
+    expect(baseNameOf('a.ts')).toBe('a.ts');
+  });
+});

package/src/shared/lib/fs/file-tree.ts

@@ -29,3 +29,162 @@ export function rehydrateTree(nodes: FsNode[], cache: Record<string, FsNode[]>):
     return { ...node, children: rehydrateTree(cached, cache) };
   });
 }
+
+/** The folder a path lives in: `.` for a top-level entry. */
+export function parentPathOf(path: string): string {
+  const cut = path.lastIndexOf('/');
+  return cut === -1 ? '.' : path.slice(0, cut);
+}
+
+/** The last segment of a path. */
+export function baseNameOf(path: string): string {
+  const cut = path.lastIndexOf('/');
+  return cut === -1 ? path : path.slice(cut + 1);
+}
+
+/**
+ * The server's own ordering (`lib/fs/listing.ts`): folders first, then by name.
+ *
+ * A locally inserted row has to land where the server would have put it, or the
+ * next real read would visibly reorder the tree under the user.
+ */
+export function sortEntries(nodes: FsNode[]): FsNode[] {
+  return [...nodes].sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'folder' ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+/** The listing after a local edit: the root list plus the children cache. */
+export interface TreeEdit {
+  nodes: FsNode[];
+  cache: Record<string, FsNode[]>;
+}
+
+/**
+ * Insert `entry` where its own path says it belongs, creating the folder chain
+ * that leads to it when the tree does not carry it yet.
+ *
+ * This is what lets a create and a rename skip a reload: the panel already
+ * knows the whole answer, and re-reading the root plus every open folder to
+ * learn it back would collapse nothing but cost a request per open folder.
+ *
+ * A chain is only extended through folders whose children are KNOWN — the root
+ * list plus the cache. A collapsed folder's contents are not this tree's to
+ * guess at, so an entry created inside one is simply not inserted: expanding it
+ * reads the real directory, which by then holds the new entry. The chain nodes
+ * that ARE inserted carry no `children` array, so the row's own expand effect
+ * reads them from disk like any other unread folder.
+ */
+export function placeEntry(nodes: FsNode[], cache: Record<string, FsNode[]>, entry: FsNode): TreeEdit {
+  const segments = entry.path.split('/');
+  const nextNodes = [...nodes];
+  const nextCache = { ...cache };
+  let container = nextNodes;
+  let containerKey: string | null = null;
+
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    const folderPath = segments.slice(0, i + 1).join('/');
+    const existing = container.find((node) => node.path === folderPath);
+    const known = existing ? (nextCache[folderPath] ?? existing.children) : null;
+    if (existing && !Array.isArray(known)) return { nodes, cache };
+    const children = Array.isArray(known) ? [...known] : [];
+    if (!existing) container.push({ name: segments[i], path: folderPath, type: 'folder', ignored: false });
+    nextCache[folderPath] = children;
+    container = children;
+    containerKey = folderPath;
+  }
+
+  container.push(entry);
+  if (containerKey !== null) nextCache[containerKey] = sortEntries(container);
+  return { nodes: sortEntries(nextNodes), cache: nextCache };
+}
+
+/**
+ * Remove the entry at `path` from wherever it lives, leaving the rest of the
+ * tree untouched. Returns `entry: null` when the path is not in this tree —
+ * a collapsed folder's contents are not, and that is not an error.
+ */
+export function takeEntry(
+  nodes: FsNode[],
+  cache: Record<string, FsNode[]>,
+  path: string,
+): TreeEdit & { entry: FsNode | null } {
+  const parent = parentPathOf(path);
+  if (parent === '.') {
+    const entry = nodes.find((node) => node.path === path) ?? null;
+    if (!entry) return { entry: null, nodes, cache };
+    return { entry, nodes: nodes.filter((node) => node.path !== path), cache };
+  }
+  const siblings = cache[parent];
+  const entry = siblings?.find((node) => node.path === path) ?? null;
+  if (!entry || !siblings) return { entry: null, nodes, cache };
+  return {
+    entry,
+    nodes,
+    cache: { ...cache, [parent]: siblings.filter((node) => node.path !== path) },
+  };
+}
+
+/**
+ * Re-point one entry and every path beneath it at a new location.
+ *
+ * A folder's descendants carry their parent's path as a prefix, so moving the
+ * folder without rewriting them would leave every child pointing at the old
+ * tree — a row whose `path` no longer resolves, and an expansion set keyed by
+ * names that are gone.
+ *
+ * A branch that does not hold the moved path is returned AS IS: the arrays are
+ * what React diffs, and a rename that rebuilt every unrelated subtree would
+ * re-render the whole tree for a change it did not touch.
+ */
+export function renameEntryAt(nodes: FsNode[], fromPath: string, toPath: string): FsNode[] {
+  let changed = false;
+  const next = nodes.map((node) => {
+    const isMoved = node.path === fromPath || node.path.startsWith(`${fromPath}/`);
+    const nested = Array.isArray(node.children) ? renameEntryAt(node.children, fromPath, toPath) : undefined;
+    // `nested === node.children` holds for a file (`undefined`) and for a folder
+    // whose subtree did not move, so an untouched row keeps its identity.
+    if (!isMoved && nested === node.children) return node;
+    changed = true;
+    const path = isMoved ? (node.path === fromPath ? toPath : `${toPath}${node.path.slice(fromPath.length)}`) : node.path;
+    const renamed: FsNode = isMoved ? { ...node, path, name: baseNameOf(path) } : { ...node };
+    if (nested !== undefined) renamed.children = nested;
+    return renamed;
+  });
+  return changed ? next : nodes;
+}
+
+/**
+ * Move every cache entry under `fromPath` to `toPath`, paths included.
+ *
+ * An entry outside the move keeps its own array identity, for the reason
+ * `renameEntryAt` does: those arrays are what the tree diffs.
+ */
+export function rekeyCache(
+  cache: Record<string, FsNode[]>,
+  fromPath: string,
+  toPath: string,
+): Record<string, FsNode[]> {
+  const next: Record<string, FsNode[]> = {};
+  for (const [key, children] of Object.entries(cache)) {
+    const moved = key === fromPath
+      ? toPath
+      : key.startsWith(`${fromPath}/`)
+        ? `${toPath}${key.slice(fromPath.length)}`
+        : key;
+    next[moved] = moved === key ? children : renameEntryAt(children, fromPath, toPath);
+  }
+  return next;
+}
+
+/** Rewrite the expansion set for a renamed folder, so open branches stay open. */
+export function rekeyExpansion(expanded: Set<string>, fromPath: string, toPath: string): Set<string> {
+  const next = new Set<string>();
+  for (const path of expanded) {
+    if (path === fromPath) next.add(toPath);
+    else if (path.startsWith(`${fromPath}/`)) next.add(`${toPath}${path.slice(fromPath.length)}`);
+    else next.add(path);
+  }
+  return next;
+}

package/src/shared/lib/fs/file-url.test.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `pathFromFileUrl` — the platform-specific half of a dropped-file reference.
+ *
+ * Pinned here rather than through the scope route because the Windows case is
+ * invisible on the machine this repository is developed on: the route's own test
+ * is `testPosix`, so the drive-letter branch had no test at all until a Windows
+ * CI run refused every dropped file.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { pathFromFileUrl } from '@/shared/lib/fs/file-url';
+
+describe('pathFromFileUrl', () => {
+  test('a POSIX file URL decodes to the path it names', () => {
+    expect(pathFromFileUrl('file:///tmp/x/b.ts')).toBe('/tmp/x/b.ts');
+  });
+
+  test('a percent-encoded space is decoded', () => {
+    expect(pathFromFileUrl('file:///tmp/x/My%20Notes.md')).toBe('/tmp/x/My Notes.md');
+  });
+
+  test('a Windows drive letter loses the leading slash, in every spelling', () => {
+    // All three forms answer `/C:/…` from `new URL().pathname`, and a leading
+    // slash on win32 resolves against the CURRENT DRIVE's root — a path no
+    // workspace contains.
+    expect(pathFromFileUrl('file:///C:/Users/x/b.ts')).toBe('C:/Users/x/b.ts');
+    expect(pathFromFileUrl('file://C:/Users/x/b.ts')).toBe('C:/Users/x/b.ts');
+    expect(pathFromFileUrl('file://C:\\Users\\x\\b.ts')).toBe('C:/Users/x/b.ts');
+  });
+
+  test('a percent-encoded drive path is decoded before the slash is dropped', () => {
+    expect(pathFromFileUrl('file:///D:/a/My%20Notes.md')).toBe('D:/a/My Notes.md');
+  });
+
+  test('a path that is not a file URL is refused rather than guessed at', () => {
+    expect(pathFromFileUrl('/tmp/x/b.ts')).toBeNull();
+    expect(pathFromFileUrl('https://example.com/x.ts')).toBeNull();
+  });
+
+  test('a malformed escape is refused, not thrown', () => {
+    expect(pathFromFileUrl('file:///tmp/%E0%A4%A')).toBeNull();
+  });
+
+  test('a lowercase drive letter is kept as written', () => {
+    expect(pathFromFileUrl('file:///c:/x/b.ts')).toBe('c:/x/b.ts');
+  });
+});

package/src/shared/lib/fs/file-url.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A `file://` URL to the path it names.
+ *
+ * Shared rather than private to the scope route, because the transformation is
+ * platform-specific and a private copy can only be exercised on the platform it
+ * was written on: the Windows branch below was wrong for as long as it lived
+ * inside a route whose test skipped Windows.
+ *
+ * Two rules, both measured:
+ *
+ * - **The pathname is percent-encoded** — a space is `%20`, and a Finder drop of
+ *   `My Notes.md` is exactly that — so decoding is not optional.
+ *   `decodeURIComponent` throws on a malformed escape, which is answered as
+ *   "not a path" rather than surfacing as a 500.
+ * - **A WINDOWS drive letter loses its leading slash.** `new URL('file://C:\a\b.ts')`
+ *   and the canonical `file:///C:/a/b.ts` BOTH answer `/C:/a/b.ts`, and
+ *   `path.resolve` on win32 turns that into `\C:\a\b.ts` — a path under the
+ *   current DRIVE's root, which no workspace contains. On the Windows CI leg
+ *   every dropped file was refused with "outside every workspace", so a file
+ *   dropped on the editor opened nothing at all. `fileURLToPath` drops the same
+ *   slash; this does it without a `node:url` import in a shared module.
+ */
+export function pathFromFileUrl(reference: string): string | null {
+  if (!/^file:\/\//i.test(reference)) return null;
+  try {
+    const pathname = decodeURIComponent(new URL(reference).pathname);
+    // `/C:/…` → `C:/…`; `/tmp/…` is left alone.
+    return /^\/[A-Za-z]:[\\/]/.test(pathname) ? pathname.slice(1) : pathname;
+  } catch {
+    return null;
+  }
+}

package/src/shared/lib/fs/patch-sides.test.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A unified patch → the two documents it compares.
+ *
+ * What this pins is the shape a chat tool card depends on: a card has a PATCH
+ * and no files, and it draws the same merge surface the diff panel does — so the
+ * sides it hands over must be exactly what the patch says they were. A context
+ * row belongs to both, a `-` row only to the original, a `+` row only to the new
+ * one; everything else (the `diff --git` header, `index`, `---`/`+++`, mode and
+ * rename lines, the "No newline" marker) is metadata and must not appear in
+ * either document.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { patchSides } from '@/shared/lib/fs/patch-sides';
+
+const GIT_DIFF = [
+  'diff --git a/src/a.ts b/src/a.ts',
+  'index 1111111..2222222 100644',
+  '--- a/src/a.ts',
+  '+++ b/src/a.ts',
+  '@@ -1,3 +1,3 @@',
+  ' const one = 1;',
+  '-const two = 2;',
+  '+const two = 22;',
+  ' const three = 3;',
+  '',
+].join('\n');
+
+describe('patchSides', () => {
+  test('splits a git diff into the documents it compares', () => {
+    const sides = patchSides(GIT_DIFF);
+
+    expect(sides.original).toBe('const one = 1;\nconst two = 2;\nconst three = 3;');
+    expect(sides.next).toBe('const one = 1;\nconst two = 22;\nconst three = 3;');
+    expect(sides.additions).toBe(1);
+    expect(sides.deletions).toBe(1);
+    expect(sides.hasHunk).toBe(true);
+  });
+
+  test('keeps the header lines out of both documents', () => {
+    // A `--- a/x` header would otherwise land in the original as `-- a/x`, and
+    // the merge view would draw a chunk that is not a change.
+    const sides = patchSides(GIT_DIFF);
+    for (const line of ['diff --git', 'index ', '--- a/', '+++ b/']) {
+      expect(sides.original.includes(line)).toBe(false);
+      expect(sides.next.includes(line)).toBe(false);
+    }
+  });
+
+  test('a new file has an empty original and the whole new document', () => {
+    const sides = patchSides(['@@ -0,0 +1,2 @@', '+alpha', '+beta'].join('\n'));
+
+    expect(sides.original).toBe('');
+    expect(sides.next).toBe('alpha\nbeta');
+    expect(sides.additions).toBe(2);
+    expect(sides.deletions).toBe(0);
+  });
+
+  test('a deleted file is the mirror image', () => {
+    const sides = patchSides(['@@ -1,1 +0,0 @@', '-gone'].join('\n'));
+
+    expect(sides.original).toBe('gone');
+    expect(sides.next).toBe('');
+    expect(sides.deletions).toBe(1);
+  });
+
+  test('a header-only patch has no rows, so the caller can fall back to text', () => {
+    const sides = patchSides('--- a/x\n+++ b/x\n');
+
+    expect(sides.rows).toBe(0);
+    expect(sides.hasHunk).toBe(false);
+  });
+
+  test('an empty patch is the empty answer, not a one-line document', () => {
+    expect(patchSides('')).toEqual({ original: '', next: '', additions: 0, deletions: 0, rows: 0, hasHunk: false });
+    expect(patchSides('   \n')).toEqual({ original: '', next: '', additions: 0, deletions: 0, rows: 0, hasHunk: false });
+  });
+
+  test('counts rows without the blank line a trailing newline leaves behind', () => {
+    const sides = patchSides(['@@ -1 +1 @@', '-a', '+b'].join('\n'));
+
+    expect(sides.rows).toBe(2);
+  });
+
+  test('a hunk starting mid-file keeps its real line numbers', () => {
+    // Without the padding the change would be line 1 of the rebuilt document,
+    // and the card's gutter would name a line the file does not have it on.
+    const sides = patchSides(['@@ -43,2 +43,2 @@', ' context', '-old', '+new'].join('\n'));
+
+    expect(sides.original.split('\n')).toHaveLength(44);
+    expect(sides.original.split('\n')[42]).toBe('context');
+    expect(sides.original.split('\n')[43]).toBe('old');
+    expect(sides.next.split('\n')[43]).toBe('new');
+  });
+
+  test('the gap between two hunks is restored from their own headers', () => {
+    const sides = patchSides(
+      ['@@ -2,1 +2,1 @@', '-a', '+b', '@@ -10,1 +10,1 @@', '-c', '+d'].join('\n'),
+    );
+
+    // Line 2 is the first change, line 10 the second, and everything between is
+    // unchanged content the patch did not carry.
+    const original = sides.original.split('\n');
+    expect(original[1]).toBe('a');
+    expect(original[9]).toBe('c');
+    expect(original).toHaveLength(10);
+  });
+});

package/src/shared/lib/fs/patch-sides.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A unified patch as its two DOCUMENTS.
+ *
+ * This replaced a table parser (`diff-parser.ts`) that produced per-row line
+ * numbers and paired split-view rows. Both of those are now the merge view's
+ * job — `@codemirror/merge` computes the alignment itself from two documents —
+ * so the only thing still needed from a patch is what the two sides were.
+ *
+ * That matters in one place: a chat tool card has a PATCH and no documents, and
+ * the card draws the same merge surface the diff panel does. Reconstructing the
+ * sides here keeps one renderer for both, instead of the card growing a second
+ * diff implementation that drifts.
+ *
+ * **The gap between hunks is restored as blank lines, and that is what keeps the
+ * gutter honest.** A hunk header names the line it starts on (`@@ -43,7 +43,8`),
+ * and a document rebuilt by concatenating hunks would number the change from 1.
+ * Padding each side up to the header's own counters puts the change back on the
+ * line the file has it on — and because the padding is unchanged content, the
+ * merge view collapses it into one marker (`contentMode: 'diff'`).
+ *
+ * The counters are the patch's own (`+`/`-` rows, hunk headers excluded), which
+ * is what the card's header prints. The diff panel deliberately does NOT use
+ * them: it has the real documents, and its counts must describe the rows the
+ * merge view actually draws (a collapsed or whitespace-folded change is not a
+ * changed row on screen).
+ */
+
+/** One side's text, and what the patch said about it. */
+export interface PatchSides {
+  /** The document before the change, with the hunk gaps as blank lines. */
+  original: string;
+  /** The document after it, the same way. */
+  next: string;
+  additions: number;
+  deletions: number;
+  /** Content rows the patch produced — zero for a header-only or empty patch. */
+  rows: number;
+  /** The patch named at least one hunk (`@@`), so it is a real diff. */
+  hasHunk: boolean;
+}
+
+const EMPTY: PatchSides = { original: '', next: '', additions: 0, deletions: 0, rows: 0, hasHunk: false };
+
+/** Header lines that describe the patch rather than its content. */
+const HEADER_PREFIXES = [
+  'diff --git',
+  'index ',
+  '---',
+  '+++',
+  'new file mode',
+  'deleted file mode',
+  'similarity index',
+  'dissimilarity index',
+  'rename from',
+  'rename to',
+  'copy from',
+  'copy to',
+  'old mode',
+  'new mode',
+  '\\ No newline',
+];
+
+/** `@@ -43,7 +43,8 @@` → the two starting lines; anything else → null. */
+function hunkStarts(line: string): { old: number; next: number } | null {
+  const match = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+  if (!match) return null;
+  return { old: Number(match[1]), next: Number(match[2]) };
+}
+
+/** Pad `lines` with blanks until it holds `count` lines. */
+function padTo(lines: string[], count: number): void {
+  while (lines.length < count) lines.push('');
+}
+
+export function patchSides(patch: string): PatchSides {
+  if (!patch.trim()) return EMPTY;
+
+  const before: string[] = [];
+  const after: string[] = [];
+  let additions = 0;
+  let deletions = 0;
+  let rows = 0;
+  let hasHunk = false;
+
+  const lines = patch.split(/\r?\n/);
+  // A patch ends with a newline, and `split` turns that into a final empty
+  // string. It is the terminator, not a blank row: keeping it put an empty line
+  // at the end of BOTH documents, which the merge view drew as a chunk.
+  if (lines[lines.length - 1] === '') lines.pop();
+
+  for (const raw of lines) {
+    if (HEADER_PREFIXES.some((prefix) => raw.startsWith(prefix))) continue;
+
+    if (raw.startsWith('@@')) {
+      hasHunk = true;
+      const starts = hunkStarts(raw);
+      // `-0,0` (a new file) has no original line to reach, and `padTo` is a
+      // no-op for it because the count is below what is already there.
+      if (starts) {
+        padTo(before, starts.old - 1);
+        padTo(after, starts.next - 1);
+      }
+      continue;
+    }
+
+    if (raw.startsWith('+')) {
+      additions++;
+      rows++;
+      after.push(raw.slice(1));
+      continue;
+    }
+    if (raw.startsWith('-')) {
+      deletions++;
+      rows++;
+      before.push(raw.slice(1));
+      continue;
+    }
+    // A context row (` ` prefix) is on BOTH sides; a bare line is what a
+    // header-less patch carries, and it is context too.
+    const text = raw.startsWith(' ') ? raw.slice(1) : raw;
+    rows++;
+    before.push(text);
+    after.push(text);
+  }
+
+  return {
+    original: before.join('\n'),
+    next: after.join('\n'),
+    additions,
+    deletions,
+    rows,
+    hasHunk,
+  };
+}