@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/compatibility/types.ts

@@ -0,0 +1,153 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { HarnessOptions } from "../harness/configuration.js";
+import type {
+    ExecutionReport,
+    ExecutionMode,
+    ExecutionStatus,
+    ExecutionOutcome,
+} from "../instrumentation/types.js";
+import type { MethodDefinition } from "../methods/types.js";
+import type { MockValue } from "../mocks/types.js";
+import type {
+    PackageMethodDeclaration,
+    PackageSqlDeclaration,
+    PackageVerificationReport,
+} from "../verification/types.js";
+import type { CapabilityDescriptor, CapabilityId } from "./capabilities.js";
+
+export interface CompatibilityOptions extends HarnessOptions {
+    /** Compile effective C# source unless an unconditional mock replaces it. Never invoke it. */
+    readonly compile?: boolean;
+    readonly executions?: readonly ExecutionReport[];
+}
+
+export enum CompatibilityIssueCode {
+    PackageImportFailed = "PACKAGE_IMPORT_FAILED",
+    UnsupportedCapability = "UNSUPPORTED_CAPABILITY",
+    ExecutorUnavailable = "EXECUTOR_UNAVAILABLE",
+    CompilationFailed = "COMPILATION_FAILED",
+    InvalidDefinition = "INVALID_DEFINITION",
+    InvalidMocks = "INVALID_MOCKS",
+    ConditionalMock = "CONDITIONAL_MOCK",
+    AmbiguousMock = "AMBIGUOUS_MOCK",
+    ExtensionNotInspected = "EXTENSION_NOT_INSPECTED",
+    AuthorizationRequired = "AUTHORIZATION_REQUIRED",
+    ExecutionSourceMismatch = "EXECUTION_SOURCE_MISMATCH",
+    ExecutionEvidenceTruncated = "EXECUTION_EVIDENCE_TRUNCATED",
+}
+
+export enum IssueSeverity {
+    Error = "ERROR",
+    Warning = "WARNING",
+    Information = "INFORMATION",
+}
+
+export interface CompatibilityIssue {
+    readonly code: CompatibilityIssueCode;
+    readonly severity: IssueSeverity;
+    readonly message: string;
+    readonly capability?: CapabilityId;
+    /** Original runtime diagnostic, when the same gap can be encountered during execution. */
+    readonly causeCode?: string;
+    readonly source?: SourceLocation;
+}
+
+export enum ExecutorStatus {
+    Available = "AVAILABLE",
+    Missing = "MISSING",
+    Disabled = "DISABLED",
+    Unavailable = "UNAVAILABLE",
+    Unknown = "UNKNOWN",
+}
+
+export interface ExecutorCheck {
+    readonly status: ExecutorStatus;
+    readonly message?: string;
+}
+
+export enum MockCoverage {
+    None = "NONE",
+    Conditional = "CONDITIONAL",
+    Unconditional = "UNCONDITIONAL",
+    Ambiguous = "AMBIGUOUS",
+    Unknown = "UNKNOWN",
+}
+
+export interface MockRuleDescription {
+    readonly definition: string;
+    readonly when: Readonly<Record<string, MockValue>>;
+    readonly layer: number;
+    readonly responseFile?: string;
+    readonly responseHash: string;
+}
+
+export interface MockCheck {
+    readonly coverage: MockCoverage;
+    readonly rules: readonly MockRuleDescription[];
+}
+
+export enum CompilationStatus {
+    NotRequested = "NOT_REQUESTED",
+    Compiled = "COMPILED",
+    Failed = "FAILED",
+    SkippedMock = "SKIPPED_MOCK",
+    Unavailable = "UNAVAILABLE",
+    Unsupported = "UNSUPPORTED",
+    Unresolved = "UNRESOLVED",
+}
+
+export interface CompilationCheck {
+    readonly status: CompilationStatus;
+    /** The effective source that was checked; never a claim about an overwritten declaration. */
+    readonly sourceHash?: string;
+    readonly message?: string;
+}
+
+export interface MethodCompatibility {
+    readonly declaration: PackageMethodDeclaration;
+    readonly definition?: Omit<MethodDefinition, "code">;
+    readonly executor: ExecutorCheck;
+    readonly mocks: MockCheck;
+    readonly compilation: CompilationCheck;
+    readonly issues: readonly CompatibilityIssue[];
+    readonly executed: boolean;
+    readonly observations: readonly SourceExecutionObservation[];
+    readonly referenceVerified: boolean;
+}
+
+export interface SqlCompatibility {
+    readonly declaration: PackageSqlDeclaration;
+    readonly definition?: {
+        readonly id: string;
+        readonly name: string;
+        readonly source: SourceLocation;
+        readonly bodyHashes: Readonly<Record<string, string>>;
+    };
+    readonly executor: ExecutorCheck;
+    readonly mocks: MockCheck;
+    readonly issues: readonly CompatibilityIssue[];
+    readonly executed: boolean;
+    readonly observations: readonly SourceExecutionObservation[];
+    readonly referenceVerified: boolean;
+}
+
+export interface SourceExecutionObservation {
+    readonly reportId: string;
+    readonly executionId: string;
+    readonly mode: ExecutionMode;
+    readonly status: ExecutionStatus;
+    readonly outcome: ExecutionOutcome;
+    readonly executed: boolean;
+    readonly sourceHash?: string;
+}
+
+export interface CompatibilityReport {
+    readonly packages: PackageVerificationReport;
+    readonly capabilities: readonly CapabilityDescriptor[];
+    readonly methods: readonly MethodCompatibility[];
+    readonly sql: readonly SqlCompatibility[];
+    readonly issues: readonly CompatibilityIssue[];
+    /** Dynamic names, generated AML, branch coverage and external effects are not statically
+     * proven. */
+    readonly limitations: readonly string[];
+}

