@grafema/util 0.3.0-beta

package/src/diagnostics/DiagnosticReporter.ts

@@ -0,0 +1,395 @@
+/**
+ * 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';
+import { CODE_TO_CATEGORY } from './categories.js';
+
+/**
+ * Report output options
+ */
+export interface ReportOptions {
+  format: 'text' | 'json' | 'csv';
+  includeSummary?: boolean;
+  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
+ */
+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 = CODE_TO_CATEGORY[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,
+    };
+  }
+
+  /**
+   * 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.
+   */
+  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}"`;
+  }
+}

package/src/diagnostics/DiagnosticWriter.ts

@@ -0,0 +1,50 @@
+/**
+ * DiagnosticWriter - Writes diagnostics to .grafema/diagnostics.log
+ *
+ * Writes diagnostics in JSON lines format (one JSON object per line).
+ * This format is:
+ * - Easy to parse line-by-line
+ * - Appendable without reading entire file
+ * - Compatible with streaming tools (grep, jq, etc.)
+ *
+ * Usage:
+ *   const writer = new DiagnosticWriter();
+ *   await writer.write(collector, '/project/.grafema');
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+import type { DiagnosticCollector } from './DiagnosticCollector.js';
+
+/**
+ * DiagnosticWriter - writes diagnostics.log file
+ */
+export class DiagnosticWriter {
+  /**
+   * Write all diagnostics to .grafema/diagnostics.log
+   *
+   * Creates the directory if it doesn't exist.
+   * Overwrites existing file.
+   */
+  async write(collector: DiagnosticCollector, grafemaDir: string): Promise<void> {
+    const logPath = this.getLogPath(grafemaDir);
+
+    // Create directory if it doesn't exist
+    const dir = dirname(logPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Write diagnostics as JSON lines
+    const content = collector.toDiagnosticsLog();
+    writeFileSync(logPath, content, 'utf-8');
+  }
+
+  /**
+   * Get the path to the diagnostics.log file
+   */
+  getLogPath(grafemaDir: string): string {
+    return join(grafemaDir, 'diagnostics.log');
+  }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Diagnostics - Error collection, reporting, and logging
+ *
+ * This module provides the diagnostics infrastructure for Grafema:
+ * - 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';
+export type { Diagnostic, DiagnosticInput } from './DiagnosticCollector.js';
+
+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';