@grafema/core 0.1.0-alpha.5 → 0.1.1-alpha

package/src/core/nodes/ObjectLiteralNode.ts

@@ -0,0 +1,65 @@
+/**
+ * ObjectLiteralNode - contract for OBJECT_LITERAL node
+ *
+ * Represents an object literal expression: { key: value, ... }
+ * Used for tracking data flow through object construction.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ObjectLiteralNodeRecord extends BaseNodeRecord {
+  type: 'OBJECT_LITERAL';
+  column: number;
+  parentCallId?: string;
+  argIndex?: number;
+}
+
+interface ObjectLiteralNodeOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
+export class ObjectLiteralNode {
+  static readonly TYPE = 'OBJECT_LITERAL' as const;
+
+  static readonly REQUIRED = ['file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['parentCallId', 'argIndex'] as const;
+
+  static create(
+    file: string,
+    line: number,
+    column: number,
+    options: ObjectLiteralNodeOptions = {}
+  ): ObjectLiteralNodeRecord {
+    if (!file) throw new Error('ObjectLiteralNode.create: file is required');
+    if (line === undefined) throw new Error('ObjectLiteralNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const argSuffix = options.argIndex !== undefined ? `arg${options.argIndex}` : 'obj';
+    const id = `OBJECT_LITERAL#${argSuffix}#${file}#${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: `<object>`,
+      file,
+      line,
+      column: column || 0,
+      parentCallId: options.parentCallId,
+      argIndex: options.argIndex
+    };
+  }
+
+  static validate(node: ObjectLiteralNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) errors.push(`Expected type ${this.TYPE}`);
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined) errors.push(`Missing: ${field}`);
+    }
+    return errors;
+  }
+}
+
+export type { ObjectLiteralNodeRecord, ObjectLiteralNodeOptions };

package/src/core/nodes/ScopeNode.ts

@@ -1,8 +1,16 @@
 /**
  * ScopeNode - contract for SCOPE node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{scope_path}->SCOPE->{scopeType}#N
+ * Example: src/app.js->handler->SCOPE->if#0
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface ScopeNodeRecord extends BaseNodeRecord {
   type: 'SCOPE';
@@ -22,6 +30,17 @@ interface ScopeNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface ScopeContextOptions {
+  discriminator: number;
+  conditional?: boolean;
+  parentScopeId?: string;
+  parentFunctionId?: string;
+  capturesFrom?: string[];
+}
+
 export class ScopeNode {
   static readonly TYPE = 'SCOPE' as const;
 
@@ -59,6 +78,52 @@ export class ScopeNode {
     };
   }
 
+  /**
+   * Create SCOPE node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Requires discriminator for multiple scopes of same type within parent scope.
+   *
+   * @param scopeType - Type of scope (if, else, try, catch, finally, for, while, switch)
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line }
+   * @param options - Options including required discriminator
+   * @returns ScopeNodeRecord with semantic ID
+   */
+  static createWithContext(
+    scopeType: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: ScopeContextOptions
+  ): ScopeNodeRecord {
+    // Validate required fields
+    if (!scopeType) throw new Error('ScopeNode.createWithContext: scopeType is required');
+    if (!context.file) throw new Error('ScopeNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('ScopeNode.createWithContext: line is required');
+    if (options.discriminator === undefined) throw new Error('ScopeNode.createWithContext: discriminator is required');
+
+    // Compute semantic ID with discriminator
+    const id = computeSemanticId('SCOPE', scopeType, context, {
+      discriminator: options.discriminator
+    });
+
+    // Name includes the discriminator for display purposes
+    const name = `${scopeType}#${options.discriminator}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      scopeType,
+      name,
+      file: context.file,
+      line: location.line,
+      conditional: options.conditional || false,
+      parentScopeId: options.parentScopeId,
+      parentFunctionId: options.parentFunctionId,
+      capturesFrom: options.capturesFrom
+    };
+  }
+
   static validate(node: ScopeNodeRecord): string[] {
     const errors: string[] = [];
 

package/src/core/nodes/TypeNode.ts

@@ -0,0 +1,78 @@
+/**
+ * TypeNode - contract for TYPE node
+ *
+ * Represents TypeScript type alias declarations.
+ *
+ * ID format: {file}:TYPE:{name}:{line}
+ * Example: /src/types.ts:TYPE:UserId:10
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface TypeNodeRecord extends BaseNodeRecord {
+  type: 'TYPE';
+  column: number;
+  aliasOf?: string;
+}
+
+interface TypeNodeOptions {
+  aliasOf?: string;
+}
+
+export class TypeNode {
+  static readonly TYPE = 'TYPE' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['column', 'aliasOf'] as const;
+
+  /**
+   * Create TYPE node
+   *
+   * @param name - Type alias name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional type properties
+   * @returns TypeNodeRecord
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: TypeNodeOptions = {}
+  ): TypeNodeRecord {
+    if (!name) throw new Error('TypeNode.create: name is required');
+    if (!file) throw new Error('TypeNode.create: file is required');
+    if (!line) throw new Error('TypeNode.create: line is required');
+
+    return {
+      id: `${file}:TYPE:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      aliasOf: options.aliasOf
+    };
+  }
+
+  static validate(node: TypeNodeRecord): 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]) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { TypeNodeRecord };

