project-graph-mcp 1.0.0

package/src/instructions.js

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

@@ -0,0 +1,214 @@
+/**
+ * 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;
+}

package/src/large-files.js

@@ -0,0 +1,162 @@
+/**
+ * Large Files Analyzer
+ * Identifies files that may need splitting
+ */
+
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { parse } from '../vendor/acorn.mjs';
+import * as walk from '../vendor/walk.mjs';
+import { shouldExcludeDir, shouldExcludeFile, parseGitignore } from './filters.js';
+
+/**
+ * @typedef {Object} LargeFileItem
+ * @property {string} file
+ * @property {number} lines
+ * @property {number} functions
+ * @property {number} classes
+ * @property {number} exports
+ * @property {string} rating - 'ok' | 'warning' | 'critical'
+ * @property {string[]} reasons
+ */
+
+/**
+ * Find all JS files
+ * @param {string} dir 
+ * @param {string} rootDir 
+ * @returns {string[]}
+ */
+function findJSFiles(dir, rootDir = dir) {
+  if (dir === rootDir) parseGitignore(rootDir);
+  const files = [];
+
+  try {
+    for (const entry of readdirSync(dir)) {
+      const fullPath = join(dir, entry);
+      const relativePath = relative(rootDir, fullPath);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        if (!shouldExcludeDir(entry, relativePath)) {
+          files.push(...findJSFiles(fullPath, rootDir));
+        }
+      } else if (entry.endsWith('.js') && !entry.endsWith('.css.js') && !entry.endsWith('.tpl.js')) {
+        if (!shouldExcludeFile(entry, relativePath)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  } catch (e) { }
+
+  return files;
+}
+
+/**
+ * Analyze a single file
+ * @param {string} filePath 
+ * @returns {LargeFileItem}
+ */
+function analyzeFile(filePath, rootDir) {
+  const code = readFileSync(filePath, 'utf-8');
+  const relPath = relative(rootDir, filePath);
+  const lines = code.split('\n').length;
+
+  let functions = 0;
+  let classes = 0;
+  let exports = 0;
+
+  let ast;
+  try {
+    ast = parse(code, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
+  } catch (e) {
+    return { file: relPath, lines, functions: 0, classes: 0, exports: 0, rating: 'ok', reasons: [] };
+  }
+
+  walk.simple(ast, {
+    FunctionDeclaration() { functions++; },
+    ArrowFunctionExpression(node) {
+      if (node.body.type === 'BlockStatement') functions++;
+    },
+    ClassDeclaration() { classes++; },
+    ExportNamedDeclaration() { exports++; },
+    ExportDefaultDeclaration() { exports++; },
+  });
+
+  // Calculate rating
+  const reasons = [];
+  let score = 0;
+
+  if (lines > 500) {
+    score += 2;
+    reasons.push(`${lines} lines (>500)`);
+  } else if (lines > 300) {
+    score += 1;
+    reasons.push(`${lines} lines (>300)`);
+  }
+
+  if (functions > 15) {
+    score += 2;
+    reasons.push(`${functions} functions (>15)`);
+  } else if (functions > 10) {
+    score += 1;
+    reasons.push(`${functions} functions (>10)`);
+  }
+
+  if (classes > 3) {
+    score += 2;
+    reasons.push(`${classes} classes (>3)`);
+  } else if (classes > 1) {
+    score += 1;
+    reasons.push(`${classes} classes (>1)`);
+  }
+
+  if (exports > 10) {
+    score += 2;
+    reasons.push(`${exports} exports (>10)`);
+  } else if (exports > 5) {
+    score += 1;
+    reasons.push(`${exports} exports (>5)`);
+  }
+
+  let rating = 'ok';
+  if (score >= 4) rating = 'critical';
+  else if (score >= 2) rating = 'warning';
+
+  return { file: relPath, lines, functions, classes, exports, rating, reasons };
+}
+
+/**
+ * Get large files analysis
+ * @param {string} dir 
+ * @param {Object} [options]
+ * @param {boolean} [options.onlyProblematic=false] - Only show warning/critical
+ * @returns {Promise<{total: number, stats: Object, items: LargeFileItem[]}>}
+ */
+export async function getLargeFiles(dir, options = {}) {
+  const onlyProblematic = options.onlyProblematic || false;
+  const resolvedDir = resolve(dir);
+  const files = findJSFiles(dir);
+  let items = files.map(f => analyzeFile(f, resolvedDir));
+
+  if (onlyProblematic) {
+    items = items.filter(i => i.rating !== 'ok');
+  }
+
+  // Sort by lines descending
+  items.sort((a, b) => b.lines - a.lines);
+
+  const stats = {
+    totalFiles: files.length,
+    ok: items.filter(i => i.rating === 'ok').length,
+    warning: items.filter(i => i.rating === 'warning').length,
+    critical: items.filter(i => i.rating === 'critical').length,
+    totalLines: items.reduce((s, i) => s + i.lines, 0),
+    avgLines: items.length > 0 ? Math.round(items.reduce((s, i) => s + i.lines, 0) / items.length) : 0,
+  };
+
+  return {
+    total: items.length,
+    stats,
+    items: items.slice(0, 30),
+  };
+}