contracts.rules_shapecheck

Per-binding derived state cached by pass 1 for the pass-2 report.

Pass 1 resolves each(template, block, shapevar, Shape)binding to its columns / computed / provided fields, occurrence-granular own reads, and attribution metadata exactly once; pass 2 emits under-fetch (per binding) and over-fetch (against the shape-group read union) from these records.

Normalize indentation soast.parseaccepts a nested handler source.

Return the_ShapeMeta sidecar on a @shape class, else None.

Return the_CompositeMeta sidecar on a @composite class, else None.

Duck-typed (a frozen sidecar exposingmembers) so this rule stays importable for db-less / data-less apps, mirroring_shape_meta().

Resolve a composite field name to its member@shape class, else None.

A block bound topage.field (where page is a @composite) reads the fields of that field's member Shape; the per-block subset check then runs against the composite member's provided fields -- never one query per block (§4-L4). ReturnsNonewhen the field is not a Shape member (skip).

Return the dataclass field names of a@shapeclass (empty if not one).

Return the Shape's derived accessors -- real attributes, not dataclass fields.

A@shape-decorated dataclass commonly exposes a @propertyor method over its columns (full_name over first_name/last_name, url() over slug). Such a name is a real class-level attribute (a property, function, descriptor, or class var) but NOT a dataclass field -- readingshapevar.full_nameresolves at runtime and renders correctly, so it must never be flagged as an under-fetch. We collect every public class-level attribute that is not a dataclass field and not a dunder; the columns these accessors consume live inside their bodies, invisible to depends_on.

Usesinspect.getattr_static so a propertyis observed as the descriptor object (never triggering its getter against the bare class).

Resolve a binding value to a@shapeclass.

Accepts either the class itself or a registry name string. Returns the class when it carries a_ShapeMeta sidecar, else None(skip).

Return the value of a string-literal AST node, elseNone.

ResolveShape.fetch(SomeShape, ...) to the SomeShapeclass.

Matchesfetch / fetch_one / stream on a receiver named Shape whose first positional arg is a bareNameresolvable in handler globals. Anything else returnsNone(skip -- not statically a Shape fetch).

ResolveComposite.load(SomePage, ...) to the SomePageclass.

Matchesload on a receiver named Compositewhose first positional arg is a bareName resolvable in handler globals to a @compositeclass. Anything else returnsNone(skip -- not statically a Composite load).

Map handler-local names to the Shape class they were assigned from.

Recognizesname = await Shape.fetch(SomeShape, ...)and name = Shape.fetch(SomeShape, ...) (and fetch_one / stream). Only single-targetNameassignments are tracked. The resolved value is the Shape class (from handler globals) --Noneentries are dropped.

Map handler-local names to the@compositeclass they were loaded from.

Recognizespage = await Composite.load(SomePage, ...)(and the non-await form). Only single-targetNameassignments are tracked. The resolved value is the@composite class from handler globals; Nonedropped.

Resolve a render-context kwarg value to a bound Shape class.

Statically-decidable forms:

• shapevar=some_local where some_local = await Shape.fetch(S, ...);
• shapevar=Shape.fetch(S, ...)(inline fetch as the kwarg value);
• shapevar=S where S is a @shapeclass in handler globals;
• shapevar=page.field where page = await Composite.load(P, ...)and field is a member Shape of the composite P(#170) -- the block's provided fields come from that composite member's Shape, never one query per block.

Recover(template, block, shapevar, shape_cls)from handler return calls.

AST-walks the handler forFragment/Page/Suspensecalls. The first positional is the template, the second positional is the block (both must be string literals). Each kwarg whose value resolves to a Shape contributes one binding:shapevar is the kwarg name (the template variable), shape_cls is the resolved class. A kwarg valuepage.field (where pageis a Composite.load(...)local) resolves to that composite field's member Shape -- the per-block subset check runs against the composite member's provided fields (#170).

Return the kida ASTBlock node for block_name, or None.

Depth-first walk of a kida AST yielding every child node.

Yield child nodes from the kida-AST container attributes.

Names bound inside a block (subtract before any field claim).

Walks the block body collecting{% set %} / let / export/ capture / def / regiontargets, loop variables, and def params via_binding_names() (the canonical single-node collector). Per §8.5 #3 we walk the body rather than calling_binding_nameson the block.

Names bound by a kidaFortarget expression (incl. tuple targets).

Parameter names declared on a kidaDef/Macro/Regionnode.

Depth-first walk of a kida AST via the nativeiter_child_nodes().

Yields every descendant node (excludingnodeitself). Uses kida's own iter_child_nodes() (dataclass-field introspection) rather than this module's hand-rolled_kida_childrenso the traversal covers every container shape kida defines (withtargets, matchcases, etc.) with zero parallel-maintenance hazard.

Return theBlock descendants nested inside block_node.

A parent block'sdepends_onis kida's documented conservative SUPERSET: it absorbs every nested child block's reads (verified empirically -- a child block nested under a{% for %}/{% if %}still bleeds into the parent viaDependencyWalker). Used for under-fetch ATTRIBUTION: a flagged path is named against the innermost block whose OWN reads contain it, so we need each nested child's name to analyze it independently.

Return a fresh OWN-readsDependencyWalker subclass instance, or None.

The walker reuses kida's ownDependencyWalker (the single source of truth for what counts as a context read -- scope handling for loop vars /{% set %}/ def params, builtin elision, dotted path building) but overridesvisit_Blockso that nested (non-root) Block nodes are treated as OPAQUE: the root block's body is recursed, but the walker does NOT descend into nested child blocks. The result is the block's OCCURRENCE-granular own reads -- a dotted read that occurs in BOTH the parent body and a nested child is retained (it genuinely lives in the parent), and a read that occurs ONLY inside a nested child is excluded (no parent bleed).

ReturnsNonewhen kida's dependency machinery is unavailable (skip-not- guess -- this is a fail-loud ERROR category, so an analysis we cannot perform must drop to no claim, never a guess).

Returnblock_name's OWN reads, pruned of nested-child bleed.

kida'sdepends_onfor a parent block is a conservative SUPERSET that absorbs every nested child block's reads. Naiveown = depends_on(parent) - union(depends_on(child))(set difference of analysis sets) is a FALSE-NEGATIVE hazard: kida'sdepends_onis set-granularity, so when the SAME dotted read (e.g.board.owner) occurs in BOTH the parent body AND a nested child under the same shapevar, subtraction removes it from the parent ENTIRELY -- a genuine parent under-fetch is silently MISSED.

We instead compute own reads at OCCURRENCE granularity by reusing kida's own DependencyWalker with visit_Block overridden to treat nested child Blocks as opaque (see _own_reads_walker()). A read in both the parent body and a nested child is retained on the parent; a read ONLY in a nested child is excluded. This fires the marquee parent under-fetch without re-introducing nested-child bleed.

ReturnsNonewhen the template/block/walker cannot be analyzed (skip). kida's reads are treated strictly as a conservative superset -- this rule never assumes kida prunes.

Map each ofblock_namesto its OWN (bleed-pruned) reads.

Used for under-fetch attribution: a flagged read path is reported against the innermost block whose OWN reads contain it, not the bound ancestor block. Blocks that cannot be analyzed are simply absent from the map.

Map the bound block + each nested descendant block to its nesting depth.

The bound block is depth 0; a block nested one level deeper is depth 1, etc. Used by_innermost_owner() to break attribution ties toward the syntactically-innermost block. Returns{}when the block cannot be found.

Return the innermost BOUND block whose OWN reads containread_path.

Attribution must name a block whose Shape contract was actually verified -- i.e. a block inbound_blocks(the set of blocks this app binds to a Shape). The innermost owner of a flagged read may be an UNBOUND nested child (e.g. a{% block badge %} nested inside a bound {% block header %}that shares the read): naming that sibling/child points the developer at a block whose contract was never checked, when the failure belongs to the BOUND binding (header). So we restrict to bound owners and pick the innermost of those; the read still fires (no false negative) -- only the reported block name changes to a verified binding.

Ties (same depth) are unlikely (a given read lives in one block); when no bound block claims the path -- e.g. a duplicate-name AST/metadata shadow made the bound block's own-reads diverge -- attribute tofallback(the bound block being checked) so a real under-fetch is never silently dropped.

Returnshapevar.field paths in a block guarded by | default(none).

Used for #11: the under-fetch remediation hint only tells the author to delete the| default(none)guard when the flagged read actually carries one. A guard appears in the kida AST as aFilter(name='default')wrapping aGetattr(obj=Name, attr=...) whose sole positional arg is the None constant. We record the dottedobj.attrpath for each such filter.

Extract theshapevar.fieldreads of a single binding.

Returns(read_fields, read_accessor): the set of first-attr field names read offshapevar(after subtracting noise / globals / block-locals and derived accessors), and whether any read resolved to a derived accessor (a @property/ method / descriptor). A derived-accessor read makes the binding's column coverage invisibly incomplete -- the over-fetch claim is suppressed for the whole shape group when any binding read one.

Shared by the over-fetch group-union pre-pass and the per-binding under-fetch pass so both observe identical read-field semantics (no parallel drift).

Flag surface-contract names whose target resolves to no registered Shape.

surface_contractsmaps a surface name -> the expected Shape name. A target absent fromshape_registry() is drift (a typo or a renamed-away view). Emits one ERROR per drifted surface, with a get_close_matches() suggestion from the live registry names.

Flag scoped Shapes whose SQL is opaque/un-injectable (#169, §8.1 #3).

The tenant-scope guarantee is delivered by structural injection on the compiler output -- not a WHERE scan. The ONE statically-decidable ERROR is reserved for a Shape that declaresscope=but whose declared SQL is opaque/un-injectable (CTE / UNION / SELECT * / no analyzable FROM), so the compiler CANNOT inject the predicate and the query would silently leak across tenants. We delegate the injectability decision to the compiler's own _scope_injectable() (single source of truth, no WHERE-column scanner).

Scoped only overshapes-- the set of Shapes this app actually uses (route-bound + resolved surface-contract targets). Iterating the entire process-wide registry would leak unrelated test/app fixtures into every other app'sapp.check(); an app's scope contract is about the Shapes the app binds, not every Shape ever imported.

flagged_names: when given, every Shape name this check ERRORs on is added to it so the caller can de-dup the_check_shape_validate() pass (whose Shape.validatewould raise the same scope failure with a less actionable message).

Best-effort registry/class name for a Shape (for de-dup and messages).

Runvalidate() over every USED Shape (#169/#167).

Shape.validateis the runtime fail-loud authority: for a scoped Shape it asserts the compiler OUTPUT carries the scope predicate, and for nested children it asserts each child is batchable (analyzable FROM, theonjoin column present as a field, the parentkeypresent). A ShapeErroris the decoration-time signal that a Shape cannot be safely compiled -- it would crash or silently misbehave at runtime, so we surface it as a startupapp.check()ERROR.

De-dup: the scope-injectability case is already reported by _check_scope_injectable() with a more actionable message; shapes whose name is inalready_flaggedare skipped here so a scoped-opaque Shape fires exactly one ERROR (not the generic validate echo too). Anything Shape.validaterejects that the scope check did NOT (a malformed nested child) still surfaces here.

Verify@shaperender bindings and surface-contract registry drift.

See the module docstring for the full claim set, ownership boundary, escape hatches, and conservatism contract. The entire body is wrapped so any unexpected analysis error returns[]-- a built-in rule must never crash app.check().