project-graph-mcp 1.5.0 → 2.0.0

package/src/undocumented.js

@@ -1,259 +0,0 @@
-/**
- * Undocumented Code Finder (AST-based)
- * Finds methods/functions missing JSDoc annotations using Acorn AST parser
- */
-
-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} UndocumentedItem
- * @property {string} name - ClassName.methodName or functionName
- * @property {string} type - 'method' | 'function' | 'class'
- * @property {string} file
- * @property {number} line
- * @property {string} reason - What's missing
- */
-
-/**
- * Find all JS files in directory
- * @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) {
-    // Directory not found
-  }
-
-  return files;
-}
-
-/**
- * Extract JSDoc comments from code with their positions
- * @param {string} code 
- * @returns {Array<{text: string, endLine: number}>}
- */
-function extractComments(code) {
-  const comments = [];
-  const regex = /\/\*\*[\s\S]*?\*\//g;
-  let match;
-
-  while ((match = regex.exec(code)) !== null) {
-    const endLine = code.slice(0, match.index + match[0].length).split('\n').length;
-    comments.push({ text: match[0], endLine });
-  }
-
-  return comments;
-}
-
-/**
- * Find JSDoc comment before a target line
- * @param {Array<{text: string, endLine: number}>} comments - Extracted JSDoc comments
- * @param {number} targetLine - Line number to search before
- * @returns {string|null}
- */
-function findJSDocBefore(comments, targetLine) {
-  for (const comment of comments) {
-    const gap = targetLine - comment.endLine;
-    if (gap >= 0 && gap <= 2) {
-      return comment.text;
-    }
-  }
-  return null;
-}
-
-/**
- * Check what's missing from JSDoc based on level
- * @param {string|null} jsdoc 
- * @param {'tests'|'params'|'all'} level 
- * @returns {string[]}
- */
-function checkMissing(jsdoc, level) {
-  const missing = [];
-
-  if (!jsdoc) {
-    if (level === 'all') missing.push('description');
-    if (level === 'params' || level === 'all') missing.push('@param', '@returns');
-    return missing;
-  }
-
-  if (level === 'params' || level === 'all') {
-    if (!jsdoc.includes('@param')) missing.push('@param');
-    if (!jsdoc.includes('@returns') && !jsdoc.includes('@return')) missing.push('@returns');
-  }
-
-  return missing;
-}
-
-/** Skip list for methods */
-const SKIP_METHODS = [
-  'constructor', 'connectedCallback', 'disconnectedCallback',
-  'attributeChangedCallback', 'renderCallback',
-];
-
-/**
- * Parse file using AST and find undocumented items (per-file export for cache integration)
- * @param {string} code 
- * @param {string} filePath 
- * @param {'tests'|'params'|'all'} level
- * @returns {UndocumentedItem[]}
- */
-export function checkUndocumentedFile(code, filePath, level) {
-  const results = [];
-
-  let ast;
-  try {
-    ast = parse(code, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
-  } catch (e) {
-    return results;
-  }
-
-  const comments = extractComments(code);
-
-  walk.simple(ast, {
-    ClassDeclaration(node) {
-      const className = node.id?.name || 'Anonymous';
-
-      // Check class itself (only for 'all' level)
-      if (level === 'all') {
-        const classJsdoc = findJSDocBefore(comments, node.loc.start.line);
-        if (!classJsdoc) {
-          results.push({
-            name: className,
-            type: 'class',
-            file: filePath,
-            line: node.loc.start.line,
-            reason: 'No JSDoc',
-          });
-        }
-      }
-
-      // Check methods
-      for (const element of node.body.body) {
-        if (element.type === 'MethodDefinition') {
-          const methodName = element.key.name || element.key.value;
-
-          // Skip: constructor, private, getters/setters, lifecycle
-          if (element.kind === 'get' || element.kind === 'set') continue;
-          if (methodName?.startsWith('_')) continue;
-          if (SKIP_METHODS.includes(methodName)) continue;
-
-          const jsdoc = findJSDocBefore(comments, element.loc.start.line);
-          const missing = checkMissing(jsdoc, level);
-
-          if (missing.length > 0) {
-            results.push({
-              name: `${className}.${methodName}`,
-              type: 'method',
-              file: filePath,
-              line: element.loc.start.line,
-              reason: missing.join(', '),
-            });
-          }
-        }
-      }
-    },
-
-    FunctionDeclaration(node) {
-      if (!node.id) return;
-      const funcName = node.id.name;
-
-      // Skip private functions
-      if (funcName.startsWith('_')) return;
-
-      const jsdoc = findJSDocBefore(comments, node.loc.start.line);
-      const missing = checkMissing(jsdoc, level);
-
-      if (missing.length > 0) {
-        results.push({
-          name: funcName,
-          type: 'function',
-          file: filePath,
-          line: node.loc.start.line,
-          reason: missing.join(', '),
-        });
-      }
-    },
-  });
-
-  return results;
-}
-
-/**
- * Get undocumented items from directory
- * @param {string} dir 
- * @param {'tests'|'params'|'all'} level
- * @returns {UndocumentedItem[]}
- */
-export function getUndocumented(dir, level = 'tests') {
-  const resolvedDir = resolve(dir);
-  const files = findJSFiles(dir);
-  const results = [];
-
-  for (const file of files) {
-    let content;
-    try {
-      content = readFileSync(file, 'utf-8');
-    } catch (e) {
-      continue; // File deleted between findJSFiles and read
-    }
-    const items = checkUndocumentedFile(content, relative(resolvedDir, file), level);
-    results.push(...items);
-  }
-
-  return results;
-}
-
-/**
- * Get summary of undocumented items
- * @param {string} dir 
- * @param {'tests'|'params'|'all'} level
- * @returns {Object}
- */
-export function getUndocumentedSummary(dir, level = 'tests') {
-  const items = getUndocumented(dir, level);
-
-  const byType = {
-    class: items.filter(i => i.type === 'class').length,
-    function: items.filter(i => i.type === 'function').length,
-    method: items.filter(i => i.type === 'method').length,
-  };
-
-  const byReason = {};
-  for (const item of items) {
-    byReason[item.reason] = (byReason[item.reason] || 0) + 1;
-  }
-
-  return {
-    total: items.length,
-    byType,
-    byReason,
-    items: items.slice(0, 20),
-  };
-}

package/src/workspace.js

@@ -1,70 +0,0 @@
-/**
- * Workspace Root Resolution
- * 
- * Resolves relative paths against the correct workspace root.
- * Priority: MCP initialize roots → --workspace arg → PROJECT_ROOT env → process.cwd()
- */
-
-import { resolve, isAbsolute } from 'path';
-
-/** @type {string|null} */
-let workspaceRoot = null;
-
-// Auto-detect --workspace arg at module load
-const wsArg = process.argv.find(a => a.startsWith('--workspace='));
-if (wsArg) {
-  workspaceRoot = wsArg.split('=')[1];
-  console.error(`[project-graph] Workspace from arg: ${workspaceRoot}`);
-}
-
-/**
- * Set workspace root from MCP initialize roots
- * @param {Array<{uri: string, name?: string}>} roots
- */
-export function setRoots(roots) {
-  if (roots && roots.length > 0) {
-    let uri = roots[0].uri;
-    // Strip file:// protocol if present
-    if (uri.startsWith('file://')) {
-      uri = uri.slice(7);
-    }
-    workspaceRoot = uri;
-    console.error(`[project-graph] Workspace root: ${workspaceRoot}`);
-  }
-}
-
-/**
- * Get current workspace root
- * @returns {string}
- */
-export function getWorkspaceRoot() {
-  if (workspaceRoot) {
-    return workspaceRoot;
-  }
-  if (process.env.PROJECT_ROOT) {
-    return process.env.PROJECT_ROOT;
-  }
-  return process.cwd();
-}
-
-/**
- * Resolve a path argument against workspace root.
- * Absolute paths are returned as-is.
- * Relative paths are resolved against the workspace root.
- * @param {string} inputPath
- * @returns {string}
- */
-export function resolvePath(inputPath) {
-  if (!inputPath) {
-    return getWorkspaceRoot();
-  }
-  const root = getWorkspaceRoot();
-  const resolved = isAbsolute(inputPath) ? inputPath : resolve(root, inputPath);
-
-  // Prevent path traversal — resolved path must stay within workspace
-  if (!resolved.startsWith(root)) {
-    throw new Error(`Path traversal blocked: '${inputPath}' resolves outside workspace root '${root}'`);
-  }
-
-  return resolved;
-}