@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/finding-policy.js

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { findingBaselineSchema, findingBaselineEntrySchema, findingKeySchema, } from "./finding-policy-schema.js";
+import { validatedReport } from "./report-validation.js";
+import { VERSION } from "./types.js";
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export function projectFindingComparison(result, detailed) {
+    if (detailed)
+        return result;
+    return {
+        schemaVersion: result.schemaVersion,
+        engineVersion: result.engineVersion,
+        provenance: result.provenance,
+        outcome: result.outcome,
+        validationOutcome: result.validationOutcome,
+        reason: result.reason,
+        sourceVerified: result.sourceVerified,
+        baselineFingerprint: result.baselineFingerprint,
+        counts: result.counts,
+        limitExceeded: result.limitExceeded,
+        unaccountedFailures: result.unaccountedFailures,
+    };
+}
+const keyId = (key) => digest([
+    key.checkId,
+    key.project,
+    key.ruleId,
+    key.file,
+    key.line,
+    key.level,
+    key.messageHash,
+]);
+function baseline(input) {
+    const result = findingBaselineSchema.parse(input);
+    const ids = new Set();
+    for (const entry of result.entries) {
+        if (entry.id !== keyId(entry) || ids.has(entry.id))
+            throw new Error("Invalid or duplicate baseline finding identity");
+        ids.add(entry.id);
+    }
+    return result;
+}
+function findings(report) {
+    const result = new Map();
+    for (const check of report.checks)
+        for (const finding of check.findings ?? []) {
+            const parsed = findingKeySchema.safeParse({
+                checkId: check.id,
+                project: check.project,
+                ruleId: finding.ruleId,
+                file: finding.file,
+                line: finding.line,
+                level: finding.level,
+                messageHash: digest(finding.message),
+            });
+            const id = parsed.success
+                ? keyId(parsed.data)
+                : digest([check.id, check.project, finding]);
+            const previous = result.get(id);
+            result.set(id, {
+                key: parsed.success ? parsed.data : undefined,
+                count: (previous?.count ?? 0) + 1,
+            });
+        }
+    return result;
+}
+export function createFindingBaseline(input, options) {
+    const report = validatedReport(input);
+    const metadata = findingBaselineEntrySchema
+        .pick({ owner: true, reason: true, kind: true, expiresAt: true })
+        .parse({ ...options, kind: options.kind ?? "baseline" });
+    if (report.outcome === "incomplete" ||
+        report.sourceFingerprint !== report.finalSourceFingerprint ||
+        report.sourceChanged ||
+        report.sourceError ||
+        report.checks.some((check) => !["passed", "failed"].includes(check.status) ||
+            check.tools?.some((tool) => tool.status !== "identified")))
+        throw new Error("Baseline creation requires current and conclusive validation evidence");
+    if (report.checks.some((check) => check.status === "failed" &&
+        (!check.findingsComplete || !check.findings?.length)))
+        throw new Error("Baseline creation cannot account for every native failure");
+    const entries = [...findings(report)].map(([id, item]) => {
+        if (!item.key)
+            throw new Error("Baselines require an exact source file, line and native finding identity");
+        return findingBaselineEntrySchema.parse({
+            ...item.key,
+            id,
+            occurrences: item.count,
+            ...metadata,
+        });
+    });
+    return baseline({
+        schemaVersion: 1,
+        createdFrom: {
+            runId: report.runId,
+            sourceFingerprint: report.sourceFingerprint,
+            policyFingerprint: report.policyFingerprint,
+        },
+        limits: {
+            maxEntries: entries.length,
+            maxExceptions: entries.filter((entry) => entry.kind === "exception")
+                .length,
+        },
+        entries,
+    });
+}
+export function compareFindings(input, baselineInput, options = {}) {
+    const report = validatedReport(input);
+    const policy = baseline(baselineInput);
+    const previous = options.previousBaseline === undefined
+        ? undefined
+        : baseline(options.previousBaseline);
+    const now = options.now === undefined
+        ? Date.now()
+        : Date.parse(z.iso.datetime().parse(options.now));
+    const sourceVerified = !report.sourceChanged &&
+        !report.sourceError &&
+        report.finalSourceFingerprint === report.sourceFingerprint;
+    const current = findings(report);
+    const counts = {
+        current: [...current.values()].reduce((sum, item) => sum + item.count, 0),
+        new: 0,
+        matched: 0,
+        stale: 0,
+        expired: 0,
+        changed: 0,
+        unverified: 0,
+        expanded: 0,
+        modified: 0,
+    };
+    const entries = [];
+    for (const entry of policy.entries) {
+        const found = current.get(entry.id);
+        const check = report.checks.find((check) => check.id === entry.checkId && check.project === entry.project);
+        const accounted = check &&
+            (check.status === "passed" ||
+                (check.status === "failed" && check.findingsComplete === true));
+        let status;
+        if (entry.expiresAt && Date.parse(entry.expiresAt) <= now)
+            status = "expired";
+        else if (!sourceVerified || !accounted)
+            status = "unverified";
+        else if (!found)
+            status = "stale";
+        else if (found.count !== entry.occurrences)
+            status = "changed";
+        else
+            status = "matched";
+        counts[status]++;
+        entries.push({ id: entry.id, status, occurrences: found?.count ?? 0 });
+    }
+    const ids = new Set(policy.entries.map((entry) => entry.id));
+    const newFindingIds = [...current.keys()].filter((id) => !ids.has(id));
+    counts.new = newFindingIds.reduce((sum, id) => sum + current.get(id).count, 0);
+    if (previous) {
+        const old = new Map(previous.entries.map((entry) => [entry.id, entry]));
+        for (const entry of policy.entries) {
+            const existing = old.get(entry.id);
+            if (!existing)
+                counts.expanded++;
+            else if (digest(existing) !== digest(entry))
+                counts.modified++;
+        }
+    }
+    const limitExceeded = policy.entries.length > policy.limits.maxEntries ||
+        policy.entries.filter((entry) => entry.kind === "exception").length >
+            policy.limits.maxExceptions ||
+        Boolean(previous &&
+            (policy.limits.maxEntries > previous.limits.maxEntries ||
+                policy.limits.maxExceptions > previous.limits.maxExceptions));
+    const unaccountedFailures = report.checks.filter((check) => check.status === "failed" &&
+        (!check.findingsComplete || !check.findings?.length)).length;
+    const failed = counts.new ||
+        counts.stale ||
+        counts.expired ||
+        counts.changed ||
+        counts.expanded ||
+        counts.modified ||
+        limitExceeded ||
+        unaccountedFailures;
+    const incomplete = !sourceVerified ||
+        counts.unverified ||
+        report.outcome === "incomplete" ||
+        report.checks.some((check) => !["passed", "failed"].includes(check.status) ||
+            check.tools?.some((tool) => tool.status !== "identified"));
+    const outcome = failed ? "failed" : incomplete ? "incomplete" : "passed";
+    return {
+        schemaVersion: 1,
+        engineVersion: VERSION,
+        provenance: "finding-comparison",
+        outcome,
+        validationOutcome: report.outcome,
+        reason: outcome === "passed"
+            ? "Finding policy matches the supplied report; the native validation outcome is retained separately."
+            : outcome === "failed"
+                ? "Finding policy has new, stale, expired, changed or expanded entries, exceeded limits, or unaccounted native failures."
+                : "Finding policy cannot be reconciled against complete current-source evidence.",
+        sourceVerified,
+        baselineFingerprint: digest(policy),
+        counts,
+        limitExceeded,
+        unaccountedFailures,
+        entries,
+        newFindingIds,
+    };
+}

