@c9up/helix 0.1.4 → 0.1.6

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

package/src/cli/coverage/thresholds.ts

@@ -1,73 +0,0 @@
-/**
- * Threshold enforcement — compare each configured metric (`lines` /
- * `functions` / `statements` / `branches`) against the aggregate totals.
- * Returns the list of violations; caller decides whether to set
- * `exitCode = 1` (today: yes, always).
- */
-
-import type {
-	CoverageSummary,
-	Thresholds,
-	ThresholdViolation,
-} from "./types.js";
-
-const METRICS: Array<keyof Thresholds> = [
-	"lines",
-	"functions",
-	"statements",
-	"branches",
-];
-
-/**
- * Validate user-supplied thresholds. Throws on NaN / negative / >100 so
- * config typos fail loudly. Empty / undefined values are accepted (no
- * gate on that metric).
- */
-function validate(thresholds: Thresholds): void {
-	for (const metric of METRICS) {
-		const v = thresholds[metric];
-		if (v === undefined) continue;
-		if (typeof v !== "number" || !Number.isFinite(v)) {
-			throw new Error(
-				`coverage threshold ${metric}: expected a finite number, got ${v}`,
-			);
-		}
-		if (v < 0 || v > 100) {
-			throw new Error(`coverage threshold ${metric}: expected 0–100, got ${v}`);
-		}
-	}
-}
-
-export function enforce(
-	summary: CoverageSummary,
-	thresholds: Thresholds,
-): ThresholdViolation[] {
-	validate(thresholds);
-	const violations: ThresholdViolation[] = [];
-	for (const metric of METRICS) {
-		const threshold = thresholds[metric];
-		if (threshold === undefined) continue;
-		// Compute the actual ratio fresh from totals (without the rounded
-		// `pct`). A threshold of 100 then catches 99.999% correctly instead
-		// of being defeated by `pct`'s 2-decimal rounding.
-		const tot = summary.total[metric];
-		const actual = tot.total === 0 ? 100 : (tot.covered / tot.total) * 100;
-		if (actual < threshold) {
-			violations.push({ metric, actual, threshold });
-		}
-	}
-	return violations;
-}
-
-/**
- * Spec format (AC #5): `coverage: lines 84.2 < threshold 88` — one
- * decimal place, no percent signs.
- */
-export function violationSummary(violations: ThresholdViolation[]): string {
-	return violations
-		.map(
-			(v) =>
-				`coverage: ${v.metric} ${v.actual.toFixed(1)} < threshold ${v.threshold}`,
-		)
-		.join("\n");
-}

package/src/cli/coverage/types.ts

@@ -1,93 +0,0 @@
-/**
- * Shared types for the coverage pipeline.
- *
- * Stages: raw V8 JSON → `RawFileCoverage` (per-file after filter) →
- * `AggregateCoverage` (merged across workers) → reporters / thresholds.
- */
-
-/** V8 function-range entry as emitted in `coverage-*.json` files. */
-export interface V8Range {
-	startOffset: number;
-	endOffset: number;
-	count: number;
-}
-
-export interface V8Function {
-	functionName: string;
-	ranges: V8Range[];
-	isBlockCoverage: boolean;
-}
-
-export interface V8Script {
-	scriptId: string;
-	url: string;
-	functions: V8Function[];
-}
-
-export interface V8CoverageFile {
-	result: V8Script[];
-}
-
-/**
- * Normalised per-file coverage — the unit passed between the collector,
- * filter, aggregator, reporter and threshold stages.
- */
-export interface RawFileCoverage {
-	/** Absolute file path (decoded from file:// URL). */
-	file: string;
-	/** Source text at the time V8 recorded coverage — needed to compute line
-	 *  offsets. We fall back to reading from disk if absent. */
-	source: string;
-	functions: V8Function[];
-}
-
-export interface FileSummary {
-	file: string;
-	lines: { covered: number; total: number };
-	functions: { covered: number; total: number };
-	statements: { covered: number; total: number };
-	branches: { covered: number; total: number };
-	/** Line numbers (1-based) with hit counts — for lcov DA entries. */
-	lineHits: Array<{ line: number; count: number }>;
-	/** Functions, with `(name, line, count)` — for lcov FN/FNDA entries. */
-	functionHits: Array<{ name: string; line: number; count: number }>;
-}
-
-export interface Totals {
-	lines: { covered: number; total: number; pct: number };
-	functions: { covered: number; total: number; pct: number };
-	statements: { covered: number; total: number; pct: number };
-	branches: { covered: number; total: number; pct: number };
-}
-
-export interface CoverageSummary {
-	files: FileSummary[];
-	total: Totals;
-}
-
-export interface Thresholds {
-	lines?: number;
-	functions?: number;
-	statements?: number;
-	branches?: number;
-}
-
-export interface ThresholdViolation {
-	metric: keyof Thresholds;
-	actual: number;
-	threshold: number;
-}
-
-export interface CoverageOptions {
-	enabled: boolean;
-	include?: string[];
-	exclude?: string[];
-	reporters?: string[];
-	outputDir?: string;
-	thresholds?: Thresholds;
-	/**
-	 * Project root coverage paths are relative to (typically the package
-	 * directory containing `package.json`). Defaults to `RunConfig.root`.
-	 */
-	root?: string;
-}

package/src/cli/discover.ts

