@decohere/ci-tools 0.0.1-dev.10

package/src/bench/trace.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const WORKSPACE_ROOT = process.cwd();
+const VITEST_BIN = join(WORKSPACE_ROOT, "node_modules/.bin/vitest");
+const CONFIG = join(WORKSPACE_ROOT, "vitest.e2e.config.ts");
+const TRACE_SPEC = "projects/terminal/e2e/build.trace.e2e.spec.ts";
+const TRACE_LOG_DIR = join(WORKSPACE_ROOT, ".decohere", "logs");
+
+function truthy(value, defaultValue = false) {
+	if (value == null) return defaultValue;
+	return !["0", "false", "no", "off"].includes(String(value).toLowerCase());
+}
+
+function toFileTimestamp(date = new Date()) {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function toTraceSample(line, parsed, durationMs) {
+	return {
+		time: parsed.time,
+		name: parsed.name,
+		message: parsed.msg,
+		durationMs,
+		line,
+	};
+}
+
+function parseTraceSamples(rawOutput) {
+	const samples = [];
+	for (const rawLine of rawOutput.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line.startsWith("{")) continue;
+
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+
+		if (typeof parsed?.name !== "string" || typeof parsed?.msg !== "string") continue;
+		const match = parsed.msg.match(/^(.*):\s+([0-9]+(?:\.[0-9]+)?)ms$/);
+		if (match == null) continue;
+
+		const durationMs = Number(match[2]);
+		if (!Number.isFinite(durationMs)) continue;
+
+		samples.push({
+			className: parsed.name,
+			methodLabel: match[1],
+			methodName: match[1].split("(")[0],
+			durationMs,
+			sample: toTraceSample(rawLine, parsed, durationMs),
+		});
+	}
+	return samples;
+}
+
+function aggregateSamples(samples, keyBuilder) {
+	const aggregates = new Map();
+	for (const sample of samples) {
+		const key = keyBuilder(sample);
+		const current = aggregates.get(key) ?? {
+			key,
+			hitCount: 0,
+			totalMs: 0,
+			maxMs: 0,
+		};
+		current.hitCount += 1;
+		current.totalMs += sample.durationMs;
+		if (sample.durationMs > current.maxMs) current.maxMs = sample.durationMs;
+		aggregates.set(key, current);
+	}
+	return [...aggregates.values()];
+}
+
+function analyzeTraceOutput(rawOutput) {
+	const samples = parseTraceSamples(rawOutput);
+	if (samples.length === 0) {
+		process.stderr.write("\n⚠  No structured trace samples found to analyze.\n");
+		return;
+	}
+
+	const byMethod = aggregateSamples(
+		samples,
+		(sample) => `${sample.className}.${sample.methodName}`,
+	);
+	const byClass = aggregateSamples(samples, (sample) => sample.className);
+	const byHits = [...byMethod].sort((a, b) => b.hitCount - a.hitCount).slice(0, 10);
+	const byTotal = [...byMethod].sort((a, b) => b.totalMs - a.totalMs).slice(0, 10);
+	const byMax = [...byMethod].sort((a, b) => b.maxMs - a.maxMs).slice(0, 10);
+	const byClassTotal = [...byClass].sort((a, b) => b.totalMs - a.totalMs).slice(0, 5);
+	const totalTraceMs = samples.reduce((sum, sample) => sum + sample.durationMs, 0);
+	const hottest = [...samples].sort((a, b) => b.durationMs - a.durationMs).slice(0, 5);
+
+	process.stderr.write(
+		"\n┌─ Trace Analysis ─────────────────────────────────────────────────────────\n",
+	);
+	process.stderr.write(`│  Samples      : ${samples.length}\n`);
+	process.stderr.write(`│  Unique funcs : ${byMethod.length}\n`);
+	process.stderr.write(`│  Total traced : ${totalTraceMs.toFixed(2)}ms\n`);
+	process.stderr.write(`│  Avg sample   : ${(totalTraceMs / samples.length).toFixed(3)}ms\n`);
+	process.stderr.write(
+		"└──────────────────────────────────────────────────────────────────────────\n",
+	);
+
+	const printTable = (title, rows, valueFormatter) => {
+		process.stderr.write(`\n${title}\n`);
+		for (const row of rows) {
+			process.stderr.write(
+				`  ${valueFormatter(row).padStart(10)}  ${row.key}  (hits=${row.hitCount}, max=${row.maxMs.toFixed(2)}ms)\n`,
+			);
+		}
+	};
+
+	printTable("Top Functions By Hit Count", byHits, (row) => String(row.hitCount));
+	printTable("Top Functions By Total Time", byTotal, (row) => `${row.totalMs.toFixed(2)}ms`);
+	printTable(
+		"Top Functions By Worst Single Call",
+		byMax,
+		(row) => `${row.maxMs.toFixed(2)}ms`,
+	);
+	printTable(
+		"Top Classes By Total Trace Time",
+		byClassTotal,
+		(row) => `${row.totalMs.toFixed(2)}ms`,
+	);
+
+	process.stderr.write("\nSlowest Individual Samples\n");
+	for (const hot of hottest) {
+		process.stderr.write(
+			`  ${hot.durationMs.toFixed(2).padStart(10)}ms  ${hot.className}.${hot.methodLabel}\n`,
+		);
+	}
+}
+
+const shouldAnalyzeTrace = truthy(process.env.BENCH_ANALYZE_TRACE, true);
+const shouldCollectTraceLog = truthy(process.env.BENCH_TRACE_LOG, true);
+const traceLogPath = shouldCollectTraceLog
+	? join(TRACE_LOG_DIR, `perf-trace-${toFileTimestamp()}.log`)
+	: null;
+
+if (traceLogPath != null) {
+	mkdirSync(TRACE_LOG_DIR, { recursive: true });
+}
+
+const result = spawnSync(VITEST_BIN, ["run", "--config", CONFIG, TRACE_SPEC], {
+	cwd: WORKSPACE_ROOT,
+	stdio: "pipe",
+	encoding: "utf8",
+	maxBuffer: 1024 * 1024 * 200,
+	env: {
+		...process.env,
+		NODE_OPTIONS: "",
+		FORGE_TRACE: "1",
+		FORGE_TRACE_STRUCTURED: "1",
+		LOG_LEVEL: process.env.LOG_LEVEL ?? "trace",
+	},
+});
+
+const stdout = typeof result.stdout === "string" ? result.stdout : "";
+const stderr = typeof result.stderr === "string" ? result.stderr : "";
+if (stdout.length > 0) process.stdout.write(stdout);
+if (stderr.length > 0) process.stderr.write(stderr);
+
+const combined = `${stdout}${stderr.length > 0 ? `\n${stderr}` : ""}`;
+if (traceLogPath != null) {
+	writeFileSync(traceLogPath, combined);
+	process.stderr.write(`\n✓  Trace log written: ${traceLogPath}\n`);
+}
+
+if (shouldAnalyzeTrace) {
+	analyzeTraceOutput(combined);
+}
+
+if (result.status !== 0) {
+	process.exit(result.status ?? 1);
+}

