exprforge 0.4.0 → 0.5.0

package/ast.js

@@ -11,24 +11,87 @@
 //   { type: "cmp",    op: ">" | "<" | ">=" | "<=" | "==" | "!=", left: Node, right: Node }
 //   { type: "select", cond: CmpNode, then: Node, else: Node }
 //   { type: "outputs", fields: { [name: string]: Node } }
+//   { type: "field",   target: Node, field: string }
+//
+// "field" is postfix "." access (e.g. b.rx) — parser sugar produced only
+// by expr.js/fn.js's grammar, and eliminated by macros.js's
+// expandMacros() before a tree ever reaches checkUnboundVars,
+// evaluate(), or any emitter. It only makes semantic sense when `target`
+// resolves to a name bound to a multi-output *macro* call (see
+// macros.js) — that's checked there, not here, same "defer semantic
+// validation to the consumer" precedent call() already follows for
+// function names. A "field" node reaching evaluate()/an emitter directly
+// means expandMacros() was skipped or didn't run to completion; both
+// throw their own "unknown node type" error in that case.
 //
 // Every "bin" node is emitted with explicit parens in every target, so
 // operation order (and therefore floating-point rounding behavior) is
 // identical everywhere.
+//
+// SECURITY: every builder below validates its own name/op/value
+// argument(s) -- see assertSafeIdentifier/assertSafeOp/assertFiniteNumber
+// just below. This is specifically about these builders being the "raw
+// AST" layer -- the one this project's own README recommends reaching
+// for when you want the least amount of magic between your formula and
+// the code it emits. Without validation, that would have been the LEAST
+// safe layer to build from untrusted input, not the most: fn`...`/
+// expr`...`'s own tokenizer already only ever produces safe identifier
+// characters, so these builders were the one place a malicious/malformed
+// name -- e.g. `v('x); process.exit(1); //')` -- could reach emitted
+// output completely unchecked, verbatim, in all 16 targets at once.
+// Confirmed, not assumed, before this existed.
+
+// Matches fn`...`/expr`...`'s own tokenizer IDENT rule exactly (see
+// expr.js's tokenizeSegment) -- anything that couldn't have come out of
+// the real parser isn't allowed in here either.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertSafeIdentifier(name, context) {
+    if (typeof name !== "string" || !IDENTIFIER.test(name)) {
+        throw new Error(
+            `${context}: ${JSON.stringify(name)} isn't a safe identifier -- must start with a letter or "_", ` +
+            `followed only by letters/digits/"_" (the same rule fn\`...\`/expr\`...\`'s own tokenizer already ` +
+            `enforces on anything parsed from text; this only matters when building a tree directly, bypassing ` +
+            `the parser)`,
+        );
+    }
+}
+
+const BIN_OPS = new Set(["+", "-", "*", "/"]);
+const CMP_OPS = new Set([">", "<", ">=", "<=", "==", "!="]);
+
+function assertSafeOp(op, allowed, context) {
+    if (!allowed.has(op)) {
+        throw new Error(`${context}: ${JSON.stringify(op)} isn't one of the allowed operators (${[...allowed].join(" ")})`);
+    }
+}
+
+function assertFiniteNumber(value, context) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(
+            `${context}: ${JSON.stringify(value)} isn't a finite number -- NaN/Infinity/non-numeric values ` +
+            `can't be emitted as a literal in every target`,
+        );
+    }
+}
 
 function num(value) {
+    assertFiniteNumber(value, "num()");
     return { type: "num", value };
 }
 
 function v(name) {
+    assertSafeIdentifier(name, "v()");
     return { type: "var", name };
 }
 
 function bin(op, left, right) {
+    assertSafeOp(op, BIN_OPS, "bin()");
     return { type: "bin", op, left, right };
 }
 
 function call(name, ...args) {
+    assertSafeIdentifier(name, "call()");
     return { type: "call", name, args };
 }
 
