@c9up/helix 0.1.3 → 0.1.5

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

package/src/cli/native.ts

@@ -1,104 +0,0 @@
-/**
- * Loads the native `ream-test-napi` binary built by `scripts/copy-napi.mjs`
- * and exposes the Rust orchestrator `run(config)` to the TS CLI.
- *
- * Per the orchestrator design (42-N-orchestrator), the Rust NAPI engine is the
- * canonical discovery + worker-pool + reporter + summary path; the TS `runOnce`
- * delegates to it whenever no TS-only layer (coverage / diff-cov / watch / a
- * pluggable reporter instance) is in play. There is NO JS fallback for a failed
- * load — the caller gets a typed error pointing at `build:napi`.
- *
- * Field names are camelCase: napi-rs converts the Rust struct's snake_case
- * fields automatically (`timeout_ms` → `timeoutMs`, etc.).
- */
-
-import { createRequire } from "node:module";
-import { arch, platform } from "node:process";
-import { fileURLToPath } from "node:url";
-
-const SUFFIX_MAP: Readonly<Record<string, string>> = {
-	"linux-x64": "linux-x64-gnu",
-	"linux-arm64": "linux-arm64-gnu",
-	"darwin-x64": "darwin-x64",
-	"darwin-arm64": "darwin-arm64",
-	"win32-x64": "win32-x64-msvc",
-};
-
-function platformSuffix(): string {
-	const key = `${platform}-${arch}`;
-	const suffix = SUFFIX_MAP[key];
-	if (typeof suffix !== "string") {
-		throw new Error(
-			`Unsupported platform/arch '${key}' for @c9up/helix native binary. Supported: ${Object.keys(SUFFIX_MAP).join(", ")}.`,
-		);
-	}
-	return suffix;
-}
-
-/** Mirror of the Rust `RunConfig` (camelCase). */
-export interface NativeRunConfig {
-	readonly root: string;
-	readonly files?: readonly string[];
-	readonly threads?: number;
-	readonly timeoutMs?: number;
-	readonly reporter?: string;
-	readonly workerEntry: string;
-	readonly nodeBin?: string;
-	readonly nodeArgs?: readonly string[];
-	readonly useColors?: boolean;
-}
-
-/** Mirror of the Rust `SummaryPayload` (camelCase). */
-export interface NativeSummaryPayload {
-	readonly pass: number;
-	readonly fail: number;
-	readonly skip: number;
-	readonly todo: number;
-	readonly fileErrors: number;
-	readonly durationMs: number;
-	readonly exitCode: number;
-	/** Full `Summary` serialized as JSON (same shape as TS `Summary`). */
-	readonly json: string;
-}
-
-interface NativeExports {
-	readonly run: (config: NativeRunConfig) => Promise<NativeSummaryPayload>;
-}
-
-function isNativeExports(value: unknown): value is NativeExports {
-	if (value === null || typeof value !== "object") return false;
-	return typeof Reflect.get(value, "run") === "function";
-}
-
-let cachedNative: NativeExports | undefined;
-
-export function getNative(): NativeExports {
-	if (cachedNative !== undefined) return cachedNative;
-
-	const require = createRequire(import.meta.url);
-	const here = fileURLToPath(import.meta.url);
-	// `here` is `…/packages/helix/{src,dist}/cli/native.ts|js`. The `.node` lives
-	// two levels up at `…/packages/helix/index.<suffix>.node`.
-	const suffix = platformSuffix();
-	const candidate = `../../index.${suffix}.node`;
-	let loaded: unknown;
-	try {
-		loaded = require(candidate);
-	} catch (err) {
-		const cause = err instanceof Error ? err.message : String(err);
-		const muslHint = suffix.endsWith("-gnu")
-			? " If you are on Alpine/musl, note the prebuilt binaries target glibc (musl is not a supported target)."
-			: "";
-		throw new Error(
-			`@c9up/helix native binary 'index.${suffix}.node' not found or failed to load near ${here} — run 'pnpm --filter @c9up/helix build:napi' to build it.${muslHint} Cause: ${cause}`,
-			{ cause: err },
-		);
-	}
-	if (!isNativeExports(loaded)) {
-		throw new Error(
-			"@c9up/helix native binary loaded but missing the expected 'run' export. Rebuild with 'pnpm --filter @c9up/helix build:napi'.",
-		);
-	}
-	cachedNative = loaded;
-	return cachedNative;
-}