@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/validation-task-worker.js

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { createPlan, validate } from "./engine.js";
+import { openTaskStore, } from "./task-store.js";
+import { validationTasksOptionsSchema, validationTaskRequestSchema, } from "./validation-tasks-protocol.js";
+let store;
+let options;
+let initializing = false;
+let closing;
+let starting;
+let active;
+function send(message) {
+    if (!process.connected)
+        return;
+    try {
+        process.send(message, (failure) => {
+            if (failure)
+                disconnect();
+        });
+    }
+    catch {
+        disconnect();
+    }
+}
+function reply(id, value) {
+    send({ id, ok: true, value });
+}
+function error(id, code) {
+    send({ id, ok: false, error: code });
+}
+function planOptions() {
+    const value = options;
+    return {
+        ...(value.base !== undefined ? { base: value.base } : {}),
+        ...(value.policyOverlay !== undefined
+            ? { policyOverlay: value.policyOverlay }
+            : {}),
+        ...(value.environment !== undefined
+            ? { environment: value.environment }
+            : {}),
+        ...(value.externalAdapters !== undefined
+            ? { externalAdapters: value.externalAdapters }
+            : {}),
+    };
+}
+async function run(taskId, controller) {
+    try {
+        try {
+            const report = await validate(options.root, {
+                ...planOptions(),
+                trusted: true,
+                timeoutMs: options.timeoutMs,
+                signal: controller.signal,
+            });
+            if (!controller.signal.aborted)
+                store.complete(taskId, report);
+        }
+        catch {
+            if (!controller.signal.aborted)
+                store.interrupt(taskId);
+        }
+        if (controller.signal.aborted)
+            store.finishCancellation(taskId);
+    }
+    catch {
+        // Persistence failure must not release the execution slot as a successful task.
+        disconnect();
+    }
+    finally {
+        active = undefined;
+    }
+}
+async function start() {
+    const { plan } = await createPlan(options.root, planOptions());
+    if (closing)
+        throw new Error("closing");
+    const task = store.create(plan.sourceFingerprint);
+    const controller = new AbortController();
+    const done = new Promise((resolve) => {
+        setImmediate(() => {
+            void run(task.taskId, controller).finally(resolve);
+        });
+    });
+    active = { taskId: task.taskId, controller, done };
+    return task;
+}
+async function cancel(taskId) {
+    const task = store.get(taskId);
+    if (task.status !== "working")
+        return task;
+    if (active?.taskId !== taskId)
+        throw new Error("No active worker for task");
+    store.requestCancellation(taskId);
+    const running = active;
+    running.controller.abort();
+    await running.done;
+    return store.get(taskId);
+}
+async function shutdown() {
+    closing ??= (async () => {
+        await starting?.catch(() => { });
+        const running = active;
+        if (running) {
+            try {
+                store.requestCancellation(running.taskId);
+            }
+            finally {
+                running.controller.abort();
+                await running.done;
+            }
+        }
+        store?.close();
+    })();
+    return closing;
+}
+function disconnect() {
+    const release = () => {
+        try {
+            store?.close();
+        }
+        finally {
+            if (process.connected)
+                process.disconnect();
+        }
+    };
+    void shutdown().then(release, release);
+}
+process.on("disconnect", disconnect);
+process.on("SIGTERM", disconnect);
+process.on("SIGINT", disconnect);
+process.on("message", (message) => {
+    void (async () => {
+        if (!options) {
+            if (initializing) {
+                error(0, "busy");
+                return;
+            }
+            initializing = true;
+            try {
+                const initial = z
+                    .strictObject({ options: validationTasksOptionsSchema })
+                    .parse(message);
+                store = await openTaskStore(initial.options);
+                if (closing) {
+                    store.close();
+                    return;
+                }
+                options = initial.options;
+                reply(0, null);
+            }
+            catch {
+                error(0, "unavailable");
+                disconnect();
+            }
+            return;
+        }
+        const request = validationTaskRequestSchema.safeParse(message);
+        if (!request.success)
+            return;
+        const { id, method } = request.data;
+        if (closing) {
+            error(id, "closed");
+            return;
+        }
+        if (method === "close") {
+            try {
+                await shutdown();
+                reply(id, null);
+            }
+            finally {
+                if (process.connected)
+                    process.disconnect();
+            }
+            return;
+        }
+        if (method === "start") {
+            if (!options.allowExecution) {
+                error(id, "denied");
+                return;
+            }
+            if (starting || active) {
+                error(id, "busy");
+                return;
+            }
+            starting = start();
+            try {
+                reply(id, await starting);
+            }
+            catch {
+                error(id, "invalid");
+            }
+            finally {
+                starting = undefined;
+            }
+            return;
+        }
+        try {
+            reply(id, method === "get"
+                ? store.get(request.data.taskId)
+                : await cancel(request.data.taskId));
+        }
+        catch {
+            error(id, "invalid");
+        }
+    })().catch(disconnect);
+});

