@jmoyers/harness 0.1.10 → 0.1.20

package/src/diff/budget.ts

@@ -0,0 +1,136 @@
+import type { DiffBudget, DiffCoverageReason } from './types.ts';
+
+interface DiffBudgetUsage {
+  readonly files: number;
+  readonly hunks: number;
+  readonly lines: number;
+  readonly bytes: number;
+}
+
+interface MutableDiffBudgetUsage {
+  files: number;
+  hunks: number;
+  lines: number;
+  bytes: number;
+}
+
+interface DiffBudgetCheckpoint {
+  readonly allowed: boolean;
+  readonly reason: DiffCoverageReason;
+}
+
+function takeReason(current: DiffCoverageReason, next: DiffCoverageReason): DiffCoverageReason {
+  if (current !== 'none') {
+    return current;
+  }
+  return next;
+}
+
+export class DiffBudgetTracker {
+  private reason: DiffCoverageReason = 'none';
+  private readonly usageMutable: MutableDiffBudgetUsage = {
+    files: 0,
+    hunks: 0,
+    lines: 0,
+    bytes: 0,
+  };
+  private readonly startedAtMs: number;
+
+  constructor(
+    private readonly budget: DiffBudget,
+    nowMs = Date.now(),
+  ) {
+    this.startedAtMs = nowMs;
+  }
+
+  usage(): DiffBudgetUsage {
+    return {
+      files: this.usageMutable.files,
+      hunks: this.usageMutable.hunks,
+      lines: this.usageMutable.lines,
+      bytes: this.usageMutable.bytes,
+    };
+  }
+
+  limitReason(): DiffCoverageReason {
+    return this.reason;
+  }
+
+  elapsedMs(nowMs = Date.now()): number {
+    return Math.max(0, nowMs - this.startedAtMs);
+  }
+
+  checkRuntime(nowMs = Date.now()): DiffBudgetCheckpoint {
+    if (this.elapsedMs(nowMs) >= this.budget.maxRuntimeMs) {
+      this.reason = takeReason(this.reason, 'max-runtime-ms');
+      return {
+        allowed: false,
+        reason: this.reason,
+      };
+    }
+    return {
+      allowed: true,
+      reason: this.reason,
+    };
+  }
+
+  addBytes(value: number): DiffBudgetCheckpoint {
+    this.usageMutable.bytes += Math.max(0, Math.floor(value));
+    if (this.usageMutable.bytes > this.budget.maxBytes) {
+      this.reason = takeReason(this.reason, 'max-bytes');
+      return {
+        allowed: false,
+        reason: this.reason,
+      };
+    }
+    return {
+      allowed: true,
+      reason: this.reason,
+    };
+  }
+
+  takeFile(): DiffBudgetCheckpoint {
+    if (this.usageMutable.files >= this.budget.maxFiles) {
+      this.reason = takeReason(this.reason, 'max-files');
+      return {
+        allowed: false,
+        reason: this.reason,
+      };
+    }
+    this.usageMutable.files += 1;
+    return {
+      allowed: true,
+      reason: this.reason,
+    };
+  }
+
+  takeHunk(): DiffBudgetCheckpoint {
+    if (this.usageMutable.hunks >= this.budget.maxHunks) {
+      this.reason = takeReason(this.reason, 'max-hunks');
+      return {
+        allowed: false,
+        reason: this.reason,
+      };
+    }
+    this.usageMutable.hunks += 1;
+    return {
+      allowed: true,
+      reason: this.reason,
+    };
+  }
+
+  takeLine(): DiffBudgetCheckpoint {
+    if (this.usageMutable.lines >= this.budget.maxLines) {
+      this.reason = takeReason(this.reason, 'max-lines');
+      return {
+        allowed: false,
+        reason: this.reason,
+      };
+    }
+    this.usageMutable.lines += 1;
+    return {
+      allowed: true,
+      reason: this.reason,
+    };
+  }
+}

package/src/diff/build.ts

