tova 0.2.9 → 0.3.1

package/src/diagnostics/error-codes.js

@@ -0,0 +1,255 @@
+// Tova Diagnostic Error Codes Registry
+// Every diagnostic has a unique code: E### for errors, W### for warnings
+
+// ─── Error Codes ─────────────────────────────────────────────
+
+export const ErrorCode = {
+  // === Syntax / Parse Errors (E001–E099) ===
+  E001: { code: 'E001', title: 'Unexpected token',           category: 'syntax' },
+  E002: { code: 'E002', title: 'Unterminated string',        category: 'syntax' },
+  E003: { code: 'E003', title: 'Expected closing delimiter', category: 'syntax' },
+  E004: { code: 'E004', title: 'Invalid number literal',     category: 'syntax' },
+  E005: { code: 'E005', title: 'Unexpected character',       category: 'syntax' },
+  E006: { code: 'E006', title: 'Unterminated comment',       category: 'syntax' },
+  E007: { code: 'E007', title: 'Expected expression',        category: 'syntax' },
+  E008: { code: 'E008', title: 'Mismatched JSX tag',         category: 'syntax' },
+  E009: { code: 'E009', title: 'Invalid operator',           category: 'syntax' },
+  E010: { code: 'E010', title: 'Max nesting depth exceeded', category: 'syntax' },
+
+  // === Type Errors (E100–E199) ===
+  E100: { code: 'E100', title: 'Type mismatch',                  category: 'type' },
+  E101: { code: 'E101', title: 'Return type mismatch',           category: 'type' },
+  E102: { code: 'E102', title: 'Cannot assign to type',          category: 'type' },
+  E103: { code: 'E103', title: 'Invalid argument type',          category: 'type' },
+  E104: { code: 'E104', title: 'Incompatible operand types',     category: 'type' },
+  E105: { code: 'E105', title: 'Cannot apply operator to type',  category: 'type' },
+
+  // === Scope / Definition Errors (E200–E299) ===
+  E200: { code: 'E200', title: 'Undefined variable',             category: 'scope' },
+  E201: { code: 'E201', title: 'Duplicate definition',           category: 'scope' },
+  E202: { code: 'E202', title: 'Cannot reassign immutable',      category: 'scope' },
+  E203: { code: 'E203', title: 'Invalid redeclaration',          category: 'scope' },
+
+  // === Context Errors (E300–E399) ===
+  E300: { code: 'E300', title: 'Invalid context: await',         category: 'context' },
+  E301: { code: 'E301', title: 'Invalid context: return',        category: 'context' },
+  E302: { code: 'E302', title: 'Invalid context: client-only',   category: 'context' },
+  E303: { code: 'E303', title: 'Invalid context: server-only',   category: 'context' },
+  E304: { code: 'E304', title: 'Invalid context: function-only', category: 'context' },
+
+  // === Import Errors (E400–E499) ===
+  E400: { code: 'E400', title: 'Invalid import',                 category: 'import' },
+  E401: { code: 'E401', title: 'Circular import',                category: 'import' },
+
+  // === Pattern Match Errors (E500–E599) ===
+  E500: { code: 'E500', title: 'Invalid pattern',                category: 'match' },
+
+  // === Trait / Impl Errors (E600–E699) ===
+  E600: { code: 'E600', title: 'Missing trait method',           category: 'trait' },
+  E601: { code: 'E601', title: 'Trait method signature mismatch', category: 'trait' },
+  E602: { code: 'E602', title: 'Unknown trait',                  category: 'trait' },
+};
+
+// ─── Warning Codes ───────────────────────────────────────────
+
+export const WarningCode = {
+  // === Unused (W001–W099) ===
+  W001: { code: 'W001', title: 'Unused variable',            category: 'unused' },
+  W002: { code: 'W002', title: 'Unused function',            category: 'unused' },
+  W003: { code: 'W003', title: 'Unused import',              category: 'unused' },
+
+  // === Style (W100–W199) ===
+  W100: { code: 'W100', title: 'Naming convention violation', category: 'style' },
+  W101: { code: 'W101', title: 'Variable shadows outer',      category: 'style' },
+
+  // === Potential Bugs (W200–W299) ===
+  W200: { code: 'W200', title: 'Non-exhaustive match',        category: 'match' },
+  W201: { code: 'W201', title: 'Unreachable code',            category: 'logic' },
+  W202: { code: 'W202', title: 'Condition always true',       category: 'logic' },
+  W203: { code: 'W203', title: 'Condition always false',      category: 'logic' },
+  W204: { code: 'W204', title: 'Potential data loss',         category: 'type' },
+  W205: { code: 'W205', title: 'Missing return on some paths', category: 'logic' },
+  W206: { code: 'W206', title: 'Non-Tova keyword used',       category: 'style' },
+  W207: { code: 'W207', title: 'Unreachable match arm',       category: 'match' },
+  W208: { code: 'W208', title: 'Defer outside function',      category: 'context' },
+
+  // === Trait Conformance (W300–W399) ===
+  W300: { code: 'W300', title: 'Missing trait method',        category: 'trait' },
+  W301: { code: 'W301', title: 'Trait parameter mismatch',    category: 'trait' },
+  W302: { code: 'W302', title: 'Trait return type mismatch',  category: 'trait' },
+  W303: { code: 'W303', title: 'Unknown derive trait',        category: 'trait' },
+};
+
+// ─── Lookup maps ─────────────────────────────────────────────
+
+const _allCodes = new Map();
+for (const entry of Object.values(ErrorCode)) _allCodes.set(entry.code, entry);
+for (const entry of Object.values(WarningCode)) _allCodes.set(entry.code, entry);
+
+export function lookupCode(code) {
+  return _allCodes.get(code) || null;
+}
+
+export function isErrorCode(code) {
+  return code.startsWith('E');
+}
+
+export function isWarningCode(code) {
+  return code.startsWith('W');
+}
+
+// ─── tova-ignore comment parsing ─────────────────────────────
+
+const IGNORE_PATTERN = /\/\/\s*tova-ignore\s+((?:[EW]\d{3}(?:\s*,\s*)?)+)/;
+
+export function parseIgnoreComment(line) {
+  const match = line.match(IGNORE_PATTERN);
+  if (!match) return null;
+  return match[1].split(',').map(c => c.trim()).filter(c => c);
+}
+
+// ─── Explanation text for --explain flag ─────────────────────
+
+const EXPLANATIONS = {
+  E001: `
+Unexpected token in source code.
+
+This error occurs when the parser encounters a token it doesn't expect
+in the current context.
+
+Example:
+    fn foo() {
+        x = 1 +
+    }            // error: unexpected '}', expected expression after '+'
+
+Fix: complete the expression or remove the trailing operator.
+`,
+  E100: `
+Type mismatch between expected and actual types.
+
+This error occurs when a value of one type is used where a different
+type is expected.
+
+Example:
+    fn add(a: Int, b: Int) -> Int {
+        return a + b
+    }
+    add("hello", 5)  // error: expected Int, got String
+
+Fix: ensure the value matches the expected type, or use a conversion
+function like to_int(), to_string(), etc.
+`,
+  E200: `
+Reference to an undefined variable or function.
+
+This error occurs when you use a name that hasn't been defined in the
+current scope or any parent scope.
+
+Example:
+    print(foo)  // error: 'foo' is not defined
+
+Fix: define the variable before using it, or check for typos.
+`,
+  E202: `
+Attempt to reassign an immutable variable.
+
+In Tova, variables bound with '=' are immutable by default. Use 'var'
+to create a mutable variable.
+
+Example:
+    x = 5
+    x = 10     // error: cannot reassign immutable variable 'x'
+
+    var y = 5
+    y = 10     // ok: 'var' makes it mutable
+
+Fix: change the declaration to 'var x = 5' if you need mutability.
+`,
+  E300: `
+'await' used outside an async function.
+
+The 'await' keyword can only be used inside functions declared with
+the 'async' keyword.
+
+Example:
+    fn fetch_data() {
+        data = await fetch("/api")  // error: await outside async
+
+    }
+
+    async fn fetch_data() {
+        data = await fetch("/api")  // ok
+    }
+
+Fix: add 'async' to the enclosing function declaration.
+`,
+  E302: `
+Client-only feature used outside a client block.
+
+Features like 'state', 'computed', 'effect', 'component', and 'store'
+can only be used inside a client { } block.
+
+Example:
+    state count = 0  // error: 'state' outside client block
+
+    client {
+        state count = 0  // ok
+    }
+
+Fix: move the code inside a client { } block.
+`,
+  E303: `
+Server-only feature used outside a server block.
+
+Features like 'route', 'middleware', 'ws', 'db', 'auth', etc.
+can only be used inside a server { } block.
+
+Example:
+    route GET "/api/users" => get_users  // error: outside server block
+
+    server {
+        route GET "/api/users" => get_users  // ok
+    }
+
+Fix: move the code inside a server { } block.
+`,
+  W001: `
+A variable is declared but never used.
+
+This warning helps catch typos and dead code.
+
+Example:
+    fn foo() {
+        x = 5       // warning: 'x' declared but never used
+        return 10
+    }
+
+Fix: remove the variable, or prefix with _ to suppress: _x = 5
+`,
+  W200: `
+A match expression doesn't cover all possible variants.
+
+This can lead to runtime errors if an unmatched variant is encountered.
+
+Example:
+    type Color = Red | Green | Blue
+    match color {
+        Red => "red"
+        Green => "green"
+    }  // warning: missing 'Blue' variant
+
+Fix: add the missing variants, or add a wildcard: _ => "other"
+`,
+  W204: `
+Implicit narrowing conversion that may lose data.
+
+Example:
+    x: Int = 3.14  // warning: assigning Float to Int loses decimal
+
+Fix: use an explicit conversion like floor(), round(), or to_int().
+`,
+};
+
+export function getExplanation(code) {
+  return EXPLANATIONS[code] || null;
+}