package/dist/src/validation-tasks-protocol.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+export declare const validationTasksOptionsSchema: z.ZodObject<{
+    root: z.ZodString;
+    directory: z.ZodString;
+    detailed: z.ZodDefault<z.ZodBoolean>;
+    allowExecution: z.ZodBoolean;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    base: z.ZodOptional<z.ZodString>;
+    policyOverlay: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodString>, z.ZodTransform<Record<string, string>, Record<string, string>>>>;
+    externalAdapters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ValidationTasksOptions = z.input<typeof validationTasksOptionsSchema>;
+export declare const validationTaskRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"start">;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"get">;
+    taskId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"cancel">;
+    taskId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"close">;
+}, z.core.$strict>], "method">;
+export declare const storedValidationTaskSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        working: "working";
+        completed: "completed";
+    }>;
+    createdAt: z.ZodISODateTime;
+    lastUpdatedAt: z.ZodISODateTime;
+    ttlMs: z.ZodNumber;
+    result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const validationTaskResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodNumber;
+    ok: z.ZodLiteral<true>;
+    value: z.ZodNullable<z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            working: "working";
+            completed: "completed";
+        }>;
+        createdAt: z.ZodISODateTime;
+        lastUpdatedAt: z.ZodISODateTime;
+        ttlMs: z.ZodNumber;
+        result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodNumber;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodEnum<{
+        unavailable: "unavailable";
+        invalid: "invalid";
+        denied: "denied";
+        busy: "busy";
+        closed: "closed";
+    }>;
+}, z.core.$strict>], "ok">;

package/dist/src/validation-tasks-protocol.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { externalReferencesSchema } from "./external-adapter.js";
+import { operatorEnvironment } from "./environment.js";
+export const validationTasksOptionsSchema = z.strictObject({
+    root: z.string().min(1).max(4096),
+    directory: z.string().min(1).max(4096),
+    detailed: z.boolean().default(false),
+    allowExecution: z.boolean(),
+    timeoutMs: z.number().int().min(1).max(120000).default(30000),
+    base: z.string().min(1).max(4096).optional(),
+    policyOverlay: z.string().min(1).max(4096).optional(),
+    environment: z
+        .record(z.string(), z.string())
+        .transform((value) => operatorEnvironment(value))
+        .optional(),
+    externalAdapters: externalReferencesSchema.optional(),
+});
+export const validationTaskRequestSchema = z.discriminatedUnion("method", [
+    z.strictObject({
+        id: z.number().int().positive(),
+        method: z.literal("start"),
+    }),
+    z.strictObject({
+        id: z.number().int().positive(),
+        method: z.literal("get"),
+        taskId: z.string().uuid(),
+    }),
+    z.strictObject({
+        id: z.number().int().positive(),
+        method: z.literal("cancel"),
+        taskId: z.string().uuid(),
+    }),
+    z.strictObject({
+        id: z.number().int().positive(),
+        method: z.literal("close"),
+    }),
+]);
+export const storedValidationTaskSchema = z.strictObject({
+    taskId: z.string().uuid(),
+    status: z.enum(["working", "completed", "cancelled"]),
+    createdAt: z.iso.datetime(),
+    lastUpdatedAt: z.iso.datetime(),
+    ttlMs: z.number().int().positive(),
+    result: z.record(z.string(), z.unknown()).optional(),
+});
+export const validationTaskResponseSchema = z.discriminatedUnion("ok", [
+    z.strictObject({
+        id: z.number().int().nonnegative(),
+        ok: z.literal(true),
+        value: storedValidationTaskSchema.nullable(),
+    }),
+    z.strictObject({
+        id: z.number().int().nonnegative(),
+        ok: z.literal(false),
+        error: z.enum(["unavailable", "denied", "busy", "invalid", "closed"]),
+    }),
+]);

