@warren-dean/code-kit 0.12.1 → 0.13.0

package/bin/code-kit.mjs

@@ -106,6 +106,8 @@ import {
 import { DEPENDENCY_APPROVAL, dependencyApproval } from '../hooks/lib/dependencies.mjs';
 import { dependencyRuleProblems, npmFacts, packageOf } from '../hooks/lib/registry.mjs';
 import { heldTo, laneOfBranch, verifyBranch } from '../hooks/lib/verify.mjs';
+import { skippedLine } from '../hooks/lib/checks.mjs';
+import { TESTS_APPROVAL } from '../hooks/lib/regression.mjs';
 
 const out = (s) => process.stdout.write(`${s}\n`);
 // Piped into `head` and the like: stop quietly when the reader closes.
@@ -398,6 +400,8 @@ const VERIFY_GROUPS = {
   layers: 'Layer rules',
   baseline: 'Baseline',
   design: 'Designs before screens',
+  tests: 'Weakened tests',
+  regression: 'Fixes and their tests',
   checks: 'Checks',
 };
 
@@ -522,9 +526,11 @@ function merge(branch) {
 
 /**
  * Verifies `branch`, checks included, and merges it into the base (`--into`, or the first protected
- * branch). Returns { into, message }; throws a MergeStop when nothing was merged.
+ * branch). With `commit`, the commit the lead's review passed, it verifies and merges exactly that
+ * commit, and refuses if the branch has moved on from it. Returns { into, message }; throws a
+ * MergeStop when nothing was merged.
  */
-function mergeOne(branch, config, byPerson) {
+function mergeOne(branch, config, byPerson, commit = null) {
   const refuse = (message) => {
     throw new MergeStop('refused', message);
   };
@@ -583,13 +589,20 @@ function mergeOne(branch, config, byPerson) {
     // temporary worktree, where checks that need an install fail rather than being skipped.
     const verifyIn = checkedOut(branch) ?? worktree(branch, true);
     clean(verifyIn, branch);
+    const tip = g(verifyIn, 'rev-parse', 'HEAD').trim();
+    if (commit && tip !== commit)
+      fail(
+        `Nothing was merged: ${branch} has moved on since its review passed (${commit.slice(0, 7)} → ${tip.slice(0, 7)}). Review it again, then queue it.`,
+        'moved',
+      );
     const lane = laneOfBranch(branch, config);
-    const { changed, found } = verifyBranch({
+    const { changed, found, skipped } = verifyBranch({
       root: verifyIn,
       base: into,
       config,
       lane,
       checks: true,
+      branch,
     });
     const problems = Object.entries(VERIFY_GROUPS).flatMap(([key, title]) =>
       found[key].map((p) => `${title}: ${p.split('\n').join('\n    ')}`),
@@ -609,8 +622,8 @@ function mergeOne(branch, config, byPerson) {
         '-m',
         `Merge ${branch} into ${into}`,
         '-m',
-        `Verified with code-kit verify (${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}) and merged ${byPerson ? 'by the person, from the code-kit pane' : 'by the lead within the delegated rules'}.`,
-        branch,
+        `Verified with code-kit verify (${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}) at ${tip.slice(0, 7)}${commit ? ', the commit the review passed,' : ''} and merged ${byPerson ? 'by the person, from the code-kit pane' : 'by the lead within the delegated rules'}.${skipped.length ? ` ${notRun(skipped)}` : ''}`,
+        tip,
       );
     } catch (e) {
       try {
@@ -644,7 +657,7 @@ function mergeOne(branch, config, byPerson) {
     }
     return {
       into,
-      message: `Merged ${branch} into ${into}: verify passed on ${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}.${removed}`,
+      message: `Merged ${branch} into ${into}: verify passed on ${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}, at ${tip.slice(0, 7)}.${skipped.length ? ` ${notRun(skipped)}` : ''}${removed}`,
     };
   } finally {
     cleanup();
@@ -669,16 +682,24 @@ function queue() {
           ? `Took ${branch} out of the merge queue.`
           : `${branch} isn't waiting in the merge queue.`,
       );
+    let commit;
     try {
-      execFileSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], {
-        stdio: 'ignore',
-      });
+      commit = execFileSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
     } catch {
       die(`There is no branch ${branch}.`);
     }
-    if (!enqueue(root, branch)) return out(`${branch} is already in the merge queue.`);
+    // The commit the review passed: the queue merges exactly it, and a branch that moves is reviewed again.
+    const added = enqueue(root, branch, commit);
+    if (!added) return out(`${branch} is already in the merge queue, at ${commit.slice(0, 7)}.`);
+    if (added === 'updated')
+      return out(`${branch} keeps its place in the merge queue, now at ${commit.slice(0, 7)}.`);
     const place = waiting(readQueue(root)).length;
-    return out(`Queued ${branch} to merge${place > 1 ? `, ${place - 1} ahead of it` : ', next'}.`);
+    return out(
+      `Queued ${branch} at ${commit.slice(0, 7)} to merge${place > 1 ? `, ${place - 1} ahead of it` : ', next'}.`,
+    );
   }
   if (sub === 'rules') return rulesOntoBase(root, config);
   if (sub === 'merge') {
@@ -687,7 +708,7 @@ function queue() {
     const head = waiting(entries)[0];
     if (!head) return out('The merge queue is empty.');
     try {
-      const { message } = mergeOne(head.branch, config, byPerson);
+      const { message } = mergeOne(head.branch, config, byPerson, head.commit ?? null);
       settle(root, head.branch, 'merged');
       const left = waiting(readQueue(root));
       return out(
@@ -697,6 +718,12 @@ function queue() {
       if (!(e instanceof MergeStop)) throw e;
       // MQ-3: a conflict or a failed verify goes back to the lane; a refusal leaves the queue as it is.
       if (e.kind === 'refused') die(e.message);
+      // A branch that moved after its review leaves the queue for the lead to review it again; it
+      // isn't sent back, since nothing is wrong with it yet.
+      if (e.kind === 'moved') {
+        settle(root, head.branch, 'moved', 'changed after its review');
+        die(`${e.message}\n${head.branch} leaves the queue until then.`);
+      }
       const into = intoName ?? config.branches.protected[0];
       const after = lastMerged(entries);
       const why =
@@ -722,7 +749,11 @@ function queue() {
   const left = waiting(entries);
   if (!left.length) out('The merge queue is empty.');
   else out(`${left.length} waiting to merge, in order:`);
-  left.forEach((e, i) => out(`  ${i + 1}. ${e.branch} (passed review ${e.passed})`));
+  left.forEach((e, i) =>
+    out(
+      `  ${i + 1}. ${e.branch} (passed review ${e.passed}${e.commit ? ` at ${e.commit.slice(0, 7)}` : ''})`,
+    ),
+  );
 }
 
 /**
@@ -906,6 +937,7 @@ function story(id) {
         config,
         lane,
         checks: false,
+        branch: s.branch,
       });
       report.verify = {
         checks: false,
@@ -1099,18 +1131,21 @@ function verify() {
     }
   }
   const lane = laneOfBranch(branch, config);
-  const { changed, found } = verifyBranch({
+  const { changed, found, skipped } = verifyBranch({
     root: resolve('.'),
     base: from,
     config,
     lane,
     checks: !flag('--no-checks'),
+    // REG-1 is code-kit's own, so CI's --no-checks still proves a fix.
+    fixes: true,
+    branch,
   });
   if (flag('--json')) {
     const count = Object.values(found).reduce((n, list) => n + list.length, 0);
     out(
       JSON.stringify(
-        { base: from, branch, lane, changed: changed.length, found, problems: count },
+        { base: from, branch, lane, changed: changed.length, found, problems: count, skipped },
         null,
         2,
       ),
@@ -1128,10 +1163,15 @@ function verify() {
     out(`\n${title}:`);
     for (const p of found[key]) out(`  ${p.split('\n').join('\n    ')}`);
   }
+  if (skipped.length) out(`\n${notRun(skipped)}`);
   if (count) die(`\n${count} problem(s). Fix them on this branch.`);
-  out('No problems.');
+  out(skipped.length ? 'No problems in what ran.' : 'No problems.');
 }
 
+/** The checks that didn't run, for verify's and a merge's report. */
+const notRun = (skipped) =>
+  `Not run, because a tool isn't installed here: ${skipped.map(skippedLine).join('; ')}. Install it where verify runs, or set "ifMissing": "fail" on the check so a missing tool fails it.`;
+
 /**
  * ONB-7: whether a branch's changes need the security reviewer, and why: sign-in, permissions, outside
  * input, personal data, encryption, payments, secrets, commands built from strings, new dependencies,
@@ -1299,7 +1339,7 @@ async function approve(given) {
     );
   if (laneName !== undefined && !config.lanes[laneName])
     die(`There is no lane "${laneName}". Lanes: ${Object.keys(config.lanes).join(', ')}.`);
-  const known = new Set(['kit', ...config.protected.map((p) => p.approval)]);
+  const known = new Set(['kit', TESTS_APPROVAL, ...config.protected.map((p) => p.approval)]);
   const isPackage = (n) => /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(n);
   const names = given.map((n) =>
     n.startsWith(DEPENDENCY_APPROVAL) || known.has(n) || !isPackage(n) ? n : dependencyApproval(n),
@@ -1327,6 +1367,10 @@ async function approve(given) {
       );
     const outside = [];
     for (const name of names) {
+      if (name === TESTS_APPROVAL) {
+        outside.push(`${name}: weakening a test is the person's to allow, and is never delegated`);
+        continue;
+      }
       if (name.startsWith(DEPENDENCY_APPROVAL)) {
         if (!rules.dependencies) {
           outside.push(`${name}: dependencies aren't delegated`);

package/hooks/guard-bash.mjs

@@ -15,6 +15,7 @@ import { CONFIG_FILE } from './lib/config.mjs';
 import { laneOfBranch, storyOfBranch, teamOf, teamProvider, whoami } from './lib/team.mjs';
 import { matchesAny } from './lib/glob.mjs';
 import { noteBefore } from './lane-audit.mjs';
+import { TESTS_APPROVAL, commitWeakenings } from './lib/regression.mjs';
 import {
   APPROVAL_LOG,
   actorFor,
@@ -452,6 +453,40 @@ function recordApprovals() {
         grantedAt: null,
       });
   }
+  // REG-2: a commit that weakens a test waits for the person's `tests` approval, which nobody else can
+  // give; it's recorded in the log, so verify accepts the branch, and used up by this commit.
+  const weakened = commitWeakenings(
+    root,
+    files.filter((f) => !arrivesWithMerge(root, f, { staged: true })),
+    config,
+  );
+  if (weakened.length) {
+    const granted = approval(root, TESTS_APPROVAL, actor);
+    const said = (w) => `it ${w.reasons.join(', and ')}`;
+    if (!granted) {
+      const [w, ...more] = weakened;
+      recordRequest(root, actor, TESTS_APPROVAL, w.file, `A weakened test: ${said(w)}.`);
+      const personOnly = { ...config, approvals: { ...config.approvals, delegate: null } };
+      block(
+        `Blocked: ${w.file} is a weakened test (${said(w)}); committing it needs a person's approval in force.
+` +
+          (more.length
+            ? `Also weakened: ${more.map((x) => `${x.file} (${said(x)})`).join('; ')}.
+`
+            : '') +
+          `A weakened test can hide a regression. Fix the code so the test passes as it was. If the test itself is wrong, ask the person: neither the lead nor a lane can approve it. They run
+${approvalHowTo(TESTS_APPROVAL, actor, root, 'weakening tests in one commit', personOnly)}`,
+      );
+    }
+    for (const w of weakened)
+      record(w.file, {
+        approval: TESTS_APPROVAL,
+        reason: granted.reason,
+        grantedAt: granted.grantedAt,
+        weakened: w.reasons,
+      });
+    useApproval(root, TESTS_APPROVAL, actor);
+  }
   // A dependency approval is used up by the commit that adds its package to a manifest or lockfile.
   const manifests = files.filter((f) => isDependencyFile(f));
   if (manifests.length && actor.kind !== 'readonly') {

package/hooks/lib/checks.mjs

@@ -15,8 +15,12 @@ function directories(check, files, root) {
   return [...new Set(dirs)].map((d) => join(root, d)).filter((d) => existsSync(d));
 }
 
-/** The first failure as { title, output }, or null. `actor` decides `owners`; the lead always may. */
-function runCheck(check, files, root, actor) {
+/**
+ * The first failure as { title, output }, or null. `actor` decides `owners`; the lead always may. A
+ * command that isn't installed skips the rest of the check, unless `ifMissing` is "fail", and is
+ * added to `skipped` as { check, command, where }, so a pass never hides a check that didn't run.
+ */
+function runCheck(check, files, root, actor, skipped) {
   if (check.owners && !(actor.kind === 'lead' || check.owners.includes(actor.lane))) {
     return {
       title: `The ${actor.label} changed ${check.name} files it does not own:`,
@@ -37,6 +41,7 @@ function runCheck(check, files, root, actor) {
           return {
             title: `${check.name}: \`${command}\` is not installed${where}. Install it so the check can run.`,
           };
+        skipped.push({ check: check.name, command, where: where.replace(/^ in /, '') || null });
         return null; // not installed yet (fresh clone): the check can't run
       }
       if (res.error || res.status === null)
@@ -53,15 +58,23 @@ function runCheck(check, files, root, actor) {
   return null;
 }
 
-/** Runs every check whose files changed, in order; the first failure, or null when all pass. */
+/**
+ * Runs every check whose files changed, in order: { failure, skipped }, where `failure` is the first
+ * failure or null, and `skipped` lists the checks that couldn't run because a tool isn't installed.
+ */
 export function runChecks(config, changed, root, actor) {
+  const skipped = [];
   for (const check of config.checks) {
     const files = changed.filter(
       (f) => matchesAny(f, check.files) && !matchesAny(f, check.exclude),
     );
     if (!files.length) continue;
-    const failure = runCheck(check, files, root, actor);
-    if (failure) return failure;
+    const failure = runCheck(check, files, root, actor, skipped);
+    if (failure) return { failure, skipped };
   }
-  return null;
+  return { failure: null, skipped };
 }
+
+/** A skipped check in a sentence: "typecheck (`tsc` isn't installed in apps/web)". */
+export const skippedLine = (s) =>
+  `${s.check} (\`${s.command}\` isn't installed${s.where ? ` in ${s.where}` : ''})`;

package/hooks/lib/config.mjs

@@ -93,6 +93,8 @@ export function withDefaults(c) {
     shell: { block: c.shell?.block ?? [], restricted: c.shell?.restricted ?? [] },
     postEdit: c.postEdit ?? [],
     checks: c.checks ?? [],
+    tests: c.tests ?? [],
+    regression: { prepare: c.regression?.prepare ?? null },
     branches: { protected: c.branches?.protected ?? ['main', 'master'] },
     approvals: { lead: c.approvals?.lead === true, delegate: delegateRules(c.approvals?.delegate) },
     harness: harnessSettings(c.harness),
@@ -211,6 +213,12 @@ export function validate(c) {
     need(e.exclude === undefined || isList(e.exclude), `${at}.exclude must be a list of globs`);
   });
   each('checks', (e, at) => validateCheck(e, at, lanes, need));
+  need(c.tests === undefined || isList(c.tests), '"tests" must be a list of globs: the test files');
+  need(
+    c.regression === undefined ||
+      (isObj(c.regression) && (c.regression.prepare === undefined || isStr(c.regression.prepare))),
+    '"regression" must be { prepare?: a command run in a fresh checkout before a fix\'s tests }',
+  );
   const known = ADAPTERS.map((a) => a.name);
   need(
     c.adapters === undefined ||

package/hooks/lib/next.mjs

@@ -26,7 +26,10 @@ const git = (root, ...args) => {
   }
 };
 
-/** The spec-design brief: { path, status, openQuestions: [question, ...] }, or null. */
+/**
+ * The spec-design brief: { path, status, openQuestions: [question, ...], open: [{ question, owner,
+ * blocks }] }, or null. `open` reads the table's Owner and Blocks columns where it has them.
+ */
 export function readBrief(root, config) {
   const specs = config?.docs?.specs;
   const candidates = [specs && `${posix.dirname(specs)}/brief.md`, 'docs/brief.md'].filter(Boolean);
@@ -39,12 +42,27 @@ export function readBrief(root, config) {
   const start = lines.findIndex((l) => /^##\s+Open questions/i.test(l));
   const section = start < 0 ? [] : lines.slice(start + 1);
   const end = section.findIndex((l) => /^##\s/.test(l));
-  const openQuestions = section
-    .slice(0, end < 0 ? undefined : end)
-    .filter((l) => /^\|/.test(l) && !/^\|\s*-/.test(l) && !/^\|\s*Question\s*\|/i.test(l))
-    .map((l) => l.split('|')[1].trim())
-    .filter((q) => q && !q.startsWith('{{'));
-  return { path, status: status ?? null, openQuestions };
+  const rows = section.slice(0, end < 0 ? undefined : end).filter((l) => /^\|/.test(l));
+  const cells = (l) =>
+    l
+      .split('|')
+      .slice(1, -1)
+      .map((c) => c.trim());
+  const header = rows.find((l) => /^\|\s*Question\s*\|/i.test(l));
+  const columns = header ? cells(header).map((c) => c.toLowerCase()) : ['question'];
+  const at = (name) => columns.findIndex((c) => c.startsWith(name));
+  const open = rows
+    .filter((l) => l !== header && !/^\|\s*-/.test(l))
+    .map((l) => {
+      const c = cells(l);
+      return {
+        question: c[0] ?? '',
+        owner: at('owner') > 0 ? c[at('owner')] || null : null,
+        blocks: at('block') > 0 ? c[at('block')] || null : null,
+      };
+    })
+    .filter((q) => q.question && !q.question.startsWith('{{'));
+  return { path, status: status ?? null, openQuestions: open.map((q) => q.question), open };
 }
 
 const hasMarkdown = (dir) => {
@@ -87,7 +105,15 @@ export function nextStep(root, base) {
   const brief = readBrief(root, config);
   if (brief?.openQuestions.length) {
     attention.push(`${brief.openQuestions.length} open question(s) in ${brief.path}.`);
-    briefQuestions = brief.openQuestions.map((question) => ({ question, path: brief.path }));
+    // A question the brief gives to the lead alone (Owner: Lead) is the lead's to settle, not the person's.
+    briefQuestions = brief.open
+      .filter(
+        (q) =>
+          !q.owner ||
+          !/\blead\b/i.test(q.owner) ||
+          /owner|person|you|product|client/i.test(q.owner),
+      )
+      .map((q) => ({ ...q, path: brief.path }));
   }
 
   if (!config) {

package/hooks/lib/plan.mjs

@@ -1,7 +1,7 @@
 // Requirements and stories, read from the project's docs. Specs (docs.specs) hold requirements as
 // headings `### BOOK-4 Short name` (`(removed)` at the end drops one); the plan (docs.plan) holds
 // stories as `### ST-12 Title` followed by `**Lane:**`, `**Requirements:**`, `**Depends on:**` and
-// `**Status:**` lines. A lane builds a story on the branch `<lane>/st-12`. The lane `lead` marks the
+// `**Status:**` lines, and for a fix, `**Fixes:**`. A lane builds a story on the branch `<lane>/st-12`. The lane `lead` marks the
 // lead's own stories (contracts, foundations, spikes), which the lead builds rather than dispatches;
 // `**Requirements:** none` marks a story that delivers no requirement, such as a spike.
 import { execFileSync } from 'node:child_process';
@@ -52,7 +52,7 @@ const field = (lines, name) =>
     .trim() ?? '';
 
 /**
- * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, milestone }]. A story's
+ * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, fixes, milestone }]. A story's
  * milestone is the `## ` heading above it ("Milestone 5: Your own key"), or null.
  */
 export function readStories(root, planPath) {
@@ -75,6 +75,8 @@ export function readStories(root, planPath) {
         lane: field(body, 'Lane'),
         requirements: [...field(body, 'Requirements').matchAll(REQUIREMENT)].map((r) => r[1]),
         noRequirements: /^none\b/i.test(field(body, 'Requirements')),
+        // REG-1: what a fix story fixes, or null.
+        fixes: field(body, 'Fixes') || null,
         dependsOn: [...field(body, 'Depends on').matchAll(/\bST-\d+\b/g)].map((r) => r[0]),
         status: STATES.includes(status) ? status : 'todo',
         milestone,

package/hooks/lib/queue.mjs

@@ -11,7 +11,10 @@ const DONE_KEPT = 20;
 
 const queueFile = (root) => join(projectWorktrees(root)[0] ?? root, QUEUE_FILE);
 
-/** The queue's entries: [{ branch, passed, state, at?, reason? }], waiting ones in merge order. */
+/**
+ * The queue's entries: [{ branch, commit, passed, state, at?, reason? }], waiting ones in merge order.
+ * `commit` is the one the lead's review passed; entries queued before 0.13.0 have none.
+ */
 export function readQueue(root) {
   try {
     const entries = JSON.parse(readFileSync(queueFile(root), 'utf8'));
@@ -35,13 +38,26 @@ function writeQueue(root, entries) {
 /** The branches still to merge, in order (MQ-1). */
 export const waiting = (entries) => entries.filter((e) => ['waiting', 'merging'].includes(e.state));
 
-/** Adds a branch the lead's review passed, at the back; a branch already waiting keeps its place. */
-export function enqueue(root, branch, now = Date.now()) {
+/**
+ * Adds a branch the lead's review passed at `commit`, at the back; a branch already waiting keeps its
+ * place, with the commit its latest review passed.
+ */
+export function enqueue(root, branch, commit, now = Date.now()) {
   const entries = readQueue(root);
-  if (waiting(entries).some((e) => e.branch === branch)) return false;
+  const queued = waiting(entries).find((e) => e.branch === branch);
+  if (queued) {
+    if (queued.commit === commit) return false;
+    writeQueue(
+      root,
+      entries.map((e) =>
+        e === queued ? { ...e, commit, passed: new Date(now).toISOString() } : e,
+      ),
+    );
+    return 'updated';
+  }
   writeQueue(root, [
     ...entries.filter((e) => e.branch !== branch),
-    { branch, passed: new Date(now).toISOString(), state: 'waiting' },
+    { branch, commit, passed: new Date(now).toISOString(), state: 'waiting' },
   ]);
   return true;
 }
@@ -57,7 +73,10 @@ export function dequeue(root, branch) {
   return true;
 }
 
-/** Sets a waiting branch's state: merging, merged, sent back (with why), or waiting again. */
+/**
+ * Sets a waiting branch's state: merging, merged, sent back (with why), moved (it changed after its
+ * review, so it's reviewed again), or waiting again.
+ */
 export function settle(root, branch, state, reason = null, now = Date.now()) {
   const entries = readQueue(root).map((e) =>
     e.branch === branch && ['waiting', 'merging'].includes(e.state)