project-graph-mcp 1.2.4 → 1.5.0

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,10 +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));
 
@@ -108,6 +119,110 @@ const TOOL_HANDLERS = {
     framework: args.framework,
     path: args.path ? resolvePath(args.path) : undefined,
   }),
+
+  // Database Analysis
+  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);
+  },
 };
 
 /**
@@ -130,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;
   },
 
@@ -177,6 +296,122 @@ const RESPONSE_HINTS = {
   get_pending_tests: () => [
     '💡 Use mark_test_passed(testId) or mark_test_failed(testId, reason) to track progress.',
   ],
+
+  get_db_schema: (result) => {
+    const hints = [];
+    if (result.totalTables > 0) {
+      hints.push(`💡 Found ${result.totalTables} tables. Use get_table_usage() to see which code reads/writes them.`);
+    } else {
+      hints.push('💡 No .sql schema files found. Add schema.sql or migrations/*.sql to your project.');
+    }
+    return hints;
+  },
+
+  get_table_usage: (result) => {
+    const hints = ['💡 Use get_db_dead_tables() to find tables defined in schema but never queried.'];
+    if (result.totalTables === 0) {
+      hints.push('💡 No SQL queries detected. This tool finds SQL in .query(), .execute(), sql`...` patterns.');
+    }
+    return 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 [];
+  },
 };
 
 /**

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) {