volaro 0.1.0-alpha.13 → 0.1.0-alpha.15

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.15`), 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": "336e0ce359237ddff36fa674c51b098bacb2a295",
   "source": "git",
   "dirty": false,
-  "content_sha256": "64c762006f1fceda3601d6c6b3a6de4ba99590d93aa14d04a749f318a840aa17"
+  "content_sha256": "588e82948fcb11b97bf14918badf69c335817fd8753f085c368bc6f1ded2f245"
 }

package/compiler/SOURCE_REV

@@ -1 +1 @@
-d6e19b4e656bee01bf90048117fb24b598abdf3b
+336e0ce359237ddff36fa674c51b098bacb2a295

package/compiler/validator/vlcheck/__main__.py

@@ -24,10 +24,12 @@ from .checks import check
 from .diagnostics import LineIndex, Severity
 from .lexer import Lexer
 from .parser import Parser
-from .resolve import resolve, resolve_page_server
+from .resolve import resolve, resolve_page_server, resolve_server_ctx
 from .project_config import load_config, ConfigError
 from .diagnostics import Diagnostic
 from .layoutcompose import check_all as check_project_composition
+from .pagemanifest import build_manifest as build_page_manifest
+from .pageroutes import build_manifest as build_route_manifest
 
 
 def _iter_paths(args: list[str]) -> list[str]:
@@ -69,19 +71,32 @@ def check_source(src: str, filename: str, strict_names: bool = False,
             resolver = resolve_page_server
         else:
             mod = parser.parse_server_ctx()
-            # A `_server.vl` holds only `context` providers; the resolver
-            # has no pass for them yet.
-            do_resolve = False
+            # A `_server.vl` holds only `context` providers. Their
+            # expressions resolve against what the build gives them: the
+            # project's app.vl, the ambient names, ancestor providers and
+            # earlier providers in the file (resolve.resolve_server_ctx).
+            resolver = resolve_server_ctx
     else:
         mod = parser.parse_module()
     diags = (list(lx.diags) + list(parser.diags)
              + check(mod, filename, li, strict_names=strict_names, release=release))
     if do_resolve:
         diags += resolver(mod, filename, li)
+        # An outbound call in a closure of server code is the server rule's
+        # E-API-SERVER-CLOSURE (the code the build gives it); the general
+        # E-ASYNC-CALL at the same call would say it twice.
+        server = {(d.start, d.end) for d in diags if d.code == "E-API-SERVER-CLOSURE"}
+        diags = [d for d in diags
+                 if not (d.code == "E-ASYNC-CALL" and (d.start, d.end) in server)]
     diags.sort(key=lambda d: (d.start, 0 if d.severity == Severity.ERROR else 1, d.code))
     return li, diags
 
 
+def _diag_key(d: Diagnostic) -> tuple:
+    return (os.path.normcase(os.path.abspath(d.file or "")), d.start, d.code,
+            d.message)
+
+
 def main(argv: list[str]) -> int:
     # Test-only hooks, same posture as vlbuild's VOLARO_TEST_BREACH_API
     # (server_emit.py): inert unless a test harness sets the env var,
@@ -128,9 +143,12 @@ def main(argv: list[str]) -> int:
     total_err = total_warn = 0
     json_rows: list[dict] = []
 
+    reported: set[tuple] = set()
+
     def report(li: LineIndex, diags: list[Diagnostic]) -> None:
         nonlocal total_err, total_warn
         for d in diags:
+            reported.add(_diag_key(d))
             if d.severity == Severity.ERROR:
                 total_err += 1
             elif d.severity == Severity.WARNING:
@@ -161,11 +179,18 @@ def main(argv: list[str]) -> int:
     # A project directory also gets the cross-file page checks (spec
     # §8.15: layout-chain landmarks, nav names, static ids, literal link
     # targets), the same ones the project build enforces.
+    # Route discovery comes first, as in the project build, which refuses
+    # to start on any of it: browser pages (E-PAGE-*,
+    # E-PROJECT-ENTRY-AMBIGUOUS) and page-server routes (R-PS-*, E-PS-*).
+    # Parse errors it repeats were reported with their file above.
     if do_resolve:
         for root in (a for a in args if os.path.isdir(os.path.join(a, "app"))):
             by_file: dict[str, list[Diagnostic]] = {}
-            for d in check_project_composition(root):
-                by_file.setdefault(d.file, []).append(d)
+            for d in (build_page_manifest(root).diagnostics
+                      + build_route_manifest(root).diagnostics
+                      + check_project_composition(root)):
+                if _diag_key(d) not in reported:
+                    by_file.setdefault(d.file, []).append(d)
             for path, diags in sorted(by_file.items()):
                 with open(path, "r", encoding="utf-8") as fh:
                     report(LineIndex(fh.read()), diags)

package/compiler/validator/vlcheck/ast_nodes.py

@@ -214,10 +214,11 @@ class Guard(Node):
 @dataclass
 class PageServerFile(Node):
     """Root of a `page.server.vl` file (dispatched on the basename, not a
-    keyword). Top level is handlers plus at most one `errors` block — no
-    `use` / `type` / other module items."""
+    keyword). Top level is `use` lines, handlers and at most one `errors`
+    block — no `type` / other module items (spec section 10.2, Imports)."""
     handlers: list = field(default_factory=list)   # list[PageServerHandler]
     errors: list = field(default_factory=list)     # list[ErrorMapEntry]
+    uses: list = field(default_factory=list)       # list[Use]
 
 
 @dataclass
@@ -246,9 +247,12 @@ class ErrorMapEntry(Node):
 # --- _server.vl context providers (spec §10.2) ------------------------------
 @dataclass
 class ServerContextFile(Node):
-    """Root of a `_server.vl` file (dispatched on the basename): only
-    `context` provider declarations."""
+    """Root of a `_server.vl` file (dispatched on the basename): `use`
+    lines, `context` provider declarations and, in a multi-page project's
+    root `app/_server.vl` only, the project's `auth` block (spec 10.2)."""
     providers: list = field(default_factory=list)   # list[ContextProvider]
+    uses: list = field(default_factory=list)        # list[Use]
+    auth: Any = None                                # AuthDecl | None
 
 
 @dataclass
@@ -456,3 +460,11 @@ class Range(Node):
 class Pattern(Node):
     binds: list = field(default_factory=list)
     head: str = ""        # constructor / variant / "_" ; "" for literal & structural patterns
+    # What the pattern tests, for the build (spec section 5.6): "wild" (`_`),
+    # "name" (a bare name: a fieldless variant, or a binding), "ctor"
+    # (`head(a, b)`), "lit" (`lo`), "range" (`lo..hi` / `lo..=hi`),
+    # "record" (`T{...}`), "list" (`[...]`) or "other".
+    kind: str = ""
+    lo: Any = None        # A.Literal of a "lit" / "range" pattern
+    hi: Any = None        # A.Literal upper bound of a "range" pattern
+    inclusive: bool = False

package/compiler/validator/vlcheck/async_calls.py

@@ -0,0 +1,395 @@
+"""Calls that wait, in positions that cannot wait (alpha.17).
+
+A call to a service route, an outbound `api` client, a page-server client
+(`api.ns.m()`), `auth.*`, or a `let` closure holding `try` / `par` returns
+before its work finishes. In a view handler, a route body, a `spawn` task
+or a closure that itself waits, the build awaits it wherever it sits
+(`upper(f(x))`, `"{f(x)}"`, `f(x) + 1`, a condition). Anywhere else -- a
+`derive`, a render value, a `state` initialiser, a plain closure -- the
+value would be a pending promise, so:
+
+- E-ASYNC-CALL: a network call in a position that cannot wait.
+- E-CLOSURE-ASYNC: a call to a `let` closure holding `try` / `par` in a
+  position that cannot wait, or such a closure handed to a view prop the
+  child calls from one (the std-function case is in
+  `checks.Checker._check_async_closure_arg`).
+
+Names are followed by binding, not by spelling (`Scopes`): a closure
+parameter or a local that shadows a `try` / `par` closure is not that
+closure. A callback prop is followed through the views that pass it on
+(`Child(onSave: onSave)`), so a grandchild calling it where nothing can
+wait counts for the view the closure was handed to.
+
+The build (vlbuild.emit) makes the same decision at emission time and
+refuses the same source with the same codes; `fn_params_called_sync` is
+shared by both.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+from . import ast_nodes as A
+
+# Fix lines, shared with the build's messages (vlbuild.emit).
+ASYNC_CALL_FIX = ("fetch it with `load NAME = CALL`, or call it in an `on` "
+                  "handler or route body and keep the result in `state` or "
+                  "a `let`")
+CLOSURE_CALL_FIX = ("call it where the call can be awaited -- an `on` handler, "
+                    "a route body, or another closure that holds `try` / "
+                    "`par` -- and use the result there (keep it in `state` "
+                    "for render code)")
+PROP_ASYNC_FIX = ("call '%s' only from an `on` handler in %s, where it is "
+                  "awaited, or pass a closure without `try` / `par`")
+STD_ASYNC_FIX = ("use `CALL() ?? fallback` inside the closure for a call that "
+                 "does not wait; make network calls in the handler or route "
+                 "body first and bind the results with `let`")
+
+
+def sentence(fix: str) -> str:
+    """A fix line as a sentence of a build message."""
+    return fix[:1].upper() + fix[1:]
+
+
+def _children(node):
+    for fname in getattr(node, "__dataclass_fields__", {}):
+        if fname in ("start", "end"):
+            continue
+        val = getattr(node, fname)
+        for item in (val if isinstance(val, (list, tuple)) else [val]):
+            for sub in (item if isinstance(item, tuple) else (item,)):
+                if hasattr(sub, "__dataclass_fields__"):
+                    yield sub
+
+
+def _closure_async(e) -> bool:
+    from .checks import closure_needs_async
+    return closure_needs_async(e)
+
+
+# Binding tags: what a name is bound to, as `Scopes.tag` finds it.
+ASYNC = "async"          # a `let` bound to a closure holding `try` / `par`
+
+
+class Scopes:
+    """Lexical scopes, innermost last: each maps a name to its binding's
+    tag (`ASYNC`, `("param", name)` for a view's `fn` param, or None)."""
+
+    def __init__(self, names=()) -> None:
+        self.frames: list[dict] = [{n: None for n in names if n}]
+
+    def push(self, names=()) -> None:
+        self.frames.append({n: None for n in names if n})
+
+    def pop(self) -> None:
+        self.frames.pop()
+
+    def bind(self, name, tag=None) -> None:
+        if name:
+            self.frames[-1][name] = tag
+
+    def tag(self, name):
+        for frame in reversed(self.frames):
+            if name in frame:
+                return frame[name]
+        return None
+
+
+def let_tag(st):
+    """`ASYNC` for `let f = fn ...` holding `try` / `par`, else None."""
+    return ASYNC if (isinstance(st.init, A.Closure) and _closure_async(st.init)) else None
+
+
+def _block(stmts, is_async, sc, visit, names=()):
+    sc.push(names)
+    try:
+        for st in (stmts if isinstance(stmts, list) else [stmts]):
+            if st is not None:
+                walk(st, is_async, sc, visit)
+    finally:
+        sc.pop()
+
+
+def walk(node, is_async, sc: Scopes, visit):
+    """Call `visit(node, is_async, sc)` for every node under `node`, with
+    `is_async` true where the build can `await` (an `on` handler, a
+    `spawn` task, a closure holding `try` / `par`; a plain closure body is
+    not) and `sc` holding the bindings in scope there: a block's `let`s, a
+    closure's params, a `for`'s variables, a `match` / `catch` arm's
+    bindings. A `let` is bound after its initialiser, which still sees the
+    outer binding; a `par` block's lets bind in the enclosing block."""
+    visit(node, is_async, sc)
+    if isinstance(node, A.Let):
+        if node.init is not None:
+            walk(node.init, is_async, sc, visit)
+        sc.bind(node.name, let_tag(node))
+    elif isinstance(node, (A.StateDecl, A.DeriveDecl, A.LoadDecl)):
+        for sub in _children(node):
+            walk(sub, is_async, sc, visit)
+        sc.bind(node.name)
+    elif isinstance(node, (A.OnBlock, A.Spawn)):
+        _block(node.body, True, sc, visit)
+    elif isinstance(node, A.Closure):
+        inner = _closure_async(node) if isinstance(node.body, list) else False
+        _block(node.body, inner, sc, visit, [p.name for p in node.params])
+    elif isinstance(node, A.For):
+        walk(node.iter, is_async, sc, visit)
+        _block(node.body, is_async, sc, visit, node.vars)
+    elif isinstance(node, A.While):
+        walk(node.cond, is_async, sc, visit)
+        _block(node.body, is_async, sc, visit)
+    elif isinstance(node, A.If):
+        walk(node.cond, is_async, sc, visit)
+        _block(node.then, is_async, sc, visit)
+        for cond, blk in node.elifs or []:
+            walk(cond, is_async, sc, visit)
+            _block(blk, is_async, sc, visit)
+        if node.orelse:
+            _block(node.orelse, is_async, sc, visit)
+    elif isinstance(node, A.Match):
+        walk(node.subject, is_async, sc, visit)
+        for arm in node.arms:
+            sc.push(getattr(arm[0], "binds", None) or ())
+            try:
+                for part in arm[1:]:
+                    for st in (part if isinstance(part, list) else [part]):
+                        if st is not None:
+                            walk(st, is_async, sc, visit)
+            finally:
+                sc.pop()
+    elif isinstance(node, A.Try):
+        walk(node.expr, is_async, sc, visit)
+        for pat, body in node.catches:
+            _block(body, is_async, sc, visit, getattr(pat, "binds", None) or ())
+    elif isinstance(node, A.Element):
+        for sub in node.args or []:
+            walk(sub, is_async, sc, visit)
+        for _k, v in node.attrs or []:
+            if hasattr(v, "__dataclass_fields__"):
+                walk(v, is_async, sc, visit)
+        _block(node.body, is_async, sc, visit)
+    else:
+        for sub in _children(node):
+            walk(sub, is_async, sc, visit)
+
+
+def load_calls(expr) -> list:
+    """The calls a `load` awaits itself: its call, and each call on the
+    left of a `??` chain after it (`load v = f() ?? g() ?? d`)."""
+    out = []
+    while True:
+        if isinstance(expr, A.Call):
+            out.append(expr)
+            return out
+        if (isinstance(expr, A.Binary) and expr.op == "??"
+                and isinstance(expr.left, A.Call)):
+            out.append(expr.left)
+            expr = expr.right
+            continue
+        return out
+
+
+def literal_exprs(lit) -> list:
+    """Each `{expr}` of a string literal, parsed from the literal's own
+    text as the build parses it (offsets are not the file's); one that
+    does not parse is left out (the build reports it)."""
+    from .lexer import Lexer
+    from .parser import Parser
+    out = []
+    raw = getattr(lit, "raw", "") or ""
+    for s, e in getattr(lit, "interp_spans", ()) or ():
+        text = re.sub(r'\\(["\\])', r"\1", raw[s - lit.start:e - lit.start])
+        try:
+            out.append(Parser(Lexer(text, "<interp>").lex(), text,
+                              "<interp>").parse_expr())
+        except Exception:  # noqa: BLE001
+            continue
+    return out
+
+
+def fn_params_called_sync(view, scope_of=None, _memo=None) -> set[str]:
+    """The `fn`-typed params of `view` that end up called from a position
+    that cannot wait (a derive, render, a `state` initialiser, a plain
+    closure): by `view` itself, or by a view it passes the param on to
+    (`Child(onSave: onSave)`), however deep. `scope_of(view)` gives the
+    views that view's body can render, by name (its file's own and its
+    imports); without it only `view`'s own calls count. A parent must not
+    hand a closure that waits to one of these."""
+    memo = {} if _memo is None else _memo
+    if id(view) in memo:
+        return memo[id(view)]      # done, or in progress (a cycle): what is known
+    found: set[str] = set()
+    memo[id(view)] = found
+    fn_params = [p.name for p in view.params
+                 if isinstance(p.type, A.TypeRef) and p.type.is_fn]
+    if not fn_params:
+        return found
+    scope = (scope_of(view) if scope_of else None) or {}
+
+    def visit(node, is_async, sc):
+        if isinstance(node, A.Literal):
+            for sub in literal_exprs(node):
+                walk(sub, is_async, sc, visit)
+        elif isinstance(node, A.Call) and isinstance(node.callee, A.Name):
+            t = sc.tag(node.callee.id)
+            if not is_async and isinstance(t, tuple):
+                found.add(t[1])
+        elif isinstance(node, A.Element) and node.name in scope:
+            passed = {k: sc.tag(v.id) for k, v in node.attrs
+                      if isinstance(v, A.Name) and isinstance(sc.tag(v.id), tuple)}
+            if passed:
+                sync = fn_params_called_sync(scope[node.name], scope_of, memo)
+                found.update(t[1] for k, t in passed.items() if k in sync)
+
+    sc = Scopes([p.name for p in view.params])
+    for p in fn_params:
+        sc.bind(p, ("param", p))
+    for st in view.body:
+        walk(st, False, sc, visit)
+    return found
+
+
+def _parse(path: str):
+    from .lexer import Lexer
+    from .parser import Parser
+    with open(path, encoding="utf-8") as fh:
+        src = fh.read()
+    return Parser(Lexer(src, path).lex(), src, path).parse_module()
+
+
+def _use_target(base: str, it) -> str | None:
+    if not (isinstance(it, A.Use) and it.path.startswith(".")):
+        return None
+    cand = os.path.normpath(os.path.join(base, it.path))
+    target = next((c for c in (cand + ".vl", os.path.join(cand, "index.vl"), cand)
+                   if os.path.isfile(c)), None)
+    return os.path.normcase(os.path.abspath(target)) if target else None
+
+
+def imported_decls(filename: str, mod):
+    """(`api` block names, views, scope_of) the way the build loads them:
+    the `api` blocks this file imports with a relative `use`, the views
+    it can render (its own and imported), and `scope_of(view)` -> the
+    views that view's own file can render, following every imported
+    file's own `use`s."""
+    files: dict[str, tuple] = {}      # path -> (module, the views it can render)
+    scopes: dict[int, dict] = {}      # id(view) -> its file's views
+
+    def file_scope(path: str, module) -> dict:
+        if path in files:
+            return files[path][1]
+        scope: dict = {}
+        files[path] = (module, scope)
+        base = os.path.dirname(path)
+        for it in getattr(module, "items", []):
+            if isinstance(it, A.ViewDecl):
+                scope[it.name] = it
+                scopes[id(it)] = scope
+        for it in getattr(module, "items", []):
+            target = _use_target(base, it)
+            if target is None:
+                continue
+            if target not in files:
+                try:
+                    file_scope(target, _parse(target))
+                except Exception:  # noqa: BLE001 -- its own check reports it
+                    continue
+            wanted = set(it.names or [])
+            for d in files[target][0].items:
+                if isinstance(d, A.ViewDecl) and (not wanted or d.name in wanted):
+                    scope.setdefault(d.name, d)
+        return scope
+
+    path = os.path.normcase(os.path.abspath(filename))
+    views = dict(file_scope(path, mod))
+    apis: set[str] = set()
+    for it in getattr(mod, "items", []):
+        target = _use_target(os.path.dirname(path), it)
+        if target is None or target not in files:
+            continue
+        wanted = set(it.names or [])
+        apis.update(d.name for d in files[target][0].items
+                    if isinstance(d, A.ApiDecl) and (not wanted or d.name in wanted))
+    return apis, views, (lambda v: scopes.get(id(v), {}))
+
+
+class AsyncCalls:
+    def __init__(self, report, clients: set, views: dict, interp=None,
+                 scope_of=None):
+        self.report = report            # report(code, message, node, fix)
+        self.interp = interp            # (start, end) -> parsed `{expr}` or None
+        self.clients = clients          # service and api block names
+        self.views = views              # the views this file can render, by name
+        self.scope_of = scope_of        # view -> the views its file can render
+        self._memo: dict = {}
+
+    def kind(self, call, sc: Scopes):
+        """"net" for a network call, "closure" for a call to a `let`
+        closure holding `try` / `par`, else None."""
+        callee = call.callee
+        if isinstance(callee, A.Member):
+            obj = callee.obj
+            # `auth.sign_in(...)`, `calc.one()`, `store.get(...)`, and the
+            # page-server client `api.posts.get(...)` / legacy `api.x()`
+            if isinstance(obj, A.Name) and (
+                    obj.id in ("api", "auth") or obj.id in self.clients):
+                return "net"
+            if (isinstance(obj, A.Member) and isinstance(obj.obj, A.Name)
+                    and obj.obj.id == "api"):
+                return "net"
+            return None
+        if isinstance(callee, A.Name) and sc.tag(callee.id) == ASYNC:
+            return "closure"
+        return None
+
+    def run(self, stmts, is_async: bool, params=()) -> None:
+        """One declaration's body (a view, a route, a page.server handler),
+        with its params in scope."""
+        allowed: set[int] = set()
+
+        def visit(node, ctx, sc):
+            if isinstance(node, A.Literal) and self.interp is not None:
+                # `"{f(x)}"`: the build lowers each `{expr}` in place
+                for s, e in getattr(node, "interp_spans", ()) or ():
+                    sub = self.interp(s, e)
+                    if sub is not None:
+                        walk(sub, ctx, sc, visit)
+            elif isinstance(node, A.LoadDecl):
+                allowed.update(id(c) for c in load_calls(node.expr))
+            elif isinstance(node, A.Element) and node.name in self.views:
+                sync = fn_params_called_sync(self.views[node.name], self.scope_of,
+                                             self._memo)
+                for k, v in node.attrs:
+                    waits = ((isinstance(v, A.Closure) and _closure_async(v))
+                             or (isinstance(v, A.Name) and sc.tag(v.id) == ASYNC))
+                    if waits and k in sync:
+                        self.report(
+                            "E-CLOSURE-ASYNC",
+                            "the closure passed as '%s' holds `try` or `par`, "
+                            "but %s calls '%s', itself or through a view it "
+                            "passes it to, from a derive, render value or plain "
+                            "closure, which cannot wait for it" % (
+                                k, node.name, k), v,
+                            PROP_ASYNC_FIX % (k, node.name))
+            elif (isinstance(node, A.Call) and not ctx
+                    and id(node) not in allowed):
+                kind = self.kind(node, sc)
+                if kind == "net":
+                    self.report(
+                        "E-ASYNC-CALL",
+                        "this call waits for a network call, and a derive, "
+                        "render value, `state` initialiser or plain closure "
+                        "cannot wait for it: it would get a pending value",
+                        node, ASYNC_CALL_FIX)
+                elif kind == "closure":
+                    self.report(
+                        "E-CLOSURE-ASYNC",
+                        "'%s' holds `try` or `par`, so a call to it waits, and "
+                        "a derive, render value, `state` initialiser or plain "
+                        "closure cannot wait for it: it would get a pending "
+                        "value" % node.callee.id, node, CLOSURE_CALL_FIX)
+
+        sc = Scopes(params)
+        for st in stmts or []:
+            walk(st, is_async, sc, visit)