package/src/controls/clock.ts

@@ -0,0 +1,108 @@
+export interface ClockSettings {
+    readonly at: string;
+}
+
+export interface ClockControl {
+    now(): Date;
+    set(value: string | Date): void;
+    advance(milliseconds: number): void;
+}
+
+/** An immutable starting instant; each world owns its own clock. */
+export function fixedClock(value: string | Date): ClockSettings {
+    return Object.freeze({ at: new Date(instant(value)).toISOString() });
+}
+
+export function clockSettings(value: unknown): ClockSettings | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    if (
+        value === null ||
+        typeof value !== "object" ||
+        !("at" in value) ||
+        typeof value.at !== "string" ||
+        Object.keys(value).some((key) => key !== "at")
+    ) {
+        throw new TypeError("Harness clock must be configured with fixedClock().");
+    }
+
+    return fixedClock(value.at);
+}
+
+export class WorldClock {
+    private current: number | undefined;
+    private baseline: number | undefined;
+
+    constructor(settings?: ClockSettings) {
+        this.current = settings === undefined ? undefined : instant(settings.at);
+        this.baseline = this.current;
+    }
+
+    now(): Date {
+        return new Date(this.current ?? Date.now());
+    }
+
+    control(assertOpen: () => void, assertIdle: () => void): ClockControl {
+        return Object.freeze({
+            now: () => {
+                assertOpen();
+
+                return this.now();
+            },
+
+            set: (value: string | Date) => {
+                assertIdle();
+                this.current = instant(value);
+            },
+
+            advance: (milliseconds: number) => {
+                assertIdle();
+
+                if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) {
+                    throw new TypeError(
+                        "Clock advancement requires nonnegative integer milliseconds.",
+                    );
+                }
+
+                this.current = instant(new Date(this.now().getTime() + milliseconds));
+            },
+        });
+    }
+
+    checkpoint(): void {
+        this.baseline = this.current;
+    }
+
+    capture(): number | undefined {
+        return this.current;
+    }
+
+    restore(value: number | undefined): void {
+        this.current = value;
+        this.checkpoint();
+    }
+
+    reset(): void {
+        this.current = this.baseline;
+    }
+}
+
+function instant(value: string | Date): number {
+    if (typeof value !== "string" && !(value instanceof Date)) {
+        throw new TypeError("Clock instants must be strings or Dates.");
+    }
+
+    if (typeof value === "string" && !/(?:Z|[+-]\d{2}:\d{2})$/u.test(value)) {
+        throw new TypeError("Clock instants must include an explicit timezone.");
+    }
+
+    const milliseconds = value instanceof Date ? value.getTime() : Date.parse(value);
+
+    if (!Number.isFinite(milliseconds)) {
+        throw new TypeError("The clock requires a valid date.");
+    }
+
+    return milliseconds;
+}