package/src/core/nodes/VariableDeclarationNode.ts

@@ -1,8 +1,16 @@
 /**
  * VariableDeclarationNode - contract for VARIABLE_DECLARATION node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{scope_path}->VARIABLE->{name}
+ * Example: src/app.js->handler->VARIABLE->result
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface VariableDeclarationNodeRecord extends BaseNodeRecord {
   type: 'VARIABLE_DECLARATION';
@@ -15,6 +23,13 @@ interface VariableDeclarationNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface VariableContextOptions {
+  parentScopeId?: string;
+}
+
 export class VariableDeclarationNode {
   static readonly TYPE = 'VARIABLE_DECLARATION' as const;
 
@@ -46,6 +61,43 @@ export class VariableDeclarationNode {
     };
   }
 
+  /**
+   * Create VARIABLE_DECLARATION node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Variable names are unique within scope (handles shadowing naturally).
+   *
+   * @param name - Variable name
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Optional variable properties
+   * @returns VariableDeclarationNodeRecord with semantic ID
+   */
+  static createWithContext(
+    name: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: VariableContextOptions = {}
+  ): VariableDeclarationNodeRecord {
+    // Validate required fields
+    if (!name) throw new Error('VariableDeclarationNode.createWithContext: name is required');
+    if (!context.file) throw new Error('VariableDeclarationNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('VariableDeclarationNode.createWithContext: line is required');
+
+    // Compute semantic ID using 'VARIABLE' type for cleaner IDs
+    const id = computeSemanticId('VARIABLE', name, context);
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      file: context.file,
+      line: location.line,
+      column: location.column ?? 0,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
   static validate(node: VariableDeclarationNodeRecord): string[] {
     const errors: string[] = [];
     if (node.type !== this.TYPE) errors.push(`Expected type ${this.TYPE}`);

package/src/core/nodes/index.ts

@@ -18,13 +18,27 @@ export { MethodCallNode, type MethodCallNodeRecord } from './MethodCallNode.js';
 export { VariableDeclarationNode, type VariableDeclarationNodeRecord } from './VariableDeclarationNode.js';
 export { ConstantNode, type ConstantNodeRecord } from './ConstantNode.js';
 export { LiteralNode, type LiteralNodeRecord } from './LiteralNode.js';
+export { ObjectLiteralNode, type ObjectLiteralNodeRecord, type ObjectLiteralNodeOptions } from './ObjectLiteralNode.js';
+export { ArrayLiteralNode, type ArrayLiteralNodeRecord, type ArrayLiteralNodeOptions } from './ArrayLiteralNode.js';
 
 // Import/Export nodes
-export { ImportNode, type ImportNodeRecord, type ImportKind } from './ImportNode.js';
+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';
+
+// TypeScript declaration nodes
+export { InterfaceNode, type InterfaceNodeRecord, type InterfacePropertyRecord } from './InterfaceNode.js';
+export { TypeNode, type TypeNodeRecord } from './TypeNode.js';
+export { EnumNode, type EnumNodeRecord, type EnumMemberRecord } from './EnumNode.js';
+export { DecoratorNode, type DecoratorNodeRecord, type DecoratorTargetType } from './DecoratorNode.js';
+
+// Expression nodes
+export { ExpressionNode, type ExpressionNodeRecord, type ExpressionNodeOptions } from './ExpressionNode.js';
+export { ArgumentExpressionNode, type ArgumentExpressionNodeRecord, type ArgumentExpressionNodeOptions } from './ArgumentExpressionNode.js';
 
 // External/IO nodes
 export { ExternalStdioNode, type ExternalStdioNodeRecord } from './ExternalStdioNode.js';
+export { NetworkRequestNode, type NetworkRequestNodeRecord } from './NetworkRequestNode.js';
 export { EventListenerNode, type EventListenerNodeRecord } from './EventListenerNode.js';
 export { HttpRequestNode, type HttpRequestNodeRecord } from './HttpRequestNode.js';
 export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQueryNode.js';
@@ -32,6 +46,9 @@ export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQuery
 // 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';
+
 // Node type constants and helpers
 export {
   NODE_TYPE,

package/src/diagnostics/DiagnosticCollector.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 } 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;
+}
+
+/**
+ * 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,
+        });
+      } 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 = [];
+  }
+}

package/src/diagnostics/DiagnosticReporter.ts

@@ -0,0 +1,204 @@
+/**
+ * DiagnosticReporter - Formats diagnostics for output
+ *
+ * Supports multiple output formats:
+ * - text: Human-readable format with severity indicators
+ * - json: Machine-readable JSON format for CI integration
+ * - csv: Spreadsheet-compatible format
+ *
+ * Usage:
+ *   const reporter = new DiagnosticReporter(collector);
+ *   console.log(reporter.report({ format: 'text', includeSummary: true }));
+ *   console.log(reporter.summary());
+ */
+
+import type { Diagnostic, DiagnosticCollector } from './DiagnosticCollector.js';
+
+/**
+ * Report output options
+ */
+export interface ReportOptions {
+  format: 'text' | 'json' | 'csv';
+  includeSummary?: boolean;
+  includeTrace?: boolean;
+}
+
+/**
+ * Summary statistics
+ */
+export interface SummaryStats {
+  total: number;
+  fatal: number;
+  errors: number;
+  warnings: number;
+  info: number;
+}
+
+/**
+ * DiagnosticReporter - formats diagnostics for different output formats
+ */
+export class DiagnosticReporter {
+  constructor(private collector: DiagnosticCollector) {}
+
+  /**
+   * Generate a formatted report of all diagnostics.
+   */
+  report(options: ReportOptions): string {
+    const diagnostics = this.collector.getAll();
+
+    if (options.format === 'json') {
+      return this.jsonReport(diagnostics, options);
+    } else if (options.format === 'csv') {
+      return this.csvReport(diagnostics);
+    } else {
+      return this.textReport(diagnostics, options);
+    }
+  }
+
+  /**
+   * Generate a human-readable summary of diagnostic counts.
+   */
+  summary(): string {
+    const stats = this.getStats();
+
+    if (stats.total === 0) {
+      return 'No issues found.';
+    }
+
+    const parts: string[] = [];
+
+    if (stats.fatal > 0) {
+      parts.push(`Fatal: ${stats.fatal}`);
+    }
+    if (stats.errors > 0) {
+      parts.push(`Errors: ${stats.errors}`);
+    }
+    if (stats.warnings > 0) {
+      parts.push(`Warnings: ${stats.warnings}`);
+    }
+
+    return parts.join(', ');
+  }
+
+  /**
+   * Get diagnostic statistics by severity.
+   */
+  getStats(): SummaryStats {
+    const diagnostics = this.collector.getAll();
+    return {
+      total: diagnostics.length,
+      fatal: diagnostics.filter(d => d.severity === 'fatal').length,
+      errors: diagnostics.filter(d => d.severity === 'error').length,
+      warnings: diagnostics.filter(d => d.severity === 'warning').length,
+      info: diagnostics.filter(d => d.severity === 'info').length,
+    };
+  }
+
+  /**
+   * Generate human-readable text report.
+   */
+  private textReport(diagnostics: Diagnostic[], options: ReportOptions): string {
+    if (diagnostics.length === 0) {
+      return 'No issues found.';
+    }
+
+    const lines: string[] = [];
+
+    for (const diag of diagnostics) {
+      const icon = this.getSeverityIcon(diag.severity);
+      const location = this.formatLocation(diag);
+
+      lines.push(`${icon} ${diag.code} ${location} ${diag.message}`);
+
+      if (diag.suggestion) {
+        lines.push(`   Suggestion: ${diag.suggestion}`);
+      }
+    }
+
+    if (options.includeSummary) {
+      lines.push('');
+      lines.push(this.summary());
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate JSON report.
+   */
+  private jsonReport(diagnostics: Diagnostic[], options: ReportOptions): string {
+    const result: {
+      diagnostics: Diagnostic[];
+      summary?: SummaryStats;
+    } = {
+      diagnostics,
+    };
+
+    if (options.includeSummary) {
+      result.summary = this.getStats();
+    }
+
+    return JSON.stringify(result, null, 2);
+  }
+
+  /**
+   * Generate CSV report.
+   */
+  private csvReport(diagnostics: Diagnostic[]): string {
+    const header = 'severity,code,file,line,message,plugin,phase,suggestion';
+    const rows = diagnostics.map(d =>
+      [
+        d.severity,
+        d.code,
+        d.file || '',
+        d.line || '',
+        this.csvEscape(d.message),
+        d.plugin,
+        d.phase,
+        d.suggestion ? this.csvEscape(d.suggestion) : '',
+      ].join(',')
+    );
+    return [header, ...rows].join('\n');
+  }
+
+  /**
+   * Get severity indicator for text output.
+   */
+  private getSeverityIcon(severity: Diagnostic['severity']): string {
+    switch (severity) {
+      case 'fatal':
+        return '[FATAL]';
+      case 'error':
+        return '[ERROR]';
+      case 'warning':
+        return '[WARN]';
+      case 'info':
+        return '[INFO]';
+      default:
+        return '[?]';
+    }
+  }
+
+  /**
+   * Format file location for display.
+   */
+  private formatLocation(diag: Diagnostic): string {
+    if (!diag.file) {
+      return '';
+    }
+    if (diag.line) {
+      return `(${diag.file}:${diag.line})`;
+    }
+    return `(${diag.file})`;
+  }
+
+  /**
+   * Escape a value for CSV output.
+   * Wraps in quotes and escapes internal quotes.
+   */
+  private csvEscape(value: string): string {
+    // Always quote to handle commas and special characters
+    const escaped = value.replace(/"/g, '""');
+    return `"${escaped}"`;
+  }
+}