@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/runtime-inventory.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+export declare const runtimeInventorySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    format: z.ZodLiteral<"runtime-inventory">;
+    producer: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    assembly: z.ZodObject<{
+        name: z.ZodString;
+        environment: z.ZodString;
+    }, z.core.$strict>;
+    sourceFingerprint: z.ZodString;
+    capturedAt: z.ZodISODateTime;
+    collections: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            routes: "routes";
+            listeners: "listeners";
+            middleware: "middleware";
+            schedules: "schedules";
+            bindings: "bindings";
+        }>;
+        complete: z.ZodBoolean;
+        ordered: z.ZodBoolean;
+        entries: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            attributes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodString>]>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RuntimeInventory = z.infer<typeof runtimeInventorySchema>;
+export declare const runtimeComparisonSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    engineVersion: z.ZodString;
+    provenance: z.ZodLiteral<"imported-runtime-comparison">;
+    outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    reason: z.ZodString;
+    beforeFingerprint: z.ZodString;
+    afterFingerprint: z.ZodString;
+    counts: z.ZodObject<{
+        collections: z.ZodNumber;
+        compared: z.ZodNumber;
+        unverified: z.ZodNumber;
+        changed: z.ZodNumber;
+        added: z.ZodNumber;
+        removed: z.ZodNumber;
+    }, z.core.$strict>;
+    collections: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            routes: "routes";
+            listeners: "listeners";
+            middleware: "middleware";
+            schedules: "schedules";
+            bindings: "bindings";
+        }>;
+        status: z.ZodEnum<{
+            unverified: "unverified";
+            changed: "changed";
+            unchanged: "unchanged";
+        }>;
+        beforeCount: z.ZodNumber;
+        afterCount: z.ZodNumber;
+        added: z.ZodNumber;
+        removed: z.ZodNumber;
+        orderChanged: z.ZodBoolean;
+        changedKeys: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const runtimeComparisonSummarySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    engineVersion: z.ZodString;
+    provenance: z.ZodLiteral<"imported-runtime-comparison">;
+    outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    reason: z.ZodString;
+    beforeFingerprint: z.ZodString;
+    afterFingerprint: z.ZodString;
+    counts: z.ZodObject<{
+        collections: z.ZodNumber;
+        compared: z.ZodNumber;
+        unverified: z.ZodNumber;
+        changed: z.ZodNumber;
+        added: z.ZodNumber;
+        removed: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RuntimeComparison = z.infer<typeof runtimeComparisonSchema>;
+export declare function compareRuntimeInventories(beforeInput: unknown, afterInput: unknown): RuntimeComparison;
+export declare function projectRuntimeComparison(result: RuntimeComparison, detailed: boolean): {
+    schemaVersion: 1;
+    engineVersion: string;
+    provenance: "imported-runtime-comparison";
+    outcome: "passed" | "failed" | "incomplete";
+    reason: string;
+    beforeFingerprint: string;
+    afterFingerprint: string;
+    counts: {
+        collections: number;
+        compared: number;
+        unverified: number;
+        changed: number;
+        added: number;
+        removed: number;
+    };
+};

package/dist/src/runtime-inventory.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { VERSION } from "./types.js";
+const label = z.string().min(1).max(4096);
+const kind = z.enum([
+    "routes",
+    "listeners",
+    "middleware",
+    "schedules",
+    "bindings",
+]);
+const attribute = z.union([
+    z.string().max(4096),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(z.string().max(4096)).max(1024),
+]);
+export const runtimeInventorySchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    format: z.literal("runtime-inventory"),
+    producer: z.strictObject({ name: label, version: label }),
+    assembly: z.strictObject({ name: label, environment: label }),
+    sourceFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    capturedAt: z.iso.datetime(),
+    collections: z
+        .array(z.strictObject({
+        kind,
+        complete: z.boolean(),
+        ordered: z.boolean(),
+        entries: z
+            .array(z.strictObject({
+            key: label,
+            attributes: z.record(label, attribute),
+        }))
+            .max(20_000),
+    }))
+        .min(1)
+        .max(5),
+});
+const count = z.number().int().nonnegative();
+export const runtimeComparisonSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    engineVersion: z.string(),
+    provenance: z.literal("imported-runtime-comparison"),
+    outcome: z.enum(["passed", "failed", "incomplete"]),
+    reason: z.string(),
+    beforeFingerprint: z.string(),
+    afterFingerprint: z.string(),
+    counts: z.strictObject({
+        collections: count,
+        compared: count,
+        unverified: count,
+        changed: count,
+        added: count,
+        removed: count,
+    }),
+    collections: z.array(z.strictObject({
+        kind,
+        status: z.enum(["unchanged", "changed", "unverified"]),
+        beforeCount: count,
+        afterCount: count,
+        added: count,
+        removed: count,
+        orderChanged: z.boolean(),
+        changedKeys: z.array(label),
+    })),
+});
+export const runtimeComparisonSummarySchema = runtimeComparisonSchema.omit({
+    collections: true,
+});
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    return JSON.stringify(value);
+}
+const digest = (value) => createHash("sha256").update(canonical(value)).digest("hex");
+function parse(input) {
+    if (Buffer.byteLength(JSON.stringify(input)) > 8 * 1024 * 1024)
+        throw new Error("Runtime inventory exceeds artifact limit");
+    const result = runtimeInventorySchema.parse(input);
+    if (new Set(result.collections.map((collection) => collection.kind)).size !==
+        result.collections.length)
+        throw new Error("Duplicate runtime collection kind");
+    if (result.collections.reduce((sum, collection) => sum + collection.entries.length, 0) > 20_000)
+        throw new Error("Runtime inventory exceeds entry limit");
+    return result;
+}
+export function compareRuntimeInventories(beforeInput, afterInput) {
+    const before = parse(beforeInput);
+    const after = parse(afterInput);
+    const compatible = canonical(before.assembly) === canonical(after.assembly) &&
+        before.producer.name === after.producer.name;
+    const kinds = [
+        ...new Set([...before.collections, ...after.collections].map((collection) => collection.kind)),
+    ].sort();
+    const collections = kinds.map((kind) => {
+        const left = before.collections.find((collection) => collection.kind === kind);
+        const right = after.collections.find((collection) => collection.kind === kind);
+        const result = {
+            kind,
+            status: "unverified",
+            beforeCount: left?.entries.length ?? 0,
+            afterCount: right?.entries.length ?? 0,
+            added: 0,
+            removed: 0,
+            orderChanged: false,
+            changedKeys: [],
+        };
+        if (!compatible ||
+            !left?.complete ||
+            !right?.complete ||
+            left.ordered !== right.ordered)
+            return result;
+        const leftCounts = new Map();
+        const rightCounts = new Map();
+        for (const [entries, counts] of [
+            [left.entries, leftCounts],
+            [right.entries, rightCounts],
+        ])
+            for (const entry of entries) {
+                const id = canonical(entry);
+                counts.set(id, {
+                    key: entry.key,
+                    count: (counts.get(id)?.count ?? 0) + 1,
+                });
+            }
+        const changedKeys = new Set();
+        for (const id of new Set([...leftCounts.keys(), ...rightCounts.keys()])) {
+            const a = leftCounts.get(id);
+            const b = rightCounts.get(id);
+            const change = (b?.count ?? 0) - (a?.count ?? 0);
+            if (change !== 0)
+                changedKeys.add((a ?? b).key);
+            if (change > 0)
+                result.added += change;
+            else
+                result.removed -= change;
+        }
+        result.orderChanged =
+            left.ordered &&
+                canonical(left.entries) !== canonical(right.entries) &&
+                result.added === 0 &&
+                result.removed === 0;
+        result.changedKeys = [...changedKeys].sort();
+        result.status =
+            result.added || result.removed || result.orderChanged
+                ? "changed"
+                : "unchanged";
+        return result;
+    });
+    const counts = {
+        collections: collections.length,
+        compared: collections.filter((collection) => collection.status !== "unverified").length,
+        unverified: collections.filter((collection) => collection.status === "unverified").length,
+        changed: collections.filter((collection) => collection.status === "changed")
+            .length,
+        added: collections.reduce((sum, collection) => sum + collection.added, 0),
+        removed: collections.reduce((sum, collection) => sum + collection.removed, 0),
+    };
+    const outcome = counts.changed
+        ? "failed"
+        : counts.unverified
+            ? "incomplete"
+            : "passed";
+    return {
+        schemaVersion: 1,
+        engineVersion: VERSION,
+        provenance: "imported-runtime-comparison",
+        outcome,
+        reason: outcome === "passed"
+            ? "Declared runtime collections match; imported artifacts do not attest current runtime or source freshness."
+            : outcome === "failed"
+                ? "Declared runtime collections changed; inspect registration counts, attributes and ordering."
+                : "Runtime collection completeness or comparable assembly identity could not be established.",
+        beforeFingerprint: digest(before),
+        afterFingerprint: digest(after),
+        counts,
+        collections,
+    };
+}
+export function projectRuntimeComparison(result, detailed) {
+    if (detailed)
+        return result;
+    return runtimeComparisonSummarySchema.parse({
+        schemaVersion: result.schemaVersion,
+        engineVersion: result.engineVersion,
+        provenance: result.provenance,
+        outcome: result.outcome,
+        reason: result.reason,
+        beforeFingerprint: result.beforeFingerprint,
+        afterFingerprint: result.afterFingerprint,
+        counts: result.counts,
+    });
+}