package/src/controls/execution.ts

@@ -0,0 +1,53 @@
+import type { RuntimeObserver } from "../core/types.js";
+import type { ExecutionRecorder } from "../instrumentation/recorder.js";
+import type { HarnessStorage } from "../storage/types.js";
+import type { FailureRegistry } from "./failures.js";
+import type { ExecutionObservers } from "./observers.js";
+import { injectionTarget } from "./targets.js";
+
+/** Internal boundary hooks preserve the single request transaction for direct and nested calls. */
+export function executionObserver(
+    storage: HarnessStorage,
+    recorder: ExecutionRecorder,
+    failures: FailureRegistry,
+    observers: ExecutionObservers,
+): RuntimeObserver {
+    return {
+        started(execution, input) {
+            recorder.started(execution, input);
+
+            if (failures.hasRules) {
+                const target = injectionTarget(storage, execution.operation, input);
+
+                if (target) {
+                    failures.enter(execution, target);
+                }
+            }
+        },
+
+        completed(execution, result) {
+            recorder.completed(execution, result);
+            failures.complete(execution);
+        },
+
+        failed(execution, error) {
+            failures.failed(execution);
+            recorder.failed(execution, error);
+        },
+
+        settled(requestId, outcome, error) {
+            failures.settled(requestId);
+            recorder.settled(requestId, outcome, error);
+            const report = recorder.executions.at(-1);
+
+            if (report?.requestId === requestId) {
+                observers.notify(report);
+            }
+        },
+
+        reset() {
+            failures.reset();
+            recorder.reset();
+        },
+    };
+}

package/src/controls/failure-types.ts

@@ -0,0 +1,61 @@
+import type { SourceLocation } from "../diagnostics/source-location.js";
+import type { MockValue } from "../mocks/types.js";
+import type { ItemAction } from "../platform/actions.js";
+
+export enum FailurePoint {
+    BeforeCall = "BEFORE_CALL",
+    AfterCall = "AFTER_CALL",
+}
+
+type FailureTarget =
+    | {
+          readonly type: string;
+          readonly action: ItemAction;
+          readonly method?: never;
+          readonly sql?: never;
+      }
+    | {
+          readonly method: string;
+          readonly type?: never;
+          readonly action?: never;
+          readonly sql?: never;
+      }
+    | {
+          readonly sql: string | true;
+          readonly type?: never;
+          readonly action?: never;
+          readonly method?: never;
+      };
+
+export type FailureInjection = FailureTarget & {
+    readonly when?: Readonly<Record<string, MockValue>>;
+    readonly at?: FailurePoint;
+    readonly occurrence?: number;
+    readonly error: Error;
+};
+
+export interface InjectedFailureHandle extends Disposable {
+    readonly triggered: boolean;
+}
+
+export interface ExecutionInjection {
+    readonly id: string;
+    readonly executionId: string;
+    readonly name: string;
+    readonly at: FailurePoint;
+    readonly occurrence: number;
+    readonly source?: SourceLocation;
+    readonly error: { readonly name: string; readonly message: string };
+}
+
+export class InjectedFailureError extends Error {
+    override readonly name = "InjectedFailureError";
+    readonly code = "InjectedFailure";
+
+    constructor(
+        readonly injection: ExecutionInjection,
+        cause: Error,
+    ) {
+        super(injection.error.message, { cause });
+    }
+}

package/src/controls/failure-validation.ts

