as-test 0.5.3 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## 2026-03-11 - v1.0.0
+
+### Docs
+
+- docs: add README guidance for strict config validation behavior and example error output.
+
+### CLI & Config Validation
+
+- feat: validate config shape and field types before applying defaults for all CLI entry points.
+- feat: reject unknown config keys with nearest-key suggestions.
+- feat: show structured validation diagnostics with JSON paths and fix hints.
+- feat: fail fast on invalid config JSON with parser error details.
+- 
+### Release Readiness
+
+- fix: resolve `@assemblyscript/wasi-shim` and `try-as` with package resolution instead of assuming a local `./node_modules` folder, so nested example projects and other valid installs run correctly.
+- fix: pass the WASI shim config to `asc` as a cwd-relative path, which avoids nested-project WASI build failures with standalone examples.
+- feat: add root `test:examples` coverage and include full standalone example validation in `release:check`.
+- feat: validate all examples in both `wasi` and `bindings` modes as part of release readiness.
+- docs: update README and examples docs for the standalone example layout and root-level validation flow.
+- chore: promote package version to `1.0.0` and switch `publishConfig` to public npm publishing.
+
 ## 2026-02-25 - v0.5.3
 
 ### CLI, Modes & Matrix

package/README.md

@@ -9,11 +9,13 @@
 - [Installation](#installation)
 - [Examples](#examples)
 - [Writing Tests](#writing-tests)
+- [Setup Diagnostics](#setup-diagnostics)
 - [Mocking](#mocking)
 - [Snapshots](#snapshots)
 - [Coverage](#coverage)
 - [Custom Reporters](#custom-reporters)
 - [Assertions](#assertions)
+- [CLI Style Guide](#cli-style-guide)
 - [License](#license)
 - [Contact](#contact)
 
@@ -40,6 +42,11 @@ The installation script will set everything up for you:
 npx as-test init --dir ./path-to-install
 ```
 
+To scaffold and install dependencies in one step:
+```bash
+npx as-test init --dir ./path-to-install --install
+```
+
 Alternatively, you can install it manually:
 ```bash
 npm install as-test --save-dev
@@ -49,13 +56,19 @@ npm install as-test --save-dev
 
 Full runnable examples live in `examples/`, including:
 
+- one standalone project per example (initialized with `ast init`)
 - complete spec files for core features
 - import mocking and import snapshot patterns
-- mode-based runtime matrix config in `examples/as-test.config.json`
-- a dedicated config you can run directly
 
 See `examples/README.md` for the walkthrough.
 
+Quick validation from this repo:
+
+```bash
+npm test
+npm run test:examples
+```
+
 ## Writing Tests
 
 Create `assembly/__tests__/math.spec.ts`:
@@ -130,6 +143,9 @@ No test files matched: ...
 - `--disable <feature>`: disable as-test feature (`coverage`, `try-as`)
 - `--verbose`: keep expanded suite/test lines and update running `....` statuses in place
 - `--clean`: disable in-place TTY updates and print only final per-file verdict lines. Useful for CI/CD.
+- `--list`: show resolved files, per-mode artifacts, and runtime command without executing
+- `--list-modes`: show configured and selected modes without executing
+- `--help` / `-h`: show command-specific help (`ast test --help`, `ast init --help`, etc.)
 
 Example:
 
@@ -138,6 +154,39 @@ ast build --enable try-as
 ast test --disable coverage
 ```
 
+Preview execution plan:
+
+```bash
+ast test --list
+ast test --list-modes
+ast run sleep --list --mode wasi
+ast build --list --mode wasi,bindings
+```
+
+## Setup Diagnostics
+
+Use `ast doctor` to validate local setup before running tests.
+
+```bash
+ast doctor
+```
+
+You can also target specific modes and config files:
+
+```bash
+ast doctor --config ./as-test.config.json --mode wasi,bindings
+```
+
+`doctor` checks:
+
+- config file loading and mode resolution
+- required dependencies (for example `assemblyscript`, `@assemblyscript/wasi-shim` for WASI targets)
+- runtime command parsing and executable availability
+- runtime script path existence (for script-host runtimes)
+- test spec file discovery from configured input patterns
+
+If any `ERROR` checks are found, `ast doctor` exits non-zero.
+
 ## Mocking
 
 Use these helpers when you need to replace behavior during tests:
@@ -248,10 +297,7 @@ Example:
 {
   "$schema": "./as-test.config.schema.json",
   "input": ["./assembly/__tests__/*.spec.ts"],
-  "outDir": "./.as-test/build",
-  "logs": "./.as-test/logs",
-  "coverageDir": "./.as-test/coverage",
-  "snapshotDir": "./.as-test/snapshots",
+  "output": "./.as-test/",
   "config": "none",
   "coverage": true,
   "env": {},
@@ -273,10 +319,12 @@ Example:
 Key fields:
 
 - `input`: glob list of spec files
+- `output`: output alias. Use a root string (`"./.as-test/"`) or object (`{ "build": "...", "logs": "...", "coverage": "...", "snapshots": "..." }`)
 - `outDir`: compiled wasm output dir
 - `logs`: log output dir or `"none"`
 - `coverageDir`: coverage output dir or `"none"`
 - `snapshotDir`: snapshot storage dir
+- `outDir`, `logs`, `coverageDir`, and `snapshotDir` still work; when both are set, these explicit fields override `output`
 - `env`: environment variables injected into build and runtime processes
 - `buildOptions.cmd`: optional custom build command template; when set it replaces default build command and flags. Supports `<file>`, `<name>`, `<outFile>`, `<target>`, `<mode>`
 - `buildOptions.target`: `wasi` or `bindings`
@@ -284,6 +332,25 @@ Key fields:
 - `runOptions.runtime.cmd`: runtime command, supports `<file>` and `<name>`; if its script path is missing, as-test falls back to the default runner for the selected target
 - `runOptions.reporter`: reporter selection as a string or object
 
+Validation behavior:
+
+- Config parsing is strict for `ast build`, `ast run`, `ast test`, and `ast doctor`.
+- Invalid JSON fails early with parser details (`line`/`column` when provided by Node).
+- Unknown properties are rejected and include a nearest-key suggestion when possible.
+- Invalid property types are reported with their JSON path and a short fix hint.
+- On validation failure, the command exits non-zero and prints `run "ast doctor" to check your setup.`
+
+Example validation error:
+
+```text
+invalid config at ./as-test.config.json
+1. $.inpoot: unknown property
+     fix: use "input" if that was intended, otherwise remove this property
+2. $.runOptions.runtime.cmd: must be a string
+     fix: set to a runtime command including "<file>"
+run "ast doctor" to check your setup.
+```
+
 Example multi-runtime matrix:
 
 ```json
@@ -501,7 +568,7 @@ Available matchers:
 - `toStartWith(prefix)`
 - `toEndWith(suffix)`
 - `toHaveLength(length)`
-- `toContain(item)`
+- `toContain(itemOrSubstring)` (`toContains` alias supported)
 - `toThrow()` (with `try-as`)
 - `toMatchSnapshot(name?)`
 

package/as-test.config.schema.json

@@ -17,6 +17,37 @@
       },
       "default": ["./assembly/__tests__/*.spec.ts"]
     },
+    "output": {
+      "description": "Output alias. Use a root string or a per-artifact object. Legacy fields (outDir/logs/coverageDir/snapshotDir) still work and override this alias when both are set.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Root output directory. Expands to build/logs/coverage/snapshots subdirectories."
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "build": {
+              "type": "string",
+              "description": "Build artifact output directory (maps to outDir)."
+            },
+            "logs": {
+              "type": "string",
+              "description": "Log artifact output directory (maps to logs). Use \"none\" to disable."
+            },
+            "coverage": {
+              "type": "string",
+              "description": "Coverage artifact output directory (maps to coverageDir). Use \"none\" to disable."
+            },
+            "snapshots": {
+              "type": "string",
+              "description": "Snapshot output directory (maps to snapshotDir)."
+            }
+          }
+        }
+      ]
+    },
     "outDir": {
       "type": "string",
       "description": "Directory where compiled artifacts are written.",

package/assembly/src/expectation.ts

@@ -334,18 +334,41 @@ export class Expectation<T> extends Tests {
   }
 
   /**
-   * Tests if an array contains an element
+   * Tests if an array or string contains a value
    */
   // @ts-ignore
   toContain(value: valueof<T>): void {
-    // @ts-ignore
-    const passed = isArray<T>() && this._left.includes(value);
-    this._resolve(
-      passed,
-      "toContain",
-      q("includes value"),
-      q("does not include value"),
-    );
+    if (isString<T>()) {
+      // @ts-ignore
+      const left = this._left as string;
+      // @ts-ignore
+      const needle = value as string;
+      const passed = left.indexOf(needle) >= 0;
+      this._resolve(passed, "toContain", q(left), q(needle));
+      return;
+    }
+
+    if (isArray<T>()) {
+      // @ts-ignore
+      const passed = this._left.includes(value);
+      this._resolve(
+        passed,
+        "toContain",
+        stringifyValue<T>(this._left),
+        stringifyValue<valueof<T>>(value),
+      );
+      return;
+    }
+
+    ERROR("toContain() can only be used on string and array types!");
+  }
+
+  /**
+   * Alias for toContain().
+   */
+  // @ts-ignore
+  toContains(value: valueof<T>): void {
+    this.toContain(value);
   }
 
   /**

package/bin/{build.js → commands/build-core.js}

@@ -1,9 +1,9 @@
 import { existsSync } from "fs";
 import { glob } from "glob";
 import chalk from "chalk";
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 import * as path from "path";
-import { applyMode, getPkgRunner, loadConfig } from "./util.js";
+import { applyMode, getPkgRunner, loadConfig, tokenizeCommand, resolveProjectModule, } from "../util.js";
 const DEFAULT_CONFIG_PATH = path.join(process.cwd(), "./as-test.config.json");
 export async function build(configPath = DEFAULT_CONFIG_PATH, selectors = [], modeName, featureToggles = {}) {
     const loadedConfig = loadConfig(configPath, false);
@@ -15,20 +15,21 @@ export async function build(configPath = DEFAULT_CONFIG_PATH, selectors = [], mo
     const pkgRunner = getPkgRunner();
     const inputPatterns = resolveInputPatterns(config.input, selectors);
     const inputFiles = (await glob(inputPatterns)).sort((a, b) => a.localeCompare(b));
+    const duplicateSpecBasenames = await resolveDuplicateSpecBasenames(config.input);
     const coverageEnabled = resolveCoverageEnabled(config.coverage, featureToggles.coverage);
     const buildEnv = {
         ...mode.env,
         AS_TEST_COVERAGE_ENABLED: coverageEnabled ? "1" : "0",
     };
     for (const file of inputFiles) {
-        const outFile = `${config.outDir}/${resolveArtifactFileName(file, config.buildOptions.target, modeName)}`;
-        const cmd = getBuildCommand(config, pkgRunner, file, outFile, modeName, featureToggles);
+        const outFile = `${config.outDir}/${resolveArtifactFileName(file, config.buildOptions.target, modeName, duplicateSpecBasenames)}`;
+        const invocation = getBuildCommand(config, pkgRunner, file, outFile, modeName, featureToggles);
         try {
-            buildFile(cmd, buildEnv);
+            buildFile(invocation, buildEnv);
         }
         catch (error) {
             const modeLabel = modeName ?? "default";
-            throw new Error(`Failed to build ${path.basename(file)} in mode ${modeLabel} with ${getBuildStderr(error)}\nBuild command: ${cmd}`);
+            throw new Error(`Failed to build ${path.basename(file)} in mode ${modeLabel} with ${getBuildStderr(error)}\nBuild command: ${formatInvocation(invocation)}`);
         }
     }
 }
@@ -38,21 +39,27 @@ function hasCustomBuildCommand(config) {
 function getBuildCommand(config, pkgRunner, file, outFile, modeName, featureToggles = {}) {
     const userArgs = getUserBuildArgs(config);
     if (hasCustomBuildCommand(config)) {
-        return `${expandBuildCommand(config.buildOptions.cmd, file, outFile, config.buildOptions.target, modeName)}${userArgs}`;
+        const tokens = tokenizeCommand(expandBuildCommand(config.buildOptions.cmd, file, outFile, config.buildOptions.target, modeName));
+        if (!tokens.length) {
+            throw new Error("custom build command is empty");
+        }
+        return {
+            command: tokens[0],
+            args: [...tokens.slice(1), ...userArgs],
+        };
     }
     const defaultArgs = getDefaultBuildArgs(config, featureToggles);
-    let cmd = `${pkgRunner} asc ${file}${userArgs}${defaultArgs}`;
-    if (config.outDir) {
-        cmd += " -o " + outFile;
+    const args = ["asc", file, ...userArgs, ...defaultArgs];
+    if (config.outDir.length) {
+        args.push("-o", outFile);
     }
-    return cmd;
+    return {
+        command: pkgRunner,
+        args,
+    };
 }
 function getUserBuildArgs(config) {
-    const args = config.buildOptions.args.filter((value) => value.length > 0);
-    if (args.length) {
-        return " " + args.join(" ");
-    }
-    return "";
+    return config.buildOptions.args.filter((value) => value.length > 0);
 }
 function expandBuildCommand(template, file, outFile, target, modeName) {
     const name = path
@@ -66,15 +73,48 @@ function expandBuildCommand(template, file, outFile, target, modeName) {
         .replace(/<target>/g, target)
         .replace(/<mode>/g, modeName ?? "");
 }
-function resolveArtifactFileName(file, target, modeName) {
+function resolveArtifactFileName(file, target, modeName, duplicateSpecBasenames = new Set()) {
     const base = path
         .basename(file)
         .replace(/\.spec\.ts$/, "")
         .replace(/\.ts$/, "");
-    if (!modeName) {
-        return `${path.basename(file).replace(".ts", ".wasm")}`;
+    const legacy = !modeName
+        ? `${path.basename(file).replace(".ts", ".wasm")}`
+        : `${base}.${modeName}.${target}.wasm`;
+    if (!duplicateSpecBasenames.has(path.basename(file))) {
+        return legacy;
+    }
+    const disambiguator = resolveDisambiguator(file);
+    if (!disambiguator.length) {
+        return legacy;
     }
-    return `${base}.${modeName}.${target}.wasm`;
+    const ext = path.extname(legacy);
+    const stem = ext.length ? legacy.slice(0, -ext.length) : legacy;
+    return `${stem}.${disambiguator}${ext}`;
+}
+async function resolveDuplicateSpecBasenames(configured) {
+    const patterns = Array.isArray(configured) ? configured : [configured];
+    const files = await glob(patterns);
+    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 resolveDisambiguator(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 resolveInputPatterns(configured, selectors) {
     const configuredInputs = Array.isArray(configured)
@@ -131,18 +171,33 @@ function stripSuiteSuffix(selector) {
 }
 function ensureDeps(config) {
     if (config.buildOptions.target == "wasi") {
-        if (!existsSync("./node_modules/@assemblyscript/wasi-shim/asconfig.json")) {
+        if (!resolveWasiShim()) {
             console.log(`${chalk.bgRed(" ERROR ")}${chalk.dim(":")} could not find @assemblyscript/wasi-shim! Add it to your dependencies to run with WASI!`);
             process.exit(1);
         }
     }
 }
-function buildFile(command, env) {
-    execSync(command, {
+function buildFile(invocation, env) {
+    const result = spawnSync(invocation.command, invocation.args, {
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf8",
         env,
+        shell: false,
     });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        const error = new Error(result.stderr?.trim() ||
+            result.stdout?.trim() ||
+            `command exited with code ${result.status}`);
+        error.stderr = result.stderr ?? "";
+        throw error;
+    }
+}
+function formatInvocation(invocation) {
+    return [invocation.command, ...invocation.args]
+        .map((token) => (/\s/.test(token) ? JSON.stringify(token) : token))
+        .join(" ");
 }
 function getBuildStderr(error) {
     const err = error;
@@ -161,27 +216,28 @@ function getBuildStderr(error) {
     return message || "unknown error";
 }
 function getDefaultBuildArgs(config, featureToggles) {
-    let buildArgs = "";
+    const buildArgs = [];
     const tryAsEnabled = resolveTryAsEnabled(featureToggles.tryAs);
-    buildArgs += " --transform as-test/transform";
+    buildArgs.push("--transform", "as-test/transform");
     if (tryAsEnabled) {
-        buildArgs += " --transform try-as/transform";
+        buildArgs.push("--transform", "try-as/transform");
     }
     if (config.config && config.config !== "none") {
-        buildArgs += " --config " + config.config;
+        buildArgs.push("--config", config.config);
     }
     if (tryAsEnabled) {
-        buildArgs += " --use AS_TEST_TRY_AS=1";
+        buildArgs.push("--use", "AS_TEST_TRY_AS=1");
     }
     // Should also strip any bindings-enabling from asconfig
     if (config.buildOptions.target == "bindings") {
-        buildArgs += " --use AS_TEST_BINDINGS=1";
-        buildArgs += " --bindings raw --exportRuntime --exportStart _start";
+        buildArgs.push("--use", "AS_TEST_BINDINGS=1", "--bindings", "raw", "--exportRuntime", "--exportStart", "_start");
     }
     else if (config.buildOptions.target == "wasi") {
-        buildArgs += " --use AS_TEST_WASI=1";
-        buildArgs +=
-            " --config ./node_modules/@assemblyscript/wasi-shim/asconfig.json";
+        const wasiShim = resolveWasiShim();
+        if (!wasiShim) {
+            throw new Error('WASI target requires package "@assemblyscript/wasi-shim"');
+        }
+        buildArgs.push("--use", "AS_TEST_WASI=1", "--config", wasiShim.configPath);
     }
     else {
         console.log(`${chalk.bgRed(" ERROR ")}${chalk.dim(":")} could not determine target in config! Set target to 'bindings' or 'wasi'`);
@@ -211,6 +267,28 @@ function resolveCoverageEnabled(rawCoverage, override) {
     return true;
 }
 function hasTryAsRuntime() {
-    return (existsSync(path.join(process.cwd(), "node_modules/try-as")) ||
-        existsSync(path.join(process.cwd(), "node_modules/try-as/package.json")));
+    return resolveProjectModule("try-as/package.json") != null;
+}
+function resolveWasiShim() {
+    const resolved = resolveProjectModule("@assemblyscript/wasi-shim/asconfig.json");
+    if (!resolved)
+        return null;
+    if (!existsSync(resolved))
+        return null;
+    const relative = path.relative(process.cwd(), resolved).replace(/\\/g, "/");
+    return {
+        configPath: normalizeCliPath(relative),
+    };
+}
+function quoteCliArg(value) {
+    if (!/[\s"]/g.test(value))
+        return value;
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+function normalizeCliPath(value) {
+    if (!value.length)
+        return ".";
+    if (value.startsWith(".") || value.startsWith("/"))
+        return value;
+    return "./" + value;
 }

package/bin/commands/build.js

@@ -0,0 +1,16 @@
+export { build } from "./build-core.js";
+export async function executeBuildCommand(rawArgs, configPath, selectedModes, deps) {
+    const commandArgs = deps.resolveCommandArgs(rawArgs, "build");
+    const listFlags = deps.resolveListFlags(rawArgs, "build");
+    const featureToggles = deps.resolveFeatureToggles(rawArgs, "build");
+    const buildFeatureToggles = {
+        tryAs: featureToggles.tryAs,
+        coverage: featureToggles.coverage,
+    };
+    const modeTargets = deps.resolveExecutionModes(configPath, selectedModes);
+    if (listFlags.list || listFlags.listModes) {
+        await deps.listExecutionPlan("build", configPath, commandArgs, modeTargets, listFlags);
+        return;
+    }
+    await deps.runBuildModes(configPath, commandArgs, modeTargets, buildFeatureToggles);
+}