@jmoyers/harness 0.1.11 → 0.1.20

package/src/diff/types.ts

@@ -0,0 +1,178 @@
+export type DiffMode = 'unstaged' | 'staged' | 'range';
+
+export type FileChangeType =
+  | 'added'
+  | 'modified'
+  | 'deleted'
+  | 'renamed'
+  | 'copied'
+  | 'binary'
+  | 'submodule'
+  | 'type-change'
+  | 'unknown';
+
+export type DiffCoverageReason =
+  | 'none'
+  | 'max-files'
+  | 'max-lines'
+  | 'max-hunks'
+  | 'max-bytes'
+  | 'max-runtime-ms';
+
+export interface DiffSpec {
+  readonly diffId: string;
+  readonly mode: DiffMode;
+  readonly baseRef: string | null;
+  readonly headRef: string | null;
+  readonly generatedAt: string;
+}
+
+export interface DiffLine {
+  readonly kind: 'context' | 'add' | 'del';
+  readonly oldLine: number | null;
+  readonly newLine: number | null;
+  readonly text: string;
+}
+
+export interface DiffHunk {
+  readonly hunkId: string;
+  readonly oldStart: number;
+  readonly oldCount: number;
+  readonly newStart: number;
+  readonly newCount: number;
+  readonly header: string;
+  readonly lines: readonly DiffLine[];
+  readonly lineCount: number;
+  readonly addCount: number;
+  readonly delCount: number;
+}
+
+export interface DiffFile {
+  readonly fileId: string;
+  readonly changeType: FileChangeType;
+  readonly oldPath: string | null;
+  readonly newPath: string | null;
+  readonly language: string | null;
+  readonly isBinary: boolean;
+  readonly isGenerated: boolean;
+  readonly isTooLarge: boolean;
+  readonly additions: number;
+  readonly deletions: number;
+  readonly hunks: readonly DiffHunk[];
+}
+
+export interface DiffTotals {
+  readonly filesChanged: number;
+  readonly additions: number;
+  readonly deletions: number;
+  readonly binaryFiles: number;
+  readonly generatedFiles: number;
+  readonly hunks: number;
+  readonly lines: number;
+}
+
+export interface DiffCoverage {
+  readonly complete: boolean;
+  readonly truncated: boolean;
+  readonly skippedFiles: number;
+  readonly truncatedFiles: number;
+  readonly reason: DiffCoverageReason;
+}
+
+export interface NormalizedDiff {
+  readonly spec: DiffSpec;
+  readonly files: readonly DiffFile[];
+  readonly totals: DiffTotals;
+  readonly coverage: DiffCoverage;
+}
+
+export interface DiffChunk {
+  readonly chunkId: string;
+  readonly fileId: string;
+  readonly path: string;
+  readonly sequence: number;
+  readonly totalForFile: number;
+  readonly hunkIds: readonly string[];
+  readonly approxTokens: number;
+  readonly approxBytes: number;
+  readonly payload: {
+    readonly fileHeader: string;
+    readonly hunks: readonly DiffHunk[];
+  };
+}
+
+export interface DiffBudget {
+  readonly maxFiles: number;
+  readonly maxHunks: number;
+  readonly maxLines: number;
+  readonly maxBytes: number;
+  readonly maxRuntimeMs: number;
+}
+
+export interface DiffBuildOptions {
+  readonly cwd: string;
+  readonly mode: DiffMode;
+  readonly baseRef?: string;
+  readonly headRef?: string;
+  readonly includeGenerated?: boolean;
+  readonly includeBinary?: boolean;
+  readonly budget: DiffBudget;
+  readonly git?: {
+    readonly noRenames?: boolean;
+    readonly renameLimit?: number;
+  };
+}
+
+export interface DiffBuildDiagnostics {
+  readonly elapsedMs: number;
+  readonly peakBufferBytes: number;
+  readonly parseWarnings: readonly string[];
+}
+
+export interface DiffBuildResult {
+  readonly diff: NormalizedDiff;
+  readonly diagnostics: DiffBuildDiagnostics;
+}
+
+export type DiffStreamEvent =
+  | { readonly type: 'start'; readonly mode: DiffMode }
+  | { readonly type: 'file'; readonly file: DiffFile }
+  | { readonly type: 'hunk'; readonly fileId: string; readonly hunk: DiffHunk }
+  | {
+      readonly type: 'progress';
+      readonly files: number;
+      readonly hunks: number;
+      readonly lines: number;
+    }
+  | { readonly type: 'coverage'; readonly coverage: DiffCoverage }
+  | { readonly type: 'complete'; readonly diff: NormalizedDiff };
+
+export interface ChunkPolicy {
+  readonly maxHunksPerChunk: number;
+  readonly maxLinesPerChunk: number;
+  readonly maxApproxTokensPerChunk: number;
+}
+
+export interface DiffBuilder {
+  build(options: DiffBuildOptions): Promise<DiffBuildResult>;
+  stream(options: DiffBuildOptions): AsyncIterable<DiffStreamEvent>;
+}
+
+export interface DiffChunker {
+  chunk(diff: NormalizedDiff, policy: ChunkPolicy): readonly DiffChunk[];
+  streamChunks(diff: NormalizedDiff, policy: ChunkPolicy): AsyncIterable<DiffChunk>;
+}
+
+export const DEFAULT_DIFF_BUDGET: DiffBudget = {
+  maxFiles: 3000,
+  maxHunks: 20000,
+  maxLines: 300000,
+  maxBytes: 64 * 1024 * 1024,
+  maxRuntimeMs: 60_000,
+};
+
+export const DEFAULT_CHUNK_POLICY: ChunkPolicy = {
+  maxHunksPerChunk: 8,
+  maxLinesPerChunk: 800,
+  maxApproxTokensPerChunk: 4000,
+};

