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

package/dist/review-inputs/surrounding-context.js

@@ -0,0 +1,180 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isDiffInputs, isFileListInputs } from './index.js';
+import { validateAndNormalizePath } from './path-validation.js';
+const DEFAULT_MAX_TOKENS_PER_FILE = 20_000;
+const DEFAULT_CONTEXT_LINES = 10;
+/**
+ * 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);
+};
+/**
+ * Extract line numbers from a diff that have changes (additions or deletions).
+ * Returns a set of line numbers (1-indexed) in the new file version.
+ */
+const extractChangedLines = (diff) => {
+    const changedLines = new Set();
+    const lines = diff.split('\n');
+    let currentLine = 0;
+    for (const line of lines) {
+        if (line.startsWith('@@')) {
+            // Parse hunk header: @@ -oldStart,oldCount +newStart,newCount @@
+            const match = line.match(/@@\s*-\d+(?:,\d+)?\s*\+(\d+)(?:,(\d+))?/);
+            if (match && match[1]) {
+                currentLine = parseInt(match[1], 10);
+            }
+            continue;
+        }
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            // Added line
+            changedLines.add(currentLine);
+            currentLine++;
+        }
+        else if (line.startsWith('-') && !line.startsWith('---')) {
+            // Deleted line (don't increment currentLine as it's in old version)
+            // But we still want context around deletions
+            if (currentLine > 0) {
+                changedLines.add(currentLine);
+            }
+        }
+        else if (!line.startsWith('\\')) {
+            // Context line (unchanged)
+            currentLine++;
+        }
+    }
+    return changedLines;
+};
+/**
+ * Extract windowed context around changed lines.
+ * Returns the file content with only the relevant windowed sections.
+ */
+const extractWindowedContext = (fileContent, changedLines, contextLines) => {
+    const lines = fileContent.split('\n');
+    const includedLines = new Set();
+    // Mark changed lines and surrounding context
+    for (const changedLine of changedLines) {
+        const start = Math.max(1, changedLine - contextLines);
+        const end = Math.min(lines.length, changedLine + contextLines);
+        for (let i = start; i <= end; i++) {
+            includedLines.add(i);
+        }
+    }
+    // Build result with line numbers and ellipsis for gaps
+    const result = [];
+    let lastIncluded = 0;
+    for (let i = 1; i <= lines.length; i++) {
+        if (includedLines.has(i)) {
+            if (lastIncluded > 0 && i - lastIncluded > 1) {
+                // Add ellipsis for gap
+                result.push(`// ... (${i - lastIncluded - 1} lines omitted) ...`);
+            }
+            const line = lines[i - 1];
+            if (line !== undefined) {
+                result.push(line);
+            }
+            lastIncluded = i;
+        }
+    }
+    return result.join('\n');
+};
+/**
+ * Extract full file content or windowed excerpt based on token budget.
+ */
+const extractFileContext = async (filePath, diff, config) => {
+    const maxTokens = config.maxTokensPerFile ?? DEFAULT_MAX_TOKENS_PER_FILE;
+    const contextLines = config.contextLines ?? DEFAULT_CONTEXT_LINES;
+    try {
+        // Validate path to prevent path traversal attacks
+        if (!config.basePath) {
+            throw new Error('basePath is required for path validation');
+        }
+        const validatedPath = validateAndNormalizePath(filePath, config.basePath);
+        const resolvedPath = path.resolve(config.basePath, validatedPath);
+        const fileContent = await readFile(resolvedPath, 'utf-8');
+        const fileTokens = estimateTokens(fileContent);
+        // If file fits within budget, return full content
+        if (fileTokens <= maxTokens) {
+            return fileContent;
+        }
+        // If we have a diff, extract windowed context around changed lines
+        if (diff) {
+            const changedLines = extractChangedLines(diff);
+            if (changedLines.size > 0) {
+                const windowed = extractWindowedContext(fileContent, changedLines, contextLines);
+                const windowedTokens = estimateTokens(windowed);
+                // If windowed context fits, return it
+                if (windowedTokens <= maxTokens) {
+                    return windowed;
+                }
+                // Otherwise, return truncated version with note
+                const truncated = fileContent.slice(0, maxTokens * 4);
+                return `${truncated}\n// ... (file truncated due to token budget) ...`;
+            }
+        }
+        // No diff or no changed lines: return truncated version
+        const truncated = fileContent.slice(0, maxTokens * 4);
+        return `${truncated}\n// ... (file truncated due to token budget) ...`;
+    }
+    catch {
+        // File not found or unreadable - return null to indicate no context available
+        return null;
+    }
+};
+/**
+ * Extract surrounding context for diff review inputs.
+ */
+const extractDiffContext = async (inputs, config) => {
+    const context = {};
+    for (const file of inputs.files) {
+        const diff = inputs.diffs[file];
+        const fileContext = await extractFileContext(file, diff, {
+            ...config,
+            basePath: config.basePath,
+        });
+        if (fileContext !== null) {
+            context[file] = fileContext;
+        }
+    }
+    return context;
+};
+/**
+ * Extract surrounding context for file-list review inputs.
+ */
+const extractFileListContext = async (inputs, config) => {
+    if (!config.basePath) {
+        throw new Error('basePath is required for file-list mode context extraction');
+    }
+    const context = {};
+    for (const file of inputs.files) {
+        const fileContext = await extractFileContext(file, undefined, config);
+        if (fileContext !== null) {
+            context[file] = fileContext;
+        }
+    }
+    return context;
+};
+/**
+ * Extract surrounding code context for review inputs.
+ * Returns a map of file paths to their context (full file or windowed excerpt).
+ *
+ * @param inputs - Review inputs (diff or file-list)
+ * @param config - Context extraction configuration
+ * @returns Map of file paths to context strings (null values indicate unavailable context)
+ */
+export const extractSurroundingContext = async (inputs, config = {}) => {
+    if (config.enabled === false) {
+        return {};
+    }
+    if (isDiffInputs(inputs)) {
+        return extractDiffContext(inputs, config);
+    }
+    if (isFileListInputs(inputs)) {
+        return extractFileListContext(inputs, config);
+    }
+    // TypeScript exhaustiveness check
+    const _exhaustive = inputs;
+    return _exhaustive;
+};

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

