@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/actionlint-inputs.js

@@ -0,0 +1,123 @@
+import path from "node:path";
+import { workflowPath } from "./actionlint.js";
+import { parseDocument, visit, isScalar } from "yaml";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function actionlintInputs(files, scope) {
+    const findings = [];
+    const visited = new Set();
+    const queue = scope.map((file) => ({ file, action: false }));
+    const requireFile = (file) => {
+        if (!files.has(file))
+            throw new Error("A local workflow, action or runtime asset is missing or excluded from the inventory");
+    };
+    const localPath = (base, value) => {
+        if (!workflowPath(value) ||
+            path.posix.isAbsolute(value) ||
+            value.includes("${{"))
+            throw new Error("Local action paths must be literal relative paths");
+        const file = path.posix.normalize(path.posix.join(base, value));
+        if (file === ".." || file.startsWith("../"))
+            throw new Error("A local action path escapes the project");
+        return file;
+    };
+    const action = (value) => {
+        if (typeof value !== "string" || !value.startsWith("./"))
+            return;
+        const directory = localPath(".", value);
+        const metadata = ["action.yml", "action.yaml"]
+            .map((name) => path.posix.join(directory, name))
+            .filter((file) => files.has(file));
+        if (metadata.length !== 1)
+            throw new Error("A local action requires exactly one inventoried metadata file");
+        queue.push({ file: metadata[0], action: true });
+    };
+    const steps = (value) => {
+        if (Array.isArray(value))
+            for (const step of value)
+                action(record(step).uses);
+    };
+    try {
+        for (let index = 0; index < queue.length; index++) {
+            const entry = queue[index];
+            if (visited.has(entry.file))
+                continue;
+            if (visited.size >= 512)
+                throw new Error("Local action dependency closure exceeds 512 YAML files");
+            visited.add(entry.file);
+            requireFile(entry.file);
+            const bytes = files.get(entry.file);
+            const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            const doc = parseDocument(text, {
+                prettyErrors: false,
+                strict: true,
+                uniqueKeys: true,
+            });
+            if (doc.errors.length) {
+                findings.push(...doc.errors.map((error) => ({
+                    ruleId: `yaml/${error.code}`,
+                    level: "error",
+                    message: error.message,
+                    file: entry.file,
+                    line: text.slice(0, error.pos[0]).split("\n").length,
+                })));
+                continue;
+            }
+            if (doc.warnings.length)
+                throw new Error("YAML warnings prevent reliable local dependency inspection");
+            visit(doc, {
+                Alias() {
+                    throw new Error("YAML aliases require a separate verified workflow profile");
+                },
+                Pair(_key, pair) {
+                    if (isScalar(pair.key) && pair.key.value === "<<")
+                        throw new Error("YAML merge keys require a separate verified workflow profile");
+                },
+            });
+            const data = record(doc.toJS({ maxAliasCount: 0 }));
+            if (entry.action) {
+                const runs = record(data.runs);
+                for (const key of [
+                    "main",
+                    "pre",
+                    "post",
+                    "image",
+                    "entrypoint",
+                    "pre-entrypoint",
+                    "post-entrypoint",
+                ]) {
+                    const value = runs[key];
+                    if (typeof value === "string" &&
+                        value &&
+                        !(key === "image" && value.startsWith("docker://")))
+                        requireFile(localPath(path.posix.dirname(entry.file), value));
+                }
+                steps(runs.steps);
+            }
+            else {
+                for (const job of Object.values(record(data.jobs))) {
+                    const item = record(job);
+                    if (typeof item.uses === "string" && item.uses.startsWith("./")) {
+                        const file = localPath(".", item.uses);
+                        requireFile(file);
+                        if (!scope.includes(file))
+                            throw new Error("Local reusable workflows must belong to the planned workflow scope");
+                    }
+                    steps(item.steps);
+                }
+            }
+        }
+        return { findings };
+    }
+    catch (error) {
+        return {
+            findings,
+            unavailable: error instanceof Error
+                ? error.message
+                : "Workflow dependencies could not be inspected",
+        };
+    }
+}

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

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

