@grafema/util 0.3.0-beta

package/src/core/nodes/IssueNode.ts

@@ -0,0 +1,177 @@
+/**
+ * IssueNode - contract for issue:* nodes
+ *
+ * Types: issue:security, issue:performance, issue:style, issue:smell
+ * ID format: issue:<category>#<hash>
+ *
+ * Issues represent detected problems in the codebase.
+ * They connect to affected code via AFFECTS edges.
+ */
+
+import { createHash } from 'crypto';
+import type { BaseNodeRecord } from '@grafema/types';
+import { getNamespace } from './NodeKind.js';
+
+// Severity type
+export type IssueSeverity = 'error' | 'warning' | 'info';
+
+// Issue types
+export type IssueType = `issue:${string}`;
+
+export interface IssueNodeRecord extends BaseNodeRecord {
+  type: IssueType;
+  severity: IssueSeverity;
+  category: string;
+  message: string;
+  plugin: string;
+  targetNodeId?: string;
+  createdAt: number;
+  context?: Record<string, unknown>;
+}
+
+export interface IssueNodeOptions {
+  context?: Record<string, unknown>;
+}
+
+// Valid severity levels
+const VALID_SEVERITIES = ['error', 'warning', 'info'] as const;
+
+export class IssueNode {
+  static readonly REQUIRED = ['category', 'severity', 'message', 'plugin', 'file'] as const;
+  static readonly OPTIONAL = ['targetNodeId', 'context'] as const;
+
+  /**
+   * Generate deterministic issue ID
+   * Format: issue:<category>#<hash12>
+   *
+   * Hash is based on plugin + file + line + column + message
+   * This ensures same issue = same ID across analysis runs
+   */
+  static generateId(
+    category: string,
+    plugin: string,
+    file: string,
+    line: number,
+    column: number,
+    message: string
+  ): string {
+    const hashInput = `${plugin}|${file}|${line}|${column}|${message}`;
+    const hash = createHash('sha256').update(hashInput).digest('hex').substring(0, 12);
+    return `issue:${category}#${hash}`;
+  }
+
+  /**
+   * Create issue node
+   *
+   * @param category - Issue category (security, performance, style, smell, or custom)
+   * @param severity - error | warning | info
+   * @param message - Human-readable description
+   * @param plugin - Plugin name that detected this issue
+   * @param file - File where issue was detected
+   * @param line - Line number
+   * @param column - Column number (optional, defaults to 0)
+   * @param options - Optional fields (context)
+   */
+  static create(
+    category: string,
+    severity: IssueSeverity,
+    message: string,
+    plugin: string,
+    file: string,
+    line: number,
+    column: number = 0,
+    options: IssueNodeOptions = {}
+  ): IssueNodeRecord {
+    if (!category) throw new Error('IssueNode.create: category is required');
+    if (!severity) throw new Error('IssueNode.create: severity is required');
+    if (!VALID_SEVERITIES.includes(severity)) {
+      throw new Error(`IssueNode.create: invalid severity "${severity}". Valid: ${VALID_SEVERITIES.join(', ')}`);
+    }
+    if (!message) throw new Error('IssueNode.create: message is required');
+    if (!plugin) throw new Error('IssueNode.create: plugin is required');
+    if (!file) throw new Error('IssueNode.create: file is required');
+
+    const type = `issue:${category}` as IssueType;
+    const id = this.generateId(category, plugin, file, line, column, message);
+    const now = Date.now();
+
+    return {
+      id,
+      type,
+      name: message.substring(0, 100), // Truncate for display
+      file,
+      line,
+      column,
+      severity,
+      category,
+      message,
+      plugin,
+      createdAt: now,
+      context: options.context,
+    };
+  }
+
+  /**
+   * Validate issue node
+   * @returns array of error messages, empty if valid
+   */
+  static validate(node: IssueNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!IssueNode.isIssueType(node.type)) {
+      errors.push(`Expected issue:* type, got ${node.type}`);
+    }
+
+    if (!node.category) {
+      errors.push('Missing required field: category');
+    }
+
+    if (!node.severity) {
+      errors.push('Missing required field: severity');
+    } else if (!VALID_SEVERITIES.includes(node.severity as IssueSeverity)) {
+      errors.push(`Invalid severity: ${node.severity}. Valid: ${VALID_SEVERITIES.join(', ')}`);
+    }
+
+    if (!node.message) {
+      errors.push('Missing required field: message');
+    }
+
+    if (!node.plugin) {
+      errors.push('Missing required field: plugin');
+    }
+
+    return errors;
+  }
+
+  /**
+   * Parse issue ID into components
+   * @param id - full ID (e.g., 'issue:security#a3f2b1c4d5e6')
+   * @returns { category, hash } or null if invalid
+   */
+  static parseId(id: string): { category: string; hash: string } | null {
+    if (!id) return null;
+
+    const match = id.match(/^issue:([^#]+)#(.+)$/);
+    if (!match) return null;
+
+    return {
+      category: match[1],
+      hash: match[2],
+    };
+  }
+
+  /**
+   * Check if type is an issue type
+   */
+  static isIssueType(type: string): boolean {
+    if (!type) return false;
+    return getNamespace(type) === 'issue';
+  }
+
+  /**
+   * Get all known issue categories
+   */
+  static getCategories(): string[] {
+    return ['security', 'performance', 'style', 'smell'];
+  }
+}

package/src/core/nodes/NodeKind.ts

@@ -0,0 +1,192 @@
+/**
+ * Node Types - string type system for nodes
+ *
+ * Base types: FUNCTION, CLASS, METHOD, etc.
+ * Namespaced types: http:route, socketio:emit, express:router, etc.
+ *
+ * Namespace convention:
+ * - http:* - HTTP endpoints and requests
+ * - express:* - Express.js specifics
+ * - socketio:* - Socket.IO
+ * - db:* - Database queries
+ * - fs:* - Filesystem operations
+ */
+
+// === BASE TYPES ===
+// Abstract types, not tied to language or framework
+
+export const NODE_TYPE = {
+  // Core code entities
+  FUNCTION: 'FUNCTION',
+  CLASS: 'CLASS',
+  METHOD: 'METHOD',
+  VARIABLE: 'VARIABLE',
+  PARAMETER: 'PARAMETER',
+  CONSTANT: 'CONSTANT',
+  LITERAL: 'LITERAL',
+  EXPRESSION: 'EXPRESSION',  // Generic expression node for data flow tracking
+  TYPE_PARAMETER: 'TYPE_PARAMETER',
+
+  // Module system
+  MODULE: 'MODULE',
+  IMPORT: 'IMPORT',
+  EXPORT: 'EXPORT',
+
+  // Call graph
+  CALL: 'CALL', // unified METHOD_CALL + CALL_SITE
+
+  // Project structure
+  PROJECT: 'PROJECT',
+  SERVICE: 'SERVICE',
+  FILE: 'FILE',
+  SCOPE: 'SCOPE',
+
+  // External dependencies
+  EXTERNAL: 'EXTERNAL',
+  EXTERNAL_MODULE: 'EXTERNAL_MODULE',
+
+  // Generic side effects
+  SIDE_EFFECT: 'SIDE_EFFECT',
+} as const;
+
+export type BaseNodeType = typeof NODE_TYPE[keyof typeof NODE_TYPE];
+
+// === NAMESPACED TYPES ===
+// Types specific to frameworks and libraries
+
+export const NAMESPACED_TYPE = {
+  // HTTP (generic)
+  HTTP_ROUTE: 'http:route',
+  HTTP_REQUEST: 'http:request',
+
+  // Express.js
+  EXPRESS_ROUTER: 'express:router',
+  EXPRESS_MIDDLEWARE: 'express:middleware',
+  EXPRESS_MOUNT: 'express:mount',
+
+  // Socket.IO
+  SOCKETIO_EMIT: 'socketio:emit',
+  SOCKETIO_ON: 'socketio:on',
+  SOCKETIO_NAMESPACE: 'socketio:namespace',
+
+  // Database
+  DB_QUERY: 'db:query',
+  DB_CONNECTION: 'db:connection',
+
+  // Redis
+  REDIS_READ: 'redis:read',
+  REDIS_WRITE: 'redis:write',
+  REDIS_DELETE: 'redis:delete',
+  REDIS_PUBLISH: 'redis:publish',
+  REDIS_SUBSCRIBE: 'redis:subscribe',
+  REDIS_TRANSACTION: 'redis:transaction',
+  REDIS_CONNECTION: 'redis:connection',
+
+  // Filesystem
+  FS_READ: 'fs:read',
+  FS_WRITE: 'fs:write',
+  FS_OPERATION: 'fs:operation',
+
+  // Network
+  NET_REQUEST: 'net:request',
+  NET_STDIO: 'net:stdio',
+
+  // Events
+  EVENT_LISTENER: 'event:listener',
+  EVENT_EMIT: 'event:emit',
+
+  // Guarantees (contract-based)
+  GUARANTEE_QUEUE: 'guarantee:queue',
+  GUARANTEE_API: 'guarantee:api',
+  GUARANTEE_PERMISSION: 'guarantee:permission',
+
+  // Grafema internal (self-describing pipeline)
+  GRAFEMA_PLUGIN: 'grafema:plugin',
+} as const;
+
+export type NamespacedNodeType = typeof NAMESPACED_TYPE[keyof typeof NAMESPACED_TYPE];
+
+// Combined node type
+export type NodeType = BaseNodeType | NamespacedNodeType | string;
+
+// === HELPERS ===
+
+/**
+ * Check if type is namespaced (contains :)
+ */
+export function isNamespacedType(nodeType: string): boolean {
+  return nodeType !== undefined && nodeType !== null && nodeType.includes(':');
+}
+
+/**
+ * Get namespace from type
+ * @returns namespace or null for base types
+ */
+export function getNamespace(nodeType: string): string | null {
+  if (!nodeType || !nodeType.includes(':')) return null;
+  return nodeType.split(':')[0];
+}
+
+/**
+ * Get base name from namespaced type
+ */
+export function getBaseName(nodeType: string): string {
+  if (!nodeType) return '';
+  if (!nodeType.includes(':')) return nodeType;
+  return nodeType.split(':').slice(1).join(':');
+}
+
+/**
+ * Check if type is an endpoint (HTTP route, WebSocket handler, etc.)
+ */
+export function isEndpointType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  const ns = getNamespace(nodeType);
+  return ns === 'http' || ns === 'express' || ns === 'socketio';
+}
+
+/**
+ * Check if type is a side effect (DB, FS, Network)
+ */
+export function isSideEffectType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  if (nodeType === NODE_TYPE.SIDE_EFFECT) return true;
+  const ns = getNamespace(nodeType);
+  return ns === 'db' || ns === 'fs' || ns === 'net' || ns === 'redis';
+}
+
+/**
+ * Check if type matches a pattern with wildcard
+ * @param nodeType - node type
+ * @param pattern - pattern (e.g., "http:*", "FUNCTION")
+ */
+export function matchesTypePattern(nodeType: string, pattern: string): boolean {
+  if (!nodeType || !pattern) return false;
+
+  // Exact match
+  if (nodeType === pattern) return true;
+
+  // Wildcard match (e.g., "http:*" matches "http:route")
+  if (pattern.endsWith(':*')) {
+    const patternNs = pattern.slice(0, -2);
+    return getNamespace(nodeType) === patternNs;
+  }
+
+  return false;
+}
+
+/**
+ * Check if type is a guarantee type (guarantee:queue, guarantee:api, etc.)
+ */
+export function isGuaranteeType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  return getNamespace(nodeType) === 'guarantee';
+}
+
+/**
+ * Check if type is a grafema internal type (grafema:plugin, etc.)
+ */
+export function isGrafemaType(nodeType: string): boolean {
+  if (!nodeType) return false;
+  return getNamespace(nodeType) === 'grafema';
+}

