as-test 0.5.3 → 1.0.0

package/bin/index.js

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 import chalk from "chalk";
-import { build } from "./build.js";
-import { createRunReporter, run } from "./run.js";
-import { init } from "./init.js";
-import { getCliVersion, loadConfig, resolveModeNames } from "./util.js";
+import { build } from "./commands/build.js";
+import { createRunReporter, run } from "./commands/run.js";
+import { executeBuildCommand } from "./commands/build.js";
+import { executeRunCommand } from "./commands/run.js";
+import { executeTestCommand } from "./commands/test.js";
+import { executeInitCommand } from "./commands/init.js";
+import { executeDoctorCommand } from "./commands/doctor.js";
+import { applyMode, getCliVersion, loadConfig, resolveModeNames, } from "./util.js";
 import * as path from "path";
 import { glob } from "glob";
 const _args = process.argv.slice(2);
 const flags = [];
 const args = [];
-const COMMANDS = ["run", "build", "test", "init"];
+const COMMANDS = ["run", "build", "test", "init", "doctor"];
 const version = getCliVersion();
 const configPath = resolveConfigPath(_args);
 const selectedModes = resolveModeNames(_args);
@@ -30,44 +34,59 @@ if (!args.length) {
 else if (COMMANDS.includes(args[0])) {
     try {
         const command = args.shift();
-        const commandArgs = resolveCommandArgs(_args, command ?? "");
-        const featureToggles = resolveFeatureToggles(_args, command ?? "");
-        const buildFeatureToggles = {
-            tryAs: featureToggles.tryAs,
-            coverage: featureToggles.coverage,
-        };
-        const runFlags = {
-            snapshot: !flags.includes("--no-snapshot"),
-            updateSnapshots: flags.includes("--update-snapshots"),
-            clean: flags.includes("--clean"),
-            showCoverage: flags.includes("--show-coverage"),
-            verbose: flags.includes("--verbose"),
-            coverage: featureToggles.coverage,
-        };
-        if (command === "build") {
-            const modeTargets = resolveExecutionModes(configPath, selectedModes);
-            runBuildModes(configPath, commandArgs, modeTargets, buildFeatureToggles).catch((error) => {
+        const normalizedCommand = command ?? "";
+        if (shouldShowCommandHelp(_args, normalizedCommand)) {
+            printCommandHelp(normalizedCommand);
+        }
+        else if (command === "build") {
+            executeBuildCommand(_args, configPath, selectedModes, {
+                resolveCommandArgs,
+                resolveListFlags,
+                resolveFeatureToggles,
+                resolveExecutionModes,
+                listExecutionPlan,
+                runBuildModes,
+            }).catch((error) => {
                 printCliError(error);
                 process.exit(1);
             });
         }
         else if (command === "run") {
-            const modeTargets = resolveExecutionModes(configPath, selectedModes);
-            runRuntimeModes(runFlags, configPath, commandArgs, modeTargets).catch((error) => {
+            executeRunCommand(_args, flags, configPath, selectedModes, {
+                resolveCommandArgs,
+                resolveListFlags,
+                resolveFeatureToggles,
+                resolveExecutionModes,
+                listExecutionPlan,
+                runRuntimeModes,
+            }).catch((error) => {
                 printCliError(error);
                 process.exit(1);
             });
         }
         else if (command === "test") {
-            const modeTargets = resolveExecutionModes(configPath, selectedModes);
-            runTestModes(runFlags, configPath, commandArgs, modeTargets, buildFeatureToggles).catch((error) => {
+            executeTestCommand(_args, flags, configPath, selectedModes, {
+                resolveCommandArgs,
+                resolveListFlags,
+                resolveFeatureToggles,
+                resolveExecutionModes,
+                listExecutionPlan,
+                runTestModes,
+            }).catch((error) => {
                 printCliError(error);
                 process.exit(1);
             });
         }
         else if (command === "init") {
-            const commandTokens = resolveCommandTokens(_args, command ?? "");
-            init(commandTokens).catch((error) => {
+            executeInitCommand(_args, {
+                resolveCommandTokens,
+            }).catch((error) => {
+                printCliError(error);
+                process.exit(1);
+            });
+        }
+        else if (command === "doctor") {
+            executeDoctorCommand(configPath, selectedModes).catch((error) => {
                 printCliError(error);
                 process.exit(1);
             });
@@ -126,6 +145,12 @@ function info() {
         chalk.dim("<./dir>") +
         "                " +
         "Initialize an empty testing template");
+    console.log("  " +
+        chalk.bold.magentaBright("doctor") +
+        "  " +
+        chalk.dim("<--mode x>") +
+        "             " +
+        "Validate environment/config/runtime setup");
     console.log("");
     console.log(chalk.bold("Flags:"));
     console.log("   " +
@@ -154,11 +179,11 @@ function info() {
         "Print all coverage points with line:column refs");
     console.log("   " +
         chalk.bold.blue("--enable <feature>") +
-        "           " +
+        "            " +
         "Enable as-test feature (coverage|try-as)");
     console.log("   " +
         chalk.bold.blue("--disable <feature>") +
-        "          " +
+        "           " +
         "Disable as-test feature (coverage|try-as)");
     console.log("   " +
         chalk.bold.blue("--verbose") +
@@ -168,6 +193,15 @@ function info() {
         chalk.bold.blue("--reporter <name|path>") +
         "        " +
         "Use built-in reporter (default|tap) or custom module path");
+    console.log("   " +
+        chalk.bold.blue("--list") +
+        "                        " +
+        "Preview resolved files/modes/artifacts without running");
+    console.log("   " +
+        chalk.bold.blue("--list-modes") +
+        "                  " +
+        "Preview configured and selected mode names");
+    console.log("   " + chalk.bold.blue("--help, -h") + "                    Show help");
     console.log("");
     console.log(chalk.dim("If your using this, consider dropping a star, it would help a lot!") + "\n");
     console.log("View the repo:                   " +
@@ -177,6 +211,102 @@ function info() {
     //     chalk.blue("https://docs.jairus.dev/as-test"),
     // );
 }
+function isHelpFlag(value) {
+    return value == "--help" || value == "-h";
+}
+function shouldShowCommandHelp(rawArgs, command) {
+    if (!command.length)
+        return false;
+    const commandIndex = rawArgs.indexOf(command);
+    if (commandIndex == -1)
+        return false;
+    for (let i = 0; i < rawArgs.length; i++) {
+        if (i == commandIndex)
+            continue;
+        if (!isHelpFlag(rawArgs[i]))
+            continue;
+        return true;
+    }
+    return false;
+}
+function printCommandHelp(command) {
+    if (command == "build") {
+        process.stdout.write(chalk.bold("Usage: ast build [selectors...] [flags]\n\n"));
+        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");
+        process.stdout.write("  --disable <feature>      Disable build feature (coverage|try-as)\n");
+        process.stdout.write("  --list                   Preview resolved files/artifacts without building\n");
+        process.stdout.write("  --list-modes             Preview configured and selected mode names\n");
+        process.stdout.write("  --help, -h               Show this help\n");
+        return;
+    }
+    if (command == "run") {
+        process.stdout.write(chalk.bold("Usage: ast run [selectors...] [flags]\n\n"));
+        process.stdout.write("Run compiled specs with the configured runtime.\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("  --update-snapshots       Create/update snapshot files on mismatch\n");
+        process.stdout.write("  --no-snapshot            Disable snapshot assertions for this run\n");
+        process.stdout.write("  --show-coverage          Print uncovered coverage point details\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("  --reporter <name|path>   Use built-in reporter (default|tap) or custom module path\n");
+        process.stdout.write("  --tap                    Shortcut for --reporter tap\n");
+        process.stdout.write("  --verbose                Keep expanded suite/test lines and live updates\n");
+        process.stdout.write("  --clean                  Disable in-place TTY updates; print final lines only\n");
+        process.stdout.write("  --list                   Preview resolved files/artifacts/runtime without running\n");
+        process.stdout.write("  --list-modes             Preview configured and selected mode names\n");
+        process.stdout.write("  --help, -h               Show this help\n");
+        return;
+    }
+    if (command == "test") {
+        process.stdout.write(chalk.bold("Usage: ast test [selectors...] [flags]\n\n"));
+        process.stdout.write("Build selected specs, run them, and print a final summary.\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("  --update-snapshots       Create/update snapshot files on mismatch\n");
+        process.stdout.write("  --no-snapshot            Disable snapshot assertions for this run\n");
+        process.stdout.write("  --show-coverage          Print uncovered coverage point details\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("  --reporter <name|path>   Use built-in reporter (default|tap) or custom module path\n");
+        process.stdout.write("  --tap                    Shortcut for --reporter tap\n");
+        process.stdout.write("  --verbose                Keep expanded suite/test lines and live updates\n");
+        process.stdout.write("  --clean                  Disable in-place TTY updates; print final lines only\n");
+        process.stdout.write("  --list                   Preview resolved files/artifacts/runtime without running\n");
+        process.stdout.write("  --list-modes             Preview configured and selected mode names\n");
+        process.stdout.write("  --help, -h               Show this help\n");
+        return;
+    }
+    if (command == "init") {
+        process.stdout.write(chalk.bold("Usage: ast init [dir] [flags]\n\n"));
+        process.stdout.write("Initialize as-test config, default runners, and example specs.\n\n");
+        process.stdout.write(chalk.bold("Flags:\n"));
+        process.stdout.write("  --target <wasi|bindings>                Set build target\n");
+        process.stdout.write("  --example <minimal|full|none>           Set example template\n");
+        process.stdout.write("  --install                               Install dependencies after scaffolding\n");
+        process.stdout.write("  --yes, -y                               Non-interactive setup with defaults\n");
+        process.stdout.write("  --force                                 Overwrite managed files\n");
+        process.stdout.write("  --dir <path>                            Target output directory\n");
+        process.stdout.write("  --help, -h                              Show this help\n");
+        return;
+    }
+    if (command == "doctor") {
+        process.stdout.write(chalk.bold("Usage: ast doctor [flags]\n\n"));
+        process.stdout.write("Validate config, dependencies, runtime command, and spec discovery.\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 checks for one or multiple named modes\n");
+        process.stdout.write("  --help, -h               Show this help\n");
+        return;
+    }
+    info();
+}
 function resolveConfigPath(rawArgs) {
     for (let i = 0; i < rawArgs.length; i++) {
         const arg = rawArgs[i];
@@ -277,6 +407,29 @@ function resolveFeatureToggles(rawArgs, command) {
     }
     return out;
 }
+function resolveListFlags(rawArgs, command) {
+    const out = {
+        list: false,
+        listModes: false,
+    };
+    if (command !== "build" && command !== "run" && command !== "test") {
+        return out;
+    }
+    let seenCommand = false;
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (!seenCommand) {
+            if (arg == command)
+                seenCommand = true;
+            continue;
+        }
+        if (arg == "--list")
+            out.list = true;
+        if (arg == "--list-modes")
+            out.listModes = true;
+    }
+    return out;
+}
 function applyFeatureToggle(out, rawFeature, enabled) {
     const key = rawFeature.trim().toLowerCase();
     if (key == "coverage") {
@@ -306,10 +459,7 @@ function resolveCommandTokens(rawArgs, command) {
 async function runTestSequential(runFlags, configPath, selectors, buildFeatureToggles, modeSummaryTotal, fileSummaryTotal, modeName) {
     const files = await resolveSelectedFiles(configPath, selectors);
     if (!files.length) {
-        const scope = selectors.length > 0
-            ? selectors.join(", ")
-            : "configured input patterns";
-        throw new Error(`No test files matched: ${scope}`);
+        throw await buildNoTestFilesMatchedError(configPath, selectors);
     }
     const reporterSession = await createRunReporter(configPath, undefined, modeName);
     const reporter = reporterSession.reporter;
@@ -323,9 +473,10 @@ async function runTestSequential(runFlags, configPath, selectors, buildFeatureTo
     });
     const results = [];
     let failed = false;
+    const duplicateSpecBasenames = resolveDuplicateSpecBasenames(files);
     for (const file of files) {
         await build(configPath, [file], modeName, buildFeatureToggles);
-        const artifactKey = path.basename(file).replace(/[^a-zA-Z0-9._-]/g, "_");
+        const artifactKey = resolvePerFileArtifactKey(file, duplicateSpecBasenames);
         const result = await run(runFlags, configPath, [file], false, {
             reporter,
             emitRunStart: false,
@@ -381,10 +532,7 @@ async function runRuntimeModes(runFlags, configPath, selectors, modes) {
 async function runRuntimeMatrix(runFlags, configPath, selectors, modes, modeSummaryTotal, fileSummaryTotal) {
     const files = await resolveSelectedFiles(configPath, selectors);
     if (!files.length) {
-        const scope = selectors.length > 0
-            ? selectors.join(", ")
-            : "configured input patterns";
-        throw new Error(`No test files matched: ${scope}`);
+        throw await buildNoTestFilesMatchedError(configPath, selectors);
     }
     const reporterSession = await createRunReporter(configPath);
     const reporter = reporterSession.reporter;
@@ -409,6 +557,7 @@ async function runRuntimeMatrix(runFlags, configPath, selectors, modes, modeSumm
         failed: false,
         passed: false,
     }));
+    const duplicateSpecBasenames = resolveDuplicateSpecBasenames(files);
     for (let fileIndex = 0; fileIndex < files.length; fileIndex++) {
         const file = files[fileIndex];
         const fileName = path.basename(file);
@@ -420,7 +569,7 @@ async function runRuntimeMatrix(runFlags, configPath, selectors, modes, modeSumm
         for (let i = 0; i < modes.length; i++) {
             const modeName = modes[i];
             try {
-                const artifactKey = fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+                const artifactKey = resolvePerFileArtifactKey(file, duplicateSpecBasenames);
                 const result = await run(runFlags, configPath, [file], false, {
                     reporter: silentReporter,
                     reporterKind: "default",
@@ -490,10 +639,7 @@ async function runTestModes(runFlags, configPath, selectors, modes, buildFeature
 async function runTestMatrix(runFlags, configPath, selectors, modes, buildFeatureToggles, modeSummaryTotal, fileSummaryTotal) {
     const files = await resolveSelectedFiles(configPath, selectors);
     if (!files.length) {
-        const scope = selectors.length > 0
-            ? selectors.join(", ")
-            : "configured input patterns";
-        throw new Error(`No test files matched: ${scope}`);
+        throw await buildNoTestFilesMatchedError(configPath, selectors);
     }
     const reporterSession = await createRunReporter(configPath);
     const reporter = reporterSession.reporter;
@@ -518,6 +664,7 @@ async function runTestMatrix(runFlags, configPath, selectors, modes, buildFeatur
         failed: false,
         passed: false,
     }));
+    const duplicateSpecBasenames = resolveDuplicateSpecBasenames(files);
     for (let fileIndex = 0; fileIndex < files.length; fileIndex++) {
         const file = files[fileIndex];
         const fileName = path.basename(file);
@@ -530,7 +677,7 @@ async function runTestMatrix(runFlags, configPath, selectors, modes, buildFeatur
             const modeName = modes[i];
             try {
                 await build(configPath, [file], modeName, buildFeatureToggles);
-                const artifactKey = fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+                const artifactKey = resolvePerFileArtifactKey(file, duplicateSpecBasenames);
                 const result = await run(runFlags, configPath, [file], false, {
                     reporter: silentReporter,
                     reporterKind: "default",
@@ -590,7 +737,9 @@ function renderMatrixFileResult(file, modes, results, modeTimes, liveMatrix, sho
             : chalk.bgBlackBright.white(" SKIP ");
     const avg = formatMatrixAverageTime(results);
     const timingText = showPerModeTimes ? modeTimes.join(",") : avg;
-    const suffix = showPerModeTimes ? ` ${chalk.dim(`(${modes.join(",")})`)}` : "";
+    const suffix = showPerModeTimes
+        ? ` ${chalk.dim(`(${modes.join(",")})`)}`
+        : "";
     const line = `${badge} ${file} ${chalk.dim(timingText)}${suffix}`;
     if (liveMatrix)
         clearLiveLine();
@@ -616,7 +765,9 @@ function renderMatrixLiveLine(file, modes, modeTimes, showPerModeTimes) {
     if (!canRewriteStdout())
         return;
     const timingText = showPerModeTimes ? modeTimes.join(",") : "...";
-    const suffix = showPerModeTimes ? ` ${chalk.dim(`(${modes.join(",")})`)}` : "";
+    const suffix = showPerModeTimes
+        ? ` ${chalk.dim(`(${modes.join(",")})`)}`
+        : "";
     const line = `${chalk.bgBlackBright.white(" .... ")} ${file} ${chalk.dim(timingText)}${suffix}`;
     process.stdout.write(`\r\x1b[2K${line}`);
 }
@@ -629,7 +780,9 @@ function formatMatrixAverageTime(results) {
         return "0.0ms";
     let total = 0;
     for (const result of results) {
-        total += Number.isFinite(result.stats.time) ? Math.max(0, result.stats.time) : 0;
+        total += Number.isFinite(result.stats.time)
+            ? Math.max(0, result.stats.time)
+            : 0;
     }
     return `${(total / results.length).toFixed(1)}ms`;
 }
@@ -711,16 +864,105 @@ function resolveExecutionModes(configPath, selectedModes) {
         return [undefined];
     return configuredModes;
 }
-async function resolveSelectedFiles(configPath, selectors) {
+async function resolveSelectedFiles(configPath, selectors, warn = true) {
     const resolvedConfigPath = configPath ?? path.join(process.cwd(), "./as-test.config.json");
-    const config = loadConfig(resolvedConfigPath, true);
+    const config = loadConfig(resolvedConfigPath, warn);
     const patterns = resolveInputPatterns(config.input, selectors);
     const matches = await glob(patterns);
     const specs = matches.filter((file) => file.endsWith(".spec.ts"));
     return [...new Set(specs)].sort((a, b) => a.localeCompare(b));
 }
+async function buildNoTestFilesMatchedError(configPath, selectors) {
+    const scope = selectors.length > 0 ? selectors.join(", ") : "configured input patterns";
+    const lines = [`No test files matched: ${scope}`];
+    const configuredFiles = await resolveSelectedFiles(configPath, [], false);
+    if (!selectors.length) {
+        lines.push('No specs were discovered from configured input patterns. Check "input" in config or run "ast doctor".');
+        return new Error(lines.join("\n"));
+    }
+    const suggestions = suggestClosestSuites(selectors, configuredFiles);
+    if (suggestions.length) {
+        lines.push(`Closest suite names: ${suggestions.join(", ")}`);
+    }
+    if (configuredFiles.length) {
+        const sample = configuredFiles
+            .slice(0, 5)
+            .map((file) => path.basename(file))
+            .join(", ");
+        lines.push(`Configured specs (${configuredFiles.length}): ${sample}${configuredFiles.length > 5 ? ", ..." : ""}`);
+    }
+    else {
+        lines.push('No specs were discovered from configured input patterns. Check "input" in config.');
+    }
+    lines.push('Run "ast test --list" to inspect resolved files.');
+    return new Error(lines.join("\n"));
+}
+function suggestClosestSuites(selectors, files) {
+    const suites = [
+        ...new Set(files.map((file) => stripSuiteSuffix(path.basename(file)))),
+    ];
+    if (!suites.length)
+        return [];
+    const out = new Set();
+    for (const selector of expandSelectors(selectors)) {
+        if (!isBareSuiteSelector(selector))
+            continue;
+        const query = stripSuiteSuffix(path.basename(selector));
+        const closest = resolveClosestSuiteName(query, suites);
+        if (closest)
+            out.add(closest);
+    }
+    return [...out].slice(0, 3);
+}
+function resolveClosestSuiteName(value, candidates) {
+    if (!value.length)
+        return null;
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    const lowered = value.toLowerCase();
+    for (const candidate of candidates) {
+        if (candidate == value)
+            return null;
+        const normalized = candidate.toLowerCase();
+        if (normalized.startsWith(lowered) || normalized.includes(lowered)) {
+            return candidate;
+        }
+        const distance = levenshteinDistance(lowered, normalized);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    if (best && bestDistance <= 3)
+        return best;
+    return null;
+}
+function levenshteinDistance(left, right) {
+    if (left == right)
+        return 0;
+    if (!left.length)
+        return right.length;
+    if (!right.length)
+        return left.length;
+    const matrix = [];
+    for (let i = 0; i <= left.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= right.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= left.length; i++) {
+        for (let j = 1; j <= right.length; j++) {
+            const cost = left[i - 1] == right[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[left.length][right.length];
+}
 function resolveInputPatterns(configured, selectors) {
-    const configuredInputs = Array.isArray(configured) ? configured : [configured];
+    const configuredInputs = Array.isArray(configured)
+        ? configured
+        : [configured];
     if (!selectors.length)
         return configuredInputs;
     const patterns = new Set();
@@ -770,6 +1012,121 @@ function isBareSuiteSelector(selector) {
 function stripSuiteSuffix(selector) {
     return selector.replace(/\.spec\.ts$/, "").replace(/\.ts$/, "");
 }
+function resolveDuplicateSpecBasenames(files) {
+    const counts = new Map();
+    for (const file of files) {
+        const base = path.basename(file);
+        counts.set(base, (counts.get(base) ?? 0) + 1);
+    }
+    const duplicates = new Set();
+    for (const [base, count] of counts) {
+        if (count > 1)
+            duplicates.add(base);
+    }
+    return duplicates;
+}
+function resolvePerFileArtifactKey(file, duplicateSpecBasenames) {
+    const base = path.basename(file);
+    let raw = base;
+    if (duplicateSpecBasenames.has(base)) {
+        const disambiguator = resolvePerFileDisambiguator(file);
+        if (disambiguator.length) {
+            raw = `${base}.${disambiguator}`;
+        }
+    }
+    return raw.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function resolvePerFileDisambiguator(file) {
+    const relDir = path.dirname(path.relative(process.cwd(), file));
+    if (!relDir.length || relDir == ".")
+        return "";
+    return relDir
+        .replace(/[\\/]+/g, "__")
+        .replace(/[^A-Za-z0-9._-]/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function resolveArtifactFileNameForPreview(file, target, modeName, duplicateSpecBasenames) {
+    const base = path
+        .basename(file)
+        .replace(/\.spec\.ts$/, "")
+        .replace(/\.ts$/, "");
+    const legacy = !modeName
+        ? `${path.basename(file).replace(".ts", ".wasm")}`
+        : `${base}.${modeName}.${target}.wasm`;
+    if (!duplicateSpecBasenames.has(path.basename(file))) {
+        return legacy;
+    }
+    const disambiguator = resolvePerFileDisambiguator(file);
+    if (!disambiguator.length) {
+        return legacy;
+    }
+    const ext = path.extname(legacy);
+    const stem = ext.length ? legacy.slice(0, -ext.length) : legacy;
+    return `${stem}.${disambiguator}${ext}`;
+}
+async function listExecutionPlan(command, configPath, selectors, modes, listFlags) {
+    const resolvedConfigPath = configPath ?? path.join(process.cwd(), "./as-test.config.json");
+    const config = loadConfig(resolvedConfigPath, true);
+    const configuredModes = Object.keys(config.modes);
+    const configuredModeLabels = configuredModes.length
+        ? configuredModes
+        : ["default"];
+    const selectedModeLabels = modes.map((modeName) => modeName ?? "default");
+    const unknownModes = modes.filter((modeName) => Boolean(modeName && !configuredModes.includes(modeName)));
+    if (unknownModes.length) {
+        throw new Error(`unknown mode "${unknownModes[0]}". Available modes: ${configuredModes.join(", ") || "(none)"}`);
+    }
+    process.stdout.write(chalk.bold.blueBright("as-test plan") + "\n");
+    process.stdout.write(chalk.dim(`command: ${command}`) + "\n");
+    process.stdout.write(chalk.dim(`config: ${resolvedConfigPath}`) + "\n");
+    process.stdout.write(chalk.dim(`selectors: ${selectors.length ? selectors.join(", ") : "(configured input patterns)"}`) + "\n\n");
+    if (listFlags.listModes) {
+        process.stdout.write(chalk.bold("Configured modes:\n"));
+        for (const modeName of configuredModeLabels) {
+            process.stdout.write(`  - ${modeName}\n`);
+        }
+        process.stdout.write(chalk.bold("\nSelected modes:\n"));
+        for (const modeName of selectedModeLabels) {
+            process.stdout.write(`  - ${modeName}\n`);
+        }
+        process.stdout.write("\n");
+    }
+    if (!listFlags.list)
+        return;
+    const files = await resolveSelectedFiles(configPath, selectors);
+    if (!files.length) {
+        const scope = selectors.length > 0 ? selectors.join(", ") : "configured input patterns";
+        throw new Error(`No test files matched: ${scope}`);
+    }
+    const duplicateSpecBasenames = resolveDuplicateSpecBasenames(files);
+    process.stdout.write(chalk.bold("Resolved files:\n"));
+    for (const file of files) {
+        process.stdout.write(`  - ${file}\n`);
+    }
+    process.stdout.write("\n");
+    for (const modeName of modes) {
+        const applied = applyMode(config, modeName);
+        const active = applied.config;
+        const modeLabel = modeName ?? "default";
+        process.stdout.write(chalk.bold(`Mode: ${modeLabel}\n`));
+        process.stdout.write(`  target: ${active.buildOptions.target}\n`);
+        process.stdout.write(`  outDir: ${active.outDir}\n`);
+        if (command != "build") {
+            process.stdout.write(`  runtime: ${active.runOptions.runtime.cmd}\n`);
+        }
+        const envOverrides = modeName
+            ? (config.modes[modeName]?.env ?? {})
+            : config.env;
+        const envKeys = Object.keys(envOverrides);
+        process.stdout.write(`  env overrides: ${envKeys.length}${envKeys.length ? ` (${envKeys.join(", ")})` : ""}\n`);
+        process.stdout.write("  artifacts:\n");
+        for (const file of files) {
+            const artifactName = resolveArtifactFileNameForPreview(file, active.buildOptions.target, modeName, duplicateSpecBasenames);
+            process.stdout.write(`    - ${path.join(active.outDir, artifactName)}\n`);
+        }
+        process.stdout.write("\n");
+    }
+}
 function aggregateRunResults(results) {
     const stats = {
         passedFiles: 0,
@@ -821,7 +1178,8 @@ function aggregateRunResults(results) {
         snapshotSummary.created += result.snapshotSummary.created;
         snapshotSummary.updated += result.snapshotSummary.updated;
         snapshotSummary.failed += result.snapshotSummary.failed;
-        coverageSummary.enabled = coverageSummary.enabled || result.coverageSummary.enabled;
+        coverageSummary.enabled =
+            coverageSummary.enabled || result.coverageSummary.enabled;
         coverageSummary.showPoints =
             coverageSummary.showPoints || result.coverageSummary.showPoints;
         for (const fileCoverage of result.coverageSummary.files) {