@sdxc/spec 0.0.0-pre.1

package/dist/runner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The host convenience over `runTests`: load a `spec/` directory from disk, give
+ * every test a fresh temp-directory workspace, and register the built-in
+ * capabilities. This is what the CLI runs, and the answers it supplies — a
+ * filesystem to read the suite from, a filesystem to run tests in, and all eight
+ * built-ins — are exactly the ones a runtime without a process cannot give. An
+ * embedder there calls `runTests` with its own answers instead.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Seed } from "@sdxc/sample";
+import type { BuiltinNamespace } from "./builtins.js";
+import type { SuiteResult } from "./diagnostics.js";
+import type { SpecError } from "./errors.js";
+import type { Grants } from "./permissions.js";
+import type { Plugin } from "./plugin.js";
+/** What a `spec run` needs: the suite directory and the caller's grants. */
+export interface RunOptions {
+    /** Directory scanned recursively for `.spec` files. */
+    root: string;
+    /** The caller's permission grants, parsed from `--allow-*` flags. */
+    grants: Grants;
+    /** Extra plugins beyond the built-ins this run registers. */
+    plugins?: Plugin[];
+    /**
+     * Which built-in namespaces to register; omit for all of them, as the CLI
+     * does. Excluding a namespace here makes it unresolvable, so a spec
+     * naming it fails as an unknown name (see `createBuiltinPlugins`).
+     */
+    builtins?: readonly BuiltinNamespace[];
+    /**
+     * How many tests may execute at once. `1` (the default) runs the suite
+     * strictly sequentially in source order; see `RunTestsOptions.concurrency`.
+     */
+    concurrency?: number;
+    /**
+     * The run's seed, which every test's generated data descends from; omit for
+     * the fixed default that makes two runs produce identical data.
+     */
+    seed?: Seed;
+}
+/**
+ * Load and execute a suite from disk. Load failures (unreadable directory,
+ * parse errors, duplicate definitions) fail the whole run before any test
+ * starts, while test failures surface as outcomes inside the returned result.
+ *
+ * @param options - Suite directory, grants, and optional plugin and concurrency choices.
+ * @returns Per-test outcomes, or the error that prevented the run entirely.
+ */
+export declare function runSuite(options: RunOptions): Promise<Result<SuiteResult, SpecError>>;

package/dist/runner.js

@@ -0,0 +1,38 @@
+/**
+ * The host convenience over `runTests`: load a `spec/` directory from disk, give
+ * every test a fresh temp-directory workspace, and register the built-in
+ * capabilities. This is what the CLI runs, and the answers it supplies — a
+ * filesystem to read the suite from, a filesystem to run tests in, and all eight
+ * built-ins — are exactly the ones a runtime without a process cannot give. An
+ * embedder there calls `runTests` with its own answers instead.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { createBuiltinPlugins } from "./builtins.js";
+import { loadSuite } from "./loader.js";
+import { runTests } from "./run.js";
+import { createWorkspace } from "./workspace.js";
+/**
+ * Load and execute a suite from disk. Load failures (unreadable directory,
+ * parse errors, duplicate definitions) fail the whole run before any test
+ * starts, while test failures surface as outcomes inside the returned result.
+ *
+ * @param options - Suite directory, grants, and optional plugin and concurrency choices.
+ * @returns Per-test outcomes, or the error that prevented the run entirely.
+ */
+export async function runSuite(options) {
+    let loaded = await loadSuite(options.root);
+    if (isFailure(loaded))
+        return loaded;
+    return runTests({
+        suite: loaded.data,
+        plugins: [...createBuiltinPlugins(options.builtins), ...(options.plugins ?? [])],
+        grants: options.grants,
+        createWorkspace,
+        concurrency: options.concurrency,
+        seed: options.seed,
+        root: options.root,
+    });
+}

package/dist/source.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Source-text bookkeeping for `.spec` files: file wrappers, spans, and
+ * positions. The lexer, parser, and diagnostics all share these shapes so
+ * every failure can point at the exact statement that produced it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** A caret location inside a source file, 1-indexed the way editors display. */
+export interface Position {
+    /** 1-indexed line number. */
+    line: number;
+    /** 1-indexed column, counted in UTF-16 code units. */
+    column: number;
+}
+/** A half-open range of source text (`start` inclusive, `end` exclusive). */
+export interface Span {
+    /** Offset of the first character, 0-indexed into the file text. */
+    start: number;
+    /** Offset one past the last character. */
+    end: number;
+}
+/** A `.spec` file's full text plus the path diagnostics report it under. */
+export interface SourceFile {
+    /** Path as handed to the loader; relative paths stay relative. */
+    path: string;
+    text: string;
+}
+/**
+ * Translate a text offset into a line/column position, for rendering
+ * diagnostics. Offsets past the end of the file clamp to the last position.
+ *
+ * @param source - The file the offset points into.
+ * @param offset - 0-indexed character offset, e.g. a `Span`'s `start`.
+ * @returns The 1-indexed line and column of that offset.
+ */
+export declare function positionAt(source: SourceFile, offset: number): Position;

