nomen-lang 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nomen-lang",
-	"version": "0.0.5",
+	"version": "0.0.7",
 	"description": "The CLI for the Nomen programming language.",
 	"keywords": [],
 	"license": "ISC",
@@ -19,16 +19,13 @@
 		"go": "tsx src/index.ts",
 		"register": "pnpm build && pnpm add -g ."
 	},
-	"dependencies": {
-		"chokidar": "^5.0.0",
-		"yargs": "^18.0.0"
-	},
 	"devDependencies": {
-		"@types/node": "^26.1.1",
+		"@types/node": "^26.1.2",
 		"@types/yargs": "^17.0.35",
+		"chokidar": "^5.0.0",
 		"tsx": "^4.23.1",
 		"typescript": "^7.0.2",
 		"vite-plus": "catalog:",
-		"vitest": "catalog:"
+		"yargs": "^18.1.0"
 	}
 }

package/src/bench_loop.nm

@@ -0,0 +1,113 @@
+// Template for one benchmark's timing loop. The CLI substitutes __NAME__,
+// __TARGET__ and __N__ and concatenates this after the test file's source
+// (so it is user code and can call the test file's functions). Kept as a
+// separate .nm file (not a TS template literal) because Nomen's generic syntax
+// (List<int>) is not valid TypeScript and would break the CLI's own build.
+//
+// Placeholders use the leading-AND-trailing `__NAME__` convention so they don't
+// collide with the `__w` / `__i` / `__samples` locals (leading-only).
+//
+// min / max / sum / sum-of-squares are tracked as running aggregates during
+// sampling, so mean and stddev need no `List.at` calls at all. Only the median
+// needs sorted data, so the samples are insertion-sorted afterwards. Every
+// `List.at` / `List.set` is guarded by `idx >= 0 && idx < __samples.length` —
+// the exact bound `List.at`'s constraint requires — because the constraint
+// checker treats an unverifiable index as an out-of-bounds risk (the backends
+// emit unchecked strided loads).
+func bench_loop___NAME__ = (ref Tester t) {
+	// Warm up so the first samples don't pay for cold caches / lazy binding.
+	var int __w = 0
+	while __w < 8 {
+		__TARGET__()
+		__w += 1
+	}
+	// Collect __N__ samples, tracking running aggregates for every statistic
+	// except the median (which needs sorted data).
+	var List<int> __samples = List<int>()
+	var int __sum = 0
+	var float __sum_sq = 0.0
+	var int __min = 0
+	var int __max = 0
+	var int __i = 0
+	while __i < __N__ {
+		const uint64 __t0 = Time.now_ns()
+		__TARGET__()
+		const uint64 __t1 = Time.now_ns()
+		const int __dt = (__t1 - __t0) as int
+		__samples.push(__dt)
+		__sum += __dt
+		__sum_sq = __sum_sq + (__dt as float) * (__dt as float)
+		if __i == 0 {
+			__min = __dt
+			__max = __dt
+		}
+		if __i > 0 {
+			if __dt < __min {
+				__min = __dt
+			}
+			if __dt > __max {
+				__max = __dt
+			}
+		}
+		__i += 1
+	}
+	const int __n = __samples.length
+	if __n > 0 {
+		const float __fn = __n as float
+		const float __mean = (__sum as float) / __fn
+		var float __variance = __sum_sq / __fn - __mean * __mean
+		if __variance < 0.0 {
+			__variance = 0.0
+		}
+		const float __stddev = Math.sqrt(__variance)
+		// Insertion sort the samples so we can pick a median. `length` is
+		// stable throughout (only `set` mutates), so every access is guarded
+		// against `__samples.length` directly.
+		var int __s = 1
+		while __s < __n {
+			if __s >= 0 && __s < __samples.length {
+				const int __v = __samples.at(__s)
+				var int __j = __s
+				var bool __more = true
+				while __more {
+					var int __pm1 = __j - 1
+					if __pm1 >= 0 && __pm1 < __samples.length {
+						const int __prev = __samples.at(__pm1)
+						if __prev > __v {
+							if __j >= 0 && __j < __samples.length {
+								__samples.set(__j, __prev)
+							}
+							__j -= 1
+						} else {
+							__more = false
+						}
+					} else {
+						__more = false
+					}
+				}
+				if __j >= 0 && __j < __samples.length {
+					__samples.set(__j, __v)
+				}
+			}
+			__s += 1
+		}
+		// Median of the sorted samples. Indices are precomputed into locals so
+		// the guards are simple variable bounds.
+		var int __median = __min
+		var int __hi = __n / 2
+		if __hi >= 0 && __hi < __samples.length {
+			__median = __samples.at(__hi)
+		}
+		if __n % 2 == 0 {
+			var int __lo = __n / 2 - 1
+			if __lo >= 0 && __lo < __samples.length {
+				if __hi >= 0 && __hi < __samples.length {
+					var int __a = __samples.at(__lo)
+					var int __b = __samples.at(__hi)
+					__median = (__a + __b) / 2
+				}
+			}
+		}
+		t.record_bench(t.bench_label, __n, __min, __median, __max, __mean, __stddev)
+	}
+}

