@young1lin/dsh-ui-gitworkbench 0.1.4 → 0.1.6

package/src/client/side-rows.ts

@@ -0,0 +1,258 @@
+/**
+ * The side-by-side diff's row model: a parsed full-context diff turned into
+ * rows that pair the two columns.
+ *
+ * A unified diff already IS an alignment — `context` lines hit both columns, a
+ * `del` the left one, an `add` the right one — so no diff algorithm is needed
+ * here or bundled: `git diff -U1000000` emits one hunk covering the whole file
+ * and this module only has to read that alignment into rows.
+ *
+ * The pairing rule is positional, the way IDEA renders it: inside a run of
+ * consecutive changed lines the 1st deletion pairs with the 1st addition, the
+ * 2nd with the 2nd, … into `change` rows, and whatever has no partner becomes a
+ * one-sided `del` or `add` row. A one-line edit is then ONE row with both
+ * sides, not a delete row above an add row.
+ *
+ * A block — a maximal run of changed rows uninterrupted by a `same` row — is
+ * the unit the stage/discard/unstage buttons of the editable view act on.
+ * `blockLines` names a block back in the hunk's own coordinates: the line
+ * indices it returns are exactly the selection `patch-model`'s `emitPatch`
+ * needs to reproduce that block alone, which is the contract that keeps those
+ * buttons correct.
+ *
+ * `` markers belong to the line before them and
+ * never form a row of their own. They are carried, not dropped: a row's
+ * `leftIndex`/`rightIndex` stay true indices into `hunk.lines`, so the marker
+ * describing a row's line is reachable as `index + 1` when a later task wants
+ * to render it.
+ *
+ * Pure: no React, no CSS, no git. `tests/side-rows.test.ts` loads it directly.
+ */
+
+import type { FilePatch } from '../patch-model.ts'
+
+/** One column's half of a row: that side's real line number and text. */
+export interface SideCell {
+  readonly line: number
+  readonly text: string
+}
+
+export interface SideRow {
+  /** `same` both columns equal; `change` a paired del/add; `del`/`add` one-sided. */
+  readonly kind: 'same' | 'change' | 'del' | 'add'
+  readonly left: SideCell | null
+  readonly right: SideCell | null
+  /** Index into the hunk's `lines` for the LEFT cell, -1 when absent. */
+  readonly leftIndex: number
+  /** Index into the hunk's `lines` for the RIGHT cell, -1 when absent. */
+  readonly rightIndex: number
+  /** Which change block this row belongs to; -1 for unchanged rows. */
+  readonly block: number
+}
+
+/** One collected side of a run of changed lines, with its hunk-line index. */
+interface RunSide {
+  readonly index: number
+  readonly text: string
+}
+
+/**
+ * Align a full-context diff's single hunk into two-column rows.
+ *
+ * @param file - a parsed diff. Full context means one hunk; anything else is
+ *               the caller's bug, and mis-aligning it silently would be worse
+ *               than refusing.
+ * @returns the rows, in file order: `same` rows carry both line numbers,
+ *          changed rows carry their block id.
+ * @throws when the patch does not have exactly one hunk.
+ */
+export function alignRows(file: FilePatch): readonly SideRow[] {
+  if (file.hunks.length !== 1) {
+    throw new Error(`alignRows expects the one hunk of a full-context diff, got ${file.hunks.length}`)
+  }
+  const hunk = file.hunks[0]!
+  const rows: SideRow[] = []
+  let oldL = hunk.oldStart
+  let newL = hunk.newStart
+  let block = -1
+
+  let i = 0
+  while (i < hunk.lines.length) {
+    const line = hunk.lines[i]!
+    if (line.kind === 'nonewline') {
+      // Describes the line before it, which a row already carries; never a row.
+      i += 1
+      continue
+    }
+    if (line.kind === 'context') {
+      rows.push({
+        kind: 'same',
+        left: { line: oldL, text: line.text },
+        right: { line: newL, text: line.text },
+        leftIndex: i,
+        rightIndex: i,
+        block: -1,
+      })
+      oldL += 1
+      newL += 1
+      i += 1
+      continue
+    }
+
+    // A run of del/add lines — one block. `\ No newline` markers inside the
+    // run are transparent: git can put one between the deletions and the
+    // additions, and that is still ONE change, not two blocks with no context
+    // line between them.
+    const dels: RunSide[] = []
+    const adds: RunSide[] = []
+    let j = i
+    while (j < hunk.lines.length) {
+      const run = hunk.lines[j]!
+      if (run.kind === 'del') dels.push({ index: j, text: run.text })
+      else if (run.kind === 'add') adds.push({ index: j, text: run.text })
+      else if (run.kind !== 'nonewline') break
+      j += 1
+    }
+    block += 1
+
+    const pairs = Math.min(dels.length, adds.length)
+    for (let p = 0; p < pairs; p += 1) {
+      rows.push({
+        kind: 'change',
+        left: { line: oldL, text: dels[p]!.text },
+        right: { line: newL, text: adds[p]!.text },
+        leftIndex: dels[p]!.index,
+        rightIndex: adds[p]!.index,
+        block,
+      })
+      oldL += 1
+      newL += 1
+    }
+    for (let p = pairs; p < dels.length; p += 1) {
+      rows.push({
+        kind: 'del',
+        left: { line: oldL, text: dels[p]!.text },
+        right: null,
+        leftIndex: dels[p]!.index,
+        rightIndex: -1,
+        block,
+      })
+      oldL += 1
+    }
+    for (let p = pairs; p < adds.length; p += 1) {
+      rows.push({
+        kind: 'add',
+        left: null,
+        right: { line: newL, text: adds[p]!.text },
+        leftIndex: -1,
+        rightIndex: adds[p]!.index,
+        block,
+      })
+      newL += 1
+    }
+    i = j
+  }
+  return rows
+}
+
+/**
+ * Every hunk line index a block covers: each of its rows' `leftIndex` and
+ * `rightIndex` where present, ascending, without duplicates.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @param block - a block id the rows carry.
+ * @returns the indices, exactly the selection `emitPatch` takes to reproduce
+ *          this block alone (its own changes plus the file's context).
+ */
+export function blockLines(rows: readonly SideRow[], block: number): readonly number[] {
+  const indices = new Set<number>()
+  for (const row of rows) {
+    if (row.block !== block) continue
+    if (row.leftIndex !== -1) indices.add(row.leftIndex)
+    if (row.rightIndex !== -1) indices.add(row.rightIndex)
+  }
+  return [...indices].sort((a, b) => a - b)
+}
+
+/**
+ * How many change blocks the rows hold.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @returns the block count, 0 for an unchanged file.
+ */
+export function blockCount(rows: readonly SideRow[]): number {
+  let max = -1
+  for (const row of rows) if (row.block > max) max = row.block
+  return max + 1
+}
+
+/**
+ * Whether a block is the file's ENTIRE content: the one block of a diff with
+ * no context row at all.
+ *
+ * An untracked file's synthesized new-file diff is exactly this shape — every
+ * line an addition, nothing unchanged — and it is the case whose roll-back
+ * DELETES the file rather than rewriting it, so the confirmation's wording
+ * asks for it by name. A tracked file whose every line changed has the same
+ * shape and only rewrites, which is why the caller combines this with the
+ * file row's status instead of reading deletion into the shape alone.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @param block - a block id the rows carry.
+ * @returns true when the block covers every row and no row is unchanged.
+ */
+export function blockIsWholeFile(rows: readonly SideRow[], block: number): boolean {
+  if (rows.length === 0 || block !== 0 || blockCount(rows) !== 1) return false
+  return rows.every(row => row.kind !== 'same')
+}
+
+/** What the pane's body area renders for the payload on screen. */
+export type SideBody =
+  | { readonly kind: 'editor' }
+  | { readonly kind: 'empty' }
+  | { readonly kind: 'rows' }
+
+/**
+ * Decide the pane's BODY area — never the whole pane.
+ *
+ * The tab row above it always renders: an empty layer diff (a fully staged
+ * file's unstaged side, a file with nothing staged) is one click from the
+ * other layer — and, on the unstaged side, one Edit button from the editor,
+ * because the working tree is the edit target even when every change in it is
+ * already staged. So "no rows" is a state of the body, not an early return
+ * for the pane, and an ARMED editor over an emptied diff still edits: the
+ * file's unstaged delta can vanish (the agent staged everything) under a
+ * buffer the reader is mid-edit in.
+ *
+ * @param rows - rows from {@link alignRows}; empty when the layer diff is.
+ * @param editable - whether the editor is armed (unstaged layer only).
+ * @returns which of the three body treatments the pane renders.
+ */
+export function sideBodyState(rows: readonly SideRow[], editable: boolean): SideBody {
+  if (editable) return { kind: 'editor' }
+  if (rows.length === 0) return { kind: 'empty' }
+  return { kind: 'rows' }
+}
+
+/**
+ * A block's line tallies: how many of its rows carry a right cell (added) and
+ * how many a left one (deleted). A paired edit counts one on each side.
+ *
+ * The roll-back confirmation states the consequence in these terms — "these N
+ * added and M deleted lines are reverted" — so the count must come from the
+ * same row model the buttons act on, not from the file row's whole-file stats.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @param block - a block id the rows carry.
+ * @returns the tallies; zeros for an id no row carries.
+ */
+export function blockTally(rows: readonly SideRow[], block: number): { readonly added: number; readonly deleted: number } {
+  let added = 0
+  let deleted = 0
+  for (const row of rows) {
+    if (row.block !== block) continue
+    if (row.left !== null) deleted += 1
+    if (row.right !== null) added += 1
+  }
+  return { added, deleted }
+}

