volaro 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -1,7 +1,8 @@
 # Volaro
 
-**Limited alpha (`0.1.0-alpha.1`). Not yet published to npm.** Install from a
-local `npm pack` tarball to try it.
+**Limited alpha, published as `0.1.0-alpha.1` under the `alpha` dist-tag** —
+`npm install volaro@alpha`. Not `latest` (that still resolves to an earlier
+`0.0.x` placeholder) — always specify `@alpha` or the exact version.
 
 Volaro is an experimental application language intended for AI authoring and
 human review. This package ships the language reference **and a working
@@ -65,9 +66,12 @@ Node 22.5+ for `node:sqlite`.
 ## Scaffold a project
 
 ```bash
-npm create volaro my-app      # the separate create-volaro package
+npm create volaro@alpha my-app      # the separate create-volaro package
 ```
 
+(`@alpha` matters — `npm create volaro` with no tag resolves `latest`, which
+is still an earlier `0.0.x` placeholder, not this build.)
+
 It writes one single-page starter, a `volaro.json`, and `package.json` scripts
 (`dev` / `build` / `check`) that call `volaro`.
 
@@ -110,3 +114,25 @@ The legacy `volara` npm package is unrelated to this release.
 ## License
 
 MIT
+
+
+## Local assets
+
+Put public files in `assets/` beside your entry `.vl` file and use
+`img src:"assets/logo.svg" alt:"Logo"`. Build and dev copy them to the browser
+bundle. Dev watches changes; refresh the browser after a rebuild. Missing
+literal asset references fail the build. Output `assets/` is compiler-owned.
+
+## Package provenance
+
+`compiler/SOURCE_REV` records the source commit. `compiler/SOURCE_INFO.json`
+adds its origin, Git dirty status where available, and a SHA-256 digest of
+compiler and CLI/documentation content. A package version alone does not
+identify a local candidate; preserve the tarball hash as well.
+
+Packaging a Git export uses `.volaro-source-rev`, expanded by `git archive`.
+For other exported source, set `VOLARO_SOURCE_REV` to the full source commit
+hash before `npm pack`. Missing/invalid revisions fail packaging; an explicit
+revision cannot override a different checkout HEAD. Export metadata identifies
+the base revision, not an assurance that someone has not modified the export;
+the content hash distinguishes modified candidates. Nothing is published by packing.

package/bin/vl.js

@@ -12,7 +12,7 @@
 // Python is located and version-checked up front with an actionable message
 // (see ../lib/env.js). Nothing here depends on the Volaro repository layout.
 
-import { readFileSync, existsSync, statSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, statSync, lstatSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve as resolvePath, extname, relative, sep, delimiter } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
@@ -148,6 +148,13 @@ const MIME = {
   ".css": "text/css; charset=utf-8",
   ".json": "application/json; charset=utf-8",
   ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
   ".map": "application/json",
 };
 
