@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/commands/audit.js

@@ -0,0 +1,571 @@
+/**
+ * `chant audit` — run chant's security, correctness, and best-practice checks against an existing repo's
+ * pipeline YAML and emit a tiered report. Does not require a chant project;
+ * it reads `.github/workflows`, `.gitlab-ci.yml`, and `.forgejo/workflows`
+ * directly and runs the real post-synth checks via the audit core.
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { auditFiles } from "../../audit/core.js";
+import { AUDIT_LEXICONS, classifyFiles, loadAuditPlugins, unclaimedFiles, walkCandidates } from "../../audit/discover.js";
+import { RULE_CATALOG, resolveAuditCatalog } from "../../audit/catalog.js";
+import { scanForSecrets, parseSecretsConfig } from "../../audit/secrets.js";
+import { auditWranglerConfigs } from "../../audit/wrangler.js";
+import { auditNginxConfigs } from "../../audit/nginx.js";
+import { auditTerraformState } from "../../audit/terraform-state.js";
+import { workspaceMemberDirs } from "../../discovery/walk.js";
+import { renderMarkdown } from "../../audit/report.js";
+import { renderHtml } from "../../audit/report-html.js";
+import { buildReportJson, REPORT_SCHEMA_VERSION } from "../../audit/report-model.js";
+import { fetchRepoFiles, resolveActionSha, resolveImageDigest, resolveRepoCommit, parseRepoUrl, FetchError } from "../../audit/fetch.js";
+import { extractUnpinnedActions, extractUnpinnedImages } from "../../audit/proof.js";
+import { formatWarning } from "../format.js";
+import { lexiconPackagesToInstall, lexiconSourceLabel, pathLexiconMap, recordedLexiconModules } from "../../lexicon-module.js";
+import { readConfigFieldsStatically, readLexiconDeclarationsStatically, unknownPathLexiconsNotice } from "../../config-static.js";
+import { findProjectConfigPastFragments } from "../../config.js";
+/** Exit code when the audit had no lexicons to look with. Distinct from 1 (findings / failure). */
+export const NO_LEXICONS_EXIT_CODE = 2;
+/**
+ * What to tell the user about lexicons that did not load: an `npm i` line for
+ * the package-backed ones, and the declared path for any lexicon
+ * `chant.config.ts` names by path (#2520), which has no package to install
+ * (chant#2578).
+ */
+function missingLexiconRemedy(names, paths) {
+    const parts = [];
+    const pkgs = lexiconPackagesToInstall(names, paths);
+    if (pkgs.length > 0)
+        parts.push(`npm i ${pkgs.join(" ")}`);
+    for (const name of names) {
+        if (paths.has(name))
+            parts.push(`${name} is declared by path: ${lexiconSourceLabel(name, process.cwd(), paths)}`);
+    }
+    return parts.join("; ");
+}
+/**
+ * The rule ids the audited project enables with `lint.rules` (anything but
+ * `"off"`), read from its config without running it, the way the audit reads
+ * its lexicon paths. Only a check marked `auditOptIn` consults this (#3190).
+ * A config that cannot be read statically enables nothing.
+ */
+export function readEnabledRules(path) {
+    const enabled = new Set();
+    try {
+        const read = readConfigFieldsStatically(findProjectConfigPastFragments(path).dir, ["lint"]);
+        const rules = read.status === "read" ? read.fields.lint?.rules : undefined;
+        if (typeof rules !== "object" || rules === null)
+            return enabled;
+        for (const [id, value] of Object.entries(rules)) {
+            const severity = Array.isArray(value) ? value[0] : value;
+            if (severity !== "off")
+                enabled.add(id);
+        }
+    }
+    catch {
+        // an unreadable config enables nothing
+    }
+    return enabled;
+}
+/**
+ * chant#2589 — the lexicons a local target's chant.config declares by path,
+ * with any recorded earlier in this process. The config is read statically
+ * (../../config-static.ts) and never evaluated, and the paths are not
+ * recorded for the loaders: audit names them in its messages, but never
+ * imports a project's lexicon module. `notice` is set when the config's
+ * `lexicons` could not be read that way.
+ */
+export function auditPathLexicons(target, isUrl) {
+    const paths = recordedLexiconModules();
+    if (isUrl)
+        return { paths };
+    const read = readLexiconDeclarationsStatically(resolve(target));
+    if (read.status === "read") {
+        for (const [name, path] of pathLexiconMap(read.entries, dirname(read.configPath)))
+            paths.set(name, path);
+    }
+    return { paths, notice: unknownPathLexiconsNotice(read) };
+}
+/** Missing audit lexicons the unclaimed files pointed at, in first-seen order. */
+function wantedLexicons(unclaimed) {
+    return [...new Set(unclaimed.map((u) => u.lexicon))];
+}
+/**
+ * The exact one-liner that gives a bare `npx @intentius/chant audit` the
+ * lexicons it needs. Every wanted lexicon is a `-p` package so npx puts all of
+ * them on the same resolution path.
+ */
+export function installLine(lexicons, target, paths = recordedLexiconModules()) {
+    // chant#2578 — a lexicon declared by path has no package for npx to fetch.
+    const pkgs = ["@intentius/chant", ...lexiconPackagesToInstall(lexicons, paths)];
+    return `npx ${pkgs.map((p) => `-p ${p}`).join(" ")} chant audit ${target}`;
+}
+/** One-line coverage hint for the partial case: some lexicons loaded, others wanted by files on disk. */
+function missingLexiconHint(unclaimed, paths) {
+    const wanted = wantedLexicons(unclaimed);
+    if (wanted.length === 0)
+        return undefined;
+    const n = unclaimed.length;
+    return `${n} file${n === 1 ? " looks" : "s look"} like ${wanted.join("/")} but ${wanted.length === 1 ? "that lexicon is" : "those lexicons are"} not installed, so ${n === 1 ? "it was" : "they were"} skipped` +
+        ` (${missingLexiconRemedy(wanted, paths)}).`;
+}
+/** Human-readable diagnostic for the zero-lexicon case. */
+function renderNoLexicons(target, unclaimed, paths, truncated) {
+    const lines = [];
+    lines.push(`chant audit had nothing to look with: no audit lexicon is installed, so nothing under ${target} was inspected.`);
+    lines.push("This is not a clean result. Detection and checks live in the lexicon packages.");
+    if (truncated)
+        lines.push("", `Note: ${truncationNote(truncated, target)}`);
+    const wanted = wantedLexicons(unclaimed);
+    if (unclaimed.length > 0) {
+        lines.push("", "Files that wanted a lexicon:");
+        for (const u of unclaimed) {
+            lines.push(`  ${u.path}  ->  ${u.lexicon}`);
+        }
+    }
+    else {
+        lines.push("", "No file under the target looked like CI, Kubernetes, Helm, Docker, CloudFormation, ARM, Config Connector, fountain, or Terraform either.");
+    }
+    lines.push("", "Run it with the lexicons those files need:");
+    const lexicons = wanted.length > 0 ? wanted : [...AUDIT_LEXICONS];
+    lines.push(`  ${installLine(lexicons, target, paths)}`);
+    // chant#2589 — a lexicon declared by path is left out of the line above.
+    for (const name of lexicons) {
+        if (paths.has(name))
+            lines.push(`  (${name} is declared by path: ${lexiconSourceLabel(name, process.cwd(), paths)})`);
+    }
+    return lines.join("\n");
+}
+/** Machine-readable form of the zero-lexicon diagnostic (`status: "no-lexicons"`). */
+function renderNoLexiconsJson(target, unclaimed, paths, truncated) {
+    const wanted = wantedLexicons(unclaimed);
+    return JSON.stringify({
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        tool: { name: "chant-audit" },
+        status: "no-lexicons",
+        target,
+        summary: { total: 0 },
+        findings: [],
+        unclaimed,
+        missingLexicons: wanted,
+        install: installLine(wanted.length > 0 ? wanted : [...AUDIT_LEXICONS], target, paths),
+        truncated,
+    }, null, 2);
+}
+/**
+ * Select the fetch token for a repo host. Tokens are host-specific — a GitHub
+ * PAT sent to GitLab/Codeberg is rejected (401) — so we never cross hosts.
+ */
+export function tokenForHost(url, env = process.env) {
+    let host;
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    switch (host) {
+        case "gitlab.com":
+            return env.GITLAB_TOKEN ?? env.CHANT_AUDIT_GITLAB_TOKEN;
+        case "codeberg.org":
+            return env.CODEBERG_TOKEN ?? env.CHANT_AUDIT_CODEBERG_TOKEN;
+        case "github.com":
+            return env.GITHUB_TOKEN ?? env.CHANT_AUDIT_GITHUB_TOKEN;
+        default:
+            return undefined;
+    }
+}
+/** GitHub token used for action-SHA resolution (always queries api.github.com). */
+function githubToken(env = process.env) {
+    return env.GITHUB_TOKEN ?? env.CHANT_AUDIT_GITHUB_TOKEN;
+}
+function isMergeWorthy(f, catalog = RULE_CATALOG) {
+    return catalog[f.checkId]?.tier === "merge-worthy";
+}
+function exitCodeFor(findings, failOn, catalog = RULE_CATALOG) {
+    if (failOn === "merge-worthy")
+        return findings.some((f) => isMergeWorthy(f, catalog)) ? 1 : 0;
+    if (failOn === "warning") {
+        return findings.some((f) => f.severity === "error" || f.severity === "warning") ? 1 : 0;
+    }
+    if (failOn === "error")
+        return findings.some((f) => f.severity === "error") ? 1 : 0;
+    return 0;
+}
+function sarifLevel(sev) {
+    return sev === "error" ? "error" : sev === "warning" ? "warning" : "note";
+}
+/** `.chant-audit.json`'s `secrets` section at the local target root, if present (tolerant of a missing/malformed file). */
+function readLocalSecretsConfig(root) {
+    const file = join(root, ".chant-audit.json");
+    if (!existsSync(file))
+        return {};
+    try {
+        return parseSecretsConfig(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge the local `.chant-audit.json` config under any explicitly-passed options (options win). */
+function resolveSecretsOptions(fileConfig, explicit) {
+    return {
+        entropyThreshold: explicit?.entropyThreshold ?? fileConfig.entropyThreshold,
+        entropyMinLength: explicit?.entropyMinLength ?? fileConfig.entropyMinLength,
+        allow: [...(fileConfig.allow ?? []), ...(explicit?.allow ?? [])],
+    };
+}
+/** Coverage caveats about what the audit could and couldn't see. */
+export function coverageNotes(inputs) {
+    const notes = [];
+    const withIncludes = inputs.filter((i) => i.lexicon === "gitlab" && /^include:/m.test(i.content)).length;
+    if (withIncludes > 0) {
+        notes.push(`${withIncludes} GitLab pipeline${withIncludes === 1 ? " uses" : "s use"} \`include:\` — included files are not fetched, so findings cover the root file only.`);
+    }
+    return notes;
+}
+function renderStylish(findings, scanned, notes, catalog = RULE_CATALOG) {
+    const lines = [];
+    for (const note of notes)
+        lines.push(`Note: ${note}`);
+    if (notes.length > 0)
+        lines.push("");
+    const mw = findings.filter((f) => isMergeWorthy(f, catalog));
+    const ro = findings.filter((f) => !isMergeWorthy(f, catalog));
+    lines.push(`Audited ${scanned.length} file${scanned.length === 1 ? "" : "s"} — ` +
+        `${findings.length} finding${findings.length === 1 ? "" : "s"} ` +
+        `(${mw.length} merge-worthy, ${ro.length} report-only).`);
+    const section = (title, list) => {
+        if (list.length === 0)
+            return;
+        lines.push("", title);
+        for (const f of list) {
+            const loc = f.line ? `${f.file}:${f.line}` : f.file;
+            // A `missing` finding (chant #2113) has nothing present to anchor
+            // `entity` to. The whole point is that `f.missing.kind` does not
+            // exist in `f.missing.scope`, so it renders that absence directly
+            // instead of falling back to `entity` (which such a check rarely sets).
+            const where = f.missing
+                ? `${loc} (missing ${f.missing.kind} in ${f.missing.scope})`
+                : f.entity
+                    ? `${loc} (${f.entity})`
+                    : loc;
+            const title = catalog[f.checkId]?.title ?? f.checkId;
+            lines.push(`  [${f.checkId}] ${f.severity}  ${where}  — ${title}`);
+        }
+    };
+    section("Merge-worthy:", mw);
+    section("Report-only:", ro);
+    return lines.join("\n");
+}
+/**
+ * SARIF (2.1.0) export (#442). Rule-level metadata — category (the finding
+ * "dimension": security/correctness/best-practice) and remediation — is
+ * carried in the property bag / `help` block since SARIF's core schema has no
+ * dedicated slot for either; `tier` is per-result (a `RuleMeta` fact looked up
+ * per finding) so consumers can triage merge-worthy vs. report-only without a
+ * second catalog lookup.
+ */
+function renderSarif(findings, catalog = RULE_CATALOG) {
+    const ruleIds = [...new Set(findings.map((f) => f.checkId))].sort();
+    const rules = ruleIds.map((id) => {
+        const m = catalog[id];
+        return {
+            id,
+            name: m?.title ?? id,
+            shortDescription: { text: m?.title ?? id },
+            ...(m?.remediation ? { help: { text: m.remediation } } : {}),
+            helpUri: m?.authority?.[0]?.url,
+            // `priorArt` credits the upstream tools whose rules check the same thing
+            // (audit/prior-art.ts) — tool key, upstream rule id, doc URL, relation.
+            ...(m?.category || m?.lineage?.length
+                ? {
+                    properties: {
+                        ...(m?.category ? { category: m.category, dimension: m.category } : {}),
+                        ...(m?.lineage?.length ? { priorArt: m.lineage } : {}),
+                    },
+                }
+                : {}),
+        };
+    });
+    const results = findings.map((f) => {
+        const tier = catalog[f.checkId]?.tier;
+        const properties = { ...(tier ? { tier } : {}), ...(f.missing ? { missing: f.missing } : {}) };
+        return {
+            ruleId: f.checkId,
+            level: sarifLevel(f.severity),
+            message: { text: f.message },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: { uri: f.file },
+                        ...(f.line ? { region: { startLine: f.line } } : {}),
+                    },
+                },
+            ],
+            // `f.missing` (chant #2113) is Snyk policy-engine's "missing-resource"
+            // archetype: nothing at `f.file` actually declares the absent thing, so
+            // there is no line to point SARIF's region at either. `missing` rides
+            // in the property bag (SARIF's core schema has no dedicated slot for an
+            // absence finding) rather than pretending a region exists.
+            ...(Object.keys(properties).length > 0 ? { properties } : {}),
+        };
+    });
+    return JSON.stringify({
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [{ tool: { driver: { name: "chant-audit", informationUri: "https://intentius.io/chant/", rules } }, results }],
+    }, null, 2);
+}
+/** Build a provenance snapshot of what was audited (for the HTML report). */
+async function buildSnapshot(options, files, isUrl) {
+    let host;
+    let repo;
+    let commit;
+    if (isUrl) {
+        try {
+            host = new URL(options.path).hostname;
+            const parsed = parseRepoUrl(options.path);
+            repo = `${parsed.owner}/${parsed.repo}`;
+        }
+        catch {
+            // leave host/repo undefined
+        }
+        commit = await resolveRepoCommit(options.path, { token: options.token ?? tokenForHost(options.path), fetchImpl: options.fetchImpl });
+    }
+    else {
+        host = "local";
+    }
+    return {
+        target: options.path,
+        host,
+        repo,
+        commit,
+        files,
+        generatedAt: options.now ?? new Date().toISOString(),
+        toolVersion: options.toolVersion ?? "0.0.0",
+    };
+}
+/** The flag that raises the local walk's file limit, named wherever a truncated scan is reported. */
+export const MAX_FILES_FLAG = "--max-files";
+/** The truncation a walk reports, or undefined for a whole scan. */
+export function walkTruncation(walk) {
+    return walk.truncated ? { limit: walk.maxFiles, flag: MAX_FILES_FLAG } : undefined;
+}
+/** The text-report note for a truncated scan. */
+export function truncationNote(t, target) {
+    return (`The scan of ${target} stopped at ${t.limit} files, so part of the tree was not audited. ` +
+        `The limit counts every file the walk reaches, not only the ones it audits. Raise it with ${t.flag} <n>.`);
+}
+/** Run the audit and produce a rendered result. */
+export async function auditCommand(options) {
+    const format = options.format ?? "stylish";
+    const tier = options.tier ?? "all";
+    const failOn = options.failOn ?? "none";
+    const isUrl = /^https?:\/\//.test(options.path);
+    // chant#2589 — path lexicons the target declares, read without running its config.
+    const pathLexicons = auditPathLexicons(options.path, isUrl);
+    // Detection lives in the lexicon plugins (each one's `detectTemplate`), so a
+    // lexicon that isn't installed can't claim its files. Every branch below
+    // therefore also computes which candidate files looked like they wanted an
+    // absent lexicon, so "nothing found" and "had nothing to look with" never
+    // render the same way (#1623).
+    const plugins = options.plugins ?? (await loadAuditPlugins());
+    let candidates;
+    let truncated;
+    if (isUrl) {
+        try {
+            // Fetch the whole repo's candidate files (all lexicons, not just CI) and
+            // run them through the same classifier the local path uses (#420).
+            candidates = await fetchRepoFiles(options.path, {
+                token: options.token ?? tokenForHost(options.path),
+                fetchImpl: options.fetchImpl,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof FetchError ? err.message : err instanceof Error ? err.message : String(err);
+            return { success: false, output: "", findings: [], scanned: [], exitCode: 1, error: msg };
+        }
+    }
+    else {
+        if (!existsSync(options.path)) {
+            return { success: false, output: "", findings: [], scanned: [], exitCode: 1, error: `Path not found: ${options.path}` };
+        }
+        // One walk, plugin-delegated detection. CI (path), Dockerfiles (name), and
+        // Helm charts (bundle) are special-cased by the classifier since content
+        // shape alone can't disambiguate them.
+        // Workspace members leave the root's audit only when a declaration exists
+        // (#2525 rule 3); without one this is a few existsSync calls (#2527).
+        const excludeDirs = await workspaceMemberDirs(options.path);
+        const walk = walkCandidates(options.path, { maxFiles: options.maxFiles, excludeDirs });
+        candidates = walk.files;
+        truncated = walkTruncation(walk);
+    }
+    // Every format but SARIF states a truncated scan in the report itself
+    // (#2528). SARIF has no slot chant fills for it, so there it goes to stderr.
+    const warnings = truncated && format === "sarif" ? [{ message: truncationNote(truncated, options.path) }] : [];
+    if (pathLexicons.notice !== undefined)
+        warnings.push({ message: pathLexicons.notice });
+    const withWarnings = warnings.length > 0 ? { warnings } : {};
+    // A local target hands its directory to the classifier, so an input whose
+    // path names a directory carries the directory itself (#2217): terraform's
+    // parse-to-graph follows a root module's local `module` calls from there. A
+    // URL target has no local tree, and never fetches `.tf` in the first place.
+    const inputs = classifyFiles(candidates, plugins, isUrl ? {} : { baseDir: options.path });
+    const unclaimed = unclaimedFiles(candidates, inputs, plugins);
+    const scanned = inputs.map((i) => i.path);
+    // Secrets detection (#443) is independent of lexicon: it scans every
+    // candidate file's raw text, not just the ones a lexicon claimed, and runs
+    // even when no lexicon is installed at all. `.chant-audit.json` at a local
+    // target's root supplies the entropy threshold / allowlist; a URL target
+    // has no local config file to read.
+    const secretsConfig = isUrl ? {} : readLocalSecretsConfig(options.path);
+    const secretsFindings = scanForSecrets(candidates, resolveSecretsOptions(secretsConfig, options.secretsScan));
+    // Wrangler config audit (#446) is likewise lexicon-independent: it scans
+    // every candidate file for `wrangler.toml` by its own detector, not through
+    // `classifyFiles`/an installed lexicon package (no such package exists —
+    // this format ships only a detector and checks, per the issue's scope).
+    const wranglerFindings = auditWranglerConfigs(candidates);
+    // nginx config audit (#1979) — same lexicon-independent shape as wrangler:
+    // its own path detector plus a parsed-content marker check (a `.conf` in a
+    // shared directory name like conf.d/ only counts once it parses as nginx).
+    const nginxFindings = auditNginxConfigs(candidates);
+    // TF023 (#2110) — committed Terraform state. Lexicon-independent for the
+    // same reason the three above are: it reads the discovered paths, not a
+    // parsed root module, so it fires with or without the terraform lexicon.
+    const terraformStateFindings = auditTerraformState(candidates);
+    if (plugins.length === 0) {
+        const output = format === "json"
+            ? renderNoLexiconsJson(options.path, unclaimed, pathLexicons.paths, truncated)
+            : renderNoLexicons(options.path, unclaimed, pathLexicons.paths, truncated);
+        return { success: true, status: "no-lexicons", output, findings: [...secretsFindings, ...wranglerFindings, ...nginxFindings, ...terraformStateFindings], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr", ...withWarnings };
+    }
+    const missingLexiconNote = missingLexiconHint(unclaimed, pathLexicons.paths);
+    if (inputs.length === 0 && secretsFindings.length === 0 && wranglerFindings.length === 0 && nginxFindings.length === 0 && terraformStateFindings.length === 0) {
+        let output = `No auditable files found under ${options.path}.${missingLexiconNote ? ` ${missingLexiconNote}` : ""}`;
+        if (truncated)
+            output += `\n\nNote: ${truncationNote(truncated, options.path)}`;
+        return { success: true, status: "ok", output, findings: [], scanned: [], unclaimed, exitCode: 0, ...withWarnings };
+    }
+    let findings = [];
+    // chant #2111: mutated in place by `auditFiles` so its inline (`# chant-
+    // ignore*`) suppressed count reaches the summary without changing
+    // `auditFiles`'s `AuditFinding[]` return type; see `SuppressionStats`'s doc.
+    const suppressionStats = { count: 0 };
+    if (inputs.length > 0) {
+        try {
+            findings = await auditFiles(inputs, {
+                checksProvider: options.checksProvider,
+                suppressionStats,
+                ...(isUrl ? {} : { enabledRules: readEnabledRules(options.path) }),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { success: false, output: "", findings: [], scanned, exitCode: 1, error: msg };
+        }
+    }
+    findings = [...findings, ...secretsFindings, ...wranglerFindings, ...nginxFindings, ...terraformStateFindings];
+    // Resolve the audit catalog once, aggregating the audited lexicons' own
+    // metadata over core's static catalog (#687). The lexicons are already loaded
+    // by `auditFiles` above, so this is cheap. Core's static catalog (always
+    // included) carries the SEC* secrets rules, so they resolve even when
+    // `inputs` claimed nothing.
+    const catalog = await resolveAuditCatalog([...new Set(inputs.map((i) => i.lexicon))]);
+    if (tier === "merge-worthy")
+        findings = findings.filter((f) => isMergeWorthy(f, catalog));
+    const notes = coverageNotes(inputs);
+    if (truncated)
+        notes.unshift(truncationNote(truncated, options.path));
+    if (missingLexiconNote)
+        notes.push(missingLexiconNote);
+    if (suppressionStats.count > 0) {
+        notes.push(`${suppressionStats.count} finding${suppressionStats.count === 1 ? "" : "s"} suppressed via inline chant-ignore comments.`);
+    }
+    // Diff-bearing renderers (markdown, html) need action SHAs / image digests
+    // resolved up front (sync maps so rendering stays synchronous).
+    let resolveSha;
+    let resolveDigest;
+    if (isUrl && (format === "markdown" || format === "html")) {
+        // Action SHAs always resolve against api.github.com, so use the GitHub
+        // token regardless of which host the repo lives on.
+        const token = githubToken();
+        const refs = new Map();
+        const images = new Set();
+        for (const inp of inputs) {
+            for (const a of extractUnpinnedActions(inp.content))
+                refs.set(`${a.action}@${a.ref}`, a);
+            for (const img of extractUnpinnedImages(inp.content))
+                images.add(img);
+        }
+        const [resolvedShas, resolvedDigests] = await Promise.all([
+            Promise.all([...refs.values()].map(async (a) => {
+                const sha = await resolveActionSha(a.action, a.ref, { token, fetchImpl: options.fetchImpl });
+                return [`${a.action}@${a.ref}`, sha];
+            })),
+            Promise.all([...images].map(async (img) => {
+                const digest = await resolveImageDigest(img, { fetchImpl: options.fetchImpl });
+                return [img, digest];
+            })),
+        ]);
+        const shaMap = new Map();
+        for (const [key, sha] of resolvedShas)
+            if (sha)
+                shaMap.set(key, sha);
+        if (shaMap.size > 0)
+            resolveSha = (action, ref) => shaMap.get(`${action}@${ref}`);
+        const digestMap = new Map();
+        for (const [img, digest] of resolvedDigests)
+            if (digest)
+                digestMap.set(img, digest);
+        if (digestMap.size > 0)
+            resolveDigest = (img) => digestMap.get(img);
+    }
+    const files = inputs.map((i) => ({ path: i.path, content: i.content }));
+    let output;
+    switch (format) {
+        case "json": {
+            const snapshot = await buildSnapshot(options, scanned, isUrl);
+            output = JSON.stringify(buildReportJson(findings, { snapshot, toolVersion: options.toolVersion, catalog, unclaimed, truncated }), null, 2);
+            break;
+        }
+        case "sarif":
+            output = renderSarif(findings, catalog);
+            break;
+        case "markdown":
+            output = renderMarkdown(findings, { target: options.path, files, resolveSha, resolveDigest, notes, catalog });
+            break;
+        case "html": {
+            const snapshot = await buildSnapshot(options, scanned, isUrl);
+            output = renderHtml(findings, { files, resolveSha, resolveDigest, notes, snapshot, theme: options.theme, template: options.template, catalog, truncated });
+            break;
+        }
+        default:
+            output = renderStylish(findings, scanned, notes, catalog);
+    }
+    const exitCode = exitCodeFor(findings, failOn, catalog);
+    if (options.output) {
+        try {
+            writeFileSync(options.output, output);
+        }
+        catch (err) {
+            return { success: false, output, findings, scanned, exitCode: 1, error: `Failed to write ${options.output}: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        return { success: true, status: "ok", output, findings, scanned, unclaimed, exitCode, wroteTo: options.output, suppressedCount: suppressionStats.count, ...withWarnings };
+    }
+    return { success: true, status: "ok", output, findings, scanned, unclaimed, exitCode, suppressedCount: suppressionStats.count, ...withWarnings };
+}
+/** Print an audit result to stdout, and its warnings to stderr. */
+export function printAuditResult(result) {
+    if (!result.success) {
+        console.error(result.error ?? "Audit failed");
+        return;
+    }
+    if (result.wroteTo)
+        console.error(`Wrote report to ${result.wroteTo}`);
+    else if (result.stream === "stderr")
+        console.error(result.output);
+    else
+        console.log(result.output);
+    for (const w of result.warnings ?? [])
+        console.error(formatWarning(w));
+}