exprforge 0.5.1 → 0.7.0

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
 
@@ -31,8 +32,15 @@ dependencies.
 
 **[▶ Try it live](https://theraccoonbear.github.io/exprforge/)** — write
 a formula in the browser and watch it emitted across every target
-language at once, no install required. Runs the real, current library
-(see `playground/`), not a frozen demo build.
+language at once, no install required, or switch to the Differentiation
+tab to get a formula's derivative and a numeric spot-check side by side.
+Runs the real, current library (see `playground/`), not a frozen demo
+build.
+
+Every open pull request also gets its own live preview of the
+playground, deployed automatically to
+`https://theraccoonbear.github.io/exprforge/pr-<N>/` and linked in a
+comment on the PR (see `.github/workflows/deploy-pr-preview.yml`).
 
 ## Motivation
 
@@ -67,7 +75,9 @@ Two shapes of real use this tends to fall into:
 **What it does**: turns one small, pure-arithmetic AST into
 identical-behavior source text for 16 real target languages, a native
 evaluator, and its own readable printer — all from the same tree, walked
-once per target.
+once per target. Symbolic differentiation (`differentiate`) works over
+that same AST too, so a derivative is just another tree, emittable and
+evaluable exactly the same way.
 
 **What it deliberately won't do** — not gaps waiting on a future
 release, but a boundary held on purpose everywhere in this project:
@@ -140,13 +150,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 +165,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
@@ -310,6 +334,53 @@ validate against), a wrong argument *count* is a structurally malformed
 call regardless of target, checked unconditionally at the same tier as
 `checkUnboundVars` — see `primitives.js`.
 
