project-graph-mcp 1.3.0 → 1.5.0

package/src/tool-defs.js

@@ -98,7 +98,7 @@ export const TOOLS = [
   // Test Checklist Tools
   {
     name: 'get_pending_tests',
-    description: 'Get list of pending browser tests from @test/@expect annotations.',
+    description: 'Get list of pending tests from ## Tests sections in .ctx.md files.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -269,7 +269,7 @@ export const TOOLS = [
         level: {
           type: 'string',
           enum: ['tests', 'params', 'all'],
-          description: 'Strictness: tests (default) = @test/@expect, params = +@param/@returns, all = +description',
+          description: 'Strictness: tests (default) = .ctx.md checklists, params = +@param/@returns, all = +description',
         },
       },
       required: ['path'],
@@ -522,4 +522,272 @@ export const TOOLS = [
       required: ['path'],
     },
   },
+
+  // AI Context Tools
+  {
+    name: 'get_compressed_file',
+    description: 'Get AI-optimized compressed version of a JS source file. Terser-minified with export legend. Saves 20-55% tokens (more with heavy JSDoc).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Path to JS/MJS file',
+        },
+        beautify: {
+          type: 'boolean',
+          description: 'Readable multi-line output (default: true). Set false for maximum compression.',
+        },
+        legend: {
+          type: 'boolean',
+          description: 'Include compact export legend header (default: true)',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'get_project_docs',
+    description: 'Get compact project documentation in doc-dialect format. Returns architecture, patterns, edge cases. Merges auto-generated docs with manual .context/ files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Project root path',
+        },
+        file: {
+          type: 'string',
+          description: 'Optional: get docs for a specific file only',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'generate_context_docs',
+    description: 'Generate .context/ doc-dialect files from AST. Creates rich templates with {DESCRIBE} markers. Use agent-pool with doc-enricher skill to auto-fill descriptions. Templates include function signatures, call graphs, and DB access patterns extracted from AST.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Project root path',
+        },
+        overwrite: {
+          type: 'boolean',
+          description: 'Overwrite existing .ctx files (default: false). Existing descriptions are preserved via merge.',
+        },
+        scope: {
+          description: 'Scope filter: "all" (default), "focus" (git diff — recently changed files only), or array of specific file paths.',
+          oneOf: [
+            { type: 'string', enum: ['all', 'focus'] },
+            { type: 'array', items: { type: 'string' } },
+          ],
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'check_stale_docs',
+    description: 'Check which .ctx documentation files are outdated. Compares AST signature hashes to detect structural changes (new functions, renamed exports). Use for CI/CD doc health audits.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Project root path',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'get_ai_context',
+    description: 'Boot AI agent context: skeleton + doc-dialect + optional compressed files in one call. Call FIRST when starting work on a new project. Returns totalTokens and savings vs reading raw source.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Project root path',
+        },
+        includeFiles: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Specific files to include compressed (e.g., ["parser.js", "tools.js"])',
+        },
+        includeDocs: {
+          type: 'boolean',
+          description: 'Include doc-dialect documentation (default: true)',
+        },
+        includeSkeleton: {
+          type: 'boolean',
+          description: 'Include project skeleton (default: true)',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  // JSDoc Consistency
+  {
+    name: 'check_jsdoc_consistency',
+    description: 'Validate JSDoc annotations against actual function signatures. Finds param count/name mismatches, missing @returns, type inconsistencies.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Path to scan (e.g., "src/")',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  // Type Checker (optional tsc)
+  {
+    name: 'check_types',
+    description: 'Run TypeScript type checking on JS files with JSDoc types. Requires tsc in PATH (npm i -g typescript). Returns structured diagnostics or graceful fallback if tsc not available.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Directory to check',
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Specific files to check (optional)',
+        },
+        maxDiagnostics: {
+          type: 'number',
+          description: 'Max diagnostics to return (default: 50)',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  // Monorepo & Performance Tools
+  {
+    name: 'discover_sub_projects',
+    description: 'Find sub-projects in a monorepo. Scans packages/, apps/, services/, modules/, libs/, plugins/ for package.json.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Root path to scan for sub-projects',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'get_analysis_summary',
+    description: 'Quick health score — runs only cached per-file metrics (complexity, undocumented, JSDoc). Much faster than get_full_analysis for large codebases.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Path to scan',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'compact_project',
+    description: 'Compact all JS files in a directory — strips comments, whitespace, dead code. Preserves all names (mangle: false). Use with .ctx docs for AI-first workflow. Irreversible without git — use --dry-run first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Directory to compact (e.g., "src/")',
+        },
+        dryRun: {
+          type: 'boolean',
+          description: 'Preview savings without modifying files (default: false)',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'beautify_project',
+    description: 'Beautify/expand all JS files in a directory — formats with proper indentation. Inverse of compact_project. Preserves all names.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Directory to beautify (e.g., "src/")',
+        },
+        dryRun: {
+          type: 'boolean',
+          description: 'Preview without modifying files (default: false)',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'validate_ctx_contracts',
+    description: 'Validate .ctx contracts against actual source code AST. Checks param count/names, export status, and reports mismatches. Zero-dependency alternative to tsc.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Project root path' },
+        strict: { type: 'boolean', description: 'Also report functions missing from .ctx (default: false)' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'edit_compressed',
+    description: 'Edit a function or class in source code by symbol name. Agent sends new code (compressed or formatted); server finds the symbol via AST, replaces it, validates syntax, and optionally beautifies. Use with get_compressed_file for token-efficient editing workflow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to JS/MJS file' },
+        symbol: { type: 'string', description: 'Function or class name to replace' },
+        code: { type: 'string', description: 'New code for the symbol (full function/class definition)' },
+        beautify: { type: 'boolean', description: 'Beautify result after editing (default: true)' },
+        dryRun: { type: 'boolean', description: 'Preview without writing (default: false)' },
+      },
+      required: ['path', 'symbol', 'code'],
+    },
+  },
+  {
+    name: 'get_mode',
+    description: 'Get current compact code mode configuration. Returns mode (1=compact, 2=full, 3=IDE), preferences, and recommended workflow for agent.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Project root path' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'set_mode',
+    description: 'Set compact code mode for a project. Mode 1: store minified, edit directly. Mode 2: store full, use get_compressed_file + edit_compressed. Mode 3: IDE integration (future).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Project root path' },
+        mode: { type: 'number', description: 'Mode number: 1, 2, or 3' },
+        beautify: { type: 'boolean', description: 'Beautify code after edits (default: true)' },
+        autoValidate: { type: 'boolean', description: 'Auto-run .ctx validation after edits (default: false)' },
+        stripJSDoc: { type: 'boolean', description: 'Auto-strip JSDoc when compacting (default: false)' },
+      },
+      required: ['path', 'mode'],
+    },
+  },
 ];

