feat(affinescript-deno-test): AffineScript→WASM→Deno test harness MVP

Adds a new component at
  affinescript-ecosystem/affinescript-deno-test/
that wires AffineScript .affine test files into Deno's test framework.

Pipeline:
  1. discover.ts — walk a root for *_test.affine / *.test.affine
  2. compile.ts — shell out to `affinescript compile ... -o ....wasm`
  3. runner.ts  — load the WASM and register a Deno.test() case

Built on top of the existing @hyperpolymath/affine-js bridge (700 LOC).
This component is ~300 LOC of Deno-test-framework glue only.

Smoke test green: `deno task smoke:test` → 1 passed / 0 failed.

MVP v0.1.0 constraints — all resolvable by small upstream changes to the
AffineScript compiler:
  - One test per file (compiler hardcodes exportable-name allowlist in
    lib/codegen.ml:1725; no pub fn / @export keyword yet).
  - WASI fd_write stub required (compiler imports it unconditionally even
    for pure programs; no-op stub is harmless).
  - Namespaced-imports path bypasses AffineModule (affine-js only supplies
    "env" imports today).

Documented in README.adoc under the "MVP constraints and planned follow-
ups" section so future contributors can see exactly which knobs upstream
needs to turn.

Unblocks the §3c TS→AffineScript migrations once the pub-fn keyword lands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

affinescript-ecosystem/affinescript-deno-test/.gitignore

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Build output — compiled .wasm files are regenerated by compileToWasm
+*.wasm

affinescript-ecosystem/affinescript-deno-test/README.adoc

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= affinescript-deno-test
+:toc:
+:icons: font
+
+A Deno test-framework integration for AffineScript. Compiles `.affine` test
+files to WebAssembly via the standard `affinescript` compiler, loads them
+through the existing `@hyperpolymath/affine-js` bridge, and registers each
+as a `Deno.test()` case so `deno test` reports pass/fail in the usual way.
+
+Part of the https://github.com/hyperpolymath/developer-ecosystem[developer-ecosystem]
+monorepo. Sibling tools in the AffineScript ecosystem live alongside this
+component: `affinescript/` (the compiler — actually mirrored from upstream),
+`affinescriptiser/`, `affinescript-vite/`, `rattlescript/`.
+
+== Status
+
+*MVP v0.1.0.* Minimal working harness, one test per file. See
+<<mvp-constraints>> below for the specific limits and planned follow-ups.
+
+== Quick start
+
+[source,bash]
+----
+# Compile + smoke-test the bundled example:
+deno task smoke:test
+# → hello ... ok (1 passed, 0 failed)
+----
+
+== Writing a test
+
+Each test is a single `.affine` file. The entry point is `fn main() -> Bool`;
+return `true` to pass, `false` to fail. Filename ends in `_test.affine` or
+`.test.affine`.
+
+[source,affine]
+----
+// example/addition_test.affine
+// SPDX-License-Identifier: PMPL-1.0-or-later
+fn main() -> Bool {
+  let result = 2 + 3;
+  result == 5
+}
+----
+
+== Running tests
+
+The public API is `runAll(root)` in `mod.ts`:
+
+[source,typescript]
+----
+// driver.ts
+import { runAll } from "@hyperpolymath/affinescript-deno-test";
+
+await runAll("./tests");
+----
+
+Invoke with `deno test`:
+
+[source,bash]
+----
+deno test --allow-read --allow-run --allow-env driver.ts
+----
+
+The runner:
+
+. Walks `root` for `*_test.affine` / `*.test.affine` files
+. Compiles each via `affinescript compile ... -o ....wasm`
+. Loads the WASM (with a minimal WASI `fd_write` stub — AffineScript codegen
+  imports this unconditionally)
+. Registers a `Deno.test()` case named after the file (stripped of the
+  `_test` suffix) that invokes `main` and checks the Bool return
+
+== CLI (smoke-check)
+
+`cli.ts` is a thin smoke-check that prints discovery + compile results
+without running assertions. Useful for CI pipelines that want to fail fast
+on compile errors before invoking `deno test`.
+
+[source,bash]
+----
+deno run --allow-read --allow-run --allow-env cli.ts ./tests
+# Discovered 3 test file(s):
+#   ✓ tests/foo_test.affine → tests/foo_test.wasm
+#   ✓ tests/bar_test.affine → tests/bar_test.wasm
+#   ...
+----
+
+== Configuration
+
+* `AFFINESCRIPT_BIN` env var — absolute path to the `affinescript` compiler.
+  Default: `/var/mnt/eclipse/repos/developer-ecosystem/nextgen-languages/affinescript/_build/install/default/bin/affinescript`
+  (the local dev build). Override when the compiler is installed elsewhere
+  or on `$PATH`.
+
+[[mvp-constraints]]
+== MVP constraints (v0.1.0) and planned follow-ups
+
+Three limits exist only because of the current AffineScript compiler's
+state. All are resolvable with small upstream changes.
+
+=== One test per file
+
+The AffineScript codegen (`lib/codegen.ml` line 1725) hardcodes the
+exportable-name allowlist to
+
+[source,ocaml]
+----
+let export_names = ["main"; "init_state"; "step_state"; "get_state"; "mission_active"]
+----
+
+with no `pub fn` / `@export` / `#[export]` keyword. Any function not on that
+list is internal to the module and cannot be invoked from JS. The harness
+therefore uses `main` as the one sanctioned test slot.
+
+*Planned follow-up:* extend the compiler with a `pub fn` keyword (parser +
+AST + codegen). Once in place, the harness switches to the original design
+of multi-test-per-file via a `test_*` naming convention.
+
+=== WASI `fd_write` imported unconditionally
+
+Every AffineScript WASM output imports `wasi_snapshot_preview1.fd_write`
+even when the program uses no IO. The harness provides a minimal no-op
+stub so tests instantiate cleanly.
+
+*Planned follow-up:* upstream compiler change so pure programs (no `effect
+IO`) skip the WASI import entirely. Until then, the stub is correct and
+harmless.
+
+=== `@hyperpolymath/affine-js` only supplies `env` imports
+
+The existing bridge's `AffineModule.fromBytes` merges custom imports under
+the `env` module key only. For WASM modules that import from a non-`env`
+module (e.g. `wasi_snapshot_preview1`), the harness bypasses `AffineModule`
+and uses raw `WebAssembly.instantiate` plus its own WASI stub. The Bool
+return is unmarshalled by hand (AffineScript compiles `Bool` → i32, 0/1).
+
+*Planned follow-up:* extend `affine-js` to accept a `namespacedImports:
+Record<string, Record<string, ImportValue>>` option, then unify both paths
+behind `AffineModule`.
+
+== Why AffineScript rather than ReScript?
+
+ReScript is the estate's default TypeScript replacement and has a mature
+Deno integration (see `fireflag`). The AffineScript path exists because
+AffineScript has stronger semantics for:
+
+* affine / quantitative types (resource lifecycle tracking)
+* algebraic effects (explicit side-effect boundaries)
+* row polymorphism (extensible records)
+
+Test suites that want to *demonstrate* these properties — e.g. "this
+resource is consumed exactly once", "this protocol sequence is honoured" —
+are a natural fit for AffineScript. Plain behavioural tests can continue
+in ReScript; there's no migration pressure either direction.
+
+The trade-off today: AffineScript's compiler matures while ReScript's is
+mature, so this harness carries the MVP constraints above. As the compiler
+gains `pub fn` / effect-conditional WASI imports / better bridge ergonomics,
+the harness sheds them.
+
+== License
+
+PMPL-1.0-or-later. See the repository root LICENSE file.
+Legal fallback: MPL-2.0 (automatic, per the hyperpolymath License Policy
+Rule 2 in `~/.claude/CLAUDE.md`).

