@specy/x86 2.1.0 → 2.3.0

package/dist/index.mjs

@@ -1,6 +1,245 @@
+import createNasm from "./wasm/nasm.mjs";
 import blinkenlib from "./wasm/blinkenlib.js";
+//#region src/project.ts
+const X86_PROJECT_ROOT = "/__x86_project";
+const stagedFiles = /* @__PURE__ */ new WeakMap();
+function validateX86Project(project) {
+	if (!isProjectPath(project.entry)) throw new Error(`Invalid x86 Project entry path: ${project.entry}`);
+	if (!Object.hasOwn(project.files, project.entry)) throw new Error(`x86 Project entry file not found: ${project.entry}`);
+	if (typeof project.files[project.entry] !== "string") throw new Error(`x86 Project entry must be a text file: ${project.entry}`);
+	for (const [path, contents] of Object.entries(project.files)) {
+		if (!isProjectPath(path)) throw new Error(`Invalid x86 Project file path: ${path}`);
+		if (typeof contents !== "string" && !(contents instanceof Uint8Array)) throw new Error(`Invalid x86 Project file contents: ${path}`);
+	}
+}
+/**
+* Writes a Project into the emulator filesystem and selects the Entry directory as NASM's working
+* directory. NASM consequently owns `%include` and `incbin` resolution, including paths produced by
+* preprocessor macros.
+*/
+function stageX86Project(fs, project) {
+	validateX86Project(project);
+	const previous = stagedFiles.get(fs) ?? /* @__PURE__ */ new Set();
+	const current = /* @__PURE__ */ new Set();
+	fs.mkdirTree(X86_PROJECT_ROOT);
+	for (const [path, contents] of Object.entries(project.files)) {
+		const absolutePath = `${X86_PROJECT_ROOT}/${path}`;
+		const separator = absolutePath.lastIndexOf("/");
+		if (separator > 0) fs.mkdirTree(absolutePath.slice(0, separator));
+		fs.writeFile(absolutePath, contents);
+		current.add(absolutePath);
+	}
+	for (const path of previous) {
+		if (current.has(path)) continue;
+		try {
+			fs.unlink(path);
+		} catch {}
+	}
+	fs.writeFile("/assembly.s", project.files[project.entry]);
+	fs.chdir(projectDirectory(project.entry));
+	stagedFiles.set(fs, current);
+}
+/**
+* Points the assembler at one staged Project File and leaves that File's own directory as the
+* working directory, so its `%include`s and `incbin`s resolve from where it was written rather
+* than from wherever the Entry happens to live. The Entry keeps its `/assembly.s` identity, which
+* is the path its existing diagnostics and source maps are written in terms of.
+*/
+function selectX86Source(fs, project, path) {
+	fs.chdir(projectDirectory(path));
+	return path === project.entry ? "/assembly.s" : `${X86_PROJECT_ROOT}/${path}`;
+}
+/** Maps a path emitted by NASM or DWARF back to the exact Project path. */
+function x86ProjectSourcePath(sourcePath, project) {
+	if (!sourcePath || sourcePath === "/assembly.s" || sourcePath === "assembly.s") return project.entry;
+	const withoutLeadingSlash = (sourcePath.startsWith(`/__x86_project/`) ? sourcePath.slice(15) : sourcePath).replace(/^\/+/, "");
+	const relativeToEntry = resolvePath(parentPath(project.entry), withoutLeadingSlash);
+	if (relativeToEntry && relativeToEntry in project.files) return relativeToEntry;
+	const relativeToRoot = resolvePath("", withoutLeadingSlash);
+	if (relativeToRoot && relativeToRoot in project.files) return relativeToRoot;
+	const suffix = `/${withoutLeadingSlash}`;
+	const suffixMatches = Object.keys(project.files).filter((path) => path === withoutLeadingSlash || path.endsWith(suffix));
+	return suffixMatches.length === 1 ? suffixMatches[0] : project.entry;
+}
+function projectDirectory(entry) {
+	const parent = parentPath(entry);
+	return parent ? `${X86_PROJECT_ROOT}/${parent}` : X86_PROJECT_ROOT;
+}
+function parentPath(path) {
+	const separator = path.lastIndexOf("/");
+	return separator < 0 ? "" : path.slice(0, separator);
+}
+function isProjectPath(path) {
+	return typeof path === "string" && path.length > 0 && !path.includes("\\") && !path.startsWith("/") && path.split("/").every((part) => part !== "" && part !== "." && part !== "..") && !Array.from(path).some((character) => {
+		const code = character.charCodeAt(0);
+		return code <= 31 || code >= 127 && code <= 159;
+	});
+}
+function resolvePath(base, written) {
+	const parts = base ? base.split("/") : [];
+	for (const part of written.split("/")) {
+		if (!part || part === ".") continue;
+		if (part === "..") {
+			if (!parts.length) return null;
+			parts.pop();
+		} else parts.push(part);
+	}
+	return parts.join("/") || null;
+}
+function x86ProjectText(project, path) {
+	const contents = project.files[path];
+	return typeof contents === "string" ? contents : "";
+}
+//#endregion
+//#region src/translation-units.ts
+/**
+* Extensions that make a Project File assembler input in its own right. `.inc` is deliberately
+* absent: it is what an include fragment is conventionally called, and a fragment assembled on
+* its own would define its symbols a second time. A fragment under any other name is caught by
+* the dependency scan instead.
+*/
+const SOURCE_EXTENSIONS = [
+	".asm",
+	".s",
+	".nasm"
+];
+function isX86Source(path) {
+	const lower = path.toLowerCase();
+	return SOURCE_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+/**
+* Every File that could be its own translation unit: assembled separately and linked with the
+* rest, which is what makes `global` in one File and `extern` in another resolve to each other.
+* The Entry comes first so it leads the link, and the rest follow in a stable order so two builds
+* of the same Project lay out identically.
+*/
+function x86TranslationUnitCandidates(project) {
+	const others = Object.keys(project.files).filter((path) => path !== project.entry).filter((path) => typeof project.files[path] === "string" && isX86Source(path)).sort();
+	return [project.entry, ...others];
+}
+/**
+* The Files named by one `nasm -M` run, as Project paths. A File that another source `%include`s
+* is already part of that source: assembling it again would define every one of its symbols a
+* second time, so the link would fail on duplicate definitions rather than on anything the author
+* wrote. Asking NASM rather than scanning for `%include` ourselves is what keeps macro-generated
+* and conditional includes right, since NASM is the only thing that knows which ones it took.
+*/
+function parseDependencyList(output, project) {
+	const separator = output.indexOf(":");
+	if (separator < 0) return [];
+	return output.slice(separator + 1).replace(/\\\r?\n/g, " ").split(/\s+/).filter(Boolean).map((written) => x86ProjectSourcePath(written, project));
+}
+//#endregion
+//#region src/wasm-assembler.ts
+const OBJECT_PATH = "/program.o";
+/**
+* `-g -F dwarf` is what makes the source map possible: the debugger reads
+* `.debug_line` out of the linked executable to map an address back to the line
+* it was written on. The working directory `selectX86Source` selects is what
+* lets NASM resolve `%include` itself.
+*/
+const NASM_ARGS = [
+	"-g",
+	"-F",
+	"dwarf",
+	"-felf64"
+];
+async function createNasmModule() {
+	let stdout = "";
+	let stderr = "";
+	return {
+		module: await createNasm({
+			noInitialRun: true,
+			print: (line) => {
+				stdout += `${line}\n`;
+			},
+			printErr: (line) => {
+				stderr += `${line}\n`;
+			}
+		}),
+		stdout: () => stdout,
+		stderr: () => stderr
+	};
+}
+/**
+* Emscripten's Node path sets `process.exitCode` from the status the module
+* exits with, so an assembly that failed would leave the host process exiting
+* non-zero for a reason of its own. NASM's status belongs to the caller of this
+* function, never to the host.
+*/
+function callNasm(module, args) {
+	const host = globalThis.process;
+	const hostExitCode = host?.exitCode;
+	const status = module.callMain(args);
+	if (host) host.exitCode = hostExitCode;
+	return status;
+}
+/**
+* Which Files the Project's candidate translation units `%include`, so that a fragment is
+* assembled as part of whatever includes it and never a second time on its own. Every candidate
+* is scanned before any of them is treated as a unit, because a fragment can be included by a
+* File that sorts after it.
+*/
+async function scanIncludedFiles(project, candidates) {
+	const included = /* @__PURE__ */ new Set();
+	if (candidates.length < 2) return included;
+	for (const path of candidates) {
+		const { module, stdout } = await createNasmModule();
+		stageX86Project(module.FS, project);
+		const source = selectX86Source(module.FS, project, path);
+		callNasm(module, [
+			"-M",
+			...NASM_ARGS,
+			source,
+			"-o",
+			OBJECT_PATH
+		]);
+		for (const dependency of parseDependencyList(stdout(), project)) if (dependency !== path) included.add(dependency);
+	}
+	return included;
+}
+const nasmWasmAssembler = { async assemble(project) {
+	const candidates = x86TranslationUnitCandidates(project);
+	const included = await scanIncludedFiles(project, candidates);
+	const units = candidates.filter((path) => path === project.entry || !included.has(path));
+	let stdout = "";
+	let stderr = "";
+	let status = 0;
+	const assembled = [];
+	for (const path of units) {
+		const { module, stdout: readStdout, stderr: readStderr } = await createNasmModule();
+		stageX86Project(module.FS, project);
+		const source = selectX86Source(module.FS, project, path);
+		const unitStatus = callNasm(module, [
+			...NASM_ARGS,
+			source,
+			"-o",
+			OBJECT_PATH
+		]);
+		stdout += readStdout();
+		stderr += readStderr();
+		if (!(unitStatus === 0 && module.FS.analyzePath(OBJECT_PATH).exists)) {
+			if (status === 0) status = unitStatus === 0 ? 1 : unitStatus;
+			continue;
+		}
+		assembled.push({
+			path,
+			object: module.FS.readFile(OBJECT_PATH)
+		});
+	}
+	const ok = status === 0 && assembled.length === units.length;
+	return {
+		status,
+		stdout,
+		stderr,
+		units: ok ? assembled : [],
+		object: ok ? assembled[0]?.object ?? null : null
+	};
+} };
+//#endregion
 //#region src/assemblers.ts
 const assemblerAsset = (filename) => new URL(`./assets/assemblers/${filename}`, import.meta.url);
+const linkCommand = (objects) => `/linker ${objects.join(" ")} -o /program`;
 const assemblers = {
 	GNU_trunk: {
 		id: "GNU_trunk",
@@ -14,7 +253,7 @@ const assemblers = {
 			},
 			linker: {
 				file: assemblerAsset("gnu-ld.2.43.50.elf"),
-				commands: "/linker /program.o -o /program"
+				link: linkCommand
 			}
 		}
 	},
@@ -31,18 +270,13 @@ const assemblers = {
 	NASM_trunk: {
 		id: "NASM_trunk",
 		displayName: "Nasm",
-		description: "NASM 3.00 + GNU ld v2.43.50. Both compiled as a static MUSL binary",
+		description: "NASM 3.00 compiled to WebAssembly, + GNU ld v2.43.50 as a static MUSL binary",
 		diagnosticsParser: nasmDiagnostics,
-		binaries: {
-			assembler: {
-				file: assemblerAsset("nasm.3.00.elf"),
-				commands: "/assembler -g -F dwarf -felf64 /assembly.s -o /program.o"
-			},
-			linker: {
-				file: assemblerAsset("gnu-ld.2.43.50.elf"),
-				commands: "/linker /program.o -o /program"
-			}
-		}
+		binaries: { linker: {
+			file: assemblerAsset("gnu-ld.2.43.50.elf"),
+			link: linkCommand
+		} },
+		wasmAssembler: nasmWasmAssembler
 	}
 };
 const DEFAULT_ASSEMBLER_ID = "NASM_trunk";
@@ -50,12 +284,18 @@ function nasmDiagnostics(str) {
 	const diagnostics = [];
 	const lines = str.split(/\r?\n/);
 	const regex = /^(.*):(\d+): (error|warning): (.*)$/;
+	const classRegex = /\s*\[-w\+([\w-]+)\]$/;
 	for (const line of lines) {
 		const match = line.match(regex);
-		if (match) diagnostics.push({
+		if (!match) continue;
+		const text = (match[4] ?? "").trim();
+		const classMatch = text.match(classRegex);
+		diagnostics.push({
 			file: match[1] || void 0,
 			line: Number.parseInt(match[2] ?? "0", 10),
-			error: (match[4] ?? "").trim()
+			error: classMatch ? text.slice(0, classMatch.index).trim() : text,
+			severity: match[3] === "warning" ? "warning" : "error",
+			...classMatch?.[1] ? { warningClass: classMatch[1] } : {}
 		});
 	}
 	return diagnostics;
@@ -63,13 +303,15 @@ function nasmDiagnostics(str) {
 function gnuDiagnostics(str) {
 	const diagnostics = [];
 	const lines = str.split("\n");
-	const regex = /^(.*):(\d+): (Error: .+)$/;
+	const regex = /^(.*):(\d+): (Error|Warning): (.+)$/;
 	for (const line of lines) {
 		const match = line.match(regex);
-		if (match) diagnostics.push({
+		if (!match) continue;
+		diagnostics.push({
 			file: match[1] || void 0,
 			line: Number.parseInt(match[2] ?? "0", 10),
-			error: match[3] ?? ""
+			error: `${match[3]}: ${match[4]}`,
+			severity: match[3] === "Warning" ? "warning" : "error"
 		});
 	}
 	return diagnostics;
@@ -92,7 +334,8 @@ function fasmDiagnostics(str) {
 			diagnostics.push({
 				file,
 				line: lineNumber,
-				error: errorMatch[0]
+				error: errorMatch[0],
+				severity: "error"
 			});
 			lineNumber = null;
 			file = void 0;
@@ -100,6 +343,71 @@ function fasmDiagnostics(str) {
 	}
 	return diagnostics;
 }
+/**
+* What `ld` said, as diagnostics. Nothing else in the toolchain reports a symbol that no
+* translation unit defines: NASM accepts every `extern` on the author's word, and the mistake
+* only surfaces here. Without this the link simply failed and the build looked like it had
+* succeeded, leaving the program unrunnable and nothing on screen to say why.
+*
+* `ld` writes a location as `file:line:(section+offset):`, and writes the notes that introduce an
+* error - "in function `_start':" - as lines ending in a colon, which are skipped in favour of
+* the error itself.
+*/
+function ldDiagnostics(str) {
+	const diagnostics = [];
+	const locatedRegex = /^(.*?):(\d+):(?:\([^)]*\))?:\s*(.+)$/;
+	for (const line of str.split(/\r?\n/)) {
+		const text = line.trim().replace(/^\/linker:\s*/, "");
+		if (!text || text.startsWith("$ ") || text.endsWith(":")) continue;
+		const located = text.match(locatedRegex);
+		const message = (located?.[3] ?? text).trim();
+		if (!message) continue;
+		if (message.includes("cannot find entry symbol")) continue;
+		const isWarning = message.startsWith("warning:");
+		diagnostics.push({
+			...located?.[1] ? { file: located[1] } : {},
+			line: located ? Number.parseInt(located[2] ?? "0", 10) : 1,
+			error: isWarning ? message.slice(8).trim() : message,
+			severity: isWarning ? "warning" : "error"
+		});
+	}
+	return diagnostics;
+}
+/**
+* The one-based column a diagnostic belongs on. NASM reports a line and no
+* column, but it names the thing it is complaining about: `msg' in "symbol
+* `msg' not defined", `.data' in a section warning. Finding that name in the
+* line turns a whole-line squiggle into one under the mistake itself.
+*
+* Falls back to the first column, which is what the caller would have used
+* anyway, so a message that names nothing findable is no worse off.
+*/
+function locateDiagnosticColumn(message, line, warningClass) {
+	if (warningClass === "label-orphan") {
+		const leading = line.search(/\S/);
+		return leading < 0 ? 1 : leading + 1;
+	}
+	const quoted = message.match(/`([^'`]+)'/)?.[1];
+	if (!quoted) return 1;
+	const index = findIdentifier(line, quoted);
+	return index < 0 ? 1 : index + 1;
+}
+/**
+* Where a name appears in a line as itself, rather than inside a longer one.
+* Identifier characters on either side mean this is a different symbol that
+* merely contains the name.
+*/
+function findIdentifier(line, name) {
+	const isIdentifierChar = (character) => character !== void 0 && /[\w$#@~.?]/.test(character);
+	let from = 0;
+	while (from <= line.length - name.length) {
+		const index = line.indexOf(name, from);
+		if (index < 0) return -1;
+		if (!isIdentifierChar(line[index - 1]) && !isIdentifierChar(line[index + name.length])) return index;
+		from = index + 1;
+	}
+	return -1;
+}
 //#endregion
 //#region \0wasm-helpers.js
 function loadWasmModule(sync, filepath, src, imports) {
@@ -470,85 +778,73 @@ function compareBigInt(left, right) {
 	return 0;
 }
 //#endregion
-//#region src/project.ts
-const X86_PROJECT_ROOT = "/__x86_project";
-const stagedFiles = /* @__PURE__ */ new WeakMap();
-function validateX86Project(project) {
-	if (!isProjectPath(project.entry)) throw new Error(`Invalid x86 Project entry path: ${project.entry}`);
-	if (!Object.hasOwn(project.files, project.entry)) throw new Error(`x86 Project entry file not found: ${project.entry}`);
-	if (typeof project.files[project.entry] !== "string") throw new Error(`x86 Project entry must be a text file: ${project.entry}`);
-	for (const [path, contents] of Object.entries(project.files)) {
-		if (!isProjectPath(path)) throw new Error(`Invalid x86 Project file path: ${path}`);
-		if (typeof contents !== "string" && !(contents instanceof Uint8Array)) throw new Error(`Invalid x86 Project file contents: ${path}`);
-	}
+//#region src/elf-symbols.ts
+/**
+* The entry symbol `ld` looks for when no `-e` is given. A program without it
+* still links: `ld` warns, defaults the entry address to the start of the text
+* segment, and the program runs from whatever happens to be there.
+*/
+const DEFAULT_ENTRY_SYMBOL = "_start";
+const SYMBOL_ENTRY_SIZE = 24;
+const SHN_UNDEF = 0;
+const STB_LOCAL = 0;
+/**
+* Names every symbol an object file defines and exports, which is what decides
+* whether the linker can find an entry point. A symbol that is merely referenced
+* (`st_shndx` of SHN_UNDEF) is not defined here, and a local one - a label
+* without a matching `global` directive - is invisible to the linker.
+*/
+function readDefinedGlobalSymbols(objectBytes) {
+	const symbolTable = findElfSection(objectBytes, ".symtab");
+	const stringTable = findElfSection(objectBytes, ".strtab");
+	if (!symbolTable || !stringTable) return [];
+	const view = new DataView(objectBytes.buffer, objectBytes.byteOffset, objectBytes.byteLength);
+	const strings = objectBytes.subarray(stringTable.offset, stringTable.offset + stringTable.size);
+	const names = [];
+	for (let offset = 0; offset + SYMBOL_ENTRY_SIZE <= symbolTable.size; offset += SYMBOL_ENTRY_SIZE) {
+		const entry = symbolTable.offset + offset;
+		const nameOffset = view.getUint32(entry, true);
+		const binding = view.getUint8(entry + 4) >> 4;
+		const sectionIndex = view.getUint16(entry + 6, true);
+		if (binding === STB_LOCAL || sectionIndex === SHN_UNDEF) continue;
+		if (nameOffset >= strings.length) continue;
+		const [name] = readNullTerminatedString(strings, nameOffset, strings.length);
+		if (name) names.push(name);
+	}
+	return names;
 }
 /**
-* Writes a Project into the emulator filesystem and selects the Entry directory as NASM's working
-* directory. NASM consequently owns `%include` and `incbin` resolution, including paths produced by
-* preprocessor macros.
+* The symbol a misspelling was probably meant to be, or null when nothing in the
+* object looks close enough to say. Deliberately strict: naming the wrong symbol
+* is worse than naming none, so this only answers for a small edit distance on a
+* name of a similar length.
 */
-function stageX86Project(fs, project) {
-	validateX86Project(project);
-	const previous = stagedFiles.get(fs) ?? /* @__PURE__ */ new Set();
-	const current = /* @__PURE__ */ new Set();
-	fs.mkdirTree(X86_PROJECT_ROOT);
-	for (const [path, contents] of Object.entries(project.files)) {
-		const absolutePath = `${X86_PROJECT_ROOT}/${path}`;
-		const separator = absolutePath.lastIndexOf("/");
-		if (separator > 0) fs.mkdirTree(absolutePath.slice(0, separator));
-		fs.writeFile(absolutePath, contents);
-		current.add(absolutePath);
-	}
-	for (const path of previous) {
-		if (current.has(path)) continue;
-		try {
-			fs.unlink(path);
-		} catch {}
+function findNearestSymbol(target, candidates) {
+	let best = null;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const candidate of candidates) {
+		if (candidate === target) return null;
+		if (Math.abs(candidate.length - target.length) > 2) continue;
+		const distance = editDistance(candidate, target);
+		if (distance < bestDistance) {
+			bestDistance = distance;
+			best = candidate;
+		}
 	}
-	fs.writeFile("/assembly.s", project.files[project.entry]);
-	fs.chdir(projectDirectory(project.entry));
-	stagedFiles.set(fs, current);
-}
-/** Maps a path emitted by NASM or DWARF back to the exact Project path. */
-function x86ProjectSourcePath(sourcePath, project) {
-	if (!sourcePath || sourcePath === "/assembly.s" || sourcePath === "assembly.s") return project.entry;
-	const withoutLeadingSlash = (sourcePath.startsWith(`/__x86_project/`) ? sourcePath.slice(15) : sourcePath).replace(/^\/+/, "");
-	const relativeToEntry = resolvePath(parentPath(project.entry), withoutLeadingSlash);
-	if (relativeToEntry && relativeToEntry in project.files) return relativeToEntry;
-	const relativeToRoot = resolvePath("", withoutLeadingSlash);
-	if (relativeToRoot && relativeToRoot in project.files) return relativeToRoot;
-	const suffix = `/${withoutLeadingSlash}`;
-	const suffixMatches = Object.keys(project.files).filter((path) => path === withoutLeadingSlash || path.endsWith(suffix));
-	return suffixMatches.length === 1 ? suffixMatches[0] : project.entry;
-}
-function projectDirectory(entry) {
-	const parent = parentPath(entry);
-	return parent ? `${X86_PROJECT_ROOT}/${parent}` : X86_PROJECT_ROOT;
+	const allowed = target.length <= 4 ? 1 : 2;
+	return bestDistance <= allowed ? best : null;
 }
-function parentPath(path) {
-	const separator = path.lastIndexOf("/");
-	return separator < 0 ? "" : path.slice(0, separator);
-}
-function isProjectPath(path) {
-	return typeof path === "string" && path.length > 0 && !path.includes("\\") && !path.startsWith("/") && path.split("/").every((part) => part !== "" && part !== "." && part !== "..") && !Array.from(path).some((character) => {
-		const code = character.charCodeAt(0);
-		return code <= 31 || code >= 127 && code <= 159;
-	});
-}
-function resolvePath(base, written) {
-	const parts = base ? base.split("/") : [];
-	for (const part of written.split("/")) {
-		if (!part || part === ".") continue;
-		if (part === "..") {
-			if (!parts.length) return null;
-			parts.pop();
-		} else parts.push(part);
+function editDistance(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+		const current = [leftIndex];
+		for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+			const substitution = previous[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1);
+			current.push(Math.min(substitution, previous[rightIndex] + 1, current[rightIndex - 1] + 1));
+		}
+		previous = current;
 	}
-	return parts.join("/") || null;
-}
-function x86ProjectText(project, path) {
-	const contents = project.files[path];
-	return typeof contents === "string" ? contents : "";
+	return previous[right.length];
 }
 //#endregion
 //#region src/types.ts
@@ -682,13 +978,20 @@ var BlinkRuntime = class BlinkRuntime {
 	state = "NOT_READY";
 	stopReason = null;
 	assemblerLogs = "";
+	/** The subset of `assemblerDiagnostics` that stopped the build. */
 	assemblerErrors = [];
+	/** Everything the assembler said, warnings included. */
+	assemblerDiagnostics = [];
 	callbacks;
 	scheduler;
 	stateWaiters = [];
 	stdinBytes = [];
 	sourceMap = null;
 	sourceProject = null;
+	assembleOnly = false;
+	assembledObjects = [];
+	/** What the linker said, kept apart from the assembler's log so `ld`'s own parser reads it. */
+	linkerLogs = null;
 	defaultArgc = "/program";
 	defaultArgv = "";
 	constructor(module, mode, callbacks, scheduler) {
@@ -735,7 +1038,7 @@ var BlinkRuntime = class BlinkRuntime {
 		this.assemblerLogs = "";
 		this.assemblerErrors = [];
 		this.setState("NOT_READY");
-		await this.writeExecutable("/assembler", await readResourceBytes(this.mode.binaries.assembler.file));
+		if (this.mode.binaries.assembler) await this.writeExecutable("/assembler", await readResourceBytes(this.mode.binaries.assembler.file));
 		if (this.mode.binaries.linker) await this.writeExecutable("/linker", await readResourceBytes(this.mode.binaries.linker.file));
 		this.setState("READY");
 	}
@@ -746,41 +1049,175 @@ var BlinkRuntime = class BlinkRuntime {
 		});
 	}
 	async compileProject(project) {
+		return this.buildProject(project, { link: true });
+	}
+	/**
+	* Assembles without linking, for diagnostics. The linked executable is only
+	* needed to run or debug a program; a caller that just wants to know what is
+	* wrong with the source pays ~450ms for a link it never looks at.
+	*
+	* A mode with a `wasmAssembler` never touches blink here, so checking also
+	* leaves a loaded program - and anything paused in the debugger - alone.
+	*/
+	async checkProject(project) {
+		if (this.mode.wasmAssembler) return this.checkProjectWithWasmAssembler(project);
+		return this.buildProject(project, { link: false });
+	}
+	async checkProjectWithWasmAssembler(project) {
+		const sourceProject = copyX86Project(project);
+		const assembled = await this.mode.wasmAssembler.assemble(sourceProject);
+		const report = assembled.stdout + assembled.stderr;
+		return toCompileResult([...this.parseAssemblerDiagnostics(report, sourceProject), ...this.entryPointDiagnostics(assembled.units.map((unit) => unit.object), sourceProject)], report);
+	}
+	async buildProject(project, options) {
 		this.assertReadyForCompile();
-		const sourceProject = {
-			entry: project.entry,
-			files: Object.fromEntries(Object.entries(project.files).map(([path, contents]) => [path, contents instanceof Uint8Array ? contents.slice() : contents]))
-		};
-		stageX86Project(this.module.FS, sourceProject);
+		const sourceProject = copyX86Project(project);
 		this.sourceProject = sourceProject;
 		this.stopReason = null;
 		this.assemblerLogs = "";
 		this.assemblerErrors = [];
+		this.assemblerDiagnostics = [];
+		this.assembledObjects = [];
+		this.linkerLogs = null;
 		this.sourceMap = null;
-		this.setState("ASSEMBLING");
+		this.assembleOnly = !options.link;
 		try {
-			await defer();
-			this.setEmulationArgs("/assembler", this.mode.binaries.assembler.commands, "");
-			this.module._blinkenlib_run_fast();
-			await this.waitForState((state) => state !== "ASSEMBLING" && state !== "LINKING");
+			if (this.mode.wasmAssembler) await this.assembleWithWasmAssembler(sourceProject, options);
+			else await this.assembleInBlink(sourceProject);
 		} finally {
+			this.assembleOnly = false;
 			this.module.FS.chdir("/");
 		}
-		if (this.state === "PROGRAM_LOADED") {
-			this.sourceMap = this.tryReadSourceMap();
-			return {
-				ok: true,
-				report: this.assemblerLogs
-			};
-		}
-		return {
-			ok: false,
-			errors: this.assemblerErrors.map((error) => ({
-				...error,
-				file: x86ProjectSourcePath(error.file, sourceProject)
+		const diagnostics = [
+			...this.assemblerDiagnostics.map((diagnostic) => ({
+				...diagnostic,
+				file: x86ProjectSourcePath(diagnostic.file, sourceProject)
 			})),
-			report: this.assemblerLogs
-		};
+			...this.entryPointDiagnostics(this.takeAssembledObjects(), sourceProject),
+			...this.linkDiagnostics(sourceProject)
+		];
+		if (this.state === "PROGRAM_LOADED") this.sourceMap = this.tryReadSourceMap();
+		return toCompileResult(diagnostics, this.assemblerLogs);
+	}
+	/**
+	* The objects this build's assembler wrote, for the checks that read them
+	* rather than the assembler's own words. Empty when the assembly failed, and
+	* when the assembler writes an executable directly and never produces one.
+	* Read once per build, so a previous build's objects can never stand in for
+	* ones that were never written.
+	*/
+	takeAssembledObjects() {
+		const objects = this.assembledObjects;
+		this.assembledObjects = [];
+		return objects;
+	}
+	/**
+	* What the link had to say. A link that failed leaves no program to run, so a build that
+	* reported nothing would hand the caller a success it cannot act on - the state stays `Ready`
+	* and the next step or run fails with a message about the emulator rather than the mistake.
+	* The fallback covers a linker that fails in a way its parser does not recognise, so a failed
+	* link is always visible as an error whatever `ld` chose to say about it.
+	*/
+	linkDiagnostics(sourceProject) {
+		if (this.linkerLogs === null) return [];
+		const diagnostics = ldDiagnostics(this.linkerLogs).map((diagnostic) => ({
+			...diagnostic,
+			file: x86ProjectSourcePath(diagnostic.file, sourceProject)
+		}));
+		if (this.state === "PROGRAM_LOADED" || diagnostics.some((diagnostic) => diagnostic.severity === "error")) return diagnostics;
+		return [...diagnostics, {
+			line: 1,
+			file: sourceProject.entry,
+			severity: "error",
+			error: "linking failed, so there is no program to run."
+		}];
+	}
+	/**
+	* Nothing in the toolchain treats a missing entry point as a failure: NASM
+	* has no opinion on it and `ld` only warns, then starts the program at the
+	* top of its text segment, where it runs whatever happens to be first. That
+	* is the least explicable thing a program can do to someone learning, so it
+	* is reported as an error here and the mistake is usually a misspelling.
+	*/
+	entryPointDiagnostics(objects, sourceProject) {
+		if (!objects.length || !this.mode.binaries.linker) return [];
+		const globals = objects.flatMap((object) => readDefinedGlobalSymbols(object));
+		if (globals.includes("_start")) return [];
+		const nearest = findNearestSymbol(DEFAULT_ENTRY_SYMBOL, globals);
+		const nearestHint = nearest ? ` Did you mean \`${DEFAULT_ENTRY_SYMBOL}\` where you wrote \`${nearest}\`?` : "";
+		const exportHint = globals.length ? "" : ` Defining the label is not enough on its own: \`global ${DEFAULT_ENTRY_SYMBOL}\` is what exports it.`;
+		return [{
+			line: 1,
+			file: sourceProject.entry,
+			severity: "error",
+			warningClass: "entry-point",
+			error: `no \`${DEFAULT_ENTRY_SYMBOL}\` to start from.${nearestHint}${exportHint}`
+		}];
+	}
+	async assembleInBlink(sourceProject) {
+		stageX86Project(this.module.FS, sourceProject);
+		this.setState("ASSEMBLING");
+		await defer();
+		this.setEmulationArgs("/assembler", this.mode.binaries.assembler.commands, "");
+		this.module._blinkenlib_run_fast();
+		await this.waitForState((state) => state !== "ASSEMBLING" && state !== "LINKING");
+		if (this.assemblerErrors.length === 0) try {
+			this.assembledObjects = [this.module.FS.readFile("/program.o")];
+		} catch {}
+	}
+	/**
+	* Assembles outside blink and hands the object file to the linker inside it,
+	* which is where the state machine picks up again as if blink had produced
+	* the object itself.
+	*/
+	async assembleWithWasmAssembler(sourceProject, options) {
+		this.setState("ASSEMBLING");
+		const assembled = await this.mode.wasmAssembler.assemble(sourceProject);
+		this.emitAssemblerOutput(assembled.stdout, this.callbacks.stdout);
+		this.emitAssemblerOutput(assembled.stderr, this.callbacks.stderr);
+		this.collectAssemblerDiagnostics();
+		if (!assembled.units.length) {
+			this.setState("READY");
+			return;
+		}
+		this.assembledObjects = assembled.units.map((unit) => unit.object);
+		if (!options.link) {
+			this.setState("READY");
+			return;
+		}
+		const objectPaths = assembled.units.map((_, index) => index === 0 ? "/program.o" : `/program.${index}.o`);
+		assembled.units.forEach((unit, index) => this.writeExecutableSync(objectPaths[index], unit.object));
+		this.beginLinking();
+		await defer();
+		this.setEmulationArgs("/linker", this.mode.binaries.linker?.link(objectPaths) ?? "", "");
+		this.module._blinkenlib_run_fast();
+		await this.waitForState((state) => state !== "LINKING");
+	}
+	/**
+	* Starts the link, and starts a log of its own for it. The assembler's parser cannot read
+	* `ld`'s diagnostics and `ld`'s cannot read the assembler's, so what each of them said has to
+	* stay separable even though both reach the caller as one report.
+	*/
+	beginLinking() {
+		this.linkerLogs = "";
+		this.setState("LINKING");
+	}
+	collectAssemblerDiagnostics() {
+		this.assemblerDiagnostics = this.mode.diagnosticsParser?.(this.assemblerLogs) ?? [];
+		this.assemblerErrors = this.assemblerDiagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	}
+	emitAssemblerOutput(text, callback) {
+		for (let index = 0; index < text.length; index += 1) {
+			const charCode = text.charCodeAt(index);
+			this.assemblerLogs += String.fromCharCode(charCode);
+			observeCallbackResult(callback(charCode));
+		}
+	}
+	parseAssemblerDiagnostics(report, sourceProject) {
+		return (this.mode.diagnosticsParser?.(report) ?? []).map((error) => ({
+			...error,
+			file: x86ProjectSourcePath(error.file, sourceProject)
+		}));
 	}
 	loadElf(data) {
 		if (this.state === "NOT_READY") throw new Error("Blink runtime is not ready");
@@ -961,7 +1398,10 @@ var BlinkRuntime = class BlinkRuntime {
 		this.module.blinkenlibSetRunControls(BigInt(limit), (options.breakpointAddresses ?? []).map((address) => address.toString()));
 	}
 	collectAssemblerLog(charCode) {
-		if (this.state === "ASSEMBLING" || this.state === "LINKING") this.assemblerLogs += String.fromCharCode(charCode);
+		if (this.state !== "ASSEMBLING" && this.state !== "LINKING") return;
+		const character = String.fromCharCode(charCode);
+		this.assemblerLogs += character;
+		if (this.state === "LINKING" && this.linkerLogs !== null) this.linkerLogs += character;
 	}
 	handleSignal(signal, code) {
 		if (signal !== SIGNALS.SIGTRAP) {
@@ -1026,8 +1466,12 @@ var BlinkRuntime = class BlinkRuntime {
 		this.setState("PROGRAM_STOPPED");
 	}
 	handleAssemblerExit(code) {
+		this.collectAssemblerDiagnostics();
 		if (code !== 0) {
-			this.assemblerErrors = this.mode.diagnosticsParser?.(this.assemblerLogs) ?? [];
+			this.setState("READY");
+			return;
+		}
+		if (this.assembleOnly) {
 			this.setState("READY");
 			return;
 		}
@@ -1036,9 +1480,9 @@ var BlinkRuntime = class BlinkRuntime {
 			this.setState("PROGRAM_LOADED");
 			return;
 		}
-		this.setState("LINKING");
+		this.beginLinking();
 		this.scheduler(() => {
-			this.setEmulationArgs("/linker", this.mode.binaries.linker?.commands ?? "", "");
+			this.setEmulationArgs("/linker", this.mode.binaries.linker?.link(["/program.o"]) ?? "", "");
 			this.module._blinkenlib_run_fast();
 		});
 	}
@@ -1121,6 +1565,31 @@ function defaultScheduler(callback) {
 function defer() {
 	return new Promise((resolve) => defaultScheduler(resolve));
 }
+/**
+* A build succeeded when nothing in it was an error. Warnings ride along on both
+* outcomes, because a program that assembles is exactly where they matter.
+*/
+function toCompileResult(diagnostics, report) {
+	const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	if (errors.length === 0) return {
+		ok: true,
+		report,
+		diagnostics
+	};
+	return {
+		ok: false,
+		errors,
+		report,
+		diagnostics
+	};
+}
+/** Detaches a Project from the caller, who is free to mutate its own copy afterwards. */
+function copyX86Project(project) {
+	return {
+		entry: project.entry,
+		files: Object.fromEntries(Object.entries(project.files).map(([path, contents]) => [path, contents instanceof Uint8Array ? contents.slice() : contents]))
+	};
+}
 //#endregion
 //#region src/interface.ts
 let RegisterSize = /* @__PURE__ */ function(RegisterSize) {
@@ -1408,21 +1877,28 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 			files: { "assembly.s": code }
 		});
 	}
+	/**
+	* Diagnostics only: this assembles but does not link, and for an assembler
+	* that runs as its own wasm module it does not touch blink at all, so a
+	* loaded or paused program survives a check.
+	*/
 	async checkProject(project) {
-		const result = await this.compileProject(project);
-		return (result.ok === false ? result.errors : []).map((error) => {
-			const path = error.file ?? project.entry;
-			const lineIndex = Math.max(0, error.line - 1);
+		return (await this.runtime.checkProject(project)).diagnostics.map((diagnostic) => {
+			const path = diagnostic.file ?? project.entry;
+			const lineIndex = Math.max(0, diagnostic.line - 1);
+			const line = x86ProjectText(project, path).split(/\r?\n/)[lineIndex] ?? "";
 			return {
 				file: path,
 				lineIndex,
-				column: 0,
+				column: locateDiagnosticColumn(diagnostic.error, line, diagnostic.warningClass),
 				line: {
-					line: x86ProjectText(project, path).split(/\r?\n/)[lineIndex] ?? "",
+					line,
 					line_index: lineIndex
 				},
-				message: error.error,
-				formatted: error.error
+				message: diagnostic.error,
+				formatted: diagnostic.error,
+				severity: diagnostic.severity,
+				...diagnostic.warningClass ? { code: diagnostic.warningClass } : {}
 			};
 		});
 	}
@@ -1727,6 +2203,6 @@ async function createX86Emulator(options = {}) {
 	return X86Emulator.create(options);
 }
 //#endregion
-export { BaseEmulator, BlinkRuntime, BlinkState, DEFAULT_ASSEMBLER_ID, EmulatorStatus, RegisterSize, X86Emulator, X86_PROJECT_ROOT, X86_REGISTER_NAMES, assemblers, createX86Emulator, defaultResourceUrl, fasmDiagnostics, gnuDiagnostics, isNodeRuntime, nasmDiagnostics, observeCallbackResult, readResourceBytes, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
+export { BaseEmulator, BlinkRuntime, BlinkState, DEFAULT_ASSEMBLER_ID, EmulatorStatus, RegisterSize, X86Emulator, X86_PROJECT_ROOT, X86_REGISTER_NAMES, assemblers, createX86Emulator, defaultResourceUrl, fasmDiagnostics, gnuDiagnostics, isNodeRuntime, ldDiagnostics, locateDiagnosticColumn, nasmDiagnostics, observeCallbackResult, readResourceBytes, selectX86Source, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
 
 //# sourceMappingURL=index.mjs.map