project-graph-mcp 1.3.0 → 1.5.0

package/src/analysis-cache.js

@@ -0,0 +1,155 @@
+/**
+ * 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

@@ -15,7 +15,16 @@ 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
@@ -137,4 +146,126 @@ export const CLI_HANDLERS = {
       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

@@ -20,7 +20,7 @@ Commands:
   expand <symbol>        Expand minified symbol (e.g., SN, SN.togglePin)
   deps <symbol>          Get dependency tree
   usages <symbol>        Find all usages
-  pending <path>         List pending @test/@expect tests
+  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
@@ -30,6 +30,18 @@ Commands:
   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
@@ -37,7 +49,7 @@ Commands:
 Examples:
   npx project-graph-mcp skeleton src/components
   npx project-graph-mcp expand SN
-  npx project-graph-mcp pending src/
+  npx project-graph-mcp compact src/ --dry-run
 `);
 }
 

package/src/compact.js

@@ -0,0 +1,207 @@
+/**
+ * Compact/Beautify — Project-wide code compression and expansion
+ * 
+ * Converts JS files between compact (minified, no comments) and 
+ * beautified (formatted, readable) forms. Both preserve all names
+ * (mangle: false) — only whitespace and comments are affected.
+ * 
+ * Types and documentation live in .ctx files, not in source code.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, extname, relative } from 'path';
+import { minify } from '../vendor/terser.mjs';
+
+const SUPPORTED = new Set(['.js', '.mjs']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'vendor', '.context', 'dev-docs', '.agent', '.agents']);
+
+/**
+ * Walk directory for JS files
+ * @param {string} dir
+ * @param {string} rootDir
+ * @returns {string[]} Absolute paths
+ */
+function walkJSFiles(dir, rootDir = dir) {
+  const results = [];
+  try {
+    for (const entry of readdirSync(dir)) {
+      if (entry.startsWith('.') && entry !== '.') continue;
+      const full = join(dir, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        if (!SKIP_DIRS.has(entry)) {
+          results.push(...walkJSFiles(full, rootDir));
+        }
+      } else if (SUPPORTED.has(extname(entry).toLowerCase())) {
+        results.push(full);
+      }
+    }
+  } catch { /* skip unreadable */ }
+  return results;
+}
+
+/**
+ * Compact a single file — minify with preserved names
+ * @param {string} filePath
+ * @returns {Promise<{original: number, compacted: number}>}
+ */
+async function compactFile(filePath) {
+  const source = readFileSync(filePath, 'utf-8');
+  const original = source.length;
+
+  if (!source.trim()) return { original: 0, compacted: 0 };
+
+  const result = await minify(source, {
+    compress: {
+      dead_code: true,
+      drop_console: false,
+      passes: 2,
+    },
+    mangle: false,
+    module: true,
+    output: {
+      beautify: false,
+      comments: false,
+      semicolons: true,
+    },
+  });
+
+  if (result.error) throw result.error;
+  
+  writeFileSync(filePath, result.code, 'utf-8');
+  return { original, compacted: result.code.length };
+}
+
+/**
+ * Beautify a single file — format with readable output
+ * @param {string} filePath
+ * @returns {Promise<{original: number, beautified: number}>}
+ */
+async function beautifyFile(filePath) {
+  const source = readFileSync(filePath, 'utf-8');
+  const original = source.length;
+
+  if (!source.trim()) return { original: 0, beautified: 0 };
+
+  const result = await minify(source, {
+    compress: false,
+    mangle: false,
+    module: true,
+    output: {
+      beautify: true,
+      comments: false,
+      indent_level: 2,
+      semicolons: true,
+    },
+  });
+
+  if (result.error) throw result.error;
+
+  writeFileSync(filePath, result.code + '\n', 'utf-8');
+  return { original, beautified: result.code.length };
+}
+
+/**
+ * Compact all JS files in a directory
+ * @param {string} dir - Directory to compact
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun=false] - Preview without writing
+ * @returns {Promise<{files: number, originalBytes: number, compactedBytes: number, savings: string}>}
+ */
+export async function compactProject(dir, options = {}) {
+  const { dryRun = false } = options;
+  const files = walkJSFiles(dir);
+  let totalOriginal = 0;
+  let totalCompacted = 0;
+  const processed = [];
+  const errors = [];
+
+  for (const filePath of files) {
+    const rel = relative(dir, filePath);
+    try {
+      const source = readFileSync(filePath, 'utf-8');
+      totalOriginal += source.length;
+
+      if (!dryRun) {
+        const { compacted } = await compactFile(filePath);
+        totalCompacted += compacted;
+      } else {
+        const result = await minify(source, {
+          compress: { dead_code: true, drop_console: false, passes: 2 },
+          mangle: false,
+          module: true,
+          output: { beautify: false, comments: false },
+        });
+        totalCompacted += result.code?.length || source.length;
+      }
+
+      processed.push(rel);
+    } catch (e) {
+      errors.push({ file: rel, error: e.message });
+    }
+  }
+
+  const savings = totalOriginal > 0
+    ? Math.round((1 - totalCompacted / totalOriginal) * 100)
+    : 0;
+
+  return {
+    files: processed.length,
+    fileList: processed,
+    originalBytes: totalOriginal,
+    compactedBytes: totalCompacted,
+    savings: `${savings}%`,
+    errors: errors.length > 0 ? errors : undefined,
+    dryRun,
+  };
+}
+
+/**
+ * Beautify all JS files in a directory
+ * @param {string} dir - Directory to beautify
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun=false] - Preview without writing
+ * @returns {Promise<{files: number, originalBytes: number, beautifiedBytes: number}>}
+ */
+export async function expandProject(dir, options = {}) {
+  const { dryRun = false } = options;
+  const files = walkJSFiles(dir);
+  let totalOriginal = 0;
+  let totalBeautified = 0;
+  const processed = [];
+  const errors = [];
+
+  for (const filePath of files) {
+    const rel = relative(dir, filePath);
+    try {
+      const source = readFileSync(filePath, 'utf-8');
+      totalOriginal += source.length;
+
+      if (!dryRun) {
+        const { beautified } = await beautifyFile(filePath);
+        totalBeautified += beautified;
+      } else {
+        const result = await minify(source, {
+          compress: false,
+          mangle: false,
+          module: true,
+          output: { beautify: true, comments: false, indent_level: 2 },
+        });
+        totalBeautified += result.code?.length || source.length;
+      }
+
+      processed.push(rel);
+    } catch (e) {
+      errors.push({ file: rel, error: e.message });
+    }
+  }
+
+  return {
+    files: processed.length,
+    fileList: processed,
+    originalBytes: totalOriginal,
+    beautifiedBytes: totalBeautified,
+    errors: errors.length > 0 ? errors : undefined,
+    dryRun,
+  };
+}

