volaro 0.0.2 → 0.1.0-alpha.3

package/compiler/validator/vlcheck/resolve.py

@@ -0,0 +1,849 @@
+"""L1 resolution pass — `vlcheck --resolve`.
+
+The Stage-3 G2 grader for the Volaro arm (`corpus/STAGE3-PROTOCOL.md` §6). Raises
+`vlcheck` from "parses" (L0) to "every referenced name / field / route / argument
+resolves with the right arity" (L1) — the rung `tsc --noEmit` occupies for the
+baseline arm.
+
+A resolver, **not** type inference. It builds a symbol table from declarations
+(this file's, plus those reached through `use`), tracks a local name → declared
+type only where the type is written down or trivially known, and reports:
+
+  R-UNDEF        name / component resolves to no declaration / import / builtin / binding
+  R-IMPORT       `use ./x { A }` where x is found but has no `A`
+  R-ROUTE        `api.f(...)` / `<svc>.f(...)` with no matching route / endpoint
+  R-ARITY        call to a resolved fn / view / route / endpoint / variant, wrong # of positional args
+  R-NAMED-ARG    named argument not in the callee's parameter list
+  R-MISSING-ARG  required parameter (no default, not optional-typed) not supplied
+  R-FIELD        `x.f` where x's type is a known record / model and f is neither a field nor a method
+  R-MATCH        `match` over a value of known union type, not exhaustive, no `_`
+  R-AUTH-METHOD  `auth.f(...)` where `f` is not one of the eight §11.3 calls
+
+Deliberately conservative — an unknown callee, an unknown receiver type, an
+element attribute value, or a `std.*` function (the spec gives no signature, and
+we do not invent one) is skipped rather than guessed. The Stage-3 hand audit
+covers the residue; a *false positive* here would unfairly fail a sample, so the
+bar (protocol §9.1) is: every hand-written reference `.vl` in `corpus/` resolves
+clean.
+
+Known spec looseness this pass papers over (each already in `PROJECT.md` §5.3 or
+the findings log):
+  * `std.ui` view surface (uppercase, no local `view`) is unlisted — `_UI_STD_VIEWS`;
+    the lowercase primitive set is `_UI_PRIMITIVES` (spec §3.4, exact);
+  * a handful of bare-word identifiers used as argument values (`asc`, `desc`,
+    `google`, …) — `_CONTEXTUAL`.
+
+The §10 item-route client name is now settled (method-aware) and implemented
+exactly in `_route_name`.
+"""
+
+from __future__ import annotations
+
+import os
+
+from . import ast_nodes as A
+from .checks import BUILTINS, _PRIM_NAMES
+from .diagnostics import Diagnostic, LineIndex, Severity
+from .lexer import Lexer
+from .parser import Parser
+
+# std.list / std.map / std math names referenced bare in the spec + corpus.
+# Names only — no arity is checked for these (no signature to check against).
+_STD_EXTRA = {
+    "sum", "count", "min", "max", "abs", "round", "floor", "ceil", "avg",
+    "reverse", "sorted", "unique", "flatten", "concat", "zip", "enumerate",
+    "range", "any", "all", "none", "contains", "index_of", "reduce", "slice",
+    "float_to_int", "trim", "upper", "lower", "starts_with", "ends_with",
+    "replace", "pad_start", "pad_end", "repeat", "now", "uuid4", "random",
+    "matches",
+}
+# bare-word identifiers the spec uses in argument position (not bindings)
+_CONTEXTUAL = {"asc", "desc", "google", "github"}
+# Spec §3.4: a component's case carries meaning.
+#   lowercase -> a std.ui *primitive element*, exactly this set (also in
+#                `checks.BUILTINS`, which is how a bare lowercase element resolves);
+#   uppercase -> a *view*, either declared with `view` here / imported, or one of
+#                the std.ui-provided views listed below.
+_UI_PRIMITIVES = {
+    "col", "row", "stack", "grid", "text", "img", "button", "input", "link",
+    "spacer", "status",
+}
+_UI_STD_VIEWS = {
+    "Spinner", "Avatar", "Icon", "Image", "Portal", "Fragment", "Divider",
+    "Skeleton", "Badge",
+}
+# Spec §11.3, exact: the compiler-owned `auth` client surface, eight calls.
+# Unlike `_STD_EXTRA` (names with no signature to check), the spec gives each of
+# these a parameter list, so an unknown method or a wrong argument here is a
+# definite mistake in a closed API, not a guess about an open one.
+#
+# This is *language* validity, deliberately not build-target support: every call
+# the spec defines belongs in this table even when a given target cannot emit it
+# yet. `vlcheck` says whether the program is written correctly; a target that
+# does not implement `verify_totp` or `start_oauth` still fails the build with
+# its own BuildError, which is where "unsupported here" is reported.
+#
+# Each entry is the parameter list in declaration order: (name, required).
+_AUTH_API = {
+    "sign_up":        (("email", True), ("password", True)),
+    "sign_in":        (("email", True), ("password", True)),
+    "sign_out":       (),
+    "start_oauth":    (("provider", True),),
+    "reset_password": (("email", True),),
+    "confirm_reset":  (("token", True), ("password", True)),
+    "confirm_verify": (("token", True),),
+    "verify_totp":    (("code", True),),
+}
+
+# member names that are methods, not record fields — never flag `x.<this>`
+_METHODS = {
+    "len", "format", "reload", "loading", "all", "first", "get", "where",
+    "order", "limit", "offset", "insert", "update", "delete", "count", "map",
+    "filter", "sort_by", "group_by", "take", "chunk", "join", "split", "trim",
+    "upper", "lower", "keys", "values", "contains", "has", "to_int", "to_str",
+    "to_float", "add", "sub", "abs", "min", "max", "round", "reverse", "unique",
+    "slice", "index_of", "starts_with", "ends_with", "replace", "parse", "raw",
+    "reload", "cancel", "retry", "emit", "close", "open", "send",
+}
+
+_KNOWN = (set(BUILTINS) | set(_PRIM_NAMES) | _STD_EXTRA | _CONTEXTUAL
+          | {"true", "false", "nil", "self", "_", "?"})
+
+
+class Sym:
+    __slots__ = ("kind", "params", "fields", "variants", "ret", "routes",
+                 "endpoints", "target")
+
+    def __init__(self, kind, *, params=None, fields=None, variants=None,
+                 ret=None, routes=None, endpoints=None, target=None):
+        self.kind = kind              # record union alias fn view service api variant endpoint route opaque
+        self.params = params          # [(name, has_default, is_optional)]
+        self.fields = fields          # {name: (base, is_list)}
+        self.variants = variants      # {vname: nargs}
+        self.ret = ret                # (base, is_list) | None
+        self.routes = routes          # {clientkey: [Sym(route), ...]}
+        self.endpoints = endpoints    # {name: Sym(endpoint)}
+        self.target = target          # alias target base name
+
+
+def _tref(t):
+    """A.TypeRef -> (base_name|None, is_list, is_optional)."""
+    if not isinstance(t, A.TypeRef):
+        return (None, False, False)
+    is_opt = bool(getattr(t, "optional", False))
+    if t.name == "list" and getattr(t, "args", None):
+        inner = t.args[0]
+        return (getattr(inner, "name", None), True, is_opt)
+    return (t.name or None, False, is_opt)
+
+
+def _params(plist):
+    out = []
+    for p in plist or []:
+        _b, _l, opt = _tref(getattr(p, "type", None))
+        out.append((p.name, getattr(p, "default", None) is not None, opt))
+    return out
+
+
+def _fields(flist):
+    out = {}
+    for f in flist or []:
+        b, is_list, _o = _tref(getattr(f, "type", None))
+        out[f.name] = (b, is_list)
+    return out
+
+
+def _singularise(seg: str) -> str:
+    """Spec §10: strip a trailing `es` after s/x/z/ch/sh, then a trailing `s`;
+    a name neither rule changes gets the suffix `_item`."""
+    for pre in ("s", "x", "z", "ch", "sh"):
+        if seg.endswith(pre + "es"):
+            return seg[:-2]
+    if len(seg) > 1 and seg.endswith("s"):
+        return seg[:-1]
+    return seg + "_item"
+
+
+def _route_name(method: str, path: str, alias: str | None = None) -> str:
+    """The generated client name for a route (spec §10, method-aware). One name
+    per route; a duplicate across a service is R-ROUTE-DUP."""
+    if alias:
+        return alias
+    segs = [s for s in path.split("/") if s]
+    bare = [s for s in segs if not s.startswith(":")]
+    seg = bare[-1] if bare else "root"
+    has_params = any(s.startswith(":") for s in segs)
+    ends_in_param = bool(segs) and segs[-1].startswith(":")
+
+    if has_params and not ends_in_param:          # action: /posts/:id/publish
+        return seg
+    sing = _singularise(seg)
+    if ends_in_param:                             # item: /posts/:id
+        return {"post": "create_" + sing, "put": "update_" + sing,
+                "patch": "update_" + sing, "delete": "delete_" + sing}.get(method, sing)
+    # collection: /posts  (get keeps the plural as written)
+    return {"post": "create_" + sing, "put": "update_" + sing,
+            "patch": "update_" + sing, "delete": "delete_" + sing}.get(method, seg)
+
+
+def _route_path_params(path: str):
+    """Path params become required named params, in path order (spec §10)."""
+    return [(s[1:], False, False) for s in path.split("/") if s.startswith(":")]
+
+
+def _iter_directives(items):
+    for d in items or []:
+        if isinstance(d, A.Directive):
+            yield d
+            yield from _iter_directives(getattr(d, "body", None))
+
+
+def _collect_module(path: str, loading: set[str]) -> dict[str, Sym]:
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            src = fh.read()
+    except OSError:
+        return {}
+    toks = Lexer(src, path).lex()
+    mod = Parser(toks, src, path).parse_module()
+    r = Resolver(path, LineIndex(src), _loading=loading, emit=False)
+    r._build_table(mod)
+    return r.table
+
+
+class Resolver:
+    def __init__(self, filename: str, li: LineIndex, _loading=None, emit=True):
+        self.filename = filename
+        self.li = li
+        self.emit = emit
+        self._loading = set(_loading or ()) | {os.path.abspath(filename)}
+        self.table: dict[str, Sym] = {}
+        self.diags: list[Diagnostic] = []
+        # E-VIEW-MODULE-FN: a view (or a closure / handler inside one) may not
+        # call a module-level `fn` -- `vlbuild` does not lower one into view
+        # code. Tracked here so the check reuses this walker's lexical scope.
+        self._in_view = False
+        self._view_name = ""
+        self._vmf_seen: set[str] = set()
+
+    # ------------------------------------------------------------------ api
+    def run(self, mod: A.Module) -> list[Diagnostic]:
+        self._build_table(mod)
+        self._walk_module(mod)
+        return self.diags
+
+    def _d(self, code, msg, node, fix=None):
+        if not self.emit:
+            return
+        s = getattr(node, "start", 0)
+        e = getattr(node, "end", s + 1)
+        self.diags.append(Diagnostic(code, Severity.ERROR, msg, s, max(e, s + 1),
+                                     fix, self.filename))
+
+    # ------------------------------------------------------------- symbol table
+    def _build_table(self, mod: A.Module) -> None:
+        for it in mod.items:
+            if isinstance(it, A.Use):
+                self._load_use(it)
+            elif isinstance(it, A.TypeDecl):
+                self._add_typedecl(it)
+            elif isinstance(it, A.ModelDecl):
+                self.table[it.name] = Sym("record", fields=_fields(it.fields))
+            elif isinstance(it, A.FnDecl):
+                self.table[it.name] = Sym("fn", params=_params(it.params),
+                                          ret=_tref(it.ret)[:2])
+            elif isinstance(it, A.ViewDecl):
+                self.table[it.name] = Sym("view", params=_params(it.params))
+            elif isinstance(it, A.ServiceDecl):
+                routes: dict[str, Sym] = {}
+                seen: dict[str, A.Route] = {}
+                for r in it.routes:
+                    name = _route_name(r.method, r.path, getattr(r, "alias", None))
+                    rs = Sym("route",
+                             params=_route_path_params(r.path) + _params(r.params),
+                             ret=_tref(r.ret)[:2])
+                    if name in seen:
+                        prev = seen[name]
+                        self._d("R-ROUTE-DUP",
+                                f"routes '{prev.method} {prev.path}' and "
+                                f"'{r.method} {r.path}' both generate client name '{name}'",
+                                r, "disambiguate one route with 'as <name>'")
+                    else:
+                        seen[name] = r
+                        routes[name] = rs
+                self.table[it.name] = Sym("service", routes=routes)
+            elif isinstance(it, A.ApiDecl):
+                eps = {ep.name: Sym("endpoint", params=_params(ep.params),
+                                    ret=_tref(ep.ret)[:2]) for ep in it.endpoints}
+                self.table[it.name] = Sym("api", endpoints=eps)
+            elif isinstance(it, A.AuthDecl):
+                for d in _iter_directives(it.settings):
+                    if d.head == "provider":
+                        for tok in d.tokens:
+                            if tok and tok.isidentifier():
+                                self.table.setdefault(tok, Sym("opaque"))
+
+    def _add_typedecl(self, it: A.TypeDecl) -> None:
+        if it.kind == "record":
+            self.table[it.name] = Sym("record", fields=_fields(it.fields))
+        elif it.kind == "union":
+            variants = {}
+            for v in it.variants:
+                vparams = getattr(v, "params", []) or []
+                variants[v.name] = len(vparams)
+                self.table[v.name] = Sym("variant", params=_params(vparams),
+                                         ret=(it.name, False))
+            self.table[it.name] = Sym("union", variants=variants)
+        elif it.kind == "alias":
+            self.table[it.name] = Sym("alias", target=_tref(it.alias_of)[0])
+
+    def _load_use(self, it: A.Use) -> None:
+        path, names = it.path, list(it.names or [])
+
+        def opaque_all():
+            for n in names:
+                self.table.setdefault(n, Sym("opaque"))
+
+        if path.startswith("std."):
+            opaque_all()
+            self.table.setdefault(path.split(".")[-1], Sym("opaque"))
+            return
+        if not (path.startswith("./") or path.startswith("../")):
+            opaque_all()
+            self.table.setdefault(path.split("/")[-1], Sym("opaque"))
+            return
+
+        base = os.path.normpath(os.path.join(os.path.dirname(self.filename), path))
+        mod_name = os.path.basename(base).split(".")[0]
+        target = next((c for c in (base + ".vl", os.path.join(base, "index.vl"), base)
+                       if os.path.isfile(c)), None)
+
+        # A project-relative import (./ ../) MUST resolve. Silently degrading to
+        # opaque here is a false-pass channel: it disables every field / arity /
+        # exhaustiveness check for the "imported" symbols. `std.*` and bare
+        # dependency names still degrade opaque above — those are genuinely
+        # external (an explicit dependency manifest is a v0.3 item).
+        fault = None
+        if target is None:
+            fault = ("R-USE", f"cannot resolve import '{path}': no file at '{base}.vl'",
+                     "check the path — './' and '../' are relative to this file")
+        elif os.path.abspath(target) in self._loading:
+            fault = ("R-USE-CYCLE", f"circular import: '{path}'",
+                     "move the shared declarations into a third file both can import")
+        elif len(self._loading) > 16:
+            fault = ("R-USE-DEPTH", f"import chain deeper than 16 files at '{path}'",
+                     "flatten the module graph")
+        if fault is not None:
+            self._d(fault[0], fault[1], it, fault[2])
+            opaque_all()
+            self.table.setdefault(mod_name, Sym("opaque"))
+            return
+
+        imported = _collect_module(target, self._loading)
+        take = names or list(imported.keys())
+        for n in take:
+            s = imported.get(n)
+            if s is None:
+                if names:
+                    self._d("R-IMPORT", f"'{n}' is not declared in '{path}'", it,
+                            "check the name or the imported file")
+                    self.table.setdefault(n, Sym("opaque"))
+                continue
+            self.table[n] = s
+            if s.kind == "union" and s.variants:
+                for vn in s.variants:
+                    self.table.setdefault(
+                        vn, imported.get(vn, Sym("variant", ret=(n, False))))
+        self.table.setdefault(os.path.basename(base).split(".")[0], Sym("opaque"))
+
+    # ------------------------------------------------------------------- walk
+    def _walk_module(self, mod: A.Module) -> None:
+        for it in mod.items:
+            if isinstance(it, A.FnDecl):
+                sc = {p.name: _tref(p.type)[:2] for p in it.params}
+                self._scoped(it.body, [sc])
+            elif isinstance(it, A.ViewDecl):
+                sc = {p.name: _tref(p.type)[:2] for p in it.params}
+                sc["session"] = None
+                for s in it.body:
+                    if isinstance(s, A.StateDecl):
+                        sc[s.name] = (_tref(s.type)[:2] if s.type
+                                      else self._typeof(s.init, [sc]))
+                    elif isinstance(s, A.DeriveDecl):
+                        sc[s.name] = None
+                    elif isinstance(s, A.LoadDecl):
+                        sc[s.name] = self._load_type(s, [sc])
+                self._in_view = True
+                self._view_name = it.name
+                self._vmf_seen = set()
+                self._scoped(it.body, [sc])
+                self._in_view = False
+            elif isinstance(it, A.ServiceDecl):
+                for r in it.routes:
+                    sc = {p.name: _tref(p.type)[:2] for p in r.params}
+                    sc["session"] = None
+                    for seg in r.path.split("/"):
+                        if seg.startswith(":"):
+                            sc[seg[1:]] = None
+                    self._scoped(r.body, [sc])
+
+    def _load_type(self, s: A.LoadDecl, scopes):
+        if isinstance(s.expr, A.Call):
+            sym = self._client_sym(s.expr.callee)
+            if sym is not None and sym.ret:
+                return sym.ret
+        return None
+
+    # -------------------------------------------------------------- statements
+    def _scoped(self, stmts, scopes):
+        for st in stmts or []:
+            self._stmt(st, scopes)
+
+    def _block(self, stmts, scopes):
+        self._scoped(stmts, scopes + [{}])
+
+    def _declare(self, name, ti, scopes):
+        if name and name != "?":
+            scopes[-1][name] = ti
+
+    def _stmt(self, st, scopes):
+        if st is None:
+            return
+        if isinstance(st, A.Let):
+            self._expr(st.init, scopes)
+            ti = _tref(st.type)[:2] if st.type else self._typeof(st.init, scopes)
+            self._declare(st.name, ti, scopes)
+        elif isinstance(st, A.Assign):
+            self._expr(st.target, scopes)
+            self._expr(st.value, scopes)
+        elif isinstance(st, A.ExprStmt):
+            self._expr(st.expr, scopes)
+        elif isinstance(st, A.Return):
+            self._expr(st.value, scopes)
+        elif isinstance(st, A.If):
+            self._expr(st.cond, scopes)
+            self._block(st.then, scopes)
+            for c, b in st.elifs:
+                self._expr(c, scopes)
+                self._block(b, scopes)
+            self._block(st.orelse, scopes)
+        elif isinstance(st, (A.Match, A.MatchExpr)):
+            self._expr(st.subject, scopes)
+            self._check_match(st.subject, st.arms, st, scopes)
+            for pat, guard, body in st.arms:
+                inner = scopes + [{b: None for b in getattr(pat, "binds", [])}]
+                if guard is not None:
+                    self._expr(guard, inner)
+                self._scoped(body, inner)
+        elif isinstance(st, A.For):
+            self._expr(st.iter, scopes)
+            it_ti = self._typeof(st.iter, scopes)
+            elem = (it_ti[0], False) if it_ti and it_ti[1] else None
+            inner = scopes + [{v: elem for v in st.vars}]
+            self._scoped(st.body, inner)
+        elif isinstance(st, A.While):
+            self._expr(st.cond, scopes)
+            self._block(st.body, scopes)
+        elif isinstance(st, A.Par):
+            self._block(st.lets, scopes)
+        elif isinstance(st, A.Spawn):
+            self._block(st.body, scopes)
+        elif isinstance(st, A.Try):
+            self._expr(st.expr, scopes)
+            for pat, body in st.catches:
+                inner = scopes + [{b: None for b in getattr(pat, "binds", [])}]
+                self._scoped(body, inner)
+        elif isinstance(st, (A.Break, A.Skip)):
+            pass
+        elif isinstance(st, A.StateDecl):
+            self._expr(st.init, scopes)
+        elif isinstance(st, A.DeriveDecl):
+            self._expr(st.expr, scopes)
+        elif isinstance(st, A.LoadDecl):
+            self._expr(st.expr, scopes)
+            self._scoped(st.pending, scopes)
+            inner = scopes + [{st.error_name: None}] if st.error_name else scopes
+            self._scoped(st.error_body, inner)
+        elif isinstance(st, A.OnBlock):
+            self._scoped(st.body, scopes + [{a: None for a in st.args}])
+        elif isinstance(st, A.ListBlock):
+            self._expr(st.src, scopes)
+            src_ti = self._typeof(st.src, scopes)
+            elem = (src_ti[0], False) if src_ti and src_ti[1] else None
+            inner = scopes + [{st.var: elem}]
+            if st.key is not None:
+                self._expr(st.key, inner)
+            self._scoped(st.body, inner)
+        elif isinstance(st, A.Element):
+            self._element(st, scopes)
+        else:
+            for node in _walk_names(st):
+                self._use(node, scopes)
+
+    def _element(self, st: A.Element, scopes):
+        name = st.name
+        sym = self.table.get(name)
+        # §3.4: uppercase element = a view. It must be declared / imported, or one
+        # of the std.ui-provided views. Lowercase elements are primitives and
+        # resolve through checks.BUILTINS.
+        if name[:1].isupper() and name not in _UI_STD_VIEWS and sym is None:
+            self._d("R-UNDEF", f"component '{name}' is not defined", st,
+                    "declare a view with this name, or check the spelling")
+        if sym is not None and sym.kind == "view" and sym.params is not None:
+            given = {k for k, _ in st.attrs}
+            for pn, has_def, is_opt in sym.params:
+                if not has_def and not is_opt and pn not in given:
+                    self._d("R-MISSING-ARG",
+                            f"component '{name}' is missing required prop '{pn}'",
+                            st, f"add {pn}:")
+        for a in st.args:
+            self._expr(a, scopes)
+        for _k, v in st.attrs:
+            if not isinstance(v, A.Name):        # bare-name attr values are tokens
+                self._expr(v, scopes)
+        self._scoped(st.body, scopes)
+
+    # -------------------------------------------------------------- expressions
+    def _expr(self, ex, scopes):
+        if ex is None:
+            return
+        if isinstance(ex, A.Name):
+            self._use(ex, scopes)
+        elif isinstance(ex, A.Literal):
+            for n in getattr(ex, "interp_names", []):
+                if not self._resolves(n, scopes):
+                    self._d("R-UNDEF",
+                            f"'{n}' in string interpolation is not defined", ex,
+                            "check the name, or add the binding / import")
+        elif isinstance(ex, A.Member):
+            self._expr(ex.obj, scopes)
+            self._check_field(ex, scopes)
+        elif isinstance(ex, A.Index):
+            self._expr(ex.obj, scopes)
+            self._expr(ex.index, scopes)
+        elif isinstance(ex, A.Call):
+            self._expr(ex.callee, scopes)
+            for a in ex.args:
+                self._expr(a, scopes)
+            for _k, v in ex.named:
+                self._expr(v, scopes)
+            self._check_call(ex, scopes)
+            self._check_view_module_fn(ex, scopes)
+        elif isinstance(ex, A.Unary):
+            self._expr(ex.operand, scopes)
+        elif isinstance(ex, A.Binary):
+            self._expr(ex.left, scopes)
+            self._expr(ex.right, scopes)
+        elif isinstance(ex, A.Range):
+            self._expr(ex.lo, scopes)
+            self._expr(ex.hi, scopes)
+        elif isinstance(ex, A.TryOp):
+            self._expr(ex.operand, scopes)
+        elif isinstance(ex, A.IfExpr):
+            self._expr(ex.cond, scopes)
+            self._expr(ex.then, scopes)
+            self._expr(ex.orelse, scopes)
+        elif isinstance(ex, A.MatchExpr):
+            self._expr(ex.subject, scopes)
+            self._check_match(ex.subject, ex.arms, ex, scopes)
+            for pat, guard, body in ex.arms:
+                inner = scopes + [{b: None for b in getattr(pat, "binds", [])}]
+                if guard is not None:
+                    self._expr(guard, inner)
+                self._scoped(body, inner)
+        elif isinstance(ex, A.Closure):
+            inner = scopes + [{p.name: _tref(p.type)[:2] for p in ex.params}]
+            if isinstance(ex.body, list):
+                self._scoped(ex.body, inner)
+            else:
+                self._expr(ex.body, inner)
+        elif isinstance(ex, A.ListLit):
+            for x in ex.items:
+                self._expr(x, scopes)
+        elif isinstance(ex, A.RecordLit):
+            self._check_record_lit(ex, scopes)
+            for _k, v in ex.fields:
+                self._expr(v, scopes)
+
+    def _use(self, node: A.Name, scopes):
+        n = node.id
+        if not n or n in ("_", "?"):
+            return
+        if self._resolves(n, scopes):
+            return
+        self._d("R-UNDEF", f"'{n}' is not defined", node,
+                "check the name, or add a binding / declaration / import")
+
+    def _resolves(self, name, scopes) -> bool:
+        if name in _KNOWN or name in self.table:
+            return True
+        return any(name in sc for sc in scopes)
+
+    # --------------------------------------------------------------- type-of
+    def _typeof(self, ex, scopes):
+        if isinstance(ex, A.Name):
+            for sc in reversed(scopes):
+                if ex.id in sc:
+                    return sc[ex.id]
+            return None
+        if isinstance(ex, A.RecordLit) and ex.type_name:
+            return (ex.type_name, False)
+        if isinstance(ex, A.TryOp):
+            return self._typeof(ex.operand, scopes)
+        if isinstance(ex, A.Member):
+            rec = self._record(self._typeof(ex.obj, scopes))
+            if rec and rec.fields and ex.name in rec.fields:
+                return rec.fields[ex.name]
+            return None
+        if isinstance(ex, A.Index):
+            ot = self._typeof(ex.obj, scopes)
+            return (ot[0], False) if ot and ot[1] else None
+        if isinstance(ex, A.Call):
+            if isinstance(ex.callee, A.Member) and isinstance(ex.callee.obj, A.Name) \
+                    and (ex.callee.obj.id == "api"
+                         or (self.table.get(ex.callee.obj.id) or Sym("x")).kind in ("service", "api")):
+                sym = self._client_sym(ex.callee)
+                return sym.ret if sym else None
+            if isinstance(ex.callee, A.Name):
+                s = self.table.get(ex.callee.id)
+                if s and s.kind in ("fn", "variant"):
+                    return s.ret
+        return None
+
+    def _record(self, ti):
+        if not ti or ti[1]:
+            return None
+        s = self.table.get(ti[0])
+        seen = 0
+        while s and s.kind == "alias" and s.target and seen < 8:
+            s = self.table.get(s.target)
+            seen += 1
+        return s if s and s.kind == "record" else None
+
+    # ------------------------------------------------------------------ checks
+    def _check_field(self, ex: A.Member, scopes):
+        rec = self._record(self._typeof(ex.obj, scopes))
+        if rec is None or not rec.fields:
+            return
+        if ex.name in rec.fields or ex.name in _METHODS:
+            return
+        obj_t = self._typeof(ex.obj, scopes)
+        self._d("R-FIELD",
+                f"type '{obj_t[0]}' has no field '{ex.name}'", ex,
+                f"fields: {', '.join(sorted(rec.fields)) or '(none)'}")
+
+    def _has_client(self) -> bool:
+        return any(s.kind in ("service", "api") for s in self.table.values())
+
+    def _client_sym(self, callee):
+        """`api.x` / `<svc>.x` -> the route/endpoint Sym, a params=None sentinel
+        when the client key is ambiguous, or None when nothing matches.
+
+        Returns None only when a service/api IS in scope but has no such route;
+        when none is in scope the caller must treat it as "defined elsewhere",
+        not as an error."""
+        if not (isinstance(callee, A.Member) and isinstance(callee.obj, A.Name)):
+            return None
+        ns, m = callee.obj.id, callee.name
+        cands = []
+        if ns == "api":
+            cands = list(self.table.values())
+        elif ns in self.table:
+            cands = [self.table[ns]]
+        for s in cands:
+            if s.kind == "service" and s.routes and m in s.routes:
+                return s.routes[m]
+            if s.kind == "api" and s.endpoints and m in s.endpoints:
+                return s.endpoints[m]
+        return None
+
+    def _auth_is_builtin(self, scopes) -> bool:
+        """True when a bare `auth` really is the §11.3 built-in.
+
+        Name resolution comes before the table: a local binding or a declared
+        module-level symbol called `auth` would shadow the built-in, and a
+        method call on *that* is an ordinary call this table knows nothing
+        about.
+
+        Today this guard cannot actually fire — `auth` is a hard keyword
+        (`lexer.KEYWORDS`), so it binds as nothing: not a `let`, not a
+        parameter, not a declaration name. It is kept deliberately, as the
+        one place that decides whether this table applies, so that relaxing
+        `auth` to a soft keyword later changes the answer here instead of
+        silently mis-attributing someone else's method call to the auth API."""
+        if any("auth" in sc for sc in scopes):
+            return False
+        return "auth" not in self.table
+
+    def _check_auth_call(self, ex: A.Call, scopes) -> None:
+        m = ex.callee.name
+        if not self._auth_is_builtin(scopes):
+            return
+        params = _AUTH_API.get(m)
+        if params is None:
+            self._d("R-AUTH-METHOD",
+                    f"'auth.{m}' is not part of the auth API", ex,
+                    "the §11.3 calls are: "
+                    + ", ".join(sorted(_AUTH_API)))
+            return
+        # Reuse the ordinary signature check: positional overflow, unknown
+        # named argument, and missing required argument all report the same way
+        # they do for a fn or a route.
+        self._arity(Sym("fn", params=[(n, False, not req) for n, req in params]),
+                    ex, f"'auth.{m}'")
+
+    def _check_view_module_fn(self, ex: A.Call, scopes) -> None:
+        """A view -- or a closure / `on` handler / block inside one -- that
+        calls a module-level `fn` resolves fine, then `vlbuild` refuses it:
+        module-level functions are not lowered into view code, so the emitted
+        call is a runtime `ReferenceError` (`emit.py`'s `precheck` is the
+        fail-closed backstop). Flag the call here so the common
+        view-calls-a-`fn` case fails at `volaro check`, not only at build.
+        Uses this walker's own lexical `scopes`, so a `let` / `list` var /
+        loop var / closure param / handler arg / `catch` bind shadows the
+        `fn` exactly where it is really in scope -- and only there.
+
+        Residual (parked, owner-gated -- RELEASE-CHECKLIST.md 3b): a
+        module-level `fn` merely *declared* in a file that has a view is still
+        `check`-clean, yet `emit.py` `precheck` rejects any module-level `fn`
+        for the view target regardless of calls, so that file builds red. The
+        `view_module_fn*_ok.vl` fixtures isolate this checker -- check-clean by
+        design, not buildable."""
+        if not self._in_view or not isinstance(ex.callee, A.Name):
+            return
+        n = ex.callee.id
+        if not n or n in ("_", "?") or n in self._vmf_seen:
+            return
+        if any(n in sc for sc in scopes):        # a local binding shadows it
+            return
+        sym = self.table.get(n)
+        if not sym or sym.kind != "fn":
+            return
+        self._vmf_seen.add(n)
+        self._d("E-VIEW-MODULE-FN",
+                f"view '{self._view_name}' calls module-level fn '{n}' -- "
+                f"vlbuild does not lower a module-level `fn` into view code, so "
+                f"the emitted call throws ReferenceError at runtime. Inline "
+                f"{n}'s body at the call site (write the expression directly); "
+                f"a view has no shared helper function yet, so logic used by "
+                f"more than one `derive` / `on` handler is repeated in each.",
+                ex,
+                f"inline {n}'s body here; repeat it in each derive / handler "
+                f"that needs it")
+
+    def _check_call(self, ex: A.Call, scopes):
+        callee = ex.callee
+        if isinstance(callee, A.Member) and isinstance(callee.obj, A.Name):
+            ns = callee.obj.id
+            if ns == "auth":
+                self._check_auth_call(ex, scopes)
+                return
+            nssym = self.table.get(ns)
+            if ns == "api" or (nssym and nssym.kind in ("service", "api")):
+                if not self._has_client():
+                    return          # client for a service defined in another file
+                sym = self._client_sym(callee)
+                if sym is None:
+                    self._d("R-ROUTE",
+                            f"no route or endpoint '{callee.name}' on '{ns}'", ex,
+                            "check the route path or endpoint name")
+                    return
+                self._arity(sym, ex, f"'{ns}.{callee.name}'")
+            return
+        if isinstance(callee, A.Name):
+            sym = self.table.get(callee.id)
+            if sym and sym.kind in ("fn", "view", "variant"):
+                self._arity(sym, ex, f"'{callee.id}'")
+
+    def _arity(self, sym: Sym, ex: A.Call, label: str):
+        params = sym.params
+        if params is None:
+            return
+        pnames = [p[0] for p in params]
+        npos = len(ex.args)
+        if npos > len(params):
+            self._d("R-ARITY",
+                    f"{label} takes {len(params)} argument(s), got {npos} positional",
+                    ex, "remove the extra argument(s)")
+            return
+        for k, _v in ex.named:
+            if k not in pnames:
+                self._d("R-NAMED-ARG",
+                        f"{label} has no parameter named '{k}'", ex,
+                        f"parameters: {', '.join(pnames) or '(none)'}")
+        filled = set(pnames[:npos]) | {k for k, _v in ex.named}
+        for pn, has_def, is_opt in params:
+            if not has_def and not is_opt and pn not in filled:
+                self._d("R-MISSING-ARG",
+                        f"{label} is missing required argument '{pn}'", ex,
+                        f"pass {pn}:")
+
+    def _check_record_lit(self, ex: A.RecordLit, scopes):
+        if not ex.type_name:
+            return
+        if ex.type_name == "Err":
+            return          # illegal, but checks.py owns that (E-ERR-LITERAL)
+        s = self.table.get(ex.type_name)
+        if s is None:
+            self._d("R-UNDEF", f"type '{ex.type_name}' is not defined", ex,
+                    "declare the record / model, or import it")
+            return
+        if s.kind != "record" or s.fields is None:
+            return
+        for k, _v in ex.fields:
+            if k is not None and k not in s.fields:
+                self._d("R-FIELD",
+                        f"'{ex.type_name}' has no field '{k}'", ex,
+                        f"fields: {', '.join(sorted(s.fields)) or '(none)'}")
+
+    def _check_match(self, subject, arms, node, scopes):
+        ti = self._typeof(subject, scopes)
+        if not ti or ti[1]:
+            return
+        s = self.table.get(ti[0])
+        seen = 0
+        while s and s.kind == "alias" and s.target and seen < 8:
+            s = self.table.get(s.target)
+            seen += 1
+        if not s or s.kind != "union" or not s.variants:
+            return
+        heads = []
+        for arm in arms:
+            pat, guard = arm[0], arm[1]
+            if guard is not None:
+                continue
+            h = getattr(pat, "head", "")
+            binds = getattr(pat, "binds", [])
+            if h == "_":
+                return
+            if h and h not in s.variants and binds == [h]:
+                return                       # bare-name binding = catch-all
+            heads.append(h)
+        missing = [v for v in s.variants if v not in set(heads)]
+        if missing:
+            self._d("R-MATCH",
+                    f"match on '{ti[0]}' is not exhaustive; missing: {', '.join(missing)}",
+                    node, "add the missing arms, or a '_' catch-all")
+
+
+def _walk_names(node):
+    """Yield A.Name nodes anywhere under an unrecognised statement shape."""
+    if node is None or isinstance(node, (str, int, float, bool)):
+        return
+    if isinstance(node, (list, tuple)):
+        for x in node:
+            yield from _walk_names(x)
+        return
+    if isinstance(node, A.Name):
+        yield node
+        return
+    if not hasattr(node, "__dataclass_fields__"):
+        return
+    for f in node.__dataclass_fields__:
+        if f in ("start", "end"):
+            continue
+        yield from _walk_names(getattr(node, f))
+
+
+def resolve(mod: A.Module, filename: str, li: LineIndex) -> list[Diagnostic]:
+    return Resolver(filename, li).run(mod)