Diagnostic and Error Codes Specification

Purpose

The ARES Diagnostic system provides granular feedback to the software developer during all phases of the compilation pipeline. It aims to be "human-readable but machine-parsable," returning structured CompilerError objects (types.ts:34) that pinpoint the exact filename, line, and column of a syntax violation or semantic mismatch. This document serves as the canonical reference for all diagnostic levels and their troubleshooting procedures.

Prerequisites

• None.

Diagnostic Levels

Operational Behavior

1. Phase 1 (Lexing): Detects unmatched string quotes, non-ARES characters, or reserved keyword misuse.
2. Phase 2 (Parsing): Detects grammar violations (e.g., missing semicolons, unmatched braces) via Chevrotain's error reporting.
3. Phase 3 (Semantic Analysis): Detects type mismatches, unbound identifiers, and invalid intent parameters.
4. Phase 5 (Routing): Provides warnings if a high-complexity script is forced into an inefficient target backend (e.g., $O(N^2)$ in Python).

Implementation Mapping

Incorrect ARES Source vs. Diagnostic Output

Example 1: Syntax Mismatch (ParseError)

Incorrect Source:

ares
if x > 0 
    print x
// Missing braces for the block

Diagnostic Output:

json
{
  "type": "ParseError",
  "line": 2,
  "column": 5,
  "message": "Expecting token of type --> LCurly <-- but found --> Print <--",
  "severity": "error"
}

Example 2: Type Conflict (SemanticError)

Incorrect Source:

ares
let count: int = "forty-two"

Diagnostic Output:

json
{
  "type": "SemanticError",
  "line": 1,
  "column": 18,
  "message": "Type mismatch: Cannot assign StringLiteral to Variable of type int.",
  "severity": "error"
}

Example 3: Routing Warning (Info/Warning)

Source:

ares
using python
use matrix_multiply on big_data
// O(N^3) on large data in Python

Diagnostic Output:

json
{
  "type": "RoutingInfo",
  "severity": "warning",
  "message": "Caution: Forcing Python target for O(N^3) task on potential large dataset. Performance may be degraded."
}

Mathematical Model

The total number of diagnostics $\mathcal{D}$ for a program $P$ is the union of errors from all pipeline stages $\Sigma$: $\mathcal{D}(P) = \bigcup_{i \in \Sigma} \mathcal{E}_i(P)$ The compilation is successful if and only if: $\forall e \in \mathcal{D}(P), \text{Severity}(e) \neq \text{error}$

Complexity

• Error Detection: $O(V)$ proportional to AST nodes or tokens.
• Reporting overhead: $O(1)$ constant time per error generated.

Examples

Defining a Custom Semantic Error: If isSorted is required for a binary_search intent but not found, the analyzer.ts generates a SemanticError warning instead of a hard crash.

Traces

Trace for let x = undefined_var:

1. Analyzer scans visitLet.
2. Initializer lookup finds undefined_var.
3. Symbol table check returns null.
4. diagnostics.push() adds the SemanticError with the identifier's source location.
5. Compilation proceeds for other nodes but Phase 3 marked as failed.

Edge Cases

• Lookahead Errors: In Phase 2, if the parser is deep in a nested rule, it may return a list of expected tokens rather than a single specific error. ARES selects the most probable candidate for reporting.
• Lazy Diagnostics: Warnings about missing formatting tools (black, prettier) are only emitted at the end of Phase 7 (Codegen).

Failure Modes

• Cascading Errors: A single syntax error (e.g., missing {) can trigger multiple subsequent ParseError reports as the parser struggles to re-sync. Developers should focus on the FIRST reported error.
• Suppressed Warnings: The --silent CLI flag suppresses info and warning diagnostics but never error.

Compatibility

• IDE Support: Diagnostic objects follow a subset of the Language Server Protocol (LSP) format for easy integration.

Testing

• Diagnostic Integrity: tests/diagnostics.test.ts runs 20+ "broken" ARES scripts and asserts that the compiler returns the correct type and message for each.
• Location Accuracy: Verifies that reported line and column numbers match the physical location of the error in the source file.

Related Entities

• src/types.ts: The CompilerError interface.
• 5_api_reference/01_compiler_api.md: How diagnostics are returned in the CompilationResult.

Source Attribution

• Component: src/semantics/analyzer.ts (Semantics), src/parser/parser.ts (Syntax).
• Standards: Follows LLVM and Rust diagnostic best-practice formatting.