project-graph-mcp 1.0.1 → 1.2.0

package/src/lang-typescript.js

@@ -0,0 +1,190 @@
+import { stripStringsAndComments } from './lang-utils.js';
+
+/**
+ * TypeScript/TSX regex-based parser.
+ * Extracts structural information (classes, functions, imports, exports, calls)
+ * directly from TypeScript code without relying on Acorn.
+ *
+ * Strategy: Instead of stripping TS syntax to feed Acorn (which causes
+ * catastrophic backtracking in regex), parse structural elements directly
+ * — same approach as lang-python.js and lang-go.js.
+ *
+ * @param {string} code - TypeScript source code
+ * @param {string} filename - File path for the result
+ * @returns {ParseResult}
+ */
+export function parseTypeScript(code, filename) {
+  const result = {
+    file: filename,
+    classes: [],
+    functions: [],
+    imports: [],
+    exports: [],
+  };
+
+  // Strip strings, template literals, and comments to avoid false matches
+  const cleaned = stripStringsAndComments(code);
+  const lines = cleaned.split('\n');
+
+  let currentClass = null;
+  let currentFunc = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    // --- Imports ---
+    // import { A, B } from 'module'
+    const importFromMatch = line.match(/^\s*import\s+(?:type\s+)?(?:\{([^}]+)\}|(\w+))\s+from\s/);
+    if (importFromMatch) {
+      if (importFromMatch[1]) {
+        importFromMatch[1].split(',').forEach(s => {
+          const name = s.trim().replace(/\s+as\s+\w+/, '').replace(/^type\s+/, '');
+          if (name) result.imports.push(name);
+        });
+      } else if (importFromMatch[2]) {
+        result.imports.push(importFromMatch[2]);
+      }
+      continue;
+    }
+    // import * as name from 'module'
+    const importStarMatch = line.match(/^\s*import\s+\*\s+as\s+(\w+)\s+from\s/);
+    if (importStarMatch) {
+      result.imports.push(importStarMatch[1]);
+      continue;
+    }
+
+    // --- Exports ---
+    const exportMatch = line.match(/^\s*export\s+(?:default\s+)?(?:class|function|const|let|var|type|interface|enum|abstract)\s+(\w+)/);
+    if (exportMatch) {
+      result.exports.push(exportMatch[1]);
+    }
+    // export { A, B }
+    const exportBraceMatch = line.match(/^\s*export\s+\{([^}]+)\}/);
+    if (exportBraceMatch) {
+      exportBraceMatch[1].split(',').forEach(s => {
+        const name = s.trim().replace(/\s+as\s+\w+/, '');
+        if (name) result.exports.push(name);
+      });
+    }
+
+    // Skip type-only declarations (no runtime code)
+    if (/^\s*(type|interface)\s+\w+/.test(line)) {
+      continue;
+    }
+
+    // --- Classes ---
+    const classMatch = line.match(/^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?/);
+    if (classMatch) {
+      currentClass = {
+        name: classMatch[1],
+        extends: classMatch[2] || null,
+        methods: [],
+        properties: [],
+        calls: [],
+        file: filename,
+        line: lineNum,
+      };
+      result.classes.push(currentClass);
+      currentFunc = null;
+      continue;
+    }
+
+    // Detect end of class or function (closing brace at col 0)
+    if (/^}/.test(line)) {
+      currentClass = null;
+      currentFunc = null;
+      continue;
+    }
+
+    // --- Methods (inside class) ---
+    if (currentClass) {
+      // public/private/protected/static/async methodName(
+      const methodMatch = line.match(/^\s+(?:(?:public|private|protected|static|readonly|abstract|override|async)\s+)*(\w+)\s*(?:<[^>]*>)?\s*\(/);
+      if (methodMatch && methodMatch[1] !== 'if' && methodMatch[1] !== 'for' &&
+          methodMatch[1] !== 'while' && methodMatch[1] !== 'switch' &&
+          methodMatch[1] !== 'catch' && methodMatch[1] !== 'return' &&
+          methodMatch[1] !== 'new' && methodMatch[1] !== 'constructor' &&
+          methodMatch[1] !== 'super') {
+        currentClass.methods.push(methodMatch[1]);
+      }
+      // constructor
+      if (/^\s+constructor\s*\(/.test(line)) {
+        currentClass.methods.push('constructor');
+      }
+      // Property: name: Type or name = value
+      const propMatch = line.match(/^\s+(?:(?:public|private|protected|static|readonly|declare|override|abstract)\s+)*(\w+)\s*[?!]?\s*[:=]/);
+      if (propMatch && !methodMatch && propMatch[1] !== 'if' && propMatch[1] !== 'const' &&
+          propMatch[1] !== 'let' && propMatch[1] !== 'var' && propMatch[1] !== 'return') {
+        currentClass.properties.push(propMatch[1]);
+      }
+    }
+
+    // --- Functions (top-level) ---
+    if (!currentClass) {
+      // function name(, async function name(, export function, export default function
+      const fnMatch = line.match(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+(\w+)/);
+      if (fnMatch) {
+        currentFunc = {
+          name: fnMatch[1],
+          exported: /^\s*export\s+/.test(line),
+          calls: [],
+          params: extractParams(line),
+          file: filename,
+          line: lineNum,
+        };
+        result.functions.push(currentFunc);
+        continue;
+      }
+      // Arrow functions: const name = (...) => or export const name = (
+      const arrowMatch = line.match(/^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_]\w*)\s*(?::\s*\w+(?:<[^>]*>)?)?\s*=>/);
+      if (arrowMatch) {
+        currentFunc = {
+          name: arrowMatch[1],
+          exported: /^\s*export\s+/.test(line),
+          calls: [],
+          params: extractParams(line),
+          file: filename,
+          line: lineNum,
+        };
+        result.functions.push(currentFunc);
+        continue;
+      }
+    }
+
+    // --- Calls ---
+    const callRegex = /\b([a-zA-Z_$]\w*)\s*(?:<[^>]*>)?\s*\(/g;
+    let callMatch;
+    while ((callMatch = callRegex.exec(line)) !== null) {
+      const name = callMatch[1];
+      // Skip keywords and common built-ins
+      if (['if', 'for', 'while', 'switch', 'catch', 'return', 'new', 'throw',
+           'typeof', 'delete', 'void', 'import', 'export', 'class', 'function',
+           'const', 'let', 'var', 'async', 'await', 'super', 'this',
+           'interface', 'type', 'enum', 'declare', 'abstract'].includes(name)) {
+        continue;
+      }
+      if (currentClass) {
+        currentClass.calls.push(name);
+      } else if (currentFunc) {
+        currentFunc.calls.push(name);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract parameter names from a function signature line.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function extractParams(line) {
+  const match = line.match(/\(([^)]*)\)/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map(p => p.trim().replace(/[?!]?\s*:.*$/, '').replace(/\s*=.*$/, '').trim())
+    .filter(p => p && !p.startsWith('...'));
+}

package/src/lang-utils.js

@@ -0,0 +1,124 @@
+/**
+ * Strip strings, template literals, and comments from source code.
+ * Preserves line structure (newlines are kept) and character positions.
+ * @param {string} code
+ * @param {Object} [options]
+ * @param {boolean} [options.singleQuote=true] - Handle single-quoted strings
+ * @param {boolean} [options.backtick=true] - Handle backtick strings/templates
+ * @param {boolean} [options.hashComment=false] - Handle # comments (Python)
+ * @param {boolean} [options.tripleQuote=false] - Handle ''' and """ (Python)
+ * @param {boolean} [options.templateInterpolation=true] - Handle ${} in backticks
+ * @returns {string}
+ */
+export function stripStringsAndComments(code, options = {}) {
+  const {
+    singleQuote = true,
+    backtick = true,
+    hashComment = false,
+    tripleQuote = false,
+    templateInterpolation = true
+  } = options;
+
+  let result = '';
+  let i = 0;
+
+  while (i < code.length) {
+    // Hash comment
+    if (hashComment && code[i] === '#') {
+      while (i < code.length && code[i] !== '\n') {
+        result += ' ';
+        i++;
+      }
+      continue;
+    }
+
+    // Triple quotes
+    if (tripleQuote && (
+      (code[i] === "'" && code[i+1] === "'" && code[i+2] === "'") ||
+      (code[i] === '"' && code[i+1] === '"' && code[i+2] === '"')
+    )) {
+      const quote = code[i];
+      result += '   ';
+      i += 3;
+      while (i < code.length) {
+        if (code[i] === '\\') {
+          result += '  ';
+          i += 2;
+          continue;
+        }
+        if (code[i] === quote && code[i+1] === quote && code[i+2] === quote) {
+          result += '   ';
+          i += 3;
+          break;
+        }
+        result += code[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      continue;
+    }
+
+    // Single-line comment //
+    if (!hashComment && code[i] === '/' && code[i + 1] === '/') {
+      while (i < code.length && code[i] !== '\n') {
+        result += ' ';
+        i++;
+      }
+      continue;
+    }
+
+    // Multi-line comment /* ... */
+    if (!hashComment && code[i] === '/' && code[i + 1] === '*') {
+      i += 2;
+      result += '  ';
+      while (i < code.length && !(code[i] === '*' && code[i + 1] === '/')) {
+        result += code[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      if (i < code.length) { result += '  '; i += 2; }
+      continue;
+    }
+
+    // String literals
+    if (code[i] === '"' || (singleQuote && code[i] === "'") || (backtick && code[i] === '`')) {
+      const quote = code[i];
+      result += ' ';
+      i++;
+      while (i < code.length) {
+        if (code[i] === '\\') {
+          result += '  ';
+          i += 2;
+          continue;
+        }
+        if (code[i] === quote) {
+          result += ' ';
+          i++;
+          break;
+        }
+        // Template literal: ${...} — keep the expression
+        if (templateInterpolation && quote === '`' && code[i] === '$' && code[i + 1] === '{') {
+          result += '${';
+          i += 2;
+          let depth = 1;
+          while (i < code.length && depth > 0) {
+            if (code[i] === '{') depth++;
+            if (code[i] === '}') depth--;
+            if (depth > 0) {
+              result += code[i] === '\n' ? '\n' : code[i];
+            } else {
+              result += '}';
+            }
+            i++;
+          }
+          continue;
+        }
+        result += code[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      continue;
+    }
+    result += code[i];
+    i++;
+  }
+
+  return result;
+}

package/src/mcp-server.js

@@ -6,8 +6,11 @@
  * - Sends server→client requests (roots/list) to get workspace info
  */
 
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
 import { TOOLS } from './tool-defs.js';
-import { getSkeleton, getFocusZone, expand, deps, usages, invalidateCache } from './tools.js';
+import { getSkeleton, getFocusZone, expand, deps, usages, invalidateCache, getCallChain } from './tools.js';
 import { getPendingTests, markTestPassed, markTestFailed, getTestSummary, resetTestState } from './test-annotations.js';
 import { getFilters, setFilters, addExcludes, removeExcludes, resetFilters } from './filters.js';
 import { getInstructions } from './instructions.js';
@@ -23,6 +26,8 @@ import { getCustomRules, setCustomRule, checkCustomRules } from './custom-rules.
 import { getFrameworkReference } from './framework-references.js';
 import { setRoots, resolvePath } from './workspace.js';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
 /**
  * Tool handlers registry
  * Maps tool names to their handler functions
@@ -34,6 +39,7 @@ const TOOL_HANDLERS = {
   expand: (args) => expand(args.symbol),
   deps: (args) => deps(args.symbol),
   usages: (args) => usages(args.symbol),
+  get_call_chain: (args) => getCallChain({ from: args.from, to: args.to, path: args.path ? resolvePath(args.path) : undefined }),
   invalidate_cache: () => { invalidateCache(); return { success: true }; },
 
   // Test Checklist Tools
@@ -51,6 +57,22 @@ const TOOL_HANDLERS = {
   reset_filters: () => resetFilters(),
 
   // Guidelines
+  get_usage_guide: (args) => {
+    try {
+      const guidePath = path.join(__dirname, '..', 'GUIDE.md');
+      const content = fs.readFileSync(guidePath, 'utf8');
+      if (!args.topic) return content;
+      const regex = new RegExp(`## ${args.topic}`, 'i');
+      const match = content.match(regex);
+      if (!match) return `Topic '${args.topic}' not found in guide.`;
+      const start = match.index;
+      let end = content.indexOf('\n## ', start + 1);
+      if (end === -1) end = content.length;
+      return content.substring(start, end).trim();
+    } catch (e) {
+      return `Failed to read usage guide: ${e.message}`;
+    }
+  },
   get_agent_instructions: () => getInstructions(),
 
   // Documentation
@@ -115,6 +137,13 @@ const RESPONSE_HINTS = {
     '💡 Use usages() for cross-project reference search.',
   ],
 
+  get_call_chain: (result) => {
+    if (result.error) return [];
+    return [
+      '💡 Use expand() on intermediate steps to understand how data is passed along the chain.',
+    ];
+  },
+
   invalidate_cache: () => [
     '✅ Cache cleared. Run get_skeleton() to rebuild the project graph.',
   ],
@@ -212,11 +241,47 @@ export function createServer(sendToClient) {
               id,
               result: {
                 protocolVersion: '2024-11-05',
-                capabilities: { tools: {} },
+                capabilities: { tools: {}, resources: {} },
                 serverInfo: { name: 'project-graph', version: '1.1.0' },
               },
             };
 
+          case 'resources/list':
+            return {
+              jsonrpc: '2.0',
+              id,
+              result: {
+                resources: [
+                  {
+                    uri: 'project-graph://guide',
+                    name: 'Project Graph Usage Guide',
+                    description: 'Comprehensive guide with workflows and examples',
+                    mimeType: 'text/markdown',
+                  },
+                ],
+              },
+            };
+
+          case 'resources/read': {
+            if (params.uri !== 'project-graph://guide') {
+              return { jsonrpc: '2.0', id, error: { code: -32602, message: `Resource not found: ${params.uri}` } };
+            }
+            const content = fs.readFileSync(path.join(__dirname, '..', 'GUIDE.md'), 'utf8');
+            return {
+              jsonrpc: '2.0',
+              id,
+              result: {
+                contents: [
+                  {
+                    uri: 'project-graph://guide',
+                    mimeType: 'text/markdown',
+                    text: content,
+                  },
+                ],
+              },
+            };
+          }
+
           case 'tools/list':
             return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
 

package/src/parser.js

@@ -8,6 +8,12 @@ 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';
+import { parseTypeScript } from './lang-typescript.js';
+import { parsePython } from './lang-python.js';
+import { parseGo } from './lang-go.js';
+
+/** Supported source file extensions */
+const SOURCE_EXTENSIONS = ['.js', '.ts', '.tsx', '.py', '.go'];
 
 /**
  * @typedef {Object} ClassInfo
@@ -239,7 +245,7 @@ export async function parseProject(dir) {
   for (const file of files) {
     const content = readFileSync(file, 'utf-8');
     const relPath = relative(resolvedDir, file);
-    const parsed = await parseFile(content, relPath);
+    const parsed = await parseFileByExtension(content, relPath);
 
     result.files.push(relPath);
     result.classes.push(...parsed.classes);
@@ -255,13 +261,46 @@ export async function parseProject(dir) {
   return result;
 }
 
+/**
+ * Route file to appropriate parser based on extension.
+ * @param {string} code
+ * @param {string} filename
+ * @returns {Promise<ParseResult>}
+ */
+async function parseFileByExtension(code, filename) {
+  if (filename.endsWith('.py')) {
+    return parsePython(code, filename);
+  }
+  if (filename.endsWith('.go')) {
+    return parseGo(code, filename);
+  }
+  if (filename.endsWith('.ts') || filename.endsWith('.tsx')) {
+    return parseTypeScript(code, filename);
+  }
+  // Default: JS via Acorn
+  return parseFile(code, filename);
+}
+
+/**
+ * Check if file is a supported source file.
+ * @param {string} filename
+ * @returns {boolean}
+ */
+function isSourceFile(filename) {
+  // Exclude Symbiote.js presentation files
+  if (filename.endsWith('.css.js') || filename.endsWith('.tpl.js')) {
+    return false;
+  }
+  return SOURCE_EXTENSIONS.some(ext => filename.endsWith(ext));
+}
+
 /**
  * Find all JS files recursively (uses filter configuration)
  * @param {string} dir 
  * @param {string} [rootDir] - Root directory for relative path calculation
  * @returns {string[]}
  */
-function findJSFiles(dir, rootDir = dir) {
+export function findJSFiles(dir, rootDir = dir) {
   // Parse gitignore on first call
   if (dir === rootDir) {
     parseGitignore(rootDir);
@@ -279,7 +318,7 @@ function findJSFiles(dir, rootDir = dir) {
         if (!shouldExcludeDir(entry, relativePath)) {
           files.push(...findJSFiles(fullPath, rootDir));
         }
-      } else if (entry.endsWith('.js') && !entry.endsWith('.css.js') && !entry.endsWith('.tpl.js')) {
+      } else if (isSourceFile(entry)) {
         if (!shouldExcludeFile(entry, relativePath)) {
           files.push(fullPath);
         }

package/src/tool-defs.js

@@ -73,6 +73,19 @@ export const TOOLS = [
       required: ['symbol'],
     },
   },
+  {
+    name: 'get_call_chain',
+    description: 'Find the shortest call chain from one function/class to another through the dependency graph.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: 'Starting symbol (e.g., "authMiddleware")' },
+        to: { type: 'string', description: 'Target symbol (e.g., "renderDashboard")' },
+        path: { type: 'string', description: 'Path to scan (optional)' }
+      },
+      required: ['from', 'to'],
+    },
+  },
   {
     name: 'invalidate_cache',
     description: 'Invalidate the cached graph. Use after making code changes.',
@@ -213,6 +226,26 @@ export const TOOLS = [
   },
 
   // Guidelines
+  {
+    name: 'get_usage_guide',
+    description: [
+      'Get the comprehensive usage guide for project-graph with examples and best practices.',
+      'Call this FIRST when planning how to analyze, navigate, or audit a codebase.',
+      'Returns practical examples and recommended workflow for each feature area.',
+      '',
+      'Available topics: navigation, analysis, testing, documentation, rules, workflow.',
+      'Omit topic to get the full guide.',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        topic: {
+          type: 'string',
+          description: 'Optional topic filter: navigation, analysis, testing, documentation, rules, workflow',
+        },
+      },
+    },
+  },
   {
     name: 'get_agent_instructions',
     description: 'Get coding guidelines, architectural standards, and JSDoc rules for this project.',