project-graph-mcp 1.3.0 → 2.0.0

package/src/graph-builder.js

@@ -1,299 +0,0 @@
-/**
- * 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, tables }
- * @property {Object<string, GraphNode>} nodes
- * @property {Array<[string, string, string]>} edges - [from, type, to] where type is →, R→, or W→
- * @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,
-      tables: (parsed.tables || []).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,
-    };
-
-    // Build DB edges from function SQL reads/writes
-    for (const table of func.dbReads || []) {
-      graph.edges.push([shortName, 'R→', table]);
-    }
-    for (const table of func.dbWrites || []) {
-      graph.edges.push([shortName, 'W→', table]);
-    }
-  }
-
-  // Build DB edges from class SQL reads/writes
-  for (const cls of classes) {
-    const shortName = legend[cls.name];
-    for (const table of cls.dbReads || []) {
-      graph.edges.push([shortName, 'R→', table]);
-    }
-    for (const table of cls.dbWrites || []) {
-      graph.edges.push([shortName, 'W→', table]);
-    }
-  }
-
-  // Build table nodes from parsed SQL files
-  for (const table of parsed.tables || []) {
-    graph.nodes[table.name] = {
-      t: 'T',
-      cols: table.columns.map(c => c.name),
-      f: table.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 = Object.create(null);
-  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;
-    }
-    // Skip Table nodes (T) — they only appear in dedicated DB tools
-  }
-
-  // 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;
-}

package/src/instructions.js

@@ -1,175 +0,0 @@
-/**
- * Project Guidelines and Instructions for AI Agents
- */
-
-export const AGENT_INSTRUCTIONS = `
-# 🤖 Project Guidelines for AI Agents
-
-## 1. Architecture Standards (Symbiote.js)
-- **Component Structure**: Always use Triple-File Partitioning for components:
-  - \`MyComponent.js\`: Class logic (extends Symbiote)
-  - \`MyComponent.tpl.js\`: HTML template (export template)
-  - \`MyComponent.css.js\`: CSS styles (export rootStyles/shadowStyles)
-- **State Management**: Use \`this.init$\` for local state and \`this.sub()\` for reactivity.
-- **Directives**: Use \`itemize\` for lists, \`js-d-kit\` for static generation.
-
-## 2. Test Annotations (@test/@expect)
-Universal verification checklist system. Works for **any** test type.
-
-### Syntax
-\`\`\`javascript
-/**
- * Method description
- * 
- * @test {type}: {description}
- * @expect {type}: {description}
- */
-async myMethod() { ... }
-\`\`\`
-
-### @test Types by Category
-
-#### 🌐 Browser / UI
-| Type | Description | Example |
-|------|-------------|---------|
-| \`click\` | Click element | \`@test click: Click submit button\` |
-| \`key\` | Keyboard input | \`@test key: Press Enter\` |
-| \`drag\` | Drag and drop | \`@test drag: Drag item to list\` |
-| \`type\` | Text input | \`@test type: Enter email in field\` |
-| \`scroll\` | Scroll action | \`@test scroll: Scroll to bottom\` |
-| \`hover\` | Mouse hover | \`@test hover: Hover over menu\` |
-
-#### 🔌 API / Function
-| Type | Description | Example |
-|------|-------------|---------|
-| \`request\` | HTTP request | \`@test request: POST /api/users\` |
-| \`call\` | Function call | \`@test call: Call with valid params\` |
-| \`invoke\` | Method invoke | \`@test invoke: Trigger event\` |
-| \`mock\` | Mock setup | \`@test mock: Mock external service\` |
-
-#### 💻 CLI / Process
-| Type | Description | Example |
-|------|-------------|---------|
-| \`run\` | Run command | \`@test run: Run with --help flag\` |
-| \`exec\` | Execute script | \`@test exec: Execute build script\` |
-| \`spawn\` | Spawn process | \`@test spawn: Start server\` |
-| \`input\` | Stdin input | \`@test input: Enter password\` |
-
-#### 🔗 Integration / System
-| Type | Description | Example |
-|------|-------------|---------|
-| \`setup\` | Test setup | \`@test setup: Create test database\` |
-| \`action\` | Main action | \`@test action: Run migration\` |
-| \`teardown\` | Cleanup | \`@test teardown: Remove temp files\` |
-| \`wait\` | Wait condition | \`@test wait: Wait for DB connection\` |
-
-### @expect Types by Category
-
-#### 🌐 Browser / UI
-| Type | Description | Example |
-|------|-------------|---------|
-| \`attr\` | Attribute check | \`@expect attr: disabled attribute set\` |
-| \`visual\` | Visual change | \`@expect visual: Button turns green\` |
-| \`element\` | Element exists | \`@expect element: Modal appears\` |
-| \`text\` | Text content | \`@expect text: Shows "Success"\` |
-
-#### 🔌 API / Function
-| Type | Description | Example |
-|------|-------------|---------|
-| \`status\` | HTTP status | \`@expect status: 201 Created\` |
-| \`body\` | Response body | \`@expect body: Contains user ID\` |
-| \`headers\` | Response headers | \`@expect headers: Content-Type JSON\` |
-| \`error\` | Error thrown | \`@expect error: Throws ValidationError\` |
-
-#### 💻 CLI / Process
-| Type | Description | Example |
-|------|-------------|---------|
-| \`output\` | Stdout content | \`@expect output: Prints version\` |
-| \`exitcode\` | Exit code | \`@expect exitcode: Returns 0\` |
-| \`file\` | File created | \`@expect file: Creates config.json\` |
-| \`stderr\` | Stderr content | \`@expect stderr: No errors\` |
-
-#### 🔗 Integration / System
-| Type | Description | Example |
-|------|-------------|---------|
-| \`state\` | State change | \`@expect state: User logged in\` |
-| \`log\` | Log entry | \`@expect log: Info message logged\` |
-| \`event\` | Event fired | \`@expect event: 'updated' emitted\` |
-| \`db\` | Database change | \`@expect db: Row inserted\` |
-
-### Full Example
-\`\`\`javascript
-/**
- * Create new user via API
- * 
- * @test request: POST /api/users with valid data
- * @test call: Validate email format
- * 
- * @expect status: 201 Created
- * @expect body: Contains user ID and email
- * @expect db: User row created in database
- * @expect event: 'user.created' event emitted
- */
-async createUser(data) {
-  // ...
-}
-\`\`\`
-
-## 3. General Coding Rules
-- **ESM Only**: Use \`import\` / \`export\`. No \`require\`.
-- **No Dependencies**: Avoid adding new npm packages unless critical.
-- **Comments**: Write clear JSDoc for all public methods.
-- **Async/Await**: Prefer async/await over promises.
-
-## 4. MCP Tools Usage
-- **Graph**: Use \`get_skeleton\` first to map the codebase.
-- **Deep Dive**: Use \`expand\` to read class details.
-- **Tests**: Use \`get_pending_tests\` to see what needs verification.
-- **Guidelines**: Use \`get_agent_instructions\` to refresh these rules.
-
-## 5. Custom Rules System
-Configurable code analysis with auto-detection.
-
-### Available Tools
-- \`get_custom_rules\`: List all rulesets and their rules
-- \`set_custom_rule\`: Add or update a rule in a ruleset
-- \`check_custom_rules\`: Run analysis (auto-detects applicable rulesets)
-
-### Auto-Detection
-Rulesets are applied automatically based on:
-1. \`package.json\` dependencies
-2. Import patterns in source code
-3. Code patterns (e.g., \`extends Symbiote\`)
-
-### Creating New Rules
-Use \`set_custom_rule\` to add framework-specific rules:
-\`\`\`json
-{
-  "ruleSet": "my-framework-2x",
-  "rule": {
-    "id": "my-rule-id",
-    "name": "Rule Name",
-    "description": "What this rule checks",
-    "pattern": "badPattern",
-    "patternType": "string",
-    "replacement": "Use goodPattern instead",
-    "severity": "warning",
-    "filePattern": "*.js",
-    "docs": "https://docs.example.com/rule"
-  }
-}
-\`\`\`
-
-### Severity Levels
-- \`error\`: Critical issues that must be fixed
-- \`warning\`: Important but not blocking
-- \`info\`: Suggestions and best practices
-`;
-
-/**
- * Get agent instructions
- * @returns {string}
- */
-export function getInstructions() {
-  return AGENT_INSTRUCTIONS;
-}

