project-graph-mcp 1.3.0 → 1.5.0

package/src/full-analysis.js

@@ -1,15 +1,24 @@
 /**
  * Full Analysis - Comprehensive Code Health Report
  * Runs all analysis tools and generates a health score
+ * 
+ * Uses incremental caching for per-file metrics (complexity, undocumented, jsdocConsistency).
+ * Cross-file metrics (dead code, similarity) always run dynamically.
  */
 
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, resolve } from 'path';
 import { getDeadCode } from './dead-code.js';
-import { getUndocumentedSummary } from './undocumented.js';
+import { checkUndocumentedFile } from './undocumented.js';
 import { getSimilarFunctions } from './similar-functions.js';
-import { getComplexity } from './complexity.js';
+import { analyzeComplexityFile } from './complexity.js';
 import { getLargeFiles } from './large-files.js';
 import { getOutdatedPatterns } from './outdated-patterns.js';
 import { getTableUsage } from './db-analysis.js';
+import { checkJSDocFile } from './jsdoc-checker.js';
+import { readCache, writeCache, computeContentHash, isCacheValid } from './analysis-cache.js';
+import { shouldExcludeDir, shouldExcludeFile, parseGitignore } from './filters.js';
+import { getWorkspaceRoot } from './workspace.js';
 
 /**
  * @typedef {Object} AnalysisResult
@@ -75,10 +84,21 @@ function calculateHealthScore(results) {
   const warningPatterns = results.outdated.stats?.bySeverity?.warning || 0;
   const outdatedPenalty = Math.min(errorPatterns * 3 + warningPatterns * 1, 10);
   score -= outdatedPenalty;
-  if (results.outdated.redundantDeps.length > 0) {
+  if (results.outdated.redundantDeps?.length > 0) {
     topIssues.push(`${results.outdated.redundantDeps.length} redundant npm dependencies`);
   }
 
+  // JSDoc consistency penalty: -2 per error, -1 per warning (max -15)
+  if (results.jsdocConsistency) {
+    const jsdocErrors = results.jsdocConsistency.errors || 0;
+    const jsdocWarnings = results.jsdocConsistency.warnings || 0;
+    const jsdocPenalty = Math.min(jsdocErrors * 2 + jsdocWarnings * 1, 15);
+    score -= jsdocPenalty;
+    if (jsdocErrors > 0) {
+      topIssues.push(`${jsdocErrors} JSDoc consistency errors`);
+    }
+  }
+
   // Clamp score
   score = Math.max(0, Math.min(100, Math.round(score)));
 
@@ -92,8 +112,158 @@ function calculateHealthScore(results) {
   return { score, rating, topIssues: topIssues.slice(0, 5) };
 }
 
+/**
+ * Find all JS files in directory
+ * @param {string} dir
+ * @param {string} rootDir
+ * @returns {string[]}
+ */
+function findJSFiles(dir, rootDir = dir) {
+  if (dir === rootDir) parseGitignore(rootDir);
+  const files = [];
+  try {
+    for (const entry of readdirSync(dir)) {
+      const fullPath = join(dir, entry);
+      const relativePath = relative(rootDir, fullPath);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        if (!shouldExcludeDir(entry, relativePath)) {
+          files.push(...findJSFiles(fullPath, rootDir));
+        }
+      } else if (entry.endsWith('.js') && !entry.endsWith('.css.js') && !entry.endsWith('.tpl.js')) {
+        if (!shouldExcludeFile(entry, relativePath)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  } catch (e) { /* dir not found */ }
+  return files;
+}
+
+/**
+ * Run cacheable per-file analyses with cache support
+ * Returns aggregated complexity, undocumented, and jsdoc results
+ * @param {string} dir
+ * @param {string} contextDir
+ * @returns {{ complexity: Object[], undocumented: Object[], jsdocIssues: Object[], cacheStats: { hits: number, misses: number } }}
+ */
+function runCacheableAnalyses(dir, contextDir) {
+  const resolvedDir = resolve(dir);
+  const wsRoot = getWorkspaceRoot();
+  const files = findJSFiles(dir);
+  
+  const allComplexity = [];
+  const allUndocumented = [];
+  const allJsdocIssues = [];
+  let cacheHits = 0;
+  let cacheMisses = 0;
+
+  for (const file of files) {
+    const relPath = relative(resolvedDir, file);
+    // Cache key: workspace-relative (src/parser.js), matches graph paths
+    const cacheKey = relative(wsRoot, file);
+    let code;
+    try {
+      code = readFileSync(file, 'utf-8');
+    } catch (e) {
+      continue; // File deleted between findJSFiles and read
+    }
+    const contentHash = computeContentHash(code);
+    
+    // Check cache (key: workspace-relative)
+    const cached = readCache(contextDir, cacheKey);
+    
+    if (cached && isCacheValid(cached, cached.sig, contentHash, 'content')) {
+      // Cache hit — use cached results
+      cacheHits++;
+      if (cached.complexity) allComplexity.push(...cached.complexity);
+      if (cached.undocumented) allUndocumented.push(...cached.undocumented);
+      if (cached.jsdocIssues) allJsdocIssues.push(...cached.jsdocIssues);
+    } else {
+      // Cache miss — compute fresh
+      cacheMisses++;
+      const complexity = analyzeComplexityFile(code, relPath);
+      const undocumented = checkUndocumentedFile(code, relPath, 'tests');
+      const jsdocIssues = checkJSDocFile(code, relPath);
+
+      allComplexity.push(...complexity);
+      allUndocumented.push(...undocumented);
+      allJsdocIssues.push(...jsdocIssues);
+
+      // Save to cache (key: workspace-relative)
+      writeCache(contextDir, cacheKey, {
+        sig: cached?.sig || contentHash,
+        contentHash,
+        complexity,
+        undocumented,
+        jsdocIssues,
+      });
+    }
+  }
+
+  return {
+    complexity: allComplexity,
+    undocumented: allUndocumented,
+    jsdocIssues: allJsdocIssues,
+    cacheStats: { hits: cacheHits, misses: cacheMisses },
+  };
+}
+
+/**
+ * Aggregate complexity items into summary format
+ * @param {Object[]} items
+ * @param {number} minComplexity
+ * @returns {Object}
+ */
+function aggregateComplexity(items, minComplexity = 5) {
+  let filtered = items.filter(i => i.complexity >= minComplexity);
+  filtered.sort((a, b) => b.complexity - a.complexity);
+
+  const stats = {
+    low: filtered.filter(i => i.rating === 'low').length,
+    moderate: filtered.filter(i => i.rating === 'moderate').length,
+    high: filtered.filter(i => i.rating === 'high').length,
+    critical: filtered.filter(i => i.rating === 'critical').length,
+    average: filtered.length > 0
+      ? Math.round(filtered.reduce((s, i) => s + i.complexity, 0) / filtered.length * 10) / 10
+      : 0,
+  };
+
+  return { total: filtered.length, stats, items: filtered.slice(0, 30) };
+}
+
+/**
+ * Aggregate undocumented items into summary format
+ * @param {Object[]} items
+ * @returns {Object}
+ */
+function aggregateUndocumented(items) {
+  const byType = {
+    class: items.filter(i => i.type === 'class').length,
+    function: items.filter(i => i.type === 'function').length,
+    method: items.filter(i => i.type === 'method').length,
+  };
+  return { total: items.length, byType, items: items.slice(0, 20) };
+}
+
+/**
+ * Aggregate JSDoc issues into summary format
+ * @param {Object[]} issues
+ * @returns {{ issues: Object[], summary: Object }}
+ */
+function aggregateJSDoc(issues) {
+  const errors = issues.filter(i => i.severity === 'error').length;
+  const warnings = issues.filter(i => i.severity === 'warning').length;
+  const byFile = {};
+  for (const issue of issues) {
+    byFile[issue.file] = (byFile[issue.file] || 0) + 1;
+  }
+  return { issues, summary: { total: issues.length, errors, warnings, byFile } };
+}
+
 /**
  * Run full analysis on directory
+ * Uses incremental cache for per-file metrics; cross-file metrics always recompute.
  * @param {string} dir 
  * @param {Object} [options]
  * @param {boolean} [options.includeItems=false] - Include individual items
@@ -101,15 +271,21 @@ function calculateHealthScore(results) {
  */
 export async function getFullAnalysis(dir, options = {}) {
   const includeItems = options.includeItems || false;
+  const resolvedDir = resolve(dir);
+  const contextDir = join(getWorkspaceRoot(), '.context');
+
+  // Run cacheable per-file analyses (complexity, undocumented, jsdoc)
+  const cached = runCacheableAnalyses(dir, contextDir);
+  const complexity = aggregateComplexity(cached.complexity);
+  const undocumented = aggregateUndocumented(cached.undocumented);
+  const jsdocCheck = aggregateJSDoc(cached.jsdocIssues);
 
-  // Run all analyses in parallel
-  const [deadCode, undocumented, similar, complexity, largeFiles, outdated, dbUsage] = await Promise.all([
-    getDeadCode(dir),
-    getUndocumentedSummary(dir, 'tests'),
-    getSimilarFunctions(dir, { threshold: 70 }),
-    getComplexity(dir, { minComplexity: 5 }),
-    getLargeFiles(dir),
-    getOutdatedPatterns(dir),
+  // Run cross-file analyses (always dynamic — NOT cacheable per-file)
+  const [deadCode, similar, largeFiles, outdated, dbUsage] = await Promise.all([
+    getDeadCode(dir).catch(() => ({ total: 0, byType: {}, items: [] })),
+    getSimilarFunctions(dir, { threshold: 70 }).catch(() => ({ total: 0, pairs: [] })),
+    getLargeFiles(dir).catch(() => ({ total: 0, stats: {}, items: [] })),
+    getOutdatedPatterns(dir).catch(() => ({ codePatterns: [], redundantDeps: [], stats: { totalPatterns: 0, bySeverity: {}, byPattern: {}, redundantDeps: 0 } })),
     getTableUsage(dir).catch(() => ({ tables: [], totalTables: 0, totalQueries: 0 })),
   ]);
 
@@ -121,6 +297,7 @@ export async function getFullAnalysis(dir, options = {}) {
     complexity,
     largeFiles,
     outdated,
+    jsdocConsistency: jsdocCheck.summary,
   });
 
   // Build result
@@ -154,6 +331,13 @@ export async function getFullAnalysis(dir, options = {}) {
       redundantDeps: outdated.redundantDeps,
       ...(includeItems && { codePatterns: outdated.codePatterns.slice(0, 10) }),
     },
+    jsdocConsistency: {
+      total: jsdocCheck.summary.total,
+      errors: jsdocCheck.summary.errors,
+      warnings: jsdocCheck.summary.warnings,
+      ...(includeItems && { issues: jsdocCheck.issues.slice(0, 10) }),
+    },
+    cache: cached.cacheStats,
     overall,
   };
 
@@ -172,3 +356,115 @@ export async function getFullAnalysis(dir, options = {}) {
 
   return result;
 }
+
+/**
+ * Quick health check — runs only cached per-file metrics, skips cross-file.
+ * @param {string} dir - Path to scan
+ * @returns {{healthScore: number, complexity: number, undocumented: number, jsdocIssues: number}}
+ */
+export function getAnalysisSummaryOnly(dir) {
+  const contextDir = join(getWorkspaceRoot(), '.context');
+  const cached = runCacheableAnalyses(dir, contextDir);
+  const complexity = aggregateComplexity(cached.complexity);
+  const undocumented = aggregateUndocumented(cached.undocumented);
+  const jsdocCheck = aggregateJSDoc(cached.jsdocIssues);
+
+  // Reuse the same health score formula as getFullAnalysis
+  const overall = calculateHealthScore({
+    deadCode: { total: 0 },
+    undocumented,
+    similar: { total: 0 },
+    complexity,
+    largeFiles: { total: 0 },
+    outdated: { stats: { totalPatterns: 0 } },
+    jsdocConsistency: jsdocCheck.summary,
+  });
+
+  return {
+    healthScore: overall.score,
+    grade: overall.rating,
+    complexity: complexity.total,
+    undocumented: undocumented.total,
+    jsdocIssues: jsdocCheck.summary.total,
+    cache: cached.cacheStats,
+    note: 'Partial score — cross-file analyses skipped for speed. Run get_full_analysis for complete health check.',
+  };
+}
+
+/**
+ * Streaming analysis — yields results as each sub-analysis completes.
+ * Useful for large codebases where waiting for all analyses is too slow.
+ * @param {string} dir - Path to scan
+ * @param {Object} [options]
+ * @param {boolean} [options.includeItems=false]
+ * @returns {AsyncGenerator<{type: string, data: Object}>}
+ */
+export async function* getFullAnalysisStreaming(dir, options = {}) {
+  const includeItems = options.includeItems || false;
+  const contextDir = join(getWorkspaceRoot(), '.context');
+  
+  // Phase 1: Cached per-file analyses (fast)
+  const cached = runCacheableAnalyses(dir, contextDir);
+  
+  const complexity = aggregateComplexity(cached.complexity);
+  yield { type: 'complexity', data: {
+    total: complexity.total,
+    stats: complexity.stats,
+    ...(includeItems && { items: complexity.items.slice(0, 10) }),
+  }};
+  
+  const undocumented = aggregateUndocumented(cached.undocumented);
+  yield { type: 'undocumented', data: {
+    total: undocumented.total,
+    byType: undocumented.byType,
+    ...(includeItems && { items: undocumented.items.slice(0, 10) }),
+  }};
+  
+  const jsdocCheck = aggregateJSDoc(cached.jsdocIssues);
+  yield { type: 'jsdocConsistency', data: {
+    total: jsdocCheck.summary.total,
+    errors: jsdocCheck.summary.errors,
+    warnings: jsdocCheck.summary.warnings,
+    ...(includeItems && { issues: jsdocCheck.issues.slice(0, 10) }),
+  }};
+  
+  yield { type: 'cache', data: cached.cacheStats };
+  
+  // Phase 2: Cross-file analyses (slow, one at a time)
+  try {
+    const deadCode = await getDeadCode(dir);
+    yield { type: 'deadCode', data: {
+      total: deadCode.total,
+      byType: deadCode.byType,
+      ...(includeItems && { items: deadCode.items.slice(0, 10) }),
+    }};
+  } catch { yield { type: 'deadCode', data: { total: 0, byType: {}, error: 'analysis failed' } }; }
+  
+  try {
+    const similar = await getSimilarFunctions(dir, { threshold: 70 });
+    yield { type: 'similar', data: {
+      total: similar.total,
+      ...(includeItems && { pairs: similar.pairs.slice(0, 5) }),
+    }};
+  } catch { yield { type: 'similar', data: { total: 0, error: 'analysis failed' } }; }
+  
+  try {
+    const largeFiles = await getLargeFiles(dir);
+    yield { type: 'largeFiles', data: {
+      total: largeFiles.total,
+      stats: largeFiles.stats,
+      ...(includeItems && { items: largeFiles.items.slice(0, 10) }),
+    }};
+  } catch { yield { type: 'largeFiles', data: { total: 0, error: 'analysis failed' } }; }
+  
+  try {
+    const outdated = await getOutdatedPatterns(dir);
+    yield { type: 'outdated', data: {
+      totalPatterns: outdated.stats.totalPatterns,
+      redundantDeps: outdated.redundantDeps,
+      ...(includeItems && { codePatterns: outdated.codePatterns.slice(0, 10) }),
+    }};
+  } catch { yield { type: 'outdated', data: { totalPatterns: 0, error: 'analysis failed' } }; }
+  
+  yield { type: 'done', data: { phases: 2, timestamp: new Date().toISOString() } };
+}

package/src/instructions.js

@@ -13,121 +13,19 @@ export const AGENT_INSTRUCTIONS = `
 - **State Management**: Use \`this.init$\` for local state and \`this.sub()\` for reactivity.
 - **Directives**: Use \`itemize\` for lists, \`js-d-kit\` for static generation.
 
-## 2. Test Annotations (@test/@expect)
-Universal verification checklist system. Works for **any** test type.
-
-### Syntax
-\`\`\`javascript
-/**
- * Method description
- * 
- * @test {type}: {description}
- * @expect {type}: {description}
- */
-async myMethod() { ... }
-\`\`\`
-
-### @test Types by Category
-
-#### 🌐 Browser / UI
-| Type | Description | Example |
-|------|-------------|---------|
-| \`click\` | Click element | \`@test click: Click submit button\` |
-| \`key\` | Keyboard input | \`@test key: Press Enter\` |
-| \`drag\` | Drag and drop | \`@test drag: Drag item to list\` |
-| \`type\` | Text input | \`@test type: Enter email in field\` |
-| \`scroll\` | Scroll action | \`@test scroll: Scroll to bottom\` |
-| \`hover\` | Mouse hover | \`@test hover: Hover over menu\` |
-
-#### 🔌 API / Function
-| Type | Description | Example |
-|------|-------------|---------|
-| \`request\` | HTTP request | \`@test request: POST /api/users\` |
-| \`call\` | Function call | \`@test call: Call with valid params\` |
-| \`invoke\` | Method invoke | \`@test invoke: Trigger event\` |
-| \`mock\` | Mock setup | \`@test mock: Mock external service\` |
-
-#### 💻 CLI / Process
-| Type | Description | Example |
-|------|-------------|---------|
-| \`run\` | Run command | \`@test run: Run with --help flag\` |
-| \`exec\` | Execute script | \`@test exec: Execute build script\` |
-| \`spawn\` | Spawn process | \`@test spawn: Start server\` |
-| \`input\` | Stdin input | \`@test input: Enter password\` |
-
-#### 🔗 Integration / System
-| Type | Description | Example |
-|------|-------------|---------|
-| \`setup\` | Test setup | \`@test setup: Create test database\` |
-| \`action\` | Main action | \`@test action: Run migration\` |
-| \`teardown\` | Cleanup | \`@test teardown: Remove temp files\` |
-| \`wait\` | Wait condition | \`@test wait: Wait for DB connection\` |
-
-### @expect Types by Category
-
-#### 🌐 Browser / UI
-| Type | Description | Example |
-|------|-------------|---------|
-| \`attr\` | Attribute check | \`@expect attr: disabled attribute set\` |
-| \`visual\` | Visual change | \`@expect visual: Button turns green\` |
-| \`element\` | Element exists | \`@expect element: Modal appears\` |
-| \`text\` | Text content | \`@expect text: Shows "Success"\` |
-
-#### 🔌 API / Function
-| Type | Description | Example |
-|------|-------------|---------|
-| \`status\` | HTTP status | \`@expect status: 201 Created\` |
-| \`body\` | Response body | \`@expect body: Contains user ID\` |
-| \`headers\` | Response headers | \`@expect headers: Content-Type JSON\` |
-| \`error\` | Error thrown | \`@expect error: Throws ValidationError\` |
-
-#### 💻 CLI / Process
-| Type | Description | Example |
-|------|-------------|---------|
-| \`output\` | Stdout content | \`@expect output: Prints version\` |
-| \`exitcode\` | Exit code | \`@expect exitcode: Returns 0\` |
-| \`file\` | File created | \`@expect file: Creates config.json\` |
-| \`stderr\` | Stderr content | \`@expect stderr: No errors\` |
-
-#### 🔗 Integration / System
-| Type | Description | Example |
-|------|-------------|---------|
-| \`state\` | State change | \`@expect state: User logged in\` |
-| \`log\` | Log entry | \`@expect log: Info message logged\` |
-| \`event\` | Event fired | \`@expect event: 'updated' emitted\` |
-| \`db\` | Database change | \`@expect db: Row inserted\` |
-
-### Full Example
-\`\`\`javascript
-/**
- * Create new user via API
- * 
- * @test request: POST /api/users with valid data
- * @test call: Validate email format
- * 
- * @expect status: 201 Created
- * @expect body: Contains user ID and email
- * @expect db: User row created in database
- * @expect event: 'user.created' event emitted
- */
-async createUser(data) {
-  // ...
-}
-\`\`\`
-
-## 3. General Coding Rules
+## 2. General Coding Rules
 - **ESM Only**: Use \`import\` / \`export\`. No \`require\`.
 - **No Dependencies**: Avoid adding new npm packages unless critical.
 - **Comments**: Write clear JSDoc for all public methods.
 - **Async/Await**: Prefer async/await over promises.
 
-## 4. MCP Tools Usage
+## 3. MCP Tools Usage
 - **Graph**: Use \`get_skeleton\` first to map the codebase.
 - **Deep Dive**: Use \`expand\` to read class details.
 - **Tests**: Use \`get_pending_tests\` to see what needs verification.
 - **Guidelines**: Use \`get_agent_instructions\` to refresh these rules.
 
-## 5. Custom Rules System
+## 4. Custom Rules System
 Configurable code analysis with auto-detection.
 
 ### Available Tools