@young1lin/dsh-ui-gitworkbench 0.1.5 → 0.1.7

package/src/client/diff-nav.ts

@@ -0,0 +1,198 @@
+/**
+ * Walking a diff change by change.
+ *
+ * A file whose whole delta is `+1 −1` is unreadable by scrolling: the change
+ * is one tinted line somewhere in two thousand, and the tint is only visible
+ * once you are already looking at it. The row model already knows where every
+ * change is — `alignRows` groups changed rows into blocks and every rendered
+ * code cell carries its block id — so nothing here has to find the changes.
+ * What it decides is which one is NEXT.
+ *
+ * Position comes from the VIEWPORT, not from a remembered index. A reader
+ * hunting for a change also scrolls with the wheel, and a counter kept in
+ * state goes stale the moment they do — pressing the button would then jump
+ * back to wherever the last press left off, which reads as the button being
+ * broken. Asking the scroller where it is costs one layout read per press and
+ * is always right.
+ *
+ * The peek is the part that is easy to get wrong. Landing a change flush
+ * against the top edge hides the line above it, which is usually the line that
+ * makes the change legible — so the scroll stops a few rows short. That offset
+ * must then be added BACK when deciding what comes next, or the block just
+ * landed on still counts as "below the top of the viewport" and every press
+ * lands on it again. {@link anchorFor} and {@link scrollTopFor} are the two
+ * halves of that one invariant, which is why they are named rather than
+ * inlined as arithmetic at the call site.
+ *
+ * Pure: no React, no DOM. The component measures, this decides.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/diff-nav
+ */
+
+/** The pane's row height, from `.sideColGrid`'s `line-height`. */
+export const NAV_ROW_PX = 20
+
+/**
+ * Rows of context kept above a change the reader is sent to.
+ *
+ * Three, because a one-line edit is read against its neighbours: the line
+ * above is what tells you which rule, which function, which property this is.
+ */
+export const NAV_PEEK_ROWS = 3
+
+/** The peek in pixels. */
+export const NAV_PEEK_PX = NAV_ROW_PX * NAV_PEEK_ROWS
+
+/**
+ * Sub-pixel tolerance. `getBoundingClientRect` reports fractions, and a block
+ * sitting a third of a pixel below the anchor is the block the reader is
+ * already looking at, not the next one.
+ */
+const EPSILON_PX = 1
+
+/** Where one change block starts, in the scroller's content coordinates. */
+export interface BlockTop {
+  /** The block id the rows carry. */
+  readonly block: number
+  /** Offset from the top of the scrolled content, in pixels. */
+  readonly top: number
+}
+
+/**
+ * The content position that counts as "where the reader is".
+ *
+ * The top of the viewport plus the peek, so a change the reader was just sent
+ * to sits exactly AT the anchor rather than below it — which is what stops
+ * "next" from choosing it a second time.
+ */
+export function anchorFor(scrollTop: number): number {
+  return scrollTop + NAV_PEEK_PX
+}
+
+/** Where to scroll so a block sits {@link NAV_PEEK_ROWS} rows below the top. */
+export function scrollTopFor(top: number): number {
+  return Math.max(0, top - NAV_PEEK_PX)
+}
+
+/** The block a press landed on, and the scroll position it actually achieved. */
+export interface NavMemory {
+  readonly block: number
+  /** `scrollTop` AFTER the browser clamped it, not the value asked for. */
+  readonly scrollTop: number
+}
+
+/**
+ * Where to step from.
+ *
+ * Normally the viewport answers this, and {@link anchorFor} is the whole
+ * story. It stops being the whole story at the END of a file: a change in the
+ * last screenful cannot be scrolled to the peek line, because the scroller
+ * runs out of content first. `scrollTop` then stops changing between presses,
+ * the viewport can no longer say which change was last visited, and "next"
+ * chooses that same block forever — the reader is stuck on the final change
+ * with no way to wrap around.
+ *
+ * So when the scroll has NOT moved since the last press, the block that press
+ * landed on is the anchor instead. The two agree everywhere they both apply: a
+ * block parked at the peek line has a top exactly equal to `anchorFor` of the
+ * resulting scroll. Any hand-scrolling invalidates the memory and the viewport
+ * takes over again, which is what keeps the wheel and the buttons consistent.
+ *
+ * @param tops - every block's top, as measured for this press.
+ * @param scrollTop - the scroller's current position.
+ * @param held - what the previous press recorded, or null.
+ */
+export function anchorFrom(
+  tops: readonly BlockTop[],
+  scrollTop: number,
+  held: NavMemory | null,
+): number {
+  if (held !== null && Math.abs(held.scrollTop - scrollTop) < 1) {
+    const landed = tops.find(entry => entry.block === held.block)
+    // A block that no longer exists — the diff was refreshed under the reader
+    // — leaves nothing to step from, so the viewport answers after all.
+    if (landed !== undefined) return landed.top
+  }
+  return anchorFor(scrollTop)
+}
+
+/**
+ * The next or previous change block, wrapping at the ends.
+ *
+ * Wrapping rather than stopping: a reader pressing the button repeatedly is
+ * taking a tour of the file's changes, and a button that goes dead at the last
+ * one asks them to notice why. Coming back around to the first says the same
+ * thing — you have seen them all — without a disabled control to interpret.
+ *
+ * @param anchors - every block's top; order does not matter.
+ * @param anchorTop - from {@link anchorFor}, never a raw `scrollTop`.
+ * @param direction - 1 for the next change, -1 for the previous one.
+ * @returns the block to go to, or null when the diff has no changes at all.
+ */
+export function stepToBlock(
+  anchors: readonly BlockTop[],
+  anchorTop: number,
+  direction: 1 | -1,
+): BlockTop | null {
+  if (anchors.length === 0) return null
+  const ordered = [...anchors].sort((a, b) => a.top - b.top)
+  if (direction === 1) {
+    const ahead = ordered.find(entry => entry.top > anchorTop + EPSILON_PX)
+    return ahead ?? ordered[0] ?? null
+  }
+  let behind: BlockTop | null = null
+  for (const entry of ordered) {
+    if (entry.top < anchorTop - EPSILON_PX) behind = entry
+    else break
+  }
+  return behind ?? ordered[ordered.length - 1] ?? null
+}
+
+/** One unified-diff row, as far as grouping is concerned. */
+export type RowKind = 'add' | 'del' | 'context' | 'hunk'
+
+/**
+ * Group a unified diff's rows into change blocks.
+ *
+ * A block is a maximal run of added and deleted rows. A replacement arrives
+ * from git as deletions followed by additions with nothing between them, and
+ * that is ONE change to a reader — sending them to the `-` lines and then
+ * again to the `+` lines directly below would be counting the same edit twice.
+ * Context and hunk headers both end a run: a hunk header means git skipped
+ * lines, so what follows is somewhere else in the file.
+ *
+ * The side-by-side pane does not need this — its row model already carries a
+ * block id per row, because the blocks there are also what the stage and
+ * roll-back buttons act on. The unified view has no such model, so the runs
+ * are read off the kinds.
+ *
+ * @param kinds - every row's kind, in document order.
+ * @returns a block id per row, aligned with the input; -1 for a row that is
+ *   not part of any change.
+ */
+export function unifiedBlocks(kinds: readonly RowKind[]): readonly number[] {
+  const ids: number[] = []
+  let block = -1
+  let inRun = false
+  for (const kind of kinds) {
+    const changed = kind === 'add' || kind === 'del'
+    if (!changed) {
+      inRun = false
+      ids.push(-1)
+      continue
+    }
+    if (!inRun) {
+      block += 1
+      inRun = true
+    }
+    ids.push(block)
+  }
+  return ids
+}
+
+/** How many change blocks {@link unifiedBlocks} found. */
+export function countBlocks(ids: readonly number[]): number {
+  let top = -1
+  for (const id of ids) if (id > top) top = id
+  return top + 1
+}

