@executablemd/testing 0.3.1

package/types/deps/jsr.io/@std/assert/1.0.19/unimplemented.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Use this to stub out methods that will throw when invoked.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { unimplemented } from "@std/assert";
+ *
+ * unimplemented(); // Throws
+ * ```
+ *
+ * @param msg Optional message to include in the error.
+ * @returns Never returns, always throws.
+ */
+export declare function unimplemented(msg?: string): never;

package/types/deps/jsr.io/@std/assert/1.0.19/unreachable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Use this to assert unreachable code.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { unreachable } from "@std/assert";
+ *
+ * unreachable(); // Throws
+ * ```
+ *
+ * @param msg Optional message to include in the error.
+ * @returns Never returns, always throws.
+ */
+export declare function unreachable(msg?: string): never;

package/types/deps/jsr.io/@std/internal/1.0.14/build_message.d.ts

@@ -0,0 +1,79 @@
+import type { DiffResult, DiffType } from "./types.js";
+/**
+ * Colors the output of assertion diffs.
+ *
+ * @param diffType Difference type, either added or removed.
+ * @param background If true, colors the background instead of the text.
+ *
+ * @returns A function that colors the input string.
+ *
+ * @example Usage
+ * ```ts
+ * import { createColor } from "@std/internal";
+ * import { assertEquals } from "@std/assert";
+ * import { bold, green, red, white } from "@std/fmt/colors";
+ *
+ * assertEquals(createColor("added")("foo"), green(bold("foo")));
+ * assertEquals(createColor("removed")("foo"), red(bold("foo")));
+ * assertEquals(createColor("common")("foo"), white("foo"));
+ * ```
+ */
+export declare function createColor(diffType: DiffType, 
+/**
+ * TODO(@littledivy): Remove this when we can detect true color terminals. See
+ * https://github.com/denoland/std/issues/2575.
+ */
+background?: boolean): (s: string) => string;
+/**
+ * Prefixes `+` or `-` in diff output.
+ *
+ * @param diffType Difference type, either added or removed
+ *
+ * @returns A string representing the sign.
+ *
+ * @example Usage
+ * ```ts
+ * import { createSign } from "@std/internal";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(createSign("added"), "+   ");
+ * assertEquals(createSign("removed"), "-   ");
+ * assertEquals(createSign("common"), "    ");
+ * ```
+ */
+export declare function createSign(diffType: DiffType): string;
+/** Options for {@linkcode buildMessage}. */
+export interface BuildMessageOptions {
+    /**
+     * Whether to output the diff as a single string.
+     * @default {false}
+     */
+    stringDiff?: boolean;
+}
+/**
+ * Builds a message based on the provided diff result.
+ *
+ * @param diffResult The diff result array.
+ * @param options Optional parameters for customizing the message.
+ * @param truncateDiff Function to truncate the diff (default is no truncation).
+ *
+ * @returns An array of strings representing the built message.
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { diffStr, buildMessage } from "@std/internal";
+ *
+ * diffStr("Hello, world!", "Hello, world");
+ * // [
+ * //   "",
+ * //   "",
+ * //   "    [Diff] Actual / Expected",
+ * //   "",
+ * //   "",
+ * //   "-   Hello, world!",
+ * //   "+   Hello, world",
+ * //   "",
+ * // ]
+ * ```
+ */
+export declare function buildMessage(diffResult: ReadonlyArray<DiffResult<string>>, options?: BuildMessageOptions, truncateDiff?: (diffResult: ReadonlyArray<DiffResult<string>>, stringDiff: boolean, contextLength?: number | null) => ReadonlyArray<DiffResult<string>>): string[];

package/types/deps/jsr.io/@std/internal/1.0.14/diff.d.ts