package/dist/src/validation-tasks.d.ts

@@ -0,0 +1,11 @@
+import { type ValidationTasksOptions } from "./validation-tasks-protocol.js";
+import type { StoredValidationTask } from "./task-store.js";
+export type { ValidationTasksOptions } from "./validation-tasks-protocol.js";
+export interface ValidationTasks {
+    start(): Promise<StoredValidationTask>;
+    get(taskId: string): Promise<StoredValidationTask>;
+    cancel(taskId: string): Promise<StoredValidationTask>;
+    close(): Promise<void>;
+}
+/** Own a local validation worker and durable result store; no MCP transport is implied. */
+export declare function openValidationTasks(input: ValidationTasksOptions): Promise<ValidationTasks>;

package/dist/src/validation-tasks.js

@@ -0,0 +1,144 @@
+import { fork } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { validationTasksOptionsSchema, validationTaskRequestSchema, validationTaskResponseSchema, } from "./validation-tasks-protocol.js";
+/** Own a local validation worker and durable result store; no MCP transport is implied. */
+export async function openValidationTasks(input) {
+    const options = validationTasksOptionsSchema.parse(input);
+    options.root = await realpath(options.root);
+    options.directory = path.resolve(options.directory);
+    const environment = {};
+    for (const name of [
+        "PATH",
+        "HOME",
+        "TMPDIR",
+        "TMP",
+        "TEMP",
+        "LANG",
+        "LC_ALL",
+    ])
+        if (process.env[name] !== undefined)
+            environment[name] = process.env[name];
+    const child = fork(new URL("./validation-task-worker.js", import.meta.url), [], {
+        execArgv: [],
+        env: environment,
+        stdio: ["ignore", "ignore", "ignore", "ipc"],
+    });
+    let sequence = 0;
+    let closed = false;
+    let closing;
+    const pending = new Map();
+    function fail() {
+        closed = true;
+        for (const entry of pending.values())
+            entry.reject(new Error("Validation task worker unavailable"));
+        pending.clear();
+    }
+    const exited = new Promise((resolve) => {
+        const finish = () => {
+            fail();
+            resolve();
+        };
+        // With ignored streams, exit is sufficient; concurrent IPC disconnects can omit close.
+        child.once("exit", finish);
+        child.once("close", finish);
+        child.on("error", () => {
+            fail();
+            if (!child.pid)
+                resolve();
+        });
+    });
+    child.on("message", (message) => {
+        const result = validationTaskResponseSchema.safeParse(message);
+        if (!result.success) {
+            fail();
+            if (child.connected)
+                child.disconnect();
+            return;
+        }
+        const entry = pending.get(result.data.id);
+        if (!entry)
+            return;
+        pending.delete(result.data.id);
+        if (result.data.ok) {
+            const value = result.data.value;
+            if (value) {
+                const { result: payload, ...metadata } = value;
+                entry.resolve({
+                    ...metadata,
+                    ...(payload !== undefined ? { result: payload } : {}),
+                });
+            }
+            else
+                entry.resolve(null);
+        }
+        else
+            entry.reject(new Error(`Validation task request ${result.data.error}`));
+    });
+    async function send(id, message) {
+        if (closed || !child.connected)
+            throw new Error("Validation task worker is closed");
+        if (pending.size >= 32)
+            throw new Error("Too many pending validation task requests");
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject });
+            child.send(message, (error) => {
+                if (error) {
+                    pending.delete(id);
+                    reject(new Error("Validation task request could not be delivered"));
+                }
+            });
+        });
+    }
+    const startupTimer = setTimeout(() => {
+        fail();
+        child.kill("SIGKILL");
+    }, 10000);
+    try {
+        await send(0, { options });
+    }
+    catch (error) {
+        if (child.connected)
+            child.disconnect();
+        await exited;
+        throw error;
+    }
+    finally {
+        clearTimeout(startupTimer);
+    }
+    async function request(method, taskId) {
+        if (closing)
+            throw new Error("Validation task worker is closing");
+        const id = ++sequence;
+        const message = validationTaskRequestSchema.parse({
+            id,
+            method,
+            ...(taskId !== undefined ? { taskId } : {}),
+        });
+        const result = await send(id, message);
+        if (!result)
+            throw new Error("Validation task response is missing");
+        return result;
+    }
+    return {
+        start: () => request("start"),
+        get: (taskId) => request("get", taskId),
+        cancel: (taskId) => request("cancel", taskId),
+        close: () => {
+            closing ??= (async () => {
+                try {
+                    if (!closed && child.connected) {
+                        const id = ++sequence;
+                        await send(id, { id, method: "close" });
+                    }
+                }
+                finally {
+                    if (child.connected)
+                        child.disconnect();
+                    await exited;
+                }
+            })();
+            return closing;
+        },
+    };
+}