affinescript-ecosystem/affinescript-deno-test/cli.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// affinescript-deno-test: CLI entry
+//
+// Usage:
+//   deno run --allow-read --allow-run --allow-env cli.ts <root>
+//   deno run --allow-read --allow-run --allow-env cli.ts ./tests
+//
+// The CLI is a thin wrapper — the actual test registration happens via
+// runAll() which calls Deno.test(). To see reporting, invoke via `deno test`
+// on a driver script that imports runAll, rather than running this module
+// standalone.
+//
+// This file is primarily here so `deno run cli.ts <root>` works as a
+// smoke-test of discovery + compile (it prints the source list + compile
+// results without actually running assertions — that requires deno test).
+
+import { compileToWasm } from "./lib/compile.ts";
+import { discoverTestFiles } from "./lib/discover.ts";
+
+function usage(): never {
+  console.error(
+    "Usage: deno run --allow-read --allow-run --allow-env cli.ts <root>\n" +
+      "\n" +
+      "Discovers *_test.affine files under <root>, compiles each to .wasm,\n" +
+      "and prints the compile results. To actually run the tests, invoke\n" +
+      "`deno test` on a driver script that imports runAll() from mod.ts.",
+  );
+  Deno.exit(2);
+}
+
+if (import.meta.main) {
+  const root = Deno.args[0];
+  if (!root) usage();
+
+  const sources = await discoverTestFiles(root);
+  if (sources.length === 0) {
+    console.error(`No *_test.affine files found under ${root}`);
+    Deno.exit(1);
+  }
+
+  console.log(`Discovered ${sources.length} test file(s):`);
+  for (const source of sources) {
+    try {
+      const wasm = await compileToWasm(source);
+      console.log(`  ✓ ${source} → ${wasm}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  ✗ ${source}\n    ${message}`);
+      Deno.exit(1);
+    }
+  }
+}

