@c9up/rover 0.1.3

package/src/templating/SimpleTemplate.ts

@@ -0,0 +1,240 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { RoverError } from "../RoverError.js";
+import { getNative, type NativeRoverIr, toReamError } from "./loadNapi.js";
+
+// The compile + interpret hot path now runs in Rust via napi-rs
+// (`rover-template-engine`). This TS facade keeps the byte-identical public
+// surface — `render` / `renderFile` / `setViewsRoot` / `getViewsRoot` /
+// `resetCache` — and owns everything that touches the filesystem: path
+// resolution (incl. the `viewsRoot` traversal guard), the FS read, the
+// compiled-IR cache, and the transitive partial pre-resolution (D55.2.1). The
+// engine never reads disk (ADR-007). Render-time `{{> partial}}` recursion is
+// detected Rust-side (D55.2.2) and surfaces here as `MAIL_TEMPLATE_RECURSION`.
+
+let viewsRoot = "resources/views/emails";
+// Resolved-absolute-path -> compiled Rust IR handle. Content-blind: an entry is
+// reused verbatim until `resetCache()` (D55.2.3 — NO mtime/content invalidation;
+// locked by `simple-template.test.ts:109-122`).
+const cache = new Map<string, NativeRoverIr>();
+
+export function setViewsRoot(rootDir: string): void {
+	viewsRoot = rootDir;
+}
+
+export function getViewsRoot(): string {
+	return viewsRoot;
+}
+
+/** Reset cached compiled templates (test helper). */
+export function resetCache(): void {
+	cache.clear();
+}
+
+export async function render(
+	source: string,
+	data: Record<string, unknown>,
+): Promise<string> {
+	const ir = compileSource(source);
+	const partials = await buildPartialMap(ir);
+	return renderNative(ir, data, partials);
+}
+
+export async function renderFile(
+	viewPath: string,
+	data: Record<string, unknown>,
+	_visited: Set<string> = new Set(),
+): Promise<string> {
+	const ir = await loadIr(viewPath);
+	const partials = await buildPartialMap(ir);
+	return renderNative(ir, data, partials);
+}
+
+/** Compile inline source to an IR handle, mapping native errors to `RoverError`. */
+function compileSource(source: string): NativeRoverIr {
+	try {
+		return getNative().compile(source);
+	} catch (err) {
+		throw toReamError(err);
+	}
+}
+
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+
+/**
+ * JSON replacer reconciling JS values the pre-migration engine rendered via
+ * `String(raw)` but that `JSON.stringify` drops or rejects at the NAPI boundary:
+ *   - bigint: widen to Number when it round-trips exactly, else refuse (a raw
+ *     `JSON.stringify` would throw a bare TypeError → opaque error).
+ *   - NaN / ±Infinity: JSON encodes both as null, so they would render empty and
+ *     Infinity would silently flip from truthy to falsy. Refuse loudly instead.
+ * Note: a `Date` is serialised by its `toJSON` (ISO-8601), a deliberate change
+ * from the old engine's locale `String(date)` — ISO is the stable mail format.
+ */
+function dataReplacer(_key: string, value: unknown): unknown {
+	if (typeof value === "bigint") {
+		if (value >= MIN_SAFE_BIGINT && value <= MAX_SAFE_BIGINT) {
+			return Number(value);
+		}
+		throw new RoverError(
+			"MAIL_TEMPLATE_SYNTAX",
+			`Cannot render bigint ${value} — it exceeds Number.MAX_SAFE_INTEGER and cannot cross the template engine boundary without precision loss; format it to a string before rendering`,
+		);
+	}
+	if (typeof value === "number" && !Number.isFinite(value)) {
+		throw new RoverError(
+			"MAIL_TEMPLATE_SYNTAX",
+			`Cannot render non-finite number ${value} — NaN and Infinity have no representation across the template engine boundary; format it to a string before rendering`,
+		);
+	}
+	return value;
+}
+
+/** Render a compiled IR, mapping native errors (syntax/recursion) to `RoverError`. */
+function renderNative(
+	ir: NativeRoverIr,
+	data: Record<string, unknown>,
+	partials: Record<string, NativeRoverIr>,
+): string {
+	try {
+		// `data` crosses as a JSON string: `JSON.stringify` is own-enumerable-only,
+		// preserving the engine's `Object.hasOwn` dot-path contract (inherited
+		// prototype-chain props stay invisible — the own-property-only parity test).
+		// `dataReplacer` reconciles bigint / NaN / Infinity (see above).
+		return getNative().renderIr(
+			ir,
+			JSON.stringify(data, dataReplacer),
+			partials,
+		);
+	} catch (err) {
+		throw toReamError(err);
+	}
+}
+
+/** Extract a Node `fs` errno string (e.g. `"ENOENT"`) without an `as` cast. */
+function errnoCode(err: unknown): string {
+	if (err !== null && typeof err === "object") {
+		const code = Reflect.get(err, "code");
+		if (typeof code === "string") return code;
+	}
+	return "";
+}
+
+/**
+ * Resolve + read + compile one template path, caching the compiled IR by its
+ * resolved absolute path. Owns the `MAIL_TEMPLATE_NOT_FOUND` / `_READ_ERROR`
+ * raising (unchanged from the pre-migration engine).
+ */
+async function loadIr(viewPath: string): Promise<NativeRoverIr> {
+	const { resolved, tried } = resolveTemplatePath(viewPath);
+	const cached = cache.get(resolved);
+	if (cached !== undefined) return cached;
+
+	let source: string;
+	try {
+		source = await readFile(resolved, "utf8");
+	} catch (err) {
+		const code = errnoCode(err);
+		// Only ENOENT maps to NOT_FOUND; permission/io errors surface distinctly.
+		if (code !== "ENOENT") {
+			throw new RoverError(
+				"MAIL_TEMPLATE_READ_ERROR",
+				`Template read failed at ${resolved} (${code || "unknown"})`,
+				{
+					hint: "Check filesystem permissions and file descriptor limits.",
+					context: { path: resolved, code, viewsRoot },
+				},
+			);
+		}
+		throw new RoverError(
+			"MAIL_TEMPLATE_NOT_FOUND",
+			`Template not found at ${resolved}`,
+			{
+				hint: "Create the file or update config.mail.viewsRoot.",
+				context: {
+					path: resolved,
+					paths: tried.join(", "),
+					viewsRoot,
+				},
+			},
+		);
+	}
+
+	const ir = compileSource(source);
+	cache.set(resolved, ir);
+	return ir;
+}
+
+/**
+ * Transitively pre-resolve every `{{> name}}` partial reachable from `rootIr`
+ * into a `name -> IR handle` map (D55.2.1). Stops re-descending once a name is
+ * mapped, so a cyclic partial graph terminates here WITHOUT erroring — the
+ * actual `MAIL_TEMPLATE_RECURSION` is raised Rust-side only when the cycle is
+ * really rendered (D55.2.2). Partials read here are cached by resolved path
+ * (content-blind), exactly as the pre-migration recursive `renderFile` did.
+ */
+async function buildPartialMap(
+	rootIr: NativeRoverIr,
+): Promise<Record<string, NativeRoverIr>> {
+	const map: Record<string, NativeRoverIr> = {};
+	const stack: NativeRoverIr[] = [rootIr];
+	while (stack.length > 0) {
+		const ir = stack.pop();
+		if (ir === undefined) break;
+		for (const name of ir.partialNames) {
+			if (Object.hasOwn(map, name)) continue;
+			let partialIr: NativeRoverIr;
+			try {
+				partialIr = await loadIr(`partials/${name}`);
+			} catch (err) {
+				// A partial referenced only inside a falsy `{{#if}}` is never
+				// rendered. The pre-migration engine loaded partials lazily, so a
+				// missing such partial did not error. Skip it here; if it IS reached
+				// at render time the Rust renderer raises MAIL_TEMPLATE_NOT_FOUND.
+				if (
+					err instanceof RoverError &&
+					err.code === "MAIL_TEMPLATE_NOT_FOUND"
+				) {
+					continue;
+				}
+				throw err;
+			}
+			map[name] = partialIr;
+			stack.push(partialIr);
+		}
+	}
+	return map;
+}
+
+/**
+ * Resolve a template path under `viewsRoot`, rejecting any attempt to escape
+ * the root (absolute path outside, or `../` traversal after normalisation).
+ * Returns the resolved absolute path plus the set of candidates tried.
+ */
+function resolveTemplatePath(viewPath: string): {
+	resolved: string;
+	tried: string[];
+} {
+	const rootAbs = path.resolve(viewsRoot);
+	const startingPoint = path.isAbsolute(viewPath)
+		? viewPath
+		: path.resolve(rootAbs, viewPath);
+	const withoutExt = startingPoint;
+	const withExt = startingPoint.endsWith(".html")
+		? startingPoint
+		: `${startingPoint}.html`;
+	const candidate = path.resolve(withExt);
+	const rel = path.relative(rootAbs, candidate);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) {
+		throw new RoverError(
+			"MAIL_TEMPLATE_NOT_FOUND",
+			`Template path "${viewPath}" resolves outside of viewsRoot`,
+			{
+				hint: "Template names must stay under viewsRoot. Absolute paths and `..` traversals are rejected.",
+				context: { path: candidate, viewsRoot: rootAbs },
+			},
+		);
+	}
+	return { resolved: candidate, tried: [withExt, withoutExt] };
+}