package/dist/src/rust-dep-info.d.ts

@@ -0,0 +1 @@
+export declare function rustDependencyPaths(text: string, cwd: string): string[];

package/dist/src/rust-dep-info.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+function words(value) {
+    const result = [];
+    let word = "";
+    for (let index = 0; index < value.length; index++) {
+        const character = value[index];
+        if (character === "\\") {
+            const escaped = value[++index];
+            if (escaped !== " " && escaped !== "\\")
+                throw new Error("Unsupported dep-info escape");
+            word += escaped;
+        }
+        else if (character === " " || character === "\t") {
+            if (word)
+                result.push(word);
+            word = "";
+        }
+        else {
+            if ("$#\r\n".includes(character))
+                throw new Error("Unsupported dep-info path character");
+            word += character;
+        }
+    }
+    if (word)
+        result.push(word);
+    return result;
+}
+export function rustDependencyPaths(text, cwd) {
+    const paths = new Set();
+    let rules = 0;
+    for (const line of text.split("\n")) {
+        if (!line.trim() || line.startsWith("# env-dep:"))
+            continue;
+        const separator = line.indexOf(":");
+        if (separator <= 0 || !words(line.slice(0, separator)).length)
+            throw new Error("Malformed dep-info rule");
+        const dependencies = words(line.slice(separator + 1));
+        if (dependencies.length)
+            rules++;
+        for (const dependency of dependencies)
+            paths.add(path.resolve(cwd, dependency));
+    }
+    if (!rules)
+        throw new Error("Empty dep-info dependency rules");
+    return [...paths].sort();
+}

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

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

