@contextrail/code-review-agent 0.1.1-alpha.0

package/dist/output/schema.js

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+/**
+ * Individual finding schema.
+ * Matches the finding structure from reviewerFindingsSchema.
+ */
+/**
+ * Azure JSON Schema validator workaround:
+ * Azure incorrectly requires ALL properties to be in the 'required' array, even optional ones.
+ * To work around this, we make optional fields nullable and required, then filter nulls in post-processing.
+ * This satisfies Azure's broken validator while maintaining optional semantics.
+ */
+export const findingSchema = z.object({
+    severity: z.enum(['critical', 'major', 'minor', 'info', 'pass']).describe('Severity level - REQUIRED'),
+    title: z.string().describe('Finding title - REQUIRED'),
+    description: z.string().describe('Detailed description - REQUIRED'),
+    rationale: z.string().min(1).describe('Required explanation of why this finding was identified - REQUIRED'),
+    // Azure workaround: Make optional fields nullable and required, filter nulls later.
+    // IMPORTANT: Do NOT use .default(null) here. In AI SDK JSON Schema conversion,
+    // .default() keeps the field out of "required", which Azure rejects.
+    suggestedFix: z
+        .string()
+        .nullable()
+        .describe('Optional suggested fix or remediation steps - Use null if not applicable (will be filtered out)'),
+    file: z
+        .string()
+        .nullable()
+        .describe('File path (relative to repo root) - Use null if finding is not file-specific (will be filtered out)'),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .describe('Start line number - Use null if finding is not line-specific (will be filtered out)'),
+    endLine: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .describe('End line number - Use null if finding does not span multiple lines (will be filtered out)'),
+    contextIdsUsed: z
+        .array(z.string())
+        .nullable()
+        .describe('ContextRail IDs used in the review - Use null if no ContextRail standards were referenced (will be filtered out)'),
+    contextIdsViolated: z
+        .array(z.string())
+        .nullable()
+        .describe('ContextRail IDs violated in the review - Use null if no ContextRail standards were violated (will be filtered out)'),
+    contextTitles: z
+        .array(z.string())
+        .nullable()
+        .describe('ContextRail standard names violated in the review - Use null if no ContextRail standards were referenced/violated (will be filtered out)'),
+});
+/**
+ * Normalize LLM finding shape for provider/schema compatibility.
+ * Azure requires all properties to be present in JSON schema outputs, so
+ * nullable fields must remain present (as null) rather than being removed.
+ * Empty attribution arrays are normalized to null for consistency.
+ */
+export const cleanFinding = (finding) => {
+    const toNullable = (value) => value ?? null;
+    return {
+        ...finding,
+        // Keep runtime payloads resilient if upstream providers emit undefined.
+        suggestedFix: toNullable(finding.suggestedFix),
+        file: toNullable(finding.file),
+        line: toNullable(finding.line),
+        endLine: toNullable(finding.endLine),
+        contextIdsUsed: finding.contextIdsUsed && finding.contextIdsUsed.length > 0 ? finding.contextIdsUsed : null,
+        contextIdsViolated: finding.contextIdsViolated && finding.contextIdsViolated.length > 0 ? finding.contextIdsViolated : null,
+        contextTitles: finding.contextTitles && finding.contextTitles.length > 0 ? finding.contextTitles : null,
+    };
+};
+/**
+ * Reviewer findings schema.
+ * Used by agentic executor output.
+ */
+export const reviewerFindingsSchema = z.object({
+    findings: z.array(findingSchema).describe('List of findings from the review'),
+    validated: z.boolean().describe('Whether findings have been validated and are ready'),
+    notes: z.string().nullable().describe('Additional notes about the review (null if none)'),
+});
+/**
+ * Per-reviewer result schema.
+ * Includes reviewer name and their findings.
+ */
+export const reviewerResultSchema = z.object({
+    reviewer: z.string().describe('Reviewer name (e.g., reviewer-security)'),
+    findings: z.array(findingSchema).describe('List of findings from this reviewer'),
+    validated: z.boolean().describe('Whether findings have been validated'),
+    notes: z.string().optional().describe('Additional notes about the review'),
+});
+/**
+ * Overall review decision schema.
+ */
+export const reviewDecisionSchema = z.object({
+    decision: z.enum(['approve', 'request-changes']).describe('Overall review decision'),
+    summary: z.string().describe('Concise overall review summary'),
+    rationale: z.string().describe('Reasoning for the decision'),
+});
+/**
+ * Summary statistics schema.
+ */
+export const summarySchema = z.object({
+    totalFindings: z.number().int().nonnegative().describe('Total number of non-pass findings across all reviewers'),
+    bySeverity: z
+        .object({
+        critical: z.number().int().nonnegative(),
+        major: z.number().int().nonnegative(),
+        minor: z.number().int().nonnegative(),
+        info: z.number().int().nonnegative(),
+        pass: z.number().int().nonnegative(),
+    })
+        .describe('Count of findings by severity level'),
+    byReviewer: z.record(z.string(), z.number().int().nonnegative()).describe('Count of findings by reviewer name'),
+});
+/**
+ * Review metadata schema.
+ */
+export const metadataSchema = z.object({
+    timestamp: z.string().describe('ISO 8601 timestamp of review completion'),
+    mode: z.enum(['diff', 'file-list']).describe('Review input mode'),
+    fileCount: z.number().int().positive().describe('Number of files reviewed'),
+});
+/**
+ * Complete aggregated review result schema.
+ */
+export const reviewResultSchema = z.object({
+    metadata: metadataSchema,
+    understanding: z.string().describe('Orchestrator understanding of the changes'),
+    decision: reviewDecisionSchema,
+    failures: z
+        .array(z.object({
+        reviewer: z.string().describe('Reviewer name that failed'),
+        message: z.string().describe('Failure message'),
+    }))
+        .optional()
+        .describe('Reviewer failures encountered during execution'),
+    synthesis: z
+        .lazy(() => synthesisResultSchema)
+        .optional()
+        .describe('Optional synthesized/deduplicated findings and contradictions'),
+    reviewers: z.array(reviewerResultSchema).min(1).describe('Review results from each reviewer'),
+    summary: summarySchema,
+});
+/**
+ * Token usage schema for a single operation (iteration, chunk, etc.)
+ */
+export const tokenUsageSchema = z.object({
+    promptTokens: z.number().int().nonnegative().describe('Number of prompt tokens used'),
+    completionTokens: z.number().int().nonnegative().describe('Number of completion tokens used'),
+    totalTokens: z.number().int().nonnegative().describe('Total tokens used'),
+});
+/**
+ * Per-chunk token usage schema.
+ */
+export const chunkTokenUsageSchema = z.object({
+    chunkIndex: z.number().int().nonnegative().describe('Chunk index (0-based)'),
+    usage: tokenUsageSchema,
+});
+/**
+ * Per-iteration token usage schema.
+ */
+export const iterationTokenUsageSchema = z.object({
+    iteration: z.number().int().positive().describe('Iteration number (1-based)'),
+    usage: tokenUsageSchema,
+    chunks: z.array(chunkTokenUsageSchema).optional().describe('Per-chunk usage if chunked'),
+});
+/**
+ * Per-reviewer token budget metrics schema.
+ */
+export const reviewerTokenMetricsSchema = z.object({
+    reviewer: z.string().describe('Reviewer name'),
+    totalUsage: tokenUsageSchema.describe('Total token usage across all iterations'),
+    iterations: z.array(iterationTokenUsageSchema).describe('Token usage per iteration'),
+});
+/**
+ * Aggregation token usage schema.
+ */
+export const aggregationTokenUsageSchema = z.object({
+    operation: z.string().describe('Operation name (e.g., "review-decision")'),
+    usage: tokenUsageSchema,
+});
+/**
+ * Complete token budget metrics schema.
+ */
+export const tokenBudgetMetricsSchema = z.object({
+    reviewers: z.array(reviewerTokenMetricsSchema).describe('Token usage per reviewer'),
+    aggregation: z.array(aggregationTokenUsageSchema).optional().describe('Token usage for aggregation operations'),
+    totalUsage: tokenUsageSchema.describe('Total token usage across all reviewers and operations'),
+});
+/**
+ * Synthesized finding schema.
+ * Includes source reviewer attribution for deduplicated findings.
+ */
+export const synthesizedFindingSchema = findingSchema.extend({
+    sourceReviewers: z.array(z.string()).min(1).describe('Reviewer names that identified this finding'),
+});
+/**
+ * Contradiction schema.
+ * Flags when reviewers disagree about the same issue.
+ */
+export const contradictionSchema = z.object({
+    findingA: z.string().describe('Description of first finding/claim'),
+    findingB: z.string().describe('Description of contradictory finding/claim'),
+    reviewerA: z.string().describe('Reviewer name for finding A'),
+    reviewerB: z.string().describe('Reviewer name for finding B'),
+    context: z.string().describe('Context explaining the contradiction'),
+});
+/**
+ * Synthesis result schema.
+ * Output from cross-reviewer synthesis step.
+ */
+export const synthesisResultSchema = z.object({
+    findings: z.array(synthesizedFindingSchema).describe('Deduplicated findings with source attribution'),
+    contradictions: z.array(contradictionSchema).describe('List of contradictions between reviewers'),
+    compoundRisks: z
+        .array(z.object({
+        description: z.string().describe('Description of the compound risk'),
+        affectedFindings: z.array(z.string()).describe('Titles of findings that contribute to this risk'),
+        severity: z.enum(['critical', 'major', 'minor', 'info']).describe('Overall severity of compound risk'),
+    }))
+        .describe('Compound risks identified from multiple findings'),
+    notes: z.string().nullable().describe('Additional synthesis notes (null if none)'),
+});

