# inspect

URL: /chirp-ui/api/inspect/
Section: api
Description: Design system introspection — dump the chirp-ui API surface.

Usage::

    python -m chirp_ui.inspect              # JSON report
    python -m chirp_ui.inspect --summary    # compact table
    python -m chirp_ui.inspect --tokens     # token catalog only
    python -m chirp_ui.inspect --components # component descriptors only
    python -m chirp_ui.inspect --provides   # {% provide %} statements + annotations
    python -m chirp_ui.inspect --consumes   # consume() calls + annotations
    python -m chirp_ui.inspect --audit-context  # dead provides, unprovided consumes, annotation drift

---

> For a complete page index, fetch /chirp-ui/llms.txt.

# inspect

Design system introspection — dump the chirp-ui API surface.

Usage::

python -m chirp_ui.inspect # JSON report
python -m chirp_ui.inspect --summary # compact table
python -m chirp_ui.inspect --tokens # token catalog only
python -m chirp_ui.inspect --components # component descriptors only
python -m chirp_ui.inspect --provides # {% provide %} statements + annotations
python -m chirp_ui.inspect --consumes # consume() calls + annotations
python -m chirp_ui.inspect --audit-context # dead provides, unprovided consumes, annotation drift

module

Design system introspection — dump the chirp-ui API surface.

Usage::

python -m chirp_ui.inspect # JSON report
python -m chirp_ui.inspect --summary # compact table
python -m chirp_ui.inspect --tokens # token catalog only
python -m chirp_ui.inspect --components # component descriptors only
python -m chirp_ui.inspect --provides # {% provide %} statements + annotations
python -m chirp_ui.inspect --consumes # consume() calls + annotations
python -m chirp_ui.inspect --audit-context # dead provides, unprovided consumes, annotation drift

ProvideRecord

class

A `{% provide _key = ... %}` statement found in a chirp-ui template.

ConsumeRecord

class

A `consume("_key", default)` call found in a chirp-ui template.

AuditReport

class

Result of `audit_provide_consume`() — context-flow health at a glance.

- ``dead_provides`` — `{% provide %}` statements whose key is never
``consume()``d anywhere in the bundled templates. Some are legitimate
(reserved for apps to extend); apps should pin an allow-list.
- ``unprovided_consumes`` — ``consume()`` calls whose key is never
``{% provide %}``d in the bundled templates. Usually means the value is
expected to come from app code (see ``_sse_state``).
- ``annotation_drift`` — human-readable diagnostics where a ``@provides``
annotation names a consumer macro that lacks a matching ``@consumes``
annotation for the same key. Flags rotted documentation.

_parse_provide_annotation

function

Parse the body of a `@provides` annotation into a tuple of consumer macro names.

_parse_consumes_annotation

function

Parse one or more `_key from: providers` clauses inside a `@consumes` annotation.

Handles compound annotations like:
_card_variant from: card, _surface_variant from: panel, surface
by splitting only at boundaries between distinct keys.

_strip_default

function

Normalize a consume() default literal: strip quotes/whitespace.

list_provides

function

Walk every chirp-ui template and return each `{% provide %}` statement.

Statements adjacent to a `{# @provides _key — consumed by: ... #}` annotation
have their ``consumed_by`` populated and ``raw_annotation`` set; statements
without an annotation have empty defaults so callers can detect undocumented
providers.

list_consumes

function

Walk every chirp-ui template and return each `consume(...)` call.

Calls adjacent to a `{# @consumes _key from: ... — falls back to ... #}`
annotation have their ``providers``, ``fallback``, and ``raw_annotation``
populated; calls without an annotation fall back to the inline default
literal (or ``""`` if none).

_macro_to_template_map

function

Index every `{% def macro_name %}` to the template file(s) it's defined in.

Most macros have one definition; a few share names across files (e.g.
``segmented_control`` lives in both ``forms.html`` and
``segmented_control.html``). Returning a tuple keeps the drift check
tolerant of these overlaps.

audit_provide_consume

function

Audit chirp-ui's provide/consume graph against the templates.

Returns an `AuditReport` with three diagnostics: dead provides
(provided but never consumed), unprovided consumes (consumed but never
provided in bundled templates — usually an app-side provider is expected),
and annotation drift (``@provides`` lists a consumer that has no matching
``@consumes`` for the same key).

main

function