codex-review-mcp 1.4.0 → 2.0.1

package/dist/review/gatherContext.test.js

@@ -0,0 +1,334 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { gatherContext } from './gatherContext.js';
+import { promises as fs } from 'node:fs';
+vi.mock('node:fs', () => ({
+    promises: {
+        readFile: vi.fn(),
+        readdir: vi.fn(),
+        realpath: vi.fn(),
+    },
+}));
+describe('gatherContext', () => {
+    const originalCwd = process.cwd();
+    const mockCwd = '/test/workspace';
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.chdir = vi.fn(() => mockCwd);
+        vi.spyOn(process, 'cwd').mockReturnValue(mockCwd);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('Project Guidelines Priority', () => {
+        it('should prioritize .cursor/rules files first', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            // Mock .cursor/rules directory scanning
+            mockRealpath.mockResolvedValue('/test/workspace/.cursor/rules');
+            mockReaddir.mockResolvedValue([
+                { name: 'project.mdc', isFile: () => true, isDirectory: () => false },
+                { name: 'tsx.mdc', isFile: () => true, isDirectory: () => false },
+            ]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('.cursor/rules/project.mdc'))
+                    return '# Project Rules\nStrict guidelines';
+                if (path.includes('.cursor/rules/tsx.mdc'))
+                    return '# TSX Rules\nComponent patterns';
+                if (path.includes('CODE_REVIEW.md'))
+                    return '# Code Review Guidelines';
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            // Verify .cursor/rules files are included
+            expect(context).toContain('Project Rules');
+            expect(context).toContain('TSX Rules');
+            // Verify files are marked with their paths
+            expect(context).toMatch(/<!--.*\.cursor\/rules.*-->/);
+        });
+        it('should include CODE_REVIEW.md when present', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('CODE_REVIEW.md')) {
+                    return '# Code Review Standards\n\n## Conventions\n- Use TypeScript strict mode\n- Follow ESLint rules';
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('Code Review Standards');
+            expect(context).toContain('<!-- CODE_REVIEW.md -->');
+        });
+        it('should include CONTRIBUTING.md guidelines', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('CONTRIBUTING.md')) {
+                    return '# Contributing\n\n## Code Style\n- 2 spaces for indentation';
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('Contributing');
+            expect(context).toContain('<!-- CONTRIBUTING.md -->');
+        });
+    });
+    describe('Configuration Files', () => {
+        it('should include ESLint configuration', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('.eslintrc.json')) {
+                    return JSON.stringify({
+                        extends: ['eslint:recommended'],
+                        rules: { 'no-console': 'error' }
+                    });
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('eslintrc');
+            expect(context).toContain('no-console');
+        });
+        it('should include TypeScript configuration', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('tsconfig.json')) {
+                    return JSON.stringify({
+                        compilerOptions: { strict: true, noImplicitAny: true }
+                    });
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('tsconfig');
+            expect(context).toContain('strict');
+        });
+        it('should include package.json for dependency info', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('package.json')) {
+                    return JSON.stringify({
+                        name: 'test-project',
+                        dependencies: { react: '^18.0.0', typescript: '^5.0.0' }
+                    });
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('package.json');
+            expect(context).toContain('react');
+        });
+    });
+    describe('Size and Safety Limits', () => {
+        it('should cap individual files at 8000 characters', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            const largeContent = 'x'.repeat(10000);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('CODE_REVIEW.md'))
+                    return largeContent;
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            // Should be capped at 8000 + overhead for comments
+            const contentLength = context.length;
+            expect(contentLength).toBeLessThan(10000);
+            expect(context).toContain('CODE_REVIEW.md');
+        });
+        it('should cap total context at ~50000 characters', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            // Create many files with max content
+            const largeContent = 'x'.repeat(8000);
+            mockReadFile.mockResolvedValue(largeContent);
+            const context = await gatherContext();
+            // Should stop before processing all files
+            expect(context.length).toBeLessThanOrEqual(60000); // Allow some overhead
+        });
+        it('should skip node_modules and other ignored directories', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockResolvedValue('/test/workspace/.cursor/rules');
+            mockReaddir.mockResolvedValue([
+                { name: 'node_modules', isDirectory: () => true, isFile: () => false },
+                { name: '.git', isDirectory: () => true, isFile: () => false },
+                { name: 'project.mdc', isFile: () => true, isDirectory: () => false },
+            ]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('project.mdc'))
+                    return '# Project Rules';
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            // Should include project.mdc but not traverse node_modules or .git
+            expect(context).toContain('Project Rules');
+            expect(mockReaddir).toHaveBeenCalledTimes(1); // Only the .cursor/rules directory
+        });
+        it('should handle circular symlinks gracefully', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            // Simulate circular symlink by returning same realpath
+            mockRealpath.mockResolvedValue('/test/workspace/.cursor/rules');
+            mockReaddir.mockResolvedValue([
+                { name: 'link', isDirectory: () => true, isFile: () => false },
+            ]);
+            const context = await gatherContext();
+            // Should not hang or error, should handle gracefully
+            expect(context).toBeDefined();
+        });
+    });
+    describe('Error Handling', () => {
+        it('should continue when individual files are missing', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('CODE_REVIEW.md'))
+                    return '# Code Review';
+                if (path.includes('CONTRIBUTING.md'))
+                    return '# Contributing';
+                // All other files throw ENOENT
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            // Should still include the files that exist
+            expect(context).toContain('Code Review');
+            expect(context).toContain('Contributing');
+        });
+        it('should return empty string when no files exist', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockRejectedValue(new Error('ENOENT'));
+            const context = await gatherContext();
+            expect(context).toBe('');
+        });
+        it('should handle permission errors gracefully', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('CODE_REVIEW.md'))
+                    return '# Code Review';
+                if (path.includes('.eslintrc.json')) {
+                    const error = new Error('EACCES: permission denied');
+                    error.code = 'EACCES';
+                    throw error;
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            // Should still include accessible files
+            expect(context).toContain('Code Review');
+            // Should not throw an error
+            expect(context).toBeDefined();
+        });
+    });
+    describe('File Format Support', () => {
+        it('should scan .cursor/rules directory for .md and .mdc files', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockResolvedValue('/test/workspace/.cursor/rules');
+            mockReaddir.mockResolvedValue([
+                { name: 'project.mdc', isFile: () => true, isDirectory: () => false },
+                { name: 'readme.md', isFile: () => true, isDirectory: () => false },
+                { name: 'config.json', isFile: () => true, isDirectory: () => false },
+            ]);
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('project.mdc'))
+                    return '# Project';
+                if (path.includes('readme.md'))
+                    return '# Readme';
+                if (path.includes('config.json'))
+                    return '{}';
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('Project');
+            expect(context).toContain('Readme');
+            // Verify .json files from directory scan are not included (checking for the file marker)
+            expect(context).not.toMatch(/<!--.*\.cursor\/rules\/config\.json.*-->/);
+            // But ts config from the root candidate list should still be included
+            expect(context).toContain('tsconfig.json');
+        });
+        it('should support multiple ESLint config formats', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockRejectedValue(new Error('ENOENT'));
+            mockReaddir.mockResolvedValue([]);
+            let callCount = 0;
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('.eslintrc.json')) {
+                    callCount++;
+                    return JSON.stringify({ rules: { 'no-console': 'error' } });
+                }
+                if (path.includes('.eslintrc.js') && callCount === 0) {
+                    // Should only read first found ESLint config
+                    throw new Error('Should not reach here');
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            expect(context).toContain('eslintrc');
+            expect(callCount).toBe(1); // Should stop after finding first config
+        });
+    });
+    describe('Deduplication', () => {
+        it('should not process the same file twice', async () => {
+            const mockReadFile = vi.mocked(fs.readFile);
+            const mockReaddir = vi.mocked(fs.readdir);
+            const mockRealpath = vi.mocked(fs.realpath);
+            mockRealpath.mockResolvedValue('/test/workspace/.cursor/rules');
+            mockReaddir.mockResolvedValue([
+                { name: 'tsx.mdc', isFile: () => true, isDirectory: () => false },
+            ]);
+            let readCount = 0;
+            mockReadFile.mockImplementation(async (path) => {
+                if (path.includes('tsx.mdc') || path.includes('.cursor/rules/tsx.mdc')) {
+                    readCount++;
+                    return '# TSX Rules';
+                }
+                return Promise.reject(new Error('ENOENT'));
+            });
+            const context = await gatherContext();
+            // tsx.mdc appears in CANDIDATE_FILES twice (explicit and in directory scan)
+            // Should only be read once
+            expect(readCount).toBe(1);
+            expect(context).toContain('TSX Rules');
+        });
+    });
+});

