nomen-lang 0.6.8 → 0.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nomen-lang",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "The CLI for the Nomen programming language.",
   "keywords": [],
   "license": "ISC",
@@ -17,7 +17,8 @@
     "dist",
     "src",
     "core",
-    "NOMEN_AGENTS.md"
+    "NOMEN_AGENTS.md",
+    "audit_runtime.c"
   ],
   "type": "module",
   "devDependencies": {

package/src/args.ts

@@ -13,6 +13,8 @@ export interface Args {
 	audit_runtime?: string;
 	check: boolean;
 	release: boolean;
+	/** `nomen test` concurrency (max test files in flight); default = CPU count. */
+	jobs?: string;
 	/** Opt in to FP reassociation: float reductions vectorize under NEON
 	 *  (results may differ in the last ulp vs the scalar loop). */
 	fast_math: boolean;
@@ -39,6 +41,8 @@ const STRING_OPTIONS: Map<string, string> = new Map([
 	["lib", "lib"],
 	["l", "lib"],
 	["audit-runtime", "audit_runtime"],
+	["jobs", "jobs"],
+	["j", "jobs"],
 ]);
 
 const BOOLEAN_OPTIONS: Map<string, string> = new Map([
@@ -174,8 +178,9 @@ export function print_help(): void {
 			"  --platform, -p <name>   Target platform: macos, ios, linux, android, windows, web",
 			"  --lib, -l <path>        Path to System library directory (containing package.jsonc)",
 			"  --audit                 Audit the generated program for memory issues",
-			"  --audit-runtime <path>  Path to audit_runtime.c, linked in when --audit is set",
-			"  --release, -r           Build with optimizations (clang -O2; asm passes on aarch64)",
+			"  --audit-runtime <path>  Path to audit_runtime.c (default: auto-discovered — walk-up or the CLI-bundled copy)",
+			"  --jobs, -j <n>          For `nomen test`: max test files run in parallel (default: CPU count)",
+			"  --release, -r           Build with optimizations (clang -O2; aarch64 asm cleanup passes)",
 			"  --fast-math             Allow FP reassociation (float loop reductions vectorize on aarch64)",
 			"  --check                 For `nomen format`: report files that would change",
 			"  -h, --help              Show this help",

package/src/index.ts

@@ -13,7 +13,7 @@ import parse from "../../src/parse.ts";
 import { parse_args, print_help, type Args } from "./args.ts";
 import { run_docs } from "./docs.ts";
 import render_errors, { render_warnings } from "./format_errors.ts";
-import { find_bundled, run_init } from "./init.ts";
+import { find_bundled, find_bundled_audit_runtime, run_init } from "./init.ts";
 import { build_dir_for, outfile_for } from "./paths.ts";
 import { runTests } from "./test.ts";
 import type Config from "./types/Config.ts";
@@ -104,12 +104,13 @@ try {
 		const root = args.in ?? process.cwd();
 		const filter = args.filter ? new RegExp(args.filter) : undefined;
 		const arch = args.arch ?? "aarch64";
-		const ok = runTests(root, {
+		const ok = await runTests(root, {
 			arch,
 			filter,
 			audit: args.audit,
 			audit_runtime: args.audit_runtime,
 			release: args.release,
+			jobs: args.jobs !== undefined ? parseInt(args.jobs, 10) : undefined,
 		});
 		process.exit(ok ? 0 : 1);
 	}
@@ -283,7 +284,10 @@ function resolve_audit_runtime(config: Config, input_path: string): string | und
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return undefined;
+	// Neither the config nor the walk-up found it: fall back to the runtime
+	// bundled with the CLI (live repo copy in the dev tree, shipped copy when
+	// published) so `--audit` works outside the nomen checkout with no flag.
+	return find_bundled_audit_runtime();
 }
 
 function compile_audit_runtime(config: Config, input_path: string, buildDir: string): string {
@@ -405,7 +409,14 @@ function processFile(filename: string, config: Config, mode: Mode, program_args:
 	// `build` links the executable but does not run it; `run` links and runs.
 	startTime = performance.now();
 
-	const audit_obj = config.audit ? compile_audit_runtime(config, resolved, buildDir) : undefined;
+	// The audit runtime is linked under --audit, and also whenever the
+	// program references it: `Tester.audit_count` (System::Test) has a raw
+	// body calling `nomen_audit_count`, so a Tester-using program run without
+	// --audit still needs the (inert) counter object at link time.
+	const needs_audit_runtime = config.audit || result.code.includes("nomen_audit_count");
+	const audit_obj = needs_audit_runtime
+		? compile_audit_runtime(config, resolved, buildDir)
+		: undefined;
 	let link_inputs = codefile;
 	if (companionfile) link_inputs += ` ${companionfile}`;
 	if (audit_obj) link_inputs += ` ${audit_obj}`;

package/src/init.ts

@@ -85,6 +85,16 @@ export function find_bundled(filename: string): string | undefined {
 	return undefined;
 }
 
+// The audit runtime for `--audit` builds: the dev tree's LIVE copy
+// (repo_root/src/audit_runtime.c — a stale bundled snapshot must not shadow
+// it, same posture as the cli/core rule above), else the copy shipped at the
+// package root by `scripts/bundle-assets.mjs` in a published install. Lets
+// `nomen test/run --audit` work outside the nomen checkout with no
+// --audit-runtime flag.
+export function find_bundled_audit_runtime(): string | undefined {
+	return find_bundled("src/audit_runtime.c") ?? find_bundled("audit_runtime.c");
+}
+
 /**
  * `nomen init <name>`: scaffold a new project under `./<name>` with a sensible
  * starting layout (package.jsonc, src/main.nm, a starter test, README and an

package/src/test.ts

@@ -1,17 +1,26 @@
-import { execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 
 import build, { default_platform } from "../../src/build.ts";
 import join from "../../src/join.ts";
 import { get_library } from "../../src/lib.ts";
 import parse from "../../src/parse.ts";
-import { find_bundled } from "./init.ts";
+import { find_bundled, find_bundled_audit_runtime } from "./init.ts";
 import { build_dir_for } from "./paths.ts";
 
 const RECORD_PREFIX = "\\nomen|";
 
+// Promise-returning `execFile`: `nomen test` builds and runs each `*.test.nm`
+// file in its own build folder and its own process, so the (latency-bound)
+// clang/link/run subprocesses overlap across files instead of serializing.
+// A rejected error carries the same `.stdout` / `.stderr` / `.signal` /
+// `.code` fields the previous synchronous `execFileSync` catch sites read.
+const execFile_async = promisify(execFile);
+
 // A discovered test function: `pub func <name> = (ref Tester t)`.
 export interface TestFunction {
 	name: string;
@@ -40,6 +49,10 @@ export interface TestFileResult {
 	// "LEAK: N allocation(s)" lines the audits runtime printed at exit. Empty
 	// unless the file was run with --audit; a non-empty list fails the file.
 	leaks: string[];
+	// Per-test leak attribution (from the harness's `\nomen|leaks` records):
+	// the tests whose allocation balance grew while they ran. Collected in
+	// every run; only --audit fails the file on them.
+	leaking_tests: LeakRecord[];
 	// Set when the compiled binary crashed before finishing (e.g. a segfault
 	// in a test). We still surface whatever records it managed to emit.
 	crashed?: string;
@@ -74,6 +87,13 @@ interface BenchRecord {
 	stddev: number;
 }
 
+// A `\nomen|leaks|<test>|<n>` record: the test's allocation balance grew by
+// `n` between the harness's counter snapshot and the test's end.
+interface LeakRecord {
+	test: string;
+	count: number;
+}
+
 /** Recursively collect `*.test.nm` files under `root`, skipping build output. */
 export function collect_test_files(root: string): string[] {
 	const out: string[] = [];
@@ -192,11 +212,25 @@ export function generate_harness(tests: TestFunction[], benches: BenchFunction[]
 		})
 		.join("\n");
 
-	let main = "\nimport System\nimport System::Test\n\npub func main = () {\n";
+	let main = "\nimport System\nimport System::Test\n";
+	// Per-test leak attribution: the harness snapshots the audit counter
+	// (Tester.audit_count — the audit runtime is linked into every test
+	// build, see run_test_file) before every test and diffs it after. A
+	// positive delta emits a `\nomen|leaks|<test>|<n>` record, which the CLI
+	// reports as a leaking test instead of leaving the file's exit-time
+	// total unattributed.
+	main += "\npub func main = () {\n";
 	main += "\tvar Tester t = Tester()\n";
+	main += "\tvar int64 audit_mark = 0\n";
+	main += "\tvar int64 audit_leaked = 0\n";
 	for (const test of tests) {
+		main += `\taudit_mark = Tester.audit_count()\n`;
 		main += `\tt.begin_test("${escape_nm_string(test.name)}")\n`;
 		main += `\t${test.name}(ref t)\n`;
+		main += `\taudit_leaked = Tester.audit_count() - audit_mark\n`;
+		main += `\tif audit_leaked > 0 {\n`;
+		main += `\t\tConsole.write_line("\\\\nomen|leaks|" + "${escape_nm_string(test.name)}" + "|\\{audit_leaked}")\n`;
+		main += `\t}\n`;
 		main += `\tt.end_test()\n`;
 	}
 	for (const bench of benches) {
@@ -218,6 +252,7 @@ interface RunRecord {
 	tests: TestRecord[];
 	fails: FailRecord[];
 	benches: BenchRecord[];
+	leaks: LeakRecord[];
 	other: string[];
 }
 
@@ -226,6 +261,7 @@ export function parse_records(stdout: string): RunRecord {
 	const tests: TestRecord[] = [];
 	const fails: FailRecord[] = [];
 	const benches: BenchRecord[] = [];
+	const leaks: LeakRecord[] = [];
 	const other: string[] = [];
 	for (const line of stdout.split("\n")) {
 		if (!line.startsWith(RECORD_PREFIX)) {
@@ -245,6 +281,8 @@ export function parse_records(stdout: string): RunRecord {
 			});
 		} else if (kind === "fail") {
 			fails.push({ test: parts[1], message: parts.slice(2).join("|") });
+		} else if (kind === "leaks") {
+			leaks.push({ test: parts[1], count: parseInt(parts[2] || "0", 10) });
 		} else if (kind === "bench") {
 			benches.push({
 				label: parts[1],
@@ -257,22 +295,28 @@ export function parse_records(stdout: string): RunRecord {
 			});
 		}
 	}
-	return { tests, fails, benches, other };
+	return { tests, fails, benches, leaks, other };
 }
 
-/** Pull the exit-time audit "LEAK: N allocation(s)" lines out of stdout. */
+/**
+ * Pull the exit-time audit lines out of stdout: "LEAK: N allocation(s)" (a
+ * nonzero malloc/free balance) and "AUDIT-STALE-FREE: N pointer(s) freed that
+ * were not live audit allocations" (a free that matched no live block — a
+ * foreign pointer or a double free; the runtime no longer passes those to
+ * libc free, so this is the only record they leave). Both fail the file.
+ */
 export function extract_leaks(stdout: string): string[] {
 	return stdout
 		.split("\n")
 		.map((l) => l.trim())
-		.filter((l) => l.startsWith("LEAK:"));
+		.filter((l) => l.startsWith("LEAK:") || l.startsWith("AUDIT-STALE-FREE:"));
 }
 
 /**
  * Compile one `*.test.nm` file (with the generated harness) and run it,
  * returning its parsed records and any crash info.
  */
-export function run_test_file(
+export async function run_test_file(
 	entry_path: string,
 	lib_path: string | undefined,
 	arch: string,
@@ -280,7 +324,7 @@ export function run_test_file(
 	audit_runtime?: string,
 	release = false,
 	cwd?: string,
-): TestFileResult {
+): Promise<TestFileResult> {
 	const start = performance.now();
 	const source_text = fs.readFileSync(entry_path, "utf8");
 	const tests = extract_test_functions(source_text);
@@ -293,8 +337,9 @@ export function run_test_file(
 		tests: [],
 		fails: [],
 		benches: [],
-		other: [],
 		leaks: [],
+		leaking_tests: [],
+		other: [],
 		ms: 0,
 	};
 
@@ -334,25 +379,27 @@ export function run_test_file(
 
 	const buildDir = build_dir_for(resolved, true);
 	if (!fs.existsSync(buildDir)) fs.mkdirSync(buildDir, { recursive: true });
-	// With --audit, compile the audit runtime (malloc/free counting) and link
-	// it in; the generated main calls nomen_audit_check() at exit, printing
-	// "LEAK: N allocation(s)" when the balance is nonzero.
-	let audit_obj: string | undefined;
-	if (audit) {
-		const runtime_src = audit_runtime
-			? path.resolve(audit_runtime)
-			: find_audit_runtime(path.dirname(resolved));
-		if (!runtime_src || !fs.existsSync(runtime_src)) {
-			result.ok = false;
-			result.phase = "setup";
-			result.crashed =
-				"Audit enabled but audit_runtime.c was not found. Pass --audit-runtime <path>.";
-			result.ms = performance.now() - start;
-			return result;
-		}
-		audit_obj = path.join(buildDir, "audit_runtime.o");
-		execFileSync("clang", ["-c", runtime_src, "-o", audit_obj]);
+	// The audit runtime is linked into EVERY test build: the generated
+	// harness polls nomen_audit_count() around every test for per-test leak
+	// attribution, and under --audit the generated main additionally calls
+	// nomen_audit_check() at exit, printing "LEAK: N allocation(s)" when the
+	// balance is nonzero.
+	// Runtime discovery: explicit flag wins; else walk up from the test file
+	// (a nomen checkout's src/audit_runtime.c); else the runtime bundled with
+	// the CLI (live repo copy in the dev tree, shipped copy when published)
+	// so it works outside the nomen checkout with no flag.
+	const runtime_src = audit_runtime
+		? path.resolve(audit_runtime)
+		: (find_audit_runtime(path.dirname(resolved)) ?? find_bundled_audit_runtime());
+	if (!runtime_src || !fs.existsSync(runtime_src)) {
+		result.ok = false;
+		result.phase = "setup";
+		result.crashed = "audit_runtime.c was not found. Pass --audit-runtime <path>.";
+		result.ms = performance.now() - start;
+		return result;
 	}
+	const audit_obj = path.join(buildDir, "audit_runtime.o");
+	await execFile_async("clang", ["-c", runtime_src, "-o", audit_obj]);
 	const platform = default_platform();
 	// Match the run/build command's emission: ObjC-bearing sources (GUI code
 	// pulled in through the library graph) must land in a `.m` TU on Apple
@@ -401,10 +448,7 @@ export function run_test_file(
 		);
 	}
 	try {
-		execFileSync("clang", link_args, {
-			encoding: "utf8",
-			stdio: ["ignore", "pipe", "pipe"],
-		});
+		await execFile_async("clang", link_args, { encoding: "utf8" });
 	} catch (err: any) {
 		const stderr = err.stderr ? err.stderr.toString() : (err.message ?? "");
 		result.ok = false;
@@ -424,13 +468,13 @@ export function run_test_file(
 	let runStdout = "";
 	let crashed: string | undefined;
 	try {
-		runStdout = execFileSync(outfile, [], {
+		const run = await execFile_async(outfile, [], {
 			encoding: "utf8",
-			stdio: ["ignore", "pipe", "pipe"],
 			timeout: 30_000,
 			maxBuffer: 16 * 1024 * 1024,
 			cwd: cwd ?? process.cwd(),
 		});
+		runStdout = run.stdout;
 	} catch (err: any) {
 		runStdout = err.stdout ? err.stdout.toString() : "";
 		if (err.signal === "SIGTERM") {
@@ -444,15 +488,22 @@ export function run_test_file(
 	result.tests = records.tests;
 	result.fails = records.fails;
 	result.benches = records.benches;
+	result.leaking_tests = records.leaks;
 	result.other = records.other;
 	// Under --audit the exit-time audit check prints "LEAK: N allocation(s)"
-	// to stdout when the malloc/free balance is nonzero. Treat any such line
-	// as a failure so a leaked test file cannot stay green.
+	// to stdout when the malloc/free balance is nonzero, and
+	// "AUDIT-STALE-FREE: N ..." for frees that matched no live block. Treat
+	// any such line as a failure so a leaked (or double-freeing) test file
+	// cannot stay green. (The per-test `leaks` records are collected always —
+	// they name the leaking tests — but only --audit makes them fail the
+	// file.)
 	result.leaks = audit ? extract_leaks(runStdout) : [];
-	// Leak lines are surfaced explicitly above; drop them from the generic
+	// Audit lines are surfaced explicitly above; drop them from the generic
 	// stdout dump so they are not printed twice.
 	if (result.leaks.length) {
-		result.other = result.other.filter((l) => !l.trim().startsWith("LEAK:"));
+		result.other = result.other.filter(
+			(l) => !l.trim().startsWith("LEAK:") && !l.trim().startsWith("AUDIT-STALE-FREE:"),
+		);
 	}
 	result.crashed = crashed;
 	if (crashed) result.phase = "run";
@@ -525,6 +576,20 @@ export function report_file(result: TestFileResult): void {
 	for (const leak of result.leaks) {
 		console.log(`   ${C.yellow("⚠")} ${C.yellow(leak)}`);
 	}
+	// Per-test attribution: which tests leaked (the exit-time LEAK line above
+	// is the file total; these name the culprits). Shown under --audit only —
+	// without it the file cannot fail on leaks, so the warning would be noise
+	// on every run.
+	if (result.leaks.length) {
+		for (const lt of result.leaking_tests) {
+			console.log(`   ${C.yellow("⚠")} ${lt.test} ${C.dim(`leaked ${lt.count} allocation(s)`)}`);
+		}
+		if (!result.leaking_tests.length) {
+			console.log(
+				`   ${C.yellow("⚠")} ${C.yellow("LEAK: no per-test attribution — leaked outside a test (harness/setup/teardown) or crashed mid-test")}`,
+			);
+		}
+	}
 	for (const b of result.benches) {
 		console.log(
 			`   ${C.cyan("⏱")} ${b.label} ${C.dim(`(n=${b.n})`)} ` +
@@ -545,12 +610,27 @@ export interface RunTestsOptions {
 	audit?: boolean;
 	audit_runtime?: string;
 	release?: boolean;
+	/**
+	 * Maximum test files built and run concurrently. Each file compiles into
+	 * its own build folder and runs in its own process, so the latency-bound
+	 * clang/link/run steps overlap across files. Defaults to the machine's
+	 * available parallelism; 1 forces the historical sequential order.
+	 */
+	jobs?: number;
+}
+
+/** The default concurrency for `runTests` when no `jobs` is given. */
+export function default_jobs(): number {
+	const n =
+		typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+	return Math.max(1, n);
 }
 
 /**
  * Locate audit_runtime.c for an audited test build: an explicit path wins,
  * otherwise walk up from `dir` looking for a `src/audit_runtime.c` (the same
- * convention the run/build commands use).
+ * convention the run/build commands use). When both miss, the caller falls
+ * back to the CLI-bundled runtime (`find_bundled_audit_runtime`).
  */
 function find_audit_runtime(dir: string): string | undefined {
 	let cur = dir;
@@ -565,7 +645,7 @@ function find_audit_runtime(dir: string): string | undefined {
 }
 
 /** Discover, run, and report every `*.test.nm` under `root`. */
-export function runTests(root: string, options: RunTestsOptions = {}): boolean {
+export async function runTests(root: string, options: RunTestsOptions = {}): Promise<boolean> {
 	const arch = options.arch ?? "aarch64";
 	const lib = resolve_lib_for(root);
 	const files = collect_test_files(root).filter((f) => !options.filter || options.filter.test(f));
@@ -577,20 +657,33 @@ export function runTests(root: string, options: RunTestsOptions = {}): boolean {
 	// fixture paths resolve there no matter where the CLI was invoked from.
 	const binary_cwd = path.resolve(root);
 
-	const results: TestFileResult[] = [];
-	for (const file of files) {
-		const result = run_test_file(
-			file,
-			lib,
-			arch,
-			options.audit,
-			options.audit_runtime,
-			options.release,
-			binary_cwd,
-		);
-		report_file(result);
-		results.push(result);
-	}
+	// Bounded-concurrency pool: at most `jobs` files are in flight. The
+	// parse/build halves are synchronous (no internal awaits), so they run
+	// atomically on the main thread between the subprocess awaits — the
+	// compiler's in-process state never interleaves. Results are collected by
+	// file INDEX and reported after the pool drains, so the report stays in
+	// discovery order regardless of completion order (and stdout isn't
+	// interleaved).
+	const jobs = Math.max(1, Math.min(options.jobs ?? default_jobs(), files.length));
+	const results: TestFileResult[] = new Array(files.length);
+	let next = 0;
+	const worker = async (): Promise<void> => {
+		for (;;) {
+			const i = next++;
+			if (i >= files.length) return;
+			results[i] = await run_test_file(
+				files[i],
+				lib,
+				arch,
+				options.audit,
+				options.audit_runtime,
+				options.release,
+				binary_cwd,
+			);
+		}
+	};
+	await Promise.all(Array.from({ length: jobs }, worker));
+	for (const result of results) report_file(result);
 
 	const elapsed = performance.now() - startTime;
 	const totalFiles = results.length;
@@ -603,6 +696,12 @@ export function runTests(root: string, options: RunTestsOptions = {}): boolean {
 	const totalFailed = results.reduce((a, r) => a + r.tests.reduce((x, t) => x + t.failed, 0), 0);
 	const totalPassed = totalTests - totalFailed;
 	const totalLeaks = results.reduce((a, r) => a + r.leaks.length, 0);
+	// Leak attribution: the count of TESTS that leaked (the old summary
+	// counted FILES — one aggregate LEAK line per file told you nothing about
+	// which test to blame). The per-file report lists the leaking tests; the
+	// files' exit-time totals can exceed the per-test sum when allocations
+	// leak outside any test (harness/setup/teardown).
+	const totalLeakingTests = results.reduce((a, r) => a + r.leaking_tests.length, 0);
 	const anyFailed = results.some((r) => !r.ok);
 
 	console.log("");
@@ -621,8 +720,9 @@ export function runTests(root: string, options: RunTestsOptions = {}): boolean {
 	);
 	if (totalLeaks) {
 		console.log(
-			` ${C.dim("Leaks ")} ${C.yellow(`${totalLeaks} reported`)}` +
-				C.dim(" (--audit; leaked files count as failures)"),
+			` ${C.dim("Leaks ")} ${C.yellow(`${totalLeakingTests} leaking test(s)`)}` +
+				(totalLeakingTests !== totalLeaks ? C.dim(` (${totalLeaks} leaked file(s))`) : "") +
+				C.dim(" (--audit; leaking tests fail their file)"),
 		);
 	}
 	console.log(` ${C.dim(" Time ")} ${format_duration(elapsed)}`);