@lokascript/framework 2.0.0

package/src/generation/diagnostics.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from 'vitest';
+import { createDiagnosticCollector, fromError, filterBySeverity } from './diagnostics';
+import type { Diagnostic } from './diagnostics';
+
+// =============================================================================
+// DiagnosticCollector
+// =============================================================================
+
+describe('createDiagnosticCollector', () => {
+  it('starts with no diagnostics', () => {
+    const collector = createDiagnosticCollector();
+    expect(collector.getDiagnostics()).toHaveLength(0);
+    expect(collector.hasErrors()).toBe(false);
+  });
+
+  it('collects errors', () => {
+    const collector = createDiagnosticCollector();
+    collector.error('Something went wrong', { code: 'parse-error', line: 3 });
+
+    const diags = collector.getDiagnostics();
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe('error');
+    expect(diags[0].message).toBe('Something went wrong');
+    expect(diags[0].code).toBe('parse-error');
+    expect(diags[0].line).toBe(3);
+  });
+
+  it('collects warnings', () => {
+    const collector = createDiagnosticCollector();
+    collector.warning('Low confidence', { code: 'low-confidence' });
+
+    const diags = collector.getDiagnostics();
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe('warning');
+  });
+
+  it('collects info', () => {
+    const collector = createDiagnosticCollector();
+    collector.info('Consider using alternative', { suggestions: ['use select instead'] });
+
+    const diags = collector.getDiagnostics();
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe('info');
+    expect(diags[0].suggestions).toEqual(['use select instead']);
+  });
+
+  it('adds raw diagnostics', () => {
+    const collector = createDiagnosticCollector();
+    collector.add({
+      message: 'Custom diagnostic',
+      severity: 'warning',
+      code: 'custom',
+      line: 5,
+      column: 10,
+      source: 'some code',
+    });
+
+    const diags = collector.getDiagnostics();
+    expect(diags).toHaveLength(1);
+    expect(diags[0].column).toBe(10);
+    expect(diags[0].source).toBe('some code');
+  });
+
+  it('hasErrors returns true when errors exist', () => {
+    const collector = createDiagnosticCollector();
+    collector.warning('just a warning');
+    expect(collector.hasErrors()).toBe(false);
+
+    collector.error('oops');
+    expect(collector.hasErrors()).toBe(true);
+  });
+
+  it('toResult produces correct summary', () => {
+    const collector = createDiagnosticCollector();
+    collector.error('err1');
+    collector.error('err2');
+    collector.warning('warn1');
+    collector.info('info1');
+    collector.info('info2');
+    collector.info('info3');
+
+    const result = collector.toResult();
+    expect(result.ok).toBe(false);
+    expect(result.summary).toEqual({ errors: 2, warnings: 1, infos: 3 });
+    expect(result.diagnostics).toHaveLength(6);
+  });
+
+  it('toResult.ok is true when no errors', () => {
+    const collector = createDiagnosticCollector();
+    collector.warning('just a warning');
+    collector.info('just info');
+
+    const result = collector.toResult();
+    expect(result.ok).toBe(true);
+    expect(result.summary.errors).toBe(0);
+  });
+
+  it('omits undefined optional fields', () => {
+    const collector = createDiagnosticCollector();
+    collector.error('bare error');
+
+    const diag = collector.getDiagnostics()[0];
+    expect(diag.code).toBeUndefined();
+    expect(diag.line).toBeUndefined();
+    expect(diag.column).toBeUndefined();
+    expect(diag.source).toBeUndefined();
+    expect(diag.suggestions).toBeUndefined();
+  });
+
+  it('omits suggestions when empty array', () => {
+    const collector = createDiagnosticCollector();
+    collector.error('msg', { suggestions: [] });
+
+    const diag = collector.getDiagnostics()[0];
+    expect(diag.suggestions).toBeUndefined();
+  });
+});
+
+// =============================================================================
+// fromError
+// =============================================================================
+
+describe('fromError', () => {
+  it('converts Error to diagnostic', () => {
+    const diag = fromError(new Error('Something broke'), { code: 'runtime-error', line: 42 });
+    expect(diag.message).toBe('Something broke');
+    expect(diag.severity).toBe('error');
+    expect(diag.code).toBe('runtime-error');
+    expect(diag.line).toBe(42);
+  });
+
+  it('converts string to diagnostic', () => {
+    const diag = fromError('string error');
+    expect(diag.message).toBe('string error');
+    expect(diag.severity).toBe('error');
+  });
+
+  it('converts unknown to diagnostic', () => {
+    const diag = fromError(12345);
+    expect(diag.message).toBe('12345');
+  });
+});
+
+// =============================================================================
+// filterBySeverity
+// =============================================================================
+
+describe('filterBySeverity', () => {
+  const diagnostics: Diagnostic[] = [
+    { message: 'e1', severity: 'error' },
+    { message: 'w1', severity: 'warning' },
+    { message: 'e2', severity: 'error' },
+    { message: 'i1', severity: 'info' },
+  ];
+
+  it('filters errors', () => {
+    const errors = filterBySeverity(diagnostics, 'error');
+    expect(errors).toHaveLength(2);
+    expect(errors.every(d => d.severity === 'error')).toBe(true);
+  });
+
+  it('filters warnings', () => {
+    const warnings = filterBySeverity(diagnostics, 'warning');
+    expect(warnings).toHaveLength(1);
+  });
+
+  it('filters info', () => {
+    const infos = filterBySeverity(diagnostics, 'info');
+    expect(infos).toHaveLength(1);
+  });
+});

