@decohere/ci-tools 0.0.1-dev.10

package/src/lib/lcov.mjs

@@ -0,0 +1,127 @@
+/**
+ * Shared LCOV file parsing utilities.
+ */
+
+/**
+ * Normalizes a file path to use forward slashes.
+ * @param {string} filePath
+ * @returns {string}
+ */
+function normalizePath(filePath) {
+	return filePath.replaceAll("\\", "/");
+}
+
+/**
+ * Extracts the top-level project name from a source path like
+ * `/workspace/projects/hearth/src/foo.ts` → `"hearth"`.
+ * @param {string} sourcePath
+ * @returns {string | undefined}
+ */
+export function getProjectFromPath(sourcePath) {
+	const match = sourcePath.match(/(?:^|\/)projects\/([^/]+)\//);
+	return match?.[1];
+}
+
+/**
+ * Parses an LCOV file and returns per-project line coverage totals.
+ * Uses the LF (lines found) and LH (lines hit) summary fields.
+ *
+ * @param {string} content  Raw LCOV file content.
+ * @returns {Map<string, { totalLines: number; coveredLines: number }>}
+ */
+export function parseLcovByProject(content) {
+	const records = content
+		.split("end_of_record")
+		.map((record) => record.trim())
+		.filter(Boolean);
+
+	const byProject = new Map();
+
+	for (const record of records) {
+		const lines = record.split("\n");
+		let sourcePath = "";
+		let totalLines = 0;
+		let coveredLines = 0;
+
+		for (const line of lines) {
+			if (line.startsWith("SF:")) {
+				sourcePath = normalizePath(line.slice(3));
+			} else if (line.startsWith("LF:")) {
+				totalLines = Number(line.slice(3));
+			} else if (line.startsWith("LH:")) {
+				coveredLines = Number(line.slice(3));
+			}
+		}
+
+		const project = getProjectFromPath(sourcePath);
+		if (project == null || totalLines === 0) continue;
+
+		const current = byProject.get(project) ?? { totalLines: 0, coveredLines: 0 };
+		current.totalLines += totalLines;
+		current.coveredLines += coveredLines;
+		byProject.set(project, current);
+	}
+
+	return byProject;
+}
+
+/**
+ * Parses an LCOV file into per-file records including uncovered line numbers.
+ * Suitable for detailed reporting.
+ *
+ * @param {string} content  Raw LCOV file content.
+ * @returns {Array<{
+ *   sourcePath: string;
+ *   project: string | undefined;
+ *   totalLines: number;
+ *   coveredLines: number;
+ *   uncoveredLines: number;
+ *   uncoveredLineNumbers: number[];
+ * }>}
+ */
+export function parseLcovFiles(content) {
+	const records = content
+		.split("end_of_record")
+		.map((record) => record.trim())
+		.filter(Boolean);
+
+	const files = [];
+
+	for (const record of records) {
+		const lines = record.split("\n");
+		let sourcePath = "";
+		let totalLines = 0;
+		let coveredLines = 0;
+		const uncoveredLineNumbers = [];
+
+		for (const line of lines) {
+			if (line.startsWith("SF:")) {
+				sourcePath = normalizePath(line.slice(3));
+			} else if (line.startsWith("LF:")) {
+				totalLines = Number(line.slice(3));
+			} else if (line.startsWith("LH:")) {
+				coveredLines = Number(line.slice(3));
+			} else if (line.startsWith("DA:")) {
+				const [lineNumberText, hitCountText] = line.slice(3).split(",");
+				const lineNumber = Number(lineNumberText);
+				const hitCount = Number(hitCountText);
+				if (!Number.isNaN(lineNumber) && !Number.isNaN(hitCount) && hitCount === 0) {
+					uncoveredLineNumbers.push(lineNumber);
+				}
+			}
+		}
+
+		if (sourcePath.length === 0 || totalLines === 0) continue;
+
+		files.push({
+			sourcePath,
+			project: getProjectFromPath(sourcePath),
+			totalLines,
+			coveredLines,
+			uncoveredLines: totalLines - coveredLines,
+			uncoveredLineNumbers: uncoveredLineNumbers.sort((a, b) => a - b),
+		});
+	}
+
+	return files;
+}

package/src/lib/svg.mjs

@@ -0,0 +1,66 @@
+/**
+ * Shared SVG badge generation utilities.
+ */
+
+/**
+ * Returns a badge color for a given line-coverage percentage.
+ * @param {number} percentage
+ * @returns {string}
+ */
+export function getColor(percentage) {
+	if (percentage >= 90) return "#2ea043";
+	if (percentage >= 80) return "#3fb950";
+	if (percentage >= 70) return "#9a6700";
+	if (percentage >= 60) return "#db6d28";
+	return "#cf222e";
+}
+
+/**
+ * Creates a two-section labeled badge SVG string.
+ * @param {string} label
+ * @param {string} value
+ * @param {string} color  Hex color for the value section.
+ * @returns {string}
+ */
+export function createBadgeSvg(label, value, color) {
+	const labelWidth = Math.max(50, 10 + label.length * 7);
+	const valueWidth = Math.max(44, 10 + value.length * 7);
+	const totalWidth = labelWidth + valueWidth;
+
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${label}: ${value}">
+  <title>${label}: ${value}</title>
+  <rect width="${labelWidth}" height="20" fill="#24292f"/>
+  <rect x="${labelWidth}" width="${valueWidth}" height="20" fill="${color}"/>
+  <text x="${labelWidth / 2}" y="14" fill="#ffffff" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">${label}</text>
+  <text x="${labelWidth + valueWidth / 2}" y="14" fill="#ffffff" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">${value}</text>
+</svg>\n`;
+}
+
+/**
+ * Maps a GitHub Actions workflow run status/conclusion to a badge color.
+ * @param {string} status
+ * @param {string | null} conclusion
+ * @returns {string}
+ */
+export function statusToColor(status, conclusion) {
+	if (status === "in_progress" || status === "queued") return "#fb8500";
+	if (conclusion === "success") return "#2ea043";
+	if (conclusion === "failure") return "#cf222e";
+	if (conclusion === "cancelled") return "#6e7781";
+	return "#6e7781";
+}
+
+/**
+ * Maps a GitHub Actions workflow run status/conclusion to a human-readable label.
+ * @param {string} status
+ * @param {string | null} conclusion
+ * @returns {string}
+ */
+export function statusToText(status, conclusion) {
+	if (status === "in_progress") return "running";
+	if (status === "queued") return "queued";
+	if (conclusion === "success") return "passing";
+	if (conclusion === "failure") return "failing";
+	if (conclusion === "cancelled") return "cancelled";
+	return "unknown";
+}

package/src/pages/artifact.mjs

@@ -0,0 +1,208 @@
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const branch = process.env.GITHUB_REF_NAME ?? "local";
+const sha = process.env.GITHUB_SHA ?? "local";
+const outputDir = process.env.PAGES_OUTPUT_DIR ?? "site";
+
+const badgesDir = "projects/ci-tools/dist/ci/badges";
+const benchHistoryPath = "projects/ci-tools/dist/ci/bench/bench-history.json";
+
+const numericFields = ["hz", "mean", "p99", "rme", "sampleCount"];
+
+function fmtMs(ms) {
+	if (typeof ms !== "number" || Number.isNaN(ms)) return "-";
+	if (ms >= 100) return `${Math.round(ms)} ms`;
+	return `${ms.toFixed(1)} ms`;
+}
+
+function fmtHz(hz) {
+	if (typeof hz !== "number" || Number.isNaN(hz)) return "-";
+	return `${hz.toFixed(2)}/s`;
+}
+
+function averageBenchmarks(runs) {
+	const first = runs[0]?.vitestOutput;
+	if (first == null) return [];
+
+	const latestBenchmarks = first.files
+		.flatMap((file) => file.groups)
+		.flatMap((group) => group.benchmarks);
+
+	return latestBenchmarks.map((benchmark) => {
+		const peers = runs
+			.flatMap((run) => run.vitestOutput?.files ?? [])
+			.flatMap((file) => file.groups ?? [])
+			.flatMap((group) => group.benchmarks ?? [])
+			.filter((candidate) => candidate.name === benchmark.name);
+
+		const averaged = { name: benchmark.name };
+		for (const field of numericFields) {
+			const values = peers
+				.map((peer) => peer[field])
+				.filter((value) => typeof value === "number");
+			if (values.length > 0) {
+				averaged[field] = values.reduce((sum, value) => sum + value, 0) / values.length;
+			}
+		}
+
+		return averaged;
+	});
+}
+
+export function buildBenchmarkHtml(benchHistory) {
+	const contexts = Object.entries(benchHistory.runs ?? {})
+		.filter(([, entry]) => Array.isArray(entry.runs) && entry.runs.length > 0)
+		.sort((a, b) => new Date(b[1].runs[0].date) - new Date(a[1].runs[0].date));
+
+	if (contexts.length === 0) {
+		return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Ark - Benchmarks</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="container">
+      <header class="hero">
+        <h1>Benchmarks</h1>
+        <p class="note">No benchmark history is available yet.</p>
+      </header>
+    </main>
+  </body>
+</html>
+`;
+	}
+
+	const rows = [];
+	for (const [, entry] of contexts) {
+		const benchmarks = averageBenchmarks(entry.runs);
+		const ctx = entry.context;
+		const environment = `${ctx.benchEnv ?? "unknown"}-${ctx.os.arch}`;
+		for (const benchmark of benchmarks) {
+			rows.push(`<tr>
+  <td>${environment}</td>
+  <td><code>${benchmark.name}</code></td>
+  <td>${fmtMs(benchmark.mean)}</td>
+  <td>${typeof benchmark.rme === "number" ? `±${benchmark.rme.toFixed(1)}%` : "-"}</td>
+  <td>${fmtMs(benchmark.p99)}</td>
+  <td>${fmtHz(benchmark.hz)}</td>
+  <td>${typeof benchmark.sampleCount === "number" ? Math.round(benchmark.sampleCount) : "-"}</td>
+</tr>`);
+		}
+	}
+
+	const details = contexts
+		.map(([, entry]) => {
+			const ctx = entry.context;
+			return `<li><strong>${ctx.benchEnv ?? "unknown"}-${ctx.os.arch}</strong> - ${ctx.os.platform} - ${ctx.cpu.model} x ${ctx.cpu.count} - ${ctx.memoryGb} GB - Node ${ctx.node} - rolling mean of ${entry.runs.length} run(s)</li>`;
+		})
+		.join("\n");
+
+	const updatedDate = contexts[0][1].runs[0].date.slice(0, 10);
+
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Ark - Benchmarks</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="container">
+      <div class="hero">
+        <h1>Benchmarks</h1>
+        <p class="note">Updated ${updatedDate} · Branch: ${branch} · Commit: ${sha.slice(0, 12)}</p>
+      </div>
+      <section class="section">
+        <h2>Performance Table</h2>
+        <table>
+          <thead>
+            <tr>
+              <th>Environment</th>
+              <th>Benchmark</th>
+              <th>Mean</th>
+              <th>±RME</th>
+              <th>P99</th>
+              <th>Ops/s</th>
+              <th>Runs</th>
+            </tr>
+          </thead>
+          <tbody>
+            ${rows.join("\n")}
+          </tbody>
+        </table>
+      </section>
+      <section class="section">
+        <h2>Environment Notes</h2>
+        <ul>
+          ${details}
+        </ul>
+      </section>
+    </main>
+  </body>
+</html>
+`;
+}
+
+function buildStylesCss() {
+	return `:root {
+  --bg: #f4f7f3;
+  --surface: #ffffff;
+  --text: #132b24;
+  --muted: #4f6f65;
+  --accent: #0f9d72;
+  --accent-strong: #0d7f5c;
+  --border: #d6e3dd;
+  --shadow: 0 14px 40px rgba(12, 58, 45, 0.08);
+}
+* { box-sizing: border-box; }
+body { margin: 0; font-family: "Segoe UI", "Helvetica Neue", sans-serif; color: var(--text); background: radial-gradient(circle at top right, #dbefe7, var(--bg) 40%); }
+a { color: var(--accent-strong); }
+.container { max-width: 1100px; margin: 0 auto; padding: 28px 18px 60px; }
+.hero { background: linear-gradient(145deg, #183a31, #0e7f5c); color: #f3fff8; padding: 26px; border-radius: 18px; box-shadow: var(--shadow); }
+.hero h1 { margin: 6px 0 10px; }
+.note { color: #d8f5eb; margin: 0; }
+.section { margin-top: 26px; }
+table { width: 100%; border-collapse: collapse; background: var(--surface); border-radius: 12px; overflow: hidden; }
+th, td { border-bottom: 1px solid var(--border); padding: 9px 10px; text-align: left; }
+th { color: var(--muted); font-weight: 600; background: #f3faf7; }
+td code { color: var(--accent-strong); }
+@media (max-width: 700px) { .hero { padding: 20px; } .container { padding: 18px 12px 40px; } }
+`;
+}
+
+await rm(outputDir, { recursive: true, force: true });
+await mkdir(outputDir, { recursive: true });
+
+await writeFile(path.join(outputDir, "styles.css"), buildStylesCss());
+
+// index.html redirects to benchmark.html — no separate dashboard needed
+await writeFile(
+	path.join(outputDir, "index.html"),
+	`<!doctype html><html><head><meta charset="utf-8"/><meta http-equiv="refresh" content="0;url=./benchmark.html"/><title>Ark Pages</title></head><body><p><a href="./benchmark.html">Benchmarks</a></p></body></html>\n`,
+);
+
+try {
+	const benchHistory = JSON.parse(await readFile(benchHistoryPath, "utf8"));
+	await writeFile(path.join(outputDir, "benchmark.html"), buildBenchmarkHtml(benchHistory));
+	const benchmarkDataDir = path.join(outputDir, "data");
+	await mkdir(benchmarkDataDir, { recursive: true });
+	await writeFile(
+		path.join(benchmarkDataDir, "bench-history.json"),
+		`${JSON.stringify(benchHistory, null, 2)}\n`,
+	);
+} catch {
+	await writeFile(path.join(outputDir, "benchmark.html"), buildBenchmarkHtml({ runs: {} }));
+}
+
+try {
+	await cp(badgesDir, path.join(outputDir, "badges"), { recursive: true });
+} catch {
+	// Badges may not exist yet for some runs.
+}
+
+await writeFile(path.join(outputDir, ".nojekyll"), "");

package/src/pages/clear-bench-history.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+// Clear benchmark history for this publish (workflow_dispatch with clear-history=true)
+
+import { writeFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+
+const HISTORY_DIR = "projects/ci-tools/dist/ci/bench";
+const HISTORY_FILE = `${HISTORY_DIR}/bench-history.json`;
+
+try {
+	await mkdir(HISTORY_DIR, { recursive: true });
+	writeFileSync(
+		HISTORY_FILE,
+		JSON.stringify(
+			{
+				runs: {},
+			},
+			null,
+			2,
+		),
+	);
+	console.log("✓ Cleared benchmark history");
+} catch (error) {
+	console.error("Error clearing benchmark history:", error.message);
+	process.exit(1);
+}

package/src/pages/keep-prior-bench-badge.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+// Keep prior bench badge if no code changes; create fallback if none exists
+
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+
+const BADGES_DIR = "projects/ci-tools/dist/ci/badges";
+const BADGE_FILE = `${BADGES_DIR}/bench.svg`;
+const PAGES_URL = "https://typesmiths.github.io/decohere/badges/bench.svg";
+
+const FALLBACK_BADGE = `<svg xmlns="http://www.w3.org/2000/svg" width="120" height="20" role="img" aria-label="bench: unavailable">
+  <title>bench: unavailable</title>
+  <rect width="120" height="20" fill="#555"/>
+  <rect x="46" width="74" height="20" fill="#9f9f9f"/>
+  <text x="24" y="14" fill="#fff" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">bench</text>
+  <text x="83" y="14" fill="#fff" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">unavailable</text>
+</svg>`;
+
+try {
+	if (!existsSync(BADGE_FILE)) {
+		await mkdir(BADGES_DIR, { recursive: true });
+
+		try {
+			execSync(`curl -fsSL "${PAGES_URL}" -o "${BADGE_FILE}"`, {
+				stdio: "pipe",
+			});
+			console.log("✓ Restored prior bench badge from Pages");
+		} catch {
+			console.warn("::warning::No prior bench badge found on Pages; creating fallback badge.");
+			writeFileSync(BADGE_FILE, FALLBACK_BADGE);
+		}
+	}
+} catch (error) {
+	console.error("Error keeping prior bench badge:", error.message);
+	process.exit(1);
+}

package/src/pages/restore-bench-history.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// Restore benchmark history from Pages, or initialize empty if not found
+
+import { execSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+
+const HISTORY_DIR = "projects/ci-tools/dist/ci/bench";
+const HISTORY_FILE = `${HISTORY_DIR}/bench-history.json`;
+const PAGES_URL = "https://typesmiths.github.io/decohere/data/bench-history.json";
+
+try {
+	await mkdir(HISTORY_DIR, { recursive: true });
+
+	try {
+		execSync(`curl -fsSL "${PAGES_URL}" -o "${HISTORY_FILE}"`, {
+			stdio: "pipe",
+		});
+		console.log("✓ Restored benchmark history from Pages");
+	} catch {
+		console.log("No benchmark history on Pages; starting from empty history");
+		writeFileSync(
+			HISTORY_FILE,
+			JSON.stringify(
+				{
+					runs: {},
+				},
+				null,
+				2,
+			),
+		);
+	}
+} catch (error) {
+	console.error("Error restoring benchmark history:", error.message);
+	process.exit(1);
+}

package/src/pages/smoke.mjs

@@ -0,0 +1,37 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const branch = process.env.GITHUB_REF_NAME ?? "local";
+const sha = process.env.GITHUB_SHA ?? "local";
+const generatedAt = new Date().toISOString();
+const outputDir = process.env.PAGES_OUTPUT_DIR ?? "site";
+
+const smokeDir = path.join(outputDir, "smoke", branch);
+
+await mkdir(smokeDir, { recursive: true });
+
+await writeFile(
+	path.join(smokeDir, "index.html"),
+	`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Ark Pages Smoke</title>
+  </head>
+  <body>
+    <h1>Pages Smoke Test</h1>
+    <p>Branch: ${branch}</p>
+    <p>Commit: ${sha}</p>
+    <p>Generated: ${generatedAt}</p>
+  </body>
+</html>
+`,
+);
+
+await writeFile(
+	path.join(smokeDir, "meta.json"),
+	`${JSON.stringify({ branch, sha, generatedAt, path: `smoke/${branch}/` }, null, 2)}\n`,
+);
+
+await writeFile(path.join(outputDir, ".nojekyll"), "");

package/src/release/capture-version.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Capture final version metadata from package.json
+ * Outputs version and is_prerelease flags for GitHub Actions
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+try {
+	const packageJson = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8"));
+	const version = packageJson.version;
+
+	if (!version) {
+		console.error("No version found in package.json");
+		process.exit(1);
+	}
+
+	console.log(`version=${version}`);
+
+	// Check if prerelease (has hyphen in version)
+	const isPrerelease = version.includes("-");
+	console.log(`is_prerelease=${isPrerelease}`);
+} catch (e) {
+	console.error(`Failed to capture version: ${e.message}`);
+	process.exit(1);
+}

package/src/release/npm-links.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Generate npm package links for all @decohere packages
+ * Outputs markdown formatted links for GitHub release notes
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const VERSION = process.argv[2] || process.env.VERSION;
+
+if (!VERSION) {
+	console.error("VERSION not provided as argument or env var");
+	process.exit(1);
+}
+
+let links = "## Published Packages\n\n";
+const projectsDir = join(process.cwd(), "projects");
+
+try {
+	const projects = readdirSync(projectsDir);
+
+	for (const project of projects) {
+		const pkgPath = join(projectsDir, project, "package.json");
+		try {
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+			if (pkg.name?.startsWith("@decohere/")) {
+				links += `- [\`${pkg.name}@${VERSION}\`](https://www.npmjs.com/package/${pkg.name}/v/${VERSION})\n`;
+			}
+		} catch {
+			// Skip projects without package.json
+		}
+	}
+
+	console.log(links);
+} catch (e) {
+	console.error(`Failed to generate npm links: ${e.message}`);
+	process.exit(1);
+}