project-graph-mcp 1.3.0 → 1.5.0

package/src/mode-config.js

@@ -0,0 +1,127 @@
+/**
+ * Compact Code Mode Configuration
+ *
+ * Manages project-level mode selection for the compact code architecture.
+ * Reads/writes `.context/config.json` to configure how agents interact with code.
+ *
+ * Modes:
+ *   1 = Native Compact: code stored minified, agent edits directly
+ *   2 = Full Storage:   code stored formatted, agent reads compressed view, edits via edit_compressed
+ *   3 = Future (IDE):   compact storage with IDE virtual display (reserved)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+const CONFIG_FILE = '.context/config.json';
+
+/** Default configuration */
+const DEFAULTS = {
+  mode: 2,
+  beautify: true,
+  autoValidate: false,
+  stripJSDoc: false,
+};
+
+/**
+ * Read project mode configuration from .context/config.json
+ * Returns defaults if file doesn't exist.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {{ mode: number, beautify: boolean, autoValidate: boolean, stripJSDoc: boolean }}
+ */
+export function getConfig(projectDir) {
+  const configPath = join(projectDir, CONFIG_FILE);
+
+  if (!existsSync(configPath)) {
+    return { ...DEFAULTS };
+  }
+
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULTS, ...parsed };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+/**
+ * Write project mode configuration to .context/config.json
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {Object} config - Configuration to save (merged with existing)
+ * @returns {{ saved: boolean, path: string, config: Object }}
+ */
+export function setConfig(projectDir, config) {
+  const configPath = join(projectDir, CONFIG_FILE);
+  const dir = dirname(configPath);
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Merge with existing
+  const existing = getConfig(projectDir);
+  const merged = { ...existing, ...config };
+
+  // Validate mode
+  if (![1, 2, 3].includes(merged.mode)) {
+    throw new Error(`Invalid mode: ${merged.mode}. Valid: 1 (compact), 2 (full), 3 (IDE)`);
+  }
+
+  writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+
+  return {
+    saved: true,
+    path: configPath,
+    config: merged,
+  };
+}
+
+/**
+ * Get human-readable description of current mode
+ * @param {number} mode
+ * @returns {string}
+ */
+export function getModeDescription(mode) {
+  switch (mode) {
+    case 1: return 'Native Compact — code stored minified, agent edits directly';
+    case 2: return 'Full Storage — code stored formatted, agent uses get_compressed_file + edit_compressed';
+    case 3: return 'IDE Virtual — compact storage with IDE virtual display (future)';
+    default: return `Unknown mode: ${mode}`;
+  }
+}
+
+/**
+ * Get recommended workflow for current mode
+ * @param {number} mode
+ * @returns {{ read: string, edit: string, docs: string, validate: string }}
+ */
+export function getModeWorkflow(mode) {
+  switch (mode) {
+    case 1:
+      return {
+        read: 'Read .js files directly (already compact)',
+        edit: 'Edit .js files directly',
+        docs: 'Read .ctx files for types and descriptions',
+        validate: 'Run validate-ctx to check .ctx ↔ AST consistency',
+      };
+    case 2:
+      return {
+        read: 'Use get_compressed_file for token-efficient reading',
+        edit: 'Use edit_compressed(path, symbol, code) for AST-safe editing',
+        docs: 'Read .ctx files for types and descriptions',
+        validate: 'Run validate-ctx to check .ctx ↔ AST consistency',
+      };
+    case 3:
+      return {
+        read: 'IDE renders full view from compact storage',
+        edit: 'IDE handles bidirectional mapping',
+        docs: 'Managed by IDE plugin',
+        validate: 'Automatic via IDE integration',
+      };
+    default:
+      return { read: 'N/A', edit: 'N/A', docs: 'N/A', validate: 'N/A' };
+  }
+}

package/src/outdated-patterns.js

