volaro 0.1.0-alpha.13 → 0.1.0-alpha.14

package/README.md

@@ -1,6 +1,6 @@
 # Volaro
 
-**Limited alpha** (this is `0.1.0-alpha.13`), published under both the
+**Limited alpha** (this is `0.1.0-alpha.14`), published under both the
 `latest` and `alpha` dist-tags: `npm install volaro`.
 
 Volaro is an experimental application language intended for AI authoring and

package/compiler/SOURCE_INFO.json

@@ -1,6 +1,6 @@
 {
-  "revision": "d6e19b4e656bee01bf90048117fb24b598abdf3b",
+  "revision": "e01dc1d92881e38143a73b21dfdf0660cb515906",
   "source": "git",
   "dirty": false,
-  "content_sha256": "64c762006f1fceda3601d6c6b3a6de4ba99590d93aa14d04a749f318a840aa17"
+  "content_sha256": "6476761bc8a3508734fee9684b80e0efe0ae151a6a40b5f5586bf1595e3a960d"
 }

package/compiler/SOURCE_REV

@@ -1 +1 @@
-d6e19b4e656bee01bf90048117fb24b598abdf3b
+e01dc1d92881e38143a73b21dfdf0660cb515906

package/compiler/validator/vlcheck/checks.py

@@ -255,11 +255,14 @@ AUTH_ERROR_CODES = frozenset({
     "provider_error", "invalid_token", "expired_token", "invalid_code",
     "no_totp_enrolled",
 })
