feat: support per-project analyzer hints

Author: PatrickSys

docs/capabilities.md

@@ -15,6 +15,12 @@ HTTP defaults to `127.0.0.1:3100`. Override with `--port`, `CODEBASE_CONTEXT_POR
 
 Config-registered project roots (from `~/.codebase-context/config.json`) are loaded at startup in both modes.
 
+Per-project config overrides supported today:
+
+- `projects[].excludePatterns`: merged with the built-in exclusion set for that project at index time
+- `projects[].analyzerHints.analyzer`: prefers a registered analyzer by name for that project and falls back safely when the name is missing or invalid
+- `projects[].analyzerHints.extensions`: adds project-local source extensions for indexing and auto-refresh watching without changing defaults for other projects
+
 Copy-pasteable client config templates are shipped in the package:
 
 - `templates/mcp/stdio/.mcp.json` — stdio setup for `.mcp.json`-style clients

package.json

@@ -114,7 +114,7 @@
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "watch": "tsc -w",
-    "test": "vitest run",
+    "test": "node scripts/run-vitest.mjs",
     "test:watch": "vitest",
     "lint": "eslint \"src/**/*.ts\"",
     "format": "prettier --write \"src/**/*.ts\"",

scripts/run-vitest.mjs

@@ -0,0 +1,29 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const forwardedArgs = process.argv.slice(2);
+const vitestArgs =
+  forwardedArgs[0] === '--' ? forwardedArgs.slice(1) : forwardedArgs;
+
+const vitestEntrypoint = fileURLToPath(
+  new URL('../node_modules/vitest/vitest.mjs', import.meta.url)
+);
+
+const child = spawn(process.execPath, [vitestEntrypoint, 'run', ...vitestArgs], {
+  stdio: 'inherit',
+  env: process.env
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});
+
+child.on('error', (error) => {
+  console.error('[test] Failed to start vitest:', error);
+  process.exit(1);
+});

src/core/analyzer-registry.ts

@@ -3,8 +3,14 @@
  * Automatically selects the best analyzer based on file type and priority
  */
 
+import path from 'path';
 import { FrameworkAnalyzer, AnalysisResult } from '../types/index.js';
 
+export interface AnalyzerSelectionOptions {
+  preferredAnalyzer?: string;
+  extraFileExtensions?: string[];
+}
+
 export class AnalyzerRegistry {
   private analyzers: Map<string, FrameworkAnalyzer> = new Map();
   private sortedAnalyzers: FrameworkAnalyzer[] = [];
@@ -43,11 +49,42 @@ export class AnalyzerRegistry {
     return [...this.sortedAnalyzers];
   }
 
+  private isExtraExtension(filePath: string, extraFileExtensions?: string[]): boolean {
+    if (!extraFileExtensions?.length) {
+      return false;
+    }
+
+    const extension = path.extname(filePath).toLowerCase();
+    return extraFileExtensions.some((candidate) => {
+      const normalized = candidate.trim().toLowerCase();
+      if (!normalized) {
+        return false;
+      }
+      return extension === (normalized.startsWith('.') ? normalized : `.${normalized}`);
+    });
+  }
+
   /**
-   * Find the best analyzer for a given file
-   * Returns the analyzer with highest priority that can handle the file
+   * Find the best analyzer for a given file.
+   * Returns the preferred analyzer when configured and applicable, otherwise the
+   * highest-priority analyzer that can handle the file.
    */
-  findAnalyzer(filePath: string, content?: string): FrameworkAnalyzer | null {
+  findAnalyzer(
+    filePath: string,
+    content?: string,
+    options?: AnalyzerSelectionOptions
+  ): FrameworkAnalyzer | null {
+    if (options?.preferredAnalyzer) {
+      const preferred = this.analyzers.get(options.preferredAnalyzer);
+      if (
+        preferred &&
+        (preferred.canAnalyze(filePath, content) ||
+          this.isExtraExtension(filePath, options.extraFileExtensions))
+      ) {
+        return preferred;
+      }
+    }
+
     for (const analyzer of this.sortedAnalyzers) {
       if (analyzer.canAnalyze(filePath, content)) {
         return analyzer;
@@ -66,8 +103,12 @@ export class AnalyzerRegistry {
   /**
    * Analyze a file using the best available analyzer
    */
-  async analyzeFile(filePath: string, content: string): Promise<AnalysisResult | null> {
-    const analyzer = this.findAnalyzer(filePath, content);
+  async analyzeFile(
+    filePath: string,
+    content: string,
+    options?: AnalyzerSelectionOptions
+  ): Promise<AnalysisResult | null> {
+    const analyzer = this.findAnalyzer(filePath, content, options);
 
     if (!analyzer) {
       if (process.env.CODEBASE_CONTEXT_DEBUG) {
@@ -76,8 +117,6 @@ export class AnalyzerRegistry {
       return null;
     }
 
-    // console.error(`Analyzing ${filePath} with ${analyzer.name} analyzer`);
-
     try {
       return await analyzer.analyze(filePath, content);
     } catch (error) {

src/core/file-watcher.ts

@@ -7,35 +7,37 @@ export interface FileWatcherOptions {
   rootPath: string;
   /** ms after last change before triggering. Default: 2000 */
   debounceMs?: number;
+  /** Additional source extensions tracked for this project only. */
+  extraExtensions?: string[];
   /** Called once chokidar finishes initial scan and starts emitting change events */
   onReady?: () => void;
   /** Called once the debounce window expires after the last detected change */
   onChanged: () => void;
 }
 
-const TRACKED_EXTENSIONS = new Set(
-  getSupportedExtensions().map((extension) => extension.toLowerCase())
-);
-
 const TRACKED_METADATA_FILES = new Set(['.gitignore']);
 
-function isTrackedSourcePath(filePath: string): boolean {
+function isTrackedSourcePath(filePath: string, trackedExtensions: Set<string>): boolean {
   const basename = path.basename(filePath).toLowerCase();
   if (TRACKED_METADATA_FILES.has(basename)) return true;
+
   const extension = path.extname(filePath).toLowerCase();
-  return extension.length > 0 && TRACKED_EXTENSIONS.has(extension);
+  return extension.length > 0 && trackedExtensions.has(extension);
 }
 
 /**
  * Watch rootPath for source file changes and call onChanged (debounced).
  * Returns a stop() function that cancels the debounce timer and closes the watcher.
  */
 export function startFileWatcher(opts: FileWatcherOptions): () => void {
-  const { rootPath, debounceMs = 2000, onReady, onChanged } = opts;
+  const { rootPath, debounceMs = 2000, extraExtensions, onReady, onChanged } = opts;
+  const trackedExtensions = new Set(
+    getSupportedExtensions(extraExtensions).map((extension) => extension.toLowerCase())
+  );
   let debounceTimer: ReturnType<typeof setTimeout> | undefined;
 
   const trigger = (filePath: string) => {
-    if (!isTrackedSourcePath(filePath)) return;
+    if (!isTrackedSourcePath(filePath, trackedExtensions)) return;
     if (debounceTimer !== undefined) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
       debounceTimer = undefined;

src/core/indexer.ts

@@ -20,6 +20,7 @@ import {
   IntelligenceData
 } from '../types/index.js';
 import { analyzerRegistry } from './analyzer-registry.js';
+import type { AnalyzerSelectionOptions } from './analyzer-registry.js';
 import { isCodeFile, isBinaryFile } from '../utils/language-detection.js';
 import {
   getEmbeddingProvider,
@@ -210,6 +211,7 @@ async function cleanupDirectory(dirPath: string): Promise<void> {
 export interface IndexerOptions {
   rootPath: string;
   config?: Partial<CodebaseConfig>;
+  projectOptions?: AnalyzerSelectionOptions;
   onProgress?: (progress: IndexingProgress) => void;
   incrementalOnly?: boolean;
 }
@@ -224,13 +226,18 @@ interface PersistedIndexingStats {
 export class CodebaseIndexer {
   private rootPath: string;
   private config: CodebaseConfig;
+  private projectOptions: AnalyzerSelectionOptions;
   private progress: IndexingProgress;
   private onProgressCallback?: (progress: IndexingProgress) => void;
   private incrementalOnly: boolean;
 
   constructor(options: IndexerOptions) {
     this.rootPath = path.resolve(options.rootPath);
     this.config = this.mergeConfig(options.config);
+    this.projectOptions = {
+      preferredAnalyzer: options.projectOptions?.preferredAnalyzer,
+      extraFileExtensions: options.projectOptions?.extraFileExtensions
+    };
     this.onProgressCallback = options.onProgress;
     this.incrementalOnly = options.incrementalOnly ?? false;
 
@@ -321,6 +328,45 @@ export class CodebaseIndexer {
     };
   }
 
+  private getProjectOptions(): AnalyzerSelectionOptions {
+    const preferredAnalyzer = this.projectOptions.preferredAnalyzer?.trim();
+    if (!preferredAnalyzer) {
+      return this.projectOptions;
+    }
+
+    if (!analyzerRegistry.get(preferredAnalyzer)) {
+      console.warn(
+        `[indexer] Preferred analyzer "${preferredAnalyzer}" is not registered. Falling back to default analyzer selection.`
+      );
+      return {
+        ...this.projectOptions,
+        preferredAnalyzer: undefined
+      };
+    }
+
+    return {
+      ...this.projectOptions,
+      preferredAnalyzer
+    };
+  }
+
+  private getIncludePatterns(): string[] {
+    const includePatterns = this.config.include || ['**/*'];
+    const extraFileExtensions = this.projectOptions.extraFileExtensions ?? [];
+
+    if (extraFileExtensions.length === 0) {
+      return includePatterns;
+    }
+
+    const extraPatterns = extraFileExtensions
+      .map((extension) => extension.trim().toLowerCase())
+      .filter((extension) => extension.length > 0)
+      .map((extension) => (extension.startsWith('.') ? extension : `.${extension}`))
+      .map((extension) => `**/*${extension}`);
+
+    return Array.from(new Set([...includePatterns, ...extraPatterns]));
+  }
+
   async index(): Promise<IndexingStats> {
     const startTime = Date.now();
     const stats: IndexingStats = {
@@ -357,6 +403,8 @@ export class CodebaseIndexer {
         analyzerRegistry.register(new GenericAnalyzer());
       }
 
+      const resolvedProjectOptions = this.getProjectOptions();
+
       const buildId = randomUUID();
       const generatedAt = new Date().toISOString();
       const toolVersion = await getToolVersion();
@@ -529,7 +577,7 @@ export class CodebaseIndexer {
           // Normalize line endings to \n for consistent cross-platform output
           const rawContent = await fs.readFile(file, 'utf-8');
           const content = rawContent.replace(/\r\n/g, '\n');
-          const result = await analyzerRegistry.analyzeFile(file, content);
+          const result = await analyzerRegistry.analyzeFile(file, content, resolvedProjectOptions);
 
           if (result) {
             const isFileChanged = !filesToProcessSet || filesToProcessSet.has(file);
@@ -1027,7 +1075,7 @@ export class CodebaseIndexer {
     }
 
     // Scan with glob
-    const includePatterns = this.config.include || ['**/*'];
+    const includePatterns = this.getIncludePatterns();
     const excludePatterns = this.config.exclude || [];
 
     for (const pattern of includePatterns) {
@@ -1053,7 +1101,7 @@ export class CodebaseIndexer {
         }
 
         // Check if it's a code file
-        if (!isCodeFile(file) || isBinaryFile(file)) {
+        if (!isCodeFile(file, this.projectOptions.extraFileExtensions) || isBinaryFile(file)) {
           continue;
         }