package/dist/src/git-selection.d.ts

@@ -0,0 +1,3 @@
+import type { ChangeSelection, GitIdentity, Inventory, Workspace } from "./types.js";
+export declare function selectGitChanges(source: Inventory, projects: string[], base: string, workspace?: Workspace): Promise<ChangeSelection>;
+export declare function verifyGitIdentity(root: string, identity: GitIdentity): Promise<"same" | "changed" | "error">;

package/dist/src/git-selection.js

@@ -0,0 +1,229 @@
+import { createHash } from "node:crypto";
+import { access, lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { constants } from "node:fs";
+import { withinRoot } from "./inventory.js";
+import { runProcess } from "./runner.js";
+import { affectedProjects } from "./workspace.js";
+const gitEnvironment = {
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_OPTIONAL_LOCKS: "0",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_NO_LAZY_FETCH: "1",
+    GIT_NO_REPLACE_OBJECTS: "1",
+    GIT_ATTR_NOSYSTEM: "1",
+};
+async function hostGit(root) {
+    const outside = (file) => {
+        const relative = path.relative(root, file);
+        return (relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative));
+    };
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!path.isAbsolute(directory))
+            continue;
+        const candidate = path.join(directory, "git");
+        if (!outside(candidate))
+            continue;
+        try {
+            const resolved = await realpath(candidate);
+            if (outside(resolved) && (await lstat(resolved)).isFile()) {
+                await access(resolved, constants.X_OK);
+                return resolved;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("A host Git executable outside the project is required");
+}
+function gitReader(root) {
+    const executable = hostGit(root);
+    const deadline = Date.now() + 5000;
+    let bytes = 4 * 1024 * 1024;
+    return async (args) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 || bytes <= 0)
+            throw new Error("Git inspection budget exceeded");
+        const result = await runProcess(root, {
+            executable: await executable,
+            args: [
+                "--no-pager",
+                "-c",
+                "core.fsmonitor=false",
+                "-c",
+                "core.hooksPath=/dev/null",
+                "-c",
+                "submodule.recurse=false",
+                ...args,
+            ],
+            cwd: ".",
+            env: gitEnvironment,
+        }, { timeoutMs: remaining, maxOutputBytes: bytes });
+        bytes -=
+            Buffer.byteLength(result.stdout) + Buffer.byteLength(result.stderr);
+        if (result.exitCode !== 0 ||
+            result.signal ||
+            result.errorCode ||
+            result.timedOut ||
+            result.cancelled ||
+            result.truncated ||
+            result.stderr.trim())
+            throw new Error("Git inspection was not conclusive");
+        return result.stdout;
+    };
+}
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const oid = (value) => {
+    const hash = value.trim();
+    if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(hash))
+        throw new Error("Invalid Git object identity");
+    return hash;
+};
+function entries(output, index) {
+    if (output && !output.endsWith("\0"))
+        throw new Error("Unterminated Git evidence");
+    const result = new Map();
+    for (const entry of output.split("\0").filter(Boolean)) {
+        const match = (index
+            ? /^(100644|100755) ([a-f0-9]{40}|[a-f0-9]{64}) 0\t([^]*)$/
+            : /^(100644|100755) blob ([a-f0-9]{40}|[a-f0-9]{64})\t([^]*)$/).exec(entry);
+        if (!match)
+            throw new Error("Unsupported Git entry or unresolved merge");
+        const file = match[3];
+        if (!file ||
+            path.posix.isAbsolute(file) ||
+            file.split("/").some((part) => !part || part === "." || part === "..") ||
+            result.has(file))
+            throw new Error("Ambiguous Git path");
+        result.set(file, { mode: match[1], hash: match[2] });
+        if (result.size > 20_000)
+            throw new Error("Git entry limit exceeded");
+    }
+    return result;
+}
+function differences(a, b, target) {
+    for (const key of new Set([...a.keys(), ...b.keys()]))
+        if (a.get(key)?.hash !== b.get(key)?.hash ||
+            a.get(key)?.mode !== b.get(key)?.mode)
+            target.add(key);
+}
+export async function selectGitChanges(source, projects, base, workspace) {
+    const full = {
+        mode: "full",
+        reason: "Git change scope could not be established; retaining the full configured plan.",
+        changedFiles: [],
+        selectedProjects: [...new Set(projects)].sort(),
+    };
+    try {
+        if (!base || base.length > 1024 || base.includes("\0"))
+            return full;
+        const read = gitReader(source.root);
+        const top = (await read(["rev-parse", "--show-toplevel"])).trimEnd();
+        if ((await realpath(top)) !== source.root)
+            return {
+                ...full,
+                reason: "The configured root is not the Git worktree root.",
+            };
+        const version = (await read(["--version"])).trim();
+        if (!/^git version \d+\.\d+\.\d+[^\n]*$/.test(version))
+            return full;
+        const headCommit = oid(await read([
+            "rev-parse",
+            "--verify",
+            "--end-of-options",
+            "HEAD^{commit}",
+        ]));
+        const baseCommit = oid(await read([
+            "rev-parse",
+            "--verify",
+            "--end-of-options",
+            `${base}^{commit}`,
+        ]));
+        const baseTree = entries(await read(["ls-tree", "-rz", "--full-tree", baseCommit]), false);
+        const headTree = entries(await read(["ls-tree", "-rz", "--full-tree", headCommit]), false);
+        const indexOutput = await read(["ls-files", "--stage", "-z"]);
+        const index = entries(indexOutput, true);
+        const identity = {
+            baseCommit,
+            headCommit,
+            version,
+            worktreeId: digest(source.root),
+            indexFingerprint: digest(indexOutput),
+        };
+        full.git = identity;
+        const files = new Set(source.files);
+        if ([...index.keys()].some((file) => !files.has(file) &&
+            source.excluded.some((excluded) => file === excluded || file.startsWith(`${excluded}/`))))
+            return {
+                ...full,
+                reason: "Tracked excluded content prevents complete working-tree comparison.",
+            };
+        const changed = new Set();
+        differences(baseTree, headTree, changed);
+        differences(headTree, index, changed);
+        let size = 0;
+        const working = new Map();
+        for (const file of source.files) {
+            const resolved = await withinRoot(source.root, file);
+            const stat = await lstat(resolved);
+            size += stat.size;
+            if (!stat.isFile() ||
+                stat.size > 8 * 1024 * 1024 ||
+                size > 64 * 1024 * 1024)
+                return full;
+            const bytes = await readFile(resolved);
+            const hash = createHash(headCommit.length === 40 ? "sha1" : "sha256")
+                .update(`blob ${bytes.length}\0`)
+                .update(bytes)
+                .digest("hex");
+            working.set(file, {
+                mode: stat.mode & 0o111 ? "100755" : "100644",
+                hash,
+            });
+        }
+        differences(index, working, changed);
+        if (oid(await read([
+            "rev-parse",
+            "--verify",
+            "--end-of-options",
+            "HEAD^{commit}",
+        ])) !== headCommit ||
+            digest(await read(["ls-files", "--stage", "-z"])) !==
+                identity.indexFingerprint)
+            return full;
+        const changedFiles = [...changed].sort();
+        const impact = affectedProjects(projects, changedFiles, workspace);
+        return {
+            mode: impact.affected ? "affected" : "full",
+            reason: impact.reason,
+            changedFiles,
+            selectedProjects: impact.projects,
+            git: identity,
+        };
+    }
+    catch {
+        return full;
+    }
+}
+export async function verifyGitIdentity(root, identity) {
+    try {
+        const read = gitReader(root);
+        const head = oid(await read([
+            "rev-parse",
+            "--verify",
+            "--end-of-options",
+            "HEAD^{commit}",
+        ]));
+        const index = digest(await read(["ls-files", "--stage", "-z"]));
+        return head === identity.headCommit && index === identity.indexFingerprint
+            ? "same"
+            : "changed";
+    }
+    catch {
+        return "error";
+    }
+}

