@grafema/core 0.2.4-beta → 0.2.6-beta

package/src/core/nodes/TypeParameterNode.ts

@@ -0,0 +1,91 @@
+/**
+ * TypeParameterNode - contract for TYPE_PARAMETER node
+ *
+ * Represents a generic type parameter on a function, class, interface, or type alias.
+ *
+ * ID format: {parentId}:TYPE_PARAMETER:{name}
+ * Example: /src/types.ts:INTERFACE:Container:5:TYPE_PARAMETER:T
+ *
+ * Type parameter names are unique within their declaration scope
+ * (TypeScript does not allow `<T, T>`), so {parentId}:{name} is sufficient.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface TypeParameterNodeRecord extends BaseNodeRecord {
+  type: 'TYPE_PARAMETER';
+  column: number;
+  constraint?: string;
+  defaultType?: string;
+  variance?: 'in' | 'out' | 'in out';
+}
+
+interface TypeParameterNodeOptions {
+  constraint?: string;
+  defaultType?: string;
+  variance?: 'in' | 'out' | 'in out';
+}
+
+export class TypeParameterNode {
+  static readonly TYPE = 'TYPE_PARAMETER' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['constraint', 'defaultType', 'variance'] as const;
+
+  /**
+   * Create TYPE_PARAMETER node
+   *
+   * @param name - Type parameter name (e.g., "T", "K")
+   * @param parentId - ID of the owning declaration (function, class, interface, type)
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional constraint, defaultType, variance
+   * @returns TypeParameterNodeRecord
+   */
+  static create(
+    name: string,
+    parentId: string,
+    file: string,
+    line: number,
+    column: number,
+    options: TypeParameterNodeOptions = {}
+  ): TypeParameterNodeRecord {
+    if (!name) throw new Error('TypeParameterNode.create: name is required');
+    if (!parentId) throw new Error('TypeParameterNode.create: parentId is required');
+    if (!file) throw new Error('TypeParameterNode.create: file is required');
+    if (!line) throw new Error('TypeParameterNode.create: line is required');
+    if (column === undefined) throw new Error('TypeParameterNode.create: column is required');
+
+    return {
+      id: `${parentId}:TYPE_PARAMETER:${name}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      ...(options.constraint !== undefined && { constraint: options.constraint }),
+      ...(options.defaultType !== undefined && { defaultType: options.defaultType }),
+      ...(options.variance !== undefined && { variance: options.variance }),
+    };
+  }
+
+  static validate(node: TypeParameterNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined || nodeRecord[field] === null) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { TypeParameterNodeRecord, TypeParameterNodeOptions };

package/src/core/nodes/index.ts

@@ -28,10 +28,12 @@ export { ArrayLiteralNode, type ArrayLiteralNodeRecord, type ArrayLiteralNodeOpt
 export { ImportNode, type ImportNodeRecord, type ImportBinding, type ImportType } from './ImportNode.js';
 export { ExportNode, type ExportNodeRecord, type ExportKind } from './ExportNode.js';
 export { ExternalModuleNode, type ExternalModuleNodeRecord } from './ExternalModuleNode.js';
+export { ExternalFunctionNode, type ExternalFunctionNodeRecord, type ExternalFunctionOptions } from './ExternalFunctionNode.js';
 
 // TypeScript declaration nodes
 export { InterfaceNode, type InterfaceNodeRecord, type InterfacePropertyRecord } from './InterfaceNode.js';
 export { TypeNode, type TypeNodeRecord } from './TypeNode.js';
+export { TypeParameterNode, type TypeParameterNodeRecord, type TypeParameterNodeOptions } from './TypeParameterNode.js';
 export { EnumNode, type EnumNodeRecord, type EnumMemberRecord } from './EnumNode.js';
 export { DecoratorNode, type DecoratorNodeRecord, type DecoratorTargetType } from './DecoratorNode.js';
 
@@ -46,12 +48,70 @@ export { EventListenerNode, type EventListenerNodeRecord } from './EventListener
 export { HttpRequestNode, type HttpRequestNodeRecord } from './HttpRequestNode.js';
 export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQueryNode.js';
 
+// HTTP/Express namespaced nodes
+export { HttpRouteNode, type HttpRouteNodeRecord, type HttpRouteNodeOptions } from './HttpRouteNode.js';
+export { FetchRequestNode, type FetchRequestNodeRecord, type FetchRequestNodeOptions } from './FetchRequestNode.js';
+export { ExpressMountNode, type ExpressMountNodeRecord, type ExpressMountNodeOptions } from './ExpressMountNode.js';
+export { ExpressMiddlewareNode, type ExpressMiddlewareNodeRecord, type ExpressMiddlewareNodeOptions } from './ExpressMiddlewareNode.js';
+export { ExternalApiNode, type ExternalApiNodeRecord } from './ExternalApiNode.js';
+
+// Rust nodes
+export { RustModuleNode, type RustModuleNodeRecord } from './RustModuleNode.js';
+export { RustFunctionNode, type RustFunctionNodeRecord } from './RustFunctionNode.js';
+export { RustStructNode, type RustStructNodeRecord } from './RustStructNode.js';
+export { RustImplNode, type RustImplNodeRecord } from './RustImplNode.js';
+export { RustMethodNode, type RustMethodNodeRecord } from './RustMethodNode.js';
+export { RustTraitNode, type RustTraitNodeRecord, type RustTraitMethodRecord } from './RustTraitNode.js';
+export { RustCallNode, type RustCallNodeRecord, type RustCallType } from './RustCallNode.js';
+
+// React domain nodes (react:*, dom:*, browser:*, canvas:*)
+export { ReactNode, type ReactNodeRecord } from './ReactNode.js';
+
+// Socket.IO domain nodes (socketio:*)
+export {
+  SocketIONode,
+  type SocketIOEmitNodeRecord,
+  type SocketIOListenerNodeRecord,
+  type SocketIORoomNodeRecord,
+  type SocketIOEventNodeRecord,
+} from './SocketIONode.js';
+
+// Socket domain nodes (os:unix-*, net:tcp-*)
+export {
+  SocketNode as SocketConnectionNode,
+  type UnixSocketNodeRecord,
+  type TcpConnectionNodeRecord,
+  type UnixServerNodeRecord,
+  type TcpServerNodeRecord,
+  type AnySocketNodeRecord,
+} from './SocketNode.js';
+
+// Database domain nodes (db:*)
+export {
+  DatabaseNode,
+  type DbConnectionNodeRecord,
+  type DbQueryNodeRecord,
+  type DbTableNodeRecord,
+} from './DatabaseNode.js';
+
+// Service Layer domain nodes (SERVICE_*)
+export {
+  ServiceLayerNode,
+  type ServiceClassNodeRecord,
+  type ServiceInstanceNodeRecord,
+  type ServiceRegistrationNodeRecord,
+  type ServiceUsageNodeRecord,
+} from './ServiceLayerNode.js';
+
 // Guarantee nodes (contract-based)
 export { GuaranteeNode, type GuaranteeNodeRecord, type GuaranteePriority, type GuaranteeStatus, type GuaranteeType } from './GuaranteeNode.js';
 
 // Issue nodes (detected problems)
 export { IssueNode, type IssueNodeRecord, type IssueSeverity, type IssueType } from './IssueNode.js';
 
+// Plugin nodes (self-describing pipeline)
+export { PluginNode, type PluginNodeRecord, type PluginNodeOptions } from './PluginNode.js';
+
 // Node type constants and helpers
 export {
   NODE_TYPE,
@@ -63,6 +123,7 @@ export {
   isSideEffectType,
   matchesTypePattern,
   isGuaranteeType,
+  isGrafemaType,
   type BaseNodeType,
   type NamespacedNodeType,
   type NodeType,

package/src/core/toposort.ts

@@ -0,0 +1,160 @@
+/**
+ * Topological sort for plugin dependency ordering (REG-367).
+ *
+ * Uses Kahn's algorithm (BFS-based) to sort items by their declared dependencies.
+ * Dependencies not present in the input set are silently ignored (cross-phase deps).
+ * When multiple items have zero in-degree, they are emitted in input order
+ * (registration order tiebreaker).
+ *
+ * Time complexity:  O(V + E)
+ * Space complexity: O(V + E)
+ */
+
+/**
+ * Thrown when a dependency cycle is detected during topological sort.
+ */
+export class CycleError extends Error {
+  readonly cycle: string[];
+
+  constructor(cycle: string[]) {
+    super(`Dependency cycle detected: ${cycle.join(' -> ')}`);
+    this.name = 'CycleError';
+    this.cycle = cycle;
+  }
+}
+
+/**
+ * Input item for topological sort.
+ */
+export interface ToposortItem {
+  id: string;
+  dependencies: string[];
+}
+
+/**
+ * Topologically sort items by their dependencies using Kahn's algorithm.
+ *
+ * Dependencies not present in the input set are silently ignored (cross-phase).
+ * Throws CycleError if a dependency cycle exists among the items.
+ * Items with no dependency relationship are emitted in their original input order.
+ *
+ * @param items - Array of items with id and dependencies
+ * @returns Array of IDs in topological order (dependencies first)
+ * @throws CycleError if a dependency cycle exists
+ */
+export function toposort(items: ToposortItem[]): string[] {
+  if (items.length === 0) return [];
+
+  // Build the set of known IDs for filtering cross-phase deps
+  const knownIds = new Set(items.map(item => item.id));
+
+  // adjacency: dep -> list of items that depend on it (successors)
+  const successors = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+
+  // Initialize
+  for (const item of items) {
+    successors.set(item.id, []);
+    inDegree.set(item.id, 0);
+  }
+
+  // Build edges: for each item's dependency that is in the same set,
+  // add edge from dependency -> item (dependency must execute first)
+  for (const item of items) {
+    for (const dep of item.dependencies) {
+      if (!knownIds.has(dep)) continue; // cross-phase, ignore
+      successors.get(dep)!.push(item.id);
+      inDegree.set(item.id, inDegree.get(item.id)! + 1);
+    }
+  }
+
+  // Initialize queue with all zero-in-degree items, preserving input order
+  const queue: string[] = [];
+  for (const item of items) {
+    if (inDegree.get(item.id) === 0) {
+      queue.push(item.id);
+    }
+  }
+
+  // Process queue (FIFO for registration-order tiebreaker)
+  const result: string[] = [];
+  let head = 0;
+
+  while (head < queue.length) {
+    const current = queue[head++];
+    result.push(current);
+
+    for (const successor of successors.get(current)!) {
+      const newDegree = inDegree.get(successor)! - 1;
+      inDegree.set(successor, newDegree);
+      if (newDegree === 0) {
+        queue.push(successor);
+      }
+    }
+  }
+
+  // If not all items were processed, there's a cycle
+  if (result.length < items.length) {
+    const cycle = findCycle(items, knownIds, result);
+    throw new CycleError(cycle);
+  }
+
+  return result;
+}
+
+/**
+ * Find a cycle among unprocessed items using DFS.
+ * Returns the cycle as an array of IDs ending with a repeat of the first.
+ */
+function findCycle(items: ToposortItem[], knownIds: Set<string>, processed: string[]): string[] {
+  const processedSet = new Set(processed);
+  const unprocessed = items.filter(item => !processedSet.has(item.id));
+
+  // Build adjacency for unprocessed items only
+  const deps = new Map<string, string[]>();
+  for (const item of unprocessed) {
+    deps.set(item.id, item.dependencies.filter(d => knownIds.has(d) && !processedSet.has(d)));
+  }
+
+  // DFS to find cycle
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const path: string[] = [];
+
+  for (const item of unprocessed) {
+    const cycle = dfs(item.id, deps, visiting, visited, path);
+    if (cycle) return cycle;
+  }
+
+  // Fallback: shouldn't reach here, but return the unprocessed IDs
+  return [...unprocessed.map(i => i.id), unprocessed[0].id];
+}
+
+function dfs(
+  node: string,
+  deps: Map<string, string[]>,
+  visiting: Set<string>,
+  visited: Set<string>,
+  path: string[]
+): string[] | null {
+  if (visited.has(node)) return null;
+
+  if (visiting.has(node)) {
+    // Found cycle — extract it from path
+    const cycleStart = path.indexOf(node);
+    return [...path.slice(cycleStart), node];
+  }
+
+  visiting.add(node);
+  path.push(node);
+
+  for (const dep of deps.get(node) ?? []) {
+    const cycle = dfs(dep, deps, visiting, visited, path);
+    if (cycle) return cycle;
+  }
+
+  path.pop();
+  visiting.delete(node);
+  visited.add(node);
+  return null;
+}

package/src/diagnostics/DiagnosticCollector.ts

@@ -17,7 +17,7 @@
  */
 
 import type { PluginPhase, PluginResult } from '@grafema/types';
-import { GrafemaError } from '../errors/GrafemaError.js';
+import { GrafemaError, type ResolutionStep, type ResolutionFailureReason } from '../errors/GrafemaError.js';
 
 /**
  * Diagnostic entry - unified format for all errors/warnings
@@ -32,6 +32,10 @@ export interface Diagnostic {
   plugin: string;
   timestamp: number;
   suggestion?: string;
+  /** Resolution chain for context (REG-332) */
+  resolutionChain?: ResolutionStep[];
+  /** Failure reason for context-aware suggestions (REG-332) */
+  failureReason?: ResolutionFailureReason;
 }
 
 /**
@@ -63,6 +67,9 @@ export class DiagnosticCollector {
           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

package/src/diagnostics/DiagnosticReporter.ts

@@ -13,21 +13,7 @@
  */
 
 import type { Diagnostic, DiagnosticCollector } from './DiagnosticCollector.js';
-
-/**
- * Mapping from diagnostic codes to category information
- */
-const DIAGNOSTIC_CODE_CATEGORIES: Record<string, { name: string; checkCommand: string }> = {
-  'ERR_DISCONNECTED_NODES': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
-  'ERR_DISCONNECTED_NODE': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
-  'ERR_UNRESOLVED_CALL': { name: 'unresolved calls', checkCommand: 'grafema check calls' },
-  'ERR_MISSING_ASSIGNMENT': { name: 'missing assignments', checkCommand: 'grafema check dataflow' },
-  'ERR_BROKEN_REFERENCE': { name: 'broken references', checkCommand: 'grafema check dataflow' },
-  'ERR_NO_LEAF_NODE': { name: 'incomplete traces', checkCommand: 'grafema check dataflow' },
-  'DISCONNECTED_NODES': { name: 'disconnected nodes', checkCommand: 'grafema check connectivity' },
-  'UNRESOLVED_FUNCTION_CALL': { name: 'unresolved calls', checkCommand: 'grafema check calls' },
-  'MISSING_ASSIGNMENT': { name: 'missing assignments', checkCommand: 'grafema check dataflow' },
-};
+import { CODE_TO_CATEGORY } from './categories.js';
 
 /**
  * Report output options
@@ -38,6 +24,16 @@ export interface ReportOptions {
   includeTrace?: boolean;
 }
 
+/**
+ * Options for strict mode formatting (REG-332)
+ */
+export interface StrictFormatOptions {
+  /** Show resolution chain (hybrid: auto-show for ≤3 errors, hide for more) */
+  verbose?: boolean;
+  /** REG-332: Number of errors suppressed by grafema-ignore comments */
+  suppressedCount?: number;
+}
+
 /**
  * Summary statistics
  */
@@ -196,7 +192,7 @@ export class DiagnosticReporter {
     // Convert to CategoryCount array with metadata
     const byCode: CategoryCount[] = [];
     for (const [code, count] of codeMap.entries()) {
-      const category = DIAGNOSTIC_CODE_CATEGORIES[code];
+      const category = CODE_TO_CATEGORY[code];
       byCode.push({
         code,
         count,
@@ -214,6 +210,81 @@ export class DiagnosticReporter {
     };
   }
 
+  /**
+   * Format strict mode errors with enhanced context (REG-332).
+   * Shows resolution chain and context-aware suggestions.
+   *
+   * Uses hybrid progressive disclosure:
+   * - ≤3 errors: show chain by default
+   * - >3 errors: hide chain unless verbose=true
+   *
+   * @param diagnostics - The fatal diagnostics from strict mode
+   * @param options - Formatting options
+   * @returns Formatted string for CLI output
+   */
+  formatStrict(diagnostics: Diagnostic[], options: StrictFormatOptions = {}): string {
+    const lines: string[] = [];
+    // Hybrid: show chain for ≤3 errors unless explicitly set
+    const showChain = options.verbose ?? diagnostics.length <= 3;
+
+    for (const diag of diagnostics) {
+      // Header: CODE file:line
+      const location = diag.file
+        ? diag.line
+          ? `${diag.file}:${diag.line}`
+          : diag.file
+        : '';
+      lines.push(`${diag.code} ${location}`);
+      lines.push('');
+
+      // Message
+      lines.push(`  ${diag.message}`);
+
+      // Resolution chain (if showing and present)
+      if (showChain && diag.resolutionChain && diag.resolutionChain.length > 0) {
+        lines.push('');
+        lines.push('  Resolution chain:');
+        for (const step of diag.resolutionChain) {
+          const stepLocation = step.file
+            ? step.line
+              ? ` (${step.file}:${step.line})`
+              : ` (${step.file})`
+            : '';
+          lines.push(`    ${step.step} -> ${step.result}${stepLocation}`);
+        }
+      }
+
+      // Suggestion (if present)
+      if (diag.suggestion) {
+        lines.push('');
+        lines.push(`  Suggestion: ${diag.suggestion}`);
+      }
+
+      lines.push('');
+      lines.push('---');
+      lines.push('');
+    }
+
+    // Remove trailing separator
+    if (lines.length > 0) {
+      lines.splice(-3);
+    }
+
+    // Add hint about verbose mode if chain hidden
+    if (!showChain && diagnostics.some(d => d.resolutionChain && d.resolutionChain.length > 0)) {
+      lines.push('');
+      lines.push('  Run with --verbose to see resolution chains.');
+    }
+
+    // REG-332: Show suppression summary if any errors were suppressed
+    if (options.suppressedCount && options.suppressedCount > 0) {
+      lines.push('');
+      lines.push(`  ${options.suppressedCount} error(s) suppressed by grafema-ignore comments.`);
+    }
+
+    return lines.join('\n');
+  }
+
   /**
    * Generate human-readable text report.
    */

package/src/diagnostics/categories.ts

@@ -0,0 +1,104 @@
+/**
+ * Diagnostic Categories - Single source of truth for category/code mappings
+ *
+ * This module defines diagnostic categories once and derives both mapping
+ * directions:
+ * - DIAGNOSTIC_CATEGORIES: category → codes (used by CLI check command)
+ * - CODE_TO_CATEGORY: code → category metadata (used by DiagnosticReporter)
+ *
+ * Adding a new diagnostic code requires updating only this file.
+ */
+
+/**
+ * Category definition with human-readable metadata and associated codes
+ */
+export interface DiagnosticCategory {
+  /** Human-readable name for display */
+  readonly name: string;
+  /** Description of what this category checks */
+  readonly description: string;
+  /** Diagnostic codes that belong to this category */
+  readonly codes: readonly string[];
+}
+
+/**
+ * Valid category keys
+ */
+export type DiagnosticCategoryKey = 'connectivity' | 'calls' | 'dataflow' | 'imports';
+
+/**
+ * Canonical definition of all diagnostic categories
+ *
+ * This is the SINGLE SOURCE OF TRUTH for category mappings.
+ * Both CLI and DiagnosticReporter derive their mappings from this.
+ */
+export const DIAGNOSTIC_CATEGORIES: Record<DiagnosticCategoryKey, DiagnosticCategory> = {
+  connectivity: {
+    name: 'Graph Connectivity',
+    description: 'Check for disconnected nodes in the graph',
+    codes: ['ERR_DISCONNECTED_NODES', 'ERR_DISCONNECTED_NODE'],
+  },
+  calls: {
+    name: 'Call Resolution',
+    description: 'Check for unresolved function calls',
+    codes: ['ERR_UNRESOLVED_CALL'],
+  },
+  dataflow: {
+    name: 'Data Flow',
+    description: 'Check for missing assignments and broken references',
+    codes: ['ERR_MISSING_ASSIGNMENT', 'ERR_BROKEN_REFERENCE', 'ERR_NO_LEAF_NODE'],
+  },
+  imports: {
+    name: 'Import Validation',
+    description: 'Check for broken imports and undefined symbols',
+    codes: ['ERR_BROKEN_IMPORT', 'ERR_UNDEFINED_SYMBOL'],
+  },
+};
+
+/**
+ * Metadata for code-to-category lookup (used by DiagnosticReporter)
+ */
+export interface CodeCategoryInfo {
+  /** Human-readable name for the issue type */
+  name: string;
+  /** CLI command to check this category */
+  checkCommand: string;
+}
+
+/**
+ * Derived mapping: code → category metadata
+ *
+ * Auto-generated from DIAGNOSTIC_CATEGORIES.
+ * Used by DiagnosticReporter to show actionable commands.
+ */
+export const CODE_TO_CATEGORY: Record<string, CodeCategoryInfo> = (() => {
+  const result: Record<string, CodeCategoryInfo> = {};
+
+  for (const [categoryKey, category] of Object.entries(DIAGNOSTIC_CATEGORIES)) {
+    // Generate human-readable name from category name (lowercase, plural)
+    const issueName = category.name.toLowerCase().replace('graph ', '');
+
+    for (const code of category.codes) {
+      result[code] = {
+        name: issueName,
+        checkCommand: `grafema check ${categoryKey}`,
+      };
+    }
+  }
+
+  return result;
+})();
+
+/**
+ * Get category for a diagnostic code
+ */
+export function getCategoryForCode(code: string): CodeCategoryInfo | undefined {
+  return CODE_TO_CATEGORY[code];
+}
+
+/**
+ * Get all codes for a category
+ */
+export function getCodesForCategory(category: DiagnosticCategoryKey): readonly string[] {
+  return DIAGNOSTIC_CATEGORIES[category].codes;
+}

package/src/diagnostics/index.ts

@@ -5,6 +5,7 @@
  * - DiagnosticCollector: Collects errors from plugin execution
  * - DiagnosticReporter: Formats diagnostics for output (text/json/csv)
  * - DiagnosticWriter: Writes diagnostics.log file
+ * - categories: Single source of truth for diagnostic category mappings
  */
 
 export { DiagnosticCollector } from './DiagnosticCollector.js';
@@ -14,3 +15,16 @@ export { DiagnosticReporter } from './DiagnosticReporter.js';
 export type { ReportOptions, SummaryStats, CategoryCount, CategorizedSummaryStats } from './DiagnosticReporter.js';
 
 export { DiagnosticWriter } from './DiagnosticWriter.js';
+
+// Category mappings (single source of truth)
+export {
+  DIAGNOSTIC_CATEGORIES,
+  CODE_TO_CATEGORY,
+  getCategoryForCode,
+  getCodesForCategory,
+} from './categories.js';
+export type {
+  DiagnosticCategory,
+  DiagnosticCategoryKey,
+  CodeCategoryInfo,
+} from './categories.js';