@c9up/helix 0.1.4 → 0.1.6

package/src/cli/coverage/collect.ts

@@ -1,63 +0,0 @@
-/**
- * Reads every `coverage-*.json` produced by the V8 profiler in a given
- * directory, decodes `file://` URLs, and returns a normalised list of
- * `RawFileCoverage` entries (one per unique script URL).
- *
- * Workers write coverage via `NODE_V8_COVERAGE=<dir>` — the orchestrator
- * sets this env var on every spawn and reads the directory after all
- * workers exit. Multiple workers may record the same file; we return ALL
- * entries here and let `aggregate.ts` merge.
- */
-
-import { readdir, readFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { RawFileCoverage, V8CoverageFile } from "./types.js";
-
-export async function collect(dir: string): Promise<RawFileCoverage[]> {
-	let entries: string[];
-	try {
-		entries = await readdir(dir);
-	} catch {
-		return [];
-	}
-	const jsonFiles = entries.filter((e) => e.endsWith(".json"));
-	const all: RawFileCoverage[] = [];
-	for (const name of jsonFiles) {
-		const p = path.join(dir, name);
-		let parsed: V8CoverageFile;
-		try {
-			const raw = await readFile(p, "utf8");
-			parsed = JSON.parse(raw) as V8CoverageFile;
-		} catch {
-			continue;
-		}
-		for (const script of parsed.result ?? []) {
-			if (!script.url?.startsWith("file://")) continue;
-			// V8 sometimes appends `?query` params (our worker uses them as
-			// cache-busters) — strip them so the same file from two workers
-			// merges correctly.
-			const cleanUrl = script.url.split("?")[0];
-			let file: string;
-			try {
-				file = fileURLToPath(cleanUrl);
-			} catch {
-				continue;
-			}
-			let source = "";
-			try {
-				source = await readFile(file, "utf8");
-			} catch {
-				// Source read may fail for transient temp files or modules that
-				// have been GC'd — leave empty; downstream stages fall back to
-				// offset-only computation.
-			}
-			all.push({
-				file,
-				source,
-				functions: script.functions ?? [],
-			});
-		}
-	}
-	return all;
-}

package/src/cli/coverage/diff/base.ts

@@ -1,46 +0,0 @@
-/**
- * Resolve the default base ref to diff against. Tries, in order:
- *   1. `origin/main`
- *   2. `origin/master`
- *   3. local `main`
- *   4. local `master`
- *
- * Returns `undefined` if none of those exist (so the caller can warn
- * instead of failing the run). Throws when the `git` binary itself is
- * missing — the caller distinguishes "no repo / no ref" (skip
- * gracefully) from "git not installed" (configuration error).
- */
-
-import { spawnSync } from "node:child_process";
-
-const CANDIDATES = ["origin/main", "origin/master", "main", "master"];
-
-export class GitMissingError extends Error {
-	constructor() {
-		super("git binary not found on PATH");
-		this.name = "GitMissingError";
-	}
-}
-
-function runGit(cwd: string, args: string[]): { ok: boolean } {
-	const result = spawnSync("git", args, {
-		cwd,
-		stdio: ["ignore", "pipe", "pipe"],
-	});
-	const err = result.error as NodeJS.ErrnoException | undefined;
-	if (err?.code === "ENOENT") throw new GitMissingError();
-	return { ok: result.status === 0 };
-}
-
-function refExists(cwd: string, ref: string): boolean {
-	return runGit(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])
-		.ok;
-}
-
-export function resolveBaseRef(cwd: string): string | undefined {
-	if (!runGit(cwd, ["rev-parse", "--git-dir"]).ok) return undefined;
-	for (const cand of CANDIDATES) {
-		if (refExists(cwd, cand)) return cand;
-	}
-	return undefined;
-}

package/src/cli/coverage/diff/index.ts