@@ -0,0 +1,99 @@
+import { cloneData, freezeData } from "../core/data.js";
+import { validateParameters } from "../mocks/parameters.js";
+import type { MockValue } from "../mocks/types.js";
+import { ItemAction } from "../platform/actions.js";
+import { FailurePoint } from "./failure-types.js";
+import type { FailureInjection } from "./failure-types.js";
+
+export interface FailureRule {
+    readonly target: {
+        readonly kind: "action" | "method" | "sql";
+        readonly name: string | true;
+        readonly action?: ItemAction;
+    };
+    readonly when: Readonly<Record<string, MockValue>>;
+    readonly at: FailurePoint;
+    readonly occurrence: number;
+    readonly error: Error;
+}
+
+export function prepareFailure(value: FailureInjection): FailureRule {
+    const allowed = new Set([
+        "type",
+        "action",
+        "method",
+        "sql",
+        "when",
+        "at",
+        "occurrence",
+        "error",
+    ]);
+
+    if (
+        value === null ||
+        typeof value !== "object" ||
+        Object.keys(value).some((key) => !allowed.has(key)) ||
+        !(value.error instanceof Error)
+    ) {
+        throw new TypeError("A failure injection needs a target and an Error.");
+    }
+
+    const at = value.at ?? FailurePoint.BeforeCall;
+    const occurrence = value.occurrence ?? 1;
+
+    if (
+        !Object.values(FailurePoint).includes(at) ||
+        !Number.isSafeInteger(occurrence) ||
+        occurrence < 1
+    ) {
+        throw new TypeError(
+            "Failure injection requires a valid point and positive integer occurrence.",
+        );
+    }
+
+    validateParameters(value.when ?? {}, "Failure injection 'when'");
+
+    return {
+        target: target(value),
+        at,
+        occurrence,
+        error: value.error,
+        when: freezeData(cloneData(value.when ?? {})),
+    };
+}
+
+function target(value: FailureInjection): FailureRule["target"] {
+    if (
+        nonempty(value.type) &&
+        value.action !== undefined &&
+        Object.values(ItemAction).includes(value.action) &&
+        value.method === undefined &&
+        value.sql === undefined
+    ) {
+        return { kind: "action", name: value.type, action: value.action };
+    }
+
+    if (
+        nonempty(value.method) &&
+        value.type === undefined &&
+        value.action === undefined &&
+        value.sql === undefined
+    ) {
+        return { kind: "method", name: value.method };
+    }
+
+    if (
+        (value.sql === true || nonempty(value.sql)) &&
+        value.type === undefined &&
+        value.action === undefined &&
+        value.method === undefined
+    ) {
+        return { kind: "sql", name: value.sql };
+    }
+
+    throw new TypeError("Select one failure target: an ItemType/action, a Method, or SQL.");
+}
+
+function nonempty(value: unknown): value is string {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/src/controls/failures.ts

@@ -0,0 +1,192 @@
+import { freezeData } from "../core/data.js";
+import type { RuntimeExecution } from "../core/types.js";
+import { matchesParameters } from "../mocks/registry.js";
+import { PlatformError } from "../platform/errors.js";
+import { FailurePoint, InjectedFailureError } from "./failure-types.js";
+import type {
+    ExecutionInjection,
+    FailureInjection,
+    InjectedFailureHandle,
+} from "./failure-types.js";
+import { prepareFailure } from "./failure-validation.js";
+import type { FailureRule } from "./failure-validation.js";
+import type { InjectionDetails, InjectionTarget } from "./targets.js";
+
+interface RegisteredRule {
+    readonly id: string;
+    readonly rule: FailureRule;
+    active: boolean;
+    triggered: boolean;
+    matches: number;
+}
+
+interface PendingInjection {
+    readonly requestId: string;
+    readonly target: InjectionDetails;
+    readonly rules: readonly RegisteredRule[];
+}
+
+const activeRulesMax = 128;
+const registrationsMax = 100_000;
+
+/** Rules count matching call entries. After-call faults run only if that invocation succeeds. */
+export class FailureRegistry {
+    private readonly rules = new Set<RegisteredRule>();
+    private readonly pending = new Map<string, PendingInjection>();
+    private serial = 0;
+
+    constructor(
+        private readonly record: (
+            execution: RuntimeExecution,
+            evidence: ExecutionInjection,
+            target: InjectionDetails,
+        ) => void,
+    ) {}
+
+    get hasRules(): boolean {
+        return this.rules.size > 0;
+    }
+
+    add(injection: FailureInjection): InjectedFailureHandle {
+        const rule = prepareFailure(injection);
+
+        if (this.rules.size >= activeRulesMax || this.serial >= registrationsMax) {
+            throw new RangeError("The world failure-injection limit was reached. Reset the world.");
+        }
+
+        const registered: RegisteredRule = {
+            id: String(++this.serial),
+            rule,
+            active: true,
+            triggered: false,
+            matches: 0,
+        };
+        this.rules.add(registered);
+
+        return Object.freeze({
+            get triggered() {
+                return registered.triggered;
+            },
+
+            [Symbol.dispose]: () => {
+                registered.active = false;
+                this.rules.delete(registered);
+            },
+        });
+    }
+
+    enter(execution: RuntimeExecution, target: InjectionTarget): void {
+        const selected: RegisteredRule[] = [];
+
+        for (const registered of this.rules) {
+            if (matches(registered.rule, target)) {
+                registered.matches += 1;
+
+                if (registered.matches === registered.rule.occurrence) {
+                    selected.push(registered);
+                }
+            }
+        }
+
+        const before = selected.filter((entry) => entry.rule.at === FailurePoint.BeforeCall);
+        this.trigger(execution, target, before);
+        const after = selected.filter((entry) => entry.rule.at === FailurePoint.AfterCall);
+
+        if (after.length > 0) {
+            const { values: _values, aliases: _aliases, action: _action, ...details } = target;
+            this.pending.set(execution.executionId, {
+                requestId: execution.requestId,
+                target: details,
+                rules: after,
+            });
+        }
+    }
+
+    complete(execution: RuntimeExecution): void {
+        const pending = this.pending.get(execution.executionId);
+        this.pending.delete(execution.executionId);
+
+        if (pending) {
+            this.trigger(
+                execution,
+                pending.target,
+                pending.rules.filter((rule) => rule.active),
+            );
+        }
+    }
+
+    failed(execution: RuntimeExecution): void {
+        this.pending.delete(execution.executionId);
+    }
+
+    settled(requestId: string): void {
+        for (const [id, pending] of this.pending) {
+            if (pending.requestId === requestId) {
+                this.pending.delete(id);
+            }
+        }
+    }
+
+    reset(): void {
+        for (const entry of this.rules) {
+            entry.active = false;
+        }
+
+        this.rules.clear();
+        this.pending.clear();
+        this.serial = 0;
+    }
+
+    private trigger(
+        execution: RuntimeExecution,
+        target: InjectionDetails,
+        selected: readonly RegisteredRule[],
+    ): void {
+        if (selected.length > 1) {
+            throw new PlatformError(
+                "AmbiguousInjection",
+                `Ambiguous failure injections at '${target.name}'. Narrow their targets.`,
+            );
+        }
+
+        const entry = selected[0];
+
+        if (!entry) {
+            return;
+        }
+
+        entry.triggered = true;
+        entry.active = false;
+        this.rules.delete(entry);
+        const evidence: ExecutionInjection = freezeData({
+            id: entry.id,
+            executionId: execution.executionId,
+            name: target.name,
+            at: entry.rule.at,
+            occurrence: entry.rule.occurrence,
+            ...(target.source ? { source: { ...target.source } } : {}),
+            error: {
+                name: entry.rule.error.name.slice(0, 128),
+                message: entry.rule.error.message.slice(0, 2048),
+            },
+        });
+        this.record(execution, evidence, target);
+
+        throw new InjectedFailureError(evidence, entry.rule.error);
+    }
+}
+
+function matches(rule: FailureRule, target: InjectionTarget): boolean {
+    return (
+        rule.target.kind === target.kind &&
+        (rule.target.action === undefined || rule.target.action === target.action) &&
+        target.aliases.some((name) => sameName(rule.target.name, name)) &&
+        matchesParameters(rule.when, target.values)
+    );
+}
+
+function sameName(left: string | true, right: string | true): boolean {
+    return typeof left === "string" && typeof right === "string"
+        ? left.toLowerCase() === right.toLowerCase()
+        : left === right;
+}