project-graph-mcp 1.5.0 → 2.0.0

package/src/ai-context.js

@@ -1,113 +0,0 @@
-/**
- * AI Context Boot — Single-call agent bootstrap
- *
- * Combines skeleton + doc-dialect + optional compressed files
- * into one response for AI agent initialization.
- */
-
-import { resolve, extname } from 'path';
-import { getSkeleton, getGraph } from './tools.js';
-import { getProjectDocs } from './doc-dialect.js';
-import { compressFile } from './compress.js';
-import { findJSFiles } from './parser.js';
-
-/** Supported extensions for compression */
-const COMPRESSIBLE = new Set(['.js', '.mjs', '.ts', '.tsx']);
-
-/**
- * Estimate tokens for any value (string or object)
- * @param {*} value
- * @returns {number}
- */
-function estimateTokens(value) {
-  const str = typeof value === 'string' ? value : JSON.stringify(value);
-  return Math.ceil(str.length / 4);
-}
-
-/**
- * Load complete AI context for agent bootstrap
- * @param {string} dirPath - Project directory
- * @param {Object} [options]
- * @param {string[]} [options.includeFiles] - Specific files to include compressed
- * @param {boolean} [options.includeDocs=true] - Include doc-dialect
- * @param {boolean} [options.includeSkeleton=true] - Include skeleton
- * @returns {Promise<{skeleton?: Object, docs?: string, files?: Object, totalTokens: number, vsOriginal: number, savings: string}>}
- */
-export async function getAiContext(dirPath, options = {}) {
-  const {
-    includeFiles = [],
-    includeDocs = true,
-    includeSkeleton = true,
-  } = options;
-
-  const projectPath = resolve(dirPath);
-  const result = {};
-  let totalTokens = 0;
-
-  // 1. Skeleton
-  if (includeSkeleton) {
-    result.skeleton = await getSkeleton(projectPath);
-    totalTokens += estimateTokens(result.skeleton);
-  }
-
-  // 2. Doc Dialect
-  if (includeDocs) {
-    const graph = await getGraph(projectPath);
-    result.docs = getProjectDocs(graph, projectPath);
-    totalTokens += estimateTokens(result.docs);
-  }
-
-  // 3. Compressed files
-  if (includeFiles.length > 0) {
-    result.files = {};
-    const allFiles = findJSFiles(projectPath);
-
-    for (const requestedFile of includeFiles) {
-      // Find matching file (by name or path)
-      const match = allFiles.find(f =>
-        f.endsWith(requestedFile) || f.endsWith('/' + requestedFile)
-      );
-
-      if (!match) {
-        result.files[requestedFile] = { error: `File not found: ${requestedFile}` };
-        continue;
-      }
-
-      const ext = extname(match).toLowerCase();
-      if (!COMPRESSIBLE.has(ext)) {
-        result.files[requestedFile] = { error: `Unsupported file type: ${ext}` };
-        continue;
-      }
-
-      try {
-        const compressed = await compressFile(match, { beautify: true, legend: true });
-        result.files[requestedFile] = compressed.code;
-        totalTokens += compressed.compressed;
-      } catch (e) {
-        result.files[requestedFile] = { error: e.message };
-      }
-    }
-  }
-
-  // Estimate original size for savings calculation
-  const allFiles = findJSFiles(projectPath);
-  let vsOriginal = 0;
-  for (const file of allFiles) {
-    try {
-      const { readFileSync } = await import('fs');
-      vsOriginal += estimateTokens(readFileSync(file, 'utf-8'));
-    } catch {
-      // skip unreadable
-    }
-  }
-
-  const savings = vsOriginal > 0
-    ? Math.round((1 - totalTokens / vsOriginal) * 100)
-    : 0;
-
-  result.totalTokens = totalTokens;
-  result.vsOriginal = vsOriginal;
-  result.savings = `${savings}%`;
-
-  return result;
-}

package/src/analysis-cache.js

