@decohere/ci-tools 0.0.1-dev.125 → 0.0.1-dev.13

package/src/coverage/enforce-thresholds.mjs

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseLcovByProject } from "../lib/lcov.mjs";
+
+function parseArgs(argv) {
+	const options = {
+		lcov: ".forge/coverage/lcov.info",
+		thresholds: null,
+		thresholdsModule: null,
+		projectsDir: "projects",
+	};
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--lcov") {
+			options.lcov = argv[index + 1] ?? options.lcov;
+			index += 1;
+			continue;
+		}
+		if (arg === "--thresholds") {
+			options.thresholds = argv[index + 1] ?? options.thresholds;
+			index += 1;
+			continue;
+		}
+		if (arg === "--thresholds-module") {
+			options.thresholdsModule = argv[index + 1] ?? options.thresholdsModule;
+			index += 1;
+			continue;
+		}
+		if (arg === "--projectsDir") {
+			options.projectsDir = argv[index + 1] ?? options.projectsDir;
+			index += 1;
+		}
+	}
+
+	return options;
+}
+
+async function resolveThresholds(options) {
+	if (options.thresholdsModule) {
+		const moduleUrl = pathToFileURL(resolve(options.thresholdsModule)).href;
+		const mod = await import(moduleUrl);
+		const thresholds = mod.projectCoverageThresholds;
+		if (typeof thresholds !== "object" || thresholds == null) {
+			console.error(
+				`Module ${options.thresholdsModule} must export a 'projectCoverageThresholds' object.`,
+			);
+			process.exit(1);
+		}
+		return thresholds;
+	}
+
+	const path = options.thresholds ?? "coverage.config.json";
+	if (!existsSync(path)) {
+		console.error(`Thresholds config not found: ${path}`);
+		process.exit(1);
+	}
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	if (typeof parsed !== "object" || parsed == null) {
+		console.error(
+			"Thresholds config must be a JSON object mapping project => minimum coverage percentage.",
+		);
+		process.exit(1);
+	}
+	return parsed;
+}
+
+function formatPct(value) {
+	return `${value.toFixed(2)}%`;
+}
+
+async function main() {
+	const options = parseArgs(process.argv.slice(2));
+	const lcovPath = resolve(options.lcov);
+	const projectsDirPath = resolve(options.projectsDir);
+
+	if (!existsSync(lcovPath)) {
+		console.error(`LCOV file not found: ${lcovPath}`);
+		console.error("Run coverage first (example: npm run test:coverage)");
+		process.exit(1);
+	}
+
+	if (!existsSync(projectsDirPath)) {
+		console.error(`Projects directory not found: ${projectsDirPath}`);
+		process.exit(1);
+	}
+
+	const thresholds = await resolveThresholds(options);
+	const projectDirs = readdirSync(projectsDirPath, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.sort((left, right) => left.localeCompare(right));
+
+	const coverageByProject = parseLcovByProject(readFileSync(lcovPath, "utf8"));
+
+	const missingThresholds = projectDirs.filter(
+		(projectName) => thresholds[projectName] == null,
+	);
+	if (missingThresholds.length > 0) {
+		console.error("Missing coverage thresholds for projects:");
+		for (const projectName of missingThresholds) console.error(`- ${projectName}`);
+		console.error(
+			"Update projectCoverageThresholds in vitest.config.ts to include all project directories.",
+		);
+		process.exit(1);
+	}
+
+	const failures = [];
+	console.log("Project line coverage thresholds");
+
+	for (const projectName of projectDirs) {
+		const projectCoverage = coverageByProject.get(projectName) ?? {
+			totalLines: 0,
+			coveredLines: 0,
+		};
+		const currentPct =
+			projectCoverage.totalLines === 0
+				? 0
+				: (projectCoverage.coveredLines / projectCoverage.totalLines) * 100;
+		const minimumPct = Number(thresholds[projectName]);
+		const passed = Number.isFinite(minimumPct) && currentPct >= minimumPct;
+
+		console.log(
+			`${passed ? "✅" : "❌"} ${projectName}: ${formatPct(currentPct)} (min ${formatPct(minimumPct)})`,
+		);
+
+		if (!passed) failures.push({ projectName, currentPct, minimumPct });
+	}
+
+	if (failures.length > 0) {
+		console.error("\nCoverage threshold check failed:");
+		for (const failure of failures) {
+			console.error(
+				`- ${failure.projectName}: ${formatPct(failure.currentPct)} is below ${formatPct(failure.minimumPct)}`,
+			);
+		}
+		process.exit(1);
+	}
+
+	console.log("\nAll project coverage thresholds passed.");
+}
+
+main();

package/src/pages/artifact.mjs

@@ -1,8 +1,5 @@
-import { existsSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { normalize } from "../bench/history.mjs";
-import { buildBenchmarkHtml, buildStylesCss } from "./bench-page.mjs";
 
 const branch = process.env.GITHUB_REF_NAME ?? "local";
 const sha = process.env.GITHUB_SHA ?? "local";
@@ -11,53 +8,201 @@ 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";
 
-/** Every badge file under `dir`, relative to it: the manifest restore-badges.mjs reads back. */
-async function listBadges(dir, prefix = "") {
-	const entries = await readdir(path.join(dir, prefix), { withFileTypes: true });
-	const nested = await Promise.all(
-		entries.map((entry) =>
-			entry.isDirectory()
-				? listBadges(dir, path.posix.join(prefix, entry.name))
-				: entry.name.endsWith(".svg")
-					? [path.posix.join(prefix, entry.name)]
-					: [],
-		),
-	);
-	return nested.flat().sort();
+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(path.join(outputDir, "data"), { recursive: 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>Decohere Pages</title></head><body><p><a href="./benchmark.html">Benchmarks</a></p></body></html>\n`,
+	`<!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`,
 );
 
-// No history yet (first deploy, or cleared) publishes the empty page, not a failure.
-const benchHistory = normalize(
-	existsSync(benchHistoryPath) ? JSON.parse(await readFile(benchHistoryPath, "utf8")) : null,
-);
-await writeFile(
-	path.join(outputDir, "benchmark.html"),
-	buildBenchmarkHtml(benchHistory, { branch, sha }),
-);
-await writeFile(
-	path.join(outputDir, "data", "bench-history.json"),
-	`${JSON.stringify(benchHistory, null, 2)}\n`,
-);
-
-// Badges are generated by earlier steps (CI status, coverage) or restored from the live site.
-if (existsSync(badgesDir)) {
-	await cp(badgesDir, path.join(outputDir, "badges"), { recursive: true });
-	const badges = await listBadges(badgesDir);
+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(outputDir, "badges", "manifest.json"),
-		`${JSON.stringify({ badges }, null, 2)}\n`,
+		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

@@ -1,24 +1,37 @@
 #!/usr/bin/env node
 
-// Restore benchmark history from Pages. Only a 404 (never published, or cleared) starts an
-// empty history: any other failure stops the job, so a network blip can't wipe the trend on
-// the next save.
+// Restore benchmark history from Pages, or initialize empty if not found
 
-import { mkdir, writeFile } from "node:fs/promises";
+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 = process.env.PAGES_URL ?? "https://typesmiths.github.io/decohere";
+const PAGES_URL = "https://typesmiths.github.io/decohere/data/bench-history.json";
 
-await mkdir(HISTORY_DIR, { recursive: true });
-const response = await fetch(`${PAGES_URL}/data/bench-history.json`);
-if (response.status === 404) {
-	console.log("No benchmark history on Pages; starting from empty history");
-	await writeFile(HISTORY_FILE, `${JSON.stringify({ version: 2, contexts: {} }, null, 2)}\n`);
-} else if (!response.ok) {
-	console.error(`Failed to restore benchmark history: HTTP ${response.status}`);
+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);
-} else {
-	await writeFile(HISTORY_FILE, await response.text());
-	console.log("✓ Restored benchmark history from Pages");
 }

package/src/release/npm-links.mjs

@@ -4,9 +4,8 @@
  * Outputs markdown formatted links for GitHub release notes
  */
 
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { listProjectDirs } from "../lib/workspace-packages.mjs";
 
 const VERSION = process.argv[2] || process.env.VERSION;
 
@@ -16,12 +15,20 @@ if (!VERSION) {
 }
 
 let links = "## Published Packages\n\n";
+const projectsDir = join(process.cwd(), "projects");
 
 try {
-	for (const projectDir of listProjectDirs(process.cwd())) {
-		const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
-		if (pkg.name?.startsWith("@decohere/")) {
-			links += `- [\`${pkg.name}@${VERSION}\`](https://www.npmjs.com/package/${pkg.name}/v/${VERSION})\n`;
+	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
 		}
 	}
 

package/src/release/sync-dependencies.mjs

@@ -7,9 +7,10 @@
 import { execSync } from "node:child_process";
 
 const DRY_RUN = process.env.DRY_RUN === "true";
+const TERMINAL_CLI = process.env.TERMINAL_CLI || "dist/debug/projects/terminal/src/cli.js";
 const DECOHERE_CONFIG = process.env.DECOHERE_CONFIG || ".decohere.js";
 
-const baseCmd = `pnpm forge --log-level info --config-file "${DECOHERE_CONFIG}" dependencies --configuration release sync`;
+const baseCmd = `node "${TERMINAL_CLI}" --log-level trace --config-file "${DECOHERE_CONFIG}" forge dependencies --configuration release sync`;
 
 try {
 	if (DRY_RUN) {

package/tests/lib/lcov.test.mjs

@@ -13,7 +13,7 @@ SF:projects/forge/src/build/index.ts
 LF:20
 LH:15
 end_of_record
-SF:projects/core/src/index.ts
+SF:projects/nexus/src/index.ts
 LF:5
 LH:5
 end_of_record
@@ -46,9 +46,9 @@ describe("parseLcovByProject", () => {
 		expect(result.get("forge")).toBeDefined();
 		expect(result.get("forge").totalLines).toBe(30);
 		expect(result.get("forge").coveredLines).toBe(24);
-		expect(result.get("core")).toBeDefined();
-		expect(result.get("core").totalLines).toBe(5);
-		expect(result.get("core").coveredLines).toBe(5);
+		expect(result.get("nexus")).toBeDefined();
+		expect(result.get("nexus").totalLines).toBe(5);
+		expect(result.get("nexus").coveredLines).toBe(5);
 	});
 
 	it("ignores records with LF:0", () => {

package/LICENSE

@@ -1,15 +0,0 @@
-ISC License
-
-Copyright (c) 2025-2026 Typesmiths
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.