@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/visualization/renderers/ascii/info.js

@@ -10,6 +10,10 @@ import { padRight } from '../../utils/unicode.js';
 import { timeAgo } from '../../utils/time.js';
 import { TIMELINE } from './symbols.js';
 
+/**
+ * @typedef {{ name: string, writers?: { count?: number, ids?: string[] }, checkpoint?: { sha?: string, date?: string | Date }, coverage?: { sha?: string }, writerPatches?: Record<string, number> }} GraphInfo
+ */
+
 // Box drawing characters (info.js uses verbose key names for card rendering)
 const BOX = {
   topLeft: '\u250C',     // ┌
@@ -77,7 +81,7 @@ function formatWriterNames(writerIds) {
 
 /**
  * Renders the header lines for a graph card.
- * @param {Object} graph - Graph info object
+ * @param {GraphInfo} graph - Graph info object
  * @param {number} contentWidth - Available content width
  * @returns {string[]} Header lines
  */
@@ -102,7 +106,7 @@ function renderCardHeader(graph, contentWidth) {
 
 /**
  * Renders writer timeline lines for a graph card.
- * @param {Object} writerPatches - Map of writerId to patch count
+ * @param {Record<string, number> | undefined} writerPatches - Map of writerId to patch count
  * @param {number} contentWidth - Available content width
  * @returns {string[]} Timeline lines
  */
@@ -133,7 +137,7 @@ function renderWriterTimelines(writerPatches, contentWidth) {
 
 /**
  * Renders checkpoint and coverage lines for a graph card.
- * @param {Object} graph - Graph info object
+ * @param {GraphInfo} graph - Graph info object
  * @param {number} contentWidth - Available content width
  * @returns {string[]} Status lines
  */
@@ -169,7 +173,7 @@ function renderCardStatus(graph, contentWidth) {
 
 /**
  * Renders a single graph card.
- * @param {Object} graph - Graph info object
+ * @param {GraphInfo} graph - Graph info object
  * @param {number} innerWidth - Available width inside the card
  * @returns {string[]} Array of lines for this graph card
  */
@@ -186,9 +190,7 @@ function renderGraphCard(graph, innerWidth) {
 
 /**
  * Renders the info view with ASCII box art.
- * @param {Object} data - Info payload from handleInfo
- * @param {string} data.repo - Repository path
- * @param {Object[]} data.graphs - Array of graph info objects
+ * @param {{ repo?: string, graphs: GraphInfo[] }} data - Info payload from handleInfo
  * @returns {string} Formatted ASCII output
  */
 export function renderInfoView(data) {

package/src/visualization/renderers/ascii/materialize.js

@@ -12,6 +12,11 @@ import { padRight } from '../../utils/unicode.js';
 import { truncate } from '../../utils/truncate.js';
 import { formatNumber, formatSha } from './formatters.js';
 
+/**
+ * @typedef {{ graph: string, error?: string, noOp?: boolean, patchCount?: number, nodes?: number, edges?: number, properties?: number, writers?: Record<string, number>, checkpoint?: string | null }} GraphResult
+ * @typedef {{ maxNodes: number, maxEdges: number, maxProps: number }} MaxValues
+ */
+
 // Bar chart settings
 const BAR_WIDTH = 20;
 const STAT_LABEL_WIDTH = 12;
@@ -55,15 +60,15 @@ function renderErrorState(errorMessage) {
 
 /**
  * Render no-op state (already materialized).
- * @param {Object} graph - Graph data
+ * @param {GraphResult} graph - Graph data
  * @returns {string[]} No-op state lines
  */
 function renderNoOpState(graph) {
   const lines = [
     `  ${colors.success('\u2713')} Already materialized (no new patches)`,
     '',
-    `  ${padRight('Nodes:', STAT_LABEL_WIDTH)} ${formatNumber(graph.nodes)}`,
-    `  ${padRight('Edges:', STAT_LABEL_WIDTH)} ${formatNumber(graph.edges)}`,
+    `  ${padRight('Nodes:', STAT_LABEL_WIDTH)} ${formatNumber(graph.nodes || 0)}`,
+    `  ${padRight('Edges:', STAT_LABEL_WIDTH)} ${formatNumber(graph.edges || 0)}`,
   ];
   if (typeof graph.properties === 'number') {
     lines.push(`  ${padRight('Properties:', STAT_LABEL_WIDTH)} ${formatNumber(graph.properties)}`);
@@ -73,7 +78,7 @@ function renderNoOpState(graph) {
 
 /**
  * Render empty graph state (0 patches).
- * @param {Object} graph - Graph data
+ * @param {GraphResult} graph - Graph data
  * @returns {string[]} Empty state lines
  */
 function renderEmptyState(graph) {
@@ -86,7 +91,7 @@ function renderEmptyState(graph) {
 
 /**
  * Render writer progress section.
- * @param {Object} writers - Writer patch counts
+ * @param {Record<string, number> | undefined} writers - Writer patch counts
  * @returns {string[]} Writer lines
  */
 function renderWriterSection(writers) {
@@ -108,15 +113,15 @@ function renderWriterSection(writers) {
 
 /**
  * Render statistics section with bar charts.
- * @param {Object} graph - Graph data
- * @param {Object} maxValues - Max values for scaling
+ * @param {GraphResult} graph - Graph data
+ * @param {MaxValues} maxValues - Max values for scaling
  * @returns {string[]} Statistics lines
  */
 function renderStatsSection(graph, { maxNodes, maxEdges, maxProps }) {
   const lines = [
     `  ${colors.dim('Statistics:')}`,
-    `  ${padRight('Nodes:', STAT_LABEL_WIDTH)} ${statBar(graph.nodes, maxNodes)} ${formatNumber(graph.nodes)}`,
-    `  ${padRight('Edges:', STAT_LABEL_WIDTH)} ${statBar(graph.edges, maxEdges)} ${formatNumber(graph.edges)}`,
+    `  ${padRight('Nodes:', STAT_LABEL_WIDTH)} ${statBar(graph.nodes || 0, maxNodes)} ${formatNumber(graph.nodes || 0)}`,
+    `  ${padRight('Edges:', STAT_LABEL_WIDTH)} ${statBar(graph.edges || 0, maxEdges)} ${formatNumber(graph.edges || 0)}`,
   ];
   if (typeof graph.properties === 'number') {
     lines.push(`  ${padRight('Properties:', STAT_LABEL_WIDTH)} ${statBar(graph.properties, maxProps)} ${formatNumber(graph.properties)}`);
@@ -139,8 +144,8 @@ function renderCheckpointInfo(checkpoint) {
 
 /**
  * Render a single graph's materialization result.
- * @param {Object} graph - Graph result from materialize
- * @param {Object} maxValues - Max values for scaling bars
+ * @param {GraphResult} graph - Graph result from materialize
+ * @param {MaxValues} maxValues - Max values for scaling bars
  * @returns {string[]} Array of lines for this graph
  */
 function renderGraphResult(graph, maxValues) {
@@ -158,14 +163,14 @@ function renderGraphResult(graph, maxValues) {
 
   lines.push(...renderWriterSection(graph.writers));
   lines.push(...renderStatsSection(graph, maxValues));
-  lines.push(...renderCheckpointInfo(graph.checkpoint));
+  lines.push(...renderCheckpointInfo(graph.checkpoint ?? null));
   return lines;
 }
 
 /**
  * Calculate max values for scaling bar charts.
- * @param {Object[]} graphs - Array of graph results
- * @returns {Object} Max values object
+ * @param {GraphResult[]} graphs - Array of graph results
+ * @returns {MaxValues} Max values object
  */
 function calculateMaxValues(graphs) {
   const successfulGraphs = graphs.filter((g) => !g.error);
@@ -212,8 +217,7 @@ function getBorderColor(successCount, errorCount) {
 
 /**
  * Render the materialize view dashboard.
- * @param {Object} payload - The materialize command payload
- * @param {Object[]} payload.graphs - Array of graph results
+ * @param {{ graphs: GraphResult[] }} payload - The materialize command payload
  * @returns {string} Formatted dashboard string
  */
 export function renderMaterializeView(payload) {

package/src/visualization/renderers/ascii/opSummary.js

@@ -8,6 +8,11 @@
 import { colors } from './colors.js';
 import { truncate } from '../../utils/truncate.js';
 
+/**
+ * @typedef {'NodeAdd' | 'EdgeAdd' | 'PropSet' | 'NodeTombstone' | 'EdgeTombstone' | 'BlobValue'} OpType
+ * @typedef {Record<OpType, number>} OpSummary
+ */
+
 // Operation type to display info mapping
 export const OP_DISPLAY = Object.freeze({
   NodeAdd: { symbol: '+', label: 'node', color: colors.success },
@@ -30,14 +35,16 @@ export const EMPTY_OP_SUMMARY = Object.freeze({
 
 /**
  * Summarizes operations in a patch.
- * @param {Object[]} ops - Array of patch operations
- * @returns {Object} Summary with counts by operation type
+ * @param {Array<{ type: string }>} ops - Array of patch operations
+ * @returns {OpSummary} Summary with counts by operation type
  */
 export function summarizeOps(ops) {
+  /** @type {OpSummary} */
   const summary = { ...EMPTY_OP_SUMMARY };
   for (const op of ops) {
-    if (op.type && summary[op.type] !== undefined) {
-      summary[op.type]++;
+    const t = /** @type {OpType} */ (op.type);
+    if (t && summary[t] !== undefined) {
+      summary[t]++;
     }
   }
   return summary;
@@ -45,17 +52,18 @@ export function summarizeOps(ops) {
 
 /**
  * Formats operation summary as a colored string.
- * @param {Object} summary - Operation counts by type
+ * @param {OpSummary | Record<string, number>} summary - Operation counts by type
  * @param {number} maxWidth - Maximum width for the summary string
  * @returns {string} Formatted summary string
  */
 export function formatOpSummary(summary, maxWidth = 40) {
+  /** @type {OpType[]} */
   const order = ['NodeAdd', 'EdgeAdd', 'PropSet', 'NodeTombstone', 'EdgeTombstone', 'BlobValue'];
   const parts = order
-    .filter((opType) => summary[opType] > 0)
+    .filter((opType) => (/** @type {Record<string, number>} */ (summary))[opType] > 0)
     .map((opType) => {
       const display = OP_DISPLAY[opType];
-      return { text: `${display.symbol}${summary[opType]}${display.label}`, color: display.color };
+      return { text: `${display.symbol}${(/** @type {Record<string, number>} */ (summary))[opType]}${display.label}`, color: display.color };
     });
 
   if (parts.length === 0) {

package/src/visualization/renderers/ascii/path.js

@@ -75,7 +75,7 @@ function createPathSegment({ nodeId, index, pathLength, edges }) {
  * Builds path segments that fit within the terminal width.
  * Wraps long paths to multiple lines.
  * @param {string[]} path - Array of node IDs
- * @param {string[]} [edges] - Optional array of edge labels (one fewer than nodes)
+ * @param {string[] | undefined} edges - Optional array of edge labels (one fewer than nodes)
  * @param {number} maxWidth - Maximum line width
  * @returns {string[]} Array of line strings
  */

package/src/visualization/renderers/ascii/seek.js

@@ -15,6 +15,30 @@ import { formatSha, formatWriterName } from './formatters.js';
 import { TIMELINE } from './symbols.js';
 import { formatOpSummary } from './opSummary.js';
 
+/**
+ * @typedef {{ ticks: number[], tipSha?: string, tickShas?: Record<number, string> }} WriterInfo
+ */
+
+/**
+ * @typedef {Object} SeekPayload
+ * @property {string} graph
+ * @property {number} tick
+ * @property {number} maxTick
+ * @property {number[]} ticks
+ * @property {number} nodes
+ * @property {number} edges
+ * @property {number} patchCount
+ * @property {Map<string, WriterInfo> | Record<string, WriterInfo>} perWriter
+ * @property {{ nodes?: number, edges?: number }} [diff]
+ * @property {Record<string, any>} [tickReceipt]
+ * @property {import('../../../domain/services/StateDiff.js').StateDiffResult | null} [structuralDiff]
+ * @property {string} [diffBaseline]
+ * @property {number | null} [baselineTick]
+ * @property {boolean} [truncated]
+ * @property {number} [totalChanges]
+ * @property {number} [shownChanges]
+ */
+
 /** Maximum number of tick columns shown in the windowed view. */
 const MAX_COLS = 9;
 
@@ -30,6 +54,7 @@ const DOT_MID = '\u00B7'; // ·
 /** Open circle used for excluded-zone patch markers. */
 const CIRCLE_OPEN = '\u25CB'; // ○
 
+/** @param {number} n @returns {string} */
 function formatDelta(n) {
   if (typeof n !== 'number' || !Number.isFinite(n) || n === 0) {
     return '';
@@ -38,10 +63,17 @@ function formatDelta(n) {
   return ` (${sign}${n})`;
 }
 
+/**
+ * @param {number} n
+ * @param {string} singular
+ * @param {string} plural
+ * @returns {string}
+ */
 function pluralize(n, singular, plural) {
   return n === 1 ? singular : plural;
 }
 
+/** @param {Record<string, any> | undefined} tickReceipt @returns {string[]} */
 function buildReceiptLines(tickReceipt) {
   if (!tickReceipt || typeof tickReceipt !== 'object') {
     return [];
@@ -200,7 +232,7 @@ function buildLane(patchSet, points, currentTick) {
  *
  * @param {Object} opts
  * @param {string} opts.writerId
- * @param {Object} opts.writerInfo - `{ ticks, tipSha, tickShas }`
+ * @param {WriterInfo} opts.writerInfo - `{ ticks, tipSha, tickShas }`
  * @param {{ points: number[] }} opts.win - Computed window
  * @param {number} opts.currentTick - Active seek cursor tick
  * @returns {string} Formatted, indented swimlane line
@@ -252,14 +284,45 @@ function buildTickPoints(ticks, tick) {
   return { allPoints, currentIdx };
 }
 
+// ============================================================================
+// Structural Diff
+// ============================================================================
+
+/** Maximum structural diff lines shown in ASCII view. */
+const MAX_DIFF_LINES = 20;
+
 /**
- * Builds the body lines for the seek dashboard.
- *
- * @param {Object} payload - Seek payload from the CLI handler
- * @returns {string[]} Lines for the box body
+ * Builds the state summary, receipt, and structural diff footer lines.
+ * @param {SeekPayload} payload
+ * @returns {string[]}
  */
+function buildFooterLines(payload) {
+  const { tick, nodes, edges, patchCount, diff, tickReceipt } = payload;
+  const lines = [];
+  lines.push('');
+  const nodesStr = `${nodes} ${pluralize(nodes, 'node', 'nodes')}${formatDelta(diff?.nodes ?? 0)}`;
+  const edgesStr = `${edges} ${pluralize(edges, 'edge', 'edges')}${formatDelta(diff?.edges ?? 0)}`;
+  lines.push(`  ${colors.bold('State:')} ${nodesStr}, ${edgesStr}, ${patchCount} ${pluralize(patchCount, 'patch', 'patches')}`);
+
+  const receiptLines = buildReceiptLines(tickReceipt);
+  if (receiptLines.length > 0) {
+    lines.push('');
+    lines.push(`  ${colors.bold(`Tick ${tick}:`)}`);
+    lines.push(...receiptLines);
+  }
+
+  const sdLines = buildStructuralDiffLines(payload, MAX_DIFF_LINES);
+  if (sdLines.length > 0) {
+    lines.push('');
+    lines.push(...sdLines);
+  }
+  lines.push('');
+  return lines;
+}
+
+/** @param {SeekPayload} payload @returns {string[]} */
 function buildSeekBodyLines(payload) {
-  const { graph, tick, maxTick, ticks, nodes, edges, patchCount, perWriter, diff, tickReceipt } = payload;
+  const { graph, tick, maxTick, ticks, perWriter } = payload;
   const lines = [];
 
   lines.push('');
@@ -272,11 +335,9 @@ function buildSeekBodyLines(payload) {
   } else {
     const { allPoints, currentIdx } = buildTickPoints(ticks, tick);
     const win = computeWindow(allPoints, currentIdx);
-
-    // Column headers with relative offsets
     lines.push(buildHeaderRow(win));
 
-    // Per-writer swimlanes
+    /** @type {Array<[string, WriterInfo]>} */
     const writerEntries = perWriter instanceof Map
       ? [...perWriter.entries()]
       : Object.entries(perWriter).map(([k, v]) => [k, v]);
@@ -286,34 +347,137 @@ function buildSeekBodyLines(payload) {
     }
   }
 
-  lines.push('');
-  const edgeLabel = pluralize(edges, 'edge', 'edges');
-  const nodeLabel = pluralize(nodes, 'node', 'nodes');
-  const patchLabel = pluralize(patchCount, 'patch', 'patches');
+  lines.push(...buildFooterLines(payload));
+  return lines;
+}
 
-  const nodesStr = `${nodes} ${nodeLabel}${formatDelta(diff?.nodes)}`;
-  const edgesStr = `${edges} ${edgeLabel}${formatDelta(diff?.edges)}`;
-  lines.push(`  ${colors.bold('State:')} ${nodesStr}, ${edgesStr}, ${patchCount} ${patchLabel}`);
+/**
+ * Builds a truncation hint line when entries exceed the display or data limit.
+ * @param {{totalEntries: number, shown: number, maxLines: number, truncated?: boolean, totalChanges?: number, shownChanges?: number}} opts
+ * @returns {string|null}
+ */
+function buildTruncationHint(opts) {
+  const { totalEntries, shown, maxLines, truncated, totalChanges, shownChanges } = opts;
+  if (totalEntries > maxLines && truncated) {
+    const remaining = Math.max(0, (totalChanges || 0) - shown);
+    return `... and ${remaining} more changes (${totalChanges} total, use --diff-limit to increase)`;
+  }
+  if (totalEntries > maxLines) {
+    return `... and ${Math.max(0, totalEntries - maxLines)} more changes`;
+  }
+  if (truncated) {
+    return `... and ${Math.max(0, (totalChanges || 0) - (shownChanges || 0))} more changes (use --diff-limit to increase)`;
+  }
+  return null;
+}
 
-  const receiptLines = buildReceiptLines(tickReceipt);
-  if (receiptLines.length > 0) {
-    lines.push('');
-    lines.push(`  ${colors.bold(`Tick ${tick}:`)}`);
-    lines.push(...receiptLines);
+/**
+ * @param {SeekPayload} payload
+ * @param {number} maxLines
+ * @returns {string[]}
+ */
+function buildStructuralDiffLines(payload, maxLines) {
+  const { structuralDiff, diffBaseline, baselineTick, truncated, totalChanges, shownChanges } = payload;
+  if (!structuralDiff) {
+    return [];
+  }
+
+  const lines = [];
+  const baselineLabel = diffBaseline === 'tick'
+    ? `baseline: tick ${baselineTick}`
+    : 'baseline: empty';
+
+  lines.push(`  ${colors.bold(`Changes (${baselineLabel}):`)}`);
+
+  let shown = 0;
+  const entries = collectDiffEntries(structuralDiff);
+
+  for (const entry of entries) {
+    if (shown >= maxLines) {
+      break;
+    }
+    lines.push(`    ${entry}`);
+    shown++;
+  }
+
+  const hint = buildTruncationHint({ totalEntries: entries.length, shown, maxLines, truncated, totalChanges, shownChanges });
+  if (hint) {
+    lines.push(`    ${colors.muted(hint)}`);
   }
-  lines.push('');
 
   return lines;
 }
 
+/**
+ * Collects formatted diff entries from a structural diff result.
+ *
+ * @param {import('../../../domain/services/StateDiff.js').StateDiffResult} diff
+ * @returns {string[]} Formatted entries with +/-/~ prefixes
+ */
+function collectDiffEntries(diff) {
+  const entries = [];
+
+  for (const nodeId of diff.nodes.added) {
+    entries.push(colors.success(`+ node ${nodeId}`));
+  }
+  for (const nodeId of diff.nodes.removed) {
+    entries.push(colors.error(`- node ${nodeId}`));
+  }
+  for (const edge of diff.edges.added) {
+    entries.push(colors.success(`+ edge ${edge.from} -[${edge.label}]-> ${edge.to}`));
+  }
+  for (const edge of diff.edges.removed) {
+    entries.push(colors.error(`- edge ${edge.from} -[${edge.label}]-> ${edge.to}`));
+  }
+  for (const prop of diff.props.set) {
+    const old = prop.oldValue !== undefined ? formatPropValue(prop.oldValue) : null;
+    const arrow = old !== null ? `${old} -> ${formatPropValue(prop.newValue)}` : formatPropValue(prop.newValue);
+    entries.push(colors.warning(`~ ${prop.nodeId}.${prop.propKey}: ${arrow}`));
+  }
+  for (const prop of diff.props.removed) {
+    entries.push(colors.error(`- ${prop.nodeId}.${prop.propKey}: ${formatPropValue(prop.oldValue)}`));
+  }
+
+  return entries;
+}
+
+/**
+ * Formats a property value for display (truncated if too long).
+ * @param {*} value
+ * @returns {string}
+ */
+function formatPropValue(value) {
+  if (value === undefined) {
+    return 'undefined';
+  }
+  const s = typeof value === 'string' ? `"${value}"` : String(value);
+  return s.length > 40 ? `${s.slice(0, 37)}...` : s;
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
+/**
+ * Formats a structural diff as a plain-text string (no boxen).
+ *
+ * Used by the non-view renderSeek() path in the CLI.
+ *
+ * @param {SeekPayload} payload - Seek payload containing structuralDiff
+ * @returns {string} Formatted diff section, or empty string if no diff
+ */
+export function formatStructuralDiff(payload) {
+  const lines = buildStructuralDiffLines(payload, MAX_DIFF_LINES);
+  if (lines.length === 0) {
+    return '';
+  }
+  return `${lines.join('\n')}\n`;
+}
+
 /**
  * Renders the seek view dashboard inside a double-bordered box.
  *
- * @param {Object} payload - Seek payload from the CLI handler
+ * @param {SeekPayload} payload - Seek payload from the CLI handler
  * @returns {string} Boxen-wrapped ASCII dashboard with trailing newline
  */
 export function renderSeekView(payload) {

package/src/visualization/renderers/ascii/table.js

@@ -6,7 +6,7 @@ import Table from 'cli-table3';
  * @param {Object} [options] - Options forwarded to cli-table3 constructor
  * @param {string[]} [options.head] - Column headers
  * @param {Object} [options.style] - Style overrides (defaults: head=cyan, border=gray)
- * @returns {import('cli-table3')} A cli-table3 instance
+ * @returns {InstanceType<typeof Table>} A cli-table3 instance
  */
 export function createTable(options = {}) {
   const defaultStyle = { head: ['cyan'], border: ['gray'] };

package/src/visualization/renderers/svg/index.js

@@ -16,6 +16,7 @@ const PALETTE = {
   arrowFill: '#a6adc8',
 };
 
+/** @param {string} str @returns {string} */
 function escapeXml(str) {
   return String(str)
     .replace(/&/g, '&')
@@ -46,6 +47,7 @@ function renderStyle() {
   ].join('\n');
 }
 
+/** @param {{ id: string, x: number, y: number, width: number, height: number, label?: string }} node @returns {string} */
 function renderNode(node) {
   const { x, y, width, height } = node;
   const label = escapeXml(node.label ?? node.id);
@@ -59,6 +61,7 @@ function renderNode(node) {
   ].join('\n');
 }
 
+/** @param {{ startPoint?: { x: number, y: number }, bendPoints?: Array<{ x: number, y: number }>, endPoint?: { x: number, y: number } }} section @returns {Array<{ x: number, y: number }>} */
 function sectionToPoints(section) {
   const pts = [];
   if (section.startPoint) {
@@ -73,6 +76,7 @@ function sectionToPoints(section) {
   return pts;
 }
 
+/** @param {{ sections?: Array<{ startPoint?: { x: number, y: number }, bendPoints?: Array<{ x: number, y: number }>, endPoint?: { x: number, y: number } }>, label?: string }} edge @returns {string} */
 function renderEdge(edge) {
   const { sections } = edge;
   if (!sections || sections.length === 0) {
@@ -115,7 +119,7 @@ function renderEdge(edge) {
 /**
  * Renders a PositionedGraph as an SVG string.
  *
- * @param {Object} positionedGraph - PositionedGraph from runLayout()
+ * @param {{ nodes?: Array<{ id: string, x: number, y: number, width: number, height: number, label?: string }>, edges?: Array<{ sections?: Array<any>, label?: string }>, width?: number, height?: number }} positionedGraph - PositionedGraph from runLayout()
  * @param {{ title?: string }} [options]
  * @returns {string} Complete SVG markup
  */