@@ -1,155 +0,0 @@
-/**
- * Analysis Cache Manager
- * Persistent file-based cache in .context/.cache/ with dual hashing
- * 
- * - sig: interface hash (function names, params, exports) → invalidates docs
- * - contentHash: full source hash → invalidates body-dependent metrics
- * 
- * Cacheable (per-file): complexity, undocumented, jsdocConsistency
- * NOT cacheable (cross-file): deadCode, similarity
- */
-
-import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs';
-import { join, dirname } from 'path';
-import { createHash } from 'crypto';
-
-/**
- * @typedef {Object} CacheEntry
- * @property {string} sig - Interface hash
- * @property {string} contentHash - Full content hash
- * @property {Object} [complexity] - Cached complexity results
- * @property {Array} [undocumented] - Cached undocumented items
- * @property {Array} [jsdocIssues] - Cached JSDoc consistency issues
- * @property {string} cachedAt - ISO timestamp
- */
-
-/**
- * Compute interface signature hash
- * Matches @sig logic from doc-dialect.js
- * @param {Object} fileData - Parsed file data with functions, classes, exports
- * @returns {string} - 8-char hex hash
- */
-export function computeSig(fileData) {
-  const parts = [];
-
-  // Function signatures
-  if (fileData.functions) {
-    for (const fn of fileData.functions) {
-      parts.push(`fn:${fn.name}:${fn.params?.length || 0}`);
-    }
-  }
-
-  // Class signatures
-  if (fileData.classes) {
-    for (const cls of fileData.classes) {
-      parts.push(`cls:${cls.name}`);
-      if (cls.methods) {
-        for (const m of cls.methods) {
-          parts.push(`m:${cls.name}.${m}`);
-        }
-      }
-    }
-  }
-
-  // Exports
-  if (fileData.exports) {
-    for (const exp of fileData.exports) {
-      parts.push(`exp:${exp}`);
-    }
-  }
-
-  const hash = createHash('md5').update(parts.sort().join('|')).digest('hex');
-  return hash.slice(0, 8);
-}
-
-/**
- * Compute full content hash (body-inclusive)
- * Used for complexity and other body-dependent metrics
- * @param {string} code - Source code
- * @returns {string} - 8-char hex hash 
- */
-export function computeContentHash(code) {
-  return createHash('md5').update(code).digest('hex').slice(0, 8);
-}
-
-/**
- * Get cache file path for a source file
- * @param {string} contextDir - .context directory path
- * @param {string} relPath - Relative path to source file (e.g., "src/parser.js")
- * @returns {string} - Cache file path
- */
-export function getCachePath(contextDir, relPath) {
-  // src/parser.js → .context/.cache/src/parser.json
-  const cacheName = relPath.replace(/\.[^.]+$/, '.json');
-  return join(contextDir, '.cache', cacheName);
-}
-
-/**
- * Read cached analysis for a file
- * @param {string} contextDir
- * @param {string} relPath
- * @returns {CacheEntry|null}
- */
-export function readCache(contextDir, relPath) {
-  const cachePath = getCachePath(contextDir, relPath);
-  try {
-    if (!existsSync(cachePath)) return null;
-    return JSON.parse(readFileSync(cachePath, 'utf-8'));
-  } catch (e) {
-    return null;
-  }
-}
-
-/**
- * Write cache entry for a file
- * @param {string} contextDir
- * @param {string} relPath
- * @param {CacheEntry} data
- */
-export function writeCache(contextDir, relPath, data) {
-  const cachePath = getCachePath(contextDir, relPath);
-  try {
-    mkdirSync(dirname(cachePath), { recursive: true });
-    writeFileSync(cachePath, JSON.stringify({
-      ...data,
-      cachedAt: new Date().toISOString(),
-    }, null, 2));
-  } catch (e) {
-    // Cache write failure is non-fatal
-  }
-}
-
-/**
- * Check if cache is still valid
- * @param {CacheEntry|null} cached
- * @param {string} currentSig - Current interface hash
- * @param {string} currentContentHash - Current content hash
- * @param {'sig'|'content'} level - Which hash to check
- * @returns {boolean}
- */
-export function isCacheValid(cached, currentSig, currentContentHash, level = 'content') {
-  if (!cached) return false;
-  if (!cached.sig || !cached.contentHash) return false;
-
-  if (level === 'sig') {
-    return cached.sig === currentSig;
-  }
-
-  // For body-dependent metrics, both hashes must match
-  return cached.sig === currentSig && cached.contentHash === currentContentHash;
-}
-
-/**
- * Invalidate all caches (e.g., after structural changes)
- * @param {string} contextDir
- */
-export function invalidateAllCaches(contextDir) {
-  const cacheDir = join(contextDir, '.cache');
-  try {
-    if (existsSync(cacheDir)) {
-      rmSync(cacheDir, { recursive: true, force: true });
-    }
-  } catch (e) {
-    // Non-fatal
-  }
-}

