volaro 0.0.2 → 0.1.0-alpha.3

package/compiler/validator/vlcheck/checks.py

@@ -0,0 +1,1227 @@
+"""Structural and heuristic-semantic checks over the parsed AST.
+
+None of this is a type checker. `E-PROP-FALLIBLE` and `W-UNDEF-NAME` are
+deliberately conservative heuristics; the real thing needs the spec's
+Hindley-Milner pass (section 17.5). See PROJECT.md section 7.2 for the non-goals.
+"""
+
+from __future__ import annotations
+
+import re
+
+from . import ast_nodes as A
+from .diagnostics import Diagnostic, LineIndex, Severity
+
+# Generous allowlist so W-UNDEF-NAME stays low-noise. NOT the real stdlib surface.
+BUILTINS = {
+    # namespaces / ambient values commonly referenced in the spec examples
+    "env", "session", "route", "auth", "db", "log", "analytics", "events", "ws",
+    "mailer", "billing", "now", "api",
+    # std free functions shown across the spec
+    "filter", "map", "sort_by", "sorted", "take", "join", "split", "first",
+    "first_char", "group_by", "fold", "chunk", "keys", "values", "merge",
+    "get_or", "to_int", "int_to_float", "len", "format", "reload", "loading",
+    "ok", "err",
+    # list growth (spec section 20.9): the only way to combine or grow a
+    # list -- no `+` overload, no spread syntax, see the open question
+    "concat", "append",
+    # error-code constructors used in `err(...)` / match arms in the spec
+    "not_found", "forbidden", "conflict", "rejected", "unexpected", "out_of_range",
+    "decode", "invalid_credentials", "unverified_email", "totp_required",
+    "rate_limited", "create_guest", "guest_user",
+    # std.ui elements (auto-imported into views per spec section 8.2)
+    "col", "row", "stack", "grid", "text", "img", "button", "input", "link",
+    "spacer", "status", "card",
+    # semantic structure (spec section 8.11)
+    "h1", "h2", "h3", "h4", "h5", "h6", "main", "nav",
+    # `where(...)` comparison-predicate constructors (spec section 13.1)
+    "lt", "lte", "gt", "gte", "ne", "between", "any_of",
+}
+_PRIM_NAMES = {"int", "float", "str", "bool", "bytes", "time", "dur", "uuid", "json", "nil"}
+
+# `use std.X { name, ... }` names `vlbuild` actually lowers to a working call
+# -- NOT the same list as `BUILTINS` above (that one is a generous, deliberately
+# loose allowlist for the W-UNDEF-NAME heuristic, and includes several names,
+# e.g. `merge`/`fold`/`first`/`to_int`, the spec shows but this build's emitter
+# has no lowering for). Duplicated from `vlbuild/emit.py`'s `STD_FNS` (plus
+# `now`, whose one working lowering — a `model` field default — lives in
+# `server_emit.py`'s `_sql_default`) rather than imported: `vlcheck` has no
+# dependency on `vlbuild` (the dependency runs the other way), so the two
+# packages cannot share this table directly. Keep in sync by hand; a mismatch
+# only makes this check too strict or too loose, never silently wrong, since
+# `vlbuild` is the actual authority on what it lowers.
+#
+# Found reproducing the login-page benchmark's Bug 3 (`test-only`
+# `login-page/volaro/NOTES.md`): `use std.http { post }` passes `vlcheck`
+# clean and compiles to a bare, undefined `post(...)` call in the emitted JS
+# (`emit.py`'s `_ex_Call` has no special case for an unrecognized `A.Name`
+# callee, so it falls through to emitting the call verbatim) -- a silent
+# ReferenceError at runtime, not a build-time diagnostic. `std.http` has no
+# member in either list below; nothing under it can pass this check.
+_STD_SUPPORTED_NAMES = {
+    "filter", "map", "take", "count", "sum", "sort_by", "group_by", "chunk",
+    "join", "split", "first_char", "int_to_float", "float_to_int",
+    "trim", "upper", "lower", "keys", "values", "get_or", "concat", "append",
+    "now",
+    # std.str's `regex` (spec section 13): `matches(s, pattern)`, added
+    # alongside its `vlbuild/emit.py` `STD_FNS` entry and `VL.std.matches`
+    # (assets/vlrt.js) -- keep all three in sync by hand.
+    "matches",
+}
+
+
+def _lit_text(v):
+    """The literal text of a plain string literal, or None when `v` is not one
+    (a bare word, an expression, or an *interpolated* string -- whose runtime
+    value the compiler cannot judge statically). Used to catch a statically
+    empty accessible name (`label:""`, `aria_label:"   "`)."""
+    if not isinstance(v, A.Literal) or v.kind != "str":
+        return None
+    if getattr(v, "interp_names", None):
+        return None
+    raw = v.raw or ""
+    if len(raw) >= 6 and raw[:3] == '"""' and raw[-3:] == '"""':
+        return raw[3:-3]
+    if len(raw) >= 2 and raw[0] == '"' and raw[-1] == '"':
+        return raw[1:-1]
+    return raw
+
+
+def _img_alt_kinds(node):
+    """Classify an `img`'s alt declarations (spec §8.10). Returns
+    (kinds, alt_value) -- `kinds` is a list of "meaningful" / "decorative" /
+    "todo", one per declaration found, so 0 = none and >1 = conflicting. The
+    name form is a single `alt:` attribute: real text, or the bare word
+    `decorative` (presentational) / `todo` (placeholder); `alt_todo:<text>`
+    is the placeholder-with-a-note variant."""
+    kinds: list[str] = []
+    alt_value = None
+    for k, v in node.attrs:
+        if k == "alt":
+            alt_value = v
+            if isinstance(v, A.Name) and v.id in ("decorative", "todo"):
+                kinds.append(v.id if v.id == "decorative" else "todo")
+            else:
+                kinds.append("meaningful")
+        elif k == "alt_todo":
+            alt_value = v
+            kinds.append("todo")
+    return kinds, alt_value
+
+
+def _is_dc(x) -> bool:
+    return hasattr(x, "__dataclass_fields__")
+
+
+def _walk(node):
+    """Yield every dataclass node reachable from `node` (through lists and tuples)."""
+    if node is None:
+        return
+    if isinstance(node, (list, tuple)):
+        for x in node:
+            yield from _walk(x)
+        return
+    if not _is_dc(node):
+        return
+    yield node
+    for f in node.__dataclass_fields__:
+        if f in ("start", "end"):
+            continue
+        yield from _walk(getattr(node, f))
+
+
+class Checker:
+    def __init__(self, filename: str, li: LineIndex, strict_names: bool = False,
+                 release: bool = False) -> None:
+        self.filename = filename
+        self.li = li
+        self.strict_names = strict_names
+        # `release` (vlcheck --release / vlbuild --release): promote the
+        # "unresolved dev placeholder" warnings to errors -- the gate that
+        # keeps a `alt_todo:` / other TODO marker out of a shipped build.
+        self.release = release
+        self.diags: list[Diagnostic] = []
+
+    # -- emit ----------------------------------------------------------
+    def _d(self, code: str, sev: Severity, msg: str, node, fix: str | None = None) -> None:
+        s = getattr(node, "start", 0)
+        e = getattr(node, "end", s + 1)
+        self.diags.append(Diagnostic(code, sev, msg, s, max(e, s + 1), fix, self.filename))
+
+    def run(self, mod: A.Module) -> list[Diagnostic]:
+        from .test_ids import check_test_ids
+        self.diags.extend(check_test_ids(mod, self.filename))
+        self.structural(mod)
+        self.styling(mod)
+        self.accessible_primitives(mod)
+        self.view_bindings(mod)
+        self.callback_props(mod)
+        self.document_structure(mod)
+        self.composed_document(mod)
+        self.services(mod)
+        self.api_params(mod)
+        self.imports(mod)
+        self.semantic(mod)
+        return self.diags
+
+    # -- std imports: only names vlbuild actually lowers are usable --------
+    def imports(self, mod: A.Module) -> None:
+        """`use std.X { name }` where `name` is not one `vlbuild` lowers
+        compiles clean today and fails at runtime instead (see
+        `_STD_SUPPORTED_NAMES`'s docstring above) -- the same silent-wrong
+        shape `E-VARIANT-LITERAL` / `E-ASSIGN-READONLY` exist to catch
+        elsewhere in this file, just for the standard library's surface
+        rather than a view's. A relative (`./`/`../`) or third-party `use` is
+        untouched here -- `vlcheck --resolve` (resolve.py) is the pass that
+        follows a project-relative path; this only judges `std.*`, the one
+        namespace with a closed, compiler-owned surface."""
+        for it in mod.items:
+            if not (isinstance(it, A.Use) and it.path.startswith("std.")):
+                continue
+            for name in it.names:
+                if name not in _STD_SUPPORTED_NAMES:
+                    self._d("E-UNKNOWN-STD-IMPORT", Severity.ERROR,
+                            f"'{name}' is not a function this build of Volaro "
+                            f"implements -- '{it.path}' has no working '{name}'; "
+                            "it would compile with 0 errors and fail at runtime "
+                            "calling an undefined function", it,
+                            "supported std functions: "
+                            + ", ".join(sorted(_STD_SUPPORTED_NAMES)))
+
+    # -- view bindings: what may be assigned to, and literal-only attrs ----
+    def view_bindings(self, mod: A.Module) -> None:
+        """Per view: (1) a `derive` / `load` value and a parameter are
+        read-only -- assigning to one lowers to a dead JS statement, so reject
+        it; (2) `variant:` takes a bare *style name*, never a value -- a
+        computed expression is dropped by the emitter and a bare identifier
+        that is really a `state` / loop var is emitted as the identifier text,
+        not its value. A silent no-op / silent-wrong-token is the worst
+        failure mode for a language whose errors are the documentation."""
+        for it in mod.items:
+            if not isinstance(it, A.ViewDecl):
+                continue
+            readonly: dict[str, str] = {}
+            for p in it.params:
+                readonly[p.name] = "parameter"
+            for st in it.body:
+                if isinstance(st, A.DeriveDecl):
+                    readonly[st.name] = "derive"
+                elif isinstance(st, A.LoadDecl):
+                    readonly[st.name] = "load result"
+            # every name that names a *value* in this view (mutable or not) --
+            # used to tell `variant:primary` (a style token) from
+            # `variant:mode` (a variable read)
+            value_names: set[str] = set(readonly)
+            for st in it.body:
+                if isinstance(st, A.StateDecl):
+                    value_names.add(st.name)
+            for node in _walk(it.body):
+                if isinstance(node, A.ListBlock) and node.var:
+                    value_names.add(node.var)
+                elif isinstance(node, A.For):
+                    value_names.update(getattr(node, "vars", []) or [])
+
+            for node in _walk(it.body):
+                if isinstance(node, A.Assign):
+                    tgt = getattr(node, "target", None)
+                    nm = tgt.id if isinstance(tgt, A.Name) else None
+                    if nm in readonly:
+                        self._d("E-ASSIGN-READONLY", Severity.ERROR,
+                                "'%s' is a %s and cannot be assigned to -- it is "
+                                "recomputed, not stored. Declare a `state` for a "
+                                "value you change." % (nm, readonly[nm]),
+                                node, None)
+                elif isinstance(node, A.Element):
+                    for k, v in node.attrs:
+                        if k != "variant":
+                            continue
+                        if not isinstance(v, A.Name):
+                            self._d("E-VARIANT-LITERAL", Severity.ERROR,
+                                    "variant: takes a bare style name "
+                                    "(variant:primary), not an expression -- a "
+                                    "computed value is silently ignored by the "
+                                    "build. Put the choice in the positional "
+                                    "label, or split into two elements.",
+                                    node, "variant:primary")
+                        elif v.id in value_names:
+                            self._d("E-VARIANT-LITERAL", Severity.ERROR,
+                                    "variant:%s reads '%s' as a literal style "
+                                    "token, not its value -- `variant:` is a "
+                                    "bare style name only. Vary the positional "
+                                    "label instead." % (v.id, v.id),
+                                    node, "variant:primary")
+
+    # -- callback props (DESIGN-01: child->parent data flow) -----------------
+    def callback_props(self, mod: A.Module) -> None:
+        """A `fn(...)`-typed view param is a callback prop (the decided
+        parent->child mutation idiom --
+        `documentation/language-design/CHILD-PARENT-DATA-FLOW-DECISION.md`):
+        the parent hands the child a closure that mutates the parent's own
+        `state`, never a raw setter. Two things this checker CAN decide
+        without real type inference (see the module docstring):
+
+        (1) at every call site that instantiates the view, the value given
+        for that prop must be a plausible callable -- a closure literal
+        (whose own arity is checked against the declared signature), or a
+        bare name (assumed to resolve to a callable somewhere in scope --
+        this prototype has no type inference to confirm it, matching how
+        `_resolve` / `R-UNDEF` elsewhere stay conservative rather than
+        guess). A literal of any other shape can never be called; the
+        emitter would still produce `<literal>(...)`, a guaranteed runtime
+        TypeError caught here at check time instead.
+
+        (2) inside the child's own body, calling that prop with the wrong
+        number of arguments -- the same arity mistake an ordinary function
+        call already gets, except no existing check reaches a `fn`-typed
+        param (it is a local binding, not a module-level declaration
+        `resolve.py`'s symbol table would recognise)."""
+        views = {it.name: it for it in mod.items if isinstance(it, A.ViewDecl)}
+        fn_params: dict[str, dict[str, A.TypeRef]] = {}
+        for name, v in views.items():
+            d = {p.name: p.type for p in v.params
+                 if isinstance(p.type, A.TypeRef) and p.type.is_fn}
+            if d:
+                fn_params[name] = d
+        if not fn_params:
+            return
+
+        # (1) every call site that passes one of these props.
+        for it in mod.items:
+            if not isinstance(it, A.ViewDecl):
+                continue
+            for node in _walk(it.body):
+                if not isinstance(node, A.Element) or node.name not in fn_params:
+                    continue
+                wanted = fn_params[node.name]
+                for k, v in node.attrs:
+                    sig = wanted.get(k)
+                    if sig is None:
+                        continue
+                    if isinstance(v, A.Closure):
+                        want_n, got_n = len(sig.fn_params), len(v.params)
+                        if got_n != want_n:
+                            self._d("E-CALLBACK-PROP-ARITY", Severity.ERROR,
+                                    "'%s:' on <%s> is %s -- the closure passed "
+                                    "has %d parameter%s, not %d"
+                                    % (k, node.name, _fn_sig(sig), got_n,
+                                       "" if got_n == 1 else "s", want_n),
+                                    v, None)
+                        continue
+                    if isinstance(v, A.Name):
+                        continue   # assumed callable; no type inference here
+                    self._d("E-CALLBACK-PROP-TYPE", Severity.ERROR,
+                            "'%s:' on <%s> is a callback prop (%s) and needs "
+                            "a closure or a callable value -- a literal can "
+                            "never be called" % (k, node.name, _fn_sig(sig)),
+                            v,
+                            "%s: fn(%s) ..." % (
+                                k, ", ".join("_" for _ in sig.fn_params)))
+
+        # (2) arity at each call *inside* the child that owns the prop.
+        for name, params in fn_params.items():
+            for node in _walk(views[name].body):
+                if not isinstance(node, A.Call) or not isinstance(node.callee, A.Name):
+                    continue
+                sig = params.get(node.callee.id)
+                if sig is None:
+                    continue
+                want, got = len(sig.fn_params), len(node.args)
+                if got != want:
+                    self._d("E-CALLBACK-PROP-ARITY", Severity.ERROR,
+                            "'%s' takes %d argument%s (%s) -- called here "
+                            "with %d" % (node.callee.id, want,
+                                        "" if want == 1 else "s", _fn_sig(sig), got),
+                            node, None)
+
+    def styling(self, mod: A.Module) -> None:
+        """Checks that are decidable within one source file. Project-wide
+        recipe selection/conflicts are checked by vlbuild after discovery."""
+        themes = [x for x in mod.items
+                  if isinstance(x, A.Directive) and x.head == "theme"]
+        for extra in themes[1:]:
+            self._d("E-THEME-DUP", Severity.ERROR,
+                    "a project may declare only one theme", extra)
+        for theme in themes[:1]:
+            categories: set[str] = set()
+            for category in theme.body:
+                if category.head not in {"color", "space", "radius", "font", "screen", "motion"}:
+                    self._d("E-THEME-SHAPE", Severity.ERROR,
+                            "unknown theme category %r" % category.head, category)
+                    continue
+                if category.head in categories:
+                    self._d("E-THEME-SHAPE", Severity.ERROR,
+                            "theme category %r is repeated" % category.head, category)
+                categories.add(category.head)
+                rows = [r.tokens for r in category.body]
+                if not rows:
+                    flat = category.tokens[1:]
+                    if not flat or len(flat) % 2:
+                        self._d("E-THEME-SHAPE", Severity.ERROR,
+                                "%s needs name/value pairs" % category.head, category)
+                        continue
+                    rows = [flat[i:i + 2] for i in range(0, len(flat), 2)]
+                names: set[str] = set()
+                for row in rows:
+                    name = row[0] if row else "?"
+                    if name in names or (category.head == "color" and name in
+                                         {"white", "black", "transparent", "current"}):
+                        self._d("E-TOKEN-DUP", Severity.ERROR,
+                                "duplicate theme token %s.%s" % (category.head, name), category)
+                    names.add(name)
+                    if name in {"container", "columns", "break", "box", "object", "overflow"}:
+                        self._d("E-TOKEN-RESERVED", Severity.ERROR,
+                                "theme token %r shadows a utility root" % name, category)
+                    valid = len(row) >= 2
+                    if category.head in {"space", "radius", "screen"}:
+                        valid = len(row) == 2 and bool(re.fullmatch(r"\d+(?:\.\d+)?", row[1]))
+                    elif category.head == "color":
+                        valid = (len(row) == 2 or
+                                 (len(row) == 4 and row[2] == "dark"))
+                    elif category.head == "motion":
+                        valid = row == ["reduce", "respect"]
+                    if not valid:
+                        self._d("E-THEME-SHAPE", Severity.ERROR,
+                                "malformed %s token row" % category.head, category)
+        allowed = {"button", "input", "card"}
+        seen_recipes: set[str] = set()
+        for recipe in (x for x in mod.items if isinstance(x, A.RecipeDecl)):
+            if recipe.primitive not in allowed:
+                self._d("E-RECIPE-UNKNOWN-PRIMITIVE", Severity.ERROR,
+                        "Slice 1 recipes support button, input, and card; got %r"
+                        % recipe.primitive, recipe)
+                continue
+            if recipe.primitive in seen_recipes:
+                self._d("E-RECIPE-SHAPE", Severity.ERROR,
+                        "recipe %r is declared more than once" % recipe.primitive,
+                        recipe)
+            seen_recipes.add(recipe.primitive)
+            bases = [r for r in recipe.body
+                     if isinstance(r, A.Directive) and r.head == "base"]
+            if len(bases) != 1 or len(bases[0].tokens) != 2:
+                self._d("E-RECIPE-SHAPE", Severity.ERROR,
+                        "recipe %r needs exactly one literal-string base row"
+                        % recipe.primitive, recipe,
+                        'base "classes"')
+                continue
+            classes = bases[0].tokens[1]
+            axes: dict[str, set[str]] = {}
+            defaults: list[tuple[str, str]] = []
+            for row in recipe.body:
+                if row.head == "base":
+                    continue
+                if row.head == "default":
+                    rest = row.tokens[1:]
+                    if len(rest) % 3 or any(rest[i + 1] != ":" for i in range(0, len(rest), 3)):
+                        self._d("E-RECIPE-SHAPE", Severity.ERROR,
+                                "default entries use axis:value", row)
+                    else:
+                        defaults.extend((rest[i], rest[i + 2]) for i in range(0, len(rest), 3))
+                    continue
+                if len(row.tokens) != 3:
+                    self._d("E-RECIPE-SHAPE", Severity.ERROR,
+                            "axis row is `axis value \"classes\"`", row)
+                    continue
+                axis, value = row.tokens[:2]
+                if value in axes.setdefault(axis, set()):
+                    self._d("E-RECIPE-SHAPE", Severity.ERROR,
+                            "duplicate recipe value %s.%s" % (axis, value), row)
+                axes[axis].add(value)
+            seen_defaults: set[str] = set()
+            for axis, value in defaults:
+                if axis in seen_defaults:
+                    self._d("E-RECIPE-AXIS-DUP", Severity.ERROR,
+                            "default repeats axis %r" % axis, recipe)
+                seen_defaults.add(axis)
+                if value not in axes.get(axis, set()):
+                    self._d("E-RECIPE-SHAPE", Severity.ERROR,
+                            "default %s:%s is not declared" % (axis, value), recipe)
+            if recipe.primitive in ("button", "input"):
+                all_tokens = " ".join(" ".join(r.tokens) for r in recipe.body)
+                if "focus-visible:" not in all_tokens:
+                    self._d("E-RECIPE-FOCUS", Severity.ERROR,
+                            "interactive recipe %r needs a focus-visible: treatment"
+                            % recipe.primitive, recipe)
+                if (("transition" in all_tokens or "animate-" in all_tokens)
+                        and "motion-reduce:" not in all_tokens):
+                    self._d("E-RECIPE-MOTION", Severity.ERROR,
+                            "recipe %r uses motion without a motion-reduce: counterpart"
+                            % recipe.primitive, recipe)
+
+        for node in _walk(mod):
+            if not isinstance(node, A.Element):
+                continue
+            class_values = [v for k, v in node.attrs if k == "class"]
+            if len(class_values) > 1:
+                self._d("E-RECIPE-AXIS-DUP", Severity.ERROR,
+                        "class: may occur only once on an element", node)
+            for value in class_values:
+                if (not isinstance(value, A.Literal) or value.kind != "str"
+                        or getattr(value, "interp_names", None)):
+                    self._d("E-CLASS-DYNAMIC", Severity.ERROR,
+                            "class: must be a complete, non-interpolated string literal",
+                            node, 'class:"w-full sm:w-auto"')
+                    continue
+                text = _lit_text(value) or ""
+                classes = text.split()
+                if any(c.rsplit(":", 1)[-1].startswith("!")
+                       or c.rsplit(":", 1)[-1].endswith("!") for c in classes):
+                    self._d("E-CLASS-IMPORTANT", Severity.ERROR,
+                            "class: cannot use !important to force precedence", node)
+                utilities = [c.rsplit(":", 1)[-1] for c in classes]
+                if node.name == "status" and any(c in {"hidden", "invisible"} for c in utilities):
+                    self._d("E-CLASS-LIVE-HIDDEN", Severity.ERROR,
+                            "a compiler-owned live region must remain exposed", node)
+                if node.name == "status" and "sr-only" in utilities:
+                    self._d("W-CLASS-LIVE-SR-ONLY", Severity.WARNING,
+                            "status feedback remains audible but should also be visually present", node)
+                if any("[" in c and "]" in c for c in classes):
+                    self._d("W-CLASS-ARBITRARY", Severity.WARNING,
+                            "arbitrary values bypass the accessibility denylist", node)
+                if (node.name in {"button", "input", "link"}
+                        and any(c in {"outline-none", "outline-0", "ring-0"} for c in utilities)
+                        and not any("focus-visible:" in c and c.rsplit(":", 1)[-1]
+                                    not in {"outline-none", "outline-0", "ring-0"}
+                                    for c in classes)):
+                    self._d("E-CLASS-FOCUS-REMOVED", Severity.ERROR,
+                            "removed focus needs a focus-visible replacement", node)
+        # `variant:` literal-only enforcement lives in `view_bindings`, which
+        # has the per-view name set needed to tell a style token from a
+        # variable read.
+
+    # -- accessible primitives: dialog, tabs / tab (spec section 8.8) --------
+    def accessible_primitives(self, mod: A.Module) -> None:
+        def has_on(el, event):
+            return any(isinstance(b, A.OnBlock) and b.event == event for b in el.body)
+
+        def visit(node, parent_el):
+            if isinstance(node, A.Element):
+                attrs = {k for k, _ in node.attrs}
+
+                if node.name == "tab" and parent_el != "tabs":
+                    self._d("E-TAB-PARENT", Severity.ERROR,
+                            "'tab' is only valid as a direct child of 'tabs'", node,
+                            "put this 'tab' inside a 'tabs' element")
+
+                if node.name == "tabs":
+                    if "bind" not in attrs and "selected" not in attrs:
+                        self._d("E-TABS-BIND", Severity.ERROR,
+                                "'tabs' needs a selection: 'bind:<state>', or "
+                                "'selected:<id>' with 'on select'", node,
+                                "tabs bind:tab")
+                    if "selected" in attrs and not has_on(node, "select"):
+                        self._d("E-TABS-SELECT", Severity.ERROR,
+                                "'tabs selected:<id>' needs 'on select t: ...' to "
+                                "write the choice back", node,
+                                "add 'on select t:' or use 'bind:tab' instead")
+                    tab_kids = [b for b in node.body
+                                if isinstance(b, A.Element) and b.name == "tab"]
+                    if not tab_kids:
+                        self._d("E-TABS-EMPTY", Severity.ERROR,
+                                "'tabs' has no 'tab' children", node,
+                                'tab "id" label:"Label"')
+                    for b in node.body:
+                        if isinstance(b, A.Element) and b.name != "tab":
+                            self._d("E-TABS-CHILD", Severity.ERROR,
+                                    "'tabs' takes only 'tab' children; put other "
+                                    "content inside a 'tab'", b, None)
+
+                if node.name == "tab":
+                    if not node.args:
+                        self._d("E-TAB-ID", Severity.ERROR,
+                                "'tab' needs an id as its first value", node,
+                                'tab "overview" label:"Overview"')
+                    if "label" not in attrs:
+                        self._d("E-TAB-LABEL", Severity.ERROR,
+                                "'tab' needs a 'label'", node,
+                                'tab "overview" label:"Overview"')
+
+                if node.name == "status":
+                    if (len(node.args) != 1 or node.body
+                            or any(k not in ("class", "test_id", "test_scope") for k, _ in node.attrs)):
+                        self._d("E-STATUS-SHAPE", Severity.ERROR,
+                                "'status' takes one POSITIONAL expression (not an "
+                                "attribute), optional class:, and no children",
+                                node, 'status outcome_message — a bare expression, '
+                                'never `status message:outcome_message`; keep it '
+                                'mounted, use nil or "" while idle')
+
+                if node.name == "input":
+                    # spec §8.9: every input carries a programmatic name,
+                    # through *exactly one* of `label:` / `aria_label:`. A
+                    # placeholder is not a label (it vanishes on input and
+                    # some assistive tech skips it), so it does not count;
+                    # neither does an empty or whitespace-only string.
+                    name_kinds = [k for k, _ in node.attrs
+                                  if k in ("label", "aria_label")]
+                    if not name_kinds:
+                        hint = (" ('placeholder' is not a label)"
+                                if "placeholder" in attrs else "")
+                        self._d("E-INPUT-NAME", Severity.ERROR,
+                                "'input' needs an accessible name: 'label:' for a "
+                                "visible label, or 'aria_label:' when the purpose is "
+                                "clear from nearby content" + hint, node,
+                                'input label:"Email" bind:email')
+                    elif len(name_kinds) > 1:
+                        self._d("E-INPUT-NAME-DUP", Severity.ERROR,
+                                "'input' takes exactly one accessible name -- "
+                                "'label:' or 'aria_label:', not both", node,
+                                'keep the visible one: input label:"Email" bind:email')
+                    for k, v in node.attrs:
+                        if k in ("label", "aria_label") and (
+                                (t := _lit_text(v)) is not None and t.strip() == ""):
+                            self._d("E-INPUT-NAME", Severity.ERROR,
+                                    "'input' %s is empty -- an accessible name "
+                                    "cannot be blank or whitespace" % k, node,
+                                    'input label:"Email" bind:email')
+
+                if node.name == "img":
+                    # spec §8.10: every image declares its alternative text
+                    # through exactly one of `alt:"…"` (meaningful),
+                    # `alt:decorative` (presentational -> alt=""), or
+                    # `alt:todo` / `alt_todo:"…"` (an unfinished placeholder
+                    # the release check flags).
+                    kinds, alt_v = _img_alt_kinds(node)
+                    if not kinds:
+                        self._d("E-IMG-ALT", Severity.ERROR,
+                                "'img' needs alternative text: 'alt:\"…\"' for a "
+                                "meaningful image, 'alt:decorative' for a "
+                                "presentational one, or 'alt:todo' / "
+                                "'alt_todo:\"…\"' to mark it unfinished", node,
+                                'img src:avatar alt:"{user.name} avatar"')
+                    elif len(kinds) > 1:
+                        self._d("E-IMG-ALT-ONE", Severity.ERROR,
+                                "'img' takes exactly one alt form: 'alt:' or "
+                                "'alt_todo:', not both", node,
+                                'img src:hero alt:"Team on stage"')
+                    elif kinds == ["meaningful"] and (
+                            (t := _lit_text(alt_v)) is not None and t.strip() == ""):
+                        self._d("E-IMG-ALT", Severity.ERROR,
+                                "'img alt:' is empty -- an empty alt means "
+                                "decorative; write 'alt:decorative' if that is "
+                                "the intent", node, "img src:divider alt:decorative")
+                    elif kinds == ["todo"] and self.release:
+                        self._d("E-IMG-ALT-TODO", Severity.ERROR,
+                                "'img' alt text is still a placeholder -- a "
+                                "release build needs real 'alt:' text or "
+                                "'alt:decorative'", node,
+                                'alt:"a clear description of what the image shows"')
+                    elif kinds == ["todo"]:
+                        self._d("W-IMG-ALT-TODO", Severity.WARNING,
+                                "'img' alt text is an unfinished placeholder -- "
+                                "replace it with real 'alt:' text or "
+                                "'alt:decorative' before release", node,
+                                'alt:"a clear description of what the image shows"')
+
+                if node.name == "dialog":
+                    if "title" not in attrs:
+                        self._d("E-DIALOG-TITLE", Severity.ERROR,
+                                "'dialog' needs a 'title' — it is the accessible name",
+                                node, 'dialog title:"Discard changes?"')
+                    if not has_on(node, "dismiss"):
+                        self._d("E-DIALOG-DISMISS", Severity.ERROR,
+                                "'dialog' needs 'on dismiss:' — it runs on Escape, a "
+                                "backdrop click, and the close control", node,
+                                "on dismiss: confirming = false")
+
+                for b in node.body:
+                    visit(b, node.name)
+                return
+
+            if isinstance(node, (list, tuple)):
+                for x in node:
+                    visit(x, parent_el)
+            elif _is_dc(node):
+                for f in node.__dataclass_fields__:
+                    visit(getattr(node, f), parent_el)
+
+        for it in mod.items:
+            if isinstance(it, A.ViewDecl):
+                for st in it.body:
+                    visit(st, None)
+
+    # -- page title / headings / landmarks (spec section 8.11) ---------------
+    def document_structure(self, mod: A.Module) -> None:
+        pages = [it for it in mod.items if isinstance(it, A.PageDecl)]
+        if len(pages) > 1:
+            self._d("E-PAGE-DUP", Severity.ERROR,
+                    "only one `page` declaration per module", pages[1], None)
+        for pg in pages:
+            attrs = {k: v for k, v in pg.attrs}
+            if "title" not in attrs:
+                self._d("E-PAGE-TITLE", Severity.ERROR,
+                        "`page` needs a `title:` -- the document's accessible name",
+                        pg, 'page title:"Weekly Report"')
+            else:
+                t = _lit_text(attrs["title"])
+                if t is not None and t.strip() == "":
+                    self._d("E-PAGE-TITLE", Severity.ERROR,
+                            "`page title:` is empty -- give the document a real "
+                            "name (a name that only goes empty at runtime is "
+                            "`render.empty_page_title`)", pg,
+                            'page title:"Weekly Report"')
+            for k in attrs:
+                if k != "title":
+                    self._d("W-PAGE-ATTR", Severity.WARNING,
+                            "`page` setting '%s' is not recognised (only "
+                            "`title:` so far)" % k, pg, None)
+
+        # Per view, in source order: heading-level skips and landmark sanity.
+        # Deliberately per-view -- a reusable component that starts at `h2`
+        # because it will be dropped under some page's `h1` is legitimate and
+        # must not be flagged. `_walk` yields depth-first in field order, which
+        # tracks source order closely enough for a warning.
+        HEAD = {"h1": 1, "h2": 2, "h3": 3, "h4": 4, "h5": 5, "h6": 6}
+        for it in mod.items:
+            if not isinstance(it, A.ViewDecl):
+                continue
+            prev = 0
+            first_h1 = None
+            navs: list = []
+            mains: list = []
+            for node in _walk(it.body):
+                if not isinstance(node, A.Element):
+                    continue
+                lvl = HEAD.get(node.name)
+                if lvl is not None:
+                    if prev and lvl > prev + 1:
+                        self._d("W-HEADING-SKIP", Severity.WARNING,
+                                "heading jumps from h%d to h%d in one view -- "
+                                "screen-reader users navigate by level; don't "
+                                "skip one" % (prev, lvl), node,
+                                "use h%d here, or restructure the section" % (prev + 1))
+                    if lvl == 1:
+                        if first_h1 is not None:
+                            self._d("W-HEADING-MULTI-H1", Severity.WARNING,
+                                    "a view renders more than one `h1`; a page "
+                                    "usually has exactly one top-level heading",
+                                    node, "make the later one `h2`")
+                        else:
+                            first_h1 = node
+                    prev = lvl
+                elif node.name == "nav":
+                    navs.append(node)
+                elif node.name == "main":
+                    mains.append(node)
+            if len(navs) > 1:
+                for n in navs:
+                    if not any(k == "aria_label" for k, _ in n.attrs):
+                        self._d("E-NAV-NAME", Severity.ERROR,
+                                "with more than one `nav` in a view, each needs "
+                                "`aria_label:` so assistive tech can tell them "
+                                "apart", n, 'nav aria_label:"Primary"')
+            if len(mains) > 1:
+                self._d("E-MAIN-DUP", Severity.ERROR,
+                        "a view renders more than one `main` landmark -- there "
+                        "is one main region per page", mains[1], None)
+
+    # -- composed-page landmarks / ids (spec section 8.11) ------------------
+    # `document_structure` above never crosses a view boundary -- by design,
+    # so a reusable component that starts at `h2` or carries its own `nav`
+    # is not punished for a page it cannot see. But the runtime builds ONE
+    # document from a page-root view that renders child views (an `Element`
+    # whose name is another `view`) and may repeat them -- directly, or in a
+    # `list`. On that composed page a second `<main>` (every one emits
+    # `id="vl-main"`, so also a duplicate id and an ambiguous skip target),
+    # two `<nav>`s assistive tech cannot tell apart (both unnamed, or
+    # sharing one `aria_label:`), or one static `id:` rendered by more than
+    # one element are real defects no per-view pass can catch. This walks
+    # the component graph from the page root and tallies them.
+    #
+    # A subtree's tally is a *summary*, not a node list: per `<main>` /
+    # unnamed-`nav` and per named-`nav` label / static id, a worst-case
+    # occurrence `count`, a `repeat` flag (reached through a `list` -> 0..N
+    # instances) and, for landmarks, a `crosses` flag (reached through a
+    # component / `list` boundary). Siblings ADD counts and OR flags;
+    # branches of an `if` are mutually exclusive, so per key they take the
+    # MAX count and OR the flags -- a landmark in one branch cannot cancel a
+    # collision the other branch (or content outside the `if`) creates.
+    # `document_structure` still owns the pure single-view case (all at
+    # depth 0, no repeat), so `E-MAIN-COMPOSED` / the unnamed-`nav` form of
+    # `E-NAV-NAME` require `crosses` to avoid a duplicate diagnostic.
+    #
+    # Runs only when the module declares a `page` -- the same "this file
+    # builds a page" signal `vlbuild` uses. Cross-file `use` composition is
+    # out of scope here (the resolver would be the place); a component
+    # reused within one module -- the common case -- is covered. This is a
+    # structural over-approximation: conditions are not evaluated, so two
+    # separate `if`s that happen to be mutually exclusive by data are still
+    # treated as independently reachable.
+    def composed_document(self, mod: A.Module) -> None:
+        if not any(isinstance(it, A.PageDecl) for it in mod.items):
+            return
+        views = {it.name: it for it in mod.items if isinstance(it, A.ViewDecl)}
+        if not views:
+            return
+
+        # Same root pick as vlbuild Emitter._root_view_name: a preferred name
+        # if present, else the last view that needs no arguments.
+        ROOT_PREFERENCE = ("Dashboard", "Main", "App", "Page", "Root", "Index")
+        rootable = [n for n, v in views.items()
+                    if not v.params or all(p.default is not None for p in v.params)]
+        root = next((n for n in ROOT_PREFERENCE if n in rootable),
+                    rootable[-1] if rootable else None)
+        if root is None:
+            return
+
+        def land():
+            return {"count": 0, "repeat": False, "crosses": False, "nodes": []}
+
+        def empty():
+            return {"mains": land(), "unnamed_navs": land(),
+                    "named_navs": {}, "ids": {}}   # label / id -> land()-ish
+
+        def land_merge(a, b, add):
+            return {"count": (a["count"] + b["count"]) if add
+                    else max(a["count"], b["count"]),
+                    "repeat": a["repeat"] or b["repeat"],
+                    "crosses": a["crosses"] or b["crosses"],
+                    "nodes": a["nodes"] + b["nodes"]}
+
+        def keyed_merge(a, b, add):
+            out = {k: dict(v) for k, v in a.items()}
+            for k, v in b.items():
+                if k in out:
+                    out[k] = land_merge(out[k], v, add)
+                else:
+                    out[k] = dict(v)
+            return out
+
+        def combine(parts, add):
+            out = empty()
+            for p in parts:
+                out = {"mains": land_merge(out["mains"], p["mains"], add),
+                       "unnamed_navs": land_merge(out["unnamed_navs"],
+                                                  p["unnamed_navs"], add),
+                       "named_navs": keyed_merge(out["named_navs"],
+                                                 p["named_navs"], add),
+                       "ids": keyed_merge(out["ids"], p["ids"], add)}
+            return out
+
+        def walk(nodes, cur, depth, repeat, stack):
+            return combine([node_tally(n, cur, depth, repeat, stack)
+                            for n in (nodes or ())], add=True)
+
+        def node_tally(node, cur, depth, repeat, stack):
+            if isinstance(node, A.Element):
+                nm = node.name
+                here = empty()
+                crosses = depth >= 1 or repeat
+                if nm == "main":
+                    here["mains"] = {"count": 1, "repeat": repeat,
+                                     "crosses": crosses, "nodes": [node]}
+                elif nm == "nav":
+                    has_attr = any(k == "aria_label" for k, _ in node.attrs)
+                    lbl = next((_lit_text(v) for k, v in node.attrs
+                                if k == "aria_label"), None)
+                    if not has_attr or (lbl is not None and lbl.strip() == ""):
+                        here["unnamed_navs"] = {"count": 1, "repeat": repeat,
+                                                "crosses": crosses, "nodes": [node]}
+                    elif lbl is not None:            # static, non-empty name
+                        here["named_navs"] = {lbl.strip(): {
+                            "count": 1, "repeat": repeat, "crosses": crosses,
+                            "nodes": [node]}}
+                    # a dynamic aria_label: is "named" but uncheckable -> skip
+                for k, v in node.attrs:
+                    if k == "id":
+                        t = _lit_text(v)
+                        if t is not None and t.strip():
+                            cur_id = here["ids"].get(t.strip())
+                            if cur_id:
+                                cur_id["count"] += 1
+                                cur_id["nodes"].append(node)
+                            else:
+                                here["ids"][t.strip()] = {
+                                    "count": 1, "repeat": repeat,
+                                    "crosses": crosses, "nodes": [node]}
+                parts = [here, walk(node.body, cur, depth, repeat, stack)]
+                if nm in views and nm not in stack:
+                    parts.append(walk(views[nm].body, nm, depth + 1, repeat,
+                                      stack | {nm}))
+                return combine(parts, add=True)
+            if isinstance(node, A.ListBlock):
+                return walk(node.body, cur, depth + 1, True, stack)
+            if isinstance(node, A.If):
+                branches = [walk(node.then, cur, depth, repeat, stack)]
+                for _c, body in node.elifs:
+                    branches.append(walk(body, cur, depth, repeat, stack))
+                branches.append(walk(node.orelse, cur, depth, repeat, stack))
+                return combine(branches, add=False)      # mutually exclusive
+            if isinstance(node, A.LoadDecl):
+                # pending / error bodies are alternatives to the loaded view.
+                return combine([walk(node.pending, cur, depth, repeat, stack),
+                                walk(node.error_body, cur, depth, repeat, stack)],
+                               add=False)
+            return empty()
+
+        t = walk(views[root].body, root, 0, False, {root})
+
+        # More than one <main> can reach the page, and at least one comes
+        # through a component / `list` boundary (the pure single-view case
+        # is `document_structure`'s `E-MAIN-DUP`).
+        m = t["mains"]
+        if m["nodes"] and m["crosses"] and (m["count"] >= 2 or m["repeat"]):
+            nodes = m["nodes"]
+            offender = nodes[1] if len(nodes) >= 2 else nodes[0]
+            self._d("E-MAIN-COMPOSED", Severity.ERROR,
+                    "the composed page renders more than one `main` landmark "
+                    "-- a `main` in the page-root view and in a view it "
+                    "renders, a view whose `main` is reused, or a `main` "
+                    "inside a `list` (mutually exclusive `if` / `else` "
+                    'branches count once). Every `main` emits id="vl-main", '
+                    "so this is also a duplicate id and an ambiguous "
+                    "skip-link target. Keep the single `main` in the "
+                    "page-root view.", offender, None)
+
+        # Two or more unnamed <nav>s can reach the page, at least one across
+        # a view / `list` boundary (single-view case is per-view `E-NAV-NAME`).
+        un = t["unnamed_navs"]
+        if un["nodes"] and un["crosses"] and (un["count"] >= 2 or un["repeat"]):
+            for n in un["nodes"]:
+                self._d("E-NAV-NAME", Severity.ERROR,
+                        "the composed page renders more than one unnamed "
+                        "`nav` landmark across the views it composes -- give "
+                        "each `nav` a distinct `aria_label:` so assistive tech "
+                        "can tell them apart", n, 'nav aria_label:"Primary"')
+
+        # Two or more <nav>s sharing one accessible name -- not caught
+        # anywhere else, within a view or across composed views.
+        for lbl, info in t["named_navs"].items():
+            if info["count"] >= 2 or info["repeat"]:
+                for n in info["nodes"]:
+                    self._d("E-NAV-NAME", Severity.ERROR,
+                            'more than one `nav` on the composed page is named '
+                            '"%s" -- sibling and composed navigation regions '
+                            "need *distinct* `aria_label:` names" % lbl, n,
+                            'e.g. aria_label:"Primary" and aria_label:"Footer"')
+
+        # Any id rendered by more than one element on the page.
+        for id_str, info in t["ids"].items():
+            if info["count"] >= 2 or info["repeat"]:
+                for node in (info["nodes"][1:] or info["nodes"]):
+                    self._d("E-ID-DUP", Severity.ERROR,
+                            'id "%s" is rendered by more than one element on '
+                            "the composed page (a reused component, a `list`, "
+                            "or two views with the same static `id:`) -- an id "
+                            "must be unique in the document" % id_str, node,
+                            "use a distinct id, or select by role / text instead")
+
+    # -- structural (no scope needed) -----------------------------------------
+    def structural(self, mod: A.Module) -> None:
+        for node in _walk(mod):
+            if isinstance(node, A.TypeRef) and node.opt_nested:
+                self._d("E-OPT-NEST", Severity.ERROR,
+                        "optional types do not nest ('T??' is not allowed)", node,
+                        "use a single '?'")
+            elif isinstance(node, A.ListBlock) and not node.has_key:
+                v = node.var if node.var and node.var != "?" else "item"
+                self._d("E-LIST-KEY", Severity.ERROR,
+                        "list block requires a stable 'key' expression", node,
+                        f"list <expr> as {v} key:{v}.id")
+            elif isinstance(node, A.Let) and node.empty_literal_no_type:
+                self._d("E-EMPTY-INFER", Severity.ERROR,
+                        "cannot infer the element type of an empty collection literal", node,
+                        "add a type annotation, e.g. 'let x list<str> = []'")
+            elif isinstance(node, A.RecordLit) and node.type_name == "Err":
+                self._d("E-ERR-LITERAL", Severity.ERROR,
+                        "'Err' is never constructed with record-literal syntax (spec section 6.3)",
+                        node, 'use err(...), e.g. err(not_found("no such post"))')
+
+    # -- services ----------------------------------------------------
+    def services(self, mod: A.Module) -> None:
+        for it in mod.items:
+            if not isinstance(it, A.ServiceDecl):
+                continue
+            routes = it.routes
+            svc_public = getattr(it, "is_public", False)
+
+            def _explicit_none(r):
+                return r.guard is not None and getattr(r.guard, "kind", "") == "none"
+
+            # `guard is None` = no line at all; `auth none` = deliberate. Both are
+            # "public" for the majority count; only the first is "maybe forgotten".
+            public = [r for r in routes if r.guard is None or _explicit_none(r)]
+
+            if not svc_public:
+                for r in routes:
+                    if r.guard is None:
+                        self._d("W-ROUTE-NO-AUTH", Severity.WARNING,
+                                f"route '{r.method} {r.path}' has no 'auth' guard (public)", r,
+                                "add an 'auth ...' line, 'auth none' to mark it deliberate, "
+                                "or 'service ... public'")
+                if routes and len(public) * 2 > len(routes):
+                    self._d("W-PUBLIC-MAJORITY", Severity.WARNING,
+                            f"{len(public)} of {len(routes)} routes in service '{it.name}' are public",
+                            it,
+                            "guards may have been omitted entirely; review each public route, "
+                            "or declare 'service ... public'")
+
+            # An unauthenticated write is a distinct claim: warn even under
+            # `service ... public` and even with an explicit `auth none` (spec section 10).
+            for r in routes:
+                if r.method in ("post", "patch", "put", "delete") and (
+                        r.guard is None or _explicit_none(r)):
+                    self._d("W-WRITE-NO-AUTH", Severity.WARNING,
+                            f"state-changing route '{r.method} {r.path}' has no 'auth' guard", r,
+                            "add 'auth role:...' or 'auth owner:...'")
+
+    # -- outbound api param routing (spec section 9) --------------------
+    def api_params(self, mod: A.Module) -> None:
+        # For a body-less method every parameter must ride in the path or the
+        # query string; there is nowhere else to put it. `post`/`put`/`patch`
+        # parameters that are neither become the request body, which is fine.
+        for it in mod.items:
+            if not isinstance(it, A.ApiDecl):
+                continue
+            for ep in it.endpoints:
+                if ep.method not in ("get", "delete", "head"):
+                    continue
+                routed: set[str] = set()
+                for d in ep.settings:
+                    if not isinstance(d, A.Directive):
+                        continue
+                    if d.head == "path":
+                        routed.update(re.findall(r"\{(\w+)\}", " ".join(d.tokens)))
+                    elif d.head == "query":
+                        routed.update(t for t in d.tokens if t.isidentifier())
+                for p in ep.params:
+                    if p.name and p.name != "?" and p.name not in routed:
+                        self._d("E-API-PARAM-UNROUTED", Severity.ERROR,
+                                f"parameter '{p.name}' of '{ep.method} {ep.name}' is in neither "
+                                f"the path nor 'query', and a '{ep.method}' has no request body "
+                                "to carry it", ep,
+                                f"add '{p.name}' to the 'query' line, or '{{{p.name}}}' to the path")
+
+    # -- semantic (scoped) ---------------------------------------------
+    def semantic(self, mod: A.Module) -> None:
+        top = set(BUILTINS) | set(_PRIM_NAMES)
+        for it in mod.items:
+            nm = getattr(it, "name", None)
+            if nm:
+                top.add(nm)
+            if isinstance(it, A.Use):
+                for n in it.names:
+                    top.add(n)
+                base = it.path.replace("./", "").replace("../", "")
+                base = base.split("/")[-1].split(".")[-1]
+                if base:
+                    top.add(base)
+            elif isinstance(it, A.ApiDecl):
+                for ep in it.endpoints:
+                    top.add(ep.name)
+            elif isinstance(it, A.TypeDecl) and it.kind == "union":
+                for v in it.variants:
+                    top.add(v.name)
+            elif isinstance(it, (A.TypeDecl, A.ModelDecl)):
+                pass
+
+        for it in mod.items:
+            if isinstance(it, A.FnDecl):
+                scope = {p.name for p in it.params}
+                self._scoped(it.body, [top, scope], fallible=_fallible(it.ret))
+            elif isinstance(it, A.ViewDecl):
+                scope = {p.name for p in it.params} | {"session"}
+                for s in it.body:
+                    if isinstance(s, (A.StateDecl, A.DeriveDecl, A.LoadDecl)):
+                        scope.add(s.name)
+                self._scoped(it.body, [top, scope], fallible=True)
+            elif isinstance(it, A.ServiceDecl):
+                for r in it.routes:
+                    scope = {p.name for p in r.params} | {"session"}
+                    for seg in r.path.split("/"):
+                        if seg.startswith(":"):
+                            scope.add(seg[1:])
+                    self._scoped(r.body, [top, scope], fallible=_fallible(r.ret))
+
+    def _resolve(self, name: str, scopes: list[set]) -> bool:
+        if name in ("?", "_", "self"):
+            return True
+        return any(name in s for s in scopes)
+
+    def _declare(self, name: str, scopes: list[set], at) -> None:
+        if not name or name == "?":
+            return
+        if name in scopes[-1]:
+            self._d("E-SHADOW", Severity.ERROR,
+                    f"'{name}' shadows a binding already in this scope", at,
+                    f"rename this binding; shadowing '{name}' is not allowed")
+        scopes[-1].add(name)
+
+    def _scoped(self, stmts, scopes: list[set], fallible: bool, in_loop: bool = False) -> None:
+        for st in stmts or []:
+            self._stmt(st, scopes, fallible, in_loop)
+
+    def _stmt(self, st, scopes: list[set], fallible: bool, in_loop: bool = False) -> None:
+        if st is None:
+            return
+        if isinstance(st, A.Let):
+            self._expr(st.init, scopes, fallible)
+            self._declare(st.name, scopes, st)
+        elif isinstance(st, A.Assign):
+            self._expr(st.target, scopes, fallible)
+            self._expr(st.value, scopes, fallible)
+        elif isinstance(st, A.ExprStmt):
+            self._expr(st.expr, scopes, fallible)
+        elif isinstance(st, A.Return):
+            self._expr(st.value, scopes, fallible)
+        elif isinstance(st, A.If):
+            self._expr(st.cond, scopes, fallible)
+            self._block(st.then, scopes, fallible, in_loop)
+            for c, b in st.elifs:
+                self._expr(c, scopes, fallible)
+                self._block(b, scopes, fallible, in_loop)
+            self._block(st.orelse, scopes, fallible, in_loop)
+        elif isinstance(st, A.Match):
+            self._expr(st.subject, scopes, fallible)
+            for pat, guard, body in st.arms:
+                inner = scopes + [set(getattr(pat, "binds", []))]
+                if guard is not None:
+                    self._expr(guard, inner, fallible)
+                self._block(body, inner, fallible, in_loop)
+        elif isinstance(st, A.For):
+            self._expr(st.iter, scopes, fallible)
+            inner = scopes + [set(st.vars)]
+            self._scoped(st.body, inner, fallible, in_loop=True)
+        elif isinstance(st, A.While):
+            self._expr(st.cond, scopes, fallible)
+            self._block(st.body, scopes, fallible, in_loop=True)
+        elif isinstance(st, A.Par):
+            self._block(st.lets, scopes, fallible, in_loop)
+        elif isinstance(st, A.Spawn):
+            self._block(st.body, scopes, fallible, in_loop=False)
+        elif isinstance(st, A.Try):
+            self._expr(st.expr, scopes, fallible)
+            for pat, body in st.catches:
+                inner = scopes + [set(getattr(pat, "binds", []))]
+                self._scoped(body, inner, fallible, in_loop)
+        elif isinstance(st, (A.Break, A.Skip)):
+            if not in_loop:
+                kw = "break" if isinstance(st, A.Break) else "skip"
+                self._d("E-LOOP-CONTROL", Severity.ERROR,
+                        f"'{kw}' is only valid inside a 'for' or 'while' loop", st,
+                        f"remove '{kw}', or move it into a loop body")
+        # view statements
+        elif isinstance(st, A.StateDecl):
+            self._expr(st.init, scopes, fallible)
+        elif isinstance(st, A.DeriveDecl):
+            self._expr(st.expr, scopes, fallible)
+        elif isinstance(st, A.LoadDecl):
+            self._expr(st.expr, scopes, fallible)
+            self._scoped(st.pending, scopes, fallible)
+            inner = scopes + [{st.error_name}] if st.error_name else scopes
+            self._scoped(st.error_body, inner, fallible)
+        elif isinstance(st, A.OnBlock):
+            inner = scopes + [set(st.args)]
+            self._scoped(st.body, inner, fallible, in_loop=False)
+        elif isinstance(st, A.ListBlock):
+            self._expr(st.src, scopes, fallible)
+            inner = scopes + [{st.var}]
+            if st.key is not None:
+                self._expr(st.key, inner, fallible)
+            self._scoped(st.body, inner, fallible, in_loop=False)
+        elif isinstance(st, A.Element):
+            for a in st.args:
+                self._expr(a, scopes, fallible)
+            for _, v in st.attrs:
+                self._expr(v, scopes, fallible)
+            self._scoped(st.body, scopes, fallible, in_loop)
+        else:
+            # unknown statement shape: still walk any expressions inside it
+            for node in _walk(st):
+                if isinstance(node, A.Name):
+                    self._use(node, scopes)
+
+    def _block(self, stmts, scopes: list[set], fallible: bool, in_loop: bool = False) -> None:
+        self._scoped(stmts, scopes + [set()], fallible, in_loop)
+
+    def _expr(self, ex, scopes: list[set], fallible: bool) -> None:
+        if ex is None:
+            return
+        if isinstance(ex, A.Name):
+            self._use(ex, scopes)
+        elif isinstance(ex, A.Literal):
+            if self.strict_names:
+                for n in ex.interp_names:
+                    if not self._resolve(n, scopes):
+                        self._d("W-UNDEF-NAME", Severity.WARNING,
+                                f"'{n}' in string interpolation is not defined in this scope", ex,
+                                "check the name, or add the binding / import")
+        elif isinstance(ex, A.Member):
+            self._expr(ex.obj, scopes, fallible)
+        elif isinstance(ex, A.Index):
+            self._expr(ex.obj, scopes, fallible)
+            self._expr(ex.index, scopes, fallible)
+        elif isinstance(ex, A.Call):
+            self._expr(ex.callee, scopes, fallible)
+            for a in ex.args:
+                self._expr(a, scopes, fallible)
+            for _, v in ex.named:
+                self._expr(v, scopes, fallible)
+        elif isinstance(ex, A.Unary):
+            self._expr(ex.operand, scopes, fallible)
+        elif isinstance(ex, A.Binary):
+            self._expr(ex.left, scopes, fallible)
+            self._expr(ex.right, scopes, fallible)
+        elif isinstance(ex, A.Range):
+            self._expr(ex.lo, scopes, fallible)
+            self._expr(ex.hi, scopes, fallible)
+        elif isinstance(ex, A.TryOp):
+            if not fallible:
+                self._d("E-PROP-FALLIBLE", Severity.ERROR,
+                        "'?' propagates an error but the enclosing function is not fallible", ex,
+                        "declare the return type as fallible (T!), or handle with try/catch or ??")
+            self._expr(ex.operand, scopes, fallible)
+        elif isinstance(ex, A.IfExpr):
+            self._expr(ex.cond, scopes, fallible)
+            self._expr(ex.then, scopes, fallible)
+            self._expr(ex.orelse, scopes, fallible)
+        elif isinstance(ex, A.MatchExpr):
+            self._expr(ex.subject, scopes, fallible)
+            for pat, guard, body in ex.arms:
+                inner = scopes + [set(getattr(pat, "binds", []))]
+                if guard is not None:
+                    self._expr(guard, inner, fallible)
+                self._scoped(body, inner, fallible)
+        elif isinstance(ex, A.Closure):
+            inner = scopes + [{p.name for p in ex.params}]
+            if isinstance(ex.body, list):
+                self._scoped(ex.body, inner, fallible)
+            else:
+                self._expr(ex.body, inner, fallible)
+        elif isinstance(ex, A.ListLit):
+            for x in ex.items:
+                self._expr(x, scopes, fallible)
+        elif isinstance(ex, A.RecordLit):
+            for _, v in ex.fields:
+                self._expr(v, scopes, fallible)
+
+    def _use(self, node: A.Name, scopes: list[set]) -> None:
+        if not self.strict_names:
+            return
+        n = node.id
+        if not n or n == "?" or n[:1].isupper():
+            return  # type / constructor names are not resolved in this prototype
+        if self._resolve(n, scopes):
+            return
+        self._d("W-UNDEF-NAME", Severity.WARNING,
+                f"'{n}' is not defined in this scope", node,
+                "check the name, or add the binding / import")
+
+
+def _fallible(tref) -> bool:
+    return isinstance(tref, A.TypeRef) and tref.fallible
+
+
+def _fn_sig(tref: A.TypeRef) -> str:
+    """Render a `fn(...)`-typed prop's signature for a diagnostic, e.g.
+    'fn(int, str) nil'."""
+    def name(t):
+        if t is None:
+            return "nil"
+        return "fn(...)" if getattr(t, "is_fn", False) else (t.name or "?")
+    return "fn(%s) %s" % (", ".join(name(p) for p in tref.fn_params),
+                          name(tref.fn_ret))
+
+
+def check(mod: A.Module, filename: str, li: LineIndex,
+          strict_names: bool = False, release: bool = False) -> list[Diagnostic]:
+    return Checker(filename, li, strict_names, release).run(mod)