project-graph-mcp 1.3.0 → 1.5.0

package/src/jsdoc-checker.js

@@ -0,0 +1,351 @@
+/**
+ * JSDoc Consistency Checker (AST-based)
+ * Validates JSDoc annotations against actual function signatures
+ * 
+ * Checks:
+ * - Param count mismatch (JSDoc vs AST)
+ * - Param name mismatch
+ * - Missing @returns on functions with return statements
+ * - Type hint inconsistency (default value vs JSDoc type)
+ */
+
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { parse } from '../vendor/acorn.mjs';
+import * as walk from '../vendor/walk.mjs';
+import { shouldExcludeDir, shouldExcludeFile, parseGitignore } from './filters.js';
+
+/**
+ * @typedef {Object} JSDocIssue
+ * @property {string} file
+ * @property {number} line
+ * @property {string} name - Function or method name
+ * @property {'error'|'warning'} severity
+ * @property {string} message
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * Extract JSDoc comments with positions
+ * @param {string} code
+ * @returns {Array<{text: string, endLine: number, params: Array<{name: string, type: string}>, hasReturns: boolean}>}
+ */
+function extractJSDocComments(code) {
+  const comments = [];
+  const regex = /\/\*\*[\s\S]*?\*\//g;
+  let match;
+
+  while ((match = regex.exec(code)) !== null) {
+    const text = match[0];
+    const endLine = code.slice(0, match.index + text.length).split('\n').length;
+
+    // Parse @param tags — handle nested braces in types like {Array<{text: string}>}
+    const params = [];
+    const paramStartRegex = /@param\s+\{/g;
+    let paramStart;
+    while ((paramStart = paramStartRegex.exec(text)) !== null) {
+      // Find matching closing brace (balanced)
+      let depth = 1;
+      let i = paramStart.index + paramStart[0].length;
+      while (i < text.length && depth > 0) {
+        if (text[i] === '{') depth++;
+        else if (text[i] === '}') depth--;
+        i++;
+      }
+      if (depth !== 0) continue;
+      const type = text.slice(paramStart.index + paramStart[0].length, i - 1);
+      // Extract param name after the closing brace
+      const afterType = text.slice(i);
+      const nameMatch = afterType.match(/^\s+(\[?\w+(?:\.\w+)*\]?)/);
+      if (!nameMatch) continue;
+      let name = nameMatch[1];
+      // Strip [] from optional params: [opts] → opts
+      if (name.startsWith('[')) name = name.slice(1);
+      if (name.endsWith(']')) name = name.slice(0, -1);
+      // Strip dotted paths: options.includeTests → skip (nested property)
+      if (name.includes('.')) continue;
+      params.push({ name, type });
+    }
+
+    const hasReturns = /@returns?\s/.test(text);
+
+    comments.push({ text, endLine, params, hasReturns });
+  }
+
+  return comments;
+}
+
+/**
+ * Find JSDoc comment before a target line
+ * @param {Array} comments
+ * @param {number} targetLine
+ * @returns {Object|null}
+ */
+function findJSDocBefore(comments, targetLine) {
+  for (const comment of comments) {
+    const gap = targetLine - comment.endLine;
+    if (gap >= 0 && gap <= 2) return comment;
+  }
+  return null;
+}
+
+/**
+ * Extract parameter name from AST node
+ * @param {Object} param
+ * @returns {string}
+ */
+function extractParamName(param) {
+  if (param.type === 'Identifier') return param.name;
+  if (param.type === 'AssignmentPattern' && param.left.type === 'Identifier') return param.left.name;
+  if (param.type === 'RestElement' && param.argument.type === 'Identifier') return param.argument.name;
+  if (param.type === 'ObjectPattern') return 'options';
+  if (param.type === 'ArrayPattern') return 'args';
+  return 'param';
+}
+
+/**
+ * Infer expected type from AST default value
+ * @param {Object} param
+ * @returns {string|null}
+ */
+function inferTypeFromDefault(param) {
+  if (param.type !== 'AssignmentPattern') return null;
+  const def = param.right;
+  if (def.type === 'Literal') {
+    if (typeof def.value === 'string') return 'string';
+    if (typeof def.value === 'number') return 'number';
+    if (typeof def.value === 'boolean') return 'boolean';
+  }
+  if (def.type === 'ArrayExpression') return 'Array';
+  if (def.type === 'ObjectExpression') return 'Object';
+  return null;
+}
+
+/**
+ * Check if function body has return statements with values
+ * @param {Object} node - Function AST node
+ * @returns {boolean}
+ */
+function hasReturnValue(node) {
+  let found = false;
+  try {
+    walk.simple(node.body, {
+      ReturnStatement(ret) {
+        if (ret.argument) found = true;
+      },
+      // Don't recurse into nested functions
+      FunctionDeclaration() { },
+      FunctionExpression() { },
+      ArrowFunctionExpression() { },
+    });
+  } catch (e) { /* walk error */ }
+  return found;
+}
+
+/**
+ * Validate a function's JSDoc against its AST
+ * @param {Object} jsdoc - Parsed JSDoc
+ * @param {Object[]} astParams - AST param nodes
+ * @param {Object} funcNode - AST function node
+ * @param {string} name - Function name
+ * @param {string} file - File path
+ * @param {number} line - Line number
+ * @returns {JSDocIssue[]}
+ */
+function validateFunction(jsdoc, astParams, funcNode, name, file, line) {
+  const issues = [];
+
+  if (!jsdoc) return issues; // No JSDoc = handled by undocumented checker
+
+  const docParams = jsdoc.params;
+
+  // 1. Param count mismatch
+  if (docParams.length !== astParams.length) {
+    issues.push({
+      file, line, name,
+      severity: 'error',
+      message: `Param count mismatch: JSDoc has ${docParams.length}, function has ${astParams.length}`,
+    });
+  }
+
+  // 2. Param name mismatch
+  const minLen = Math.min(docParams.length, astParams.length);
+  for (let i = 0; i < minLen; i++) {
+    const docName = docParams[i].name;
+    const astName = extractParamName(astParams[i]);
+
+    if (docName !== astName && astName !== 'options' && astName !== 'args' && astName !== 'param') {
+      issues.push({
+        file, line, name,
+        severity: 'error',
+        message: `Param name mismatch at position ${i}: JSDoc says "${docName}", code has "${astName}"`,
+      });
+    }
+  }
+
+  // 3. Missing @returns on non-void functions
+  if (!jsdoc.hasReturns && hasReturnValue(funcNode)) {
+    issues.push({
+      file, line, name,
+      severity: 'warning',
+      message: 'Function returns a value but JSDoc has no @returns',
+    });
+  }
+
+  // 4. Type hint inconsistency
+  for (let i = 0; i < minLen; i++) {
+    const docType = docParams[i].type;
+    const inferredType = inferTypeFromDefault(astParams[i]);
+
+    if (inferredType && docType && docType !== '*') {
+      let compatible = docType.includes(inferredType);
+      // Union types like 'a'|'b' are valid strings
+      if (!compatible && inferredType === 'string' && docType.includes("'") && docType.includes('|')) {
+        compatible = true;
+      }
+      // Type[] shorthand is a valid Array
+      if (!compatible && inferredType === 'Array' && docType.includes('[]')) {
+        compatible = true;
+      }
+      if (!compatible) {
+        issues.push({
+          file, line, name,
+          severity: 'warning',
+          message: `Type mismatch for "${docParams[i].name}": JSDoc says {${docType}}, default value suggests {${inferredType}}`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check JSDoc consistency for a single file (per-file export for cache integration)
+ * @param {string} code
+ * @param {string} filePath
+ * @returns {JSDocIssue[]}
+ */
+export function checkJSDocFile(code, filePath) {
+  const issues = [];
+
+  let ast;
+  try {
+    ast = parse(code, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
+  } catch (e) {
+    return issues;
+  }
+
+  const comments = extractJSDocComments(code);
+
+  walk.simple(ast, {
+    FunctionDeclaration(node) {
+      if (!node.id) return;
+      const jsdoc = findJSDocBefore(comments, node.loc.start.line);
+      if (jsdoc) {
+        issues.push(...validateFunction(jsdoc, node.params, node, node.id.name, filePath, node.loc.start.line));
+      }
+    },
+
+    // Exported arrow/const functions
+    VariableDeclaration(node) {
+      for (const decl of node.declarations) {
+        if (!decl.init) continue;
+        const func = decl.init.type === 'ArrowFunctionExpression' || decl.init.type === 'FunctionExpression'
+          ? decl.init : null;
+        if (!func || !decl.id?.name) continue;
+
+        const jsdoc = findJSDocBefore(comments, node.loc.start.line);
+        if (jsdoc) {
+          issues.push(...validateFunction(jsdoc, func.params, func, decl.id.name, filePath, node.loc.start.line));
+        }
+      }
+    },
+
+    ClassDeclaration(node) {
+      const className = node.id?.name || 'Anonymous';
+      for (const element of node.body.body) {
+        if (element.type !== 'MethodDefinition') continue;
+        const methodName = element.key.name || element.key.value;
+        if (!methodName || methodName === 'constructor') continue;
+        if (element.kind !== 'method') continue;
+
+        const funcNode = element.value;
+        const jsdoc = findJSDocBefore(comments, element.loc.start.line);
+        if (jsdoc) {
+          issues.push(...validateFunction(jsdoc, funcNode.params, funcNode, `${className}.${methodName}`, filePath, element.loc.start.line));
+        }
+      }
+    },
+  });
+
+  return issues;
+}
+
+/**
+ * Check JSDoc consistency across a directory
+ * @param {string} dir
+ * @returns {{ issues: JSDocIssue[], summary: { total: number, errors: number, warnings: number, byFile: Object } }}
+ */
+export function checkJSDocConsistency(dir) {
+  const resolvedDir = resolve(dir);
+  const files = findJSFiles(dir);
+  const allIssues = [];
+
+  for (const file of files) {
+    let content;
+    try {
+      content = readFileSync(file, 'utf-8');
+    } catch (e) {
+      continue; // File deleted between findJSFiles and read
+    }
+    const relPath = relative(resolvedDir, file);
+    const issues = checkJSDocFile(content, relPath);
+    allIssues.push(...issues);
+  }
+
+  const errors = allIssues.filter(i => i.severity === 'error').length;
+  const warnings = allIssues.filter(i => i.severity === 'warning').length;
+
+  const byFile = {};
+  for (const issue of allIssues) {
+    byFile[issue.file] = (byFile[issue.file] || 0) + 1;
+  }
+
+  return {
+    issues: allIssues,
+    summary: {
+      total: allIssues.length,
+      errors,
+      warnings,
+      byFile,
+    },
+  };
+}

package/src/jsdoc-generator.js

@@ -22,11 +22,9 @@ import { getWorkspaceRoot } from './workspace.js';
  * Generate JSDoc for a single file
  * @param {string} filePath - Absolute path to file
  * @param {Object} [options]
- * @param {boolean} [options.includeTests=true] - Include @test/@expect placeholders
  * @returns {JSDocTemplate[]}
  */
 export function generateJSDoc(filePath, options = {}) {
-  const includeTests = options.includeTests !== false;
   const results = [];
 
   const code = readFileSync(filePath, 'utf-8');
@@ -72,7 +70,6 @@ export function generateJSDoc(filePath, options = {}) {
         name: node.id.name,
         params: node.params,
         async: node.async,
-        includeTests,
       });
 
       results.push({
@@ -102,7 +99,6 @@ export function generateJSDoc(filePath, options = {}) {
             name: methodName,
             params: funcNode.params,
             async: funcNode.async,
-            includeTests,
           });
 
           results.push({
@@ -126,7 +122,6 @@ export function generateJSDoc(filePath, options = {}) {
  * @param {string} info.name
  * @param {Array} info.params
  * @param {boolean} info.async
- * @param {boolean} info.includeTests
  * @returns {string}
  */
 function buildJSDoc(info) {
@@ -145,12 +140,6 @@ function buildJSDoc(info) {
   // Return type
   lines.push(` * @returns {${info.async ? 'Promise<*>' : '*'}}`);
 
-  // Test annotations (Agentic Verification)
-  if (info.includeTests) {
-    lines.push(` * @test TODO: describe test scenario`);
-    lines.push(` * @expect TODO: expected result`);
-  }
-
   lines.push(' */');
   return lines.join('\n');
 }

package/src/large-files.js

@@ -54,6 +54,7 @@ function findJSFiles(dir, rootDir = dir) {
 /**
  * Analyze a single file
  * @param {string} filePath 
+ * @param {string} rootDir - Root directory for relative path calculation
  * @returns {LargeFileItem}
  */
 function analyzeFile(filePath, rootDir) {

package/src/mcp-server.js

@@ -21,11 +21,21 @@ import { getSimilarFunctions } from './similar-functions.js';
 import { getComplexity } from './complexity.js';
 import { getLargeFiles } from './large-files.js';
 import { getOutdatedPatterns } from './outdated-patterns.js';
-import { getFullAnalysis } from './full-analysis.js';
+import { getFullAnalysis, getAnalysisSummaryOnly } from './full-analysis.js';
 import { getCustomRules, setCustomRule, checkCustomRules } from './custom-rules.js';
 import { getFrameworkReference } from './framework-references.js';
 import { setRoots, resolvePath } from './workspace.js';
 import { getDBSchema, getTableUsage, getDBDeadTables } from './db-analysis.js';
+import { compressFile, editCompressed } from './compress.js';
+import { getProjectDocs, generateContextFiles, checkStaleness } from './doc-dialect.js';
+import { getGraph } from './tools.js';
+import { parseProject, discoverSubProjects } from './parser.js';
+import { getAiContext } from './ai-context.js';
+import { checkJSDocConsistency } from './jsdoc-checker.js';
+import { checkTypes } from './type-checker.js';
+import { compactProject, expandProject } from './compact.js';
+import { validateCtxContracts } from './ctx-to-jsdoc.js';
+import { getConfig, setConfig, getModeDescription, getModeWorkflow } from './mode-config.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -114,6 +124,105 @@ const TOOL_HANDLERS = {
   get_db_schema: (args) => getDBSchema(resolvePath(args.path)),
   get_table_usage: (args) => getTableUsage(resolvePath(args.path), args.table),
   get_db_dead_tables: (args) => getDBDeadTables(resolvePath(args.path)),
+
+  // AI Context
+  get_compressed_file: (args) => compressFile(resolvePath(args.path), {
+    beautify: args.beautify,
+    legend: args.legend,
+  }),
+  get_project_docs: async (args) => {
+    const projectPath = resolvePath(args.path);
+    const graph = await getGraph(projectPath);
+    const docs = getProjectDocs(graph, projectPath, { file: args.file });
+    // Lazy staleness check — wrapped in try-catch for projects with parse errors
+    try {
+      const parsed = await parseProject(projectPath);
+      const staleness = checkStaleness(projectPath, parsed);
+      return { docs, staleFiles: staleness.stale, freshCount: staleness.fresh };
+    } catch { return { docs }; }
+  },
+  generate_context_docs: async (args) => {
+    const projectPath = resolvePath(args.path);
+    const graph = await getGraph(projectPath);
+    const parsed = await parseProject(projectPath);
+    return generateContextFiles(graph, projectPath, parsed, {
+      overwrite: args.overwrite,
+      scope: args.scope,
+    });
+  },
+  check_stale_docs: async (args) => {
+    const projectPath = resolvePath(args.path);
+    const parsed = await parseProject(projectPath);
+    return checkStaleness(projectPath, parsed);
+  },
+  get_ai_context: async (args) => {
+    const projectPath = resolvePath(args.path);
+    const result = await getAiContext(projectPath, {
+      includeFiles: args.includeFiles,
+      includeDocs: args.includeDocs,
+      includeSkeleton: args.includeSkeleton,
+    });
+    // Add staleness info
+    try {
+      const parsed = await parseProject(projectPath);
+      const staleness = checkStaleness(projectPath, parsed);
+      result.staleFiles = staleness.stale;
+    } catch { /* parse error — skip staleness */ }
+    return result;
+  },
+
+  // JSDoc Consistency
+  check_jsdoc_consistency: (args) => {
+    return checkJSDocConsistency(resolvePath(args.path));
+  },
+
+  // Type Checker (optional tsc)
+  check_types: async (args) => {
+    return checkTypes(resolvePath(args.path), {
+      files: args.files,
+      maxDiagnostics: args.maxDiagnostics,
+    });
+  },
+
+  // Monorepo & Performance
+  discover_sub_projects: (args) => {
+    return discoverSubProjects(resolvePath(args.path));
+  },
+  get_analysis_summary: (args) => {
+    return getAnalysisSummaryOnly(resolvePath(args.path));
+  },
+  compact_project: (args) => {
+    return compactProject(resolvePath(args.path), { dryRun: args.dryRun || false });
+  },
+  beautify_project: (args) => {
+    return expandProject(resolvePath(args.path), { dryRun: args.dryRun || false });
+  },
+  validate_ctx_contracts: (args) => {
+    return validateCtxContracts(resolvePath(args.path), { strict: args.strict || false });
+  },
+  edit_compressed: (args) => {
+    return editCompressed(resolvePath(args.path), args.symbol, args.code, {
+      beautify: args.beautify !== false,
+      dryRun: args.dryRun || false,
+    });
+  },
+  get_mode: (args) => {
+    const dir = resolvePath(args.path);
+    const config = getConfig(dir);
+    return {
+      ...config,
+      description: getModeDescription(config.mode),
+      workflow: getModeWorkflow(config.mode),
+    };
+  },
+  set_mode: (args) => {
+    const dir = resolvePath(args.path);
+    const updates = { mode: args.mode };
+    if (args.beautify !== undefined) updates.beautify = args.beautify;
+    if (args.autoValidate !== undefined) updates.autoValidate = args.autoValidate;
+    if (args.stripJSDoc !== undefined) updates.stripJSDoc = args.stripJSDoc;
+    return setConfig(dir, updates);
+  },
 };
 
 /**
@@ -136,6 +245,10 @@ const RESPONSE_HINTS = {
       hints.push('💡 Large class detected. Run get_complexity() to find refactoring targets.');
     }
     hints.push('💡 Use deps() to see what depends on this symbol.');
+    // Nudge: document if no .ctx exists
+    if (result.file) {
+      hints.push(`📝 No .ctx for ${result.file}? Run generate_context_docs({ scope: ["${result.file}"] }) to create documentation.`);
+    }
     return hints;
   },
 
@@ -205,6 +318,100 @@ const RESPONSE_HINTS = {
   get_db_dead_tables: () => [
     '💡 Dead columns detection is best-effort — verify before removing.',
   ],
+
+  get_compressed_file: (result) => {
+    const hints = [`💡 Saved ${result.savings} tokens (${result.original} → ${result.compressed}).`];
+    hints.push('💡 Use get_ai_context() for full project boot: skeleton + docs + compressed files.');
+    if (result.file) {
+      hints.push(`📝 Working on ${result.file}? Run generate_context_docs({ scope: ["${result.file}"] }) to document it.`);
+    }
+    return hints;
+  },
+
+  get_project_docs: (result) => {
+    const hints = [
+      '💡 Enrich docs by editing .context/*.ctx files — they are git-tracked.',
+      '💡 Use generate_context_docs() to create initial .ctx stubs.',
+    ];
+    if (result.staleFiles?.length > 0) {
+      hints.push(`⚠️ ${result.staleFiles.length} .ctx files are STALE: ${result.staleFiles.slice(0, 5).join(', ')}. Run generate_context_docs({ scope: ${JSON.stringify(result.staleFiles)}, overwrite: true }) to update (descriptions will be preserved).`);
+    }
+    return hints;
+  },
+
+  check_stale_docs: (result) => {
+    const hints = [];
+    if (result.stale?.length > 0) {
+      hints.push(`⚠️ ${result.stale.length} stale: ${result.stale.join(', ')}`);
+      hints.push(`💡 Run generate_context_docs({ scope: ${JSON.stringify(result.stale)}, overwrite: true }) — existing descriptions will be preserved.`);
+    } else {
+      hints.push('✅ All .ctx docs are up to date.');
+    }
+    if (result.unknown > 0) {
+      hints.push(`ℹ️ ${result.unknown} .ctx files without @sig header (pre-staleness format).`);
+    }
+    return hints;
+  },
+
+  generate_context_docs: (result) => {
+    const hints = [];
+    if (result.created?.length > 0) {
+      hints.push(`✅ Created ${result.created.length} .ctx files with @sig hashes.`);
+    }
+    if (result.skipped?.length > 0) {
+      hints.push(`ℹ️ Skipped ${result.skipped.length} existing files. Use overwrite=true to regenerate (descriptions are preserved via merge).`);
+    }
+    if (result.templates && Object.keys(result.templates).length > 0) {
+      hints.push(`📝 .ctx files have {DESCRIBE} markers. To enrich automatically:`);
+      hints.push(`   delegate_task({ prompt: "Enrich .context/*.ctx files — replace {DESCRIBE} with compact descriptions", skill: "doc-enricher" })`);
+      hints.push(`   Or enrich manually: read source files and replace {DESCRIBE} markers with pipe-separated descriptions (max 80 chars).`);
+    }
+    return hints;
+  },
+
+  get_ai_context: (result) => {
+    const hints = [`💡 Context loaded: ${result.totalTokens} tokens (${result.savings} savings vs ${result.vsOriginal} original).`];
+    hints.push('💡 Use expand() to drill into specific symbols. Use get_compressed_file() for additional files.');
+    if (result.staleFiles?.length > 0) {
+      hints.push(`⚠️ ${result.staleFiles.length} .ctx docs are stale. Run generate_context_docs({ scope: ${JSON.stringify(result.staleFiles)}, overwrite: true }) then delegate_task({ skill: "doc-enricher" }) to update.`);
+    }
+    return hints;
+  },
+
+  validate_ctx_contracts: (result) => {
+    const hints = [];
+    if (result.summary?.errors > 0) {
+      hints.push(`⚠️ ${result.summary.errors} contract violations found. Run generate_context_docs({ overwrite: true }) to regenerate .ctx files.`);
+    } else {
+      hints.push('✅ All .ctx contracts valid — documentation matches source.');
+    }
+    return hints;
+  },
+
+  edit_compressed: (result) => {
+    const hints = [];
+    if (result.success) {
+      hints.push(`✅ Symbol "${result.symbol}" replaced in ${result.file}.`);
+      hints.push('💡 Run invalidate_cache() to refresh the graph after editing.');
+      hints.push('💡 Run validate_ctx_contracts() to check if .ctx docs need updating.');
+    }
+    return hints;
+  },
+
+  get_mode: (result) => {
+    const hints = [`📋 Current mode: ${result.mode} — ${result.description}`];
+    if (result.mode === 2) {
+      hints.push('💡 Workflow: get_compressed_file() → read → edit_compressed() → write.');
+    }
+    return hints;
+  },
+
+  set_mode: (result) => {
+    if (result.saved) {
+      return [`✅ Mode set to ${result.config.mode}. Saved to ${result.path}.`];
+    }
+    return [];
+  },
 };
 
 /**