package/src/cli-handlers.js

@@ -1,271 +0,0 @@
-/**
- * CLI Command Handlers Registry
- * Extracted from cli.js to reduce cyclomatic complexity
- */
-
-import { getSkeleton, getFocusZone, expand, deps, usages } from './tools.js';
-import { getPendingTests, getTestSummary } from './test-annotations.js';
-import { getFilters } from './filters.js';
-import { getInstructions } from './instructions.js';
-import { getUndocumentedSummary } from './undocumented.js';
-import { getDeadCode } from './dead-code.js';
-import { generateJSDoc } from './jsdoc-generator.js';
-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 { compressFile } from './compress.js';
-import { getProjectDocs, generateContextFiles } from './doc-dialect.js';
-import { getGraph } from './tools.js';
-import { parseProject } from './parser.js';
-import { resolvePath } from './workspace.js';
-import { checkJSDocConsistency } from './jsdoc-checker.js';
-import { checkTypes } from './type-checker.js';
-import { compactProject, expandProject } from './compact.js';
-import { injectJSDoc, stripJSDoc, validateCtxContracts } from './ctx-to-jsdoc.js';
-import { getConfig, setConfig, getModeDescription, getModeWorkflow } from './mode-config.js';
-
-/**
- * Parse named argument from args array
- * @param {string[]} args 
- * @param {string} name 
- * @returns {string|undefined}
- */
-function getArg(args, name) {
-  const arg = args.find(a => a.startsWith(`--${name}=`));
-  return arg ? arg.split('=')[1] : undefined;
-}
-
-/**
- * Get path argument (first non-flag arg), resolved against workspace root
- * @param {string[]} args 
- * @returns {string}
- */
-function getPath(args) {
-  const raw = args.find(a => !a.startsWith('--')) || '.';
-  return resolvePath(raw);
-}
-
-/**
- * CLI command handlers registry
- * Each handler returns a result or throws an error
- */
-export const CLI_HANDLERS = {
-  skeleton: {
-    requiresArg: true,
-    argError: 'Path required: skeleton <path>',
-    handler: async (args) => getSkeleton(resolvePath(args[0])),
-  },
-
-  expand: {
-    requiresArg: true,
-    argError: 'Symbol required: expand <symbol>',
-    handler: async (args) => expand(args[0]),
-  },
-
-  deps: {
-    requiresArg: true,
-    argError: 'Symbol required: deps <symbol>',
-    handler: async (args) => deps(args[0]),
-  },
-
-  usages: {
-    requiresArg: true,
-    argError: 'Symbol required: usages <symbol>',
-    handler: async (args) => usages(args[0]),
-  },
-
-  pending: {
-    handler: async (args) => getPendingTests(getPath(args)),
-  },
-
-  summary: {
-    handler: async (args) => getTestSummary(getPath(args)),
-  },
-
-  filters: {
-    handler: async () => getFilters(),
-  },
-
-  instructions: {
-    rawOutput: true,
-    handler: async () => getInstructions(),
-  },
-
-  undocumented: {
-    handler: async (args) => {
-      const level = getArg(args, 'level') || 'tests';
-      return getUndocumentedSummary(getPath(args), level);
-    },
-  },
-
-  deadcode: {
-    handler: async (args) => getDeadCode(getPath(args)),
-  },
-
-  jsdoc: {
-    requiresArg: true,
-    argError: 'Usage: jsdoc <file>',
-    handler: async (args) => generateJSDoc(resolvePath(args[0])),
-  },
-
-  similar: {
-    handler: async (args) => {
-      const threshold = parseInt(getArg(args, 'threshold')) || 60;
-      return getSimilarFunctions(getPath(args), { threshold });
-    },
-  },
-
-  complexity: {
-    handler: async (args) => {
-      const minComplexity = parseInt(getArg(args, 'min')) || 1;
-      const onlyProblematic = args.includes('--problematic');
-      return getComplexity(getPath(args), { minComplexity, onlyProblematic });
-    },
-  },
-
-  largefiles: {
-    handler: async (args) => {
-      const onlyProblematic = args.includes('--problematic');
-      return getLargeFiles(getPath(args), { onlyProblematic });
-    },
-  },
-
-  outdated: {
-    handler: async (args) => {
-      const codeOnly = args.includes('--code');
-      const depsOnly = args.includes('--deps');
-      return getOutdatedPatterns(getPath(args), { codeOnly, depsOnly });
-    },
-  },
-
-  analyze: {
-    handler: async (args) => {
-      const includeItems = args.includes('--items');
-      return getFullAnalysis(getPath(args), { includeItems });
-    },
-  },
-
-  'jsdoc-check': {
-    handler: async (args) => checkJSDocConsistency(getPath(args)),
-  },
-
-  types: {
-    handler: async (args) => {
-      const maxDiagnostics = parseInt(getArg(args, 'max')) || 50;
-      return checkTypes(getPath(args), { maxDiagnostics });
-    },
-  },
-
-  compress: {
-    requiresArg: true,
-    argError: 'Usage: compress <file> [--no-beautify] [--no-legend]',
-    handler: async (args) => {
-      const beautify = !args.includes('--no-beautify');
-      const legend = !args.includes('--no-legend');
-      return compressFile(resolvePath(args[0]), { beautify, legend });
-    },
-  },
-
-  docs: {
-    requiresArg: true,
-    argError: 'Usage: docs <path> [--file=<filename>]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const graph = await getGraph(projectPath);
-      const file = args.find(a => a.startsWith('--file='))?.split('=')[1];
-      return getProjectDocs(graph, projectPath, { file });
-    },
-  },
-
-  'generate-ctx': {
-    requiresArg: true,
-    argError: 'Usage: generate-ctx <path> [--overwrite] [--scope=focus|all]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const graph = await getGraph(projectPath);
-      const parsed = await parseProject(projectPath);
-      const overwrite = args.includes('--overwrite');
-      const scope = args.find(a => a.startsWith('--scope='))?.split('=')[1] || 'all';
-      return generateContextFiles(graph, projectPath, parsed, { overwrite, scope });
-    },
-  },
-
-  compact: {
-    requiresArg: true,
-    argError: 'Usage: compact <path> [--dry-run]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const dryRun = args.includes('--dry-run');
-      return compactProject(projectPath, { dryRun });
-    },
-  },
-
-  beautify: {
-    requiresArg: true,
-    argError: 'Usage: beautify <path> [--dry-run]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const dryRun = args.includes('--dry-run');
-      return expandProject(projectPath, { dryRun });
-    },
-  },
-
-  'inject-jsdoc': {
-    requiresArg: true,
-    argError: 'Usage: inject-jsdoc <path> [--dry-run]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const dryRun = args.includes('--dry-run');
-      return injectJSDoc(projectPath, { dryRun });
-    },
-  },
-
-  'strip-jsdoc': {
-    requiresArg: true,
-    argError: 'Usage: strip-jsdoc <path> [--dry-run]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const dryRun = args.includes('--dry-run');
-      return stripJSDoc(projectPath, { dryRun });
-    },
-  },
-
-  'validate-ctx': {
-    requiresArg: true,
-    argError: 'Usage: validate-ctx <path> [--strict]',
-    handler: async (args) => {
-      const projectPath = resolvePath(args[0]);
-      const strict = args.includes('--strict');
-      return validateCtxContracts(projectPath, { strict });
-    },
-  },
-
-  mode: {
-    requiresArg: true,
-    argError: 'Usage: mode <path>',
-    handler: async (args) => {
-      const dir = resolvePath(args[0]);
-      const config = getConfig(dir);
-      return {
-        ...config,
-        description: getModeDescription(config.mode),
-        workflow: getModeWorkflow(config.mode),
-      };
-    },
-  },
-
-  'set-mode': {
-    requiresArg: true,
-    argError: 'Usage: set-mode <path> <1|2|3>',
-    handler: async (args) => {
-      const dir = resolvePath(args[0]);
-      const mode = parseInt(args[1], 10);
-      if (!mode || ![1, 2, 3].includes(mode)) {
-        throw new Error('Mode must be 1, 2, or 3');
-      }
-      return setConfig(dir, { mode });
-    },
-  },
-};