package/src/jsdoc-generator.js

@@ -1,214 +0,0 @@
-/**
- * JSDoc Generator
- * Auto-generates JSDoc templates from AST analysis
- */
-
-import { readFileSync } from 'fs';
-import { relative } from 'path';
-import { parse } from '../vendor/acorn.mjs';
-import * as walk from '../vendor/walk.mjs';
-import { getWorkspaceRoot } from './workspace.js';
-
-/**
- * @typedef {Object} JSDocTemplate
- * @property {string} name - Function/method name
- * @property {string} type - 'function' | 'method' | 'class'
- * @property {string} file
- * @property {number} line
- * @property {string} jsdoc - Generated JSDoc template
- */
-
-/**
- * Generate JSDoc for a single file
- * @param {string} filePath - Absolute path to file
- * @param {Object} [options]
- * @param {boolean} [options.includeTests=true] - Include @test/@expect placeholders
- * @returns {JSDocTemplate[]}
- */
-export function generateJSDoc(filePath, options = {}) {
-  const includeTests = options.includeTests !== false;
-  const results = [];
-
-  const code = readFileSync(filePath, 'utf-8');
-  const relPath = relative(getWorkspaceRoot(), filePath);
-
-  let ast;
-  try {
-    ast = parse(code, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
-  } catch (e) {
-    return results;
-  }
-
-  // Check if line already has JSDoc
-  const hasJSDocAt = (line) => {
-    const lines = code.split('\n');
-    // Look backwards from function line for JSDoc closing */
-    for (let i = line - 2; i >= Math.max(0, line - 15); i--) {
-      const trimmed = lines[i]?.trim();
-      if (!trimmed) continue; // Skip empty lines
-      // Found JSDoc end - look for start
-      if (trimmed === '*/' || trimmed.endsWith('*/')) {
-        // Now look for /** opening above
-        for (let j = i - 1; j >= Math.max(0, i - 20); j--) {
-          const upper = lines[j]?.trim();
-          if (upper?.startsWith('/**')) return true;
-          // If we hit something non-JSDoc, stop
-          if (upper && !upper.startsWith('*')) break;
-        }
-        return false;
-      }
-      // If we hit code, stop
-      if (!trimmed.startsWith('*') && !trimmed.startsWith('//')) break;
-    }
-    return false;
-  };
-
-  walk.simple(ast, {
-    FunctionDeclaration(node) {
-      if (!node.id) return;
-      if (hasJSDocAt(node.loc.start.line)) return;
-
-      const jsdoc = buildJSDoc({
-        name: node.id.name,
-        params: node.params,
-        async: node.async,
-        includeTests,
-      });
-
-      results.push({
-        name: node.id.name,
-        type: 'function',
-        file: relPath,
-        line: node.loc.start.line,
-        jsdoc,
-      });
-    },
-
-    ClassDeclaration(node) {
-      if (!node.id) return;
-
-      // Check methods
-      for (const element of node.body.body) {
-        if (element.type === 'MethodDefinition') {
-          const methodName = element.key.name || element.key.value;
-
-          // Skip constructor, getters, setters, private
-          if (element.kind !== 'method') continue;
-          if (methodName.startsWith('_')) continue;
-          if (hasJSDocAt(element.loc.start.line)) continue;
-
-          const funcNode = element.value;
-          const jsdoc = buildJSDoc({
-            name: methodName,
-            params: funcNode.params,
-            async: funcNode.async,
-            includeTests,
-          });
-
-          results.push({
-            name: `${node.id.name}.${methodName}`,
-            type: 'method',
-            file: relPath,
-            line: element.loc.start.line,
-            jsdoc,
-          });
-        }
-      }
-    },
-  });
-
-  return results;
-}
-
-/**
- * Build JSDoc string from function info
- * @param {Object} info
- * @param {string} info.name
- * @param {Array} info.params
- * @param {boolean} info.async
- * @param {boolean} info.includeTests
- * @returns {string}
- */
-function buildJSDoc(info) {
-  const lines = ['/**'];
-
-  // Description placeholder
-  lines.push(` * TODO: Add description for ${info.name}`);
-
-  // Parameters
-  for (const param of info.params) {
-    const paramName = extractParamName(param);
-    const paramType = inferParamType(param);
-    lines.push(` * @param {${paramType}} ${paramName}`);
-  }
-
-  // Return type
-  lines.push(` * @returns {${info.async ? 'Promise<*>' : '*'}}`);
-
-  // Test annotations (Agentic Verification)
-  if (info.includeTests) {
-    lines.push(` * @test TODO: describe test scenario`);
-    lines.push(` * @expect TODO: expected result`);
-  }
-
-  lines.push(' */');
-  return lines.join('\n');
-}
-
-/**
- * Extract parameter name from AST node
- * @param {Object} param 
- * @returns {string}
- */
-function extractParamName(param) {
-  if (param.type === 'Identifier') {
-    return param.name;
-  }
-  if (param.type === 'AssignmentPattern' && param.left.type === 'Identifier') {
-    return `[${param.left.name}]`; // Optional param
-  }
-  if (param.type === 'RestElement' && param.argument.type === 'Identifier') {
-    return `...${param.argument.name}`;
-  }
-  if (param.type === 'ObjectPattern') {
-    return 'options';
-  }
-  if (param.type === 'ArrayPattern') {
-    return 'args';
-  }
-  return 'param';
-}
-
-/**
- * Infer parameter type from AST
- * @param {Object} param 
- * @returns {string}
- */
-function inferParamType(param) {
-  if (param.type === 'AssignmentPattern') {
-    const defaultVal = param.right;
-    if (defaultVal.type === 'Literal') {
-      if (typeof defaultVal.value === 'string') return 'string';
-      if (typeof defaultVal.value === 'number') return 'number';
-      if (typeof defaultVal.value === 'boolean') return 'boolean';
-    }
-    if (defaultVal.type === 'ArrayExpression') return 'Array';
-    if (defaultVal.type === 'ObjectExpression') return 'Object';
-  }
-  if (param.type === 'RestElement') return 'Array';
-  if (param.type === 'ObjectPattern') return 'Object';
-  if (param.type === 'ArrayPattern') return 'Array';
-  return '*';
-}
-
-/**
- * Generate JSDoc for specific function by name
- * @param {string} filePath 
- * @param {string} functionName 
- * @param {Object} [options]
- * @returns {JSDocTemplate|null}
- */
-export function generateJSDocFor(filePath, functionName, options = {}) {
-  const results = generateJSDoc(filePath, options);
-  return results.find(r => r.name === functionName || r.name.endsWith(`.${functionName}`)) || null;
-}