package/src/client/stable-list.ts

@@ -0,0 +1,31 @@
+/**
+ * Is this list the same list as last time?
+ *
+ * React memoisation keys on IDENTITY, and the drawer polls: `git status` comes
+ * back every 3–15 seconds and every derived array is a new object even when
+ * the repository has not moved. In the Files tab that identity change is the
+ * head of a chain — the untracked paths feed the merged path list, which feeds
+ * the directory tree, which feeds the rows — so one fresh array per poll
+ * rebuilds a 20,000-path tree that is byte-for-byte what it already was.
+ *
+ * Comparing the contents costs one pass over the list; rebuilding costs a sort
+ * and a tree walk. The comparison wins by two orders of magnitude, and it wins
+ * by more the larger the repository is, which is exactly where it matters.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/stable-list
+ */
+
+/**
+ * Element-wise equality, in order.
+ *
+ * Identity first: the common case is that nothing upstream changed at all, and
+ * then there is nothing to compare.
+ */
+export function sameList(a: readonly string[], b: readonly string[]): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}

package/src/client/use-change-nav.ts

@@ -0,0 +1,83 @@
+/**
+ * Walking a scroller change by change — the wiring half of `diff-nav.ts`.
+ *
+ * The decisions (which block is next, where to stop, how to survive the end of
+ * the file) are pure and live next door, where vitest can reach them. What is
+ * left is the part that cannot be pure: reading the DOM for where the blocks
+ * actually are, and moving the scroller. Both panes that offer the walk — the
+ * side-by-side view in Changes and the unified view in History and Compare —
+ * need exactly this, and a second copy of it is a second place for the
+ * scroll-position bookkeeping to be got subtly wrong.
+ *
+ * The scroller is passed IN rather than created here: in Changes the pane owns
+ * it, in History the drawer does. The blocks are found by attribute, so any
+ * renderer that marks its changed rows with `data-block` can be walked.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/use-change-nav
+ */
+
+import { useRef, type MutableRefObject } from 'react'
+
+import { anchorFrom, scrollTopFor, stepToBlock, type BlockTop, type NavMemory } from './diff-nav.ts'
+
+/** What a pane needs to offer the walk. */
+export interface ChangeNav {
+  /** Move to the next (1) or previous (-1) change, wrapping at both ends. */
+  readonly goToChange: (direction: 1 | -1) => void
+}
+
+/**
+ * @param scrollRef - the element that scrolls, and the one whose subtree
+ *   carries the `data-block` marks.
+ */
+export function useChangeNav(scrollRef: MutableRefObject<HTMLDivElement | null>): ChangeNav {
+  /** What the last press landed on. A ref, not state: it exists to make the
+   *  NEXT press correct, and nothing on screen reads it. */
+  const navMemory = useRef<NavMemory | null>(null)
+
+  /**
+   * Every change block's position inside the scrolled content.
+   *
+   * Measured off the DOM rather than derived from a row model: a model knows
+   * which rows changed, not how many pixels down the page they sit, and the
+   * rows are never the only thing in the scroller — padding, a sticky bar and,
+   * in the armed side-by-side pane, a CodeMirror view of a different height
+   * all move the answer. One layout read per PRESS is cheap; nothing here runs
+   * on scroll.
+   *
+   * `offsetTop` is deliberately not used: it is relative to whichever ancestor
+   * happens to be positioned, which no rule in the stylesheet guarantees.
+   * Measuring both boxes and subtracting is independent of that.
+   */
+  const blockTops = (): readonly BlockTop[] => {
+    const scroller = scrollRef.current
+    if (scroller === null) return []
+    // First element carrying each id, in document order. A side-by-side row
+    // marks both of its columns, so the first hit for a block is its first row.
+    const first = new Map<number, HTMLElement>()
+    for (const cell of scroller.querySelectorAll<HTMLElement>('[data-block]')) {
+      const block = Number(cell.dataset.block)
+      if (!Number.isInteger(block) || block < 0 || first.has(block)) continue
+      first.set(block, cell)
+    }
+    const base = scroller.getBoundingClientRect().top - scroller.scrollTop
+    const tops: BlockTop[] = []
+    for (const [block, cell] of first) tops.push({ block, top: cell.getBoundingClientRect().top - base })
+    return tops
+  }
+
+  const goToChange = (direction: 1 | -1): void => {
+    const scroller = scrollRef.current
+    if (scroller === null) return
+    const tops = blockTops()
+    const target = stepToBlock(tops, anchorFrom(tops, scroller.scrollTop, navMemory.current), direction)
+    if (target === null) return
+    scroller.scrollTop = scrollTopFor(target.top)
+    // Read back rather than storing what was asked for: the browser clamps at
+    // the end of the content, and the clamped value is what the next press
+    // compares against to tell "still here" from "the reader scrolled".
+    navMemory.current = { block: target.block, scrollTop: scroller.scrollTop }
+  }
+
+  return { goToChange }
+}

