docs: add source location error messages design document

2026-06-10 19:56:55 +03:00
parent 2824d25369
commit de3ac76581
1 changed files with 239 additions and 0 deletions
@@ -0,0 +1,239 @@
+# Bux Source Location Tracking in Error Messages — Design Document
+
+> **Date:** 2026-06-10
+> **Status:** Design Approved
+> **Scope:** MVP Rust-style error messages with code snippets for parser and sema diagnostics
+
+---
+
+## 1. Overview
+
+The Bux self-hosted compiler already tracks source locations (lexer tokens have line/column, AST nodes have line/column, parser and sema have diagnostic structs with line/column). However, the CLI prints errors as plain strings or raw `line X col Y` text, without code snippets or consistent formatting.
+
+This feature unifies and improves error display to match the Rust-style format:
+```
+error: type mismatch
+  --> src/Main.bux:42:15
+   |
+42 | let x: int = "hello";
+   |              ^
+```
+
+### Goals
+- Unified Rust-style error formatting for all parser and sema diagnostics
+- Code snippets showing the exact line with an underline
+- Consistent severity prefixes (`error:`, `warning:`, `note:`)
+
+### Non-Goals (for MVP)
+- Source maps (mapping merged-source line numbers back to original files)
+- Multi-line error spans
+- Multi-character underlines (`^^^^` for entire tokens)
+- Colorized output
+- Error codes (e.g., `E0001`)
+- HIR lower / C backend diagnostics (these phases do not currently emit errors)
+
+---
+
+## 2. Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  Parser/Sema Diagnostics                │
+│  ParserDiag { line, col, message }      │
+│  SemaDiag   { line, col, message }      │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│  Unified Diagnostic Formatter           │
+│  (inline in cli.bux or lib/Diagnostic)  │
+│  • Reads source line from file          │
+│  • Formats snippet with underline       │
+│  • Prints Rust-style error block        │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│  CLI Output                             │
+│  error: type mismatch                   │
+│    --> src/Main.bux:42:15               │
+│     |                                   │
+│  42 | let x: int = "hello";             │
+│     |              ^                    │
+└─────────────────────────────────────────┘
+```
+
+### Components
+
+1. **Source Line Loader** — reads a specific line from a source file
+2. **Snippet Renderer** — formats `line_num | code` + underline
+3. **Diagnostic Printer** — assembles the full Rust-style error block
+
+**Note:** Bux compiles a merged source file (all `.bux` files merged before compilation). For MVP, snippets show lines from the merged source. Source map tracking (which original file a line came from) is future work.
+
+---
+
+## 3. Data Structures
+
+```bux
+struct Diagnostic {
+    message: String;
+    line: uint32;       /* 1-based */
+    column: uint32;     /* 1-based */
+    severity: int;      /* 0=error, 1=warning, 2=note */
+}
+```
+
+**Severity values:**
+- `0` — `error:`
+- `1` — `warning:`
+- `2` — `note:`
+
+For MVP, parser and sema diagnostics are always severity `0` (error). Warning/note severity is reserved for future use.
+
+---
+
+## 4. API Design
+
+```bux
+/* Print a single diagnostic in Rust-style format */
+func Diagnostic_Print(diag: *Diagnostic, sourcePath: String);
+
+/* Helper: read line N from a file (1-based) */
+func Diagnostic_GetLine(path: String, lineNum: uint32) -> String;
+```
+
+### Output Format
+
+```
+error: <message>
+  --> <path>:<line>:<col>
+   |
+<ln> | <source_line>
+   | <spaces>^
+```
+
+Where:
+- `<ln>` is the line number, right-aligned
+- `<spaces>` is `column - 1` spaces to position the `^`
+- If `source_line` is empty (file not found), only the header is printed
+
+---
+
+## 5. Snippet Rendering Algorithm
+
+### `Diagnostic_GetLine(path, lineNum)`
+
+1. Open the file at `path`
+2. Read character by character, counting newlines
+3. When reaching line `lineNum`, accumulate characters until `\n` or EOF
+4. Return the accumulated string (without trailing `\n`)
+5. If file cannot be opened or `lineNum` exceeds file length, return `""`
+
+### `Diagnostic_Print(diag, sourcePath)`
+
+```
+Print severity prefix + message
+Print "  --> " + sourcePath + ":" + line + ":" + column + "\n"
+Print "   |\n"
+Print line number + " | " + source line + "\n"
+Print "   | " + (column-1 spaces) + "^\n"
+```
+
+**Underline:** Single `^` at the column position. Multi-character spans are future work.
+
+---
+
+## 6. Integration Points
+
+### Parser Diagnostics
+
+**Current code** (`src/cli.bux`, lexer error printing):
+```bux
+PrintLine(lex.diags[i].message);
+```
+
+**New code:**
+```bux
+let diag: Diagnostic = Diagnostic {
+    message: lex.diags[i].message,
+    line: lex.diags[i].line,
+    column: lex.diags[i].column,
+    severity: 0,
+};
+Diagnostic_Print(&diag, sourcePath);
+```
+
+### Sema Diagnostics
+
+**Current code** (`src/cli.bux`, `Cli_Compile` path):
+```bux
+PrintLine(sema.diags[i].message);
+```
+
+**Current code** (`src/cli.bux`, `Cli_BuildProject` path):
+```bux
+Print("  line "); PrintInt(sema.diags[i].line as int64);
+Print(" col ");  PrintInt(sema.diags[i].column as int64);
+Print(": ");     PrintLine(sema.diags[i].message);
+```
+
+**New code (both paths):**
+```bux
+let diag: Diagnostic = Diagnostic {
+    message: sema.diags[i].message,
+    line: sema.diags[i].line,
+    column: sema.diags[i].column,
+    severity: 0,
+};
+Diagnostic_Print(&diag, sourcePath);
+```
+
+### Unified Helper
+
+Add to `src/cli.bux`:
+```bux
+func Cli_ReportSemaErrors(sema: *Sema, sourcePath: String) {
+    let i: int = 0;
+    while i < Sema_DiagCount(sema) {
+        let d: SemaDiag = sema.diags[i];
+        let diag: Diagnostic = Diagnostic {
+            message: d.message, line: d.line,
+            column: d.column, severity: 0,
+        };
+        Diagnostic_Print(&diag, sourcePath);
+        i = i + 1;
+    }
+}
+```
+
+---
+
+## 7. Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/cli.bux` | Replace all manual error printing with `Diagnostic_Print`. Add `Diagnostic` struct and helper functions. |
+
+**No changes needed to:**
+- `src/lexer.bux` — already emits `LexerDiag` with line/col
+- `src/parser.bux` — already emits `ParserDiag` with line/col
+- `src/sema.bux` — already emits `SemaDiag` with line/col via `Sema_EmitError`
+- `src/ast.bux` — already stores line/col on every node
+- `src/hir.bux` — already stores line/col on HIR nodes
+
+---
+
+## 8. Testing Strategy
+
+1. **Type error test:** Create a `.bux` file with `let x: int = "hello";` → build → verify Rust-style output with snippet
+2. **Syntax error test:** Create a `.bux` file with missing `}` → build → verify parser error shows snippet
+3. **Selfhost loop:** Verify compiler C output remains identical (CLI changes do not affect codegen)
+
+---
+
+## 9. Future Work
+
+- **Source maps:** Track which original file each merged line came from, so errors show original paths
+- **Multi-character underlines:** Underline entire token/span, not just a single `^`
+- **Colorized output:** ANSI color codes for error/warning/note
+- **Error codes:** Assign stable codes like `E0001` for each error type
+- **Notes and help text:** Attach explanatory notes to errors (Rust's `help:` and `note:` blocks)