@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/config.js

@@ -0,0 +1,140 @@
+import { validateWorkspace } from "./workspace.js";
+import { environmentName } from "./environment.js";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { readProjectFile } from "./inventory.js";
+import { loadPolicyPack, packReferenceSchema, } from "./policy-pack.js";
+export const workspaceSchema = z.strictObject({
+    complete: z.boolean(),
+    dependencies: z
+        .array(z.strictObject({
+        consumer: z.string().min(1),
+        producer: z.string().min(1),
+    }))
+        .max(20_000),
+});
+export const configSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    workspace: workspaceSchema.optional(),
+    projects: z
+        .array(z.strictObject({
+        path: z.string().min(1),
+        checks: z.array(z.string().min(1)).max(256),
+        packs: z.array(packReferenceSchema).max(32).optional(),
+        environment: z.array(environmentName).max(64).optional(),
+    }))
+        .min(1),
+});
+export async function loadConfig(source, overlayPath) {
+    const legacyNames = new Set([
+        "repo-verifier.json",
+        ...[
+            "actionlint",
+            "django",
+            "dotnet",
+            "fastapi",
+            "java",
+            "laravel",
+            "nuxt",
+            "vue-router",
+        ].map((profile) => `repo-verifier.${profile}.json`),
+    ]);
+    const legacy = source.files.find((file) => legacyNames.has(file.split("/").at(-1)));
+    if (legacy)
+        throw new Error(`Rename legacy configuration ${legacy} to its checktrail filename before validation`);
+    const raw = source.files.includes("checktrail.json")
+        ? await readProjectFile(source.root, "checktrail.json")
+        : undefined;
+    const base = raw === undefined ? undefined : configSchema.parse(JSON.parse(raw));
+    const overlay = overlayPath === undefined
+        ? undefined
+        : configSchema.parse(JSON.parse(await readProjectFile(source.root, overlayPath)));
+    if (overlay && !base)
+        throw new Error("Policy overlays require an explicit base checktrail.json");
+    const loaded = new Map();
+    const cache = new Map();
+    async function resolve(input) {
+        if (!input)
+            return undefined;
+        const paths = new Set();
+        for (const project of input.projects) {
+            if (paths.has(project.path))
+                throw new Error("Duplicate configured project path");
+            paths.add(project.path);
+            if (new Set(project.checks).size !== project.checks.length)
+                throw new Error("Duplicate check ID");
+            if (new Set(project.environment).size !== (project.environment?.length ?? 0))
+                throw new Error("Duplicate environment requirement");
+            const references = new Set();
+            for (const reference of project.packs ?? []) {
+                const key = JSON.stringify(reference);
+                if (!cache.has(key)) {
+                    if (cache.size >= 64)
+                        throw new Error("Policy pack reference limit exceeded");
+                    cache.set(key, await loadPolicyPack(source.root, reference));
+                }
+                const { pack, sha256 } = cache.get(key);
+                if (references.has(pack.id))
+                    throw new Error("Duplicate policy pack ID for project");
+                references.add(pack.id);
+                if (loaded.has(pack.id) && loaded.get(pack.id) !== sha256)
+                    throw new Error("Conflicting policy pack versions or contents");
+                loaded.set(pack.id, sha256);
+                project.checks = [
+                    ...new Set([...project.checks, ...pack.requiredChecks]),
+                ];
+                const names = [
+                    ...new Set([
+                        ...(project.environment ?? []),
+                        ...(pack.requiredEnvironment ?? []),
+                    ]),
+                ];
+                if (names.length)
+                    project.environment = names;
+            }
+            if (!project.checks.length)
+                throw new Error("Project policy has no required checks");
+        }
+        return input;
+    }
+    const resolvedBase = await resolve(base);
+    const resolvedOverlay = await resolve(overlay);
+    const config = resolvedBase ?? resolvedOverlay;
+    if (resolvedBase && resolvedOverlay) {
+        for (const extra of resolvedOverlay.projects) {
+            const existing = resolvedBase.projects.find((project) => project.path === extra.path);
+            if (!existing)
+                resolvedBase.projects.push(extra);
+            else {
+                existing.checks = [...new Set([...existing.checks, ...extra.checks])];
+                const names = [
+                    ...new Set([
+                        ...(existing.environment ?? []),
+                        ...(extra.environment ?? []),
+                    ]),
+                ];
+                if (names.length)
+                    existing.environment = names;
+            }
+        }
+        if (resolvedOverlay.workspace) {
+            if (resolvedBase.workspace &&
+                JSON.stringify(resolvedBase.workspace) !==
+                    JSON.stringify(resolvedOverlay.workspace))
+                throw new Error("Conflicting workspace declarations in policy overlay");
+            resolvedBase.workspace = resolvedOverlay.workspace;
+        }
+    }
+    if (config?.workspace)
+        validateWorkspace(config.workspace, config.projects.map((project) => project.path));
+    return {
+        config: config === undefined ? undefined : configSchema.parse(config),
+        fingerprint: createHash("sha256")
+            .update(JSON.stringify({
+            config: config ?? { defaults: 1 },
+            packs: [...loaded].sort(),
+            overlay: overlayPath ?? null,
+        }))
+            .digest("hex"),
+    };
+}

