@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/src/data/globals/definitions.ts

@@ -0,0 +1,156 @@
+/**
+ * Global Symbol Definitions
+ *
+ * JavaScript/TypeScript globals that should not be reported as undefined.
+ * Organized by environment and category.
+ */
+
+/**
+ * ECMAScript standard globals (available in all JS environments)
+ */
+export const ECMASCRIPT_GLOBALS: string[] = [
+  // Value properties
+  'globalThis', 'Infinity', 'NaN', 'undefined',
+
+  // Function properties
+  'eval', 'isFinite', 'isNaN', 'parseFloat', 'parseInt', 'decodeURI',
+  'decodeURIComponent', 'encodeURI', 'encodeURIComponent',
+
+  // Fundamental objects
+  'Object', 'Function', 'Boolean', 'Symbol',
+
+  // Error objects
+  'Error', 'AggregateError', 'EvalError', 'RangeError', 'ReferenceError',
+  'SyntaxError', 'TypeError', 'URIError',
+
+  // Numbers and dates
+  'Number', 'BigInt', 'Math', 'Date',
+
+  // Text processing
+  'String', 'RegExp',
+
+  // Collections
+  'Array', 'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array',
+  'Uint16Array', 'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array',
+  'BigInt64Array', 'BigUint64Array', 'Map', 'Set', 'WeakMap', 'WeakSet',
+
+  // Structured data
+  'ArrayBuffer', 'SharedArrayBuffer', 'DataView', 'Atomics', 'JSON',
+
+  // Control abstraction
+  'Promise', 'Generator', 'GeneratorFunction', 'AsyncFunction',
+  'AsyncGenerator', 'AsyncGeneratorFunction',
+
+  // Reflection
+  'Reflect', 'Proxy',
+
+  // Internationalization
+  'Intl',
+];
+
+/**
+ * Node.js-specific globals
+ */
+export const NODEJS_GLOBALS: string[] = [
+  // Core globals
+  'console', 'process', 'global', 'Buffer',
+
+  // Timers
+  'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval',
+  'setImmediate', 'clearImmediate',
+
+  // Module system
+  'require', 'module', 'exports', '__dirname', '__filename',
+
+  // URL/fetch (Node 18+)
+  'fetch', 'URL', 'URLSearchParams', 'Request', 'Response', 'Headers',
+
+  // Blob/File (Node 18+)
+  'Blob', 'File', 'FormData',
+
+  // Streams
+  'ReadableStream', 'WritableStream', 'TransformStream',
+
+  // Crypto
+  'crypto', 'Crypto', 'CryptoKey', 'SubtleCrypto',
+
+  // Text encoding
+  'TextEncoder', 'TextDecoder',
+
+  // Events
+  'Event', 'EventTarget', 'AbortController', 'AbortSignal',
+
+  // Performance
+  'performance', 'PerformanceEntry', 'PerformanceObserver',
+
+  // Queuing
+  'queueMicrotask',
+
+  // MessageChannel
+  'MessageChannel', 'MessagePort', 'BroadcastChannel',
+
+  // Structured clone
+  'structuredClone',
+];
+
+/**
+ * Browser-specific globals (commonly used, may appear in isomorphic code)
+ */
+export const BROWSER_GLOBALS: string[] = [
+  // DOM
+  'window', 'document', 'navigator', 'location', 'history',
+
+  // Elements
+  'HTMLElement', 'Element', 'Node', 'NodeList', 'DocumentFragment',
+
+  // Events
+  'addEventListener', 'removeEventListener', 'CustomEvent',
+
+  // Storage
+  'localStorage', 'sessionStorage', 'indexedDB',
+
+  // Workers
+  'Worker', 'SharedWorker', 'ServiceWorker',
+
+  // Animation
+  'requestAnimationFrame', 'cancelAnimationFrame',
+
+  // Alerts
+  'alert', 'confirm', 'prompt',
+
+  // Screen/viewport
+  'screen', 'innerWidth', 'innerHeight', 'scrollX', 'scrollY',
+
+  // Image/media
+  'Image', 'Audio', 'Video',
+
+  // Observers
+  'MutationObserver', 'IntersectionObserver', 'ResizeObserver',
+];
+
+/**
+ * Test framework globals (common testing environments)
+ */
+export const TEST_GLOBALS: string[] = [
+  // Node.js test runner
+  'describe', 'it', 'test', 'before', 'after', 'beforeEach', 'afterEach',
+
+  // Jest
+  'expect', 'jest', 'mock', 'spyOn', 'fn',
+
+  // Mocha/Chai
+  'assert', 'should',
+
+  // Vitest
+  'vi',
+];
+
+/**
+ * All default globals combined
+ */
+export const ALL_GLOBALS: Set<string> = new Set([
+  ...ECMASCRIPT_GLOBALS,
+  ...NODEJS_GLOBALS,
+  ...BROWSER_GLOBALS,
+  ...TEST_GLOBALS,
+]);

