@sdxc/spec 0.0.0-pre.1

package/dist/ast.d.ts

@@ -0,0 +1,193 @@
+/**
+ * The abstract syntax tree for `.spec` files, mirroring GRAMMAR.md one node
+ * per production. The tree is deliberately flat and operator-free: statements
+ * are linear, arguments are literals/references/words, and the only nesting
+ * is blocks and object literals.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Span } from "./source.js";
+/** A parsed `.spec` file: its `use` imports, definitions, and tests. */
+export interface SpecFileNode {
+    /** Path the file was loaded from, used in every diagnostic. */
+    path: string;
+    /** Namespaces imported unqualified into this file (file-scoped). */
+    uses: UseNode[];
+    /** Suite-global command and fixture definitions declared here. */
+    definitions: DefinitionNode[];
+    /** Executable tests declared here, in source order. */
+    tests: TestNode[];
+}
+/** `use fs` — imports one namespace's tools as unqualified names. */
+export interface UseNode {
+    /** The imported namespace, e.g. `"fs"`. */
+    namespace: string;
+    /** Location of the whole statement. */
+    span: Span;
+}
+/** A suite-global definition: a reusable command or fixture. */
+export type DefinitionNode = CommandNode | FixtureNode;
+/** `command login(user) { … }` — reusable behavior composed of statements. */
+export interface CommandNode {
+    kind: "command";
+    /** The command's suite-global name. */
+    name: string;
+    /** Positional parameter names; empty for `command logout { … }`. */
+    params: string[];
+    /** The statements the command executes. */
+    body: BlockNode;
+    /** Location of the whole definition. */
+    span: Span;
+}
+/** `fixture user { … }` — reusable setup that yields a value via `return`. */
+export interface FixtureNode {
+    kind: "fixture";
+    /** The fixture's suite-global name. */
+    name: string;
+    /** The statements the fixture executes. */
+    body: BlockNode;
+    /** Location of the whole definition. */
+    span: Span;
+}
+/** `test "title" { given {…} when {…} then {…} }` — one specification. */
+export interface TestNode {
+    /** The test's human-readable title. */
+    title: string;
+    /** Setup phase, when present. */
+    given?: BlockNode;
+    /** Action phase, when present. */
+    when?: BlockNode;
+    /** Verification phase, when present. */
+    then?: BlockNode;
+    /** Location of the whole test. */
+    span: Span;
+}
+/** A `{ … }` sequence of statements. */
+export interface BlockNode {
+    /** The statements, in source order. */
+    statements: StatementNode[];
+    /** Location including the braces. */
+    span: Span;
+}
+/** Every statement the language has, forming a closed, exhaustive set. */
+export type StatementNode = LetNode | ReturnNode | ExpectNode | EventuallyNode | CallNode;
+/** `let name = <rhs>` — binds a value in the enclosing test/body scope. */
+export interface LetNode {
+    kind: "let";
+    /** The name being bound. */
+    name: string;
+    /** What to evaluate: an expression or a value-producing invocation. */
+    value: RhsNode;
+    span: Span;
+}
+/** `return <rhs>` — ends a fixture/command body, producing a value. */
+export interface ReturnNode {
+    kind: "return";
+    /** What to evaluate and yield to the caller. */
+    value: RhsNode;
+    span: Span;
+}
+/**
+ * The right-hand side of `let`/`return`: a plain expression, a fixture
+ * invocation, or a call expression. Calls are only legal here — never nested
+ * inside arguments — which keeps statements linear.
+ */
+export type RhsNode = ExpressionNode | FixtureCallNode | CallExprNode;
+/** `fixture user` in expression position — runs the fixture for its value. */
+export interface FixtureCallNode {
+    kind: "fixture-call";
+    name: string;
+    span: Span;
+}
+/** A value-producing invocation: `run "node" "index.js"` on a `let`/`return`. */
+export interface CallExprNode {
+    kind: "call-expr";
+    /** Dotted target as written: `"run"` or `"http.post"`. */
+    target: string;
+    /** The invocation's arguments, in order. */
+    args: ArgumentNode[];
+    span: Span;
+}
+/** `expect <argument>+` — value or observable assertion (see GRAMMAR.md). */
+export interface ExpectNode {
+    kind: "expect";
+    /** The assertion's arguments; resolution decides the form at runtime. */
+    args: ArgumentNode[];
+    span: Span;
+}
+/** `eventually [within 10s] { … }` — retried assertions, `then`-only. */
+export interface EventuallyNode {
+    kind: "eventually";
+    /** Deadline override in milliseconds, from `within <duration>`. */
+    withinMs?: number;
+    /** The assertions to retry as a unit. */
+    block: BlockNode;
+    span: Span;
+}
+/** A statement-position invocation: `login user`, `open post.url`. */
+export interface CallNode {
+    kind: "call";
+    /** Dotted target as written: `"login"`, `"fs.write"`. */
+    target: string;
+    /** The invocation's arguments, in order. */
+    args: ArgumentNode[];
+    span: Span;
+}
+/** One argument: an expression, or a bare-identifier word. */
+export type ArgumentNode = ExpressionNode | WordNode;
+/** A bare identifier in argument position — a symbol for the tool. */
+export interface WordNode {
+    kind: "word";
+    /** The identifier as written, e.g. `"exists"`, `"textbox"`, `"with"`. */
+    word: string;
+    span: Span;
+}
+/** Every expression form; references are dotted paths into bindings. */
+export type ExpressionNode = StringNode | NumberNode | BooleanNode | DurationNode | ObjectNode | ReferenceNode;
+/** A single-line or multiline string literal, already decoded/dedented. */
+export interface StringNode {
+    kind: "string";
+    /** The decoded content. */
+    value: string;
+    span: Span;
+}
+/** A numeric literal. */
+export interface NumberNode {
+    kind: "number";
+    value: number;
+    span: Span;
+}
+/** `true` or `false`. */
+export interface BooleanNode {
+    kind: "boolean";
+    value: boolean;
+    span: Span;
+}
+/** A duration literal like `10s`, normalized to milliseconds at lex time. */
+export interface DurationNode {
+    kind: "duration";
+    milliseconds: number;
+    span: Span;
+}
+/** `{ key: expr, … }` — an object literal. */
+export interface ObjectNode {
+    kind: "object";
+    /** Entries in source order; later duplicate keys are a parse error. */
+    entries: ObjectEntryNode[];
+    span: Span;
+}
+/** One `key: value` entry of an object literal. */
+export interface ObjectEntryNode {
+    /** The key, from an identifier or string. */
+    key: string;
+    value: ExpressionNode;
+    span: Span;
+}
+/** A dotted reference into bindings: `user`, `result.exit_code`. */
+export interface ReferenceNode {
+    kind: "reference";
+    /** The path segments, e.g. `["result", "exit_code"]`. */
+    path: string[];
+    span: Span;
+}

