feat(mcp): refactor dev_inspect and optimize pattern analysis

BREAKING CHANGE: dev_inspect no longer requires 'action' parameter

Major Changes:
- Refactored dev_inspect to single-purpose tool
  (finds similar files + pattern analysis)
- Created PatternAnalysisService with 5 pattern extractors
  (imports, error handling, types, testing, size)
- Optimized pattern analysis with batch scanning (5-10x faster)
- Fixed semantic search to use document embeddings
  instead of path strings
- Fixed --force flag to properly clear vector store
- Removed outputSchema from all 9 MCP adapters
  to fix Cursor/Claude compatibility
- Added extension filtering for relevant file comparisons

Performance Improvements:
- Batch scan all files in one pass
  (1 ts-morph initialization vs 6)
- Added searchByDocumentId for embedding-based similarity
- Pattern analysis now 500-1000ms (down from 2-3 seconds)

Bug Fixes:
- Fixed findSimilar to search by embeddings, not file paths
- Fixed force re-index to actually clear old data
- Fixed race condition in LanceDB table creation
- Fixed all MCP protocol compliance issues

New Features:
- Test utilities in core/utils
  (reusable isTestFile, findTestFile)
- Vector store clear() method
- searchByDocumentId() for similarity search
- Comprehensive pattern analysis (5 categories)

Documentation:
- Updated README.md with pattern categories
- Updated CLAUDE.md with new dev_inspect description
- Complete rewrite of dev-inspect.mdx website docs
- Added migration guide from dev_explore

Tests:
- All 1100+ tests passing
- Added 10 new test-utils tests
- Pattern analysis service fully tested

Author: prosdev

CLAUDE.md

@@ -168,7 +168,7 @@ Once installed, AI tools gain access to:
 - **`dev_map`** - Codebase structure with component counts and change frequency
 - **`dev_history`** - Semantic search over git commits (who changed what and why)
 - **`dev_plan`** - Assemble context for GitHub issues (code + history + patterns)
-- **`dev_inspect`** - Inspect files (compare similar implementations, check patterns)
+- **`dev_inspect`** - Inspect files for pattern analysis (finds similar code, compares error handling, types, imports, testing)
 - **`dev_gh`** - Search GitHub issues/PRs semantically
 - **`dev_status`** - Repository indexing status
 - **`dev_health`** - Server health checks

README.md

@@ -158,13 +158,20 @@ Assemble context for issue #42
 **Note:** This tool no longer generates task breakdowns. It provides comprehensive context so the AI assistant can create better plans.
 
 ### `dev_inspect` - File Analysis
-Inspect specific files, compare implementations, validate patterns.
+Inspect files for pattern analysis. Finds similar code and compares patterns (error handling, type coverage, imports, testing).
 
 ```
-Compare src/auth/middleware.ts with similar implementations
-Validate pattern consistency in src/hooks/useAuth.ts
+Inspect src/auth/middleware.ts for patterns
+Check how src/hooks/useAuth.ts compares to similar hooks
 ```
 
+**Pattern Categories:**
+- Import style (ESM vs CJS)
+- Error handling (throw vs result types)
+- Type coverage (full, partial, none)
+- Test coverage (co-located test files)
+- File size relative to similar code
+
 ### `dev_status` - Repository Status
 View indexing status, component health, and repository information.
 

packages/core/src/indexer/index.ts

