as-test 1.2.0 → 1.4.0

package/bin/index.js

@@ -3,10 +3,12 @@ import chalk from "chalk";
 import {
   build,
   BuildFailureError,
+  flushModeWarnings,
   formatInvocation as formatBuildInvocation,
   getBuildInvocationPreview,
+  warnOnUnknownModeReferences,
 } from "./commands/build.js";
-import { createRunReporter, run } from "./commands/run.js";
+import { createRunReporter, resetCollectedLogs, run } from "./commands/run.js";
 import { executeBuildCommand } from "./commands/build.js";
 import { executeRunCommand } from "./commands/run.js";
 import { executeTestCommand } from "./commands/test.js";
@@ -24,16 +26,21 @@ import {
   loadConfig,
   resolveArtifactPath,
   resolveModeNames,
+  resolveSnapshotPath,
   resolveSpecRelativePath,
 } from "./util.js";
+import { normalizeFeatureName } from "./types.js";
 import * as path from "path";
 import { spawnSync } from "child_process";
 import { glob } from "glob";
 import { createInterface } from "readline";
 import { existsSync, watch as fsWatch } from "fs";
+import { minimatch } from "minimatch";
 import { availableParallelism, cpus } from "os";
 import { BuildWorkerPool } from "./build-worker-pool.js";
 import { PersistentWebSessionHost } from "./commands/web-session.js";
+import { buildRecorderStorage } from "./commands/build-core.js";
+import { DependencyGraph } from "./dependency-graph.js";
 const _args = process.argv.slice(2);
 const flags = [];
 const args = [];
@@ -282,20 +289,17 @@ function printCommandHelp(command) {
     );
     process.stdout.write("Compile selected specs into wasm artifacts.\n\n");
     process.stdout.write(chalk.bold("Flags:\n"));
