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

package/dist/review-inputs/file-patterns.d.ts

@@ -0,0 +1,40 @@
+/**
+ * File pattern configuration from prompt metadata
+ */
+export type FilePatterns = {
+    include?: string[];
+    exclude?: string[];
+};
+/**
+ * Check if a file matches file patterns from prompt metadata.
+ *
+ * Security improvements:
+ * - Validates and sanitizes patterns to prevent path traversal
+ * - Error handling for malformed glob patterns
+ * - Limits pattern complexity
+ *
+ * @param filename - File path to check
+ * @param filePatterns - File pattern configuration from prompt metadata
+ * @returns True if file should be included for review
+ */
+export declare function fileMatchesPatterns(filename: string, filePatterns?: FilePatterns): boolean;
+/**
+ * Filter files based on file patterns from prompt metadata.
+ *
+ * @param files - Array of file paths to filter
+ * @param filePatterns - File pattern configuration from prompt metadata
+ * @returns Filtered array of file paths
+ */
+export declare function filterFilesByPatterns(files: string[], filePatterns?: FilePatterns): string[];
+/**
+ * Filter diff inputs by file patterns from prompt metadata.
+ *
+ * @param files - Array of file paths
+ * @param diffs - Record of file paths to diff content
+ * @param filePatterns - File pattern configuration from prompt metadata
+ * @returns Filtered files and diffs
+ */
+export declare function filterDiffInputsByPatterns(files: string[], diffs: Record<string, string>, filePatterns?: FilePatterns): {
+    files: string[];
+    diffs: Record<string, string>;
+};

package/dist/review-inputs/file-patterns.js

