project-graph-mcp 1.0.0

package/src/framework-references.js

@@ -0,0 +1,177 @@
+/**
+ * Framework Reference System
+ * Loads framework-specific AI references from GitHub (with caching) or local files
+ */
+
+import { readFileSync, readdirSync, existsSync, writeFileSync } from 'fs';
+import { join, basename, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { detectProjectRuleSets } from './custom-rules.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REFERENCES_DIR = join(__dirname, '..', 'references');
+
+/**
+ * Remote sources for framework references
+ * Maps reference name to raw GitHub URL
+ */
+const REMOTE_SOURCES = {
+  'symbiote-3x': 'https://raw.githubusercontent.com/symbiotejs/symbiote.js/main/AI_REFERENCE.md',
+};
+
+/** @type {Map<string, {content: string, fetchedAt: number}>} */
+const cache = new Map();
+
+/** Cache TTL: 1 hour */
+const CACHE_TTL = 60 * 60 * 1000;
+
+/**
+ * Fetch reference from GitHub with caching
+ * Falls back to local file if fetch fails
+ * @param {string} name - Reference name
+ * @returns {Promise<{content: string, source: string}>}
+ */
+async function fetchReference(name) {
+  const url = REMOTE_SOURCES[name];
+  const localPath = join(REFERENCES_DIR, `${name}.md`);
+
+  // Check in-memory cache
+  const cached = cache.get(name);
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL) {
+    return { content: cached.content, source: 'cache' };
+  }
+
+  // Try fetching from GitHub
+  if (url) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
+      if (response.ok) {
+        const content = await response.text();
+        cache.set(name, { content, fetchedAt: Date.now() });
+
+        // Update local file as backup
+        try {
+          writeFileSync(localPath, content, 'utf-8');
+        } catch (e) {
+          // Write failure is non-critical
+        }
+
+        return { content, source: `github (${url})` };
+      }
+    } catch (e) {
+      // Fetch failed — fall back to local
+    }
+  }
+
+  // Fall back to local file
+  if (existsSync(localPath)) {
+    const content = readFileSync(localPath, 'utf-8');
+    cache.set(name, { content, fetchedAt: Date.now() });
+    return { content, source: 'local' };
+  }
+
+  return { content: '', source: 'not_found' };
+}
+
+/**
+ * Map ruleset names to reference names
+ */
+const RULESET_TO_REFERENCE = {
+  'symbiote-3x': 'symbiote-3x',
+  'symbiote-2x': 'symbiote-3x',
+};
+
+/**
+ * List available framework references (local + remote)
+ * @returns {string[]}
+ */
+function listAvailable() {
+  const names = new Set(Object.keys(REMOTE_SOURCES));
+
+  if (existsSync(REFERENCES_DIR)) {
+    for (const f of readdirSync(REFERENCES_DIR)) {
+      if (f.endsWith('.md')) {
+        names.add(basename(f, '.md'));
+      }
+    }
+  }
+
+  return [...names];
+}
+
+/**
+ * Get framework reference content
+ * @param {Object} options
+ * @param {string} [options.framework] - Explicit framework name
+ * @param {string} [options.path] - Project path for auto-detection
+ * @returns {Promise<Object>}
+ */
+export async function getFrameworkReference(options = {}) {
+  const available = listAvailable();
+
+  // Explicit framework requested
+  if (options.framework) {
+    if (!available.includes(options.framework)) {
+      return {
+        error: `Framework reference '${options.framework}' not found`,
+        available,
+      };
+    }
+
+    const { content, source } = await fetchReference(options.framework);
+    if (!content) {
+      return { error: `Failed to load reference '${options.framework}'`, available };
+    }
+
+    return {
+      framework: options.framework,
+      source,
+      lines: content.split('\n').length,
+      content,
+    };
+  }
+
+  // Auto-detect from project path
+  if (options.path) {
+    const { detected, reasons } = detectProjectRuleSets(options.path);
+
+    const matchedRefs = [];
+    for (const ruleset of detected) {
+      const refName = RULESET_TO_REFERENCE[ruleset];
+      if (refName && available.includes(refName) && !matchedRefs.includes(refName)) {
+        matchedRefs.push(refName);
+      }
+    }
+
+    if (matchedRefs.length === 0) {
+      return {
+        error: 'No framework references found for this project',
+        detected,
+        reasons,
+        available,
+      };
+    }
+
+    const results = await Promise.all(matchedRefs.map(fetchReference));
+    const contents = results.map(r => r.content).filter(Boolean);
+    const sources = results.map(r => r.source);
+
+    return {
+      frameworks: matchedRefs,
+      sources,
+      detected: { rulesets: detected, reasons },
+      lines: contents.reduce((sum, c) => sum + c.split('\n').length, 0),
+      content: contents.join('\n\n---\n\n'),
+    };
+  }
+
+  // No framework specified — list available
+  return {
+    error: 'Specify framework name or path for auto-detection',
+    available: available.map(name => ({
+      name,
+      remote: !!REMOTE_SOURCES[name],
+      url: REMOTE_SOURCES[name] ?? null,
+    })),
+  };
+}

