@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/harness/setup-module.ts

@@ -0,0 +1,118 @@
+import { tmpdir } from "node:os";
+import { dirname, extname, join } from "node:path";
+
+import { Deadline } from "../core/deadline.js";
+import { readTextFile } from "../core/files.js";
+import { setupBytesMax, setupFilesMax } from "../core/limits.js";
+import { withTemporaryDirectory } from "../core/resources.js";
+import { resolveSetupImports } from "./setup-imports.js";
+
+const setupTimeoutMs = 60_000;
+
+/** Load a fresh local setup graph, including imported data and helper modules. */
+export async function loadSetupModule(path: string): Promise<unknown> {
+    using deadline = new Deadline(
+        setupTimeoutMs,
+        () => new Error(`Harness setup '${path}' exceeded its loading deadline.`),
+    );
+    const result = await deadline.wait(
+        Bun.build({
+            entrypoints: [path],
+            target: "bun",
+            format: "esm",
+            packages: "external",
+            sourcemap: "inline",
+            plugins: [locationPlugin()],
+        }),
+    );
+
+    if (!result.success) {
+        throw new AggregateError(result.logs, `Cannot load Harness setup module '${path}'.`);
+    }
+
+    const output = result.outputs[0];
+
+    if (!output) {
+        throw new Error(`No compiled setup module was produced for '${path}'.`);
+    }
+
+    return await withTemporaryDirectory(
+        join(tmpdir(), "innovator-harness-setup-"),
+        async (directory) => {
+            const temporary = join(directory, "setup.mjs");
+            await Bun.write(temporary, output);
+
+            const module: unknown = await deadline.wait(import(temporary));
+
+            return module;
+        },
+    );
+}
+
+function locationPlugin(): Bun.BunPlugin {
+    let files = 0;
+    let bytes = 0;
+
+    return {
+        name: "harness-setup-locations",
+
+        setup(build) {
+            build.onResolve({ filter: /^(?:file:|bun:|node:)/ }, (input) => ({
+                path: input.path,
+                external: true,
+            }));
+            build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (input) => {
+                files += 1;
+
+                if (files > setupFilesMax) {
+                    throw new Error("The Harness setup module graph has too many files.");
+                }
+
+                const source = await readTextFile(input.path);
+                bytes += source.length * 3;
+
+                if (bytes > setupBytesMax) {
+                    throw new Error("The Harness setup module graph exceeds its byte limit.");
+                }
+
+                const compiled = transpilerFor(input.path).transformSync(source);
+                const contents = await resolveSetupImports(compiled, input.path);
+
+                return { contents, loader: "js" };
+            });
+        },
+    };
+}
+
+function transpilerFor(path: string): Bun.Transpiler {
+    return new Bun.Transpiler({
+        loader: sourceLoader(path),
+        target: "bun",
+        define: {
+            "import.meta.dir": JSON.stringify(dirname(path)),
+            "import.meta.dirname": JSON.stringify(dirname(path)),
+            "import.meta.path": JSON.stringify(path),
+            "import.meta.filename": JSON.stringify(path),
+            "import.meta.url": JSON.stringify(Bun.pathToFileURL(path).href),
+            "import.meta.main": "false",
+        },
+    });
+}
+
+function sourceLoader(path: string): "js" | "jsx" | "ts" | "tsx" {
+    const extension = extname(path);
+
+    if (extension === ".tsx") {
+        return "tsx";
+    }
+
+    if (extension === ".jsx") {
+        return "jsx";
+    }
+
+    if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
+        return "ts";
+    }
+
+    return "js";
+}

package/src/harness/world.ts