package/src/changeset/aggregate-changelog.mjs

@@ -0,0 +1,119 @@
+/**
+ * Aggregates pending .changeset/*.md entries into the root CHANGELOG.md,
+ * then deletes the consumed entry files.
+ *
+ * Changeset entry format:
+ *   ---
+ *   "@pkg/name": major|minor|patch
+ *   ---
+ *   Human-readable description of the change.
+ *
+ * Usage: node aggregate-changelog.mjs [--dry-run]
+ *   --dry-run   Print what would be written without modifying any files.
+ */
+
+import { readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const dryRun = process.argv.includes("--dry-run");
+const root = process.cwd();
+const changesetDir = join(root, ".changeset");
+
+/** Bump type precedence (higher = more significant) */
+const PRECEDENCE = { major: 3, minor: 2, patch: 1, prerelease: 0 };
+
+/** Section headers for each bump type */
+const SECTION_HEADINGS = {
+	major: "Breaking Changes",
+	minor: "Minor Changes",
+	patch: "Patch Changes",
+};
+
+let entries;
+try {
+	const allFiles = await readdir(changesetDir);
+	entries = allFiles.filter((f) => f.endsWith(".md") && f !== "README.md");
+} catch {
+	console.log("No .changeset directory found. Nothing to aggregate.");
+	process.exit(0);
+}
+
+if (entries.length === 0) {
+	console.log("No pending changeset entries found. Nothing to aggregate.");
+	process.exit(0);
+}
+
+/** Parse a single changeset file → { packages: Record<string, string>, body: string } */
+function parseEntry(content) {
+	const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+	if (!match) return null;
+	const packages = {};
+	for (const line of match[1].split("\n")) {
+		const m = line.match(/^"([^"]+)"\s*:\s*(\w+)/);
+		if (m) packages[m[1]] = m[2];
+	}
+	return { packages, body: match[2].trim() };
+}
+
+/** Group entries into sections by the highest bump type they declare */
+const sections = { major: [], minor: [], patch: [] };
+
+for (const file of entries) {
+	const content = await readFile(join(changesetDir, file), "utf8");
+	const parsed = parseEntry(content);
+	if (!parsed) {
+		console.warn(`Skipping malformed changeset: ${file}`);
+		continue;
+	}
+
+	const bumpTypes = Object.values(parsed.packages);
+	const highestBump = bumpTypes.reduce((max, t) => {
+		return (PRECEDENCE[t] ?? -1) > (PRECEDENCE[max] ?? -1) ? t : max;
+	}, "patch");
+
+	const section = sections[highestBump] ?? sections.patch;
+	const pkgList = Object.keys(parsed.packages)
+		.map((p) => `\`${p}\``)
+		.join(", ");
+	section.push(`- **${pkgList}**: ${parsed.body}`);
+}
+
+const date = new Date().toISOString().slice(0, 10);
+const sectionBlocks = [];
+
+for (const [type, heading] of Object.entries(SECTION_HEADINGS)) {
+	if (sections[type].length > 0) {
+		sectionBlocks.push(`### ${heading}\n\n${sections[type].join("\n")}`);
+	}
+}
+
+if (sectionBlocks.length === 0) {
+	console.log("No parseable changeset entries. Nothing written.");
+	process.exit(0);
+}
+
+const newEntry = `## ${date}\n\n${sectionBlocks.join("\n\n")}\n\n`;
+
+let existing = "";
+try {
+	existing = await readFile(join(root, "CHANGELOG.md"), "utf8");
+} catch {
+	/* new file */
+}
+
+if (dryRun) {
+	console.log("[dry-run] Would prepend to CHANGELOG.md:");
+	console.log(newEntry);
+	console.log(`[dry-run] Would delete ${entries.length} changeset file(s):`, entries);
+	process.exit(0);
+}
+
+await writeFile(join(root, "CHANGELOG.md"), newEntry + existing);
+console.log(`Wrote aggregated changelog with ${entries.length} changeset(s).`);
+
+for (const file of entries) {
+	await rm(join(changesetDir, file));
+}
+console.log(`Deleted ${entries.length} consumed changeset file(s).`);
+
+console.log(`Wrote aggregated changelog with ${sections.length} package(s).`);

