irx.diagnostics

`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.