@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/mocks/configuration.ts

@@ -0,0 +1,158 @@
+import { dirname, resolve } from "node:path";
+
+import { cloneData } from "../core/data.js";
+import { errorMessage } from "../core/errors.js";
+import { readJsonFile } from "../core/files.js";
+import { setupFilesMax } from "../core/limits.js";
+import { object } from "../items/codec.js";
+import { validateParameters } from "./parameters.js";
+import { MockRegistry, mockTarget } from "./registry.js";
+import type { PreparedMock } from "./registry.js";
+import { parseResponse, prepareResponse } from "./response.js";
+import type { Mock, MockInput } from "./types.js";
+
+export function mockInputs(value: unknown): readonly MockInput[] {
+    if (!Array.isArray(value)) {
+        throw new TypeError("Harness 'mocks' must be an array of definitions or JSON file paths.");
+    }
+
+    return value.map((entry, index) => {
+        if (typeof entry === "string" && entry.trim()) {
+            return entry;
+        }
+
+        return parseMock(entry, `mocks[${index}]`);
+    });
+}
+
+export async function loadMocks(
+    directory: string,
+    shared: readonly MockInput[] | undefined,
+    overrides: readonly MockInput[] | undefined,
+): Promise<MockRegistry> {
+    const prepared: PreparedMock[] = [];
+    let inputs = shared;
+
+    if (inputs === undefined) {
+        const conventional = Bun.file(resolve(directory, "mocks.json"));
+
+        if (await conventional.exists()) {
+            inputs = ["./mocks.json"];
+        }
+    }
+
+    // An explicit empty list clears shared mocks; otherwise local definitions override matching
+    // calls.
+    if (overrides?.length === 0) {
+        return new MockRegistry([]);
+    }
+
+    await prepare(inputs ?? [], directory, 0, prepared);
+    await prepare(overrides ?? [], directory, 1, prepared);
+
+    return new MockRegistry(prepared);
+}
+
+async function prepare(
+    inputs: readonly MockInput[],
+    directory: string,
+    layer: number,
+    output: PreparedMock[],
+): Promise<void> {
+    for (const [index, input] of inputs.entries()) {
+        if (typeof input === "string") {
+            const file = resolve(directory, input);
+            const value = await readJsonFile(file);
+
+            if (!Array.isArray(value)) {
+                throw new TypeError(`${file} must contain an array of mock definitions.`);
+            }
+
+            for (const [entry, candidate] of value.entries()) {
+                await add(
+                    parseMock(candidate, `${file}[${entry}]`),
+                    dirname(file),
+                    `${file}[${entry}]`,
+                    layer,
+                    output,
+                );
+            }
+        } else {
+            await add(
+                input,
+                directory,
+                `configuration mocks[${index}] (layer ${layer})`,
+                layer,
+                output,
+            );
+        }
+    }
+}
+
+async function add(
+    mock: Mock,
+    directory: string,
+    definition: string,
+    layer: number,
+    output: PreparedMock[],
+): Promise<void> {
+    try {
+        if (output.length >= setupFilesMax) {
+            throw new Error("The mock definition limit was reached.");
+        }
+
+        output.push({
+            ...mockTarget(mock),
+            when: cloneData(mock.when ?? {}),
+            response: await prepareResponse(mock.response, directory),
+            definition,
+            layer,
+        });
+    } catch (error) {
+        throw new Error(`Cannot load mock ${definition}: ${errorMessage(error)}`, { cause: error });
+    }
+}
+
+function parseMock(value: unknown, path: string): Mock {
+    if (
+        !object(value) ||
+        !Object.keys(value).every((key) => ["method", "sql", "when", "response"].includes(key))
+    ) {
+        throw new Error(`${path} must contain method or sql, optional when, and response.`);
+    }
+
+    if (!("response" in value)) {
+        throw new Error(`${path} is missing response.`);
+    }
+
+    const method = typeof value.method === "string" && value.method.trim().length > 0;
+    const sql =
+        value.sql === true || (typeof value.sql === "string" && value.sql.trim().length > 0);
+
+    if (
+        (method ? 1 : 0) + (sql ? 1 : 0) !== 1 ||
+        (method && "sql" in value) ||
+        (sql && "method" in value)
+    ) {
+        throw new Error(`${path} must select exactly one method or sql target.`);
+    }
+
+    const response = parseResponse(value.response);
+    const when = value.when;
+
+    if (when !== undefined) {
+        validateParameters(when, `${path}.when`);
+    }
+
+    const options = { response, ...(when === undefined ? {} : { when }) };
+
+    if (typeof value.method === "string") {
+        return { method: value.method, ...options };
+    }
+
+    if (value.sql === true || typeof value.sql === "string") {
+        return { sql: value.sql, ...options };
+    }
+
+    throw new Error(`${path} has no mock target.`);
+}