package/src/changeset/check-status.mjs

@@ -0,0 +1,54 @@
+/**
+ * Checks whether there is at least one pending changeset entry describing the
+ * nature of the changes (breaking, minor, or patch). Works in workspace/lockstep
+ * mode: one entry covering any package is sufficient — you do NOT need an entry
+ * per package.
+ *
+ * Usage: node check-status.mjs [--allow-empty]
+ *   --allow-empty   Exit 0 even when no changeset entries are found (e.g. docs-only PRs)
+ */
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+
+const allowEmpty = process.argv.includes("--allow-empty");
+const root = process.cwd();
+
+// Find all changeset files
+const changesetFiles = await glob(".changeset/*.md", { cwd: root, absolute: false });
+const pendingChangesets = changesetFiles.filter((f) => !f.endsWith("README.md"));
+
+if (pendingChangesets.length === 0 && allowEmpty) {
+	console.log("No pending changesets found (--allow-empty: OK).");
+	process.exit(0);
+}
+
+if (pendingChangesets.length === 0) {
+	console.error("No pending changeset files found in .changeset/");
+	console.error("Run: pnpm changeset  to create one.");
+	process.exit(1);
+}
+
+// Parse which packages are covered and what bump types are declared
+const coveredPackages = new Set();
+const bumpTypes = new Set();
+for (const filePath of pendingChangesets) {
+	const content = await readFile(path.join(root, filePath), "utf8");
+	const match = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!match) continue;
+	for (const line of match[1].split("\n")) {
+		const m = line.match(/^"([^"]+)"\s*:\s*(\w+)/);
+		if (m) {
+			coveredPackages.add(m[1]);
+			bumpTypes.add(m[2]);
+		}
+	}
+}
+
+console.log(
+	`Found ${pendingChangesets.length} changeset file(s): bump=${[...bumpTypes].join("/")} packages=${[...coveredPackages].join(", ") || "(none)"}`,
+);
+console.log("OK — changeset entries present.");
+
+console.log("All changed packages have pending changesets.");