package/dist/src/contract-schema.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+export declare const contractBundleSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    format: z.ZodLiteral<"contract-samples">;
+    capturedAt: z.ZodISODateTime;
+    contracts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        producer: z.ZodObject<{
+            name: z.ZodString;
+            sourceFingerprint: z.ZodString;
+        }, z.core.$strict>;
+        consumer: z.ZodObject<{
+            name: z.ZodString;
+            sourceFingerprint: z.ZodString;
+        }, z.core.$strict>;
+        complete: z.ZodBoolean;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        samples: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            payload: z.ZodUnknown;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ContractBundle = z.infer<typeof contractBundleSchema>;
+export declare const contractReportSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    engineVersion: z.ZodString;
+    provenance: z.ZodLiteral<"imported-contract-samples">;
+    outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    reason: z.ZodString;
+    artifactFingerprint: z.ZodString;
+    counts: z.ZodObject<{
+        contracts: z.ZodNumber;
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+        unverified: z.ZodNumber;
+        samples: z.ZodNumber;
+        accepted: z.ZodNumber;
+        rejected: z.ZodNumber;
+    }, z.core.$strict>;
+    contracts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        outcome: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            incomplete: "incomplete";
+        }>;
+        reason: z.ZodString;
+        samples: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            accepted: z.ZodBoolean;
+            errors: z.ZodArray<z.ZodObject<{
+                keyword: z.ZodString;
+                instancePath: z.ZodString;
+                schemaPath: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ContractReport = z.infer<typeof contractReportSchema>;
+export declare const contractSummarySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    engineVersion: z.ZodString;
+    provenance: z.ZodLiteral<"imported-contract-samples">;
+    outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    reason: z.ZodString;
+    counts: z.ZodObject<{
+        contracts: z.ZodNumber;
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+        unverified: z.ZodNumber;
+        samples: z.ZodNumber;
+        accepted: z.ZodNumber;
+        rejected: z.ZodNumber;
+    }, z.core.$strict>;
+    artifactFingerprint: z.ZodString;
+}, z.core.$strict>;

package/dist/src/contract-schema.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+const name = z.string().min(1).max(1024);
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const count = z.number().int().nonnegative();
+export const contractBundleSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    format: z.literal("contract-samples"),
+    capturedAt: z.iso.datetime(),
+    contracts: z
+        .array(z.strictObject({
+        id: name,
+        producer: z.strictObject({ name, sourceFingerprint: hash }),
+        consumer: z.strictObject({ name, sourceFingerprint: hash }),
+        complete: z.boolean(),
+        schema: z.record(z.string(), z.unknown()),
+        samples: z
+            .array(z.strictObject({ name, payload: z.unknown() }))
+            .max(1000),
+    }))
+        .min(1)
+        .max(100),
+});
+export const contractReportSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    engineVersion: z.string(),
+    provenance: z.literal("imported-contract-samples"),
+    outcome: z.enum(["passed", "failed", "incomplete"]),
+    reason: z.string(),
+    artifactFingerprint: hash,
+    counts: z.strictObject({
+        contracts: count,
+        passed: count,
+        failed: count,
+        unverified: count,
+        samples: count,
+        accepted: count,
+        rejected: count,
+    }),
+    contracts: z.array(z.strictObject({
+        id: name,
+        outcome: z.enum(["passed", "failed", "incomplete"]),
+        reason: z.string(),
+        samples: z.array(z.strictObject({
+            name,
+            accepted: z.boolean(),
+            errors: z.array(z.strictObject({
+                keyword: z.string(),
+                instancePath: z.string(),
+                schemaPath: z.string(),
+            })),
+        })),
+    })),
+});
+export const contractSummarySchema = contractReportSchema.omit({
+    contracts: true,
+});