package/src/docs.ts

@@ -0,0 +1,267 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { get_library, resolve_export_files, type Library } from "../../src/lib.ts";
+import type BaseNode from "../../src/nodes/BaseNode.ts";
+import type BitsetNode from "../../src/nodes/BitsetNode.ts";
+import type EnumNode from "../../src/nodes/EnumNode.ts";
+import type FunctionNode from "../../src/nodes/FunctionNode.ts";
+import type StructNode from "../../src/nodes/StructNode.ts";
+import type TraitNode from "../../src/nodes/TraitNode.ts";
+import type Type from "../../src/nodes/Type.ts";
+import parse from "../../src/parse.ts";
+
+interface DocItem {
+	kind: string;
+	name: string;
+	signature?: string;
+	doc?: string;
+	node: BaseNode;
+}
+
+/**
+ * `nomen docs`: parse every `.nm` file in scope, then write one markdown file per
+ * source file into `<root>/docs/`, mirroring the source tree. Emits a warning
+ * for each top-level `pub` item that has no documentation comment.
+ */
+export function run_docs(explicit_in?: string): void {
+	const root = path.resolve(explicit_in || process.cwd());
+	const { files, library, docs_root } = gather_doc_files(root);
+	if (!files.length) {
+		console.log(`No .nm files found under ${root}`);
+		return;
+	}
+
+	let warnings = 0;
+	let written = 0;
+	for (const file of files) {
+		const text = fs.readFileSync(file, "utf8");
+		let parsed;
+		try {
+			parsed = parse(text, library, file);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.log(`  warning: could not parse ${path.relative(root, file)} (${msg})`);
+			continue;
+		}
+		const items = collect_items(parsed.root, text.length);
+		if (!items.length) continue;
+
+		const rel = path.relative(docs_root, file).replace(/\.nm$/, ".md");
+		const out_path = path.join(docs_root, "docs", rel);
+		const { markdown, warns } = render_file(file, items, text);
+		warnings += warns;
+		fs.mkdirSync(path.dirname(out_path), { recursive: true });
+		fs.writeFileSync(out_path, markdown);
+		written++;
+	}
+
+	console.log(
+		`Wrote ${written} doc file(s) to ${path.join(docs_root, "docs")}` +
+			(warnings ? ` with ${warnings} warning(s)` : ""),
+	);
+}
+
+// Decide which files to document. A package.jsonc with `exports` is a library
+// (document every exported file); otherwise document the resolved input file
+// alongside its module siblings.
+function gather_doc_files(root: string): {
+	files: string[];
+	library: Library | undefined;
+	docs_root: string;
+} {
+	const config_path = path.join(root, "package.jsonc");
+	if (fs.existsSync(config_path)) {
+		try {
+			const raw = fs.readFileSync(config_path, "utf8");
+			const json = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+			const parsed = JSON.parse(json);
+			if (parsed.exports) {
+				let files: string[] = [];
+				for (const pattern of Object.values(parsed.exports) as string[]) {
+					files = files.concat(resolve_export_files(root, pattern));
+				}
+				return { files, library: get_library(root), docs_root: root };
+			}
+		} catch {
+			// fall through
+		}
+	}
+
+	// App / single-file mode: one module folder of siblings.
+	const dir = fs.existsSync(root) && fs.lstatSync(root).isDirectory() ? root : path.dirname(root);
+	let files: string[] = [];
+	try {
+		files = fs
+			.readdirSync(dir)
+			.filter((f) => f.endsWith(".nm"))
+			.map((f) => path.join(dir, f));
+	} catch {
+		// unreadable
+	}
+	return { files, library: resolve_library_for(dir), docs_root: dir };
+}
+
+function resolve_library_for(dir: string): Library | undefined {
+	let d = dir;
+	for (let i = 0; i < 20; i++) {
+		const config_path = path.join(d, "package.jsonc");
+		if (fs.existsSync(config_path)) {
+			try {
+				const raw = fs.readFileSync(config_path, "utf8");
+				const json = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+				const parsed = JSON.parse(json);
+				if (parsed.exports) return get_library(d);
+				if (parsed.imports?.System) return get_library(path.resolve(d, parsed.imports.System));
+			} catch {
+				// ignore
+			}
+		}
+		const lib_config = path.join(d, "core", "package.jsonc");
+		if (fs.existsSync(lib_config)) return get_library(path.join(d, "core"));
+		const parent = path.dirname(d);
+		if (parent === d) break;
+		d = parent;
+	}
+	return undefined;
+}
+
+// Collect this file's own top-level pub declarations (those starting before the
+// appended library source — i.e. defined in `text`, not pulled in for linking).
+function collect_items(root_node: BaseNode, user_length: number): DocItem[] {
+	const items: DocItem[] = [];
+	const statements = (root_node as unknown as { statements: BaseNode[] }).statements;
+	for (const stmt of statements) {
+		if (stmt.start >= user_length) continue;
+		switch (stmt.node_type) {
+			case "struct": {
+				const s = stmt as unknown as StructNode;
+				if (s.visibility !== "pub") break;
+				items.push({
+					kind: s.is_class ? "class" : "struct",
+					name: s.name,
+					doc: s.doc,
+					node: s,
+				});
+				break;
+			}
+			case "trait": {
+				const t = stmt as unknown as TraitNode;
+				if (t.visibility !== "pub") break;
+				items.push({ kind: "trait", name: t.name, doc: t.doc, node: t });
+				break;
+			}
+			case "enum": {
+				const e = stmt as unknown as EnumNode;
+				if (e.visibility !== "pub") break;
+				items.push({ kind: "enum", name: e.name, doc: e.doc, node: e });
+				break;
+			}
+			case "bitset": {
+				const b = stmt as unknown as BitsetNode;
+				if (b.visibility !== "pub") break;
+				items.push({ kind: "bitset", name: b.name, doc: b.doc, node: b });
+				break;
+			}
+			case "func": {
+				const f = stmt as unknown as FunctionNode;
+				if (f.visibility !== "pub") break;
+				items.push({
+					kind: "func",
+					name: f.name,
+					signature: signature_of(f),
+					doc: f.doc,
+					node: f,
+				});
+				break;
+			}
+		}
+	}
+	return items;
+}
+
+function render_file(
+	file: string,
+	items: DocItem[],
+	source: string,
+): { markdown: string; warns: number } {
+	const lines: string[] = [];
+	const title = path.basename(file, ".nm");
+	lines.push(`# ${title}`);
+	lines.push("");
+
+	let warns = 0;
+	for (const item of items) {
+		const where = `${path.basename(file)}:${line_of(source, item.node.start)}`;
+		lines.push(`## \`${heading_of(item)}\``);
+		lines.push("");
+		if (item.doc) {
+			lines.push(item.doc);
+		} else {
+			lines.push(`_No documentation._`);
+			console.log(`  warning: ${item.kind} \`${item.name}\` has no doc comment (${where})`);
+			warns++;
+		}
+		lines.push("");
+
+		// Struct/trait: list pub members.
+		const members = members_of(item.node);
+		if (members.length) {
+			lines.push("**Members:**");
+			lines.push("");
+			for (const m of members) {
+				const sig = signature_of(m);
+				const doc = m.doc ? ` — ${m.doc.split("\n")[0]}` : "";
+				lines.push(`- \`${sig}\`${doc}`);
+			}
+			lines.push("");
+		}
+	}
+	return { markdown: lines.join("\n"), warns };
+}
+
+function heading_of(item: DocItem): string {
+	if (item.kind === "func") return `func ${item.name}${item.signature ?? ""}`;
+	const generic = generic_params_of(item.node);
+	return `${item.kind} ${item.name}${generic}`;
+}
+
+// Render a function signature like `name(type name, …) -> Ret`, omitting the
+// implicit `self` parameter of methods.
+function signature_of(fn: FunctionNode): string {
+	const params = fn.params
+		.filter((p) => !p.is_self_param)
+		.map((p) => `${render_type(p.type)}${p.name ? " " + p.name : ""}`);
+	let sig = `${fn.name}(${params.join(", ")})`;
+	if (fn.return_type?.name) sig += ` -> ${render_type(fn.return_type)}`;
+	return sig;
+}
+
+function members_of(node: BaseNode): FunctionNode[] {
+	if (node.node_type === "struct" || node.node_type === "trait") {
+		const n = node as unknown as { functions: FunctionNode[] };
+		return n.functions.filter((f) => f.visibility === "pub" && !f.name.startsWith("#"));
+	}
+	return [];
+}
+
+function generic_params_of(node: BaseNode): string {
+	const n = node as unknown as { type_params?: string[] };
+	if (n.type_params && n.type_params.length) return `<${n.type_params.join(", ")}>`;
+	return "";
+}
+
+function render_type(t: Type): string {
+	let s = t.name;
+	if (t.type_args?.length) s += `<${t.type_args.map(render_type).join(", ")}>`;
+	if (t.is_ref) s = `ref ${s}`;
+	if (t.is_view) s = `view ${s}`;
+	if (t.is_array) s += "[]";
+	return s;
+}
+
+function line_of(source: string, start: number): number {
+	let line = 1;
+	for (let i = 0; i < start && i < source.length; i++) if (source[i] === "\n") line++;
+	return line;
+}