package/src/templating/loadNapi.ts

@@ -0,0 +1,169 @@
+// Loads the native `rover-template-engine-napi` binary built by
+// `scripts/copy-napi.mjs` and re-throws load failures as
+// `MAIL_TEMPLATE_NAPI_REQUIRED` (D55.2.4) — actionable hint points at
+// `pnpm --filter @c9up/rover build:napi`.
+//
+// Per cerebrum 2026-04-15 there is NO JS fallback. If the binary fails to load,
+// consumers get a typed `RoverError`. Zero `as` / `any` per `feedback_no_any_types`
+// — every boundary is narrowed with a `Reflect.get` type guard.
+
+import { createRequire } from "node:module";
+import { arch, platform } from "node:process";
+import { fileURLToPath } from "node:url";
+import { RoverError } from "../RoverError.js";
+
+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 RoverError(
+			"MAIL_TEMPLATE_NAPI_REQUIRED",
+			`Unsupported platform/arch '${key}' for @c9up/rover native binary. Supported: ${Object.keys(SUFFIX_MAP).join(", ")}.`,
+			{
+				hint: "Build the native binary on a supported platform with 'pnpm --filter @c9up/rover build:napi'.",
+			},
+		);
+	}
+	return suffix;
+}
+
+/** Opaque handle to a compiled template IR (Rust `RoverIr`). */
+export interface NativeRoverIr {
+	/** Referenced partial names, in document order (descends into if-bodies). */
+	readonly partialNames: readonly string[];
+}
+
+interface NativeExports {
+	readonly engineVersion: () => string;
+	readonly compile: (source: string) => NativeRoverIr;
+	readonly renderIr: (
+		ir: NativeRoverIr,
+		dataJson: string,
+		partials: Record<string, NativeRoverIr>,
+	) => string;
+}
+
+function isNativeExports(value: unknown): value is NativeExports {
+	if (value === null || typeof value !== "object") return false;
+	return (
+		typeof Reflect.get(value, "engineVersion") === "function" &&
+		typeof Reflect.get(value, "compile") === "function" &&
+		typeof Reflect.get(value, "renderIr") === "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/rover/src/templating/loadNapi.ts` (or `dist/…`). The
+	// `.node` lives at the package root `…/packages/rover/index.<suffix>.node`,
+	// two levels up from `src/templating` / `dist/templating`.
+	const suffix = platformSuffix();
+	const candidate = `../../index.${suffix}.node`;
+	let loaded: unknown;
+	let lastErr: unknown;
+	try {
+		loaded = require(candidate);
+	} catch (err) {
+		lastErr = err;
+	}
+	if (loaded === undefined) {
+		const causeMessage =
+			lastErr instanceof Error ? lastErr.message : String(lastErr);
+		// The prebuilt linux binaries target glibc (`-gnu`). On musl hosts (Alpine
+		// containers) the `-gnu` binary fails to dlopen with a libc symbol error —
+		// surface that explicitly rather than only pointing at the build step.
+		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 RoverError(
+			"MAIL_TEMPLATE_NAPI_REQUIRED",
+			`@c9up/rover native binary 'index.${suffix}.node' not found or failed to load near ${here} — run 'pnpm --filter @c9up/rover build:napi' to build it.${muslHint} Cause: ${causeMessage}`,
+			{
+				hint: "Run 'pnpm --filter @c9up/rover build:napi' to compile the native template engine.",
+			},
+		);
+	}
+	if (!isNativeExports(loaded)) {
+		throw new RoverError(
+			"MAIL_TEMPLATE_NAPI_REQUIRED",
+			"@c9up/rover native binary loaded but missing expected exports (engineVersion / compile / renderIr). Rebuild with 'pnpm --filter @c9up/rover build:napi'.",
+			{
+				hint: "The native binary is stale — rebuild with 'pnpm --filter @c9up/rover build:napi'.",
+			},
+		);
+	}
+	cachedNative = loaded;
+	return cachedNative;
+}
+
+/**
+ * Shape of the JSON payload Rust packs into `napi::Error::from_reason`. Rust
+ * guarantees `code` + `message` are present.
+ */
+interface NapiErrorPayload {
+	readonly code: string;
+	readonly message: string;
+}
+
+function isNapiErrorPayload(value: unknown): value is NapiErrorPayload {
+	if (value === null || typeof value !== "object") return false;
+	return (
+		typeof Reflect.get(value, "code") === "string" &&
+		typeof Reflect.get(value, "message") === "string"
+	);
+}
+
+/** Codes the Rust engine legitimately emits, with their actionable hints. */
+const CODE_HINTS: Readonly<Record<string, string>> = {
+	MAIL_TEMPLATE_SYNTAX:
+		"Check the template grammar: {{ var }}, {{{ raw }}}, {{#if x}}...{{/if}}, {{> partial}}.",
+	MAIL_TEMPLATE_RECURSION:
+		"Break the cycle — a template cannot include itself (directly or via partials).",
+	MAIL_TEMPLATE_NOT_FOUND:
+		"Create the referenced partial file or remove the {{> name}} reference.",
+};
+
+/**
+ * Translate a thrown value from a native call into a `RoverError`.
+ * Already a `RoverError` (e.g. the loader threw) → pass through. A `napi::Error`
+ * carrying our `{code,message}` JSON envelope → reconstruct typed (line numbers
+ * preserved in `message`). Anything else → wrap as a syntax error.
+ */
+export function toReamError(err: unknown): RoverError {
+	if (err instanceof RoverError) return err;
+	if (err instanceof Error) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(err.message);
+		} catch {
+			parsed = undefined;
+		}
+		if (isNapiErrorPayload(parsed)) {
+			const hint = CODE_HINTS[parsed.code];
+			if (hint !== undefined) {
+				return new RoverError(parsed.code, parsed.message, { hint });
+			}
+		}
+		return new RoverError(
+			"MAIL_TEMPLATE_SYNTAX",
+			`Native template call failed: ${err.message}`,
+		);
+	}
+	return new RoverError(
+		"MAIL_TEMPLATE_SYNTAX",
+		`Native template call failed with non-Error: ${String(err)}`,
+	);
+}