package/dist/src/rust-evidence.js

@@ -0,0 +1,157 @@
+import path from "node:path";
+import { z } from "zod";
+const target = z.object({
+    name: z.string(),
+    src_path: z.string(),
+    kind: z.array(z.string()).min(1),
+    test: z.boolean(),
+});
+const event = z.discriminatedUnion("reason", [
+    z.object({ reason: z.literal("build-finished"), success: z.boolean() }),
+    z.object({
+        reason: z.literal("compiler-artifact"),
+        package_id: z.string(),
+        target,
+        fresh: z.boolean(),
+        profile: z.object({ test: z.boolean() }),
+    }),
+    z.object({
+        reason: z.literal("compiler-message"),
+        package_id: z.string(),
+        message: z.object({
+            level: z.enum(["error", "warning", "note", "help", "failure-note"]),
+            code: z.object({ code: z.string() }).nullable(),
+            message: z.string(),
+            spans: z.array(z.object({
+                file_name: z.string(),
+                line_start: z.number().int().nonnegative(),
+                is_primary: z.boolean(),
+            })),
+        }),
+    }),
+    z.object({
+        reason: z.literal("build-script-executed"),
+        package_id: z.string(),
+    }),
+]);
+const schema = z.strictObject({
+    version: z.literal(1),
+    cargoVersion: z.literal("1.98.1"),
+    rustcVersion: z.literal("1.98.1"),
+    project: z.string(),
+    packageId: z.string(),
+    exitCode: z.number().int(),
+    targets: z.array(target).min(1),
+    events: z.array(event).max(20_000),
+    observedSources: z.array(z.string()).max(20_000),
+    depInfoCount: z.number().int().nonnegative().max(20_000),
+    scopeError: z.boolean(),
+});
+export function rustEvidence(check, processes, root) {
+    const incomplete = {
+        status: "inconclusive",
+        reason: "Rust evidence is malformed, stale or missing native target/source coverage.",
+    };
+    if (processes.length !== 1 || !root)
+        return incomplete;
+    const process = processes[0];
+    if (process.exitCode === 3) {
+        try {
+            z.strictObject({
+                unavailable: z.literal("rust-toolchain"),
+                reason: z.enum(["unsupported-version", "unsupported-workspace"]),
+            }).parse(JSON.parse(process.stdout));
+            return {
+                status: "unavailable",
+                reason: "The installed Rust version or Cargo workspace shape is outside the verified profile.",
+            };
+        }
+        catch {
+            return incomplete;
+        }
+    }
+    if (process.exitCode !== 0)
+        return {
+            status: "error",
+            reason: "Rust tooling could not resolve the package or complete native evidence collection.",
+        };
+    try {
+        const data = schema.parse(JSON.parse(process.stdout));
+        if (data.project !== check.project)
+            return incomplete;
+        const expected = new Set(check.scope.map((file) => path.resolve(root, check.project, file)));
+        const findings = [];
+        let errors = 0;
+        for (const item of data.events) {
+            if (item.reason !== "compiler-message")
+                continue;
+            if (item.message.level === "error")
+                errors++;
+            if (!["error", "warning"].includes(item.message.level))
+                continue;
+            const location = item.message.spans.find((span) => span.is_primary);
+            const absolute = location
+                ? path.resolve(root, check.project, location.file_name)
+                : undefined;
+            findings.push({
+                ruleId: `rustc/${item.message.code?.code ?? "diagnostic"}`,
+                level: item.message.level === "error" ? "error" : "warning",
+                message: item.message.message,
+                ...(absolute && expected.has(absolute) && location.line_start > 0
+                    ? {
+                        file: path.relative(root, absolute).split(path.sep).join("/"),
+                        line: location.line_start,
+                    }
+                    : {}),
+            });
+        }
+        if (errors)
+            return {
+                status: "failed",
+                reason: "The Rust compiler reported errors; compilation failures do not establish complete analysis.",
+                findings,
+                findingsComplete: false,
+            };
+        if (data.exitCode !== 0)
+            return {
+                status: "error",
+                reason: "Cargo failed without structured compiler-error evidence.",
+                findings,
+                findingsComplete: false,
+            };
+        const finished = data.events.filter((item) => item.reason === "build-finished");
+        const artifacts = data.events
+            .filter((item) => item.reason === "compiler-artifact")
+            .filter((item) => item.package_id === data.packageId);
+        const observed = new Set(data.observedSources.map((file) => path.resolve(root, check.project, file)));
+        if (finished.length !== 1 ||
+            !finished[0].success ||
+            data.events.at(-1)?.reason !== "build-finished" ||
+            data.scopeError ||
+            !data.depInfoCount ||
+            !expected.size ||
+            observed.size !== data.observedSources.length ||
+            observed.size !== expected.size ||
+            [...observed].some((file) => !expected.has(file)) ||
+            !artifacts.length ||
+            artifacts.some((item) => item.fresh) ||
+            data.targets.some((item) => !expected.has(path.resolve(item.src_path)) ||
+                !artifacts.some((artifact) => artifact.target.name === item.name &&
+                    artifact.target.src_path === item.src_path &&
+                    JSON.stringify(artifact.target.kind) ===
+                        JSON.stringify(item.kind) &&
+                    (!item.test ||
+                        item.kind.includes("custom-build") ||
+                        artifact.profile.test))))
+            return { ...incomplete, findings, findingsComplete: false };
+        return {
+            status: "passed",
+            reason: "Cargo checked all declared targets with fresh output and dep-info coverage of inventoried Rust source; no tests were executed.",
+            findings,
+            findingsComplete: true,
+        };
+    }
+    catch {
+        return incomplete;
+    }
+}

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

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

