manifest
Agent-groundable manifest of the chirp-ui component surface. This module publishes the component registry (``chirp_ui.components.COMPONENTS`` plus ``chirp_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`` additions ``macro``, ``params``, and ``lineno``, the ``@3`` composition additions ``composes``, ``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.macro`` if set, else ``block.replace("-", "_")``). ``null`` when the descriptor has no template or no matching macro is found. * ``lineno`` is the source line of the ``{% def %}`` tag (``0`` when 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 merged ``slots`` contract. * ``slots_yielded`` is the source-derived list of ``{% yield %}`` / ``{% yield name %}`` caller slots. Composite forwarding metadata is explicit in ``composes`` and ``slot_forwards``. * ``provides`` / ``consumes`` are 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. * ``description`` is 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_packs`` lists packaged token-only theme CSS resources in stable catalog order. * ``stats`` aggregates counts, including ``components_with_params``, a ``registry_debt`` scorecard for descriptor/CSS reconciliation burn-down, and a ``manifest_quality`` scorecard for agent-facing metadata coverage. Deterministic: two calls to `build_manifest`() yield byte-identical JSON. CLI --- ``python -m chirp_ui.manifest --json`` writes JSON to stdout. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and ``docs/DESIGN-manifest-signature-extraction.md``.
_resolve_macro
Look up the ``MacroInfo`` for a descriptor, or ``None`` if unresolvable. Resolution order: explicit ``descriptor.macro`` → ``block.replace("-", "_")``. Returns ``None`` when the template is missing, the file has no defs, or no def name matches the resolved macro identifier.
_runtime_requirements
Return sorted runtime requirements from descriptor + derived macro metadata.
_macro_source
Return the source slice for one macro body, bounded by the next ``{% def %}``.
_literal_attribute_names
Return literal HTML attribute names in a macro body using Kida analysis.
_manifest_quality
Return agent-facing metadata gap counts for public templated components.
_owning_macro
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. Returns ``None`` if the line is before any def (top-of-file noise).
_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 sites before the first def) are dropped silently.
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, etc.) is sorted. Param order is preserved as declared in the template (positional order matters for macro callers).
to_json
Serialize a manifest to stable JSON (sort_keys, UTF-8, no trailing NL).