@@ -0,0 +1,289 @@
+import { DiffBudgetTracker } from './budget.ts';
+import { computeDiffId } from './hash.ts';
+import {
+  buildGitDiffArgs,
+  readGitDiffPreflight,
+  resolveRangeBaseRef,
+  streamGitLines,
+  type GitDiffInvocationOptions,
+} from './git-invoke.ts';
+import { GitDiffPatchParser } from './git-parse.ts';
+import type {
+  DiffBuildOptions,
+  DiffBuildResult,
+  DiffBuilder,
+  DiffCoverage,
+  DiffCoverageReason,
+  DiffStreamEvent,
+  NormalizedDiff,
+} from './types.ts';
+
+interface BuildHooks {
+  emit(event: DiffStreamEvent): void;
+}
+
+interface NormalizedBuildOptions {
+  readonly cwd: string;
+  readonly mode: DiffBuildOptions['mode'];
+  readonly baseRef: string | null;
+  readonly headRef: string | null;
+  readonly includeGenerated: boolean;
+  readonly includeBinary: boolean;
+  readonly noRenames: boolean;
+  readonly renameLimit: number | null;
+  readonly budget: DiffBuildOptions['budget'];
+}
+
+function normalizeOptions(options: DiffBuildOptions): NormalizedBuildOptions {
+  return {
+    cwd: options.cwd,
+    mode: options.mode,
+    baseRef: options.baseRef ?? null,
+    headRef: options.headRef ?? null,
+    includeGenerated: options.includeGenerated ?? false,
+    includeBinary: options.includeBinary ?? false,
+    noRenames: options.git?.noRenames ?? true,
+    renameLimit:
+      typeof options.git?.renameLimit === 'number' && Number.isFinite(options.git.renameLimit)
+        ? Math.max(0, Math.floor(options.git.renameLimit))
+        : null,
+    budget: options.budget,
+  };
+}
+
+function toInvocationOptions(options: NormalizedBuildOptions): GitDiffInvocationOptions {
+  return {
+    cwd: options.cwd,
+    mode: options.mode,
+    baseRef: options.baseRef,
+    headRef: options.headRef,
+    noRenames: options.noRenames,
+    renameLimit: options.renameLimit,
+  };
+}
+
+async function resolveRangeRefs(options: NormalizedBuildOptions): Promise<{
+  readonly baseRef: string | null;
+  readonly headRef: string | null;
+}> {
+  if (options.mode !== 'range') {
+    return {
+      baseRef: options.baseRef,
+      headRef: options.headRef,
+    };
+  }
+
+  const headRef = options.headRef ?? 'HEAD';
+  if (options.baseRef !== null) {
+    return {
+      baseRef: options.baseRef,
+      headRef,
+    };
+  }
+
+  const baseRef = await resolveRangeBaseRef({
+    cwd: options.cwd,
+    headRef,
+    timeoutMs: options.budget.maxRuntimeMs,
+  });
+  return {
+    baseRef,
+    headRef,
+  };
+}
+
+function resolveCoverage(input: {
+  filesObservedInPreflight: number;
+  filesIncluded: number;
+  filesSkippedByFilter: number;
+  filesTruncatedByBudget: number;
+  limitReason: DiffCoverageReason;
+}): DiffCoverage {
+  const remainder = Math.max(
+    0,
+    input.filesObservedInPreflight - input.filesIncluded - input.filesSkippedByFilter,
+  );
+  const truncatedByLimit = input.limitReason !== 'none' ? remainder : 0;
+  const truncatedFiles = Math.max(input.filesTruncatedByBudget, truncatedByLimit);
+  const skippedFiles = Math.max(
+    input.filesSkippedByFilter,
+    input.filesObservedInPreflight - input.filesIncluded - truncatedFiles,
+  );
+  return {
+    complete: input.limitReason === 'none' && truncatedFiles === 0,
+    truncated: input.limitReason !== 'none' || truncatedFiles > 0,
+    skippedFiles,
+    truncatedFiles,
+    reason: input.limitReason,
+  };
+}
+
+async function runBuild(
+  rawOptions: DiffBuildOptions,
+  hooks?: BuildHooks,
+): Promise<DiffBuildResult> {
+  const options = normalizeOptions(rawOptions);
+  const startedAtMs = Date.now();
+  hooks?.emit({
+    type: 'start',
+    mode: options.mode,
+  });
+  const resolvedRefs = await resolveRangeRefs(options);
+  const invocation = toInvocationOptions({
+    ...options,
+    baseRef: resolvedRefs.baseRef,
+    headRef: resolvedRefs.headRef,
+  });
+  const preflight = await readGitDiffPreflight(invocation, options.budget.maxRuntimeMs);
+
+  const budget = new DiffBudgetTracker(options.budget, startedAtMs);
+  const parser = new GitDiffPatchParser({
+    includeGenerated: options.includeGenerated,
+    includeBinary: options.includeBinary,
+    budget,
+    onHunk: (fileId, hunk) => {
+      hooks?.emit({
+        type: 'hunk',
+        fileId,
+        hunk,
+      });
+      const usage = budget.usage();
+      hooks?.emit({
+        type: 'progress',
+        files: usage.files,
+        hunks: usage.hunks,
+        lines: usage.lines,
+      });
+    },
+    onFile: (file) => {
+      hooks?.emit({
+        type: 'file',
+        file,
+      });
+      const usage = budget.usage();
+      hooks?.emit({
+        type: 'progress',
+        files: usage.files,
+        hunks: usage.hunks,
+        lines: usage.lines,
+      });
+    },
+  });
+
+  const patchResult = await streamGitLines({
+    cwd: options.cwd,
+    args: buildGitDiffArgs(invocation, 'patch'),
+    timeoutMs: options.budget.maxRuntimeMs,
+    onBytes: (bytes) => budget.addBytes(bytes).allowed,
+    onLine: (line) => parser.pushLine(line),
+  });
+  if (patchResult.exitCode !== 0 && !patchResult.aborted)
+    throw new Error(`git diff --patch failed: ${patchResult.stderr || 'unknown error'}`);
+
+  const parsed = parser.finish();
+  const limitReason: DiffCoverageReason =
+    parsed.limitReason === 'none' && patchResult.timedOut ? 'max-runtime-ms' : parsed.limitReason;
+  const coverage = resolveCoverage({
+    filesObservedInPreflight: preflight.filesChanged,
+    filesIncluded: parsed.files.length,
+    filesSkippedByFilter: parsed.skippedFiles,
+    filesTruncatedByBudget: parsed.truncatedFiles,
+    limitReason,
+  });
+  const generatedAt = new Date().toISOString();
+  const diff: NormalizedDiff = {
+    spec: {
+      diffId: computeDiffId(options.mode, invocation.baseRef, invocation.headRef, parsed.files),
+      mode: options.mode,
+      baseRef: invocation.baseRef,
+      headRef: invocation.headRef,
+      generatedAt,
+    },
+    files: parsed.files,
+    totals: parsed.totals,
+    coverage,
+  };
+
+  const parseWarnings = [...parsed.warnings];
+  const expectedTotal = parsed.files.length + coverage.skippedFiles + coverage.truncatedFiles;
+  if (expectedTotal !== preflight.filesChanged) {
+    parseWarnings.push(
+      `preflight mismatch: filesChanged=${preflight.filesChanged} accounted=${expectedTotal}`,
+    );
+  }
+
+  hooks?.emit({
+    type: 'coverage',
+    coverage,
+  });
+  hooks?.emit({
+    type: 'complete',
+    diff,
+  });
+
+  return {
+    diff,
+    diagnostics: {
+      elapsedMs: Math.max(0, Date.now() - startedAtMs),
+      peakBufferBytes: patchResult.peakLineBufferBytes,
+      parseWarnings,
+    },
+  };
+}
+
+async function* streamDiff(options: DiffBuildOptions): AsyncIterable<DiffStreamEvent> {
+  const events: DiffStreamEvent[] = [];
+  let notifyNext: (() => void) | null = null;
+  let done = false;
+  let failure: unknown = null;
+
+  const notify = (): void => {
+    const callback = notifyNext;
+    notifyNext = null;
+    callback?.();
+  };
+
+  void runBuild(options, {
+    emit(event) {
+      events.push(event);
+      notify();
+    },
+  })
+    .then(() => {
+      done = true;
+      notify();
+    })
+    .catch((error: unknown) => {
+      failure = error;
+      done = true;
+      notify();
+    });
+
+  while (true) {
+    while (events.length > 0) {
+      const event = events.shift();
+      if (event !== undefined) {
+        yield event;
+      }
+    }
+
+    if (failure !== null) {
+      throw failure;
+    }
+
+    if (done) {
+      return;
+    }
+
+    await new Promise<void>((resolve) => {
+      notifyNext = resolve;
+    });
+  }
+}
+
+export function createDiffBuilder(): DiffBuilder {
+  return {
+    build: async (options: DiffBuildOptions): Promise<DiffBuildResult> => await runBuild(options),
+    stream: streamDiff,
+  };
+}