package/dist/output/writer.d.ts

@@ -0,0 +1,31 @@
+import { type ReviewResult, type ReviewerResult, type Metadata, type ReviewDecision, type AggregationTokenUsage, type SynthesisResult } from './schema.js';
+/**
+ * Aggregate orchestrator and reviewer outputs into final result structure.
+ *
+ * @param metadata - Review metadata (timestamp, mode, fileCount)
+ * @param understanding - Orchestrator's understanding of changes
+ * @param reviewerResults - Array of reviewer results (name + findings)
+ * @returns Aggregated review result with computed summary statistics
+ */
+export declare const aggregateResults: (metadata: Metadata, understanding: string, decision: ReviewDecision, reviewerResults: ReviewerResult[], failures?: Array<{
+    reviewer: string;
+    message: string;
+}>, synthesis?: SynthesisResult) => ReviewResult;
+/**
+ * Validate result against schema and write to result.json.
+ * Throws error if validation fails.
+ *
+ * @param outputDir - Output directory path
+ * @param result - Review result to validate and write
+ * @throws Error if validation fails or file write fails
+ */
+export declare const writeResult: (outputDir: string, result: ReviewResult) => Promise<void>;
+/**
+ * Aggregate token budget metrics from all reviewers and write to token-budget.json.
+ *
+ * @param outputDir - Output directory path
+ * @param reviewerNames - List of reviewer names that were executed
+ * @param aggregationUsage - Optional aggregation token usage
+ * @throws Error if file read/write fails
+ */
+export declare const writeTokenBudgetMetrics: (outputDir: string, reviewerNames: string[], aggregationUsage?: AggregationTokenUsage[]) => Promise<void>;

