preflight-mcp 0.7.2 → 0.7.4

package/README.md

@@ -86,7 +86,7 @@ Preflight: 📄 Parsed design-spec.pdf (45 pages)
 - 📖 **Auto-generated guides** — `START_HERE.md`, `AGENTS.md`, `OVERVIEW.md`
 - ☁️ **Cloud sync** — Multi-path mirror backup for redundancy
 - 🧠 **EDDA (Evidence-Driven Deep Analysis)** — Auto-generate auditable claims with evidence
-- ⚡ **21 MCP tools + 6 prompts** — Streamlined toolkit optimized for LLM use
+- ⚡ **22 MCP tools + 6 prompts** — Streamlined toolkit optimized for LLM use
 - 🧠 **Intelligent routing** — Auto-suggest tools based on task
 - 🔗 **Call graph analysis** — Function-level dependency tracking (v0.7.2)
 
@@ -199,7 +199,7 @@ This will:
 "Search for architecture diagrams in the bundle"
 ```
 
-## Tools (25 active)
+## Tools (22 active)
 
 ### Call Graph Tools (NEW v0.7.2)
 
@@ -426,6 +426,13 @@ Response includes:
 ### Analysis & Evidence
 - `PREFLIGHT_ANALYSIS_MODE`: `none` | `quick` | `full` (default: `full`)
 - `PREFLIGHT_AST_ENGINE`: `wasm` (default) or `native`
+- `PREFLIGHT_DEEP_ANALYSIS_MAX_OVERVIEW_CHARS`: max chars for overview summary (default: 800)
+- `PREFLIGHT_DEFAULT_SEARCH_CONTEXT_LINES`: context lines for search excerpts (default: 30)
+
+### Performance Tuning
+- `PREFLIGHT_MANIFEST_CACHE_TTL_MS`: manifest cache TTL in ms (default: 300000 = 5 min)
+- `PREFLIGHT_MANIFEST_CACHE_MAX_SIZE`: max manifest cache entries (default: 100)
+- `PREFLIGHT_TASK_CLEANUP_DELAY_MS`: task cleanup delay after completion (default: 60000 = 1 min)
 
 ### Built-in HTTP API
 - `PREFLIGHT_HTTP_ENABLED`: enable/disable REST API (default: true)

package/README.zh-CN.md

@@ -217,7 +217,7 @@ npm run smoke
 - 列表与清理逻辑只接受 UUID v4 作为 bundleId
 - 会自动过滤 `#recycle`、`tmp`、`.deleting` 等非 bundle 目录
 
-## Tools (25 active)
+## Tools (22 active)
 
 ### 调用图工具 (v0.7.2 新增)
 

package/dist/analysis/call-graph/adapters/base-adapter.js