package/src/client/file-icon.ts

@@ -0,0 +1,190 @@
+/**
+ * What a file's icon says about its language: a colour and a one- or two-letter
+ * monogram, keyed off the path.
+ *
+ * The obvious ask is the mascots — the gopher, the coffee cup, the crab. Those
+ * are not ours to ship: the gopher is a CC-BY work of Renée French, the cup and
+ * the two snakes are registered marks of Oracle and the PSF, and this is a
+ * package published to npm rather than a screenshot. So the icon keeps the
+ * drawer's own sheet outline and carries the language's canonical brand colour
+ * with a monogram on it — recognisable at a glance in a column of files, and
+ * nobody's mark reproduced.
+ *
+ * Colours are each language's own published one where it has it (Go's cyan,
+ * Rust's rust, TypeScript's blue), which is what makes the column scannable:
+ * you learn "the cyan ones are Go" in about four files without reading a
+ * single letter.
+ *
+ * Pure: no React, no DOM. `tests/file-icon.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/file-icon
+ */
+
+/** How one file type paints. */
+export interface FileIcon {
+  /** One or two characters, uppercase; '' for a file with no language. */
+  readonly mono: string
+  /** The tint, as a CSS colour. */
+  readonly color: string
+}
+
+/** What a file whose type we have nothing to say about looks like: the
+ *  drawer's ordinary foreground, no monogram. */
+export const PLAIN: FileIcon = { mono: '', color: 'var(--gs-fg-faint)' }
+
+/**
+ * By extension. Two letters where one would collide (JS/JSON, TS/TSX), one
+ * where it reads cleanly.
+ */
+const BY_EXT: Readonly<Record<string, FileIcon>> = {
+  go: { mono: 'GO', color: '#00add8' },
+  mod: { mono: 'GO', color: '#00add8' },
+  sum: { mono: 'GO', color: '#00add8' },
+  java: { mono: 'J', color: '#e76f00' },
+  class: { mono: 'J', color: '#e76f00' },
+  jar: { mono: 'J', color: '#e76f00' },
+  kt: { mono: 'KT', color: '#7f52ff' },
+  kts: { mono: 'KT', color: '#7f52ff' },
+  scala: { mono: 'SC', color: '#dc322f' },
+  groovy: { mono: 'GR', color: '#4298b8' },
+  ts: { mono: 'TS', color: '#3178c6' },
+  mts: { mono: 'TS', color: '#3178c6' },
+  cts: { mono: 'TS', color: '#3178c6' },
+  tsx: { mono: 'TX', color: '#3178c6' },
+  js: { mono: 'JS', color: '#f7df1e' },
+  mjs: { mono: 'JS', color: '#f7df1e' },
+  cjs: { mono: 'JS', color: '#f7df1e' },
+  jsx: { mono: 'JX', color: '#f7df1e' },
+  py: { mono: 'PY', color: '#3776ab' },
+  pyi: { mono: 'PY', color: '#3776ab' },
+  rs: { mono: 'RS', color: '#dea584' },
+  rb: { mono: 'RB', color: '#cc342d' },
+  php: { mono: 'PH', color: '#777bb4' },
+  cs: { mono: 'C#', color: '#68217a' },
+  c: { mono: 'C', color: '#5588cc' },
+  h: { mono: 'H', color: '#5588cc' },
+  cpp: { mono: 'C+', color: '#00599c' },
+  cc: { mono: 'C+', color: '#00599c' },
+  cxx: { mono: 'C+', color: '#00599c' },
+  hpp: { mono: 'H+', color: '#00599c' },
+  hh: { mono: 'H+', color: '#00599c' },
+  m: { mono: 'OC', color: '#438eff' },
+  mm: { mono: 'OC', color: '#438eff' },
+  swift: { mono: 'SW', color: '#f05138' },
+  dart: { mono: 'DA', color: '#0175c2' },
+  lua: { mono: 'LU', color: '#000080' },
+  r: { mono: 'R', color: '#276dc3' },
+  jl: { mono: 'JL', color: '#9558b2' },
+  ex: { mono: 'EX', color: '#6e4a7e' },
+  exs: { mono: 'EX', color: '#6e4a7e' },
+  erl: { mono: 'ER', color: '#a90533' },
+  hs: { mono: 'HS', color: '#5e5086' },
+  clj: { mono: 'CL', color: '#5881d8' },
+  cljs: { mono: 'CL', color: '#5881d8' },
+  zig: { mono: 'ZI', color: '#f7a41d' },
+  nim: { mono: 'NI', color: '#ffe953' },
+  pl: { mono: 'PL', color: '#39457e' },
+  pm: { mono: 'PL', color: '#39457e' },
+  vue: { mono: 'VU', color: '#41b883' },
+  svelte: { mono: 'SV', color: '#ff3e00' },
+  astro: { mono: 'AS', color: '#ff5d01' },
+  sh: { mono: 'SH', color: '#89e051' },
+  bash: { mono: 'SH', color: '#89e051' },
+  zsh: { mono: 'SH', color: '#89e051' },
+  fish: { mono: 'SH', color: '#89e051' },
+  ps1: { mono: 'PS', color: '#012456' },
+  bat: { mono: 'BT', color: '#c1f12e' },
+  sql: { mono: 'SQ', color: '#e38c00' },
+  html: { mono: 'HT', color: '#e34c26' },
+  htm: { mono: 'HT', color: '#e34c26' },
+  css: { mono: 'CS', color: '#563d7c' },
+  scss: { mono: 'SA', color: '#c6538c' },
+  sass: { mono: 'SA', color: '#c6538c' },
+  less: { mono: 'LE', color: '#1d365d' },
+  json: { mono: 'JN', color: '#cbcb41' },
+  jsonc: { mono: 'JN', color: '#cbcb41' },
+  yaml: { mono: 'YM', color: '#cb171e' },
+  yml: { mono: 'YM', color: '#cb171e' },
+  toml: { mono: 'TM', color: '#9c4221' },
+  ini: { mono: 'IN', color: '#6d8086' },
+  cfg: { mono: 'IN', color: '#6d8086' },
+  conf: { mono: 'IN', color: '#6d8086' },
+  env: { mono: 'EN', color: '#edd100' },
+  xml: { mono: 'XM', color: '#0060ac' },
+  md: { mono: 'MD', color: '#7aa6da' },
+  mdx: { mono: 'MD', color: '#7aa6da' },
+  rst: { mono: 'RS', color: '#7aa6da' },
+  txt: { mono: 'TX', color: 'var(--gs-fg-faint)' },
+  csv: { mono: 'CV', color: '#41a05f' },
+  svg: { mono: 'SV', color: '#ffb13b' },
+  png: { mono: 'IM', color: '#a074c4' },
+  jpg: { mono: 'IM', color: '#a074c4' },
+  jpeg: { mono: 'IM', color: '#a074c4' },
+  gif: { mono: 'IM', color: '#a074c4' },
+  webp: { mono: 'IM', color: '#a074c4' },
+  ico: { mono: 'IM', color: '#a074c4' },
+  pdf: { mono: 'PD', color: '#d93831' },
+  zip: { mono: 'ZP', color: '#b8a038' },
+  gz: { mono: 'ZP', color: '#b8a038' },
+  tar: { mono: 'ZP', color: '#b8a038' },
+  lock: { mono: 'LK', color: '#8b8b8b' },
+  proto: { mono: 'PB', color: '#4285f4' },
+  graphql: { mono: 'GQ', color: '#e10098' },
+  gql: { mono: 'GQ', color: '#e10098' },
+  tf: { mono: 'TF', color: '#7b42bc' },
+  vim: { mono: 'VI', color: '#019833' },
+}
+
+/**
+ * By whole filename, for the files that carry their type in their NAME rather
+ * than an extension — a Dockerfile has no suffix, and `.gitignore` is all
+ * suffix. Matched case-insensitively before the extension table.
+ */
+const BY_NAME: Readonly<Record<string, FileIcon>> = {
+  dockerfile: { mono: 'DK', color: '#2496ed' },
+  'docker-compose.yml': { mono: 'DK', color: '#2496ed' },
+  'docker-compose.yaml': { mono: 'DK', color: '#2496ed' },
+  makefile: { mono: 'MK', color: '#427819' },
+  cmakelists: { mono: 'CM', color: '#064f8c' },
+  'cmakelists.txt': { mono: 'CM', color: '#064f8c' },
+  '.gitignore': { mono: 'GI', color: '#f05033' },
+  '.gitattributes': { mono: 'GI', color: '#f05033' },
+  '.gitmodules': { mono: 'GI', color: '#f05033' },
+  '.npmrc': { mono: 'NP', color: '#cb3837' },
+  '.nvmrc': { mono: 'NP', color: '#cb3837' },
+  'package.json': { mono: 'NP', color: '#cb3837' },
+  'package-lock.json': { mono: 'NP', color: '#cb3837' },
+  'pnpm-lock.yaml': { mono: 'PN', color: '#f69220' },
+  'yarn.lock': { mono: 'YN', color: '#2c8ebb' },
+  'cargo.toml': { mono: 'RS', color: '#dea584' },
+  'cargo.lock': { mono: 'RS', color: '#dea584' },
+  'go.mod': { mono: 'GO', color: '#00add8' },
+  'go.sum': { mono: 'GO', color: '#00add8' },
+  'pom.xml': { mono: 'MV', color: '#c71a36' },
+  'build.gradle': { mono: 'GD', color: '#02303a' },
+  'build.gradle.kts': { mono: 'GD', color: '#02303a' },
+  license: { mono: 'LI', color: '#d0b000' },
+  'license.md': { mono: 'LI', color: '#d0b000' },
+  readme: { mono: 'MD', color: '#7aa6da' },
+  'readme.md': { mono: 'MD', color: '#7aa6da' },
+}
+
+/**
+ * The icon for one path.
+ *
+ * The whole-name table wins over the extension table, so `package.json` reads
+ * as npm rather than as generic JSON — the name is the more specific fact.
+ *
+ * @param path - repo-relative or bare filename; only the last segment matters.
+ */
+export function fileIcon(path: string): FileIcon {
+  const name = (path.split('/').pop() ?? '').toLowerCase()
+  if (name.length === 0) return PLAIN
+  const byName = BY_NAME[name]
+  if (byName !== undefined) return byName
+  const dot = name.lastIndexOf('.')
+  // A leading dot is the whole name of a dotfile, not the start of a suffix:
+  // `.gitignore` has no extension, and `git` is not a language.
+  if (dot <= 0) return PLAIN
+  return BY_EXT[name.slice(dot + 1)] ?? PLAIN
+}

