@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/architecture.js

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { VERSION } from "./types.js";
+const name = z.string().min(1).max(1024);
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const count = z.number().int().nonnegative();
+const edge = z.strictObject({ consumer: name, producer: name });
+export const dependencyGraphSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    format: z.literal("dependency-graph"),
+    capturedAt: z.iso.datetime(),
+    collector: z.strictObject({ name, version: name }),
+    complete: z.boolean(),
+    projects: z
+        .array(z.strictObject({
+        id: name,
+        language: name,
+        sourceFingerprint: hash,
+        complete: z.boolean(),
+    }))
+        .min(1)
+        .max(1000),
+    dependencies: z.array(edge).max(20_000),
+});
+export const architecturePolicySchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    format: z.literal("architecture-policy"),
+    projects: z
+        .array(z.strictObject({ id: name, layer: name }))
+        .min(1)
+        .max(1000),
+    layers: z.array(name).min(1).max(128),
+    allowedDependencies: z.array(edge).max(16_384),
+    requireAcyclic: z.boolean(),
+});
+export const architectureReportSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    engineVersion: z.string(),
+    provenance: z.literal("imported-dependency-graph"),
+    outcome: z.enum(["passed", "failed", "incomplete"]),
+    reason: z.string(),
+    artifactFingerprint: hash,
+    policyFingerprint: hash,
+    captureComplete: z.boolean(),
+    counts: z.strictObject({
+        projects: count,
+        verifiedProjects: count,
+        unverifiedProjects: count,
+        dependencies: count,
+        allowed: count,
+        forbidden: count,
+        unverified: count,
+        cycles: count,
+    }),
+    projects: z.array(z.strictObject({
+        id: name,
+        status: z.enum(["verified", "missing", "unconfigured", "incomplete"]),
+    })),
+    dependencies: z.array(edge.extend({ status: z.enum(["allowed", "forbidden", "unverified"]) })),
+    cycles: z.array(z.array(name)),
+});
+export const architectureSummarySchema = architectureReportSchema.omit({
+    projects: true,
+    dependencies: true,
+    cycles: true,
+});
+function bounded(input) {
+    const serialized = JSON.stringify(input);
+    if (typeof serialized !== "string" ||
+        Buffer.byteLength(serialized) > 8 * 1024 * 1024)
+        throw new Error("Architecture artifact exceeds input limit");
+    return serialized;
+}
+function unique(values, description) {
+    const result = new Set(values);
+    if (result.size !== values.length)
+        throw new Error(`Duplicate ${description}`);
+    return result;
+}
+const pair = (consumer, producer) => JSON.stringify([consumer, producer]);
+function cycleComponents(graph) {
+    const forward = new Map(graph.projects.map((project) => [project.id, []]));
+    const reverse = new Map(graph.projects.map((project) => [project.id, []]));
+    for (const { consumer, producer } of graph.dependencies) {
+        forward.get(consumer).push(producer);
+        reverse.get(producer).push(consumer);
+    }
+    const visited = new Set();
+    const finish = [];
+    for (const start of forward.keys()) {
+        if (visited.has(start))
+            continue;
+        const stack = [{ id: start, offset: 0 }];
+        visited.add(start);
+        while (stack.length) {
+            const item = stack[stack.length - 1];
+            const next = forward.get(item.id)[item.offset++];
+            if (next === undefined) {
+                finish.push(item.id);
+                stack.pop();
+            }
+            else if (!visited.has(next)) {
+                visited.add(next);
+                stack.push({ id: next, offset: 0 });
+            }
+        }
+    }
+    visited.clear();
+    const cycles = [];
+    for (const start of finish.reverse()) {
+        if (visited.has(start))
+            continue;
+        const members = [];
+        const pending = [start];
+        visited.add(start);
+        while (pending.length) {
+            const id = pending.pop();
+            members.push(id);
+            for (const dependency of reverse.get(id))
+                if (!visited.has(dependency)) {
+                    visited.add(dependency);
+                    pending.push(dependency);
+                }
+        }
+        if (members.length > 1 || forward.get(start).includes(start))
+            cycles.push(members.sort());
+    }
+    return cycles.sort((a, b) => a[0].localeCompare(b[0], "en"));
+}
+export function checkArchitecture(graphInput, policyInput) {
+    const graphBytes = bounded(graphInput);
+    const policyBytes = bounded(policyInput);
+    const graph = dependencyGraphSchema.parse(graphInput);
+    const policy = architecturePolicySchema.parse(policyInput);
+    const observed = unique(graph.projects.map((project) => project.id), "observed project ID");
+    unique(policy.projects.map((project) => project.id), "policy project ID");
+    const layers = unique(policy.layers, "architecture layer");
+    for (const project of policy.projects)
+        if (!layers.has(project.layer))
+            throw new Error("Project uses an undeclared architecture layer");
+    const allowed = unique(policy.allowedDependencies.map((item) => pair(item.consumer, item.producer)), "allowed layer dependency");
+    for (const item of policy.allowedDependencies)
+        if (!layers.has(item.consumer) || !layers.has(item.producer))
+            throw new Error("Allowed dependency uses an undeclared layer");
+    unique(graph.dependencies.map((item) => pair(item.consumer, item.producer)), "observed project dependency");
+    for (const item of graph.dependencies)
+        if (!observed.has(item.consumer) || !observed.has(item.producer))
+            throw new Error("Observed dependency references a missing graph project");
+    const observedProjects = new Map(graph.projects.map((project) => [project.id, project]));
+    const configured = new Map(policy.projects.map((project) => [project.id, project.layer]));
+    const projects = [
+        ...new Set([...observed, ...configured.keys()]),
+    ]
+        .sort()
+        .map((id) => ({
+        id,
+        status: !observed.has(id)
+            ? "missing"
+            : !configured.has(id)
+                ? "unconfigured"
+                : !observedProjects.get(id).complete
+                    ? "incomplete"
+                    : "verified",
+    }));
+    const dependencies = graph.dependencies.map((item) => {
+        const consumer = configured.get(item.consumer);
+        const producer = configured.get(item.producer);
+        return {
+            ...item,
+            status: consumer === undefined || producer === undefined
+                ? "unverified"
+                : allowed.has(pair(consumer, producer))
+                    ? "allowed"
+                    : "forbidden",
+        };
+    });
+    const cycles = policy.requireAcyclic ? cycleComponents(graph) : [];
+    const counts = {
+        projects: projects.length,
+        verifiedProjects: projects.filter((item) => item.status === "verified")
+            .length,
+        unverifiedProjects: projects.filter((item) => item.status !== "verified")
+            .length,
+        dependencies: dependencies.length,
+        allowed: dependencies.filter((item) => item.status === "allowed").length,
+        forbidden: dependencies.filter((item) => item.status === "forbidden")
+            .length,
+        unverified: dependencies.filter((item) => item.status === "unverified")
+            .length,
+        cycles: cycles.length,
+    };
+    const outcome = counts.forbidden || counts.cycles
+        ? "failed"
+        : !graph.complete || counts.unverifiedProjects || counts.unverified
+            ? "incomplete"
+            : "passed";
+    return {
+        schemaVersion: 1,
+        engineVersion: VERSION,
+        provenance: "imported-dependency-graph",
+        outcome,
+        captureComplete: graph.complete,
+        reason: outcome === "failed"
+            ? "Observed dependencies cross forbidden layer boundaries or contain prohibited cycles."
+            : outcome === "incomplete"
+                ? "Dependency capture or project-to-layer coverage is incomplete."
+                : "The supplied complete graph satisfies the explicit layer boundaries and cycle policy.",
+        artifactFingerprint: createHash("sha256").update(graphBytes).digest("hex"),
+        policyFingerprint: createHash("sha256").update(policyBytes).digest("hex"),
+        counts,
+        projects,
+        dependencies,
+        cycles,
+    };
+}
+export function projectArchitectureReport(report, detailed) {
+    if (detailed)
+        return report;
+    return architectureSummarySchema.parse({
+        schemaVersion: report.schemaVersion,
+        engineVersion: report.engineVersion,
+        provenance: report.provenance,
+        outcome: report.outcome,
+        reason: report.reason,
+        artifactFingerprint: report.artifactFingerprint,
+        policyFingerprint: report.policyFingerprint,
+        captureComplete: report.captureComplete,
+        counts: report.counts,
+    });
+}

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

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

