nanvm-lib: one source of truth for operator tests - #1489

Approving. Reviewed at bcef2af against main (03126e4). CI is green across all platforms.

This is a nicer shape than the coverage table it replaces, and the part that makes it work is that the generator is checkable. So that is what I checked hardest.

The generated file is what the generator produces

I deleted nanvm-lib/tests/test/generated.rs outright and regenerated from scratch:

$ rm nanvm-lib/tests/test/generated.rs
$ npm run ci-update
$ diff generated.committed.rs nanvm-lib/tests/test/generated.rs
BYTE-IDENTICAL
$ git status --porcelain
(empty)

So the committed copy is reproducible, and the CI drift check (git add -A && git diff --cached --exit-code) has something real to bite on now that ci-update chains the generator.

The generated cases actually run, and name themselves when they fail

Worth confirming rather than assuming, because cargo test reports the whole integration target as one test:

Running unittests src/lib.rs   → 110 passed
Running tests/test/main.rs     → 1 passed
Doc-tests nanvm_lib            → 5 passed

That single test is gen_test, and generated::all::<A>() is its first call — so all 179 cases execute inside it. The design only holds up if a failure is diagnosable, and it is: check_eq asserts with the case name as the message (assert_eq!(a == b, expected, "{case}")), including a "{case} reversed" for the symmetric direction.

The divergence mechanism does what the description says

This is the claim I most wanted to see hold, since it is what replaces the stale table. Traced end to end for the bigint coercion gap:

• module.f.mjs carries the two cases with rust: hexadecimalBigint.
• generated.rs emits them commented out, each above a // TODO: naming nanvm-lib/todo/bigint-decimal-string-coercion.md.
• proof.f.mjs has no reference to rust at all, so it does not skip them — and the suite shows both running and passing against the JS engine:

proof.stringCoercion.bigint(): ok
proof.stringCoercion.negativeBigint(): ok

• The todo file exists with a real problem statement pointing at StringCoercion::bigint.

Divergence really is a property of the case, and deleting the reason plus regenerating really is what closes it.

Everything else

• npx tsc clean. fjs test — 2481 pass / 0 fail, matching the claimed number exactly (2356 before).
• cargo fmt -- --check clean. cargo clippy -- -D warnings — the command as stated, and the one fjs/ci/rust/module.f.mjs generates — passes.
• Markdown links improve: 144 broken on main, 141 here. The three fixed are the deleted todo's own links, and nothing new broke. No dangling references to the removed file.
• .gitattributes marking generated.rs as linguist-generated=true is a good touch — it collapses the file in diffs and keeps it out of language stats.
• CHANGELOG entry is present and correctly not marked breaking, since this is test infrastructure.

old_eq being dropped is justified: the generated eq group covers it.

Two notes on my own verification, for the record

• I could not check npm run cov. On this machine (Node v23.11.0) node --test discovers zero test files, so a bare npm run cov prints tests 0 and then a vacuous 100.00 — and it does the identical thing on origin/main, so it is my Node version, not anything here. AGENTS.md §1.4 lists Node 22+ and CI runs 22/24/26. Flagging only so nobody reads my approval as having confirmed that particular line.
• cargo clippy --all-targets (stricter than the stated command or CI) surfaces clippy::eq_op at nanvm-lib/src/vm/mod.rs:40 — assert_eq!(x, x). That is pre-existing on main and this PR does not touch nanvm-lib/src, so it is out of scope here; mentioning it only in case it is worth its own cleanup someday.

