# diagnostics URL: /kida/api/diagnostics/ Section: api Description: Public, surface-neutral diagnostics for Kida tooling. The functions in this module expose the same immutable facts used by ``kida check`` without inheriting CLI stream or exit-code policy. Locations use 1-based lines and 0-based columns; end positions are exclusive when present. --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/diagnostics/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fdiagnostics%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fdiagnostics%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fdiagnostics%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fdiagnostics%2Findex.txt) Module # `diagnostics` Public, surface-neutral diagnostics for Kida tooling. The functions in this module expose the same immutable facts used by `kida check`without inheriting CLI stream or exit-code policy. Locations use 1-based lines and 0-based columns; end positions are exclusive when present. 11Classes4Functions ## Classes `DiagnosticSeverity` 0 ▼ Severity assigned by the diagnostic producer. Severity assigned by the diagnostic producer. `DiagnosticConfidence` 0 ▼ How conclusively Kida can make a diagnostic claim. How conclusively Kida can make a diagnostic claim. `SourcePosition` 3 ▼ One source position using a 1-based line and optional 0-based column. One source position using a 1-based line and optional 0-based column. #### Attributes Name Type Description `line` `int` — `column` `int | None` — #### Methods Internal Methods 1 ▼ `__post_init__` 0 ▼ `def __post_init__(self) -> None` `SourceSpan` 5 ▼ Logical template path and optional half-open source range. Logical template path and optional half-open source range. #### Attributes Name Type Description `path` `str | None` — `start` `SourcePosition | None` — `end` `SourcePosition | None` — #### Methods `is_exact` 0 `bool` ▼ Return whether the span is precise enough for a source edit. property `def is_exact(self) -> bool` ##### Returns `bool` Internal Methods 1 ▼ `__post_init__` 0 ▼ `def __post_init__(self) -> None` `RelatedLocation` 3 ▼ A labeled source location related to the primary finding. A labeled source location related to the primary finding. #### Attributes Name Type Description `label` `str` — `span` `SourceSpan` — #### Methods Internal Methods 1 ▼ `__post_init__` 0 ▼ `def __post_init__(self) -> None` `SafeEdit` 4 ▼ An unambiguous replacement over an exact source span. An unambiguous replacement over an exact source span. #### Attributes Name Type Description `span` `SourceSpan` — `replacement` `str` — `description` `str | None` — #### Methods Internal Methods 1 ▼ `__post_init__` 0 ▼ `def __post_init__(self) -> None` `DiagnosticSnippet` 4 ▼ Plain source lines surrounding a diagnostic. Plain source lines surrounding a diagnostic. #### Attributes Name Type Description `lines` `tuple[tuple[int, str], ...]` — `error_line` `int` — `column` `int | None` — #### Methods Internal Methods 1 ▼ `__post_init__` 0 ▼ `def __post_init__(self) -> None` `Diagnostic` 16 ▼ One immutable Kida finding, independent of its output surface. One immutable Kida finding, independent of its output surface. #### Attributes Name Type Description `code` `str` — `category` `str` — `severity` `DiagnosticSeverity` — `message` `str` — `span` `SourceSpan` — `title` `str | None` — `kind` `str | None` — `suggestion` `str | None` — `safe_edit` `SafeEdit | None` — `related_locations` `tuple[RelatedLocation, ...]` — `confidence` `DiagnosticConfidence` — `notes` `tuple[str, ...]` — `documentation_url` `str | None` — `source_snippet` `DiagnosticSnippet | None` — `metadata` `tuple[tuple[str, str], ...]` — #### Methods Internal Methods 1 ▼ `__post_init__` 0 ▼ `def __post_init__(self) -> None` `DiagnosticConverter` 1 ▼ Pure conversion boundary from one producer record to ``Diagnostic``. Pure conversion boundary from one producer record to`Diagnostic`. #### Methods Internal Methods 1 ▼ `__call__` 1 `Diagnostic` ▼ `def __call__(self, source: SourceT, /) -> Diagnostic` ##### Parameters Name Type Description `source` `—` ##### Returns `Diagnostic` `DiagnosticOptions` 5 ▼ Opt-in static checks shared by source and directory diagnosis. Opt-in static checks shared by source and directory diagnosis. #### Attributes Name Type Description `strict` `bool` — `validate_calls` `bool` — `a11y` `bool` — `typed` `bool` — `lint_fragile_paths` `bool` — `DiagnosticReport` 2 ▼ Policy-neutral result of one programmatic diagnostic request. Policy-neutral result of one programmatic diagnostic request. #### Attributes Name Type Description `diagnostics` `tuple[Diagnostic, ...]` — `partial` `bool` — ## Functions `diagnose_directory` 2 `DiagnosticReport` ▼ Diagnose templates below *root* with the same collection as ``kida check``. `def diagnose_directory(root: str | PathLike[str], *, options: DiagnosticOptions = _DEFAULT_OPTIONS) -> DiagnosticReport` ##### Parameters Name Type Description `root` `str | PathLike[str]` `options` `DiagnosticOptions` Default:`_DEFAULT_OPTIONS` ##### Returns `DiagnosticReport` `diagnose_source` 4 `DiagnosticReport` ▼ Diagnose an in-memory template without adding it to environment caches. A supp… `def diagnose_source(source: str, *, name: str = '', environment: Environment | None = None, options: DiagnosticOptions = _DEFAULT_OPTIONS) -> DiagnosticReport` Diagnose an in-memory template without adding it to environment caches. A supplied environment contributes lexer/parser configuration, extensions, autoescape selection, and loader-backed imported component metadata. Kida does not mutate its registries; resolving imports may use that environment's existing thread-safe template cache. ##### Parameters Name Type Description `source` `str` `name` `str` Default:`''` `environment` `Environment | None` Default:`None` `options` `DiagnosticOptions` Default:`_DEFAULT_OPTIONS` ##### Returns `DiagnosticReport` `diagnostic_from_exception` 2 `Diagnostic` ▼ Convert a Kida template or lexer exception into one public diagnostic. ``TypeE… `def diagnostic_from_exception(error: Exception, *, path: str | None = None) -> Diagnostic` Convert a Kida template or lexer exception into one public diagnostic. `TypeError`is raised for unrelated Python exceptions so framework adapters cannot accidentally relabel arbitrary application failures as Kida diagnostics. ##### Parameters Name Type Description `error` `Exception` `path` `str | None` Default:`None` ##### Returns `Diagnostic` `apply_safe_edits` 3 `str` ▼ Apply non-overlapping, snapshot-matched safe edits for one template. Diagnosti… `def apply_safe_edits(source: str, diagnostics: Iterable[Diagnostic], *, path: str) -> str` Apply non-overlapping, snapshot-matched safe edits for one template. Diagnostics for other paths and diagnostics without a safe edit are ignored. A`ValueError`is raised before any edit is applied when the current source differs from the captured source lines, a snapshot is incomplete, or two selected edits overlap. ##### Parameters Name Type Description `source` `str` `diagnostics` `Iterable[Diagnostic]` `path` `str` ##### Returns `str`