package/src/format_errors.ts

@@ -47,32 +47,46 @@ function visual_start(line_text: string, col: number): number {
 }
 
 export default function render_errors(source: string, errors: CompileError[]): string {
+	return render_messages(source, errors, "Error");
+}
+
+/** Render `messages` with a `Warning:`/`Error:` label and matching summary. */
+export function render_warnings(source: string, warnings: CompileError[]): string {
+	return render_messages(source, warnings, "Warning");
+}
+
+function render_messages(
+	source: string,
+	messages: CompileError[],
+	severity: "Error" | "Warning",
+): string {
+	if (!messages.length) return "";
 	const lines = source.split("\n");
 	const markers = find_file_markers(source);
 
 	const blocks: string[] = [];
-	for (const error of errors) {
-		const line_text = lines[error.line - 1] ?? "";
+	for (const message of messages) {
+		const line_text = lines[message.line - 1] ?? "";
 
 		// Map the joined-source line back to the originating file + in-file line.
 		let rel_path = "";
-		let file_line = error.line;
+		let file_line = message.line;
 		for (let m = markers.length - 1; m >= 0; m--) {
-			if (markers[m].joined_line < error.line) {
-				file_line = error.line - markers[m].joined_line;
+			if (markers[m].joined_line < message.line) {
+				file_line = message.line - markers[m].joined_line;
 				rel_path = path.relative(process.cwd(), markers[m].abs_path) || markers[m].abs_path;
 				break;
 			}
 		}
 
 		const gutter = " ".repeat(String(file_line).length);
-		const col = Math.max(1, error.column);
+		const col = Math.max(1, message.column);
 		const display_line = line_text.replace(/\t/g, " ".repeat(TAB_WIDTH));
 		const squiggle = "~".repeat(token_width(line_text, col - 1));
 
 		blocks.push(
 			[
-				`Error: ${error.message}`,
+				`${severity}: ${message.message}`,
 				` File: ${rel_path}:${file_line}:${col}`,
 				`${gutter} |`,
 				`${file_line} | ${display_line}`,
@@ -81,6 +95,6 @@ export default function render_errors(source: string, errors: CompileError[]): s
 		);
 	}
 
-	const label = errors.length === 1 ? "error" : "errors";
-	return `\n${blocks.join("\n\n")}\n\n${errors.length} ${label} found.\n`;
+	const label = messages.length === 1 ? severity.toLowerCase() : `${severity.toLowerCase()}s`;
+	return `\n${blocks.join("\n\n")}\n\n${messages.length} ${label} found.\n`;
 }