@specy/x86 2.1.0 → 2.2.1

package/dist/index.mjs

@@ -1,4 +1,130 @@
+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);
+}
+/** 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/wasm-assembler.ts
+const SOURCE_PATH = "/assembly.s";
+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 paths match what `stageX86Project` writes, and the
+* working directory it selects is what lets NASM resolve `%include` itself.
+*/
+const NASM_ARGS = [
+	"-g",
+	"-F",
+	"dwarf",
+	"-felf64",
+	SOURCE_PATH,
+	"-o",
+	OBJECT_PATH
+];
+const nasmWasmAssembler = { async assemble(project) {
+	let stdout = "";
+	let stderr = "";
+	const module = await createNasm({
+		noInitialRun: true,
+		print: (line) => {
+			stdout += `${line}\n`;
+		},
+		printErr: (line) => {
+			stderr += `${line}\n`;
+		}
+	});
+	stageX86Project(module.FS, project);
+	const host = globalThis.process;
+	const hostExitCode = host?.exitCode;
+	const status = module.callMain([...NASM_ARGS]);
+	if (host) host.exitCode = hostExitCode;
+	const object = status === 0 && module.FS.analyzePath(OBJECT_PATH).exists ? module.FS.readFile(OBJECT_PATH) : null;
+	return {
+		status,
+		stdout,
+		stderr,
+		object
+	};
+} };
+//#endregion
 //#region src/assemblers.ts
 const assemblerAsset = (filename) => new URL(`./assets/assemblers/${filename}`, import.meta.url);
 const assemblers = {
@@ -31,18 +157,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"),
+			commands: "/linker /program.o -o /program"
+		} },
+		wasmAssembler: nasmWasmAssembler
 	}
 };
 const DEFAULT_ASSEMBLER_ID = "NASM_trunk";
@@ -50,12 +171,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 +190,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 +221,8 @@ function fasmDiagnostics(str) {
 			diagnostics.push({
 				file,
 				line: lineNumber,
-				error: errorMatch[0]
+				error: errorMatch[0],
+				severity: "error"
 			});
 			lineNumber = null;
 			file = void 0;
@@ -100,6 +230,41 @@ function fasmDiagnostics(str) {
 	}
 	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 +635,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);
+	const allowed = target.length <= 4 ? 1 : 2;
+	return bestDistance <= allowed ? best : null;
 }
-/** 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);
+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 +835,18 @@ 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;
+	assembledObject = null;
 	defaultArgc = "/program";
 	defaultArgv = "";
 	constructor(module, mode, callbacks, scheduler) {
@@ -735,7 +893,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 +904,140 @@ 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.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.assembledObject = 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
-			};
+		const diagnostics = [...this.assemblerDiagnostics.map((diagnostic) => ({
+			...diagnostic,
+			file: x86ProjectSourcePath(diagnostic.file, sourceProject)
+		})), ...this.entryPointDiagnostics(this.takeAssembledObject(), sourceProject)];
+		if (this.state === "PROGRAM_LOADED") this.sourceMap = this.tryReadSourceMap();
+		return toCompileResult(diagnostics, this.assemblerLogs);
+	}
+	/**
+	* The object this build's assembler wrote, for the checks that read it
+	* rather than the assembler's own words. Null 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 object can never stand in for
+	* one that was never written.
+	*/
+	takeAssembledObject() {
+		const object = this.assembledObject;
+		this.assembledObject = null;
+		return object;
+	}
+	/**
+	* 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(object, sourceProject) {
+		if (!object || !this.mode.binaries.linker) return [];
+		const globals = 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.assembledObject = 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.object) {
+			this.setState("READY");
+			return;
+		}
+		if (!options.link) {
+			this.assembledObject = assembled.object;
+			this.setState("READY");
+			return;
+		}
+		this.assembledObject = assembled.object;
+		this.writeExecutableSync("/program.o", assembled.object);
+		this.setState("LINKING");
+		await defer();
+		this.setEmulationArgs("/linker", this.mode.binaries.linker?.commands ?? "", "");
+		this.module._blinkenlib_run_fast();
+		await this.waitForState((state) => state !== "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));
 		}
-		return {
-			ok: false,
-			errors: this.assemblerErrors.map((error) => ({
-				...error,
-				file: x86ProjectSourcePath(error.file, sourceProject)
-			})),
-			report: this.assemblerLogs
-		};
+	}
+	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");
@@ -1026,8 +1283,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;
 		}
@@ -1121,6 +1382,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 +1694,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 +2020,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, locateDiagnosticColumn, nasmDiagnostics, observeCallbackResult, readResourceBytes, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
 
 //# sourceMappingURL=index.mjs.map