@@ -0,0 +1,182 @@
+import { Minimatch } from 'minimatch';
+/**
+ * Security constants for input validation
+ */
+const MAX_STRING_LENGTH = 10000;
+/**
+ * Cache for compiled minimatch patterns to avoid recompilation
+ */
+const minimatchCache = new Map();
+/**
+ * Check if a pattern contains dangerous characters using safe string methods
+ */
+function hasDangerousPatternChars(pattern) {
+    // Use simple string methods instead of regex to avoid ReDoS
+    return (pattern.includes('..') || // Path traversal
+        pattern.startsWith('/') || // Absolute path
+        pattern.includes('\\') || // Backslash (Windows path separator)
+        pattern.includes('\x00') // Null byte
+    );
+}
+/**
+ * Validate and sanitize a file pattern to prevent path traversal
+ */
+function sanitizeFilePattern(pattern) {
+    if (!pattern || typeof pattern !== 'string') {
+        return null;
+    }
+    // Check for dangerous patterns using safe string methods (no ReDoS risk)
+    if (hasDangerousPatternChars(pattern)) {
+        return null;
+    }
+    // Limit length to prevent ReDoS in minimatch
+    if (pattern.length > MAX_STRING_LENGTH) {
+        return pattern.substring(0, MAX_STRING_LENGTH);
+    }
+    return pattern;
+}
+/**
+ * Get or compile a minimatch pattern with caching
+ */
+function getCompiledPattern(pattern) {
+    const cached = minimatchCache.get(pattern);
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        const compiled = new Minimatch(pattern, { dot: true, nocomment: true });
+        minimatchCache.set(pattern, compiled);
+        return compiled;
+    }
+    catch {
+        minimatchCache.set(pattern, null);
+        return null;
+    }
+}
+/**
+ * Normalize file path separators for cross-platform compatibility.
+ * Converts Windows backslashes to forward slashes for consistent glob matching.
+ */
+function normalizePath(path) {
+    return path.replace(/\\/g, '/');
+}
+/**
+ * Safely match a file against a compiled pattern
+ */
+function safeMinimatch(filename, pattern) {
+    const compiled = getCompiledPattern(pattern);
+    if (!compiled) {
+        return false;
+    }
+    try {
+        // Normalize filename to use forward slashes for consistent matching
+        const normalizedFilename = normalizePath(filename);
+        return compiled.match(normalizedFilename);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a file matches file patterns from prompt metadata.
+ *
+ * Security improvements:
+ * - Validates and sanitizes patterns to prevent path traversal
+ * - Error handling for malformed glob patterns
+ * - Limits pattern complexity
+ *
+ * @param filename - File path to check
+ * @param filePatterns - File pattern configuration from prompt metadata
+ * @returns True if file should be included for review
+ */
+export function fileMatchesPatterns(filename, filePatterns) {
+    // If no file patterns, include all files (backward compatible)
+    if (!filePatterns) {
+        return true;
+    }
+    // Validate filename
+    if (!filename || typeof filename !== 'string') {
+        return false;
+    }
+    const { include, exclude } = filePatterns;
+    try {
+        // Check exclude patterns first (higher priority)
+        if (exclude && Array.isArray(exclude) && exclude.length > 0) {
+            for (const pattern of exclude) {
+                const sanitized = sanitizeFilePattern(pattern);
+                if (!sanitized) {
+                    continue; // Skip invalid patterns
+                }
+                if (safeMinimatch(filename, sanitized)) {
+                    return false;
+                }
+            }
+        }
+        // If include patterns are specified, file must match at least one
+        if (include && Array.isArray(include) && include.length > 0) {
+            let hasMatch = false;
+            let hasValidPattern = false;
+            for (const pattern of include) {
+                const sanitized = sanitizeFilePattern(pattern);
+                if (!sanitized) {
+                    continue; // Skip invalid patterns
+                }
+                hasValidPattern = true;
+                if (safeMinimatch(filename, sanitized)) {
+                    hasMatch = true;
+                    break;
+                }
+            }
+            // Fail-safe: if all patterns were invalid, include the file
+            if (!hasValidPattern) {
+                return true;
+            }
+            if (!hasMatch) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        // Fail-safe: include file if pattern matching fails
+        return true;
+    }
+}
+/**
+ * Filter files based on file patterns from prompt metadata.
+ *
+ * @param files - Array of file paths to filter
+ * @param filePatterns - File pattern configuration from prompt metadata
+ * @returns Filtered array of file paths
+ */
+export function filterFilesByPatterns(files, filePatterns) {
+    if (!filePatterns) {
+        return files;
+    }
+    return files.filter((file) => fileMatchesPatterns(file, filePatterns));
+}
+/**
+ * Filter diff inputs by file patterns from prompt metadata.
+ *
+ * @param files - Array of file paths
+ * @param diffs - Record of file paths to diff content
+ * @param filePatterns - File pattern configuration from prompt metadata
+ * @returns Filtered files and diffs
+ */
+export function filterDiffInputsByPatterns(files, diffs, filePatterns) {
+    const filteredFiles = filterFilesByPatterns(files, filePatterns);
+    // Filter diffs to only include files that passed filtering
+    const filteredDiffs = {};
+    for (const file of filteredFiles) {
+        if (file in diffs) {
+            if (!diffs[file]) {
+                continue;
+            }
+            filteredDiffs[file] = diffs[file];
+        }
+    }
+    return {
+        files: filteredFiles,
+        diffs: filteredDiffs,
+    };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Configuration for file filtering.
+ */
+export type FilteringConfig = {
+    /**
+     * Patterns to exclude from review.
+     * Uses glob patterns (minimatch) for secure matching.
+     * Default: DEFAULT_EXCLUDE_PATTERNS
+     */
+    excludePatterns?: ReadonlyArray<string>;
+};
+/**
+ * Filter files based on exclude patterns.
+ *
+ * @param files - Array of file paths to filter
+ * @param config - Filtering configuration
+ * @returns Filtered array of file paths
+ */
+export declare const filterFiles: (files: string[], config?: FilteringConfig) => string[];
+/**
+ * Filter diff inputs by removing excluded files and their diffs.
+ *
+ * @param files - Array of file paths
+ * @param diffs - Record of file paths to diff content
+ * @param config - Filtering configuration
+ * @returns Filtered files and diffs
+ */
+export declare const filterDiffInputs: (files: string[], diffs: Record<string, string>, config?: FilteringConfig) => {
+    files: string[];
+    diffs: Record<string, string>;
+};

package/dist/review-inputs/filtering.js

@@ -0,0 +1,53 @@
+import { DEFAULT_EXCLUDE_PATTERNS } from '../config/defaults.js';
+import { fileMatchesPatterns } from './file-patterns.js';
+/**
+ * Check if a file path matches any exclude pattern.
+ * Uses minimatch for secure glob pattern matching (prevents ReDoS).
+ *
+ * @param filePath - File path to check (relative or absolute)
+ * @param patterns - Glob patterns to match against
+ * @returns True if file should be excluded
+ */
+const matchesExcludePattern = (filePath, patterns) => {
+    // Convert patterns to FilePatterns format for consistent matching
+    const filePatterns = {
+        exclude: [...patterns],
+    };
+    // Use fileMatchesPatterns which handles minimatch safely
+    // If file matches exclude patterns, it should be excluded
+    return !fileMatchesPatterns(filePath, filePatterns);
+};
+/**
+ * Filter files based on exclude patterns.
+ *
+ * @param files - Array of file paths to filter
+ * @param config - Filtering configuration
+ * @returns Filtered array of file paths
+ */
+export const filterFiles = (files, config = {}) => {
+    const patterns = config.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS;
+    return files.filter((file) => !matchesExcludePattern(file, patterns));
+};
+/**
+ * Filter diff inputs by removing excluded files and their diffs.
+ *
+ * @param files - Array of file paths
+ * @param diffs - Record of file paths to diff content
+ * @param config - Filtering configuration
+ * @returns Filtered files and diffs
+ */
+export const filterDiffInputs = (files, diffs, config = {}) => {
+    const filteredFiles = filterFiles(files, config);
+    // Filter diffs to only include files that passed filtering
+    const filteredDiffs = {};
+    for (const file of filteredFiles) {
+        const diff = diffs[file];
+        if (diff !== undefined) {
+            filteredDiffs[file] = diff;
+        }
+    }
+    return {
+        files: filteredFiles,
+        diffs: filteredDiffs,
+    };
+};

package/dist/review-inputs/git-diff-provider.d.ts

@@ -0,0 +1,2 @@
+import type { DiffProvider } from './index.js';
+export declare const gitDiffProvider: DiffProvider;

package/dist/review-inputs/git-diff-provider.js

@@ -0,0 +1,42 @@
+import simpleGit from 'simple-git';
+import { validateAndNormalizePath } from './path-validation.js';
+const parseFileList = (filesRaw) => {
+    return filesRaw
+        .split('\n')
+        .map((file) => file.trim())
+        .filter(Boolean);
+};
+export const gitDiffProvider = async ({ repoPath, from, to }) => {
+    try {
+        const git = simpleGit(repoPath);
+        const topLevel = (await git.revparse(['--show-toplevel'])).trim();
+        const topGit = simpleGit(topLevel);
+        // Use array arguments to prevent command injection
+        // simple-git handles array args safely by treating each element as a separate argument
+        const filesRaw = await topGit.raw(['diff', '--name-only', `${from}..${to}`]);
+        const filesRawList = parseFileList(filesRaw);
+        const files = [];
+        const diffs = {};
+        // Validate and normalize all file paths to prevent path traversal
+        for (const file of filesRawList) {
+            try {
+                const validatedPath = validateAndNormalizePath(file, topLevel);
+                files.push(validatedPath);
+                // Use array arguments for git diff command to prevent injection
+                const diff = await topGit.raw(['diff', '--no-color', `${from}..${to}`, '--', validatedPath]);
+                diffs[validatedPath] = diff;
+            }
+            catch (pathError) {
+                // Skip files that fail path validation (path traversal attempts)
+                // Log error but continue processing other files
+                const message = pathError instanceof Error ? pathError.message : 'Path validation failed';
+                throw new Error(`Invalid file path "${file}": ${message}`);
+            }
+        }
+        return { files, diffs };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Failed to compute git diff: ${message}`);
+    }
+};

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

@@ -0,0 +1,46 @@
+import { type FilteringConfig } from './filtering.js';
+import type { SurroundingContextConfig } from './surrounding-context.js';
+export { triagePr, type TriageConfig, type TriageResult } from './triage.js';
+export type ReviewInputMode = 'diff' | 'file-list';
+export type DiffReviewInputs = {
+    mode: 'diff';
+    files: string[];
+    diffs: Record<string, string>;
+    context?: Record<string, string>;
+};
+export type FileListReviewInputs = {
+    mode: 'file-list';
+    files: string[];
+    context?: Record<string, string>;
+};
+export type ReviewInputs = DiffReviewInputs | FileListReviewInputs;
+export type DiffInput = {
+    mode: 'diff';
+    repoPath: string;
+    from: string;
+    to: string;
+    filtering?: FilteringConfig;
+    surroundingContext?: SurroundingContextConfig;
+};
+export type FileListInput = {
+    mode: 'file-list';
+    files: string[];
+    basePath?: string;
+    filtering?: FilteringConfig;
+    surroundingContext?: SurroundingContextConfig;
+};
+export type ReviewInputOptions = DiffInput | FileListInput;
+export declare const isDiffInputs: (inputs: ReviewInputs) => inputs is DiffReviewInputs;
+export declare const isFileListInputs: (inputs: ReviewInputs) => inputs is FileListReviewInputs;
+export type DiffProvider = (params: {
+    repoPath: string;
+    from: string;
+    to: string;
+}) => Promise<{
+    files: string[];
+    diffs: Record<string, string>;
+}>;
+export declare const buildReviewInputs: (options: ReviewInputOptions, deps?: {
+    diffProvider?: DiffProvider;
+}) => Promise<ReviewInputs>;
+export declare const persistReviewInputs: (inputs: ReviewInputs, outputDir: string) => Promise<void>;

package/dist/review-inputs/index.js

@@ -0,0 +1,122 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gitDiffProvider } from './git-diff-provider.js';
+import { filterDiffInputs, filterFiles } from './filtering.js';
+export { triagePr } from './triage.js';
+export const isDiffInputs = (inputs) => inputs.mode === 'diff';
+export const isFileListInputs = (inputs) => inputs.mode === 'file-list';
+const resolveFilePath = (file, basePath) => {
+    if (!basePath) {
+        return file;
+    }
+    if (path.isAbsolute(file)) {
+        return file;
+    }
+    return path.resolve(basePath, file);
+};
+const toRelativeIfInsideBase = (filePath, basePath) => {
+    if (!basePath) {
+        return filePath;
+    }
+    const relative = path.relative(basePath, filePath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return filePath;
+    }
+    return relative;
+};
+const validateFileList = async (files, basePath) => {
+    if (files.length === 0) {
+        throw new Error('File list must include at least one file.');
+    }
+    const missing = [];
+    for (const file of files) {
+        try {
+            const resolved = resolveFilePath(file, basePath);
+            await access(resolved);
+        }
+        catch {
+            missing.push(file);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`Files not found: ${missing.join(', ')}`);
+    }
+};
+const normalizeFiles = (files) => {
+    return files.map((file) => file.trim()).filter(Boolean);
+};
+export const buildReviewInputs = async (options, deps) => {
+    if (options.mode === 'diff') {
+        const diffProvider = deps?.diffProvider ?? gitDiffProvider;
+        const result = await diffProvider({
+            repoPath: options.repoPath,
+            from: options.from,
+            to: options.to,
+        });
+        const normalizedFiles = normalizeFiles(result.files);
+        const { files, diffs } = filterDiffInputs(normalizedFiles, result.diffs, options.filtering);
+        if (files.length === 0) {
+            throw new Error('Diff mode produced no files to review after filtering.');
+        }
+        const inputs = {
+            mode: 'diff',
+            files,
+            diffs,
+        };
+        // Extract surrounding context if configured
+        if (options.surroundingContext?.enabled !== false) {
+            const { extractSurroundingContext } = await import('./surrounding-context.js');
+            const context = await extractSurroundingContext(inputs, {
+                ...options.surroundingContext,
+                basePath: options.surroundingContext?.basePath ?? options.repoPath,
+            });
+            if (Object.keys(context).length > 0) {
+                inputs.context = context;
+            }
+        }
+        return inputs;
+    }
+    const normalizedFiles = normalizeFiles(options.files);
+    const files = filterFiles(normalizedFiles, options.filtering);
+    if (files.length === 0) {
+        throw new Error('File list produced no files to review after filtering.');
+    }
+    await validateFileList(files, options.basePath);
+    const relativeFiles = files.map((file) => toRelativeIfInsideBase(resolveFilePath(file, options.basePath), options.basePath));
+    const inputs = {
+        mode: 'file-list',
+        files: relativeFiles,
+    };
+    // Extract surrounding context if configured
+    // For file-list mode, basePath is required for context extraction
+    if (options.surroundingContext?.enabled !== false) {
+        // Skip context extraction if basePath is missing in file-list mode
+        if (options.mode === 'file-list' && !options.basePath) {
+            // Context extraction requires basePath for file-list mode, skip it
+        }
+        else {
+            const { extractSurroundingContext } = await import('./surrounding-context.js');
+            const context = await extractSurroundingContext(inputs, {
+                ...options.surroundingContext,
+                basePath: options.basePath,
+            });
+            if (Object.keys(context).length > 0) {
+                inputs.context = context;
+            }
+        }
+    }
+    return inputs;
+};
+export const persistReviewInputs = async (inputs, outputDir) => {
+    await mkdir(outputDir, { recursive: true });
+    const filesPayload = JSON.stringify({ mode: inputs.mode, files: inputs.files }, null, 2);
+    await writeFile(path.join(outputDir, 'files.json'), filesPayload);
+    if (inputs.mode !== 'diff') {
+        return;
+    }
+    for (const [filePath, diff] of Object.entries(inputs.diffs)) {
+        const diffPath = path.join(outputDir, 'diff', `${filePath}.diff`);
+        await mkdir(path.dirname(diffPath), { recursive: true });
+        await writeFile(diffPath, diff);
+    }
+};

package/dist/review-inputs/path-validation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validates that a file path is safe and within the repository boundary.
+ * Prevents path traversal attacks by ensuring resolved paths stay within basePath.
+ *
+ * @param filePath - Relative file path from git or file list
+ * @param basePath - Base directory (repository root) to validate against
+ * @returns Normalized, validated relative path
+ * @throws Error if path traversal is detected or path is outside basePath
+ */
+export declare const validateAndNormalizePath: (filePath: string, basePath: string) => string;

package/dist/review-inputs/path-validation.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+/**
+ * Validates that a file path is safe and within the repository boundary.
+ * Prevents path traversal attacks by ensuring resolved paths stay within basePath.
+ *
+ * @param filePath - Relative file path from git or file list
+ * @param basePath - Base directory (repository root) to validate against
+ * @returns Normalized, validated relative path
+ * @throws Error if path traversal is detected or path is outside basePath
+ */
+export const validateAndNormalizePath = (filePath, basePath) => {
+    // Normalize the file path (remove . and .. segments)
+    const normalized = path.normalize(filePath);
+    // Resolve against basePath to get absolute path
+    const resolved = path.resolve(basePath, normalized);
+    // Resolve basePath to absolute (handles symlinks)
+    const baseResolved = path.resolve(basePath);
+    // Check if resolved path is within basePath
+    // Use realpathSync to resolve symlinks and ensure we're checking actual filesystem paths
+    try {
+        const resolvedReal = realpathSync(resolved);
+        const baseReal = realpathSync(baseResolved);
+        // Ensure the resolved path starts with the base path
+        if (!resolvedReal.startsWith(baseReal + path.sep) && resolvedReal !== baseReal) {
+            throw new Error(`Path traversal detected: "${filePath}" resolves outside repository boundary`);
+        }
+    }
+    catch {
+        // If realpathSync fails, the file doesn't exist - but we still check the resolved path
+        if (!resolved.startsWith(baseResolved + path.sep) && resolved !== baseResolved) {
+            throw new Error(`Path traversal detected: "${filePath}" resolves outside repository boundary`);
+        }
+    }
+    // Return normalized relative path
+    return normalized;
+};

package/dist/review-inputs/surrounding-context.d.ts

@@ -0,0 +1,35 @@
+import type { ReviewInputs } from './index.js';
+/**
+ * Configuration for surrounding context extraction.
+ */
+export type SurroundingContextConfig = {
+    /**
+     * Maximum tokens to use for surrounding context per file.
+     * Default: 20000 (roughly 80KB of text)
+     */
+    maxTokensPerFile?: number;
+    /**
+     * Number of lines of context to include before and after changed lines.
+     * Only used in diff mode when extracting windowed context.
+     * Default: 10
+     */
+    contextLines?: number;
+    /**
+     * Whether to extract surrounding context.
+     * Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Base path for resolving file paths (required for file-list mode).
+     */
+    basePath?: string;
+};
+/**
+ * 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 declare const extractSurroundingContext: (inputs: ReviewInputs, config?: SurroundingContextConfig) => Promise<Record<string, string>>;