package/src/diff/chunker.ts

@@ -0,0 +1,146 @@
+import { computeDiffChunkId } from './hash.ts';
+import type { ChunkPolicy, DiffChunk, DiffChunker, DiffHunk, NormalizedDiff } from './types.ts';
+
+function normalizeChunkPolicy(policy: ChunkPolicy): ChunkPolicy {
+  return {
+    maxHunksPerChunk: Math.max(1, Math.floor(policy.maxHunksPerChunk)),
+    maxLinesPerChunk: Math.max(1, Math.floor(policy.maxLinesPerChunk)),
+    maxApproxTokensPerChunk: Math.max(1, Math.floor(policy.maxApproxTokensPerChunk)),
+  };
+}
+
+function hunkApproxBytes(hunk: DiffHunk): number {
+  let bytes = Buffer.byteLength(hunk.header);
+  for (const line of hunk.lines) {
+    bytes += Buffer.byteLength(line.text) + 1;
+  }
+  return bytes;
+}
+
+function approxTokensFromBytes(bytes: number): number {
+  return Math.max(1, Math.ceil(bytes / 4));
+}
+
+function policySignature(policy: ChunkPolicy): string {
+  return `${policy.maxHunksPerChunk}:${policy.maxLinesPerChunk}:${policy.maxApproxTokensPerChunk}`;
+}
+
+function finalizeChunk(
+  fileId: string,
+  path: string,
+  sequence: number,
+  totalForFile: number,
+  hunks: readonly DiffHunk[],
+  policySig: string,
+): DiffChunk {
+  const hunkIds: string[] = [];
+  for (const hunk of hunks) {
+    hunkIds.push(hunk.hunkId);
+  }
+  let approxBytes = Buffer.byteLength(path);
+  for (const hunk of hunks) {
+    approxBytes += hunkApproxBytes(hunk);
+  }
+  return {
+    chunkId: computeDiffChunkId(fileId, sequence, hunkIds, policySig),
+    fileId,
+    path,
+    sequence,
+    totalForFile,
+    hunkIds,
+    approxTokens: approxTokensFromBytes(approxBytes),
+    approxBytes,
+    payload: {
+      fileHeader: path,
+      hunks,
+    },
+  };
+}
+
+function chunkSingleFile(
+  fileId: string,
+  path: string,
+  hunks: readonly DiffHunk[],
+  policy: ChunkPolicy,
+): readonly DiffChunk[] {
+  const policySig = policySignature(policy);
+  const chunksHunks: DiffHunk[][] = [];
+  let current: DiffHunk[] = [];
+  let currentLines = 0;
+  let currentApproxTokens = 0;
+
+  for (const hunk of hunks) {
+    const hunkLines = hunk.lineCount;
+    const hunkTokens = approxTokensFromBytes(hunkApproxBytes(hunk));
+    const wouldExceed =
+      current.length >= policy.maxHunksPerChunk ||
+      currentLines + hunkLines > policy.maxLinesPerChunk ||
+      currentApproxTokens + hunkTokens > policy.maxApproxTokensPerChunk;
+    if (wouldExceed && current.length > 0) {
+      chunksHunks.push(current);
+      current = [];
+      currentLines = 0;
+      currentApproxTokens = 0;
+    }
+    current.push(hunk);
+    currentLines += hunkLines;
+    currentApproxTokens += hunkTokens;
+    const mustFlush =
+      current.length >= policy.maxHunksPerChunk ||
+      currentLines >= policy.maxLinesPerChunk ||
+      currentApproxTokens >= policy.maxApproxTokensPerChunk;
+    if (mustFlush) {
+      chunksHunks.push(current);
+      current = [];
+      currentLines = 0;
+      currentApproxTokens = 0;
+    }
+  }
+  if (current.length > 0) {
+    chunksHunks.push(current);
+  }
+
+  const totalForFile = chunksHunks.length;
+  const chunks: DiffChunk[] = [];
+  for (let index = 0; index < chunksHunks.length; index += 1) {
+    const hunkChunk = chunksHunks[index]!;
+    chunks.push(finalizeChunk(fileId, path, index + 1, totalForFile, hunkChunk, policySig));
+  }
+  return chunks;
+}
+
+function chunkDiff(diff: NormalizedDiff, policy: ChunkPolicy): readonly DiffChunk[] {
+  const normalizedPolicy = normalizeChunkPolicy(policy);
+  const chunks: DiffChunk[] = [];
+  for (const file of diff.files) {
+    if (file.isBinary || file.hunks.length === 0) {
+      continue;
+    }
+    const path = file.newPath ?? file.oldPath ?? file.fileId;
+    chunks.push(...chunkSingleFile(file.fileId, path, file.hunks, normalizedPolicy));
+  }
+  return chunks;
+}
+
+async function* streamDiffChunks(
+  diff: NormalizedDiff,
+  policy: ChunkPolicy,
+): AsyncIterable<DiffChunk> {
+  const normalizedPolicy = normalizeChunkPolicy(policy);
+  for (const file of diff.files) {
+    if (file.isBinary || file.hunks.length === 0) {
+      continue;
+    }
+    const path = file.newPath ?? file.oldPath ?? file.fileId;
+    for (const chunk of chunkSingleFile(file.fileId, path, file.hunks, normalizedPolicy)) {
+      yield chunk;
+    }
+  }
+}
+
+export function createDiffChunker(): DiffChunker {
+  return {
+    chunk: chunkDiff,
+    streamChunks: streamDiffChunks,
+  };
+}