-# A route body's `catch <head>` tests the thrown error's code when <head> is
-# one of these (or a declared union variant); any other head binds the
-# caught error itself (`catch e`). resolve.py and vlbuild's `_route_try`
-# both read this set, so `err(e)` means the same thing to check and build.
-ROUTE_CATCH_CODES = (_ERROR_CODES | AUTH_ERROR_CODES
+# `catch <head>` tests the thrown error's code when <head> is one of these
+# (or a declared union variant), in a route body and in a view handler
+# alike; any other head binds the caught error itself (`catch e`). The code
+# matches when it equals <head> or starts with "<head>." (`catch decode`
+# catches `decode.missing_field`). resolve.py, the W-CATCH-NO-FALLBACK
+# check and vlbuild's `_route_try` / `_handler_try` all read this set, so a
+# catch arm means the same thing to check and build, client and server.
+CATCH_CODES = (_ERROR_CODES | AUTH_ERROR_CODES
                      | frozenset({"bad_request", "unauthorized"}))
 _ERR_ROUTE_FIX = ("`return err(not_found(\"...\"))` in a `service` or "
                   "page.server route body; a view reports a failure by "
@@ -414,6 +417,28 @@ def _walk(node):
         yield from _walk(getattr(node, f))
 
 
+def _h1_path(nodes) -> list:
+    """The `h1` elements one render of `nodes` can show together, in source
+    order: siblings add up, while the branches of an `if` / `match` are
+    alternatives, so only the branch with the most `h1`s counts. Anything
+    else is searched whole, as before (a `list` body counts once)."""
+    out: list = []
+    for n in nodes or ():
+        if isinstance(n, A.Element):
+            out += ([n] if n.name == "h1" else []) + _h1_path(n.body)
+        elif isinstance(n, A.If):
+            branches = ([n.then] + [body for _c, body in n.elifs]
+                        + [n.orelse])
+            out += max((_h1_path(b) for b in branches), key=len)
+        elif isinstance(n, A.Match):
+            out += max((_h1_path(arm[-1]) for arm in n.arms),
+                       key=len, default=[])
+        else:
+            out += [x for x in _walk(n)
+                    if isinstance(x, A.Element) and x.name == "h1"]
+    return out
+
+
 def _rendered_children(el):
     """Yield the element children `el` actually renders, in source order.
 
@@ -2398,7 +2423,6 @@ class Checker:
             if not isinstance(it, A.ViewDecl):
                 continue
             prev = 0
-            first_h1 = None
             navs: list = []
             mains: list = []
             # action-45.3: `aside` (role=complementary) has the same problem
@@ -2416,14 +2440,6 @@ class Checker:
                                 "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)
@@ -2432,6 +2448,14 @@ class Checker:
                     mains.append(node)
                 elif node.name in landmarks:
                     landmarks[node.name].append(node)
+            # Branches of an `if` / `match` render one at a time, so a view
+            # with `h1 "Not found"` in one branch and `h1 found.title` in
+            # the other renders one `h1`: count the branch with the most.
+            for node in _h1_path(it.body)[1:]:
+                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`")
             for lname, nodes in landmarks.items():
                 if lname == "nav" or len(nodes) < 2:
                     continue  # `nav` keeps its own E-NAV-NAME below
@@ -3530,6 +3554,19 @@ class Checker:
                     "'?' inside 'try' is redundant -- the catch arms below "
                     "already handle the error, so nothing is propagated", t.expr,
                     "remove the trailing '?'")
+        heads = [getattr(pat, "head", "") for pat, _body in t.catches]
+        if (self._ctx == "view" and heads
+                and all(h in CATCH_CODES or h in self._variants for h in heads)):
+            # Every arm names a code, so any other error is rethrown out of
+            # the handler. Through 0.1.0-alpha.13 a view handler's
+            # `catch not_found` caught every error; code written against
+            # that now lets the others through. A warning, not an error:
+            # rethrowing can be what the author wants.
+            self._d("W-CATCH-NO-FALLBACK", Severity.WARNING,
+                    "every `catch` arm here names an error code, so any other "
+                    "error (a 500, a network failure) is rethrown out of the "
+                    "handler", t,
+                    "add a final `catch e` arm to handle the rest")
         self._expr(t.expr, scopes, fallible)
         for pat, body in t.catches:
             inner = scopes + [_Scope(getattr(pat, "binds", []), "catch binding")]

package/compiler/validator/vlcheck/resolve.py

@@ -50,7 +50,7 @@ import os
 import re
 
 from . import ast_nodes as A
-from .checks import (BUILTINS, CONTEXTUAL_WORDS, ROUTE_CATCH_CODES,
+from .checks import (BUILTINS, CONTEXTUAL_WORDS, CATCH_CODES,
                      STD_BUILT_FNS, _ERROR_CODES, _FN_NOT_BUILT, _PRIM_NAMES)
 from .diagnostics import Diagnostic, LineIndex, Severity
 from .elements import ELEMENT_NAMES
@@ -1057,7 +1057,7 @@ class Resolver:
         head = getattr(pat, "head", "")
         binds = list(getattr(pat, "binds", []) or [])
         sym = self.table.get(head)
-        if (head == "_" or head in ROUTE_CATCH_CODES
+        if (head == "_" or head in CATCH_CODES
                 or (sym is not None and sym.kind == "variant")
                 or binds != [head]):
             return {b: None for b in binds}

package/compiler/vlbuild/vlbuild/emit.py

@@ -59,7 +59,7 @@ from vlcheck.elements import (
     SPELLCHECK_HOMES, TABINDEX_ALLOWED, TEXT_STYLE_ATTRS,
     UNSAFE_ELEMENTS,
 )
-from vlcheck.checks import (AUTH_ERROR_CODES, ROUTE_CATCH_CODES, STD_BUILT_FNS,
+from vlcheck.checks import (CATCH_CODES, STD_BUILT_FNS,
                             _ERROR_CODES, _lit_int, _lit_text,
                             _rendered_children)
 from vlcheck.lexer import Lexer
@@ -171,7 +171,16 @@ WHERE_PREDICATES = {
     "contains": 1,
 }
 
-_AUTH_ERROR_CODES = AUTH_ERROR_CODES
+
+
+def _catch_code_test(head: str) -> str:
+    """The JS condition a `catch <code>` arm tests (spec section 6.2), in a
+    view handler and a route body alike: the caught error's `code` is
+    `head` or starts with `head.`, so `catch decode` also catches the
+    runtime's `decode.missing_field`."""
+    return ('_vlErr && typeof _vlErr.code === "string" && (_vlErr.code === %s'
+            ' || _vlErr.code.indexOf(%s) === 0)'
+            % (json.dumps(head), json.dumps(head + ".")))
 
 
 def _where_predicate_call(v):
@@ -3167,16 +3176,27 @@ class Emitter:
             return ["var %s = _vlErr;" % self._bind_local(binds[0])]
         return []
 
+    def _is_catch_code(self, head: str) -> bool:
+        """`catch <head>` tests the error's code (an error code, an auth
+        error code or a declared union variant); any other head (`catch
+        e`, `catch _`) catches every error. One rule for view handlers and
+        route bodies: `vlcheck.checks.CATCH_CODES`."""
+        return head in CATCH_CODES or head in self.variant_params
+
     def _handler_try(self, st: A.Try, in_loop: bool = False) -> str:
-        """Lower Volaro's non-fall-through handled errors (§6.2)."""
+        """Lower Volaro's non-fall-through handled errors (§6.2). An arm
+        headed by an error code runs for that code only (it was a
+        catch-all for every code but the auth ones and declared variants,
+        so `catch not_found` swallowed every error); an error no arm
+        matches is rethrown."""
         out = ["try { await %s; } catch (_vlErr) {" % self.expr(st.expr)]
         fallback = False
         for i, (pat, body) in enumerate(st.catches):
             head = getattr(pat, "head", "")
-            is_variant = head in _AUTH_ERROR_CODES or head in self.variant_params
+            is_variant = self._is_catch_code(head)
             if is_variant:
-                out.append("%s (_vlErr && _vlErr.code === %s) {" %
-                           ("if" if i == 0 else "else if", json.dumps(head)))
+                out.append("%s (%s) {" % ("if" if i == 0 else "else if",
+                                          _catch_code_test(head)))
             else:
                 out.append("{" if i == 0 else "else {")
                 fallback = True
@@ -3216,10 +3236,10 @@ class Emitter:
         fallback = False
         for i, (pat, body) in enumerate(try_node.catches):
             head = getattr(pat, "head", "")
-            is_variant = head in _AUTH_ERROR_CODES or head in self.variant_params
+            is_variant = self._is_catch_code(head)
             if is_variant:
-                out.append("%s (_vlErr && _vlErr.code === %s) {" %
-                           ("if" if i == 0 else "else if", json.dumps(head)))
+                out.append("%s (%s) {" % ("if" if i == 0 else "else if",
+                                          _catch_code_test(head)))
             else:
                 out.append("{" if i == 0 else "else {")
                 fallback = True
@@ -3629,11 +3649,11 @@ class Emitter:
         `catch e` / `return err(e)` example could not be built.
 
         - An arm headed by an error code (`catch not_found`), a declared
-          union variant or an auth error code runs when the thrown error has
-          that `code`, binding the variant's fields by name. Any other head
-          (`catch e`, `catch _`) catches every error and binds it to `e`;
-          arms after it are unreachable, as in a view handler. An error no
-          arm matches is rethrown.
+          union variant or an auth error code runs when the thrown error's
+          `code` is that head or starts with `head.`, binding the variant's
+          fields by name. Any other head (`catch e`, `catch _`) catches
+          every error and binds it to `e`; arms after it are unreachable,
+          as in a view handler. An error no arm matches is rethrown.
         - Statement form: a handled error does not fall through. The arm
           ends the route: its last expression statement is the route's
           value (like a route body's own last line); otherwise the route
@@ -3643,7 +3663,6 @@ class Emitter:
           the `let` then run as usual.
         - `err(e)` inside an arm rethrows the caught error unchanged
           (`_ex_ServerErr`)."""
-        codes = set(ROUTE_CATCH_CODES) | set(self.variant_params)
         call_js = self.expr(t.expr)
         out: list[str] = []
         target = None
@@ -3656,10 +3675,10 @@ class Emitter:
         fallback = False
         for i, (pat, body) in enumerate(t.catches):
             head = getattr(pat, "head", "")
-            is_code = head in codes
+            is_code = self._is_catch_code(head)
             if is_code:
-                out.append("%s (_vlErr && _vlErr.code === %s) {" %
-                           ("if" if i == 0 else "else if", json.dumps(head)))
+                out.append("%s (%s) {" % ("if" if i == 0 else "else if",
+                                          _catch_code_test(head)))
             else:
                 out.append("{" if i == 0 else "else {")
                 fallback = True

package/language/crib.md

@@ -49,6 +49,8 @@ run either way goes *before* the `try`; fire-and-forget uses `spawn`.
 try auth.sign_in(email: email, password: password)
 catch invalid_credentials
   error = "Wrong email or password."     # no `return` needed
+catch e
+  error = "Something went wrong."
 route.to("/")                            # reached only when nothing was caught
 ```
 `let v = try EXPR catch ...` above is different: it binds a value (whichever arm
@@ -59,6 +61,12 @@ fall-through bug this rule exists to prevent — put that logic in each `catch`
 arm (or in an `if`/`else` reading a flag the `catch` set, declared `let mut`)
 instead.
 
+`catch not_found` (an error code, an auth code like `invalid_credentials`, or a
+variant you declared) runs for that code only; `catch decode` also catches
+`decode.missing_field`. Any other name (`catch e`) or `catch _` catches
+everything, so it goes last. An error no arm matches is rethrown: in a view
+handler, end the arms with `catch e` or check warns `W-CATCH-NO-FALLBACK`.
+
 `if C then else E` is also an expression (`derive x = if ok "a" else "b"`):
 `else` **required**, **binary only** (nest for 3+: `if a X else (if b Y else Z)`),
 each branch **one simple expression**, and the whole `derive` on **one line**

package/language/spec.md

@@ -413,7 +413,9 @@ catch e
   return err(e)
 ```
 
-`?` requires the enclosing function to be fallible with a compatible error type. `??` takes a value of the success type. `try`/`catch` matches on the error union with the same exhaustiveness rules as `match`.
+`?` requires the enclosing function to be fallible with a compatible error type. `??` takes a value of the success type. `try`/`catch` matches on the error union with the same exhaustiveness rules as `match`; `volaro check` does not enforce them yet.
+
+A `catch` arm headed by an error code (`catch not_found`), an auth error code or a declared union variant runs when the error's `code` is that name or starts with that name and a dot, so `catch decode` also catches `decode.missing_field` (§9). Any other head (`catch e`, `catch _`) catches every error, and arms after it never run. An error no arm matches is rethrown, in a view handler and in a route body alike. In a view handler, a `try` whose arms all name codes is the warning `W-CATCH-NO-FALLBACK`, because a 500 or a network failure then leaves the handler: end it with `catch e` to handle the rest.
 
 **A handled error does not fall through.** When a `catch` arm runs, the statements after the `try` block do **not** execute — the `try` statement is complete. This is the opposite of the usual imperative reading and it is chosen deliberately: the fall-through version produced a login form that showed an error message *and* redirected to the success page, which was the single most common bug in early Volaro examples.
 
@@ -1063,7 +1065,7 @@ page title:"Weekly Report"
 
 `title:` is an expression evaluated at module scope (a literal, or something a module-level `fn` / config produces — not view state). It becomes the document `<title>` when it is a literal, and is assigned to `document.title` at boot regardless, so a full navigation to another page picks up that page's own title. `page` with no `title:`, or a statically empty one, is `E-PAGE-TITLE`; a build that renders a page with no `page` declaration at all is refused (`E-PAGE-TITLE` at build time). A `title:` expression that resolves to empty at load time raises `render.empty_page_title`. One `page` per module (`E-PAGE-DUP`).
 
-**Headings.** `h1`…`h6` are `std.ui` primitives that emit the real HTML heading elements. The level is **semantic and independent of visual size** — `h2 "…" size:28` is a second-level heading that happens to be large. Within one view, a heading that jumps more than one level below the previous one is `W-HEADING-SKIP`, and a second `h1` is `W-HEADING-MULTI-H1` — warnings, not errors, and scoped to a single view so a reusable component that legitimately starts at `h2` or `h3` under some page's `h1` is never flagged.
+**Headings.** `h1`…`h6` are `std.ui` primitives that emit the real HTML heading elements. The level is **semantic and independent of visual size** — `h2 "…" size:28` is a second-level heading that happens to be large. Within one view, a heading that jumps more than one level below the previous one is `W-HEADING-SKIP`, and a second `h1` the view can render at the same time is `W-HEADING-MULTI-H1` (one `h1` in each branch of an `if` is one `h1`) — warnings, not errors, and scoped to a single view so a reusable component that legitimately starts at `h2` or `h3` under some page's `h1` is never flagged.
 
 **Landmarks.** `main` and `nav` are `std.ui` primitives emitting `<main>` / `<nav>`. There is one `main` region per page (`E-MAIN-DUP` for two in a view). A `nav` takes `aria_label:` (emitted as `aria-label`); when a view has more than one `nav`, each **must** carry a distinct name (`E-NAV-NAME`) so assistive tech can tell them apart. These rules hold on the **composed** document, not just within one view: a `main` in the page-root view and in a view it renders (or a view whose `main` is reused) is `E-MAIN-COMPOSED` — every `main` emits `id="vl-main"`, so a second one is also a duplicate id and an ambiguous skip target; two `<nav>`s assistive tech cannot tell apart — both unnamed, or sharing one `aria_label:` — from different composed views are likewise `E-NAV-NAME`; and one static `id:` rendered by more than one element is `E-ID-DUP`. The composed pass follows component instantiation within a module from the page root and treats `if` / `else` branches as mutually exclusive (a landmark in both branches counts once); it does not evaluate conditions, and cross-file `use` composition is not yet followed.
 

package/language/supported.md

@@ -472,6 +472,13 @@ audio video source track picture map area
   prop or field (`on_retry()`) are not value methods and are unaffected.
 - `try call()?` is a warning (`W-TRY-PROPAGATE`): the `catch` arms already
   handle the error, so the `?` does nothing. Drop it.
+- `catch not_found` in a view handler (an error code, an auth error code
+  or a declared variant) runs for that code only, the same as in a route
+  body; `catch decode` also catches `decode.missing_field`. `catch e` /
+  `catch _` catches anything. An error no arm matches is rethrown. Through
+  0.1.0-alpha.13, `catch not_found` and the other standard codes caught
+  every error in a view handler. A handler `try` whose arms all name codes
+  is a warning (`W-CATCH-NO-FALLBACK`): add a final `catch e`.
 
 ### Data / services
 - `service` with `db.<model>` query builder (`where` / `order` / `limit` /
@@ -484,8 +491,9 @@ audio video source track picture map area
   value. Any other statement (`match` as a statement, `par`, `spawn`) fails
   the build, at any nesting depth. Use `?` to propagate errors.
 - `try`/`catch` in a route body, both forms. `catch not_found` (an error
-  code, or a variant of a union you declare) runs for that code only and
-  binds the variant's fields; `catch e` catches anything. An error no arm
+  code, or a variant of a union you declare) runs for that code (or a
+  `not_found.` code) only and binds the variant's fields; `catch e`
+  catches anything. An error no arm
   matches propagates. The bare statement form does not fall through: the
   arm ends the route, and its last expression is the route's value.
   `let x = try ...` gives `x` the arm's last expression and carries on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "volaro",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.14",
   "description": "Volaro \u2014 an application language written to be authored by an AI agent and read by a person. Ships the language reference and a working compiler for a supported subset (volaro check / build / dev). CLI: `volaro` (alias `vl`).",
   "repository": {
     "type": "git",