package/dist/ast.js

@@ -0,0 +1,9 @@
+/**
+ * The abstract syntax tree for `.spec` files, mirroring GRAMMAR.md one node
+ * per production. The tree is deliberately flat and operator-free: statements
+ * are linear, arguments are literals/references/words, and the only nesting
+ * is blocks and object literals.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/dist/builtins.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The built-in capability set, and how a host chooses part of it.
+ *
+ * Kept apart from the runner because importing a plugin is not free: `cli` and
+ * `browser` spawn processes and `db` imports Bun's SQL client. `runTests` takes
+ * a plugin set so a host can assemble the factories it is able to load.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Plugin } from "./plugin.js";
+/**
+ * Every built-in namespace, in the order a run registers them.
+ *
+ * The order is what a selection is sorted back into, so two hosts asking for the
+ * same namespaces get the same list regardless of how they wrote it down.
+ */
+export declare const BUILTIN_NAMESPACES: readonly ["fs", "cli", "http", "browser", "db", "url", "jwt", "env", "sample"];
+/** A built-in namespace's name. */
+export type BuiltinNamespace = (typeof BUILTIN_NAMESPACES)[number];
+/**
+ * Build the built-in plugins, all of them or a chosen few. Choosing a subset
+ * is not a permission decision: a namespace left out simply does not exist,
+ * so a spec naming it fails to resolve, on the same footing as a capability.
+ *
+ * @param only - Namespaces to build; omit for every built-in. Duplicates collapse.
+ * @returns The plugins, in {@link BUILTIN_NAMESPACES} order.
+ */
+export declare function createBuiltinPlugins(only?: readonly BuiltinNamespace[]): Plugin[];

package/dist/builtins.js