package/dist/output/writer.js

@@ -0,0 +1,120 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { reviewResultSchema, tokenBudgetMetricsSchema, } from './schema.js';
+/**
+ * Aggregate orchestrator and reviewer outputs into final result structure.
+ *
+ * @param metadata - Review metadata (timestamp, mode, fileCount)
+ * @param understanding - Orchestrator's understanding of changes
+ * @param reviewerResults - Array of reviewer results (name + findings)
+ * @returns Aggregated review result with computed summary statistics
+ */
+export const aggregateResults = (metadata, understanding, decision, reviewerResults, failures, synthesis) => {
+    // Collect all findings across reviewers
+    const allFindings = reviewerResults.flatMap((rr) => rr.findings);
+    const summaryFindings = synthesis?.findings ?? allFindings;
+    const summaryNonPassFindings = summaryFindings.filter((f) => f.severity !== 'pass');
+    // Compute summary statistics
+    const bySeverity = {
+        critical: summaryFindings.filter((f) => f.severity === 'critical').length,
+        major: summaryFindings.filter((f) => f.severity === 'major').length,
+        minor: summaryFindings.filter((f) => f.severity === 'minor').length,
+        info: summaryFindings.filter((f) => f.severity === 'info').length,
+        pass: summaryFindings.filter((f) => f.severity === 'pass').length,
+    };
+    const byReviewer = {};
+    for (const rr of reviewerResults) {
+        byReviewer[rr.reviewer] = rr.findings.filter((f) => f.severity !== 'pass').length;
+    }
+    const summary = {
+        totalFindings: summaryNonPassFindings.length,
+        bySeverity,
+        byReviewer,
+    };
+    return {
+        metadata,
+        understanding,
+        decision,
+        failures: failures && failures.length > 0 ? failures : undefined,
+        synthesis,
+        reviewers: reviewerResults,
+        summary,
+    };
+};
+/**
+ * Validate result against schema and write to result.json.
+ * Throws error if validation fails.
+ *
+ * @param outputDir - Output directory path
+ * @param result - Review result to validate and write
+ * @throws Error if validation fails or file write fails
+ */
+export const writeResult = async (outputDir, result) => {
+    // Validate against schema
+    const validatedResult = reviewResultSchema.parse(result);
+    // Write result.json
+    await mkdir(outputDir, { recursive: true });
+    const resultPath = path.join(outputDir, 'result.json');
+    await writeFile(resultPath, JSON.stringify(validatedResult, null, 2), 'utf-8');
+};
+/**
+ * Aggregate token budget metrics from all reviewers and write to token-budget.json.
+ *
+ * @param outputDir - Output directory path
+ * @param reviewerNames - List of reviewer names that were executed
+ * @param aggregationUsage - Optional aggregation token usage
+ * @throws Error if file read/write fails
+ */
+export const writeTokenBudgetMetrics = async (outputDir, reviewerNames, aggregationUsage) => {
+    const reviewersDir = path.join(outputDir, 'reviewers');
+    const reviewerMetrics = [];
+    // Read token metrics from each reviewer directory
+    for (const reviewer of reviewerNames) {
+        const reviewerDir = path.join(reviewersDir, reviewer);
+        const tokenBudgetPath = path.join(reviewerDir, 'token-budget.json');
+        try {
+            const content = await readFile(tokenBudgetPath, 'utf-8');
+            const metrics = JSON.parse(content);
+            reviewerMetrics.push(metrics);
+        }
+        catch (error) {
+            // If token-budget.json doesn't exist, skip this reviewer.
+            // This can happen when a reviewer fails before completing an iteration.
+            if (error.code !== 'ENOENT') {
+                console.warn(`Error reading token budget metrics for reviewer ${reviewer}:`, error);
+            }
+            continue;
+        }
+    }
+    // Calculate total usage across all reviewers and aggregation
+    let totalPromptTokens = 0;
+    let totalCompletionTokens = 0;
+    let totalTokens = 0;
+    for (const rm of reviewerMetrics) {
+        totalPromptTokens += rm.totalUsage.promptTokens;
+        totalCompletionTokens += rm.totalUsage.completionTokens;
+        totalTokens += rm.totalUsage.totalTokens;
+    }
+    if (aggregationUsage) {
+        for (const agg of aggregationUsage) {
+            totalPromptTokens += agg.usage.promptTokens;
+            totalCompletionTokens += agg.usage.completionTokens;
+            totalTokens += agg.usage.totalTokens;
+        }
+    }
+    const metrics = {
+        reviewers: reviewerMetrics,
+        aggregation: aggregationUsage && aggregationUsage.length > 0 ? aggregationUsage : undefined,
+        totalUsage: {
+            promptTokens: totalPromptTokens,
+            completionTokens: totalCompletionTokens,
+            totalTokens,
+        },
+    };
+    // Validate against schema
+    const validatedMetrics = tokenBudgetMetricsSchema.parse(metrics);
+    // Write token-budget.json
+    await mkdir(outputDir, { recursive: true });
+    const metricsPath = path.join(outputDir, 'token-budget.json');
+    await writeFile(metricsPath, JSON.stringify(validatedMetrics, null, 2), 'utf-8');
+};