package/src/mocks/parameters.ts

@@ -0,0 +1,20 @@
+import { assertDataTree } from "../core/data.js";
+import { object } from "../items/codec.js";
+import type { MockValue } from "./types.js";
+
+export function validateParameters(
+    value: unknown,
+    path: string,
+): asserts value is Readonly<Record<string, MockValue>> {
+    if (!object(value)) {
+        throw new TypeError(`${path} must be an object of property matches.`);
+    }
+
+    try {
+        assertDataTree(value, { allowArrays: false, allowUndefined: false });
+    } catch (error) {
+        throw new TypeError(`${path} contains an invalid or circular property match.`, {
+            cause: error,
+        });
+    }
+}

package/src/mocks/registry.ts

@@ -0,0 +1,214 @@
+import { assertDataTree, cloneData, getOwn, setOwn } from "../core/data.js";
+import type { Item } from "../items/item.js";
+import type { PreparedResponse } from "./response.js";
+import type { Mock, MockValue } from "./types.js";
+
+export interface PreparedMock {
+    readonly kind: "method" | "sql";
+    readonly name: string | true;
+    readonly when: Readonly<Record<string, MockValue>>;
+    readonly response: PreparedResponse;
+    readonly definition: string;
+    readonly layer: number;
+}
+
+export interface MockMatch {
+    readonly result: Item;
+    readonly definition: string;
+    readonly responseFile?: string;
+    readonly responseHash: string;
+    readonly parameters: Readonly<Record<string, MockValue>>;
+}
+
+export interface MockDescription {
+    readonly definition: string;
+    readonly when: Readonly<Record<string, MockValue>>;
+    readonly layer: number;
+    readonly responseFile?: string;
+    readonly responseHash: string;
+}
+
+/** Immutable response definitions; every invocation receives its own Item. */
+export class MockRegistry {
+    constructor(private readonly mocks: readonly PreparedMock[]) {}
+
+    /** Describe matching targets without selecting a response for invented parameters. */
+    describe(kind: PreparedMock["kind"], names: readonly string[]): readonly MockDescription[] {
+        return Object.freeze(
+            this.mocks
+                .filter(
+                    (mock) => mock.kind === kind && names.some((name) => sameName(name, mock.name)),
+                )
+                .map((mock) =>
+                    Object.freeze({
+                        definition: mock.definition,
+                        when: cloneData(mock.when),
+                        layer: mock.layer,
+                        responseHash: mock.response.hash,
+                        ...(mock.response.file ? { responseFile: mock.response.file } : {}),
+                    }),
+                ),
+        );
+    }
+
+    method(names: readonly string[], item: Item): MockMatch | undefined {
+        const matches = this.mocks.some(
+            (mock) => mock.kind === "method" && names.some((name) => sameName(name, mock.name)),
+        );
+
+        if (!matches) {
+            return undefined;
+        }
+
+        return this.find("method", names, properties(item));
+    }
+
+    sql(name: string | true, values: Readonly<Record<string, MockValue>>): MockMatch | undefined {
+        return this.find("sql", [name], values);
+    }
+
+    private find(
+        kind: PreparedMock["kind"],
+        names: readonly (string | true)[],
+        values: Readonly<Record<string, MockValue>>,
+    ): MockMatch | undefined {
+        const candidates = this.mocks.filter(
+            (mock) =>
+                mock.kind === kind &&
+                names.some((name) => sameName(name, mock.name)) &&
+                matchesParameters(mock.when, values),
+        );
+
+        if (candidates.length === 0) {
+            return undefined;
+        }
+
+        const layer = candidates.reduce(
+            (highest, mock) => Math.max(highest, mock.layer),
+            -Infinity,
+        );
+        const current = candidates.filter((mock) => mock.layer === layer);
+        const specificity = current.reduce(
+            (highest, mock) => Math.max(highest, weight(mock.when)),
+            0,
+        );
+        const selected = current.filter((mock) => weight(mock.when) === specificity);
+        const mock = selected[0];
+
+        if (selected.length !== 1 || !mock) {
+            throw new Error(
+                `Ambiguous ${kind} mocks for '${names.join(" / ")}': ${selected.map((mock) => mock.definition).join(", ")}.`,
+            );
+        }
+
+        return {
+            result: mock.response.item.clone(),
+            definition: mock.definition,
+            responseHash: mock.response.hash,
+            parameters: cloneData(values),
+            ...(mock.response.file ? { responseFile: mock.response.file } : {}),
+        };
+    }
+}
+
+export function properties(item: Item): Readonly<Record<string, MockValue>> {
+    if (item.payload.items.length !== 1 || item.isError()) {
+        return {};
+    }
+
+    assertDataTree(item.payload);
+    const result: Record<string, MockValue> = {};
+    const pending = [{ node: item.node, output: result }];
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("A mock parameter frame must exist while traversal is pending.");
+        }
+
+        for (const [name, value] of Object.entries(frame.node.properties)) {
+            setOwn(frame.output, name, value);
+        }
+
+        setOwn(frame.output, "id", frame.node.attributes.id ?? "");
+
+        for (const [name, node] of Object.entries(frame.node.propertyItems)) {
+            const output: Record<string, MockValue> = {};
+            setOwn(frame.output, name, output);
+            pending.push({ node, output });
+        }
+    }
+
+    return result;
+}
+
+export function matchesParameters(
+    expected: Readonly<Record<string, MockValue>>,
+    actual: Readonly<Record<string, MockValue>>,
+): boolean {
+    const pending = [{ expected, actual }];
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("A mock match frame must exist while traversal is pending.");
+        }
+
+        for (const [name, value] of Object.entries(frame.expected)) {
+            const candidate = getOwn(frame.actual, name);
+
+            if (value !== null && typeof value === "object") {
+                if (candidate === null || typeof candidate !== "object") {
+                    return false;
+                }
+
+                pending.push({ expected: value, actual: candidate });
+            } else if (candidate === undefined || candidate !== value) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}
+
+function sameName(left: string | true, right: string | true): boolean {
+    if (typeof left === "string" && typeof right === "string") {
+        return left.toLowerCase() === right.toLowerCase();
+    }
+
+    return left === right;
+}
+
+function weight(when: Readonly<Record<string, MockValue>>): number {
+    let total = 0;
+    const pending = [when];
+
+    while (pending.length > 0) {
+        const current = pending.pop();
+
+        if (!current) {
+            throw new Error("A mock weight frame must exist while traversal is pending.");
+        }
+
+        for (const value of Object.values(current)) {
+            total += 1;
+
+            if (value !== null && typeof value === "object") {
+                pending.push(value);
+            }
+        }
+    }
+
+    return total;
+}
+
+export function mockTarget(mock: Mock): Pick<PreparedMock, "kind" | "name"> {
+    if (mock.method !== undefined) {
+        return { kind: "method", name: mock.method };
+    }
+
+    return { kind: "sql", name: mock.sql };
+}