package/dist/src/vitest-evidence.d.ts

@@ -0,0 +1,2 @@
+import type { Check, CheckResult, ProcessResult } from "./types.js";
+export declare function vitestEvidence(check: Check, processes: ProcessResult[], root: string | undefined): Pick<CheckResult, "status" | "reason" | "tests">;

package/dist/src/vitest-evidence.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { z } from "zod";
+const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const schema = z.object({
+    success: z.boolean(),
+    numTotalTests: count,
+    numPassedTests: count,
+    numFailedTests: count,
+    numPendingTests: count,
+    numTodoTests: count,
+    numTotalTestSuites: count,
+    numPassedTestSuites: count,
+    numFailedTestSuites: count,
+    numPendingTestSuites: count,
+    testResults: z.array(z.object({
+        name: z.string(),
+        status: z.enum(["passed", "failed"]),
+        assertionResults: z.array(z.object({
+            status: z.enum([
+                "passed",
+                "failed",
+                "skipped",
+                "pending",
+                "todo",
+                "disabled",
+            ]),
+            fullName: z.string(),
+        })),
+    })),
+});
+export function vitestEvidence(check, processes, root) {
+    const incomplete = {
+        status: "inconclusive",
+        reason: "Vitest evidence is incomplete, inconsistent, or does not account for every planned test file.",
+    };
+    if (!root || processes.length !== 1 || !check.scope.length)
+        return incomplete;
+    const process = processes[0];
+    if (process.exitCode !== 0 && process.exitCode !== 1)
+        return {
+            status: "error",
+            reason: "Vitest could not start or complete normally; inspect the runtime and configuration.",
+        };
+    let report;
+    try {
+        report = schema.parse(JSON.parse(process.stdout));
+    }
+    catch {
+        return incomplete;
+    }
+    const expected = new Set(check.scope.map((file) => path.resolve(root, check.project, file)));
+    const seen = new Set();
+    const tests = { total: 0, passed: 0, failed: 0, skipped: 0 };
+    let pending = 0;
+    let todo = 0;
+    let failedFiles = false;
+    for (const file of report.testResults) {
+        if (!expected.has(file.name) || seen.has(file.name))
+            return incomplete;
+        seen.add(file.name);
+        failedFiles ||= file.status === "failed";
+        for (const assertion of file.assertionResults) {
+            if (assertion.status === "pending")
+                return incomplete;
+            tests.total++;
+            if (assertion.status === "passed")
+                tests.passed++;
+            else if (assertion.status === "failed")
+                tests.failed++;
+            else {
+                tests.skipped++;
+                if (assertion.status === "todo")
+                    todo++;
+                else
+                    pending++;
+            }
+        }
+    }
+    if (seen.size !== expected.size ||
+        tests.total !== report.numTotalTests ||
+        tests.passed !== report.numPassedTests ||
+        tests.failed !== report.numFailedTests ||
+        pending !== report.numPendingTests ||
+        todo !== report.numTodoTests ||
+        report.numTotalTestSuites !==
+            report.numPassedTestSuites +
+                report.numFailedTestSuites +
+                report.numPendingTestSuites ||
+        report.numPendingTestSuites > 0)
+        return incomplete;
+    if (tests.failed ||
+        failedFiles ||
+        report.numFailedTestSuites ||
+        !report.success ||
+        process.exitCode !== 0)
+        return {
+            status: "failed",
+            reason: "Vitest reported a test, suite, or execution failure.",
+            tests,
+        };
+    if (!tests.passed)
+        return {
+            ...incomplete,
+            reason: "No passing, non-skipped Vitest assertions were observed.",
+            tests,
+        };
+    return {
+        status: "passed",
+        reason: "Vitest accounted for every planned file and reported passing non-skipped assertions.",
+        tests,
+    };
+}