package/dist/src/clang-evidence.js

@@ -0,0 +1,194 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { clangInvocationSchema } from "./clang.js";
+import { clangVersion, supportedClangVersion } from "./clang-protocol.js";
+const location = z.object({
+    physicalLocation: z.object({
+        artifactLocation: z.object({
+            uri: z.string(),
+            index: z.number().int().nonnegative().optional(),
+        }),
+        region: z.object({ startLine: z.number().int().positive() }),
+    }),
+});
+const sarif = z.object({
+    version: z.literal("2.1.0"),
+    runs: z
+        .array(z.object({
+        tool: z.object({
+            driver: z.object({
+                name: z.literal("clang"),
+                version: z.string(),
+                rules: z.array(z.object({ id: z.string() })),
+            }),
+        }),
+        invocations: z
+            .array(z.object({ executionSuccessful: z.boolean() }))
+            .length(1)
+            .optional(),
+        results: z
+            .array(z.object({
+            level: z.enum(["error", "warning", "note"]),
+            ruleId: z.string(),
+            ruleIndex: z.number().int().nonnegative(),
+            message: z.object({ text: z.string() }),
+            locations: z.array(location).optional(),
+        }))
+            .max(20_000),
+    }))
+        .length(1),
+});
+const schema = z.strictObject({
+    version: z.literal(1),
+    project: z.string(),
+    units: z
+        .array(z.strictObject({
+        index: z.number().int().nonnegative(),
+        file: z.string(),
+        compiler: z.enum(["clang", "clang++"]),
+        version: z.string(),
+        exitCode: z.number().int(),
+        diagnostics: z.unknown(),
+        observedSources: z.array(z.string()).max(20_000),
+        externalDependencyCount: z.number().int().nonnegative(),
+        scopeError: z.boolean(),
+    }))
+        .min(1)
+        .max(64),
+});
+export function clangEvidence(check, processes, root) {
+    const incomplete = {
+        status: "inconclusive",
+        reason: "Clang evidence is malformed or lacks compilation/source accounting",
+        findingsComplete: false,
+    };
+    if (!root || processes.length !== 1)
+        return incomplete;
+    const process = processes[0];
+    if (process.exitCode === 3) {
+        try {
+            const value = z
+                .strictObject({
+                unavailable: z.literal("clang-toolchain"),
+                reason: z.enum(["missing-tool", "unsupported-version"]),
+            })
+                .safeParse(JSON.parse(process.stdout));
+            return value.success
+                ? {
+                    status: "unavailable",
+                    reason: "The required Clang toolchain is missing or outside the verified native profile",
+                }
+                : incomplete;
+        }
+        catch {
+            return incomplete;
+        }
+    }
+    if (process.exitCode !== 0)
+        return {
+            status: "error",
+            reason: "Clang evidence collection did not complete normally",
+        };
+    try {
+        const data = schema.parse(JSON.parse(process.stdout));
+        const planned = clangInvocationSchema.parse(JSON.parse(check.commands[0].args[2]));
+        if (data.project !== check.project ||
+            data.units.length !== planned.units.length ||
+            JSON.stringify(planned.scope) !== JSON.stringify(check.scope))
+            return incomplete;
+        const observed = new Set();
+        const findings = [];
+        let partial = false;
+        let failed = false;
+        for (const [index, unit] of data.units.entries()) {
+            const expected = planned.units[index];
+            if (unit.index !== index ||
+                unit.file !== expected.file ||
+                unit.compiler !== expected.compiler ||
+                !supportedClangVersion(unit.version))
+                return incomplete;
+            const parsed = sarif.safeParse(unit.diagnostics);
+            if (!parsed.success) {
+                partial = true;
+                continue;
+            }
+            const run = parsed.data.runs[0];
+            if (run.tool.driver.version !==
+                (unit.version.startsWith("Apple ")
+                    ? unit.version.split("\n")[0]
+                    : clangVersion(unit.version)) ||
+                (unit.version.startsWith("Apple ") && !run.invocations) ||
+                (run.invocations !== undefined &&
+                    run.invocations[0].executionSuccessful !== (unit.exitCode === 0))) {
+                partial = true;
+                continue;
+            }
+            let errors = 0;
+            for (const diagnostic of run.results) {
+                if (run.tool.driver.rules[diagnostic.ruleIndex]?.id !== diagnostic.ruleId) {
+                    partial = true;
+                    continue;
+                }
+                if (diagnostic.level === "error")
+                    errors++;
+                const first = diagnostic.locations?.[0]?.physicalLocation;
+                let relative;
+                if (first) {
+                    try {
+                        const absolute = fileURLToPath(first.artifactLocation.uri);
+                        const file = path
+                            .relative(path.resolve(root, check.project), absolute)
+                            .split(path.sep)
+                            .join("/");
+                        if (check.scope.includes(file))
+                            relative = path.posix.join(check.project, file);
+                    }
+                    catch {
+                        partial = true;
+                    }
+                }
+                findings.push({
+                    ruleId: `clang/${diagnostic.ruleId}`,
+                    level: diagnostic.level,
+                    message: diagnostic.message.text,
+                    ...(relative && first
+                        ? { file: relative, line: first.region.startLine }
+                        : {}),
+                });
+            }
+            if (errors && unit.exitCode !== 0)
+                failed = true;
+            else if (unit.exitCode !== 0 || errors)
+                partial = true;
+            if (unit.scopeError ||
+                new Set(unit.observedSources).size !== unit.observedSources.length ||
+                !unit.observedSources.includes(unit.file))
+                partial = true;
+            for (const file of unit.observedSources) {
+                if (!check.scope.includes(file))
+                    partial = true;
+                else
+                    observed.add(file);
+            }
+        }
+        if (failed)
+            return {
+                status: "failed",
+                reason: "Clang reported native compiler errors; failed compilation does not establish complete analysis",
+                findings,
+                findingsComplete: false,
+            };
+        if (partial || observed.size !== check.scope.length || !observed.size)
+            return { ...incomplete, findings };
+        return {
+            status: "passed",
+            reason: "Every prepared Clang compilation completed with dependency coverage of inventoried C/C++ sources; linking and tests were not executed",
+            findings,
+            findingsComplete: true,
+        };
+    }
+    catch {
+        return incomplete;
+    }
+}

