visaljs 0.0.1 → 0.0.2

package/README.md

@@ -9,9 +9,24 @@ visaljs build app.js -o app
 ./app
 ```
 
-Needs Node 22 or later and a C compiler (`cc`, `gcc` or `clang`). Linux and macOS for now.
+Needs Node 22 or later and a C compiler (`cc`, `gcc` or `clang`). Linux and macOS for now; on Windows, run it under WSL.
 The C runtime is built on first use and cached in `~/.cache/visaljs`.
 
+`visaljs build` reports each step as it goes:
+
+```
+ ✓ 🔍 Detected GCC 13.3.0  10ms
+ ✓ 📦 Rolled 6 modules into a single file (63.7 kB)  37ms
+ ✓ 🌳 Parsed 1,988 lines of JavaScript  60ms
+ ✓ 🧩 Compiled 1 regular expression  6ms
+ ✓ 🔧 Converted 272 functions to IR and optimized them  46ms
+ ✓ 📝 Emitted 21,951 lines of C code (1.2 MB)  39ms
+ ✓ 📚 Runtime libraries ready (cached ⚡)  39ms
+ ✓ 🔨 Compiled the binary (-O2, stripped)  6.57s
+
+ 🎉 Built srv in 6.85s: 1.2 MB, fits on a floppy disk 💾
+```
+
 ```
 usage: visaljs build <entry.js> [options]
 
@@ -25,6 +40,7 @@ options:
   --all-builtins     install every built-in, not only those the program names
   --no-bundle        skip the bundler: the input is one ES module (a bundle)
   --script           compile as a classic script (sloppy mode, no bundler)
