manifest - chirp-ui

Agent-groundable manifest of the chirp-ui component surface.

This module publishes the component registry (chirp_ui.components.COMPONENTS pluschirp_ui.tokens.TOKEN_CATALOG) as a stable JSON snapshot. AI agents and docs tooling can read the manifest to cite real classes, tokens, slots, and templates instead of plausible-sounding ones.

Schema

{"schema": "chirpui-manifest@5", "version": "<pkg>", "components": {...}, "tokens": {...}, "theme_packs": [...], "stats": {...}}

components keys sorted; each entry contains block, variants, sizes, modifiers, elements, slots, tokens, extra_emits, trim_emits, emits, template, category, maturity, role, authoring, requires, plus the @2 additionsmacro, params, and lineno, the @3composition additionscomposes, slot_forwards, and slots_yielded, and the @4 appearance/tone additions appearances and tones.
params is a list of {"name": str, "has_default": bool, "is_required": bool}derived from the template AST via chirp_ui._macro_introspect. Empty when the descriptor has no template, the macro cannot be resolved, or the template has no {% def %}matching the resolved name.
macro is the resolved macro identifier (descriptor.macroif set, elseblock.replace("-", "_")). nullwhen the descriptor has no template or no matching macro is found.
lineno is the source line of the {% def %} tag (0when unavailable).
slots is the sorted union of descriptor.slots, direct slots extracted from the macro body, and yielded slots accepted by composite wrappers. The unnamed default slot is represented as"". Hand-authored descriptor entries can over-declare (e.g. for documentation), but the manifest never under-reports a real slot.
slots_extracted is the AST-derived slot list (sorted, default = "") exposed separately so parity tests can spot descriptor↔template drift without losing the mergedslotscontract.
slots_yielded is the source-derived list of {% yield %}/ {% yield name %}caller slots. Composite forwarding metadata is explicit incomposes and slot_forwards.
provides / consumesare sorted lists of context keys (e.g. "_card_variant") sourced from chirp_ui.inspect. A key is attributed to the macro whose{% def %}lineno is the largest one preceding the{% provide %} / consume()site.
descriptionis the stripped text inside the leading {#- chirp-ui: ... -#}doc-block of the template file. One block per file, covering every macro; empty string when the descriptor has no template. New chirp-ui templates must carry a doc-block (tests/test_description_coverage.py).
tokens keys sorted; each entry is {"category": …, "scope": …}.
theme_packslists packaged token-only theme CSS resources in stable catalog order.
stats aggregates counts, including components_with_params, a registry_debtscorecard for descriptor/CSS reconciliation burn-down, and amanifest_qualityscorecard for agent-facing metadata coverage.

Deterministic: two calls tobuild_manifest() yield byte-identical JSON.

CLI

python -m chirp_ui.manifest --jsonwrites JSON to stdout.

Seedocs/plans/done/PLAN-agent-grounding-depth.mdand docs/decisions/manifest-signature-extraction.md.

manifest

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

function _resolve_macro

Look up theMacroInfo for a descriptor, or Noneif unresolvable.

Resolution order: explicitdescriptor.macro → block.replace("-", "_"). ReturnsNonewhen the template…

function _runtime_requirements

Return sorted runtime requirements from descriptor + derived macro metadata.

function _macro_source

Return the source slice for one macro body, bounded by the next{% def %}.

function _literal_attribute_names

Return literal HTML attribute names in a macro body using Kida analysis.

function _manifest_quality

Return agent-facing metadata gap counts for public templated components.

function _owning_macro

Return the macro name whose{% def %} lineno most-recently precedes line.

Used to attribute a{% provide %} or consume()site (which…

function _provide_consume_index

Index(template, macro_name) → (provides_keys, consumes_keys).

Built once per manifest; relies on the line-walked records from chirp_ui.inspect. Templates with no defs (or…

function build_manifest

Return the component/token manifest as a JSON-serializable dict.

Output is deterministic: components and tokens are sorted by key, and every per-entry list (emits, variants,…

function to_json

Serialize a manifest to stable JSON (sort_keys, UTF-8, no trailing NL).

function main

_resolve_macro

function

def _resolve_macro(desc: ComponentDescriptor) -> MacroInfo | None

Look up theMacroInfo for a descriptor, or Noneif unresolvable.

Resolution order: explicitdescriptor.macro → block.replace("-", "_"). ReturnsNonewhen the template is missing, the file has no defs, or no def name matches the resolved macro identifier.

Parameters

Name	Type	Default	Description
`desc`	`ComponentDescriptor`	—

_runtime_requirements

function

def _runtime_requirements(desc: ComponentDescriptor, macro_info: MacroInfo | None) -> list[str]

Return sorted runtime requirements from descriptor + derived macro metadata.

Parameters

Name	Type	Default	Description
`desc`	`ComponentDescriptor`	—
`macro_info`	`MacroInfo \| None`	—

_macro_source

function

def _macro_source(macro_info: MacroInfo) -> str

Return the source slice for one macro body, bounded by the next{% def %}.

Parameters

Name	Type	Default	Description
`macro_info`	`MacroInfo`	—

_literal_attribute_names

function

def _literal_attribute_names(macro_info: MacroInfo) -> frozenset[str]

Return literal HTML attribute names in a macro body using Kida analysis.

Parameters

Name	Type	Default	Description
`macro_info`	`MacroInfo`	—

_manifest_quality

function

def _manifest_quality(components: dict[str, dict[str, Any]]) -> dict[str, int]

Return agent-facing metadata gap counts for public templated components.

Parameters

Name	Type	Default	Description
`components`	`dict[str, dict[str, Any]]`	—

_owning_macro

function

def _owning_macro(macros: dict[str, MacroInfo], line: int) -> str | None

Return the macro name whose{% def %} lineno most-recently precedes line.

Used to attribute a{% provide %} or consume()site (which has only a template + line) to the macro it lives inside. ReturnsNoneif the line is before any def (top-of-file noise).

Parameters

Name	Type	Default	Description
`macros`	`dict[str, MacroInfo]`	—
`line`	`int`	—

_provide_consume_index

function

def _provide_consume_index() -> dict[tuple[str, str], tuple[set[str], set[str]]]

Index(template, macro_name) → (provides_keys, consumes_keys).

Built once per manifest; relies on the line-walked records from chirp_ui.inspect. Templates with no defs (or sites before the first def) are dropped silently.

No parameters.

build_manifest

function

def build_manifest() -> dict[str, Any]

Return the component/token manifest as a JSON-serializable dict.

Output is deterministic: components and tokens are sorted by key, and every per-entry list (emits, variants, etc.) is sorted. Param order is preserved as declared in the template (positional order matters for macro callers).

No parameters.

to_json

function

def to_json(manifest: dict[str, Any], *, indent: int = 2) -> str

Serialize a manifest to stable JSON (sort_keys, UTF-8, no trailing NL).

Parameters

Name	Type	Default	Description
`manifest`	`dict[str, Any]`	—
`indent`	`int`	`2`

main

function

def main(argv: list[str] | None = None) -> int

Parameters

Name	Type	Default	Description
`argv`	`list[str] \| None`	`None`

View source · /home/runner/work/chirp-ui/chirp-ui/site/../src/chirp_ui/manifest.py:1