# _macro_introspect

URL: /chirp-ui/api/_macro_introspect/
Section: api
Description: AST introspection for ``{% def %}`` macros — internal.

Wraps `kida.lexer` + `kida.parser` to extract per-macro parameter
metadata without compiling the template (so no chirp-ui filter stubs are
required at manifest-build time).

Used by `chirp_ui.manifest` to project macro Python signatures into the
agent-groundable manifest. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

---

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

# _macro_introspect

AST introspection for ``{% def %}`` macros — internal.

Wraps `kida.lexer` + `kida.parser` to extract per-macro parameter
metadata without compiling the template (so no chirp-ui filter stubs are
required at manifest-build time).

Used by `chirp_ui.manifest` to project macro Python signatures into the
agent-groundable manifest. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

module

AST introspection for ``{% def %}`` macros — internal.

Wraps `kida.lexer` + `kida.parser` to extract per-macro parameter
metadata without compiling the template (so no chirp-ui filter stubs are
required at manifest-build time).

Used by `chirp_ui.manifest` to project macro Python signatures into the
agent-groundable manifest. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

ParamInfo

class

Single ``{% def %}`` parameter, derived from the AST.

``has_default`` follows Python's trailing-defaults convention: kida's
``Def`` node parallels ``defaults`` to the last *N* of ``params``.

MacroInfo

class

Per-macro introspection result.

``slots`` is the tuple of ``{% slot name %}`` placeholders found in the
macro body, in declaration order, deduplicated (a slot rendered twice
appears once). The unnamed default slot is normalized from kida's
``"default"`` to ``""`` to match ``ComponentDescriptor.slots`` convention.
``yielded_slots`` is the tuple of ``{% yield %}`` / ``{% yield name %}``
caller slots accepted by composite macros and forwarded into child calls.

macros_in_template

function

Return ``{macro_name: MacroInfo}`` for every ``{% def %}`` in the template.

Cached. Returns ``{}`` if the template file is missing or contains no defs.
Template name is relative to ``src/chirp_ui/templates/chirpui/``.

_walk_slot_names

function

Yield public slot names reachable from ``node`` without crossing a nested ``Def``.

chirp-ui currently has no nested defs (verified at Sprint 2), so this is
defensive only — keeps slot ownership per-macro if that ever changes.

_yielded_slots_by_macro

function

Return ``macro_name → yielded slot names`` attributed by source line.

The installed kida AST exposes ``Slot`` placeholders but not a public
``Yield`` node, so composite forwarded slots are found from the raw source
and attributed to the nearest preceding ``{% def %}`` line. chirp-ui does
not use nested defs, which keeps the ownership rule straightforward.

description_from_template

function

Return the leading ``{#- chirp-ui: ... -#}`` doc-block text, or ``""``.

One doc-block per file, covering the file's entire set of macros — verified
at Sprint 4 across all 195 chirp-ui templates. The block must appear before
any ``{% def %}`` or ``{% from %}`` statement (the parser scans only the
first ~2 KB to honor that invariant cheaply).

Whitespace inside the block is preserved except for a single leading /
trailing strip — so multi-line usage examples keep their shape. Inner
indentation is left alone; downstream renderers (COMPONENT-OPTIONS
generator, etc.) can post-process as needed.