@rcrsr/rill-cli 0.6.0

package/src/cli-error-enrichment.ts

@@ -0,0 +1,274 @@
+/**
+ * CLI Error Enrichment
+ * Functions for extracting source snippets and suggesting similar names
+ */
+
+import type { SourceSpan, RillError, CallFrame } from '@rcrsr/rill';
+
+// ============================================================
+// PUBLIC TYPES
+// ============================================================
+
+export interface SourceSnippet {
+  readonly lines: SnippetLine[];
+  readonly highlightSpan: SourceSpan;
+}
+
+export interface SnippetLine {
+  readonly lineNumber: number;
+  readonly content: string;
+  readonly isErrorLine: boolean;
+}
+
+export interface ScopeInfo {
+  readonly variableNames: string[];
+  readonly functionNames: string[];
+}
+
+export interface EnrichedError {
+  readonly errorId: string;
+  readonly message: string;
+  readonly span?: SourceSpan | undefined;
+  readonly context?: Record<string, unknown> | undefined;
+  readonly callStack?: CallFrame[] | undefined;
+  readonly sourceSnippet?: SourceSnippet | undefined;
+  readonly suggestions?: string[] | undefined;
+  readonly helpUrl?: string | undefined;
+}
+
+// ============================================================
+// SOURCE SNIPPET EXTRACTION
+// ============================================================
+
+/**
+ * Extract source lines around error location.
+ *
+ * Constraints:
+ * - Context lines: 2 before, 2 after (configurable)
+ * - Line numbers: 1-based
+ * - Handles edge cases: line 1, last line
+ *
+ * @param source - Full source text
+ * @param span - Error location span
+ * @param contextLines - Number of context lines before/after (default: 2)
+ * @returns Snippet with context lines
+ * @throws {RangeError} When span exceeds source bounds
+ */
+export function extractSnippet(
+  source: string,
+  span: SourceSpan,
+  contextLines: number = 2
+): SourceSnippet {
+  // EC-7: Empty source returns empty snippet
+  if (source === '') {
+    return { lines: [], highlightSpan: span };
+  }
+
+  const lines = source.split('\n');
+  const totalLines = lines.length;
+
+  // EC-6: Validate span is within bounds (1-based line numbers)
+  if (span.start.line < 1 || span.start.line > totalLines) {
+    throw new RangeError('Span exceeds source bounds');
+  }
+  if (span.end.line < 1 || span.end.line > totalLines) {
+    throw new RangeError('Span exceeds source bounds');
+  }
+
+  // Calculate context range
+  const errorStartLine = span.start.line;
+  const errorEndLine = span.end.line;
+  const firstLine = Math.max(1, errorStartLine - contextLines);
+  const lastLine = Math.min(totalLines, errorEndLine + contextLines);
+
+  // Build snippet lines
+  const snippetLines: SnippetLine[] = [];
+  for (let lineNum = firstLine; lineNum <= lastLine; lineNum++) {
+    const isErrorLine = lineNum >= errorStartLine && lineNum <= errorEndLine;
+    snippetLines.push({
+      lineNumber: lineNum,
+      content: lines[lineNum - 1] ?? '', // Convert 1-based to 0-based index
+      isErrorLine,
+    });
+  }
+
+  return {
+    lines: snippetLines,
+    highlightSpan: span,
+  };
+}
+
+// ============================================================
+// NAME SUGGESTION
+// ============================================================
+
+/**
+ * Find similar names using fuzzy matching.
+ *
+ * Constraints:
+ * - Edit distance threshold: <= 2
+ * - Max suggestions: 3
+ * - Sort: ascending by distance, then alphabetically
+ *
+ * @param target - Name to match against
+ * @param candidates - Available names
+ * @returns Up to 3 similar names, sorted by distance then alphabetically
+ */
+export function suggestSimilarNames(
+  target: string,
+  candidates: string[]
+): string[] {
+  // EC-9: Empty target returns []
+  if (target === '') {
+    return [];
+  }
+
+  // EC-10: Empty candidates returns []
+  if (candidates.length === 0) {
+    return [];
+  }
+
+  // Calculate edit distance for each candidate
+  const candidatesWithDistance = candidates
+    .map((candidate) => ({
+      name: candidate,
+      distance: levenshteinDistance(target, candidate),
+    }))
+    .filter((item) => item.distance <= 2); // IR-8: Edit distance threshold
+
+  // Sort: ascending by distance, then alphabetically
+  candidatesWithDistance.sort((a, b) => {
+    if (a.distance !== b.distance) {
+      return a.distance - b.distance;
+    }
+    return a.name.localeCompare(b.name);
+  });
+
+  // IR-8: Max 3 suggestions
+  return candidatesWithDistance.slice(0, 3).map((item) => item.name);
+}
+
+/**
+ * Calculate Levenshtein distance between two strings.
+ * Uses dynamic programming with O(m*n) time and O(min(m,n)) space.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Edit distance (number of operations to transform a into b)
+ */
+function levenshteinDistance(a: string, b: string): number {
+  // Ensure a is the shorter string for space optimization
+  if (a.length > b.length) {
+    [a, b] = [b, a];
+  }
+
+  const m = a.length;
+  const n = b.length;
+
+  // Early exit for empty strings
+  if (m === 0) return n;
+  if (n === 0) return m;
+
+  // Use rolling array optimization (only need previous row)
+  let prevRow = Array.from({ length: m + 1 }, (_, i) => i);
+  let currRow = new Array<number>(m + 1);
+
+  for (let j = 1; j <= n; j++) {
+    currRow[0] = j;
+
+    for (let i = 1; i <= m; i++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      currRow[i] = Math.min(
+        prevRow[i]! + 1, // deletion
+        currRow[i - 1]! + 1, // insertion
+        prevRow[i - 1]! + cost // substitution
+      );
+    }
+
+    // Swap rows for next iteration
+    [prevRow, currRow] = [currRow, prevRow];
+  }
+
+  return prevRow[m] ?? 0;
+}
+
+// ============================================================
+// ERROR ENRICHMENT
+// ============================================================
+
+/**
+ * Enrich RillError with source snippets and suggestions.
+ *
+ * Constraints:
+ * - Source must be valid UTF-8
+ * - Snippet extraction: 2 lines before, error line, 2 after
+ * - Fuzzy matching: edit distance <= 2
+ * - Max 3 suggestions
+ *
+ * @param error - RillError to enrich
+ * @param source - Full source text
+ * @param scope - Optional scope information for suggestions
+ * @returns Enriched error with snippet and suggestions
+ * @throws {TypeError} When source is not a string or error is null
+ */
+export function enrichError(
+  error: RillError,
+  source: string,
+  scope?: ScopeInfo
+): EnrichedError {
+  // EC-4: Null error
+  if (!error) {
+    throw new TypeError('Error is required');
+  }
+
+  // EC-3: Invalid source encoding (JavaScript strings are always valid UTF-16)
+  if (typeof source !== 'string') {
+    throw new TypeError('Source must be valid UTF-8');
+  }
+
+  // Extract span from error location
+  let span: SourceSpan | undefined;
+  if (error.location) {
+    // Create a minimal span from the location (single character)
+    span = {
+      start: error.location,
+      end: error.location,
+    };
+  }
+
+  // Extract source snippet if we have a span
+  let sourceSnippet: SourceSnippet | undefined;
+  if (span && source !== '') {
+    try {
+      sourceSnippet = extractSnippet(source, span);
+    } catch {
+      // If snippet extraction fails (e.g., invalid span), skip it
+      sourceSnippet = undefined;
+    }
+  }
+
+  // Generate suggestions if scope info is provided
+  let suggestions: string[] | undefined;
+  if (scope && error.context) {
+    // Look for undefined variable names in context
+    const undefinedName = error.context['name'] as string | undefined;
+    if (undefinedName && typeof undefinedName === 'string') {
+      const candidates = [...scope.variableNames, ...scope.functionNames];
+      const similarNames = suggestSimilarNames(undefinedName, candidates);
+      if (similarNames.length > 0) {
+        suggestions = similarNames;
+      }
+    }
+  }
+
+  return {
+    errorId: error.errorId,
+    message: error.message.replace(/ at \d+:\d+$/, ''), // Strip location suffix
+    span,
+    context: error.context,
+    callStack: undefined, // Call stack not part of base RillError
+    sourceSnippet,
+    suggestions,
+    helpUrl: error.helpUrl,
+  };
+}