package/dist/review-inputs/chunking.d.ts

@@ -0,0 +1,29 @@
+import type { ReviewInputs } from './index.js';
+/**
+ * Configuration for chunking review inputs.
+ */
+export type ChunkingConfig = {
+    /**
+     * Maximum tokens per chunk (approximate).
+     * Default: 100000 (roughly 400KB of text)
+     */
+    maxTokensPerChunk?: number;
+    /**
+     * Maximum files per chunk.
+     * Default: 50
+     */
+    maxFilesPerChunk?: number;
+};
+/**
+ * Chunk of review inputs for processing.
+ */
+export type ReviewInputChunk = ReviewInputs;
+/**
+ * Chunk review inputs into smaller batches for processing.
+ * Chunks are created based on token budget and file count limits.
+ *
+ * @param inputs - Review inputs to chunk
+ * @param config - Chunking configuration
+ * @returns Array of input chunks (may be single chunk if inputs are small)
+ */
+export declare const chunkReviewInputs: (inputs: ReviewInputs, config?: ChunkingConfig) => ReviewInputChunk[];

package/dist/review-inputs/chunking.js

@@ -0,0 +1,113 @@
+import { isDiffInputs, isFileListInputs } from './index.js';
+const DEFAULT_MAX_TOKENS_PER_CHUNK = 100_000;
+const DEFAULT_MAX_FILES_PER_CHUNK = 50;
+/**
+ * Rough token estimation: ~4 characters per token.
+ * This is a conservative estimate for code/diff content.
+ */
+const estimateTokens = (text) => {
+    return Math.ceil(text.length / 4);
+};
+/**
+ * Chunk diff inputs based on token budget and file count limits.
+ *
+ * @param inputs - Diff review inputs to chunk
+ * @param config - Chunking configuration
+ * @returns Array of input chunks
+ */
+const chunkDiffInputs = (inputs, config) => {
+    const maxTokens = config.maxTokensPerChunk ?? DEFAULT_MAX_TOKENS_PER_CHUNK;
+    const maxFiles = config.maxFilesPerChunk ?? DEFAULT_MAX_FILES_PER_CHUNK;
+    // If inputs fit within limits, return as single chunk
+    const totalTokens = Object.values(inputs.diffs).reduce((sum, diff) => sum + estimateTokens(diff), 0);
+    const totalFiles = inputs.files.length;
+    if (totalTokens <= maxTokens && totalFiles <= maxFiles) {
+        return [inputs];
+    }
+    // Need to chunk: group files into chunks
+    const chunks = [];
+    let currentChunkFiles = [];
+    let currentChunkDiffs = {};
+    let currentChunkTokens = 0;
+    let currentChunkFileCount = 0;
+    for (const file of inputs.files) {
+        const diff = inputs.diffs[file];
+        if (!diff) {
+            continue;
+        }
+        const fileTokens = estimateTokens(diff);
+        // Check if adding this file would exceed limits
+        const wouldExceedTokens = currentChunkTokens + fileTokens > maxTokens;
+        const wouldExceedFiles = currentChunkFileCount >= maxFiles;
+        if ((wouldExceedTokens || wouldExceedFiles) && currentChunkFiles.length > 0) {
+            // Finalize current chunk
+            chunks.push({
+                mode: 'diff',
+                files: currentChunkFiles,
+                diffs: currentChunkDiffs,
+            });
+            // Start new chunk
+            currentChunkFiles = [];
+            currentChunkDiffs = {};
+            currentChunkTokens = 0;
+            currentChunkFileCount = 0;
+        }
+        // Add file to current chunk
+        currentChunkFiles.push(file);
+        currentChunkDiffs[file] = diff;
+        currentChunkTokens += fileTokens;
+        currentChunkFileCount += 1;
+    }
+    // Add final chunk if it has files
+    if (currentChunkFiles.length > 0) {
+        chunks.push({
+            mode: 'diff',
+            files: currentChunkFiles,
+            diffs: currentChunkDiffs,
+        });
+    }
+    return chunks;
+};
+/**
+ * Chunk file-list inputs based on file count limits.
+ *
+ * @param inputs - File-list review inputs to chunk
+ * @param config - Chunking configuration
+ * @returns Array of input chunks
+ */
+const chunkFileListInputs = (inputs, config) => {
+    const maxFiles = config.maxFilesPerChunk ?? DEFAULT_MAX_FILES_PER_CHUNK;
+    // If inputs fit within limits, return as single chunk
+    if (inputs.files.length <= maxFiles) {
+        return [inputs];
+    }
+    // Need to chunk: split files into groups
+    const chunks = [];
+    for (let i = 0; i < inputs.files.length; i += maxFiles) {
+        const chunkFiles = inputs.files.slice(i, i + maxFiles);
+        chunks.push({
+            mode: 'file-list',
+            files: chunkFiles,
+        });
+    }
+    return chunks;
+};
+/**
+ * Chunk review inputs into smaller batches for processing.
+ * Chunks are created based on token budget and file count limits.
+ *
+ * @param inputs - Review inputs to chunk
+ * @param config - Chunking configuration
+ * @returns Array of input chunks (may be single chunk if inputs are small)
+ */
+export const chunkReviewInputs = (inputs, config = {}) => {
+    if (isDiffInputs(inputs)) {
+        return chunkDiffInputs(inputs, config);
+    }
+    if (isFileListInputs(inputs)) {
+        return chunkFileListInputs(inputs, config);
+    }
+    // TypeScript exhaustiveness check
+    const _exhaustive = inputs;
+    return _exhaustive;
+};

