@young1lin/dsh-ui-gitworkbench 0.1.2 → 0.1.4

package/src/client/log-filter-query.ts

@@ -0,0 +1,189 @@
+/**
+ * The query-box grammar for the history filter, and its chip model.
+ *
+ * The box and the funnel popup are two views of ONE LogFilter: typing
+ * `user:lia after:2 weeks ago` and ticking authors in the popup produce the
+ * same object, rendered back into the box by {@link serializeLogQuery} and
+ * into removable chips by {@link chipsFromFilter}. Everything is pure so the
+ * grammar round-trips under test: parse(serialize(f)) === f.
+ *
+ * Grammar (prefixes case-insensitive, IDEA-style):
+ *   bare words      → the text criterion (commit-message match)
+ *   user:<name>     → author; repeatable, multiple OR
+ *   path:<spec>     → pathspec; repeatable, union
+ *   after:<date>    → approxidate lower bound, single (last wins)
+ *   before:<date>   → approxidate upper bound, single
+ *   "..."           → quoted span: exact value after a prefix, or exact text
+ *   unknown:prefix  → an ordinary word (lenient, like IDEA)
+ *
+ * Only DATE values auto-extend over following words ("after:2 weeks ago") —
+ * approxidate is naturally multi-word. user/path take their inline value;
+ * names with spaces come from the popup or quotes.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/log-filter-query
+ */
+
+import type { LogFilter } from '../log-filter.ts'
+
+/** The filter that filters nothing. */
+export function emptyQueryFilter(): LogFilter {
+  return { users: [], text: '', textRegex: false, paths: [], after: '', before: '' }
+}
+
+/** Criterion kinds a chip can represent. */
+export type ChipKind = 'user' | 'path' | 'after' | 'before' | 'text'
+
+/** One removable criterion, as shown under the filter box. */
+export interface FilterChip {
+  readonly kind: ChipKind
+  readonly value: string
+}
+
+const PREFIXES: readonly ChipKind[] = ['user', 'path', 'after', 'before']
+const PREFIX_RE = /^(user|path|after|before):(.*)$/i
+
+interface Token {
+  readonly value: string
+  readonly quoted: boolean
+  readonly kind?: ChipKind
+}
+
+function tokenize(query: string): Token[] {
+  const tokens: Token[] = []
+  let i = 0
+  while (i < query.length) {
+    while (i < query.length && /\s/.test(query[i]!)) i += 1
+    if (i >= query.length) break
+    if (query[i] === '"') {
+      const end = query.indexOf('"', i + 1)
+      const value = end === -1 ? query.slice(i + 1) : query.slice(i + 1, end)
+      tokens.push({ value, quoted: true })
+      i = end === -1 ? query.length : end + 1
+      continue
+    }
+    // `prefix:"value with spaces"` — the quote opens INSIDE the word, right
+    // after the colon, so the word scanner below must not eat it as text.
+    const prefixQuote = /^(user|path|after|before):"/i.exec(query.slice(i))
+    if (prefixQuote !== null) {
+      const kind = prefixQuote[1]!.toLowerCase() as ChipKind
+      const open = i + prefixQuote[0].length
+      const end = query.indexOf('"', open)
+      const value = end === -1 ? query.slice(open) : query.slice(open, end)
+      tokens.push({ value, quoted: true, kind })
+      i = end === -1 ? query.length : end + 1
+      continue
+    }
+    const start = i
+    while (i < query.length && !/\s/.test(query[i]!)) i += 1
+    const word = query.slice(start, i)
+    const match = PREFIX_RE.exec(word)
+    tokens.push(match === null
+      ? { value: word, quoted: false }
+      : { value: match[2]!, quoted: false, kind: match[1]!.toLowerCase() as ChipKind })
+  }
+  return tokens
+}
+
+/**
+ * Parse the box's text into a filter.
+ * @param query - raw box contents.
+ */
+export function parseLogQuery(query: string): LogFilter {
+  const tokens = tokenize(query)
+  const users: string[] = []
+  const paths: string[] = []
+  let text = ''
+  let after = ''
+  let before = ''
+
+  const textWords: string[] = []
+  let i = 0
+  while (i < tokens.length) {
+    const token = tokens[i]!
+    if (token.kind === undefined) {
+      textWords.push(token.value)
+      i += 1
+      continue
+    }
+    if (token.kind === 'user' || token.kind === 'path') {
+      const list = token.kind === 'user' ? users : paths
+      if (token.value.length > 0 && !list.includes(token.value)) list.push(token.value)
+      i += 1
+      continue
+    }
+    // Date bounds: approxidate is naturally multi-word, so an unquoted value
+    // swallows the bare words that follow, stopping at the next prefix token
+    // or a quoted span. A QUOTED base value is exact — no extension.
+    const parts: string[] = [token.value]
+    let j = token.quoted ? i : i + 1
+    while (j < tokens.length && tokens[j]!.kind === undefined && !tokens[j]!.quoted && tokens[j]!.value.length > 0) {
+      parts.push(tokens[j]!.value)
+      j += 1
+    }
+    const value = parts.join(' ').trim()
+    if (token.kind === 'after') after = value
+    else before = value
+    i = token.quoted ? i + 1 : j
+  }
+  text = textWords.join(' ').trim()
+  return { users, text, textRegex: false, paths, after, before }
+}
+
+/** Quote a serialized value iff it would not reparse as itself. */
+function quote(value: string): string {
+  return /\s/.test(value) ? `"${value}"` : value
+}
+
+/**
+ * Render a filter back into the box's grammar. The text criterion goes last
+ * and is quoted when any of its words would parse as a prefix token.
+ * @param filter - the filter to render.
+ */
+export function serializeLogQuery(filter: LogFilter): string {
+  const parts: string[] = []
+  for (const user of filter.users) parts.push(`user:${quote(user)}`)
+  for (const path of filter.paths) parts.push(`path:${quote(path)}`)
+  if (filter.after.length > 0) parts.push(`after:${quote(filter.after)}`)
+  if (filter.before.length > 0) parts.push(`before:${quote(filter.before)}`)
+  if (filter.text.length > 0) {
+    const looksPrefixed = filter.text.split(/\s+/).some(word => PREFIX_RE.test(word))
+    parts.push(looksPrefixed ? `"${filter.text}"` : filter.text)
+  }
+  return parts.join(' ')
+}
+
+/**
+ * One chip per criterion, in grammar order: users, paths, bounds, text.
+ * @param filter - the filter to decompose.
+ */
+export function chipsFromFilter(filter: LogFilter): readonly FilterChip[] {
+  const chips: FilterChip[] = []
+  for (const user of filter.users) chips.push({ kind: 'user', value: user })
+  for (const path of filter.paths) chips.push({ kind: 'path', value: path })
+  if (filter.after.length > 0) chips.push({ kind: 'after', value: filter.after })
+  if (filter.before.length > 0) chips.push({ kind: 'before', value: filter.before })
+  if (filter.text.length > 0) chips.push({ kind: 'text', value: filter.text })
+  return chips
+}
+
+/**
+ * The filter minus one chip. Immutable; dropping the last criterion yields
+ * the empty filter.
+ * @param filter - current filter.
+ * @param kind - the chip's criterion kind.
+ * @param value - the chip's value (which user, which path).
+ */
+export function removeChip(filter: LogFilter, kind: ChipKind, value: string): LogFilter {
+  switch (kind) {
+    case 'user':
+      return { ...filter, users: filter.users.filter(user => user !== value) }
+    case 'path':
+      return { ...filter, paths: filter.paths.filter(path => path !== value) }
+    case 'after':
+      return { ...filter, after: '' }
+    case 'before':
+      return { ...filter, before: '' }
+    case 'text':
+      return { ...filter, text: '', textRegex: false }
+  }
+}