@@ -0,0 +1,139 @@
+import type { DiffResult, DiffType } from "./types.js";
+/** Represents the farthest point in the diff algorithm. */
+export interface FarthestPoint {
+    /** The y-coordinate of the point. */
+    y: number;
+    /** The id of the point. */
+    id: number;
+}
+/**
+ * Creates an array of common elements between two arrays.
+ *
+ * @typeParam T The type of elements in the arrays.
+ *
+ * @param A The first array.
+ * @param B The second array.
+ *
+ * @returns An array containing the common elements between the two arrays.
+ *
+ * @example Usage
+ * ```ts
+ * import { createCommon } from "@std/internal/diff";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = [1, 2, 3];
+ * const b = [1, 2, 4];
+ *
+ * assertEquals(createCommon(a, b), [1, 2]);
+ * ```
+ */
+export declare function createCommon<T>(A: T[], B: T[]): T[];
+/**
+ * Asserts that the value is a {@linkcode FarthestPoint}.
+ * If not, an error is thrown.
+ *
+ * @param value The value to check.
+ *
+ * @returns A void value that returns once the assertion completes.
+ *
+ * @example Usage
+ * ```ts
+ * import { assertFp } from "@std/internal/diff";
+ * import { assertThrows } from "@std/assert";
+ *
+ * assertFp({ y: 0, id: 0 });
+ * assertThrows(() => assertFp({ id: 0 }));
+ * assertThrows(() => assertFp({ y: 0 }));
+ * assertThrows(() => assertFp(undefined));
+ * ```
+ */
+export declare function assertFp(value: unknown): asserts value is FarthestPoint;
+/**
+ * Creates an array of backtraced differences.
+ *
+ * @typeParam T The type of elements in the arrays.
+ *
+ * @param A The first array.
+ * @param B The second array.
+ * @param current The current {@linkcode FarthestPoint}.
+ * @param swapped Boolean indicating if the arrays are swapped.
+ * @param routes The routes array.
+ * @param diffTypesPtrOffset The offset of the diff types in the routes array.
+ *
+ * @returns An array of backtraced differences.
+ *
+ * @example Usage
+ * ```ts
+ * import { backTrace } from "@std/internal/diff";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(
+ *   backTrace([], [], { y: 0, id: 0 }, false, new Uint32Array(0), 0),
+ *   [],
+ * );
+ * ```
+ */
+export declare function backTrace<T>(A: T[], B: T[], current: FarthestPoint, swapped: boolean, routes: Uint32Array, diffTypesPtrOffset: number): Array<{
+    type: DiffType;
+    value: T;
+}>;
+/**
+ * Creates a {@linkcode FarthestPoint}.
+ *
+ * @param k The current index.
+ * @param M The length of the first array.
+ * @param routes The routes array.
+ * @param diffTypesPtrOffset The offset of the diff types in the routes array.
+ * @param ptr The current pointer.
+ * @param slide The slide {@linkcode FarthestPoint}.
+ * @param down The down {@linkcode FarthestPoint}.
+ *
+ * @returns A {@linkcode FarthestPoint}.
+ *
+ * @example Usage
+ * ```ts
+ * import { createFp } from "@std/internal/diff";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(
+ *   createFp(
+ *     0,
+ *     0,
+ *     new Uint32Array(0),
+ *     0,
+ *     0,
+ *     { y: -1, id: 0 },
+ *     { y: 0, id: 0 },
+ *   ),
+ *   { y: -1, id: 1 },
+ * );
+ * ```
+ */
+export declare function createFp(k: number, M: number, routes: Uint32Array, diffTypesPtrOffset: number, ptr: number, slide?: FarthestPoint, down?: FarthestPoint): FarthestPoint;
+/**
+ * Renders the differences between the actual and expected values.
+ *
+ * @typeParam T The type of elements in the arrays.
+ *
+ * @param A Actual value
+ * @param B Expected value
+ *
+ * @returns An array of differences between the actual and expected values.
+ *
+ * @example Usage
+ * ```ts
+ * import { diff } from "@std/internal/diff";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const a = [1, 2, 3];
+ * const b = [1, 2, 4];
+ *
+ * assertEquals(diff(a, b), [
+ *   { type: "common", value: 1 },
+ *   { type: "common", value: 2 },
+ *   { type: "removed", value: 3 },
+ *   { type: "added", value: 4 },
+ * ]);
+ * ```
+ */
+export declare function diff<T>(A: T[], B: T[]): DiffResult<T>[];

package/types/deps/jsr.io/@std/internal/1.0.14/diff_str.d.ts