@@ -59,6 +122,7 @@ function neg(x) {
 // then divide three components by it). Lifted out by collectLets before
 // emission — see there for how `v(name)` ends up referring to it.
 function letIn(name, value, body) {
+    assertSafeIdentifier(name, "letIn()");
     return { type: "let", name, value, body };
 }
 
@@ -86,6 +150,7 @@ function letChain(bindings, body) {
 // Comparison predicate — only valid as the `cond` of a select(); not a
 // general boolean expression, and shouldn't appear anywhere else in a tree.
 function cmp(left, op, right) {
+    assertSafeOp(op, CMP_OPS, "cmp()");
     return { type: "cmp", op, left, right };
 }
 
@@ -107,9 +172,28 @@ function select(cond, thenNode, elseNode) {
 // return, an object literal, output parameters) — see formatSuite in each
 // emitters/<lang>.js.
 function outputs(fields) {
+    for (const name of Object.keys(fields)) assertSafeIdentifier(name, "outputs()");
     return { type: "outputs", fields };
 }
 
+// Postfix "." field access into a multi-output intrinsic's result — see
+// the "field" node-shape comment at the top of this file for what this
+// actually means and who consumes it.
+function field(target, name) {
+    assertSafeIdentifier(name, "field()");
+    return { type: "field", target, field: name };
+}
+
+// The prefix macros.js's own gensym'd internal let-names always start
+// with (see substituteAndRename's "let" case there) — defined HERE, not
+// there, specifically so collectLets below can recognize a collision
+// against one WITHOUT macros.js needing to require this file back (it
+// already does the other direction: macros.js requires ast.js). Kept as
+// one shared constant rather than a duplicated string literal in both
+// files, so it can't quietly drift out of sync between "the name this
+// generates" and "the name this recognizes".
+const MACRO_GENSYM_PREFIX = "efMacro_";
+
 // Lifts every `let` node out of the tree into a flat, ordered list of
 // { name, node } bindings, replacing each with a plain v(name) reference.
 // The list is in dependency order — safe to declare/assign top-to-bottom.
@@ -152,7 +236,23 @@ function collectLets(node) {
     const seen = new Set();
     for (const { name } of bindings) {
         if (seen.has(name)) {
-            throw new Error(`collectLets: duplicate let binding name "${name}" in one function`);
+            // A colliding name that happens to start with macros.js's own
+            // gensym prefix is almost certainly NOT something you wrote
+            // on purpose -- vanishingly unlikely to be an intentional
+            // collision, and confusing to debug as a plain "duplicate
+            // name" if you don't already know that prefix means
+            // "internally generated" -- named explicitly here rather
+            // than left for you to work out. The gensym'd name itself is
+            // never the one to rename (it's already unique per macro
+            // invocation, see toMacro's own comment in macros.js) -- only
+            // your OWN same-named binding actually needs to change.
+            const hint = name.startsWith(MACRO_GENSYM_PREFIX)
+                ? ` -- this looks like an internal name macro expansion generates automatically ` +
+                  `(see macros.js's own gensym'd "let" renaming), not something you wrote; if you ` +
+                  `have your own let/param actually named "${name}", rename YOURS to something that ` +
+                  `doesn't start with "${MACRO_GENSYM_PREFIX}"`
+                : "";
+            throw new Error(`collectLets: duplicate let binding name "${name}" in one function${hint}`);
         }
         seen.add(name);
     }
@@ -160,4 +260,92 @@ function collectLets(node) {
     return { bindings, body };
 }
 
-module.exports = { num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, collectLets };
+// Every v(name) reference anywhere in `node`, regardless of whether
+// anything actually declares it -- a pure structural walk, no binding
+// awareness at all. `refs` accumulates across recursive calls so this
+// can be called repeatedly against several subtrees (e.g. once per
+// let-binding's own value, plus once for the final body) and still
+// build one combined set. Mirrors collectLets's own node-type walk
+// above exactly, since it needs to see the identical tree shape.
+function collectVarRefs(node, refs = new Set()) {
+    if (node.type === "var") {
+        refs.add(node.name);
+    } else if (node.type === "bin") {
+        collectVarRefs(node.left, refs);
+        collectVarRefs(node.right, refs);
+    } else if (node.type === "call") {
+        for (const a of node.args) collectVarRefs(a, refs);
+    } else if (node.type === "cmp") {
+        collectVarRefs(node.left, refs);
+        collectVarRefs(node.right, refs);
+    } else if (node.type === "select") {
+        collectVarRefs(node.cond, refs);
+        collectVarRefs(node.then, refs);
+        collectVarRefs(node.else, refs);
+    } else if (node.type === "let") {
+        collectVarRefs(node.value, refs);
+        collectVarRefs(node.body, refs);
+    } else if (node.type === "outputs") {
+        for (const fieldNode of Object.values(node.fields)) collectVarRefs(fieldNode, refs);
+    }
+    // num: nothing to add.
+    return refs;
+}
+
+// Confirms every var() reference anywhere in fn.body -- inside a
+// let-binding's own value, or in the final body/outputs -- corresponds
+// to something actually declared: a parameter, or a let binding
+// somewhere else in the same function. "Somewhere else", not
+// "somewhere earlier": collectLets's own doc comment already
+// establishes there's no real lexical scoping here -- every let-binding
+// is one flat, function-wide name -- so "declared anywhere in this
+// function" is the right, and only meaningful, check, not an
+// order-sensitive one.
+//
+// Catches a typo'd or forgotten identifier at the earliest possible
+// point, for every target and for evaluate() uniformly, rather than
+// relying on evaluate() happening to hit it at runtime (which it might
+// never do -- e.g. a reference inside a select() branch that a
+// particular call's arguments never take would never surface that way)
+// or on whichever target language's own compiler/runtime eventually
+// notices, with wildly inconsistent timing and clarity (a real compile
+// error in Java, a silent-until-called ReferenceError in JS). Confirmed
+// the gap first, not assumed: before this existed, emitAll() silently
+// succeeded across all 18 targets for a body referencing a completely
+// undeclared name.
+//
+// Also validates fn.name and every fn.params entry as safe identifiers
+// (see assertSafeIdentifier above) -- the SAME concern as every builder
+// above, just here instead of at a constructor call site, since
+// {name, params, body} is a plain object literal shape with no
+// constructor function of its own to hook into. This is the one place
+// every real consumption path (evaluate(), every emitter's
+// emitFunction(), cobol.js's own override) already runs unconditionally,
+// so it's the natural single checkpoint for this too.
+function checkUnboundVars(fn) {
+    assertSafeIdentifier(fn.name, "fn.name");
+    for (const p of fn.params) assertSafeIdentifier(p, "fn.params");
+
+    const { bindings, body } = collectLets(fn.body);
+    const declared = new Set([...fn.params, ...bindings.map((b) => b.name)]);
+
+    const referenced = new Set();
+    for (const { node } of bindings) collectVarRefs(node, referenced);
+    collectVarRefs(body, referenced);
+
+    for (const name of referenced) {
+        if (!declared.has(name)) {
+            throw new Error(
+                `checkUnboundVars: "${name}" is referenced in "${fn.name}" but never declared -- ` +
+                `not a parameter (${fn.params.length ? fn.params.join(", ") : "none"}) and no ` +
+                `"let ${name} = ..." binding exists anywhere in this function`,
+            );
+        }
+    }
+}
+
+module.exports = {
+    num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, field, collectLets,
+    checkUnboundVars,
+    MACRO_GENSYM_PREFIX,
+};

package/emitters/base.js

@@ -26,7 +26,8 @@
 //                    suite gets emitted through this emitter; omitted
 //                    otherwise.
 
-const { collectLets } = require("../ast.js");
+const { collectLets, checkUnboundVars } = require("../ast.js");
+const { expandMacros, resolveExternForEmitter, withContext } = require("../macros.js");
 
 class Emitter {
     constructor(config) {
@@ -64,11 +65,23 @@ class Emitter {
             }
             case "call": {
                 const args = node.args.map((a) => this.emitExpr(a));
-                const template = this.calls[node.name];
+                // `this.lang` is injected by emitters/registry.js (the
+                // registered key, e.g. "js"/"cobol") -- not set for an
+                // Emitter built standalone outside the registry, in which
+                // case an extern simply never resolves here, same as an
+                // unmapped name.
+                const builtin = this.calls[node.name];
+                const template = builtin || (this.lang && resolveExternForEmitter(node.name, this.lang, this._registry));
                 if (!template) {
                     throw new Error(`emitter for .${this.ext}: no mapping for Math function "${node.name}"`);
                 }
-                return template(args);
+                // Only an extern's own per-target template is caller-
+                // supplied code that could have a bug worth attributing
+                // -- a built-in primitive's template is exprforge's own,
+                // not worth wrapping.
+                return builtin
+                    ? template(args)
+                    : withContext(`emitter for .${this.ext}: while emitting extern "${node.name}"`, () => template(args));
             }
             case "select": {
                 const thenStr = this.emitExpr(node.then);
@@ -89,7 +102,26 @@ class Emitter {
         }
     }
 
-    emitFunction(fn) {
+    // `registry` (see macros.js's createRegistry()) defaults to the
+    // process-wide default when omitted -- pass a session's own (see
+    // index.js's createSession()) to resolve macros/externs against that
+    // session instead. Stashed on `this` for emitExpr's "call" case to
+    // read, same instance-state pattern emitters/cobol.js's own
+    // `this._pool` already established.
+    emitFunction(fn, registry = undefined) {
+        this._registry = registry;
+        // Resolves every macro call and field() access into plain
+        // arithmetic first -- see macros.js's own header comment. Must
+        // run before checkUnboundVars: expansion is what introduces the
+        // flattened let-bindings a multi-output macro's fields become,
+        // and eliminates "field" nodes, which checkUnboundVars/
+        // collectLets don't know how to walk.
+        fn = expandMacros(fn, null, registry);
+        // Checked once, before any per-target work starts -- see
+        // checkUnboundVars's own comment in ast.js for why this matters
+        // (a typo'd/forgotten identifier used to silently succeed here,
+        // for every target, with no error at all).
+        checkUnboundVars(fn);
         const { bindings, body } = collectLets(fn.body);
         const letBindings = bindings.map(({ name, node }) => ({
             name,

package/emitters/cobol.js

@@ -319,8 +319,27 @@ class TempPool {
 }
 
 class CobolEmitter extends Emitter {
-    emitFunction(fn) {
-        const { collectLets } = require("../ast.js");
+    // `registry` -- see base.js's own emitFunction comment and
+    // macros.js's createRegistry()/index.js's createSession() -- same
+    // `this._registry` instance-state convention as base.js, read by the
+    // inherited emitExpr's "call" case for extern resolution.
+    emitFunction(fn, registry = undefined) {
+        this._registry = registry;
+        const { collectLets, checkUnboundVars } = require("../ast.js");
+        const { expandMacros } = require("../macros.js");
+        // This class overrides emitFunction entirely (never calls
+        // super.emitFunction), so it needs its own copy of the same two
+        // steps base.js's Emitter.emitFunction runs -- see
+        // expandMacros's and checkUnboundVars's own comments (in
+        // macros.js and ast.js respectively). Both run against the
+        // ORIGINAL fn, before renameConflictingParams runs below, so an
+        // error message reports whatever name the caller actually wrote,
+        // not an internally-renamed one (doesn't change which names are
+        // considered declared/resolved either way -- the rename is
+        // identity-preserving over the set of bound names, just changes
+        // their string).
+        fn = expandMacros(fn, null, registry);
+        checkUnboundVars(fn);
         // Must run before collectLets, and before anything else in this
         // function -- collectLets flattens the tree's let structure away,
         // and every check/emission step below assumes fn.params is

package/emitters/registry.js

@@ -1,7 +1,7 @@
 // exprforge/emitters/registry.js
 // Add a new language: write emitters/<lang>.js exporting an Emitter instance,
 // then add one line here. Nothing else in the project needs to change.
-module.exports = {
+const emitters = {
     js: require("./js.js"),
     ts: require("./typescript.js"),
     qb64: require("./qb64.js"),
@@ -21,3 +21,14 @@ module.exports = {
     cobol: require("./cobol.js"),
     expr: require("./exprsyntax.js"),
 };
+
+// Each emitter learns its own registered key here, once -- base.js's
+// emitExpr uses this.lang to resolve an extern (see loadExtern() in
+// macros.js), and this is the one place that already knows the
+// name<->instance mapping, so it's the only file that needs to change
+// for this instead of every emitters/<lang>.js.
+for (const [lang, emitter] of Object.entries(emitters)) {
+    emitter.lang = lang;
+}
+
+module.exports = emitters;

package/evaluate.js

@@ -9,11 +9,12 @@
 // there's exactly one node-shape contract (ast.js's own header comment)
 // for both this file and every emitters/<lang>.js to agree with.
 //
-// Every intrinsic name maps 1:1 onto emitters/js.js's own `calls` table
+// Every primitive name maps 1:1 onto emitters/js.js's own `calls` table
 // keys (the simplest existing source of truth for "what the ~22
-// intrinsics are called") straight to the real Math.* function -- this
+// primitives are called") straight to the real Math.* function -- this
 // target has no codegen step to route an intermediate string through.
-const { collectLets } = require("./ast.js");
+const { collectLets, checkUnboundVars } = require("./ast.js");
+const { expandMacros, resolveExternForEvaluate, withContext } = require("./macros.js");
 
 const CMP_OPS = {
     ">": (a, b) => a > b,
@@ -43,7 +44,12 @@ const CALLS = {
 // valid pre-collectLets (a function's top-level let-chain/body shape),
 // never nested inside a bin/call/select, same constraint every emitter
 // already relies on (see ast.js's own comments on letIn/outputs).
-function evalNode(node, env) {
+// `registry` -- see macros.js's createRegistry()/index.js's
+// createSession() -- resolves an extern against the right session's own
+// registrations, defaulting to the process-wide one when not passed
+// (evaluate() below never passes `undefined` on purpose either way, see
+// there).
+function evalNode(node, env, registry) {
     switch (node.type) {
         case "num":
             return node.value;
@@ -55,18 +61,25 @@ function evalNode(node, env) {
         case "bin": {
             const op = BIN_OPS[node.op];
             if (!op) throw new Error(`evaluate(): unknown bin op "${node.op}"`);
-            return op(evalNode(node.left, env), evalNode(node.right, env));
+            return op(evalNode(node.left, env, registry), evalNode(node.right, env, registry));
         }
         case "call": {
-            const impl = CALLS[node.name];
+            const impl = CALLS[node.name] || resolveExternForEvaluate(node.name, registry);
             if (!impl) throw new Error(`evaluate(): no mapping for Math function "${node.name}"`);
-            return impl(...node.args.map((a) => evalNode(a, env)));
+            const args = node.args.map((a) => evalNode(a, env, registry));
+            // Only an extern's own `evaluate` entry is caller-supplied
+            // code that could have a bug worth attributing -- a built-in
+            // primitive (impl === CALLS[node.name]) is exprforge's own
+            // Math.* wrapper, not worth wrapping.
+            return CALLS[node.name]
+                ? impl(...args)
+                : withContext(`evaluate(): while running extern "${node.name}"`, () => impl(...args));
         }
         case "select": {
             const cmpFn = CMP_OPS[node.cond.op];
             if (!cmpFn) throw new Error(`evaluate(): unknown cmp op "${node.cond.op}"`);
-            const cond = cmpFn(evalNode(node.cond.left, env), evalNode(node.cond.right, env));
-            return evalNode(cond ? node.then : node.else, env);
+            const cond = cmpFn(evalNode(node.cond.left, env, registry), evalNode(node.cond.right, env, registry));
+            return evalNode(cond ? node.then : node.else, env, registry);
         }
         default:
             throw new Error(
@@ -81,8 +94,28 @@ function evalNode(node, env) {
 // fn.params. Returns a number for a plain body, or a {name: value}
 // object for a multi-output (outputs()) body -- matching the shape
 // test/conformance.test.js's own parseSuiteOutput() already expects
-// back from every other target.
-function evaluate(fn, args) {
+// back from every other target. `registry` (see macros.js's
+// createRegistry()) defaults to the process-wide default when omitted --
+// pass a session's own (see index.js's createSession()) to resolve
+// macros/externs against that session instead; ordinary callers never
+// need to pass it.
+function evaluate(fn, args, registry = undefined) {
+    // Resolves every macro call and field() access into plain arithmetic
+    // FIRST -- checkUnboundVars/collectLets/evalNode below know nothing
+    // about either (see macros.js's own header comment); an extern's
+    // call node is left alone here, and resolved above in evalNode's own
+    // "call" case instead.
+    fn = expandMacros(fn, null, registry);
+    // Checked once, up front, exhaustively -- NOT relying on evalNode's
+    // own runtime "unbound variable" throw below to happen to hit it,
+    // which it might never do for a given call: a bad reference inside
+    // a select() branch these particular args don't take would silently
+    // never surface that way. See checkUnboundVars's own comment in
+    // ast.js. evalNode's runtime check stays in place too, as a cheap
+    // internal backstop -- it should be unreachable now that this runs
+    // first, same "check early, keep the deeper check anyway" precedent
+    // emitters/cobol.js already follows for its own reserved-name checks.
+    checkUnboundVars(fn);
     if (args.length !== fn.params.length) {
         throw new Error(`evaluate(): ${fn.name} expects ${fn.params.length} argument(s), got ${args.length}`);
     }
@@ -93,17 +126,17 @@ function evaluate(fn, args) {
 
     const { bindings, body } = collectLets(fn.body);
     for (const { name, node } of bindings) {
-        env[name] = evalNode(node, env);
+        env[name] = evalNode(node, env, registry);
     }
 
     if (body.type === "outputs") {
         const result = {};
         for (const [name, node] of Object.entries(body.fields)) {
-            result[name] = evalNode(node, env);
+            result[name] = evalNode(node, env, registry);
         }
         return result;
     }
-    return evalNode(body, env);
+    return evalNode(body, env, registry);
 }
 
 module.exports = { evaluate };

package/expr.js

@@ -23,7 +23,8 @@
 //   additive       := multiplicative ( ("+"|"-") multiplicative )*
 //   multiplicative := unary ( ("*"|"/") unary )*
 //   unary          := "-" unary | power
-//   power          := primary ( "^" unary )?
+//   power          := postfix ( "^" unary )?
+//   postfix        := primary ( "." IDENT )*
 //   primary        := NUMBER | IDENT ("(" args ")")? | "(" expression ")" | HOLE
 //   args           := expression ("," expression)*
 //
@@ -40,7 +41,7 @@
 //     is only ever "+"|"-"|"*"|"/" (see ast.js), and every emitter's
 //     `calls` table keys "pow" by name, even for targets whose own
 //     syntax has a native ^/** operator.
-const { num, v, add, sub, mul, div, neg, call, cmp, select } = require("./ast.js");
+const { num, v, add, sub, mul, div, neg, call, cmp, select, field } = require("./ast.js");
 
 const COMPARE_OPS = [">", "<", ">=", "<=", "==", "!="];
 
@@ -131,8 +132,12 @@ function tokenizeSegment(str, offset, tokens, state = { inComment: false }, labe
         // {...};) to reuse this same tokenizer instead of forking it.
         // Inert for expr(): nothing that parses successfully today could
         // contain them anyway ("=" alone was always a lex error before,
-        // since only "==" was recognized).
-        if ("+-*/^(),?:><;{}=".includes(ch)) {
+        // since only "==" was recognized). "." is new too -- postfix field
+        // access (b.rx), see parsePostfix() below; harmless to add here
+        // since a bare "." was always a lex error before (the NUMBER
+        // branch above already claims every "." that's followed by a
+        // digit, e.g. ".5", so there's no ambiguity with number literals).
+        if ("+-*/^(),?:><;{}=.".includes(ch)) {
             tokens.push({ type: "OP", value: ch, pos: offset + start });
             i++;
             continue;
@@ -155,6 +160,21 @@ function holeToNode(value, label = "expr()") {
     );
 }
 
+// How deep parseExpression() can recurse into itself -- nested
+// parens/function-call args/ternary branches, the only places genuine
+// nesting comes from (the additive/multiplicative/unary/power/postfix
+// precedence chain always runs once per primary regardless of how deep
+// the tree ends up, so it isn't what this is bounding). 100 is
+// deliberately generous, not tight: the deepest real formula in this
+// project (Cardano's cubic, samples/ via the playground's own example)
+// doesn't come close to double digits. It exists so a pathologically
+// nested input -- "((((((...))))))" or "f(f(f(f(...))))" thousands
+// deep, plausible if this ever parses genuinely untrusted, unbounded-
+// size text -- fails with one clear, controlled error instead of a raw
+// "Maximum call stack size exceeded" RangeError once the real JS stack
+// (which this sits comfortably below at 100) actually gives out.
+const MAX_EXPRESSION_DEPTH = 100;
+
 class Parser {
     // `label` -- see tokenizeSegment above; also threaded through to
     // holeToNode so a bad interpolation inside `` fn`...` `` reports
@@ -164,6 +184,7 @@ class Parser {
         this.source = source;
         this.i = 0;
         this.label = label;
+        this.depth = 0;
     }
 
     peek() {
@@ -201,8 +222,22 @@ class Parser {
         throw new Error(`${this.label}: ${message} -- found ${tokDesc} at position ${t.pos} in \`${this.source}\``);
     }
 
+    // Every recursive re-entry (a parenthesized group, a function-call
+    // argument, a ternary's then/else branch) goes through here, so
+    // tracking depth at this ONE point -- not at every precedence-level
+    // method, which would overcount a wide-but-shallow expression like
+    // "a + b + c + ..." as if it were deeply nested -- correctly bounds
+    // genuine nesting without rejecting a merely long one.
     parseExpression() {
-        return this.parseTernary();
+        this.depth++;
+        if (this.depth > MAX_EXPRESSION_DEPTH) {
+            this.error(`expression nested too deeply (max ${MAX_EXPRESSION_DEPTH} levels of parens/calls/ternaries)`);
+        }
+        try {
+            return this.parseTernary();
+        } finally {
+            this.depth--;
+        }
     }
 
     // Only place a comparison is ever accepted -- matches cmp()'s own
@@ -270,7 +305,7 @@ class Parser {
     // into `unary`, not `power`, which is also what lets the exponent
     // itself carry a leading unary minus (2^-1 = 0.5).
     parsePower() {
-        const base = this.parsePrimary();
+        const base = this.parsePostfix();
         if (this.isOp("^")) {
             this.next();
             const exponent = this.parseUnary();
@@ -279,6 +314,26 @@ class Parser {
         return base;
     }
 
+    // Postfix "." field access (b.rx, chainable: a.b.c) -- binds tighter
+    // than "^", same as function-call parens already do inside
+    // parsePrimary. Accepted generally here, for any primary, same "defer
+    // semantic validation" precedent call() already follows for unknown
+    // function names -- whether `target` actually resolves to something
+    // with that field is checked later, by macros.js's expandMacros(),
+    // which is the only thing that ever consumes a "field" node (see its
+    // and ast.js's own comments).
+    parsePostfix() {
+        let node = this.parsePrimary();
+        while (this.isOp(".")) {
+            this.next();
+            const t = this.peek();
+            if (t.type !== "IDENT") this.error('expected a field name after "."');
+            this.next();
+            node = field(node, t.value);
+        }
+        return node;
+    }
+
     parsePrimary() {
         const t = this.peek();
         if (t.type === "NUMBER") {

package/fn.js

@@ -14,7 +14,13 @@
 //   signature  := IDENT "(" (IDENT ("," IDENT)*)? ")" ":"
 //   stmt       := "let" IDENT "=" expression ";"
 //   returnStmt := "return" expression ";"
-//               | "return" "{" IDENT ":" expression ("," IDENT ":" expression)* "}" ";"
+//               | "return" "{" field ("," field)* "}" ";"
+//   field      := IDENT (":" expression)?
+//
+// A field with no ":" is shorthand for "name: name" (return { rx, ry, rz };
+// means return { rx: rx, ry: ry, rz: rz };) -- same convention JS object
+// literals use for a property whose value is a same-named variable, and
+// fields can freely mix shorthand and explicit form in one return.
 //
 // "let"/"return" are recognized contextually -- an IDENT token whose
 // value happens to be "let"/"return" at statement-start position. They
@@ -40,7 +46,7 @@
 // was a deliberate API choice, not an oversight -- see the GitHub issue
 // this shipped from for the alternative considered (a separate,
 // always-full-definition tag) and why this was preferred.
-const { letChain, outputs } = require("./ast.js");
+const { letChain, outputs, v } = require("./ast.js");
 const { Parser, tokenizeSegment } = require("./expr.js");
 
 function isKeyword(parser, word) {
@@ -73,7 +79,15 @@ function parseReturnStatement(parser) {
         const fields = {};
         const readField = () => {
             const name = expectIdent(parser, 'as an output name inside "return { ... }"');
-            parser.expectOp(":");
+            // No ":" -- shorthand for "name: name" (return { rx, ry, rz };
+            // means return { rx: rx, ry: ry, rz: rz };), matching JS object
+            // literal shorthand. Explicit ":" still works, and either form
+            // can appear anywhere in the same field list.
+            if (!parser.isOp(":")) {
+                fields[name] = v(name);
+                return;
+            }
+            parser.next(); // consume ":"
             fields[name] = parser.parseExpression();
         };
         if (!parser.isOp("}")) {
@@ -172,4 +186,9 @@ function fn(strings, ...values) {
     return node;
 }
 
-module.exports = { fn };
+// parseProgram is also exported for load-expr.js: loading a .expr file
+// means parsing zero or more of these back-to-back over one shared token
+// stream (see load-expr.js's own header comment), which needs the same
+// "signature? stmt* returnStmt" grammar this file already implements --
+// reused directly, not forked.
+module.exports = { fn, parseProgram };