package/src/generation/diagnostics.ts

@@ -0,0 +1,239 @@
+/**
+ * Structured Error Diagnostics
+ *
+ * Framework-level diagnostic types for reporting errors, warnings, and hints
+ * during parsing, validation, and compilation. These provide richer feedback
+ * than simple error strings, enabling:
+ *
+ * - Severity levels (error, warning, info)
+ * - Machine-readable error codes
+ * - Source location tracking
+ * - Actionable suggestions
+ * - Programmatic fix lookup
+ */
+
+// =============================================================================
+// Diagnostic Types
+// =============================================================================
+
+/**
+ * Severity level for a diagnostic.
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+
+/**
+ * A structured diagnostic message.
+ *
+ * Diagnostics provide rich error information beyond simple strings.
+ * They're used for parser errors, validation warnings, and hints.
+ */
+export interface Diagnostic {
+  /** Human-readable message */
+  readonly message: string;
+
+  /** Severity level */
+  readonly severity: DiagnosticSeverity;
+
+  /** Machine-readable code for programmatic handling (e.g., 'parse-error', 'missing-role') */
+  readonly code?: string;
+
+  /** 1-based line number in source */
+  readonly line?: number;
+
+  /** 0-based column offset in line */
+  readonly column?: number;
+
+  /** Original source text that triggered the diagnostic */
+  readonly source?: string;
+
+  /** Actionable suggestions for fixing the issue */
+  readonly suggestions?: readonly string[];
+}
+
+/**
+ * Result of a diagnostic-aware validation.
+ */
+export interface DiagnosticResult {
+  /** Whether validation passed (no errors, though warnings/info may exist) */
+  readonly ok: boolean;
+
+  /** All diagnostics, including errors, warnings, and info */
+  readonly diagnostics: readonly Diagnostic[];
+
+  /** Convenience: count of each severity level */
+  readonly summary: DiagnosticSummary;
+}
+
+/**
+ * Summary counts by severity.
+ */
+export interface DiagnosticSummary {
+  readonly errors: number;
+  readonly warnings: number;
+  readonly infos: number;
+}
+
+// =============================================================================
+// Diagnostic Collector
+// =============================================================================
+
+/**
+ * Collects diagnostics during a parsing/validation/compilation pass.
+ *
+ * Use this in your domain's validate() or parse() to accumulate
+ * structured feedback instead of throwing on the first error.
+ *
+ * @example
+ * ```typescript
+ * const collector = createDiagnosticCollector();
+ *
+ * // During parsing:
+ * collector.error('Unknown command: foo', { code: 'unknown-command', line: 3 });
+ * collector.warning('Low confidence match', { code: 'low-confidence', line: 5 });
+ * collector.info('Consider using "select" instead of "get"', { line: 5 });
+ *
+ * // Get result:
+ * const result = collector.toResult();
+ * // { ok: false, diagnostics: [...], summary: { errors: 1, warnings: 1, infos: 1 } }
+ * ```
+ */
+export interface DiagnosticCollector {
+  /** Add an error diagnostic */
+  error(message: string, options?: DiagnosticOptions): void;
+
+  /** Add a warning diagnostic */
+  warning(message: string, options?: DiagnosticOptions): void;
+
+  /** Add an info diagnostic */
+  info(message: string, options?: DiagnosticOptions): void;
+
+  /** Add a diagnostic with explicit severity */
+  add(diagnostic: Diagnostic): void;
+
+  /** Whether any errors have been collected */
+  hasErrors(): boolean;
+
+  /** Get all collected diagnostics */
+  getDiagnostics(): readonly Diagnostic[];
+
+  /** Build a DiagnosticResult from collected diagnostics */
+  toResult(): DiagnosticResult;
+}
+
+/**
+ * Options for adding a diagnostic via the collector's convenience methods.
+ */
+export interface DiagnosticOptions {
+  readonly code?: string;
+  readonly line?: number;
+  readonly column?: number;
+  readonly source?: string;
+  readonly suggestions?: readonly string[];
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a new diagnostic collector.
+ */
+export function createDiagnosticCollector(): DiagnosticCollector {
+  const diagnostics: Diagnostic[] = [];
+
+  function addWithSeverity(
+    severity: DiagnosticSeverity,
+    message: string,
+    options?: DiagnosticOptions
+  ): void {
+    const diag: Diagnostic = {
+      message,
+      severity,
+      ...(options?.code != null && { code: options.code }),
+      ...(options?.line != null && { line: options.line }),
+      ...(options?.column != null && { column: options.column }),
+      ...(options?.source != null && { source: options.source }),
+      ...(options?.suggestions != null &&
+        options.suggestions.length > 0 && { suggestions: options.suggestions }),
+    };
+    diagnostics.push(diag);
+  }
+
+  return {
+    error(message, options) {
+      addWithSeverity('error', message, options);
+    },
+
+    warning(message, options) {
+      addWithSeverity('warning', message, options);
+    },
+
+    info(message, options) {
+      addWithSeverity('info', message, options);
+    },
+
+    add(diagnostic) {
+      diagnostics.push(diagnostic);
+    },
+
+    hasErrors() {
+      return diagnostics.some(d => d.severity === 'error');
+    },
+
+    getDiagnostics() {
+      return diagnostics;
+    },
+
+    toResult(): DiagnosticResult {
+      let errors = 0;
+      let warnings = 0;
+      let infos = 0;
+      for (const d of diagnostics) {
+        if (d.severity === 'error') errors++;
+        else if (d.severity === 'warning') warnings++;
+        else infos++;
+      }
+
+      return {
+        ok: errors === 0,
+        diagnostics,
+        summary: { errors, warnings, infos },
+      };
+    },
+  };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Create a diagnostic from an Error object.
+ * Useful for converting caught exceptions into structured diagnostics.
+ */
+export function fromError(
+  error: unknown,
+  options?: Omit<DiagnosticOptions, 'code'> & { code?: string }
+): Diagnostic {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message,
+    severity: 'error',
+    ...(options?.code != null && { code: options.code }),
+    ...(options?.line != null && { line: options.line }),
+    ...(options?.column != null && { column: options.column }),
+    ...(options?.source != null && { source: options.source }),
+    ...(options?.suggestions != null &&
+      options.suggestions.length > 0 && { suggestions: options.suggestions }),
+  };
+}
+
+/**
+ * Filter diagnostics by severity.
+ */
+export function filterBySeverity(
+  diagnostics: readonly Diagnostic[],
+  severity: DiagnosticSeverity
+): readonly Diagnostic[] {
+  return diagnostics.filter(d => d.severity === severity);
+}

package/src/generation/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Pattern generation, rendering, and diagnostics
+ */
+
+export * from './pattern-generator';
+export * from './renderer';
+export * from './diagnostics';