+## Symbolic differentiation (`differentiate`)
+
+```js
+const { fn, differentiate, emit, evaluate } = require("exprforge");
+
+const f = fn`
+    f(x):
+    return x^2 * sin(x);
+`;
+const df = { name: "df_dx", params: f.params, body: differentiate(f.body, "x") };
+
+console.log(emit(df, "python").source);
+console.log(evaluate(df, [Math.PI])); // -π² ≈ -9.8696
+```
+
+`differentiate(node, varName)` returns an ordinary AST node — the
+symbolic derivative of `node` with respect to `varName` — in the exact
+same representation as everything else, so it's emittable to all 18
+targets via `emit()`/`emitMany()` and evaluable via `evaluate()`
+unchanged. The input is never mutated.
+
+- **Covers every differentiable primitive**: sum/difference/product/
+  quotient rule, plus the chain rule for `sqrt abs sin cos tan asin acos
+  atan log log2 log10 exp pow atan2 min max hypot` (`pow` picks power
+  rule, exponential rule, or the general product-and-chain-rule case,
+  depending on which side of `^` actually varies with respect to
+  `varName`).
+- **`floor ceil round trunc sign` throw** at differentiation time, with a
+  clear error naming the offending call — these are piecewise-constant/
+  discontinuous primitives with no meaningful derivative, so this fails
+  loudly instead of silently producing a wrong AST.
+- **Output is simplified, not the raw mechanical rules verbatim.** A
+  bottom-up pass folds constant subtrees (`num op num` → `num`) and
+  eliminates arithmetic identities (`x + 0`, `x * 1`, `x / 1`, `x^0`,
+  `x^1`, `0 - x`) to a fixpoint, so a real formula's derivative doesn't
+  come back buried in the `* 1`/`+ 0` swell every mechanical
+  product/chain rule application produces.
+- **Verified numerically, not hand-checked algebraically** — every rule's
+  test asserts the symbolic result against a central-difference
+  approximation at several sample points (see `test/differentiate.test.js`),
+  the same "proof by running" approach this project already uses for
+  round-tripping expr syntax (see "Testing").
+
+Try it interactively in the [live playground](https://theraccoonbear.github.io/exprforge/)'s
+Differentiation tab — enter a formula, see the derivative and a numeric
+spot-check side by side.
+
 ## Math utilities (`exprforge/math`)
 
 A separate, additive export — `require("exprforge")` is unchanged — of
@@ -770,13 +841,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 +872,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 +909,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 +1079,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/differentiate.js

@@ -0,0 +1,345 @@
+// exprforge/differentiate.js
+//
+// Symbolic differentiation: differentiate(node, varName) returns an AST
+// node representing the derivative of `node` with respect to `varName`.
+//
+// The result is an ordinary AST in the exact same representation as
+// everything else -- emittable to all 18 targets via emit()/emitMany()
+// unchanged, and evaluable via evaluate() for the numerical verification
+// the issue describes (central-difference proof).
+//
+// Scope: all differentiable primitives in the AST grammar.
+// Non-differentiable operations (floor, ceil, round, trunc, sign) throw
+// with a clear error at differentiation time rather than silently
+// producing a wrong result.
+//
+// Design notes:
+//   - differentiateRaw() is purely mechanical -- product/quotient/chain
+//     rules produce expression swell (terms like `* 1`, `+ 0`) verbatim,
+//     which keeps every rule obviously correct by inspection. simplify()
+//     (below) is a separate bottom-up pass over that raw output --
+//     constant folding plus arithmetic-identity elimination -- run
+//     automatically by the exported differentiate(), so callers never
+//     see the raw swell. A standalone, general-purpose version of this
+//     (usable on any AST, not just differentiate()'s output) is issue #9.
+//   - Every rule is structural: it only looks at node.type and recurses.
+//     No alpha-renaming, no capture-avoiding substitution -- the output
+//     is a fresh tree built from the input's subterms, never mutating
+//     the input.
+
+const { num, v, bin, call, add, mul, sub, div, neg, select, cmp } = require("./ast.js");
+
+// The non-differentiable built-in primitives. These are piecewise-constant
+// or discontinuous -- no meaningful derivative exists. Throwing here
+// catches the mistake at differentiation time rather than silently
+// producing a semantically wrong AST that happens to evaluate.
+const NON_DIFFERENTIABLE = new Set(["floor", "ceil", "round", "trunc", "sign"]);
+
+// differentiate(node, varName) -> Node
+//
+// Returns the symbolic derivative of `node` with respect to the variable
+// named `varName`. The input is never mutated.
+function differentiate(node, varName) {
+    return simplify(differentiateRaw(node, varName));
+}
+
+function differentiateRaw(node, varName) {
+    switch (node.type) {
+        // d/dx c = 0
+        case "num":
+            return num(0);
+
+        // d/dx x = 1, d/dx y = 0
+        case "var":
+            return node.name === varName ? num(1) : num(0);
+
+        // Binary arithmetic: product rule, quotient rule, sum/difference rule
+        case "bin":
+            return differentiateBin(node, varName);
+
+        // Function calls: chain rule + one derivative rule per intrinsic
+        case "call":
+            return differentiateCall(node, varName);
+
+        // select/cmp: differentiate both branches (both are always
+        // evaluated by design -- this is a value, not a branch). The
+        // condition's derivative is irrelevant (it selects, not computes).
+        case "select":
+            return select(
+                node.cond,
+                differentiateRaw(node.then, varName),
+                differentiateRaw(node.else, varName),
+            );
+
+        default:
+            throw new Error(
+                `differentiate(): unexpected node type "${node.type}" -- ` +
+                `"let"/"outputs"/"field" must already be resolved by expandMacros/collectLets before differentiation`,
+            );
+    }
+}
+
+function differentiateBin(node, varName) {
+    const { op, left, right } = node;
+    const dl = differentiateRaw(left, varName);
+    const dr = differentiateRaw(right, varName);
+
+    switch (op) {
+        // d/dx (f + g) = f' + g'
+        case "+":
+            return add(dl, dr);
+
+        // d/dx (f - g) = f' - g'
+        case "-":
+            return sub(dl, dr);
+
+        // Product rule: d/dx (f * g) = f' * g + f * g'
+        case "*":
+            return add(mul(dl, right), mul(left, dr));
+
+        // Quotient rule: d/dx (f / g) = (f' * g - f * g') / g²
+        case "/":
+            return div(
+                sub(mul(dl, right), mul(left, dr)),
+                mul(right, right),
+            );
+
+        default:
+            throw new Error(`differentiateBin(): unknown op "${op}"`);
+    }
+}
+
+function differentiateCall(node, varName) {
+    const { name, args } = node;
+
+    if (NON_DIFFERENTIABLE.has(name)) {
+        throw new Error(
+            `differentiate(): "${name}" is not differentiable (piecewise-constant/discontinuous)`,
+        );
+    }
+
+    // Unary primitives: chain rule is d/dx f(u) = f'(u) * u'
+    // where u = args[0] and u' = differentiate(args[0], varName).
+    //
+    // Binary primitives: chain rule is d/dx f(u, v) = (∂f/∂u * u' + ∂f/∂v * v')
+    // where partial derivatives are computed treating the other arg as constant.
+
+    const du = differentiateRaw(args[0], varName);
+
+    switch (name) {
+        // d/dx sqrt(u) = u' / (2 * sqrt(u))
+        case "sqrt":
+            return div(du, mul(num(2), call("sqrt", args[0])));
+
+        // d/dx abs(u) = u' * sign(u)
+        case "abs":
+            return mul(du, call("sign", args[0]));
+
+        // d/dx sin(u) = u' * cos(u)
+        case "sin":
+            return mul(du, call("cos", args[0]));
+
+        // d/dx cos(u) = -u' * sin(u)
+        case "cos":
+            return mul(neg(du), call("sin", args[0]));
+
+        // d/dx tan(u) = u' / cos²(u) = u' * (1 + tan²(u))
+        // Using 1/cos² form via sec² identity avoids needing a sec builtin.
+        case "tan":
+            return mul(du, add(num(1), mul(call("tan", args[0]), call("tan", args[0]))));
+
+        // d/dx asin(u) = u' / sqrt(1 - u²)
+        case "asin":
+            return div(du, call("sqrt", sub(num(1), mul(args[0], args[0]))));
+
+        // d/dx acos(u) = -u' / sqrt(1 - u²)
+        case "acos":
+            return div(neg(du), call("sqrt", sub(num(1), mul(args[0], args[0]))));
+
+        // d/dx atan(u) = u' / (1 + u²)
+        case "atan":
+            return div(du, add(num(1), mul(args[0], args[0])));
+
+        // d/dx log(u) = u' / u
+        case "log":
+            return div(du, args[0]);
+
+        // d/dx log2(u) = u' / (u * ln(2))
+        case "log2":
+            return div(du, mul(args[0], num(Math.LN2)));
+
+        // d/dx log10(u) = u' / (u * ln(10))
+        case "log10":
+            return div(du, mul(args[0], num(Math.LN10)));
+
+        // d/dx exp(u) = u' * exp(u)
+        case "exp":
+            return mul(du, call("exp", args[0]));
+
+        // d/dx pow(u, v) -- three cases:
+        //   1. v is constant: d/dx u^v = v * u^(v-1) * u'  (power rule)
+        //   2. u is constant: d/dx c^v = c^v * ln(c) * v'   (exponential rule)
+        //   3. Both vary:      d/dx u^v = u^v * (v' * ln(u) + v * u'/u)
+        case "pow": {
+            const dv = differentiateRaw(args[1], varName);
+            const uIsConst = isConstant(args[0], varName);
+            const vIsConst = isConstant(args[1], varName);
+
+            if (vIsConst) {
+                // Power rule: v * u^(v-1) * u'
+                return mul(
+                    mul(args[1], call("pow", args[0], sub(args[1], num(1)))),
+                    du,
+                );
+            }
+            if (uIsConst) {
+                // Exponential rule: c^v * ln(c) * v'
+                return mul(
+                    mul(node, call("log", args[0])),
+                    dv,
+                );
+            }
+            // General: u^v * (v' * ln(u) + v * u'/u)
+            return mul(
+                node,
+                add(
+                    mul(dv, call("log", args[0])),
+                    mul(args[1], div(du, args[0])),
+                ),
+            );
+        }
+
+        // d/dx atan2(u, v) = (u' * v - u * v') / (u² + v²)
+        // Partial w.r.t. first arg (u): v / (u² + v²)
+        // Partial w.r.t. second arg (v): -u / (u² + v²)
+        case "atan2": {
+            const dv = differentiateRaw(args[1], varName);
+            const denom = add(mul(args[0], args[0]), mul(args[1], args[1]));
+            return div(
+                sub(mul(du, args[1]), mul(args[0], dv)),
+                denom,
+            );
+        }
+
+        // d/dx min(u, v):
+        //   If u < v: derivative is du (min is u)
+        //   If v < u: derivative is dv (min is v)
+        //   If equal: undefined, but both branches evaluated anyway
+        case "min": {
+            const dv = differentiateRaw(args[1], varName);
+            return select(cmp(args[0], "<", args[1]), du, dv);
+        }
+
+        // d/dx max(u, v):
+        //   If u > v: derivative is du (max is u)
+        //   If v > u: derivative is dv (max is v)
+        case "max": {
+            const dv = differentiateRaw(args[1], varName);
+            return select(cmp(args[0], ">", args[1]), du, dv);
+        }
+
+        // d/dx hypot(u, v) = (u * u' + v * v') / hypot(u, v)
+        case "hypot": {
+            const dv = differentiateRaw(args[1], varName);
+            return div(
+                add(mul(args[0], du), mul(args[1], dv)),
+                call("hypot", args[0], args[1]),
+            );
+        }
+
+        default:
+            throw new Error(`differentiate(): unknown call "${name}"`);
+    }
+}
+
+// Check whether a node is a constant with respect to varName -- a num
+// literal, or a var reference to anything OTHER than the differentiation
+// variable. Doesn't recurse into subtrees -- if the node is a call/bin,
+// it's not constant (even if all its leaves are). This is deliberately
+// conservative: we only need to distinguish "definitely constant" (num,
+// unrelated var) from "might not be" (everything else) for the pow()
+// special cases.
+function isConstant(node, varName) {
+    if (node.type === "num") return true;
+    if (node.type === "var") return node.name !== varName;
+    return false;
+}
+
+// Bottom-up algebraic simplification. Handles the expression swell that
+// differentiation rules inevitably produce (terms like `* 0`, `+ 0`,
+// `* 1`, `/ 1`, `^ 0`, `^ 1`). Runs to fixpoint — a single pass can
+// create new simplifiable patterns (e.g. `0 * (x + 0)` → `0 * x` → `0`).
+function simplify(node) {
+    if (!node || typeof node !== "object") return node;
+
+    // Recurse bottom-up first.
+    if (node.type === "bin") {
+        node = { ...node, left: simplify(node.left), right: simplify(node.right) };
+    } else if (node.type === "call") {
+        node = { ...node, args: node.args.map(simplify) };
+    } else if (node.type === "select") {
+        node = {
+            ...node,
+            then: simplify(node.then),
+            else: simplify(node.else),
+            cond: { ...node.cond, left: simplify(node.cond.left), right: simplify(node.cond.right) },
+        };
+    } else {
+        return node; // num, var — nothing to simplify
+    }
+
+    // --- bin node simplifications ---
+    if (node.type === "bin") {
+        const { op, left, right } = node;
+
+        // Constant folding: if both operands are num literals, evaluate.
+        if (left.type === "num" && right.type === "num") {
+            switch (op) {
+                case "+": return num(left.value + right.value);
+                case "-": return num(left.value - right.value);
+                case "*": return num(left.value * right.value);
+                case "/": return num(left.value / right.value);
+            }
+        }
+
+        if (op === "+") {
+            if (left.type === "num" && left.value === 0) return right;
+            if (right.type === "num" && right.value === 0) return left;
+        }
+
+        if (op === "-") {
+            if (right.type === "num" && right.value === 0) return left;
+            if (left.type === "num" && left.value === 0) {
+                // 0 - x → -(x): if x is a num, fold to negated literal
+                if (right.type === "num") return num(-right.value);
+                return mul(num(-1), right);
+            }
+        }
+
+        if (op === "*") {
+            if (left.type === "num" && left.value === 0) return num(0);
+            if (right.type === "num" && right.value === 0) return num(0);
+            if (left.type === "num" && left.value === 1) return right;
+            if (right.type === "num" && right.value === 1) return left;
+            // -1 * x → negated
+            if (left.type === "num" && left.value === -1) return mul(num(-1), right);
+            if (right.type === "num" && right.value === -1) return mul(num(-1), left);
+        }
+
+        if (op === "/") {
+            if (left.type === "num" && left.value === 0) return num(0);
+            if (right.type === "num" && right.value === 1) return left;
+        }
+    }
+
+    // --- call node simplifications ---
+    if (node.type === "call" && node.name === "pow" && node.args.length === 2) {
+        const [base, exp] = node.args;
+        if (exp.type === "num" && exp.value === 0) return num(1);
+        if (exp.type === "num" && exp.value === 1) return base;
+    }
+
+    return node;
+}
+
+module.exports = { differentiate };

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/index.js

@@ -4,6 +4,7 @@ const { forComponents } = require("./util.js");
 const { expr } = require("./expr.js");
 const { fn } = require("./fn.js");
 const { evaluate } = require("./evaluate.js");
+const { differentiate } = require("./differentiate.js");
 const { loadMacro, loadExtern, expandMacros, createRegistry } = require("./macros.js");
 const { loadExpr, loadExprSource } = require("./load-expr.js");
 const emitters = require("./emitters/registry.js");
@@ -132,6 +133,9 @@ module.exports = {
     // A native interpreter over the AST -- evaluate(fn, args) computes a
     // result directly in JS, no codegen/compile step. See evaluate.js.
     evaluate,
+    // Symbolic differentiation: differentiate(node, varName) returns an
+    // AST node for the derivative. See differentiate.js.
+    differentiate,
     // Register a macro: a name usable inside fn`...`/expr`...` text
     // beyond the built-in primitives, inline-expanded at build time,
     // never emitted as a real call. See macros.js's own header comment.

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.1",
+  "version": "0.7.0",
   "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",
@@ -16,6 +16,7 @@
     "expr.js",
     "fn.js",
     "evaluate.js",
+    "differentiate.js",
     "macros.js",
     "primitives.js",
     "load-expr.js",
@@ -25,8 +26,10 @@
     "math/"
   ],
   "scripts": {
+    "dev": "npm run dev --prefix playground",
     "build": "node build.js",
     "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude=\"test/**\"",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -35,7 +38,9 @@
     "math",
     "cross-language",
     "transpiler",
-    "qb64"
+    "qb64",
+    "differentiation",
+    "calculus"
   ],
   "license": "MIT",
   "author": {