@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/clang.js

@@ -0,0 +1,197 @@
+import { access, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { readProjectFile, withinRoot } from "./inventory.js";
+const text = z
+    .string()
+    .min(1)
+    .max(8192)
+    .refine((value) => !value.includes("\0"));
+export const clangDatabaseSchema = z
+    .array(z.strictObject({
+    directory: text,
+    file: text,
+    arguments: z.array(text).min(2).max(256).optional(),
+    command: text.optional(),
+    output: text.optional(),
+}))
+    .min(1)
+    .max(64);
+export const clangUnitSchema = z.strictObject({
+    compiler: z.enum(["clang", "clang++"]),
+    cwd: z.string(),
+    file: z.string(),
+    input: z.string().min(1),
+    args: z.array(z.string()),
+});
+export const clangInvocationSchema = z.strictObject({
+    units: z.array(clangUnitSchema).min(1).max(64),
+    scope: z.array(z.string()).min(1).max(20_000),
+});
+export const clangEnvironment = {
+    // Clang treats a leading # as a quiet, empty override list.
+    CCC_OVERRIDE_OPTIONS: "#",
+    CPATH: "",
+    C_INCLUDE_PATH: "",
+    CPLUS_INCLUDE_PATH: "",
+    OBJC_INCLUDE_PATH: "",
+    CLANG_CONFIG_FILE_USER_DIR: "",
+    CLANG_CONFIG_FILE_SYSTEM_DIR: "",
+};
+const sourceExtension = /\.(?:c|cc|cpp|cxx|C|c\+\+)$/;
+const inventoriedExtension = /\.(?:c|cc|cpp|cxx|C|c\+\+|h|hh|hpp|hxx|h\+\+|inc|ipp|tpp|ixx|cppm)$/;
+export async function clangExecutableMatches(name, declared) {
+    if (declared === name)
+        return true;
+    if (!path.isAbsolute(declared) || path.basename(declared) !== name)
+        return false;
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+        const candidate = path.resolve(directory, name);
+        try {
+            await access(candidate, constants.X_OK);
+            return (await realpath(candidate)) === (await realpath(declared));
+        }
+        catch {
+            /* Keep searching PATH until its first executable is found. */
+        }
+    }
+    return false;
+}
+async function databaseUnits(source, project) {
+    const database = clangDatabaseSchema.parse(JSON.parse(await readProjectFile(source.root, path.posix.join(project.path, "compile_commands.json"))));
+    const projectRoot = await withinRoot(source.root, project.path);
+    const units = [];
+    for (const entry of database) {
+        if (!entry.arguments)
+            throw new Error("Shell-string compilation databases require an arguments-array export");
+        const cwd = await withinRoot(source.root, path.relative(source.root, path.resolve(projectRoot, entry.directory)));
+        if (!(await stat(cwd)).isDirectory())
+            throw new Error("Compilation directory must exist");
+        const absolute = await withinRoot(source.root, path.relative(source.root, path.resolve(cwd, entry.file)));
+        const file = path.relative(projectRoot, absolute).split(path.sep).join("/");
+        if (!sourceExtension.test(file) || !project.files.includes(file))
+            throw new Error("Compilation database includes a non-inventoried translation unit");
+        const declared = entry.arguments[0];
+        const compiler = path.basename(declared);
+        if ((compiler !== "clang" && compiler !== "clang++") ||
+            !(await clangExecutableMatches(compiler, declared)))
+            throw new Error("Compilation database must select the registered PATH Clang executable");
+        const args = [];
+        let inputs = 0;
+        let input = "";
+        let compileOnly = false;
+        for (let i = 1; i < entry.arguments.length; i++) {
+            const arg = entry.arguments[i];
+            if (arg === "-c") {
+                compileOnly = true;
+                continue;
+            }
+            if (arg === "-o" || arg === "-MF" || arg === "-MT" || arg === "-MQ") {
+                if (!entry.arguments[++i])
+                    throw new Error("Missing compilation output argument");
+                continue;
+            }
+            if (["-MD", "-MMD", "-MP", "-g", "-g0"].includes(arg))
+                continue;
+            if (/^-std=(?:c(?:89|90|99|11|17|18|23|2x)|gnu(?:89|90|99|11|17|18|23|2x)|(?:c|gnu)\+\+(?:98|03|11|14|17|20|23|2b|26|2c))$/.test(arg) ||
+                /^-O[0-3sgz]$/.test(arg) ||
+                ["-fPIC", "-fPIE", "-fno-exceptions", "-fno-rtti", "-pthread"].includes(arg) ||
+                /^-W(?:all|extra|error|pedantic|conversion|sign-conversion|shadow|unused|unused-parameter|no-unused-parameter)$/.test(arg)) {
+                args.push(arg);
+                continue;
+            }
+            const define = /^(-[DU])(.*)$/.exec(arg);
+            if (define) {
+                const value = define[2] || entry.arguments[++i];
+                if (!value ||
+                    !/^[A-Za-z_][A-Za-z0-9_]*(?:=[^\r\n]*)?$/.test(value) ||
+                    (define[1] === "-U" && value.includes("=")))
+                    throw new Error("Unsupported macro argument");
+                args.push(define[1], value);
+                continue;
+            }
+            const include = /^(?:-I(.+))$/.exec(arg);
+            if (include || ["-I", "-iquote", "-isystem"].includes(arg)) {
+                const value = include?.[1] ?? entry.arguments[++i];
+                if (!value)
+                    throw new Error("Missing include directory");
+                const directory = await withinRoot(source.root, path.relative(source.root, path.resolve(cwd, value)));
+                if (!(await stat(directory)).isDirectory())
+                    throw new Error("Include path must be a directory");
+                args.push(include ? "-I" : arg, value);
+                continue;
+            }
+            if (arg.startsWith("-") ||
+                arg.startsWith("@") ||
+                (await withinRoot(source.root, path.relative(source.root, path.resolve(cwd, arg)))) !== absolute)
+                throw new Error("Compilation database uses an unsupported compiler flag or input");
+            input = arg;
+            inputs++;
+        }
+        if (!compileOnly || inputs !== 1)
+            throw new Error("Compilation database must describe exactly one compile-only source input per entry");
+        units.push({
+            compiler,
+            cwd: path.relative(source.root, cwd).split(path.sep).join("/") || ".",
+            file,
+            input,
+            args,
+        });
+    }
+    if (new Set(units.map((unit) => JSON.stringify(unit))).size !== units.length)
+        throw new Error("Duplicate compilation database entry");
+    return units;
+}
+export async function clangCheck(source, project) {
+    const scope = project.files.filter((file) => inventoriedExtension.test(file));
+    const check = {
+        id: "cpp.clang-check",
+        adapter: project.adapter,
+        project: project.path,
+        scope,
+        kind: "analysis",
+        parser: "clang-json",
+        commands: [],
+        reason: "Check prepared Clang compilation database entries without emitting objects; account for native translation-unit and header dependencies.",
+    };
+    if (!project.files.includes("compile_commands.json"))
+        check.unavailableReason =
+            "Prepare an inventoried project-root compile_commands.json with arguments arrays; build systems are not run automatically.";
+    else if (!scope.length)
+        check.unavailableReason = "No C/C++ source was inventoried";
+    else if ([source.root, project.path, ...scope].some((file) => /[\r\n\\$#:]/.test(file)))
+        check.unavailableReason =
+            "This dependency-file profile does not support newline, backslash, dollar, hash or colon in source paths";
+    else if (scope.some((file) => /\.(?:ixx|cppm)$/.test(file)))
+        check.unavailableReason =
+            "C++ module translation units require a separate verified build profile";
+    else {
+        try {
+            const invocation = JSON.stringify({
+                units: await databaseUnits(source, project),
+                scope,
+            });
+            if (Buffer.byteLength(invocation) > 100 * 1024)
+                throw new Error("Compilation invocation exceeds the 100 KiB argument limit");
+            check.commands.push({
+                executable: process.execPath,
+                args: [
+                    fileURLToPath(new URL("./clang-runner.js", import.meta.url)),
+                    source.root,
+                    invocation,
+                ],
+                cwd: project.path,
+                env: { ...clangEnvironment, PATH: process.env.PATH ?? "" },
+            });
+        }
+        catch (error) {
+            check.unavailableReason =
+                error instanceof Error
+                    ? error.message
+                    : "Compilation database could not be prepared";
+        }
+    }
+    return check;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { createReviewContext, projectReviewContext, receiveReview, projectReviewReceipt, } from "./review.js";
+import { fetchPolicyPack } from "./fetch-pack.js";
+import { externalReferencesSchema, loadExternalAdapters, } from "./external-adapter.js";
+import { runMutations, projectMutations } from "./mutation.js";
+import { retrieveGuidance, projectGuidance } from "./guidance.js";
+import { createFindingBaseline, compareFindings, projectFindingComparison, } from "./finding-policy.js";
+import { checkArchitecture, projectArchitectureReport, } from "./architecture.js";
+import { inheritEnvironment } from "./environment.js";
+import { parseArgs } from "node:util";
+import { realpath } from "node:fs/promises";
+import { adapters } from "./adapters.js";
+import { createPlan, validate } from "./engine.js";
+import { serve } from "./mcp.js";
+import { projectPlan, projectReport } from "./output.js";
+import { exportSarif } from "./sarif.js";
+import { reportSchema } from "./schemas.js";
+import { importJUnit } from "./junit.js";
+import { readProjectFile } from "./inventory.js";
+import { VERSION } from "./types.js";
+import { validateContracts, projectContractReport } from "./contracts.js";
+import { compareRuntimeInventories, projectRuntimeComparison, } from "./runtime-inventory.js";
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        strict: true,
+        options: {
+            root: { type: "string", default: "." },
+            "trust-project": { type: "boolean", default: false },
+            "allow-execution": { type: "boolean", default: false },
+            detailed: { type: "boolean", default: false },
+            input: { type: "string" },
+            context: { type: "string" },
+            "allow-review-source": { type: "boolean", default: false },
+            url: { type: "string" },
+            sha256: { type: "string" },
+            output: { type: "string" },
+            topic: { type: "string", multiple: true },
+            policy: { type: "string" },
+            before: { type: "string" },
+            after: { type: "string" },
+            baseline: { type: "string" },
+            "previous-baseline": { type: "string" },
+            owner: { type: "string" },
+            reason: { type: "string" },
+            base: { type: "string" },
+            "policy-overlay": { type: "string" },
+            adapter: { type: "string", multiple: true },
+            "allow-env": { type: "string", multiple: true },
+            "timeout-ms": { type: "string", default: "30000" },
+            help: { type: "boolean", default: false },
+            version: { type: "boolean", default: false },
+        },
+    });
+    if (values.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    if (values.help || positionals.length === 0) {
+        process.stdout.write("checktrail <inspect|plan|run|serve|adapters|import-junit|export-sarif|create-baseline|compare-findings|compare-runtime|check-contracts|check-architecture|guidance|review-context|review-receipt|mutate|fetch-pack> [--root PATH] [--detailed] [--base REVISION] [--policy-overlay PATH] [--adapter PATH#sha256=DIGEST ...]\nRun: --trust-project [--timeout-ms 30000] [--allow-env NAME ...]\nServe: --allow-execution (optional; disabled by default) [--allow-env NAME ...]\nFetch-pack: --url HTTPS_URL --sha256 DIGEST --output RELATIVE_JSON_PATH\nExit: 0 passed/read-only success/completed advisory experiment, 1 failed checks, 2 incomplete/error\n");
+        return;
+    }
+    if (positionals.length !== 1)
+        throw new Error("Expected exactly one command");
+    const command = positionals[0];
+    if (values["allow-review-source"] &&
+        (!values.detailed ||
+            !["review-context", "review-receipt", "serve"].includes(command)))
+        throw new Error("Review source disclosure requires --detailed with review-context, review-receipt or serve");
+    if (values.context !== undefined && command !== "review-receipt")
+        throw new Error("--context applies only to review-receipt");
+    if (command !== "fetch-pack" &&
+        (values.url !== undefined ||
+            values.sha256 !== undefined ||
+            values.output !== undefined))
+        throw new Error("Download options apply only to fetch-pack");
+    const externalAdapters = externalReferencesSchema.parse((values.adapter ?? []).map((value) => {
+        const split = value.lastIndexOf("#sha256=");
+        if (split <= 0)
+            throw new Error("External adapters require PATH#sha256=DIGEST");
+        return {
+            path: path.resolve(value.slice(0, split)),
+            sha256: value.slice(split + 8),
+        };
+    }));
+    if (externalAdapters.length &&
+        !["inspect", "plan", "run", "serve", "adapters", "guidance"].includes(command))
+        throw new Error("External adapters apply only to inspection, planning, validation, serving and derived guidance");
+    if (externalAdapters.length && command === "guidance" && values.input)
+        throw new Error("External adapters require derived guidance, not an imported context");
+    const print = (value) => {
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    };
+    if (command === "adapters") {
+        print([
+            ...adapters,
+            ...(await loadExternalAdapters(externalAdapters)).map((item) => ({
+                ...item.identity,
+                markers: item.manifest.markers,
+                checks: item.manifest.checks.map((check) => `${item.identity.id}.${check.id}`),
+            })),
+        ]);
+        return;
+    }
+    const root = await realpath(values.root);
+    if (command === "fetch-pack") {
+        if (!values.url || !values.sha256 || !values.output)
+            throw new Error("fetch-pack requires --url HTTPS_URL --sha256 DIGEST --output RELATIVE_JSON_PATH");
+        if (values["trust-project"] ||
+            values["allow-execution"] ||
+            values.base ||
+            values["policy-overlay"] ||
+            values["allow-env"]?.length)
+            throw new Error("Policy pack download does not accept execution or project policy options");
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        process.once("SIGINT", cancel);
+        process.once("SIGTERM", cancel);
+        try {
+            print(await fetchPolicyPack(root, {
+                url: values.url,
+                sha256: values.sha256,
+                output: values.output,
+                timeoutMs: Number(values["timeout-ms"]),
+                signal: controller.signal,
+            }));
+        }
+        finally {
+            process.removeListener("SIGINT", cancel);
+            process.removeListener("SIGTERM", cancel);
+        }
+        return;
+    }
+    if (command === "review-context") {
+        if (!values.input)
+            throw new Error("review-context requires --input selection.json");
+        print(projectReviewContext(await createReviewContext(root, JSON.parse(await readProjectFile(root, values.input))), values["allow-review-source"]));
+        return;
+    }
+    if (command === "review-receipt") {
+        if (!values.context || !values.input)
+            throw new Error("review-receipt requires --context context.json and --input assessment.json");
+        const result = await receiveReview(root, JSON.parse(await readProjectFile(root, values.context)), JSON.parse(await readProjectFile(root, values.input)));
+        print(projectReviewReceipt(result, values["allow-review-source"]));
+        process.exitCode =
+            result.freshness === "current" && result.citations.unmatched === 0
+                ? 0
+                : 2;
+        return;
+    }
+    if (command === "mutate") {
+        if (values.base !== undefined ||
+            values["policy-overlay"] !== undefined ||
+            values["allow-env"]?.length)
+            throw new Error("Mutation experiments do not support Git selection, private overlays or environment grants in this profile");
+        if (!values["trust-project"])
+            throw new Error("Mutation experiments require --trust-project");
+        if (!values.input)
+            throw new Error("Mutation experiments require --input recipe path");
+        const report = await runMutations(root, JSON.parse(await readProjectFile(root, values.input)), {
+            trusted: true,
+            timeoutMs: Number(values["timeout-ms"]),
+        });
+        print(projectMutations(report, values.detailed));
+        process.exitCode = report.complete ? 0 : 2;
+        return;
+    }
+    if (command === "guidance") {
+        if (values.input && values.topic)
+            throw new Error("Use either --input context or --topic, not both");
+        const context = values.input
+            ? JSON.parse(await readProjectFile(root, values.input))
+            : {
+                schemaVersion: 1,
+                checks: [
+                    ...new Set((await createPlan(root, {
+                        externalAdapters,
+                        environment: inheritEnvironment(values["allow-env"] ?? []),
+                        ...(values.base !== undefined ? { base: values.base } : {}),
+                        ...(values["policy-overlay"] !== undefined
+                            ? { policyOverlay: values["policy-overlay"] }
+                            : {}),
+                    })).plan.checks.map((check) => check.id)),
+                ],
+                topics: values.topic ?? [],
+            };
+        print(projectGuidance(retrieveGuidance(context), values.detailed));
+        return;
+    }
+    if (command === "check-architecture") {
+        if (!values.input || !values.policy)
+            throw new Error("Architecture validation requires --input graph and --policy boundary artifact paths");
+        const result = checkArchitecture(JSON.parse(await readProjectFile(root, values.input)), JSON.parse(await readProjectFile(root, values.policy)));
+        print(projectArchitectureReport(result, values.detailed));
+        process.exitCode =
+            result.outcome === "passed" ? 0 : result.outcome === "failed" ? 1 : 2;
+        return;
+    }
+    if (command === "check-contracts") {
+        if (!values.input)
+            throw new Error("Contract validation requires --input relative artifact path");
+        const result = await validateContracts(JSON.parse(await readProjectFile(root, values.input)), { timeoutMs: Number(values["timeout-ms"]) });
+        print(projectContractReport(result, values.detailed));
+        process.exitCode =
+            result.outcome === "passed" ? 0 : result.outcome === "failed" ? 1 : 2;
+        return;
+    }
+    if (command === "compare-runtime") {
+        if (!values.before || !values.after)
+            throw new Error("Runtime comparison requires --before and --after relative artifact paths");
+        const result = compareRuntimeInventories(JSON.parse(await readProjectFile(root, values.before)), JSON.parse(await readProjectFile(root, values.after)));
+        print(projectRuntimeComparison(result, values.detailed));
+        process.exitCode =
+            result.outcome === "passed" ? 0 : result.outcome === "failed" ? 1 : 2;
+        return;
+    }
+    if (command === "create-baseline" || command === "compare-findings") {
+        if (!values.input)
+            throw new Error("Finding policy requires --input relative/report.json");
+        const report = JSON.parse(await readProjectFile(root, values.input));
+        if (command === "create-baseline") {
+            if (!values.owner || !values.reason)
+                throw new Error("Baseline creation requires --owner and --reason");
+            const result = createFindingBaseline(report, {
+                owner: values.owner,
+                reason: values.reason,
+            });
+            print(values.detailed
+                ? result
+                : {
+                    schemaVersion: result.schemaVersion,
+                    provenance: "baseline-draft",
+                    entries: result.entries.length,
+                    limits: result.limits,
+                });
+        }
+        else {
+            if (!values.baseline)
+                throw new Error("Comparison requires --baseline relative/baseline.json");
+            const previous = values["previous-baseline"] === undefined
+                ? undefined
+                : JSON.parse(await readProjectFile(root, values["previous-baseline"]));
+            const result = compareFindings(report, JSON.parse(await readProjectFile(root, values.baseline)), previous === undefined ? {} : { previousBaseline: previous });
+            print(projectFindingComparison(result, values.detailed));
+            process.exitCode =
+                result.outcome === "passed" ? 0 : result.outcome === "failed" ? 1 : 2;
+        }
+        return;
+    }
+    if (command === "export-sarif") {
+        if (!values.input)
+            throw new Error("SARIF export requires --input relative/report.json");
+        const report = reportSchema.parse(JSON.parse(await readProjectFile(root, values.input)));
+        print(exportSarif(report));
+        process.exitCode =
+            report.outcome === "passed" ? 0 : report.outcome === "failed" ? 1 : 2;
+        return;
+    }
+    if (command === "import-junit") {
+        if (!values.input)
+            throw new Error("JUnit import requires --input relative/path.xml");
+        const result = importJUnit(await readProjectFile(root, values.input));
+        print(values.detailed
+            ? result
+            : {
+                schemaVersion: result.schemaVersion,
+                engineVersion: result.engineVersion,
+                format: result.format,
+                provenance: result.provenance,
+                outcome: result.outcome,
+                reason: result.reason,
+                ...(result.tests ? { tests: result.tests } : {}),
+            });
+        process.exitCode =
+            result.outcome === "passed" ? 0 : result.outcome === "failed" ? 1 : 2;
+        return;
+    }
+    const environment = inheritEnvironment(values["allow-env"] ?? []);
+    if (command === "serve") {
+        await serve({
+            root,
+            allowExecution: values["allow-execution"],
+            allowReviewSource: values["allow-review-source"],
+            detailed: values.detailed,
+            environment,
+            externalAdapters,
+            ...(values.base !== undefined ? { base: values.base } : {}),
+            ...(values["policy-overlay"] !== undefined
+                ? { policyOverlay: values["policy-overlay"] }
+                : {}),
+        });
+        return;
+    }
+    if (command === "inspect" || command === "plan") {
+        print(projectPlan((await createPlan(root, {
+            environment,
+            externalAdapters,
+            ...(values.base !== undefined ? { base: values.base } : {}),
+            ...(values["policy-overlay"] !== undefined
+                ? { policyOverlay: values["policy-overlay"] }
+                : {}),
+        })).plan, values.detailed));
+        return;
+    }
+    if (command === "run") {
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        process.once("SIGINT", cancel);
+        process.once("SIGTERM", cancel);
+        try {
+            const report = await validate(root, {
+                trusted: values["trust-project"],
+                environment,
+                externalAdapters,
+                ...(values.base !== undefined ? { base: values.base } : {}),
+                ...(values["policy-overlay"] !== undefined
+                    ? { policyOverlay: values["policy-overlay"] }
+                    : {}),
+                timeoutMs: Number(values["timeout-ms"]),
+                signal: controller.signal,
+            });
+            print(projectReport(report, values.detailed));
+            process.exitCode =
+                report.outcome === "passed" ? 0 : report.outcome === "failed" ? 1 : 2;
+        }
+        finally {
+            process.removeListener("SIGINT", cancel);
+            process.removeListener("SIGTERM", cancel);
+        }
+        return;
+    }
+    throw new Error("Unknown command");
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : "Unexpected error"}\n`);
+    process.exitCode = 2;
+});

package/dist/src/config.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { Inventory } from "./types.js";
+export declare const workspaceSchema: z.ZodObject<{
+    complete: z.ZodBoolean;
+    dependencies: z.ZodArray<z.ZodObject<{
+        consumer: z.ZodString;
+        producer: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const configSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    workspace: z.ZodOptional<z.ZodObject<{
+        complete: z.ZodBoolean;
+        dependencies: z.ZodArray<z.ZodObject<{
+            consumer: z.ZodString;
+            producer: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    projects: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        checks: z.ZodArray<z.ZodString>;
+        packs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>>>;
+        environment: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof configSchema>;
+export declare function loadConfig(source: Inventory, overlayPath?: string): Promise<{
+    config: Config | undefined;
+    fingerprint: string;
+}>;