refactor(todo2code): split workspace comparison into focused modules

src/comparison/workspace-deadline.ts

@@ -0,0 +1,110 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { T2CConfig } from '../config/env.js';
+import { resolveGlobs } from '../core/io.js';
+import { OPENROUTER_TIMEOUT_POLICY } from '../llm/openrouter-timeout.js';
+import { assertNonNegativeInteger } from './workspace-helpers.js';
+import type {
+  WorkspaceComparisonDeadlineDecision,
+  WorkspaceComparisonDeadlineLoad,
+  WorkspaceComparisonOptions,
+} from './workspace-types.js';
+
+export const WORKSPACE_COMPARISON_DEADLINE_POLICY = Object.freeze({
+  inputBytesBaseline: 128 * 1024,
+  llmWorkUnitsBaseline: 16,
+  scaleFactor: 2,
+  maximumMultiplier: 4,
+  maximumDeadlineMs: 40 * 60 * 1000,
+});
+
+// Generated graphs are denser than their source records. Platform currently
+// produces a ~136 MiB graph, so the generic 128 MiB JSON ceiling rejects an
+// artifact that the bounded pipeline has just produced. Keep a separate,
+// explicit ceiling for the two comparison graphs instead of weakening the
+// default limit for every JSON consumer.
+export const WORKSPACE_COMPARISON_GRAPH_MAX_BYTES = 256 * 1024 * 1024;
+
+/** Bound the two-pipeline operation, not only each individual provider call. */
+export function calculateWorkspaceComparisonDeadline(
+  load: WorkspaceComparisonDeadlineLoad,
+): WorkspaceComparisonDeadlineDecision {
+  assertNonNegativeInteger(load.inputBytes, 'input bytes');
+  assertNonNegativeInteger(load.llmWorkUnits, 'LLM work units');
+  const baseDeadlineMs = OPENROUTER_TIMEOUT_POLICY.maximumTimeoutMs;
+  const pressure = Math.max(
+    1,
+    load.inputBytes / WORKSPACE_COMPARISON_DEADLINE_POLICY.inputBytesBaseline,
+    load.llmWorkUnits / WORKSPACE_COMPARISON_DEADLINE_POLICY.llmWorkUnitsBaseline,
+  );
+  const steps = pressure <= 1 ? 0 : Math.ceil(Math.log2(pressure));
+  const multiplier = Math.min(
+    WORKSPACE_COMPARISON_DEADLINE_POLICY.maximumMultiplier,
+    WORKSPACE_COMPARISON_DEADLINE_POLICY.scaleFactor ** steps,
+  );
+  const scaledDeadlineMs = baseDeadlineMs * multiplier;
+  const effectiveDeadlineMs = Math.min(
+    WORKSPACE_COMPARISON_DEADLINE_POLICY.maximumDeadlineMs,
+    scaledDeadlineMs,
+  );
+  const capped = effectiveDeadlineMs < scaledDeadlineMs;
+  return {
+    ...load,
+    baseDeadlineMs,
+    pressure,
+    multiplier,
+    effectiveDeadlineMs,
+    capped,
+  };
+}
+
+export async function workspaceComparisonDeadlineLoad(
+  root: string,
+  options: WorkspaceComparisonOptions,
+  config: T2CConfig,
+): Promise<WorkspaceComparisonDeadlineLoad> {
+  const files = new Set<string>();
+  const addIfPresent = async (file: string | null | undefined): Promise<void> => {
+    if (!file) return;
+    const absolute = path.resolve(root, file);
+    const relative = path.relative(root, absolute);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) return;
+    try {
+      if ((await fs.stat(absolute)).isFile()) files.add(absolute);
+    } catch {
+      // Missing optional inputs are skipped by the pipeline too.
+    }
+  };
+  await Promise.all([
+    addIfPresent(options.taskFile),
+    addIfPresent(options.todoFile === undefined ? 'TODO.md' : options.todoFile),
+    addIfPresent(options.changelogFile === undefined ? 'CHANGELOG.md' : options.changelogFile),
+  ]);
+  const documentFiles = await resolveGlobs(
+    root,
+    options.documentPatterns ?? config.documentPatterns,
+    options.documentExcludes ?? config.documentExcludes,
+  );
+  const documentFileSet = new Set(documentFiles);
+  for (const file of documentFiles) files.add(file);
+
+  let inputBytes = 0;
+  let documentChunks = 0;
+  for (const file of files) {
+    const size = (await fs.stat(file)).size;
+    inputBytes += size;
+    if (documentFileSet.has(file)) {
+      documentChunks += Math.min(config.documentMaxChunks, Math.max(1, Math.ceil(size / config.documentChunkChars)));
+    }
+  }
+  const markdownMode = options.markdownMode ?? config.markdownMode;
+  const communicationMode = options.communicationMode ?? config.communicationMode;
+  const semanticUnitsPerPipeline = (options.includeDocumentationLlm ? documentChunks : 0)
+    + (markdownMode === 'deterministic' ? 0 : 2)
+    + (config.nlMode === 'deterministic' || !options.taskFile ? 0 : 1)
+    + (communicationMode === 'deterministic' ? 0 : 1);
+  return {
+    inputBytes: inputBytes * 2,
+    llmWorkUnits: semanticUnitsPerPipeline * 2,
+  };
+}

