@decohere/ci-tools 0.0.1-dev.42 → 0.0.1-dev.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/ci-tools",
-  "version": "0.0.1-dev.42",
+  "version": "0.0.1-dev.43",
   "description": "CI utility scripts for badge generation, coverage reporting, pages artifact assembly, and GitHub API tooling",
   "keywords": [
     "typescript",
@@ -22,9 +22,11 @@
     "./badges/ci-status": "./src/badges/ci-status.mjs",
     "./pages/artifact": "./src/pages/artifact.mjs",
     "./pages/smoke": "./src/pages/smoke.mjs",
+    "./audit/format": "./src/audit/format.mjs",
     "./audit/summarize": "./src/audit/summarize.mjs",
     "./audit/enforce": "./src/audit/enforce.mjs",
     "./audit/upsert-issue": "./src/audit/upsert-issue.mjs",
+    "./audit/upsert-clickup": "./src/audit/upsert-clickup.mjs",
     "./bench/bench": "./src/bench/bench.mjs",
     "./bench/trace": "./src/bench/trace.mjs",
     "./changeset/aggregate-changelog": "./src/changeset/aggregate-changelog.mjs",

package/src/audit/enforce.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { formatLog, highCritical, parseAudit } from "./format.mjs";
 
 const auditFilePath = process.argv[2] ?? "npm-audit.json";
 
@@ -10,12 +11,13 @@ try {
 	process.exit(1);
 }
 
-const vulnerabilities = data.metadata?.vulnerabilities ?? {};
-const high = vulnerabilities.high ?? 0;
-const critical = vulnerabilities.critical ?? 0;
+const parsed = parseAudit(data);
+const blocking = highCritical(parsed);
 
-if (high > 0 || critical > 0) {
-	console.error(`Security gate failed: high=${high}, critical=${critical}`);
+if (blocking.length > 0) {
+	console.error(
+		`Security gate failed: high=${parsed.high}, critical=${parsed.critical}\n${formatLog({ ...parsed, advisories: blocking })}`,
+	);
 	process.exit(1);
 }
 

package/src/audit/format.mjs

@@ -0,0 +1,133 @@
+/**
+ * Shared npm/pnpm audit JSON helpers.
+ *
+ * Supports pnpm's classic `{ advisories }` report and npm audit v2
+ * `{ auditReportVersion: 2, vulnerabilities }` (pnpm 9+/10).
+ */
+
+const SEVERITY_ORDER = ["critical", "high", "moderate", "low", "info"];
+
+function ghsaFromUrl(url) {
+	return typeof url === "string" ? (url.match(/GHSA-[a-z0-9-]+/i)?.[0] ?? "") : "";
+}
+
+function fromClassicAdvisories(data) {
+	return Object.values(data?.advisories ?? {}).map((raw) => {
+		const paths = (raw.findings ?? []).flatMap((f) => f.paths ?? []);
+		const url = raw.url ?? "";
+		return {
+			id: raw.id,
+			module: raw.module_name ?? "(unknown)",
+			severity: String(raw.severity ?? "info").toLowerCase(),
+			title: raw.title ?? "",
+			url,
+			vulnerable: raw.vulnerable_versions ?? "",
+			patched: raw.patched_versions ?? "",
+			cves: raw.cves ?? [],
+			ghsa: ghsaFromUrl(url),
+			paths: paths.slice(0, 3),
+		};
+	});
+}
+
+function fromNpmV2(data) {
+	const byKey = new Map();
+	for (const vuln of Object.values(data?.vulnerabilities ?? {})) {
+		const vias = Array.isArray(vuln.via) ? vuln.via : [];
+		for (const via of vias) {
+			if (via == null || typeof via !== "object") continue;
+			const url = via.url ?? "";
+			const key = url || `${via.name ?? vuln.name}:${via.title ?? ""}`;
+			const existing = byKey.get(key);
+			const node = Array.isArray(vuln.nodes) ? vuln.nodes[0] : undefined;
+			if (existing) {
+				if (node && existing.paths.length < 3 && !existing.paths.includes(node)) {
+					existing.paths.push(node);
+				}
+				continue;
+			}
+			byKey.set(key, {
+				id: via.source,
+				module: via.name ?? vuln.name ?? "(unknown)",
+				severity: String(via.severity ?? vuln.severity ?? "info").toLowerCase(),
+				title: via.title ?? "",
+				url,
+				vulnerable: via.range ?? vuln.range ?? "",
+				patched: "",
+				cves: [],
+				ghsa: ghsaFromUrl(url),
+				paths: node ? [node] : [],
+			});
+		}
+	}
+	return [...byKey.values()];
+}
+
+export function parseAudit(data) {
+	const counts = data?.metadata?.vulnerabilities ?? {};
+	const info = counts.info ?? 0;
+	const low = counts.low ?? 0;
+	const moderate = counts.moderate ?? 0;
+	const high = counts.high ?? 0;
+	const critical = counts.critical ?? 0;
+	const total = counts.total ?? info + low + moderate + high + critical;
+
+	const classic = data?.advisories != null && Object.keys(data.advisories).length > 0;
+	const advisories = classic ? fromClassicAdvisories(data) : fromNpmV2(data);
+
+	advisories.sort((a, b) => {
+		const d = SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity);
+		if (d !== 0) return d;
+		return String(a.module).localeCompare(String(b.module));
+	});
+
+	return { total, critical, high, moderate, low, info, advisories };
+}
+
+export function formatLog(parsed) {
+	const lines = [
+		`npm audit: total=${parsed.total} critical=${parsed.critical} high=${parsed.high} moderate=${parsed.moderate} low=${parsed.low} info=${parsed.info}`,
+	];
+	for (const a of parsed.advisories) {
+		const id = a.ghsa || a.cves[0] || a.id;
+		lines.push(
+			`  [${a.severity}] ${a.module} ${id}: ${a.title} (vulnerable ${a.vulnerable}; patched ${a.patched})`,
+		);
+		if (a.url) lines.push(`    ${a.url}`);
+		if (a.paths[0]) lines.push(`    ${a.paths[0]}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function formatMarkdown(parsed) {
+	const lines = [
+		"## npm audit",
+		"",
+		"| Severity | Count |",
+		"|---|---|",
+		`| Critical | ${parsed.critical} |`,
+		`| High | ${parsed.high} |`,
+		`| Moderate | ${parsed.moderate} |`,
+		`| Low | ${parsed.low} |`,
+		`| Info | ${parsed.info} |`,
+		`| **Total** | **${parsed.total}** |`,
+		"",
+	];
+	if (parsed.advisories.length === 0) {
+		lines.push("No advisories.");
+		return `${lines.join("\n")}\n`;
+	}
+	lines.push("### Advisories", "");
+	for (const a of parsed.advisories) {
+		const id = a.ghsa || a.cves.join(", ") || a.id;
+		const link = a.url ? `[${id}](${a.url})` : id;
+		lines.push(`- **${a.severity}** \`${a.module}\` ${link} — ${a.title}`);
+		lines.push(`  - vulnerable: \`${a.vulnerable}\`; patched: \`${a.patched}\``);
+		if (a.paths[0]) lines.push(`  - ${a.paths[0]}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function highCritical(parsed) {
+	return parsed.advisories.filter((a) => a.severity === "high" || a.severity === "critical");
+}

package/src/audit/summarize.mjs

@@ -1,46 +1,24 @@
 import { appendFileSync, readFileSync } from "node:fs";
+import { formatLog, formatMarkdown, parseAudit } from "./format.mjs";
 
 const auditFilePath = process.argv[2] ?? "npm-audit.json";
 
-function writeSummary(lines) {
-	const summaryText = `${lines.join("\n")}\n`;
+function writeSummary(text) {
 	if (process.env.GITHUB_STEP_SUMMARY) {
-		appendFileSync(process.env.GITHUB_STEP_SUMMARY, summaryText);
-		return;
+		appendFileSync(process.env.GITHUB_STEP_SUMMARY, text);
 	}
-	process.stdout.write(summaryText);
 }
 
 let data = null;
 try {
 	data = JSON.parse(readFileSync(auditFilePath, "utf8"));
 } catch {
-	writeSummary([
-		"## Security Audit",
-		"",
-		"- npm audit output could not be parsed.",
-		`- See uploaded \`${auditFilePath}\` artifact for raw output.`,
-	]);
+	const msg = `npm audit output could not be parsed (${auditFilePath}).\n`;
+	process.stderr.write(msg);
+	writeSummary(`## Security Audit\n\n- ${msg}`);
 	process.exit(1);
 }
 
-const vulnerabilities = data.metadata?.vulnerabilities ?? {};
-const info = vulnerabilities.info ?? 0;
-const low = vulnerabilities.low ?? 0;
-const moderate = vulnerabilities.moderate ?? 0;
-const high = vulnerabilities.high ?? 0;
-const critical = vulnerabilities.critical ?? 0;
-const total = vulnerabilities.total ?? info + low + moderate + high + critical;
-
-writeSummary([
-	"## Security Audit",
-	"",
-	`| Severity  | Count |`,
-	`|-----------|-------|`,
-	`| Critical  | ${critical} |`,
-	`| High      | ${high} |`,
-	`| Moderate  | ${moderate} |`,
-	`| Low       | ${low} |`,
-	`| Info      | ${info} |`,
-	`| **Total** | **${total}** |`,
-]);
+const parsed = parseAudit(data);
+process.stdout.write(formatLog(parsed));
+writeSummary(formatMarkdown(parsed));

package/src/audit/upsert-clickup.mjs

@@ -0,0 +1,117 @@
+/**
+ * Upsert a ClickUp task with the current npm audit report.
+ *
+ * Env: CLICKUP_API_KEY (required), CLICKUP_LIST_ID (default Decohere list).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { formatMarkdown, parseAudit } from "./format.mjs";
+
+const auditFilePath = process.argv[2] ?? "npm-audit.json";
+const TASK_NAME = "chore(security): npm audit findings";
+const LIST_ID = process.env.CLICKUP_LIST_ID ?? "901220171084";
+const API = "https://api.clickup.com/api/v2";
+
+function runUrl() {
+	if (
+		process.env.GITHUB_SERVER_URL &&
+		process.env.GITHUB_REPOSITORY &&
+		process.env.GITHUB_RUN_ID
+	) {
+		return `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
+	}
+	return "(run URL unavailable)";
+}
+
+async function clickup(method, path, body) {
+	const key = process.env.CLICKUP_API_KEY;
+	if (key == null || key.length === 0) {
+		throw new Error("Missing CLICKUP_API_KEY");
+	}
+	const response = await fetch(`${API}${path}`, {
+		method,
+		headers: {
+			Authorization: key,
+			"Content-Type": "application/json",
+		},
+		body: body == null ? undefined : JSON.stringify(body),
+	});
+	const text = await response.text();
+	if (!response.ok) {
+		throw new Error(
+			`ClickUp ${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`,
+		);
+	}
+	return text.length === 0 ? undefined : JSON.parse(text);
+}
+
+async function findTaskByName(name) {
+	for (let page = 0; page < 10; page++) {
+		const qs = new URLSearchParams({
+			include_closed: "true",
+			subtasks: "false",
+			page: String(page),
+		});
+		const data = await clickup("GET", `/list/${LIST_ID}/task?${qs}`);
+		const tasks = Array.isArray(data) ? data : (data?.tasks ?? []);
+		const match = tasks.find((t) => t.name === name);
+		if (match) return match;
+		if (tasks.length < 100) break;
+	}
+	return null;
+}
+
+async function firstOpenStatus() {
+	const list = await clickup("GET", `/list/${LIST_ID}`);
+	return (list.statuses ?? []).find((s) => s.type === "open")?.status;
+}
+
+function buildDescription(parsed) {
+	const sha = process.env.GITHUB_SHA ? process.env.GITHUB_SHA.slice(0, 12) : "unknown";
+	return [
+		formatMarkdown(parsed).trim(),
+		"",
+		`- Commit: \`${sha}\``,
+		`- Workflow run: ${runUrl()}`,
+		"",
+		"Updated by the nightly npm-audit workflow. PR CI still gates high/critical.",
+	].join("\n");
+}
+
+if (!existsSync(auditFilePath)) {
+	console.log(`No audit file at ${auditFilePath}; skipping ClickUp upsert.`);
+	process.exit(0);
+}
+
+const parsed = parseAudit(JSON.parse(readFileSync(auditFilePath, "utf8")));
+const existing = await findTaskByName(TASK_NAME);
+
+if (parsed.total === 0) {
+	if (existing) {
+		await clickup("PUT", `/task/${existing.id}`, {
+			markdown_description: buildDescription(parsed),
+		});
+		console.log(`Cleared findings on ClickUp task ${existing.id}`);
+	} else {
+		console.log("No vulnerabilities and no existing ClickUp task; nothing to upsert.");
+	}
+	process.exit(0);
+}
+
+const payload = {
+	name: TASK_NAME,
+	markdown_description: buildDescription(parsed),
+	custom_item_id: 1004,
+};
+
+if (existing) {
+	const update = { markdown_description: payload.markdown_description };
+	if (existing.closed || existing.status?.type === "closed") {
+		const status = await firstOpenStatus();
+		if (status) update.status = status;
+	}
+	await clickup("PUT", `/task/${existing.id}`, update);
+	console.log(`Updated ClickUp task ${existing.id} (${existing.url ?? ""})`);
+} else {
+	const created = await clickup("POST", `/list/${LIST_ID}/task`, payload);
+	console.log(`Created ClickUp task ${created.id} ${created.url ?? ""}`);
+}

package/src/audit/upsert-issue.mjs

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { formatMarkdown, parseAudit } from "./format.mjs";
 
 const auditFilePath = process.argv[2] ?? "npm-audit.json";
 const ISSUE_TITLE = "security(ci): npm audit vulnerabilities detected";
@@ -14,40 +15,15 @@ function runGh(args) {
 	return result.stdout;
 }
 
-function readAuditSummary(filePath) {
-	const data = JSON.parse(readFileSync(filePath, "utf8"));
-	const vulnerabilities = data.metadata?.vulnerabilities ?? {};
-	const info = vulnerabilities.info ?? 0;
-	const low = vulnerabilities.low ?? 0;
-	const moderate = vulnerabilities.moderate ?? 0;
-	const high = vulnerabilities.high ?? 0;
-	const critical = vulnerabilities.critical ?? 0;
-	const total = vulnerabilities.total ?? info + low + moderate + high + critical;
-	return { total, critical, high, moderate, low, info };
-}
-
-function buildBody(summary) {
-	const runUrl =
-		process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
-			? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
-			: "(run URL unavailable)";
-	const sha = process.env.GITHUB_SHA ? process.env.GITHUB_SHA.slice(0, 12) : "unknown";
-
-	return [
-		"## npm audit detected vulnerabilities",
-		"",
-		`- Total: ${summary.total}`,
-		`- Critical: ${summary.critical}`,
-		`- High: ${summary.high}`,
-		`- Moderate: ${summary.moderate}`,
-		`- Low: ${summary.low}`,
-		`- Info: ${summary.info}`,
-		"",
-		`- Commit: ${sha}`,
-		`- Workflow run: ${runUrl}`,
-		"",
-		"This issue is managed by CI and will be updated on subsequent main-branch runs while vulnerabilities remain.",
-	].join("\n");
+function runUrl() {
+	if (
+		process.env.GITHUB_SERVER_URL &&
+		process.env.GITHUB_REPOSITORY &&
+		process.env.GITHUB_RUN_ID
+	) {
+		return `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
+	}
+	return "(run URL unavailable)";
 }
 
 function findExistingIssueNumber() {
@@ -70,13 +46,22 @@ if (!existsSync(auditFilePath)) {
 	process.exit(0);
 }
 
-const summary = readAuditSummary(auditFilePath);
-if (summary.total === 0) {
+const parsed = parseAudit(JSON.parse(readFileSync(auditFilePath, "utf8")));
+if (parsed.total === 0) {
 	console.log("No vulnerabilities found; skipping issue create/update.");
 	process.exit(0);
 }
 
-const body = buildBody(summary);
+const sha = process.env.GITHUB_SHA ? process.env.GITHUB_SHA.slice(0, 12) : "unknown";
+const body = [
+	formatMarkdown(parsed).trim(),
+	"",
+	`- Commit: \`${sha}\``,
+	`- Workflow run: ${runUrl()}`,
+	"",
+	"This issue is managed by CI and will be updated on subsequent main-branch runs while vulnerabilities remain.",
+].join("\n");
+
 const tempFile = path.join(os.tmpdir(), `npm-audit-issue-${Date.now()}.md`);
 writeFileSync(tempFile, body, "utf8");
 

package/tests/audit/format.test.mjs

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import {
+	formatLog,
+	formatMarkdown,
+	highCritical,
+	parseAudit,
+} from "../../src/audit/format.mjs";
+
+const fixture = {
+	metadata: {
+		vulnerabilities: { info: 0, low: 1, moderate: 0, high: 1, critical: 0, total: 2 },
+	},
+	advisories: {
+		1: {
+			id: 1,
+			module_name: "nanoid",
+			severity: "high",
+			title: "nanoid: custom generators can loop indefinitely when size is zero",
+			url: "https://github.com/advisories/GHSA-2v37-7h3g-55p8",
+			vulnerable_versions: "<3.3.18",
+			patched_versions: ">=3.3.18",
+			cves: [],
+			findings: [{ version: "3.3.17", paths: [". > vite > postcss > nanoid@3.3.17"] }],
+		},
+		2: {
+			id: 2,
+			module_name: "esbuild",
+			severity: "low",
+			title: "esbuild Windows file read",
+			url: "https://github.com/advisories/GHSA-g7r4-m6w7-qqqr",
+			vulnerable_versions: "<0.28.1",
+			patched_versions: ">=0.28.1",
+			cves: [],
+			findings: [{ version: "0.27.3", paths: [". > vite > esbuild"] }],
+		},
+	},
+};
+
+describe("parseAudit", () => {
+	it("reads severity counts and sorts advisories critical/high first", () => {
+		const parsed = parseAudit(fixture);
+		expect(parsed.total).toBe(2);
+		expect(parsed.high).toBe(1);
+		expect(parsed.low).toBe(1);
+		expect(parsed.advisories.map((a) => a.module)).toEqual(["nanoid", "esbuild"]);
+		expect(parsed.advisories[0]?.severity).toBe("high");
+		expect(parsed.advisories[0]?.ghsa).toBe("GHSA-2v37-7h3g-55p8");
+	});
+});
+
+describe("formatLog", () => {
+	it("prints severity counts and advisory lines including GHSA", () => {
+		const log = formatLog(parseAudit(fixture));
+		expect(log).toContain("high=1");
+		expect(log).toContain("[high] nanoid GHSA-2v37-7h3g-55p8");
+		expect(log).toContain("[low] esbuild");
+	});
+});
+
+describe("formatMarkdown", () => {
+	it("includes a severity table and linked advisories", () => {
+		const md = formatMarkdown(parseAudit(fixture));
+		expect(md).toContain("| High | 1 |");
+		expect(md).toContain("**high** `nanoid`");
+		expect(md).toContain("GHSA-2v37-7h3g-55p8");
+	});
+});
+
+describe("highCritical", () => {
+	it("filters to high and critical only", () => {
+		expect(highCritical(parseAudit(fixture)).map((a) => a.module)).toEqual(["nanoid"]);
+	});
+});
+
+describe("parseAudit npm v2", () => {
+	it("dedupes GHSA rows from package via objects", () => {
+		const v2 = {
+			auditReportVersion: 2,
+			metadata: {
+				vulnerabilities: { info: 0, low: 0, moderate: 0, high: 1, critical: 0, total: 1 },
+			},
+			vulnerabilities: {
+				nanoid: {
+					name: "nanoid",
+					severity: "high",
+					via: [
+						{
+							source: 1103848,
+							name: "nanoid",
+							title: "nanoid infinite loop",
+							url: "https://github.com/advisories/GHSA-2v37-7h3g-55p8",
+							severity: "high",
+							range: "<3.3.18",
+						},
+					],
+					range: "<3.3.18",
+					nodes: ["node_modules/.pnpm/nanoid@3.3.17/node_modules/nanoid"],
+				},
+				postcss: {
+					name: "postcss",
+					severity: "high",
+					via: ["nanoid"],
+					effects: [],
+					range: "*",
+					nodes: ["node_modules/.pnpm/postcss@8.5.26/node_modules/postcss"],
+				},
+			},
+		};
+		const parsed = parseAudit(v2);
+		expect(parsed.advisories).toHaveLength(1);
+		expect(parsed.advisories[0]?.module).toBe("nanoid");
+		expect(parsed.advisories[0]?.ghsa).toBe("GHSA-2v37-7h3g-55p8");
+		expect(parsed.advisories[0]?.vulnerable).toBe("<3.3.18");
+	});
+});