staysfixed 0.1.0

package/src/marker/mark.js

@@ -0,0 +1,260 @@
+/**
+ * Known-good markers.
+ *
+ * A marker is a small, boring JSON file that says "on this day, at this commit,
+ * every screen looked like this and every guard held". It stores fingerprints,
+ * never copies of pictures, so pinning a release costs a couple of kilobytes.
+ *
+ * Markers are what turn "it broke sometime last week" into "it broke between
+ * v0.14.0 and v0.15.0, here are the nine commits". That only works if they are
+ * honest, so writing over one is refused unless a human insists.
+ */
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { safeName } from '../core/paths.js';
+import { gitInfo } from '../core/git.js';
+import { approvedHashes } from '../picture/store.js';
+import { platformTag } from '../drive/find.js';
+import { StaysFixedError } from '../core/errors.js';
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * Pin the way things look right now.
+ *
+ * @param {import('../types.js').Project} project
+ * @param {string} label  'v0.15.0', 'before-the-store-work' — anything a person will recognise later.
+ * @param {{
+ *   note?: string,
+ *   force?: boolean,
+ *   at?: string,
+ *   guards?: Record<string, import('../types.js').CheckStatus>,
+ *   pictures?: Record<string, string>,
+ *   run?: import('../types.js').RunSummary,
+ *   tool?: string,
+ * }} [opts]
+ * @returns {Promise<import('../types.js').Marker>}
+ */
+export async function writeMarker(project, label, opts = {}) {
+  const clean = String(label ?? '').trim();
+  if (!clean) {
+    throw new StaysFixedError('A marker needs a name.', {
+      hint: 'Something you will recognise in three months: `staysfixed mark v0.15.0`.',
+    });
+  }
+
+  const file = markerFile(project, clean);
+  if (!opts.force && (await exists(file))) {
+    throw new StaysFixedError(`There is already a marker called "${clean}".`, {
+      hint: 'Markers are history, and history should not be quietly rewritten. Use a new name, or pass --force if this one really was wrong.',
+    });
+  }
+
+  const pictures = opts.pictures ?? (await approvedHashes(project.paths));
+
+  /** @type {import('../types.js').Marker} */
+  const marker = {
+    label: clean,
+    at: opts.at ?? new Date().toISOString(),
+    git: await gitInfo(project.paths.root),
+    pictures,
+    guards: guardsFor(opts),
+    tool: opts.tool ?? (await toolVersion()),
+    platform: platformTag(),
+  };
+  if (opts.note) marker.note = opts.note;
+
+  await fsp.mkdir(project.paths.markers, { recursive: true });
+  await fsp.writeFile(file, JSON.stringify(marker, null, 2) + '\n');
+  return marker;
+}
+
+/**
+ * Where the guard column of a marker comes from.
+ *
+ * An explicit map wins. Otherwise we take the real statuses out of the run being
+ * pinned — recording a guard as passing when it did not would make the marker a
+ * lie, and a lying marker is worse than no marker.
+ *
+ * @param {{guards?: Record<string, import('../types.js').CheckStatus>, run?: import('../types.js').RunSummary}} opts
+ * @returns {Record<string, import('../types.js').CheckStatus>}
+ */
+function guardsFor(opts) {
+  if (opts.guards) return { ...opts.guards };
+  /** @type {Record<string, import('../types.js').CheckStatus>} */
+  const out = {};
+  for (const g of opts.run?.guards ?? []) out[g.name] = g.status ?? 'passed';
+  return out;
+}
+
+/**
+ * Every marker, newest first.
+ * @param {import('../types.js').Project} project
+ * @returns {Promise<import('../types.js').Marker[]>}
+ */
+export async function listMarkers(project) {
+  /** @type {string[]} */
+  let names;
+  try {
+    names = await fsp.readdir(project.paths.markers);
+  } catch {
+    return [];
+  }
+
+  /** @type {import('../types.js').Marker[]} */
+  const markers = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith('.json')) continue;
+    const marker = await readMarkerFile(path.join(project.paths.markers, name));
+    if (marker) markers.push(marker);
+  }
+  // Newest first. Ties keep a stable order, so two markers written in the same
+  // second never swap places between runs.
+  return markers.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0));
+}
+
+/**
+ * @param {import('../types.js').Project} project
+ * @param {string} label
+ * @returns {Promise<import('../types.js').Marker|null>}
+ */
+export async function readMarker(project, label) {
+  const direct = await readMarkerFile(markerFile(project, label));
+  if (direct) return direct;
+  // The file name is a tidied-up version of the label, so a person typing the
+  // original label with spaces or slashes in it should still find their marker.
+  const all = await listMarkers(project);
+  return all.find((m) => m.label === label) ?? null;
+}
+
+/**
+ * @param {import('../types.js').Project} project
+ * @param {string} label
+ * @returns {Promise<boolean>} true when a marker was actually removed
+ */
+export async function deleteMarker(project, label) {
+  const file = markerFile(project, label);
+  if (await exists(file)) {
+    await fsp.rm(file, { force: true });
+    return true;
+  }
+  const found = (await listMarkers(project)).find((m) => m.label === label);
+  if (!found) return false;
+  const other = markerFile(project, found.label);
+  if (await exists(other)) {
+    await fsp.rm(other, { force: true });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * One line a person can read at a glance:
+ * "v0.15.0 — 12 pictures, 8 guards, at 3f9a1c2 on main, 28 Aug 2026"
+ *
+ * @param {import('../types.js').Marker} marker
+ * @returns {string}
+ */
+export function describeMarker(marker) {
+  const pictures = Object.keys(marker.pictures ?? {}).length;
+  const guards = Object.keys(marker.guards ?? {}).length;
+
+  const parts = [
+    `${pictures} ${pictures === 1 ? 'picture' : 'pictures'}`,
+    `${guards} ${guards === 1 ? 'guard' : 'guards'}`,
+  ];
+  if (marker.git?.shortSha) {
+    parts.push(marker.git.branch ? `at ${marker.git.shortSha} on ${marker.git.branch}` : `at ${marker.git.shortSha}`);
+  }
+  const day = readableDay(marker.at);
+  if (day) parts.push(day);
+
+  return `${marker.label} — ${parts.join(', ')}`;
+}
+
+/**
+ * @param {import('../types.js').Project} project
+ * @param {string} label
+ * @returns {string}
+ */
+function markerFile(project, label) {
+  return path.join(project.paths.markers, `${safeName(label)}.json`);
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<import('../types.js').Marker|null>}
+ */
+async function readMarkerFile(file) {
+  let raw;
+  try {
+    raw = await fsp.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.label !== 'string') return null;
+    // Older or hand-edited markers may be missing pieces; fill them in rather
+    // than throwing, because a half-readable marker still narrows a search.
+    return {
+      label: parsed.label,
+      at: typeof parsed.at === 'string' ? parsed.at : '',
+      note: typeof parsed.note === 'string' ? parsed.note : undefined,
+      git: parsed.git ?? { sha: null, shortSha: null, branch: null, dirty: false, user: null },
+      pictures: parsed.pictures ?? {},
+      guards: parsed.guards ?? {},
+      tool: typeof parsed.tool === 'string' ? parsed.tool : 'unknown',
+      platform: typeof parsed.platform === 'string' ? parsed.platform : 'unknown',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * '2026-08-28T21:03:00.000Z' -> '28 Aug 2026'. Read in UTC so the same marker
+ * reads the same on every machine that opens it.
+ * @param {string} iso
+ * @returns {string|null}
+ */
+function readableDay(iso) {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return null;
+  const d = new Date(t);
+  return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<boolean>}
+ */
+async function exists(file) {
+  try {
+    await fsp.stat(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @type {string|null} */
+let cachedVersion = null;
+
+/**
+ * Which build of the tool wrote this marker. Read off package.json rather than
+ * hard-coded, so it can never drift from the version that actually shipped.
+ * @returns {Promise<string>}
+ */
+async function toolVersion() {
+  if (cachedVersion !== null) return cachedVersion;
+  try {
+    const raw = await fsp.readFile(new URL('../../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    cachedVersion = typeof parsed.version === 'string' ? `staysfixed ${parsed.version}` : 'staysfixed';
+  } catch {
+    cachedVersion = 'staysfixed';
+  }
+  return cachedVersion;
+}

package/src/marker/trace.js

@@ -0,0 +1,293 @@
+/**
+ * "Which change broke this?"
+ *
+ * Markers hold a fingerprint of every screen at moments a human trusted. So when
+ * a screen looks wrong today, we can walk backwards through the markers to find
+ * the newest one where it still looked the way it does now, and the very next one
+ * where it did not. The commits between those two are the suspects — usually a
+ * handful, instead of a week of work.
+ *
+ * The honest answer is often "I cannot tell", and this file says so out loud
+ * rather than guessing. A trace that points at the wrong commit costs more time
+ * than no trace at all.
+ */
+
+import { listMarkers } from './mark.js';
+import { approvedHashes } from '../picture/store.js';
+import { commitsBetween, filesBetween, commitExists } from '../core/git.js';
+
+/** More than this many commits is a wall of text, not an answer. */
+const COMMIT_CAP = 40;
+
+/**
+ * @param {import('../types.js').Project} project
+ * @param {{names?: string[], current?: Record<string,string>}} [opts]
+ *   `current` defaults to the fingerprints of today's approved pictures. When
+ *   tracing a live failure the CLI passes the fingerprints of the pictures the
+ *   failing run actually took, so the trace follows the broken thing, not the
+ *   thing that was approved.
+ * @returns {Promise<import('../types.js').TraceReport>}
+ */
+export async function traceScreens(project, opts = {}) {
+  const markers = await listMarkers(project);
+  const current = opts.current ?? (await approvedHashes(project.paths));
+  const names =
+    opts.names && opts.names.length > 0 ? [...opts.names] : Object.keys(current).sort();
+
+  /** @type {import('../types.js').TraceFinding[]} */
+  const findings = [];
+  for (const name of names) {
+    findings.push(await traceOne(project, markers, name, current[name]));
+  }
+
+  /** @type {import('../types.js').TraceReport} */
+  const report = { findings, markersSearched: markers.length };
+  if (markers.length === 0) {
+    report.message =
+      'There are no known-good markers in this project yet, so there is no history to search. Mark a release you trust with `staysfixed mark v1.2.3` and the next trace will have something to work with.';
+  } else if (names.length === 0) {
+    report.message = 'There are no approved pictures to trace.';
+  }
+  return report;
+}
+
+/**
+ * @param {import('../types.js').Project} project
+ * @param {import('../types.js').Marker[]} markers  newest first
+ * @param {string} name
+ * @param {string|undefined} now  fingerprint of how the screen looks right now
+ * @returns {Promise<import('../types.js').TraceFinding>}
+ */
+async function traceOne(project, markers, name, now) {
+  const who = readable(name);
+
+  if (now === undefined) {
+    return {
+      name,
+      verdict: 'unknown',
+      message: `There is no picture of ${who} to compare against — nothing has been approved for it yet.`,
+    };
+  }
+  if (markers.length === 0) {
+    return {
+      name,
+      verdict: 'unknown',
+      message: `There are no known-good markers yet, so there is nothing to compare ${who} against.`,
+    };
+  }
+
+  const lastGoodIndex = markers.findIndex((m) => m.pictures?.[name] === now);
+  if (lastGoodIndex === -1) {
+    const oldest = markers[markers.length - 1];
+    return {
+      name,
+      verdict: 'unknown',
+      message: `None of the ${markers.length} markers show ${who} looking the way it does now. Either it is brand new, or it changed before the oldest marker (${oldest.label}).`,
+    };
+  }
+
+  const lastGood = markers[lastGoodIndex];
+  if (lastGoodIndex === 0) {
+    return {
+      name,
+      verdict: 'unchanged',
+      lastGood,
+      message: `${capitalise(who)} looks exactly as it did at ${lastGood.label}, the newest marker.`,
+    };
+  }
+
+  // The boundary is the first marker written AFTER lastGood that actually
+  // recorded this screen and recorded it differently. Markers that never saw
+  // this screen are skipped rather than blamed.
+  let firstBad;
+  for (let j = lastGoodIndex - 1; j >= 0; j--) {
+    const seen = markers[j].pictures?.[name];
+    if (seen !== undefined && seen !== now) {
+      firstBad = markers[j];
+      break;
+    }
+  }
+  if (!firstBad) {
+    return {
+      name,
+      verdict: 'unknown',
+      lastGood,
+      message: `${capitalise(who)} last matched at ${lastGood.label}, and no marker written after that one recorded this screen at all.`,
+    };
+  }
+
+  const from = lastGood.git?.sha;
+  const to = firstBad.git?.sha;
+  if (!from || !to) {
+    const which = !from ? lastGood.label : firstBad.label;
+    return {
+      name,
+      verdict: 'unknown',
+      lastGood,
+      firstBad,
+      message: `${capitalise(who)} changed between ${lastGood.label} and ${firstBad.label}, but ${which} was not marked inside a git repository, so there is no list of commits to show.`,
+    };
+  }
+
+  const root = project.paths.root;
+  const missing = [];
+  if (!(await commitExists(root, from))) missing.push(`${lastGood.label} (${short(from)})`);
+  if (!(await commitExists(root, to))) missing.push(`${firstBad.label} (${short(to)})`);
+  if (missing.length > 0) {
+    return {
+      name,
+      verdict: 'unknown',
+      lastGood,
+      firstBad,
+      message: `${capitalise(who)} changed between ${lastGood.label} and ${firstBad.label}, but git here cannot find ${missing.join(' or ')}. That usually means the branch was rebuilt or this is a shallow clone.`,
+    };
+  }
+
+  const allCommits = await commitsBetween(root, from, to);
+  const files = await filesBetween(root, from, to);
+  const commits = allCommits.slice(0, COMMIT_CAP);
+
+  let message = `${capitalise(who)} looked right at ${lastGood.label} and wrong by ${firstBad.label}. ${countOf(allCommits.length, 'commit')} landed in between`;
+  message += files.length > 0 ? `, touching ${countOf(files.length, 'file')}.` : '.';
+  if (allCommits.length > commits.length) {
+    // A silent cap reads as "that's all of them", which would send someone
+    // looking in the wrong half of the range.
+    message += ` Only the newest ${COMMIT_CAP} commits are listed here.`;
+  }
+
+  return { name, verdict: 'changed', lastGood, firstBad, commits, files, message };
+}
+
+/**
+ * One plain sentence about a single finding.
+ *
+ * @param {import('../types.js').TraceFinding} finding
+ * @returns {string}
+ */
+export function summariseTrace(finding) {
+  const who = readable(finding.name);
+
+  if (finding.verdict === 'unchanged') {
+    return finding.lastGood
+      ? `${who} still looks the way it did at ${finding.lastGood.label}.`
+      : `${who} has not changed.`;
+  }
+
+  if (finding.verdict === 'changed' && finding.lastGood && finding.firstBad) {
+    const commits = finding.commits ?? [];
+    let line = `${who} looked right at ${finding.lastGood.label} and wrong by ${finding.firstBad.label} — ${countOf(commits.length, 'commit')} in between`;
+    const hot = busiestFolder(finding.files ?? []);
+    if (hot) {
+      line += hot.all
+        ? `, and all ${hot.count} changed files are under ${hot.dir}.`
+        : `, and ${hot.count} of the changed files are under ${hot.dir}.`;
+    } else {
+      line += '.';
+    }
+    return line;
+  }
+
+  return finding.message ?? `There is not enough history to say when ${who} changed.`;
+}
+
+/**
+ * The folder the changed files sit in — the quickest hint about where to look
+ * first. Counting is inclusive of sub-folders, so the sentence it feeds is
+ * literally true: saying "5 of the files are under src" while nine of them are
+ * would send someone looking in the wrong place.
+ *
+ * @param {string[]} files
+ * @returns {{dir: string, count: number, all: boolean}|null}
+ */
+function busiestFolder(files) {
+  if (files.length < 2) return null;
+
+  const shared = sharedFolder(files);
+  if (shared) return { dir: shared, count: files.length, all: true };
+
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  for (const file of files) {
+    const parts = file.split('/');
+    for (let depth = 1; depth <= Math.min(2, parts.length - 1); depth++) {
+      const dir = parts.slice(0, depth).join('/');
+      counts.set(dir, (counts.get(dir) ?? 0) + 1);
+    }
+  }
+
+  /** @type {{dir: string, count: number, all: boolean}|null} */
+  let best = null;
+  for (const [dir, count] of counts) {
+    // A deeper folder wins a tie: 'src/renderer' is an answer, 'src' is a shrug.
+    const better = !best || count > best.count || (count === best.count && dir.length > best.dir.length);
+    if (better) best = { dir, count, all: false };
+  }
+  return best && best.count >= 2 ? best : null;
+}
+
+/**
+ * The deepest folder that contains every one of these files, or null when they
+ * are scattered across the repository.
+ * @param {string[]} files
+ * @returns {string|null}
+ */
+function sharedFolder(files) {
+  /** @type {string[]|null} */
+  let common = null;
+  for (const file of files) {
+    const parts = file.split('/').slice(0, -1);
+    if (common === null) {
+      common = parts;
+      continue;
+    }
+    let i = 0;
+    while (i < common.length && i < parts.length && common[i] === parts[i]) i++;
+    common = common.slice(0, i);
+    if (common.length === 0) return null;
+  }
+  return common && common.length > 0 ? common.join('/') : null;
+}
+
+/**
+ * @param {number} n
+ * @param {string} one
+ * @param {string} [many]
+ * @returns {string}
+ */
+function countOf(n, one, many) {
+  if (n === 0) return `no ${many ?? one + 's'}`;
+  return `${n} ${n === 1 ? one : many ?? one + 's'}`;
+}
+
+/**
+ * 'sessions-list' -> 'the sessions list'. Screen names are file-safe ids; people
+ * are not, so nothing a person reads should be an id.
+ * @param {string} name
+ * @returns {string}
+ */
+function readable(name) {
+  const words = String(name ?? '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_.]+/g, ' ')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, ' ');
+  if (!words) return 'this screen';
+  return /^(the|a|an) /.test(words) ? words : `the ${words}`;
+}
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function capitalise(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * @param {string} sha
+ * @returns {string}
+ */
+function short(sha) {
+  return sha.slice(0, 7);
+}