nomen-lang 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nomen-lang",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"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/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`;
 }

package/src/index.ts

@@ -8,18 +8,84 @@ import { hideBin } from "yargs/helpers";
 import yargs from "yargs/yargs";
 
 import build, { default_platform } from "../../src/build.ts";
+import { format_source, type FormatOptions } from "../../src/format.ts";
 import join from "../../src/join.ts";
 import { get_library } from "../../src/lib.ts";
 import parse from "../../src/parse.ts";
-import render_errors from "./format_errors.ts";
+import { run_docs } from "./docs.ts";
+import render_errors, { render_warnings } from "./format_errors.ts";
 import type Config from "./types/Config.ts";
 
 const SUPPORTED_EXTENSION = ".nm";
 
+type Mode = "check" | "build" | "run";
+
+// Strip `//` line and `/* */` block comments so a .jsonc file parses as JSON.
+function parse_jsonc(text: string): any {
+	return JSON.parse(text.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, ""));
+}
+
+/** Read the `format` options from the nearest package.jsonc above `start`. */
+function load_format_options(start: string): Partial<FormatOptions> {
+	let dir = fs.lstatSync(start).isDirectory() ? start : path.dirname(start);
+	for (let i = 0; i < 20; i++) {
+		const config_path = path.join(dir, "package.jsonc");
+		if (fs.existsSync(config_path)) {
+			try {
+				const parsed = parse_jsonc(fs.readFileSync(config_path, "utf8"));
+				if (parsed.format) return parsed.format as Partial<FormatOptions>;
+			} catch {
+				// ignore malformed package.jsonc and keep searching
+			}
+		}
+		const lib_config = path.join(dir, "core", "package.jsonc");
+		if (fs.existsSync(lib_config)) {
+			try {
+				const parsed = parse_jsonc(fs.readFileSync(lib_config, "utf8"));
+				if (parsed.format) return parsed.format as Partial<FormatOptions>;
+			} catch {
+				// ignore
+			}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return {};
+}
+
+/** Recursively collect every `.nm` file under `folder`. */
+function collect_nm_files(folder: string): string[] {
+	const out: string[] = [];
+	for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+		const full = path.join(folder, entry.name);
+		if (entry.isDirectory()) out.push(...collect_nm_files(full));
+		else if (shouldProcessFile(entry.name)) out.push(full);
+	}
+	return out;
+}
+
+// The folder whose `build/` subdirectory receives compiler output. Set during
+// input resolution: the --in folder, the .nm file's folder, or — for
+// package.jsonc discovery — the package folder (cwd), not the entry's folder.
+let build_root: string | undefined;
+
 console.log("\n~ NOMEN ~\n");
 
-const options = yargs(hideBin(process.argv))
-	.usage("Usage: nomen --in [file/folder]")
+const parser = yargs(hideBin(process.argv))
+	.usage(
+		"Usage:\n" +
+			"  nomen run --in [file/folder]    Parse, check, build and run a program\n" +
+			"  nomen build --in [file/folder]   Parse, check and build (no run)\n" +
+			"  nomen check --in [file/folder]   Parse and check only\n" +
+			"  nomen format [--in folder]       Reformat every .nm file\n" +
+			"  nomen docs [--in file]           Generate markdown documentation",
+	)
+	.command("run", "Parse, check, build and run a program")
+	.command("build", "Parse, check and build (compile and link, but do not run)")
+	.command("check", "Parse and check only")
+	.command("format", "Reformat every .nm file")
+	.command("docs", "Generate markdown documentation")
 	.option("in", {
 		alias: "i",
 		describe: "Input file or folder",
@@ -64,16 +130,70 @@ const options = yargs(hideBin(process.argv))
 		describe: "Path to audit_runtime.c, linked in when --audit is set",
 		type: "string",
 	})
-	.help(true)
-	.parseSync();
+	.option("check", {
+		describe: "For `nomen format`: report files that would change without writing them",
+		type: "boolean",
+	})
+	.help(true);
+
+const options = parser.parseSync();
+
+const command = options._[0];
 
 try {
+	// `nomen docs` generates markdown documentation instead of compiling.
+	if (command === "docs") {
+		run_docs(typeof options.in === "string" ? options.in : undefined);
+		process.exit(0);
+	}
+
+	// `nomen format` re-indents and tidies every .nm file under a folder.
+	if (command === "format") {
+		const root = options.in ?? process.cwd();
+		const format_options = load_format_options(root);
+		const files = collect_nm_files(root);
+		let changed = 0;
+		for (const file of files) {
+			const source = fs.readFileSync(file, "utf8");
+			const result = format_source(source, format_options);
+			if (result.unsafe) {
+				console.log(`Skipped ${file}: ${result.unsafe}`);
+				continue;
+			}
+			if (result.changed) {
+				if (!options.check) fs.writeFileSync(file, result.code);
+				changed += 1;
+				console.log(`Formatted ${file}`);
+			}
+		}
+		console.log(`\nFormatted ${changed} of ${files.length} file(s).`);
+		process.exit(0);
+	}
+
+	// `run`, `build` and `check` all start from parsed + checked source; `run`
+	// also links and executes, `build` stops after linking, `check` stops after
+	// checking. An unknown (or missing) command prints the help instead.
+	let mode: Mode | undefined;
+	if (command === "run") mode = "run";
+	else if (command === "build") mode = "build";
+	else if (command === "check") mode = "check";
+
+	if (!mode) {
+		parser.showHelp("log");
+		process.exit(1);
+	}
+
 	// An explicit --in wins; otherwise discover what to compile from the
 	// working folder — a package.jsonc `entry`, or a lone .nm file.
 	options.in = options.in ?? resolve_input();
 	if (!options.in) {
 		process.exit(0);
 	}
+	// For an explicit --in, build next to whatever was passed (the folder
+	// itself, or the file's folder). Discovery cases set build_root themselves.
+	if (!build_root) {
+		build_root = fs.lstatSync(options.in).isDirectory() ? options.in : path.dirname(options.in);
+	}
 
 	if (fs.existsSync(options.in)) {
 		let config: Config = { arch: "aarch64", platform: default_platform() };
@@ -90,24 +210,21 @@ try {
 
 		// Is the --in path a folder
 		if (fs.lstatSync(options.in).isDirectory()) {
-			// Loop through files in the folder
-			//processFolder(options.in);
 			if (options.watch) {
-				watchPath(options.in, config);
+				watchPath(options.in, config, mode);
 			} else {
-				processFolder(options.in, config);
+				processFolder(options.in, config, mode);
 			}
 		} else {
 			// Process the supplied file
 			const extname = path.extname(options.in);
 			if (shouldProcessFile(options.in)) {
-				//processFile(options.in);
 				// NOTE: We get add notifications for all watched files immediately
 				// TODO: Is this the case on Windows etc too?
 				if (options.watch) {
-					watchPath(options.in, config);
+					watchPath(options.in, config, mode);
 				} else {
-					processFile(options.in, config);
+					processFile(options.in, config, mode);
 				}
 			} else {
 				console.log("Unsupported file type: " + extname);
@@ -131,6 +248,7 @@ function resolve_input(): string | undefined {
 			const json = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
 			const parsed = JSON.parse(json);
 			if (parsed.entry) {
+				build_root = cwd;
 				return path.resolve(cwd, parsed.entry);
 			}
 		} catch {
@@ -146,6 +264,7 @@ function resolve_input(): string | undefined {
 		// unreadable working folder
 	}
 	if (nm_files.length === 1) {
+		build_root = cwd;
 		return path.resolve(cwd, nm_files[0]);
 	}
 	if (nm_files.length > 1) {
@@ -215,20 +334,20 @@ function compile_audit_runtime(config: Config, input_path: string, buildDir: str
 	return audit_obj;
 }
 
-function watchPath(p: string, config: Config) {
+function watchPath(p: string, config: Config, mode: Mode) {
 	chokidar.watch(p).on("all", (event, filePath) => {
 		if (shouldProcessFile(filePath)) {
-			processFile(filePath, config);
+			processFile(filePath, config, mode);
 		}
 	});
 }
 
-function processFolder(folder: string, config: Config) {
+function processFolder(folder: string, config: Config, mode: Mode) {
 	const dir = fs.opendirSync(folder);
 	let dirent;
 	while ((dirent = dir.readSync()) !== null) {
 		if (shouldProcessFile(dirent.name)) {
-			processFile(path.join(folder, dirent.name), config);
+			processFile(path.join(folder, dirent.name), config, mode);
 			// @ts-ignore
 			let _ = fs.watch;
 		}
@@ -240,7 +359,7 @@ function shouldProcessFile(filename: string) {
 	return path.extname(filename) === SUPPORTED_EXTENSION;
 }
 
-function processFile(filename: string, config: Config) {
+function processFile(filename: string, config: Config, mode: Mode) {
 	console.log("Processing", filename);
 
 	const arch = config.arch || "aarch64";
@@ -253,22 +372,28 @@ function processFile(filename: string, config: Config) {
 
 	let startTime = performance.now();
 
-	let input = join(path.resolve(filename), config.lib);
+	const resolved_path = path.resolve(filename);
+	const input = join(resolved_path, config.lib);
 	const library = config.lib ? get_library(config.lib) : undefined;
-	const parsed = parse(input, library);
-	// TODO: If verbose flag
-	// console.log("Parsed");
+	const parsed = parse(input, library, resolved_path);
 
 	let errors = parsed.errors;
-	const ok = !errors.length;
 
-	if (!ok) {
+	if (errors.length) {
 		console.log(render_errors(input, errors));
 		return;
 	}
 
-	// TODO: If verbose flag
-	// console.log("Built");
+	// Warnings come out of the parse/check phase, so every mode reports them.
+	if (parsed.warnings.length) console.log(render_warnings(input, parsed.warnings));
+
+	// `check` stops after parsing and checking — no building, linking or running.
+	if (mode === "check") {
+		const checkTime = performance.now();
+		console.log(`Checked in ${(checkTime - startTime).toFixed(2)}ms`);
+		return;
+	}
+
 	const result = build(parsed.root, { arch, platform, audit: config.audit });
 
 	if (result.errors && result.errors.length > 0) {
@@ -276,9 +401,8 @@ function processFile(filename: string, config: Config) {
 		return;
 	}
 
-	const dir = path.dirname(filename);
 	const basename = path.basename(filename, ".nm");
-	const buildDir = path.join(dir, "build");
+	const buildDir = path.join(build_root ?? path.dirname(filename), "build");
 	if (!fs.existsSync(buildDir)) {
 		fs.mkdirSync(buildDir, { recursive: true });
 	}
@@ -300,6 +424,7 @@ function processFile(filename: string, config: Config) {
 	console.log(`Created ${codefile} in ${(compileTime - startTime).toFixed(2)}ms`);
 	console.log("");
 
+	// `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;
@@ -311,6 +436,13 @@ function processFile(filename: string, config: Config) {
 			? " -framework CoreGraphics -framework Foundation -framework AppKit -lobjc"
 			: "";
 	execSync(`clang -o ${outfile} ${link_inputs}${framework_flags}`);
+
+	if (mode === "build") {
+		const buildTime = performance.now();
+		console.log(`Built ${outfile} in ${(buildTime - startTime).toFixed(2)}ms`);
+		return;
+	}
+
 	execSync(outfile, { stdio: "inherit" });
 
 	const runTime = performance.now();

package/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+	pack: {
+		dts: false,
+	},
+});

package/dist/index.d.mts

@@ -1 +0,0 @@
-export { };