package/src/mocks/response.ts

@@ -0,0 +1,128 @@
+import { extname, resolve } from "node:path";
+
+import { assertDataTree } from "../core/data.js";
+import { readTextFile } from "../core/files.js";
+import { object } from "../items/codec.js";
+import { Item } from "../items/item.js";
+import { parseItems } from "../items/xml.js";
+import type { MockResponse, JsonValue } from "./types.js";
+
+export interface PreparedResponse {
+    readonly item: Item;
+    readonly file?: string;
+    readonly hash: string;
+}
+
+export async function prepareResponse(
+    response: string | MockResponse,
+    directory: string,
+): Promise<PreparedResponse> {
+    if (typeof response !== "string") {
+        const item = responseItem(response);
+
+        return { item, hash: hash(JSON.stringify(item.payload)) };
+    }
+
+    const file = resolve(directory, response);
+    const text = await readTextFile(file);
+    const extension = extname(file).toLowerCase();
+    let item: Item;
+
+    if (extension === ".json") {
+        item = jsonResult(JSON.parse(text.replace(/^\uFEFF/u, "")));
+    } else if (extension === ".xml" || extension === ".aml") {
+        item = amlResult(text);
+    } else if (extension === ".txt") {
+        item = new Item({ items: [], result: text });
+    } else {
+        throw new Error(`Mock response '${file}' must be JSON, AML/XML, or text.`);
+    }
+
+    return { item, file, hash: hash(text) };
+}
+
+export function parseResponse(value: unknown): string | MockResponse {
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value;
+    }
+
+    if (value instanceof Item) {
+        return value;
+    }
+
+    if (!object(value)) {
+        throw new Error("A mock response must be a file, Item, or json/text/aml/error response.");
+    }
+
+    const keys = Object.keys(value);
+
+    if (keys.length === 1 && "json" in value) {
+        assertJson(value.json);
+
+        return { json: value.json };
+    }
+
+    if (keys.length === 1 && typeof value.text === "string") {
+        return { text: value.text };
+    }
+
+    if (keys.length === 1 && typeof value.aml === "string") {
+        return { aml: value.aml };
+    }
+
+    if (
+        typeof value.error === "string" &&
+        (value.code === undefined || typeof value.code === "string") &&
+        keys.every((key) => key === "error" || key === "code")
+    ) {
+        return { error: value.error, ...(value.code === undefined ? {} : { code: value.code }) };
+    }
+
+    throw new Error("A mock response must contain exactly one of json, text, aml, or error.");
+}
+
+function responseItem(response: MockResponse): Item {
+    if (response instanceof Item) {
+        return response.clone();
+    }
+
+    if ("json" in response) {
+        return jsonResult(response.json);
+    }
+
+    if ("text" in response) {
+        return new Item({ items: [], result: response.text });
+    }
+
+    if ("aml" in response) {
+        return amlResult(response.aml);
+    }
+
+    return Item.error(response.error, response.code);
+}
+
+function jsonResult(value: unknown): Item {
+    assertJson(value);
+
+    return new Item({ items: [], result: JSON.stringify(value) });
+}
+
+function assertJson(value: unknown): asserts value is JsonValue {
+    try {
+        assertDataTree(value, { allowArrays: true, allowUndefined: false });
+    } catch (error) {
+        throw new Error("Mock JSON must contain only finite plain JSON values without cycles.", {
+            cause: error,
+        });
+    }
+}
+
+function amlResult(xml: string): Item {
+    const items = parseItems(xml);
+
+    return new Item({ items: items.flatMap((item) => item.payload.items) });
+}
+
+function hash(text: string): string {
+    return new Bun.CryptoHasher("sha256").update(text).digest("hex");
+}