@@ -0,0 +1,57 @@
+import type { ReviewInputs } from './index.js';
+/**
+ * Configuration for PR triage.
+ */
+export type TriageConfig = {
+    /**
+     * Maximum number of files to consider a PR trivial.
+     * Default: DEFAULT_TRIAGE_MAX_FILES
+     */
+    maxFiles?: number;
+    /**
+     * Maximum total lines changed (added + removed) to consider a PR trivial.
+     * Default: DEFAULT_TRIAGE_MAX_TOTAL_LINES
+     */
+    maxTotalLines?: number;
+    /**
+     * File extensions considered documentation-only.
+     * Default: DEFAULT_TRIAGE_DOCS_ONLY_EXTENSIONS
+     */
+    docsOnlyExtensions?: ReadonlyArray<string>;
+};
+/**
+ * Result of triage analysis.
+ */
+export type TriageResult = {
+    /**
+     * Whether the PR is considered trivial.
+     */
+    isTrivial: boolean;
+    /**
+     * Reason for the triage decision.
+     */
+    reason: string;
+    /**
+     * Whether the PR contains only documentation files.
+     */
+    isDocsOnly: boolean;
+    /**
+     * Number of files changed.
+     */
+    fileCount: number;
+    /**
+     * Total lines changed (added + removed).
+     */
+    totalLinesChanged: number;
+};
+/**
+ * Analyze review inputs to determine if the PR is trivial.
+ * A PR is considered trivial if:
+ * - It contains only documentation files, OR
+ * - It has few files AND small total diff size
+ *
+ * @param inputs - Review inputs to analyze
+ * @param config - Triage configuration
+ * @returns Triage result with decision and metadata
+ */
+export declare const triagePr: (inputs: ReviewInputs, config?: TriageConfig) => TriageResult;