+  -q, --quiet        don't report each step of the build
   --version          print the version
   --help             print this help
 ```

package/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { isBuiltin } from "node:module";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import ts from "typescript";
 import { rolldown } from "rolldown";
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { availableParallelism, homedir, tmpdir } from "node:os";
 //#region \0rolldown/runtime.js
@@ -7470,7 +7470,8 @@ async function bundle(entry, hosts, warn) {
 			const chunk = output[0];
 			return {
 				code: chunk.code,
-				map: chunk.map?.toString() ?? ""
+				map: chunk.map?.toString() ?? "",
+				modules: chunk.moduleIds.filter((id) => !id.startsWith("\0")).length
 			};
 		} finally {
 			await build.close();
@@ -7531,7 +7532,10 @@ function formatLog(log, kind) {
 //#region cli/src/cc.ts
 /** $CC, else the first of the usual C compilers on the PATH. */
 function findCompiler() {
-	if (process.env.CC) return process.env.CC;
+	if (process.env.CC) {
+		if (!compilerVersion(process.env.CC)) throw new Error(`$CC (${process.env.CC}) doesn't run`);
+		return process.env.CC;
+	}
 	for (const cc of [
 		"cc",
 		"clang",
@@ -7552,6 +7556,16 @@ const COMMON = [
 ];
 const LINK = process.platform === "darwin" ? ["-Wl,-dead_strip"] : ["-Wl,--gc-sections"];
 const STRIP = process.platform === "darwin" ? ["-Wl,-S,-x"] : ["-s"];
+/** "GCC 13.3.0", "clang 18.1.3": the compiler's name and version, else its command. */
+function describeCompiler(cc) {
+	const text = compilerVersion(cc);
+	const first = text.split("\n")[0] ?? "";
+	const version = (/version (\d+\.\d+(?:\.\d+)?)/.exec(first) ?? /(\d+\.\d+(?:\.\d+)?)\S*\s*$/.exec(first))?.[1];
+	if (!version) return cc;
+	if (/clang/i.test(text)) return `${/apple/i.test(text) ? "Apple clang" : "clang"} ${version}`;
+	if (/gcc|free software foundation/i.test(text)) return `GCC ${version}`;
+	return `${cc} ${version}`;
+}
 function compilerVersion(cc) {
 	try {
 		return execFileSync(cc, ["--version"], { encoding: "utf8" });
@@ -7559,8 +7573,9 @@ function compilerVersion(cc) {
 		return "";
 	}
 }
-/** Builds (or reuses) lib<name>.a for this toolchain; returns its path. */
-function libraryArchive(tc, lib) {
+/** Builds (or reuses) lib<name>.a for this toolchain; returns its path. `building` hears
+*  about a library that isn't cached, before it's built. */
+function libraryArchive(tc, lib, building) {
 	const hash = createHash("sha256");
 	hash.update(`${tc.cc}\n${compilerVersion(tc.cc)}\n${[
 		...COMMON,
@@ -7573,6 +7588,7 @@ function libraryArchive(tc, lib) {
 	const dir = join(root, `${lib.name}-${key}`);
 	const archive = join(dir, `lib${lib.name}.a`);
 	if (existsSync(archive)) return archive;
+	building?.(lib.name);
 	const work = join(root, `tmp-${process.pid}-${Date.now()}`);
 	mkdirSync(work, { recursive: true });
 	try {
@@ -7636,11 +7652,6 @@ function compileAll(commands) {
 		]
 	});
 }
-/** The runtime's archives for this toolchain, in link order: libjsrt.a, then libbearssl.a
-*  (the test262 host links them too). */
-function runtimeArchives(tc) {
-	return runtimeLibraries().map((l) => libraryArchive(tc, l));
-}
 function cacheRoot() {
 	return process.env.VISALJS_CACHE ?? join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "visaljs");
 }
@@ -7680,12 +7691,17 @@ function regexpCompiler(cc) {
 	renameSync(tmp, tool);
 	return tool;
 }
-/** Compiles program.c and links it with the host packages' libraries, then libjsrt (which they
-*  use). The linker takes only what the program reaches: a program without I/O links no libuv.
-*  The libraries keep their debug info (-g); stripping, when asked, happens at this link. */
-function compileProgram(tc, cFile, output, hosts, extraFlags = []) {
-	const archives = [...hosts.flatMap((h) => h.libraries(RUNTIME_INCLUDE)).filter((l) => l.sources.length).map((l) => libraryArchive(tc, l)), ...runtimeArchives(tc)];
-	execFileSync(tc.cc, [
+/** A program's archives, in link order: the host packages' libraries, then libjsrt (which they
+*  use). Each is built the first time; `building` hears about it. */
+function programArchives(tc, hosts, building) {
+	return [...hosts.flatMap((h) => h.libraries(RUNTIME_INCLUDE)).filter((l) => l.sources.length), ...runtimeLibraries()].map((l) => libraryArchive(tc, l, building));
+}
+/** Compiles program.c and links it with `archives` (programArchives). The linker takes only
+*  what the program reaches: a program without I/O links no libuv. The libraries keep their
+*  debug info (-g); stripping, when asked, happens at this link. Asynchronous: the build's
+*  report keeps drawing while the compiler runs. */
+function compileProgram(tc, cFile, output, archives, extraFlags = []) {
+	const args = [
 		...COMMON,
 		...tc.opt,
 		...extraFlags,
@@ -7697,11 +7713,14 @@ function compileProgram(tc, cFile, output, hosts, extraFlags = []) {
 		...tc.strip ? STRIP : [],
 		"-o",
 		output
-	], { stdio: [
-		"ignore",
-		"inherit",
-		"inherit"
-	] });
+	];
+	return new Promise((resolve, reject) => {
+		spawn(tc.cc, args, { stdio: [
+			"ignore",
+			"inherit",
+			"inherit"
+		] }).on("error", reject).on("close", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`${tc.cc} exited with code ${code}`)));
+	});
 }
 function scratchDir() {
 	const dir = join(tmpdir(), `visaljs-${process.pid}-${Date.now()}`);
@@ -7758,8 +7777,115 @@ function compileRegExps(cc, literals) {
 	return bytecode;
 }
 //#endregion
+//#region cli/src/report.ts
+const CLEAR = "\r\x1B[2K";
+const FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+var Report = class {
+	#write;
+	#style;
+	#start = performance.now();
+	#running;
+	#timer;
+	#frame = 0;
+	/** No style: reports nothing (--quiet, and callers that capture the CLI's output). */
+	constructor(write, style) {
+		this.#write = write;
+		this.#style = style;
+	}
+	/** Runs one step: `label` while it runs, then `done(result)`. A failed step is crossed out
+	*  and its error rethrown, for the caller to print. The spinner turns only while the event
+	*  loop is free: an asynchronous step. */
+	async step(icon, label, run, done) {
+		this.#running = {
+			icon,
+			label,
+			since: performance.now()
+		};
+		if (this.#live) {
+			this.#draw();
+			this.#timer = setInterval(() => (this.#frame++, this.#draw()), 80);
+			this.#timer.unref();
+		}
+		let result;
+		try {
+			result = await run();
+		} catch (e) {
+			this.#end(this.#paint("31", `✗ ${label}`));
+			throw e;
+		}
+		this.#end(`${this.#paint("32", "✓")} ${icon} ${done(result)}`);
+		return result;
+	}
+	/** Renames the running step (what it turned out to be doing). */
+	relabel(label) {
+		if (!this.#running) return;
+		this.#running.label = label;
+		if (this.#live) this.#draw();
+	}
+	/** A message from inside a step (a bundler warning): printed even when quiet. */
+	note(text) {
+		if (this.#live && this.#running) this.#write(CLEAR);
+		this.#write(`${text}\n`);
+		if (this.#live && this.#running) this.#draw();
+	}
+	/** The last line, given the whole build's time. */
+	finish(icon, text) {
+		if (this.#style) this.#write(`\n ${icon} ${this.#paint("1", text(since(this.#start)))}\n`);
+	}
+	get #live() {
+		return this.#style?.live === true;
+	}
+	#paint(code, text) {
+		return this.#style?.color ? `\x1b[${code}m${text}\x1b[0m` : text;
+	}
+	#draw() {
+		const { icon, label } = this.#running;
+		this.#write(`${CLEAR} ${this.#paint("36", FRAMES[this.#frame % FRAMES.length])} ${icon} ${this.#paint("2", `${label}…`)}`);
+	}
+	#end(line) {
+		clearInterval(this.#timer);
+		const start = this.#running.since;
+		this.#running = void 0;
+		if (this.#style) this.#write(`${this.#live ? CLEAR : ""} ${line}  ${this.#paint("2", since(start))}\n`);
+	}
+};
+function since(start) {
+	const ms = performance.now() - start;
+	return ms < 1e3 ? `${Math.round(ms)}ms` : `${(ms / 1e3).toFixed(2)}s`;
+}
+/** 383.2 kB, 1.2 MB (decimal units). */
+function size(bytes) {
+	if (bytes < 1e3) return `${bytes} B`;
+	return bytes < 1e6 ? `${(bytes / 1e3).toFixed(1)} kB` : `${(bytes / 1e6).toFixed(1)} MB`;
+}
+/** The binary's size, put in scale. */
+function sizeQuip(bytes) {
+	const FLOPPY = 1474560;
+	if (bytes <= 65536) return "small enough for a Commodore 64 🕹️";
+	if (bytes <= FLOPPY) return "fits on a floppy disk 💾";
+	return `${Math.ceil(bytes / FLOPPY)} floppy disks' worth 💾`;
+}
+/** "1 module", "1,204 lines". */
+const count = (n, one, many = `${one}s`) => `${n.toLocaleString("en-US")} ${n === 1 ? one : many}`;
+function lineCount(text) {
+	let n = text.length > 0 && !text.endsWith("\n") ? 1 : 0;
+	for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) n++;
+	return n;
+}
+//#endregion
 //#region cli/src/main.ts
-const VERSION = "0.0.1";
+const VERSION = "0.0.2";
 const USAGE = `usage: visaljs build <entry.js> [options]
 
 options:
@@ -7772,6 +7898,7 @@ options:
   --all-builtins     install every built-in, not only those the program names
   --no-bundle        skip the bundler: the input is one ES module (a bundle)
   --script           compile as a classic script (sloppy mode, no bundler)
+  -q, --quiet        don't report each step of the build
   --version          print the version
   --help             print this help
 `;
@@ -7795,6 +7922,10 @@ async function main(argv, io) {
 				"all-builtins": { type: "boolean" },
 				"no-bundle": { type: "boolean" },
 				script: { type: "boolean" },
+				quiet: {
+					type: "boolean",
+					short: "q"
+				},
 				version: { type: "boolean" },
 				help: {
 					type: "boolean",
@@ -7815,6 +7946,10 @@ async function main(argv, io) {
 		io.stdout(USAGE);
 		return values.help ? 0 : 2;
 	}
+	if ((io.platform ?? process.platform) === "win32") {
+		io.stderr("visaljs: Windows is not supported yet; use Linux or macOS (on Windows, WSL works)\n");
+		return 1;
+	}
 	const [command, ...rest] = positionals;
 	switch (command) {
 		case "build":
@@ -7836,13 +7971,23 @@ async function build(entry, options, io) {
 		io.stderr(`visaljs: cannot read ${entry}: ${e.message}\n`);
 		return 1;
 	}
+	const dump = options["dump-ast"] === true || options["dump-ir"] === true;
+	const report = new Report(io.stderr, options.quiet || dump ? void 0 : io.report);
+	const binary = !dump && !options["emit-c"];
 	const hosts = DEFAULT_HOSTS;
 	const primitives = hostPrimitives(hosts);
+	let cc;
+	if (binary) try {
+		cc = await report.step("🔍", "Detecting a C compiler", findCompiler, (cc) => `Detected ${describeCompiler(cc)}${process.env.CC ? " (from $CC)" : ""}`);
+	} catch (e) {
+		io.stderr(`visaljs: ${e.message}\n`);
+		return 1;
+	}
 	const script = options.script === true;
 	const bundled = !script && options["no-bundle"] !== true;
 	let map;
 	if (bundled) try {
-		const b = await bundle(entry, hosts, (message) => io.stderr(`${message}\n`));
+		const b = await report.step("📦", "Rolling the modules into a single file", () => bundle(entry, hosts, (message) => report.note(message)), (b) => `Rolled ${count(b.modules, "module")} into a single file (${size(Buffer.byteLength(b.code))})`);
 		source = b.code;
 		if (b.map) map = new SourceMap(b.map, displayPath);
 	} catch (e) {
@@ -7852,30 +7997,30 @@ async function build(entry, options, io) {
 	}
 	let c;
 	try {
-		const ast = script ? parseScript(source, entry) : parseModule(source, map ? "bundle.js" : entry, map, resolve(entry), primitives);
+		const ast = await report.step("🌳", "Parsing the JavaScript", () => script ? parseScript(source, entry) : parseModule(source, map ? "bundle.js" : entry, map, resolve(entry), primitives), () => `Parsed ${count(lineCount(source), "line")} of JavaScript`);
 		if (options["dump-ast"]) {
 			io.stdout(JSON.stringify(ast, null, 2) + "\n");
 			return 0;
 		}
 		const info = analyze(ast);
 		const literals = regexpLiterals(ast);
-		const regexps = literals.length ? compileRegExps(findCompiler(), literals) : /* @__PURE__ */ new Map();
+		const regexps = literals.length ? await report.step("🧩", "Compiling the regular expressions", () => compileRegExps(cc ??= findCompiler(), literals), () => `Compiled ${count(literals.length, "regular expression")}`) : /* @__PURE__ */ new Map();
 		const unsupported = firstUnsupported(ast);
 		if (unsupported) throw unsupported;
-		const ir = optimize(lower(ast, info));
+		const ir = await report.step("🔧", "Converting to IR and optimizing", () => optimize(lower(ast, info)), (ir) => `Converted ${count(ir.functions.length + 1, "function")} to IR and optimized them`);
 		if (options["dump-ir"]) {
 			io.stdout(printModule(ir));
 			return 0;
 		}
 		const names = programNames(ast);
 		const all = options["all-builtins"] === true;
-		c = emitProgram(ir, {
+		c = await report.step("📝", "Emitting C code", () => emitProgram(ir, {
 			embedSource: options["embed-source"] === true,
 			components: (all ? COMPONENTS : reachableComponents(names)).map((c) => c.symbol),
 			core: all ? void 0 : namedCore(names),
 			regexps,
 			hostPrimitives: primitives
-		});
+		}), (c) => `Emitted ${count(lineCount(c), "line")} of C code (${size(Buffer.byteLength(c))})`);
 	} catch (e) {
 		if (!(e instanceof CompileError)) throw e;
 		io.stderr(`${e.message}\n`);
@@ -7885,18 +8030,25 @@ async function build(entry, options, io) {
 		mkdirSync(options["emit-c"], { recursive: true });
 		writeFileSync(join(options["emit-c"], "program.c"), c);
 		if (bundled) writeFileSync(join(options["emit-c"], "bundle.js"), source);
+		report.finish("📂", (time) => `Wrote ${displayPath(resolve(options["emit-c"], "program.c"))} in ${time}`);
 		return 0;
 	}
 	const output = options.output ?? basename(entry).replace(/\.[cm]?js$/, "");
+	const tc = {
+		cc,
+		opt: options.debug ? ["-O0"] : ["-O2"],
+		strip: !options.debug
+	};
 	const dir = scratchDir();
 	try {
 		const file = join(dir, "program.c");
 		writeFileSync(file, c);
-		compileProgram({
-			cc: findCompiler(),
-			opt: options.debug ? ["-O0"] : ["-O2"],
-			strip: !options.debug
-		}, file, output, hosts);
+		const built = [];
+		const archives = await report.step("📚", "Preparing the runtime libraries", () => programArchives(tc, hosts, (name) => {
+			built.push(`lib${name}`);
+			report.relabel(`Building lib${name} (first build only: it's cached after)`);
+		}), () => built.length ? `Built ${built.join(", ")} (cached for next time)` : "Runtime libraries ready (cached ⚡)");
+		await report.step("🔨", `Compiling with ${describeCompiler(tc.cc)}`, () => compileProgram(tc, file, output, archives), () => `Compiled the binary (${tc.opt.join(" ")}, ${tc.strip ? "stripped" : "with debug info"})`);
 	} catch (e) {
 		io.stderr(`visaljs: C compilation failed: ${e.message}\n`);
 		return 1;
@@ -7906,6 +8058,8 @@ async function build(entry, options, io) {
 			force: true
 		});
 	}
+	const bytes = statSync(output).size;
+	report.finish("🎉", (time) => `Built ${displayPath(resolve(output))} in ${time}: ${size(bytes)}, ${sizeQuip(bytes)}`);
 	return 0;
 }
 /** How diagnostics and #line name an original file: relative to the working directory when
@@ -7917,9 +8071,14 @@ function displayPath(source) {
 }
 //#endregion
 //#region cli/src/cli.ts
+const tty = process.stderr.isTTY === true;
 process.exitCode = await main(process.argv.slice(2), {
 	stdout: (text) => process.stdout.write(text),
-	stderr: (text) => process.stderr.write(text)
+	stderr: (text) => process.stderr.write(text),
+	report: {
+		live: tty,
+		color: tty && !process.env.NO_COLOR && process.env.TERM !== "dumb"
+	}
 });
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visaljs",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Ahead-of-time JavaScript to C compiler: the command line",
   "license": "MIT",
   "repository": {