@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/compatibility/executors.ts

@@ -0,0 +1,180 @@
+import { stat } from "node:fs/promises";
+
+import { errorMessage } from "../core/errors.js";
+import { readProcessOutput } from "../core/process.js";
+import type { PackageConfiguration } from "../harness/configuration.js";
+import { resolveCSharpOptions } from "../harness/configuration.js";
+import { CSharpCompiler } from "../methods/csharp/compiler.js";
+import type { MethodDefinition } from "../methods/types.js";
+import { PlatformError } from "../platform/errors.js";
+import type { CatalogEntry } from "../storage/types.js";
+import { CompilationStatus, ExecutorStatus } from "./types.js";
+import type { CompilationCheck, ExecutorCheck } from "./types.js";
+
+/** Checks dependencies lazily; neither the managed worker nor consumer extension factories
+ * start. */
+export class ExecutorInspection {
+    private environment: Promise<ExecutorCheck> | undefined;
+    private host: Promise<string> | undefined;
+    private readonly compiler: CSharpCompiler;
+    private readonly compiled = new Map<string, Promise<CompilationCheck>>();
+
+    constructor(
+        private readonly configuration: PackageConfiguration,
+        private readonly bindings: readonly CatalogEntry[] = [],
+    ) {
+        this.compiler = new CSharpCompiler(resolveCSharpOptions(configuration));
+    }
+
+    async executor(language: string | undefined, needed: boolean): Promise<ExecutorCheck> {
+        const extensions = (this.configuration.settings.executors?.length ?? 0) > 0;
+
+        if (language?.toLowerCase() !== "c#") {
+            return Object.freeze({
+                status: extensions ? ExecutorStatus.Unknown : ExecutorStatus.Missing,
+                message: extensions
+                    ? "Custom executor factories require runtime inspection; they are not constructed by preflight."
+                    : `No built-in '${language ?? "unspecified"}' executor.`,
+            });
+        }
+
+        if (this.configuration.settings.csharp === false) {
+            return Object.freeze({
+                status: extensions ? ExecutorStatus.Unknown : ExecutorStatus.Disabled,
+                message: "The built-in C# executor is disabled.",
+            });
+        }
+
+        if (!needed) {
+            return Object.freeze({
+                status: ExecutorStatus.Unknown,
+                message:
+                    "C# is configured; dependency probes are skipped for unconditionally mocked source.",
+            });
+        }
+
+        this.environment ??= this.probe();
+
+        return await this.environment;
+    }
+
+    compile(method: MethodDefinition): Promise<CompilationCheck> {
+        const key = `${method.id}:${method.hash}`;
+        let result = this.compiled.get(key);
+
+        if (!result) {
+            result = this.compileMethod(method);
+            this.compiled.set(key, result);
+        }
+
+        return result;
+    }
+
+    private async probe(): Promise<ExecutorCheck> {
+        const missing: string[] = [];
+
+        for (const reference of this.compiler.references) {
+            try {
+                if (!(await stat(reference)).isFile()) {
+                    missing.push(reference);
+                    continue;
+                }
+
+                await Bun.file(reference).slice(0, 1).bytes();
+            } catch {
+                missing.push(reference);
+            }
+        }
+
+        if (missing.length > 0) {
+            return Object.freeze({
+                status: ExecutorStatus.Unavailable,
+                message: `Missing or unreadable configured C# assemblies: ${missing.join(", ")}.`,
+            });
+        }
+
+        try {
+            const process = Bun.spawn([this.compiler.dotnet, "--list-sdks"], {
+                stdin: "ignore",
+                stdout: "pipe",
+                stderr: "pipe",
+                timeout: 5000,
+            });
+            const [exitCode, stdout, stderr] = await Promise.all([
+                process.exited,
+                readProcessOutput(process.stdout),
+                readProcessOutput(process.stderr),
+            ]);
+
+            if (exitCode !== 0 || !/^10\.\d+\.\d+/m.test(stdout)) {
+                return Object.freeze({
+                    status: ExecutorStatus.Unavailable,
+                    message: `The C# executor requires the .NET 10 SDK. ${stderr.trim()}`.trim(),
+                });
+            }
+
+            return Object.freeze({ status: ExecutorStatus.Available });
+        } catch (error) {
+            return Object.freeze({
+                status: ExecutorStatus.Unavailable,
+                message: `Cannot inspect the .NET 10 SDK: ${errorMessage(error)}`,
+            });
+        }
+    }
+
+    private async compileMethod(method: MethodDefinition): Promise<CompilationCheck> {
+        try {
+            this.host ??= this.compiler.host();
+            const events = this.eventContexts(method);
+
+            for (const event of events) {
+                await this.compiler.method(method, await this.host, event);
+            }
+
+            return Object.freeze({ status: CompilationStatus.Compiled, sourceHash: method.hash });
+        } catch (error) {
+            const inputChanged =
+                error instanceof Error &&
+                "code" in error &&
+                ["ENOENT", "EACCES", "EISDIR", "ENOTDIR"].includes(String(error.code));
+
+            if (!(error instanceof PlatformError) && !inputChanged) {
+                throw error;
+            }
+
+            return Object.freeze({
+                status: CompilationStatus.Failed,
+                sourceHash: method.hash,
+                message: errorMessage(error),
+            });
+        }
+    }
+
+    private eventContexts(method: MethodDefinition): readonly (string | undefined)[] {
+        const supported = new Set([
+            "onget",
+            "onadd",
+            "onupdate",
+            "ondelete",
+            "onlock",
+            "onunlock",
+            "onpromote",
+            "onbeforeupdate",
+            "onafteradd",
+            "onafterupdate",
+            "onafterversion",
+        ]);
+        const contexts = new Set<string | undefined>();
+
+        for (const binding of this.bindings) {
+            if (String(binding.properties.related_id).toLowerCase() !== method.id.toLowerCase()) {
+                continue;
+            }
+
+            const name = String(binding.properties.server_event);
+            contexts.add(supported.has(name.toLowerCase()) ? name : undefined);
+        }
+
+        return contexts.size > 0 ? [...contexts] : [undefined];
+    }
+}