package/dist/src/contract-worker.d.ts

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

package/dist/src/contract-worker.js

@@ -0,0 +1,123 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsImport from "ajv-formats";
+import { VERSION } from "./types.js";
+const addFormats = addFormatsImport.default ?? addFormatsImport;
+const { bundle, fingerprint } = workerData;
+function localSchema(value) {
+    if (value === null || typeof value !== "object")
+        return true;
+    for (const [key, item] of Object.entries(value)) {
+        if (["$ref", "$dynamicRef", "$recursiveRef"].includes(key) &&
+            (typeof item !== "string" || !item.startsWith("#")))
+            return false;
+        if (["$async", "$data", "nullable", "discriminator"].includes(key))
+            return false;
+        if ([
+            "$defs",
+            "definitions",
+            "properties",
+            "patternProperties",
+            "dependentSchemas",
+        ].includes(key) &&
+            item !== null &&
+            typeof item === "object" &&
+            !Object.values(item).every(localSchema))
+            return false;
+        if (["allOf", "anyOf", "oneOf", "prefixItems"].includes(key) &&
+            Array.isArray(item) &&
+            !item.every(localSchema))
+            return false;
+        if ([
+            "items",
+            "additionalProperties",
+            "unevaluatedProperties",
+            "unevaluatedItems",
+            "contains",
+            "not",
+            "if",
+            "then",
+            "else",
+            "propertyNames",
+        ].includes(key) &&
+            !localSchema(item))
+            return false;
+    }
+    return true;
+}
+const contracts = bundle.contracts.map((contract) => {
+    const incomplete = {
+        id: contract.id,
+        outcome: "incomplete",
+        reason: "Contract lacks complete samples or a supported strict JSON Schema 2020-12 definition.",
+        samples: [],
+    };
+    if (!contract.complete ||
+        !contract.samples.length ||
+        typeof contract.schema.type !== "string" ||
+        !localSchema(contract.schema))
+        return incomplete;
+    try {
+        const ajv = new Ajv2020({
+            strict: true,
+            strictRequired: true,
+            allErrors: false,
+            ownProperties: true,
+            logger: false,
+            coerceTypes: false,
+            useDefaults: false,
+            removeAdditional: false,
+            loopRequired: 32,
+            loopEnum: 32,
+        });
+        addFormats(ajv);
+        const validate = ajv.compile(contract.schema);
+        const samples = contract.samples.map((sample) => ({
+            name: sample.name,
+            accepted: validate(sample.payload) === true,
+            errors: (validate.errors ?? []).slice(0, 20).map((error) => ({
+                keyword: error.keyword,
+                instancePath: error.instancePath,
+                schemaPath: error.schemaPath,
+            })),
+        }));
+        const outcome = samples.some((sample) => !sample.accepted)
+            ? "failed"
+            : "passed";
+        return {
+            id: contract.id,
+            outcome,
+            reason: outcome === "passed"
+                ? "Captured producer samples satisfy the consumer schema."
+                : "A captured producer sample violates the consumer schema.",
+            samples,
+        };
+    }
+    catch {
+        return incomplete;
+    }
+});
+const counts = {
+    contracts: contracts.length,
+    passed: contracts.filter((contract) => contract.outcome === "passed").length,
+    failed: contracts.filter((contract) => contract.outcome === "failed").length,
+    unverified: contracts.filter((contract) => contract.outcome === "incomplete")
+        .length,
+    samples: contracts.reduce((sum, contract) => sum + contract.samples.length, 0),
+    accepted: contracts.reduce((sum, contract) => sum + contract.samples.filter((sample) => sample.accepted).length, 0),
+    rejected: contracts.reduce((sum, contract) => sum + contract.samples.filter((sample) => !sample.accepted).length, 0),
+};
+parentPort?.postMessage({
+    schemaVersion: 1,
+    engineVersion: VERSION,
+    provenance: "imported-contract-samples",
+    outcome: counts.failed
+        ? "failed"
+        : counts.unverified
+            ? "incomplete"
+            : "passed",
+    reason: "Consumer schemas were checked against supplied producer samples; this does not prove live integration, source freshness or general schema compatibility.",
+    artifactFingerprint: fingerprint,
+    counts,
+    contracts,
+});