package/src/mocks/types.ts

@@ -0,0 +1,56 @@
+import type { Item } from "../items/item.js";
+
+export type JsonValue =
+    | null
+    | boolean
+    | number
+    | string
+    | readonly JsonValue[]
+    | {
+          readonly [name: string]: JsonValue;
+      };
+
+export type MockValue =
+    | null
+    | boolean
+    | number
+    | string
+    | {
+          readonly [name: string]: MockValue;
+      };
+
+export type MockResponse =
+    | Item
+    | {
+          readonly json: JsonValue;
+      }
+    | {
+          readonly text: string;
+      }
+    | {
+          readonly aml: string;
+      }
+    | {
+          readonly error: string;
+          readonly code?: string;
+      };
+
+interface MockOptions {
+    readonly when?: Readonly<Record<string, MockValue>>;
+    readonly response: string | MockResponse;
+}
+
+export interface MethodMock extends MockOptions {
+    readonly method: string;
+    readonly sql?: never;
+}
+
+/** A named SQL procedure, or an inline query selected by its calling Method. */
+export interface SqlMock extends MockOptions {
+    readonly sql: string | true;
+    readonly method?: never;
+}
+
+export type Mock = MethodMock | SqlMock;
+
+export type MockInput = string | Mock;

package/src/packages/bootstrap.ts

