@warren-dean/code-kit 0.6.0 → 0.8.0

package/hooks/mod/review.mjs

@@ -0,0 +1,102 @@
+// The reviewer agent (spec 07), the pure parts: its definition, the lead's prompts that start it and
+// that hand its findings on, and reading its report. The hooks keep it read-only: any subagent that
+// isn't a lane's may only read (hooks/lib/rules.mjs).
+
+export const REVIEWER = 'reviewer';
+export const SEVERITIES = ['blocker', 'concern', 'nit'];
+/** The lead reviews without the reviewer once it has had this long (spec 07's quality target). */
+export const REVIEW_WAIT_MS = 15 * 60000;
+
+/** The reviewer's definition, for `$.agent.register`: read, search and run commands; never write. */
+export function reviewerSpec({ cli, checklist, model }) {
+  return {
+    name: REVIEWER,
+    description:
+      "code-kit's background reviewer: reviews one finished branch, read-only, and reports findings graded blocker, concern or nit. Started by the lead when code-kit's loop asks for it.",
+    tools: ['Read', 'Grep', 'Glob', 'Bash'],
+    ...(model ? { model } : {}),
+    prompt: [
+      "You are code-kit's reviewer. You review one branch, read-only: you never edit or write files, commit, approve, merge or record a send-back (code-kit's hooks refuse those for you). The lead decides; you report.",
+      '',
+      'For the branch you are given:',
+      `1. Run \`node "${cli}" verify --branch <branch>\` from the branch's worktree if it has one (\`git worktree list\`), otherwise in a throwaway worktree (\`git worktree add .claude/worktrees/reviewer-<n> <branch>\`, removed when you're done). A failing verify is always a blocker.`,
+      `2. Read ${checklist} and apply its review checklist to the branch's changes against its base, and to the story's requirements. Skip its steps that act (recording a send-back, merging): those are the lead's.`,
+      "3. Run the project's test commands that cover the changed files.",
+      '',
+      'Grade each finding: blocker (it must not merge as it is: a failing check, a requirement not met, a rule broken), concern (worth fixing; the lead decides), nit (small). Say where (path:line), what is wrong and what fixed looks like, and the requirement or rule it cites.',
+      '',
+      'End your report with one fenced json block, exactly this shape:',
+      '```json',
+      '{"verify": {"passed": true, "problems": []}, "findings": [{"severity": "blocker", "where": "src/a.ts:12", "text": "…", "rule": "REQ-1"}]}',
+      '```',
+    ].join('\n'),
+  };
+}
+
+/** The lead's prompt to start the reviewer for a branch at its head (REVW-1). */
+export function startReviewerPrompt({ agent, story, branch, head }) {
+  const reqs = story.requirements?.length ? ` (requirements ${story.requirements.join(', ')})` : '';
+  return `Start code-kit's reviewer in the background for ${branch}: use the Agent tool with subagent_type "${agent}", run_in_background true, description "Review ${branch} (${story.id})", and the prompt "Review ${branch} at ${head.slice(0, 12)} for ${story.id} ${story.title ?? ''}${reqs}." Then carry on; its findings come back to you and code-kit asks for your review then.`;
+}
+
+/**
+ * The reviewer's report, read (REVW-3): { findings, verify } from its json block, every failed
+ * verify problem a blocker; or { error } when the report has no block that reads.
+ */
+export function readReport(answer) {
+  const blocks = [...String(answer ?? '').matchAll(/```json\s*\n([\s\S]*?)```/g)];
+  if (!blocks.length) return { error: "the reviewer's report had no findings block" };
+  let data;
+  try {
+    data = JSON.parse(blocks.at(-1)[1]);
+  } catch {
+    return { error: "the reviewer's findings block isn't valid JSON" };
+  }
+  const findings = (Array.isArray(data.findings) ? data.findings : [])
+    .filter((f) => f && SEVERITIES.includes(f.severity) && typeof f.text === 'string')
+    .map((f) => ({
+      severity: f.severity,
+      text: f.text,
+      ...(f.where ? { where: String(f.where) } : {}),
+      ...(f.rule ? { rule: String(f.rule) } : {}),
+    }));
+  const verify = data.verify ?? null;
+  return { findings: withVerify(findings, verify), verify };
+}
+
+/** Findings with a blocker for each problem of a failed verify, unless one already names it. */
+export function withVerify(findings, verify) {
+  if (!verify || verify.passed !== false) return findings;
+  const problems = verify.problems?.length ? verify.problems : ['code-kit verify fails'];
+  const extra = problems
+    .filter((p) => !findings.some((f) => f.severity === 'blocker' && f.text.includes(p)))
+    .map((p) => ({ severity: 'blocker', text: `verify: ${p}`, rule: 'code-kit verify' }));
+  return [...extra, ...findings];
+}
+
+/** "1 blocker, 2 nits": the findings counted by severity. */
+export function findingsCount(findings) {
+  const n = (s) => findings.filter((f) => f.severity === s).length;
+  const parts = SEVERITIES.flatMap((s) => (n(s) ? [`${n(s)} ${s}${n(s) === 1 ? '' : 's'}`] : []));
+  return parts.length ? parts.join(', ') : 'no findings';
+}
+
+/** The lead's review prompt, with the reviewer's findings (REVW-4); a blocker means send back. */
+export function leadReviewPrompt(storyId, review) {
+  const head = `Review ${storyId}: run /code-kit:review ${storyId}.`;
+  if (!review || review.state === 'skipped')
+    return `${head}${review?.why ? ` (No background review: ${review.why}.)` : ''}`;
+  if (review.state === 'failed')
+    return `${head} (The background reviewer didn't report: ${review.error}. Review it yourself.)`;
+  const lines = review.findings.map(
+    (f) =>
+      `- ${f.severity}${f.where ? ` ${f.where}` : ''}: ${f.text}${f.rule ? ` (${f.rule})` : ''}`,
+  );
+  return [
+    `${head} code-kit's reviewer found ${lines.length ? findingsCount(review.findings) : 'nothing to fix'} on ${review.branch} at ${review.head.slice(0, 12)}${lines.length ? ':' : '.'}`,
+    ...lines,
+    ...(review.findings.some((f) => f.severity === 'blocker')
+      ? ['A blocker means you send the branch back. Concerns and nits are yours to weigh.']
+      : []),
+  ].join('\n');
+}