package/src/client/path-select.ts

@@ -0,0 +1,131 @@
+/**
+ * Checkbox-tree semantics for the path picker.
+ *
+ * Ticking a FOLDER means its whole subtree — so the selection is a set of
+ * pathspecs with an invariant: no member covers another. Ticking a folder
+ * absorbs the files already ticked inside it (the lone file's chip gives way
+ * to the folder's one); unticking one file under a checked folder cascades
+ * OUT — the folder is replaced by its other children, level by level. Rows
+ * then DERIVE their checkbox state (on / off / partial) from the set, which
+ * is why ticking a folder visibly checks everything under it.
+ *
+ * Pure throughout; the index is built from the same raw path list the host
+ * sent, so children order is the tree's alphabetical order.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/path-select
+ */
+
+/** Directory path → its direct children, full paths, files and dirs apart. */
+export interface PathIndex {
+  readonly dirs: ReadonlyMap<string, readonly string[]>
+  readonly files: ReadonlyMap<string, readonly string[]>
+}
+
+/**
+ * Index a raw path list for child lookup.
+ * @param paths - repo-relative file paths, exactly as `repoTree` returned.
+ */
+export function buildIndex(paths: readonly string[]): PathIndex {
+  const dirs = new Map<string, string[]>()
+  const files = new Map<string, string[]>()
+  const noteDir = (dir: string): void => {
+    if (!dirs.has(dir)) dirs.set(dir, [])
+  }
+  noteDir('')
+  for (const path of paths) {
+    if (path.length === 0) continue
+    const parts = path.split('/')
+    let dir = ''
+    for (let i = 0; i < parts.length - 1; i += 1) {
+      const childDir = dir === '' ? parts[i]! : `${dir}/${parts[i]!}`
+      noteDir(childDir)
+      const list = dirs.get(dir)!
+      if (!list.includes(childDir)) list.push(childDir)
+      dir = childDir
+    }
+    const list = files.get(dir) ?? []
+    list.push(path)
+    files.set(dir, list)
+  }
+  for (const list of dirs.values()) list.sort()
+  for (const list of files.values()) list.sort()
+  return { dirs, files }
+}
+
+/** Children of a directory, alphabetical by full path — the tree's order. */
+function childrenOf(index: PathIndex, dir: string): readonly string[] {
+  return [...(index.dirs.get(dir) ?? []), ...(index.files.get(dir) ?? [])].sort()
+}
+
+/**
+ * Is `p` selected — itself ticked, or inside a ticked directory?
+ * (Segment-boundary prefix: `src` does not cover `src2`.)
+ */
+export function isCovered(paths: readonly string[], p: string): boolean {
+  return paths.some(tick => tick === p || p.startsWith(`${tick}/`))
+}
+
+/**
+ * Tick a path. No-op when an ancestor already covers it; absorbs every
+ * descendant it covers, keeping the set minimal — one folder chip, never the
+ * pile of files under it.
+ */
+export function addPath(paths: readonly string[], p: string): readonly string[] {
+  if (isCovered(paths, p)) return paths
+  const kept = paths.filter(tick => !(tick === p || tick.startsWith(`${p}/`)))
+  return [...kept, p]
+}
+
+/**
+ * Untick a path. Removing an exact tick drops it; removing a file COVERED by
+ * a ticked folder replaces that folder with its other children, level by
+ * level down to the file — the standard cascade-out.
+ */
+export function removePath(paths: readonly string[], p: string, index: PathIndex): readonly string[] {
+  const out: string[] = []
+  for (const tick of paths) {
+    if (tick !== p && !p.startsWith(`${tick}/`)) {
+      out.push(tick)
+      continue
+    }
+    // This tick is p itself or an ancestor of it; replace it with the subtree
+    // minus p. Walk down the chain, adding each level's other children.
+    let dir = tick
+    while (dir !== p) {
+      // The child of `dir` on the way to p: the next path segment.
+      const rest = p.slice(dir.length + 1)
+      const nextName = dir === '' ? p.split('/')[0]! : rest.split('/')[0]!
+      const next = dir === '' ? nextName : `${dir}/${nextName}`
+      for (const child of childrenOf(index, dir)) {
+        if (child !== next) out.push(child)
+      }
+      dir = next
+    }
+  }
+  return out
+}
+
+/** Every file under a directory (empty for a file path). */
+function filesUnder(index: PathIndex, dir: string): readonly string[] {
+  const out: string[] = []
+  const stack = [dir]
+  while (stack.length > 0) {
+    const current = stack.pop()!
+    out.push(...(index.files.get(current) ?? []))
+    stack.push(...(index.dirs.get(current) ?? []))
+  }
+  return out
+}
+
+/**
+ * A row's checkbox state, derived: `on` when covered — by an ancestor tick OR
+ * by every file under it being covered individually; `partial` when a
+ * directory holds some but not all of its files; else `off`.
+ */
+export function checkedState(paths: readonly string[], p: string, index: PathIndex): 'on' | 'off' | 'partial' {
+  if (isCovered(paths, p)) return 'on'
+  const files = filesUnder(index, p)
+  if (files.length === 0) return 'off'
+  const covered = files.filter(file => isCovered(paths, file)).length
+  return covered === files.length ? 'on' : covered > 0 ? 'partial' : 'off'
+}