package/src/complexity.js

@@ -109,13 +109,12 @@ function getRating(complexity) {
 }
 
 /**
- * Analyze complexity of file
- * @param {string} filePath 
+ * Analyze complexity of a single file (per-file export for cache integration)
+ * @param {string} code - File source code
+ * @param {string} relPath - Relative path for reporting
  * @returns {ComplexityItem[]}
  */
-function analyzeFile(filePath, rootDir) {
-  const code = readFileSync(filePath, 'utf-8');
-  const relPath = relative(rootDir, filePath);
+export function analyzeComplexityFile(code, relPath) {
   const items = [];
 
   let ast;
@@ -140,11 +139,9 @@ function analyzeFile(filePath, rootDir) {
     },
 
     ArrowFunctionExpression(node) {
-      // Skip small arrow functions
       if (node.body.type !== 'BlockStatement') return;
       const complexity = calculateComplexity(node.body);
       if (complexity > 5) {
-        // Only report complex arrow functions
         items.push({
           name: '(arrow)',
           type: 'function',
@@ -174,6 +171,23 @@ function analyzeFile(filePath, rootDir) {
   return items;
 }
 
+/**
+ * Analyze complexity of file (internal, reads from disk)
+ * @param {string} filePath 
+ * @param {string} rootDir
+ * @returns {ComplexityItem[]}
+ */
+function analyzeFile(filePath, rootDir) {
+  let code;
+  try {
+    code = readFileSync(filePath, 'utf-8');
+  } catch (e) {
+    return []; // File deleted between findJSFiles and read
+  }
+  const relPath = relative(rootDir, filePath);
+  return analyzeComplexityFile(code, relPath);
+}
+
 /**
  * Get complexity analysis for directory
  * @param {string} dir