@@ -0,0 +1,98 @@
+import type { DiffResult } from "./types.js";
+/**
+ * Unescape invisible characters.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#escape_sequences}
+ *
+ * @param string String to unescape.
+ *
+ * @returns Unescaped string.
+ *
+ * @example Usage
+ * ```ts
+ * import { unescape } from "@std/internal/diff-str";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(unescape("Hello\nWorld"), "Hello\\n\nWorld");
+ * ```
+ */
+export declare function unescape(string: string): string;
+/**
+ * Tokenizes a string into an array of tokens.
+ *
+ * @param string The string to tokenize.
+ * @param wordDiff If true, performs word-based tokenization. Default is false.
+ *
+ * @returns An array of tokens.
+ *
+ * @example Usage
+ * ```ts
+ * import { tokenize } from "@std/internal/diff-str";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(tokenize("Hello\nWorld"), ["Hello\n", "World"]);
+ * ```
+ */
+export declare function tokenize(string: string, wordDiff?: boolean): string[];
+/**
+ * Create details by filtering relevant word-diff for current line and merge
+ * "space-diff" if surrounded by word-diff for cleaner displays.
+ *
+ * @param line Current line
+ * @param tokens Word-diff tokens
+ *
+ * @returns Array of diff results.
+ *
+ * @example Usage
+ * ```ts
+ * import { createDetails } from "@std/internal/diff-str";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const tokens = [
+ *   { type: "added", value: "a" },
+ *   { type: "removed", value: "b" },
+ *   { type: "common", value: "c" },
+ * ] as const;
+ * assertEquals(
+ *   createDetails({ type: "added", value: "a" }, [...tokens]),
+ *   [{ type: "added", value: "a" }, { type: "common", value: "c" }]
+ * );
+ * ```
+ */
+export declare function createDetails(line: DiffResult<string>, tokens: DiffResult<string>[]): DiffResult<string>[];
+/**
+ * Renders the differences between the actual and expected strings. Partially
+ * inspired from {@link https://github.com/kpdecker/jsdiff}.
+ *
+ * @param A Actual string
+ * @param B Expected string
+ *
+ * @returns Array of diff results.
+ *
+ * @example Usage
+ * ```ts
+ * import { diffStr } from "@std/internal/diff-str";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(diffStr("Hello!", "Hello"), [
+ *   {
+ *     type: "removed",
+ *     value: "Hello!\n",
+ *     details: [
+ *       { type: "common", value: "Hello" },
+ *       { type: "removed", value: "!" },
+ *       { type: "common", value: "\n" }
+ *     ]
+ *   },
+ *   {
+ *     type: "added",
+ *     value: "Hello\n",
+ *     details: [
+ *       { type: "common", value: "Hello" },
+ *       { type: "common", value: "\n" }
+ *     ]
+ *   }
+ * ]);
+ * ```
+ */
+export declare function diffStr(A: string, B: string): DiffResult<string>[];

package/types/deps/jsr.io/@std/internal/1.0.14/format.d.ts

@@ -0,0 +1,28 @@
+export type InspectFn = (v: unknown, options: {
+    depth: number;
+    sorted: boolean;
+    trailingComma: boolean;
+    compact: boolean;
+    iterableLimit: number;
+    getters: boolean;
+    strAbbreviateSize: number;
+}) => string;
+/**
+ * Converts the input into a string. Objects, Sets and Maps are sorted so as to
+ * make tests less flaky.
+ *
+ * @param v Value to be formatted
+ *
+ * @returns The formatted string
+ *
+ * @example Usage
+ * ```ts
+ * import { format } from "@std/internal/format";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(format({ a: 1, b: 2 }), "{\n  a: 1,\n  b: 2,\n}");
+ * assertEquals(format(new Set([1, 2])), "Set(2) {\n  1,\n  2,\n}");
+ * assertEquals(format(new Map([[1, 2]])), "Map(1) {\n  1 => 2,\n}");
+ * ```
+ */
+export declare function format(v: unknown): string;

