@warren-dean/code-kit 0.6.0 → 0.8.0

package/hooks/lib/storymap.mjs

@@ -0,0 +1,155 @@
+// A story's code as the pane draws it (docs/specs/14-mission-and-maps.md): the files it changed, by the
+// layer each sits in, with the imports between them (MAP-1); and each requirement's trail to its
+// stories, their files and the tests that name it (TRAIL-1). Read from git, the config and the plan.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { matchesAny } from './glob.mjs';
+import { CODE, importsOf, layerOf, targetOf } from './layers.mjs';
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return '';
+  }
+};
+
+/** Files that are the build's own code: not the plan, the specs, or the tools' state. */
+const KIT = /^(\.claude|\.ctx|\.github)\//;
+const isCode = (rel) => CODE.test(rel) && !KIT.test(rel);
+
+/**
+ * The code files a story changed: those in commits whose message names it (on any branch, so a merged
+ * story still has its files) and, while its branch is open, its diff against the base. Only files that
+ * still exist, in path order.
+ */
+export function storyFiles(root, story, from) {
+  const found = new Set();
+  const id = story.id;
+  const log = git(
+    root,
+    'log',
+    '--all',
+    '--no-merges',
+    '-E',
+    // POSIX ERE has no \b: "ST-1" mustn't match "ST-12".
+    `--grep=(^|[^A-Za-z0-9-])${id}([^0-9]|$)`,
+    '--format=',
+    '--name-only',
+  );
+  for (const f of log.split('\n')) if (f) found.add(f);
+  if (story.branchExists && story.branch)
+    for (const f of git(root, 'diff', '--name-only', `${from}...${story.branch}`).split('\n'))
+      if (f) found.add(f);
+  return [...found].filter((f) => isCode(f) && existsSync(join(root, f))).sort();
+}
+
+const EXTENSIONS = [
+  '',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '/index.ts',
+  '/index.tsx',
+  '/index.js',
+];
+
+/** The file in `files` an import specifier in `rel` points at, or null. */
+function resolveIn(spec, rel, aliases, files) {
+  const target = targetOf(spec, rel, aliases);
+  if (!target) return null;
+  // `./x.js` in TypeScript source names `./x.ts`.
+  const bare = target.replace(/\.(js|mjs|cjs)$/, '');
+  for (const ext of EXTENSIONS) {
+    for (const candidate of [`${target}${ext}`, `${bare}${ext}`])
+      if (files.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The lane that owns `rel`, or `lead`, or null. */
+export function laneOfFile(rel, config) {
+  const lane = Object.keys(config.lanes).find((name) => {
+    const { paths, exclude = [] } = config.lanes[name];
+    return matchesAny(rel, paths) && !matchesAny(rel, exclude);
+  });
+  if (lane) return lane;
+  return matchesAny(
+    rel,
+    config.lead.paths.filter((p) => p !== '*'),
+  )
+    ? 'lead'
+    : null;
+}
+
+const TEST = /(^|\/)(tests?|e2e|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * MAP-1: a story's code: { story, layers, files: [{ path, layer, lane, imports }] }. `layers` are the
+ * config's layers in their order, then `tests` and `other` where any file falls there; each file's
+ * imports are the story's other files it imports.
+ */
+export function storyMap(root, story, config, from) {
+  const paths = storyFiles(root, story, from);
+  const set = new Set(paths);
+  const aliases = config.importAliases ?? {};
+  const files = paths.map((rel) => {
+    let source = '';
+    try {
+      source = readFileSync(join(root, rel), 'utf8');
+    } catch {
+      // unreadable: no imports
+    }
+    const imports = [
+      ...new Set(
+        importsOf(source)
+          .map((spec) => resolveIn(spec, rel, aliases, set))
+          .filter((t) => t && t !== rel),
+      ),
+    ];
+    const layer = TEST.test(rel) ? 'tests' : (layerOf(rel, config.layers)?.name ?? 'other');
+    return { path: rel, layer, lane: laneOfFile(rel, config), imports };
+  });
+  const used = new Set(files.map((f) => f.layer));
+  const layers = [...config.layers.map((l) => l.name), 'tests', 'other'].filter((l) => used.has(l));
+  return {
+    story: { id: story.id, title: story.title, lane: story.lane, state: story.state },
+    layers,
+    files,
+  };
+}
+
+/**
+ * TRAIL-1: each requirement's trail: { id, title, spec, state, stories: [{ id, state, lane }],
+ * files, tests }. Files are the code its stories changed, tests aside; tests are the files that name it.
+ */
+export function trail(root, status, from) {
+  const byStory = new Map();
+  const filesOf = (s) => {
+    if (!byStory.has(s.id)) byStory.set(s.id, storyFiles(root, s, from));
+    return byStory.get(s.id);
+  };
+  return status.requirements
+    .filter((r) => !r.removed)
+    .map((r) => {
+      const stories = status.stories.filter((s) => s.requirements.includes(r.id));
+      const files = [...new Set(stories.flatMap((s) => filesOf(s)).filter((f) => !TEST.test(f)))];
+      return {
+        id: r.id,
+        title: r.title,
+        spec: r.file ? posix.basename(r.file) : null,
+        state: r.state,
+        stories: stories.map((s) => ({ id: s.id, state: s.state, lane: s.lane })),
+        files,
+        tests: [...(r.tests ?? [])],
+      };
+    });
+}

package/hooks/lib/timeline.mjs

@@ -0,0 +1,77 @@
+// When each story's work happened (docs/specs/11-panes.md, VIEW-2), from git and the project's own
+// records: when its branch was made, its commits, its merge into the base, its send-backs and the
+// approvals its commits logged. The mod draws these as a bar per lane on a shared time axis.
+import { execFileSync } from 'node:child_process';
+import { APPROVAL_LOG } from './rules.mjs';
+import { sendBacks } from './reviews.mjs';
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * For each story with a branch, or done: { id, lane, branch, state, started, lastCommit, merged,
+ * sentBack: [ms], approvals: [{ at, names }] }, times in milliseconds or null.
+ */
+export function storyTimes(root, stories, base) {
+  const git = (...args) => {
+    try {
+      return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 32 * 1024 * 1024,
+      }).trim();
+    } catch {
+      return '';
+    }
+  };
+  const lines = (text) => text.split('\n').filter(Boolean);
+  const merges = lines(git('log', '--merges', '--format=%ct%x09%s', base)).map((l) => {
+    const [t, ...subject] = l.split('\t');
+    return { at: Number(t) * 1000, subject: subject.join('\t') };
+  });
+  const backs = sendBacks(root);
+  const logged = (ref) => new Set(lines(git('show', `${ref}:${APPROVAL_LOG}`)));
+  const onBase = logged(base);
+  return stories
+    .filter((s) => s.branchExists || s.state === 'done')
+    .map((s) => {
+      const b = s.branch;
+      // The reflog's oldest entry is the branch's making, when it's still there.
+      const made = s.branchExists
+        ? lines(git('reflog', 'show', '--format=%ct', `refs/heads/${b}`))
+        : [];
+      const commits = s.branchExists
+        ? lines(git('log', '--format=%ct', `${base}..${b}`)).map((t) => Number(t) * 1000)
+        : [];
+      const named = new RegExp(`(^|[\\s'"])${escape(b)}($|[\\s'"])`);
+      const merged = merges.find((m) => named.test(m.subject))?.at ?? null;
+      const approvals = s.branchExists
+        ? [...logged(b)]
+            .filter((l) => !onBase.has(l))
+            .flatMap((l) => {
+              try {
+                const e = JSON.parse(l);
+                return e.grantedAt || e.at
+                  ? [{ at: Date.parse(e.grantedAt ?? e.at), names: [e.approval].filter(Boolean) }]
+                  : [];
+              } catch {
+                return [];
+              }
+            })
+        : [];
+      return {
+        id: s.id,
+        lane: s.lane,
+        branch: b,
+        state: s.state,
+        started: made.length
+          ? Number(made.at(-1)) * 1000
+          : commits.length
+            ? Math.min(...commits)
+            : null,
+        lastCommit: commits.length ? Math.max(...commits) : null,
+        merged,
+        sentBack: backs.filter((x) => x.branch === b).map((x) => Date.parse(x.at)),
+        approvals,
+      };
+    });
+}

package/hooks/mod/art.mjs

@@ -0,0 +1,200 @@
+// Panes v2's pictures (docs/specs/11-panes.md, VIEW-2 and VIEW-3): a timeline bar per lane on a
+// shared time axis, and a small pixel character per lane agent whose pose shows its state. The
+// terminal draws characters as half-block cells (a Raster, repainted in place with $.ui.blit while
+// the agent works); Desktop draws them, and the timelines, as SVG. Every state has a glyph too.
+
+// --- the characters (VIEW-3) ---------------------------------------------------------------------
+
+/** Each pose, 6 by 6 pixels: H the lane's tint, E eyes, X stalled eyes, L closed eyes, C a crown. */
+const POSES = {
+  working: [
+    ['..HH..', '.HEEH.', '..HH..', '.HHHH.', 'H.HH.H', '.H..H.'],
+    ['..HH..', '.HEEH.', '..HH..', 'HHHHHH', '..HH..', '..HH..'],
+  ],
+  waiting: [['..HH.H', '.HEEHH', '..HH..', '.HHH..', '..HH..', '.H..H.']],
+  quiet: [['......', '..HH..', '.HLLH.', '..HH..', '.HHHH.', '.H..H.']],
+  stalled: [['..HH..', '.HXXH.', '..HH..', '.HHHH.', '..HH..', '.H..H.']],
+  done: [['H.HH.H', 'HHEEHH', '..HH..', '..HH..', '..HH..', '.H..H.']],
+  idle: [['......', '..HH..', '.HLLH.', '..HH..', '.HHHH.', '.H..H.']],
+};
+/** What a pose reads as without its picture, and in words. */
+export const POSE_GLYPH = {
+  working: '⚙',
+  waiting: '?',
+  quiet: '…',
+  stalled: '✗',
+  done: '✓',
+  idle: '·',
+};
+
+/** Each lane's tint, fixed by its place in the config so the person learns them; the lead's is gold. */
+const TINTS = [0x4aa3ff, 0x5cc85c, 0xd070e0, 0x40c8c8, 0xff9a40, 0xff6070, 0xa0a0ff];
+export function tintOf(lane, lanes) {
+  if (lane === 'lead') return 0xd8a840;
+  const i = lanes.filter((l) => l !== 'lead').indexOf(lane);
+  return TINTS[(i < 0 ? 0 : i) % TINTS.length];
+}
+
+const dim = (rgb) =>
+  (((rgb >> 16) & 0xff) >> 1) * 0x10000 + (((rgb >> 8) & 0xff) >> 1) * 0x100 + ((rgb & 0xff) >> 1);
+
+/** The pose's frame as a grid of colours (null for none), the lead crowned. */
+export function sprite(pose, frame, tint, { lead = false } = {}) {
+  const frames = POSES[pose] ?? POSES.idle;
+  const rows = frames[frame % frames.length].map((r) => [...r]);
+  if (lead) rows[0] = [...'C.CC.C'];
+  const body = pose === 'quiet' || pose === 'idle' ? dim(tint) : tint;
+  const colour = { H: body, E: 0x202020, X: 0xff3030, L: 0x707070, C: 0xffcc00 };
+  return rows.map((r) => r.map((c) => colour[c] ?? null));
+}
+
+const DEFAULT = 0x01000000;
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function base64(bytes) {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const [a, b = 0, c = 0] = [bytes[i], bytes[i + 1], bytes[i + 2]];
+    const n = (a << 16) | (b << 8) | c;
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+    out += i + 1 < bytes.length ? B64[(n >> 6) & 63] : '=';
+    out += i + 2 < bytes.length ? B64[n & 63] : '=';
+  }
+  return out;
+}
+
+/**
+ * A sprite as a Raster's cells (VIEW-3): two pixels a cell, the upper as the half block's colour and
+ * the lower as its background. 6 columns by 3 rows.
+ */
+export function rasterCells(grid) {
+  const words = [];
+  for (let y = 0; y < grid.length; y += 2)
+    for (let x = 0; x < grid[y].length; x++) {
+      const top = grid[y][x];
+      const bottom = grid[y + 1]?.[x] ?? null;
+      if (top === null && bottom === null) words.push(0x20, DEFAULT, DEFAULT);
+      else if (top === null) words.push(0x2584, bottom, DEFAULT);
+      else words.push(0x2580, top, bottom ?? DEFAULT);
+    }
+  const bytes = [];
+  for (const w of words)
+    bytes.push(w & 0xff, (w >>> 8) & 0xff, (w >>> 16) & 0xff, (w >>> 24) & 0xff);
+  return base64(bytes);
+}
+
+const hex = (rgb) => `#${rgb.toString(16).padStart(6, '0')}`;
+
+/** A sprite as SVG for Desktop, the working pose's frames alternating (SMIL), 4 px a pixel. */
+export function spriteSvg(pose, tint, { lead = false } = {}) {
+  const frames = (POSES[pose] ?? POSES.idle).map((_, f) => sprite(pose, f, tint, { lead }));
+  const rects = (grid) =>
+    grid
+      .flatMap((row, y) =>
+        row.map((c, x) =>
+          c === null
+            ? ''
+            : `<rect x="${x * 4}" y="${y * 4}" width="4" height="4" fill="${hex(c)}"/>`,
+        ),
+      )
+      .join('');
+  const groups = frames.map((g, f) =>
+    frames.length > 1
+      ? `<g visibility="${f ? 'hidden' : 'visible'}"><animate attributeName="visibility" values="${f ? 'hidden;visible' : 'visible;hidden'}" dur="0.8s" repeatCount="indefinite" calcMode="discrete"/>${rects(g)}</g>`
+      : `<g>${rects(g)}</g>`,
+  );
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" shape-rendering="crispEdges">${groups.join('')}</svg>`;
+}
+
+/**
+ * A lane's pose (VIEW-3): stalled when flagged or quiet past the restart time, waiting while a call
+ * of its is held or its request is open, working while its agent is at work, quiet when it has
+ * gone quiet, done once its branch is finished, idle otherwise.
+ */
+export function poseOf(
+  lane,
+  { live = null, waiting = false, flagged = false, shown = lane.state } = {},
+) {
+  if (flagged || live?.level === 'stalled') return 'stalled';
+  if (waiting) return 'waiting';
+  if (live?.level === 'quiet') return 'quiet';
+  if (lane.active) return 'working';
+  if (['in review', 'queued'].includes(shown)) return 'done';
+  return 'idle';
+}
+
+// --- the timelines (VIEW-2) ----------------------------------------------------------------------
+
+/** Each cell kind's glyph and colour: the glyph alone reads in a terminal without colour. */
+export const BAR = {
+  building: { glyph: '█', color: 'blue' },
+  review: { glyph: '▒', color: 'yellow' },
+  sentBack: { glyph: '↩', color: 'magenta' },
+  approval: { glyph: '◆', color: 'cyan' },
+  merged: { glyph: '✓', color: 'green' },
+  none: { glyph: ' ', color: undefined },
+};
+
+/** Where the shared axis starts: the earliest start among the lanes' stories, at most a day back. */
+export function axisStart(times, now) {
+  const starts = times.map((t) => t.started).filter((t) => t !== null && t !== undefined);
+  return starts.length ? Math.max(Math.min(...starts), now - 24 * 3600000) : now - 3600000;
+}
+
+/**
+ * A story's bar as `width` cells from `start` to `now` (VIEW-2): building from its start, in review
+ * from its last commit once finished, ending at its merge or now; its send-backs, approvals and
+ * merge marked where they fell. [kind], a kind of BAR's.
+ */
+export function barCells(t, { start, now, width }) {
+  const span = Math.max(1, now - start) / width;
+  const finished =
+    ['review', 'in review', 'queued', 'done'].includes(t.state) && t.lastCommit !== null;
+  const end = t.merged ?? now;
+  const cells = [];
+  for (let i = 0; i < width; i++) {
+    const mid = start + (i + 0.5) * span;
+    if (t.started === null || mid < t.started || mid > end + span / 2) cells.push('none');
+    else if (finished && mid >= t.lastCommit) cells.push('review');
+    else cells.push('building');
+  }
+  const mark = (at, kind) => {
+    if (at === null || at === undefined || at < start || at > now) return;
+    cells[Math.min(width - 1, Math.floor((at - start) / span))] = kind;
+  };
+  for (const at of t.sentBack ?? []) mark(at, 'sentBack');
+  for (const a of t.approvals ?? []) mark(a.at, 'approval');
+  mark(t.merged, 'merged');
+  return cells;
+}
+
+/** Runs of the same kind, to draw as one Text each: [{ kind, n }]. */
+export function runs(cells) {
+  const out = [];
+  for (const kind of cells) {
+    if (out.at(-1)?.kind === kind) out.at(-1).n += 1;
+    else out.push({ kind, n: 1 });
+  }
+  return out;
+}
+
+/** The bars as SVG for Desktop: a row per lane, the same kinds and colours. */
+export function timelineSvg(rows, { width = 480, rowHeight = 10 } = {}) {
+  const FILL = {
+    building: '#4aa3ff',
+    review: '#e0c040',
+    sentBack: '#d070e0',
+    approval: '#40c8c8',
+    merged: '#5cc85c',
+  };
+  const cell = width / Math.max(1, rows[0]?.cells.length ?? 1);
+  const rects = rows
+    .flatMap((r, y) =>
+      r.cells.map((k, x) =>
+        k === 'none'
+          ? ''
+          : `<rect x="${(x * cell).toFixed(1)}" y="${y * (rowHeight + 4)}" width="${cell.toFixed(1)}" height="${rowHeight}" fill="${FILL[k]}"/>`,
+      ),
+    )
+    .join('');
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${rows.length * (rowHeight + 4)}" shape-rendering="crispEdges">${rects}</svg>`;
+}