package/src/discard-ops.ts

@@ -0,0 +1,197 @@
+/**
+ * What "discard this file" resolves to, as a plan the host can carry out.
+ *
+ * This is the confirmation design `git-ops.ts` says a destructive button owes
+ * before it may exist. Three rules hold here, and each one closes a way this
+ * feature could quietly destroy the wrong thing:
+ *
+ *   - **The plan is derived from git's OWN report of the file, never from what
+ *     the client said it was.** A client that mislabels a tracked file as
+ *     untracked would otherwise turn a restore into a delete. `planFor` takes
+ *     a porcelain XY pair that the host read itself.
+ *   - **No plan may contain a destructive spelling.** Not `clean`, not
+ *     `reset --hard`, not `checkout -f`, no `--force`. `git restore` scoped to
+ *     one pathspec after `--` is the whole vocabulary; a stray `clean` would
+ *     take out every untracked file in the tree instead of the one named.
+ *     `tests/discard-ops.test.ts` scans every plan this module can produce.
+ *   - **A path that is deleted from disk is checked far harder than a
+ *     pathspec.** git refuses to leave the repository; `fs.rm` does not, so
+ *     `isSafeRelativePath` rejects absolutes, drive letters, UNC prefixes and
+ *     any `..` segment before a delete step can name a file.
+ *
+ * IDEA parity decides the semantics: Rollback there takes a file back to its
+ * committed state in one gesture and does not ask whether the change was
+ * staged, so neither does this. A file that was never committed goes away; a
+ * file that was deleted comes back.
+ *
+ * Pure throughout — no spawning, no fs. `src/index.ts` executes the steps.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/discard-ops
+ */
+
+import { isSafePathArg, parseStatusLine } from './git-ops.js'
+
+/** One thing the host does, in order. */
+export type DiscardStep =
+  /** Run git with this argv. */
+  | { readonly kind: 'git'; readonly argv: readonly string[] }
+  /** Remove this repo-relative path from disk. Tolerates an absent file. */
+  | { readonly kind: 'delete'; readonly path: string }
+
+/**
+ * What the reader is about to lose, which is what the confirmation must say.
+ * The client maps these to copy; keeping them as data means the wording can be
+ * bilingual without this module knowing about locales.
+ */
+export type DiscardEffect =
+  /** Tracked file returns to its committed content. Local edits are gone. */
+  | 'restore'
+  /** File leaves the disk. git never had it, so nothing can bring it back. */
+  | 'delete'
+  /** A deleted file comes back. Nothing is lost — no confirmation needed. */
+  | 'recover'
+  /** A rename is undone: the old path returns, the new one goes. */
+  | 'unrename'
+
+export interface DiscardPlan {
+  readonly steps: readonly DiscardStep[]
+  readonly effect: DiscardEffect
+  /**
+   * Whether carrying this out can lose work no git object holds. Drives
+   * whether the client confirms at all: recovering a deleted file is pure
+   * gain, and a dialog in front of it is noise that teaches people to click
+   * through dialogs.
+   */
+  readonly irreversible: boolean
+  /** The path the reader named, for the confirmation copy. */
+  readonly path: string
+  /** For `unrename`, the path the file is going back to. */
+  readonly previousPath?: string
+}
+
+/**
+ * Whether a path is safe to hand a filesystem delete.
+ *
+ * Stricter than {@link isSafePathArg}, which only has to keep git from reading
+ * a path as an option: git will not step outside the repository whatever it is
+ * given, so a pathspec needs no traversal check. A delete has no such backstop.
+ * Rejected: absolute paths (POSIX and Windows), UNC prefixes, drive letters,
+ * NUL bytes, and any `..` segment — including one buried mid-path, which is
+ * how traversal is usually spelled.
+ * @param path - repo-relative path from a plan step.
+ */
+export function isSafeRelativePath(path: string): boolean {
+  if (!isSafePathArg(path)) return false
+  if (path.includes('\0')) return false
+  // Windows accepts both separators, so normalise before splitting or
+  // `a\..\..\b` walks out through a check that only knew about `/`.
+  const unified = path.replace(/\\/g, '/')
+  if (unified.startsWith('/')) return false
+  if (/^[A-Za-z]:/.test(unified)) return false
+  if (unified.startsWith('//')) return false
+  return !unified.split('/').includes('..')
+}
+
+/** Take one file back to HEAD in both the index and the working tree. */
+function restoreBoth(path: string): DiscardStep {
+  return { kind: 'git', argv: ['restore', '--source=HEAD', '--staged', '--worktree', '--', path] }
+}
+
+/** Drop a file's index entry, leaving the working tree untouched. */
+function unstage(path: string): DiscardStep {
+  return { kind: 'git', argv: ['restore', '--staged', '--', path] }
+}
+
+/**
+ * The plan for one file, from git's own porcelain line.
+ *
+ * @param xy - the two porcelain status columns for this path, e.g. ` M`, `??`,
+ *             `R `. Read by the host from `git status --porcelain`, never
+ *             supplied by the client.
+ * @param path - repo-relative path, as git printed it.
+ * @param previousPath - for a rename, the path HEAD still knows the file by.
+ * @returns the ordered plan, or null when the file has nothing to discard.
+ * @throws if a path is not safe to pass on.
+ */
+export function planFor(xy: string, path: string, previousPath?: string): DiscardPlan | null {
+  if (!isSafePathArg(path)) throw new Error(`unsafe path argument: ${JSON.stringify(path)}`)
+  const index = xy[0] ?? ' '
+  const worktree = xy[1] ?? ' '
+
+  // Untracked and ignored: git has no copy, so the only way back is the
+  // filesystem's, and there is none.
+  if (xy === '??' || xy === '!!') {
+    if (!isSafeRelativePath(path)) throw new Error(`unsafe path to delete: ${JSON.stringify(path)}`)
+    return { steps: [{ kind: 'delete', path }], effect: 'delete', irreversible: true, path }
+  }
+
+  // A rename: HEAD holds `previousPath`, the index holds `path`. Bring the old
+  // one back first, then retire the new one — doing it the other way round
+  // would leave the tree with neither name for as long as the second step
+  // takes, which a reader watching a file tree would see.
+  if (index === 'R' || index === 'C') {
+    if (previousPath === undefined || !isSafePathArg(previousPath)) {
+      throw new Error(`rename without a usable previous path: ${JSON.stringify(path)}`)
+    }
+    if (!isSafeRelativePath(path)) throw new Error(`unsafe path to delete: ${JSON.stringify(path)}`)
+    return {
+      steps: [restoreBoth(previousPath), unstage(path), { kind: 'delete', path }],
+      effect: 'unrename',
+      irreversible: true,
+      path,
+      previousPath,
+    }
+  }
+
+  // Added to the index but absent from HEAD: rolling back means the file was
+  // never committed, so it leaves. Unstage first — otherwise the index would
+  // still carry an entry for a path that no longer exists on disk.
+  if (index === 'A') {
+    if (!isSafeRelativePath(path)) throw new Error(`unsafe path to delete: ${JSON.stringify(path)}`)
+    return {
+      steps: [unstage(path), { kind: 'delete', path }],
+      effect: 'delete',
+      irreversible: true,
+      path,
+    }
+  }
+
+  // Deleted, either side. HEAD still has the content, so this is recovery:
+  // nothing is lost and nothing needs confirming.
+  if (index === 'D' || worktree === 'D') {
+    return { steps: [restoreBoth(path)], effect: 'recover', irreversible: false, path }
+  }
+
+  // Everything else that git reported as changed — modified, type-changed,
+  // staged, unstaged, or both — goes back to HEAD wholesale. Content only the
+  // working tree ever held has no object behind it.
+  if (index !== ' ' || worktree !== ' ') {
+    return { steps: [restoreBoth(path)], effect: 'restore', irreversible: true, path }
+  }
+
+  // Clean: git reported the path with nothing to say about it.
+  return null
+}
+
+/**
+ * Find the file in a status report and plan for it.
+ *
+ * The report is the WHOLE tree's, not one narrowed by a pathspec: git detects
+ * a rename by pairing a deletion with an addition, and a pathspec that admits
+ * only one of the pair turns `R old -> new` into an unrelated `D` and `??`.
+ * The plan for those two is delete-and-lose where the truth is un-rename.
+ *
+ * @param stdout - `git status --porcelain=v1` over the whole worktree.
+ * @param path - the file the reader asked about, as the drawer lists it.
+ * @returns the plan, or null when git does not report that path as changed —
+ *          which is also what a stale tree looks like, and is not an error.
+ */
+export function planFromStatus(stdout: string, path: string): DiscardPlan | null {
+  if (!isSafePathArg(path)) throw new Error(`unsafe path argument: ${JSON.stringify(path)}`)
+  for (const line of stdout.split('\n')) {
+    const parsed = parseStatusLine(line)
+    if (parsed === null || parsed.path !== path) continue
+    return planFor(parsed.xy, parsed.path, parsed.renamed ? parsed.previousPath : undefined)
+  }
+  return null
+}