package/types/deps/jsr.io/@std/internal/1.0.14/styles.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Sets the style of text to be printed to bold.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make bold
+ *
+ * @returns Bold text for printing
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { bold } from "@std/internal/styles";
+ *
+ * console.log(bold("Hello, world!")); // Prints "Hello, world!" in bold
+ * ```
+ */
+export declare function bold(str: string): string;
+/**
+ * Sets the color of text to be printed to red.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make red
+ *
+ * @returns Red text for printing
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { red } from "@std/internal/styles";
+ *
+ * console.log(red("Hello, world!")); // Prints "Hello, world!" in red
+ * ```
+ */
+export declare function red(str: string): string;
+/**
+ * Sets the color of text to be printed to green.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make green
+ *
+ * @returns Green text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { green } from "@std/internal/styles";
+ *
+ * console.log(green("Hello, world!")); // Prints "Hello, world!" in green
+ * ```
+ */
+export declare function green(str: string): string;
+/**
+ * Sets the color of text to be printed to yellow.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make yellow
+ *
+ * @returns Yellow text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { yellow } from "@std/internal/styles";
+ *
+ * console.log(yellow("Hello, world!")); // Prints "Hello, world!" in yellow
+ * ```
+ */
+export declare function yellow(str: string): string;
+/**
+ * Sets the color of text to be printed to white.
+ *
+ * @param str Text to make white
+ *
+ * @returns White text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { white } from "@std/internal/styles";
+ *
+ * console.log(white("Hello, world!")); // Prints "Hello, world!" in white
+ * ```
+ */
+export declare function white(str: string): string;
+/**
+ * Sets the color of text to be printed to gray.
+ *
+ * @param str Text to make gray
+ *
+ * @returns Gray text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { gray } from "@std/internal/styles";
+ *
+ * console.log(gray("Hello, world!")); // Prints "Hello, world!" in gray
+ * ```
+ */
+export declare function gray(str: string): string;
+/**
+ * Sets the color of text to be printed to bright-black.
+ *
+ * @param str Text to make bright-black
+ *
+ * @returns Bright-black text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { brightBlack } from "@std/internal/styles";
+ *
+ * console.log(brightBlack("Hello, world!")); // Prints "Hello, world!" in bright-black
+ * ```
+ */
+export declare function brightBlack(str: string): string;
+/**
+ * Sets the background color of text to be printed to red.
+ *
+ * @param str Text to make its background red
+ *
+ * @returns Red background text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { bgRed } from "@std/internal/styles";
+ *
+ * console.log(bgRed("Hello, world!")); // Prints "Hello, world!" with red background
+ * ```
+ */
+export declare function bgRed(str: string): string;
+/**
+ * Sets the background color of text to be printed to green.
+ *
+ * @param str Text to make its background green
+ *
+ * @returns Green background text for print
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { bgGreen } from "@std/internal/styles";
+ *
+ * console.log(bgGreen("Hello, world!")); // Prints "Hello, world!" with green background
+ * ```
+ */
+export declare function bgGreen(str: string): string;
+/**
+ * Remove ANSI escape codes from the string.
+ *
+ * @param string Text to remove ANSI escape codes from
+ *
+ * @returns Text without ANSI escape codes
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { red, stripAnsiCode } from "@std/internal/styles";
+ *
+ * console.log(stripAnsiCode(red("Hello, world!"))); // Prints "Hello, world!"
+ * ```
+ */
+export declare function stripAnsiCode(string: string): string;

package/types/deps/jsr.io/@std/internal/1.0.14/types.d.ts

@@ -0,0 +1,24 @@
+/** Ways that lines in a diff can be different. */
+export type DiffType = DiffResult<unknown>["type"];
+/**
+ * Represents the result of a diff operation.
+ * @typeParam T The type of the value in the diff result.
+ */
+export type DiffResult<T> = ChangedDiffResult<T> | CommonDiffResult<T>;
+/**
+ * Represents the result of a common diff operation.
+ * @typeParam T The type of the value in the diff result.
+ */
+export type CommonDiffResult<T> = {
+    type: "common" | "truncation";
+    value: T;
+};
+/**
+ * Represents the result of a changed diff operation.
+ * @typeParam T The type of the value in the diff result.
+ */
+export type ChangedDiffResult<T> = {
+    type: "removed" | "added";
+    value: T;
+    details?: DiffResult<T>[];
+};

package/types/mod.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module
+ * Testing vocabulary for executable.md documents (specs/testing-spec.md).
+ *
+ * `<Testing>` activates testing mode for its expanded subtree, `<Test>`
+ * defines an atomic test, and the assertion components map to `@std/assert`.
+ *
+ * Composition with core execution:
+ *
+ * ```ts
+ * import { execute } from "@executablemd/core";
+ * import { useTesting } from "@executablemd/testing";
+ *
+ * const tests = yield* useTesting();
+ * const execution = yield* execute(options);
+ * const outcome = yield* execution;          // Result<string>
+ * const results = yield* tests.results;
+ * ```
+ *
+ * Vocabulary registration (`installTestingVocabulary`) is distinct from
+ * testing-mode activation (`useTesting()` at the root, or a `<Testing>`
+ * element for a subtree).
+ */
+import "./_dnt.polyfills.js";
+export { Test, testing, record, results, TestFailureError } from "./src/test-api.js";
+export type { TestApi, TestResult, BoundaryOutcome } from "./src/test-api.js";
+export { installTestingVocabulary } from "./src/vocabulary.js";
+export { useTesting } from "./src/use-testing.js";
+export type { Testing } from "./src/use-testing.js";

