as-test 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Change Log
 
+## 2026-06-01 - v1.6.0
+
+### Incremental test cache — only rebuild and rerun what changed
+
+- feat: an opt-in incremental cache for `ast test` skips recompiling and rerunning specs whose inputs are unchanged since the last run, only acting on the ones that changed — themselves or via their dependency tree. Enable per run with `--cache`, or persistently with `"cache": true | "build" | "full"` in `as-test.config.json` (`--no-cache` overrides). Default is off. Because asc compilation is ~all of a run's wall-clock (a spec runs in microseconds but builds in seconds), skipping unchanged builds is the dominant win. New module `cli/build-cache.ts` persists a manifest under `.as-test/cache/`.
+- feat: **Tier 1 (build cache)** — `build()` (`cli/commands/build-core.ts`) and the parallel `buildFileForMode` (`cli/index.ts`) skip the asc invocation when a spec, every file it imported, and the build signature (`getBuildReuseInfo`) are all unchanged and the `.wasm` still exists. Dependencies are captured from asc's actual file reads (reusing the existing `buildRecorderStorage`/`onReads` plumbing that previously only fed `--watch`), so editing a shared helper correctly rebuilds just its dependents. The cache context is threaded once via an `AsyncLocalStorage` (`cacheStorage`) set in `runTestModes`, so no per-variant plumbing was needed and `--watch` (which keeps its own in-memory graph) is untouched.
+- feat: **Tier 2 (run replay)** — under `"full"`/`--cache`, `run()` (`cli/commands/run-core.ts`) replays a stored passing report instead of spawning the runtime, so cached specs still appear in the live output and in the summary/coverage. Replayed specs keep the coloured verdict badge (white text) but render the **filename dimmed with a `(cache)` tag in place of the timing**, so freshly-run specs stand out — in both the default reporter (`cli/reporters/default.ts`) and the multi-mode matrix display (`formatMatrixFileResultLine`). Only passing reports are replayed; a failing spec re-runs for fresh output. A rebuild clears the stored report, so a changed spec never replays a stale result.
+- feat: change detection uses a content hash (sha256) with an mtime+size fast-path — correct across `git checkout`/`clone`/`touch` (no false rebuilds) yet cheap when nothing changed. The whole cache is invalidated when the as-test version changes (transform output may differ); replay additionally keys on the runtime command and snapshot file contents. The build signature hashes only as-test's _declared_ env (config + `buildOptions.env` + the `AS_TEST_*` flags), not the inherited `process.env`, so volatile ambient vars like `FORCE_COLOR`/`TERM`/`CI` can't spuriously invalidate the cache between runs.
+- note: a reachability-based dep-pruning mode (`cache: "reachable"`) was prototyped but **not shipped** — it was unsound for AssemblyScript's compile-time inlining (inlined `const`s, `static readonly` fields, `@inline` bodies, and re-export barrels can change a spec's output without being "reachable"), so it could serve a stale pass. `"reachable"` is accepted as a deprecated alias for `"full"`, which tracks the complete dependency set and is always correct.
+- feat: the run summary gains a **`Cache:` line** (between `Modes:` and `Time:`), rendered in the same aligned three-column layout as the other totals — e.g. `Cache:   46 cached,  0 skipped,  46 total` (counted per file/mode execution; `skipped` = ran fresh). It only appears when the cache is active — each report carries a `cached` flag (true = replayed, false = freshly run) that the default reporter tallies in `onRunComplete`.
+- feat: **time-based expiry** via the object config form — `"cache": { "type": "full", "maxTime": "1h" }`. `maxTime` accepts `ms`/`s`/`m`/`h`/`d` durations; an entry built longer ago than that is treated as stale and rebuilt+rerun (which resets its timer). `type` selects the tier (`build`/`full`); the bare boolean/string forms still work. Parsed by `parseDurationMs`, resolved by `resolveCacheSettings` (`cli/util.ts`), enforced per-entry in `BuildCache.isBuildFresh` against a `builtAt` timestamp.
+- fix: the cache is now honored under `--watch` — previously `--cache --watch` silently ignored the cache (watch only set up its own in-memory dependency graph), so every watch run rebuilt from scratch. Each watch iteration now runs inside the cache context (a fresh load per run so `maxTime` stays current), making the initial watch run and `a` (re-run all) replay unchanged specs. `build()`'s read-recorder forwards to the watch graph recorder so both stay correct together; entry-pruning is skipped under watch (scoped re-runs resolve only a subset). A new **`c` keybinding toggles the cache** live; toggling `c` (and `w`) now rewrites the watch footer in place — `c = cache (on/off)` — instead of appending a message + a fresh footer each time.
+- feat: the cache is bypassed automatically when it cannot be trusted — `--fuzz` (non-deterministic), a custom build command, and (for replay only) `--create-snapshots`/`--overwrite-snapshots`. `ast clean` removes `.as-test/cache`.
+- fix: under `--parallel`, per-file result lines are now emitted in resolved order (the `localeCompare` sort `resolveSpecFiles` applies after globbing) instead of completion order. Previously a cache replay finished instantly and printed ahead of still-running fresh specs, scrambling the list; `ParallelQueueDisplay` now buffers completed output and flushes the contiguous prefix in start order, so cached and freshly-run specs stay interleaved in their original order.
+- chore: the cache manifest and per-spec reports under `.as-test/cache/` are gzipped (`manifest.json.gz`, `reports/*.json.gz`) — they're large, repetitive JSON dominated by coverage points, so this shrinks the cache directory ~10× (≈8 MB → ≈0.8 MB on as-test's own suite) at negligible read/write cost.
+
+## 2026-06-01 - v1.5.3
+
+### A file with no runnable tests is skipped, not crashed
+
+- fix: a spec file whose only suites are skip variants (`xdescribe`/`xtest`/`xit`) is now reported as **SKIP** instead of failing with `missing report payload from test runtime`. The transform's auto-`run()` injection keys off `analyzeSourceText` → `hasSuiteCalls` (`transform/src/index.ts`), whose regex was `\b(?:describe|test|it|only|xonly|todo|fuzz|xfuzz)`. `\bdescribe` can't match `xdescribe(` — `x` and `d` are both word chars, so there's no word boundary — and likewise `\btest`/`\bit` miss `xtest`/`xit`. A file whose only suites were skipped therefore reported `hasSuiteCalls = false`, `run()` was never injected, the wasm emitted no lifecycle frames and exited `0`, and the CLI read that silent-but-clean exit as a runtime crash. The regex now matches the `x?` variants (`x?describe|x?test|x?it|x?only|todo|x?fuzz`), so `run()` is injected and the file reports itself skipped (with the suite shown and counted). `looksLikeAsTestImport` got the same `x?` treatment so a file importing _only_ an x-variant still resolves its `run` import path.
+- feat: a spec file with no suites at all (empty, or only imports/comments) is now reported as a skipped file with a `… contains no tests; marked as skipped` warning, instead of `missing report payload`. Such a file never injects `run()` either, so `runProcess` (`cli/commands/run-core.ts`) now treats a clean exit (`code 0`) with zero data frames, no `file-start`/`file-end` events, no suite starts, and no stderr as an empty test file — returning a skip report (`createEmptyFileSkipReport`, `suites: []` so it counts as one skipped file and zero skipped suites) rather than a crash. A file that _does_ have suites always emits `file-start` before anything can go wrong, so this only ever fires for genuinely empty files.
+
+## 2026-06-01 - v1.5.2
+
+### Selectors resolve folders, files, and globs consistently
+
+- feat: positional selectors for `ast test`/`ast run`/`ast build` now resolve through a single shared resolver (`cli/selectors.ts:resolveSpecFiles`), replacing three drifting private copies of `resolveInputPatterns` (in `build-core`, `run-core`, and `index`). Three input shapes are supported:
+  - **Bare folders/files/globs** (no leading `./`) resolve against the configured input root(s) — the static prefix of each `input` glob, e.g. `assembly/__tests__` — searched recursively, and fall back to the cwd only if nothing matched there: `ast test rfc/` → `<root>/**/rfc/**/*.spec.ts`; `ast test foo` → `<root>/**/foo.spec.ts`; `ast test 'rfc/*.spec.ts'` → `<root>/**/rfc/*.spec.ts` (the user's glob appended verbatim). A bare path shorthand like `nested/array` is tried as a cwd path first, then anchored to the test folder.
+  - **`./`-prefixed** selectors (and absolute / `~` paths) are cwd-relative only; on a miss we emit a `did you mean "rfc/*.spec.ts"` hint pointing at the test-folder form when that would have matched.
+- feat: a bare selector that matches under more than one configured input root is flagged with a `WARN` (it still runs everything that matched), and a selector that matches nothing emits a `WARN` naming where it looked. Warnings are deduped by text across the orchestrator + per-file build/run passes (`emitSelectorWarnings`), so each prints once per invocation. Folder selectors (`rfc/`) and `,`-joined bare names (`a,b`) are recognized; selectors with an internal path separator (e.g. the orchestrator's own `assembly/__tests__/foo.spec.ts`) are still treated as direct cwd paths, preserving existing per-file dispatch.
+
 ## 2026-05-30 - v1.5.1
 
 ### An early-exiting runtime now fails instead of warning

package/as-test.config.schema.json

@@ -87,6 +87,28 @@
       "description": "Reserved config field used by existing projects.",
       "default": "none"
     },
+    "cache": {
+      "description": "Incremental test cache (opt-in). false = off; \"build\" = skip recompiling unchanged specs; \"full\"/true = also replay passing run results; \"reachable\" = full + reachability-pruned deps. The object form adds \"maxTime\" to expire entries older than that. Override per run with --cache / --no-cache.",
+      "oneOf": [
+        { "type": "boolean" },
+        { "type": "string", "enum": ["build", "full", "reachable"] },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["build", "full", "reachable"]
+            },
+            "maxTime": {
+              "type": "string",
+              "description": "Entry expiry, e.g. \"1h\", \"30m\", \"90s\", \"7d\"."
+            }
+          }
+        }
+      ],
+      "default": false
+    },
     "coverage": {
       "description": "Coverage settings. Use a boolean for quick toggle or object for options.",
       "oneOf": [
@@ -378,6 +400,24 @@
                 "type": "string",
                 "description": "Mode-specific asconfig path or \"none\"."
               },
+              "cache": {
+                "description": "Mode-specific incremental cache setting.",
+                "oneOf": [
+                  { "type": "boolean" },
+                  { "type": "string", "enum": ["build", "full", "reachable"] },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "enum": ["build", "full", "reachable"]
+                      },
+                      "maxTime": { "type": "string" }
+                    }
+                  }
+                ]
+              },
               "coverage": {
                 "description": "Mode-specific coverage settings.",
                 "oneOf": [

package/bin/build-cache.js

@@ -0,0 +1,278 @@
+import { createHash } from "crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import { gunzipSync, gzipSync } from "zlib";
+import * as path from "path";
+import { AsyncLocalStorage } from "async_hooks";
+// Persisted incremental cache for `ast test`. Two tiers:
+//   Tier 1 (build): skip the asc compile when a spec + every file it imported is
+//     byte-for-byte unchanged and the build signature still matches.
+//   Tier 2 (replay): skip running and replay the stored per-file report when the
+//     spec is build-fresh AND the runtime command + snapshot file are unchanged.
+// Both read the run-scoped context in `cacheStorage` (set once by the test
+// orchestrator), mirroring how `buildRecorderStorage` threads the watch
+// recorder down without plumbing a param through every call site.
+const CACHE_FORMAT_VERSION = 1;
+const MODE_KEY_DEFAULT = "__default__";
+// Manifest and reports are gzipped (repetitive JSON, large coverage payloads).
+const MANIFEST_FILE = "manifest.json.gz";
+// Mirror dependency-graph.ts specKey: NUL cannot appear in a mode name or path,
+// so the (mode, path) key can never collide.
+function specKey(mode, spec) {
+  return `${mode ?? MODE_KEY_DEFAULT}\u0000${path.resolve(spec)}`;
+}
+// asc reads its own bundled stdlib/toolchain on every build; those never change
+// between runs and would balloon every entry's dep set, so drop them — same
+// filter dependency-graph.ts applies for watch.
+function isUninterestingDep(absPath) {
+  const normalized = absPath.replace(/\\/g, "/");
+  if (normalized.includes("/node_modules/assemblyscript/")) return true;
+  if (normalized.includes("/node_modules/binaryen/")) return true;
+  return false;
+}
+// `.as-test/cache` — sibling of build/logs/coverage, derived from the build root
+// so a custom outDir keeps everything together. Always the un-mode-qualified
+// base dir: the manifest is mode-scoped internally via its keys.
+export function resolveCacheDir(baseOutDir) {
+  return path.join(path.dirname(baseOutDir), "cache");
+}
+export function sha256OfFile(absPath) {
+  try {
+    return createHash("sha256").update(readFileSync(absPath)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+export class BuildCache {
+  constructor(
+    cacheDir,
+    asTestVersion,
+    manifest,
+    // Entry expiry window in ms (null = none) and the run's reference time.
+    maxTimeMs,
+    now,
+  ) {
+    this.cacheDir = cacheDir;
+    this.asTestVersion = asTestVersion;
+    this.manifest = manifest;
+    this.maxTimeMs = maxTimeMs;
+    this.now = now;
+    this.dirty = false;
+  }
+  // Loads the manifest, self-healing to an empty cache on a missing/corrupt
+  // file or a format/version mismatch (a new as-test may emit different
+  // transform output, so the whole cache is invalidated on version bump).
+  static load(cacheDir, asTestVersion, opts = {}) {
+    const maxTimeMs = opts.maxTimeMs ?? null;
+    const now = opts.now ?? Date.now();
+    const empty = {
+      version: CACHE_FORMAT_VERSION,
+      asTestVersion,
+      entries: {},
+    };
+    const manifestPath = path.join(cacheDir, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+      return new BuildCache(cacheDir, asTestVersion, empty, maxTimeMs, now);
+    }
+    try {
+      const parsed = JSON.parse(
+        gunzipSync(readFileSync(manifestPath)).toString("utf8"),
+      );
+      if (
+        parsed.version !== CACHE_FORMAT_VERSION ||
+        parsed.asTestVersion !== asTestVersion ||
+        typeof parsed.entries !== "object" ||
+        parsed.entries === null
+      ) {
+        return new BuildCache(cacheDir, asTestVersion, empty, maxTimeMs, now);
+      }
+      return new BuildCache(cacheDir, asTestVersion, parsed, maxTimeMs, now);
+    } catch {
+      return new BuildCache(cacheDir, asTestVersion, empty, maxTimeMs, now);
+    }
+  }
+  isBuildFresh(mode, spec, ctx) {
+    const entry = this.manifest.entries[specKey(mode, spec)];
+    if (!entry) return false;
+    if (entry.buildSignature !== ctx.signature) return false;
+    if (entry.coverageEnabled !== ctx.coverageEnabled) return false;
+    // Time-based expiry: an entry built longer ago than maxTime is stale.
+    // Entries from before this field existed (builtAt undefined) count as 0,
+    // so they expire on the first run with maxTime set.
+    if (
+      this.maxTimeMs != null &&
+      this.now - (entry.builtAt ?? 0) > this.maxTimeMs
+    ) {
+      return false;
+    }
+    if (!existsSync(entry.outFile)) return false;
+    for (const [dep, fp] of Object.entries(entry.deps)) {
+      if (!this.depUnchanged(dep, fp)) return false;
+    }
+    return true;
+  }
+  // Tier 2: can we replay the stored report instead of running? A non-null
+  // reportPath means the build was fresh this session (recordBuild clears it on
+  // any rebuild), so the build signature + deps were already validated by
+  // build() before run() — we only re-check the run-specific inputs here
+  // (runtime command + snapshot file).
+  canReplay(mode, spec, ctx) {
+    const entry = this.manifest.entries[specKey(mode, spec)];
+    if (!entry?.reportPath) return false;
+    if ((entry.runtimeCmd ?? null) !== (ctx.runtimeCmd ?? null)) return false;
+    if ((entry.snapshotSha ?? null) !== (ctx.snapshotSha ?? null)) return false;
+    if (!existsSync(entry.outFile)) return false;
+    return existsSync(path.join(this.cacheDir, entry.reportPath));
+  }
+  recordBuild(mode, spec, args) {
+    const absSpec = path.resolve(spec);
+    const deps = {};
+    const record = (file) => {
+      const abs = path.resolve(file);
+      if (isUninterestingDep(abs)) return;
+      if (deps[abs]) return;
+      const fp = this.fingerprint(abs);
+      if (fp) deps[abs] = fp;
+    };
+    record(absSpec); // a spec is always its own dependency
+    for (const file of args.deps) record(file);
+    const key = specKey(mode, spec);
+    const prior = this.manifest.entries[key];
+    // A rebuild means any stored report is stale: drop it so isReplayFresh
+    // fails until the fresh run records a new one.
+    this.removeReportFile(prior?.reportPath ?? null);
+    this.manifest.entries[key] = {
+      spec: absSpec,
+      mode: mode ?? null,
+      buildSignature: args.signature,
+      outFile: path.resolve(args.outFile),
+      coverageEnabled: args.coverageEnabled,
+      deps,
+      builtAt: this.now,
+      runtimeCmd: null,
+      snapshotSha: null,
+      reportPath: null,
+    };
+    this.dirty = true;
+  }
+  recordReport(mode, spec, args) {
+    const key = specKey(mode, spec);
+    const entry = this.manifest.entries[key];
+    if (!entry) return; // recordBuild must have run first
+    const relPath = path.join("reports", `${sha1(key)}.json.gz`);
+    const absPath = path.join(this.cacheDir, relPath);
+    mkdirSync(path.dirname(absPath), { recursive: true });
+    // Reports are large (coverage points) and highly compressible repetitive
+    // JSON — gzip keeps .as-test/cache small (~15x on coverage-heavy specs).
+    writeFileSync(absPath, gzipSync(Buffer.from(JSON.stringify(args.report))));
+    entry.reportPath = relPath;
+    entry.snapshotSha = args.snapshotSha;
+    entry.runtimeCmd = args.runtimeCmd;
+    this.dirty = true;
+  }
+  getReport(mode, spec) {
+    const entry = this.manifest.entries[specKey(mode, spec)];
+    if (!entry?.reportPath) return undefined;
+    try {
+      return JSON.parse(
+        gunzipSync(
+          readFileSync(path.join(this.cacheDir, entry.reportPath)),
+        ).toString("utf8"),
+      );
+    } catch {
+      return undefined;
+    }
+  }
+  // Drop entries whose spec is no longer produced by the current input glob
+  // (deleted/renamed specs), along with their stored report files. liveKeys are
+  // specKey() strings for every (mode, spec) in this run.
+  prune(liveKeys) {
+    for (const [key, entry] of Object.entries(this.manifest.entries)) {
+      if (liveKeys.has(key)) continue;
+      this.removeReportFile(entry.reportPath ?? null);
+      delete this.manifest.entries[key];
+      this.dirty = true;
+    }
+  }
+  keyFor(mode, spec) {
+    return specKey(mode, spec);
+  }
+  save() {
+    if (!this.dirty) return;
+    mkdirSync(this.cacheDir, { recursive: true });
+    const manifestPath = path.join(this.cacheDir, MANIFEST_FILE);
+    const tmp = `${manifestPath}.tmp`;
+    writeFileSync(tmp, gzipSync(Buffer.from(JSON.stringify(this.manifest))));
+    renameSync(tmp, manifestPath);
+    this.dirty = false;
+  }
+  fingerprint(absPath) {
+    try {
+      const st = statSync(absPath);
+      const sha = sha256OfFile(absPath);
+      if (sha === null) return null;
+      return { sha, mtimeMs: st.mtimeMs, size: st.size };
+    } catch {
+      return null;
+    }
+  }
+  // Fast-path: trust mtime+size when both match (cheap stat, no read). Only when
+  // they differ do we hash — and if the hash still matches (e.g. git checkout
+  // rewrote mtime), refresh the stored stat so we don't re-hash next run.
+  depUnchanged(absPath, fp) {
+    let st;
+    try {
+      st = statSync(absPath);
+    } catch {
+      return false; // dep deleted
+    }
+    if (st.mtimeMs === fp.mtimeMs && st.size === fp.size) return true;
+    const sha = sha256OfFile(absPath);
+    if (sha === null) return false;
+    if (sha === fp.sha) {
+      fp.mtimeMs = st.mtimeMs;
+      fp.size = st.size;
+      this.dirty = true;
+      return true;
+    }
+    return false;
+  }
+  removeReportFile(relPath) {
+    if (!relPath) return;
+    try {
+      rmSync(path.join(this.cacheDir, relPath), { force: true });
+    } catch {
+      // best effort
+    }
+  }
+}
+function sha1(value) {
+  return createHash("sha1").update(value).digest("hex");
+}
+// True if any suite or test in a file report carries a "fail" verdict. We only
+// replay passing reports — a failing spec is cheap to re-run and gives fresh
+// failure output rather than a confusing replay.
+export function reportHasFailure(report) {
+  const suites = report?.suites;
+  if (!Array.isArray(suites)) return false;
+  return suites.some(suiteHasFailure);
+}
+function suiteHasFailure(suite) {
+  const s = suite;
+  if (s?.verdict === "fail") return true;
+  if (Array.isArray(s?.tests) && s.tests.some((t) => t?.verdict === "fail")) {
+    return true;
+  }
+  if (Array.isArray(s?.suites) && s.suites.some(suiteHasFailure)) return true;
+  return false;
+}
+// Run-scoped cache context, set once by the test orchestrator. `replay` gates
+// Tier 2 (off under snapshot-write flags, on for `cache: "full"`).
+export const cacheStorage = new AsyncLocalStorage();

package/bin/commands/build-core.js

@@ -22,8 +22,34 @@ import {
 } from "../util.js";
 import { persistCrashRecord } from "../crash-store.js";
 import { BuildWorkerPool } from "../build-worker-pool.js";
+import { resolveSpecFiles, emitSelectorWarnings } from "../selectors.js";
+import { cacheStorage } from "../build-cache.js";
 const DEFAULT_CONFIG_PATH = path.join(process.cwd(), "./as-test.config.json");
 export const buildRecorderStorage = new AsyncLocalStorage();
+// The canonical build signature: identical inputs (command, args sans -o, env)
+// yield an identical string. Used by both the cache freshness check inside
+// build() and getBuildReuseInfo() so the two never drift.
+function computeBuildSignature(invocation, signatureEnv) {
+  return JSON.stringify({
+    command: invocation.command,
+    args: stripOutputArgs(invocation.args),
+    apiArgs: invocation.apiArgs ? stripOutputArgs(invocation.apiArgs) : [],
+    env: sortRecord(signatureEnv),
+  });
+}
+// The env that actually affects build output, for the cache signature — only
+// as-test's *declared* env (config + buildOptions env + the AS_TEST_* flags),
+// NOT the inherited process.env. The real build env passed to asc is a superset
+// (it spreads process.env for PATH etc.), but hashing that would let volatile
+// vars like FORCE_COLOR/TERM spuriously invalidate the cache every run.
+function buildSignatureEnv(config, coverageEnabled, modeName) {
+  return {
+    ...config.env,
+    ...config.buildOptions.env,
+    AS_TEST_COVERAGE_ENABLED: coverageEnabled ? "1" : "0",
+    AS_TEST_MODE_NAME: modeName ?? "default",
+  };
+}
 export class BuildFailureError extends Error {
   constructor(args) {
     super(args.message);
@@ -67,14 +93,9 @@ export async function build(
   const pkgRunner = getPkgRunner();
   const sourceInputPatterns =
     overrides.kind === "fuzz" ? config.fuzz.input : config.input;
-  const inputPatterns = resolveInputPatterns(sourceInputPatterns, selectors);
-  const includePatterns = inputPatterns.filter((p) => !p.startsWith("!"));
-  const ignorePatterns = inputPatterns
-    .filter((p) => p.startsWith("!"))
-    .map((p) => p.slice(1));
-  const inputFiles = (
-    await glob(includePatterns, { ignore: ignorePatterns })
-  ).sort((a, b) => a.localeCompare(b));
+  const { files: inputFiles, warnings: selectorWarnings } =
+    await resolveSpecFiles(sourceInputPatterns, selectors);
+  emitSelectorWarnings(selectorWarnings);
   await assertNoArtifactCollisions(sourceInputPatterns);
   warnOnUnknownModeReferences(inputFiles, loadedConfig.modes ?? {});
   const coverageEnabled = resolveCoverageEnabled(
@@ -87,11 +108,15 @@ export async function build(
     AS_TEST_COVERAGE_ENABLED: coverageEnabled ? "1" : "0",
     AS_TEST_MODE_NAME: modeName ?? "default",
   };
+  // The cache needs the in-process API build path (only it can record asc's
+  // file reads), so when a cache context is active fall through to the direct
+  // loop below rather than the child-process serial pool.
   if (
     !resolvedConfig &&
     !process.env.AS_TEST_BUILD_API &&
     !hasCustomBuildCommand(config) &&
-    !buildRecorderStorage.getStore()
+    !buildRecorderStorage.getStore() &&
+    !cacheStorage.getStore()
   ) {
     const pool = getSerialBuildWorkerPool();
     for (const file of inputFiles) {
@@ -118,12 +143,13 @@ export async function build(
     }
     return;
   }
+  const cacheCtx = cacheStorage.getStore();
+  const canCache = !!cacheCtx && !hasCustomBuildCommand(config);
   for (const file of inputFiles) {
     const outFile = path.join(
       config.outDir,
       resolveArtifactPath(file, sourceInputPatterns),
     );
-    mkdirSync(path.dirname(outFile), { recursive: true });
     const invocation = getBuildCommand(
       config,
       pkgRunner,
@@ -132,8 +158,50 @@ export async function build(
       modeName,
       featureToggles,
     );
+    const signature = canCache
+      ? computeBuildSignature(
+          invocation,
+          buildSignatureEnv(config, coverageEnabled, modeName),
+        )
+      : "";
+    // Cache hit: spec + every recorded dependency unchanged and the build
+    // signature still matches, so the existing .wasm is current — skip asc.
+    if (
+      canCache &&
+      cacheCtx.cache.isBuildFresh(modeName, file, {
+        signature,
+        coverageEnabled,
+      })
+    ) {
+      continue;
+    }
+    mkdirSync(path.dirname(outFile), { recursive: true });
+    const reads = new Set();
     try {
-      await buildFile(invocation, buildEnv);
+      if (canCache) {
+        // Capture asc's file reads (the spec's transitive deps) so the next
+        // run can tell when any of them changed. Forward to any outer recorder
+        // (e.g. the watch loop's dependency-graph recorder) so it still sees
+        // reads while the cache is active.
+        const outer = buildRecorderStorage.getStore();
+        await buildRecorderStorage.run(
+          {
+            record: (mode, spec, abs) => {
+              reads.add(abs);
+              outer?.record(mode, spec, abs);
+            },
+          },
+          () => buildFile(invocation, buildEnv),
+        );
+        cacheCtx.cache.recordBuild(modeName, file, {
+          signature,
+          outFile,
+          deps: reads,
+          coverageEnabled,
+        });
+      } else {
+        await buildFile(invocation, buildEnv);
+      }
     } catch (error) {
       const modeLabel = modeName ?? "default";
       const stdout = getBuildStdout(error);
@@ -267,20 +335,13 @@ export async function getBuildReuseInfo(
     config.coverage,
     featureToggles.coverage,
   );
-  const buildEnv = {
-    ...mode.env,
-    ...config.buildOptions.env,
-    AS_TEST_COVERAGE_ENABLED: coverageEnabled ? "1" : "0",
-    AS_TEST_MODE_NAME: modeName ?? "default",
-  };
   return {
-    signature: JSON.stringify({
-      command: invocation.command,
-      args: stripOutputArgs(invocation.args),
-      apiArgs: invocation.apiArgs ? stripOutputArgs(invocation.apiArgs) : [],
-      env: sortRecord(buildEnv),
-    }),
+    signature: computeBuildSignature(
+      invocation,
+      buildSignatureEnv(config, coverageEnabled, modeName),
+    ),
     outFile,
+    coverageEnabled,
   };
 }
 function hasCustomBuildCommand(config) {
@@ -540,61 +601,6 @@ async function assertNoArtifactCollisions(configured) {
     seen.set(artifact, file);
   }
 }
-function resolveInputPatterns(configured, selectors) {
-  const configuredInputs = Array.isArray(configured)
-    ? configured
-    : [configured];
-  if (!selectors.length) return configuredInputs;
-  const patterns = new Set();
-  for (const selector of expandSelectors(selectors)) {
-    if (!selector) continue;
-    if (isBareSuiteSelector(selector)) {
-      const base = stripSuiteSuffix(selector);
-      for (const configuredInput of configuredInputs) {
-        patterns.add(
-          path.join(path.dirname(configuredInput), `${base}.spec.ts`),
-        );
-      }
-      continue;
-    }
-    patterns.add(selector);
-  }
-  return [...patterns];
-}
-function expandSelectors(selectors) {
-  const expanded = [];
-  for (const selector of selectors) {
-    if (!selector) continue;
-    if (!shouldSplitSelector(selector)) {
-      expanded.push(selector);
-      continue;
-    }
-    for (const token of selector.split(",")) {
-      const trimmed = token.trim();
-      if (!trimmed.length) continue;
-      expanded.push(trimmed);
-    }
-  }
-  return expanded;
-}
-function shouldSplitSelector(selector) {
-  return (
-    selector.includes(",") &&
-    !selector.includes("/") &&
-    !selector.includes("\\") &&
-    !/[*?[\]{}]/.test(selector)
-  );
-}
-function isBareSuiteSelector(selector) {
-  return (
-    !selector.includes("/") &&
-    !selector.includes("\\") &&
-    !/[*?[\]{}]/.test(selector)
-  );
-}
-function stripSuiteSuffix(selector) {
-  return selector.replace(/\.spec\.ts$/, "").replace(/\.ts$/, "");
-}
 function ensureDeps(config) {
   if (config.buildOptions.target == "wasi") {
     if (!resolveWasiShim()) {

package/bin/commands/clean-core.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { existsSync, rmSync } from "fs";
 import * as path from "path";
 import { applyMode, loadConfig } from "../util.js";
+import { resolveCacheDir } from "../build-cache.js";
 const DEFAULT_CONFIG_PATH = path.join(process.cwd(), "./as-test.config.json");
 export async function clean(
   configPath = DEFAULT_CONFIG_PATH,
@@ -11,6 +12,9 @@ export async function clean(
   const loadedConfig = loadConfig(configPath, true);
   const targets = new Map();
   const ownership = buildOwnershipMap(loadedConfig);
+  // The incremental cache (.as-test/cache) is a single global dir, not
+  // per-mode, so it is always cleaned whenever `ast clean` runs.
+  collectRootTarget(targets, resolveCacheDir(loadedConfig.outDir), "cache");
   if (fullClean) {
     collectRootTarget(targets, loadedConfig.outDir, "build");
     collectRootTarget(targets, loadedConfig.fuzz.crashDir, "crashes");