@@ -0,0 +1,248 @@
+import type { ClockControl } from "../controls/clock.js";
+import type { FailureInjection, InjectedFailureHandle } from "../controls/failure-types.js";
+import type { ExecutionObserver, Observation } from "../controls/observers.js";
+import type { StateReader } from "../controls/state.js";
+import { dataDepthMax, dataNodesMax } from "../core/limits.js";
+import type { Engine } from "../engine.js";
+import type { ExecutionReport } from "../instrumentation/types.js";
+import { Item } from "../items/item.js";
+import type { ItemNode } from "../items/item.js";
+import { PlatformError } from "../platform/errors.js";
+import type { PlatformTraceEvent } from "../platform/trace.js";
+import type { StorageValue, StoredItem } from "../storage/types.js";
+
+export type Properties = Readonly<Record<string, StorageValue>>;
+
+export interface MethodParameters {
+    readonly [name: string]: StorageValue | Item | MethodParameters;
+}
+
+/** An isolated, configured test world. Creation and fixture setup are complete. */
+export class Harness implements Disposable {
+    constructor(private readonly engine: Engine) {}
+
+    get state(): StateReader {
+        return this.engine.state;
+    }
+
+    get clock(): ClockControl {
+        return this.engine.clock;
+    }
+
+    observe(callback: ExecutionObserver): Observation {
+        return this.engine.observe(callback);
+    }
+
+    injectFailure(injection: FailureInjection): InjectedFailureHandle {
+        return this.engine.injectFailure(injection);
+    }
+
+    get trace(): readonly PlatformTraceEvent[] {
+        return this.engine.trace;
+    }
+
+    get executions(): readonly ExecutionReport[] {
+        return this.engine.executions;
+    }
+
+    clearExecutions(): void {
+        this.engine.clearExecutions();
+    }
+
+    async get(type: string, selector: Properties = {}): Promise<readonly StoredItem[]> {
+        const query = Item.create(type, "get");
+        setProperties(query, selector);
+        const result = await this.engine.apply(query);
+
+        if (result.isError() && result.getErrorCode() === "0") {
+            return [];
+        }
+
+        assertSuccess(result);
+
+        return result.payload.items.map(toRecord);
+    }
+
+    async getOne(type: string, selector: Properties): Promise<StoredItem> {
+        const records = await this.get(type, selector);
+        const record = records[0];
+
+        if (records.length !== 1 || !record) {
+            throw new PlatformError(
+                "ItemResolution",
+                `Expected one '${type}' record; found ${records.length}.`,
+            );
+        }
+
+        return record;
+    }
+
+    async add(type: string, properties: Properties): Promise<StoredItem> {
+        const request = Item.create(type, "add");
+        setProperties(request, properties);
+
+        return toRecord(assertSuccess(await this.engine.apply(request)).node);
+    }
+
+    async update(record: StoredItem, changes: Properties): Promise<StoredItem> {
+        const request = Item.create(record.type, "edit");
+        request.setProperty("id", record.id);
+        setProperties(request, changes);
+
+        return toRecord(assertSuccess(await this.engine.apply(request)).node);
+    }
+
+    async delete(record: StoredItem): Promise<void> {
+        const request = Item.create(record.type, "delete");
+        request.setProperty("id", record.id);
+        assertSuccess(await this.engine.apply(request));
+    }
+
+    async callMethod(name: string, parameters: MethodParameters | Item = {}): Promise<Item> {
+        if (parameters instanceof Item) {
+            return await this.engine.callMethod(name, parameters);
+        }
+
+        const context = Item.create("Method", name);
+        setMethodParameters(context, parameters, new Set());
+
+        return await this.engine.callMethod(name, context);
+    }
+
+    applyAML(xml: string): Promise<Item> {
+        return this.engine.applyAML(xml);
+    }
+
+    reset(): void {
+        this.engine.reset();
+    }
+
+    close(): void {
+        this.engine.close();
+    }
+
+    [Symbol.dispose](): void {
+        this.close();
+    }
+}
+
+function setMethodParameters(
+    item: Item,
+    parameters: MethodParameters,
+    ancestors: Set<MethodParameters>,
+): void {
+    interface Frame {
+        readonly item: Item;
+        readonly input: MethodParameters;
+        readonly entries: [string, MethodParameters[string]][];
+        next: number;
+    }
+
+    const pending: Frame[] = [
+        { item, input: parameters, entries: parameterEntries(parameters), next: 0 },
+    ];
+    ancestors.add(parameters);
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.at(-1);
+
+        if (!frame) {
+            throw new Error("A parameter frame must exist while traversal is pending.");
+        }
+
+        const entry = frame.entries[frame.next];
+
+        if (!entry) {
+            ancestors.delete(frame.input);
+            pending.pop();
+            continue;
+        }
+
+        frame.next += 1;
+        visited += 1;
+
+        if (visited > dataNodesMax || pending.length > dataDepthMax) {
+            throw new TypeError("Method parameters exceed their node or nesting limit.");
+        }
+
+        const [name, value] = entry;
+
+        if (value instanceof Item) {
+            frame.item.setPropertyItem(name, value.clone());
+        } else if (value !== null && typeof value === "object") {
+            if (ancestors.has(value)) {
+                throw new TypeError("Method parameters cannot contain circular references.");
+            }
+
+            const nested = Item.create("");
+            frame.item.setPropertyItem(name, nested);
+            ancestors.add(value);
+            pending.push({ item: nested, input: value, entries: parameterEntries(value), next: 0 });
+        } else if (
+            value === null ||
+            typeof value === "string" ||
+            (typeof value === "number" && Number.isFinite(value))
+        ) {
+            frame.item.setProperty(name, value);
+        } else {
+            throw new TypeError(`Invalid Method parameter '${name}'.`);
+        }
+    }
+}
+
+function parameterEntries(parameters: MethodParameters): [string, MethodParameters[string]][] {
+    if (
+        parameters === null ||
+        typeof parameters !== "object" ||
+        Array.isArray(parameters) ||
+        !isPlainObject(parameters)
+    ) {
+        throw new TypeError("Method parameters must contain Item properties.");
+    }
+
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(parameters))) {
+        if (descriptor.get || descriptor.set) {
+            throw new TypeError("Method parameters cannot contain accessors.");
+        }
+    }
+
+    return Object.entries(parameters);
+}
+
+function setProperties(item: Item, properties: Properties): void {
+    for (const [name, value] of Object.entries(properties)) {
+        item.setProperty(name, value);
+    }
+}
+
+function toRecord(node: ItemNode): StoredItem {
+    const id = node.attributes.id;
+
+    if (!id) {
+        throw new PlatformError(
+            "InvalidActionResult",
+            "The action did not return a persisted record ID.",
+        );
+    }
+
+    return {
+        id,
+        type: node.type,
+        properties: { ...node.properties },
+    };
+}
+
+function assertSuccess(result: Item): Item {
+    if (result.isError()) {
+        throw new PlatformError(result.getErrorCode(), result.getErrorString());
+    }
+
+    return result;
+}
+
+function isPlainObject(value: object): boolean {
+    const prototype: unknown = Object.getPrototypeOf(value);
+
+    return prototype === Object.prototype || prototype === null;
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+export { createHarness } from "./harness/create.js";
+export { AuthorizationMode } from "./platform/security/types.js";
+export {
+    checkCompatibility,
+    CapabilityId,
+    CapabilitySupport,
+    CompatibilityIssueCode,
+    IssueSeverity,
+    ExecutorStatus,
+    MockCoverage,
+    CompilationStatus,
+} from "./compatibility/index.js";
+export type {
+    CapabilityDescriptor,
+    CompatibilityOptions,
+    CompatibilityReport,
+    CompatibilityIssue,
+    MethodCompatibility,
+    SqlCompatibility,
+    ExecutorCheck,
+    MockCheck,
+    MockRuleDescription,
+    CompilationCheck,
+    SourceExecutionObservation,
+} from "./compatibility/index.js";
+export {
+    ExecutionOutcome,
+    ExecutionStatus,
+    ExecutionMode,
+    ExecutionKind,
+} from "./instrumentation/types.js";
+export type {
+    ExecutionReport,
+    ExecutionCall,
+    ExecutionChange,
+    ExecutionMock,
+    ExecutionFailure,
+    ExecutionLocation,
+    ExecutionDefinition,
+    ExecutionEvent,
+    ExecutionTruncation,
+    ExecutionValue,
+} from "./instrumentation/types.js";
+export { verifyPackages, PackageIssueCode } from "./verification/index.js";
+export type {
+    PackageVerificationOptions,
+    PackageVerificationReport,
+    PackageVerificationIssue,
+    PackageMethodDeclaration,
+    PackageSqlDeclaration,
+    PackageReference,
+} from "./verification/index.js";
+export type { Mock, MockInput, MockResponse, MethodMock, SqlMock } from "./mocks/types.js";
+export type { Harness } from "./harness/world.js";
+export type { HarnessConfig, HarnessOptions } from "./harness/configuration.js";
+export type { ModuleFactory, ExecutorFactory } from "./harness/extensions.js";
+export type { MethodParameters, Properties } from "./harness/world.js";
+export type { Fixtures, FixtureRecord, FixtureValue } from "./fixtures/types.js";
+export type { StoredItem, StorageValue } from "./storage/types.js";
+export type { PlatformTraceEvent } from "./platform/trace.js";
+export { PlatformError } from "./platform/errors.js";
+
+export { fixedClock } from "./controls/clock.js";
+export type { ClockSettings, ClockControl } from "./controls/clock.js";
+export { seededIds } from "./controls/ids.js";
+export type { IdSettings } from "./controls/ids.js";
+export { FailurePoint, InjectedFailureError } from "./controls/failure-types.js";
+export type {
+    FailureInjection,
+    InjectedFailureHandle,
+    ExecutionInjection,
+} from "./controls/failure-types.js";
+export { ObserverError } from "./controls/observers.js";
+export type { ExecutionObserver, Observation } from "./controls/observers.js";
+export type { StateReader } from "./controls/state.js";
+export { ItemAction } from "./platform/actions.js";
+export { MethodEventDataKind } from "./methods/event-data.js";
+export type {
+    MethodEventData,
+    BeforeUpdateEventData,
+    AfterAddEventData,
+    AfterUpdateEventData,
+    AfterVersionEventData,
+} from "./methods/event-data.js";

package/src/instrumentation/failures.ts

@@ -0,0 +1,148 @@
+import type { CapabilityId } from "../compatibility/capabilities.js";
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import { ApplicationError, PlatformError } from "../platform/errors.js";
+import type { Snapshots } from "./snapshots.js";
+import type { ExecutionFailure, ExecutionLocation } from "./types.js";
+
+const causeDepthMax = 4;
+const causeCountMax = 8;
+
+interface FailureDraft {
+    name: string;
+    message: string;
+    code?: string;
+    capability?: CapabilityId;
+    source?: SourceLocation;
+    callChain: readonly ExecutionLocation[];
+    causes: FailureDraft[];
+}
+
+interface PendingFailure {
+    readonly error: unknown;
+    readonly depth: number;
+    readonly failure: FailureDraft;
+}
+
+/** Preserve the diagnostic tree without recursion or unbounded cause expansion. */
+export function describeFailure(
+    error: unknown,
+    chain: readonly ExecutionLocation[],
+    snapshots: Snapshots,
+    depth = 0,
+): ExecutionFailure {
+    const root = failureDraft(error, chain, snapshots);
+    const pending: PendingFailure[] = [{ error, depth, failure: root }];
+    const failures = [root];
+
+    while (pending.length > 0) {
+        const current = pending.pop();
+
+        if (!current) {
+            throw new Error("A pending failure must exist while the stack is nonempty.");
+        }
+
+        const causes = failureCauses(current.error);
+
+        if (current.depth >= causeDepthMax) {
+            if (causes.length > 0) {
+                snapshots.omitted += 1;
+            }
+
+            continue;
+        }
+
+        snapshots.omitted += Math.max(0, causes.length - causeCountMax);
+
+        for (const cause of causes.slice(0, causeCountMax)) {
+            const failure = failureDraft(cause, chain, snapshots);
+            current.failure.causes.push(failure);
+            failures.push(failure);
+            pending.push({ error: cause, depth: current.depth + 1, failure });
+        }
+    }
+
+    for (const failure of failures.reverse()) {
+        Object.freeze(failure.causes);
+        Object.freeze(failure);
+    }
+
+    return root;
+}
+
+function failureDraft(
+    error: unknown,
+    chain: readonly ExecutionLocation[],
+    snapshots: Snapshots,
+): FailureDraft {
+    let name = "Error";
+    let originalMessage: string;
+
+    if (error instanceof Error) {
+        name = error.name;
+        originalMessage = error.message;
+    } else {
+        originalMessage = String(error);
+    }
+
+    let message = "Error message omitted by snapshot limits.";
+    const captured = snapshots.value(originalMessage);
+
+    if (typeof captured === "string") {
+        message = captured;
+    }
+
+    const failure: FailureDraft = {
+        name,
+        message,
+        callChain: Object.freeze([...chain]),
+        causes: [],
+    };
+
+    if (error instanceof Error && "code" in error && typeof error.code === "string") {
+        failure.code = error.code;
+    } else if (error instanceof ApplicationError) {
+        failure.code = error.item.getErrorCode();
+    }
+
+    let source = failureSource(chain);
+
+    if (error instanceof PlatformError) {
+        if (error.capability !== undefined) {
+            failure.capability = error.capability;
+        }
+
+        if (error.source) {
+            source = error.source;
+        }
+    }
+
+    if (source) {
+        failure.source = Object.freeze({ ...source });
+    }
+
+    return failure;
+}
+
+function failureSource(chain: readonly ExecutionLocation[]): SourceLocation | undefined {
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const source = chain[index]?.source;
+
+        if (source) {
+            return source;
+        }
+    }
+
+    return undefined;
+}
+
+function failureCauses(error: unknown): readonly unknown[] {
+    if (error instanceof AggregateError) {
+        return error.errors;
+    }
+
+    if (error instanceof Error && error.cause !== undefined) {
+        return [error.cause];
+    }
+
+    return [];
+}