package/src/full-analysis.js

@@ -0,0 +1,159 @@
+/**
+ * Full Analysis - Comprehensive Code Health Report
+ * Runs all analysis tools and generates a health score
+ */
+
+import { getDeadCode } from './dead-code.js';
+import { getUndocumentedSummary } from './undocumented.js';
+import { getSimilarFunctions } from './similar-functions.js';
+import { getComplexity } from './complexity.js';
+import { getLargeFiles } from './large-files.js';
+import { getOutdatedPatterns } from './outdated-patterns.js';
+
+/**
+ * @typedef {Object} AnalysisResult
+ * @property {Object} deadCode
+ * @property {Object} undocumented
+ * @property {Object} similar
+ * @property {Object} complexity
+ * @property {Object} largeFiles
+ * @property {Object} outdated
+ * @property {Object} overall
+ */
+
+/**
+ * Calculate health score from analysis results
+ * @param {Object} results 
+ * @returns {{score: number, rating: string, topIssues: string[]}}
+ */
+function calculateHealthScore(results) {
+  let score = 100;
+  const topIssues = [];
+
+  // Dead code penalty: -2 per item (max -20)
+  const deadPenalty = Math.min(results.deadCode.total * 2, 20);
+  score -= deadPenalty;
+  if (results.deadCode.total > 0) {
+    topIssues.push(`${results.deadCode.total} unused functions/classes`);
+  }
+
+  // Undocumented penalty: -0.5 per item (max -15)
+  const undocPenalty = Math.min(results.undocumented.total * 0.5, 15);
+  score -= undocPenalty;
+  if (results.undocumented.total > 10) {
+    topIssues.push(`${results.undocumented.total} undocumented items`);
+  }
+
+  // Similar functions penalty: -3 per pair (max -15)
+  const similarPenalty = Math.min(results.similar.total * 3, 15);
+  score -= similarPenalty;
+  if (results.similar.total > 0) {
+    topIssues.push(`${results.similar.total} similar function pairs`);
+  }
+
+  // Complexity penalty: -5 per critical, -2 per high (max -20)
+  const criticalCount = results.complexity.stats?.critical || 0;
+  const highCount = results.complexity.stats?.high || 0;
+  const complexityPenalty = Math.min(criticalCount * 5 + highCount * 2, 20);
+  score -= complexityPenalty;
+  if (criticalCount > 0) {
+    topIssues.push(`${criticalCount} critical complexity functions`);
+  }
+
+  // Large files penalty: -4 per critical, -1 per warning (max -10)
+  const largeCritical = results.largeFiles.stats?.critical || 0;
+  const largeWarning = results.largeFiles.stats?.warning || 0;
+  const largePenalty = Math.min(largeCritical * 4 + largeWarning * 1, 10);
+  score -= largePenalty;
+  if (largeCritical > 0) {
+    topIssues.push(`${largeCritical} files need splitting`);
+  }
+
+  // Outdated patterns penalty: -3 per error, -1 per warning (max -10)
+  const errorPatterns = results.outdated.stats?.bySeverity?.error || 0;
+  const warningPatterns = results.outdated.stats?.bySeverity?.warning || 0;
+  const outdatedPenalty = Math.min(errorPatterns * 3 + warningPatterns * 1, 10);
+  score -= outdatedPenalty;
+  if (results.outdated.redundantDeps.length > 0) {
+    topIssues.push(`${results.outdated.redundantDeps.length} redundant npm dependencies`);
+  }
+
+  // Clamp score
+  score = Math.max(0, Math.min(100, Math.round(score)));
+
+  // Determine rating
+  let rating;
+  if (score >= 90) rating = 'excellent';
+  else if (score >= 70) rating = 'good';
+  else if (score >= 50) rating = 'warning';
+  else rating = 'critical';
+
+  return { score, rating, topIssues: topIssues.slice(0, 5) };
+}
+
+/**
+ * Run full analysis on directory
+ * @param {string} dir 
+ * @param {Object} [options]
+ * @param {boolean} [options.includeItems=false] - Include individual items
+ * @returns {Promise<AnalysisResult>}
+ */
+export async function getFullAnalysis(dir, options = {}) {
+  const includeItems = options.includeItems || false;
+
+  // Run all analyses in parallel
+  const [deadCode, undocumented, similar, complexity, largeFiles, outdated] = await Promise.all([
+    getDeadCode(dir),
+    getUndocumentedSummary(dir, 'tests'),
+    getSimilarFunctions(dir, { threshold: 70 }),
+    getComplexity(dir, { minComplexity: 5 }),
+    getLargeFiles(dir),
+    getOutdatedPatterns(dir),
+  ]);
+
+  // Calculate overall health
+  const overall = calculateHealthScore({
+    deadCode,
+    undocumented,
+    similar,
+    complexity,
+    largeFiles,
+    outdated,
+  });
+
+  // Build result
+  const result = {
+    deadCode: {
+      total: deadCode.total,
+      byType: deadCode.byType,
+      ...(includeItems && { items: deadCode.items.slice(0, 10) }),
+    },
+    undocumented: {
+      total: undocumented.total,
+      byType: undocumented.byType,
+      ...(includeItems && { items: undocumented.items.slice(0, 10) }),
+    },
+    similar: {
+      total: similar.total,
+      ...(includeItems && { pairs: similar.pairs.slice(0, 5) }),
+    },
+    complexity: {
+      total: complexity.total,
+      stats: complexity.stats,
+      ...(includeItems && { items: complexity.items.slice(0, 10) }),
+    },
+    largeFiles: {
+      total: largeFiles.total,
+      stats: largeFiles.stats,
+      ...(includeItems && { items: largeFiles.items.slice(0, 10) }),
+    },
+    outdated: {
+      totalPatterns: outdated.stats.totalPatterns,
+      redundantDeps: outdated.redundantDeps,
+      ...(includeItems && { codePatterns: outdated.codePatterns.slice(0, 10) }),
+    },
+    overall,
+  };
+
+  return result;
+}

