@c9up/helix 0.1.4 → 0.1.5

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 };

package/src/cli/coverage/index.ts

@@ -1,126 +0,0 @@
-/**
- * Coverage facade — wires collect → filter → aggregate → reporters →
- * thresholds. Called by `run.ts` after the worker pool finishes.
- */
-
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { aggregate } from "./aggregate.js";
-import { collect } from "./collect.js";
-import { filter } from "./filter.js";
-import { jsonSummary } from "./reporters/json.js";
-import { lcov } from "./reporters/lcov.js";
-import { textSummary } from "./reporters/text.js";
-import { enforce } from "./thresholds.js";
-import type {
-	CoverageOptions,
-	CoverageSummary,
-	ThresholdViolation,
-} from "./types.js";
-
-export { textSummary } from "./reporters/text.js";
-export { enforce, violationSummary } from "./thresholds.js";
-export type {
-	CoverageOptions,
-	CoverageSummary,
-	ThresholdViolation,
-} from "./types.js";
-
-export interface CoverageSession {
-	/** Temp dir passed as `NODE_V8_COVERAGE` to every worker. */
-	envDir: string;
-	/** Inject into the child environment. */
-	env: NodeJS.ProcessEnv;
-}
-
-/**
- * Create a unique temp directory for a run. The orchestrator passes its
- * path via `NODE_V8_COVERAGE`; every spawned worker writes its own
- * `coverage-*.json` on exit. Returns an env bag the pool forwards.
- */
-export async function openSession(baseDir?: string): Promise<CoverageSession> {
-	const root = baseDir ?? path.join(process.cwd(), ".helix-coverage");
-	const unique = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-	const envDir = path.join(root, unique);
-	await mkdir(envDir, { recursive: true });
-	return {
-		envDir,
-		env: {
-			NODE_V8_COVERAGE: envDir,
-		},
-	};
-}
-
-export interface FinaliseOptions extends CoverageOptions {
-	root: string;
-	session: CoverageSession;
-}
-
-export interface FinaliseResult {
-	summary: CoverageSummary;
-	violations: ThresholdViolation[];
-	textReport: string;
-	/** Absolute paths of written report files (lcov + json-summary). */
-	reportFiles: string[];
-}
-
-const KNOWN_REPORTERS = new Set(["text-summary", "lcov", "json-summary"]);
-
-/**
- * After all workers have exited, read the raw v8 output, aggregate, emit
- * reporters + enforce thresholds.
- *
- * The temp dir is removed in `finally` so a write/aggregate failure
- * doesn't leak gigabytes of raw V8 JSON under `.helix-coverage/`.
- */
-export async function finalise(opts: FinaliseOptions): Promise<FinaliseResult> {
-	try {
-		const raw = await collect(opts.session.envDir);
-		const filtered = filter(raw, {
-			root: opts.root,
-			include: opts.include,
-			exclude: opts.exclude,
-		});
-		const summary = aggregate(filtered);
-
-		// Treat empty array as "use defaults" — same as undefined.
-		const requested =
-			opts.reporters && opts.reporters.length > 0
-				? opts.reporters
-				: ["text-summary", "lcov"];
-		// Warn on unknown reporter names so typos surface (instead of the
-		// reporter silently being skipped).
-		for (const r of requested) {
-			if (!KNOWN_REPORTERS.has(r)) {
-				process.stderr.write(
-					`helix-coverage: unknown reporter "${r}" — known: ${[...KNOWN_REPORTERS].join(", ")}\n`,
-				);
-			}
-		}
-		const outputDir = opts.outputDir ?? path.join(opts.root, "coverage");
-		await mkdir(outputDir, { recursive: true });
-
-		const reportFiles: string[] = [];
-		if (requested.includes("lcov")) {
-			const file = path.join(outputDir, "lcov.info");
-			await writeFile(file, lcov(summary, opts.root), "utf8");
-			reportFiles.push(file);
-		}
-		if (requested.includes("json-summary")) {
-			const file = path.join(outputDir, "coverage-summary.json");
-			await writeFile(file, jsonSummary(summary, opts.root), "utf8");
-			reportFiles.push(file);
-		}
-
-		const textReport = requested.includes("text-summary")
-			? textSummary(summary, opts.root)
-			: "";
-
-		const violations = opts.thresholds ? enforce(summary, opts.thresholds) : [];
-
-		return { summary, violations, textReport, reportFiles };
-	} finally {
-		// Always tidy the temp dir — even on aggregate / writeFile failure.
-		await rm(opts.session.envDir, { recursive: true, force: true });
-	}
-}

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

