@git-stunts/git-warp 10.1.2 → 10.4.2

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

@@ -6,79 +6,20 @@
 import { colors } from './colors.js';
 import { createBox } from './box.js';
 import { padRight, padLeft } from '../../utils/unicode.js';
-import { truncate } from '../../utils/truncate.js';
 import { TIMELINE } from './symbols.js';
-
-// Default pagination settings
-const DEFAULT_PAGE_SIZE = 20;
-
-// Operation type to display info mapping
-const OP_DISPLAY = {
-  NodeAdd: { symbol: '+', label: 'node', color: colors.success },
-  NodeTombstone: { symbol: '-', label: 'node', color: colors.error },
-  EdgeAdd: { symbol: '+', label: 'edge', color: colors.success },
-  EdgeTombstone: { symbol: '-', label: 'edge', color: colors.error },
-  PropSet: { symbol: '~', label: 'prop', color: colors.warning },
-  BlobValue: { symbol: '+', label: 'blob', color: colors.primary },
-};
-
-// Default empty operation summary
-const EMPTY_OP_SUMMARY = Object.freeze({
-  NodeAdd: 0,
-  EdgeAdd: 0,
-  PropSet: 0,
-  NodeTombstone: 0,
-  EdgeTombstone: 0,
-  BlobValue: 0,
-});
+import { OP_DISPLAY, EMPTY_OP_SUMMARY, summarizeOps, formatOpSummary } from './opSummary.js';
 
 /**
- * Summarizes operations in a patch.
- * @param {Object[]} ops - Array of patch operations
- * @returns {Object} Summary with counts by operation type
+ * @typedef {{ sha?: string, lamport?: number, writerId?: string, opSummary?: Record<string, number>, ops?: Array<{ type: string }> }} PatchEntry
  */
-function summarizeOps(ops) {
-  const summary = { ...EMPTY_OP_SUMMARY };
-  for (const op of ops) {
-    if (op.type && summary[op.type] !== undefined) {
-      summary[op.type]++;
-    }
-  }
-  return summary;
-}
 