package/src/client/worktree-view.ts

@@ -12,6 +12,16 @@ function normalize(path: string): string {
   return path.replace(/\\/g, '/').replace(/\/+$/, '')
 }
 
+/**
+ * A path in the one form everything compares by — the same normalisation
+ * {@link samePath} uses, exposed so state can be KEYED by a worktree rather
+ * than only tested against one. An absent path keys as '', which is a real
+ * key: it names the session's own repository, the source the drawer starts on.
+ */
+export function pathKey(path: string | null | undefined): string {
+  return path === null || path === undefined ? '' : normalize(path)
+}
+
 /**
  * Whether two paths name the same place.
  *
@@ -23,7 +33,7 @@ function normalize(path: string): string {
  */
 export function samePath(a: string | null | undefined, b: string | null | undefined): boolean {
   if (a === null || a === undefined || b === null || b === undefined) return false
-  return normalize(a) === normalize(b)
+  return pathKey(a) === pathKey(b)
 }
 
 /**

package/src/fs-remove.ts

@@ -0,0 +1,76 @@
+/**
+ * The one filesystem delete in this plugin, and the checks it carries.
+ *
+ * `discard-ops.ts` plans a delete when git has no copy of a file to restore
+ * from — untracked, or added-but-never-committed. git will not carry that out:
+ * `git clean` refuses paths it cannot index, which on Windows includes every
+ * reserved device name (`nul`, `con`, `aux`, `com1`, and the same names with
+ * any extension). So the removal goes through the filesystem, where git's own
+ * refusal to leave the repository does not apply — hence the checks here
+ * rather than a bare `rm`.
+ *
+ * Lives outside `index.ts` so vitest can load it: the class there needs the
+ * dsh runtime, and the property worth testing is "what does this delete, and
+ * what does it refuse" — a question about paths and the disk, not about RPC.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/fs-remove
+ */
+
+import { rm } from 'node:fs/promises'
+import { resolve, sep } from 'node:path'
+
+import { isSafeRelativePath } from './discard-ops.js'
+
+/**
+ * Resolve a repo-relative path against the worktree root, refusing to leave it.
+ *
+ * The second lock rather than the only one: {@link isSafeRelativePath} already
+ * rejected traversal spellings when the plan was made. This re-checks the
+ * RESOLVED path, which is the form the filesystem acts on, so a path that
+ * survives the first check by being spelled unusually still has to land inside
+ * the root to be acted on.
+ *
+ * @param root - the worktree directory, absolute.
+ * @param relative - repo-relative path from a plan step.
+ * @returns the absolute path to act on.
+ * @throws if the path is not a safe relative path, resolves outside the root,
+ *         or IS the root.
+ */
+export function resolveInside(root: string, relative: string): string {
+  if (!isSafeRelativePath(relative)) {
+    throw new Error(`unsafe path to delete: ${JSON.stringify(relative)}`)
+  }
+  const base = resolve(root)
+  const target = resolve(base, relative)
+  if (target === base) throw new Error('refusing to delete the worktree root')
+  if (!target.startsWith(base + sep)) {
+    throw new Error(`refusing to delete outside the worktree: ${JSON.stringify(relative)}`)
+  }
+  return target
+}
+
+/**
+ * Remove one entry from the worktree, having proven it is inside it.
+ *
+ * `recursive` is not a widening of the blast radius: `resolveInside` has
+ * already pinned the target to one path git named, and git names a DIRECTORY
+ * whenever it will not look inside one — an untracked nested repository is
+ * reported as `sub/`, with no per-file lines even under
+ * `--untracked-files=all`. Without `recursive` that row is the only one in the
+ * drawer whose roll-back fails, and it fails as `EISDIR`, which says nothing
+ * to the person who clicked it.
+ *
+ * `force` makes an absent entry a success: the reader asked for it to be gone,
+ * and it is.
+ *
+ * A symlinked directory inside the worktree could still point outward; that is
+ * a repository someone already has write access to, and resolving link targets
+ * per segment on every delete would cost a stat per segment for a case git
+ * itself does not defend against.
+ *
+ * @param root - the worktree directory, absolute.
+ * @param relative - repo-relative path from a plan step.
+ */
+export async function removePathInside(root: string, relative: string): Promise<void> {
+  await rm(resolveInside(root, relative), { recursive: true, force: true })
+}