package/dist/source.js

@@ -0,0 +1,31 @@
+/**
+ * Source-text bookkeeping for `.spec` files: file wrappers, spans, and
+ * positions. The lexer, parser, and diagnostics all share these shapes so
+ * every failure can point at the exact statement that produced it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Translate a text offset into a line/column position, for rendering
+ * diagnostics. Offsets past the end of the file clamp to the last position.
+ *
+ * @param source - The file the offset points into.
+ * @param offset - 0-indexed character offset, e.g. a `Span`'s `start`.
+ * @returns The 1-indexed line and column of that offset.
+ */
+export function positionAt(source, offset) {
+    let line = 1;
+    let column = 1;
+    let end = Math.min(offset, source.text.length);
+    for (let index = 0; index < end; index++) {
+        if (source.text[index] === "\n") {
+            line += 1;
+            column = 1;
+        }
+        else {
+            column += 1;
+        }
+    }
+    return { line, column };
+}

package/dist/sources.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Suite loading from sources already in memory: parse each one, then register
+ * suite-global definitions in a second pass — so name resolution never depends
+ * on source order and duplicates surface before any test runs.
+ *
+ * This is the whole of loading that does not involve a filesystem, which is why
+ * it lives apart from `loader.ts`: a host that already holds its spec text
+ * (from a database row, an HTTP body, a bundled string) needs this and not the
+ * directory walk, and a runtime with no filesystem can reach nothing else.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { CommandNode, FixtureNode, SpecFileNode } from "./ast.js";
+import type { SpecError } from "./errors.js";
+/** One `.spec` file's text, plus the path errors from it are attributed to. */
+export interface SpecSource {
+    /**
+     * How this source is named in diagnostics. Never opened, so it need not exist
+     * on any disk — but it is what a failure reports and what `positionAt` is
+     * given, so prefer something a reader can locate.
+     */
+    path: string;
+    /** The source text, verbatim. */
+    text: string;
+}
+/** A fully loaded suite: every parsed file plus its global definition maps. */
+export interface LoadedSuite {
+    /** Every parsed `.spec` file, in the order its sources were given. */
+    files: SpecFileNode[];
+    /** Suite-global commands by name, registered across every file. */
+    commands: Map<string, CommandNode>;
+    /** Suite-global fixtures by name, registered across every file. */
+    fixtures: Map<string, FixtureNode>;
+}
+/**
+ * Load a suite from sources: parse each one, then register every definition
+ * suite-globally, failing on the first parse error or on any duplicate name
+ * across files. Sources are parsed and reported in the caller's order.
+ *
+ * @param sources - Every `.spec` source in the suite, in the intended order.
+ * @returns The loaded suite, or the load/parse error that prevented it.
+ */
+export declare function loadSources(sources: readonly SpecSource[]): Result<LoadedSuite, SpecError>;

package/dist/sources.js

@@ -0,0 +1,54 @@
+/**
+ * Suite loading from sources already in memory: parse each one, then register
+ * suite-global definitions in a second pass — so name resolution never depends
+ * on source order and duplicates surface before any test runs.
+ *
+ * This is the whole of loading that does not involve a filesystem, which is why
+ * it lives apart from `loader.ts`: a host that already holds its spec text
+ * (from a database row, an HTTP body, a bundled string) needs this and not the
+ * directory walk, and a runtime with no filesystem can reach nothing else.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { LoadError, ParseError } from "./errors.js";
+import { parse } from "./parser.js";
+/**
+ * Load a suite from sources: parse each one, then register every definition
+ * suite-globally, failing on the first parse error or on any duplicate name
+ * across files. Sources are parsed and reported in the caller's order.
+ *
+ * @param sources - Every `.spec` source in the suite, in the intended order.
+ * @returns The loaded suite, or the load/parse error that prevented it.
+ */
+export function loadSources(sources) {
+    if (sources.length === 0) {
+        return failure(new LoadError("load-error", "No .spec sources were given to load."));
+    }
+    let files = [];
+    for (let source of sources) {
+        let parsed = parse(source);
+        if (isFailure(parsed)) {
+            return failure(new ParseError(`${source.path}: ${parsed.error.message}`, parsed.error.file ?? source.path, parsed.error.span));
+        }
+        files.push(parsed.data);
+    }
+    let commands = new Map();
+    let fixtures = new Map();
+    let origins = new Map();
+    for (let file of files) {
+        for (let definition of file.definitions) {
+            let previous = origins.get(definition.name);
+            if (previous) {
+                return failure(new LoadError("duplicate-definition", `Duplicate definition "${definition.name}": ${previous.kind} in ${previous.file} and ${definition.kind} in ${file.path}.`));
+            }
+            origins.set(definition.name, { kind: definition.kind, file: file.path });
+            if (definition.kind === "command")
+                commands.set(definition.name, definition);
+            else
+                fixtures.set(definition.name, definition);
+        }
+    }
+    return success({ files, commands, fixtures });
+}