package/dist/src/actionlint-runner.js

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, realpath, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { actionlintInputs } from "./actionlint-inputs.js";
+import { actionlintInvocationSchema, workflowRoot, workflowPath, } from "./actionlint.js";
+import { inventory, withinRoot } from "./inventory.js";
+let nativeBytes = 0;
+function invoke(args, cwd) {
+    const result = spawnSync("actionlint", args, {
+        cwd,
+        env: { PATH: process.env.PATH ?? "" },
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024,
+    });
+    nativeBytes +=
+        Buffer.byteLength(result.stdout ?? "") +
+            Buffer.byteLength(result.stderr ?? "");
+    if (result.error ||
+        result.signal ||
+        result.status === null ||
+        nativeBytes > 4 * 1024 * 1024)
+        throw new Error("Actionlint evidence exceeded process limits");
+    return result;
+}
+async function main() {
+    const temporary = await realpath(await mkdtemp(path.join(tmpdir(), "checktrail-actionlint-")));
+    try {
+        try {
+            const result = invoke(["-version"], temporary);
+            if (result.status !== 0 ||
+                result.stderr ||
+                !/^1\.7\.12\ninstalled by downloading from release page\nbuilt with go[^\r\n]+ compiler for (?:darwin|linux)\/(?:arm64|amd64)\n$/.test(result.stdout))
+                throw new Error("Unverified actionlint toolchain");
+        }
+        catch {
+            process.stdout.write(JSON.stringify({ unavailable: "actionlint-toolchain" }));
+            process.exitCode = 3;
+            return;
+        }
+        if (process.argv[2] === "--version") {
+            process.stdout.write("1.7.12\n");
+            return;
+        }
+        const root = await realpath(process.argv[2]);
+        const projectRoot = await realpath(process.cwd());
+        const project = path.relative(root, projectRoot).split(path.sep).join("/") || ".";
+        const invocation = actionlintInvocationSchema.parse(JSON.parse(process.argv[3]));
+        const source = await inventory(root);
+        if (source.fingerprint !== invocation.fingerprint)
+            throw new Error("Workflow source changed after planning");
+        const prefix = project === "." ? "" : `${project}/`;
+        const scope = source.files
+            .filter((file) => workflowRoot(file) === project)
+            .map((file) => file.slice(prefix.length));
+        if (JSON.stringify(scope) !== JSON.stringify(invocation.scope))
+            throw new Error("Workflow scope changed after planning");
+        const files = new Map();
+        let bytes = 0;
+        for (const file of source.files.filter((file) => file.startsWith(prefix))) {
+            const relative = file.slice(prefix.length);
+            if (relative.split("/").some((part) => part.toLowerCase() === ".git") ||
+                /(?:^|\/)\.github\/actionlint\.ya?ml$/i.test(relative))
+                continue;
+            if (!workflowPath(relative))
+                throw new Error("Workflow input paths contain unsupported characters");
+            const resolved = await withinRoot(root, file);
+            if (resolved !== path.resolve(root, file))
+                throw new Error("Workflow inputs must not traverse symbolic links");
+            const content = await readFile(resolved);
+            bytes += content.length;
+            if (content.length > 8 * 1024 * 1024 || bytes > 64 * 1024 * 1024)
+                throw new Error("Workflow copy exceeds inventory bounds");
+            files.set(relative, content);
+        }
+        const preflight = actionlintInputs(files, scope);
+        const results = [];
+        if (!preflight.unavailable && !preflight.findings.length) {
+            const snapshot = path.join(temporary, "project");
+            await mkdir(path.join(snapshot, ".git"), { recursive: true });
+            for (const [file, content] of files) {
+                const output = path.join(snapshot, file);
+                await mkdir(path.dirname(output), { recursive: true });
+                await writeFile(output, content, { flag: "wx" });
+            }
+            const configFile = path.join(temporary, "actionlint.json");
+            await writeFile(configFile, JSON.stringify({
+                "self-hosted-runner": { labels: invocation.config.runnerLabels },
+                "config-variables": invocation.config.variables,
+            }));
+            for (const file of scope) {
+                const result = invoke([
+                    "-verbose",
+                    "-format",
+                    "{{json .}}",
+                    "-shellcheck=",
+                    "-pyflakes=",
+                    "-no-color",
+                    "-config-file",
+                    configFile,
+                    file,
+                ], snapshot);
+                results.push({
+                    file,
+                    exitCode: result.status,
+                    stdout: result.stdout.replaceAll(snapshot, "<project>"),
+                    stderr: result.stderr.replaceAll(snapshot, "<project>"),
+                });
+            }
+        }
+        if ((await inventory(root)).fingerprint !== invocation.fingerprint)
+            throw new Error("Workflow inputs changed during validation");
+        process.stdout.write(JSON.stringify({ version: "1.7.12", ...invocation, preflight, results }));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+main().catch(() => {
+    process.stderr.write("Workflow evidence collection could not complete\n");
+    process.exitCode = 2;
+});

package/dist/src/actionlint.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { Check, Inventory, Project } from "./types.js";
+export declare function workflowPath(value: string): boolean;
+export declare const actionlintConfigSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    runnerLabels: z.ZodArray<z.ZodString>;
+    variables: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const actionlintInvocationSchema: z.ZodObject<{
+    config: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        runnerLabels: z.ZodArray<z.ZodString>;
+        variables: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    scope: z.ZodArray<z.ZodString>;
+    fingerprint: z.ZodString;
+}, z.core.$strict>;
+export declare function workflowRoot(file: string): string | undefined;
+export declare function actionlintCheck(source: Inventory, project: Project): Promise<Check>;

package/dist/src/actionlint.js

@@ -0,0 +1,80 @@
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { readProjectFile } from "./inventory.js";
+export function workflowPath(value) {
+    return [...value].every((character) => character.charCodeAt(0) >= 32 &&
+        character.charCodeAt(0) !== 127 &&
+        character !== "\\");
+}
+export const actionlintConfigSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    runnerLabels: z
+        .array(z.string().regex(/^[A-Za-z0-9_-]{1,128}$/))
+        .max(128)
+        .refine((items) => new Set(items.map((item) => item.toLowerCase())).size === items.length),
+    variables: z
+        .array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/))
+        .max(256)
+        .refine((items) => new Set(items.map((item) => item.toLowerCase())).size === items.length),
+});
+export const actionlintInvocationSchema = z.strictObject({
+    config: actionlintConfigSchema,
+    scope: z
+        .array(z
+        .string()
+        .regex(/^\.github\/workflows\/[^/]+\.ya?ml$/)
+        .refine(workflowPath))
+        .min(1)
+        .max(128),
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export function workflowRoot(file) {
+    const match = /^(.*?)(?:^|\/)\.github\/workflows\/[^/]+\.ya?ml$/.exec(file);
+    return match ? match[1] || "." : undefined;
+}
+export async function actionlintCheck(source, project) {
+    const prefix = project.path === "." ? "" : `${project.path}/`;
+    const scope = source.files
+        .filter((file) => workflowRoot(file) === project.path)
+        .map((file) => file.slice(prefix.length));
+    const check = {
+        id: "infrastructure.actionlint",
+        adapter: project.adapter,
+        project: project.path,
+        scope,
+        kind: "analysis",
+        parser: "actionlint-json",
+        commands: [],
+        reason: "Statically check every inventoried workflow with native completion accounting and explicit local dependencies.",
+    };
+    try {
+        const file = `${prefix}checktrail.actionlint.json`;
+        if (!source.files.includes(file))
+            throw new Error("Prepare checktrail.actionlint.json with explicit runnerLabels and variables");
+        const config = actionlintConfigSchema.parse(JSON.parse(await readProjectFile(source.root, file)));
+        const invocation = JSON.stringify(actionlintInvocationSchema.parse({
+            config,
+            scope,
+            fingerprint: source.fingerprint,
+        }));
+        if (Buffer.byteLength(invocation) > 100 * 1024)
+            throw new Error("Actionlint invocation exceeds 100 KiB");
+        check.commands.push({
+            executable: process.execPath,
+            args: [
+                fileURLToPath(new URL("./actionlint-runner.js", import.meta.url)),
+                source.root,
+                invocation,
+            ],
+            cwd: project.path,
+            env: { PATH: process.env.PATH ?? "" },
+        });
+    }
+    catch (error) {
+        check.unavailableReason =
+            error instanceof Error
+                ? error.message
+                : "Workflow profile could not be prepared";
+    }
+    return check;
+}

package/dist/src/adapters.d.ts

@@ -0,0 +1,49 @@
+import type { ExternalAdapter } from "./external-adapter.js";
+import type { Check, Inventory, Project } from "./types.js";
+export declare const adapters: readonly [{
+    readonly id: "javascript";
+    readonly markers: readonly ["package.json"];
+    readonly checks: readonly ["javascript.node-test", "javascript.typescript", "javascript.typescript-build", "javascript.vue-tsc", "javascript.vue-router", "javascript.nuxt-runtime", "javascript.eslint", "javascript.vitest", "javascript.jest", "javascript.playwright"];
+}, {
+    readonly id: "python";
+    readonly markers: readonly ["pyproject.toml", "setup.py", "requirements.txt"];
+    readonly checks: readonly ["python.unittest", "python.pytest", "python.ruff", "python.mypy", "python.fastapi-routes", "python.django-routes"];
+}, {
+    readonly id: "go";
+    readonly markers: readonly ["go.mod"];
+    readonly checks: readonly ["go.format", "go.vet", "go.test", "go.test-race", "go.staticcheck", "go.golangci-lint"];
+}, {
+    readonly id: "php";
+    readonly markers: readonly ["composer.json"];
+    readonly checks: readonly ["php.syntax", "php.phpstan", "php.phpunit", "php.pest", "php.pint", "php.laravel-runtime"];
+}, {
+    readonly id: "rust";
+    readonly markers: readonly ["Cargo.toml"];
+    readonly checks: readonly ["rust.cargo-check"];
+}, {
+    readonly id: "jvm";
+    readonly markers: readonly ["pom.xml", "build.gradle", "build.gradle.kts"];
+    readonly checks: readonly ["jvm.javac"];
+}, {
+    readonly id: "dotnet";
+    readonly markers: readonly [];
+    readonly checks: readonly ["dotnet.csharp"];
+}, {
+    readonly id: "ruby";
+    readonly markers: readonly ["Gemfile"];
+    readonly checks: readonly ["ruby.syntax"];
+}, {
+    readonly id: "swift";
+    readonly markers: readonly ["Package.swift"];
+    readonly checks: readonly ["swift.syntax"];
+}, {
+    readonly id: "cpp";
+    readonly markers: readonly ["CMakeLists.txt", "meson.build", "compile_commands.json"];
+    readonly checks: readonly ["cpp.clang-check"];
+}, {
+    readonly id: "infrastructure";
+    readonly markers: readonly ["Chart.yaml", "kustomization.yaml"];
+    readonly checks: readonly ["infrastructure.actionlint"];
+}];
+export declare function discover(source: Inventory, external?: ExternalAdapter[]): Project[];
+export declare function checksFor(source: Inventory, project: Project, requested?: readonly string[]): Promise<Check[]>;