package/dist/src/go-directives.d.ts

@@ -0,0 +1 @@
+export declare function hasGoSuppression(source: string): boolean;

package/dist/src/go-directives.js

@@ -0,0 +1,32 @@
+export function hasGoSuppression(source) {
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i];
+        if (char === '"' || char === "'" || char === "`") {
+            for (i++; i < source.length; i++) {
+                if (source[i] === char)
+                    break;
+                if (char !== "`" && source[i] === "\\")
+                    i++;
+            }
+        }
+        else if (char === "/" && source[i + 1] === "/") {
+            const end = source.indexOf("\n", i);
+            const text = source
+                .slice(i, end === -1 ? source.length : end)
+                .replace(/\r/g, "")
+                .replace(/^[ /]+/, "");
+            if (/^(?:nolint(?: |:|$)|lint:(?:ignore|file-ignore)(?: |$))/.test(text))
+                return true;
+            if (end === -1)
+                break;
+            i = end;
+        }
+        else if (char === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            if (end === -1)
+                break;
+            i = end + 1;
+        }
+    }
+    return false;
+}

package/dist/src/go-scope.d.ts

@@ -0,0 +1,11 @@
+import type { Check, Command, ProcessResult } from "./types.js";
+export declare const goEnvironment: {
+    GOPROXY: string;
+    GOTOOLCHAIN: string;
+    GOFLAGS: string;
+    GOWORK: string;
+    GOENV: string;
+    GOCACHEPROG: string;
+};
+export declare function goScopeCommand(project: string, env?: Record<string, string>): Command;
+export declare function goScopeComplete(check: Check, process: ProcessResult | undefined, root: string | undefined, testOutput?: string): boolean;