@@ -92,6 +92,13 @@ export class RepositoryIndexer {
     const _documentsIndexed = 0;
 
     try {
+      // Clear vector store if force re-index requested
+      if (options.force) {
+        options.logger?.info('Force re-index requested, clearing existing vectors');
+        await this.vectorStorage.clear();
+        this.state = null; // Reset state to force fresh scan
+      }
+
       // Phase 1: Scan repository
       const onProgress = options.onProgress;
       onProgress?.({
@@ -526,6 +533,14 @@ export class RepositoryIndexer {
     return this.vectorStorage.search(query, options);
   }
 
+  /**
+   * Find similar documents to a given document by ID
+   * More efficient than search() as it reuses the document's existing embedding
+   */
+  async searchByDocumentId(documentId: string, options?: SearchOptions): Promise<SearchResult[]> {
+    return this.vectorStorage.searchByDocumentId(documentId, options);
+  }
+
   /**
    * Get all indexed documents without semantic search (fast scan)
    * Use this when you need all documents and don't need relevance ranking

packages/core/src/services/pattern-analysis-service.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { scanRepository } from '../scanner';
 import type { Document } from '../scanner/types';
+import { findTestFile, isTestFile } from '../utils/test-utils';
 import type {
   ErrorHandlingComparison,
   ErrorHandlingPattern,
@@ -65,35 +66,50 @@ export class PatternAnalysisService {
 
     const documents = result.documents.filter((d) => d.metadata.file === filePath);
 
-    // Step 2: Get file stats and content
-    const fullPath = path.join(this.config.repositoryPath, filePath);
-    const [stat, content] = await Promise.all([fs.stat(fullPath), fs.readFile(fullPath, 'utf-8')]);
-
-    const lines = content.split('\n').length;
-
-    // Step 3: Extract all patterns
-    return {
-      fileSize: {
-        lines,
-        bytes: stat.size,
-      },
-      testing: await this.analyzeTesting(filePath),
-      importStyle: await this.analyzeImportsFromFile(filePath, documents),
-      errorHandling: this.analyzeErrorHandling(content),
-      typeAnnotations: this.analyzeTypes(documents),
-    };
+    // Step 2: Use the optimized analysis method
+    return this.analyzeFileWithDocs(filePath, documents);
   }
 
   /**
    * Compare patterns between target file and similar files
    *
+   * OPTIMIZED: Batch scans all files in one pass to avoid repeated ts-morph initialization
+   *
    * @param targetFile - Target file to analyze
    * @param similarFiles - Array of similar file paths
    * @returns Pattern comparison results
    */
   async comparePatterns(targetFile: string, similarFiles: string[]): Promise<PatternComparison> {
-    const targetPatterns = await this.analyzeFile(targetFile);
-    const similarPatterns = await Promise.all(similarFiles.map((f) => this.analyzeFile(f)));
+    // OPTIMIZATION: Batch scan all files at once (5-10x faster than individual scans)
+    const allFiles = [targetFile, ...similarFiles];
+    const batchResult = await scanRepository({
+      repoRoot: this.config.repositoryPath,
+      include: allFiles,
+    });
+
+    // Group documents by file for fast lookup
+    const docsByFile = new Map<string, Document[]>();
+    for (const doc of batchResult.documents) {
+      const file = doc.metadata.file;
+      if (!docsByFile.has(file)) {
+        docsByFile.set(file, []);
+      }
+      const docs = docsByFile.get(file);
+      if (docs) {
+        docs.push(doc);
+      }
+    }
+
+    // Analyze target file with cached documents
+    const targetPatterns = await this.analyzeFileWithDocs(
+      targetFile,
+      docsByFile.get(targetFile) || []
+    );
+
+    // Analyze similar files in parallel with cached documents
+    const similarPatterns = await Promise.all(
+      similarFiles.map((f) => this.analyzeFileWithDocs(f, docsByFile.get(f) || []))
+    );
 
     return {
       fileSize: this.compareFileSize(
@@ -119,6 +135,36 @@ export class PatternAnalysisService {
     };
   }
 
+  /**
+   * Analyze file patterns using pre-scanned documents (faster)
+   *
+   * @param filePath - Relative path from repository root
+   * @param documents - Pre-scanned documents for this file
+   * @returns Pattern analysis results
+   */
+  private async analyzeFileWithDocs(
+    filePath: string,
+    documents: Document[]
+  ): Promise<FilePatterns> {
+    // Step 1: Get file stats and content
+    const fullPath = path.join(this.config.repositoryPath, filePath);
+    const [stat, content] = await Promise.all([fs.stat(fullPath), fs.readFile(fullPath, 'utf-8')]);
+
+    const lines = content.split('\n').length;
+
+    // Step 2: Extract all patterns (using cached documents)
+    return {
+      fileSize: {
+        lines,
+        bytes: stat.size,
+      },
+      testing: await this.analyzeTesting(filePath),
+      importStyle: await this.analyzeImportsFromFile(filePath, documents),
+      errorHandling: this.analyzeErrorHandling(content),
+      typeAnnotations: this.analyzeTypes(documents),
+    };
+  }
+
   // ========================================================================
   // Pattern Extractors (MVP: 5 core patterns)
   // ========================================================================
@@ -130,11 +176,11 @@ export class PatternAnalysisService {
    */
   private async analyzeTesting(filePath: string): Promise<TestingPattern> {
     // Skip if already a test file
-    if (this.isTestFile(filePath)) {
+    if (isTestFile(filePath)) {
       return { hasTest: false };
     }
 
-    const testFile = await this.findTestFile(filePath);
+    const testFile = await findTestFile(filePath, this.config.repositoryPath);
     return {
       hasTest: testFile !== null,
       testPath: testFile || undefined,
@@ -440,35 +486,4 @@ export class PatternAnalysisService {
   // ========================================================================
   // Utility Methods
   // ========================================================================
-
-  /**
-   * Check if a path is a test file
-   */
-  private isTestFile(filePath: string): boolean {
-    return filePath.includes('.test.') || filePath.includes('.spec.');
-  }
-
-  /**
-   * Find test file for a source file
-   *
-   * Checks for common patterns: *.test.*, *.spec.*
-   */
-  private async findTestFile(sourcePath: string): Promise<string | null> {
-    const ext = path.extname(sourcePath);
-    const base = sourcePath.slice(0, -ext.length);
-
-    const patterns = [`${base}.test${ext}`, `${base}.spec${ext}`];
-
-    for (const testPath of patterns) {
-      const fullPath = path.join(this.config.repositoryPath, testPath);
-      try {
-        await fs.access(fullPath);
-        return testPath;
-      } catch {
-        // File doesn't exist, try next pattern
-      }
-    }
-
-    return null;
-  }
 }

packages/core/src/services/search-service.ts

@@ -124,19 +124,24 @@ export class SearchService {
   async findSimilar(filePath: string, options?: SimilarityOptions): Promise<SearchResult[]> {
     const indexer = await this.getIndexer();
     try {
-      // Search for documents from the target file
-      const fileResults = await indexer.search(filePath, { limit: 5 });
-      if (fileResults.length === 0) {
+      // Step 1: Get all documents from the target file
+      const allDocs = await indexer.getAll({ limit: 10000 });
+      const fileDocuments = allDocs.filter((doc) => doc.metadata.path === filePath);
+
+      if (fileDocuments.length === 0) {
+        this.logger?.warn({ filePath }, 'No indexed documents found for file');
         return [];
       }
 
-      // Use the path as query to find similar code patterns
-      const results = await indexer.search(filePath, {
-        limit: (options?.limit ?? 10) + 1, // +1 to account for the file itself
+      // Step 2: Use the first document's embedding to find similar documents
+      // This is more accurate than searching by file path string
+      const referenceDocId = fileDocuments[0].id;
+      const results = await indexer.searchByDocumentId(referenceDocId, {
+        limit: (options?.limit ?? 10) + fileDocuments.length, // +N to account for the file's own documents
         scoreThreshold: options?.threshold ?? 0.7,
       });
 
-      // Filter out the original file
+      // Step 3: Filter out documents from the same file
       return results.filter((r) => r.metadata.path !== filePath);
     } finally {
       await indexer.close();

packages/core/src/utils/__tests__/test-utils.test.ts

@@ -0,0 +1,114 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { findTestFile, isTestFile } from '../test-utils';
+
+describe('test-utils', () => {
+  describe('isTestFile', () => {
+    it('should identify .test. files', () => {
+      expect(isTestFile('src/utils/helper.test.ts')).toBe(true);
+      expect(isTestFile('src/components/Button.test.tsx')).toBe(true);
+      expect(isTestFile('lib/parser.test.js')).toBe(true);
+    });
+
+    it('should identify .spec. files', () => {
+      expect(isTestFile('src/utils/helper.spec.ts')).toBe(true);
+      expect(isTestFile('src/components/Button.spec.tsx')).toBe(true);
+      expect(isTestFile('lib/parser.spec.js')).toBe(true);
+    });
+
+    it('should return false for non-test files', () => {
+      expect(isTestFile('src/utils/helper.ts')).toBe(false);
+      expect(isTestFile('src/components/Button.tsx')).toBe(false);
+      expect(isTestFile('lib/parser.js')).toBe(false);
+      expect(isTestFile('README.md')).toBe(false);
+    });
+
+    it('should handle edge cases', () => {
+      expect(isTestFile('')).toBe(false);
+      expect(isTestFile('test.ts')).toBe(false); // Needs .test. or .spec.
+      expect(isTestFile('spec.ts')).toBe(false);
+    });
+  });
+
+  describe('findTestFile', () => {
+    const testDir = path.join(__dirname, '__temp_test_utils__');
+
+    beforeEach(async () => {
+      await fs.mkdir(testDir, { recursive: true });
+    });
+
+    afterEach(async () => {
+      await fs.rm(testDir, { recursive: true, force: true });
+    });
+
+    it('should find .test. file', async () => {
+      // Create source and test file
+      const sourceFile = 'helper.ts';
+      const testFile = 'helper.test.ts';
+      await fs.writeFile(path.join(testDir, sourceFile), '// source');
+      await fs.writeFile(path.join(testDir, testFile), '// test');
+
+      const result = await findTestFile(sourceFile, testDir);
+      expect(result).toBe(testFile);
+    });
+
+    it('should find .spec. file', async () => {
+      // Create source and spec file
+      const sourceFile = 'parser.ts';
+      const specFile = 'parser.spec.ts';
+      await fs.writeFile(path.join(testDir, sourceFile), '// source');
+      await fs.writeFile(path.join(testDir, specFile), '// spec');
+
+      const result = await findTestFile(sourceFile, testDir);
+      expect(result).toBe(specFile);
+    });
+
+    it('should prefer .test. over .spec.', async () => {
+      // Create source and both test files
+      const sourceFile = 'utils.ts';
+      const testFile = 'utils.test.ts';
+      const specFile = 'utils.spec.ts';
+      await fs.writeFile(path.join(testDir, sourceFile), '// source');
+      await fs.writeFile(path.join(testDir, testFile), '// test');
+      await fs.writeFile(path.join(testDir, specFile), '// spec');
+
+      const result = await findTestFile(sourceFile, testDir);
+      expect(result).toBe(testFile); // .test. is checked first
+    });
+
+    it('should return null if no test file exists', async () => {
+      // Create only source file
+      const sourceFile = 'lonely.ts';
+      await fs.writeFile(path.join(testDir, sourceFile), '// source');
+
+      const result = await findTestFile(sourceFile, testDir);
+      expect(result).toBeNull();
+    });
+
+    it('should handle different extensions', async () => {
+      // Test with .tsx
+      const sourceFile = 'Component.tsx';
+      const testFile = 'Component.test.tsx';
+      await fs.writeFile(path.join(testDir, sourceFile), '// component');
+      await fs.writeFile(path.join(testDir, testFile), '// test');
+
+      const result = await findTestFile(sourceFile, testDir);
+      expect(result).toBe(testFile);
+    });
+
+    it('should handle nested paths', async () => {
+      // Create nested directory structure
+      const nestedDir = path.join(testDir, 'src', 'utils');
+      await fs.mkdir(nestedDir, { recursive: true });
+
+      const sourceFile = 'src/utils/helper.ts';
+      const testFile = 'src/utils/helper.test.ts';
+      await fs.writeFile(path.join(testDir, sourceFile), '// source');
+      await fs.writeFile(path.join(testDir, testFile), '// test');
+
+      const result = await findTestFile(sourceFile, testDir);
+      expect(result).toBe(testFile);
+    });
+  });
+});

packages/core/src/utils/index.ts

@@ -6,4 +6,5 @@ export * from './concurrency';
 export * from './file-validator';
 export * from './icons';
 export * from './retry';
+export * from './test-utils';
 export * from './wasm-resolver';