@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/harness/extensions.ts

@@ -0,0 +1,86 @@
+import type { HarnessModule } from "../core/types.js";
+import type { MethodExecutor } from "../methods/types.js";
+import type { HarnessStorage } from "../storage/types.js";
+
+export type ModuleFactory = (storage: HarnessStorage) => HarnessModule;
+
+export type ExecutorFactory = () => MethodExecutor;
+
+export function moduleFactories(value: unknown): readonly ModuleFactory[] {
+    return factories(value, "modules").map((create) => (storage) => {
+        const module: unknown = create(storage);
+
+        if (!isModule(module)) {
+            throw new Error("A Harness module factory must return a valid module.");
+        }
+
+        return module;
+    });
+}
+
+export function executorFactories(value: unknown): readonly ExecutorFactory[] {
+    return factories(value, "executors").map((create) => () => {
+        const executor: unknown = create();
+
+        if (!isMethodExecutor(executor)) {
+            throw new Error("A Harness executor factory must return a language executor.");
+        }
+
+        return executor;
+    });
+}
+
+function factories(
+    value: unknown,
+    name: string,
+): readonly ((...arguments_: unknown[]) => unknown)[] {
+    if (value === undefined) {
+        return [];
+    }
+
+    if (!Array.isArray(value) || value.length > 1000) {
+        throw new TypeError(`Harness '${name}' must be an array of factories.`);
+    }
+
+    return value.map((factory) => {
+        if (!isFactory(factory)) {
+            throw new TypeError(`Each Harness '${name}' entry must create a fresh instance.`);
+        }
+
+        return (...arguments_: unknown[]): unknown => factory(...arguments_);
+    });
+}
+
+function isMethodExecutor(value: unknown): value is MethodExecutor {
+    return (
+        isObject(value) &&
+        typeof value.language === "string" &&
+        typeof value.execute === "function" &&
+        optionalFunction(value.reset) &&
+        optionalFunction(value.dispose)
+    );
+}
+
+function isModule(value: unknown): value is HarnessModule {
+    return (
+        isObject(value) &&
+        typeof value.id === "string" &&
+        typeof value.setup === "function" &&
+        optionalFunction(value.reset) &&
+        optionalFunction(value.dispose) &&
+        (value.requires === undefined ||
+            (Array.isArray(value.requires) && value.requires.every((id) => typeof id === "string")))
+    );
+}
+
+function optionalFunction(value: unknown): boolean {
+    return value === undefined || typeof value === "function";
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+function isFactory(value: unknown): value is (...arguments_: unknown[]) => unknown {
+    return typeof value === "function";
+}

package/src/harness/fixtures.ts

@@ -0,0 +1,186 @@
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { extname, join } from "node:path";
+
+import { assertDataTree, setOwn, getOwn } from "../core/data.js";
+import { setupFilesMax, setupBytesMax } from "../core/limits.js";
+import type { Engine } from "../engine.js";
+import { loadFixtureRecords } from "../fixtures/module.js";
+import type { FixtureRecord, Fixtures, FixtureValue } from "../fixtures/types.js";
+import { loadSetupModule } from "./setup-module.js";
+
+export async function splitFixturePaths(paths: readonly string[]): Promise<{
+    readonly aml: readonly string[];
+    readonly typescript: readonly string[];
+}> {
+    const aml: string[] = [];
+    const typescript: string[] = [];
+    const seen = new Set<string>();
+
+    const pending = [...paths].reverse();
+    let visited = 0;
+
+    while (pending.length > 0) {
+        visited += 1;
+
+        if (visited > setupFilesMax || pending.length > setupFilesMax) {
+            throw new Error("Fixture discovery exceeded its file limit.");
+        }
+
+        const path = pending.pop();
+
+        if (path === undefined) {
+            throw new Error("A fixture path must exist while discovery is pending.");
+        }
+
+        const status = await lstat(path);
+
+        if (status.isSymbolicLink()) {
+            throw new Error(`Fixture input '${path}' is a symbolic link. Supply its real path.`);
+        }
+
+        if (status.isDirectory()) {
+            const entries = await readdir(path);
+
+            for (const entry of entries.sort().reverse()) {
+                pending.push(join(path, entry));
+            }
+
+            continue;
+        }
+
+        const canonical = await realpath(path);
+
+        if (seen.has(canonical)) {
+            throw new Error(`Fixture input '${path}' was supplied more than once.`);
+        }
+
+        seen.add(canonical);
+
+        if (extname(path) === ".ts") {
+            typescript.push(canonical);
+        } else if (extname(path).toLowerCase() === ".xml") {
+            aml.push(canonical);
+        } else {
+            throw new Error(
+                `Unsupported fixture '${path}'. Use a TypeScript data module or AML XML.`,
+            );
+        }
+    }
+
+    return { aml, typescript };
+}
+
+export async function loadTypeScriptFixtures(
+    engine: Engine,
+    paths: readonly string[],
+): Promise<void> {
+    const records = await readTypeScriptFixtures(paths);
+
+    if (paths.length > 0) {
+        engine.runtime.executeSync(loadFixtureRecords, records);
+    }
+}
+
+export async function readTypeScriptFixtures(paths: readonly string[]): Promise<Fixtures> {
+    const combined: Record<string, FixtureRecord[]> = {};
+    let bytes = 0;
+
+    for (const path of paths) {
+        const imported = await loadSetupModule(path);
+
+        if (!isObject(imported)) {
+            throw new Error(`Cannot read fixture module '${path}'.`);
+        }
+
+        assertDataTree(imported.default, { allowArrays: true, allowUndefined: false });
+        bytes += JSON.stringify(imported.default).length * 3;
+
+        if (bytes > setupBytesMax) {
+            throw new Error("Combined fixture data exceeds its byte limit.");
+        }
+
+        const fixtures = parseFixtures(imported.default, path);
+
+        for (const [type, records] of Object.entries(fixtures)) {
+            const existing = Object.hasOwn(combined, type) ? getOwn(combined, type) : undefined;
+
+            if (existing) {
+                for (const record of records) {
+                    existing.push(record);
+                }
+            } else {
+                setOwn(combined, type, [...records]);
+            }
+        }
+    }
+
+    return combined;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseFixtures(value: unknown, path: string): Fixtures {
+    if (!isObject(value)) {
+        throw new Error(`${path} must default-export fixture records grouped by ItemType.`);
+    }
+
+    const fixtures: Record<string, FixtureRecord[]> = {};
+
+    for (const [type, records] of Object.entries(value)) {
+        if (!Array.isArray(records)) {
+            throw new TypeError(`Fixture '${type}' in ${path} must be an array of records.`);
+        }
+
+        setOwn(
+            fixtures,
+            type,
+            records.map((record) => parseRecord(record, path, type)),
+        );
+    }
+
+    return fixtures;
+}
+
+function parseRecord(value: unknown, path: string, type: string): FixtureRecord {
+    if (!isObject(value)) {
+        throw new Error(`Fixture '${type}' in ${path} contains an invalid record.`);
+    }
+
+    const record: Record<string, FixtureValue> = {};
+
+    for (const [name, property] of Object.entries(value)) {
+        if (isObject(property)) {
+            const selector: Record<string, string | number | null> = {};
+
+            for (const [key, entry] of Object.entries(property)) {
+                if (!isScalar(entry)) {
+                    throw new Error(
+                        `Invalid fixture selector '${type}.${name}.${key}' in ${path}.`,
+                    );
+                }
+
+                setOwn(selector, key, entry);
+            }
+
+            setOwn(record, name, selector);
+        } else {
+            if (!isScalar(property)) {
+                throw new Error(`Invalid fixture value '${type}.${name}' in ${path}.`);
+            }
+
+            setOwn(record, name, property);
+        }
+    }
+
+    return record;
+}
+
+function isScalar(value: unknown): value is string | number | null {
+    return (
+        value === null ||
+        typeof value === "string" ||
+        (typeof value === "number" && Number.isFinite(value))
+    );
+}

package/src/harness/runtime-identity.ts

@@ -0,0 +1,41 @@
+import { readBinaryFile } from "../core/files.js";
+
+const directory = Bun.fileURLToPath(new URL("..", import.meta.url));
+let identity: Promise<string> | undefined;
+
+/** A setup image belongs to this exact runtime, including baseline data and seeding behavior. */
+export function runtimeIdentity(): Promise<string> {
+    identity ??= hashRuntime();
+
+    return identity;
+}
+
+async function hashRuntime(): Promise<string> {
+    const paths = [
+        ...new Bun.Glob("**/*.{js,ts,json,bin,cs,template,csproj,Config}").scanSync({
+            cwd: directory,
+        }),
+    ]
+        .filter(
+            (path) =>
+                !path.endsWith(".d.ts") &&
+                !path.split("/").some((part) => part === "bin" || part === "obj"),
+        )
+        .sort();
+    const hash = new Bun.CryptoHasher("sha256").update(Bun.version);
+
+    for (let offset = 0; offset < paths.length; offset += 32) {
+        const sources = await Promise.all(
+            paths.slice(offset, offset + 32).map(async (path) => ({
+                path,
+                bytes: await readBinaryFile(`${directory}/${path}`),
+            })),
+        );
+
+        for (const source of sources) {
+            hash.update(JSON.stringify([source.path, source.bytes.length])).update(source.bytes);
+        }
+    }
+
+    return hash.digest("hex");
+}

package/src/harness/setup-cache.ts

@@ -0,0 +1,56 @@
+import type { EngineImage } from "../engine/instance.js";
+
+const imagesMax = 4;
+const imageBytesMax = 64 * 1024 * 1024;
+
+/** Retain immutable setup images, never worlds, connections, executors or test mutations. */
+export class SetupCache {
+    private readonly images = new Map<string, EngineImage>();
+    private bytes = 0;
+
+    get(key: string): EngineImage | undefined {
+        const image = this.images.get(key);
+
+        if (image) {
+            this.images.delete(key);
+            this.images.set(key, image);
+        }
+
+        return image;
+    }
+
+    put(key: string, image: EngineImage): void {
+        if (image.database.byteLength > imageBytesMax) {
+            return;
+        }
+
+        this.remove(key);
+
+        while (
+            this.images.size >= imagesMax ||
+            this.bytes + image.database.byteLength > imageBytesMax
+        ) {
+            const oldest = this.images.keys().next().value;
+
+            if (oldest === undefined) {
+                throw new Error("Setup image eviction requires an existing image.");
+            }
+
+            this.remove(oldest);
+        }
+
+        this.images.set(key, image);
+        this.bytes += image.database.byteLength;
+    }
+
+    private remove(key: string): void {
+        const image = this.images.get(key);
+
+        if (image) {
+            this.bytes -= image.database.byteLength;
+            this.images.delete(key);
+        }
+    }
+}
+
+export const setupCache = new SetupCache();

package/src/harness/setup-image.ts

@@ -0,0 +1,155 @@
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { readBinaryFile } from "../core/files.js";
+import type { EngineImage } from "../engine/instance.js";
+
+const imageBytesMax = 64 * 1024 * 1024;
+const metadataBytesMax = 4096;
+const headerBytes = 12;
+const signature = new TextEncoder().encode("IHSETUP1");
+
+/** One replaceable artifact per project, shared by all test cases and Bun invocations. */
+export async function readSetupImage(path: string, key: string): Promise<EngineImage | undefined> {
+    try {
+        const bytes = await readBinaryFile(path, imageBytesMax + metadataBytesMax + headerBytes);
+
+        return decodeImage(bytes, key);
+    } catch (error) {
+        if (unavailable(error) || error instanceof SyntaxError || error instanceof TypeError) {
+            return undefined;
+        }
+
+        throw error;
+    }
+}
+
+function decodeImage(bytes: Uint8Array, key: string): EngineImage | undefined {
+    if (bytes.length < headerBytes || !signature.every((value, index) => bytes[index] === value)) {
+        return undefined;
+    }
+
+    const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(
+        8,
+        true,
+    );
+
+    if (length > metadataBytesMax || headerBytes + length >= bytes.length) {
+        return undefined;
+    }
+
+    const parsed: unknown = JSON.parse(
+        new TextDecoder().decode(bytes.subarray(headerBytes, headerBytes + length)),
+    );
+
+    if (
+        !record(parsed) ||
+        parsed.key !== key ||
+        !record(parsed.values) ||
+        !record(parsed.values.ids)
+    ) {
+        return undefined;
+    }
+
+    const clock = parsed.values.clock;
+    const fixtures = parsed.values.ids.fixtures;
+    const items = parsed.values.ids.items;
+
+    if (
+        (clock !== undefined && (typeof clock !== "number" || !Number.isFinite(clock))) ||
+        !counter(fixtures) ||
+        !counter(items)
+    ) {
+        return undefined;
+    }
+
+    const database = bytes.subarray(headerBytes + length);
+
+    if (
+        database.length > imageBytesMax ||
+        new Bun.CryptoHasher("sha256")
+            .update(JSON.stringify({ key: parsed.key, values: parsed.values }))
+            .update(database)
+            .digest("hex") !== parsed.hash
+    ) {
+        return undefined;
+    }
+
+    return { database, values: { clock, ids: { fixtures, items } } };
+}
+
+export async function writeSetupImage(
+    path: string,
+    key: string,
+    image: EngineImage,
+): Promise<void> {
+    if (image.database.byteLength > imageBytesMax) {
+        return;
+    }
+
+    const metadata = new TextEncoder().encode(
+        JSON.stringify({
+            key,
+            hash: new Bun.CryptoHasher("sha256")
+                .update(JSON.stringify({ key, values: image.values }))
+                .update(image.database)
+                .digest("hex"),
+            values: image.values,
+        }),
+    );
+    const bytes = new Uint8Array(headerBytes + metadata.length + image.database.byteLength);
+    bytes.set(signature);
+    new DataView(bytes.buffer).setUint32(8, metadata.length, true);
+    bytes.set(metadata, headerBytes);
+    bytes.set(image.database, headerBytes + metadata.length);
+    const temporary = `${path}.${crypto.randomUUID()}.tmp`;
+
+    try {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await ignoreCache(dirname(path));
+        await Bun.write(temporary, bytes, { mode: 0o600 });
+        await rename(temporary, path);
+    } catch (error) {
+        if (!unavailable(error)) {
+            throw error;
+        }
+    } finally {
+        await removeTemporaryImage(temporary);
+    }
+}
+
+async function removeTemporaryImage(path: string): Promise<void> {
+    try {
+        await rm(path, { force: true });
+    } catch (error) {
+        if (!unavailable(error)) {
+            throw error;
+        }
+    }
+}
+
+async function ignoreCache(directory: string): Promise<void> {
+    try {
+        await writeFile(join(directory, ".gitignore"), "*\n", { flag: "wx", mode: 0o600 });
+    } catch (error) {
+        if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") {
+            throw error;
+        }
+    }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function counter(value: unknown): value is number {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function unavailable(error: unknown): boolean {
+    return (
+        error instanceof Error &&
+        "code" in error &&
+        ["ENOENT", "EACCES", "EPERM", "EROFS", "ENOSPC", "ENOTDIR"].includes(String(error.code))
+    );
+}

package/src/harness/setup-imports.ts

@@ -0,0 +1,40 @@
+import { dirname, isAbsolute } from "node:path";
+
+import { init, parse } from "es-module-lexer";
+
+/** External imports must resolve from their source file, not the temporary setup bundle. */
+export async function resolveSetupImports(source: string, path: string): Promise<string> {
+    await init();
+    const [imports] = parse(source, path);
+    const fragments: string[] = [];
+    let copied = 0;
+
+    for (const entry of imports) {
+        const specifier = entry.specifier;
+
+        if (
+            !specifier ||
+            specifier.startsWith(".") ||
+            specifier.startsWith("/") ||
+            specifier.startsWith("file:") ||
+            (entry.type === "dynamic" && entry.glob)
+        ) {
+            continue;
+        }
+
+        const resolved = Bun.resolveSync(specifier, dirname(path));
+
+        if (!isAbsolute(resolved)) {
+            continue;
+        }
+
+        const url = Bun.pathToFileURL(resolved).href;
+        const replacement = entry.type === "dynamic" ? JSON.stringify(url) : url;
+        fragments.push(source.slice(copied, entry.start), replacement);
+        copied = entry.end;
+    }
+
+    fragments.push(source.slice(copied));
+
+    return fragments.join("");
+}

package/src/harness/setup-inputs.ts

@@ -0,0 +1,80 @@
+import { setupBytesMax, setupFilesMax } from "../core/limits.js";
+import type { Fixtures } from "../fixtures/types.js";
+import { PackageFileError, readText } from "../packages/files.js";
+import { parseAml } from "../packages/parser.js";
+import type { AmlDocument } from "../packages/types.js";
+import type { ResolvedConfig } from "./configuration.js";
+
+export interface SetupSource {
+    readonly path: string;
+    readonly xml: string;
+}
+
+const readsParallelMax = 32;
+
+/** Hash actual bytes on each creation; unchanged inputs do not need parsing or import. */
+export async function readSetupSources(paths: readonly string[]): Promise<readonly SetupSource[]> {
+    if (paths.length > setupFilesMax) {
+        throw new PackageFileError("PackageReadFailed", "<setup>", "Too many setup inputs.");
+    }
+
+    const sources: SetupSource[] = [];
+    let bytes = 0;
+
+    for (let offset = 0; offset < paths.length; offset += readsParallelMax) {
+        const batch = await Promise.all(
+            paths.slice(offset, offset + readsParallelMax).map(async (path) => ({
+                path,
+                xml: await readText(path),
+            })),
+        );
+
+        for (const source of batch) {
+            bytes += source.xml.length * 3;
+
+            if (bytes > setupBytesMax) {
+                throw new PackageFileError(
+                    "PackageReadFailed",
+                    source.path,
+                    "Setup inputs exceed the byte limit.",
+                );
+            }
+
+            sources.push(source);
+        }
+    }
+
+    return sources;
+}
+
+export function setupKey(
+    configuration: ResolvedConfig,
+    sources: readonly SetupSource[],
+    packages: number,
+    fixtures: Fixtures,
+    runtime: string,
+): string {
+    const settings = configuration.settings;
+    const hash = new Bun.CryptoHasher("sha256").update(
+        JSON.stringify({
+            directory: configuration.directory,
+            runtime,
+            packages,
+            fixtures,
+            clock: settings.clock,
+            ids: settings.ids,
+            session: settings.session,
+            authorization: settings.authorization,
+        }),
+    );
+
+    for (const source of sources) {
+        hash.update(JSON.stringify([source.path, source.xml.length])).update(source.xml);
+    }
+
+    return hash.digest("hex");
+}
+
+export function parseSetupSources(sources: readonly SetupSource[]): readonly AmlDocument[] {
+    return sources.map((source) => parseAml(source.xml, source.path));
+}