@@ -1,160 +0,0 @@
-/**
- * Diff-coverage facade — wires base resolution → git diff → parser →
- * overlay → reporters → thresholds. Called by `run.ts` after the
- * full-tree finalise.
- */
-
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { enforce } from "../thresholds.js";
-import type {
-	CoverageSummary,
-	Thresholds,
-	ThresholdViolation,
-} from "../types.js";
-import { GitMissingError, resolveBaseRef } from "./base.js";
-import { overlay } from "./overlay.js";
-import { parseDiff } from "./parse.js";
-import { diffJson, diffTextSummary } from "./reporters.js";
-import type { DiffOptions, DiffSummary } from "./types.js";
-
-export type { DiffOptions, DiffSummary } from "./types.js";
-
-export interface DiffFinaliseInput extends DiffOptions {
-	root: string;
-	coverage: CoverageSummary;
-}
-
-export interface DiffFinaliseResult {
-	summary: DiffSummary;
-	violations: ThresholdViolation[];
-	textReport: string;
-	reportFiles: string[];
-	/** When `undefined`, the diff stage was skipped (not in a repo, no
-	 *  base ref, etc.) — callers should print `warning` and move on. */
-	warning?: string;
-}
-
-/**
- * Wrap the diff totals into a `CoverageSummary`-shaped object so we can
- * reuse the full-tree `enforce()` helper. Only `lines`/`statements` are
- * populated; `functions`/`branches` are unsupported in diff mode and are
- * rejected upfront in `validateDiffThresholds`.
- */
-function toCoverageSummary(diff: DiffSummary): CoverageSummary {
-	return {
-		files: [],
-		total: {
-			lines: {
-				covered: diff.total.covered,
-				total: diff.total.added,
-				pct: diff.total.pct,
-			},
-			statements: {
-				covered: diff.total.covered,
-				total: diff.total.added,
-				pct: diff.total.pct,
-			},
-			functions: { covered: 0, total: 0, pct: 100 },
-			branches: { covered: 0, total: 0, pct: 100 },
-		},
-	};
-}
-
-function violationLine(
-	metric: keyof Thresholds,
-	actual: number,
-	threshold: number,
-): string {
-	return `coverage-diff: ${metric} ${actual.toFixed(1)} < threshold ${threshold}`;
-}
-
-/**
- * Reject `functions`/`branches` thresholds in diff mode — we only track
- * line-level diff coverage today, so silently passing those metrics
- * would let users gate on metrics that always read 100%.
- */
-function validateDiffThresholds(t: Thresholds | undefined): void {
-	if (!t) return;
-	const unsupported: string[] = [];
-	if (typeof t.functions === "number" && t.functions > 0)
-		unsupported.push("functions");
-	if (typeof t.branches === "number" && t.branches > 0)
-		unsupported.push("branches");
-	if (unsupported.length > 0) {
-		throw new Error(
-			`diff-cov thresholds: ${unsupported.join(", ")} are not supported (line-only). Drop those keys.`,
-		);
-	}
-}
-
-export async function finaliseDiff(
-	input: DiffFinaliseInput,
-): Promise<DiffFinaliseResult> {
-	validateDiffThresholds(input.thresholds);
-
-	const cwd = input.cwd ?? input.root;
-	let base: string | undefined;
-	try {
-		base = input.base ?? resolveBaseRef(cwd);
-	} catch (err) {
-		if (err instanceof GitMissingError) {
-			return {
-				summary: { files: [], total: { added: 0, covered: 0, pct: 100 } },
-				violations: [],
-				textReport: "",
-				reportFiles: [],
-				warning: "diff-cov: git binary not found on PATH. Skipping.",
-			};
-		}
-		throw err;
-	}
-	if (!base) {
-		return {
-			summary: { files: [], total: { added: 0, covered: 0, pct: 100 } },
-			violations: [],
-			textReport: "",
-			reportFiles: [],
-			warning:
-				"diff-cov: no git base ref resolved (origin/main, main, master). Skipping.",
-		};
-	}
-
-	let diffMap: ReturnType<typeof parseDiff>;
-	try {
-		diffMap = parseDiff({ cwd, base });
-	} catch (err) {
-		return {
-			summary: { files: [], total: { added: 0, covered: 0, pct: 100 } },
-			violations: [],
-			textReport: "",
-			reportFiles: [],
-			warning: `diff-cov: ${err instanceof Error ? err.message : String(err)}`,
-		};
-	}
-
-	const summary = overlay(input.coverage, diffMap);
-
-	const reportFiles: string[] = [];
-	const outputDir = input.outputDir ?? path.join(input.root, "coverage");
-	await mkdir(outputDir, { recursive: true });
-	const file = path.join(outputDir, "coverage-diff.json");
-	await writeFile(file, diffJson(summary, input.root), "utf8");
-	reportFiles.push(file);
-
-	const textReport = diffTextSummary(summary, input.root);
-
-	let violations: ThresholdViolation[] = [];
-	if (input.thresholds) {
-		violations = enforce(toCoverageSummary(summary), input.thresholds);
-	}
-
-	return { summary, violations, textReport, reportFiles };
-}
-
-/** Reformat threshold violations with the `coverage-diff:` prefix. */
-export function diffViolationSummary(violations: ThresholdViolation[]): string {
-	return violations
-		.map((v) => violationLine(v.metric, v.actual, v.threshold))
-		.join("\n");
-}