package/src/cli-error-formatter.ts

@@ -0,0 +1,313 @@
+/**
+ * CLI Error Formatter
+ * Format enriched errors for human-readable, JSON, or compact output
+ */
+
+import type { SourceSpan, CallFrame } from '@rcrsr/rill';
+import type { EnrichedError } from './cli-error-enrichment.js';
+
+// ============================================================
+// PUBLIC TYPES
+// ============================================================
+
+export type { CallFrame, EnrichedError };
+
+/**
+ * Format options for error output.
+ */
+export interface FormatOptions {
+  readonly format: 'human' | 'json' | 'compact';
+  readonly verbose: boolean;
+  readonly includeCallStack: boolean;
+  readonly maxCallStackDepth: number;
+}
+
+// ============================================================
+// ERROR FORMATTING
+// ============================================================
+
+/**
+ * Format enriched error for output.
+ *
+ * Constraints:
+ * - Human format: multi-line with snippet and caret underline
+ * - JSON format: LSP Diagnostic compatible
+ * - Compact format: single line for CI output
+ *
+ * @param error - Enriched error with context
+ * @param options - Format options
+ * @returns Formatted error string
+ * @throws {TypeError} Unknown format
+ */
+export function formatError(
+  error: EnrichedError,
+  options: FormatOptions
+): string {
+  // EC-5: Unknown format throws TypeError
+  if (
+    options.format !== 'human' &&
+    options.format !== 'json' &&
+    options.format !== 'compact'
+  ) {
+    throw new TypeError(`Unknown format: ${options.format}`);
+  }
+
+  if (options.format === 'json') {
+    return formatErrorJson(error, options);
+  }
+
+  if (options.format === 'compact') {
+    return formatErrorCompact(error);
+  }
+
+  return formatErrorHuman(error, options);
+}
+
+/**
+ * Format error in human-readable format.
+ *
+ * Output format:
+ * ```
+ * error[RILL-R005]: Variable foo is not defined
+ *   --> script.rill:5:10
+ *    |
+ *  3 | "start" => $begin
+ *  4 | $begin -> .upper => $upper
+ *  5 | $foo -> .len
+ *    |   ^^^^ undefined variable
+ *    |
+ *    = help: Did you mean `$begin`?
+ * ```
+ */
+function formatErrorHuman(
+  error: EnrichedError,
+  options: FormatOptions
+): string {
+  const lines: string[] = [];
+
+  // Header: error[RILL-XXXX]: message
+  lines.push(`error[${error.errorId}]: ${error.message}`);
+
+  // Location: --> script.rill:5:10
+  if (error.span) {
+    const location = `${error.span.start.line}:${error.span.start.column}`;
+    lines.push(`  --> ${location}`);
+  }
+
+  // Source snippet with caret underline
+  if (error.sourceSnippet && error.sourceSnippet.lines.length > 0) {
+    lines.push('   |');
+
+    // Calculate padding width for line numbers
+    const maxLineNumber = Math.max(
+      ...error.sourceSnippet.lines.map((l) => l.lineNumber)
+    );
+    const lineNumberWidth = String(maxLineNumber).length;
+
+    for (const line of error.sourceSnippet.lines) {
+      const lineNumStr = String(line.lineNumber).padStart(lineNumberWidth, ' ');
+      lines.push(` ${lineNumStr} | ${line.content}`);
+
+      // Add caret underline for error lines
+      if (line.isErrorLine && error.span) {
+        const caret = renderCaretUnderline(error.span, line.content);
+        const padding = ' '.repeat(lineNumberWidth);
+        lines.push(` ${padding} | ${caret}`);
+      }
+    }
+    lines.push('   |');
+  }
+
+  // Suggestions: = help: Did you mean `$begin`?
+  if (error.suggestions && error.suggestions.length > 0) {
+    for (const suggestion of error.suggestions) {
+      lines.push(`   = help: ${suggestion}`);
+    }
+  }
+
+  // Help URL
+  if (options.verbose && error.helpUrl) {
+    lines.push(`   = see: ${error.helpUrl}`);
+  }
+
+  // Call stack
+  if (
+    options.includeCallStack &&
+    error.callStack &&
+    error.callStack.length > 0
+  ) {
+    lines.push('');
+    lines.push('Call stack:');
+    const depth = Math.min(error.callStack.length, options.maxCallStackDepth);
+    for (let i = 0; i < depth; i++) {
+      const frame = error.callStack[i]!;
+      const location = `${frame.location.start.line}:${frame.location.start.column}`;
+      const name = frame.functionName ?? '<anonymous>';
+      const context = frame.context ? ` (${frame.context})` : '';
+      lines.push(`  ${i + 1}. ${name}${context} at ${location}`);
+    }
+    if (error.callStack.length > depth) {
+      lines.push(`  ... ${error.callStack.length - depth} more frames`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format error in JSON format (LSP Diagnostic compatible).
+ */
+function formatErrorJson(error: EnrichedError, options: FormatOptions): string {
+  const diagnostic: {
+    errorId: string;
+    severity: number;
+    message: string;
+    range?: {
+      start: { line: number; character: number };
+      end: { line: number; character: number };
+    };
+    source: string;
+    code: string;
+    suggestions?: string[];
+    callStack?: Array<{
+      location: {
+        start: { line: number; character: number };
+        end: { line: number; character: number };
+      };
+      functionName?: string | undefined;
+      context?: string | undefined;
+    }>;
+    helpUrl?: string;
+  } = {
+    errorId: error.errorId,
+    severity: 1, // Error severity in LSP (1 = Error, 2 = Warning, 3 = Information, 4 = Hint)
+    message: error.message,
+    source: 'rill',
+    code: error.errorId,
+  };
+
+  if (error.span) {
+    diagnostic.range = {
+      start: {
+        line: error.span.start.line - 1, // LSP uses 0-based line numbers
+        character: error.span.start.column,
+      },
+      end: {
+        line: error.span.end.line - 1, // LSP uses 0-based line numbers
+        character: error.span.end.column,
+      },
+    };
+  }
+
+  if (error.suggestions && error.suggestions.length > 0) {
+    diagnostic.suggestions = error.suggestions;
+  }
+
+  if (
+    options.includeCallStack &&
+    error.callStack &&
+    error.callStack.length > 0
+  ) {
+    const depth = Math.min(error.callStack.length, options.maxCallStackDepth);
+    diagnostic.callStack = error.callStack.slice(0, depth).map((frame) => {
+      const callFrame: {
+        location: {
+          start: { line: number; character: number };
+          end: { line: number; character: number };
+        };
+        functionName?: string | undefined;
+        context?: string | undefined;
+      } = {
+        location: {
+          start: {
+            line: frame.location.start.line - 1,
+            character: frame.location.start.column,
+          },
+          end: {
+            line: frame.location.end.line - 1,
+            character: frame.location.end.column,
+          },
+        },
+      };
+      if (frame.functionName !== undefined) {
+        callFrame.functionName = frame.functionName;
+      }
+      if (frame.context !== undefined) {
+        callFrame.context = frame.context;
+      }
+      return callFrame;
+    });
+  }
+
+  if (options.verbose && error.helpUrl) {
+    diagnostic.helpUrl = error.helpUrl;
+  }
+
+  return JSON.stringify(diagnostic, null, 2);
+}
+
+/**
+ * Format error in compact format (single line for CI).
+ */
+function formatErrorCompact(error: EnrichedError): string {
+  const parts: string[] = [`[${error.errorId}]`, error.message];
+
+  if (error.span) {
+    parts.push(`at ${error.span.start.line}:${error.span.start.column}`);
+  }
+
+  if (error.suggestions && error.suggestions.length > 0) {
+    parts.push(`(hint: ${error.suggestions[0]})`);
+  }
+
+  return parts.join(' ');
+}
+
+// ============================================================
+// CARET UNDERLINE
+// ============================================================
+
+/**
+ * Render caret underline for error span.
+ *
+ * Constraints:
+ * - Single-char: single ^
+ * - Multi-char same line: ^^^^^ (length = span width)
+ * - Multi-line: ^^^^^ (continues) on first line only
+ *
+ * @param span - Error span
+ * @param lineContent - Content of the line
+ * @returns Caret underline string
+ * @throws {RangeError} Invalid span (start after end)
+ */
+export function renderCaretUnderline(
+  span: SourceSpan,
+  lineContent: string
+): string {
+  // EC-8: Invalid span throws RangeError
+  if (
+    span.start.line > span.end.line ||
+    (span.start.line === span.end.line && span.start.column > span.end.column)
+  ) {
+    throw new RangeError('Span start must precede end');
+  }
+
+  // Calculate the width of the underline
+  const startColumn = span.start.column;
+  let endColumn: number;
+
+  if (span.start.line === span.end.line) {
+    // Single-line span: underline from start to end
+    endColumn = span.end.column;
+  } else {
+    // Multi-line span: underline to end of first line
+    endColumn = lineContent.length;
+  }
+
+  // Build underline: spaces before, carets for the span
+  const padding = ' '.repeat(startColumn);
+  const caretCount = Math.max(1, endColumn - startColumn);
+  const carets = '^'.repeat(caretCount);
+
+  return padding + carets;
+}