package/src/compatibility/index.ts

@@ -0,0 +1,22 @@
+export { checkCompatibility } from "./check.js";
+export { CapabilityId, CapabilitySupport } from "./capabilities.js";
+export type { CapabilityDescriptor } from "./capabilities.js";
+export {
+    CompatibilityIssueCode,
+    IssueSeverity,
+    ExecutorStatus,
+    MockCoverage,
+    CompilationStatus,
+} from "./types.js";
+export type {
+    CompatibilityOptions,
+    CompatibilityReport,
+    CompatibilityIssue,
+    MethodCompatibility,
+    SqlCompatibility,
+    ExecutorCheck,
+    MockCheck,
+    MockRuleDescription,
+    CompilationCheck,
+    SourceExecutionObservation,
+} from "./types.js";

package/src/compatibility/metadata.ts

@@ -0,0 +1,219 @@
+import { dataNodesMax } from "../core/limits.js";
+import type { HarnessConfig } from "../harness/configuration.js";
+import { PlatformError } from "../platform/errors.js";
+import { EventBindings } from "../platform/events/bindings.js";
+import { ServerEventVersion } from "../platform/events/types.js";
+import { eventVersion } from "../platform/events/version.js";
+import type { CatalogEntry, HarnessStorage } from "../storage/types.js";
+import { CapabilityId, capabilityForError } from "./capabilities.js";
+import { inspectRevisions } from "./revisions.js";
+import { inspectSecurity } from "./security.js";
+import { CompatibilityIssueCode, IssueSeverity } from "./types.js";
+import type { CompatibilityIssue } from "./types.js";
+
+/** Metadata requirements only: presence identifies a boundary, not proof it will be exercised. */
+export function inspectMetadata(
+    storage: HarnessStorage,
+    files: ReadonlySet<string>,
+    settings: HarnessConfig,
+): readonly CompatibilityIssue[] {
+    const issues: CompatibilityIssue[] = [];
+    const entries = storage.listCatalogEntries().filter((entry) => files.has(entry.source.file));
+    const eventOrder = new Map<string, CatalogEntry>();
+
+    for (const entry of entries) {
+        const properties = entry.properties;
+        const type = entry.type.toLowerCase();
+        inspectServerEvent(entry, eventOrder, issues);
+
+        if (
+            type === "life cycle transition" &&
+            Boolean(properties.post_action) &&
+            String(properties.execute_post_in_main_txn ?? "0") !== "1"
+        ) {
+            unsupported(
+                issues,
+                entry,
+                "UnsupportedPostTransactionMethod",
+                "This transition runs a post Method outside the main transaction, which is unavailable.",
+            );
+        }
+
+        if (type === "life cycle state" && Boolean(properties.workflow)) {
+            unsupported(
+                issues,
+                entry,
+                "UnsupportedWorkflow",
+                `State '${properties.name}' starts a workflow, which requires an adapter.`,
+            );
+        }
+
+        inspectItemType(entry, issues);
+        const restrictedMethod = type === "method" && Boolean(properties.execution_allowed_to);
+        const restrictedTransition = type === "life cycle transition" && Boolean(properties.role);
+
+        if ((restrictedMethod || restrictedTransition) && settings.authorization === undefined) {
+            issues.push(
+                Object.freeze({
+                    code: CompatibilityIssueCode.AuthorizationRequired,
+                    severity: IssueSeverity.Warning,
+                    capability: CapabilityId.NativePermissions,
+                    causeCode: "AuthorizationRequired",
+                    message: `Restricted ${entry.type} '${properties.name ?? entry.id}' requires an explicit authorization policy or unchecked execution.`,
+                    source: entry.source,
+                }),
+            );
+        }
+    }
+
+    inspectInheritedEvents(storage, entries, issues);
+
+    return [
+        ...issues,
+        ...inspectRevisions(storage, files),
+        ...inspectSecurity(entries, settings.authorization),
+    ];
+}
+
+function inspectServerEvent(
+    entry: CatalogEntry,
+    eventOrder: Map<string, CatalogEntry>,
+    issues: CompatibilityIssue[],
+): void {
+    const properties = entry.properties;
+    const type = entry.type.toLowerCase();
+
+    if (type === "server event") {
+        const name = String(properties.server_event ?? "");
+        const version = String(properties.event_version ?? "version_1");
+
+        if (name.toLowerCase() === "onafterresetlifecycle") {
+            unsupported(
+                issues,
+                entry,
+                "UnsupportedLifecycleResetEvent",
+                "Lifecycle reset callbacks require native reset event metadata, which is unavailable.",
+            );
+        }
+
+        try {
+            eventVersion(name, properties.event_version, entry.source);
+        } catch (error) {
+            if (!(error instanceof PlatformError)) {
+                throw error;
+            }
+
+            unsupported(issues, entry, error.code, error.message);
+        }
+
+        const owner = String(properties.source_id).toLowerCase();
+        const order = Number(properties.sort_order ?? 0);
+        const key = `${owner}:${name.toLowerCase()}:${version}:${order}`;
+
+        if (eventOrder.has(key)) {
+            unsupported(
+                issues,
+                entry,
+                "AmbiguousEventOrder",
+                `Events for '${name}' share sort_order '${properties.sort_order ?? 0}'; runtime rejects tied ordering.`,
+            );
+        } else {
+            eventOrder.set(key, entry);
+        }
+    }
+}
+
+function inspectItemType(entry: CatalogEntry, issues: CompatibilityIssue[]): void {
+    const properties = entry.properties;
+    const type = entry.type.toLowerCase();
+
+    if (type === "itemtype") {
+        const implementation = properties.implementation_type;
+
+        if (Boolean(implementation) && implementation !== "table") {
+            const capability =
+                String(implementation).toLowerCase() === "polymorphic"
+                    ? CapabilityId.Polymorphism
+                    : CapabilityId.Federation;
+            unsupported(
+                issues,
+                entry,
+                "UnsupportedImplementation",
+                `ItemType '${properties.name}' uses '${implementation}' storage; its metadata can import but runtime queries require an adapter.`,
+                capability,
+            );
+        }
+    }
+}
+
+function unsupported(
+    issues: CompatibilityIssue[],
+    entry: CatalogEntry,
+    causeCode: string,
+    message: string,
+    capability = capabilityForError(causeCode),
+): void {
+    issues.push(
+        Object.freeze({
+            code: CompatibilityIssueCode.UnsupportedCapability,
+            severity: IssueSeverity.Warning,
+            causeCode,
+            message,
+            source: entry.source,
+            ...(capability !== undefined ? { capability } : {}),
+        }),
+    );
+}
+
+function inspectInheritedEvents(
+    storage: HarnessStorage,
+    entries: readonly CatalogEntry[],
+    issues: CompatibilityIssue[],
+): void {
+    const bindings = new EventBindings(storage);
+    const related = new Set(
+        storage
+            .listCatalogEntries("Morphae")
+            .map((entry) => String(entry.properties.related_id).toLowerCase()),
+    );
+    const types = storage.listItemTypes().filter((type) => related.has(type.id.toLowerCase()));
+    const names = new Set(
+        entries
+            .filter((entry) => entry.type === "Server Event")
+            .map((entry) => String(entry.properties.server_event)),
+    );
+
+    if (types.length * names.size > dataNodesMax) {
+        throw new PlatformError(
+            "ProtocolLimit",
+            "Inherited event inspection exceeds its work budget.",
+        );
+    }
+
+    for (const type of types) {
+        for (const name of names) {
+            for (const version of Object.values(ServerEventVersion)) {
+                try {
+                    bindings.select(type, name, true, version);
+                } catch (error) {
+                    if (!(error instanceof PlatformError)) {
+                        throw error;
+                    }
+
+                    issues.push(
+                        Object.freeze({
+                            code: CompatibilityIssueCode.UnsupportedCapability,
+                            severity: IssueSeverity.Warning,
+                            causeCode: error.code,
+                            message: error.message,
+                            ...(error.capability !== undefined
+                                ? { capability: error.capability }
+                                : {}),
+                            ...(error.source ? { source: error.source } : {}),
+                        }),
+                    );
+                }
+            }
+        }
+    }
+}