package/src/git-ops.ts

@@ -210,7 +210,15 @@ export function stageStateOf(xy: string): StageState {
   return { staged: index !== ' ', unstaged: worktree !== ' ' }
 }
 
-/** Why an operation failed, in terms the drawer can explain to a person. */
+/**
+ * Why an operation failed, in terms the drawer can explain to a person.
+ *
+ * The last two are caller-derived, which is why {@link classifyFailure} never
+ * returns them: `stale` is a sha mismatch the caller compared before running
+ * git at all, and `invalid` an argument combination the caller refused before
+ * anything spawned. They ride the same union so a `GitOpResult` needs no
+ * parallel classification for the operations that produce them.
+ */
 export type OpFailure =
   | 'auth'
   | 'network'
@@ -219,6 +227,8 @@ export type OpFailure =
   | 'conflict'
   | 'nothing-to-commit'
   | 'dirty'
+  | 'stale'
+  | 'invalid'
   | 'unknown'
 
 /**
@@ -489,6 +499,31 @@ export function isBinaryPrefix(bytes: Buffer, windowBytes: number): boolean {
   return bytes.subarray(0, windowBytes).includes(0)
 }
 
+/**
+ * Whether a buffer is valid UTF-8, and so survives a decode/encode round trip.
+ *
+ * The editable pane hands the browser a decoded string and writes back what
+ * comes home encoded as UTF-8. For a file in any other encoding — GBK, Shift
+ * JIS, Latin-1 — that trip is LOSSY: every byte the decoder cannot read
+ * becomes U+FFFD, and writing the result replaces every non-ASCII byte in the
+ * file, including the lines nobody edited. Such a file carries no NUL byte,
+ * so the binary sniff above waves it through; only decoding it says so.
+ *
+ * `fatal` makes the decoder throw on the first invalid sequence rather than
+ * substituting, which is the whole question asked in one call and without
+ * allocating the string twice to compare it.
+ *
+ * @param bytes - the file's contents.
+ */
+export function decodesAsUtf8(bytes: Buffer): boolean {
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    return true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Clip a diff to a character cap, and SAY so when the clip happened — a
  * silently shortened diff reads as a complete one (TESTS.md H1).