package/dist/review/invokeAgent.js

@@ -1,14 +1,52 @@
-import { Agent, run } from '@openai/agents';
+import { Agent, run, tool } from '@openai/agents';
 import { debugLog } from '../util/debug.js';
-export async function invokeAgent({ prompt, maxTokens }) {
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export async function invokeAgent({ prompt, maxTokens, workspaceDir }) {
     const model = process.env.CODEX_MODEL || 'gpt-5-codex';
+    const cwd = workspaceDir || process.cwd();
+    // Tool: Read file from the codebase
+    const readFileTool = tool({
+        name: 'read_file',
+        description: 'Read the contents of a file from the codebase to examine existing patterns, utilities, or configuration. Use this to check for existing code before suggesting changes.',
+        parameters: z.object({
+            path: z.string().describe('Relative path to the file from the repository root'),
+        }),
+        execute: async (params) => {
+            try {
+                // Basic path sandboxing to keep reads under cwd
+                const requested = params.path.replace(/\\/g, '/');
+                if (requested.includes('..')) {
+                    return 'Access denied: parent directory traversal is not allowed.';
+                }
+                const fullPath = join(cwd, requested);
+                if (!fullPath.startsWith(cwd)) {
+                    return 'Access denied: path escapes workspace boundary.';
+                }
+                const content = await fs.readFile(fullPath, 'utf8');
+                const MAX_RETURN = 50_000; // cap very large files
+                const body = content.length > MAX_RETURN ? content.slice(0, MAX_RETURN) + '\n... [truncated]' : content;
+                await debugLog(`Agent read file: ${params.path} (${content.length} chars)`);
+                return `File: ${params.path}\n\n${body}`;
+            }
+            catch (error) {
+                const errorMsg = `Unable to read ${params.path}: ${error.message}`;
+                await debugLog(`Agent file read error: ${errorMsg}`);
+                return errorMsg;
+            }
+        },
+    });
     const agent = new Agent({
         name: 'Code Reviewer',
-        instructions: 'You are a precise code-review agent. Follow the output contract exactly. Use minimal verbosity.',
+        instructions: 'You are a precise code-review agent. Follow the output contract exactly. Use minimal verbosity. When you need to examine existing code patterns, utilities, or configurations to provide accurate recommendations, use the read_file tool.',
         model,
+        tools: [readFileTool],
     });
     try {
-        const result = await run(agent, prompt);
+        const result = await run(agent, prompt, {
+            maxTurns: 25, // Allow more turns for file reading (default is 10)
+        });
         const out = result.finalOutput ?? '';
         await debugLog(`Agent model=${model} outputLen=${out.length}`);
         return out;

package/dist/review/invokeAgent.test.js

@@ -5,6 +5,7 @@ import { run } from '@openai/agents';
 vi.mock('@openai/agents', () => ({
     Agent: vi.fn().mockImplementation((config) => config),
     run: vi.fn(),
+    tool: vi.fn().mockImplementation((config) => config),
 }));
 vi.mock('../util/debug', () => ({
     debugLog: vi.fn(),
@@ -74,4 +75,34 @@ describe('invokeAgent', () => {
             process.env.CODEX_MODEL = originalEnv;
         }
     });
+    it('should create agent with read_file tool for examining codebase', async () => {
+        vi.mocked(run).mockResolvedValue({
+            finalOutput: '# Review',
+        });
+        await invokeAgent({
+            prompt: 'Review this code',
+            workspaceDir: '/test/workspace'
+        });
+        const { Agent, tool } = await import('@openai/agents');
+        // Verify tool was created
+        expect(tool).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'read_file',
+            description: expect.stringContaining('examine existing patterns'),
+        }));
+        // Verify agent was created with tools
+        expect(Agent).toHaveBeenCalledWith(expect.objectContaining({
+            tools: expect.arrayContaining([expect.anything()]),
+        }));
+    });
+    it('should pass workspaceDir to control file reading scope', async () => {
+        vi.mocked(run).mockResolvedValue({
+            finalOutput: '# Review',
+        });
+        const result = await invokeAgent({
+            prompt: 'Test',
+            workspaceDir: '/custom/workspace'
+        });
+        expect(result).toBe('# Review');
+        expect(run).toHaveBeenCalled();
+    });
 });