package/src/testing/FakeMail.ts

@@ -0,0 +1,112 @@
+import type { MailMessage, MailSendOutcome, MailTransport } from "../Mail.js";
+
+export interface FakeMailPredicate {
+	from?: string;
+	to?: string;
+	cc?: string;
+	bcc?: string;
+	replyTo?: string;
+	subject?: string;
+	containing?: string;
+}
+
+export type FakeMailPredicateArg =
+	| FakeMailPredicate
+	| ((m: MailMessage) => boolean);
+
+/**
+ * In-memory transport for tests — captures every `send(message)` call and
+ * exposes Adonis/Laravel-style `assertSent` / `assertNotSent` helpers.
+ *
+ * Not re-exported from the main barrel; reach via `@c9up/rover/testing`.
+ */
+export class FakeMail implements MailTransport {
+	#captured: MailMessage[] = [];
+
+	async send(message: MailMessage): Promise<MailSendOutcome> {
+		this.#captured.push(message);
+		return undefined;
+	}
+
+	/**
+	 * Return a defensive snapshot of captured messages. Each message is cloned
+	 * (shallow-per-field with array copies) so test-side mutations can't bleed
+	 * back into the internal capture store — avoids cross-test contamination.
+	 */
+	getSent(): MailMessage[] {
+		return this.#captured.map((m) => ({
+			from: m.from,
+			to: m.to.slice(),
+			cc: m.cc.slice(),
+			bcc: m.bcc.slice(),
+			replyTo: m.replyTo,
+			subject: m.subject,
+			html: m.html,
+			text: m.text,
+			attachments: m.attachments.slice(),
+			headers: { ...m.headers },
+		}));
+	}
+
+	reset(): void {
+		this.#captured = [];
+	}
+
+	assertSent(predicate: FakeMailPredicateArg): void {
+		const match = makeMatcher(predicate);
+		if (this.#captured.some(match)) return;
+		throw new Error(
+			`mail.assertSent() failed — no captured message matches ${describePredicate(predicate)}.\n${describeCaptured(this.#captured)}`,
+		);
+	}
+
+	assertNotSent(predicate: FakeMailPredicateArg): void {
+		const match = makeMatcher(predicate);
+		const found = this.#captured.find(match);
+		if (!found) return;
+		throw new Error(
+			`mail.assertNotSent() failed — at least one captured message matches ${describePredicate(predicate)}.\n${describeCaptured(this.#captured)}`,
+		);
+	}
+}
+
+function makeMatcher(
+	predicate: FakeMailPredicateArg,
+): (m: MailMessage) => boolean {
+	if (typeof predicate === "function") return predicate;
+	const p = predicate;
+	if (p.containing !== undefined && p.containing === "") {
+		throw new Error(
+			"FakeMail: `containing` predicate cannot be an empty string — it would match every captured message. Pass a non-empty needle.",
+		);
+	}
+	return (m) => {
+		if (p.from !== undefined && m.from !== p.from) return false;
+		if (p.replyTo !== undefined && m.replyTo !== p.replyTo) return false;
+		if (p.subject !== undefined && m.subject !== p.subject) return false;
+		if (p.to !== undefined && !m.to.includes(p.to)) return false;
+		if (p.cc !== undefined && !m.cc.includes(p.cc)) return false;
+		if (p.bcc !== undefined && !m.bcc.includes(p.bcc)) return false;
+		if (p.containing !== undefined) {
+			const needle = p.containing;
+			const inHtml = m.html?.includes(needle) ?? false;
+			const inText = m.text?.includes(needle) ?? false;
+			if (!inHtml && !inText) return false;
+		}
+		return true;
+	};
+}
+
+function describePredicate(predicate: FakeMailPredicateArg): string {
+	if (typeof predicate === "function") return "<function predicate>";
+	return JSON.stringify(predicate);
+}
+
+function describeCaptured(captured: MailMessage[]): string {
+	if (captured.length === 0) return "Captured: (none)";
+	const lines = captured.map(
+		(m, i) =>
+			`  [${i}] to=[${m.to.join(", ")}] subject="${m.subject}" from="${m.from}"`,
+	);
+	return `Captured (${captured.length}):\n${lines.join("\n")}`;
+}