@@ -1,40 +0,0 @@
-/**
- * `coverage-summary.json` — Istanbul-compatible shape consumed by CI
- * tooling (lcov-reporter-action, Codecov uploaders that prefer JSON).
- *
- * File keys are emitted as paths RELATIVE to `root` so the artifact is
- * portable across machines. The reserved `total` key holds the
- * aggregate; if a real file path collides with it (extraordinarily
- * unlikely after relativisation), we keep the totals row and skip the
- * collision rather than overwrite — protecting the consumer's invariant.
- */
-
-import path from "node:path";
-import type { CoverageSummary } 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;
-}
-
-export function jsonSummary(summary: CoverageSummary, root: string): string {
-	// Use a fresh prototype-less object so a pathological file path of
-	// "__proto__" can't pollute the global Object prototype.
-	const out: Record<string, unknown> = Object.create(null);
-	out.total = summary.total;
-	for (const f of summary.files) {
-		const key = rel(f.file, root);
-		if (key === "total") {
-			// Astronomical edge: a file literally named "total" at the root.
-			// Prefer correctness of the totals row over reporting that file.
-			continue;
-		}
-		out[key] = {
-			lines: f.lines,
-			statements: f.statements,
-			functions: f.functions,
-			branches: f.branches,
-		};
-	}
-	return `${JSON.stringify(out, null, 2)}\n`;
-}

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

@@ -1,54 +0,0 @@
-/**
- * LCOV reporter — writes standard `lcov.info` that Codecov, Coveralls,
- * and IDE coverage gutters consume directly.
- *
- * Format reference: `man geninfo` /
- *   http://ltp.sourceforge.net/coverage/lcov/geninfo.1.php
- *
- * Paths in `SF:` are emitted RELATIVE TO `root` so the same artifact
- * lines up across machines (developer laptop, CI runner, Codecov server).
- */
-
-import path from "node:path";
-import type { CoverageSummary } 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;
-}
-
-export function lcov(summary: CoverageSummary, root: string): string {
-	const out: string[] = [];
-	for (const f of summary.files) {
-		out.push(`TN:`);
-		out.push(`SF:${rel(f.file, root)}`);
-
-		let fnf = 0;
-		let fnh = 0;
-		for (const fn of f.functionHits) {
-			// Skip records lcov rejects (line < 1).
-			if (fn.line < 1) continue;
-			out.push(`FN:${fn.line},${fn.name}`);
-			out.push(`FNDA:${fn.count},${fn.name}`);
-			fnf += 1;
-			if (fn.count > 0) fnh += 1;
-		}
-		out.push(`FNF:${fnf}`);
-		out.push(`FNH:${fnh}`);
-
-		let lf = 0;
-		let lh = 0;
-		for (const l of f.lineHits) {
-			out.push(`DA:${l.line},${l.count}`);
-			lf += 1;
-			if (l.count > 0) lh += 1;
-		}
-		out.push(`LF:${lf}`);
-		out.push(`LH:${lh}`);
-
-		out.push(`BRF:0`);
-		out.push(`BRH:0`);
-		out.push(`end_of_record`);
-	}
-	return `${out.join("\n")}\n`;
-}

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

@@ -1,48 +0,0 @@
-/**
- * Text summary reporter — one line per file + totals, written to stdout.
- * Deliberately terse (mirrors c8's default output) so it fits alongside
- * the test reporter's summary without overwhelming.
- */
-
-import type { CoverageSummary } from "../types.js";
-
-function fmtPct(n: number): string {
-	return `${n.toFixed(2).padStart(6)}%`;
-}
-
-function padRight(s: string, w: number): string {
-	if (s.length === w) return s;
-	if (s.length > w) {
-		// Ellipsize from the LEFT — preserves the filename tail which is
-		// usually more informative than the leading directory.
-		return `…${s.slice(s.length - w + 1)}`;
-	}
-	return s + " ".repeat(w - s.length);
-}
-
-export function textSummary(summary: CoverageSummary, root: string): string {
-	const lines: string[] = [];
-	lines.push("");
-	lines.push("── Coverage ─────────────────────────────────────────────────");
-	lines.push(
-		`${padRight("File", 50)}  ${"Lines".padStart(8)}  ${"Funcs".padStart(8)}`,
-	);
-	lines.push("─".repeat(70));
-	for (const f of summary.files) {
-		const rel = f.file.startsWith(root)
-			? f.file.slice(root.length + 1)
-			: f.file;
-		const linesPct =
-			f.lines.total > 0 ? (f.lines.covered / f.lines.total) * 100 : 100;
-		const fnPct =
-			f.functions.total > 0
-				? (f.functions.covered / f.functions.total) * 100
-				: 100;
-		lines.push(`${padRight(rel, 50)}  ${fmtPct(linesPct)}  ${fmtPct(fnPct)}`);
-	}
-	lines.push("─".repeat(70));
-	lines.push(
-		`${padRight("All files", 50)}  ${fmtPct(summary.total.lines.pct)}  ${fmtPct(summary.total.functions.pct)}`,
-	);
-	return `${lines.join("\n")}\n`;
-}