package/dist/review-inputs/diff-summary.d.ts

@@ -0,0 +1,52 @@
+import type { ReviewInputs } from './index.js';
+/**
+ * Statistics for a single file diff.
+ */
+export type FileDiffStats = {
+    /**
+     * File path (relative to repo root).
+     */
+    file: string;
+    /**
+     * File extension (e.g., '.ts', '.js', '.md').
+     * Empty string if no extension.
+     */
+    fileType: string;
+    /**
+     * Number of lines added.
+     */
+    added: number;
+    /**
+     * Number of lines removed.
+     */
+    removed: number;
+};
+/**
+ * Summary of diff statistics across all files.
+ */
+export type DiffSummary = {
+    /**
+     * Per-file diff statistics.
+     */
+    files: FileDiffStats[];
+    /**
+     * Total files changed.
+     */
+    totalFiles: number;
+    /**
+     * Total lines added across all files.
+     */
+    totalAdded: number;
+    /**
+     * Total lines removed across all files.
+     */
+    totalRemoved: number;
+};
+/**
+ * Generate diff summary statistics from review inputs.
+ * Only processes diff inputs; file-list inputs return empty summary.
+ *
+ * @param inputs - Review inputs (diff or file-list)
+ * @returns Diff summary with per-file stats and totals
+ */
+export declare const generateDiffSummary: (inputs: ReviewInputs) => DiffSummary;