@@ -1,174 +0,0 @@
-/**
- * File-system discovery of test files.
- *
- * Design goals:
- *   - Walks a root directory
- *   - Honours `.gitignore` (basic pattern subset: basename match, leading-`/`
- *     root anchor, directory-trailing `/`, simple `*` glob, path-scoped
- *     `a/*.ts` patterns)
- *   - Uses `lstat` so symlinks are NOT followed (cycle-safe, matches Rust's
- *     `ignore::WalkBuilder::follow_links(false)`)
- *   - Tracks visited absolute paths so any escape via junctions is capped
- *   - Emits a warning on permission-denied subtrees (so silent tests-gone-missing
- *     is visible) while still returning the discoverable set
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { lstat, readdir } from "node:fs/promises";
-import path from "node:path";
-
-export interface DiscoveryOptions {
-	/** Filename suffixes that mark a test file (e.g. `.test.ts`). */
-	suffixes?: string[];
-	/** Directory basenames pruned from the walk. */
-	hardExcludes?: string[];
-	/** Read `.gitignore` at `root` + every descendant and apply rules. */
-	honourGitignore?: boolean;
-	/** Called with a human-readable message when a directory is skipped
-	 *  because of an IO error (ENOENT, EACCES). Default: `console.warn`. */
-	onWarn?: (message: string) => void;
-}
-
-const DEFAULT_SUFFIXES = [
-	".test.ts",
-	".test.tsx",
-	".test.js",
-	".test.mjs",
-	".test.cjs",
-	".spec.ts",
-	".spec.tsx",
-	".spec.js",
-	".spec.mjs",
-	".spec.cjs",
-];
-
-const DEFAULT_HARD_EXCLUDES = [
-	"node_modules",
-	"dist",
-	"build",
-	"coverage",
-	".git",
-	".wolf",
-	"target",
-	".next",
-];
-
-interface GitignorePattern {
-	raw: string;
-	/** If true, pattern is anchored to the directory that defined it. */
-	anchored: boolean;
-	/** If true, pattern only matches directories (trailing `/`). */
-	dirOnly: boolean;
-	/** Regex compiled from the literal pattern, matched against a relative path. */
-	regex: RegExp;
-}
-
-function compilePattern(line: string): GitignorePattern | undefined {
-	let p = line.trim();
-	if (!p || p.startsWith("#")) return undefined;
-	const anchored = p.startsWith("/");
-	if (anchored) p = p.slice(1);
-	const dirOnly = p.endsWith("/");
-	if (dirOnly) p = p.slice(0, -1);
-	if (!p) return undefined;
-	// Translate a tiny glob subset to regex:
-	//   `*` → `[^/]*`
-	//   `**` → `.*`
-	const escaped = p
-		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
-		.replace(/\*\*/g, "__DOUBLESTAR__")
-		.replace(/\*/g, "[^/]*")
-		.replace(/__DOUBLESTAR__/g, ".*");
-	const regex = anchored
-		? new RegExp(`^${escaped}(?:/.*)?$`)
-		: new RegExp(`(?:^|/)${escaped}(?:/.*)?$`);
-	return { raw: line, anchored, dirOnly, regex };
-}
-
-function readGitignore(dir: string): GitignorePattern[] {
-	const file = path.join(dir, ".gitignore");
-	if (!existsSync(file)) return [];
-	try {
-		return readFileSync(file, "utf8")
-			.split("\n")
-			.map(compilePattern)
-			.filter((p): p is GitignorePattern => p !== undefined);
-	} catch {
-		return [];
-	}
-}
-
-function matches(
-	pattern: GitignorePattern,
-	relPath: string,
-	isDir: boolean,
-): boolean {
-	if (pattern.dirOnly && !isDir) return false;
-	return pattern.regex.test(relPath);
-}
-
-export async function discover(
-	root: string,
-	options: DiscoveryOptions = {},
-): Promise<string[]> {
-	const suffixes = options.suffixes ?? DEFAULT_SUFFIXES;
-	const hardExcludes = new Set(options.hardExcludes ?? DEFAULT_HARD_EXCLUDES);
-	const honourGitignore = options.honourGitignore ?? true;
-	const warn = options.onWarn ?? ((m) => process.stderr.write(`helix: ${m}\n`));
-
-	const results: string[] = [];
-	const absRoot = path.isAbsolute(root) ? root : path.resolve(root);
-	const visited = new Set<string>();
-
-	async function walk(
-		dir: string,
-		relativeToRoot: string,
-		inherited: GitignorePattern[],
-	): Promise<void> {
-		const realDir = path.resolve(dir);
-		if (visited.has(realDir)) return;
-		visited.add(realDir);
-
-		let entries: string[];
-		try {
-			entries = await readdir(dir);
-		} catch (err) {
-			warn(`skipping ${dir}: ${(err as NodeJS.ErrnoException).code ?? err}`);
-			return;
-		}
-		const local = honourGitignore
-			? [...inherited, ...readGitignore(dir)]
-			: inherited;
-
-		for (const name of entries) {
-			if (hardExcludes.has(name)) continue;
-			const relPath = relativeToRoot ? `${relativeToRoot}/${name}` : name;
-			const fullPath = path.join(dir, name);
-			let st: Awaited<ReturnType<typeof lstat>>;
-			try {
-				st = await lstat(fullPath);
-			} catch (err) {
-				warn(
-					`skipping ${fullPath}: ${(err as NodeJS.ErrnoException).code ?? err}`,
-				);
-				continue;
-			}
-			// Symlinks are NOT followed. Users who need symlink-following can
-			// walk the target manually; matches Rust's `follow_links(false)`.
-			if (st.isSymbolicLink()) continue;
-			if (local.some((p) => matches(p, relPath, st.isDirectory()))) continue;
-			if (st.isDirectory()) {
-				await walk(fullPath, relPath, local);
-				continue;
-			}
-			if (!st.isFile()) continue;
-			if (suffixes.some((s) => name.endsWith(s))) {
-				results.push(fullPath);
-			}
-		}
-	}
-
-	await walk(absRoot, "", []);
-	results.sort();
-	return results;
-}