package/src/cli/coverage/diff/overlay.ts

@@ -1,62 +0,0 @@
-/**
- * Overlay the diff map onto a `CoverageSummary` to compute per-file
- * "added vs covered" totals.
- *
- * For each file in the diff:
- *   - find the matching coverage entry by absolute path
- *   - intersect the added line numbers with `lineHits` (count > 0 means
- *     covered)
- *   - emit a `DiffFileSummary`
- *
- * Files in the diff with no coverage entry are still reported (added
- * lines, 0 covered) so a freshly-added module without any tests shows
- * up red. Files in coverage but not in the diff are skipped (the PR
- * didn't touch them, so they don't move the diff-coverage needle).
- */
-
-import type { CoverageSummary } from "../types.js";
-import type { DiffFileSummary, DiffMap, DiffSummary } from "./types.js";
-
-function pct(covered: number, added: number): number {
-	if (added === 0) return 100;
-	return Math.round((covered / added) * 10000) / 100;
-}
-
-export function overlay(coverage: CoverageSummary, diff: DiffMap): DiffSummary {
-	const coverageByFile = new Map(coverage.files.map((f) => [f.file, f]));
-	const files: DiffFileSummary[] = [];
-	let totalAdded = 0;
-	let totalCovered = 0;
-
-	for (const [file, addedLines] of diff) {
-		if (addedLines.size === 0) continue;
-		const cov = coverageByFile.get(file);
-		const hitsByLine = cov
-			? new Map(cov.lineHits.map((h) => [h.line, h.count]))
-			: undefined;
-		const sortedAdded = [...addedLines].sort((a, b) => a - b);
-		const lineHits: DiffFileSummary["lineHits"] = sortedAdded.map((line) => {
-			const count = hitsByLine?.get(line);
-			return { line, covered: typeof count === "number" && count > 0 };
-		});
-		const covered = lineHits.filter((h) => h.covered).length;
-		files.push({
-			file,
-			added: addedLines.size,
-			covered,
-			lineHits,
-		});
-		totalAdded += addedLines.size;
-		totalCovered += covered;
-	}
-
-	files.sort((a, b) => a.file.localeCompare(b.file));
-	return {
-		files,
-		total: {
-			added: totalAdded,
-			covered: totalCovered,
-			pct: pct(totalCovered, totalAdded),
-		},
-	};
-}

package/src/cli/coverage/diff/parse.ts

@@ -1,121 +0,0 @@
-/**
- * Parse `git diff --unified=0 --no-color <base>...HEAD` output into a
- * `DiffMap`. Why three-dot: it computes the diff at the merge-base, so
- * commits made on `base` AFTER our branch diverged are excluded. That's
- * the "what this PR contributes" semantic users expect.
- *
- * We force `--src-prefix=a/ --dst-prefix=b/` and `core.quotepath=false`
- * so the parser doesn't have to guess at user-side `diff.noprefix` or
- * non-ASCII path quoting.
- *
- * Renames produce `+++ b/<new path>` so they're picked up at the new
- * location. Deletes produce `+++ /dev/null` and are skipped. Binary
- * files produce no `+` lines so they contribute nothing.
- */
-
-import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
-import path from "node:path";
-import type { DiffMap } from "./types.js";
-
-const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
-const FILE_HEADER_PLUS = /^\+\+\+ (?:b\/(.*)|\/dev\/null)$/;
-
-export interface ParseOptions {
-	cwd: string;
-	base: string;
-}
-
-function tryRealpath(p: string): string {
-	try {
-		return realpathSync(p);
-	} catch {
-		return p;
-	}
-}
-
-export function parseDiff(opts: ParseOptions): DiffMap {
-	const result = spawnSync(
-		"git",
-		[
-			"-c",
-			"core.quotepath=false",
-			"diff",
-			"--unified=0",
-			"--no-color",
-			"--src-prefix=a/",
-			"--dst-prefix=b/",
-			`${opts.base}...HEAD`,
-		],
-		{
-			cwd: opts.cwd,
-			encoding: "utf8",
-			maxBuffer: 64 * 1024 * 1024,
-		},
-	);
-	if (result.error) {
-		const err = result.error as NodeJS.ErrnoException;
-		if (err.code === "ENOENT") {
-			throw new Error("git binary not found on PATH");
-		}
-		if (err.code === "ENOBUFS") {
-			throw new Error(
-				"diff output exceeded 64 MB — branch is too divergent to overlay",
-			);
-		}
-		throw new Error(`git diff failed: ${err.message}`);
-	}
-	if (result.status !== 0) {
-		throw new Error(
-			`git diff exited ${result.status}: ${result.stderr?.trim() || "(no stderr — likely shallow clone or pruned ref)"}`,
-		);
-	}
-	return parseDiffString(result.stdout, opts.cwd);
-}
-
-/**
- * Pure parser — exposed separately so tests can feed canned diff
- * strings without spawning git. Keys are canonicalised via realpath so
- * they line up with V8 coverage paths (which `filter.ts` realpaths).
- */
-export function parseDiffString(diff: string, cwd: string): DiffMap {
-	const map: DiffMap = new Map();
-	let currentFile: string | undefined;
-	let nextAddedLine = 0;
-	const lines = diff.split(/\r?\n/);
-	for (const line of lines) {
-		const fileMatch = line.match(FILE_HEADER_PLUS);
-		if (fileMatch) {
-			const newPath = fileMatch[1];
-			if (!newPath) {
-				currentFile = undefined;
-				nextAddedLine = 0;
-				continue;
-			}
-			currentFile = tryRealpath(path.resolve(cwd, newPath));
-			nextAddedLine = 0;
-			continue;
-		}
-		if (!currentFile) continue;
-		const hunkMatch = line.match(HUNK_HEADER);
-		if (hunkMatch) {
-			nextAddedLine = Number.parseInt(hunkMatch[1], 10);
-			continue;
-		}
-		if (line.startsWith("+") && !line.startsWith("+++")) {
-			if (nextAddedLine < 1) {
-				// `+0,0` deletion-only hunks set nextAddedLine = 0; ignore stray
-				// `+` lines rather than emit invalid line numbers.
-				continue;
-			}
-			let set = map.get(currentFile);
-			if (!set) {
-				set = new Set();
-				map.set(currentFile, set);
-			}
-			set.add(nextAddedLine);
-			nextAddedLine += 1;
-		}
-	}
-	return map;
-}