package/src/git-log.ts

@@ -14,6 +14,20 @@ export interface GitCommit {
   readonly subject: string
   readonly when: string
   readonly body: string
+  /**
+   * Author name (`%an`) — who wrote the change. The history filter matches it.
+   */
+  readonly authorName: string
+  /**
+   * Committer name (`%cn`) — who applied it. Equals the author in most repos;
+   * differs on rebases, cherry-picks and patches applied by a maintainer.
+   */
+  readonly committerName: string
+  /**
+   * Committer date as strict ISO 8601 (`%cI`) — the exact moment, same clock
+   * `when` summarizes. Rendered client-side in the viewer's own timezone.
+   */
+  readonly dateIso: string
   /**
    * Abbreviated parent hashes, in git's order — first parent first. This is the
    * DAG: the commit graph is drawn from nothing else. Empty for a root commit.
@@ -27,13 +41,14 @@ export interface GitCommit {
 }
 
 /**
- * Pretty format: RS, hash, when, subject, parents, refs, body.
+ * Pretty format: RS, hash, when, subject, parents, refs, author, committer,
+ * ISO date, body.
  *
  * `body` stays last because it is the only field that may contain newlines;
- * anything after it would have to survive them. Parents (`%p`) and refs (`%D`)
- * are single-line by construction.
+ * anything after it would have to survive them. Parents (`%p`), refs (`%D`),
+ * names (`%an`, `%cn`) and the ISO date (`%cI`) are single-line by construction.
  */
-export const LOG_FORMAT = '%x1e%h%x1f%cr%x1f%s%x1f%p%x1f%D%x1f%b'
+export const LOG_FORMAT = '%x1e%h%x1f%cr%x1f%s%x1f%p%x1f%D%x1f%an%x1f%cn%x1f%cI%x1f%b'
 
 /**
  * Split `%D` into plain ref names.
@@ -76,8 +91,11 @@ export function parseLog(stdout: string): GitCommit[] {
     const subject = (parts[2] ?? '').replace(/\n+$/g, '')
     const parents = (parts[3] ?? '').trim().split(/\s+/).filter(part => part.length > 0)
     const refs = parseRefs(parts[4] ?? '')
-    const body = (parts[5] ?? '').replace(/^\n+/, '').replace(/\n+$/g, '')
-    if (hash.length > 0) out.push({ hash, subject, when, body, parents, refs })
+    const authorName = parts[5] ?? ''
+    const committerName = parts[6] ?? ''
+    const dateIso = parts[7] ?? ''
+    const body = (parts[8] ?? '').replace(/^\n+/, '').replace(/\n+$/g, '')
+    if (hash.length > 0) out.push({ hash, subject, when, body, authorName, committerName, dateIso, parents, refs })
   }
   return out
 }

package/src/git-ops.ts

@@ -13,8 +13,12 @@
  *     of that. A file may legitimately be named `-f`, and passed positionally
  *     it becomes an option instead of a path.
  *   - Nothing here builds a destructive command. There is no `--force`, no
- *     `reset --hard`, no `clean`. Losing committed work needs a confirmation
- *     design of its own, not a button that happens to be adjacent to Push.
+ *     `reset --hard`, no `clean`. The one action that does lose work — rolling
+ *     one file back — lives in `discard-ops.ts` instead, behind the
+ *     confirmation design this rule demanded: git's own reading of the file
+ *     rather than the client's claim, `git restore` scoped to a single
+ *     pathspec as the whole vocabulary, and a dialog that names the
+ *     consequence. It is deliberately not a button adjacent to Push.
  *
  * @module
  */
@@ -341,16 +345,44 @@ export function parseNumstat(stdout: string): Map<string, NumstatEntry> {
   return out
 }
 
+/** One porcelain line, split into the parts a caller can act on. */
+export interface StatusLine {
+  /** The two status columns, e.g. ` M`, `??`, `R `. */
+  readonly xy: string
+  /** The path git reports the file under NOW — the rename target, if renamed. */
+  readonly path: string
+  /** For a rename, the path HEAD still knows the file by; '' otherwise. */
+  readonly previousPath: string
+  readonly renamed: boolean
+}
+
+/**
+ * Split one `git status --porcelain=v1` line.
+ *
+ * Exported because more than the file list needs it: `discard-ops` plans from
+ * the RAW XY pair, which {@link parseStatus} folds away into a
+ * {@link GitFileStatus}. Sharing this keeps the quoting and `old -> new`
+ * handling in one place — a second implementation of it is how a path with a
+ * non-ASCII name ends up being acted on unescaped.
+ * @param line - one output line, branch header and blanks included.
+ * @returns the split, or null for a line that names no file.
+ */
+export function parseStatusLine(line: string): StatusLine | null {
+  if (line.length === 0 || line.startsWith('##')) return null
+  if (line.length < 3) return null
+  const { path, previousPath, renamed } = parsePath(line.slice(3))
+  if (path.length === 0) return null
+  return { xy: line.slice(0, 2), path, previousPath, renamed }
+}
+
 /** Parse porcelain lines into a MUTABLE file list — untracked entries get their
  * counts filled in by the synthesis pass afterwards. */
 export function parseStatus(stdout: string, numstat: Map<string, NumstatEntry>): MutableGitFile[] {
   const files: MutableGitFile[] = []
   for (const line of stdout.split('\n')) {
-    if (line.length === 0 || line.startsWith('##')) continue
-    if (line.length < 3) continue
-    const xy = line.slice(0, 2)
-    const { path, previousPath, renamed } = parsePath(line.slice(3))
-    if (path.length === 0) continue
+    const parsed = parseStatusLine(line)
+    if (parsed === null) continue
+    const { xy, path, previousPath, renamed } = parsed
     const counts = numstat.get(path) ?? { added: 0, deleted: 0, binary: false }
     const { staged, unstaged } = stageStateOf(xy)
     const base: MutableGitFile = {