package/dist/src/contracts.d.ts

@@ -0,0 +1,22 @@
+import { type ContractReport } from "./contract-schema.js";
+export declare function validateContracts(input: unknown, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<ContractReport>;
+export declare function projectContractReport(result: ContractReport, detailed: boolean): {
+    schemaVersion: 1;
+    engineVersion: string;
+    provenance: "imported-contract-samples";
+    outcome: "passed" | "failed" | "incomplete";
+    reason: string;
+    counts: {
+        contracts: number;
+        passed: number;
+        failed: number;
+        unverified: number;
+        samples: number;
+        accepted: number;
+        rejected: number;
+    };
+    artifactFingerprint: string;
+};

package/dist/src/contracts.js

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { Worker } from "node:worker_threads";
+import { contractBundleSchema, contractReportSchema, contractSummarySchema, } from "./contract-schema.js";
+import { VERSION } from "./types.js";
+function inputJSON(input) {
+    let count = 0;
+    const seen = new Set();
+    function visit(value, depth) {
+        if (++count > 100_000 || depth > 32)
+            throw new Error("Contract input exceeds structure limits");
+        if (value === null ||
+            typeof value === "string" ||
+            typeof value === "boolean" ||
+            (typeof value === "number" && Number.isFinite(value)))
+            return;
+        if (typeof value !== "object" || seen.has(value))
+            throw new Error("Contract input must be finite acyclic JSON");
+        seen.add(value);
+        if (!Array.isArray(value) &&
+            Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null)
+            throw new Error("Contract input must contain plain JSON objects");
+        for (const item of Object.values(value))
+            visit(item, depth + 1);
+        seen.delete(value);
+    }
+    visit(input, 0);
+    const json = JSON.stringify(input);
+    if (Buffer.byteLength(json) > 8 * 1024 * 1024)
+        throw new Error("Contract input exceeds 8 MiB limit");
+    return json;
+}
+export async function validateContracts(input, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000)
+        throw new Error("Contract timeout must be between 1 and 30000 milliseconds");
+    const json = inputJSON(input);
+    const bundle = contractBundleSchema.parse(JSON.parse(json));
+    const ids = new Set();
+    for (const contract of bundle.contracts) {
+        if (ids.has(contract.id))
+            throw new Error("Duplicate contract ID");
+        ids.add(contract.id);
+        const samples = new Set();
+        for (const sample of contract.samples) {
+            if (samples.has(sample.name) || !Object.hasOwn(sample, "payload"))
+                throw new Error("Duplicate sample name or missing payload");
+            samples.add(sample.name);
+        }
+    }
+    const fingerprint = createHash("sha256").update(json).digest("hex");
+    const incomplete = () => ({
+        schemaVersion: 1,
+        engineVersion: VERSION,
+        provenance: "imported-contract-samples",
+        outcome: "incomplete",
+        reason: "Contract validation did not finish within its worker, time or cancellation limits.",
+        artifactFingerprint: fingerprint,
+        counts: {
+            contracts: bundle.contracts.length,
+            passed: 0,
+            failed: 0,
+            unverified: bundle.contracts.length,
+            samples: 0,
+            accepted: 0,
+            rejected: 0,
+        },
+        contracts: bundle.contracts.map((contract) => ({
+            id: contract.id,
+            outcome: "incomplete",
+            reason: "Worker validation did not complete.",
+            samples: [],
+        })),
+    });
+    if (options.signal?.aborted)
+        return incomplete();
+    return new Promise((resolve) => {
+        const worker = new Worker(new URL("./contract-worker.js", import.meta.url), {
+            workerData: { bundle, fingerprint },
+            execArgv: [],
+            resourceLimits: {
+                maxOldGenerationSizeMb: 64,
+                maxYoungGenerationSizeMb: 16,
+                stackSizeMb: 4,
+            },
+            stdout: true,
+            stderr: true,
+        });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+            void worker.terminate().finally(() => resolve(value));
+        };
+        const abort = () => finish(incomplete());
+        const timer = setTimeout(abort, timeoutMs);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        worker.once("message", (message) => {
+            const result = contractReportSchema.safeParse(message);
+            finish(result.success ? result.data : incomplete());
+        });
+        worker.once("error", abort);
+        worker.once("exit", abort);
+        if (options.signal?.aborted)
+            abort();
+    });
+}
+export function projectContractReport(result, detailed) {
+    if (detailed)
+        return result;
+    return contractSummarySchema.parse({
+        schemaVersion: result.schemaVersion,
+        engineVersion: result.engineVersion,
+        provenance: result.provenance,
+        outcome: result.outcome,
+        reason: result.reason,
+        artifactFingerprint: result.artifactFingerprint,
+        counts: result.counts,
+    });
+}

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

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

