@git-stunts/git-warp 10.3.2 → 10.4.2

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,11 @@ 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 {{ graph: string, tick: number, maxTick: number, ticks: number[], nodes: number, edges: number, patchCount: number, perWriter: Map<string, WriterInfo> | Record<string, WriterInfo>, diff?: { nodes?: number, edges?: number }, tickReceipt?: Record<string, any> }} SeekPayload
+ */
+
 /** Maximum number of tick columns shown in the windowed view. */
 const MAX_COLS = 9;
 
@@ -30,6 +35,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 +44,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 +213,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
@@ -255,7 +268,7 @@ function buildTickPoints(ticks, tick) {
 /**
  * Builds the body lines for the seek dashboard.
  *
- * @param {Object} payload - Seek payload from the CLI handler
+ * @param {SeekPayload} payload - Seek payload from the CLI handler
  * @returns {string[]} Lines for the box body
  */
 function buildSeekBodyLines(payload) {
@@ -277,6 +290,7 @@ function buildSeekBodyLines(payload) {
     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]);
@@ -291,8 +305,8 @@ function buildSeekBodyLines(payload) {
   const nodeLabel = pluralize(nodes, 'node', 'nodes');
   const patchLabel = pluralize(patchCount, 'patch', 'patches');
 
-  const nodesStr = `${nodes} ${nodeLabel}${formatDelta(diff?.nodes)}`;
-  const edgesStr = `${edges} ${edgeLabel}${formatDelta(diff?.edges)}`;
+  const nodesStr = `${nodes} ${nodeLabel}${formatDelta(diff?.nodes ?? 0)}`;
+  const edgesStr = `${edges} ${edgeLabel}${formatDelta(diff?.edges ?? 0)}`;
   lines.push(`  ${colors.bold('State:')} ${nodesStr}, ${edgesStr}, ${patchCount} ${patchLabel}`);
 
   const receiptLines = buildReceiptLines(tickReceipt);
@@ -313,7 +327,7 @@ function buildSeekBodyLines(payload) {
 /**
  * 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
  */