Re-approving at 2b8c739. My earlier approval was against bcef2af, and the head has since picked up two main merges (bringing in #1488 and #1490) plus the go commit.

go is the adaptation #1488 forced: fjs/effects/node migrated to .f.mjs on main, so tests/update/module.f.ts and proof.f.ts now take runtime values from effects/node/module.f.mjs and types from effects/node/types.ts, split into separate import statements. Exactly the mechanical change that migration requires, and nothing in this PR's own design moved.

Since update/module.f.ts is the effectful shell that writes the generated file, I re-ran the check that matters rather than assuming the merge was inert:

$ rm nanvm-lib/tests/test/generated.rs
$ npm run ci-update
$ diff gen.committed.rs nanvm-lib/tests/test/generated.rs
BYTE-IDENTICAL
$ git status --porcelain
(empty)

Still reproducible, still clean for the CI drift check.

Everything else re-verified at this head:

• npx tsc clean; 2482 pass / 0 fail — one more than the 2481 I saw before, which is #1490's new btree case arriving via main.
• cargo fmt -- --check, cargo clippy -- -D warnings clean; cargo test 110 unit + 1 integration + 5 doctests, all passing.
• Markdown links 141 vs main's 144 — still three better, none added, 0 label/target mismatches.
• MERGEABLE, CI green.

The two caveats from my first review still stand as written: I can't exercise npm run cov on this machine (Node 23 discovers no test files, identically on main), and the clippy::eq_op that --all-targets surfaces in nanvm-lib/src/vm/mod.rs is pre-existing and untouched here.

Re-approving at bd7228e. Address review is a real restructure, not a touch-up, so I re-ran everything rather than trusting the earlier pass.

The move is the right call and it is complete

FunctionalScript sources leave the Rust crate: nanvm-lib/tests/{module.f.mjs, types.ts, rust/, update/, proof.f.mjs} become fjs/nanvm/…, with the generic Rust printer split out to fjs/media/rust/. nanvm-lib/ is now only Rust plus the generated file and its harness, which is the boundary you would want.

I checked the move left nothing behind: no reference anywhere — markdown, JSON, .mjs, .ts, or .rs — still points at the old nanvm-lib/tests/ FunctionalScript paths. ci-update follows to ./fjs/nanvm/update/module.f.ts.

The generator still round-trips from its new home

The thing most likely to break in a move like this:

$ rm nanvm-lib/tests/test/generated.rs
$ npm run ci-update
$ diff gen.committed.rs nanvm-lib/tests/test/generated.rs
BYTE-IDENTICAL
$ git status --porcelain
(empty)

And the diff on generated.rs and harness.rs between the two heads is only the provenance comment (nanvm-lib/tests/module.f.mjs → fjs/nanvm/module.f.mjs). Not one generated statement changed, so the restructure is genuinely a relocation rather than a rewrite of what gets tested.

Re-verified at this head

• npx tsc clean; 2484 pass / 0 fail — up from 2482, the two new proofs being fjs/media/rust and fjs/nanvm/rust. 195 cases now run across the fjs/nanvm and fjs/media/rust proofs.
• cargo fmt -- --check and cargo clippy -- -D warnings clean; cargo test 110 unit + 1 integration + 5 doctests, all passing.
• Links 141 against main's 144 — still three better, none added, 0 label/target mismatches.
• MERGEABLE, CI green.

Both caveats from my first review are unchanged: npm run cov stays unverifiable on this machine (Node 23 discovers no test files, identically on main), and the clippy::eq_op in nanvm-lib/src/vm/mod.rs that --all-targets surfaces is pre-existing and still untouched here.

Re-approving at cb4f230. The only change since bd7228e is the main merge that brings in #1491 — no new work of its own — so this pass was about confirming the merge didn't break anything rather than re-reviewing the design.

The merge touched package.json from both sides and resolved correctly, which is the one thing here that could have gone quietly wrong: #1489 repoints ci-update at the relocated generator while #1491 repoints dev-update and index-html at migrated modules. All three survived:

ci-update:  node ./fjs/module.ts ci && node ./fjs/module.ts r ./fjs/nanvm/update/module.f.ts
dev-update: node ./fjs/module.ts r ./fjs/dev/update/module.f.mjs
index-html: node ./fjs/module.ts r ./fjs/website/module.f.mjs

A wrong resolution here type-checks and tests clean, so I ran them: dev-update and index-html both execute, and ci-update still round-trips the generator byte-identical with a clean tree.

Re-verified at this head:

• npx tsc clean; 2484 pass / 0 fail.
• Generator: rm generated.rs && npm run ci-update reproduces it byte-for-byte; git status empty.
• cargo fmt -- --check and cargo clippy -- -D warnings clean; cargo test 110 + 1 + 5 passing.
• Links 141 against main's 144 — still three better, none added, 0 label/target mismatches.
• MERGEABLE, CI green.

Same two caveats as before, unchanged: npm run cov is unverifiable on this machine (Node 23, identical behaviour on main), and the pre-existing clippy::eq_op in nanvm-lib/src/vm/mod.rs is untouched here.

Re-approving at e48f98c. One commit: the generated-tests writer itself becomes .f.mjs, with ci-update repointed to match.

That is the one file in this PR whose migration could break the whole mechanism, so the round-trip is the check that matters:

$ rm nanvm-lib/tests/test/generated.rs
$ npm run ci-update
$ diff gen.committed.rs nanvm-lib/tests/test/generated.rs
BYTE-IDENTICAL
$ git status --porcelain
(empty)

The writer runs from its new extension and reproduces the committed file exactly, so the CI drift check still has teeth.

• npx tsc clean; 2484 pass / 0 fail.
• cargo fmt -- --check clean; cargo test 110 + 1 + 5 passing.
• package.json's ci-update follows to ./fjs/nanvm/update/module.f.mjs; dev-update and index-html are untouched and still resolve.
• MERGEABLE.

Caveats unchanged: npm run cov remains unverifiable here (Node 23, same on main), and the pre-existing clippy::eq_op in nanvm-lib/src/vm/mod.rs is untouched.

Re-approving at 348bf4c. Two main merges since e48f98c (pulling in #1492 and #1493) and no new work of its own, so this was a check that the merges left the mechanism intact.

• Generator still round-trips: rm generated.rs && npm run ci-update reproduces it byte-identical, git status empty.
• npx tsc clean; 2484 pass / 0 fail.
• cargo test — all three targets green.
• MERGEABLE.

#1492 landed the EOF = -1 documents and #1493 the fjs/ci migrations; neither disturbs anything here.

Re-reviewed at 2fa156a25ee74d5d2d8ccb97fbb58f292dfb6648. My earlier approval was against
348bf4c, and the rebase onto the post-#1494 main moved enough that I re-ran the whole
battery rather than carrying it forward. Everything holds. Approving again at this head.

JavaScript side. npx tsc --noEmit exits 0 and npm run prepack exits 0 with 0 errors
from a clean tree. npm test gives 2484 pass / 0 fail against main's 2357 — the +127 being
the operator cases. Branch is level with origin/main and GitHub reports MERGEABLE CLEAN.

Generator round-trip. Deleted nanvm-lib/tests/test/generated.rs, ran npm run ci-update, then the repository's own drift gate — git add -A && git diff --cached --exit-code — came back clean. Regeneration is byte-identical, so CI's drift check will pass
and the checked-in file genuinely is the generator's output.

Rust side, using CI's exact invocations: cargo fmt -- --check clean, cargo test green
(110 + 1 + 5), cargo clippy -- -D warnings clean, cargo clippy --release -- -D warnings
clean.

The two things I most wanted to confirm are behavioural rather than structural, so I tested
both rather than reading them.

The single Rust test isn't vacuous. #[test] fn test() running the whole generated suite
through one entry point could in principle pass while exercising nothing. Flipping one
expectation in generated.rs — zeroByNegativeZero from true to false — fails, and
names the case:

assertion `left == right` failed: zeroByNegativeZero
test result: FAILED. 0 passed; 1 failed

So harness.rs's "{case}" message does the work a per-case #[test] would have, which was
the thing that made collapsing to one test acceptable.

The single source of truth is real. Renaming one case in fjs/nanvm/module.f.mjs propagates
to both consumers after npm run ci-update — the new name appears in the generated Rust and
in the JavaScript proof run. One data edit, two consumers, no manual synchronisation, which
is exactly what the PR title claims.

One observation that is explicitly not this PR's problem, recorded only so it isn't
rediscovered later: cargo clippy --all-targets -- -D warnings fails on
nanvm-lib/src/vm/mod.rs:40 with clippy::eq_op for assert_eq!(x, x). That is pre-existing
— origin/main fails identically, this branch touches no files under nanvm-lib/src, and CI
doesn't pass --all-targets, so nothing here regresses. Worth a small cleanup PR of its own
sometime.

Re-approving at 537896b07d3a69cfecd93b3cfe4f4c59fa0f56d3. The only change since the head I
approved is 537896b, a merge of main bringing in #1498 — the PR's own content is
untouched — but the merge moves the tree, so I re-ran the gates rather than assuming.

All green: npx tsc --noEmit 0, npm run prepack 0 errors from a clean tree, and npm test
2495 pass / 0 fail. That count is worth one sanity note: it's up from 2484 at the previous
head by exactly 11, which is #1498's new fjs/media/json/rtti proof arriving via the merge
rather than anything changing here.

Generator round-trip still holds — deleting nanvm-lib/tests/test/generated.rs, running npm run ci-update, and applying the repo's own git add -A && git diff --cached --exit-code
gate comes back clean, so regeneration is byte-identical.

Rust, on CI's exact invocations: cargo fmt -- --check clean, cargo test green (110 + 1 +
5), cargo clippy -- -D warnings and cargo clippy --release -- -D warnings both clean.
GitHub now reports MERGEABLE CLEAN.

I didn't repeat the two behavioural probes from my last pass — that the single #[test] names
its failing case, and that one edit to fjs/nanvm/module.f.mjs propagates to both the
generated Rust and the JavaScript proof — since neither the data, the generator, nor the
harness changed in this merge.

Re-approving at b6e5d24ca99e057e41cc38a9f27e52bef875106a. Same situation as last time: the
only new commit is b6e5d24, a merge of main picking up #1496, whose entire content is a
33-line AGENTS.md addition. The PR's own content is untouched and the branch is now level
with origin/main.

Re-ran the gates anyway since the tree moved: npx tsc --noEmit 0, npm test 2495 pass / 0
fail, generator round-trip still byte-identical under git add -A && git diff --cached --exit-code, cargo test green across all three suites, cargo clippy -- -D warnings clean.

Re-approving at f30a0538c838560a5a465b940168e54f114253fe. Same pattern as the last two
passes: the only new commit is f30a053, a merge of main picking up #1499 and #1500. The
PR's own delta is unchanged at 25 files and the branch is level with origin/main.

Gates re-run on the merged tree: npx tsc --noEmit 0, npm test 2495 pass / 0 fail, generator
round-trip byte-identical under git add -A && git diff --cached --exit-code, cargo fmt -- --check clean, cargo test green across all three suites, cargo clippy -- -D warnings clean.

Re-review at 0148edb, previously approved at f30a053. Short, because the delta is small.

What actually changed since f30a053: two merges of main (b23693f, 0148edb, picking
up #1502 and #1501) plus one real commit, a0a8985 — a comment-only change that moves six
@import tags into the @module header block and adds the required blank line to the two
headers that had none, across fjs/media/rust/proof.f.mjs, fjs/nanvm/{module,proof}.f.mjs,
fjs/nanvm/rust/{module,proof}.f.mjs and fjs/nanvm/update/{module,proof}.f.mjs. No runtime
statement changed. Since main had moved a long way, I re-ran the gates on the merged tree
rather than assuming.

Gates, all from a freshly cleaned tree at 0148edb:

• npx tsc --noEmit — exit 0.
• npm run prepack — exit 0 (both passes).
• npm test — 2495/2495 pass, 0 fail. origin/main at ede2a96 is 2368/2368; +127 is the
  new fjs/nanvm proof surface replacing the deleted nanvm-lib/tests/proof.f.ts, which is
  what this PR is for.
• Rust, with CI's exact invocations: cargo fmt -- --check 0, cargo test 0 (incl. 5
  doc-tests), cargo clippy -- -D warnings 0, cargo clippy --release -- -D warnings 0.
• Generator round-trip: deleted nanvm-lib/tests/test/generated.rs, ran npm run ci-update,
  then the repo's own drift gate git add -A && git diff --cached --exit-code — clean. The
  committed generated file is exactly what the generator produces.
• §4 module header, which is the point of a0a8985: grep -c '@module' on each emitted
  declaration is 1 for all seven touched modules plus fjs/nanvm/types.d.ts, so no header was
  folded into import trivia and lost. No elided and no bare : any anywhere in the emitted
  fjs/nanvm/** or fjs/media/rust/** declarations.
• Link check: broken-link set comparison against main, not just the count — 141 vs main's
  144, and the diff is one-directional. The three that disappear are the dangling
  tests/proof.f.ts, tests/README.md and tests/test.rs references in the now-deleted
  nanvm-lib/todo/single-source-of-truth-for-operator-tests.md. Nothing new is stranded.
• CHANGELOG: single ## Unreleased entry linking only /pull/1489, no issue or todo/ link,
  released sections untouched.

Not verified: coverage. npm run cov reports a vacuous 100.00 over 0 tests in this Node
v23 environment, and does the same on main, so it says nothing about this PR either way.

Nothing to flag. Draft status is not a blocker per your standing instruction. Approving.