irx.diagnostics

Source: packages/irx/src/irx/diagnostics.py

title: Shared diagnostics and source-location helpers.
summary: >-
  Provide one small diagnostics foundation that semantic analysis, lowering,
  native compilation, linking, and runtime feature resolution can all share.

Functions

get_diagnostic_code_formatter() -> DiagnosticCodeFormatter

title: Return the active diagnostic-code formatter.
returns:
  type: DiagnosticCodeFormatter

set_diagnostic_code_formatter(formatter: DiagnosticCodeFormatter) -> DiagnosticCodeFormatter

title: Replace the process-wide diagnostic-code formatter.
parameters:
  formatter:
    type: DiagnosticCodeFormatter
returns:
  type: DiagnosticCodeFormatter

set_diagnostic_code_prefix(prefix: str) -> DiagnosticCodeFormatter

title: Configure the process-wide diagnostic-code prefix.
parameters:
  prefix:
    type: str
returns:
  type: DiagnosticCodeFormatter

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

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

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

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

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

Classes

DiagnosticCodeFormatter

title: Render logical diagnostic identifiers with one configurable prefix.
attributes:
  prefix:
    type: str

Methods

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

title: Format one logical diagnostic identifier.
parameters:
  code:
    type: str | None
returns:
  type: str | None

SourceLocation

title: One best-effort source location.
attributes:
  line:
    type: int | None
  col:
    type: int | None
  end_line:
    type: int | None
  end_col:
    type: int | None

Methods

is_known(self) -> bool

title: Return whether any source position is known.
returns:
  type: bool

format(self) -> str

title: Render one location without module identity.
returns:
  type: str

DiagnosticRelatedInformation

title: One secondary diagnostic location or note.
attributes:
  message:
    type: str
  node:
    type: astx.AST | None
  module_key:
    type: str | None
  source:
    type: SourceLocation | None

Methods

resolved_source(self) -> SourceLocation | None

title: Return the related entry's source location.
returns:
  type: SourceLocation | None

resolved_module_key(self) -> str | None

title: Return the related entry's module attribution.
returns:
  type: str | None

Diagnostic

title: One structured diagnostic record.
attributes:
  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: tuple[str, Ellipsis]
  hint:
    type: str | None
  cause:
    type: Exception | None
  related:
    type: tuple[DiagnosticRelatedInformation, Ellipsis]

Methods

resolved_source(self) -> SourceLocation | None

title: Return the diagnostic's best-effort source location.
returns:
  type: SourceLocation | None

resolved_module_key(self) -> str | None

title: Return the diagnostic's best-effort module attribution.
returns:
  type: str | None

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

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

title: Format the diagnostic for human display.
parameters:
  code_formatter:
    type: DiagnosticCodeFormatter | None
returns:
  type: str

DiagnosticBag

title: Collect diagnostics across one semantic-analysis attempt.
attributes:
  diagnostics:
    type: list[Diagnostic]
  default_module_key:
    type: str | None

Methods

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]

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

title: Extend the bag with additional diagnostics.
parameters:
  diagnostics:
    type: Iterable[Diagnostic]

has_errors(self) -> bool

title: Return True when the bag contains diagnostics.
returns:
  type: bool

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

title: Format the whole bag.
parameters:
  code_formatter:
    type: DiagnosticCodeFormatter | None
returns:
  type: str

raise_if_errors(self) -> None

title: Raise SemanticError when diagnostics exist.

IRxDiagnosticError(Exception)

title: Raised when one non-semantic compiler phase emits a diagnostic.
attributes:
  diagnostic:
    type: Diagnostic
  code_formatter:
    type: DiagnosticCodeFormatter

Methods

format(self) -> str

title: Return the formatted diagnostic message.
returns:
  type: str

LoweringError(IRxDiagnosticError)

title: Raised when lowering fails with one structured diagnostic.
attributes:
  diagnostic:
    type: Diagnostic
  code_formatter:
    type: DiagnosticCodeFormatter

NativeCompileError(IRxDiagnosticError)

title: Raised when native artifact compilation fails.
attributes:
  diagnostic:
    type: Diagnostic
  code_formatter:
    type: DiagnosticCodeFormatter

LinkingError(IRxDiagnosticError)

title: Raised when final executable linking fails.
attributes:
  diagnostic:
    type: Diagnostic
  code_formatter:
    type: DiagnosticCodeFormatter

RuntimeFeatureError(IRxDiagnosticError)

title: Raised when runtime feature activation or symbol resolution fails.
attributes:
  diagnostic:
    type: Diagnostic
  code_formatter:
    type: DiagnosticCodeFormatter

SemanticError(Exception)

title: Raised when semantic analysis fails.
attributes:
  diagnostics:
    type: DiagnosticBag
  code_formatter:
    type: DiagnosticCodeFormatter

Methods

format(self) -> str

title: Return the formatted diagnostic bag.
returns:
  type: str

DiagnosticCodes

title: Stable logical diagnostic identifiers.
summary: >-
  Group the most important semantic, lowering, FFI, runtime, compile, and
  link families under short stable identifiers. These identifiers are
  rendered through one shared DiagnosticCodeFormatter.