staysfixed 0.1.0

package/src/core/history.js

@@ -0,0 +1,173 @@
+/**
+ * The flake register.
+ *
+ * Asad's rule, and it is the right one: a check that flakes twice gets fixed or
+ * deleted, never tolerated. So the tool has to remember. Every run appends a
+ * status per check; when a check changes its mind while the code stood still,
+ * that is a flake. Past the limit the check is condemned and `check` says so in
+ * red until a human deals with it.
+ */
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+const KEEP_RECENT = 12;
+
+/**
+ * @param {string} file
+ * @returns {Promise<import('../types.js').History>}
+ */
+export async function loadHistory(file) {
+  try {
+    const raw = await fsp.readFile(file, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {string} file
+ * @param {import('../types.js').History} history
+ */
+export async function saveHistory(file, history) {
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  await fsp.writeFile(file, JSON.stringify(history, null, 2) + '\n');
+}
+
+/**
+ * Fold one run into the register.
+ *
+ * A flake is: this check passed and then failed (or the reverse) while the git
+ * sha and the working-tree state did not change. That is the only honest
+ * definition — anything else blames the developer for their own edits.
+ *
+ * @param {import('../types.js').History} history
+ * @param {{name: string, kind: 'picture'|'guard', status: import('../types.js').CheckStatus, retriedToPass?: boolean}[]} results
+ * @param {import('../types.js').GitInfo} git
+ * @param {string} at ISO timestamp
+ * @param {number} flakeLimit
+ * @returns {{history: import('../types.js').History, newlyCondemned: string[], flakedNow: string[]}}
+ */
+export function foldRun(history, results, git, at, flakeLimit) {
+  const next = /** @type {import('../types.js').History} */ (structuredClone(history));
+  const newlyCondemned = [];
+  const flakedNow = [];
+  // What "the code did not change" means.
+  //
+  // Only a clean tree at a known commit proves it. Without git there is no way to tell a
+  // wobble from an edit, and guessing costs more than it gives: treating consecutive runs
+  // in a repo-less folder as "the same state" made a deliberately broken stylesheet, and
+  // then its repair, register as two flakes on every screen in the project — the register
+  // shouting about eleven perfectly good checks. A false accusation of flakiness is
+  // exactly as corrosive as a false failure.
+  //
+  // So a run with no git evidence still records its status, and still catches the
+  // unambiguous signal (a check that needed a retry to pass INSIDE one run). It just does
+  // not compare across runs. `staysfixed flake` says so out loud rather than looking
+  // clean — see `blindWithoutGit`.
+  const stamp = git.dirty ? null : git.sha;
+
+  for (const r of results) {
+    const key = `${r.kind}:${r.name}`;
+    const entry = next[key] ?? {
+      name: r.name,
+      kind: r.kind,
+      runs: 0,
+      flakes: 0,
+      recent: [],
+    };
+
+    const previous = entry.recent.length ? entry.recent[entry.recent.length - 1] : null;
+    const previousSha = /** @type {any} */ (entry).lastSha ?? null;
+
+    // Two ways to catch a wobble:
+    //  1. it needed a retry to pass inside this very run — unambiguous;
+    //  2. it flipped between runs at the same commit, clean tree both times.
+    const flippedAtSameCommit =
+      previous !== null &&
+      previous !== r.status &&
+      stamp !== null &&
+      previousSha === stamp &&
+      isDecided(previous) &&
+      isDecided(r.status);
+
+    if (r.retriedToPass || flippedAtSameCommit) {
+      entry.flakes += 1;
+      entry.lastFlakeAt = at;
+      entry.lastFlakeGitSha = git.sha ?? undefined;
+      flakedNow.push(r.name);
+      if (entry.flakes >= flakeLimit && !entry.condemned) {
+        entry.condemned = true;
+        newlyCondemned.push(r.name);
+      }
+    }
+
+    entry.runs += 1;
+    entry.recent = [...entry.recent, r.status].slice(-KEEP_RECENT);
+    /** @type {any} */ (entry).lastSha = stamp;
+    next[key] = entry;
+  }
+
+  return { history: next, newlyCondemned, flakedNow };
+}
+
+/**
+ * A status that means the check actually reached a verdict.
+ * @param {import('../types.js').CheckStatus} s
+ */
+function isDecided(s) {
+  return s === 'passed' || s === 'changed' || s === 'failed';
+}
+
+/**
+ * @param {import('../types.js').History} history
+ * @returns {import('../types.js').HistoryEntry[]}
+ */
+export function condemned(history) {
+  return Object.values(history).filter((e) => e.condemned);
+}
+
+/**
+ * @param {import('../types.js').History} history
+ * @returns {import('../types.js').HistoryEntry[]}
+ */
+export function wobbly(history) {
+  return Object.values(history)
+    .filter((e) => e.flakes > 0)
+    .sort((a, b) => b.flakes - a.flakes);
+}
+
+/**
+ * Forgive a check — used by `staysfixed flake --clear <name>` once it has been fixed.
+ * @param {import('../types.js').History} history
+ * @param {string} name
+ * @returns {import('../types.js').History}
+ */
+export function clearFlakes(history, name) {
+  const next = /** @type {import('../types.js').History} */ (structuredClone(history));
+  for (const [key, entry] of Object.entries(next)) {
+    if (entry.name === name || key === name) {
+      entry.flakes = 0;
+      entry.condemned = false;
+      delete entry.lastFlakeAt;
+      delete entry.lastFlakeGitSha;
+    }
+  }
+  return next;
+}
+
+/**
+ * Whether the register can only see wobbles inside a single run.
+ *
+ * True when there is no commit to pin a status to — no git, or a dirty tree. The `flake`
+ * command prints this, because a register that looks empty for the wrong reason is worse
+ * than one that admits what it cannot see.
+ *
+ * @param {import('../types.js').GitInfo} git
+ * @returns {boolean}
+ */
+export function blindWithoutGit(git) {
+  return git.sha === null || git.dirty;
+}

package/src/core/log.js

@@ -0,0 +1,144 @@
+/**
+ * Terminal output. No dependencies, no spinners that break in CI, no jargon.
+ *
+ * Everything a human reads comes through here, so the voice stays the same
+ * whether it is printed by `check`, by `walk`, or quoted back by the MCP server.
+ */
+
+const noColor =
+  process.env.NO_COLOR !== undefined ||
+  process.env.STAYSFIXED_NO_COLOR !== undefined ||
+  process.env.TERM === 'dumb';
+
+const tty = Boolean(process.stdout.isTTY) && !noColor;
+
+/** @type {(code: string) => (s: string) => string} */
+const wrap = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const paint = {
+  bold: wrap('1'),
+  dim: wrap('2'),
+  red: wrap('31'),
+  green: wrap('32'),
+  yellow: wrap('33'),
+  blue: wrap('34'),
+  magenta: wrap('35'),
+  cyan: wrap('36'),
+  grey: wrap('90'),
+};
+
+/** Symbols that survive a plain terminal. */
+export const mark = {
+  pass: tty ? '✓' : 'ok',
+  fail: tty ? '✗' : 'X',
+  warn: tty ? '!' : '!',
+  info: tty ? '·' : '-',
+  arrow: tty ? '→' : '->',
+};
+
+let quiet = false;
+let verbose = false;
+
+/** @param {{quiet?: boolean, verbose?: boolean}} opts */
+export function setLogLevel(opts) {
+  if (opts.quiet !== undefined) quiet = opts.quiet;
+  if (opts.verbose !== undefined) verbose = opts.verbose;
+}
+
+export function isVerbose() {
+  return verbose;
+}
+
+/** @param {...unknown} args */
+export function say(...args) {
+  if (!quiet) process.stdout.write(args.map(String).join(' ') + '\n');
+}
+
+/** @param {...unknown} args */
+export function detail(...args) {
+  if (verbose && !quiet) process.stdout.write(paint.grey(args.map(String).join(' ')) + '\n');
+}
+
+/** @param {...unknown} args */
+export function warn(...args) {
+  process.stderr.write(paint.yellow(`${mark.warn} ` + args.map(String).join(' ')) + '\n');
+}
+
+/** @param {...unknown} args */
+export function fail(...args) {
+  process.stderr.write(paint.red(`${mark.fail} ` + args.map(String).join(' ')) + '\n');
+}
+
+/** @param {...unknown} args */
+export function ok(...args) {
+  if (!quiet) process.stdout.write(paint.green(`${mark.pass} `) + args.map(String).join(' ') + '\n');
+}
+
+export function blank() {
+  if (!quiet) process.stdout.write('\n');
+}
+
+/**
+ * A heading with a rule under it.
+ * @param {string} text
+ */
+export function heading(text) {
+  if (quiet) return;
+  process.stdout.write('\n' + paint.bold(text) + '\n');
+}
+
+/**
+ * Print rows as an aligned table. Values are strings already painted if needed.
+ * @param {string[][]} rows
+ * @param {{indent?: number}} [opts]
+ */
+export function table(rows, opts = {}) {
+  if (quiet || rows.length === 0) return;
+  const indent = ' '.repeat(opts.indent ?? 0);
+  const widths = /** @type {number[]} */ ([]);
+  for (const row of rows) {
+    row.forEach((cell, i) => {
+      const w = visibleWidth(cell);
+      if (widths[i] === undefined || w > widths[i]) widths[i] = w;
+    });
+  }
+  for (const row of rows) {
+    const line = row
+      .map((cell, i) => (i === row.length - 1 ? cell : cell + ' '.repeat(widths[i] - visibleWidth(cell))))
+      .join('  ');
+    process.stdout.write(indent + line.trimEnd() + '\n');
+  }
+}
+
+/**
+ * Width ignoring ANSI colour codes.
+ * @param {string} s
+ */
+export function visibleWidth(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+/**
+ * Human duration: 900 -> "0.9s", 65000 -> "1m 5s".
+ * @param {number} ms
+ */
+export function duration(ms) {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  const m = Math.floor(ms / 60_000);
+  const s = Math.round((ms % 60_000) / 1000);
+  return `${m}m ${s}s`;
+}
+
+/**
+ * A path shortened for reading, relative to cwd when it is inside it.
+ * @param {string} p
+ */
+export function shortPath(p) {
+  const cwd = process.cwd();
+  if (p.startsWith(cwd + '/')) return p.slice(cwd.length + 1);
+  const home = process.env.HOME;
+  if (home && p.startsWith(home + '/')) return '~/' + p.slice(home.length + 1);
+  return p;
+}

package/src/core/paths.js

@@ -0,0 +1,135 @@
+/**
+ * Where everything lives inside a project.
+ *
+ * Committed (belongs in git):   approved/  guards/  markers/  fixtures/  config
+ * Not committed (throwaway):    results/   diffs/   report.html  last-run.json
+ *
+ * The split matters: approved pictures are the promise, results are just the
+ * evidence from the last run.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+export const CONFIG_NAMES = [
+  'staysfixed.config.js',
+  'staysfixed.config.mjs',
+  'staysfixed.config.json',
+  '.staysfixed/config.js',
+  '.staysfixed/config.mjs',
+  '.staysfixed/config.json',
+];
+
+export const DEFAULT_DIR = '.staysfixed';
+
+/**
+ * Walk up from `from` looking for a config file.
+ * @param {string} [from]
+ * @returns {string|null} absolute path to the config file, or null
+ */
+export function findConfigFile(from = process.cwd()) {
+  let dir = path.resolve(from);
+  for (;;) {
+    for (const name of CONFIG_NAMES) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * The project root for a config file: the folder holding it, or its parent
+ * when the config lives inside `.staysfixed/`.
+ * @param {string} configFile
+ */
+export function rootForConfig(configFile) {
+  const dir = path.dirname(configFile);
+  return path.basename(dir) === DEFAULT_DIR ? path.dirname(dir) : dir;
+}
+
+/**
+ * @param {string} root
+ * @param {string} configFile
+ * @param {string} [dirName]
+ * @returns {import('../types.js').ProjectPaths}
+ */
+export function pathsFor(root, configFile, dirName = DEFAULT_DIR) {
+  const dir = path.isAbsolute(dirName) ? dirName : path.join(root, dirName);
+  return {
+    root,
+    dir,
+    approved: path.join(dir, 'approved'),
+    results: path.join(dir, 'results'),
+    diffs: path.join(dir, 'results', 'diffs'),
+    markers: path.join(dir, 'markers'),
+    guards: path.join(dir, 'guards'),
+    fixtures: path.join(dir, 'fixtures'),
+    historyFile: path.join(dir, 'history.json'),
+    reportFile: path.join(dir, 'report.html'),
+    configFile,
+  };
+}
+
+/**
+ * Create the folders that must exist before a run.
+ * @param {import('../types.js').ProjectPaths} paths
+ */
+export async function ensureDirs(paths) {
+  for (const d of [paths.dir, paths.approved, paths.results, paths.diffs, paths.markers]) {
+    await fsp.mkdir(d, { recursive: true });
+  }
+}
+
+/**
+ * File name for an approved picture and its metadata.
+ * @param {import('../types.js').ProjectPaths} paths
+ * @param {string} name
+ */
+export function approvedPicture(paths, name) {
+  return {
+    png: path.join(paths.approved, `${safeName(name)}.png`),
+    json: path.join(paths.approved, `${safeName(name)}.json`),
+  };
+}
+
+/**
+ * File names for this run's output for one screen.
+ * @param {import('../types.js').ProjectPaths} paths
+ * @param {string} name
+ */
+export function resultPicture(paths, name) {
+  return {
+    png: path.join(paths.results, `${safeName(name)}.png`),
+    diff: path.join(paths.diffs, `${safeName(name)}.diff.png`),
+  };
+}
+
+/**
+ * Screen names become file names, so keep them boring.
+ * @param {string} name
+ */
+export function safeName(name) {
+  return String(name)
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 120) || 'unnamed';
+}
+
+/**
+ * Clear the previous run's evidence so a stale diff can never be mistaken for a fresh one.
+ * @param {import('../types.js').ProjectPaths} paths
+ */
+export async function clearResults(paths) {
+  await fsp.rm(paths.results, { recursive: true, force: true });
+  await fsp.mkdir(paths.diffs, { recursive: true });
+}
+
+/**
+ * The .gitignore lines a project needs. Written by `init`, checked by `doctor`.
+ */
+export const GITIGNORE_LINES = ['# Stays Fixed — evidence from the last run, not the promise', '.staysfixed/results/', '.staysfixed/report.html'];