@@ -0,0 +1,73 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { PropertyDefinition } from "../storage/types.js";
+
+/** Retained for export fidelity; these definitions require a presentation adapter to execute. */
+export const presentationTypes = new Set([
+    "Form",
+    "Body",
+    "Field",
+    "View",
+    "PresentationConfiguration",
+    "ITPresentationConfiguration",
+    "CommandBarButton",
+    "CommandBarMenuButton",
+    "CommandBarSection",
+    "CommandBarMenu",
+    "CommandBarItem",
+    "CUI_Application",
+    "CUI_Application_Pages",
+    "cui_Location",
+    "Section",
+    "CommandBarSectionItem",
+    "Form Event",
+    "TOC View",
+    "PresentationCommandBarSection",
+    "Grid Event",
+]);
+
+export const systemProperties: readonly PropertyDefinition[] = [
+    { name: "id", dataType: "string" },
+    { name: "config_id", dataType: "item" },
+    { name: "generation", dataType: "integer" },
+    { name: "is_current", dataType: "boolean" },
+    { name: "new_version", dataType: "boolean" },
+    { name: "not_lockable", dataType: "boolean" },
+    { name: "keyed_name", dataType: "string" },
+    { name: "classification", dataType: "string" },
+    { name: "state", dataType: "string" },
+    { name: "current_state", dataType: "item" },
+    { name: "created_on", dataType: "date" },
+    { name: "modified_on", dataType: "date" },
+    { name: "created_by_id", dataType: "item" },
+    { name: "modified_by_id", dataType: "item" },
+    { name: "owned_by_id", dataType: "item" },
+    { name: "managed_by_id", dataType: "item" },
+    { name: "permission_id", dataType: "item" },
+    { name: "locked_by_id", dataType: "item" },
+    { name: "is_released", dataType: "boolean" },
+    { name: "major_rev", dataType: "string" },
+    { name: "minor_rev", dataType: "string" },
+    { name: "css", dataType: "text" },
+    { name: "team_id", dataType: "item" },
+];
+
+export const versionableProperties: readonly PropertyDefinition[] = [
+    { name: "effective_date", dataType: "date" },
+    { name: "release_date", dataType: "date" },
+    { name: "superseded_date", dataType: "date" },
+];
+
+export const relationshipProperties: readonly PropertyDefinition[] = [
+    { name: "source_id", dataType: "item" },
+    { name: "related_id", dataType: "item" },
+    { name: "sort_order", dataType: "integer" },
+    { name: "behavior", dataType: "string" },
+];
+
+export function stableId(value: string): string {
+    return new Bun.CryptoHasher("sha256").update(value).digest("hex").slice(0, 32).toUpperCase();
+}
+
+export function bootstrapSource(path: string): SourceLocation {
+    return { file: "<innovator-harness:bootstrap-v1>", line: 1, column: 1, path };
+}