package/src/compatibility/mocks.ts

@@ -0,0 +1,32 @@
+import type { MockRegistry } from "../mocks/registry.js";
+import { MockCoverage } from "./types.js";
+import type { MockCheck } from "./types.js";
+
+export function checkMocks(
+    registry: MockRegistry | undefined,
+    kind: "method" | "sql",
+    names: readonly string[],
+): MockCheck {
+    if (!registry) {
+        return Object.freeze({ coverage: MockCoverage.Unknown, rules: Object.freeze([]) });
+    }
+
+    const rules = registry.describe(kind, names);
+    const unconditional = rules.filter((rule) => Object.keys(rule.when).length === 0);
+    let coverage = MockCoverage.None;
+
+    if (unconditional.length > 0) {
+        let highestLayer = -Infinity;
+
+        for (const rule of unconditional) {
+            highestLayer = Math.max(highestLayer, rule.layer);
+        }
+
+        const winners = unconditional.filter((rule) => rule.layer === highestLayer);
+        coverage = winners.length > 1 ? MockCoverage.Ambiguous : MockCoverage.Unconditional;
+    } else if (rules.length > 0) {
+        coverage = MockCoverage.Conditional;
+    }
+
+    return Object.freeze({ coverage, rules });
+}

package/src/compatibility/revisions.ts