package/src/cli.js

@@ -1,95 +0,0 @@
-/**
- * CLI Entry Point for Project Graph MCP
- */
-
-import { CLI_HANDLERS } from './cli-handlers.js';
-
-/**
- * Print CLI help
- */
-export function printHelp() {
-  console.log(`
-project-graph-mcp - MCP server for AI agents
-
-Usage:
-  npx project-graph-mcp                  Start MCP stdio server
-  npx project-graph-mcp <command> [args] Run CLI command
-
-Commands:
-  skeleton <path>        Get compact project overview
-  expand <symbol>        Expand minified symbol (e.g., SN, SN.togglePin)
-  deps <symbol>          Get dependency tree
-  usages <symbol>        Find all usages
-  pending <path>         List pending .ctx.md test checklists
-  summary <path>         Get test progress summary
-  undocumented <path>    Find missing JSDoc (--level=tests|params|all)
-  deadcode <path>        Find unused functions/classes
-  jsdoc <file>           Generate JSDoc for file
-  similar <path>         Find similar functions (--threshold=60)
-  complexity <path>      Analyze cyclomatic complexity (--min=1)
-  largefiles <path>      Find files needing split (--problematic)
-  outdated <path>        Find legacy patterns & redundant deps
-  analyze <path>         Run ALL checks with Health Score
-  jsdoc-check <path>     Validate JSDoc ↔ function signatures
-  types <path>           Run tsc type checking (--max=50)
-  compress <file>        Compress JS file for AI (--no-beautify, --no-legend)
-  compact <path>         Compact all JS files — strips comments/whitespace (--dry-run)
-  beautify <path>        Beautify/expand all JS files — inverse of compact (--dry-run)
-  inject-jsdoc <path>    Generate JSDoc from .ctx files and inject into source
-  strip-jsdoc <path>     Strip all JSDoc blocks from source files
-  docs <path>            Get project docs in doc-dialect format (--file=<name>)
-  generate-ctx <path>    Generate .context/ docs (--overwrite --scope=focus)
-  validate-ctx <path>    Validate .ctx contracts against source AST (--strict)
-  mode <path>            Show current compact code mode and workflow
-  set-mode <path> <1|2|3> Set compact code mode (1=compact, 2=full, 3=IDE)
-  filters                Show current filter configuration
-  instructions           Show agent guidelines (JSDoc, Arch)
-  help                   Show this help
-
-Examples:
-  npx project-graph-mcp skeleton src/components
-  npx project-graph-mcp expand SN
-  npx project-graph-mcp compact src/ --dry-run
-`);
-}
-
-/**
- * Run CLI command
- * @param {string} command 
- * @param {string[]} args 
- */
-export async function runCLI(command, args) {
-  // Handle help commands
-  if (!command || command === 'help' || command === '--help' || command === '-h') {
-    printHelp();
-    return;
-  }
-
-  // Look up handler
-  const def = CLI_HANDLERS[command];
-  if (!def) {
-    console.error(`Unknown command: ${command}`);
-    console.error('Run with "help" for usage information');
-    process.exit(1);
-  }
-
-  // Validate required arg
-  if (def.requiresArg && !args[0]) {
-    console.error(def.argError || `Argument required for: ${command}`);
-    process.exit(1);
-  }
-
-  try {
-    const result = await def.handler(args);
-
-    // Handle raw output (like instructions)
-    if (def.rawOutput) {
-      console.log(result);
-    } else {
-      console.log(JSON.stringify(result, null, 2));
-    }
-  } catch (error) {
-    console.error('Error:', error.message);
-    process.exit(1);
-  }
-}