package/src/diagnostics/DiagnosticCollector.ts

@@ -0,0 +1,170 @@
+/**
+ * DiagnosticCollector - Collects and filters diagnostics from plugin execution
+ *
+ * The DiagnosticCollector aggregates errors from PluginResult.errors[],
+ * converting both GrafemaError instances (with rich info) and plain Error
+ * instances (treated as generic errors) into unified Diagnostic entries.
+ *
+ * Usage:
+ *   const collector = new DiagnosticCollector();
+ *   collector.addFromPluginResult('INDEXING', 'JSModuleIndexer', result);
+ *
+ *   if (collector.hasFatal()) {
+ *     throw new Error('Fatal error detected');
+ *   }
+ *
+ *   console.log(collector.toDiagnosticsLog());
+ */
+
+import type { PluginPhase, PluginResult } from '@grafema/types';
+import { GrafemaError, type ResolutionStep, type ResolutionFailureReason } from '../errors/GrafemaError.js';
+
+/**
+ * Diagnostic entry - unified format for all errors/warnings
+ */
+export interface Diagnostic {
+  code: string;
+  severity: 'fatal' | 'error' | 'warning' | 'info';
+  message: string;
+  file?: string;
+  line?: number;
+  phase: PluginPhase;
+  plugin: string;
+  timestamp: number;
+  suggestion?: string;
+  /** Resolution chain for context (REG-332) */
+  resolutionChain?: ResolutionStep[];
+  /** Failure reason for context-aware suggestions (REG-332) */
+  failureReason?: ResolutionFailureReason;
+}
+
+/**
+ * Diagnostic input (without timestamp, which is auto-generated)
+ */
+export type DiagnosticInput = Omit<Diagnostic, 'timestamp'>;
+
+/**
+ * DiagnosticCollector - collects, filters, and formats diagnostics
+ */
+export class DiagnosticCollector {
+  private diagnostics: Diagnostic[] = [];
+
+  /**
+   * Extract errors from PluginResult and add as diagnostics.
+   *
+   * GrafemaError instances provide rich info (code, severity, context, suggestion).
+   * Plain Error instances are treated as generic errors with code 'ERR_UNKNOWN'.
+   */
+  addFromPluginResult(phase: PluginPhase, plugin: string, result: PluginResult): void {
+    for (const error of result.errors) {
+      if (error instanceof GrafemaError) {
+        this.add({
+          code: error.code,
+          severity: error.severity,
+          message: error.message,
+          file: error.context.filePath,
+          line: error.context.lineNumber,
+          phase,
+          plugin,
+          suggestion: error.suggestion,
+          // REG-332: Pass through resolution context
+          resolutionChain: error.context.resolutionChain as ResolutionStep[] | undefined,
+          failureReason: error.context.failureReason as ResolutionFailureReason | undefined,
+        });
+      } else {
+        // Plain Error - treat as generic error
+        this.add({
+          code: 'ERR_UNKNOWN',
+          severity: 'error',
+          message: error.message,
+          phase,
+          plugin,
+        });
+      }
+    }
+  }
+
+  /**
+   * Add a diagnostic directly.
+   * Timestamp is set automatically.
+   */
+  add(diagnostic: DiagnosticInput): void {
+    this.diagnostics.push({
+      ...diagnostic,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Get all diagnostics.
+   * Returns a copy to prevent external modification.
+   */
+  getAll(): Diagnostic[] {
+    return [...this.diagnostics];
+  }
+
+  /**
+   * Get diagnostics filtered by phase.
+   */
+  getByPhase(phase: PluginPhase): Diagnostic[] {
+    return this.diagnostics.filter(d => d.phase === phase);
+  }
+
+  /**
+   * Get diagnostics filtered by plugin name (case-sensitive).
+   */
+  getByPlugin(plugin: string): Diagnostic[] {
+    return this.diagnostics.filter(d => d.plugin === plugin);
+  }
+
+  /**
+   * Get diagnostics filtered by error code.
+   */
+  getByCode(code: string): Diagnostic[] {
+    return this.diagnostics.filter(d => d.code === code);
+  }
+
+  /**
+   * Check if any fatal diagnostic exists.
+   * Fatal errors require immediate stop of analysis.
+   */
+  hasFatal(): boolean {
+    return this.diagnostics.some(d => d.severity === 'fatal');
+  }
+
+  /**
+   * Check if any error (including fatal) exists.
+   */
+  hasErrors(): boolean {
+    return this.diagnostics.some(d => d.severity === 'error' || d.severity === 'fatal');
+  }
+
+  /**
+   * Check if any warning exists.
+   */
+  hasWarnings(): boolean {
+    return this.diagnostics.some(d => d.severity === 'warning');
+  }
+
+  /**
+   * Get total count of diagnostics.
+   */
+  count(): number {
+    return this.diagnostics.length;
+  }
+
+  /**
+   * Format diagnostics as JSON lines (one JSON object per line).
+   * Suitable for .grafema/diagnostics.log file.
+   */
+  toDiagnosticsLog(): string {
+    return this.diagnostics.map(d => JSON.stringify(d)).join('\n');
+  }
+
+  /**
+   * Clear all diagnostics.
+   */
+  clear(): void {
+    this.diagnostics = [];
+  }
+}