@@ -0,0 +1,45 @@
+import { PlatformError } from "../platform/errors.js";
+import { RevisionSequences } from "../platform/revisions/sequences.js";
+import type { HarnessStorage } from "../storage/types.js";
+import { CapabilityId } from "./capabilities.js";
+import { CompatibilityIssueCode, IssueSeverity } from "./types.js";
+import type { CompatibilityIssue } from "./types.js";
+
+/** Sequence validation shares the runtime resolver and never executes business Methods. */
+export function inspectRevisions(
+    storage: HarnessStorage,
+    files: ReadonlySet<string>,
+): readonly CompatibilityIssue[] {
+    const sequences = new RevisionSequences(storage);
+    const issues = new Map<string, CompatibilityIssue>();
+
+    for (const definition of storage.listItemTypes()) {
+        if (!definition.isVersionable || !definition.source || !files.has(definition.source.file)) {
+            continue;
+        }
+
+        try {
+            sequences.resolve(definition);
+        } catch (error) {
+            if (!(error instanceof PlatformError)) {
+                throw error;
+            }
+
+            const source = error.source ?? definition.source;
+            const key = `${error.code}:${source.file}:${source.path}`;
+            issues.set(
+                key,
+                Object.freeze({
+                    code: CompatibilityIssueCode.InvalidDefinition,
+                    severity: IssueSeverity.Error,
+                    capability: CapabilityId.Revision,
+                    causeCode: error.code,
+                    message: error.message,
+                    source,
+                }),
+            );
+        }
+    }
+
+    return [...issues.values()];
+}

package/src/compatibility/security.ts

