gap_diagnostics

contracts.gap_diagnostics

module

Private architecture-gap projection for approved structural debt (#885).

This module copies facts that already exist in a frozen HypermediaProgram, a finalized CheckResult, and the author-declared severity override map. It does…

Private architecture-gap projection for approved structural debt (#885).

This module copies facts that already exist in a frozen HypermediaProgram, a finalized CheckResult, and the author-declared severity override map. It does not accept anApp, does not rescan templates, does not promote severities, and does not invent a second topology scanner.

Approved gap kinds (RFC 028 / issue #885):

dead / orphan / unreachable_block— projected from existing check findings (architecture debt / unproven static navigation / composition gaps)
suppressed— every severity override, never treated as clean coverage
unproven— unresolved enhancement edges and the standing undeclared dynamic-selection caveat
unobserved— missing or unmatched behavioral evidence; static reachability is never counted as behavioral coverage

This module is internal and is not exported fromchirpor chirp.contracts. Its records are not a public inspection schema.

contracts.gap_diagnostics

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

class ArchitectureGap

One projected architecture debt, suppression, or unknown.

class ArchitectureGapReport

Deterministic inventory of approved architecture gaps.

is_cleanis True only when the report contains no debt findings, no severity overrides, no unproven dynamic edges,…

function build_architecture_gap_report

Project approved architecture gaps without changing check behavior.

result may be Noneonly when findings are unavailable; that state is an explicit unobserved gap,…

function architecture_gap_to_dict

Serialize one gap for structured inspection consumers.

function architecture_gap_report_to_dict

Serialize a gap report with deterministic key order.

function format_architecture_gap_report

Render a stable terminal summary that mirrors the structured payload.

function _project_unproven_dynamic_gaps

Project concrete unproven dynamic edges from compiler facts.

The standing caveat that undeclared runtime template selection remains outside static reachability lives in_NOTESso…

ArchitectureGap

class

One projected architecture debt, suppression, or unknown.

ArchitectureGapReport

class

Deterministic inventory of approved architecture gaps.

is_cleanis True only when the report contains no debt findings, no severity overrides, no unproven dynamic edges, and no unobserved behavioral gaps. Suppressions never make a report clean.

build_architecture_gap_report

function

def build_architecture_gap_report(program: HypermediaProgram | None, result: CheckResult | None, *, severity_overrides: Mapping[str, Severity] | None = None, observed_transition_ids: frozenset[str] | None = None) -> ArchitectureGapReport

Project approved architecture gaps without changing check behavior.

result may be Noneonly when findings are unavailable; that state is an explicit unobserved gap, never a clean result.observed_transition_ids may beNonewhen no runtime evidence snapshot was supplied; the report then records behavioral evidence as unavailable rather than inventing per-edge failures from static topology alone.

Parameters

Name	Type	Default
`program`	`HypermediaProgram \| None`	—
`result`	`CheckResult \| None`	—
`severity_overrides`	`Mapping[str, Severity] \| None`	`None`
`observed_transition_ids`	`frozenset[str] \| None`	`None`

architecture_gap_to_dict

function

def architecture_gap_to_dict(gap: ArchitectureGap) -> dict[str, str | None]

Serialize one gap for structured inspection consumers.

Parameters

Name	Type	Default	Description
`gap`	`ArchitectureGap`	—

architecture_gap_report_to_dict

function

def architecture_gap_report_to_dict(report: ArchitectureGapReport) -> dict[str, object]

Serialize a gap report with deterministic key order.

Parameters

Name	Type	Default	Description
`report`	`ArchitectureGapReport`	—

format_architecture_gap_report

function

def format_architecture_gap_report(report: ArchitectureGapReport) -> str

Render a stable terminal summary that mirrors the structured payload.

Parameters

Name	Type	Default	Description
`report`	`ArchitectureGapReport`	—

_project_unproven_dynamic_gaps

function

def _project_unproven_dynamic_gaps(program: HypermediaProgram | None) -> list[ArchitectureGap]

Project concrete unproven dynamic edges from compiler facts.

The standing caveat that undeclared runtime template selection remains outside static reachability lives in_NOTESso every app is not forced into a permanentunprovenfinding. Concrete unresolved enhancement fallback edges are projected here.

Parameters

Name	Type	Default	Description
`program`	`HypermediaProgram \| None`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/contracts/gap_diagnostics.py:1