package/types/src/assertions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Assertion components (specs/testing-spec.md §Assertions).
+ *
+ * Each component maps to an `@std/assert` export with the same name and
+ * parameter names. Expression props evaluate LIVE against the merged binding
+ * environment — never through JSON serialization, which would destroy
+ * `RegExp`s, `undefined`, and object identity.
+ *
+ * The assertion runs on the raw values BEFORE any diagnostic formatting, so
+ * formatting arbitrary values (mutating or throwing getters/toJSON/toString)
+ * can never change the assertion outcome. Diagnostics are built afterwards
+ * under guarded fallback.
+ */
+import { AssertionError } from "../deps/jsr.io/@std/assert/1.0.19/mod.js";
+import type { Operation } from "effection";
+import type { ComponentInvocation, InvocationContext, Segment } from "@executablemd/core";
+type AssertionKind = "unary-truthy" | "unary-exists" | "binary-eq" | "string-includes" | "match" | "numeric";
+export interface AssertionEntry {
+    name: string;
+    kind: AssertionKind;
+    /** Runs the underlying @std/assert function on the resolved raw values. */
+    run(values: ResolvedValues): void;
+    allowsExpectedChildren: boolean;
+}
+interface ResolvedValues {
+    expr?: unknown;
+    actual?: unknown;
+    expected?: unknown;
+    msg?: string;
+}
+export declare const ASSERTIONS: Map<string, AssertionEntry>;
+/**
+ * An assertion failure enriched with its Markdown diagnostic. Still an
+ * `AssertionError`, so containment and classification treat it as the
+ * original @std/assert failure.
+ */
+export declare class AssertionDiagnostic extends AssertionError {
+    name: string;
+    diagnostic: string;
+    detail: {
+        actual?: string;
+        expected?: string;
+    };
+    constructor(cause: Error, diagnostic: string, detail: {
+        actual?: string;
+        expected?: string;
+    });
+}
+/**
+ * Expand one assertion component: validate props, resolve raw values, run the
+ * @std/assert function, then build the diagnostic. Returns diagnostic text on
+ * a visible pass; throws `AssertionDiagnostic` on failure.
+ */
+export declare function expandAssertion(assertion: AssertionEntry, invocation: ComponentInvocation, ctx: InvocationContext): Operation<Segment[]>;
+export {};

package/types/src/handlers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `<Testing>` and `<Test>` handlers (specs/testing-spec.md).
+ *
+ * `createTestHandlers` is the internal dependency-injection seam for the
+ * fixed 20-second test timeout: the public vocabulary always constructs
+ * handlers with 20_000; tests construct them directly with a small timeout.
+ */
+import type { Operation } from "effection";
+import type { ComponentInvocation, InvocationContext, Segment } from "@executablemd/core";
+import type { AssertionEntry } from "./assertions.js";
+export interface TestHandlers {
+    expandTesting(invocation: ComponentInvocation, ctx: InvocationContext): Operation<Segment[]>;
+    expandTest(invocation: ComponentInvocation, ctx: InvocationContext): Operation<Segment[]>;
+    expandAssertion(assertion: AssertionEntry, invocation: ComponentInvocation, ctx: InvocationContext): Operation<Segment[]>;
+}
+export declare function createTestHandlers(options: {
+    timeoutMs: number;
+}): TestHandlers;

package/types/src/journal.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Durable testing records (specs/testing-spec.md §Testing Mode).
+ *
+ * Completed tests and explicit `<Testing>` boundary outcomes are journaled
+ * as testing-owned durable operations while document expansion runs —
+ * before the root Close event. On a full replay of a completed journal,
+ * `durableRun` returns the stored root result without re-expanding the
+ * document, so no test would ever re-record; the stored records are
+ * restored from the stream instead. On partial replay the document
+ * re-expands and each record replays in place, recording exactly once in
+ * discovery order.
+ *
+ * Record identities are deterministic, derived from source position.
+ */
+import type { DurableStream, Workflow } from "@executablemd/durable-streams";
+import type { Operation } from "effection";
+import type { BoundaryOutcome, TestResult } from "./test-api.js";
+export declare function persistTestResult(result: TestResult): Workflow<TestResult>;
+export declare function persistBoundaryOutcome(outcome: BoundaryOutcome, location: string): Workflow<BoundaryOutcome>;
+export interface CompletedRunRecords {
+    results: TestResult[];
+    boundaries: BoundaryOutcome[];
+}
+/**
+ * Read testing records from a journal that already holds a root Close
+ * event — the confirmed-full-replay case. Returns undefined for a live or
+ * partial journal, where expansion itself (re)records each result.
+ */
+export declare function readCompletedRun(stream: DurableStream): Operation<CompletedRunRecords | undefined>;