package/src/diagnostics/formatter.js

@@ -1,5 +1,23 @@
 // Rich error message formatter for the Tova language
-// Produces Rust/Elm-style error messages with source context and carets
+// Produces Rust/Elm-style error messages with source context, carets, and fix suggestions
+
+import { parseIgnoreComment } from './error-codes.js';
+
+// ─── ANSI color helpers (terminal only) ──────────────────────
+
+const _isTTY = typeof process !== 'undefined' && process.stderr && process.stderr.isTTY;
+
+const _c = {
+  red:     (s) => _isTTY ? `\x1b[31m${s}\x1b[0m` : s,
+  yellow:  (s) => _isTTY ? `\x1b[33m${s}\x1b[0m` : s,
+  cyan:    (s) => _isTTY ? `\x1b[36m${s}\x1b[0m` : s,
+  green:   (s) => _isTTY ? `\x1b[32m${s}\x1b[0m` : s,
+  blue:    (s) => _isTTY ? `\x1b[34m${s}\x1b[0m` : s,
+  dim:     (s) => _isTTY ? `\x1b[2m${s}\x1b[0m` : s,
+  bold:    (s) => _isTTY ? `\x1b[1m${s}\x1b[0m` : s,
+};
+
+// ─── DiagnosticFormatter ─────────────────────────────────────
 
 export class DiagnosticFormatter {
   constructor(source, filename = '<stdin>') {
@@ -8,24 +26,46 @@ export class DiagnosticFormatter {
     this.lines = source.split('\n');
   }
 
-  format(level, message, loc, hint = null) {
-    const line = loc.line || 1;
+  /**
+   * Format a diagnostic with full source context.
+   * @param {string} level     - 'error' | 'warning' | 'info' | 'hint'
+   * @param {string} message   - Human-readable message
+   * @param {object} loc       - { line, column }
+   * @param {object} [opts]    - { hint, code, length, fix }
+   *   hint:   string — suggestion text
+   *   code:   string — error code like 'E100'
+   *   length: number — underline length (default 1)
+   *   fix:    { description, replacement } — auto-fix suggestion
+   */
+  format(level, message, loc, opts = {}) {
+    // Backwards compat: opts can be a string (hint)
+    if (typeof opts === 'string') opts = { hint: opts };
+
+    const hint   = opts.hint || null;
+    const code   = opts.code || null;
+    const length = opts.length || 0;
+    const fix    = opts.fix || null;
+
+    const line   = loc.line || 1;
     const column = loc.column || 1;
     const lineNum = Math.max(1, Math.min(line, this.lines.length));
-    const gutterWidth = String(lineNum + 1).length;
+    const gutterWidth = Math.max(String(lineNum + 1).length, 3);
 
     let output = '';
 
-    // Header
-    const levelStr = level === 'error' ? 'error' : 'warning';
-    output += `${levelStr}: ${message}\n`;
-    output += `${' '.repeat(gutterWidth)} --> ${this.filename}:${lineNum}:${column}\n`;
+    // ── Header ──
+    const levelStr = level === 'error' ? _c.red(_c.bold('error'))
+                   : level === 'warning' ? _c.yellow(_c.bold('warning'))
+                   : _c.blue(_c.bold(level));
+    const codeStr = code ? _c.dim(`[${code}]`) + ' ' : '';
+    output += `${levelStr}: ${codeStr}${_c.bold(message)}\n`;
+    output += `${' '.repeat(gutterWidth)}${_c.blue(' -->')} ${this.filename}:${lineNum}:${column}\n`;
 
-    // Context lines
+    // ── Context lines ──
     const startLine = Math.max(1, lineNum - 2);
     const endLine = Math.min(this.lines.length, lineNum + 1);
 
-    output += `${' '.repeat(gutterWidth)} |\n`;
+    output += `${' '.repeat(gutterWidth)} ${_c.blue('|')}\n`;
 
     for (let i = startLine; i <= endLine; i++) {
       const lineContent = this.lines[i - 1] || '';
@@ -33,53 +73,79 @@ export class DiagnosticFormatter {
 
       if (i === lineNum) {
         // The error line
-        output += `${lineStr} | ${lineContent}\n`;
-        // Caret pointer
+        output += `${_c.blue(lineStr)} ${_c.blue('|')} ${lineContent}\n`;
+        // Underline with carets
         const caretPad = ' '.repeat(Math.max(0, column - 1));
-        output += `${' '.repeat(gutterWidth)} | ${caretPad}^\n`;
+        const underlineLen = Math.max(1, length || _guessLength(lineContent, column));
+        const underline = '^'.repeat(underlineLen);
+        const caretColor = level === 'error' ? _c.red : _c.yellow;
+        output += `${' '.repeat(gutterWidth)} ${_c.blue('|')} ${caretPad}${caretColor(underline)}\n`;
       } else {
-        output += `${lineStr} | ${lineContent}\n`;
+        output += `${_c.dim(lineStr)} ${_c.blue('|')} ${lineContent}\n`;
       }
     }
 
-    output += `${' '.repeat(gutterWidth)} |\n`;
+    output += `${' '.repeat(gutterWidth)} ${_c.blue('|')}\n`;
 
-    // Hint
+    // ── Hint ──
     if (hint) {
-      output += `${' '.repeat(gutterWidth)} = hint: ${hint}\n`;
+      output += `${' '.repeat(gutterWidth)} ${_c.blue('=')} ${_c.cyan('hint')}: ${hint}\n`;
+    }
+
+    // ── Fix suggestion ──
+    if (fix) {
+      output += `${' '.repeat(gutterWidth)} ${_c.blue('=')} ${_c.green('fix')}: ${fix.description}\n`;
+      if (fix.replacement !== undefined) {
+        output += `${' '.repeat(gutterWidth)}   ${_c.green('|')} ${_c.green(fix.replacement)}\n`;
+      }
     }
 
     return output;
   }
 
-  formatError(message, loc, hint = null) {
-    return this.format('error', message, loc, hint);
+  formatError(message, loc, hintOrOpts = null) {
+    const opts = typeof hintOrOpts === 'string' ? { hint: hintOrOpts } : (hintOrOpts || {});
+    return this.format('error', message, loc, opts);
   }
 
-  formatWarning(message, loc, hint = null) {
-    return this.format('warning', message, loc, hint);
+  formatWarning(message, loc, hintOrOpts = null) {
+    const opts = typeof hintOrOpts === 'string' ? { hint: hintOrOpts } : (hintOrOpts || {});
+    return this.format('warning', message, loc, opts);
   }
 }
 
-// Format errors from the Lexer, Parser, or Analyzer
+// Guess a reasonable underline length from the token at the given column
+function _guessLength(lineContent, column) {
+  const rest = lineContent.slice(column - 1);
+  // Try to find a word boundary
+  const wordMatch = rest.match(/^(\w+|[^\s]+)/);
+  if (wordMatch) return wordMatch[1].length;
+  return 1;
+}
+
+// ─── Format arrays of diagnostics ────────────────────────────
+
 export function formatDiagnostics(source, filename, errors, warnings = []) {
   const formatter = new DiagnosticFormatter(source, filename);
+  const ignoredCodes = _collectIgnoredCodes(source);
   let output = '';
 
   for (const err of errors) {
+    if (err.code && ignoredCodes.has(err.code)) continue;
     output += formatter.formatError(
       err.message,
       { line: err.line, column: err.column },
-      err.hint
+      { hint: err.hint, code: err.code, length: err.length, fix: err.fix }
     );
     output += '\n';
   }
 
   for (const warn of warnings) {
+    if (warn.code && ignoredCodes.has(warn.code)) continue;
     output += formatter.formatWarning(
       warn.message,
       { line: warn.line, column: warn.column },
-      warn.hint
+      { hint: warn.hint, code: warn.code, length: warn.length, fix: warn.fix }
     );
     output += '\n';
   }
@@ -87,7 +153,20 @@ export function formatDiagnostics(source, filename, errors, warnings = []) {
   return output;
 }
 
-// Helper: extract location from typical Tova error messages
+// Collect all tova-ignore codes from source comments
+function _collectIgnoredCodes(source) {
+  const codes = new Set();
+  for (const line of source.split('\n')) {
+    const parsed = parseIgnoreComment(line);
+    if (parsed) {
+      for (const c of parsed) codes.add(c);
+    }
+  }
+  return codes;
+}
+
+// ─── Helper: extract location from typical Tova error messages ──
+
 export function parseErrorLocation(errorMessage) {
   const match = errorMessage.match(/^(.+?):(\d+):(\d+)\s*[—-]\s*(.+)/);
   if (match) {
@@ -101,14 +180,47 @@ export function parseErrorLocation(errorMessage) {
   return null;
 }
 
-// Create a rich error from a Tova parse/analysis error
+// ─── Create a rich error from a Tova parse/analysis error ────
+
 export function richError(source, error, filename = '<stdin>') {
   const formatter = new DiagnosticFormatter(source, filename);
 
+  // If error carries structured errors, format them all
+  if (error.errors && Array.isArray(error.errors)) {
+    let output = '';
+    for (const e of error.errors) {
+      if (e.line && e.column) {
+        output += formatter.formatError(
+          e.message,
+          { line: e.line, column: e.column },
+          { hint: e.hint, code: e.code, length: e.length, fix: e.fix }
+        );
+        output += '\n';
+      } else if (e.loc) {
+        output += formatter.formatError(
+          e.message.replace(/^.+?:\d+:\d+\s*[—-]\s*/, ''),
+          { line: e.loc.line, column: e.loc.column },
+          { hint: e.hint, code: e.code }
+        );
+        output += '\n';
+      } else {
+        // Try to parse location from message
+        const loc = parseErrorLocation(e.message);
+        if (loc) {
+          output += formatter.formatError(loc.message, { line: loc.line, column: loc.column });
+          output += '\n';
+        } else {
+          output += formatter.formatError(e.message, { line: 1, column: 1 });
+          output += '\n';
+        }
+      }
+    }
+    return output || error.message;
+  }
+
   // Try to extract location from error message
   const loc = parseErrorLocation(error.message);
   if (loc) {
-    // Try to detect hint
     let hint = null;
     if (loc.message.includes("Expected '}'")) {
       hint = "check for a matching opening '{' above";
@@ -118,7 +230,7 @@ export function richError(source, error, filename = '<stdin>') {
       hint = "check for a matching opening '[' above";
     }
 
-    return formatter.formatError(loc.message, { line: loc.line, column: loc.column }, hint);
+    return formatter.formatError(loc.message, { line: loc.line, column: loc.column }, { hint });
   }
 
   // Fallback: try to parse the error for analysis errors
@@ -137,3 +249,13 @@ export function richError(source, error, filename = '<stdin>') {
 
   return error.message;
 }
+
+// ─── Summary line for CLI output ─────────────────────────────
+
+export function formatSummary(errorCount, warningCount) {
+  const parts = [];
+  if (errorCount > 0) parts.push(_c.red(`${errorCount} error${errorCount === 1 ? '' : 's'}`));
+  if (warningCount > 0) parts.push(_c.yellow(`${warningCount} warning${warningCount === 1 ? '' : 's'}`));
+  if (parts.length === 0) return _c.green('no errors');
+  return parts.join(', ') + ' emitted';
+}