diagnostics

Provide one small diagnostics foundation that semantic analysis, lowering, native compilation, linking, and runtime feature resolution can all share.

Classes:

• Diagnostic –
• DiagnosticBag –
• DiagnosticCodeFormatter –
• DiagnosticCodes –
• DiagnosticRelatedInformation –
• IRxDiagnosticError –
• LinkingError –
• LoweringError –
• NativeCompileError –
• RuntimeFeatureError –
• SemanticError –
• SourceLocation –

Functions:

• format_diagnostic_code –
• format_source_location –
• get_diagnostic_code_formatter –
• get_node_module_key –
• get_node_source_location –
• set_diagnostic_code_formatter –
• set_diagnostic_code_prefix –
• source_location_from_loc –

Diagnostic dataclass

Diagnostic(
    message: str,
    node: AST | None = None,
    code: str | None = None,
    severity: str = "error",
    module_key: str | None = None,
    phase: str = "semantic",
    source: SourceLocation | None = None,
    notes: tuple[str, ...] = (),
    hint: str | None = None,
    cause: Exception | None = None,
    related: tuple[DiagnosticRelatedInformation, ...] = (),
)

Methods:

• format –
• rendered_code –
• resolved_module_key –
• resolved_source –

format

format(
    *, code_formatter: DiagnosticCodeFormatter | None = None
) -> str

Source code in src/irx/diagnostics.py