package/src/diff-ui/args.ts

@@ -0,0 +1,346 @@
+import { resolve } from 'node:path';
+import { DEFAULT_DIFF_BUDGET, type DiffMode } from '../diff/types.ts';
+import type {
+  DiffUiCliOptions,
+  DiffUiSyntaxMode,
+  DiffUiViewMode,
+  DiffUiWordDiffMode,
+} from './types.ts';
+
+interface ParseDiffUiArgsOptions {
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly isStdoutTty?: boolean;
+}
+
+interface MutableDiffUiBudget {
+  maxFiles: number;
+  maxHunks: number;
+  maxLines: number;
+  maxBytes: number;
+  maxRuntimeMs: number;
+}
+
+function parseFiniteInt(value: string, flag: string): number {
+  const trimmed = value.trim();
+  if (!/^\d+$/u.test(trimmed)) {
+    throw new Error(`invalid ${flag} value: ${value}`);
+  }
+  return Number.parseInt(trimmed, 10);
+}
+
+function parsePositiveInt(value: string, flag: string): number {
+  const parsed = parseFiniteInt(value, flag);
+  if (parsed <= 0) {
+    throw new Error(`${flag} must be greater than zero`);
+  }
+  return parsed;
+}
+
+function readNextValue(argv: readonly string[], index: number, flag: string): string {
+  const next = argv[index + 1];
+  if (next === undefined) {
+    throw new Error(`missing value for ${flag}`);
+  }
+  return next;
+}
+
+function hasFlagPrefix(value: string): boolean {
+  return value.startsWith('--');
+}
+
+function parseViewMode(raw: string): DiffUiViewMode {
+  if (raw === 'auto' || raw === 'split' || raw === 'unified') {
+    return raw;
+  }
+  throw new Error(`invalid --view value: ${raw}`);
+}
+
+function parseSyntaxMode(raw: string): DiffUiSyntaxMode {
+  if (raw === 'auto' || raw === 'on' || raw === 'off') {
+    return raw;
+  }
+  throw new Error(`invalid --syntax value: ${raw}`);
+}
+
+function parseWordDiffMode(raw: string): DiffUiWordDiffMode {
+  if (raw === 'auto' || raw === 'on' || raw === 'off') {
+    return raw;
+  }
+  throw new Error(`invalid --word-diff value: ${raw}`);
+}
+
+function cloneBudget(): MutableDiffUiBudget {
+  return {
+    maxFiles: DEFAULT_DIFF_BUDGET.maxFiles,
+    maxHunks: DEFAULT_DIFF_BUDGET.maxHunks,
+    maxLines: DEFAULT_DIFF_BUDGET.maxLines,
+    maxBytes: DEFAULT_DIFF_BUDGET.maxBytes,
+    maxRuntimeMs: DEFAULT_DIFF_BUDGET.maxRuntimeMs,
+  };
+}
+
+export function parseDiffUiArgs(
+  argv: readonly string[],
+  options: ParseDiffUiArgsOptions = {},
+): DiffUiCliOptions {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const stdoutIsTty = options.isStdoutTty ?? process.stdout.isTTY === true;
+
+  let mode: DiffMode = 'unstaged';
+  let baseRef: string | null = null;
+  let headRef: string | null = null;
+
+  let includeGenerated = false;
+  let includeBinary = false;
+  let noRenames = true;
+  let renameLimit: number | null = null;
+
+  let viewMode: DiffUiViewMode = 'auto';
+  let syntaxMode: DiffUiSyntaxMode = 'auto';
+  let wordDiffMode: DiffUiWordDiffMode = 'auto';
+  let color = stdoutIsTty && env.NO_COLOR === undefined;
+  let pagerExplicit: boolean | null = null;
+  let watch = false;
+  let jsonEvents = false;
+  let rpcStdio = false;
+  let snapshot = false;
+  let width: number | null = null;
+  let height: number | null = null;
+  let theme: string | null = null;
+  let resolvedCwd = cwd;
+
+  const budget = cloneBudget();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+
+    if (arg === '--help' || arg === '-h') {
+      throw new Error('help requested');
+    }
+    if (arg === '--staged') {
+      mode = 'staged';
+      continue;
+    }
+    if (arg === '--base') {
+      const next = argv[index + 1];
+      if (next !== undefined && !hasFlagPrefix(next)) {
+        baseRef = next;
+        index += 1;
+      } else {
+        baseRef = null;
+      }
+      mode = 'range';
+      continue;
+    }
+    if (arg === '--head') {
+      const value = readNextValue(argv, index, '--head');
+      headRef = value;
+      index += 1;
+      continue;
+    }
+    if (arg === '--view') {
+      const value = readNextValue(argv, index, '--view');
+      viewMode = parseViewMode(value);
+      index += 1;
+      continue;
+    }
+    if (arg === '--syntax') {
+      const value = readNextValue(argv, index, '--syntax');
+      syntaxMode = parseSyntaxMode(value);
+      index += 1;
+      continue;
+    }
+    if (arg === '--word-diff') {
+      const value = readNextValue(argv, index, '--word-diff');
+      wordDiffMode = parseWordDiffMode(value);
+      index += 1;
+      continue;
+    }
+    if (arg === '--no-color') {
+      color = false;
+      continue;
+    }
+    if (arg === '--pager') {
+      pagerExplicit = true;
+      continue;
+    }
+    if (arg === '--no-pager') {
+      pagerExplicit = false;
+      continue;
+    }
+    if (arg === '--json-events') {
+      jsonEvents = true;
+      continue;
+    }
+    if (arg === '--rpc-stdio') {
+      rpcStdio = true;
+      continue;
+    }
+    if (arg === '--snapshot') {
+      snapshot = true;
+      continue;
+    }
+    if (arg === '--watch') {
+      watch = true;
+      continue;
+    }
+    if (arg === '--theme') {
+      const value = readNextValue(argv, index, '--theme');
+      theme = value;
+      index += 1;
+      continue;
+    }
+    if (arg === '--width') {
+      const value = readNextValue(argv, index, '--width');
+      width = parsePositiveInt(value, '--width');
+      index += 1;
+      continue;
+    }
+    if (arg === '--height') {
+      const value = readNextValue(argv, index, '--height');
+      height = parsePositiveInt(value, '--height');
+      index += 1;
+      continue;
+    }
+    if (arg === '--max-files') {
+      const value = readNextValue(argv, index, '--max-files');
+      budget.maxFiles = parsePositiveInt(value, '--max-files');
+      index += 1;
+      continue;
+    }
+    if (arg === '--max-hunks') {
+      const value = readNextValue(argv, index, '--max-hunks');
+      budget.maxHunks = parsePositiveInt(value, '--max-hunks');
+      index += 1;
+      continue;
+    }
+    if (arg === '--max-lines') {
+      const value = readNextValue(argv, index, '--max-lines');
+      budget.maxLines = parsePositiveInt(value, '--max-lines');
+      index += 1;
+      continue;
+    }
+    if (arg === '--max-bytes') {
+      const value = readNextValue(argv, index, '--max-bytes');
+      budget.maxBytes = parsePositiveInt(value, '--max-bytes');
+      index += 1;
+      continue;
+    }
+    if (arg === '--max-runtime-ms') {
+      const value = readNextValue(argv, index, '--max-runtime-ms');
+      budget.maxRuntimeMs = parsePositiveInt(value, '--max-runtime-ms');
+      index += 1;
+      continue;
+    }
+    if (arg === '--include-generated') {
+      includeGenerated = true;
+      continue;
+    }
+    if (arg === '--include-binary') {
+      includeBinary = true;
+      continue;
+    }
+    if (arg === '--renames') {
+      noRenames = false;
+      continue;
+    }
+    if (arg === '--no-renames') {
+      noRenames = true;
+      continue;
+    }
+    if (arg === '--rename-limit') {
+      const value = readNextValue(argv, index, '--rename-limit');
+      renameLimit = parseFiniteInt(value, '--rename-limit');
+      noRenames = false;
+      index += 1;
+      continue;
+    }
+    if (arg === '--cwd') {
+      const value = readNextValue(argv, index, '--cwd');
+      resolvedCwd = resolve(cwd, value);
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`unknown option: ${arg}`);
+  }
+
+  if (mode === 'range' && headRef === null) {
+    headRef = 'HEAD';
+  }
+  if (mode !== 'range' && (baseRef !== null || headRef !== null)) {
+    throw new Error('--base/--head are only valid for range mode');
+  }
+  const pagerIncompatibleMode = jsonEvents || rpcStdio || snapshot;
+  const pager = pagerExplicit === null ? stdoutIsTty && !pagerIncompatibleMode : pagerExplicit;
+  if (pager && pagerIncompatibleMode) {
+    throw new Error('--pager cannot be combined with --json-events, --rpc-stdio, or --snapshot');
+  }
+
+  return {
+    cwd: resolvedCwd,
+    mode,
+    baseRef,
+    headRef,
+    includeGenerated,
+    includeBinary,
+    noRenames,
+    renameLimit,
+    viewMode,
+    syntaxMode,
+    wordDiffMode,
+    color,
+    pager,
+    watch,
+    jsonEvents,
+    rpcStdio,
+    snapshot,
+    width,
+    height,
+    theme,
+    budget,
+  };
+}
+
+export function diffUiUsage(): string {
+  return [
+    'usage: harness diff [options]',
+    '',
+    'diff source:',
+    '  --staged',
+    '  --base [<ref>] [--head <ref>]',
+    '',
+    'display:',
+    '  --view <auto|split|unified>',
+    '  --syntax <auto|on|off>',
+    '  --word-diff <auto|on|off>',
+    '  --theme <name>',
+    '  --no-color',
+    '  --pager',
+    '  --no-pager',
+    '  --width <n>',
+    '  --height <n>',
+    '',
+    'runtime:',
+    '  --json-events',
+    '  --rpc-stdio',
+    '  --snapshot',
+    '  --watch',
+    '',
+    'budgets:',
+    '  --max-files <n>',
+    '  --max-hunks <n>',
+    '  --max-lines <n>',
+    '  --max-bytes <n>',
+    '  --max-runtime-ms <n>',
+    '',
+    'git:',
+    '  --include-generated',
+    '  --include-binary',
+    '  --renames | --no-renames',
+    '  --rename-limit <n>',
+    '  --cwd <path>',
+  ].join('\n');
+}