package/src/coverage/badge.mjs

@@ -0,0 +1,57 @@
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { parseLcovByProject } from "../lib/lcov.mjs";
+import { createBadgeSvg, getColor } from "../lib/svg.mjs";
+
+const summaryPath = path.resolve("dist/coverage/coverage-summary.json");
+const lcovPath = path.resolve("dist/coverage/lcov.info");
+const badgesDirectory = path.resolve("projects/ci-tools/dist/ci/badges");
+const globalBadgePath = path.join(badgesDirectory, "coverage.svg");
+const projectBadgesDirectory = path.join(badgesDirectory, "projects");
+
+if (!existsSync(summaryPath)) {
+	throw new Error(`Coverage summary not found: ${summaryPath}`);
+}
+
+if (!existsSync(lcovPath)) {
+	throw new Error(`LCOV file not found: ${lcovPath}`);
+}
+
+const summary = JSON.parse(readFileSync(summaryPath, "utf8"));
+const linesCoverage = summary?.total?.lines?.pct;
+
+if (typeof linesCoverage !== "number" || Number.isNaN(linesCoverage)) {
+	throw new Error("Invalid coverage summary: missing total.lines.pct");
+}
+
+const percentage = Number(linesCoverage.toFixed(1));
+const color = getColor(percentage);
+
+mkdirSync(badgesDirectory, { recursive: true });
+writeFileSync(globalBadgePath, createBadgeSvg("Coverage", `${percentage}%`, color));
+
+mkdirSync(projectBadgesDirectory, { recursive: true });
+for (const entry of existsSync(projectBadgesDirectory)
+	? readdirSync(projectBadgesDirectory)
+	: []) {
+	if (entry.endsWith(".svg")) {
+		rmSync(path.join(projectBadgesDirectory, entry));
+	}
+}
+
+const projectCoverage = parseLcovByProject(readFileSync(lcovPath, "utf8"));
+for (const [project, metrics] of [...projectCoverage.entries()].sort(([a], [b]) =>
+	a.localeCompare(b),
+)) {
+	if (metrics.totalLines === 0) continue;
+	const pct = Number(((metrics.coveredLines / metrics.totalLines) * 100).toFixed(1));
+	const projectBadgePath = path.join(projectBadgesDirectory, `${project}.svg`);
+	writeFileSync(projectBadgePath, createBadgeSvg(project, `${pct}%`, getColor(pct)));
+}

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/coverage/report.mjs

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseLcovFiles } from "../lib/lcov.mjs";
+
+function parseArgs(argv) {
+	const options = {
+		lcov: ".forge/coverage/lcov.info",
+		project: undefined,
+		pathPrefix: undefined,
+		top: undefined,
+		json: false,
+	};
+
+	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 === "--project") {
+			options.project = argv[index + 1] ?? options.project;
+			index += 1;
+			continue;
+		}
+		if (arg === "--pathPrefix") {
+			options.pathPrefix = argv[index + 1] ?? options.pathPrefix;
+			index += 1;
+			continue;
+		}
+		if (arg === "--top") {
+			const parsed = Number(argv[index + 1]);
+			if (!Number.isNaN(parsed) && parsed > 0) options.top = parsed;
+			index += 1;
+			continue;
+		}
+		if (arg === "--json") options.json = true;
+	}
+
+	return options;
+}
+
+function formatLineRanges(lines) {
+	if (lines.length === 0) return "-";
+	const ranges = [];
+	let rangeStart = lines[0];
+	let previous = lines[0];
+	for (const current of lines.slice(1)) {
+		if (current === previous + 1) {
+			previous = current;
+			continue;
+		}
+		ranges.push(rangeStart === previous ? `${rangeStart}` : `${rangeStart}-${previous}`);
+		rangeStart = current;
+		previous = current;
+	}
+	ranges.push(rangeStart === previous ? `${rangeStart}` : `${rangeStart}-${previous}`);
+	return ranges.join(",");
+}
+
+function padRight(value, width) {
+	const text = String(value);
+	return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+
+function printHumanReport(files, options) {
+	const totalLines = files.reduce((sum, file) => sum + file.totalLines, 0);
+	const coveredLines = files.reduce((sum, file) => sum + file.coveredLines, 0);
+	const uncoveredLines = totalLines - coveredLines;
+	const linePct = totalLines === 0 ? 100 : (coveredLines / totalLines) * 100;
+
+	const headerProject = options.project == null ? "all projects" : options.project;
+	console.log(`Uncovered lines report (${headerProject})`);
+	console.log(
+		`Scope lines: ${coveredLines}/${totalLines} covered (${linePct.toFixed(2)}%), ${uncoveredLines} uncovered`,
+	);
+	console.log("");
+
+	if (files.length === 0) {
+		console.log("No uncovered files found for this scope.");
+		return;
+	}
+
+	const pathWidth = Math.min(
+		100,
+		Math.max("File".length, ...files.map((file) => file.sourcePath.length)),
+	);
+	console.log(
+		`${padRight("Uncovered", 10)} ${padRight("File", pathWidth)} ${padRight("Line %", 7)} Uncovered line ranges`,
+	);
+	console.log(`${"-".repeat(10)} ${"-".repeat(pathWidth)} ${"-".repeat(7)} ${"-".repeat(24)}`);
+
+	for (const file of files) {
+		const pct = file.totalLines === 0 ? 100 : (file.coveredLines / file.totalLines) * 100;
+		console.log(
+			`${padRight(file.uncoveredLines, 10)} ${padRight(file.sourcePath, pathWidth)} ${padRight(pct.toFixed(2), 7)} ${formatLineRanges(file.uncoveredLineNumbers)}`,
+		);
+	}
+}
+
+const options = parseArgs(process.argv.slice(2));
+const lcovPath = resolve(options.lcov);
+
+if (!existsSync(lcovPath)) {
+	console.error(`LCOV file not found: ${lcovPath}`);
+	console.error("Run coverage first (example: npm run test:coverage)");
+	process.exit(1);
+}
+
+const files = parseLcovFiles(readFileSync(lcovPath, "utf8"));
+const filtered = files.filter((file) => {
+	if (options.project == null) {
+		return options.pathPrefix == null
+			? file.project != null
+			: file.sourcePath.startsWith(options.pathPrefix);
+	}
+	if (file.project !== options.project) return false;
+	return options.pathPrefix == null || file.sourcePath.startsWith(options.pathPrefix);
+});
+
+const uncoveredOnly = filtered
+	.filter((file) => file.uncoveredLines > 0)
+	.sort(
+		(left, right) =>
+			right.uncoveredLines - left.uncoveredLines ||
+			left.sourcePath.localeCompare(right.sourcePath),
+	);
+
+const ranked = options.top == null ? uncoveredOnly : uncoveredOnly.slice(0, options.top);
+
+if (options.json) {
+	console.log(
+		JSON.stringify({ scope: options.project ?? "all", lcovPath, files: ranked }, null, 2),
+	);
+	process.exit(0);
+}
+
+printHumanReport(ranked, options);