-    process.stdout.write(
-      "  --config <path>          Use a specific config file\n",
-    );
     process.stdout.write(
       "  --mode <name[,name...]>  Run one or multiple named config modes\n",
     );
     process.stdout.write(
-      "  --enable <feature>       Enable build feature (coverage|try-as)\n",
+      "  --enable <list>          Enable features, comma-separated (e.g. coverage,try-as,simd)\n",
     );
     process.stdout.write(
-      "  --disable <feature>      Disable build feature (coverage|try-as)\n",
+      "  --disable <list>         Disable features, comma-separated\n",
     );
     process.stdout.write(
-      "  --parallel              Run files through an ordered worker pool using an automatic worker count\n",
+      "  --config <path>          Use a specific config file\n",
     );
     process.stdout.write(
       "  --jobs <n>               Run files through an ordered worker pool\n",
@@ -356,10 +360,10 @@ function printCommandHelp(command) {
     );
     process.stdout.write("  --suites <name[,name...]> Alias for --suite\n");
     process.stdout.write(
-      "  --enable <feature>       Enable feature (coverage|try-as)\n",
+      "  --enable <list>          Enable features, comma-separated (e.g. coverage,try-as,simd)\n",
     );
     process.stdout.write(
-      "  --disable <feature>      Disable feature (coverage|try-as)\n",
+      "  --disable <list>         Disable features, comma-separated\n",
     );
     process.stdout.write(
       "  --reporter <name|path>   Use built-in reporter (default|tap) or custom module path\n",
@@ -391,16 +395,19 @@ function printCommandHelp(command) {
     );
     process.stdout.write(chalk.bold("Flags:\n"));
     process.stdout.write(
-      "  --config <path>          Use a specific config file\n",
+      "  --mode <name[,name...]>  Run one or multiple named config modes\n",
     );
     process.stdout.write(
-      "  --mode <name[,name...]>  Run one or multiple named config modes\n",
+      "  --enable <list>          Enable features, comma-separated (e.g. coverage,try-as,simd)\n",
     );
     process.stdout.write(
-      "  --browser <name|path>    Use chrome, chromium, firefox, webkit, or an executable path for web modes\n",
+      "  --disable <list>         Disable features, comma-separated\n",
     );
     process.stdout.write(
-      "  --parallel              Run files through an ordered worker pool using an automatic worker count\n",
+      "  --config <path>          Use a specific config file\n",
+    );
+    process.stdout.write(
+      "  --browser <name|path>    Use chrome, chromium, firefox, webkit, or an executable path for web modes\n",
     );
     process.stdout.write(
       "  --jobs <n>               Run files through an ordered worker pool\n",
@@ -427,12 +434,6 @@ function printCommandHelp(command) {
       "  --suite <name[,name...]> Filter results to matching suite names or suite slug paths\n",
     );
     process.stdout.write("  --suites <name[,name...]> Alias for --suite\n");
-    process.stdout.write(
-      "  --enable <feature>       Enable feature (coverage|try-as)\n",
-    );
-    process.stdout.write(
-      "  --disable <feature>      Disable feature (coverage|try-as)\n",
-    );
     process.stdout.write(
       "  --fuzz                   Run fuzz targets after the normal test pass\n",
     );
@@ -473,7 +474,7 @@ function printCommandHelp(command) {
       "  --list-modes             Preview configured and selected mode names\n",
     );
     process.stdout.write(
-      "  --watch                  Re-run on source or spec changes\n",
+      "  --watch, -w              Re-run on source or spec changes\n",
     );
     process.stdout.write("  --help, -h               Show this help\n");
     return;
@@ -534,6 +535,12 @@ function printCommandHelp(command) {
     process.stdout.write(
       "  --example <minimal|full|none>           Set example template\n",
     );
+    process.stdout.write(
+      "  --enable <list>                         Enable features, comma-separated (coverage,try-as)\n",
+    );
+    process.stdout.write(
+      "  --disable <list>                        Disable features, comma-separated\n",
+    );
     process.stdout.write(
       "  --install                               Install dependencies after scaffolding\n",
     );
@@ -685,7 +692,7 @@ function resolveCommandArgs(rawArgs, command) {
     if (arg == "--parallel") {
       continue;
     }
-    if (arg == "--watch") {
+    if (arg == "--watch" || arg == "-w") {
       continue;
     }
     if (
@@ -709,8 +716,9 @@ function resolveCommandArgs(rawArgs, command) {
   return values;
 }
 function resolveFeatureToggles(rawArgs, command) {
-  if (command !== "build" && command !== "run" && command !== "test") return {};
-  const out = {};
+  if (command !== "build" && command !== "run" && command !== "test")
+    return { featureOverrides: {} };
+  const out = { featureOverrides: {} };
   let seenCommand = false;
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
@@ -722,7 +730,9 @@ function resolveFeatureToggles(rawArgs, command) {
       const enabled = arg == "--enable";
       const next = rawArgs[i + 1];
       if (next && !next.startsWith("-")) {
-        applyFeatureToggle(out, next, enabled);
+        for (const name of splitFeatureList(next)) {
+          applyFeatureToggle(out, name, enabled);
+        }
         i++;
       }
       continue;
@@ -730,9 +740,9 @@ function resolveFeatureToggles(rawArgs, command) {
     if (arg.startsWith("--enable=") || arg.startsWith("--disable=")) {
       const enabled = arg.startsWith("--enable=");
       const eq = arg.indexOf("=");
-      const value = arg.slice(eq + 1).trim();
-      if (value.length) {
-        applyFeatureToggle(out, value, enabled);
+      const value = arg.slice(eq + 1);
+      for (const name of splitFeatureList(value)) {
+        applyFeatureToggle(out, name, enabled);
       }
     }
   }
@@ -1280,19 +1290,24 @@ function parseIntegerFlag(flag, value) {
   }
   return Math.floor(parsed);
 }
+function splitFeatureList(value) {
+  return value
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
 function applyFeatureToggle(out, rawFeature, enabled) {
-  const key = rawFeature.trim().toLowerCase();
+  const key = normalizeFeatureName(rawFeature);
+  if (!key.length) {
+    throw new Error(
+      `empty feature name passed to ${enabled ? "--enable" : "--disable"}`,
+    );
+  }
   if (key == "coverage") {
     out.coverage = enabled;
     return;
   }
-  if (key == "try-as" || key == "try_as" || key == "tryas") {
-    out.tryAs = enabled;
-    return;
-  }
-  throw new Error(
-    `unknown feature "${rawFeature}". Supported features: coverage, try-as`,
-  );
+  out.featureOverrides[key] = enabled;
 }
 function resolveCommandTokens(rawArgs, command) {
   const values = [];
@@ -1308,6 +1323,10 @@ function resolveCommandTokens(rawArgs, command) {
   return values;
 }
 async function buildFileForMode(args) {
+  // If the caller has an active buildRecorderStorage context (e.g. the watch
+  // loop), forward reads from the pool's worker process back into the same
+  // recorder so the dependency graph still gets populated under --parallel.
+  const recorder = buildRecorderStorage.getStore();
   if (args.buildPool) {
     const buildInvocation = await getBuildInvocationPreview(
       args.configPath,
@@ -1321,6 +1340,11 @@ async function buildFileForMode(args) {
       modeName: args.modeName,
       buildCommand: formatBuildInvocation(buildInvocation),
       featureToggles: args.buildFeatureToggles,
+      onReads: recorder
+        ? (reads) => {
+            for (const r of reads) recorder.record(r.mode, r.spec, r.file);
+          }
+        : undefined,
     });
   } else {
     await build(
@@ -1344,6 +1368,7 @@ async function runTestSequential(
   reporterOverride,
   webSession = null,
   emitRunComplete = true,
+  onSpecOutcome,
 ) {
   const files = await resolveSelectedFiles(configPath, selectors);
   if (!files.length) {
@@ -1362,6 +1387,7 @@ async function runTestSequential(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -1400,6 +1426,7 @@ async function runTestSequential(
     }
     results.push(result);
     if (result?.failed) failed = true;
+    onSpecOutcome?.({ file, mode: modeName, failed: !!result?.failed });
   }
   const summary = aggregateRunResults(results);
   summary.stats = applyConfiguredFileTotalToStats(
@@ -1418,6 +1445,8 @@ async function runTestSequential(
       coverageSummary: summary.coverageSummary,
       stats: summary.stats,
       reports: summary.reports,
+      showLogs: runFlags.showLogs,
+      logSummary: summary.logSummary,
       modeSummary: buildSingleModeSummary(
         summary.stats,
         summary.snapshotSummary,
@@ -1425,6 +1454,7 @@ async function runTestSequential(
       ),
     });
     reporter.flush?.();
+    flushModeWarnings(process.argv.includes("--show-warnings"));
   }
   return {
     failed,
@@ -1434,6 +1464,7 @@ async function runTestSequential(
       coverageSummary: summary.coverageSummary,
       stats: summary.stats,
       reports: summary.reports,
+      logSummary: summary.logSummary,
     },
   };
 }
@@ -1626,6 +1657,7 @@ async function runRuntimeMatrix(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -1729,6 +1761,8 @@ async function runRuntimeMatrix(
     coverageSummary: summary.coverageSummary,
     stats: summary.stats,
     reports: summary.reports,
+    showLogs: runFlags.showLogs,
+    logSummary: summary.logSummary,
     modeSummary: buildModeSummary(modeState, modeSummaryTotal),
   });
   return allResults.some((result) => result.failed);
@@ -1743,6 +1777,7 @@ async function runTestModesCore(
   buildFeatureToggles,
   fuzzEnabled,
   fuzzOverrides,
+  onSpecOutcome,
 ) {
   await ensureWebBrowsersReady(configPath, modes, runFlags.browser);
   const modeSummaryTotal = Math.max(modes.length, 1);
@@ -1775,6 +1810,7 @@ async function runTestModesCore(
         fileSummaryTotal,
         fuzzEnabled,
         fuzzOverrides,
+        onSpecOutcome,
       );
       return failed;
     }
@@ -1792,6 +1828,7 @@ async function runTestModesCore(
         fuzzEnabled,
         fuzzOverrides,
         modeName,
+        onSpecOutcome,
       );
       if (modeFailed) failed = true;
     }
@@ -1810,6 +1847,7 @@ async function runTestModesCore(
       fileSummaryTotal,
       fuzzEnabled,
       fuzzOverrides,
+      onSpecOutcome,
     );
     return failed;
   }
@@ -1838,6 +1876,7 @@ async function runTestModesCore(
         reporterSession.reporter,
         sharedWebSession,
         !fuzzEnabled,
+        onSpecOutcome,
       );
       if (modeResult.failed) failed = true;
       if (fuzzEnabled) {
@@ -1866,6 +1905,8 @@ async function runTestModesCore(
           coverageSummary: modeResult.summary.coverageSummary,
           stats: modeResult.summary.stats,
           reports: modeResult.summary.reports,
+          showLogs: effectiveRunFlags.showLogs,
+          logSummary: modeResult.summary.logSummary,
           fuzzSummary: summarizeFuzzExecutions(fuzzResults),
           modeSummary: buildSingleModeSummary(
             modeResult.summary.stats,
@@ -1874,6 +1915,7 @@ async function runTestModesCore(
           ),
         });
         reporterSession.reporter.flush?.();
+        flushModeWarnings(process.argv.includes("--show-warnings"));
       }
     }
   } finally {
@@ -1932,99 +1974,461 @@ async function runWatchLoop(
 ) {
   const resolvedConfigPath =
     configPath ?? path.join(process.cwd(), "./as-test.config.json");
-  const config = loadConfig(resolvedConfigPath, false);
-  const watchDirs = resolveWatchDirectories(config);
+  const absConfigPath = path.resolve(resolvedConfigPath);
+  let config = loadConfig(resolvedConfigPath, false);
+  // Respect the user's parallelism flags. Worker-pool builds forward their
+  // file-read records back through IPC (see BuildWorkerPool / build-worker
+  // and buildFileForMode), so the dependency graph stays correct under
+  // --parallel as well.
+  const watchRunFlags = { ...runFlags };
+  const graph = new DependencyGraph();
+  let graphPopulated = false;
+  // Sticky failure tracker: each entry is "this (spec, mode) was last seen
+  // failing." Only updated for (spec, mode) pairs that actually re-ran this
+  // iteration, so a spec the watch loop skipped stays visible at the bottom
+  // until it passes again. `space` retries this exact set.
+  const failingSpecs = new Map();
+  function recordSpecOutcome(file, mode, failed) {
+    const abs = path.resolve(file);
+    const modes = failingSpecs.get(abs) ?? new Set();
+    if (failed) {
+      modes.add(mode);
+      failingSpecs.set(abs, modes);
+      return;
+    }
+    if (!modes.size) return;
+    modes.delete(mode);
+    if (modes.size === 0) failingSpecs.delete(abs);
+  }
   let isRunning = false;
-  let pendingFile = null;
+  let pendingTrigger = null;
   let debounceTimer = null;
-  async function doRun(changedFile) {
-    if (changedFile) {
-      console.clear();
-      process.stdout.write(
+  // Toggled with `w`. When false, file changes are remembered in
+  // `changedWhilePaused` but not auto-run — the user invokes runs manually
+  // (`a` / space). Resuming re-runs everything if anything changed meanwhile.
+  let autoRun = true;
+  const changedWhilePaused = new Set();
+  // Keyed by absolute directory path so attachWatcherFor is idempotent;
+  // makes it safe to re-scan & top up watchers after every iteration without
+  // double-attaching to the same dir.
+  const attachedDirWatchers = new Map();
+  let configFileWatcher = null;
+  function describeAffected(specs) {
+    const list = Array.from(specs).map((s) => path.relative(process.cwd(), s));
+    if (list.length <= 3) return list.join(", ");
+    return `${list.slice(0, 3).join(", ")} (+${list.length - 3} more)`;
+  }
+  function watchFooter() {
+    if (!autoRun) {
+      const pending = changedWhilePaused.size
+        ? ` (${changedWhilePaused.size} change(s) pending)`
+        : "";
+      return chalk.dim(
+        `Auto-run paused${pending}. ` +
+          chalk.bold("w") +
+          " = resume, " +
+          chalk.bold("a") +
+          " = re-run all, " +
+          chalk.bold("space") +
+          " = retry failing, " +
+          chalk.bold("ctrl+c") +
+          " = stop.\n",
+      );
+    }
+    return chalk.dim(
+      "Watching for changes. " +
+        chalk.bold("space") +
+        " = retry failing, " +
+        chalk.bold("a") +
+        " = re-run all, " +
+        chalk.bold("w") +
+        " = pause, " +
+        chalk.bold("ctrl+c") +
+        " = stop.\n",
+    );
+  }
+  function writeWatchHeader(headline, detail) {
+    // Preserve scrollback — never `console.clear()`. A blank line plus a
+    // dim rule visually delimits each iteration so prior output stays
+    // readable above.
+    process.stdout.write(
+      "\n" +
+        chalk.dim("─".repeat(Math.max(24, process.stdout.columns ?? 60))) +
+        "\n" +
         chalk.dim(`[${new Date().toLocaleTimeString()}] `) +
-          chalk.yellow("Change detected: ") +
-          chalk.bold(changedFile) +
-          "\n\n",
+        chalk.yellow(headline) +
+        (detail ? chalk.bold(detail) : "") +
+        "\n",
+    );
+  }
+  // Render the sticky "currently failing" pin. Renders nothing when empty so
+  // happy paths stay visually clean. Mode tags shown only when the user has
+  // configured >1 mode; in the single-mode case the bare path is enough.
+  function renderFailingSpecs() {
+    if (failingSpecs.size === 0) return "";
+    const multiMode = modes.length > 1;
+    const entries = Array.from(failingSpecs.entries()).map(([abs, modeSet]) => {
+      const rel = path.relative(process.cwd(), abs);
+      const tags = multiMode
+        ? Array.from(modeSet, (m) => m ?? "default").sort()
+        : [];
+      return { rel, tags };
+    });
+    entries.sort((a, b) => a.rel.localeCompare(b.rel));
+    const MAX_LINES = 8;
+    const shown = entries.slice(0, MAX_LINES);
+    const overflow = entries.length - shown.length;
+    const lines = [];
+    lines.push(chalk.red.bold(`Currently failing (${failingSpecs.size}):`));
+    for (const { rel, tags } of shown) {
+      const tagSuffix = tags.length ? chalk.dim(`  [${tags.join(", ")}]`) : "";
+      lines.push(`  ${chalk.gray(rel)}${tagSuffix}`);
+    }
+    if (overflow > 0) {
+      lines.push(chalk.dim(`  (+${overflow} more)`));
+    }
+    return lines.join("\n") + "\n\n";
+  }
+  async function doRun(trigger) {
+    let runSelectors = selectors;
+    let scopedRun = false;
+    if (trigger.kind === "manual-rerun") {
+      if (failingSpecs.size === 0) {
+        // Nothing to retry; stay silent so we don't pollute scrollback.
+        return;
+      }
+      const failingPaths = new Set(failingSpecs.keys());
+      writeWatchHeader("Retrying failing specs");
+      process.stdout.write(
+        chalk.dim(`Retrying ${failingPaths.size} failing spec(s): `) +
+          chalk.bold(describeAffected(failingPaths)) +
+          "\n",
+      );
+      runSelectors = Array.from(failingPaths).map((spec) =>
+        path.relative(process.cwd(), spec),
       );
+      scopedRun = true;
+    } else if (trigger.kind === "manual-runall") {
+      writeWatchHeader("Re-running all specs");
+    } else if (trigger.kind === "change") {
+      const absChanged = path.resolve(trigger.file);
+      if (absChanged === absConfigPath) {
+        writeWatchHeader("Change detected: ", trigger.file);
+        process.stdout.write(
+          chalk.dim("Config changed; reloading and rebuilding everything.\n"),
+        );
+        try {
+          config = loadConfig(resolvedConfigPath, false);
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          process.stderr.write(
+            chalk.red("Failed to reload config: ") + msg + "\n",
+          );
+        }
+        graph.clear();
+        graphPopulated = false;
+        failingSpecs.clear();
+        // The previous config's input/snapshotDir may no longer be relevant;
+        // drop every dir watcher and re-derive from the fresh config so we
+        // don't leak watchers for dirs we no longer care about.
+        closeDirWatchers();
+        refreshWatchedDirs();
+      } else if (graphPopulated) {
+        const affected = new Set(graph.specsAffectedBy(absChanged));
+        // A new .spec.ts file the graph hasn't seen yet should still be
+        // built and run. Cheapest heuristic without re-globbing: treat any
+        // .spec.ts under cwd that we don't already know as a candidate.
+        if (
+          affected.size === 0 &&
+          /\.spec\.ts$/i.test(absChanged) &&
+          existsSync(absChanged) &&
+          !graph.knownSpecs().has(absChanged)
+        ) {
+          affected.add(absChanged);
+        }
+        if (affected.size === 0) {
+          // Nothing depends on this file; skip silently so scrollback isn't
+          // littered with no-op events for unrelated edits.
+          return;
+        }
+        writeWatchHeader("Change detected: ", trigger.file);
+        process.stdout.write(
+          chalk.dim(`Rebuilding ${affected.size} affected spec(s): `) +
+            chalk.bold(describeAffected(affected)) +
+            "\n",
+        );
+        runSelectors = Array.from(affected).map((spec) =>
+          path.relative(process.cwd(), spec),
+        );
+        scopedRun = true;
+      } else {
+        // Change arrived before the graph was populated (e.g. queued during
+        // the initial run). Run everything; surface the header so the user
+        // knows the iteration was caused by the edit.
+        writeWatchHeader("Change detected: ", trigger.file);
+      }
     }
+    process.stdout.write("\n");
+    // A full re-run starts the aggregated-log collector fresh and clears any
+    // changes tracked while paused (they're now covered). Scoped reruns keep
+    // prior specs' logs (each re-run spec's entry is replaced in place), so
+    // latest.log stays complete instead of collapsing to just the rerun.
+    if (!scopedRun) {
+      resetCollectedLogs();
+      changedWhilePaused.clear();
+    }
+    const collected = [];
+    const recorder = {
+      record: (mode, specFile, absPath) => {
+        collected.push({ mode, spec: specFile, file: absPath });
+      },
+    };
     try {
-      await runTestModesCore(
-        runFlags,
-        configPath,
-        selectors,
-        suiteSelectors,
-        fuzzerSelectors,
-        modes,
-        buildFeatureToggles,
-        fuzzEnabled,
-        fuzzOverrides,
-      );
+      await buildRecorderStorage.run(recorder, async () => {
+        await runTestModesCore(
+          watchRunFlags,
+          configPath,
+          runSelectors,
+          suiteSelectors,
+          fuzzerSelectors,
+          modes,
+          buildFeatureToggles,
+          fuzzEnabled,
+          fuzzOverrides,
+          (outcome) =>
+            recordSpecOutcome(outcome.file, outcome.mode, outcome.failed),
+        );
+      });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       process.stderr.write(chalk.red("Error: ") + message + "\n");
     }
-    process.stdout.write(
-      "\n" + chalk.dim("Watching for changes. Press Ctrl+C to stop.\n"),
-    );
+    // Bucket reads by (mode, spec) then merge into the graph. Skipped specs
+    // (those not touched this run) keep their prior entries — important for
+    // scoped reruns and for builds that fail before any reads happen.
+    const bySpec = new Map();
+    for (const entry of collected) {
+      const key = `${entry.mode ?? ""}${entry.spec}`;
+      let bucket = bySpec.get(key);
+      if (!bucket) {
+        bucket = { mode: entry.mode, spec: entry.spec, files: new Set() };
+        bySpec.set(key, bucket);
+      }
+      bucket.files.add(entry.file);
+    }
+    for (const bucket of bySpec.values()) {
+      if (config.snapshotDir) {
+        bucket.files.add(
+          resolveSnapshotPath(bucket.spec, config.snapshotDir, config.input),
+        );
+      }
+      graph.recordBuild(bucket.spec, bucket.mode, bucket.files);
+    }
+    // Only mark populated after a full (unscoped) run that recorded at least
+    // one spec — that way we never trust a scoped run to validate the full
+    // dependency picture.
+    if (!scopedRun && bySpec.size > 0) {
+      graphPopulated = true;
+    }
+    // Top up watchers after every iteration so newly-created dirs (the
+    // snapshot dir on first run, dirs introduced by config edits, etc.) get
+    // monitored without restarting the loop.
+    refreshWatchedDirs();
+    attachConfigWatcher();
+    process.stdout.write("\n" + renderFailingSpecs() + watchFooter());
+  }
+  function attachWatcherFor(absDir, recursive) {
+    if (attachedDirWatchers.has(absDir)) return;
+    if (!existsSync(absDir)) return;
+    try {
+      const w = fsWatch(absDir, { recursive }, (_evt, filename) => {
+        if (!filename) return;
+        const full = path.join(absDir, filename);
+        if (shouldIgnoreWatchPath(full, config)) return;
+        scheduleRerun(path.relative(process.cwd(), full));
+      });
+      attachedDirWatchers.set(absDir, w);
+    } catch {
+      // some dirs (or filesystems) can't be watched recursively; skip.
+    }
+  }
+  // Called after every iteration so dirs created lazily (snapshotDir on
+  // first run, dirs introduced by config reload, etc.) get watchers.
+  function refreshWatchedDirs() {
+    const cwd = process.cwd();
+    for (const dir of resolveWatchDirectories(config, modes)) {
+      attachWatcherFor(dir, true);
+    }
+    for (const file of graph.allRecordedFiles()) {
+      const rel = path.relative(cwd, file);
+      if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) continue;
+      if (rel.startsWith("node_modules") || rel.startsWith(".git")) continue;
+      attachWatcherFor(path.dirname(file), false);
+    }
+  }
+  function attachConfigWatcher() {
+    if (configFileWatcher) return;
+    if (!existsSync(resolvedConfigPath)) return;
+    try {
+      configFileWatcher = fsWatch(resolvedConfigPath, () => {
+        scheduleRerun(path.relative(process.cwd(), resolvedConfigPath));
+      });
+    } catch {
+      // ignore — fs.watch on a single file isn't supported everywhere.
+    }
+  }
+  function closeDirWatchers() {
+    for (const w of attachedDirWatchers.values()) w.close();
+    attachedDirWatchers.clear();
+  }
+  function closeAllWatchers() {
+    closeDirWatchers();
+    if (configFileWatcher) {
+      configFileWatcher.close();
+      configFileWatcher = null;
+    }
   }
   async function triggerRerun() {
-    const changedFile = pendingFile ?? undefined;
-    pendingFile = null;
+    const trigger = pendingTrigger ?? { kind: "initial" };
+    pendingTrigger = null;
     isRunning = true;
     try {
-      await doRun(changedFile);
+      await doRun(trigger);
     } finally {
       isRunning = false;
-      if (pendingFile) {
+      if (pendingTrigger) {
         void triggerRerun();
       }
     }
   }
-  function scheduleRerun(filename) {
-    pendingFile = filename;
+  function scheduleTrigger(next, delayMs) {
+    // Manual triggers preempt any pending change-trigger; if a manual one is
+    // already pending, leave it (latest wins regardless).
+    pendingTrigger = next;
     if (debounceTimer) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
       if (isRunning) return;
       void triggerRerun();
-    }, 150);
-  }
-  // Initial run
-  await doRun();
-  // Set up file watchers
-  const watchers = [];
-  for (const dir of watchDirs) {
-    if (!existsSync(dir)) continue;
-    try {
-      const w = fsWatch(dir, { recursive: true }, (_evt, filename) => {
-        if (!filename) return;
-        const full = path.join(dir, filename);
-        if (shouldIgnoreWatchPath(full, config)) return;
-        scheduleRerun(path.relative(process.cwd(), full));
-      });
-      watchers.push(w);
-    } catch {
-      // directory may not support recursive watching; skip
+    }, delayMs);
+  }
+  function scheduleRerun(filename) {
+    if (!autoRun) {
+      // Manual mode: remember the edit (for the footer + resume) but don't run.
+      changedWhilePaused.add(path.resolve(filename));
+      return;
     }
+    scheduleTrigger({ kind: "change", file: filename }, 150);
+  }
+  function scheduleManualRerun(kind) {
+    scheduleTrigger({ kind }, 0);
   }
-  if (existsSync(resolvedConfigPath)) {
+  // Attach watchers before the initial run so file events that happen during
+  // the run are queued for the next iteration.
+  refreshWatchedDirs();
+  attachConfigWatcher();
+  // Initial run populates the graph as a side effect of recording every read.
+  await doRun({ kind: "initial" });
+  const stdin = process.stdin;
+  let rawModeEnabled = false;
+  if (stdin.isTTY && typeof stdin.setRawMode === "function") {
     try {
-      const w = fsWatch(resolvedConfigPath, () => {
-        scheduleRerun(path.relative(process.cwd(), resolvedConfigPath));
+      stdin.setRawMode(true);
+      rawModeEnabled = true;
+      stdin.resume();
+      stdin.on("data", (chunk) => {
+        // A held key (or any chord with multiple bytes) arrives as a single
+        // chunk; we only need to honour the first actionable byte. Without
+        // this guard, holding `space` would schedule a fresh rerun for every
+        // byte in the chunk.
+        for (const byte of chunk) {
+          if (byte === 0x03) {
+            if (rawModeEnabled) stdin.setRawMode(false);
+            closeAllWatchers();
+            process.exit(0);
+          }
+          if (isRunning) break;
+          if (byte === 0x77 || byte === 0x57) {
+            // `w` — toggle auto-run / manual mode.
+            autoRun = !autoRun;
+            if (autoRun) {
+              const hadPending = changedWhilePaused.size > 0;
+              if (hadPending) {
+                process.stdout.write(
+                  "\n" +
+                    chalk.dim(
+                      "Auto-run resumed — re-running all (files changed while paused).\n",
+                    ),
+                );
+                scheduleManualRerun("manual-runall");
+              } else {
+                process.stdout.write(
+                  "\n" + chalk.dim("Auto-run resumed.\n") + watchFooter(),
+                );
+              }
+            } else {
+              process.stdout.write(
+                "\n" +
+                  chalk.dim(
+                    "Auto-run paused — edits won't re-run. Press w to resume, or a / space to run now.\n",
+                  ) +
+                  watchFooter(),
+              );
+            }
+            break;
+          }
+          if (byte === 0x20 || byte === 0x0d || byte === 0x0a) {
+            scheduleManualRerun("manual-rerun");
+            break;
+          }
+          if (byte === 0x61 || byte === 0x41) {
+            scheduleManualRerun("manual-runall");
+            break;
+          }
+        }
       });
-      watchers.push(w);
-    } catch {}
+    } catch {
+      // some terminals don't support raw mode (e.g. piped stdin); just fall
+      // back to SIGINT-only behavior.
+    }
   }
   process.on("SIGINT", () => {
-    for (const w of watchers) w.close();
+    if (rawModeEnabled) stdin.setRawMode(false);
+    closeAllWatchers();
     process.exit(0);
   });
   // Keep the process alive
   await new Promise(() => {});
 }
-function resolveWatchDirectories(config) {
+// Union of every glob the user has declared as a spec/fuzz source —
+// top-level plus each mode override. We watch only directories derived from
+// these so unrelated files (e.g. CLI source while developing as-test itself)
+// don't trigger spurious iterations.
+function collectInputPatterns(config, modes) {
+  const out = new Set();
+  for (const p of config.input) out.add(p);
+  for (const p of config.fuzz.input) out.add(p);
+  for (const modeName of modes) {
+    if (!modeName) continue;
+    let merged;
+    try {
+      merged = applyMode(config, modeName);
+    } catch {
+      continue;
+    }
+    for (const p of merged.config.input) out.add(p);
+    for (const p of merged.config.fuzz.input) out.add(p);
+  }
+  return [...out];
+}
+function resolveWatchDirectories(config, modes) {
   const cwd = process.cwd();
   const dirs = new Set();
-  for (const pattern of config.input) {
+  const patterns = collectInputPatterns(config, modes);
+  for (const pattern of patterns) {
+    // `!`-prefixed entries are exclusions, not include sources — their
+    // "base" would be `!` (which never exists), causing the walk-up loop
+    // to land on cwd and watch the whole repo.
+    if (pattern.startsWith("!")) continue;
     const starIdx = pattern.indexOf("*");
     const base = starIdx >= 0 ? pattern.slice(0, starIdx) : pattern;
     let dir = path.resolve(cwd, base);
@@ -2033,20 +2437,62 @@ function resolveWatchDirectories(config) {
     }
     if (existsSync(dir)) dirs.add(dir);
   }
-  const assemblyDir = path.resolve(cwd, "assembly");
-  if (existsSync(assemblyDir)) dirs.add(assemblyDir);
-  if (dirs.size === 0) dirs.add(cwd);
+  const snapshotDir = path.resolve(cwd, config.snapshotDir);
+  if (existsSync(snapshotDir)) dirs.add(snapshotDir);
   return [...dirs];
 }
+// Returns true if `rel` (a cwd-relative path with `/` separators) matches any
+// `!`-prefixed pattern from the supplied input arrays. Lets users opt out of
+// watch events for files they've already excluded from their spec/fuzz globs
+// — no separate watch config needed.
+function matchesAnyExclusion(rel, inputs) {
+  const normalized = rel.split(path.sep).join("/");
+  for (const input of inputs) {
+    if (!input) continue;
+    const patterns = Array.isArray(input) ? input : [input];
+    for (const raw of patterns) {
+      if (typeof raw != "string" || !raw.startsWith("!")) continue;
+      const pattern = raw.slice(1);
+      if (!pattern.length) continue;
+      if (minimatch(normalized, pattern, { dot: true, matchBase: true })) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 function shouldIgnoreWatchPath(filePath, config) {
   const cwd = process.cwd();
   const rel = path.relative(cwd, filePath);
   if (rel.startsWith("node_modules") || rel.startsWith(".git")) return true;
+  // Dotfiles (.swp, .DS_Store, …) are always noise.
+  const base = path.basename(rel);
+  if (base.startsWith(".")) return true;
+  // Respect `!`-prefixed glob negations in the user's existing input arrays.
+  // Files the user already excluded from their spec/fuzz globs are also out
+  // of scope for watch — no separate "watch.ignore" config needed.
+  if (matchesAnyExclusion(rel, [config.input, config.fuzz?.input])) {
+    return true;
+  }
   const outRel = path.normalize(
     path.relative(cwd, path.resolve(cwd, config.outDir)),
   );
-  if (rel.startsWith(outRel + path.sep) || rel === outRel) return true;
-  if (!rel.endsWith(".ts") && !rel.endsWith("as-test.config.json")) return true;
+  const snapRel = path.normalize(
+    path.relative(cwd, path.resolve(cwd, config.snapshotDir)),
+  );
+  const underSnap = rel === snapRel || rel.startsWith(snapRel + path.sep);
+  const underOut = rel === outRel || rel.startsWith(outRel + path.sep);
+  // Snapshots often live under outDir (default ./.as-test/snapshots); they
+  // are dependencies of their specs, so we keep watching them even when the
+  // rest of the output tree is ignored.
+  if (underOut && !underSnap) return true;
+  if (
+    !rel.endsWith(".ts") &&
+    !rel.endsWith(".snap") &&
+    !rel.endsWith("as-test.config.json")
+  ) {
+    return true;
+  }
   return false;
 }
 async function runTestMatrix(
@@ -2061,8 +2507,17 @@ async function runTestMatrix(
   fileSummaryTotal,
   fuzzEnabled,
   fuzzOverrides,
+  onSpecOutcome,
 ) {
   const files = await resolveSelectedFiles(configPath, selectors);
+  if (files.length && configPath) {
+    try {
+      const loaded = loadConfig(configPath, false);
+      warnOnUnknownModeReferences(files, loaded.modes ?? {});
+    } catch {
+      // Best-effort: never fail the run on a scan error.
+    }
+  }
   if (!files.length) {
     if (!fuzzEnabled) {
       throw await buildNoTestFilesMatchedError(configPath, selectors);
@@ -2083,6 +2538,7 @@ async function runTestMatrix(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -2158,6 +2614,7 @@ async function runTestMatrix(
       }
       fileResults.push(result);
       allResults.push(result);
+      onSpecOutcome?.({ file, mode: modeName, failed: result.failed });
     }
     if (reporterSession.reporterKind == "default") {
       renderMatrixFileResult(
@@ -2211,10 +2668,13 @@ async function runTestMatrix(
     coverageSummary: summary.coverageSummary,
     stats: summary.stats,
     reports: summary.reports,
+    showLogs: runFlags.showLogs,
+    logSummary: summary.logSummary,
     fuzzSummary,
     modeSummary: buildModeSummary(modeState, modeSummaryTotal),
   });
   reporter.flush?.();
+  flushModeWarnings(process.argv.includes("--show-warnings"));
   return failed;
 }
 async function runFuzzModes(
@@ -2295,6 +2755,7 @@ async function runRuntimeSingleParallel(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -2365,6 +2826,8 @@ async function runRuntimeSingleParallel(
     coverageSummary: summary.coverageSummary,
     stats: summary.stats,
     reports: summary.reports,
+    showLogs: runFlags.showLogs,
+    logSummary: summary.logSummary,
     modeSummary: buildSingleModeSummary(
       summary.stats,
       summary.snapshotSummary,
@@ -2372,6 +2835,7 @@ async function runRuntimeSingleParallel(
     ),
   });
   reporter.flush?.();
+  flushModeWarnings(process.argv.includes("--show-warnings"));
   return results.some((result) => result.failed);
 }
 async function runRuntimeMatrixParallel(
@@ -2397,6 +2861,7 @@ async function runRuntimeMatrixParallel(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -2513,9 +2978,12 @@ async function runRuntimeMatrixParallel(
     coverageSummary: summary.coverageSummary,
     stats: summary.stats,
     reports: summary.reports,
+    showLogs: runFlags.showLogs,
+    logSummary: summary.logSummary,
     modeSummary: buildModeSummary(modeState, modeSummaryTotal),
   });
   reporter.flush?.();
+  flushModeWarnings(process.argv.includes("--show-warnings"));
   return allResults.some((result) => result.failed);
 }
 async function runTestSingleParallel(
@@ -2530,6 +2998,7 @@ async function runTestSingleParallel(
   fuzzEnabled,
   fuzzOverrides,
   modeName,
+  onSpecOutcome,
 ) {
   const files = await resolveSelectedFiles(configPath, selectors);
   if (!files.length && !fuzzEnabled) {
@@ -2546,6 +3015,7 @@ async function runTestSingleParallel(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -2616,6 +3086,7 @@ async function runTestSingleParallel(
         }
         buffered?.reporter.flush?.();
         results[index] = result;
+        onSpecOutcome?.({ file, mode: modeName, failed: result.failed });
         if (buffered && token != null) {
           queueDisplay.complete(token, buffered.output());
         }
@@ -2663,6 +3134,8 @@ async function runTestSingleParallel(
     coverageSummary: summary.coverageSummary,
     stats: summary.stats,
     reports: summary.reports,
+    showLogs: runFlags.showLogs,
+    logSummary: summary.logSummary,
     fuzzSummary,
     modeSummary: buildSingleModeSummary(
       summary.stats,
@@ -2671,6 +3144,7 @@ async function runTestSingleParallel(
     ),
   });
   reporter.flush?.();
+  flushModeWarnings(process.argv.includes("--show-warnings"));
   return failed;
 }
 async function runTestMatrixParallel(
@@ -2685,8 +3159,17 @@ async function runTestMatrixParallel(
   fileSummaryTotal,
   fuzzEnabled,
   fuzzOverrides,
+  onSpecOutcome,
 ) {
   const files = await resolveSelectedFiles(configPath, selectors);
+  if (files.length && configPath) {
+    try {
+      const loaded = loadConfig(configPath, false);
+      warnOnUnknownModeReferences(files, loaded.modes ?? {});
+    } catch {
+      // Best-effort: never fail the run on a scan error.
+    }
+  }
   if (!files.length) {
     if (!fuzzEnabled) {
       throw await buildNoTestFilesMatchedError(configPath, selectors);
@@ -2710,6 +3193,7 @@ async function runTestMatrixParallel(
     runtimeName: reporterSession.runtimeName,
     clean: runFlags.clean,
     verbose: runFlags.verbose,
+    showLogs: runFlags.showLogs,
     snapshotEnabled,
     createSnapshots: runFlags.createSnapshots,
   });
@@ -2775,6 +3259,7 @@ async function runTestMatrixParallel(
         }
         modeTimes[i] = formatMatrixModeTime(result.stats.time);
         fileResults.push(result);
+        onSpecOutcome?.({ file, mode: modeName, failed: result.failed });
       }
       ordered[fileIndex] = { fileName, fileResults, modeTimes };
       if (token != null) {
@@ -2847,10 +3332,13 @@ async function runTestMatrixParallel(
     coverageSummary: summary.coverageSummary,
     stats: summary.stats,
     reports: summary.reports,
+    showLogs: runFlags.showLogs,
+    logSummary: summary.logSummary,
     fuzzSummary,
     modeSummary: buildModeSummary(modeState, modeSummaryTotal),
   });
   reporter.flush?.();
+  flushModeWarnings(process.argv.includes("--show-warnings"));
   return failed;
 }
 async function runFuzzMatrixResultsParallel(
@@ -3249,6 +3737,7 @@ function createBuildFailureRunResult(error) {
       files: [],
     },
     reports: [report],
+    logSummary: { count: 0, file: null, groups: [], text: "" },
   };
 }
 function formatBuildFailureMessage(error) {
@@ -4236,6 +4725,9 @@ function aggregateRunResults(results) {
   let fallbackCoverageUncovered = 0;
   const fallbackCoverageFiles = [];
   const reports = [];
+  // run() rewrites the cumulative latest.log on every call and returns the
+  // running total, so the result with the highest count is the most complete.
+  let logSummary = { count: 0, file: null, groups: [], text: "" };
   for (const result of results) {
     stats.passedFiles += result.stats.passedFiles;
     stats.failedFiles += result.stats.failedFiles;
@@ -4275,6 +4767,9 @@ function aggregateRunResults(results) {
       }
     }
     reports.push(...result.reports);
+    if (result.logSummary && result.logSummary.count >= logSummary.count) {
+      logSummary = result.logSummary;
+    }
   }
   if (uniqueCoveragePoints.size > 0) {
     const byFile = new Map();
@@ -4320,7 +4815,7 @@ function aggregateRunResults(results) {
   coverageSummary.percent = coverageSummary.total
     ? (coverageSummary.covered * 100) / coverageSummary.total
     : 100;
-  return { stats, snapshotSummary, coverageSummary, reports };
+  return { stats, snapshotSummary, coverageSummary, reports, logSummary };
 }
 function printCliError(error) {
   const message = error instanceof Error ? error.message : String(error);