@@ -184,7 +191,7 @@ function staticServer(dir, port) {
 // Polling beats fs.watch here: it is identical across platforms and editors
 // (rename-replace, truncate-write and append all show up), which fs.watch is
 // not, and the cost is trivial for a project-sized tree.
-function scanVl(dir, depth = 6, acc = new Map()) {
+function scanVl(dir, depth = 6, acc = new Map(), excluded = null) {
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
@@ -194,8 +201,9 @@ function scanVl(dir, depth = 6, acc = new Map()) {
   for (const e of entries) {
     if (e.name === "node_modules" || e.name === ".git" || e.name.startsWith(".")) continue;
     const p = join(dir, e.name);
+    if (resolvePath(p) === excluded) continue;
     if (e.isDirectory()) {
-      if (depth > 0) scanVl(p, depth - 1, acc);
+      if (depth > 0) scanVl(p, depth - 1, acc, excluded);
     } else if (extname(e.name) === ".vl") {
       try {
         const s = statSync(p);
@@ -214,10 +222,24 @@ function snapEqual(a, b) {
 
 // Poll watchDir for .vl changes and call onChange (debounced by the interval).
 // Returns a close() that stops polling.
-function watchVl(watchDir, onChange) {
-  let prev = scanVl(watchDir);
+function watchVl(watchDir, onChange, outDir) {
+  const snapshot = () => {
+    const acc = scanVl(watchDir, 6, new Map(), resolvePath(outDir));
+    const scanAssets = (dir) => {
+      try {
+        const s = lstatSync(dir);
+        acc.set(dir, `${s.mtimeMs}:${s.ctimeMs}:${s.size}`);
+        if (s.isDirectory() && !s.isSymbolicLink()) {
+          for (const name of readdirSync(dir)) scanAssets(join(dir, name));
+        }
+      } catch {}
+    };
+    scanAssets(join(watchDir, "assets"));
+    return acc;
+  };
+  let prev = snapshot();
   const iv = setInterval(() => {
-    const now = scanVl(watchDir);
+    const now = snapshot();
     if (!snapEqual(prev, now)) {
       prev = now;
       onChange();
@@ -299,7 +321,7 @@ function cmdDev(args) {
       await restartServer();
       startServer();
       process.stdout.write("volaro dev: server restarted\n");
-    });
+    }, out);
 
     const bye = () => {
       if (shuttingDown) return;
@@ -326,7 +348,7 @@ function cmdDev(args) {
     process.stdout.write("volaro dev: change detected — rebuilding\n");
     const r = buildOnce(entry, out);
     process.stdout.write(r.ok ? "volaro dev: rebuilt\n" : "volaro dev: build failed — keeping last good bundle\n");
-  });
+  }, out);
 
   const bye = () => {
     if (shuttingDown) return;
@@ -351,7 +373,14 @@ function cmdReference(which) {
     );
   }
   const file = which === "supported" ? "supported" : which;
-  process.stdout.write(read(`language/${file}.md`));
+  // `supported.md`'s own title carries this build's exact version as a
+  // `{{VERSION}}` placeholder rather than a hardcoded string -- found stale
+  // (still reading a prior release's version after a version bump, since
+  // nothing kept it in sync) in the Test_003 benchmark's packaged-docs
+  // finding. Substituted from `package.json` at print time so it can never
+  // drift again, the same way the "supported"-vs-"spec" note above already
+  // reads `pkg.version` live rather than a copy-pasted string.
+  process.stdout.write(read(`language/${file}.md`).replace("{{VERSION}}", pkg.version));
 }
 
 function cmdExample(name) {

package/compiler/SOURCE_INFO.json

@@ -0,0 +1,6 @@
+{
+  "revision": "a450e6fe6549b8c7df43ba343793ab2e52758a78",
+  "source": "git",
+  "dirty": false,
+  "content_sha256": "095f3d5b55826d6aa0c560ce5570c91752d8f03cbd0e869ce61df1fcf53e2593"
+}

package/compiler/SOURCE_REV

@@ -1 +1 @@
-e1d25fea4407ecd621dc6a0982a2023dfb5c5ba1
+a450e6fe6549b8c7df43ba343793ab2e52758a78

package/compiler/validator/vlcheck/checks.py

@@ -39,6 +39,36 @@ BUILTINS = {
 }
 _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
@@ -125,13 +155,39 @@ class Checker:
         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
@@ -195,6 +251,88 @@ class Checker:
                                     "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."""
@@ -401,8 +539,11 @@ class Checker:
                     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 message, optional class:, and no children",
-                                node, 'status message — keep it mounted; use nil or "" while idle')
+                                "'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,
@@ -1070,6 +1211,17 @@ 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)

package/compiler/validator/vlcheck/lexer.py

@@ -191,7 +191,10 @@ class Lexer:
         if src[self.i:self.i + 3] == '"""':
             self.i += 3
             while self.i < self.n and src[self.i:self.i + 3] != '"""':
-                self.i += 1
+                if src[self.i] == "\\":
+                    self._lex_escape()
+                else:
+                    self.i += 1
             if src[self.i:self.i + 3] == '"""':
                 self.i += 3
             else:
@@ -204,7 +207,7 @@ class Lexer:
         while self.i < self.n:
             c = src[self.i]
             if c == "\\":
-                self.i += 2
+                self._lex_escape()
                 continue
             if c == "\n":
                 self._err("E-STRING", "unterminated string literal", s, self.i,
@@ -236,6 +239,35 @@ class Lexer:
         tok = self._add("STRING", src[s:self.i], s, self.i)
         tok.interps = interps
 
+    def _lex_escape(self) -> None:
+        """Validate escapes before emission can silently change their meaning."""
+        start = self.i
+        self.i += 1
+        if self.i < self.n and self.src[self.i] in 'nt"\\{}':
+            self.i += 1
+            return
+        if self.src[self.i:self.i + 2] == "u{":
+            end = self.src.find("}", self.i + 2)
+            digits = self.src[self.i + 2:end] if end != -1 else ""
+            if (1 <= len(digits) <= 6
+                    and all(c in "0123456789abcdefABCDEF" for c in digits)):
+                value = int(digits, 16)
+                if value <= 0x10ffff and not 0xd800 <= value <= 0xdfff:
+                    self.i = end + 1
+                    return
+            self._err("E-STRING-ESCAPE", "invalid Unicode string escape", start,
+                      min(self.n, end + 1 if end != -1 else self.i + 1),
+                      r"use \u{HEX} with a Unicode scalar value (no surrogate code points)")
+            if end != -1 and not any(c in self.src[self.i:end] for c in '\n"'):
+                self.i = end + 1
+            return
+        self._err("E-STRING-ESCAPE", "unknown string escape", start,
+                  min(self.n, self.i + 1),
+                  r'double a literal backslash: "\\s" for regex \s; supported escapes: \n \t \" \\ \{ \} \u{HEX}')
+        # Keep a closing quote/newline available for normal string recovery.
+        if self.i < self.n and self.src[self.i] not in '\n"':
+            self.i += 1
+
     def _lex_number(self) -> None:
         s = self.i
         src = self.src