exprforge 0.5.0 → 0.6.1

package/README.md

@@ -19,6 +19,7 @@
 [![Zig](https://github.com/theraccoonbear/exprforge/actions/workflows/test-zig.yml/badge.svg)](https://github.com/theraccoonbear/exprforge/actions/workflows/test-zig.yml)
 [![Scheme](https://github.com/theraccoonbear/exprforge/actions/workflows/test-scheme.yml/badge.svg)](https://github.com/theraccoonbear/exprforge/actions/workflows/test-scheme.yml)
 [![COBOL](https://github.com/theraccoonbear/exprforge/actions/workflows/test-cobol.yml/badge.svg)](https://github.com/theraccoonbear/exprforge/actions/workflows/test-cobol.yml)
+[![Test Coverage](https://github.com/theraccoonbear/exprforge/actions/workflows/test-coverage.yml/badge.svg)](https://github.com/theraccoonbear/exprforge/actions/workflows/test-coverage.yml)
 
 ## Brief
 
@@ -140,13 +141,13 @@ editor buffer accepts:
 const { loadExprSource, evaluate, emit } = require("exprforge");
 
 const defs = loadExprSource(`
-cross3(ax, ay, az, bx, by, bz):
+macro cross3(ax, ay, az, bx, by, bz):
   let rx = ay * bz - az * by;
   let ry = az * bx - ax * bz;
   let rz = ax * by - ay * bx;
   return { rx, ry, rz };
 
-crossLength(ax, ay, az, bx, by, bz):
+fn crossLength(ax, ay, az, bx, by, bz):
   let c = cross3(ax, ay, az, bx, by, bz);
   return sqrt(c.rx^2 + c.ry^2 + c.rz^2);
 `);
@@ -155,6 +156,20 @@ evaluate(defs.crossLength, [1, 0, 0, 0, 1, 0]); // 1
 emit(defs.crossLength, "rust").source;          // a real fn crossLength(...) -- no trace of cross3 left
 ```
 
+Every definition starts with `fn` or `macro` — never optional, never
+implied. `fn` means "hand this back to me": `defs.crossLength` exists
+because it's marked `fn`. `macro` means "inline this into whatever
+references it later in this same buffer, but don't hand it back on its
+own": `cross3` is fully usable *inside* `crossLength` — that's the whole
+point — but `defs.cross3` doesn't exist; `Object.keys(defs)` here is just
+`["crossLength"]`. There's no default either way, on purpose: a helper
+you only ever meant as an internal step for something else can't
+accidentally end up looking like part of your file's real, callable
+output just because nothing said otherwise. Mark it `fn` instead if you
+*do* want `cross3` usable standalone too — both marks register the
+definition identically for inlining purposes; the only difference is
+whether it also lands in what this call returns.
+
 `cross3` never appears in `crossLength`'s emitted output, in any target —
 by the time `loadExprSource` returns, `defs.crossLength` is
 self-contained arithmetic, `cross3`'s formula copied in and simplified
@@ -288,7 +303,7 @@ package individually, or together as `samples`):
   fixture exercising every `exprforge/math` helper (see below) in one
   suite.
 - `samples/macro-demo.js` — also not a worked example: a conformance-test
-  fixture specifically for the `loadMacro(name, fn\`...\`)` AST-function
+  fixture specifically for the `` loadMacro(name, fn`...`) `` AST-function
   tier, proving its internal gensym'd let-renaming produces valid
   identifiers on every real target, not just `evaluate()` (which can't
   see codegen at all — see "Macros and externs").
@@ -386,7 +401,7 @@ const rodrigues = fn`
   Safe by construction — if `def` returns real `ast.js` Nodes, the result
   is exactly as trustworthy as anything else this library emits. `def`
   can also be an AST function definition directly (e.g. straight out of
-  `fn\`...\``: `loadMacro("foo", fn\`foo(x): return x * 2;\`)`), sugar
+  `` fn`...` ``: `` loadMacro("foo", fn`foo(x): return x * 2;`) ``), sugar
   for the same thing — this is exactly how "Examples, flashiest first"
   above registers `cross3`.
 
@@ -418,10 +433,10 @@ const rodrigues = fn`
   duplication matters to you.
 
 - **`loadExtern(name, def)`** — `def` is a plain per-target mapping
-  object instead of a function, e.g. `{ evaluate: (x) => ..., js: ([x])
-  => \`myLib.f(${x})\`, zig: ([x]) => \`mylib.f(${x})\` }`. A **real
-  native call**, same mechanism as the 22 built-in primitives — just
-  supplied by you instead of shipped here. Only the targets you provide a
+  object instead of a function, e.g.
+  `` { evaluate: (x) => ..., js: ([x]) => `myLib.f(${x})`, zig: ([x]) => `mylib.f(${x})` } ``.
+  A **real native call**, same mechanism as the 22 built-in primitives —
+  just supplied by you instead of shipped here. Only the targets you provide a
   key for resolve; every other target still throws "no mapping" for that
   name, same as an unmapped primitive. **ExprForge can't verify the named
   symbol actually exists in a given target, or that it behaves
@@ -446,7 +461,7 @@ itself, and here's exactly what happens:
 - **A macro can't call itself, directly or through a cycle.** This is
   enforced two different ways depending on how the macro was defined, and
   it's worth knowing which one applies: a macro defined as an AST
-  function (straight `fn\`...\`` text, or every function in a `.expr`
+  function (straight `` fn`...` `` text, or every function in a `.expr`
   file/buffer) is resolved and **inline-expanded once, at
   registration/load time**, against whatever's registered so far — a
   definition only becomes referenceable *after* it's fully registered,
@@ -770,13 +785,28 @@ grammar above; and that `let`/`return` are ordinary identifiers
 means `v("let") * 2`, not a syntax error, since `expr`'s own grammar has
 no `stmt`/`signature` rules to make either one special.
 
+`loadExprSource`/`loadExpr` (below) parse the exact same `program`
+grammar, repeatedly, over one shared buffer — with one deliberate
+difference: `signature` is no longer optional, and gains a mandatory
+leading keyword:
+
+```
+signature := ("fn" | "macro") IDENT "(" (IDENT ("," IDENT)*)? ")" ":"
+```
+
+`fn`/`macro` are contextual the same way `let`/`return` already are —
+special only in this exact position, ordinary identifiers everywhere
+else (a parameter, or even a signature name, genuinely called `fn` still
+works: `` fn`fn(x): return x * 2;` `` parses as a function named `fn`,
+unaffected, since a *single* `` fn`...` `` call never runs in this
+stricter mode at all — see "Loading a `.expr` file" below for what the
+two keywords mean and why the keyword is mandatory there specifically.
+
 ## Printing an AST back out, and a native evaluator
 
 Two things that fall out of `fn` existing: `emitters.expr` is a real,
 registered target that prints any AST *back out* as `fn`/`expr` source
-text (the reverse of parsing it) — useful for debugging a formula built
-from several composed helpers, or just getting a readable string to log
-or paste into a future `fn`/`expr` call. And `evaluate(fn, args)` (also
+text (the reverse of parsing it). And `evaluate(fn, args)` (also
 exported from the main package) is a native tree-walking interpreter
 over the same AST, computing a result directly in JS with no codegen or
 compile step — the same node types every emitter already handles,
@@ -786,17 +816,36 @@ backed by the real `Math.*` functions.
 const { emit, evaluate } = require("exprforge");
 
 emit(normalize2, "expr").source;
-// "normalize2(x, y):\n  let mag = sqrt(((x^2) + (y^2)));\n  return { nx: (x / mag), ny: (y / mag) };\n"
+// "fn normalize2(x, y):\n  let mag = sqrt(((x^2) + (y^2)));\n  return { nx: (x / mag), ny: (y / mag) };\n"
 
 evaluate(normalize2, [3, 4]);
 // { nx: 0.6, ny: 0.8 }
 ```
 
+Read this output for what it actually is, not as a pretty-printer of
+whatever you originally typed: `expandMacros()` runs before *every*
+emitter, "expr" included (same as Rust's/COBOL's/etc. own `crossLength`
+never mentions `cross3` either — see "Examples, flashiest first" above)
+— so a macro-free formula like `normalize2` above prints back out
+genuinely readable, but a formula built from several composed
+macros/helpers prints its fully-reduced canonical form instead:
+gensym'd internal let names, multi-output fields flattened to
+`name__field`, all of it. That's not a readability regression to fix —
+it's the same "converges on the true, expanded form" property every
+other target already has, just visible here because "expr" is the one
+target whose reduced output happens to also be valid input to itself
+again. What that buys you is real, just not "pretty debug output": a
+concrete, load-bearing way to confirm a composed formula actually
+reduces to what you expect (`test/conformance.test.js`'s own round-trip
+check — print, reparse, re-evaluate, compare — is exactly this, run
+against every sample this project has).
+
 ### Loading a `.expr` file (`loadExpr`)
 
 `loadExpr(path)` goes the other direction from `emit(fn, "expr")` above:
 reads a `.expr` file (that same round-trip text format) and parses it as
-zero or more `name(params): let ...; return ...;` definitions, each
+zero or more `fn name(params): let ...; return ...;` / `macro
+name(params): let ...; return ...;` definitions, each `fn`-marked one
 usable directly with `evaluate()`/`emit()`/`emitMany()` — this is the
 file-backed sibling of `loadExprSource` in "Examples, flashiest first"
 above:
@@ -804,17 +853,23 @@ above:
 ```js
 const { loadExpr, evaluate } = require("exprforge");
 
-const defs = loadExpr("./formulas/vectors.expr");
+const defs = loadExpr("./formulas/vectors.expr"); // "fn hyp(a, b): return sqrt(a^2 + b^2);"
 evaluate(defs.hyp, [3, 4]); // 5
 ```
 
 A function defined earlier in the file is available to a function defined
 **later** in the same file — as an inline macro, the exact same
 "expanded, not called" model `loadMacro` itself uses above (see that
-section for why). Every definition needs a `name(params):` signature line
-(nothing later in the file, or the caller, could refer to one that
-didn't), and a `.expr` file can reference globally loaded macros too, not
-just earlier definitions in the same file — the two sources merge.
+section for why) — **regardless of whether it's marked `fn` or `macro`**.
+The keyword only decides what's in the object this call actually returns:
+`fn` means "hand this back to me too," `macro` means "inline-only, never
+returned on its own" (see "Examples, flashiest first" above for the full
+`cross3`/`crossLength` walkthrough — `cross3` is `macro`, `crossLength`
+is `fn`, and only `defs.crossLength` exists). Neither keyword is optional
+— every definition states one explicitly; a bare `name(params):` with
+neither throws, naming both keywords and what each means. A `.expr` file
+can also reference globally loaded macros, not just earlier definitions
+in the same file — the two sources merge.
 
 `loadExpr(path)` is a thin `fs.readFileSync` wrapper around
 **`loadExprSource(text, label?)`** — the same parser, given source text
@@ -968,6 +1023,27 @@ and a redundant sanity check each time. Unset locally, so a plain
 `npm test` still runs everything your own machine's installed toolchains
 allow.
 
+**Coverage**: `npm run test:coverage` runs the same suite through Node's
+own built-in instrumentation (`--experimental-test-coverage` — no
+external dependency), honoring whatever toolchains are on your machine,
+with no threshold enforced. CI's own "Test Coverage" workflow (badge
+above) is deliberately narrower and stricter: it runs only the
+toolchain-free `Interpreter` slice (`EXPRFORGE_TEST_TARGETS=Interpreter`,
+same filter every `test-*.yml` workflow already uses), gated on a fixed
+threshold, since that's the one environment where the number means the
+same thing on every run — installing zero, one, or a different subset of
+the 17 per-language toolchains would make an aggregate threshold either
+flaky or meaningless. Core logic (`ast.js`/`evaluate.js`/`expr.js`/
+`fn.js`/`index.js`/`load-expr.js`/`macros.js`/`math/`/`primitives.js`/
+`samples/`/`util.js`) sits at 95-100% in every environment, toolchains or
+not; per-target emitter coverage is intentionally excluded from that
+mental model — code that only really runs inside a real compiled/
+interpreted program can't be exercised without that target's own
+toolchain, and that verification already happens for real, by actually
+compiling and running the output, in the 17 other workflows — a lower
+coverage *percentage* there isn't itself a problem this gate is
+positioned to catch.
+
 A few of these needed real debugging to get right, all found by actually
 compiling/running against a real toolchain rather than assumed to work:
 

package/ast.js

@@ -323,6 +323,25 @@ function collectVarRefs(node, refs = new Set()) {
 // emitFunction(), cobol.js's own override) already runs unconditionally,
 // so it's the natural single checkpoint for this too.
 function checkUnboundVars(fn) {
+    // checkUnboundVars is called both internally (every real consumption
+    // path runs it after expandMacros, see macros.js's own comment on
+    // expandMacros) AND directly by callers who want the check on its
+    // own (e.g. the playground's useExprForge.ts) -- unlike the internal
+    // callers, a direct caller hasn't necessarily gone through
+    // expandMacros' own equivalent guard first, so this needs its own
+    // copy: without it, `fn.name` below crashes with a raw "Cannot read
+    // properties of undefined (reading 'name')" for the same "looked up
+    // a macro-only name loadExprSource() never returned" mistake
+    // expandMacros' own guard exists to catch clearly instead.
+    if (!fn || typeof fn !== "object" || typeof fn.name !== "string" || !Array.isArray(fn.params) ||
+        !fn.body || typeof fn.body !== "object" || typeof fn.body.type !== "string") {
+        throw new Error(
+            `checkUnboundVars: expected a {name, params, body} function definition, got ` +
+            `${fn === null ? "null" : typeof fn} -- if this came from a loadExprSource()/loadExpr() result ` +
+            `object, double check the definition you're looking up was actually marked "fn" (exported), not ` +
+            `"macro" (private -- never included in what that call returns)`,
+        );
+    }
     assertSafeIdentifier(fn.name, "fn.name");
     for (const p of fn.params) assertSafeIdentifier(p, "fn.params");
 

package/emitters/exprsyntax.js

@@ -64,8 +64,8 @@ const emitter = new ExprSyntaxEmitter({
     // `` fn`...` `` call, and exactly what the round-trip test reparses
     // with zero unwrapping first.
     //
-    // ALWAYS includes the "name(params):" signature line -- every other
-    // emitter's formatFunction includes the full declaration per
+    // ALWAYS includes the "fn name(params):" signature line -- every
+    // other emitter's formatFunction includes the full declaration per
     // base.js's own documented contract ("Full source text for one
     // function, including any language-specific signature/type/wrapper
     // syntax"); this was the one target that didn't, dropping fn.name/
@@ -75,6 +75,24 @@ const emitter = new ExprSyntaxEmitter({
     // reparsing this emitter's own output via fn() could only ever
     // recover a bare Node, never a runnable {name, params, body}, unlike
     // literally every other target's output being immediately usable.
+    //
+    // Always "fn", never "macro" -- and this is a real, permanent,
+    // one-way loss, not an oversight: fn.name/fn.params/fn.body is ALL
+    // this function ever receives, and "was this originally marked
+    // fn/macro" isn't part of that shape at all (see load-expr.js's own
+    // loop -- the exported/private flag is read once, to decide whether
+    // to copy the result into loadExprSource's returned object, and then
+    // discarded; it was never stored on the def itself, by design --
+    // every def looks identical regardless of how it was produced,
+    // that's the whole "sugar lowers to the same primitives" guarantee).
+    // So there is nothing left here to recover a "macro" marking FROM --
+    // "fn" is simply the only correct thing to print for "you asked to
+    // print this one, standalone" once that context is gone. Same shape
+    // of loss as `2^3` reprinting as `2^3` but `pow(2, 3)` never coming
+    // back as `pow` (see emitExpr's own pow special-case above), or
+    // comments/whitespace never surviving either -- this printer
+    // round-trips VALUES, never original source text/structure.
+    //
     // Body lines (every let, the return) are indented 2 spaces deeper
     // than the signature line itself -- a Python-esque pretty-print
     // convention, not something the parser requires (whitespace is
@@ -83,7 +101,7 @@ const emitter = new ExprSyntaxEmitter({
     // AST comes out reading the same way automatically.
     formatFunction: (fn, bodyStr, letBindings = []) => {
         const body = [...letLines(letBindings), `return ${bodyStr};`].map((line) => `  ${line}`);
-        return [`${fn.name}(${fn.params.join(", ")}):`, ...body].join("\n") + "\n";
+        return [`fn ${fn.name}(${fn.params.join(", ")}):`, ...body].join("\n") + "\n";
     },
     // Each output field gets its own line (4 spaces -- one level deeper
     // than "return {" itself, which sits at the usual 2), rather than
@@ -91,7 +109,9 @@ const emitter = new ExprSyntaxEmitter({
     // this against a hand-formatted multi-output example and noticing
     // the printer didn't follow its own convention once a suite had
     // more than a couple of fields (a real, wide, 5-output formula made
-    // this one very long line instead of something readable).
+    // this one very long line instead of something readable). Signature
+    // line always "fn" here too -- see formatFunction's own comment
+    // above for why (same reasoning, same permanent one-way loss).
     formatSuite: (fn, outputStrs, letBindings = []) => {
         const entries = Object.entries(outputStrs);
         const fieldLines = entries.map(([name, valueStr], i) => {
@@ -99,7 +119,7 @@ const emitter = new ExprSyntaxEmitter({
             return `    ${name}: ${valueStr}${comma}`;
         });
         const lines = [
-            `${fn.name}(${fn.params.join(", ")}):`,
+            `fn ${fn.name}(${fn.params.join(", ")}):`,
             ...letLines(letBindings).map((line) => `  ${line}`),
             "  return {",
             ...fieldLines,

package/fn.js

@@ -28,6 +28,42 @@
 // expr()'s behavior changes: `` expr`let * 2` `` still means
 // v("let") * 2 today, same as before this file existed.
 //
+// parseProgram() has a SECOND, stricter mode -- parseProgram(parser,
+// { requireExportKeyword: true }) -- used only by load-expr.js's
+// repeated-parse loop (loadExprSource()/loadExpr()), never by fn() below.
+// In that mode the grammar becomes:
+//
+//   program    := signature stmt* returnStmt   // no longer optional
+//   signature  := ("fn" | "macro") IDENT "(" (IDENT ("," IDENT)*)? ")" ":"
+//
+// Why this exists, and why it's scoped to load-expr.js specifically: a
+// single fn`...` call never auto-exports anything -- you already hold
+// the one thing it returns, in an ordinary JS variable, and decide
+// yourself what happens to it. loadExprSource()/loadExpr() are different:
+// they parse a WHOLE BUFFER of back-to-back definitions and hand back a
+// {name: FnDef} object covering every one of them, automatically, with
+// no per-definition opt-in -- so a definition meant purely as an internal
+// building block for a later one in the same buffer (e.g. cross3, when
+// only crossLength's fully-inlined result is meant to be used/emitted)
+// used to land in that returned object too, indistinguishable from a
+// definition you actually meant to use standalone. "fn"/"macro" make
+// that choice explicit, per definition, with no default to get wrong:
+// "fn" means "yes, include this in what you hand back"; "macro" means
+// "no -- inline-expand this into whatever references it later in this
+// same buffer, same as loadMacro()'s own AST-fn-def tier, but never
+// return it on its own." Nothing else differs between the two -- both
+// go through the exact same registration path (toMacro/fileRegistry, see
+// load-expr.js), so a "macro"-marked definition is, structurally, no
+// different from one registered via loadMacro(name, fn`...`) directly;
+// the keyword only decides whether load-expr.js's own loop additionally
+// copies the result into the object it returns.
+//
+// A single fn`...` call's own (still-optional) signature line never
+// accepts "fn"/"macro" -- there's nothing there for them to opt out of,
+// so recognizing them would just be unearned ceremony; `` fn`fn(x):
+// return x * 2;` `` still means what it always has, a function literally
+// named "fn", identical to before this mode existed.
+//
 // Duplicate let-names are deliberately NOT checked here -- letChain()
 // doesn't check either (ast.js); collectLets() already does, at
 // emission time. Same "defer semantic validation to emission" precedent
@@ -116,6 +152,12 @@ function parseReturnStatement(parser) {
 // still ends up an error either way, just reported as a missing ":"
 // rather than a missing "return"; not worth deeper lookahead to improve
 // one malformed-input error message.)
+//
+// Only used in fn()'s own (non-strict) mode -- see this file's header
+// comment. requireExportKeyword mode never calls this: a signature is no
+// longer optional there, so there's no "is this a signature or a
+// statement" ambiguity left to resolve by lookahead at all -- see
+// parseProgram below.
 function looksLikeSignature(parser) {
     const t = parser.peek();
     if (t.type !== "IDENT" || t.value === "let" || t.value === "return") return false;
@@ -123,24 +165,56 @@ function looksLikeSignature(parser) {
     return next.type === "OP" && next.value === "(";
 }
 
-function parseSignature(parser) {
-    const name = expectIdent(parser, "as the function name starting a fn`...` signature");
+// `requireExportKeyword` -- see this file's own header comment -- is the
+// ONLY thing that changes here: false (fn()'s own mode, the default)
+// parses exactly the signature grammar this always has, no "fn"/"macro"
+// recognized at all (they're ordinary identifiers there, same as any
+// other word); true (load-expr.js's mode) requires the very first token
+// to literally be "fn" or "macro", consumed here before the name. This
+// couldn't be optional-but-recognized in requireExportKeyword mode
+// without real ambiguity (a definition genuinely named "fn"/"macro"
+// would be indistinguishable from the keyword) -- making it MANDATORY
+// removes that ambiguity entirely instead of needing to resolve it: a
+// signature is required, so the first token is unconditionally expected
+// to be the keyword, full stop.
+function parseSignature(parser, { requireExportKeyword = false } = {}) {
+    let exported = true; // meaningless outside requireExportKeyword mode -- see parseProgram
+    if (requireExportKeyword) {
+        const t = parser.peek();
+        if (t.type !== "IDENT" || (t.value !== "fn" && t.value !== "macro")) {
+            parser.error(
+                'every definition needs to start with "fn" (exported -- included in what this call returns) ' +
+                'or "macro" (private -- inline-expanded into whatever references it later in this same source, ' +
+                'never returned on its own) -- e.g. "fn crossLength(...):" or "macro cross3(...):"',
+            );
+        }
+        exported = t.value === "fn";
+        parser.next(); // consume "fn"/"macro"
+    }
+    const name = expectIdent(parser, "as the function name starting a signature");
     parser.expectOp("(");
     const params = [];
     if (!parser.isOp(")")) {
-        params.push(expectIdent(parser, "as a parameter name in a fn`...` signature"));
+        params.push(expectIdent(parser, "as a parameter name in a signature"));
         while (parser.isOp(",")) {
             parser.next();
-            params.push(expectIdent(parser, "as a parameter name in a fn`...` signature"));
+            params.push(expectIdent(parser, "as a parameter name in a signature"));
         }
     }
     parser.expectOp(")");
     parser.expectOp(":");
-    return { name, params };
+    return { name, params, exported };
 }
 
-function parseProgram(parser) {
-    const signature = looksLikeSignature(parser) ? parseSignature(parser) : null;
+function parseProgram(parser, { requireExportKeyword = false } = {}) {
+    // requireExportKeyword mode: a signature is mandatory, so it's parsed
+    // unconditionally -- parseSignature itself throws a clear error if
+    // the buffer doesn't actually start with "fn"/"macro". Non-strict
+    // (fn()'s own) mode keeps the original "maybe there's no signature
+    // at all" lookahead, completely unchanged.
+    const signature = requireExportKeyword
+        ? parseSignature(parser, { requireExportKeyword: true })
+        : (looksLikeSignature(parser) ? parseSignature(parser) : null);
 
     const bindings = [];
     while (isKeyword(parser, "let")) {
@@ -152,7 +226,16 @@ function parseProgram(parser) {
     const body = parseReturnStatement(parser);
     const result = bindings.length > 0 ? letChain(bindings, body) : body;
 
-    return signature ? { name: signature.name, params: signature.params, body: result } : result;
+    if (!signature) return result;
+    const def = { name: signature.name, params: signature.params, body: result };
+    // `exported` is only ever meaningful to load-expr.js's own loop (the
+    // one caller that runs in requireExportKeyword mode) -- omitted
+    // entirely from fn()'s own return shape below, so a plain fn`...`
+    // call's result is byte-for-byte identical to before this mode
+    // existed; nothing downstream (evaluate()/emit()/checkUnboundVars/...)
+    // has ever known or needed to know about it.
+    if (requireExportKeyword) def.exported = signature.exported;
+    return def;
 }
 
 // Same token-splicing loop expr() uses in expr.js -- see that file's

package/load-expr.js

@@ -4,26 +4,39 @@
 // test/conformance.test.js's assertExprSyntaxRoundTrips) as zero or more
 // function definitions, using the exact same grammar/engine fn`...`
 // already uses (see fn.js's parseProgram), just applied repeatedly
-// instead of once. Two entry points: loadExprSource(text) parses text
-// directly (no filesystem involved -- usable anywhere source text comes
-// from, including a browser); loadExpr(path) reads a real file first and
-// delegates to it.
+// instead of once, in fn.js's stricter requireExportKeyword mode (see
+// its own header comment for the full rationale). Two entry points:
+// loadExprSource(text) parses text directly (no filesystem involved --
+// usable anywhere source text comes from, including a browser);
+// loadExpr(path) reads a real file first and delegates to it.
 //
-// Functions defined earlier are available to functions defined LATER (in
-// the same source) as inline macros -- the exact same "inline expansion,
-// not runtime calls" model loadMacro() itself uses (see macros.js's own
-// header comment), and for the same reasons: no call graph, no linking
-// problem, no runtime coupling. And, structurally, no recursion: a
-// definition is only added to this source's own local registry AFTER
-// it's been fully parsed and expanded (see the loop below), so it's
-// never resolvable through its own name while its own body is being
-// expanded, whether directly or transitively through another
-// not-yet-defined function.
+// Every definition MUST have a "fn name(params):" or "macro name(params):"
+// signature line -- no bare "name(params):" (fn.js's own requireExportKeyword
+// mode rejects it outright), and no signature-less bare-Node definition
+// either (which would have no name for a later definition, or the
+// caller, to refer to it by anyway). "fn" and "macro" are otherwise
+// identical -- both get registered into this source's own local macro
+// registry below, so BOTH are available to whatever's defined later in
+// the same source as an inline macro (the exact same "inline expansion,
+// not runtime calls" model loadMacro() itself uses, see macros.js's own
+// header comment, and for the same reasons: no call graph, no linking
+// problem, no runtime coupling). The ONLY difference: a "macro"
+// definition is never copied into the object this returns -- it exists
+// purely to be inlined into something else in this same source, the
+// same role a helper registered via loadMacro(name, fn`...`) directly
+// already plays; a "fn" definition is both registered AND returned, so
+// it's directly usable on its own (evaluate()/emit()/emitMany()) too.
+// There's no default: every definition states which one it is, so a
+// definition meant only as an internal building block for another one
+// (e.g. cross3, when only crossLength's fully-inlined result actually
+// gets used) can never accidentally show up in what this call hands
+// back just because nothing said otherwise.
 //
-// Each definition MUST have a "name(params):" signature line -- a
-// bare-Node definition with no signature has no name for a later
-// definition (or the caller) to refer to it by, so it can't usefully
-// appear alongside others.
+// And, structurally, no recursion, for either kind: a definition is only
+// added to this source's own local registry AFTER it's been fully parsed
+// and expanded (see the loop below), so it's never resolvable through
+// its own name while its own body is being expanded, whether directly or
+// transitively through another not-yet-defined function.
 const fs = require("node:fs");
 const { Parser, tokenizeSegment } = require("./expr.js");
 const { parseProgram } = require("./fn.js");
@@ -42,19 +55,27 @@ function tokenizeFile(source, label) {
 
 /**
  * Parses `source` (plain text, not a file path -- see loadExpr below for
- * the file-reading variant) as zero or more "name(params): let ...;
- * return ...;" definitions back-to-back, in the same grammar fn`...`
- * uses for one. Returns an object keyed by function name, each value the
- * fully-expanded {name, params, body} -- ready to pass straight into
- * evaluate()/emit()/emitMany(), with every reference to an earlier
- * definition in the same source already inlined (see this file's own
- * header comment). `label` identifies the source in error messages (e.g.
- * a file path, or just "playground" for an in-browser text buffer that
- * was never written to disk at all -- this is the one entry point here
- * that has no `fs` dependency, so it's the one usable from a browser).
+ * the file-reading variant) as zero or more "fn name(params): let ...;
+ * return ...;" / "macro name(params): let ...; return ...;" definitions
+ * back-to-back, in the same grammar fn`...` uses for one (fn.js's
+ * requireExportKeyword mode -- see its own header comment). Returns an
+ * object keyed by the name of every "fn"-marked definition ONLY, each
+ * value the fully-expanded {name, params, body} -- ready to pass
+ * straight into evaluate()/emit()/emitMany(). A "macro"-marked
+ * definition is registered for inlining into later definitions in the
+ * same source (see this file's own header comment) but never appears in
+ * the returned object. `label` identifies the source in error messages
+ * (e.g. a file path, or just "playground" for an in-browser text buffer
+ * that was never written to disk at all -- this is the one entry point
+ * here that has no `fs` dependency, so it's the one usable from a
+ * browser).
  *
- * Throws if any definition has no "name(params):" signature line, or if
- * two definitions share a name.
+ * Throws if any definition doesn't start with "fn"/"macro" (a bare
+ * "name(params):" signature, or no signature at all, are both
+ * rejected), or if two definitions share a name -- regardless of
+ * whether either or both are "fn" vs "macro"; the two share one
+ * namespace, same as loadMacro()/loadExtern() already do for the
+ * process-wide registry.
  *
  * `registry` (see macros.js's createRegistry()) defaults to the
  * process-wide default when omitted -- pass a session's own (see
@@ -66,28 +87,42 @@ function loadExprSource(source, label = "loadExprSource()", registry = undefined
 
     const fileRegistry = new Map(); // name -> {arity, fn, alreadyExpanded} -- see toMacro in macros.js
     const defs = {};
+    // Tracked independently of `defs` -- a "macro"-marked definition
+    // never lands in `defs` at all (see above), so `defs` alone can't
+    // catch two macro-marked definitions (or a macro and a fn) sharing a
+    // name; every parsed name, exported or not, goes through this Set.
+    const seenNames = new Set();
 
     while (parser.peek().type !== "EOF") {
-        const raw = parseProgram(parser);
-        if (!raw || typeof raw.name !== "string") {
-            throw new Error(
-                `${label}: every definition needs a "name(params):" signature line -- found one with no signature`,
-            );
-        }
-        if (defs[raw.name]) {
+        // requireExportKeyword: true -- see fn.js's own header comment.
+        // Throws its own clear error if this definition doesn't start
+        // with "fn"/"macro"; there's no longer a "no signature at all"
+        // case to separately detect here the way there used to be.
+        const raw = parseProgram(parser, { requireExportKeyword: true });
+        if (seenNames.has(raw.name)) {
             throw new Error(`${label}: duplicate function name "${raw.name}" -- names must be unique in one file`);
         }
+        seenNames.add(raw.name);
 
         // Expanded against whatever's already in fileRegistry (earlier
         // definitions in this same source) PLUS every macro/extern
         // registered in `registry` (expandMacros merges both -- see
-        // macros.js).
+        // macros.js). `raw` carries an extra `exported` field (see
+        // fn.js's parseProgram) that expandMacros' own fn-def branch
+        // ignores -- it only ever reads/returns name/params/body, so
+        // `expanded` below comes back with exactly those three keys
+        // regardless.
         const expanded = expandMacros(raw, fileRegistry, registry);
-        defs[raw.name] = expanded;
+        if (raw.exported) {
+            defs[raw.name] = expanded;
+        }
 
         // Available to whatever's defined AFTER this point in the source
         // -- never to itself (expanded above, against fileRegistry
-        // BEFORE this line adds it) or to anything defined earlier.
+        // BEFORE this line adds it) or to anything defined earlier. Both
+        // "fn" and "macro" definitions are registered here identically
+        // -- see this file's own header comment for why "exported" only
+        // ever affects `defs` above, nothing about inlining eligibility.
         // `expanded` has nothing left to resolve (macro calls/field
         // access are already gone), so no extraRegistry/registry needs
         // passing here.

package/macros.js

@@ -688,6 +688,29 @@ function expandBody(node, ctx) {
  * process-wide default ones.
  */
 function expandMacros(fnOrNode, extraRegistry = null, registry = defaultRegistry) {
+    // Every real caller (evaluate(), every emitter's emitFunction()) runs
+    // this first, unconditionally, before touching fnOrNode.type/.name/
+    // .body itself -- so this is the one place positioned to catch a
+    // caller passing something that isn't actually a Node or a
+    // {name, params, body} at all (undefined, null, a typo'd lookup that
+    // silently evaluated to undefined, ...) with ONE clear message,
+    // instead of letting it fall through to expandBody below and crash
+    // with a raw "Cannot read properties of undefined (reading 'type')"
+    // several frames later -- or, worse, having emitMany() (see index.js)
+    // catch and report that same confusing crash once per language,
+    // 18 near-identical unhelpful errors instead of one. Concretely
+    // motivated by the "macro"-marked definitions loadExprSource() never
+    // returns (see load-expr.js) -- a caller looking up a macro-only name
+    // in the returned object gets `undefined` back, and previously the
+    // very next thing that happened with it was exactly this crash.
+    if (!isFnDefShape(fnOrNode) && !isNode(fnOrNode)) {
+        throw new Error(
+            `expandMacros: expected an AST Node ({type: ...}) or a {name, params, body} function ` +
+            `definition, got ${fnOrNode === null ? "null" : typeof fnOrNode} -- if this came from a ` +
+            `loadExprSource()/loadExpr() result object, double check the definition you're looking up was ` +
+            `actually marked "fn" (exported), not "macro" (private -- never included in what that call returns)`,
+        );
+    }
     const ctx = { extraRegistry, aliases: new Map(), registry };
     if (isFnDefShape(fnOrNode)) {
         return { name: fnOrNode.name, params: fnOrNode.params, body: expandBody(fnOrNode.body, ctx) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exprforge",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Author a math expression once as an AST (or readable infix text via expr/fn), emit identical-behavior implementations in JS, TypeScript, Python, C#, Lua, QB64, C, Java, Go, Rust, Perl, PHP, Julia, Fortran, Zig, Scheme, and COBOL, plus a native evaluator and its own readable syntax printer.",
   "main": "index.js",
   "type": "commonjs",
@@ -27,6 +27,7 @@
   "scripts": {
     "build": "node build.js",
     "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude=\"test/**\"",
     "prepublishOnly": "npm test"
   },
   "keywords": [