src/comparison/workspace-helpers.ts

@@ -0,0 +1,109 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import type { T2CConfig } from '../config/env.js';
+import { pathExists } from '../core/io.js';
+import { assertPathWithinRoot } from '../core/security.js';
+import type { DiagnosticReport, PipelineOptions } from '../core/types.js';
+import type { IntentRealityView } from '../diff/reality.js';
+import type { CoverageSnapshot, WorkspaceComparisonOptions } from './workspace-types.js';
+
+const execFileAsync = promisify(execFile);
+
+export function assertNonNegativeInteger(value: number, name: string): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`Workspace comparison ${name} must be a non-negative safe integer`);
+  }
+}
+
+/**
+ * Every other scoping call site honours `T2C_ALLOW_OUTSIDE_ROOT`; this one hard
+ * coded the restriction, so comparing a third-party checkout while keeping its
+ * artifacts out of the tree failed where the same `--out` works for `pipeline`.
+ * The default stays closed.
+ */
+export async function scopedOutputDirectory(
+  root: string,
+  requested: string,
+  allowOutsideRoot: boolean,
+): Promise<string> {
+  const absolute = await assertPathWithinRoot(root, path.resolve(root, requested), allowOutsideRoot);
+  const relative = path.relative(root, absolute);
+  if (!relative) return '.';
+  return relative.startsWith('..') ? absolute : relative;
+}
+
+export function commonPipelineOptions(options: WorkspaceComparisonOptions, config: T2CConfig): PipelineOptions {
+  return {
+    root: options.root,
+    taskFile: defaulted(options.taskFile, null),
+    todoFile: options.todoFile === undefined ? 'TODO.md' : options.todoFile,
+    changelogFile: options.changelogFile === undefined ? 'CHANGELOG.md' : options.changelogFile,
+    documentPatterns: defaulted(options.documentPatterns, config.documentPatterns),
+    documentExcludes: defaulted(options.documentExcludes, config.documentExcludes),
+    includeDocumentationLlm: defaulted(options.includeDocumentationLlm, false),
+    outputDir: defaulted(options.outputDir, config.outputDir),
+    gitCommitCount: defaulted(options.gitCommitCount, config.gitCommitCount),
+    allowSummaryFallback: true,
+    includeSummaryLlm: false,
+    nlMode: config.nlMode,
+    markdownMode: defaulted(options.markdownMode, config.markdownMode),
+    communicationMode: defaulted(options.communicationMode, config.communicationMode),
+  };
+}
+
+function defaulted<T>(value: T | undefined, fallback: T): T {
+  return value === undefined ? fallback : value;
+}
+
+export async function optionsForRoot(root: string, options: PipelineOptions): Promise<PipelineOptions> {
+  return {
+    ...options,
+    taskFile: await existingFile(root, options.taskFile),
+    todoFile: await existingFile(root, options.todoFile),
+    changelogFile: await existingFile(root, options.changelogFile),
+  };
+}
+
+async function existingFile(root: string, file: string | null): Promise<string | null> {
+  if (!file) return null;
+  const relative = path.isAbsolute(file) ? path.relative(root, file) : file;
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return await pathExists(path.resolve(root, relative)) ? relative : null;
+}
+
+export function coverage(view: IntentRealityView, diagnostics: DiagnosticReport): CoverageSnapshot {
+  return {
+    ...view.totals,
+    alignmentRate: view.totals.topics ? rounded(view.totals.aligned / view.totals.topics) : 1,
+    diagnostics: { ...diagnostics.counts },
+  };
+}
+
+export function diagnosticDelta(before: DiagnosticReport, after: DiagnosticReport): DiagnosticReport['counts'] {
+  return {
+    info: after.counts.info - before.counts.info,
+    warning: after.counts.warning - before.counts.warning,
+    review_required: after.counts.review_required - before.counts.review_required,
+    blocking: after.counts.blocking - before.counts.blocking,
+  };
+}
+
+export function parseAheadBehind(value: string): [number, number] {
+  const [behind = '0', ahead = '0'] = value.trim().split(/\s+/);
+  return [Number(behind) || 0, Number(ahead) || 0];
+}
+
+export function defaultBaseRef(): string {
+  return 'origin/main';
+}
+
+export function rounded(value: number): number {
+  return Math.round(value * 10_000) / 10_000;
+}
+
+export async function git(cwd: string, args: string[]): Promise<string> {
+  const result = await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  return result.stdout;
+}