package/dist/src/go-scope.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { z } from "zod";
+export const goEnvironment = {
+    GOPROXY: "off",
+    GOTOOLCHAIN: "local",
+    GOFLAGS: "-mod=readonly",
+    GOWORK: "off",
+    GOENV: "off",
+    GOCACHEPROG: "",
+};
+export function goScopeCommand(project, env = goEnvironment) {
+    return {
+        executable: "go",
+        args: ["list", "-json", "./..."],
+        cwd: project,
+        env,
+    };
+}
+function objects(text) {
+    const result = [];
+    let depth = 0, start = 0, quoted = false, escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (!depth && char?.trim() && char !== "{")
+            throw new Error("Unexpected package output");
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                quoted = false;
+        }
+        else if (char === '"')
+            quoted = true;
+        else if (char === "{") {
+            if (!depth)
+                start = i;
+            depth++;
+        }
+        else if (char === "}") {
+            depth--;
+            if (!depth)
+                result.push(JSON.parse(text.slice(start, i + 1)));
+            if (depth < 0)
+                throw new Error("Invalid package JSON");
+        }
+        else if (!depth && char?.trim())
+            throw new Error("Unexpected package output");
+    }
+    if (depth || quoted)
+        throw new Error("Partial package output");
+    return result;
+}
+const names = z.array(z.string()).default([]);
+const packageSchema = z.object({
+    Dir: z.string(),
+    ImportPath: z.string().min(1),
+    GoFiles: names,
+    CgoFiles: names,
+    TestGoFiles: names,
+    XTestGoFiles: names,
+    Error: z.unknown().optional(),
+    DepsErrors: z.array(z.unknown()).optional(),
+});
+export function goScopeComplete(check, process, root, testOutput) {
+    if (!root ||
+        !process ||
+        process.exitCode !== 0 ||
+        process.stderr.trim() ||
+        !check.scope.length)
+        return false;
+    try {
+        const packages = objects(process.stdout).map((value) => packageSchema.parse(value));
+        const expected = new Set(check.scope.map((file) => path.resolve(root, check.project, file)));
+        const seen = new Set();
+        const ids = new Set();
+        for (const item of packages) {
+            if (!path.isAbsolute(item.Dir) ||
+                ids.has(item.ImportPath) ||
+                item.Error ||
+                item.DepsErrors?.length)
+                return false;
+            ids.add(item.ImportPath);
+            for (const file of [
+                ...item.GoFiles,
+                ...item.CgoFiles,
+                ...item.TestGoFiles,
+                ...item.XTestGoFiles,
+            ]) {
+                if (path.basename(file) !== file || !file.endsWith(".go"))
+                    return false;
+                const resolved = path.resolve(item.Dir, file);
+                if (!expected.has(resolved) || seen.has(resolved))
+                    return false;
+                seen.add(resolved);
+            }
+        }
+        if (testOutput !== undefined) {
+            const tested = new Set();
+            for (const line of testOutput.split("\n").filter(Boolean)) {
+                const event = z
+                    .object({
+                    Action: z.string(),
+                    Package: z.string(),
+                    Test: z.string().optional(),
+                })
+                    .parse(JSON.parse(line));
+                if (!ids.has(event.Package))
+                    return false;
+                if (event.Action === "pass" && event.Test)
+                    tested.add(event.Package);
+            }
+            if (tested.size !== ids.size)
+                return false;
+        }
+        return ids.size > 0 && seen.size === expected.size;
+    }
+    catch {
+        return false;
+    }
+}

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

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