@@ -0,0 +1,102 @@
+import { PlatformError } from "../platform/errors.js";
+import { sourceAccessEnabled } from "../platform/security/source-access.js";
+import { AuthorizationMode } from "../platform/security/types.js";
+import type { AuthorizationPolicy } from "../platform/security/types.js";
+import type { CatalogEntry } from "../storage/types.js";
+import { CapabilityId } from "./capabilities.js";
+import { CompatibilityIssueCode, IssueSeverity } from "./types.js";
+import type { CompatibilityIssue } from "./types.js";
+
+/** Report known metadata gaps without pretending to evaluate unexercised business paths. */
+export function inspectSecurity(
+    entries: readonly CatalogEntry[],
+    authorization: AuthorizationPolicy | undefined,
+): readonly CompatibilityIssue[] {
+    if (authorization === AuthorizationMode.Unchecked) {
+        return [
+            Object.freeze({
+                code: CompatibilityIssueCode.UnsupportedCapability,
+                severity: IssueSeverity.Information,
+                capability: CapabilityId.NativePermissions,
+                message:
+                    "Authorization is explicitly unchecked; these tests do not validate native permission rules.",
+            }),
+        ];
+    }
+
+    if (authorization !== AuthorizationMode.Native) {
+        return [];
+    }
+
+    const issues: CompatibilityIssue[] = [];
+
+    for (const entry of entries) {
+        const sourceAccess = inspectSourceAccess(entry, entries);
+
+        if (sourceAccess) {
+            issues.push(sourceAccess);
+        }
+    }
+
+    return issues;
+}
+
+function inspectSourceAccess(
+    entry: CatalogEntry,
+    entries: readonly CatalogEntry[],
+): CompatibilityIssue | undefined {
+    if (entry.type !== "ItemType") {
+        return undefined;
+    }
+
+    try {
+        const enabled = sourceAccessEnabled(
+            {
+                name: String(entry.properties.name),
+                isRelationship: String(entry.properties.is_relationship) === "1",
+                source: entry.source,
+            },
+            entry.properties.use_src_access,
+        );
+
+        if (!enabled) {
+            return undefined;
+        }
+    } catch (error) {
+        if (!(error instanceof PlatformError)) {
+            throw error;
+        }
+
+        const invalid = error.code === "InvalidSourceAccess";
+
+        return Object.freeze({
+            code: invalid
+                ? CompatibilityIssueCode.InvalidDefinition
+                : CompatibilityIssueCode.UnsupportedCapability,
+            severity: invalid ? IssueSeverity.Error : IssueSeverity.Warning,
+            capability: CapabilityId.NativePermissions,
+            causeCode: error.code,
+            message: error.message,
+            source: entry.source,
+        });
+    }
+
+    const relationship = entries.find(
+        (candidate) =>
+            candidate.type === "RelationshipType" &&
+            String(candidate.properties.relationship_id).toLowerCase() === entry.id.toLowerCase(),
+    );
+
+    if (relationship && String(relationship.properties.source_id ?? "") === "") {
+        return Object.freeze({
+            code: CompatibilityIssueCode.UnsupportedCapability,
+            severity: IssueSeverity.Warning,
+            capability: CapabilityId.NativePermissions,
+            causeCode: "UnsupportedSourceAccess",
+            message: `Source access on '${entry.properties.name}' requires for_all source-type resolution, which is not implemented.`,
+            source: entry.source,
+        });
+    }
+
+    return undefined;
+}

package/src/compatibility/sources.ts

@@ -0,0 +1,38 @@
+import type { CatalogEntry, HarnessStorage } from "../storage/types.js";
+import type { PackageMethodDeclaration, PackageSqlDeclaration } from "../verification/types.js";
+
+/** Resolve declarations against the actual imported catalog, including patches and generated
+ * IDs. */
+export function resolveDeclaration(
+    storage: HarnessStorage,
+    type: "Method" | "SQL",
+    declaration: PackageMethodDeclaration | PackageSqlDeclaration,
+): CatalogEntry | undefined {
+    const entries = storage.listCatalogEntries(type);
+
+    if (declaration.id) {
+        return entries.find((entry) => entry.id.toLowerCase() === declaration.id?.toLowerCase());
+    }
+
+    const sameSource = entries.find(
+        (entry) =>
+            entry.source.file === declaration.source.file &&
+            entry.source.path === declaration.source.path,
+    );
+
+    if (sameSource) {
+        return sameSource;
+    }
+
+    const sameName = entries.filter(
+        (entry) =>
+            typeof entry.properties.name === "string" &&
+            entry.properties.name.toLowerCase() === declaration.name?.toLowerCase(),
+    );
+
+    if (sameName.length === 1) {
+        return sameName[0];
+    }
+
+    return undefined;
+}