@@ -152,6 +152,7 @@ function findJSFiles(dir, rootDir = dir) {
 /**
  * Analyze file for outdated patterns
  * @param {string} filePath 
+ * @param {string} rootDir - Root directory for relative path calculation
  * @returns {PatternMatch[]}
  */
 function analyzeFilePatterns(filePath, rootDir) {

package/src/parser.js

@@ -3,7 +3,7 @@
  * Extracts classes, functions, methods, properties, imports, calls, and SQL queries
  */
 
-import { readFileSync, readdirSync, statSync } from 'fs';
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
 import { join, relative, resolve } from 'path';
 import { parse } from '../vendor/acorn.mjs';
 import * as walk from '../vendor/walk.mjs';
@@ -64,12 +64,15 @@ export async function parseFile(code, filename) {
     exports: [],
   };
 
+  // Collect JSDoc comments for type extraction
+  const comments = [];
   let ast;
   try {
     ast = parse(code, {
       ecmaVersion: 'latest',
       sourceType: 'module',
       locations: true,
+      onComment: comments,
     });
   } catch (e) {
     // If parsing fails, return empty result
@@ -77,6 +80,9 @@ export async function parseFile(code, filename) {
     return result;
   }
 
+  // Build JSDoc type map: endLine → { params: [{name, type}], returns: string }
+  const jsdocMap = buildJSDocTypeMap(comments, code);
+
   // Track exported names
   const exportedNames = new Set();
 
@@ -158,9 +164,24 @@ export async function parseFile(code, filename) {
     // Standalone function declarations
     FunctionDeclaration(node) {
       if (node.id) {
+        const rawParams = node.params.map(p => {
+          if (p.type === 'Identifier') return p.name;
+          if (p.type === 'AssignmentPattern' && p.left.type === 'Identifier') return p.left.name + '=';
+          if (p.type === 'RestElement' && p.argument.type === 'Identifier') return '...' + p.argument.name;
+          if (p.type === 'ObjectPattern') return 'options';
+          return '?';
+        });
+
+        // Enrich params with JSDoc types
+        const jsdoc = findJSDocForNode(jsdocMap, node.loc.start.line);
+        const typedParams = enrichParamsWithTypes(rawParams, jsdoc);
+
         const funcInfo = {
           name: node.id.name,
           exported: false, // Will be updated later
+          params: typedParams,
+          async: node.async || false,
+          returns: jsdoc?.returns || null,
           calls: [],
           dbReads: [],
           dbWrites: [],
@@ -338,12 +359,53 @@ function templateToString(tplNode) {
   return result;
 }
 
+/**
+ * Discover sub-projects in a monorepo directory structure
+ * @param {string} rootDir 
+ * @returns {Array<{name: string, path: string, absolutePath: string}>}
+ */
+export function discoverSubProjects(rootDir) {
+  const resolvedRoot = resolve(rootDir);
+  const subProjects = [];
+  
+  // Known monorepo directory conventions
+  const MONO_DIRS = ['packages', 'apps', 'services', 'modules', 'libs', 'plugins'];
+  
+  for (const monoDir of MONO_DIRS) {
+    const monoPath = join(resolvedRoot, monoDir);
+    if (!existsSync(monoPath)) continue;
+    
+    try {
+      for (const entry of readdirSync(monoPath)) {
+        const entryPath = join(monoPath, entry);
+        const pkgPath = join(entryPath, 'package.json');
+        if (statSync(entryPath).isDirectory() && existsSync(pkgPath)) {
+          try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            subProjects.push({
+              name: pkg.name || entry,
+              path: relative(resolvedRoot, entryPath),
+              absolutePath: entryPath,
+            });
+          } catch { 
+            subProjects.push({ name: entry, path: relative(resolvedRoot, entryPath), absolutePath: entryPath });
+          }
+        }
+      }
+    } catch { /* dir not readable */ }
+  }
+  
+  return subProjects;
+}
+
 /**
  * Parse all JS files in a directory
  * @param {string} dir 
+ * @param {Object} [options={}]
+ * @param {boolean} [options.recursive=false]
  * @returns {Promise<ParseResult>}
  */
-export async function parseProject(dir) {
+export async function parseProject(dir, options = {}) {
   const result = {
     files: [],
     classes: [],
@@ -357,17 +419,48 @@ export async function parseProject(dir) {
   const files = findJSFiles(dir);
 
   for (const file of files) {
-    const content = readFileSync(file, 'utf-8');
-    const relPath = relative(resolvedDir, file);
-    const parsed = await parseFileByExtension(content, relPath);
-
-    result.files.push(relPath);
-    result.classes.push(...parsed.classes);
-    result.functions.push(...parsed.functions);
-    result.imports.push(...parsed.imports);
-    result.exports.push(...parsed.exports);
-    if (parsed.tables?.length) {
-      result.tables.push(...parsed.tables);
+    try {
+      const content = readFileSync(file, 'utf-8');
+      const relPath = relative(resolvedDir, file);
+      const parsed = await parseFileByExtension(content, relPath);
+
+      result.files.push(relPath);
+      result.classes.push(...parsed.classes);
+      result.functions.push(...parsed.functions);
+      result.imports.push(...parsed.imports);
+      result.exports.push(...parsed.exports);
+      if (parsed.tables?.length) {
+        result.tables.push(...parsed.tables);
+      }
+    } catch (e) {
+      // Ignore unreadable files
+    }
+  }
+
+  // Recursive monorepo support
+  if (options.recursive) {
+    const subs = discoverSubProjects(dir);
+    result.subProjects = [];
+    for (const sub of subs) {
+      try {
+        const subResult = await parseProject(sub.absolutePath);
+        // Prefix all file paths with sub-project path
+        for (const f of subResult.files) {
+          result.files.push(join(sub.path, f));
+        }
+        for (const c of subResult.classes) {
+          c.file = join(sub.path, c.file);
+          result.classes.push(c);
+        }
+        for (const fn of subResult.functions) {
+          fn.file = join(sub.path, fn.file);
+          result.functions.push(fn);
+        }
+        result.imports.push(...subResult.imports);
+        result.exports.push(...subResult.exports);
+        if (subResult.tables?.length) result.tables.push(...subResult.tables);
+        result.subProjects.push({ name: sub.name, path: sub.path, files: subResult.files.length });
+      } catch { /* sub-project parse failure is non-fatal */ }
     }
   }
 
@@ -450,3 +543,120 @@ export function findJSFiles(dir, rootDir = dir) {
 
   return files;
 }
+
+// ============================
+// JSDoc Type Extraction
+// ============================
+
+/**
+ * Build a map of JSDoc comment end-lines to their extracted type info.
+ * @param {Array} comments - Acorn onComment array
+ * @param {string} code - Full source code
+ * @returns {Map<number, {params: Array<{name: string, type: string}>, returns: string|null}>}
+ */
+function buildJSDocTypeMap(comments, code) {
+  const map = new Map();
+
+  for (const comment of comments) {
+    // Only process JSDoc blocks (/** ... */)
+    if (comment.type !== 'Block' || !comment.value.startsWith('*')) continue;
+
+    const text = '/*' + comment.value + '*/';
+    const endLine = code.slice(0, comment.end).split('\n').length;
+
+    // Parse @param tags with balanced brace matching
+    const params = [];
+    const paramStartRegex = /@param\s+\{/g;
+    let paramStart;
+    while ((paramStart = paramStartRegex.exec(text)) !== null) {
+      // Find matching closing brace (balanced — handles {Array<{text: string}>})
+      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);
+      // Skip dotted paths (options.x)
+      if (name.includes('.')) continue;
+      params.push({ name, type });
+    }
+
+    // Parse @returns {Type}
+    let returns = null;
+    const returnsMatch = text.match(/@returns?\s+\{([^}]+)\}/);
+    if (returnsMatch) {
+      returns = returnsMatch[1];
+    }
+
+    if (params.length > 0 || returns) {
+      map.set(endLine, { params, returns });
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Find the JSDoc entry that applies to a function at the given line.
+ * JSDoc must end within 2 lines above the function declaration.
+ * @param {Map} jsdocMap
+ * @param {number} funcLine - Function start line
+ * @returns {{ params: Array<{name: string, type: string}>, returns: string|null }|null}
+ */
+function findJSDocForNode(jsdocMap, funcLine) {
+  // JSDoc can end 1 or 2 lines above (direct or with blank line)
+  for (let offset = 1; offset <= 3; offset++) {
+    const entry = jsdocMap.get(funcLine - offset);
+    if (entry) return entry;
+  }
+  return null;
+}
+
+/**
+ * Enrich AST-extracted param names with types from JSDoc.
+ * Input:  ['filePath', 'options=']  + jsdoc.params: [{name:'filePath', type:'string'}, {name:'options', type:'Object'}]
+ * Output: ['filePath:string', 'options:Object=']
+ * @param {string[]} rawParams
+ * @param {Object|null} jsdoc
+ * @returns {string[]}
+ */
+function enrichParamsWithTypes(rawParams, jsdoc) {
+  if (!jsdoc || jsdoc.params.length === 0) return rawParams;
+
+  // Build name→type lookup from JSDoc
+  const typeMap = new Map();
+  for (const p of jsdoc.params) {
+    typeMap.set(p.name, p.type);
+  }
+
+  return rawParams.map(param => {
+    // Parse: '...name', 'name=', 'name', 'options'
+    const isRest = param.startsWith('...');
+    const hasDefault = param.endsWith('=');
+    let cleanName = param;
+    if (isRest) cleanName = cleanName.slice(3);
+    if (hasDefault) cleanName = cleanName.slice(0, -1);
+
+    let type = typeMap.get(cleanName);
+    if (!type) return param; // No JSDoc type found
+
+    // Strip JSDoc rest indicator {...Type} — rest is already from AST
+    if (type.startsWith('...')) type = type.slice(3);
+
+    // Reconstruct: ...name:Type, name:Type=, name:Type
+    const prefix = isRest ? '...' : '';
+    const suffix = hasDefault ? '=' : '';
+    return `${prefix}${cleanName}:${type}${suffix}`;
+  });
+}

package/src/similar-functions.js

@@ -63,6 +63,7 @@ function findJSFiles(dir, rootDir = dir) {
 /**
  * Extract function signatures from a file
  * @param {string} filePath 
+ * @param {string} rootDir - Root directory for relative path calculation
  * @returns {FunctionSignature[]}
  */
 function extractSignatures(filePath, rootDir) {