package/src/client/file-rows.ts

@@ -0,0 +1,184 @@
+/**
+ * The file browser's row list: which rows a repository tree renders, given
+ * which directories the reader has opened.
+ *
+ * This sits on top of {@link buildDirTree}, which the history filter's path
+ * picker already uses, and adds the two things a BROWSER needs that a picker
+ * did not. First, root-level files: `buildDirTree` returns the root's child
+ * directories, so a file living on no directory — `package.json`, `README.md`
+ * — never appears in it. A picker could leave those to its search; a browser
+ * that cannot open `package.json` is not a browser. Second, a flat row list
+ * with depth, because the tree renders as rows and the component should not
+ * be walking a recursive structure while it also handles clicks.
+ *
+ * Search results are FILE rows only. The picker lists directories too, since
+ * a directory is a tickable pathspec there; here a row is something to open,
+ * and a directory does not open.
+ *
+ * Pure: no React, no DOM, no git. `tests/file-rows.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/file-rows
+ */
+
+import type { DirEntry } from './dir-tree.ts'
+
+/** One rendered row of the browser's tree. */
+export interface FileRow {
+  /** `more` is the "and N others" marker a capped directory ends with. */
+  readonly kind: 'dir' | 'file' | 'more'
+  /** Repo-relative path — for a file row, what gets opened. */
+  readonly path: string
+  /** What the row shows: the last segment, or the whole path in a search. */
+  readonly name: string
+  /** Indent level; 0 at the top. */
+  readonly depth: number
+  /** Whether this directory is expanded. Always false on a file row. */
+  readonly open: boolean
+  /** On a `more` row: how many entries the cap held back. */
+  readonly hidden?: number
+  /**
+   * On a `more` row: what it is holding back.
+   *
+   * A directory can end with both markers — too many subdirectories AND too
+   * many files — and they sit at the same depth under the same prefix, so
+   * without this they are indistinguishable, including to the key the renderer
+   * builds from a row.
+   */
+  readonly more?: 'dirs' | 'files'
+}
+
+/**
+ * The files that live directly in the repository root, sorted by name.
+ * @param paths - repo-relative paths, exactly as `repoTree` returned them.
+ */
+export function rootFiles(paths: readonly string[]): readonly string[] {
+  return paths.filter(path => path.length > 0 && !path.includes('/')).sort((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Flatten the tree into the rows to render.
+ *
+ * Directories come before files at every level — the shape every file tree
+ * has — and a directory's contents appear only while it is expanded. An entry
+ * in `expanded` whose parent is closed contributes nothing: expansion is only
+ * meaningful along a path that is itself visible.
+ *
+ * @param tree - top-level directories from {@link buildDirTree}.
+ * @param roots - root-level files from {@link rootFiles}.
+ * @param expanded - paths of the directories the reader has opened.
+ * @param cap - most SUBDIRECTORIES and most files rendered per directory; the
+ *              rest become one `more` row each. Each row is a button and two
+ *              icons, so the cost is the DOM rather than this walk, and one
+ *              click must not be able to put an unbounded number of them
+ *              there. Capping files alone was not enough: a directory holding
+ *              6,000 subdirectories froze the tab for 628ms on expanding it,
+ *              measured, and that grows with the directory. Both caps have the
+ *              same escape hatch — the search box, which reads the whole path
+ *              list and ignores the tree. Omit for no cap.
+ */
+export function treeRows(
+  tree: readonly DirEntry[],
+  roots: readonly string[],
+  expanded: ReadonlySet<string>,
+  cap = Number.POSITIVE_INFINITY,
+): readonly FileRow[] {
+  const out: FileRow[] = []
+  /** Emit a directory's files, then the marker if the cap bit. */
+  const files = (names: readonly string[], prefix: string, depth: number): void => {
+    const shown = names.length > cap ? names.slice(0, cap) : names
+    for (const name of shown) {
+      out.push({ kind: 'file', path: `${prefix}${name}`, name, depth, open: false })
+    }
+    if (names.length > shown.length) {
+      out.push({
+        kind: 'more',
+        path: prefix,
+        name: '',
+        depth,
+        open: false,
+        hidden: names.length - shown.length,
+        more: 'files',
+      })
+    }
+  }
+  const walk = (dirs: readonly DirEntry[], prefix: string, depth: number): void => {
+    const shown = dirs.length > cap ? dirs.slice(0, cap) : dirs
+    for (const dir of shown) {
+      const open = expanded.has(dir.path)
+      out.push({ kind: 'dir', path: dir.path, name: dir.name, depth, open })
+      if (!open) continue
+      walk(dir.children, `${dir.path}/`, depth + 1)
+      files(dir.files, `${dir.path}/`, depth + 1)
+    }
+    if (dirs.length > shown.length) {
+      out.push({
+        kind: 'more',
+        path: prefix,
+        name: '',
+        depth,
+        open: false,
+        hidden: dirs.length - shown.length,
+        more: 'dirs',
+      })
+    }
+  }
+  walk(tree, '', 0)
+  files(roots, '', 0)
+  return out
+}
+
+/**
+ * Every directory above a path, outermost first — what to expand so that
+ * opening a file reveals it in the tree.
+ */
+export function ancestorsOf(path: string): readonly string[] {
+  const parts = path.split('/')
+  const out: string[] = []
+  for (let i = 1; i < parts.length; i += 1) out.push(parts.slice(0, i).join('/'))
+  return out
+}
+
+/**
+ * Search the repository's files, case-insensitively over the whole path.
+ *
+ * Each hit carries its full path as its name: a flat list of bare filenames
+ * cannot be told apart, and a repository usually holds several `index.ts`.
+ *
+ * @param paths - repo-relative paths as `repoTree` returned them.
+ * @param needle - raw search text; blank matches nothing.
+ * @param cap - most rows to return, so a one-letter search cannot render the
+ *              whole repository.
+ */
+export function searchRows(paths: readonly string[], needle: string, cap: number): readonly FileRow[] {
+  const n = needle.trim().toLowerCase()
+  if (n.length === 0) return []
+  const out: FileRow[] = []
+  for (const path of paths) {
+    if (out.length >= cap) break
+    if (path.toLowerCase().includes(n)) {
+      out.push({ kind: 'file', path, name: path, depth: 0, open: false })
+    }
+  }
+  return out
+}
+
+/**
+ * The browsable path list: everything git tracks, plus files that exist on
+ * disk but not in HEAD.
+ *
+ * `repoTree` is `git ls-tree HEAD`, so a file created five minutes ago is not
+ * in it — and a browser that cannot open the file you just wrote reads as
+ * broken rather than as principled. The drawer already holds the working
+ * tree's own file list, so the union costs one pass.
+ *
+ * @param tracked - paths from `repoTree`.
+ * @param extra - paths from the working-tree status; deleted files must be
+ *                filtered out by the caller, since opening one would fail.
+ */
+export function mergePaths(tracked: readonly string[], extra: readonly string[]): readonly string[] {
+  const all = new Set(tracked)
+  for (const path of extra) {
+    if (path.length > 0) all.add(path)
+  }
+  return [...all].sort((a, b) => a.localeCompare(b))
+}