@grafema/core 0.2.5-beta → 0.2.7

package/src/plugins/validation/PackageCoverageValidator.ts

@@ -0,0 +1,181 @@
+/**
+ * PackageCoverageValidator -- creates ISSUE nodes for external packages
+ * that are imported but have no semantic analyzer configured (REG-259).
+ *
+ * Reads the 'coverage:packages' resource from ResourceRegistry (populated
+ * by Orchestrator from plugin metadata `covers` fields) and compares
+ * against all IMPORT nodes with non-relative, non-builtin sources.
+ *
+ * Creates ONE issue:coverage ISSUE node per unique uncovered package
+ * (not per file or per import).
+ *
+ * Phase: VALIDATION
+ */
+
+import { builtinModules } from 'module';
+import { Plugin, createSuccessResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+import type { Resource } from '@grafema/types';
+
+/** Resource ID for the covered packages set. */
+export const COVERED_PACKAGES_RESOURCE_ID = 'coverage:packages';
+
+/**
+ * Resource containing the set of package names covered by semantic analyzers.
+ * Populated by Orchestrator before the VALIDATION phase.
+ */
+export interface CoveredPackagesResource extends Resource {
+  readonly id: typeof COVERED_PACKAGES_RESOURCE_ID;
+  readonly packages: ReadonlySet<string>;
+}
+
+/** Factory for creating an empty CoveredPackagesResource. */
+export function createCoveredPackagesResource(packages: Set<string>): CoveredPackagesResource {
+  return {
+    id: COVERED_PACKAGES_RESOURCE_ID,
+    packages,
+  };
+}
+
+/** Set of Node.js builtin module names (without 'node:' prefix). */
+const NODE_BUILTINS = new Set(builtinModules);
+
+/**
+ * Check if an import source is a relative path (starts with . or /).
+ */
+function isRelativeImport(source: string): boolean {
+  return source.startsWith('.') || source.startsWith('/');
+}
+
+/**
+ * Check if an import source is a Node.js builtin module.
+ * Handles the 'node:' prefix and subpath imports like 'fs/promises'.
+ */
+function isBuiltinModule(source: string): boolean {
+  if (source.startsWith('node:')) {
+    return true;
+  }
+  // Handle subpath imports like 'fs/promises' -> check 'fs'
+  const baseModule = source.split('/')[0];
+  return NODE_BUILTINS.has(baseModule);
+}
+
+/**
+ * Extract the package name from an import source.
+ * Handles scoped packages (@scope/pkg) and subpath imports (lodash/map).
+ *
+ * Examples:
+ *   'lodash'          -> 'lodash'
+ *   'lodash/map'      -> 'lodash'
+ *   '@prisma/client'  -> '@prisma/client'
+ *   '@scope/pkg/util' -> '@scope/pkg'
+ */
+function extractPackageName(source: string): string {
+  if (source.startsWith('@')) {
+    // Scoped package: @scope/pkg or @scope/pkg/subpath
+    const parts = source.split('/');
+    // Package name is @scope/pkg (first two parts)
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : source;
+  }
+  // Regular package: pkg or pkg/subpath
+  return source.split('/')[0];
+}
+
+export class PackageCoverageValidator extends Plugin {
+  get metadata(): PluginMetadata {
+    return {
+      name: 'PackageCoverageValidator',
+      phase: 'VALIDATION',
+      dependencies: [],
+      creates: {
+        nodes: ['ISSUE'],
+        edges: ['AFFECTS'],
+      },
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const { graph } = context;
+    const logger = this.log(context);
+
+    // Get covered packages from ResourceRegistry
+    const resource = context.resources?.get<CoveredPackagesResource>(COVERED_PACKAGES_RESOURCE_ID);
+    const coveredPackages = resource?.packages ?? new Set<string>();
+
+    logger.info('Starting package coverage check', {
+      coveredPackages: coveredPackages.size,
+    });
+
+    // Collect all external packages and track uncovered ones
+    const importedPackageNames = new Set<string>();
+    const uncoveredPackages = new Map<string, { file: string; line: number }>();
+
+    for await (const node of graph.queryNodes({ type: 'IMPORT' })) {
+      const source = (node as unknown as { source?: string }).source;
+      if (!source) continue;
+
+      // Skip relative imports
+      if (isRelativeImport(source)) continue;
+
+      // Skip Node.js builtins
+      if (isBuiltinModule(source)) continue;
+
+      const packageName = extractPackageName(source);
+      importedPackageNames.add(packageName);
+
+      // Skip if already covered by a semantic analyzer
+      if (coveredPackages.has(packageName)) continue;
+
+      // Track first occurrence for the issue location
+      if (!uncoveredPackages.has(packageName)) {
+        uncoveredPackages.set(packageName, {
+          file: node.file || '',
+          line: node.line || 0,
+        });
+      }
+    }
+
+    // Report one issue per unique uncovered package
+    let issueCount = 0;
+
+    for (const [packageName, location] of uncoveredPackages) {
+      if (context.reportIssue) {
+        await context.reportIssue({
+          category: 'coverage',
+          severity: 'warning',
+          message: `Package '${packageName}' is imported but no semantic analyzer is configured for it`,
+          file: location.file,
+          line: location.line,
+          context: {
+            type: 'UNCOVERED_PACKAGE',
+            packageName,
+          },
+        });
+        issueCount++;
+      }
+    }
+
+    const coveredCount = [...importedPackageNames].filter(p => coveredPackages.has(p)).length;
+
+    const summary = {
+      importedPackages: importedPackageNames.size,
+      coveredPackages: coveredCount,
+      uncoveredPackages: uncoveredPackages.size,
+      issuesCreated: issueCount,
+    };
+
+    if (uncoveredPackages.size > 0) {
+      logger.info('Uncovered packages found', {
+        count: uncoveredPackages.size,
+        packages: [...uncoveredPackages.keys()],
+      });
+    } else {
+      logger.info('All external packages are covered');
+    }
+
+    return createSuccessResult(
+      { nodes: issueCount, edges: issueCount },
+      { summary }
+    );
+  }
+}

package/src/plugins/validation/UnconnectedRouteValidator.ts

@@ -0,0 +1,93 @@
+/**
+ * UnconnectedRouteValidator -- creates ISSUE nodes for customer-facing routes
+ * that have no frontend consumers (REG-256).
+ *
+ * Only checks routes marked with customerFacing: true (set by ServiceConnectionEnricher).
+ * Routes without the flag are considered internal and don't raise issues.
+ *
+ * Creates issue:connectivity ISSUE nodes with AFFECTS edges to flagged routes.
+ *
+ * Phase: VALIDATION
+ */
+
+import { Plugin, createSuccessResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+
+interface RouteNode {
+  id: string;
+  type: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  method?: string;
+  path?: string;
+  fullPath?: string;
+  customerFacing?: boolean;
+}
+
+export class UnconnectedRouteValidator extends Plugin {
+  get metadata(): PluginMetadata {
+    return {
+      name: 'UnconnectedRouteValidator',
+      phase: 'VALIDATION',
+      dependencies: [],
+      creates: {
+        nodes: ['ISSUE'],
+        edges: ['AFFECTS'],
+      },
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const { graph } = context;
+    const logger = this.log(context);
+
+    logger.info('Starting unconnected route check');
+
+    let issueCount = 0;
+
+    for await (const node of graph.queryNodes({ type: 'http:route' })) {
+      const route = node as unknown as RouteNode;
+
+      // Only check customer-facing routes
+      if (!route.customerFacing) continue;
+
+      // Check for incoming INTERACTS_WITH edges (frontend consumers)
+      const incoming = await graph.getIncomingEdges(route.id, ['INTERACTS_WITH']);
+
+      if (incoming.length === 0) {
+        const routePath = route.fullPath || route.path || '';
+        const method = route.method || 'UNKNOWN';
+
+        if (context.reportIssue) {
+          await context.reportIssue({
+            category: 'connectivity',
+            severity: 'warning',
+            message: `Customer-facing route ${method} ${routePath} has no frontend consumers`,
+            file: route.file || '',
+            line: route.line || 0,
+            column: route.column || 0,
+            targetNodeId: route.id,
+            context: {
+              type: 'UNCONNECTED_CUSTOMER_ROUTE',
+              method,
+              path: routePath,
+            },
+          });
+          issueCount++;
+        }
+      }
+    }
+
+    if (issueCount > 0) {
+      logger.info('Unconnected customer-facing routes found', { count: issueCount });
+    } else {
+      logger.info('No unconnected customer-facing routes');
+    }
+
+    return createSuccessResult(
+      { nodes: issueCount, edges: issueCount },
+      { issueCount }
+    );
+  }
+}

package/src/queries/NodeContext.ts

@@ -0,0 +1,277 @@
+/**
+ * Node Context — shared data logic for building node neighborhood context
+ *
+ * Extracts source code preview and all incoming/outgoing edges
+ * for a given node, grouped by edge type.
+ *
+ * Used by CLI (grafema context) and MCP (get_context tool).
+ * Consumers handle their own formatting; this module provides data only.
+ *
+ * @module queries/NodeContext
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+
+// ---------------------------------------------------------------------------
+// Minimal backend interface (matches project pattern — loose coupling)
+// ---------------------------------------------------------------------------
+
+interface GraphBackend {
+  getNode(id: string): Promise<BaseNodeRecord | null>;
+  getOutgoingEdges(
+    nodeId: string,
+    edgeTypes?: string[] | null,
+  ): Promise<EdgeRecord[]>;
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes?: string[] | null,
+  ): Promise<EdgeRecord[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Edge types that are structural/containment — shown in compact form.
+ * These describe HOW code is nested, not WHAT it does.
+ */
+export const STRUCTURAL_EDGE_TYPES = new Set([
+  'CONTAINS',
+  'HAS_SCOPE',
+  'DECLARES',
+  'DEFINES',
+  'HAS_CONDITION',
+  'HAS_CASE',
+  'HAS_DEFAULT',
+  'HAS_CONSEQUENT',
+  'HAS_ALTERNATE',
+  'HAS_BODY',
+  'HAS_INIT',
+  'HAS_UPDATE',
+  'HAS_CATCH',
+  'HAS_FINALLY',
+  'HAS_PARAMETER',
+  'HAS_PROPERTY',
+  'HAS_ELEMENT',
+  'USES',
+  'GOVERNS',
+  'VIOLATES',
+  'AFFECTS',
+  'UNKNOWN',
+]);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EdgeWithNode {
+  edge: EdgeRecord;
+  node: BaseNodeRecord | null;
+}
+
+export interface EdgeGroup {
+  edgeType: string;
+  edges: EdgeWithNode[];
+}
+
+export interface SourcePreview {
+  file: string;
+  startLine: number;
+  endLine: number;
+  lines: string[];
+}
+
+export interface NodeContext {
+  node: BaseNodeRecord;
+  source: SourcePreview | null;
+  outgoing: EdgeGroup[];
+  incoming: EdgeGroup[];
+}
+
+export interface BuildNodeContextOptions {
+  /** Lines of context before the highlighted line (default: 3) */
+  contextLines?: number;
+  /** Filter to only these edge types (null = show all) */
+  edgeTypeFilter?: Set<string> | null;
+  /**
+   * DI callback for reading file content.
+   * Return file content as string, or null if file can't be read.
+   * Default uses fs.readFileSync.
+   */
+  readFileContent?: (filePath: string) => string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Default file reader
+// ---------------------------------------------------------------------------
+
+function defaultReadFileContent(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core function
+// ---------------------------------------------------------------------------
+
+/**
+ * Build full node context: source preview + all edges with connected nodes.
+ *
+ * @param backend  - Graph backend for queries
+ * @param node     - The node to build context for (already looked up by caller)
+ * @param options  - Context options
+ * @returns NodeContext with source preview and grouped edges
+ */
+export async function buildNodeContext(
+  backend: GraphBackend,
+  node: BaseNodeRecord,
+  options: BuildNodeContextOptions = {},
+): Promise<NodeContext> {
+  const {
+    contextLines = 3,
+    edgeTypeFilter = null,
+    readFileContent = defaultReadFileContent,
+  } = options;
+
+  // Source code preview
+  let source: SourcePreview | null = null;
+  if (node.file && node.line) {
+    const content = readFileContent(node.file);
+    if (content) {
+      const allLines = content.split('\n');
+      const line = node.line as number;
+      const startLine = Math.max(1, line - contextLines);
+      const endLine = Math.min(allLines.length, line + contextLines + 12);
+      source = {
+        file: node.file,
+        startLine,
+        endLine,
+        lines: allLines.slice(startLine - 1, endLine),
+      };
+    }
+  }
+
+  // Outgoing edges
+  const rawOutgoing = await backend.getOutgoingEdges(node.id);
+  const outgoing = await groupEdges(backend, rawOutgoing, 'dst', edgeTypeFilter);
+
+  // Incoming edges
+  const rawIncoming = await backend.getIncomingEdges(node.id);
+  const incoming = await groupEdges(backend, rawIncoming, 'src', edgeTypeFilter);
+
+  return { node, source, outgoing, incoming };
+}
+
+// ---------------------------------------------------------------------------
+// Edge grouping
+// ---------------------------------------------------------------------------
+
+/**
+ * Group edges by type and resolve connected nodes.
+ *
+ * Sort order: non-structural edges first (alphabetical),
+ * then structural edges (alphabetical).
+ */
+async function groupEdges(
+  backend: GraphBackend,
+  edges: EdgeRecord[],
+  nodeField: 'src' | 'dst',
+  edgeTypeFilter: Set<string> | null,
+): Promise<EdgeGroup[]> {
+  const groups = new Map<string, EdgeWithNode[]>();
+
+  for (const edge of edges) {
+    const edgeType = edge.type || 'UNKNOWN';
+
+    // Apply edge type filter
+    if (edgeTypeFilter && !edgeTypeFilter.has(edgeType)) continue;
+
+    const connectedId = edge[nodeField];
+    const connectedNode = await backend.getNode(connectedId);
+
+    if (!groups.has(edgeType)) {
+      groups.set(edgeType, []);
+    }
+    groups.get(edgeType)!.push({ edge, node: connectedNode });
+  }
+
+  // Sort groups: primary edges first, then structural
+  return Array.from(groups.entries())
+    .sort(([a], [b]) => {
+      const aStructural = STRUCTURAL_EDGE_TYPES.has(a);
+      const bStructural = STRUCTURAL_EDGE_TYPES.has(b);
+      if (aStructural !== bStructural) return aStructural ? 1 : -1;
+      return a.localeCompare(b);
+    })
+    .map(([edgeType, edgeList]) => ({ edgeType, edges: edgeList }));
+}
+
+// ---------------------------------------------------------------------------
+// Display helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get display name for a node based on its type.
+ *
+ * Special cases:
+ * - HTTP routes: "METHOD /path"
+ * - HTTP requests: "METHOD url"
+ * - Socket.IO: event name
+ * - Default: node.name or node.id
+ */
+export function getNodeDisplayName(node: BaseNodeRecord): string {
+  // HTTP nodes: method + path/url
+  if (node.type === 'http:route') {
+    const method = node.method as string | undefined;
+    const path = node.path as string | undefined;
+    if (method && path) return `${method} ${path}`;
+  }
+  if (node.type === 'http:request') {
+    const method = node.method as string | undefined;
+    const url = node.url as string | undefined;
+    if (method && url) return `${method} ${url}`;
+  }
+
+  // Socket.IO: event name
+  if (node.type === 'socketio:emit' || node.type === 'socketio:on') {
+    const event = node.event as string | undefined;
+    if (event) return event;
+  }
+
+  // Default: name or ID fallback
+  if (node.name && !node.name.startsWith('{')) return node.name;
+  return node.id;
+}
+
+/**
+ * Format edge metadata for inline display (only meaningful fields).
+ *
+ * Returns a string like "  [arg0]" or "" if no relevant metadata.
+ */
+export function formatEdgeMetadata(edge: EdgeRecord): string {
+  const parts: string[] = [];
+  const meta = edge.metadata || {};
+
+  if (edge.type === 'PASSES_ARGUMENT' || edge.type === 'RECEIVES_ARGUMENT') {
+    if ('argIndex' in meta) {
+      parts.push(`arg${meta.argIndex}`);
+    }
+  }
+  if (edge.type === 'FLOWS_INTO') {
+    if ('mutationMethod' in meta) parts.push(`via ${meta.mutationMethod}`);
+  }
+  if (edge.type === 'HAS_PROPERTY') {
+    if ('propertyName' in meta) parts.push(`key: ${meta.propertyName}`);
+  }
+  if (edge.type === 'ITERATES_OVER') {
+    if ('iterates' in meta) parts.push(`${meta.iterates}`);
+  }
+
+  return parts.length > 0 ? `  [${parts.join(', ')}]` : '';
+}

package/src/queries/findCallsInFunction.ts

@@ -41,6 +41,15 @@ interface GraphBackend {
   ): Promise<Array<{ src: string; dst: string; type: string }>>;
 }
 
+/**
+ * Maximum BFS depth for downward scope traversal.
+ *
+ * Each depth level = one CONTAINS hop through nested scopes.
+ * Typical function bodies: 2-5 scope levels (if → loop → try → ...).
+ * Set to 10 to cover deep nesting while bounding traversal in malformed graphs.
+ */
+const DEFAULT_MAX_SCOPE_DEPTH = 10;
+
 /**
  * Find all CALL and METHOD_CALL nodes inside a function.
  *
@@ -55,7 +64,7 @@ export async function findCallsInFunction(
   options: FindCallsOptions = {}
 ): Promise<CallInfo[]> {
   const {
-    maxDepth = 10,
+    maxDepth = DEFAULT_MAX_SCOPE_DEPTH,
     transitive = false,
     transitiveDepth = 5,
   } = options;
@@ -183,7 +192,7 @@ async function collectTransitiveCalls(
 
   // Find calls in this function (non-transitive to avoid recursion)
   const innerCalls = await findCallsInFunction(backend, functionId, {
-    maxDepth: 10,
+    maxDepth: DEFAULT_MAX_SCOPE_DEPTH,
     transitive: false,
   });
 

package/src/queries/findContainingFunction.ts

@@ -34,18 +34,29 @@ interface GraphBackend {
   ): Promise<Array<{ src: string; dst: string; type: string }>>;
 }
 
+/**
+ * Maximum BFS depth for upward containment traversal.
+ *
+ * Each depth level = one CONTAINS/HAS_SCOPE/DECLARES hop.
+ * Typical real-world nesting: 3-7 levels (function body → if → loop → try → ...).
+ * Set to 15 to handle pathological cases (deeply nested callbacks, complex control flow)
+ * while still bounding traversal in malformed graphs.
+ */
+const DEFAULT_MAX_DEPTH = 15;
+
 /**
  * Find the FUNCTION, CLASS, or MODULE that contains a node.
  *
  * @param backend - Graph backend for queries
  * @param nodeId - ID of the node to find container for
- * @param maxDepth - Maximum traversal depth (default: 15)
- * @returns CallerInfo or null if no container found
+ * @param maxDepth - Maximum traversal depth (default: {@link DEFAULT_MAX_DEPTH}).
+ *   Traversal visits depths 0 through maxDepth inclusive.
+ * @returns CallerInfo or null if no container found within maxDepth hops
  */
 export async function findContainingFunction(
   backend: GraphBackend,
   nodeId: string,
-  maxDepth: number = 15
+  maxDepth: number = DEFAULT_MAX_DEPTH
 ): Promise<CallerInfo | null> {
   const visited = new Set<string>();
   const queue: Array<{ id: string; depth: number }> = [{ id: nodeId, depth: 0 }];

package/src/queries/index.ts

@@ -10,8 +10,21 @@
 export { findCallsInFunction } from './findCallsInFunction.js';
 export { findContainingFunction } from './findContainingFunction.js';
 export { traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './traceValues.js';
+export {
+  buildNodeContext,
+  getNodeDisplayName,
+  formatEdgeMetadata,
+  STRUCTURAL_EDGE_TYPES,
+} from './NodeContext.js';
 
 export type { CallInfo, CallerInfo, FindCallsOptions } from './types.js';
+export type {
+  EdgeWithNode,
+  EdgeGroup,
+  SourcePreview,
+  NodeContext,
+  BuildNodeContextOptions,
+} from './NodeContext.js';
 export type {
   TracedValue,
   ValueSource,