package/src/data/globals/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Global Symbols Registry
+ *
+ * Provides lookup for JavaScript/TypeScript global symbols.
+ * Used by BrokenImportValidator to avoid false positives on globals.
+ */
+
+import { ALL_GLOBALS as DEFAULT_GLOBALS } from './definitions.js';
+
+export {
+  ECMASCRIPT_GLOBALS,
+  NODEJS_GLOBALS,
+  BROWSER_GLOBALS,
+  TEST_GLOBALS,
+  ALL_GLOBALS,
+} from './definitions.js';
+
+/**
+ * GlobalsRegistry class for extensible globals management.
+ *
+ * Usage:
+ *   const registry = new GlobalsRegistry();
+ *   if (registry.isGlobal('console')) { ... }
+ *   registry.addCustomGlobals(['myGlobal']);
+ */
+export class GlobalsRegistry {
+  private globals: Set<string>;
+
+  constructor(includeDefaults: boolean = true) {
+    this.globals = includeDefaults
+      ? new Set(DEFAULT_GLOBALS)
+      : new Set();
+  }
+
+  /**
+   * Check if a symbol name is a known global.
+   */
+  isGlobal(name: string): boolean {
+    return this.globals.has(name);
+  }
+
+  /**
+   * Add custom globals (e.g., from project config).
+   */
+  addCustomGlobals(names: string[]): void {
+    for (const name of names) {
+      this.globals.add(name);
+    }
+  }
+
+  /**
+   * Remove globals from the set (e.g., if project doesn't use browser env).
+   */
+  removeGlobals(names: string[]): void {
+    for (const name of names) {
+      this.globals.delete(name);
+    }
+  }
+
+  /**
+   * Get all registered globals.
+   */
+  getAllGlobals(): string[] {
+    return Array.from(this.globals);
+  }
+}

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,324 @@
+/**
+ * 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';
+
+/**
+ * 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' },
+};
+
+/**
+ * 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;
+}
+
+/**
+ * Category count with metadata
+ */
+export interface CategoryCount {
+  code: string;
+  count: number;
+  name: string;
+  checkCommand: string;
+}
+
+/**
+ * Summary statistics with category breakdown
+ */
+export interface CategorizedSummaryStats extends SummaryStats {
+  byCode: CategoryCount[];
+}
+
+/**
+ * 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(', ');
+  }
+
+  /**
+   * Generate a categorized summary with actionable commands.
+   */
+  categorizedSummary(): string {
+    const stats = this.getCategorizedStats();
+
+    if (stats.total === 0) {
+      return 'No issues found.';
+    }
+
+    const lines: string[] = [];
+
+    // Severity totals (same format as summary())
+    const severityParts: string[] = [];
+    if (stats.fatal > 0) {
+      severityParts.push(`Fatal: ${stats.fatal}`);
+    }
+    if (stats.errors > 0) {
+      severityParts.push(`Errors: ${stats.errors}`);
+    }
+    if (stats.warnings > 0) {
+      severityParts.push(`Warnings: ${stats.warnings}`);
+    }
+    lines.push(severityParts.join(', '));
+
+    // Top 5 categories
+    const topCategories = stats.byCode.slice(0, 5);
+    for (const category of topCategories) {
+      lines.push(`  - ${category.count} ${category.name} (run \`${category.checkCommand}\`)`);
+    }
+
+    // "Other issues" if more than 5 categories
+    if (stats.byCode.length > 5) {
+      const remainingCount = stats.byCode.slice(5).reduce((sum, cat) => sum + cat.count, 0);
+      const issueWord = remainingCount === 1 ? 'other issue' : 'other issues';
+      lines.push(`  - ${remainingCount} ${issueWord}`);
+    }
+
+    // Footer
+    lines.push('');
+    lines.push('Run `grafema check --all` for full diagnostics.');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 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,
+    };
+  }
+
+  /**
+   * Get diagnostic statistics grouped by category.
+   */
+  getCategorizedStats(): CategorizedSummaryStats {
+    const diagnostics = this.collector.getAll();
+
+    // Get severity stats
+    const severityStats: SummaryStats = {
+      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,
+    };
+
+    // Group by code
+    const codeMap = new Map<string, number>();
+    for (const diag of diagnostics) {
+      const count = codeMap.get(diag.code) || 0;
+      codeMap.set(diag.code, count + 1);
+    }
+
+    // Convert to CategoryCount array with metadata
+    const byCode: CategoryCount[] = [];
+    for (const [code, count] of codeMap.entries()) {
+      const category = DIAGNOSTIC_CODE_CATEGORIES[code];
+      byCode.push({
+        code,
+        count,
+        name: category?.name || code,
+        checkCommand: category?.checkCommand || 'grafema check --all',
+      });
+    }
+
+    // Sort by count descending
+    byCode.sort((a, b) => b.count - a.count);
+
+    return {
+      ...severityStats,
+      byCode,
+    };
+  }
+
+  /**
+   * 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}"`;
+  }
+}