staysfixed 0.6.2 → 0.7.0

package/src/v2/adapters/isolate.js

@@ -61,6 +61,89 @@ const alive = new Map();
 /** @param {number} ms */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// ---------------------------------------------------------------------------
+// Saying out loud that something was opened
+// ---------------------------------------------------------------------------
+
+/**
+ * What this tool opened, and enough about it to be able to look after it.
+ *
+ * The screen is the reason this exists. A check that starts a desktop app has to be
+ * able to say, afterwards and to something outside this file: THAT application, with
+ * THAT unix id, is mine — I opened it, I will close it, and while it is up it does
+ * not get to keep taking the screen from whoever is using this machine. Nothing else
+ * on the machine can work that out for itself: a scratch copy of an app and the
+ * person's own copy of the same app are indistinguishable from the outside.
+ *
+ * @typedef {object} OpenedApp
+ * @property {string} name     The application's name, as macOS reports it.
+ * @property {number} pid
+ * @property {string} binary   What was actually run.
+ * @property {string} label    Which build it is, in plain English.
+ */
+
+/**
+ * Everybody who wants to be told. A Set rather than a single hook because a check, a
+ * panel and a test can all reasonably want to know at once.
+ * @type {Set<(app: OpenedApp) => void>}
+ */
+const told = new Set();
+
+/**
+ * Be told whenever this tool opens a desktop app.
+ *
+ * Called before anything is started, and the listener runs the moment the process
+ * exists — before the app has drawn a window, which is what makes it early enough to
+ * be useful. A listener that throws is ignored: nothing that merely wants to WATCH a
+ * run may break one.
+ *
+ * @param {(app: OpenedApp) => void} listener
+ * @returns {() => void} stop being told
+ */
+export function onAppStarted(listener) {
+  told.add(listener);
+  return () => {
+    told.delete(listener);
+  };
+}
+
+/**
+ * @param {OpenedApp} app
+ * @returns {void}
+ */
+function announce(app) {
+  for (const listener of [...told]) {
+    try {
+      listener(app);
+    } catch {
+      // Watching is never allowed to be the reason a run fails.
+    }
+  }
+}
+
+/**
+ * The application name macOS will use for this binary.
+ *
+ * A Mac app is run through the executable buried inside its bundle —
+ * `Foo.app/Contents/MacOS/Foo` — but everything that talks about windows and the
+ * foreground talks about "Foo". The bundle is what to read: the executable inside it
+ * is often called something else entirely, and for a development build it is called
+ * `Electron`.
+ *
+ * @param {string} binary
+ * @returns {string}
+ */
+export function appNameFor(binary) {
+  const text = String(binary ?? '');
+  const parts = text.split(path.sep);
+  for (let i = parts.length - 1; i >= 0; i -= 1) {
+    if (parts[i].toLowerCase().endsWith('.app')) return parts[i].slice(0, -4);
+  }
+  const base = path.basename(text);
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
 // ---------------------------------------------------------------------------
 // The shapes
 // ---------------------------------------------------------------------------
@@ -516,6 +599,12 @@ export function startIsolated(isolation, opts) {
   // A quit later on must never take the tool down with an unhandled error event.
   child.on('error', () => {});
 
+  // Said out loud the moment the process exists, and before it has drawn anything.
+  // Whoever is looking after the screen during this check needs to know that this
+  // application belongs to the tool BEFORE it appears, or its first appearance is
+  // read as the person choosing it.
+  announce({ name: appNameFor(opts.binary), pid: child.pid ?? -1, binary: opts.binary, label: isolation.label });
+
   return {
     child,
     pid: child.pid ?? -1,

package/src/v2/cause.js

@@ -58,6 +58,11 @@ const run = promisify(execFile);
  * @property {string} [why]        Why it could not be tested, when it could not.
  * @property {ChangedHunk[]} [candidates]  Hunks it could have tested, when it could not choose.
  * @property {string} [worktree]   Where it ran, when `keep` was asked for.
+ * @property {string} [leftBehind] Set when the scratch checkout could not be removed. It says
+ *                                 exactly what is still on disk and how to get rid of it,
+ *                                 because a cleanup that fails in silence leaves a stale
+ *                                 entry in the real repository's worktree list and the next
+ *                                 `git status` there is frightening for no reason.
  */
 
 // EVERY difference in the finding is re-checked, and there is deliberately no ceiling.
@@ -99,6 +104,15 @@ export async function proveCause(finding, opts) {
 
   const changed = opts.changed ?? (await whatChanged(opts.cwd));
   if (!changed.ok) return cannot(changed.why ?? 'The working tree could not be read.', null);
+  // "git could not hand over the diff" and "there is no diff" both left `hunks` empty, and
+  // the sentence below was said about both. Telling somebody their tree is clean when it is
+  // not is worse than telling them nothing, because they act on it.
+  if (changed.patchUnread === true && changed.hunks.length === 0) {
+    return cannot(
+      `${changed.patchUnreadWhy ?? 'The working diff could not be read.'} That is not the same as nothing having changed — ${changed.files.length} tracked ${changed.files.length === 1 ? 'file has' : 'files have'} edits in ${changed.files.length === 1 ? 'it' : 'them'} — so no change could be undone and nothing here is proved either way.`,
+      null,
+    );
+  }
   if (changed.hunks.length === 0 && changed.untracked.length === 0) {
     return cannot('Nothing in the working tree has changed, so there is no change to undo.', null);
   }
@@ -133,6 +147,19 @@ export async function proveCause(finding, opts) {
   }
 
   let checkedOut = false;
+  // The answer is held rather than only returned, so the tidy-up below can write on it. A
+  // cleanup that fails after the verdict is decided must still reach whoever reads the
+  // verdict; `gitQuiet` hands back whether it worked and nothing used to look.
+  /** @type {{proof: CauseProof|null}} */
+  const held = { proof: null };
+  /**
+   * @param {CauseProof} p
+   * @returns {CauseProof}
+   */
+  const done = (p) => {
+    held.proof = p;
+    return p;
+  };
   try {
     await gitOrThrow(['worktree', 'add', '--detach', tree, 'HEAD'], changed.root);
     checkedOut = true;
@@ -148,9 +175,22 @@ export async function proveCause(finding, opts) {
     // by hand — all of them except the suspect, which is left out, because
     // leaving a file out IS undoing the change that added it.
     const suspectIsNew = changed.untracked.includes(hunk.file);
+    /** @type {string[]} */
+    const notCarried = [];
     for (const file of changed.untracked) {
       if (file === hunk.file) continue;
-      await copyInto(changed.root, tree, file);
+      const copied = await copyInto(changed.root, tree, file);
+      if (!copied.ok) notCarried.push(`${file} (${copied.why})`);
+    }
+    // A new file that did not make it into the scratch checkout is a file the re-walk runs
+    // WITHOUT. The difference then disappears because the file is missing, not because the
+    // suspect change caused it — and the proof comes back "caused by that change", stamped,
+    // machine-checked and wrong. That is a verdict built on a silence, so there is no verdict.
+    if (notCarried.length > 0) {
+      return done(cannot(
+        `${notCarried.length} new ${notCarried.length === 1 ? 'file' : 'files'} could not be copied into the scratch checkout: ${notCarried.join('; ')}. Anything that went away in a copy missing those files would have gone away for the wrong reason, so nothing is claimed here.`,
+        hunk,
+      ));
     }
 
     // And now undo the one change under suspicion.
@@ -165,10 +205,10 @@ export async function proveCause(finding, opts) {
         undone = await gitQuiet(['apply', '--reverse', '--recount', '--whitespace=nowarn', suspectPatch], tree);
       }
       if (!undone.ok) {
-        return cannot(
+        return done(cannot(
           `That change could not be undone on its own: ${undone.why}. It probably overlaps another change in the same place.`,
           hunk,
-        );
+        ));
       }
     }
 
@@ -221,15 +261,83 @@ export async function proveCause(finding, opts) {
     };
     if (opts.keep === true) result.worktree = tree;
     if (events) events.emit({ type: 'proof:done', at: events.elapsed(), message: result.what });
-    return result;
+    return done(result);
   } catch (e) {
-    return cannot(messageOf(e), hunk);
+    return done(cannot(messageOf(e), hunk));
   } finally {
     // Even when it throws. A leftover worktree makes the next `git status`
-    // confusing and the one after that frightening.
-    if (checkedOut && opts.keep !== true) await gitQuiet(['worktree', 'remove', '--force', tree], changed.root);
-    await gitQuiet(['worktree', 'prune'], changed.root);
-    if (opts.keep !== true) await fsp.rm(base, { recursive: true, force: true }).catch(() => {});
+    // confusing and the one after that frightening — and until 2026-08-30, if the removal
+    // itself failed, it failed in complete silence and left one behind anyway.
+    const mess = await tidyUp({ tree, base, root: changed.root, checkedOut, keep: opts.keep === true });
+    if (mess) {
+      if (held.proof) held.proof.leftBehind = mess;
+      if (opts.events) opts.events.emit({ type: 'note', at: opts.events.elapsed(), message: mess });
+    }
+  }
+}
+
+/**
+ * Put the scratch checkout away, and say so plainly when it will not go.
+ *
+ * `git worktree remove` fails for ordinary reasons — a file still open, a folder the run
+ * itself is sitting in, a permission. When it does, the folder is deleted directly and the
+ * registration is pruned, which is the same outcome by another road. If even that does not
+ * work, the one thing left worth doing is saying exactly what is on disk and the one command
+ * that clears it, rather than leaving the person to find it themselves in a month.
+ *
+ * @param {{tree: string, base: string, root: string, checkedOut: boolean, keep: boolean}} where
+ * @returns {Promise<string>} empty when everything was cleared away
+ */
+async function tidyUp(where) {
+  if (where.keep) return '';
+  /** @type {string[]} */
+  const problems = [];
+
+  if (where.checkedOut) {
+    const removed = await gitQuiet(['worktree', 'remove', '--force', where.tree], where.root);
+    if (!removed.ok && (await stillThere(where.tree))) {
+      if (!(await wipe(where.tree))) problems.push(`the scratch checkout is still at ${where.tree} (${removed.why})`);
+    }
+  }
+  const pruned = await gitQuiet(['worktree', 'prune'], where.root);
+  if (!pruned.ok) {
+    problems.push(`the stale worktree entry could not be pruned from ${where.root} (${pruned.why}), so \`git worktree list\` there may still name a folder that is gone`);
+  }
+  if (!(await wipe(where.base)) && (await stillThere(where.base))) {
+    problems.push(`the temporary folder ${where.base} could not be deleted`);
+  }
+
+  if (problems.length === 0) return '';
+  return (
+    `Proving the cause left something behind: ${problems.join('; ')}. ` +
+    `Nothing of yours was touched — all of it is inside a temporary folder — but it will not clear itself. ` +
+    `To remove it: git -C ${where.root} worktree prune && rm -rf ${where.base}`
+  );
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<boolean>} true when it was removed or was never there
+ */
+async function wipe(dir) {
+  try {
+    await fsp.rm(dir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<boolean>}
+ */
+async function stillThere(dir) {
+  try {
+    await fsp.stat(dir);
+    return true;
+  } catch {
+    return false;
   }
 }
 
@@ -317,21 +425,52 @@ function cannot(why, hunk) {
 
 /**
  * Copy one file from the real project into the scratch checkout, folders and all.
+ *
+ * A file that vanished between git listing it and this copying it really is nothing to fail
+ * a proof over — it is not in the working tree any more either, so the scratch checkout is
+ * right to be without it. Every OTHER failure is different in kind: the file IS there, the
+ * scratch copy does not have it, and the re-walk is therefore running a different product.
+ * Those two used to be the same empty catch.
+ *
  * @param {string} from
  * @param {string} to
  * @param {string} file  repo-relative
+ * @returns {Promise<{ok: boolean, why: string}>}
  */
 async function copyInto(from, to, file) {
   const source = path.resolve(from, file);
   const target = path.resolve(to, file);
   // A path that climbs out of the scratch tree is never copied.
-  if (!target.startsWith(path.resolve(to))) return;
+  if (!target.startsWith(path.resolve(to) + path.sep)) {
+    return { ok: false, why: 'its path points outside the scratch checkout' };
+  }
   try {
     await fsp.mkdir(path.dirname(target), { recursive: true });
     await fsp.copyFile(source, target);
+    return { ok: true, why: '' };
+  } catch (e) {
+    const code = /** @type {{code?: string}} */ (e).code;
+    if (code === 'ENOENT' && !(await exists(source))) return { ok: true, why: '' };
+    if (code === 'EISDIR') {
+      // git only lists a bare directory when it is asked for untracked directories rather
+      // than untracked files, which is not how this asks — but if it ever happens, a folder
+      // silently not copied is a whole subtree the re-walk does not have.
+      return { ok: false, why: 'it is a folder, not a file' };
+    }
+    return { ok: false, why: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<boolean>}
+ */
+async function exists(file) {
+  try {
+    await fsp.stat(file);
+    return true;
   } catch {
-    // A file that vanished between listing it and copying it is not worth
-    // failing a proof over.
+    return false;
   }
 }