@@ -0,0 +1,193 @@
+/**
+ * Base Language Adapter for Call Graph Analysis
+ *
+ * Provides common functionality for all language adapters:
+ * - File and cache management
+ * - Common utility methods
+ * - Abstract method declarations for language-specific implementations
+ *
+ * This base class was extracted to reduce code duplication across adapters.
+ *
+ * @module analysis/call-graph/adapters/base-adapter
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createNodeId, } from '../types.js';
+// ============================================================================
+// Base Adapter Abstract Class
+// ============================================================================
+/**
+ * Abstract base class for language-specific call graph adapters.
+ * Provides common caching and utility functionality.
+ */
+export class BaseLanguageAdapter {
+    /** Project root path */
+    rootPath = '';
+    /** Cache for file contents */
+    fileCache = new Map();
+    /** Whether the adapter has been initialized */
+    initialized = false;
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
+    /**
+     * Initialize the adapter with the project root path.
+     * Override in subclasses to perform language-specific initialization.
+     */
+    async initialize(rootPath) {
+        this.rootPath = rootPath;
+        this.initialized = true;
+    }
+    /**
+     * Shutdown the adapter and clean up resources.
+     * Override in subclasses to perform language-specific cleanup.
+     */
+    async shutdown() {
+        this.fileCache.clear();
+        this.initialized = false;
+    }
+    // ============================================================================
+    // File Support
+    // ============================================================================
+    /**
+     * Check if a file is supported by this adapter based on extension.
+     */
+    supportsFile(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return this.supportedExtensions.includes(ext);
+    }
+    // ============================================================================
+    // File Cache Management
+    // ============================================================================
+    /**
+     * Read file content with caching.
+     * Returns null if file cannot be read.
+     */
+    readFileCached(filePath) {
+        // Check cache first
+        const cached = this.fileCache.get(filePath);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Read from disk
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            this.fileCache.set(filePath, content);
+            return content;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Clear the file cache, optionally for a specific file.
+     */
+    clearCache(filePath) {
+        if (filePath) {
+            this.fileCache.delete(filePath);
+        }
+        else {
+            this.fileCache.clear();
+        }
+    }
+    /**
+     * Invalidate cache for files matching a pattern.
+     */
+    invalidateCacheMatching(pattern) {
+        let cleared = 0;
+        for (const key of this.fileCache.keys()) {
+            if (pattern.test(key)) {
+                this.fileCache.delete(key);
+                cleared++;
+            }
+        }
+        return cleared;
+    }
+    // ============================================================================
+    // Path Utilities
+    // ============================================================================
+    /**
+     * Convert absolute path to relative path from root.
+     */
+    toRelativePath(absolutePath) {
+        return path.relative(this.rootPath, absolutePath);
+    }
+    /**
+     * Convert relative path to absolute path from root.
+     */
+    toAbsolutePath(relativePath) {
+        if (path.isAbsolute(relativePath)) {
+            return relativePath;
+        }
+        return path.join(this.rootPath, relativePath);
+    }
+    /**
+     * Normalize path separators to forward slashes.
+     */
+    normalizePath(filePath) {
+        return filePath.replace(/\\/g, '/');
+    }
+    // ============================================================================
+    // Source Location Utilities
+    // ============================================================================
+    /**
+     * Create a source location object.
+     */
+    createLocation(filePath, line, column, endLine, endColumn) {
+        return {
+            filePath,
+            line,
+            column,
+            endLine,
+            endColumn,
+        };
+    }
+    /**
+     * Generate a unique node ID for a symbol.
+     */
+    generateNodeId(filePath, line, column, name) {
+        return createNodeId(filePath, line, column, name);
+    }
+    // ============================================================================
+    // Optional Override Points
+    // ============================================================================
+    /**
+     * Check if the adapter is ready to process requests.
+     * Override in subclasses that need async initialization.
+     */
+    isReady() {
+        return this.initialized;
+    }
+    /**
+     * Ensure the adapter is initialized before processing requests.
+     * Throws an error if not initialized.
+     */
+    ensureInitialized() {
+        if (!this.isReady()) {
+            throw new Error(`${this.language} adapter not initialized. Call initialize() first.`);
+        }
+    }
+}
+// ============================================================================
+// Helper Exports
+// ============================================================================
+/**
+ * Common symbol kind mapping for languages that use similar conventions.
+ */
+export const COMMON_SYMBOL_KINDS = {
+    function: 'function',
+    method: 'method',
+    constructor: 'constructor',
+    getter: 'getter',
+    setter: 'setter',
+    class: 'class',
+    interface: 'interface',
+    module: 'module',
+    enum: 'enum',
+};
+/**
+ * Check if a name follows common export conventions (starts with uppercase).
+ */
+export function isExportedByConvention(name) {
+    return /^[A-Z]/.test(name);
+}

package/dist/analysis/deep.js

@@ -7,8 +7,9 @@ import { createEmptyCoverageReport, isCoverageSufficient, } from '../types/evide
  * Build a deep analysis result from individual component results.
  * This is called by the server after gathering data from each source.
  */
-export function buildDeepAnalysis(bundleId, components) {
+export function buildDeepAnalysis(bundleId, components, options) {
     const { tree, search, deps, traces, overviewContent, testInfo, focusPath, focusQuery, errors = [] } = components;
+    const maxOverviewChars = options?.maxOverviewChars ?? 800;
     // Build coverage report
     const coverageReport = createEmptyCoverageReport();
     if (tree) {
@@ -30,9 +31,8 @@ export function buildDeepAnalysis(bundleId, components) {
         const lines = overviewContent.overview.split('\n');
         const contentLines = [];
         let charCount = 0;
-        const MAX_CHARS = 800; // Limit to ~200 tokens
         for (const line of lines) {
-            if (charCount >= MAX_CHARS)
+            if (charCount >= maxOverviewChars)
                 break;
             // Skip empty lines at start and title lines
             if (contentLines.length === 0 && (line.trim() === '' || line.startsWith('#')))
@@ -42,7 +42,7 @@ export function buildDeepAnalysis(bundleId, components) {
         }
         if (contentLines.length > 0) {
             summaryParts.push(contentLines.join('\n'));
-            if (charCount >= MAX_CHARS) {
+            if (charCount >= maxOverviewChars) {
                 summaryParts.push('...(truncated, see OVERVIEW.md for full content)');
             }
         }

package/dist/analysis/languages/go-analyzer.js

@@ -11,6 +11,7 @@
  */
 import { createModuleLogger } from '../../logging/logger.js';
 import { extractExtensionPointsWasm, } from '../../ast/treeSitter.js';
+import { INTERFACE_BASE_SCORE, INTERFACE_METHODS_HIGH_BONUS, INTERFACE_METHODS_LOW_BONUS, INTERFACE_EMPTY_SCORE, INTERFACE_EMBEDDING_BONUS, INTERFACE_HANDLER_BONUS, INTERFACE_PLUGIN_BONUS, CONSTRAINT_BASE_SCORE, CONSTRAINT_MEMBERS_HIGH_BONUS, CONSTRAINT_MEMBERS_LOW_BONUS, CONSTRAINT_HIGH_MEMBER_THRESHOLD, CONSTRAINT_LOW_MEMBER_THRESHOLD, MAX_SCORE, } from '../scoring-config.js';
 const logger = createModuleLogger('go-analyzer');
 // ============================================================================
 // Go Analyzer Class
@@ -24,6 +25,17 @@ export class GoAnalyzer {
         // Try tree-sitter first for accurate AST parsing
         const treeSitterResult = await extractExtensionPointsWasm(filePath, content);
         if (treeSitterResult && treeSitterResult.extensionPoints.length > 0) {
+            // Check if tree-sitter found methods in interfaces
+            const hasMethodsInInterfaces = treeSitterResult.extensionPoints.some(p => p.kind === 'interface' && p.methods && p.methods.length > 0);
+            // If tree-sitter found interfaces but no methods, fall back to regex
+            // as tree-sitter might have failed to parse the methods
+            if (!hasMethodsInInterfaces) {
+                const hasInterfaces = treeSitterResult.extensionPoints.some(p => p.kind === 'interface');
+                if (hasInterfaces) {
+                    logger.debug('Tree-sitter found interfaces without methods, falling back to regex');
+                    return this.analyzeContentWithRegex(content, filePath);
+                }
+            }
             return this.convertTreeSitterResult(treeSitterResult.extensionPoints, filePath);
         }
         // Fallback to regex-based parsing
@@ -434,37 +446,45 @@ export class GoAnalyzer {
         }
         return 'enum-options';
     }
+    /**
+     * Calculate extensibility score for a Go interface.
+     * See src/analysis/scoring-config.ts for scoring constant documentation.
+     */
     scoreInterface(iface) {
-        let score = 60; // Base score for exported interfaces
+        let score = INTERFACE_BASE_SCORE;
         // More methods = more extensible
         if (iface.methods.length >= 3)
-            score += 15;
+            score += INTERFACE_METHODS_HIGH_BONUS;
         else if (iface.methods.length >= 1)
-            score += 10;
-        // Empty interface (any) is very extensible
+            score += INTERFACE_METHODS_LOW_BONUS;
+        // Empty interface (any) is very extensible but too generic
         if (iface.methods.length === 0 && iface.embedded.length === 0) {
-            score = 50; // Lower score - too generic
+            score = INTERFACE_EMPTY_SCORE;
         }
         // Embedding other interfaces suggests composition pattern
         if (iface.embedded.length > 0)
-            score += 10;
+            score += INTERFACE_EMBEDDING_BONUS;
         // Common extension patterns
         const nameLower = iface.name.toLowerCase();
         if (nameLower.includes('handler') || nameLower.includes('processor')) {
-            score += 15;
+            score += INTERFACE_HANDLER_BONUS;
         }
         if (nameLower.includes('plugin') || nameLower.includes('provider')) {
-            score += 20;
+            score += INTERFACE_PLUGIN_BONUS;
         }
-        return Math.min(score, 100);
+        return Math.min(score, MAX_SCORE);
     }
+    /**
+     * Calculate extensibility score for a Go type constraint.
+     * See src/analysis/scoring-config.ts for scoring constant documentation.
+     */
     scoreConstraint(memberCount) {
-        let score = 50;
-        if (memberCount >= 5)
-            score += 20;
-        else if (memberCount >= 3)
-            score += 10;
-        return Math.min(score, 100);
+        let score = CONSTRAINT_BASE_SCORE;
+        if (memberCount >= CONSTRAINT_HIGH_MEMBER_THRESHOLD)
+            score += CONSTRAINT_MEMBERS_HIGH_BONUS;
+        else if (memberCount >= CONSTRAINT_LOW_MEMBER_THRESHOLD)
+            score += CONSTRAINT_MEMBERS_LOW_BONUS;
+        return Math.min(score, MAX_SCORE);
     }
 }
 // ============================================================================

package/dist/analysis/pattern-analyzer.js

@@ -10,6 +10,7 @@
  */
 import * as fs from 'node:fs/promises';
 import { createModuleLogger } from '../logging/logger.js';
+import { getConfig } from '../config.js';
 const logger = createModuleLogger('pattern-analyzer');
 /**
  * Design hint patterns to detect.
@@ -70,8 +71,13 @@ const INTERFACE_EXTENSION_PATTERNS = [
  * Analyzer for design patterns and comments in source code.
  */
 export class PatternAnalyzer {
+    strictMode;
+    constructor(options) {
+        this.strictMode = options?.strictMode ?? getConfig().strictMode;
+    }
     /**
      * Analyze a file for design hints.
+     * In strict mode, errors are thrown instead of being logged and returning empty results.
      */
     async analyzeFile(filePath, content) {
         const results = [];
@@ -101,6 +107,10 @@ export class PatternAnalyzer {
         }
         catch (error) {
             logger.error(`Failed to analyze ${filePath}`, error instanceof Error ? error : undefined);
+            // In strict mode, propagate errors instead of returning empty results
+            if (this.strictMode) {
+                throw error;
+            }
             return [];
         }
     }

package/dist/analysis/scoring-config.js

@@ -0,0 +1,118 @@
+/**
+ * Scoring Configuration Constants
+ *
+ * This file contains all scoring-related constants used in static analysis.
+ * Centralizing these values makes them easier to tune and document.
+ *
+ * @module analysis/scoring-config
+ */
+// ============================================================================
+// Interface Scoring (Go Analyzer)
+// ============================================================================
+/**
+ * Base score for exported interfaces.
+ * Starting point before applying bonuses.
+ */
+export const INTERFACE_BASE_SCORE = 60;
+/**
+ * Score bonus for interfaces with 3+ methods.
+ * More methods typically indicate more extensible APIs.
+ */
+export const INTERFACE_METHODS_HIGH_BONUS = 15;
+/**
+ * Score bonus for interfaces with 1-2 methods.
+ * Moderate extensibility indication.
+ */
+export const INTERFACE_METHODS_LOW_BONUS = 10;
+/**
+ * Score for empty interfaces (any type).
+ * Lower than base because they're too generic.
+ */
+export const INTERFACE_EMPTY_SCORE = 50;
+/**
+ * Score bonus for interfaces embedding other interfaces.
+ * Suggests composition pattern usage.
+ */
+export const INTERFACE_EMBEDDING_BONUS = 10;
+/**
+ * Score bonus for handler/processor named interfaces.
+ * Common extensibility patterns.
+ */
+export const INTERFACE_HANDLER_BONUS = 15;
+/**
+ * Score bonus for plugin/provider named interfaces.
+ * Strong extensibility indication.
+ */
+export const INTERFACE_PLUGIN_BONUS = 20;
+// ============================================================================
+// Type Constraint Scoring (Go Analyzer)
+// ============================================================================
+/**
+ * Base score for type constraints.
+ */
+export const CONSTRAINT_BASE_SCORE = 50;
+/**
+ * Score bonus for constraints with 5+ members.
+ * More members indicate more comprehensive type bounds.
+ */
+export const CONSTRAINT_MEMBERS_HIGH_BONUS = 20;
+/**
+ * Score bonus for constraints with 3-4 members.
+ */
+export const CONSTRAINT_MEMBERS_LOW_BONUS = 10;
+/**
+ * Member count threshold for high bonus.
+ */
+export const CONSTRAINT_HIGH_MEMBER_THRESHOLD = 5;
+/**
+ * Member count threshold for low bonus.
+ */
+export const CONSTRAINT_LOW_MEMBER_THRESHOLD = 3;
+// ============================================================================
+// General Scoring Limits
+// ============================================================================
+/**
+ * Maximum possible score for any item.
+ */
+export const MAX_SCORE = 100;
+/**
+ * Minimum score threshold for including items in results.
+ */
+export const MIN_SCORE_THRESHOLD = 0;
+// ============================================================================
+// TypeScript/JavaScript Scoring (for future use)
+// ============================================================================
+/**
+ * Base score for exported TypeScript interfaces.
+ */
+export const TS_INTERFACE_BASE_SCORE = 60;
+/**
+ * Base score for exported TypeScript types.
+ */
+export const TS_TYPE_BASE_SCORE = 50;
+/**
+ * Score bonus for discriminated unions.
+ */
+export const TS_DISCRIMINATED_UNION_BONUS = 25;
+// ============================================================================
+// Python Scoring (for future use)
+// ============================================================================
+/**
+ * Base score for Python ABC classes.
+ */
+export const PY_ABC_BASE_SCORE = 60;
+/**
+ * Base score for Python Protocol classes.
+ */
+export const PY_PROTOCOL_BASE_SCORE = 65;
+// ============================================================================
+// Rust Scoring (for future use)
+// ============================================================================
+/**
+ * Base score for Rust traits.
+ */
+export const RUST_TRAIT_BASE_SCORE = 60;
+/**
+ * Score bonus for traits with default implementations.
+ */
+export const RUST_TRAIT_DEFAULT_IMPL_BONUS = 10;