-/**
- * Formats operation summary as a colored string.
- * @param {Object} summary - Operation counts by type
- * @param {number} maxWidth - Maximum width for the summary string
- * @returns {string} Formatted summary string
- */
-function formatOpSummary(summary, maxWidth = 40) {
-  const order = ['NodeAdd', 'EdgeAdd', 'PropSet', 'NodeTombstone', 'EdgeTombstone', 'BlobValue'];
-  const parts = order
-    .filter((opType) => summary[opType] > 0)
-    .map((opType) => {
-      const display = OP_DISPLAY[opType];
-      return { text: `${display.symbol}${summary[opType]}${display.label}`, color: display.color };
-    });
-
-  if (parts.length === 0) {
-    return colors.muted('(empty)');
-  }
-
-  // Truncate plain text first to avoid breaking ANSI escape sequences
-  const plain = parts.map((p) => p.text).join(' ');
-  const truncated = truncate(plain, maxWidth);
-  if (truncated === plain) {
-    return parts.map((p) => p.color(p.text)).join(' ');
-  }
-  return colors.muted(truncated);
-}
+// Default pagination settings
+const DEFAULT_PAGE_SIZE = 20;
 
 /**
  * Ensures entry has an opSummary, computing one if needed.
- * @param {Object} entry - Patch entry
- * @returns {Object} Operation summary
+ * @param {PatchEntry} entry - Patch entry
+ * @returns {Record<string, number>} Operation summary
  */
 function ensureOpSummary(entry) {
   if (entry.opSummary) {
@@ -92,10 +33,10 @@ function ensureOpSummary(entry) {
 
 /**
  * Paginates entries, returning display entries and truncation info.
- * @param {Object[]} entries - All entries
+ * @param {PatchEntry[]} entries - All entries
  * @param {number} pageSize - Page size
  * @param {boolean} showAll - Whether to show all
- * @returns {{displayEntries: Object[], truncated: boolean, hiddenCount: number}}
+ * @returns {{displayEntries: PatchEntry[], truncated: boolean, hiddenCount: number}}
  */
 function paginateEntries(entries, pageSize, showAll) {
   if (showAll || entries.length <= pageSize) {
@@ -127,17 +68,22 @@ function renderTruncationIndicator(truncated, hiddenCount) {
 /**
  * Renders a single patch entry line.
  * @param {Object} params - Entry parameters
+ * @param {PatchEntry} params.entry - Patch entry
+ * @param {boolean} params.isLast - Whether this is the last entry
+ * @param {number} params.lamportWidth - Width for lamport timestamp padding
+ * @param {string} [params.writerStr] - Writer string
+ * @param {number} [params.maxWriterIdLen] - Max writer ID length for padding
  * @returns {string} Formatted entry line
  */
 function renderEntryLine({ entry, isLast, lamportWidth, writerStr, maxWriterIdLen }) {
   const connector = isLast ? TIMELINE.end : TIMELINE.connector;
   const shortSha = (entry.sha || '').slice(0, 7);
-  const lamportStr = padLeft(String(entry.lamport), lamportWidth);
+  const lamportStr = padLeft(String(entry.lamport ?? 0), lamportWidth);
   const opSummary = ensureOpSummary(entry);
   const opSummaryStr = formatOpSummary(opSummary, writerStr ? 30 : 40);
 
   if (writerStr) {
-    const paddedWriter = padRight(writerStr, maxWriterIdLen);
+    const paddedWriter = padRight(writerStr, maxWriterIdLen ?? 6);
     return `  ${connector}${TIMELINE.dot} ${colors.muted(`L${lamportStr}`)} ${colors.primary(paddedWriter)}:${colors.muted(shortSha)} ${opSummaryStr}`;
   }
   return `  ${connector}${TIMELINE.dot} ${colors.muted(`L${lamportStr}`)} ${colors.primary(shortSha)}  ${opSummaryStr}`;
@@ -164,8 +110,8 @@ function renderSingleWriterFooter(totalCount) {
 
 /**
  * Renders single-writer timeline view.
- * @param {Object} payload - History payload
- * @param {Object} options - Rendering options
+ * @param {{ entries: PatchEntry[], writer: string }} payload - History payload
+ * @param {{ pageSize?: number, showAll?: boolean }} options - Rendering options
  * @returns {string[]} Lines for the timeline
  */
 function renderSingleWriterTimeline(payload, options) {
@@ -184,7 +130,7 @@ function renderSingleWriterTimeline(payload, options) {
     lines.push(colors.muted('  (no patches)'));
     return lines;
   }
-  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport));
+  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport ?? 0));
   const lamportWidth = String(maxLamport).length;
 
   lines.push(...renderTruncationIndicator(truncated, hiddenCount));
@@ -200,8 +146,8 @@ function renderSingleWriterTimeline(payload, options) {
 
 /**
  * Merges and sorts entries from all writers by lamport timestamp.
- * @param {Object} writers - Map of writerId to entries
- * @returns {Object[]} Sorted entries with writerId attached
+ * @param {Record<string, PatchEntry[]>} writers - Map of writerId to entries
+ * @returns {PatchEntry[]} Sorted entries with writerId attached
  */
 function mergeWriterEntries(writers) {
   const allEntries = [];
@@ -210,7 +156,7 @@ function mergeWriterEntries(writers) {
       allEntries.push({ ...entry, writerId });
     }
   }
-  allEntries.sort((a, b) => a.lamport - b.lamport || a.writerId.localeCompare(b.writerId));
+  allEntries.sort((a, b) => (a.lamport ?? 0) - (b.lamport ?? 0) || (a.writerId ?? '').localeCompare(b.writerId ?? ''));
   return allEntries;
 }
 
@@ -241,8 +187,8 @@ function renderMultiWriterFooter(totalCount, writerCount) {
 
 /**
  * Renders multi-writer timeline view with parallel columns.
- * @param {Object} payload - History payload with allWriters data
- * @param {Object} options - Rendering options
+ * @param {{ writers: Record<string, PatchEntry[]>, graph: string }} payload - History payload with allWriters data
+ * @param {{ pageSize?: number, showAll?: boolean }} options - Rendering options
  * @returns {string[]} Lines for the timeline
  */
 function renderMultiWriterTimeline(payload, options) {
@@ -269,7 +215,7 @@ function renderMultiWriterTimeline(payload, options) {
     lines.push(colors.muted('  (no patches)'));
     return lines;
   }
-  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport));
+  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport ?? 0));
   const lamportWidth = String(maxLamport).length;
   const maxWriterIdLen = Math.max(...writerIds.map((id) => id.length), 6);
 
@@ -293,15 +239,8 @@ function renderMultiWriterTimeline(payload, options) {
 
 /**
  * Renders the history view with ASCII timeline.
- * @param {Object} payload - History payload from handleHistory
- * @param {string} payload.graph - Graph name
- * @param {string} [payload.writer] - Writer ID (single writer mode)
- * @param {string|null} [payload.nodeFilter] - Node filter if applied
- * @param {Object[]} [payload.entries] - Array of patch entries (single writer mode)
- * @param {Object} [payload.writers] - Map of writerId to entries (multi-writer mode)
- * @param {Object} [options] - Rendering options
- * @param {number} [options.pageSize=20] - Number of patches to show per page
- * @param {boolean} [options.showAll=false] - Show all patches (no pagination)
+ * @param {{ graph: string, writer?: string, nodeFilter?: string | null, entries?: PatchEntry[], writers?: Record<string, PatchEntry[]> }} payload - History payload from handleHistory
+ * @param {{ pageSize?: number, showAll?: boolean }} [options] - Rendering options
  * @returns {string} Formatted ASCII output
  */
 export function renderHistoryView(payload, options = {}) {
@@ -311,8 +250,8 @@ export function renderHistoryView(payload, options = {}) {
 
   const isMultiWriter = payload.writers && typeof payload.writers === 'object';
   const contentLines = isMultiWriter
-    ? renderMultiWriterTimeline(payload, options)
-    : renderSingleWriterTimeline(payload, options);
+    ? renderMultiWriterTimeline(/** @type {{ writers: Record<string, PatchEntry[]>, graph: string }} */ (payload), options)
+    : renderSingleWriterTimeline(/** @type {{ entries: PatchEntry[], writer: string }} */ (payload), options);
 
   // Add node filter indicator if present
   if (payload.nodeFilter) {
@@ -330,6 +269,6 @@ export function renderHistoryView(payload, options = {}) {
   return `${box}\n`;
 }
 
-export { summarizeOps };
+export { summarizeOps, formatOpSummary, OP_DISPLAY, EMPTY_OP_SUMMARY };
 
 export default { renderHistoryView, summarizeOps };

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

@@ -9,6 +9,6 @@ export { progressBar } from './progress.js';
 export { renderInfoView } from './info.js';
 export { renderCheckView } from './check.js';
 export { renderMaterializeView } from './materialize.js';
-export { renderHistoryView, summarizeOps } from './history.js';
+export { renderHistoryView, summarizeOps, formatOpSummary, OP_DISPLAY, EMPTY_OP_SUMMARY } from './history.js';
 export { renderPathView } from './path.js';
 export { renderGraphView } from './graph.js';

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

@@ -0,0 +1,81 @@
+/**
+ * Shared operation summary utilities for ASCII renderers.
+ *
+ * Extracted from history.js so other views (e.g. seek) can reuse the same
+ * op-type ordering, symbols, and formatting.
+ */
+
+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 },
+  NodeTombstone: { symbol: '-', label: 'node', color: colors.error },
+  EdgeAdd: { symbol: '+', label: 'edge', color: colors.success },
+  EdgeTombstone: { symbol: '-', label: 'edge', color: colors.error },
+  PropSet: { symbol: '~', label: 'prop', color: colors.warning },
+  BlobValue: { symbol: '+', label: 'blob', color: colors.primary },
+});
+
+// Default empty operation summary
+export const EMPTY_OP_SUMMARY = Object.freeze({
+  NodeAdd: 0,
+  EdgeAdd: 0,
+  PropSet: 0,
+  NodeTombstone: 0,
+  EdgeTombstone: 0,
+  BlobValue: 0,
+});
+
+/**
+ * Summarizes operations in a patch.
+ * @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) {
+    const t = /** @type {OpType} */ (op.type);
+    if (t && summary[t] !== undefined) {
+      summary[t]++;
+    }
+  }
+  return summary;
+}
+
+/**
+ * Formats operation summary as a colored string.
+ * @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) => (/** @type {Record<string, number>} */ (summary))[opType] > 0)
+    .map((opType) => {
+      const display = OP_DISPLAY[opType];
+      return { text: `${display.symbol}${(/** @type {Record<string, number>} */ (summary))[opType]}${display.label}`, color: display.color };
+    });
+
+  if (parts.length === 0) {
+    return colors.muted('(empty)');
+  }
+
+  // Truncate plain text first to avoid breaking ANSI escape sequences
+  const plain = parts.map((p) => p.text).join(' ');
+  const truncated = truncate(plain, maxWidth);
+  if (truncated === plain) {
+    return parts.map((p) => p.color(p.text)).join(' ');
+  }
+  return colors.muted(truncated);
+}
+

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
  */