package/src/diff-ui/commands.ts

@@ -0,0 +1,123 @@
+import type { DiffUiCommand, DiffUiStateAction } from './types.ts';
+
+export function parseDiffUiCommand(value: unknown): DiffUiCommand | null {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const type = record['type'];
+  if (typeof type !== 'string') {
+    return null;
+  }
+
+  if (type === 'view.setMode') {
+    const mode = record['mode'];
+    if (mode === 'auto' || mode === 'split' || mode === 'unified') {
+      return { type, mode };
+    }
+    return null;
+  }
+  if (type === 'nav.scroll') {
+    const delta = record['delta'];
+    return typeof delta === 'number' && Number.isFinite(delta) ? { type, delta } : null;
+  }
+  if (type === 'nav.page') {
+    const delta = record['delta'];
+    return typeof delta === 'number' && Number.isFinite(delta) ? { type, delta } : null;
+  }
+  if (type === 'nav.gotoFile' || type === 'nav.gotoHunk') {
+    const index = record['index'];
+    if (typeof index !== 'number' || !Number.isFinite(index)) {
+      return null;
+    }
+    if (type === 'nav.gotoFile') {
+      return { type, index };
+    }
+    return { type, index };
+  }
+  if (type === 'finder.open' || type === 'finder.close' || type === 'finder.accept') {
+    return { type };
+  }
+  if (type === 'finder.query' || type === 'search.set') {
+    const query = record['query'];
+    if (typeof query !== 'string') {
+      return null;
+    }
+    if (type === 'finder.query') {
+      return { type, query };
+    }
+    return { type, query };
+  }
+  if (type === 'finder.move') {
+    const delta = record['delta'];
+    return typeof delta === 'number' && Number.isFinite(delta) ? { type, delta } : null;
+  }
+  if (type === 'session.quit') {
+    return { type };
+  }
+
+  return null;
+}
+
+type DiffUiActionCommand = Exclude<DiffUiCommand, { readonly type: 'session.quit' }>;
+
+export function diffUiCommandToStateAction(
+  command: DiffUiActionCommand,
+  pageSize: number,
+): DiffUiStateAction {
+  switch (command.type) {
+    case 'view.setMode':
+      return {
+        type: 'view.setMode',
+        mode: command.mode,
+      };
+    case 'nav.scroll':
+      return {
+        type: 'nav.scroll',
+        delta: Math.trunc(command.delta),
+      };
+    case 'nav.page':
+      return {
+        type: 'nav.page',
+        delta: Math.trunc(command.delta),
+        pageSize,
+      };
+    case 'nav.gotoFile':
+      return {
+        type: 'nav.gotoFile',
+        fileIndex: Math.trunc(command.index),
+      };
+    case 'nav.gotoHunk':
+      return {
+        type: 'nav.gotoHunk',
+        hunkIndex: Math.trunc(command.index),
+      };
+    case 'finder.open':
+      return {
+        type: 'finder.open',
+      };
+    case 'finder.close':
+      return {
+        type: 'finder.close',
+      };
+    case 'finder.query':
+      return {
+        type: 'finder.query',
+        query: command.query,
+      };
+    case 'finder.move':
+      return {
+        type: 'finder.move',
+        delta: Math.trunc(command.delta),
+      };
+    case 'finder.accept':
+      return {
+        type: 'finder.accept',
+      };
+    case 'search.set':
+      return {
+        type: 'search.set',
+        query: command.query,
+      };
+  }
+}