def format(
    self,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> str:
    """
    title: Format the diagnostic for human display.
    parameters:
      code_formatter:
        type: DiagnosticCodeFormatter | None
    returns:
      type: str
    """
    prefix = format_source_location(
        self.resolved_module_key(),
        self.resolved_source(),
    )
    prefix_text = f"{prefix}: " if prefix else ""
    rendered_code = self.rendered_code(code_formatter=code_formatter)
    label = self.severity
    if rendered_code is not None:
        label = f"{label}[{rendered_code}]"
    if self.phase and self.phase != "semantic":
        label = f"{label} ({self.phase})"

    lines = [f"{prefix_text}{label}: {self.message}"]
    for note in self.notes:
        lines.append(f"  note: {note}")
    if self.hint is not None:
        lines.append(f"  hint: {self.hint}")
    if self.cause is not None:
        cause_message = (
            str(self.cause).strip() or self.cause.__class__.__name__
        )
        lines.append(
            f"  cause: {self.cause.__class__.__name__}: {cause_message}"
        )
    for related in self.related:
        related_prefix = format_source_location(
            related.resolved_module_key(),
            related.resolved_source(),
        )
        related_text = (
            f"{related_prefix}: {related.message}"
            if related_prefix
            else related.message
        )
        lines.append(f"  related: {related_text}")
    return "\n".join(lines)

rendered_code

rendered_code(
    *, code_formatter: DiagnosticCodeFormatter | None = None
) -> str | None

Source code in src/irx/diagnostics.py

def rendered_code(
    self,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> str | None:
    """
    title: Return the final rendered diagnostic code.
    parameters:
      code_formatter:
        type: DiagnosticCodeFormatter | None
    returns:
      type: str | None
    """
    return format_diagnostic_code(
        self.code,
        code_formatter=code_formatter,
    )

resolved_module_key

resolved_module_key() -> str | None

Source code in src/irx/diagnostics.py

def resolved_module_key(self) -> str | None:
    """
    title: Return the diagnostic's best-effort module attribution.
    returns:
      type: str | None
    """
    return self.module_key or get_node_module_key(self.node)

resolved_source

resolved_source() -> SourceLocation | None

Source code in src/irx/diagnostics.py

def resolved_source(self) -> SourceLocation | None:
    """
    title: Return the diagnostic's best-effort source location.
    returns:
      type: SourceLocation | None
    """
    return self.source or get_node_source_location(self.node)

DiagnosticBag

DiagnosticBag()

Methods:

• add –
• extend –
• format –
• has_errors –
• raise_if_errors –

Source code in src/irx/diagnostics.py

def __init__(self) -> None:
    """
    title: Initialize DiagnosticBag.
    """
    self.diagnostics = []
    self.default_module_key = None

add

add(
    message: str,
    *,
    node: AST | None = None,
    code: str | None = None,
    severity: str = "error",
    module_key: str | None = None,
    phase: str = "semantic",
    source: SourceLocation | None = None,
    notes: Iterable[str] = (),
    hint: str | None = None,
    cause: Exception | None = None,
    related: Iterable[DiagnosticRelatedInformation] = (),
) -> None

Source code in src/irx/diagnostics.py

def add(
    self,
    message: str,
    *,
    node: astx.AST | None = None,
    code: str | None = None,
    severity: str = "error",
    module_key: str | None = None,
    phase: str = "semantic",
    source: SourceLocation | None = None,
    notes: Iterable[str] = (),
    hint: str | None = None,
    cause: Exception | None = None,
    related: Iterable[DiagnosticRelatedInformation] = (),
) -> None:
    """
    title: Add one diagnostic to the bag.
    parameters:
      message:
        type: str
      node:
        type: astx.AST | None
      code:
        type: str | None
      severity:
        type: str
      module_key:
        type: str | None
      phase:
        type: str
      source:
        type: SourceLocation | None
      notes:
        type: Iterable[str]
      hint:
        type: str | None
      cause:
        type: Exception | None
      related:
        type: Iterable[DiagnosticRelatedInformation]
    """
    self.diagnostics.append(
        Diagnostic(
            message=message,
            node=node,
            code=code,
            severity=severity,
            module_key=module_key or self.default_module_key,
            phase=phase,
            source=source,
            notes=tuple(notes),
            hint=hint,
            cause=cause,
            related=tuple(related),
        )
    )

extend

extend(diagnostics: Iterable[Diagnostic]) -> None

Source code in src/irx/diagnostics.py

def extend(self, diagnostics: Iterable[Diagnostic]) -> None:
    """
    title: Extend the bag with additional diagnostics.
    parameters:
      diagnostics:
        type: Iterable[Diagnostic]
    """
    self.diagnostics.extend(diagnostics)

format

format(
    *, code_formatter: DiagnosticCodeFormatter | None = None
) -> str

Source code in src/irx/diagnostics.py

def format(
    self,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> str:
    """
    title: Format the whole bag.
    parameters:
      code_formatter:
        type: DiagnosticCodeFormatter | None
    returns:
      type: str
    """
    return "\n".join(
        diagnostic.format(code_formatter=code_formatter)
        for diagnostic in self.diagnostics
    )

has_errors

has_errors() -> bool

Source code in src/irx/diagnostics.py

def has_errors(self) -> bool:
    """
    title: Return True when the bag contains diagnostics.
    returns:
      type: bool
    """
    return bool(self.diagnostics)

raise_if_errors

raise_if_errors() -> None

Source code in src/irx/diagnostics.py

def raise_if_errors(self) -> None:
    """
    title: Raise SemanticError when diagnostics exist.
    """
    if self.has_errors():
        raise SemanticError(self)

DiagnosticCodeFormatter dataclass

DiagnosticCodeFormatter(
    prefix: str = DEFAULT_DIAGNOSTIC_CODE_PREFIX,
)

Methods:

• format –

format

format(code: str | None) -> str | None

Source code in src/irx/diagnostics.py

def format(self, code: str | None) -> str | None:
    """
    title: Format one logical diagnostic identifier.
    parameters:
      code:
        type: str | None
    returns:
      type: str | None
    """
    if code is None:
        return None
    stripped = code.strip()
    if not stripped:
        return None
    if _RENDERED_CODE_PATTERN.match(stripped):
        return stripped
    return f"{self.prefix}{stripped}"

DiagnosticCodes

Group the most important semantic, lowering, FFI, runtime, compile, and link families under short stable identifiers. These identifiers are rendered through one shared DiagnosticCodeFormatter.

DiagnosticRelatedInformation dataclass

DiagnosticRelatedInformation(
    message: str,
    node: AST | None = None,
    module_key: str | None = None,
    source: SourceLocation | None = None,
)

Methods:

• resolved_module_key –
• resolved_source –

resolved_module_key

resolved_module_key() -> str | None

Source code in src/irx/diagnostics.py

def resolved_module_key(self) -> str | None:
    """
    title: Return the related entry's module attribution.
    returns:
      type: str | None
    """
    return self.module_key or get_node_module_key(self.node)

resolved_source

resolved_source() -> SourceLocation | None

Source code in src/irx/diagnostics.py

def resolved_source(self) -> SourceLocation | None:
    """
    title: Return the related entry's source location.
    returns:
      type: SourceLocation | None
    """
    return self.source or get_node_source_location(self.node)

IRxDiagnosticError

IRxDiagnosticError(
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
)

Bases: Exception

Methods:

• format –

Source code in src/irx/diagnostics.py

def __init__(
    self,
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> None:
    """
    title: Initialize IRxDiagnosticError.
    parameters:
      diagnostic:
        type: Diagnostic
      code_formatter:
        type: DiagnosticCodeFormatter | None
    """
    self.diagnostic = diagnostic
    self.code_formatter = code_formatter or get_diagnostic_code_formatter()
    super().__init__(diagnostic.format(code_formatter=self.code_formatter))

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Return the formatted diagnostic message.
    returns:
      type: str
    """
    return self.diagnostic.format(code_formatter=self.code_formatter)

LinkingError

LinkingError(
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
)

Bases: IRxDiagnosticError

Methods:

• format –

Source code in src/irx/diagnostics.py

def __init__(
    self,
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> None:
    """
    title: Initialize IRxDiagnosticError.
    parameters:
      diagnostic:
        type: Diagnostic
      code_formatter:
        type: DiagnosticCodeFormatter | None
    """
    self.diagnostic = diagnostic
    self.code_formatter = code_formatter or get_diagnostic_code_formatter()
    super().__init__(diagnostic.format(code_formatter=self.code_formatter))

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Return the formatted diagnostic message.
    returns:
      type: str
    """
    return self.diagnostic.format(code_formatter=self.code_formatter)

LoweringError

LoweringError(
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
)

Bases: IRxDiagnosticError

Methods:

• format –

Source code in src/irx/diagnostics.py

def __init__(
    self,
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> None:
    """
    title: Initialize IRxDiagnosticError.
    parameters:
      diagnostic:
        type: Diagnostic
      code_formatter:
        type: DiagnosticCodeFormatter | None
    """
    self.diagnostic = diagnostic
    self.code_formatter = code_formatter or get_diagnostic_code_formatter()
    super().__init__(diagnostic.format(code_formatter=self.code_formatter))

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Return the formatted diagnostic message.
    returns:
      type: str
    """
    return self.diagnostic.format(code_formatter=self.code_formatter)

NativeCompileError

NativeCompileError(
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
)

Bases: IRxDiagnosticError

Methods:

• format –

Source code in src/irx/diagnostics.py

def __init__(
    self,
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> None:
    """
    title: Initialize IRxDiagnosticError.
    parameters:
      diagnostic:
        type: Diagnostic
      code_formatter:
        type: DiagnosticCodeFormatter | None
    """
    self.diagnostic = diagnostic
    self.code_formatter = code_formatter or get_diagnostic_code_formatter()
    super().__init__(diagnostic.format(code_formatter=self.code_formatter))

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Return the formatted diagnostic message.
    returns:
      type: str
    """
    return self.diagnostic.format(code_formatter=self.code_formatter)

RuntimeFeatureError

RuntimeFeatureError(
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
)

Bases: IRxDiagnosticError

Methods:

• format –

Source code in src/irx/diagnostics.py

def __init__(
    self,
    diagnostic: Diagnostic,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> None:
    """
    title: Initialize IRxDiagnosticError.
    parameters:
      diagnostic:
        type: Diagnostic
      code_formatter:
        type: DiagnosticCodeFormatter | None
    """
    self.diagnostic = diagnostic
    self.code_formatter = code_formatter or get_diagnostic_code_formatter()
    super().__init__(diagnostic.format(code_formatter=self.code_formatter))

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Return the formatted diagnostic message.
    returns:
      type: str
    """
    return self.diagnostic.format(code_formatter=self.code_formatter)

SemanticError

SemanticError(
    diagnostics: DiagnosticBag,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
)

Bases: Exception

Methods:

• format –

Source code in src/irx/diagnostics.py

def __init__(
    self,
    diagnostics: DiagnosticBag,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> None:
    """
    title: Initialize SemanticError.
    parameters:
      diagnostics:
        type: DiagnosticBag
      code_formatter:
        type: DiagnosticCodeFormatter | None
    """
    self.diagnostics = diagnostics
    self.code_formatter = code_formatter or get_diagnostic_code_formatter()
    super().__init__(
        diagnostics.format(code_formatter=self.code_formatter)
    )

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Return the formatted diagnostic bag.
    returns:
      type: str
    """
    return self.diagnostics.format(code_formatter=self.code_formatter)

SourceLocation dataclass

SourceLocation(
    line: int | None = None,
    col: int | None = None,
    end_line: int | None = None,
    end_col: int | None = None,
)

Methods:

• format –
• is_known –

format

format() -> str

Source code in src/irx/diagnostics.py

def format(self) -> str:
    """
    title: Render one location without module identity.
    returns:
      type: str
    """
    if self.line is None:
        return ""
    if self.col is None:
        return str(self.line)
    return f"{self.line}:{self.col}"

is_known

is_known() -> bool

Source code in src/irx/diagnostics.py

def is_known(self) -> bool:
    """
    title: Return whether any source position is known.
    returns:
      type: bool
    """
    return self.line is not None or self.col is not None

format_diagnostic_code

format_diagnostic_code(
    code: str | None,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> str | None

Source code in src/irx/diagnostics.py

@public
@typechecked
def format_diagnostic_code(
    code: str | None,
    *,
    code_formatter: DiagnosticCodeFormatter | None = None,
) -> str | None:
    """
    title: Render one logical diagnostic identifier.
    parameters:
      code:
        type: str | None
      code_formatter:
        type: DiagnosticCodeFormatter | None
    returns:
      type: str | None
    """
    formatter = code_formatter or get_diagnostic_code_formatter()
    return formatter.format(code)

format_source_location

format_source_location(
    module_key: str | None = None,
    source: SourceLocation | None = None,
) -> str

Source code in src/irx/diagnostics.py

@public
@typechecked
def format_source_location(
    module_key: str | None = None,
    source: SourceLocation | None = None,
) -> str:
    """
    title: Format one module-aware source location.
    parameters:
      module_key:
        type: str | None
      source:
        type: SourceLocation | None
    returns:
      type: str
    """
    location_text = source.format() if source is not None else ""
    if module_key and location_text:
        return f"{module_key}:{location_text}"
    if module_key:
        return module_key
    return location_text

get_diagnostic_code_formatter

get_diagnostic_code_formatter() -> DiagnosticCodeFormatter

Source code in src/irx/diagnostics.py

@public
@typechecked
def get_diagnostic_code_formatter() -> DiagnosticCodeFormatter:
    """
    title: Return the active diagnostic-code formatter.
    returns:
      type: DiagnosticCodeFormatter
    """
    return _DIAGNOSTIC_CODE_FORMATTER

get_node_module_key

get_node_module_key(node: AST | None) -> str | None

Source code in src/irx/diagnostics.py

@public
@typechecked
def get_node_module_key(node: astx.AST | None) -> str | None:
    """
    title: Return one AST node's best-effort module attribution.
    parameters:
      node:
        type: astx.AST | None
    returns:
      type: str | None
    """
    if node is None:
        return None

    direct = _string_or_none(getattr(node, "module_key", None))
    if direct is not None:
        return direct

    semantic = getattr(node, "semantic", None)
    if semantic is None:
        return None

    candidates: list[object] = [
        getattr(semantic, "resolved_function", None),
        getattr(semantic, "resolved_symbol", None),
        getattr(semantic, "resolved_struct", None),
        getattr(semantic, "resolved_module", None),
    ]
    resolved_call = getattr(semantic, "resolved_call", None)
    if resolved_call is not None:
        candidates.append(
            getattr(getattr(resolved_call, "callee", None), "function", None)
        )
    resolved_return = getattr(semantic, "resolved_return", None)
    if resolved_return is not None:
        candidates.append(
            getattr(
                getattr(resolved_return, "callable", None), "function", None
            )
        )
    resolved_assignment = getattr(semantic, "resolved_assignment", None)
    if resolved_assignment is not None:
        candidates.append(getattr(resolved_assignment, "target", None))
    resolved_field_access = getattr(semantic, "resolved_field_access", None)
    if resolved_field_access is not None:
        candidates.append(getattr(resolved_field_access, "struct", None))

    for candidate in candidates:
        module_key = _string_or_none(getattr(candidate, "module_key", None))
        if module_key is not None:
            return module_key
    return None

get_node_source_location

get_node_source_location(
    node: AST | None,
) -> SourceLocation | None

Source code in src/irx/diagnostics.py

@public
@typechecked
def get_node_source_location(node: astx.AST | None) -> SourceLocation | None:
    """
    title: Return one AST node's best-effort source location.
    parameters:
      node:
        type: astx.AST | None
    returns:
      type: SourceLocation | None
    """
    if node is None:
        return None
    return source_location_from_loc(getattr(node, "loc", None))

set_diagnostic_code_formatter

set_diagnostic_code_formatter(
    formatter: DiagnosticCodeFormatter,
) -> DiagnosticCodeFormatter

Source code in src/irx/diagnostics.py

@public
@typechecked
def set_diagnostic_code_formatter(
    formatter: DiagnosticCodeFormatter,
) -> DiagnosticCodeFormatter:
    """
    title: Replace the process-wide diagnostic-code formatter.
    parameters:
      formatter:
        type: DiagnosticCodeFormatter
    returns:
      type: DiagnosticCodeFormatter
    """
    globals()["_DIAGNOSTIC_CODE_FORMATTER"] = formatter
    return formatter

set_diagnostic_code_prefix

set_diagnostic_code_prefix(
    prefix: str,
) -> DiagnosticCodeFormatter

Source code in src/irx/diagnostics.py

@public
@typechecked
def set_diagnostic_code_prefix(prefix: str) -> DiagnosticCodeFormatter:
    """
    title: Configure the process-wide diagnostic-code prefix.
    parameters:
      prefix:
        type: str
    returns:
      type: DiagnosticCodeFormatter
    """
    return set_diagnostic_code_formatter(DiagnosticCodeFormatter(prefix))

source_location_from_loc

source_location_from_loc(
    loc: object | None,
) -> SourceLocation | None

Source code in src/irx/diagnostics.py

@public
@typechecked
def source_location_from_loc(loc: object | None) -> SourceLocation | None:
    """
    title: Convert one arbitrary location-like object to SourceLocation.
    parameters:
      loc:
        type: object | None
    returns:
      type: SourceLocation | None
    """
    if loc is None:
        return None
    line = _non_negative_int(getattr(loc, "line", None))
    col = _non_negative_int(getattr(loc, "col", getattr(loc, "column", None)))
    end_line = _non_negative_int(getattr(loc, "end_line", None))
    end_col = _non_negative_int(
        getattr(loc, "end_col", getattr(loc, "end_column", None))
    )
    source = SourceLocation(
        line=line,
        col=col,
        end_line=end_line,
        end_col=end_col,
    )
    if not source.is_known():
        return None
    return source