Diagnostics

Every compiler phase emits structured diagnostics with stable error codes, exact source locations, and optional suggested fixes. Diagnostics are collected in a DiagnosticBag - never thrown as exceptions. This makes them ideal for AI agents that need to parse errors and self-correct.

Diagnostic Structure

Every diagnostic includes these fields:

diagnostics.json

{
  "phase": "binder",
  "category": "resolution_error",
  "severity": "error",
  "code": "PRD0201",
  "message": "Unknown symbol 'crm.customer'. Did you mean to import it?",
  "file": "billing.prd",
  "line": 4,
  "column": 14,
  "fix": {
    "description": "Add import for crm.customer",
    "edits": [
      {
        "line": 2,
        "column": 1,
        "text": "  import customer from crm\n"
      }
    ]
  }
}

Severity Levels

error - Compilation failure. Must be fixed before a valid Product Graph can be produced.
warning - Potential issue that won't block compilation but may indicate problems (e.g., unused imports, naming conventions).
info - Informational message for awareness (e.g., deprecation notices, optimization hints).

Error Code Ranges

Error codes are stable across compiler versions. Each phase has a reserved range:

Range	Phase	Examples
PRD0001–0099	Lexer	Unterminated strings, invalid characters, malformed numbers
PRD0100–0199	Parser	Missing braces, unexpected tokens, invalid syntax
PRD0200–0299	Binder	Unknown symbols, duplicate declarations, import errors
PRD0300–0399	Type Checker	Type mismatches, invalid generics, missing fields
PRD0400–0499	Validator	Invalid transitions, missing authorization, rule violations
PRD0500–0599	Graph Validator	Invalid edges, orphan nodes, self-references
PRD0600–0699	Registry	Missing packages, version conflicts
PRD0700–0799	Planner	Circular dependencies, unresolvable impacts
PRD0800–0899	Test Runner	Failed assertions, unknown targets, invalid expect keys

Diagnostic Categories

Beyond phase-based ranges, diagnostics are grouped into semantic categories:

lexical_error

Tokenization problems in source text

syntax_error

Invalid grammar or structure

resolution_error

Unresolved symbols or imports

type_error

Type checking failures

semantic_error

Business logic rule violations

graph_error

Product Graph structural issues

registry_error

Package registry problems

planning_error

Plan generation failures

test_failure

Spec test assertion failures

verification_error

Post-build verification problems

warning

Non-blocking issues and style hints

lint

Code quality and convention suggestions

Suggested Fixes

Many diagnostics include a fix property with a description and text edit suggestions. AI agents can automatically apply these fixes as part of an iterative compile/fix loop:

{
  "code": "PRD0301",
  "message": "Type 'string' is not assignable to field 'total' of type 'money'",
  "fix": {
    "description": "Change field type to 'money'",
    "edits": [
      { "line": 5, "column": 10, "delete": 6, "text": "money" }
    ]
  }
}

JSON Output

Use --format json to get machine-readable diagnostics from the CLI:

# Get diagnostics as JSON for AI agent consumption
prodara validate --format json ./project

# Full build also includes diagnostics in its output
prodara build --format json ./project

Or access diagnostics programmatically via the @prodara/compiler API:

import { compile, formatDiagnosticsJson } from '@prodara/compiler';

const result = await compile('./project');
const json = formatDiagnosticsJson(result.diagnostics);
console.log(json);