package/dist/review-inputs/diff-summary.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { isDiffInputs } from './index.js';
+/**
+ * Parse a git diff to count added and removed lines.
+ * Handles unified diff format (default git diff output).
+ *
+ * @param diff - Git diff content
+ * @returns Object with added and removed line counts
+ */
+const parseDiffStats = (diff) => {
+    let added = 0;
+    let removed = 0;
+    // Git unified diff format:
+    // Lines starting with '+' are additions (except '+++')
+    // Lines starting with '-' are removals (except '---')
+    // Lines starting with '@@' are hunk headers
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        // Skip hunk headers and file headers
+        if (line.startsWith('@@') || line.startsWith('+++') || line.startsWith('---')) {
+            continue;
+        }
+        // Count additions (lines starting with '+')
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            added++;
+        }
+        // Count removals (lines starting with '-')
+        if (line.startsWith('-') && !line.startsWith('---')) {
+            removed++;
+        }
+    }
+    return { added, removed };
+};
+/**
+ * Extract file extension from a file path.
+ *
+ * @param filePath - File path
+ * @returns File extension (e.g., '.ts', '.js', '.md') or empty string
+ */
+const getFileType = (filePath) => {
+    const ext = path.extname(filePath);
+    return ext;
+};
+/**
+ * Generate diff summary statistics from review inputs.
+ * Only processes diff inputs; file-list inputs return empty summary.
+ *
+ * @param inputs - Review inputs (diff or file-list)
+ * @returns Diff summary with per-file stats and totals
+ */
+export const generateDiffSummary = (inputs) => {
+    if (!isDiffInputs(inputs)) {
+        // File-list mode: return empty summary
+        return {
+            files: [],
+            totalFiles: inputs.files.length,
+            totalAdded: 0,
+            totalRemoved: 0,
+        };
+    }
+    const fileStats = [];
+    let totalAdded = 0;
+    let totalRemoved = 0;
+    for (const file of inputs.files) {
+        const diff = inputs.diffs[file] || '';
+        const { added, removed } = parseDiffStats(diff);
+        const fileType = getFileType(file);
+        fileStats.push({
+            file,
+            fileType,
+            added,
+            removed,
+        });
+        totalAdded += added;
+        totalRemoved += removed;
+    }
+    return {
+        files: fileStats,
+        totalFiles: fileStats.length,
+        totalAdded,
+        totalRemoved,
+    };
+};