package/dist/src/vitest-runner.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/vitest-runner.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { withinRoot } from "./inventory.js";
+async function main() {
+    const [entry, root, ...files] = process.argv.slice(2);
+    if (!entry || !root || !files.length)
+        throw new Error("Invalid Vitest runner arguments");
+    const tool = await withinRoot(root, path.relative(root, entry));
+    const { startVitest, JsonReporter, VitestPackageInstaller } = (await import(pathToFileURL(tool).href));
+    class InstalledOnly extends VitestPackageInstaller {
+        async ensureInstalled(dependency, cwd) {
+            if (!this.isPackageExists(dependency, { paths: [cwd] }))
+                throw new Error(`Install required Vitest dependency locally: ${dependency}`);
+            return true;
+        }
+    }
+    const filters = [];
+    for (const file of files)
+        filters.push(await withinRoot(root, path.relative(root, path.resolve(file))));
+    const ctx = await startVitest(filters, {
+        root: process.cwd(),
+        run: true,
+        watch: false,
+        update: "none",
+        allowOnly: false,
+        passWithNoTests: false,
+        dangerouslyIgnoreUnhandledErrors: false,
+        onUnhandledError: () => true,
+        cache: false,
+        fsModuleCache: false,
+        reporters: [new JsonReporter({ stdout: true, outputFile: "" })],
+    }, undefined, { packageInstaller: new InstalledOnly() });
+    const errors = ctx.state.getUnhandledErrors();
+    if (errors.length) {
+        process.exitCode = 1;
+        for (const error of errors) {
+            const message = typeof error === "object" && error !== null && "message" in error
+                ? String(error.message)
+                : String(error);
+            process.stderr.write(`Unhandled Vitest error: ${message}\n`);
+        }
+    }
+    await ctx.close();
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : "Vitest execution failed"}\n`);
+    process.exitCode = 2;
+});

package/dist/src/vitest.d.ts

@@ -0,0 +1,2 @@
+import type { Check, Inventory, Project } from "./types.js";
+export declare function vitestCheck(source: Inventory, project: Project): Promise<Check>;

package/dist/src/vitest.js

@@ -0,0 +1,36 @@
+import { fileURLToPath } from "node:url";
+import { localTool } from "./local-tool.js";
+export async function vitestCheck(source, project) {
+    const files = project.files.filter((file) => /\.(?:test|spec)\.(?:[cm]?[jt]s|[jt]sx)$/.test(file));
+    const tool = await localTool(source.root, project.path, "vitest/dist/node.js");
+    const check = {
+        id: "javascript.vitest",
+        adapter: project.adapter,
+        project: project.path,
+        scope: files,
+        kind: "test",
+        parser: "vitest-json",
+        reason: "Run installed Vitest once and account for every planned test file; require passing non-skipped assertions and consistent native JSON evidence.",
+        commands: tool
+            ? [
+                {
+                    executable: process.execPath,
+                    args: [
+                        fileURLToPath(new URL("./vitest-runner.js", import.meta.url)),
+                        tool,
+                        source.root,
+                        ...files,
+                    ],
+                    cwd: project.path,
+                    env: { CI: "1" },
+                },
+            ]
+            : [],
+    };
+    if (!files.length)
+        check.unavailableReason = "No .test or .spec JS/TS files were inventoried.";
+    else if (!tool)
+        check.unavailableReason =
+            "Vitest is not installed within the configured root.";
+    return check;
+}