@@ -0,0 +1,66 @@
+/**
+ * The built-in capability set, and how a host chooses part of it.
+ *
+ * Kept apart from the runner because importing a plugin is not free: `cli` and
+ * `browser` spawn processes and `db` imports Bun's SQL client. `runTests` takes
+ * a plugin set so a host can assemble the factories it is able to load.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createBrowserPlugin } from "./plugins/browser.js";
+import { createCliPlugin } from "./plugins/cli.js";
+import { createDbPlugin } from "./plugins/db.js";
+import { createEnvPlugin } from "./plugins/env.js";
+import { createFsPlugin } from "./plugins/fs.js";
+import { createHttpPlugin } from "./plugins/http.js";
+import { createJwtPlugin } from "./plugins/jwt.js";
+import { createSamplePlugin } from "./plugins/sample.js";
+import { createUrlPlugin } from "./plugins/url.js";
+/**
+ * Every built-in namespace, in the order a run registers them.
+ *
+ * The order is what a selection is sorted back into, so two hosts asking for the
+ * same namespaces get the same list regardless of how they wrote it down.
+ */
+export const BUILTIN_NAMESPACES = [
+    "fs",
+    "cli",
+    "http",
+    "browser",
+    "db",
+    "url",
+    "jwt",
+    "env",
+    "sample",
+];
+/** How each built-in namespace is constructed. */
+const BUILTIN_FACTORIES = {
+    fs: createFsPlugin,
+    cli: createCliPlugin,
+    http: createHttpPlugin,
+    browser: createBrowserPlugin,
+    db: createDbPlugin,
+    url: createUrlPlugin,
+    jwt: createJwtPlugin,
+    env: createEnvPlugin,
+    sample: createSamplePlugin,
+};
+/**
+ * Build the built-in plugins, all of them or a chosen few. Choosing a subset
+ * is not a permission decision: a namespace left out simply does not exist,
+ * so a spec naming it fails to resolve, on the same footing as a capability.
+ *
+ * @param only - Namespaces to build; omit for every built-in. Duplicates collapse.
+ * @returns The plugins, in {@link BUILTIN_NAMESPACES} order.
+ */
+export function createBuiltinPlugins(only) {
+    let wanted = new Set(only ?? BUILTIN_NAMESPACES);
+    let plugins = [];
+    for (let namespace of BUILTIN_NAMESPACES) {
+        if (!wanted.has(namespace))
+            continue;
+        plugins.push(BUILTIN_FACTORIES[namespace]());
+    }
+    return plugins;
+}

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+/**
+ * The `spec` command-line interface. `spec run [dir] [--allow-*]` loads a
+ * suite and executes it under the caller's grants — nothing is granted by
+ * default, and a permission failure is a security feature, not a bug.
+ * Exit codes: 0 all passed, 1 some test failed, 2 usage or load error.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Sink } from "./diagnostics.js";
+/**
+ * Run the CLI against an argument vector and write through the sink —
+ * separated from the entry point so tests can drive it without a process.
+ * Config grants apply only with `--allow-config`, so a clone cannot self-grant.
+ *
+ * @param argv - Arguments after the program name, e.g. `["run", "spec"]`.
+ * @param sink - Where human output goes.
+ * @returns The process exit code to use.
+ */
+export declare function main(argv: string[], sink: Sink): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env bun
+/**
+ * The `spec` command-line interface. `spec run [dir] [--allow-*]` loads a
+ * suite and executes it under the caller's grants — nothing is granted by
+ * default, and a permission failure is a security feature, not a bug.
+ * Exit codes: 0 all passed, 1 some test failed, 2 usage or load error.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { readFile } from "node:fs/promises";
+import { failure, isFailure, success } from "@sdxc/result";
+import { systemSeed } from "@sdxc/sample";
+import { SpecError } from "./errors.js";
+import { loadSuite } from "./loader.js";
+import { configWouldAdmit, grantsFromConfig, mergeGrants, parseGrants } from "./permissions.js";
+import { connectDeclaredPlugins, deniedReferences, disposeAll, launchDeniedError, loadProjectConfig, mergePluginGrants, parsePluginGrant, planPluginLaunch, pluginGrantAdmits, pluginGrantFromConfig, } from "./project-config.js";
+import { reportFatal, reportSuite } from "./reporter.js";
+import { DEFAULT_SEED } from "./run.js";
+import { runSuite } from "./runner.js";
+/**
+ * The line appended to a permission denial when the project's
+ * `spec/config.jsonc` would have granted it under `--allow-config`. Points at
+ * the one-flag path without ever weakening the primary `--allow-*` remedy.
+ */
+const CONFIG_HINT = "This project's spec/config.jsonc declares this permission; re-run with --allow-config to apply the project's declared permissions.";
+/** What `spec --help` prints. */
+const USAGE = `spec — executable specifications
+
+Usage:
+  spec run [directory] [--allow-*]     Run the suite (directory defaults to ./spec)
+
+Scheduling:
+  --concurrency=N (alias --jobs=N)   Run up to N tests at once (default 1, sequential)
+
+Generated data:
+  --seed=VALUE                       Seed the data sample generates (default: fixed)
+  --seed=random                      Draw a seed and print it, to replay with --seed=<it>
+
+Permissions (denied unless granted):
+  --allow-run[=name,...]      Execute processes (scoped to executable names)
+  --allow-net[=host[:port]]   Reach the network (scoped to hosts)
+  --allow-env[=VAR,...]       Read environment variables (scoped to names)
+  --allow-host-fs[=dir,...]   Touch the host filesystem outside the workspace
+  --allow-plugins[=ns,...]    Launch project-declared plugins (from spec/config.jsonc)
+  --allow-config              Apply the permissions spec/config.jsonc declares
+`;
+/**
+ * Run the CLI against an argument vector and write through the sink —
+ * separated from the entry point so tests can drive it without a process.
+ * Config grants apply only with `--allow-config`, so a clone cannot self-grant.
+ *
+ * @param argv - Arguments after the program name, e.g. `["run", "spec"]`.
+ * @param sink - Where human output goes.
+ * @returns The process exit code to use.
+ */
+export async function main(argv, sink) {
+    if (argv[0] === "--help" || argv[0] === "-h" || argv.length === 0) {
+        sink.write(USAGE);
+        return argv.length === 0 ? 2 : 0;
+    }
+    if (argv[0] !== "run") {
+        reportFatal(new SpecError("usage-error", `Unknown command: ${argv[0]}`), sink);
+        sink.write(USAGE);
+        return 2;
+    }
+    let configOptIn = parseConfigOptIn(argv.slice(1));
+    if (isFailure(configOptIn)) {
+        reportFatal(configOptIn.error, sink);
+        return 2;
+    }
+    let { allowConfig, remaining: afterConfigOptIn } = configOptIn.data;
+    let concurrencyParsed = parseConcurrency(afterConfigOptIn);
+    if (isFailure(concurrencyParsed)) {
+        reportFatal(concurrencyParsed.error, sink);
+        return 2;
+    }
+    let { concurrency, remaining: afterConcurrency } = concurrencyParsed.data;
+    let seedParsed = parseSeed(afterConcurrency);
+    if (isFailure(seedParsed)) {
+        reportFatal(seedParsed.error, sink);
+        return 2;
+    }
+    let { seed, drawn, remaining: afterSeed } = seedParsed.data;
+    let pluginParsed = parsePluginGrant(afterSeed);
+    if (isFailure(pluginParsed)) {
+        reportFatal(pluginParsed.error, sink);
+        return 2;
+    }
+    let { grant: cliPluginGrant, remaining: afterPluginGrant } = pluginParsed.data;
+    let parsed = parseGrants(afterPluginGrant);
+    if (isFailure(parsed)) {
+        reportFatal(parsed.error, sink);
+        return 2;
+    }
+    let { grants: cliGrants, remaining } = parsed.data;
+    let unknown = remaining.filter((argument) => argument.startsWith("-"));
+    if (unknown.length > 0) {
+        reportFatal(new SpecError("usage-error", `Unknown flag: ${unknown[0]}`), sink);
+        return 2;
+    }
+    if (remaining.length > 1) {
+        reportFatal(new SpecError("usage-error", `Expected one suite directory, got: ${remaining.join(", ")}`), sink);
+        return 2;
+    }
+    let root = remaining[0] ?? "spec";
+    let config = await loadProjectConfig(root);
+    if (isFailure(config)) {
+        reportFatal(config.error, sink);
+        return 2;
+    }
+    let configEntries = config.data.permissions.allow;
+    let configGrants = grantsFromConfig(configEntries);
+    let grants = allowConfig ? mergeGrants(cliGrants, configGrants) : cliGrants;
+    let configPluginGrant = pluginGrantFromConfig(configEntries);
+    let pluginGrant = allowConfig
+        ? mergePluginGrants(cliPluginGrant, configPluginGrant)
+        : cliPluginGrant;
+    let { launch, deniedNamespaces } = planPluginLaunch(config.data, pluginGrant);
+    if (deniedNamespaces.length > 0) {
+        let loaded = await loadSuite(root);
+        if (isFailure(loaded)) {
+            reportFatal(loaded.error, sink);
+            return 2;
+        }
+        let referenced = deniedReferences(loaded.data, deniedNamespaces);
+        if (referenced.length > 0) {
+            let error = launchDeniedError(referenced);
+            if (!allowConfig && referenced.every((ns) => pluginGrantAdmits(configPluginGrant, ns))) {
+                error.hint = CONFIG_HINT;
+            }
+            reportFatal(error, sink);
+            return 2;
+        }
+    }
+    let externalPlugins = [];
+    if (launch.length > 0) {
+        let connected = await connectDeclaredPlugins(launch);
+        if (isFailure(connected)) {
+            reportFatal(connected.error, sink);
+            return 2;
+        }
+        externalPlugins = connected.data;
+    }
+    if (drawn)
+        sink.write(`seed ${seed} (replay with --seed=${seed})\n\n`);
+    let run = await runSuite({ root, grants, plugins: externalPlugins, concurrency, seed });
+    if (isFailure(run)) {
+        await disposeAll(externalPlugins);
+        reportFatal(run.error, sink);
+        return 2;
+    }
+    if (!allowConfig) {
+        for (let result of run.data.results) {
+            let error = result.error;
+            if (error === undefined || error.code !== "permission-denied")
+                continue;
+            let denial = error;
+            if (denial.permission === undefined || denial.resource === undefined)
+                continue;
+            if (configWouldAdmit(configGrants, denial.permission, denial.resource, denial.familyGate ?? false))
+                error.hint = CONFIG_HINT;
+        }
+    }
+    let sources = new Map();
+    for (let result of run.data.results) {
+        let paths = [result.file];
+        if (result.error?.file !== undefined)
+            paths.push(result.error.file);
+        for (let path of paths) {
+            if (!sources.has(path)) {
+                let text = await readFile(path, "utf8").catch(() => "");
+                sources.set(path, { path, text });
+            }
+        }
+    }
+    reportSuite(run.data, sources, sink);
+    return run.data.failed > 0 ? 1 : 0;
+}
+/**
+ * Peel the bare `--allow-config` flag out of an argument list, opting into
+ * the permissions `spec/config.jsonc` declares; `--allow-config=…` is a usage
+ * error since the flag takes no value. Other arguments pass through untouched.
+ *
+ * @param args - The raw CLI arguments after `run`.
+ * @returns Whether the opt-in was given, plus the remaining arguments.
+ */
+function parseConfigOptIn(args) {
+    let allowConfig = false;
+    let remaining = [];
+    for (let argument of args) {
+        if (argument === "--allow-config") {
+            allowConfig = true;
+            continue;
+        }
+        if (argument.startsWith("--allow-config=")) {
+            return failure(new SpecError("usage-error", "--allow-config takes no value; it is a bare flag that applies the permissions spec/config.jsonc declares."));
+        }
+        remaining.push(argument);
+    }
+    return success({ allowConfig, remaining });
+}
+/**
+ * Peel `--concurrency=N` (or its `--jobs=N` alias) out of an argument list; N
+ * sets how many tests run at once and defaults to 1. A missing, malformed, or
+ * non-positive value is a usage error; a repeated flag keeps the last value.
+ *
+ * @param args - The raw CLI arguments after the config opt-in was removed.
+ * @returns The chosen concurrency and the remaining arguments.
+ */
+function parseConcurrency(args) {
+    let concurrency = 1;
+    let remaining = [];
+    for (let argument of args) {
+        let flag = matchConcurrencyFlag(argument);
+        if (flag === undefined) {
+            remaining.push(argument);
+            continue;
+        }
+        let value = parsePositiveInteger(flag.value);
+        if (value === undefined) {
+            return failure(new SpecError("usage-error", `${flag.name} expects a positive integer, e.g. ${flag.name}=8; got ${JSON.stringify(flag.value)}.`));
+        }
+        concurrency = value;
+    }
+    return success({ concurrency, remaining });
+}
+/**
+ * Peel `--seed=VALUE` out of an argument list. `--seed=random` draws one, which
+ * the caller prints so a run that turned up a bad value can be replayed;
+ * anything else is taken as written, since text and numbers both name a stream.
+ * Omitting the flag keeps the runner's fixed default, so a bare run repeats.
+ *
+ * @param argv - Arguments after the earlier flags were peeled off.
+ * @returns The seed, whether it was drawn, and the remaining arguments.
+ */
+function parseSeed(argv) {
+    let remaining = [];
+    let seed = DEFAULT_SEED;
+    let drawn = false;
+    for (let argument of argv) {
+        if (argument !== "--seed" && !argument.startsWith("--seed=")) {
+            remaining.push(argument);
+            continue;
+        }
+        let value = argument === "--seed" ? "" : argument.slice("--seed=".length);
+        if (value === "") {
+            return failure(new SpecError("usage-error", "--seed expects a value, e.g. --seed=checkout or --seed=random to draw one."));
+        }
+        if (value === "random") {
+            seed = systemSeed();
+            drawn = true;
+            continue;
+        }
+        seed = /^\d+$/.test(value) ? Number(value) : value;
+        drawn = false;
+    }
+    return success({ seed, drawn, remaining });
+}
+/**
+ * Match a concurrency flag and split off its value, recognizing both
+ * `--concurrency` and `--jobs` in `--flag=value` form. The bare `--flag` form
+ * matches with an empty value so the caller reports the missing-value usage error.
+ *
+ * @param argument - One raw CLI argument.
+ * @returns The matched flag name and its value, or undefined for a non-match.
+ */
+function matchConcurrencyFlag(argument) {
+    for (let name of ["--concurrency", "--jobs"]) {
+        if (argument === name)
+            return { name, value: "" };
+        if (argument.startsWith(`${name}=`))
+            return { name, value: argument.slice(name.length + 1) };
+    }
+    return undefined;
+}
+/**
+ * Parse a strictly positive integer written in decimal, rejecting everything
+ * else — empty strings, signs, decimals, whitespace, and non-numeric text — so
+ * the caller can turn a bad `--concurrency` value into a usage error.
+ *
+ * @param text - The flag's raw value.
+ * @returns The integer, or undefined when the text is not a positive integer.
+ */
+function parsePositiveInteger(text) {
+    if (!/^\d+$/.test(text))
+        return undefined;
+    let value = Number(text);
+    if (!Number.isInteger(value) || value < 1)
+        return undefined;
+    return value;
+}
+if (import.meta.main) {
+    let sink = { write: (text) => void process.stdout.write(text) };
+    let code = await main(process.argv.slice(2), sink);
+    process.exit(code);
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Result shapes the runner produces and the reporter renders: per-test
+ * outcomes and the suite roll-up. Failures travel as structured `SpecError`s
+ * (spans, expected/observed, remedies), never as pre-rendered strings.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SpecError } from "./errors.js";
+/** How one test ended. */
+export type TestStatus = "passed" | "failed";
+/** The outcome of executing one test. */
+export interface TestResult {
+    /** The test's title as written in the spec. */
+    title: string;
+    /** Path of the file the test lives in. */
+    file: string;
+    /** Whether every statement held. */
+    status: TestStatus;
+    /** The failure that ended the test, when it failed. */
+    error?: SpecError;
+    /** Wall-clock duration of the test in milliseconds. */
+    durationMs: number;
+}
+/** The outcome of one `spec run`. */
+export interface SuiteResult {
+    /** Per-test outcomes in execution order. */
+    results: TestResult[];
+    /** Count of passed tests. */
+    passed: number;
+    /** Count of failed tests. */
+    failed: number;
+    /**
+     * Wall-clock duration of the whole run in milliseconds, from just before
+     * the first test starts to just after the last one finishes. Tracks real
+     * elapsed time at any concurrency, since concurrent {@link TestResult.durationMs} values overlap.
+     */
+    wallMs: number;
+}
+/**
+ * Where the reporter writes. The CLI passes stdout/stderr; tests pass a
+ * buffer. Product output goes through this sink, never through a logger.
+ */
+export interface Sink {
+    /** Append text verbatim; the reporter controls its own newlines. */
+    write(text: string): void;
+}

package/dist/diagnostics.js

@@ -0,0 +1,8 @@
+/**
+ * Result shapes the runner produces and the reporter renders: per-test
+ * outcomes and the suite roll-up. Failures travel as structured `SpecError`s
+ * (spans, expected/observed, remedies), never as pre-rendered strings.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */