Refactor error handling in parser and semantic analyzer

- Introduced a new error handling system with specific error classes for compile-time errors.
- Replaced generic error messages with more descriptive and structured error types.
- Updated the parser to use the new error classes for expected token errors, invalid expressions, and semantic errors.
- Enhanced the semantic analyzer to log errors with source location and context.
- Improved error reporting in tests to reflect the new error structure.

Author: alec-jensen

docs/changelog.md

@@ -14,6 +14,7 @@ firescript follows [Semantic Versioning](https://semver.org/). This makes it eas
 
 ### Compiler improvements
 - Standard library modules can now import sibling modules using short relative paths (e.g., `import tuple.Tuple;`).
+- Compiler diagnostics are now unified under structured compile-time error objects across parser, semantic analysis, code generation, and `lint_text(...)`; this improves consistency of reported locations and diagnostics integrations (for example LSP).
 - Bug fixes
 - Fixed `for-in` loops and `length()` calls on array function parameters.
 - Fixed error caret positions for indented code.

firescript/codegen/base.py

@@ -1,5 +1,6 @@
 from enums import NodeTypes
 from parser import ASTNode, get_line_and_coumn_from_index, get_line
+from errors import CompileTimeError, CodegenError
 from utils.type_utils import is_copyable, is_owned, register_class
 from typing import Optional
 import logging
@@ -35,6 +36,7 @@ def __init__(self, ast: ASTNode, source_file: Optional[str] = None):
         self.ast = ast
         self.source_file = source_file
         self.source_code: Optional[str] = None
+        self.errors: list[CompileTimeError] = []
         self.symbol_table: SymbolTable = {}
         # Fixed-size array lengths by variable name
         self.array_lengths: dict[str, int] = {}
@@ -142,7 +144,12 @@ def __init__(self, ast: ASTNode, source_file: Optional[str] = None):
     def error(self, text: str, node: Optional[ASTNode] = None):
         """Report a compilation error with source location"""
         if node is None:
-            logging.error(text)
+            err = CodegenError(
+                message=text,
+                source_file=self.source_file,
+            )
+            self.errors.append(err)
+            logging.error(err.to_log_string())
             return
 
         # Get source file and source code for this node
@@ -160,22 +167,34 @@ def error(self, text: str, node: Optional[ASTNode] = None):
             node_source_file = self.source_file
 
         if node_source_file is None or node_source_code is None:
-            logging.error(text)
+            err = CodegenError(
+                message=text,
+                source_file=self.source_file,
+            )
+            self.errors.append(err)
+            logging.error(err.to_log_string())
             return
 
         try:
             line_num, column_num = get_line_and_coumn_from_index(node_source_code, node.index)
             line_text = get_line(node_source_code, line_num)
-            logging.error(
-                text
-                + f"\n> {line_text.rstrip()}\n"
-                + " " * (column_num + 1)
-                + "^"
-                + f"\n({node_source_file}:{line_num}:{column_num})"
+            err = CodegenError(
+                message=text,
+                source_file=node_source_file,
+                line=line_num,
+                column=column_num,
+                snippet=line_text,
             )
+            self.errors.append(err)
+            logging.error(err.to_log_string())
         except (IndexError, ValueError):
             # Node index is out of range - just show the error without source location
-            logging.error(text)
+            err = CodegenError(
+                message=text,
+                source_file=node_source_file,
+            )
+            self.errors.append(err)
+            logging.error(err.to_log_string())
 
     def _normalize_source_path(self, source_path: Optional[str]) -> Optional[str]:
         """Normalize a source path for directive/source-map lookups."""

firescript/errors.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class ErrorCategory(str, Enum):
+    PARSER = "parser"
+    SEMANTIC = "semantic"
+    CODEGEN = "codegen"
+    IMPORT = "import"
+
+
+class CompileTimeError:
+    code: str = "FS-COMP-0000"
+    category: ErrorCategory = ErrorCategory.PARSER
+    message_template: str = "{message}"
+
+    def __init__(
+        self,
+        *,
+        source_file: Optional[str] = None,
+        line: int = 0,
+        column: int = 0,
+        snippet: Optional[str] = None,
+        **context: object,
+    ):
+        self.source_file = source_file
+        self.line = line
+        self.column = column
+        self.snippet = snippet
+        self.message = self._render(context)
+
+    def _render(self, context: dict[str, object]) -> str:
+        try:
+            return self.message_template.format(**context)
+        except Exception:
+            # Fallback to avoid formatter crashes hiding the actual compiler error.
+            return self.message_template
+
+    def to_log_string(self) -> str:
+        header = self.message
+        if (
+            self.source_file
+            and self.line > 0
+            and self.column >= 0
+            and self.snippet is not None
+        ):
+            return (
+                header
+                + f"\n> {self.snippet.rstrip()}\n"
+                + " " * (self.column + 1)
+                + "^"
+                + f"\n({self.source_file}:{self.line}:{self.column})"
+            )
+        return header
+
+
+class ParserError(CompileTimeError):
+    code = "FS-PARSE-0001"
+    category = ErrorCategory.PARSER
+    message_template = "{message}"
+
+
+class UnexpectedTokenError(CompileTimeError):
+    code = "FS-PARSE-0002"
+    category = ErrorCategory.PARSER
+    message_template = "Expected {expected} but got {actual}"
+
+
+class UndefinedIdentifierError(CompileTimeError):
+    code = "FS-PARSE-0003"
+    category = ErrorCategory.PARSER
+    message_template = "Variable '{identifier}' not defined"
+
+
+class SemanticError(CompileTimeError):
+    code = "FS-SEM-0001"
+    category = ErrorCategory.SEMANTIC
+    message_template = "{message}"
+
+
+class TypeError(CompileTimeError):
+    code = "FS-SEM-0002"
+    category = ErrorCategory.SEMANTIC
+    message_template = "{detail}"
+
+
+class CodegenError(CompileTimeError):
+    code = "FS-CGEN-0001"
+    category = ErrorCategory.CODEGEN
+    message_template = "{message}"
+
+
+class ImportNotFoundError(CompileTimeError):
+    code = "FS-IMP-0001"
+    category = ErrorCategory.IMPORT
+    message_template = "Module not found: {module}"
+
+
+class CyclicImportError(CompileTimeError):
+    code = "FS-IMP-0002"
+    category = ErrorCategory.IMPORT
+    message_template = "Cyclic import detected: {cycle}"
+
+
+# Additional Parser Errors for specific syntax issues
+class ExpectedTokenError(CompileTimeError):
+    code = "FS-PARSE-0010"
+    category = ErrorCategory.PARSER
+    message_template = "Expected {expected}"
+
+
+class MissingIdentifierError(CompileTimeError):
+    code = "FS-PARSE-0011"
+    category = ErrorCategory.PARSER
+    message_template = "Expected identifier"
+
+
+class InvalidExpressionError(CompileTimeError):
+    code = "FS-PARSE-0012"
+    category = ErrorCategory.PARSER
+    message_template = "{detail}"
+
+
+class InvalidArrayAccessError(CompileTimeError):
+    code = "FS-PARSE-0013"
+    category = ErrorCategory.PARSER
+    message_template = "{detail}"
+
+
+class InvalidFieldAccessError(CompileTimeError):
+    code = "FS-PARSE-0014"
+    category = ErrorCategory.PARSER
+    message_template = "{detail}"
+
+
+# Type System Errors
+class InvalidTypeError(CompileTimeError):
+    code = "FS-SEM-0010"
+    category = ErrorCategory.SEMANTIC
+    message_template = "{detail}"
+
+
+class FieldNotFoundError(CompileTimeError):
+    code = "FS-SEM-0011"
+    category = ErrorCategory.SEMANTIC
+    message_template = "Type '{type_name}' has no field '{field_name}'"
+
+
+class MethodNotFoundError(CompileTimeError):
+    code = "FS-SEM-0012"
+    category = ErrorCategory.SEMANTIC
+    message_template = "Type '{type_name}' has no method '{method_name}'"
+
+
+class ConstructorNotFoundError(CompileTimeError):
+    code = "FS-SEM-0013"
+    category = ErrorCategory.SEMANTIC
+    message_template = "No constructor defined for type '{type_name}'"
+
+
+class InvalidOperatorError(CompileTimeError):
+    code = "FS-SEM-0014"
+    category = ErrorCategory.SEMANTIC
+    message_template = "Operator '{operator}' is not valid for type '{type_name}'"
+
+
+class ControlFlowError(CompileTimeError):
+    code = "FS-SEM-0015"
+    category = ErrorCategory.SEMANTIC
+    message_template = "{statement} statement not within a loop"
+
+
+class InvalidSuperError(CompileTimeError):
+    code = "FS-SEM-0016"
+    category = ErrorCategory.SEMANTIC
+    message_template = "{detail}"

firescript/frontend_pipeline.py

@@ -10,6 +10,7 @@
 from lexer import Lexer
 from parser import Parser, ASTNode
 from enums import NodeTypes
+from errors import UndefinedIdentifierError
 from imports import ModuleResolver, Module, build_merged_ast
 
 
@@ -69,6 +70,9 @@ def resolve_imports_and_deferred_identifiers(
                 for c in (merged_ast.children or [])
             ):
                 continue
-            parser_instance.error(f"Variable '{name}' not defined", tok)
+            parser_instance.report_error(
+                UndefinedIdentifierError(identifier=name, source_file=file_path),
+                token=tok,
+            )
 
     return merged_ast

firescript/imports.py

@@ -6,6 +6,7 @@
 from lexer import Lexer
 from parser import Parser, ASTNode
 from enums import NodeTypes
+from errors import ImportNotFoundError, CyclicImportError
 from compiler_types import SourceMap, MergedSymbolTable
 
 
@@ -99,8 +100,10 @@ def parse_file(self, file_path: str) -> tuple[ASTNode, str]:
         ast = parser.parse()
         if parser.errors:
             # Surface the first parser error to the caller
-            msg, line, col = parser.errors[0]
-            raise RuntimeError(f"Parse error in {file_path}: {msg} at {line}:{col}")
+            err = parser.errors[0]
+            raise RuntimeError(
+                f"Parse error in {file_path}: {err.message} at {err.line}:{err.column}"
+            )
         return ast, file_content
 
     def collect_exports(self, mod: Module) -> Dict[str, ASTNode]:
@@ -134,11 +137,13 @@ def _load_module(self, dotted: str, load_stack: List[str]) -> Module:
         # Cycle detection
         if dotted in load_stack:
             cycle = load_stack + [dotted]
-            raise RuntimeError("Cyclic import detected: " + " -> ".join(cycle))
+            err = CyclicImportError(cycle=" -> ".join(cycle))
+            raise RuntimeError(err.to_log_string())
 
         path = self.dotted_to_path(dotted)
         if not os.path.isfile(path):
-            raise FileNotFoundError(f"Module not found: {dotted} (looked in {path})")
+            err = ImportNotFoundError(module=f"{dotted} (looked in {path})")
+            raise FileNotFoundError(err.to_log_string())
 
         ast, source_text = self.parse_file(path)
         mod = Module(dotted, path, ast, source_text)

firescript/lsp/lsp_server.py

@@ -135,7 +135,10 @@ def _publish_diagnostics(ls: LanguageServer, uri: str, text: str, version: Optio
 
     source_lines = text.split("\n")
     diagnostics: list[Diagnostic] = []
-    for message, line, col in raw_errors:
+    for err in raw_errors:
+        message = err.message
+        line = err.line
+        col = err.column
         # lint_text returns 1-based line/col; LSP is 0-based.
         # When position is unavailable both are 0 — keep them at 0:0.
         lsp_line = max(0, line - 1) if line > 0 else 0

firescript/main.py

@@ -9,6 +9,7 @@
 
 from log_formatter import LogFormatter
 from compiler_pipeline import CompilerPipeline
+from errors import CompileTimeError
 
 FIRESCRIPT_VERSION = "0.4.0"
 FIRESCRIPT_RELEASE_DATE = "February 2, 2026"
@@ -129,6 +130,9 @@ def compile_file(file_path, target, cc=None, output=None):
         generator = CCodeGenerator(ast, source_file=file_path)
         generator.source_code = file_content
         output = generator.generate()
+        if generator.errors:
+            logging.error(f"Code generation failed with {len(generator.errors)} errors")
+            return False
         # Safety: wrap any raw free() calls emitted by codegen into firescript_free()
         # This prevents double-free and freeing static literals.
         output = output.replace(" free(", " firescript_free(")
@@ -248,16 +252,16 @@ def lint_text(source_text: str, file_path: str = "<stdin>"):
 
     Runs the full compiler front-end (lex → parse → import-merge → preprocess →
     semantic-analysis) against the given in-memory text and returns all collected
-    diagnostics as a list of ``(message, line, col)`` tuples (1-based line/col).
-    Line and col are both 0 when no position is available.
+    diagnostics as a list of CompileTimeError objects. Line and column are
+    1-based when available, otherwise 0.
 
     This function never writes to disk and never writes to logging — errors are
     returned purely as structured data so callers (e.g. the LSP server) can
     display them without polluting stdio.
     """
     import logging as _logging
 
-    errors: list[tuple[str, int, int]] = []
+    errors: list[CompileTimeError] = []
 
     # Silence the root logger while linting so that error() calls inside the
     # parser / semantic-analyser don't write to stderr and corrupt JSON-RPC I/O.