package/src/cli/coverage/diff/reporters.ts

@@ -1,82 +0,0 @@
-/**
- * Diff-coverage reporters: text summary + JSON.
- *
- * The text reporter mirrors the full-tree text format so users can read
- * both side-by-side. JSON is namespaced under `files` to avoid
- * collisions with the literal `total` key (in case a file is named
- * `total`).
- */
-
-import path from "node:path";
-import type { DiffFileSummary, DiffSummary } from "./types.js";
-
-function rel(file: string, root: string): string {
-	const r = path.relative(root, file).split(path.sep).join("/");
-	return r.length > 0 && !r.startsWith("..") ? r : file;
-}
-
-function padRight(s: string, w: number): string {
-	if (s.length === w) return s;
-	if (s.length > w) return `…${s.slice(s.length - w + 1)}`;
-	return s + " ".repeat(w - s.length);
-}
-
-function fmtPct(n: number): string {
-	return `${n.toFixed(2).padStart(6)}%`;
-}
-
-export function diffTextSummary(summary: DiffSummary, root: string): string {
-	const lines: string[] = [];
-	lines.push("");
-	lines.push("── Diff coverage ───────────────────────────────────────────");
-	if (summary.files.length === 0) {
-		lines.push("  No instrumented files were touched by the diff.");
-		lines.push(
-			`  ${summary.total.covered}/${summary.total.added} lines covered`,
-		);
-		return `${lines.join("\n")}\n`;
-	}
-	lines.push(
-		`${padRight("File", 50)}  ${"Covered".padStart(10)}  ${"%".padStart(8)}`,
-	);
-	lines.push("─".repeat(72));
-	for (const f of summary.files) {
-		const ratio = `${f.covered}/${f.added}`;
-		const pct = f.added > 0 ? (f.covered / f.added) * 100 : 100;
-		lines.push(
-			`${padRight(rel(f.file, root), 50)}  ${ratio.padStart(10)}  ${fmtPct(pct)}`,
-		);
-	}
-	lines.push("─".repeat(72));
-	lines.push(
-		`${padRight("Total", 50)}  ${`${summary.total.covered}/${summary.total.added}`.padStart(10)}  ${fmtPct(summary.total.pct)}`,
-	);
-	return `${lines.join("\n")}\n`;
-}
-
-interface DiffJsonFileEntry {
-	added: number;
-	covered: number;
-	lineHits: DiffFileSummary["lineHits"];
-}
-
-interface DiffJsonOutput {
-	total: DiffSummary["total"];
-	files: Record<string, DiffJsonFileEntry>;
-}
-
-export function diffJson(summary: DiffSummary, root: string): string {
-	const filesOut: Record<string, DiffJsonFileEntry> = Object.create(null);
-	for (const f of summary.files) {
-		filesOut[rel(f.file, root)] = {
-			added: f.added,
-			covered: f.covered,
-			lineHits: f.lineHits,
-		};
-	}
-	const out: DiffJsonOutput = {
-		total: summary.total,
-		files: filesOut,
-	};
-	return `${JSON.stringify(out, null, 2)}\n`;
-}