package/dist/src/clang-protocol.d.ts

@@ -0,0 +1,3 @@
+export declare function clangVersion(output: string): string | undefined;
+export declare function supportedClangVersion(output: string): boolean;
+export declare function clangDependencies(text: string, cwd: string): string[];

package/dist/src/clang-protocol.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+export function clangVersion(output) {
+    return /^(?:Apple |Debian |Ubuntu |Alpine )?clang version (\d+\.\d+\.\d+)(?:[^\r\n]*)\r?\nTarget: [^\r\n]+\r?\nThread model: posix\r?\nInstalledDir: [^\r\n]+$/.exec(output.trim())?.[1];
+}
+export function supportedClangVersion(output) {
+    return ((clangVersion(output) === "21.0.0" &&
+        output.startsWith("Apple clang version 21.0.0 (clang-2100.3.34.2)\n")) ||
+        (clangVersion(output) === "22.1.3" &&
+            output.startsWith("Alpine clang version 22.1.3\n")));
+}
+export function clangDependencies(text, cwd) {
+    const flattened = text.replace(/\\\r?\n/g, "").trim();
+    if (!flattened.startsWith("checktrail: "))
+        throw new Error("Missing native dependency target");
+    const body = flattened.slice("checktrail: ".length);
+    if (/[\r\n$#:]/.test(body) || body.replaceAll("\\ ", "").includes("\\"))
+        throw new Error("Unsupported dependency-file spelling");
+    const paths = body
+        .split(/(?<!\\)[ \t]+/)
+        .filter(Boolean)
+        .map((word) => path.resolve(cwd, word.replaceAll("\\ ", " ")));
+    if (!paths.length)
+        throw new Error("Native dependency list is empty");
+    return [...new Set(paths)].sort();
+}

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

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

package/dist/src/clang-runner.js

@@ -0,0 +1,159 @@
+import { spawnSync } from "node:child_process";
+import { mkdtemp, readFile, realpath, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { clangInvocationSchema } from "./clang.js";
+import { clangDependencies, supportedClangVersion } from "./clang-protocol.js";
+import { withinRoot } from "./inventory.js";
+function invoke(executable, args, cwd) {
+    const result = spawnSync(executable, args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024,
+    });
+    if (result.error || result.signal || result.status === null)
+        throw new Error("Clang did not complete within native evidence limits");
+    return result;
+}
+async function main() {
+    const [rootInput, encoded] = process.argv.slice(2);
+    if (!rootInput || !encoded)
+        throw new Error("Missing Clang invocation");
+    const root = await realpath(rootInput);
+    const projectRoot = await realpath(process.cwd());
+    const invocation = clangInvocationSchema.parse(JSON.parse(encoded));
+    const versions = new Map();
+    for (const name of new Set(invocation.units.map((unit) => unit.compiler))) {
+        let output;
+        try {
+            output = invoke(name, ["--no-default-config", "--version"], projectRoot);
+        }
+        catch {
+            process.stdout.write(JSON.stringify({
+                unavailable: "clang-toolchain",
+                reason: "missing-tool",
+            }));
+            process.exitCode = 3;
+            return;
+        }
+        if (output.status !== 0 ||
+            output.stderr.trim() ||
+            !supportedClangVersion(output.stdout)) {
+            process.stdout.write(JSON.stringify({
+                unavailable: "clang-toolchain",
+                reason: "unsupported-version",
+            }));
+            process.exitCode = 3;
+            return;
+        }
+        versions.set(name, output.stdout.trim());
+    }
+    const temporary = await mkdtemp(path.join(tmpdir(), "checktrail-clang-"));
+    const expected = new Set(invocation.scope.map((file) => path.resolve(projectRoot, file)));
+    let bytes = 0;
+    let dependencyBytes = 0;
+    try {
+        const units = [];
+        for (const [index, unit] of invocation.units.entries()) {
+            const cwd = await withinRoot(root, unit.cwd);
+            await withinRoot(root, path.relative(root, path.resolve(projectRoot, unit.file)));
+            const dependencyFile = path.join(temporary, `unit-${index}.d`);
+            const args = [
+                "--no-default-config",
+                ...unit.args,
+                "-fsyntax-only",
+                "-fno-modules",
+                "-fno-implicit-modules",
+                "-fdiagnostics-format=sarif",
+                "-Wno-sarif-format-unstable",
+                "-fno-color-diagnostics",
+                "-ferror-limit=0",
+                "-MD",
+                "-MF",
+                dependencyFile,
+                "-MT",
+                "checktrail",
+                unit.input,
+            ];
+            const native = invoke(unit.compiler, args, cwd);
+            bytes +=
+                Buffer.byteLength(native.stdout) + Buffer.byteLength(native.stderr);
+            if (bytes > 4 * 1024 * 1024)
+                throw new Error("Clang evidence exceeds total output limits");
+            const first = native.stderr.indexOf("{");
+            const last = native.stderr.lastIndexOf("}");
+            let diagnostics = null;
+            let scopeError = native.stdout.trim() !== "";
+            const tail = native.stderr.slice(last + 1).trim();
+            if (first < 0 ||
+                native.stderr.slice(0, first).trim() ||
+                (tail &&
+                    !/^(?:(?:\d+ warnings?(?: and )?)?\d+ errors?|\d+ warnings?) generated\.$/.test(tail)))
+                scopeError = true;
+            else {
+                try {
+                    diagnostics = JSON.parse(native.stderr.slice(first, last + 1));
+                }
+                catch {
+                    scopeError = true;
+                }
+            }
+            const observedSources = [];
+            let externalDependencyCount = 0;
+            try {
+                const size = (await stat(dependencyFile)).size;
+                dependencyBytes += size;
+                if (size > 8 * 1024 * 1024 || dependencyBytes > 16 * 1024 * 1024)
+                    throw new Error("Dependency evidence exceeds limits");
+                for (const dependency of clangDependencies(await readFile(dependencyFile, "utf8"), cwd)) {
+                    const physical = await realpath(dependency);
+                    const lexical = path.relative(root, dependency);
+                    const physicalRelative = path.relative(root, physical);
+                    const inside = (relative) => relative !== ".." &&
+                        !relative.startsWith(`..${path.sep}`) &&
+                        !path.isAbsolute(relative);
+                    if (physical !== dependency &&
+                        (inside(lexical) || inside(physicalRelative)))
+                        scopeError = true;
+                    if (expected.has(physical))
+                        observedSources.push(path.relative(projectRoot, physical).split(path.sep).join("/"));
+                    else {
+                        const relative = path.relative(root, physical);
+                        if (relative !== ".." &&
+                            !relative.startsWith(`..${path.sep}`) &&
+                            !path.isAbsolute(relative))
+                            scopeError = true;
+                        else
+                            externalDependencyCount++;
+                    }
+                }
+            }
+            catch {
+                scopeError = true;
+            }
+            units.push({
+                index,
+                file: unit.file,
+                compiler: unit.compiler,
+                version: versions.get(unit.compiler),
+                exitCode: native.status,
+                diagnostics,
+                observedSources: observedSources.sort(),
+                externalDependencyCount,
+                scopeError,
+            });
+        }
+        process.stdout.write(JSON.stringify({
+            version: 1,
+            project: path.relative(root, projectRoot).split(path.sep).join("/") || ".",
+            units,
+        }));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+main().catch(() => {
+    process.stderr.write("Clang evidence collection could not complete\n");
+    process.exitCode = 2;
+});

package/dist/src/clang.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { Check, Inventory, Project } from "./types.js";
+export declare const clangDatabaseSchema: z.ZodArray<z.ZodObject<{
+    directory: z.ZodString;
+    file: z.ZodString;
+    arguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    command: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const clangUnitSchema: z.ZodObject<{
+    compiler: z.ZodEnum<{
+        clang: "clang";
+        "clang++": "clang++";
+    }>;
+    cwd: z.ZodString;
+    file: z.ZodString;
+    input: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const clangInvocationSchema: z.ZodObject<{
+    units: z.ZodArray<z.ZodObject<{
+        compiler: z.ZodEnum<{
+            clang: "clang";
+            "clang++": "clang++";
+        }>;
+        cwd: z.ZodString;
+        file: z.ZodString;
+        input: z.ZodString;
+        args: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    scope: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ClangUnit = z.infer<typeof clangUnitSchema>;
+export declare const clangEnvironment: {
+    CCC_OVERRIDE_OPTIONS: string;
+    CPATH: string;
+    C_INCLUDE_PATH: string;
+    CPLUS_INCLUDE_PATH: string;
+    OBJC_INCLUDE_PATH: string;
+    CLANG_CONFIG_FILE_USER_DIR: string;
+    CLANG_CONFIG_FILE_SYSTEM_DIR: string;
+};
+export declare function clangExecutableMatches(name: "clang" | "clang++", declared: string): Promise<boolean>;
+export declare function clangCheck(source: Inventory, project: Project): Promise<Check>;