package/src/graph-builder.js

@@ -0,0 +1,269 @@
+/**
+ * Graph Builder - Creates minified project graph from parsed data
+ */
+
+/**
+ * @typedef {Object} GraphNode
+ * @property {string} t - type (class/func)
+ * @property {string} [x] - extends
+ * @property {string[]} [m] - methods
+ * @property {string[]} [$] - properties (init$)
+ * @property {string[]} [i] - imports
+ * @property {string[]} [→] - calls (outgoing)
+ * @property {string[]} [←] - usedBy (incoming)
+ * @property {string} [f] - source file path
+ * @property {boolean} [e] - exported flag (functions)
+ */
+
+/**
+ * @typedef {Object} Graph
+ * @property {number} v - version
+ * @property {Object<string, string>} legend - minified name → full name
+ * @property {Object<string, string>} reverseLegend - full name → minified
+ * @property {Object} stats - { files, classes, functions }
+ * @property {Object<string, GraphNode>} nodes
+ * @property {Array<[string, string, string]>} edges - [from, type, to]
+ * @property {string[]} orphans
+ * @property {Object<string, string[]>} duplicates
+ * @property {string[]} files - list of parsed file paths
+ */
+
+/**
+ * Create minified legend from names
+ * Strategy: Use camelCase initials + suffix if collision
+ * @param {string[]} names 
+ * @returns {Object<string, string>}
+ */
+export function minifyLegend(names) {
+  const legend = {};
+  const used = new Set();
+
+  for (const name of names) {
+    let short = createShortName(name);
+    let suffix = 1;
+
+    while (used.has(short)) {
+      short = createShortName(name) + suffix;
+      suffix++;
+    }
+
+    used.add(short);
+    legend[name] = short;
+  }
+
+  return legend;
+}
+
+/**
+ * Create short name from full name
+ * SymNode → SN, togglePin → tP, autoArrange → aA
+ * @param {string} name 
+ * @returns {string}
+ */
+function createShortName(name) {
+  // For PascalCase: extract uppercase letters
+  const upperOnly = name.replace(/[a-z]/g, '');
+  if (upperOnly.length >= 2) {
+    return upperOnly.slice(0, 3);
+  }
+
+  // For camelCase: first letter + next uppercase
+  const firstUpper = name.match(/[A-Z]/g);
+  if (firstUpper && firstUpper.length > 0) {
+    return name[0].toLowerCase() + firstUpper[0];
+  }
+
+  // Fallback: first 2 letters
+  return name.slice(0, 2);
+}
+
+/**
+ * Build graph from parsed project data
+ * @param {import('./parser.js').ParseResult} parsed 
+ * @returns {Graph}
+ */
+export function buildGraph(parsed) {
+  // Collect all names for legend
+  const classes = parsed.classes || [];
+  const functions = parsed.functions || [];
+
+  const allNames = [
+    ...classes.map(c => c.name),
+    ...functions.map(f => f.name),
+    ...classes.flatMap(c => c.methods || []),
+  ];
+
+  const legend = minifyLegend([...new Set(allNames)]);
+  const reverseLegend = Object.fromEntries(
+    Object.entries(legend).map(([k, v]) => [v, k])
+  );
+
+  const graph = {
+    v: 1,
+    legend,
+    reverseLegend,
+    stats: {
+      files: (parsed.files || []).length,
+      classes: classes.length,
+      functions: functions.length,
+    },
+    nodes: {},
+    edges: [],
+    orphans: [],
+    duplicates: {},
+    files: parsed.files || [],
+  };
+
+  // Build class nodes
+  for (const cls of classes) {
+    const shortName = legend[cls.name];
+    graph.nodes[shortName] = {
+      t: 'C',
+      x: cls.extends || undefined,
+      m: (cls.methods || []).map(m => legend[m] || m),
+      $: (cls.properties || []).length ? cls.properties : undefined,
+      i: cls.imports?.length ? cls.imports : undefined,
+      f: cls.file || undefined,
+    };
+
+    // Build edges from calls
+    for (const call of cls.calls || []) {
+      if (call.includes('.')) {
+        // Class.method() pattern
+        const [target, method] = call.split('.');
+        if (legend[target]) {
+          const edge = [shortName, '→', `${legend[target]}.${legend[method] || method}`];
+          graph.edges.push(edge);
+        }
+      } else {
+        // Standalone function call
+        if (legend[call]) {
+          const edge = [shortName, '→', legend[call]];
+          graph.edges.push(edge);
+        }
+      }
+    }
+  }
+
+  // Build function nodes
+  for (const func of functions) {
+    const shortName = legend[func.name];
+    graph.nodes[shortName] = {
+      t: 'F',
+      e: func.exported,
+      f: func.file || undefined,
+    };
+  }
+
+  // Detect orphans (nodes with no incoming edges)
+  const hasIncoming = new Set();
+  for (const edge of graph.edges) {
+    const target = edge[2].split('.')[0];
+    hasIncoming.add(target);
+  }
+
+  for (const name of Object.keys(graph.nodes)) {
+    if (!hasIncoming.has(name) && graph.nodes[name].t === 'F' && !graph.nodes[name].e) {
+      graph.orphans.push(reverseLegend[name]);
+    }
+  }
+
+  // Detect duplicates (same method name in multiple classes)
+  const methodLocations = {};
+  for (const cls of classes) {
+    for (const method of cls.methods || []) {
+      if (!methodLocations[method]) {
+        methodLocations[method] = [];
+      }
+      methodLocations[method].push(`${cls.name}:${cls.line}`);
+    }
+  }
+
+  for (const [method, locations] of Object.entries(methodLocations)) {
+    if (locations.length > 1) {
+      graph.duplicates[method] = locations;
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Create compact skeleton (minimal tokens)
+ * @param {Graph} graph 
+ * @returns {Object}
+ */
+export function createSkeleton(graph) {
+  const legend = {};
+  const nodes = {};
+
+  // Build class nodes with file path
+  // graph.legend = {fullName → shortName}
+  for (const [full, short] of Object.entries(graph.legend)) {
+    const node = graph.nodes[short];
+    if (!node) continue;
+
+    if (node.t === 'C') {
+      // Skip empty classes (0 methods, 0 props)
+      const methodCount = node.m?.length || 0;
+      const propCount = node.$?.length || 0;
+      if (methodCount === 0 && propCount === 0) continue;
+
+      legend[short] = full;
+      const entry = { m: methodCount };
+      if (propCount > 0) entry.$ = propCount;
+      if (node.f) entry.f = node.f;
+      nodes[short] = entry;
+    }
+  }
+
+  // Build exported functions grouped by file: { "file.js": ["shortName1", ...] }
+  // Also add function names to legend
+  const exportsByFile = {};
+  for (const [full, short] of Object.entries(graph.legend)) {
+    const node = graph.nodes[short];
+    if (node?.t === 'F' && node.e) {
+      legend[short] = full;
+      const file = node.f || '?';
+      if (!exportsByFile[file]) exportsByFile[file] = [];
+      exportsByFile[file].push(short);
+    }
+  }
+
+  // Build file tree grouped by directory (only files not covered by n/X)
+  const coveredFiles = new Set();
+  for (const v of Object.values(nodes)) {
+    if (v.f) coveredFiles.add(v.f);
+  }
+  for (const file of Object.keys(exportsByFile)) {
+    coveredFiles.add(file);
+  }
+
+  const fileTree = {};
+  for (const filePath of graph.files || []) {
+    if (coveredFiles.has(filePath)) continue;
+    const lastSlash = filePath.lastIndexOf('/');
+    const dir = lastSlash >= 0 ? filePath.slice(0, lastSlash + 1) : './';
+    const file = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath;
+    if (!fileTree[dir]) fileTree[dir] = [];
+    fileTree[dir].push(file);
+  }
+
+  const result = {
+    v: graph.v,
+    L: legend,
+    s: graph.stats,
+    n: nodes,
+    X: exportsByFile,
+    e: graph.edges.length,
+    o: graph.orphans.length,
+    d: Object.keys(graph.duplicates).length,
+  };
+
+  // Only add uncovered files if there are any
+  if (Object.keys(fileTree).length > 0) {
+    result.f = fileTree;
+  }
+
+  return result;
+}