package/src/tools.js

@@ -81,7 +81,7 @@ function loadDiskCache(path) {
  * @param {string} path 
  * @returns {Promise<import('./graph-builder.js').Graph>}
  */
-async function getGraph(path) {
+export async function getGraph(path) {
   // Different path = full rebuild
   if (cachedGraph && cachedPath === path) {
     // Check for file changes via mtime

package/src/type-checker.js

@@ -0,0 +1,188 @@
+/**
+ * Optional Type Checker (tsc wrapper)
+ * Provides JSDoc type validation via TypeScript compiler
+ * 
+ * Requires `tsc` in PATH (npm i -g typescript)
+ * Graceful fallback if not available
+ */
+
+import { execSync, spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve, join } from 'path';
+
+/**
+ * @typedef {Object} TypeDiagnostic
+ * @property {string} file
+ * @property {number} line
+ * @property {number} column
+ * @property {'error'|'warning'} severity
+ * @property {string} message
+ * @property {string} code - TS error code (e.g. "TS2345")
+ */
+
+/**
+ * Check if tsc is available
+ * @returns {{ available: boolean, version: string|null, path: string|null }}
+ */
+function detectTsc() {
+  try {
+    const version = execSync('tsc --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    const tscPath = execSync('which tsc', { encoding: 'utf-8', timeout: 5000 }).trim();
+    return { available: true, version, path: tscPath };
+  } catch (e) {
+    // Try npx
+    try {
+      const version = execSync('npx tsc --version', { encoding: 'utf-8', timeout: 15000 }).trim();
+      return { available: true, version, path: 'npx tsc' };
+    } catch (e2) {
+      return { available: false, version: null, path: null };
+    }
+  }
+}
+
+/**
+ * Parse tsc output line into structured diagnostic
+ * @param {string} line
+ * @param {string} baseDir
+ * @returns {TypeDiagnostic|null}
+ */
+function parseDiagnosticLine(line, baseDir) {
+  // Format: file.js(line,col): error TS1234: message
+  const match = line.match(/^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.+)$/);
+  if (!match) return null;
+
+  return {
+    file: match[1],
+    line: parseInt(match[2]),
+    column: parseInt(match[3]),
+    severity: match[4],
+    message: match[6],
+    code: match[5],
+  };
+}
+
+/**
+ * Build tsc arguments
+ * @param {string} dir
+ * @param {Object} options
+ * @returns {string[]}
+ */
+function buildArgs(dir, options = {}) {
+  const args = ['--noEmit'];
+
+  // Check for existing config
+  const tsconfig = join(dir, 'tsconfig.json');
+  const jsconfig = join(dir, 'jsconfig.json');
+
+  if (existsSync(tsconfig)) {
+    args.push('--project', tsconfig);
+  } else if (existsSync(jsconfig)) {
+    args.push('--project', jsconfig);
+  } else {
+    // No config — use sensible defaults for JS projects
+    args.push('--allowJs', '--checkJs');
+    args.push('--target', 'ESNext');
+    args.push('--module', 'NodeNext');
+    args.push('--moduleResolution', 'NodeNext');
+    args.push('--skipLibCheck');
+
+    // Include the directory
+    if (options.files?.length) {
+      args.push(...options.files);
+    } else {
+      args.push('--rootDir', dir);
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Run type checking on a directory
+ * @param {string} dir - Directory to check
+ * @param {Object} [options]
+ * @param {string[]} [options.files] - Specific files to check
+ * @param {number} [options.maxDiagnostics=50] - Max diagnostics to return
+ * @returns {Promise<{ available: boolean, version: string|null, diagnostics: TypeDiagnostic[], summary: Object, hint: string|null }>}
+ */
+export async function checkTypes(dir, options = {}) {
+  const maxDiagnostics = options.maxDiagnostics || 50;
+  const resolvedDir = resolve(dir);
+
+  // Detect tsc
+  const tsc = detectTsc();
+  if (!tsc.available) {
+    return {
+      available: false,
+      version: null,
+      diagnostics: [],
+      summary: { total: 0, errors: 0, warnings: 0 },
+      hint: 'TypeScript not found. Install: npm i -g typescript',
+    };
+  }
+
+  // Build and run command
+  const args = buildArgs(resolvedDir, options);
+  const cmd = tsc.path.includes('npx') ? 'npx' : 'tsc';
+  const cmdArgs = tsc.path.includes('npx') ? ['tsc', ...args] : args;
+
+  const result = await new Promise((res) => {
+    const child = spawn(cmd, cmdArgs, {
+      cwd: resolvedDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      res({ stdout, stderr, killed: true });
+    }, 60000);
+
+    child.on('close', () => {
+      clearTimeout(timer);
+      res({ stdout, stderr, killed: false });
+    });
+
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      res({ stdout: '', stderr: e.message, killed: false });
+    });
+  });
+
+  // Parse output (tsc exits with 1 on errors, stdout has diagnostics)
+  const output = (result.stdout || '') + (result.stderr || '');
+  const lines = output.split('\n').filter(l => l.trim());
+
+  const diagnostics = [];
+  for (const line of lines) {
+    const diag = parseDiagnosticLine(line, resolvedDir);
+    if (diag && diagnostics.length < maxDiagnostics) {
+      diagnostics.push(diag);
+    }
+  }
+
+  const errors = diagnostics.filter(d => d.severity === 'error').length;
+  const warnings = diagnostics.filter(d => d.severity === 'warning').length;
+
+  const byFile = {};
+  for (const d of diagnostics) {
+    byFile[d.file] = (byFile[d.file] || 0) + 1;
+  }
+
+  return {
+    available: true,
+    version: tsc.version,
+    diagnostics,
+    summary: {
+      total: diagnostics.length,
+      errors,
+      warnings,
+      byFile,
+    },
+    hint: null,
+  };
+}

package/src/undocumented.js

@@ -74,8 +74,8 @@ function extractComments(code) {
 
 /**
  * Find JSDoc comment before a target line
- * @param {Array<{text: string, endLine: number}>} comments 
- * @param {number} targetLine 
+ * @param {Array<{text: string, endLine: number}>} comments - Extracted JSDoc comments
+ * @param {number} targetLine - Line number to search before
  * @returns {string|null}
  */
 function findJSDocBefore(comments, targetLine) {
@@ -100,15 +100,9 @@ function checkMissing(jsdoc, level) {
   if (!jsdoc) {
     if (level === 'all') missing.push('description');
     if (level === 'params' || level === 'all') missing.push('@param', '@returns');
-    if (level === 'tests' || level === 'params' || level === 'all') missing.push('@test', '@expect');
     return missing;
   }
 
-  if (level === 'tests' || level === 'params' || level === 'all') {
-    if (!jsdoc.includes('@test')) missing.push('@test');
-    if (!jsdoc.includes('@expect')) missing.push('@expect');
-  }
-
   if (level === 'params' || level === 'all') {
     if (!jsdoc.includes('@param')) missing.push('@param');
     if (!jsdoc.includes('@returns') && !jsdoc.includes('@return')) missing.push('@returns');
@@ -124,13 +118,13 @@ const SKIP_METHODS = [
 ];
 
 /**
- * Parse file using AST and find undocumented items
+ * Parse file using AST and find undocumented items (per-file export for cache integration)
  * @param {string} code 
  * @param {string} filePath 
  * @param {'tests'|'params'|'all'} level
  * @returns {UndocumentedItem[]}
  */
-function parseFile(code, filePath, level) {
+export function checkUndocumentedFile(code, filePath, level) {
   const results = [];
 
   let ast;
@@ -223,8 +217,13 @@ export function getUndocumented(dir, level = 'tests') {
   const results = [];
 
   for (const file of files) {
-    const content = readFileSync(file, 'utf-8');
-    const items = parseFile(content, relative(resolvedDir, file), level);
+    let content;
+    try {
+      content = readFileSync(file, 'utf-8');
+    } catch (e) {
+      continue; // File deleted between findJSFiles and read
+    }
+    const items = checkUndocumentedFile(content, relative(resolvedDir, file), level);
     results.push(...items);
   }
 

package/src/workspace.js

@@ -51,7 +51,7 @@ export function getWorkspaceRoot() {
  * Resolve a path argument against workspace root.
  * Absolute paths are returned as-is.
  * Relative paths are resolved against the workspace root.
- * @param {string} path
+ * @param {string} inputPath
  * @returns {string}
  */
 export function resolvePath(inputPath) {