affinescript-ecosystem/affinescript-deno-test/deno.json

@@ -0,0 +1,19 @@
+{
+  "//": "SPDX-License-Identifier: PMPL-1.0-or-later",
+  "name": "@hyperpolymath/affinescript-deno-test",
+  "version": "0.1.0",
+  "exports": {
+    ".": "./mod.ts",
+    "./cli": "./cli.ts"
+  },
+  "license": "PMPL-1.0-or-later",
+  "imports": {
+    "@hyperpolymath/affine-js": "../../nextgen-languages/affinescript/packages/affine-js/mod.js"
+  },
+  "tasks": {
+    "smoke:compile": "deno run --allow-read --allow-run --allow-env cli.ts example",
+    "smoke:test": "deno test --allow-read --allow-run --allow-env example/smoke_driver.ts",
+    "fmt": "deno fmt",
+    "lint": "deno lint"
+  }
+}

affinescript-ecosystem/affinescript-deno-test/deno.lock

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Example AffineScript test file for affinescript-deno-test.
+//
+// Convention (MVP v0.1.0):
+//   - One test per `.affine` file.
+//   - The test entry point is the function `main`, returning `Bool`.
+//   - The harness uses the filename (without the `_test.affine` / `.test.affine`
+//     suffix) as the Deno.test() case name.
+//
+// This single-test-per-file convention is an MVP constraint driven by the
+// current AffineScript codegen, which hardcodes the exportable-name
+// allowlist in lib/codegen.ml (only `main`, `init_state`, `step_state`,
+// `get_state`, `mission_active` are exported). Multi-test-per-file support
+// is a planned follow-up once the compiler gains a `pub fn` / `@export`
+// keyword.
+//
+// For now: each behaviour you want reported separately needs its own
+// `<name>_test.affine` file.
+
+fn main() -> Bool {
+  let two_plus_three = 2 + 3;
+  let forty_two = 42;
+  (two_plus_three == 5) && (forty_two == 42) && (1 != 2)
+}

affinescript-ecosystem/affinescript-deno-test/example/hello_test.affine

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// affinescript-deno-test: smoke test driver
+//
+// Run with:
+//   deno test --allow-read --allow-run --allow-env example/smoke_driver.ts
+//
+// Expected output: three green tests (test_addition, test_identity,
+// test_inequality) from example/hello_test.affine.
+
+import { runAll } from "../mod.ts";
+
+await runAll(new URL("./", import.meta.url).pathname);

affinescript-ecosystem/affinescript-deno-test/example/smoke_driver.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// affinescript-deno-test: compile.ts
+//
+// Wraps the `affinescript compile` CLI. Given a `.affine` source file,
+// produces a sibling `.wasm` file and returns its absolute path.
+//
+// The `AFFINESCRIPT_BIN` env var overrides the default path to the compiler.
+// Default is the local dev-build at developer-ecosystem/nextgen-languages/
+// affinescript/_build/install/default/bin/affinescript (useful while the
+// compiler is not on $PATH).
+
+const DEFAULT_BIN =
+  "/var/mnt/eclipse/repos/developer-ecosystem/nextgen-languages/affinescript/_build/install/default/bin/affinescript";
+
+/** Absolute path to the `affinescript` compiler binary. */
+export function resolveCompilerPath(): string {
+  return Deno.env.get("AFFINESCRIPT_BIN") ?? DEFAULT_BIN;
+}
+
+/**
+ * Compile an AffineScript source file to WebAssembly. Returns the absolute
+ * path to the emitted `.wasm`. Throws with compiler stderr if compilation
+ * fails.
+ */
+export async function compileToWasm(sourcePath: string): Promise<string> {
+  const absolute = sourcePath.startsWith("/")
+    ? sourcePath
+    : `${Deno.cwd()}/${sourcePath}`;
+
+  const wasmPath = absolute.replace(/\.(affine|afs|rattle|pyaff|jsaff)$/, ".wasm");
+  if (wasmPath === absolute) {
+    throw new Error(
+      `compileToWasm: source file must end in .affine / .afs / .rattle / .pyaff / .jsaff — got ${sourcePath}`,
+    );
+  }
+
+  const bin = resolveCompilerPath();
+  const cmd = new Deno.Command(bin, {
+    args: ["compile", absolute, "-o", wasmPath],
+    stdout: "piped",
+    stderr: "piped",
+  });
+
+  const { code, stdout, stderr } = await cmd.output();
+  if (code !== 0) {
+    const out = new TextDecoder().decode(stdout);
+    const err = new TextDecoder().decode(stderr);
+    throw new Error(
+      `affinescript compile failed (exit ${code}) for ${sourcePath}\n` +
+        `STDOUT:\n${out}\nSTDERR:\n${err}`,
+    );
+  }
+
+  return wasmPath;
+}