package/src/cli/coverage/diff/types.ts

@@ -1,46 +0,0 @@
-/**
- * Types for the diff-coverage pipeline.
- *
- * `DiffMap` is the output of `parse.ts` — for every file changed in
- * `<base>...HEAD`, the set of 1-based line numbers added or modified
- * (i.e. lines starting with `+` in unified diff, excluding the `+++`
- * header). Deleted lines aren't relevant: we only care whether NEW
- * code is covered.
- *
- * `DiffFileSummary` and `DiffSummary` mirror the shape of the full-tree
- * `FileSummary` / `CoverageSummary` so the existing threshold
- * enforcement machinery applies unchanged.
- */
-
-export type DiffMap = Map<string, Set<number>>;
-
-export interface DiffFileSummary {
-	file: string;
-	/** Lines added by the PR (1-based). */
-	added: number;
-	/** Subset of `added` that have a hit count > 0 in the coverage summary. */
-	covered: number;
-	/** Per-line breakdown for reporters. */
-	lineHits: Array<{ line: number; covered: boolean }>;
-}
-
-export interface DiffSummary {
-	files: DiffFileSummary[];
-	total: {
-		added: number;
-		covered: number;
-		pct: number;
-	};
-}
-
-export interface DiffOptions {
-	enabled: boolean;
-	/** Git revision to diff against. Default: resolved by `base.ts`. */
-	base?: string;
-	/** Inline thresholds. Reuses the full-tree shape. */
-	thresholds?: import("../types.js").Thresholds;
-	/** Output dir for `coverage-diff.json`. Defaults to coverage outputDir. */
-	outputDir?: string;
-	/** Where to spawn `git diff`. Defaults to `process.cwd()`. */
-	cwd?: string;
-}

package/src/cli/coverage/filter.ts

@@ -1,71 +0,0 @@
-// Include / exclude filter for coverage files. Glob subset is
-// implemented in `./glob.ts` (shared with the watch-mode filter).
-//
-// Symlinks are NOT followed: `path.realpath` is used to verify the file
-// actually lives under `root`. Anything pointing outside (off-tree
-// symlinks) is dropped — defence in depth against a malicious source
-// tree dragging unrelated files into the coverage report.
-
-import { realpathSync } from "node:fs";
-import path from "node:path";
-import { compileGlobs, globToRegex, matchesAnyGlob } from "./glob.js";
-import type { RawFileCoverage } from "./types.js";
-
-const DEFAULT_INCLUDE = ["src/**/*.{ts,tsx,js,mjs,cjs}"];
-const DEFAULT_EXCLUDE = [
-	"node_modules/**",
-	"dist/**",
-	"build/**",
-	"coverage/**",
-	".git/**",
-	".wolf/**",
-	"target/**",
-	".next/**",
-	"tests/**",
-	"test/**",
-	"**/*.test.*",
-	"**/*.spec.*",
-];
-
-export interface FilterConfig {
-	root: string;
-	include?: string[];
-	exclude?: string[];
-}
-
-/**
- * Resolve a path's real (canonical) absolute location. Falls back to
- * the lexical path if the file no longer exists (already deleted by the
- * worker exit). Symlinks point at the target's real path.
- */
-function tryRealpath(p: string): string {
-	try {
-		return realpathSync(p);
-	} catch {
-		return p;
-	}
-}
-
-export function filter(
-	raw: RawFileCoverage[],
-	config: FilterConfig,
-): RawFileCoverage[] {
-	const include = compileGlobs(config.include ?? DEFAULT_INCLUDE);
-	const exclude = compileGlobs(config.exclude ?? DEFAULT_EXCLUDE);
-	const root = tryRealpath(path.resolve(config.root));
-	const out: RawFileCoverage[] = [];
-	for (const entry of raw) {
-		const real = tryRealpath(entry.file);
-		const rel = path.relative(root, real).split(path.sep).join("/");
-		if (rel.length === 0 || rel.startsWith("..") || path.isAbsolute(rel)) {
-			continue;
-		}
-		if (!matchesAnyGlob(include, rel)) continue;
-		if (matchesAnyGlob(exclude, rel)) continue;
-		out.push({ ...entry, file: real });
-	}
-	return out;
-}
-
-/** Exposed for tests. */
-export const __test__ = { globToRegex };