Suspense{% if key %}defer-falsy footgun detection.
A deferred Suspense key is theDEFERREDsentinel in the shell render, then
resolves to real data. Templates that branch on raw truthiness
({% if key %}) treat empty list [], empty string "", 0and
Falseidentically to an application-defined empty state — the skeleton or
fallback branch can render forever and a user sees a perpetual spinner with no
console error.
Templates should use thedeferredtest or the
"key" in __chirp_defer_pending__pending-key set to separate loading from
loaded states; this rule promotes that guidance to a startup-time contract
check.
Detection is scoped to templates that self-declare their defer keys via
"<NAME>" in __chirp_defer_pending__ or the <NAME> is deferredtest,
so we don't false-positive on arbitrary{% if x %}elsewhere in the
codebase. Severity isWARNING— the rule ships informational by default
and can be promoted toERRORvia
app.override_contract_severity("defer_falsy", Severity.ERROR)in CI.
contracts.rules_defer_falsy
| 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
_bare_truthy_pattern
function
def _bare_truthy_pattern(key: str) -> re.Pattern[str]Build a regex that matches{% if KEY %} / {% if not KEY %}.
Matches kidaif and elifstart tags with optional whitespace
trimming ({%-, -%}) and an optional not. Crucially, the
pattern requires the tag to end immediately after the identifier
(\s*-?%}) — that's what excludes {% if KEY is none %},
{% if KEY == X %}, {% if KEY and Y %}, etc.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
key
|
str
|
— |
check_defer_falsy_conditionals
function
def check_defer_falsy_conditionals(template_sources: dict[str, str]) -> list[ContractIssue]Flag bare{% if KEY %}conditionals on Suspense-deferred keys.
Only fires whenKEYis explicitly declared as a defer key in the
same template (via__chirp_defer_pending__membership or the
is deferred test). One WARNINGper (template, key) pair.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
template_sources
|
dict[str, str]
|
— |
View source · /home/runner/work/chirp/chirp/site/../src/chirp/contracts/rules_defer_falsy.py:1