@intentius/chant 0.4.0 → 0.5.0

package/src/cli/commands/audit.ts

@@ -0,0 +1,352 @@
+/**
+ * `chant audit` — run chant's CI security 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, readdirSync, statSync, writeFileSync } from "fs";
+import { join, relative } from "path";
+import { auditFiles, type AuditInput, type AuditFinding, type AuditLexicon, type ChecksProvider } from "../../audit/core";
+import { RULE_CATALOG } from "../../audit/catalog";
+import { renderMarkdown } from "../../audit/report";
+import { renderHtml, type ReportTheme } from "../../audit/report-html";
+import { buildReportJson, type AuditSnapshot } from "../../audit/report-model";
+import { fetchCiFiles, resolveActionSha, resolveImageDigest, resolveRepoCommit, parseRepoUrl, FetchError } from "../../audit/fetch";
+import { extractUnpinnedActions, extractUnpinnedImages } from "../../audit/proof";
+import type { ProveOptions } from "../../audit/proof";
+import type { Severity } from "../../lint/rule";
+
+export type AuditFormat = "stylish" | "json" | "sarif" | "markdown" | "html";
+export type AuditTier = "merge-worthy" | "all";
+export type AuditFailOn = "merge-worthy" | "warning" | "none";
+
+export interface AuditCommandOptions {
+  /** Repo root/dir to scan, or an https:// repo URL to fetch and audit. */
+  path: string;
+  format?: AuditFormat;
+  /** Restrict findings to a tier (default "all"). */
+  tier?: AuditTier;
+  /** Exit-code policy (default "none" — read-only friendly). */
+  failOn?: AuditFailOn;
+  /** Server-side token for remote fetch (defaults to env). */
+  token?: string;
+  /** Injectable fetch for testing remote audits. */
+  fetchImpl?: typeof fetch;
+  /** Write the rendered report to this file instead of returning it for stdout. */
+  output?: string;
+  /** Injectable post-synth checks provider (testing). */
+  checksProvider?: ChecksProvider;
+  /** HTML report: theme knobs (title, logo, accent, footer). */
+  theme?: ReportTheme;
+  /** HTML report: full template override. */
+  template?: string;
+  /** Snapshot timestamp (ISO); defaults to now. Injectable for deterministic output. */
+  now?: string;
+  /** Tool version recorded in the HTML snapshot. */
+  toolVersion?: string;
+}
+
+export interface AuditCommandResult {
+  success: boolean;
+  /** Rendered report in the requested format. */
+  output: string;
+  findings: AuditFinding[];
+  /** Files that were scanned (relative to the root). */
+  scanned: string[];
+  exitCode: number;
+  error?: string;
+  /** Set when the report was written to a file (via `output`). */
+  wroteTo?: string;
+}
+
+/**
+ * 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: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  let host: string;
+  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: NodeJS.ProcessEnv = process.env): string | undefined {
+  return env.GITHUB_TOKEN ?? env.CHANT_AUDIT_GITHUB_TOKEN;
+}
+
+function isYaml(name: string): boolean {
+  return name.endsWith(".yml") || name.endsWith(".yaml");
+}
+
+function collectDir(root: string, dir: string, lexicon: AuditLexicon, out: AuditInput[]): void {
+  const abs = join(root, dir);
+  if (!existsSync(abs) || !statSync(abs).isDirectory()) return;
+  for (const name of readdirSync(abs).sort()) {
+    if (!isYaml(name)) continue;
+    const full = join(abs, name);
+    if (!statSync(full).isFile()) continue;
+    out.push({ path: relative(root, full), content: readFileSync(full, "utf-8"), lexicon });
+  }
+}
+
+/** Discover CI files under a repo root. */
+export function discoverCiFiles(root: string): AuditInput[] {
+  const inputs: AuditInput[] = [];
+  collectDir(root, ".github/workflows", "github", inputs);
+  collectDir(root, ".forgejo/workflows", "forgejo", inputs);
+  const gitlab = join(root, ".gitlab-ci.yml");
+  if (existsSync(gitlab) && statSync(gitlab).isFile()) {
+    inputs.push({ path: ".gitlab-ci.yml", content: readFileSync(gitlab, "utf-8"), lexicon: "gitlab" });
+  }
+  return inputs;
+}
+
+function isMergeWorthy(f: AuditFinding): boolean {
+  return RULE_CATALOG[f.checkId]?.tier === "merge-worthy";
+}
+
+function exitCodeFor(findings: AuditFinding[], failOn: AuditFailOn): number {
+  if (failOn === "merge-worthy") return findings.some(isMergeWorthy) ? 1 : 0;
+  if (failOn === "warning") {
+    return findings.some((f) => f.severity === "error" || f.severity === "warning") ? 1 : 0;
+  }
+  return 0;
+}
+
+function sarifLevel(sev: Severity): string {
+  return sev === "error" ? "error" : sev === "warning" ? "warning" : "note";
+}
+
+/** Coverage caveats about what the audit could and couldn't see. */
+export function coverageNotes(inputs: AuditInput[]): string[] {
+  const notes: string[] = [];
+  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: AuditFinding[], scanned: string[], notes: string[]): string {
+  const lines: string[] = [];
+  for (const note of notes) lines.push(`Note: ${note}`);
+  if (notes.length > 0) lines.push("");
+  const mw = findings.filter(isMergeWorthy);
+  const ro = findings.filter((f) => !isMergeWorthy(f));
+  lines.push(
+    `Audited ${scanned.length} CI file${scanned.length === 1 ? "" : "s"} — ` +
+      `${findings.length} finding${findings.length === 1 ? "" : "s"} ` +
+      `(${mw.length} merge-worthy, ${ro.length} report-only).`,
+  );
+  const section = (title: string, list: AuditFinding[]) => {
+    if (list.length === 0) return;
+    lines.push("", title);
+    for (const f of list) {
+      const where = f.entity ? `${f.file} (${f.entity})` : f.file;
+      const title = RULE_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");
+}
+
+function renderSarif(findings: AuditFinding[]): string {
+  const ruleIds = [...new Set(findings.map((f) => f.checkId))].sort();
+  const rules = ruleIds.map((id) => {
+    const m = RULE_CATALOG[id];
+    return {
+      id,
+      name: m?.title ?? id,
+      shortDescription: { text: m?.title ?? id },
+      helpUri: m?.authority?.[0]?.url,
+    };
+  });
+  const results = findings.map((f) => ({
+    ruleId: f.checkId,
+    level: sarifLevel(f.severity),
+    message: { text: f.message },
+    locations: [{ physicalLocation: { artifactLocation: { uri: f.file } } }],
+  }));
+  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: AuditCommandOptions, files: string[], isUrl: boolean): Promise<AuditSnapshot> {
+  let host: string | undefined;
+  let repo: string | undefined;
+  let commit: string | undefined;
+  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",
+  };
+}
+
+/** Run the audit and produce a rendered result. */
+export async function auditCommand(options: AuditCommandOptions): Promise<AuditCommandResult> {
+  const format = options.format ?? "stylish";
+  const tier = options.tier ?? "all";
+  const failOn = options.failOn ?? "none";
+
+  const isUrl = /^https?:\/\//.test(options.path);
+
+  let inputs: AuditInput[];
+  if (isUrl) {
+    try {
+      inputs = await fetchCiFiles(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}` };
+    }
+    inputs = discoverCiFiles(options.path);
+  }
+
+  const scanned = inputs.map((i) => i.path);
+
+  if (inputs.length === 0) {
+    return { success: true, output: `No CI files found under ${options.path}.`, findings: [], scanned: [], exitCode: 0 };
+  }
+
+  let findings: AuditFinding[];
+  try {
+    findings = await auditFiles(inputs, { checksProvider: options.checksProvider });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { success: false, output: "", findings: [], scanned, exitCode: 1, error: msg };
+  }
+  if (tier === "merge-worthy") findings = findings.filter(isMergeWorthy);
+  const notes = coverageNotes(inputs);
+
+  // Diff-bearing renderers (markdown, html) need action SHAs / image digests
+  // resolved up front (sync maps so rendering stays synchronous).
+  let resolveSha: ProveOptions["resolveSha"];
+  let resolveDigest: ProveOptions["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<string, { action: string; ref: string }>();
+    const images = new Set<string>();
+    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] as [string, string | undefined];
+        }),
+      ),
+      Promise.all(
+        [...images].map(async (img) => {
+          const digest = await resolveImageDigest(img, { fetchImpl: options.fetchImpl });
+          return [img, digest] as [string, string | undefined];
+        }),
+      ),
+    ]);
+    const shaMap = new Map<string, string>();
+    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<string, string>();
+    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: string;
+  switch (format) {
+    case "json": {
+      const snapshot = await buildSnapshot(options, scanned, isUrl);
+      output = JSON.stringify(buildReportJson(findings, { snapshot, toolVersion: options.toolVersion }), null, 2);
+      break;
+    }
+    case "sarif":
+      output = renderSarif(findings);
+      break;
+    case "markdown":
+      output = renderMarkdown(findings, { target: options.path, files, resolveSha, resolveDigest, notes });
+      break;
+    case "html": {
+      const snapshot = await buildSnapshot(options, scanned, isUrl);
+      output = renderHtml(findings, { files, resolveSha, resolveDigest, notes, snapshot, theme: options.theme, template: options.template });
+      break;
+    }
+    default:
+      output = renderStylish(findings, scanned, notes);
+  }
+
+  const exitCode = exitCodeFor(findings, failOn);
+  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, output, findings, scanned, exitCode, wroteTo: options.output };
+  }
+
+  return { success: true, output, findings, scanned, exitCode };
+}
+
+/** Print an audit result to stdout. */
+export function printAuditResult(result: AuditCommandResult): void {
+  if (!result.success) {
+    console.error(result.error ?? "Audit failed");
+    return;
+  }
+  if (result.wroteTo) {
+    console.error(`Wrote report to ${result.wroteTo}`);
+    return;
+  }
+  console.log(result.output);
+}

package/src/cli/handlers/misc.ts

@@ -1,9 +1,80 @@
 import { listCommand, printListResult } from "../commands/list";
 import { describeCommand, printDescribeResult } from "../commands/describe";
 import { importCommand, importFromLive, printImportResult } from "../commands/import";
+import { auditCommand, printAuditResult, type AuditFormat, type AuditTier, type AuditFailOn } from "../commands/audit";
+import type { ReportTheme } from "../../audit/report-html";
 import type { ResourceSelector } from "../../lexicon";
 import { formatError, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
+import { createRequire } from "module";
+
+const CHANT_VERSION: string = (() => {
+  try {
+    return createRequire(import.meta.url)("../../../package.json").version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const AUDIT_FORMATS: AuditFormat[] = ["stylish", "json", "sarif", "markdown", "html"];
+const AUDIT_TIERS: AuditTier[] = ["merge-worthy", "all"];
+const AUDIT_FAIL_ON: AuditFailOn[] = ["merge-worthy", "warning", "none"];
+
+export async function runAudit(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+
+  const format: AuditFormat = args.json ? "json" : ((args.format || "stylish") as AuditFormat);
+  if (!AUDIT_FORMATS.includes(format)) {
+    console.error(formatError({ message: `Invalid --format: ${format}. Expected one of ${AUDIT_FORMATS.join(", ")}.` }));
+    return 1;
+  }
+  const tier = (args.tier ?? "all") as AuditTier;
+  if (!AUDIT_TIERS.includes(tier)) {
+    console.error(formatError({ message: `Invalid --tier: ${tier}. Expected one of ${AUDIT_TIERS.join(", ")}.` }));
+    return 1;
+  }
+  const failOn = (args.failOn ?? "none") as AuditFailOn;
+  if (!AUDIT_FAIL_ON.includes(failOn)) {
+    console.error(formatError({ message: `Invalid --fail-on: ${failOn}. Expected one of ${AUDIT_FAIL_ON.join(", ")}.` }));
+    return 1;
+  }
+
+  // HTML report customization: --template <file> (full override) + --theme <file> (JSON knobs).
+  let template: string | undefined;
+  let theme: ReportTheme | undefined;
+  if (format === "html") {
+    const { readFileSync } = await import("fs");
+    if (args.template) {
+      try {
+        template = readFileSync(args.template, "utf-8");
+      } catch (err) {
+        console.error(formatError({ message: `Failed to read --template ${args.template}: ${err instanceof Error ? err.message : String(err)}` }));
+        return 1;
+      }
+    }
+    if (args.theme) {
+      try {
+        theme = JSON.parse(readFileSync(args.theme, "utf-8")) as ReportTheme;
+      } catch (err) {
+        console.error(formatError({ message: `Failed to read --theme ${args.theme}: ${err instanceof Error ? err.message : String(err)}` }));
+        return 1;
+      }
+    }
+  }
+
+  const result = await auditCommand({
+    path: args.path,
+    format,
+    tier,
+    failOn,
+    output: args.output,
+    template,
+    theme,
+    toolVersion: CHANT_VERSION,
+  });
+  printAuditResult(result);
+  return result.exitCode;
+}
 
 export async function runList(ctx: CommandContext): Promise<number> {
   const { args } = ctx;

package/src/cli/main.ts

@@ -11,7 +11,7 @@ import { runLint } from "./handlers/lint";
 import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDevUnknown } from "./handlers/dev";
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
-import { runList, runDescribe, runImport, runUpdate, runDoctor } from "./handlers/misc";
+import { runList, runDescribe, runImport, runAudit, runUpdate, runDoctor } from "./handlers/misc";
 import { runVendor } from "./handlers/vendor";
 import { runMigrate } from "./handlers/migrate";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
@@ -118,6 +118,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.src = args[++i];
     } else if (arg === "--env") {
       result.env = args[++i];
+    } else if (arg === "--tier") {
+      result.tier = args[++i];
+    } else if (arg === "--fail-on") {
+      result.failOn = args[++i];
+    } else if (arg === "--theme") {
+      result.theme = args[++i];
     } else if (arg === "--stacks") {
       result.stacks = true;
     } else if (arg === "--base") {
@@ -169,6 +175,10 @@ Commands:
   describe              Show the effective config for one component
   vendor                Pull pinned, checksummed patterns into your repo
   import                Import external template into TypeScript
+  audit [path|url]      Audit a repo's CI YAML for security issues
+                        (--format stylish|json|sarif|markdown|html, -o <file>,
+                         --tier merge-worthy|all, --fail-on merge-worthy|warning|none,
+                         --template <file> / --theme <file> for the html report)
   migrate <file>        Translate a workflow between lexicons
                         (default: --from github --to gitlab)
 
@@ -287,6 +297,7 @@ const registry: CommandDef[] = [
   { name: "list", handler: runList },
   { name: "describe", handler: runDescribe },
   { name: "import", handler: runImport },
+  { name: "audit", handler: runAudit },
   { name: "migrate", handler: runMigrate },
   { name: "init", handler: runInit },
   { name: "init lexicon", handler: runInitLexicon },

package/src/cli/registry.ts

@@ -63,6 +63,12 @@ export interface ParsedArgs {
   head?: string;
   /** `chant lifecycle affected --include-dependents` — add downstream consumers */
   includeDependents?: boolean;
+  /** `chant audit --tier merge-worthy|all` */
+  tier?: string;
+  /** `chant audit --fail-on merge-worthy|warning|none` */
+  failOn?: string;
+  /** `chant audit --theme <file>` — JSON theme knobs for the HTML report */
+  theme?: string;
 }
 
 /**