package/hooks/mod/trail.mjs

@@ -0,0 +1,152 @@
+// The trail (docs/specs/14-mission-and-maps.md, TRAIL-1), drawn: each requirement of a spec flowing to
+// the stories that deliver it, the code they changed and the tests that name it, with a gap where any
+// link is missing. Box-drawing text in the terminal, an SVG elsewhere. Its data is `code-kit trail`.
+
+/** A story's state as the trail colours it: done, moving (in progress or review), or waiting. */
+export const storyTone = (state) =>
+  state === 'done'
+    ? 'done'
+    : ['in progress', 'review', 'sent back'].includes(state)
+      ? 'moving'
+      : 'waiting';
+
+const GLYPH = { done: '✓', moving: '●', waiting: '■' };
+
+const fit = (s, n) => (s.length > n ? `${s.slice(0, Math.max(0, n - 1))}…` : s.padEnd(n));
+const short = (p) => p.split('/').pop();
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * TRAIL-1 in the terminal: one row per requirement, as runs [{ text, style }]. Consecutive
+ * requirements delivered by the same stories meet at one story node (┬ … ┘). Styles: req, selected,
+ * dim, done, moving, waiting, gap (red), test (green).
+ */
+export function trailRows(rows, { selected = null, width = 100 } = {}) {
+  const titleW = Math.max(14, Math.min(34, width - 70));
+  const key = (r) => r.stories.map((s) => s.id).join(' ');
+  return rows.map((r, i) => {
+    const runs = [];
+    const add = (text, style) => runs.push({ text, style });
+    add(r.id.padEnd(9), r.id === selected ? 'selected' : 'req');
+    add(fit(r.title, titleW), r.id === selected ? 'selected' : 'dim');
+    const same = i > 0 && key(rows[i - 1]) === key(r) && r.stories.length > 0;
+    const next = i < rows.length - 1 && key(rows[i + 1]) === key(r) && r.stories.length > 0;
+    if (!r.stories.length) {
+      add(' ╌╌╌ ', 'gap');
+      add(fit('no story', 16), 'gap');
+    } else if (same) {
+      add(next ? ' ───┤' : ' ───┘', 'dim');
+      add(''.padEnd(16), 'dim');
+    } else {
+      add(next ? ' ───┬ ' : ' ──── ', 'dim');
+      const tone = r.stories.every((s) => s.state === 'done')
+        ? 'done'
+        : r.stories.some((s) => storyTone(s.state) === 'moving')
+          ? 'moving'
+          : 'waiting';
+      add(fit(`${GLYPH[tone]} ${r.stories.map((s) => s.id).join(' ')}`, 15), tone);
+    }
+    if (r.files.length) {
+      add(' ─── ', 'dim');
+      add(fit(plural(r.files.length, 'file', 'files'), 9), 'dim');
+    } else {
+      add(' ╌╌╌ ', 'gap');
+      add(fit('no code', 9), 'gap');
+    }
+    if (r.tests.length) {
+      add(' ─── ', 'dim');
+      add(`✓ ${short(r.tests[0])}${r.tests.length > 1 ? ` +${r.tests.length - 1}` : ''}`, 'test');
+    } else {
+      add(' ╌╌╌ ', 'gap');
+      add('no test names it', 'gap');
+    }
+    return runs;
+  });
+}
+
+const esc = (s) =>
+  String(s).replace(
+    /[&<>"]/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c],
+  );
+
+const COLOR = {
+  done: '#78c98a',
+  moving: '#8fb8ff',
+  waiting: '#e06a6a',
+  dim: '#6e8286',
+  fg: '#cfd9da',
+  line: '#3b4c50',
+  gap: '#e06a6a',
+  test: '#78c98a',
+};
+
+/**
+ * TRAIL-1 on the remote surfaces: the flow as an SVG: requirements on the left, curves meeting at each
+ * story, then the files and the test that names it; a gap drawn dashed in red.
+ */
+export function trailSvg(rows, { selected = null } = {}) {
+  const rowH = 30;
+  const W = 820;
+  const H = rows.length * rowH + 44;
+  const X = { req: 12, story: 300, files: 430, test: 640 };
+  const parts = [];
+  for (const [label, x] of [
+    ['requirement', X.req],
+    ['story', X.story],
+    ['code', X.files],
+    ['test that names it', X.test],
+  ])
+    parts.push(`<text x="${x}" y="16" fill="${COLOR.dim}" font-size="11">${esc(label)}</text>`);
+  const storyY = {};
+  rows.forEach((r, i) => {
+    const y = 38 + i * rowH;
+    const key = r.stories.map((s) => s.id).join(' ');
+    if (key && storyY[key] === undefined) storyY[key] = y;
+    const sy = key ? storyY[key] : y;
+    const sel = r.id === selected;
+    parts.push(
+      `<text x="${X.req}" y="${y + 4}" fill="${sel ? '#8fb8ff' : COLOR.fg}" font-size="12"${sel ? ' font-weight="700"' : ''}>${esc(r.id)}</text>`,
+    );
+    parts.push(
+      `<text x="${X.req + 70}" y="${y + 4}" fill="${COLOR.dim}" font-size="11">${esc(r.title.length > 26 ? `${r.title.slice(0, 25)}…` : r.title)}</text>`,
+    );
+    if (key) {
+      parts.push(
+        `<path d="M${X.story - 50},${y} C${X.story - 25},${y} ${X.story - 25},${sy} ${X.story - 6},${sy}" fill="none" stroke="${COLOR.line}"/>`,
+      );
+      if (sy === y) {
+        const tone = r.stories.every((s) => s.state === 'done')
+          ? 'done'
+          : r.stories.some((s) => storyTone(s.state) === 'moving')
+            ? 'moving'
+            : 'waiting';
+        parts.push(`<circle cx="${X.story + 3}" cy="${y}" r="4" fill="${COLOR[tone]}"/>`);
+        parts.push(
+          `<text x="${X.story + 13}" y="${y + 4}" fill="${COLOR.fg}" font-size="12">${esc(key)}</text>`,
+        );
+      }
+      parts.push(
+        `<path d="M${X.story + 80},${sy} C${X.files - 30},${sy} ${X.files - 30},${y} ${X.files - 6},${y}" fill="none" stroke="${r.files.length ? COLOR.line : COLOR.gap}"${r.files.length ? '' : ' stroke-dasharray="3 3"'}/>`,
+      );
+    } else {
+      parts.push(
+        `<line x1="${X.story - 50}" y1="${y}" x2="${X.story - 6}" y2="${y}" stroke="${COLOR.gap}" stroke-dasharray="3 3"/>`,
+      );
+      parts.push(
+        `<text x="${X.story}" y="${y + 4}" fill="${COLOR.gap}" font-size="11">no story</text>`,
+      );
+    }
+    const files = r.files.map(short).join(', ');
+    parts.push(
+      `<text x="${X.files}" y="${y + 4}" fill="${r.files.length ? COLOR.dim : COLOR.gap}" font-size="11">${esc(r.files.length ? (files.length > 30 ? `${files.slice(0, 29)}…` : files) : 'no code yet')}</text>`,
+    );
+    parts.push(
+      `<line x1="${X.test - 18}" y1="${y}" x2="${X.test - 6}" y2="${y}" stroke="${r.tests.length ? COLOR.test : COLOR.gap}"${r.tests.length ? '' : ' stroke-dasharray="3 3"'}/>`,
+    );
+    parts.push(
+      `<text x="${X.test}" y="${y + 4}" fill="${r.tests.length ? COLOR.test : COLOR.gap}" font-size="11">${esc(r.tests.length ? `✓ ${short(r.tests[0])}${r.tests.length > 1 ? ` +${r.tests.length - 1}` : ''}` : 'no test names it yet')}</text>`,
+    );
+  });
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" font-family="ui-monospace, Menlo, monospace">${parts.join('')}</svg>`;
+}