package/dist/tokens.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Token vocabulary shared by the lexer and parser. The set is intentionally
+ * tiny: the language has no operators, so tokens are literals, identifiers,
+ * keywords, a handful of punctuation marks, and significant newlines.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Span } from "./source.js";
+/** Reserved words; never valid as identifiers, tool names, or definitions. */
+export declare const KEYWORDS: readonly ["use", "test", "given", "when", "then", "command", "fixture", "let", "return", "expect", "eventually", "within", "true", "false"];
+/** One of the reserved words in {@link KEYWORDS}. */
+export type Keyword = (typeof KEYWORDS)[number];
+/**
+ * Every kind of token the lexer emits. `identifier` covers dotted paths too:
+ * identifiers joined by `.` with no surrounding whitespace lex as a single
+ * token whose text contains the dots (`http.post`, `user.email`).
+ */
+export type TokenKind = "string" | "multiline-string" | "number" | "duration" | "identifier" | "keyword" | "lbrace" | "rbrace" | "lparen" | "rparen" | "comma" | "colon" | "equals" | "newline" | "eof";
+/** A lexed token: kind, raw text, location, and decoded value when relevant. */
+export interface Token {
+    kind: TokenKind;
+    /** The raw source text the token covers. */
+    text: string;
+    /** Where in the file the token sits. */
+    span: Span;
+    /**
+     * Decoded payload: the unescaped/dedented content for strings, the numeric
+     * value for numbers, milliseconds for durations. Absent otherwise.
+     */
+    value?: string | number;
+    /** The specific reserved word, present when `kind` is `"keyword"`. */
+    keyword?: Keyword;
+}

package/dist/tokens.js

@@ -0,0 +1,25 @@
+/**
+ * Token vocabulary shared by the lexer and parser. The set is intentionally
+ * tiny: the language has no operators, so tokens are literals, identifiers,
+ * keywords, a handful of punctuation marks, and significant newlines.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Reserved words; never valid as identifiers, tool names, or definitions. */
+export const KEYWORDS = [
+    "use",
+    "test",
+    "given",
+    "when",
+    "then",
+    "command",
+    "fixture",
+    "let",
+    "return",
+    "expect",
+    "eventually",
+    "within",
+    "true",
+    "false",
+];

package/dist/transport-stdio.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The NDJSON-over-stdio plugin transport: how an external executable becomes
+ * a `Plugin`, one JSON document per line over the child's stdio, with
+ * strictly increasing request ids and in-order replies. The child inherits
+ * no environment beyond PATH.
+ *
+ * `workspaceRoot` crosses the wire so a plugin can resolve its own paths, but
+ * scoped permission enforcement over the wire is still an open design
+ * question — the host's coarse `requires` gate runs before every call.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Plugin } from "./plugin.js";
+import { SpecError } from "./errors.js";
+/**
+ * Spawn an external plugin process and connect it as a `Plugin`: send the
+ * describe handshake (5s timeout), cache the returned descriptors, and hand
+ * back a `call()` that round-trips over the child's stdio.
+ *
+ * @param command - The argv to spawn, e.g. `["bun", "plugins/demo.ts"]`.
+ * @param namespace - The namespace the connected plugin's tools live under.
+ * @returns The connected plugin, or the failure that prevented the handshake.
+ */
+export declare function connectStdioPlugin(command: string[], namespace: string): Promise<Result<Plugin, SpecError>>;
+/**
+ * The plugin-side serve loop: read requests from stdin, dispatch each to the
+ * given plugin, and write matching replies to stdout, in order. A line that
+ * fails to parse carries no id, so parsing simply continues to the next one.
+ *
+ * @param plugin - The local plugin implementation to expose over the wire.
+ */
+export declare function servePlugin(plugin: Plugin): Promise<undefined>;