@grafema/util 0.3.0-beta

package/src/core/CoverageAnalyzer.ts

@@ -0,0 +1,243 @@
+/**
+ * CoverageAnalyzer - Calculates analysis coverage for a project
+ *
+ * Determines which files in a project have been analyzed and categorizes
+ * files into three groups:
+ * - Analyzed: Files that appear as MODULE nodes in the graph
+ * - Unsupported: Files with extensions that no indexer can handle
+ * - Unreachable: Files with supported extensions but not in the graph
+ *
+ * Usage:
+ *   const analyzer = new CoverageAnalyzer(graphBackend, '/path/to/project');
+ *   const result = await analyzer.analyze();
+ */
+
+import { readdirSync, existsSync, lstatSync } from 'fs';
+import { join, relative, extname } from 'path';
+import type { GraphBackend } from '@grafema/types';
+
+/**
+ * Supported file extensions by language
+ */
+const JS_SUPPORTED = ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'];
+const RUST_SUPPORTED = ['.rs'];
+const SUPPORTED_EXTENSIONS = new Set([...JS_SUPPORTED, ...RUST_SUPPORTED]);
+
+/**
+ * Known code file extensions (for scanning)
+ * Files with these extensions are considered source code
+ */
+const CODE_EXTENSIONS = new Set([
+  // Supported
+  ...JS_SUPPORTED,
+  ...RUST_SUPPORTED,
+  // Unsupported but tracked
+  '.go', '.kt', '.java', '.py', '.rb', '.php', '.c', '.cpp', '.h', '.hpp',
+  '.cs', '.swift', '.scala', '.sql', '.graphql', '.gql',
+]);
+
+/**
+ * Directories to always skip during scanning
+ */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.grafema',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '.next',
+  '.nuxt',
+  '__pycache__',
+  'target', // Rust
+  'vendor',
+]);
+
+/**
+ * Coverage analysis result
+ */
+export interface CoverageResult {
+  projectPath: string;
+  total: number;
+  analyzed: {
+    count: number;
+    files: string[];
+  };
+  unsupported: {
+    count: number;
+    byExtension: Record<string, string[]>;
+  };
+  unreachable: {
+    count: number;
+    files: string[];
+    byExtension: Record<string, string[]>;
+  };
+  percentages: {
+    analyzed: number;
+    unsupported: number;
+    unreachable: number;
+  };
+}
+
+/**
+ * CoverageAnalyzer calculates what percentage of a codebase has been analyzed.
+ */
+export class CoverageAnalyzer {
+  private graph: GraphBackend;
+  private projectPath: string;
+
+  constructor(graph: GraphBackend, projectPath: string) {
+    this.graph = graph;
+    this.projectPath = projectPath;
+  }
+
+  /**
+   * Analyze the project and return coverage statistics
+   */
+  async analyze(): Promise<CoverageResult> {
+    // Step 1: Get all MODULE nodes from the graph
+    const analyzedFiles = await this.getAnalyzedFiles();
+    const analyzedSet = new Set(analyzedFiles);
+
+    // Step 2: Scan project for all code files
+    const allCodeFiles = this.scanProjectFiles();
+
+    // Step 3: Categorize files
+    const unsupportedByExt: Record<string, string[]> = {};
+    const unreachableByExt: Record<string, string[]> = {};
+    const unreachableFiles: string[] = [];
+
+    for (const file of allCodeFiles) {
+      if (analyzedSet.has(file)) {
+        continue; // Already analyzed
+      }
+
+      const ext = extname(file).toLowerCase();
+
+      if (SUPPORTED_EXTENSIONS.has(ext)) {
+        // Supported but not in graph = unreachable
+        unreachableFiles.push(file);
+        if (!unreachableByExt[ext]) {
+          unreachableByExt[ext] = [];
+        }
+        unreachableByExt[ext].push(file);
+      } else {
+        // Not supported = unsupported
+        if (!unsupportedByExt[ext]) {
+          unsupportedByExt[ext] = [];
+        }
+        unsupportedByExt[ext].push(file);
+      }
+    }
+
+    // Calculate counts
+    const unsupportedCount = Object.values(unsupportedByExt)
+      .reduce((sum, files) => sum + files.length, 0);
+    const unreachableCount = unreachableFiles.length;
+    const analyzedCount = analyzedFiles.length;
+    const total = analyzedCount + unsupportedCount + unreachableCount;
+
+    // Calculate percentages (handle division by zero)
+    const percentages = {
+      analyzed: total > 0 ? Math.round((analyzedCount / total) * 100) : 0,
+      unsupported: total > 0 ? Math.round((unsupportedCount / total) * 100) : 0,
+      unreachable: total > 0 ? Math.round((unreachableCount / total) * 100) : 0,
+    };
+
+    return {
+      projectPath: this.projectPath,
+      total,
+      analyzed: {
+        count: analyzedCount,
+        files: analyzedFiles,
+      },
+      unsupported: {
+        count: unsupportedCount,
+        byExtension: unsupportedByExt,
+      },
+      unreachable: {
+        count: unreachableCount,
+        files: unreachableFiles,
+        byExtension: unreachableByExt,
+      },
+      percentages,
+    };
+  }
+
+  /**
+   * Get list of analyzed files from the graph (MODULE nodes)
+   */
+  private async getAnalyzedFiles(): Promise<string[]> {
+    const files: string[] = [];
+
+    // Use queryNodes with type: 'MODULE'
+    for await (const node of this.graph.queryNodes({ type: 'MODULE' })) {
+      if (node.file) {
+        // Store relative path for consistency
+        const relativePath = node.file.startsWith(this.projectPath)
+          ? relative(this.projectPath, node.file)
+          : node.file;
+        files.push(relativePath);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Scan project directory for all code files
+   * Respects common ignore patterns (node_modules, .git, etc.)
+   */
+  private scanProjectFiles(): string[] {
+    const files: string[] = [];
+    this.walkDirectory(this.projectPath, files);
+    return files;
+  }
+
+  /**
+   * Recursively walk directory and collect code files
+   */
+  private walkDirectory(dir: string, files: string[], depth = 0): void {
+    // Safety: limit recursion depth
+    if (depth > 20) return;
+
+    if (!existsSync(dir)) return;
+
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return; // Skip directories we can't read
+    }
+
+    for (const entry of entries) {
+      // Skip hidden files and directories
+      if (entry.startsWith('.')) continue;
+
+      // Skip known non-source directories
+      if (SKIP_DIRS.has(entry)) continue;
+
+      const fullPath = join(dir, entry);
+
+      // Skip symlinks to avoid infinite loops
+      try {
+        const stat = lstatSync(fullPath);
+        if (stat.isSymbolicLink()) continue;
+
+        if (stat.isDirectory()) {
+          this.walkDirectory(fullPath, files, depth + 1);
+        } else if (stat.isFile()) {
+          const ext = extname(entry).toLowerCase();
+          if (CODE_EXTENSIONS.has(ext)) {
+            // Store relative path
+            files.push(relative(this.projectPath, fullPath));
+          }
+        }
+      } catch {
+        // Skip files we can't stat
+        continue;
+      }
+    }
+  }
+}

package/src/core/FileExplainer.ts

@@ -0,0 +1,179 @@
+/**
+ * FileExplainer - Show what nodes exist in a file for discovery
+ *
+ * Purpose: Help users discover what nodes exist in the graph for a file,
+ * displaying semantic IDs so users can query them.
+ *
+ * This addresses the core UX problem: users can't find nodes because
+ * semantic IDs are opaque (e.g., "src/app.ts->fetchData->try#0->VARIABLE->response").
+ * This tool shows what's in the graph so users know what they can query.
+ *
+ * @see _tasks/REG-177/006-don-revised-plan.md for design rationale
+ */
+
+import type { GraphBackend, BaseNodeRecord, NodeFilter } from '@grafema/types';
+
+/**
+ * Result of explaining a file's graph contents
+ */
+export interface FileExplainResult {
+  /** The file path that was explained */
+  file: string;
+  /** Whether the file has been analyzed */
+  status: 'ANALYZED' | 'NOT_ANALYZED';
+  /** All nodes in the graph for this file, enhanced with context */
+  nodes: EnhancedNode[];
+  /** Node counts grouped by type */
+  byType: Record<string, number>;
+  /** Total number of nodes in the file */
+  totalCount: number;
+}
+
+/**
+ * A node record enhanced with scope context information.
+ *
+ * The context field provides human-readable information about
+ * where the node appears (e.g., "inside try block", "catch parameter").
+ */
+export interface EnhancedNode extends BaseNodeRecord {
+  /** Human-readable context about the node's scope */
+  context?: string;
+}
+
+/**
+ * Scope patterns to detect from semantic IDs.
+ * Order matters - more specific patterns should come first.
+ */
+const SCOPE_PATTERNS: Array<{ pattern: RegExp; context: string }> = [
+  { pattern: /->catch#\d+->/, context: 'inside catch block' },
+  { pattern: /->try#\d+->/, context: 'inside try block' },
+  { pattern: /->if#\d+->/, context: 'inside conditional' },
+  { pattern: /->else#\d+->/, context: 'inside else block' },
+  { pattern: /->for#\d+->/, context: 'inside loop' },
+  { pattern: /->while#\d+->/, context: 'inside loop' },
+  { pattern: /->switch#\d+->/, context: 'inside switch' },
+];
+
+/**
+ * FileExplainer class - explains what nodes exist in a file's graph.
+ *
+ * Use this when:
+ * - User can't find a variable/function they expect to be in the graph
+ * - User wants to understand what's been analyzed for a file
+ * - User needs semantic IDs to construct queries
+ *
+ * Example:
+ * ```typescript
+ * const explainer = new FileExplainer(graphBackend);
+ * const result = await explainer.explain('src/app.ts');
+ *
+ * if (result.status === 'NOT_ANALYZED') {
+ *   console.log('File not in graph. Run: grafema analyze');
+ * } else {
+ *   for (const node of result.nodes) {
+ *     console.log(`[${node.type}] ${node.name}`);
+ *     console.log(`  ID: ${node.id}`);
+ *     if (node.context) {
+ *       console.log(`  Context: ${node.context}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FileExplainer {
+  constructor(private graph: GraphBackend) {}
+
+  /**
+   * Explain what nodes exist in the graph for a file.
+   *
+   * @param filePath - The file path to explain (relative or absolute)
+   * @returns FileExplainResult with all nodes, grouped by type, with context
+   */
+  async explain(filePath: string): Promise<FileExplainResult> {
+    // Query graph for all nodes in this file
+    const nodes = await this.getNodesForFile(filePath);
+
+    // Group by type
+    const byType = this.groupByType(nodes);
+
+    // Enhance with context from semantic ID parsing
+    const enhanced = this.enhanceWithContext(nodes);
+
+    // Sort nodes: by type, then by name
+    enhanced.sort((a, b) => {
+      const typeCompare = a.type.localeCompare(b.type);
+      if (typeCompare !== 0) return typeCompare;
+      return (a.name || '').localeCompare(b.name || '');
+    });
+
+    return {
+      file: filePath,
+      status: nodes.length > 0 ? 'ANALYZED' : 'NOT_ANALYZED',
+      nodes: enhanced,
+      byType,
+      totalCount: nodes.length,
+    };
+  }
+
+  /**
+   * Query graph for all nodes in a file
+   *
+   * Note: The server-side file filter may not work correctly in all cases,
+   * so we also filter client-side to ensure only nodes from the requested file are returned.
+   */
+  private async getNodesForFile(filePath: string): Promise<BaseNodeRecord[]> {
+    const filter: NodeFilter = { file: filePath };
+    const nodes: BaseNodeRecord[] = [];
+
+    for await (const node of this.graph.queryNodes(filter)) {
+      // Client-side filter as backup (server filter may not work correctly)
+      if (node.file === filePath) {
+        nodes.push(node);
+      }
+    }
+
+    return nodes;
+  }
+
+  /**
+   * Group nodes by type, counting occurrences
+   */
+  private groupByType(nodes: BaseNodeRecord[]): Record<string, number> {
+    const counts: Record<string, number> = {};
+
+    for (const node of nodes) {
+      const type = node.type || 'UNKNOWN';
+      counts[type] = (counts[type] || 0) + 1;
+    }
+
+    return counts;
+  }
+
+  /**
+   * Enhance nodes with human-readable scope context.
+   *
+   * Detects patterns in semantic IDs like:
+   * - "file->func->try#0->VARIABLE->x" → "inside try block"
+   * - "file->func->catch#0->VARIABLE->error" → "inside catch block"
+   */
+  private enhanceWithContext(nodes: BaseNodeRecord[]): EnhancedNode[] {
+    return nodes.map((node) => {
+      const context = this.detectScopeContext(node.id);
+      return context ? { ...node, context } : { ...node };
+    });
+  }
+
+  /**
+   * Detect scope context from semantic ID patterns.
+   *
+   * Returns human-readable context string or undefined if no special scope.
+   */
+  private detectScopeContext(semanticId: string): string | undefined {
+    for (const { pattern, context } of SCOPE_PATTERNS) {
+      if (pattern.test(semanticId)) {
+        return context;
+      }
+    }
+    return undefined;
+  }
+}