package/dist/review-inputs/triage.js

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { generateDiffSummary } from './diff-summary.js';
+import { DEFAULT_TRIAGE_MAX_FILES, DEFAULT_TRIAGE_MAX_TOTAL_LINES, DEFAULT_TRIAGE_DOCS_ONLY_EXTENSIONS, } from '../config/defaults.js';
+/**
+ * Check if a file extension is considered documentation-only.
+ *
+ * @param filePath - File path to check
+ * @param docsOnlyExtensions - List of documentation file extensions
+ * @returns True if file is documentation-only
+ */
+const isDocsOnlyFile = (filePath, docsOnlyExtensions) => {
+    const ext = path.extname(filePath).toLowerCase();
+    // Check extension
+    if (docsOnlyExtensions.includes(ext)) {
+        return true;
+    }
+    // Check common documentation filenames (case-insensitive)
+    const docsFilenames = ['readme', 'changelog', 'license', 'contributing', 'authors', 'credits'];
+    const baseName = path.basename(filePath, ext).toLowerCase();
+    if (docsFilenames.includes(baseName)) {
+        return true;
+    }
+    return false;
+};
+/**
+ * Analyze review inputs to determine if the PR is trivial.
+ * A PR is considered trivial if:
+ * - It contains only documentation files, OR
+ * - It has few files AND small total diff size
+ *
+ * @param inputs - Review inputs to analyze
+ * @param config - Triage configuration
+ * @returns Triage result with decision and metadata
+ */
+export const triagePr = (inputs, config = {}) => {
+    const maxFiles = config.maxFiles ?? DEFAULT_TRIAGE_MAX_FILES;
+    const maxTotalLines = config.maxTotalLines ?? DEFAULT_TRIAGE_MAX_TOTAL_LINES;
+    const docsOnlyExtensions = config.docsOnlyExtensions ?? DEFAULT_TRIAGE_DOCS_ONLY_EXTENSIONS;
+    const fileCount = inputs.files.length;
+    const summary = generateDiffSummary(inputs);
+    const totalLinesChanged = summary.totalAdded + summary.totalRemoved;
+    // Empty PRs are not trivial
+    if (fileCount === 0) {
+        return {
+            isTrivial: false,
+            reason: 'PR contains no files',
+            isDocsOnly: false,
+            fileCount: 0,
+            totalLinesChanged: 0,
+        };
+    }
+    // Check if all files are documentation-only
+    const allDocsOnly = inputs.files.every((file) => isDocsOnlyFile(file, docsOnlyExtensions));
+    if (allDocsOnly && fileCount > 0) {
+        return {
+            isTrivial: true,
+            reason: `PR contains only documentation files (${fileCount} file${fileCount === 1 ? '' : 's'})`,
+            isDocsOnly: true,
+            fileCount,
+            totalLinesChanged,
+        };
+    }
+    // Check if PR is small enough to be trivial
+    if (fileCount <= maxFiles && totalLinesChanged <= maxTotalLines) {
+        return {
+            isTrivial: true,
+            reason: `PR is small (${fileCount} file${fileCount === 1 ? '' : 's'}, ${totalLinesChanged} line${totalLinesChanged === 1 ? '' : 's'} changed)`,
+            isDocsOnly: false,
+            fileCount,
+            totalLinesChanged,
+        };
+    }
+    // PR is not trivial
+    return {
+        isTrivial: false,
+        reason: `PR exceeds trivial thresholds (${fileCount} file${fileCount === 1 ? '' : 's'}, ${totalLinesChanged} line${totalLinesChanged === 1 ? '' : 's'} changed)`,
+        isDocsOnly: false,
+        fileCount,
+        totalLinesChanged,
+    };
+};

package/dist/reviewers/executor.d.ts

@@ -0,0 +1,41 @@
+import type { ReviewInputs } from '../review-inputs/index.js';
+import { type ChunkingConfig } from '../review-inputs/chunking.js';
+import { type FilePatterns } from '../review-inputs/file-patterns.js';
+import type { McpClient } from '../mcp/client.js';
+import type { ReviewerFindings } from '../output/schema.js';
+import type { Logger } from '../logging/logger.js';
+/**
+ * Extract filePatterns from prompt metadata.
+ *
+ * @param metadata - Prompt metadata (may be undefined or have nested structure)
+ * @returns FilePatterns if found, undefined otherwise
+ */
+export declare function extractFilePatterns(metadata: unknown): FilePatterns | undefined;
+export type AgenticExecutorConfig = {
+    openRouterApiKey: string;
+    reviewerModel: string;
+    criticModel?: string;
+    maxSteps?: number;
+    maxIterations?: number;
+    chunking?: ChunkingConfig;
+    prDescription?: string;
+    reviewDomains?: string[];
+};
+export type AgenticExecutorDeps = {
+    mcpClient: McpClient;
+    config: AgenticExecutorConfig;
+    logger?: Logger;
+};
+/**
+ * Run reviewer loop with self-validation.
+ * Each iteration is a fresh generateText call (no history bleed).
+ * Based on context://agentic/execution/loop-orchestration
+ *
+ * @param reviewer - Reviewer name (e.g., 'reviewer-security')
+ * @param inputs - Review inputs (files, diffs)
+ * @param understanding - Orchestrator's understanding of changes
+ * @param outputDir - Base output directory
+ * @param deps - Dependencies (MCP client, config)
+ * @returns Reviewer findings
+ */
+export declare const runReviewerLoop: (reviewer: string, inputs: ReviewInputs, understanding: string, outputDir: string, deps: AgenticExecutorDeps) => Promise<ReviewerFindings>;