M4.4: Git gutter change markers and status colours in tree and tabs

- git.lineChanges {id} -> {ranges: [{kind, startLine, endLine}], version}:
  the buffer against its index blob, line diff with similar (Myers +
  Replace, no Compact) off the lock, CRLF-safe; index texts cached per
  path and dropped on gitChanged (State::emit -> git_lines::observe)
- editor gutter markers for added, modified and deleted lines, queried
  150 ms after edits, on show and on gitChanged, mapped through edits
- vcsStatus store (git.status on projectOpened and gitChanged, no
  polling) colouring file names in the project tree and editor tabs with
  the --lt-vcs-* tokens; contrast also checked on the active tab
- tests: unit and property tests, real-repo engine tests, Vitest
- docs: architecture, parity, gaps, roadmap, ui-parity, ROADMAP

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 17:36:59 +01:00
parent 56dadc91dc
commit fc8ae6c2e3
24 changed files with 1970 additions and 20 deletions

244
ui/src/stores/vcsStatus.ts Normal file
View file

@ -0,0 +1,244 @@
/**
* Git status of the project's files for colouring file names in the
* project tree and the editor tabs (M4.4).
*
* - **Source:** `git.status` (a pending outcome, so through `runWaiting`)
* on start, when a project opens and on every `gitChanged`; never
* polled. One query runs at a time; requests made while it runs share
* one more query after it.
* - **Colour:** {@link statusColour} folds a file's index and work tree
* states into one of the `--lt-vcs-*` tokens. Ignored files are not in
* `git.status`; the tree colours its ignored entries itself while a
* repository is open.
* - **Gutters:** every `gitChanged` also asks the editors' change markers
* to refresh (`refreshGitGutters`), since the index may have changed.
*
* Results are untrusted: malformed files are skipped, a failed query
* keeps the last state and shows nothing (the Changes window reports git
* problems).
*/
import { defineStore } from "pinia";
import { shallowRef } from "vue";
import { onEngineEvent, runWaiting, type EngineEventPayload } from "../ipc";
import { refreshGitGutters } from "../components/editor/gitGutter";
/** A file state as `git.status` names it. */
export type GitFileState =
| "unmodified"
| "modified"
| "added"
| "deleted"
| "renamed"
| "copied"
| "untracked"
| "ignored"
| "conflicted";
/** The status token names (`--lt-vcs-<name>`). */
export type VcsColour = "added" | "modified" | "deleted" | "untracked" | "ignored" | "conflicted";
/** Every state `git.status` may report. */
const STATES = new Set<string>([
"unmodified",
"modified",
"added",
"deleted",
"renamed",
"copied",
"untracked",
"ignored",
"conflicted",
]);
/** Whether a value is a file state. */
function isState(value: unknown): value is GitFileState {
return typeof value === "string" && STATES.has(value);
}
/**
* The colour of a file from its two states: conflicts first, then
* untracked, ignored, added, deleted, and any other change as modified.
*
* @param index - the staged side.
* @param worktree - the work tree side.
* @returns the token name, or null for an unchanged file.
*/
export function statusColour(index: GitFileState, worktree: GitFileState): VcsColour | null {
const sides = [index, worktree];
if (sides.includes("conflicted")) {
return "conflicted";
}
if (sides.includes("untracked")) {
return "untracked";
}
if (sides.includes("ignored")) {
return "ignored";
}
if (index === "added") {
return worktree === "deleted" ? null : "added";
}
if (sides.includes("deleted")) {
return "deleted";
}
if (sides.some((side) => side !== "unmodified")) {
return "modified";
}
return null;
}
/**
* Reads the colours of a `git.status` result.
*
* @param value - the untrusted result.
* @returns colour by project-relative path, and whether a repository is
* open; null when the result is not an object.
*/
export function readStatus(value: unknown): { colours: Map<string, VcsColour>; repo: boolean } | null {
if (typeof value !== "object" || value === null || Array.isArray(value)) {
return null;
}
const record = value as Record<string, unknown>;
const colours = new Map<string, VcsColour>();
const files = Array.isArray(record.files) ? (record.files as unknown[]) : [];
for (const file of files) {
if (typeof file !== "object" || file === null) {
continue;
}
const { path, index, worktree } = file as Record<string, unknown>;
if (typeof path !== "string" || !isState(index) || !isState(worktree)) {
continue;
}
const colour = statusColour(index, worktree);
if (colour !== null) {
colours.set(path, colour);
}
}
const repo = record.available === true && typeof record.repo === "object" && record.repo !== null;
return { colours, repo };
}
/** How the store reaches the engine; replaced in tests. */
export interface VcsStatusTransport {
/** Runs `git.status`. */
status(): Promise<{ ok: true; value: unknown } | { ok: false }>;
}
/** The transport through the engine IPC. */
const engineTransport: VcsStatusTransport = {
status: () => runWaiting<unknown>("git.status", {}),
};
export const useVcsStatusStore = defineStore("vcsStatus", () => {
/** Colour by project-relative path, for changed files only. */
const colours = shallowRef<ReadonlyMap<string, VcsColour>>(new Map());
/** Whether the project is inside a repository with a usable git. */
const repo = shallowRef(false);
let transport: VcsStatusTransport = engineTransport;
let running: Promise<void> | null = null;
const queued = { again: false };
let generation = 0;
let unsubscribe: (() => void) | null = null;
/**
* Replaces the transport (tests).
*
* @param next - the transport.
*/
function configure(next: VcsStatusTransport): void {
transport = next;
}
/** Runs `git.status` once and applies it unless the project changed. */
async function query(): Promise<void> {
const asked = generation;
const result = await transport.status();
if (!result.ok || asked !== generation) {
return;
}
const read = readStatus(result.value);
if (read !== null) {
colours.value = read.colours;
repo.value = read.repo;
}
}
/** Whether a refresh was asked for while the last query ran. */
function wantsAgain(): boolean {
return queued.again;
}
/**
* Refreshes the status: starts a query, or, while one runs, makes sure
* one more runs after it.
*
* @returns resolves when the status is current.
*/
function refresh(): Promise<void> {
if (running !== null) {
queued.again = true;
return running;
}
running = (async () => {
do {
queued.again = false;
await query();
} while (wantsAgain());
running = null;
})();
return running;
}
/** Forgets everything (project closed). */
function clear(): void {
generation += 1;
colours.value = new Map();
repo.value = false;
}
/**
* The colour of a file name.
*
* @param path - project-relative path with `/`.
* @returns the token name, or null when unchanged or unknown.
*/
function colourOf(path: string): VcsColour | null {
return colours.value.get(path) ?? null;
}
/** Handles one engine event. */
function handle(event: EngineEventPayload): void {
switch (event.kind) {
case "projectOpened":
clear();
void refresh();
break;
case "projectClosed":
clear();
break;
case "gitChanged":
void refresh();
refreshGitGutters();
break;
default:
break;
}
}
/** Starts following the engine and queries once; repeated calls do nothing. */
function start(): void {
if (unsubscribe !== null) {
return;
}
unsubscribe = onEngineEvent(handle);
void refresh();
}
/** Stops following the engine. */
function stop(): void {
unsubscribe?.();
unsubscribe = null;
}
return { colours, repo, configure, refresh, clear, colourOf, handle, start, stop };
});