package/dist/tools/performCodeReview.js

@@ -1,26 +1,63 @@
-import { collectDiff } from '../review/collectDiff.js';
 import { gatherContext } from '../review/gatherContext.js';
 import { buildPrompt } from '../review/buildPrompt.js';
 import { invokeAgent } from '../review/invokeAgent.js';
 import { formatOutput } from '../review/formatOutput.js';
 import { debugLog } from '../util/debug.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// Read version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
+const VERSION = packageJson.version;
+/**
+ * Perform code review with GPT-5 Codex
+ *
+ * The calling agent provides the content (diff or code) to review.
+ * We handle: context gathering, expert prompt building, GPT-5 invocation, formatting.
+ */
 export async function performCodeReview(input, onProgress) {
-    await onProgress?.('Collecting diff…', 10, 100);
-    const diffText = await collectDiff(input, input.workspaceDir);
-    if (!diffText.trim()) {
-        throw new Error('No changes to review. You are on the default branch with a clean working tree.');
+    // Validate input
+    if (!input.content || !input.content.trim()) {
+        throw new Error('content is required and cannot be empty. ' +
+            'The calling agent should provide the diff or code to review.');
     }
-    await onProgress?.('Gathering context…', 30, 100);
-    const context = await gatherContext();
-    await onProgress?.('Building prompt…', 45, 100);
-    const prompt = buildPrompt({ diffText, context, focus: input.focus });
-    // Count lines in the diff for progress message
-    const lineCount = diffText.split('\n').length;
-    const addedLines = diffText.split('\n').filter(line => line.startsWith('+')).length;
-    const removedLines = diffText.split('\n').filter(line => line.startsWith('-')).length;
-    await onProgress?.(`Calling GPT-5 Codex with ~${lineCount} lines (+${addedLines} -${removedLines})…`, 65, 100);
-    const agentMd = await invokeAgent({ prompt, maxTokens: input.maxTokens });
+    await onProgress?.('Preparing review…', 10, 100);
+    // Gather context with smart precedence
+    const shouldSkip = input.skipContextGathering === true;
+    const usingCustom = Boolean(input.customContext?.trim());
+    await onProgress?.(usingCustom
+        ? 'Using provided project context…'
+        : shouldSkip
+            ? 'Skipping context gathering…'
+            : 'Gathering project context…', 30, 100);
+    const context = usingCustom
+        ? input.customContext
+        : shouldSkip
+            ? ''
+            : await gatherContext(input.workspaceDir);
+    // Build expert prompt
+    await onProgress?.('Building expert prompt…', 50, 100);
+    const isStaticReview = input.contentType === 'code';
+    const prompt = buildPrompt({
+        diffText: input.content,
+        context,
+        focus: input.focus,
+        version: VERSION,
+        isStaticReview
+    });
+    // Invoke GPT-5 Codex
+    const lineCount = input.content.split('\n').length;
+    const reviewType = isStaticReview ? 'code' : 'diff';
+    await onProgress?.(`Calling GPT-5 Codex with ${reviewType} (~${lineCount} lines)…`, 70, 100);
+    const agentMd = await invokeAgent({
+        prompt,
+        maxTokens: input.maxTokens,
+        workspaceDir: input.workspaceDir || process.cwd()
+    });
     await debugLog(`Review produced ${agentMd.length} chars`);
+    // Format output
     await onProgress?.('Formatting output…', 90, 100);
     const out = formatOutput(agentMd);
     await onProgress?.('Done', 100, 100);