package/dist/src/django-evidence.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { runtimeInventorySchema } from "./runtime-inventory.js";
+const count = z.number().int().nonnegative().max(20_000);
+const schema = z.strictObject({
+    version: z.literal(1),
+    djangoVersion: z.literal("6.1.1"),
+    visitedNodes: count,
+    unsupportedNodes: count,
+    runtime: runtimeInventorySchema,
+});
+const attributesSchema = z.strictObject({
+    patterns: z.array(z.string()).min(1).max(33),
+    namespaces: z.array(z.string()),
+    handler: z.string().min(1),
+    name: z.string().nullable(),
+    defaultsHash: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export function djangoEvidence(check, processes) {
+    const incomplete = {
+        status: "inconclusive",
+        reason: "Django URL inventory is empty, unsupported, malformed or incomplete.",
+    };
+    if (processes.length !== 1)
+        return incomplete;
+    if (processes[0].exitCode === 3) {
+        try {
+            z.strictObject({
+                unavailable: z.literal("django-runtime"),
+                reason: z.enum(["missing-package", "unsupported-version"]),
+            }).parse(JSON.parse(processes[0].stdout));
+            return {
+                status: "unavailable",
+                reason: "The pinned Django runtime profile is not installed.",
+            };
+        }
+        catch {
+            return incomplete;
+        }
+    }
+    if (processes[0].exitCode !== 0)
+        return {
+            status: "error",
+            reason: "Django settings, setup, URL resolver or supported collector could not complete.",
+        };
+    try {
+        const result = schema.parse(JSON.parse(processes[0].stdout));
+        const profile = JSON.parse(check.commands[0].args[2]);
+        const routes = result.runtime.collections[0];
+        if (result.runtime.sourceFingerprint !== check.commands[0].args[3] ||
+            result.runtime.producer.name !== "checktrail.django-routes" ||
+            result.runtime.producer.version !== "1.0.0" ||
+            result.runtime.assembly.name !== profile.assembly ||
+            result.runtime.assembly.environment !== profile.environment ||
+            result.runtime.collections.length !== 1 ||
+            routes?.kind !== "routes" ||
+            !routes.ordered ||
+            routes.complete !== (result.unsupportedNodes === 0) ||
+            !routes.entries.length ||
+            routes.entries.length + result.unsupportedNodes > result.visitedNodes)
+            return incomplete;
+        const identities = new Set();
+        let duplicates = 0;
+        for (const entry of routes.entries) {
+            const attributes = attributesSchema.parse(entry.attributes);
+            if (entry.key !== JSON.stringify(attributes.patterns))
+                return incomplete;
+            for (const pattern of attributes.patterns) {
+                const parsed = z
+                    .tuple([
+                    z.enum(["RoutePattern", "RegexPattern"]),
+                    z.string(),
+                    z.number().int().nonnegative(),
+                    z.boolean(),
+                ])
+                    .parse(JSON.parse(pattern));
+                if (pattern !== JSON.stringify(parsed))
+                    return incomplete;
+            }
+            if (identities.has(entry.key))
+                duplicates++;
+            identities.add(entry.key);
+        }
+        if (duplicates)
+            return {
+                status: "failed",
+                reason: "Django registered exact duplicate native URL pattern chains.",
+                runtime: result.runtime,
+            };
+        if (!routes.complete)
+            return { ...incomplete, runtime: result.runtime };
+        return {
+            status: "passed",
+            reason: "Django setup completed and supported native URL pattern chains contain no exact duplicates.",
+            runtime: result.runtime,
+        };
+    }
+    catch {
+        return incomplete;
+    }
+}

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

@@ -0,0 +1 @@
+export declare const djangoRunner: string;