@warren-dean/code-kit 0.7.0 → 0.8.1

package/hooks/mod/panes.mjs

@@ -1,12 +1,20 @@
 // Panes v2 (docs/specs/11-panes.md): the Lanes pane's frame. A counts header, tabs, what needs the
 // person, the tab's body and the keys, as pure functions of what the mod already holds. The Lanes
 // tab's body is view.mjs's lanesPane; the Queue and Usage tabs reuse its sections.
+import { trailRows as trailRowsDrawn, trailSvg } from './trail.mjs';
+import {
+  MAP_LEGEND,
+  cardOf,
+  mapRows as codeRows,
+  mapStoryOf,
+  mapSvg,
+  neighboursOf,
+} from './codemap.mjs';
 import {
   NOT_CODE_KIT,
   STATE_COLOR,
   ago,
   lanesPane,
-  loopSection,
   queueSection,
   shownState,
   tokens,
@@ -15,9 +23,12 @@ import {
 
 export const TABS = [
   { id: 'lanes', label: 'Lanes', hotkey: '1' },
-  { id: 'queue', label: 'Queue', hotkey: '2' },
-  { id: 'usage', label: 'Usage', hotkey: '3' },
-  { id: 'map', label: 'Map', hotkey: '4' },
+  { id: 'decisions', label: 'Decisions', hotkey: '2' },
+  { id: 'journal', label: 'Journal', hotkey: '3' },
+  { id: 'code', label: 'Code map', hotkey: '4' },
+  { id: 'map', label: 'Trail', hotkey: '5' },
+  { id: 'queue', label: 'Queue', hotkey: '6' },
+  { id: 'usage', label: 'Usage', hotkey: '7' },
 ];
 
 /** The pane's own state, kept by the mod between draws. */
@@ -173,6 +184,8 @@ export function lanesFrame(view, els, on) {
       children: [
         text('!', { color: 'yellow', bold: true }),
         text(line.text, { bold: true }),
+        // DECIDE-2: which story it's for.
+        ...(line.context ? [text(line.context, { dimColor: true, wrap: 'truncate-end' })] : []),
         ...actions.map((a) => {
           const letter = LETTER[a.id] && !used.has(LETTER[a.id]) ? LETTER[a.id] : undefined;
           if (letter) used.add(letter);
@@ -254,35 +267,48 @@ export function lanesFrame(view, els, on) {
 
   const selected = state.lanes.find((l) => l.name === ui.selected) ?? null;
   const body =
-    ui.tab === 'map'
-      ? mapTab(view.status, ui.cell, els, on)
-      : ui.tab === 'queue'
-        ? queueSection(loop, text, Box)
-        : ui.tab === 'usage'
-          ? usageSection(view.usage, plan, text, Box)
-          : [
-              lanesPane(state, els, view.usage, plan, loop, {
-                filter: ui.filter,
-                search: ui.search,
-                selected: ui.selected,
-                live: view.live ?? {},
-                art: view.art ?? null,
-                detail: selected
-                  ? {
-                      owns: view.paths?.[selected.name] ?? [],
-                      stories: laneStories(selected, state),
-                    }
-                  : null,
-                combined: view.combined ?? null,
-              }),
-              ...loopSection(loop, text, Box),
-            ];
+    ui.tab === 'decisions'
+      ? decisionsTab(view.cards ?? [], ui, els, on)
+      : ui.tab === 'journal'
+        ? journalTab(view.journal ?? [], els, view.now)
+        : ui.tab === 'code'
+          ? codeTab(view, els, on)
+          : ui.tab === 'map'
+            ? mapTab(view.status, ui.cell, els, on, view.trail, {
+                surface: view.surface,
+                columns: view.columns,
+              })
+            : ui.tab === 'queue'
+              ? queueSection(loop, text, Box)
+              : ui.tab === 'usage'
+                ? usageSection(view.usage, plan, text, Box)
+                : [
+                    lanesPane(state, els, view.usage, plan, loop, {
+                      filter: ui.filter,
+                      search: ui.search,
+                      selected: ui.selected,
+                      live: view.live ?? {},
+                      art: view.art ?? null,
+                      detail: selected
+                        ? {
+                            agent: selected.agent ?? null,
+                            owns: view.paths?.[selected.name] ?? [],
+                            stories: laneStories(selected, state),
+                          }
+                        : null,
+                      combined: view.combined ?? null,
+                    }),
+                  ];
   const empty =
-    ui.tab === 'queue'
-      ? 'The merge queue is empty.'
-      : ui.tab === 'usage'
-        ? 'No usage measured yet this session.'
-        : null;
+    ui.tab === 'decisions'
+      ? 'Nothing needs you. The lead is handling the build.'
+      : ui.tab === 'journal'
+        ? 'Nothing recorded yet: the journal starts with the brief.'
+        : ui.tab === 'queue'
+          ? 'The merge queue is empty.'
+          : ui.tab === 'usage'
+            ? 'No usage measured yet this session.'
+            : null;
 
   // VIEW-6: j/k move between lanes; the selected lane's acts; f filters.
   const opening = selected ? storyToOpen(selected, state) : null;
@@ -819,7 +845,14 @@ export function moveCell(requirements, id, step, { rows = false } = {}) {
  * The Map tab (TRACE-1 to TRACE-4): a row per spec, a cell per requirement, a legend, and the
  * selected requirement's stories and tests. `status` is `code-kit status --json`'s.
  */
-export function mapTab(status, selectedId, { Box, Text, Button, Select }, on) {
+export function mapTab(
+  status,
+  selectedId,
+  { Box, Text, Button, Select, Svg },
+  on,
+  trail = null,
+  { surface = 'terminal', columns = 100 } = {},
+) {
   const text = (value, style = {}) => Text({ ...style, children: [value] });
   const requirements = status?.requirements ?? [];
   if (!requirements.length)
@@ -929,6 +962,28 @@ export function mapTab(status, selectedId, { Box, Text, Button, Select }, on) {
             ),
           )
         : [text('No story delivers it yet: a gap in the plan.', { color: 'red' })]),
+      // TRAIL-1: the code its stories changed, once the trail is read.
+      ...(() => {
+        const row = trail?.requirements?.find((r) => r.id === selected.id);
+        if (!row) return [];
+        return row.files.length
+          ? [
+              text(`Code its stories changed (${row.files.length})`, { bold: true }),
+              Box({
+                key: 'map-files',
+                children: [
+                  text(
+                    `  ${row.files
+                      .slice(0, 6)
+                      .map((f) => f.split('/').pop())
+                      .join(', ')}${row.files.length > 6 ? ', …' : ''}`,
+                    { dimColor: true, wrap: 'truncate-end' },
+                  ),
+                ],
+              }),
+            ]
+          : [text('No code changed for it yet.', { dimColor: true })];
+      })(),
       ...(selected.tests?.length
         ? [
             text('Tests that name it', { bold: true }),
@@ -939,5 +994,385 @@ export function mapTab(status, selectedId, { Box, Text, Button, Select }, on) {
         : [text('No test names it.', { dimColor: true })]),
     ],
   });
-  return [legend, grid, keys, detail];
+  // TRAIL-1: the selected requirement's spec as a trail: each requirement to its stories, the code
+  // they changed and the tests that name it, a gap where any link is missing.
+  const spec = selected.file;
+  const trailRows = (trail?.requirements ?? []).filter(
+    (r) =>
+      r.spec === spec?.split('/').pop() && requirements.find((q) => q.id === r.id)?.file === spec,
+  );
+  const TONE = {
+    req: {},
+    selected: { bold: true, color: 'cyan' },
+    dim: { dimColor: true },
+    done: { color: 'green' },
+    moving: { color: 'blue' },
+    waiting: { color: 'red' },
+    gap: { color: 'red' },
+    test: { color: 'green' },
+  };
+  const flow =
+    surface && surface !== 'terminal' && Svg
+      ? Svg({
+          source: trailSvg(trailRows, { selected: selected.id }),
+          alt: `${label(spec)}'s trail: each requirement to its stories, code and tests`,
+        })
+      : Box({
+          key: 'trail-flow',
+          flexDirection: 'column',
+          children: trailRowsDrawn(trailRows, { selected: selected.id, width: columns }).map(
+            (runs, i) =>
+              Box({
+                key: `trail-${trailRows[i].id}`,
+                flexDirection: 'row',
+                children: runs.map((r) => text(r.text, TONE[r.style] ?? {})),
+              }),
+          ),
+        });
+  const trailBox = trailRows.length
+    ? [
+        Box({
+          key: 'trail',
+          flexDirection: 'column',
+          children: [text(`Trail · ${label(spec)}`, { bold: true }), flow],
+        }),
+      ]
+    : [];
+  return [legend, grid, keys, ...trailBox, detail];
+}
+
+/** A tint darkened toward the terminal's ground, for a glowing box's fill: `share` of the tint kept. */
+const shade = (hex, share) => {
+  const n = Number.parseInt(String(hex).replace('#', ''), 16);
+  if (!Number.isFinite(n)) return undefined;
+  const c = (v) => Math.round(((n >> v) & 0xff) * share + 14 * (1 - share));
+  return `#${[16, 8, 0].map((v) => c(v).toString(16).padStart(2, '0')).join('')}`;
+};
+
+/** A code map run's text style: its lane's tint where it glows, a fill inside a glowing box. */
+function runStyle(r, tints) {
+  const tint = r.lane ? (tints[r.lane] ?? '#5fb3b3') : null;
+  if (tint && (r.style === 'fill-read' || r.style === 'fill-edit'))
+    return {
+      backgroundColor: shade(tint, r.style === 'fill-edit' ? 0.45 : 0.28),
+      color: 'white',
+      ...(r.style === 'fill-edit' ? { bold: true } : {}),
+    };
+  if (tint && (r.style === 'reading' || r.style === 'editing'))
+    return { color: tint, bold: r.style === 'editing' };
+  return RUN_STYLE[r.style] ?? {};
+}
+
+/** The colour each style of the code map's runs takes, the lane's tint where it glows. */
+const RUN_STYLE = {
+  dim: { dimColor: true },
+  node: {},
+  selected: { color: 'cyan', bold: true },
+  ok: { color: 'green' },
+  warn: { color: 'yellow' },
+};
+
+/**
+ * MAP-1 to MAP-4: the Code map tab: the stories to choose from, the story's files by layer with their
+ * imports (glowing where a lane reads or edits them), and the selected file's card and neighbours.
+ * `view` holds { state, codeMap, ui, glow, art, surface, columns }; `on` holds onMapStory(id),
+ * onMapFile(path), onOpenFile(path).
+ */
+export function codeTab(view, { Box, Text, Button, Svg }, on) {
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  const { state, ui = DEFAULT_UI, codeMap: map = null, glow = {}, art = null } = view;
+  const storyId = mapStoryOf(state, ui.selected, ui.mapStory);
+  const choices = (state?.stories ?? []).filter(
+    (s) => s.id === storyId || ['in progress', 'review', 'sent back'].includes(s.state),
+  );
+  const picker = Box({
+    key: 'map-stories',
+    flexDirection: 'row',
+    columnGap: 1,
+    flexWrap: 'wrap',
+    children: choices.map((s) =>
+      Button({
+        key: `map-story-${s.id}`,
+        label: `${s.id} ${s.title}`,
+        ...(s.id === storyId ? { variant: 'primary' } : { plain: true }),
+        onPress: () => on.onMapStory(s.id),
+      }),
+    ),
+  });
+  if (!storyId) return [text('No story to map yet: the plan has none open.', { dimColor: true })];
+  if (!map || map.story?.id !== storyId)
+    return [picker, text(`Reading ${storyId}'s code…`, { dimColor: true })];
+  if (!map.files.length)
+    return [picker, text(`${storyId} hasn't changed any code yet.`, { dimColor: true })];
+  const selected = map.files.some((f) => f.path === ui.mapFile) ? ui.mapFile : map.files[0].path;
+  // The lanes' tints are RGB numbers (the characters' colours); text and SVG take them as hex.
+  const tints = Object.fromEntries(
+    Object.entries(art?.tints ?? {}).map(([lane, rgb]) => [
+      lane,
+      typeof rgb === 'number' ? `#${rgb.toString(16).padStart(6, '0')}` : rgb,
+    ]),
+  );
+  const width = Math.max(40, (view.columns ?? 100) - 4);
+  const drawing =
+    view.surface !== 'terminal' && Svg
+      ? Svg({
+          source: mapSvg(map, { glow, selected, tints, width }),
+          alt: `${storyId}'s code: ${map.files.length} files by layer`,
+          isInteractive: true,
+        })
+      : Box({
+          key: 'code-map',
+          flexDirection: 'column',
+          children: codeRows(map, { glow, selected, width }).map((runs, y) =>
+            Box({
+              key: `code-row-${y}`,
+              flexDirection: 'row',
+              children: runs.map((r) => text(r.text, runStyle(r, tints))),
+            }),
+          ),
+        });
+  const at = map.files.findIndex((f) => f.path === selected);
+  const file = map.files[at];
+  const card = cardOf(file);
+  const near = neighboursOf(map, selected);
+  const short = (p) => p.split('/').pop();
+  const detail = Box({
+    key: 'code-file',
+    flexDirection: 'column',
+    borderStyle: 'round',
+    borderColor: 'gray',
+    paddingX: 1,
+    children: [
+      text(selected, { bold: true }),
+      text(`${file.layer}${file.lane ? ` · ${file.lane} lane` : ''}`, { dimColor: true }),
+      ...(card
+        ? [
+            text(
+              card.state === 'missing'
+                ? 'No why written yet: Context Graph keeps one as a card once it is.'
+                : card.text,
+              card.state === 'current' ? {} : { color: 'yellow' },
+            ),
+            ...(card.state === 'stale'
+              ? [text('The file changed since its why was written.', { dimColor: true })]
+              : []),
+          ]
+        : []),
+      ...(near.imports.length
+        ? [text(`imports ${near.imports.map(short).join(', ')}`, { dimColor: true })]
+        : []),
+      ...(near.importers.length
+        ? [text(`imported by ${near.importers.map(short).join(', ')}`, { dimColor: true })]
+        : []),
+    ],
+  });
+  const keys = Box({
+    key: 'code-keys',
+    flexDirection: 'row',
+    columnGap: 1,
+    children: [
+      Button({
+        key: 'code-next',
+        label: 'Next file',
+        hotkey: 'j',
+        plain: true,
+        onPress: () => on.onMapFile(map.files[(at + 1) % map.files.length].path),
+      }),
+      Button({
+        key: 'code-prev',
+        label: 'Previous',
+        hotkey: 'k',
+        plain: true,
+        onPress: () => on.onMapFile(map.files[(at - 1 + map.files.length) % map.files.length].path),
+      }),
+      ...(map.open
+        ? [
+            Button({
+              key: 'code-open',
+              label: 'Open in Context Graph',
+              hotkey: 'o',
+              plain: true,
+              onPress: () => on.onOpenFile(selected),
+            }),
+          ]
+        : []),
+    ],
+  });
+  const legend = Box({
+    key: 'code-legend',
+    flexDirection: 'row',
+    columnGap: 2,
+    flexWrap: 'wrap',
+    children: MAP_LEGEND.map((l) =>
+      text(
+        l.text,
+        l.style === 'glow' ? { color: tints[file.lane] ?? 'cyan' } : (RUN_STYLE[l.style] ?? {}),
+      ),
+    ),
+  });
+  return [picker, drawing, legend, detail, keys];
+}
+
+/**
+ * DECIDE-3: the Decisions tab: each decision that needs the person, the selected one as a card with its
+ * lineage (what they asked for, the story and requirements, what was happening, what's settled, why it
+ * needs them) and its options, each saying what it does. `on`: onDecision(i), onNeed(id, line).
+ */
+export function decisionsTab(cards, ui, { Box, Text, Button }, on) {
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  if (!cards.length) return [];
+  const at = Math.min(ui.decision ?? 0, cards.length - 1);
+  const card = cards[at];
+  const row = (label, value, style = {}) =>
+    Box({
+      key: `decision-${label}`,
+      flexDirection: 'row',
+      columnGap: 1,
+      children: [
+        text(label.padEnd(15), { dimColor: true }),
+        text(value, { wrap: 'wrap', ...style }),
+      ],
+    });
+  const list = Box({
+    key: 'decision-list',
+    flexDirection: 'column',
+    children: cards.map((c, i) =>
+      Button({
+        key: `decision-pick-${i}`,
+        label: `${i === at ? '›' : ' '} ${c.title}`,
+        plain: true,
+        onPress: () => on.onDecision(i),
+      }),
+    ),
+  });
+  const detail = Box({
+    key: 'decision-card',
+    flexDirection: 'column',
+    borderStyle: 'round',
+    borderColor: 'yellow',
+    paddingX: 1,
+    rowGap: 0,
+    children: [
+      text(card.title, { bold: true }),
+      ...(card.asked ? [row('You asked for', card.asked)] : []),
+      ...(card.story
+        ? [
+            row(
+              'Story',
+              `${card.story.id} ${card.story.title}${card.story.branch ? ` · ${card.story.branch}` : ''}`,
+            ),
+          ]
+        : []),
+      ...(card.requirements.length
+        ? [
+            row(
+              'Requirements',
+              card.requirements.map((r) => `${r.id}${r.title ? ` ${r.title}` : ''}`).join('; '),
+            ),
+          ]
+        : []),
+      ...(card.doing ? [row('Happening', card.doing)] : []),
+      ...(card.settled.length
+        ? [
+            text('Already settled', { dimColor: true }),
+            ...card.settled.map((line, i) =>
+              Box({
+                key: `decision-settled-${i}`,
+                children: [text(`  · ${line}`, { wrap: 'wrap' })],
+              }),
+            ),
+          ]
+        : []),
+      ...(card.why ? [row('Why it is yours', card.why, { color: 'yellow' })] : []),
+      text('Your options', { dimColor: true }),
+      ...card.options.map((o) =>
+        Box({
+          key: `decision-option-${o.id}`,
+          flexDirection: 'row',
+          columnGap: 2,
+          children: [
+            Button({
+              key: `decide-${o.id}`,
+              label: o.label,
+              ...(o.hotkey ? { hotkey: o.hotkey } : {}),
+              variant: 'primary',
+              onPress: () => on.onNeed(o.id, card.line),
+            }),
+            ...(o.effect ? [text(o.effect, { dimColor: true, wrap: 'wrap' })] : []),
+          ],
+        }),
+      ),
+    ],
+  });
+  return [
+    text(
+      `${cards.length} decision${cards.length === 1 ? '' : 's'} need${cards.length === 1 ? 's' : ''} you. Everything else is the lead's.`,
+      { bold: true },
+    ),
+    ...(cards.length > 1 ? [list] : []),
+    detail,
+  ];
+}
+
+const JOURNAL_GLYPH = {
+  request: '✦',
+  decision: '◆',
+  spec: '▤',
+  setup: '⚙',
+  dispatch: '→',
+  sentBack: '↩',
+  merge: '✓',
+  approval: '✔',
+  milestone: '★',
+  loop: '·',
+};
+
+/**
+ * JOURNAL-1: the Journal tab: the build's lineage, newest last, each event with its time and a glyph,
+ * your own approvals and choices marked. The latest 60 are drawn.
+ */
+export function journalTab(events, { Box, Text }, now = Date.now()) {
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  if (!events.length) return [];
+  const shown = events.slice(-60);
+  const day = (at) => new Date(at).toISOString().slice(0, 10);
+  const time = (at) => new Date(at).toISOString().slice(11, 16);
+  const rows = [];
+  let lastDay = null;
+  shown.forEach((e, i) => {
+    if (day(e.at) !== lastDay) {
+      lastDay = day(e.at);
+      rows.push(
+        Box({ key: `journal-day-${i}`, children: [text(lastDay, { bold: true, dimColor: true })] }),
+      );
+    }
+    const yours = e.who === 'person' || e.kind === 'request';
+    rows.push(
+      Box({
+        key: `journal-${i}`,
+        flexDirection: 'row',
+        columnGap: 1,
+        children: [
+          text(time(e.at), { dimColor: true }),
+          text(JOURNAL_GLYPH[e.kind] ?? '·', {
+            color: yours
+              ? 'yellow'
+              : e.kind === 'merge' || e.kind === 'milestone'
+                ? 'green'
+                : e.kind === 'sentBack'
+                  ? 'magenta'
+                  : undefined,
+          }),
+          text(e.text, { wrap: 'wrap', ...(yours ? { color: 'yellow' } : {}) }),
+        ],
+      }),
+    );
+  });
+  return [
+    text(
+      `From your request to now: ${events.length} event${events.length === 1 ? '' : 's'}${events.length > shown.length ? `, the latest ${shown.length} shown` : ''}. Yours are in yellow.`,
+      { dimColor: true },
+    ),
+    Box({ key: 'journal', flexDirection: 'column', children: rows }),
+  ];
 }