package/dist/src/rust-runner.js

@@ -0,0 +1,161 @@
+import { spawnSync } from "node:child_process";
+import { mkdtemp, readdir, readFile, realpath, rm, stat, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { rustDependencyPaths } from "./rust-dep-info.js";
+const target = z.object({
+    name: z.string(),
+    src_path: z.string(),
+    kind: z.array(z.string()),
+    test: z.boolean(),
+});
+const metadataSchema = z.object({
+    version: z.literal(1),
+    workspace_root: z.string(),
+    target_directory: z.string(),
+    build_directory: z.string(),
+    workspace_members: z.array(z.string()),
+    packages: z.array(z.object({
+        id: z.string(),
+        manifest_path: z.string(),
+        targets: z.array(target),
+    })),
+});
+function invoke(executable, args) {
+    const result = spawnSync(executable, args, {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024,
+    });
+    if (result.error || result.signal || result.status === null)
+        throw new Error("Rust tool did not complete within evidence limits");
+    return result;
+}
+async function main() {
+    const [root, ...scope] = process.argv.slice(2);
+    if (!root || !scope.length)
+        throw new Error("Invalid Rust scope");
+    for (const tool of ["rustc", "cargo"]) {
+        const version = invoke(tool, ["--version"]);
+        if (version.status !== 0 ||
+            version.stderr.trim() ||
+            !new RegExp(`^${tool} 1\\.98\\.1 \\([a-f0-9]+ [0-9-]+\\)$`).test(version.stdout.trim())) {
+            process.stdout.write(JSON.stringify({
+                unavailable: "rust-toolchain",
+                reason: "unsupported-version",
+            }));
+            process.exitCode = 3;
+            return;
+        }
+    }
+    const temporary = await mkdtemp(path.join(tmpdir(), "checktrail-rust-"));
+    try {
+        const config = [
+            "--config",
+            `build.build-dir=${JSON.stringify(temporary)}`,
+            "--config",
+            `build.target-dir=${JSON.stringify(temporary)}`,
+        ];
+        const metadataProcess = invoke("cargo", [
+            "metadata",
+            "--format-version=1",
+            "--offline",
+            "--locked",
+            "--no-deps",
+            ...config,
+        ]);
+        if (metadataProcess.status !== 0)
+            throw new Error("Cargo metadata could not resolve the locked local package");
+        const metadata = metadataSchema.parse(JSON.parse(metadataProcess.stdout));
+        if (metadata.target_directory !== temporary ||
+            metadata.build_directory !== temporary)
+            throw new Error("Cargo did not select fresh output directories");
+        const cwd = await realpath(process.cwd());
+        const selected = metadata.packages.find((item) => item.manifest_path === path.join(cwd, "Cargo.toml"));
+        if (metadata.workspace_root !== cwd ||
+            metadata.workspace_members.length !== 1 ||
+            !selected ||
+            metadata.workspace_members[0] !== selected.id) {
+            process.stdout.write(JSON.stringify({
+                unavailable: "rust-toolchain",
+                reason: "unsupported-workspace",
+            }));
+            process.exitCode = 3;
+            return;
+        }
+        const execution = invoke("cargo", [
+            "check",
+            "--all-targets",
+            "--offline",
+            "--locked",
+            "--message-format=json",
+            "--color=never",
+            "--target-dir",
+            temporary,
+            ...config,
+        ]);
+        const events = execution.stdout
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+        const files = new Set();
+        let entries = 0;
+        let bytes = 0;
+        let depInfoCount = 0;
+        let scopeError = false;
+        try {
+            const pending = [temporary];
+            while (pending.length) {
+                const directory = pending.pop();
+                for (const entry of await readdir(directory, { withFileTypes: true })) {
+                    if (++entries > 20_000)
+                        throw new Error("Rust build inventory limit");
+                    const file = path.join(directory, entry.name);
+                    if (entry.isDirectory())
+                        pending.push(file);
+                    else if (entry.isFile() && entry.name.endsWith(".d")) {
+                        if ((await stat(file)).size >
+                            Math.min(8 * 1024 * 1024, 16 * 1024 * 1024 - bytes))
+                            throw new Error("Rust dep-info byte limit");
+                        const source = await readFile(file, "utf8");
+                        bytes += Buffer.byteLength(source);
+                        if (bytes > 16 * 1024 * 1024)
+                            throw new Error("Rust dep-info byte limit");
+                        for (const dependency of rustDependencyPaths(source, cwd))
+                            files.add(dependency);
+                        depInfoCount++;
+                    }
+                }
+            }
+        }
+        catch {
+            scopeError = true;
+        }
+        const expected = new Set(scope.map((item) => path.resolve(cwd, item)));
+        const observedSources = [...files]
+            .filter((file) => expected.has(file))
+            .map((file) => path.relative(cwd, file))
+            .sort();
+        process.stdout.write(JSON.stringify({
+            version: 1,
+            cargoVersion: "1.98.1",
+            rustcVersion: "1.98.1",
+            exitCode: execution.status,
+            project: path.relative(root, cwd) || ".",
+            packageId: selected.id,
+            targets: selected.targets,
+            events,
+            observedSources,
+            depInfoCount,
+            scopeError,
+        }));
+        process.stderr.write(execution.stderr);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+main().catch(() => {
+    process.stderr.write("Rust collector failed while resolving the package or bounded native evidence.\n");
+    process.exitCode = 2;
+});