@specy/x86 2.0.5 → 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,30 +157,32 @@ 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";
 function nasmDiagnostics(str) {
 	const diagnostics = [];
 	const lines = str.split(/\r?\n/);
-	const regex = /^.*:(\d+): (error|warning): (.*)$/;
+	const regex = /^(.*):(\d+): (error|warning): (.*)$/;
+	const classRegex = /\s*\[-w\+([\w-]+)\]$/;
 	for (const line of lines) {
 		const match = line.match(regex);
-		if (match) diagnostics.push({
-			line: Number.parseInt(match[1] ?? "0", 10),
-			error: (match[3] ?? "").trim()
+		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: classMatch ? text.slice(0, classMatch.index).trim() : text,
+			severity: match[3] === "warning" ? "warning" : "error",
+			...classMatch?.[1] ? { warningClass: classMatch[1] } : {}
 		});
 	}
 	return diagnostics;
@@ -62,36 +190,81 @@ function nasmDiagnostics(str) {
 function gnuDiagnostics(str) {
 	const diagnostics = [];
 	const lines = str.split("\n");
-	const regex = /\/assembly\.s:(\d+): (Error: .+)/;
+	const regex = /^(.*):(\d+): (Error|Warning): (.+)$/;
 	for (const line of lines) {
 		const match = line.match(regex);
-		if (match) diagnostics.push({
-			line: Number.parseInt(match[1] ?? "0", 10),
-			error: match[2] ?? ""
+		if (!match) continue;
+		diagnostics.push({
+			file: match[1] || void 0,
+			line: Number.parseInt(match[2] ?? "0", 10),
+			error: `${match[3]}: ${match[4]}`,
+			severity: match[3] === "Warning" ? "warning" : "error"
 		});
 	}
 	return diagnostics;
 }
 function fasmDiagnostics(str) {
 	const diagnostics = [];
-	const lineRegex = /\/assembly\.s \[(\d+)\]:/;
+	const lineRegex = /^(.*) \[(\d+)\]:/;
 	const errorRegex = /error: .+/;
 	const lines = str.split("\n");
 	let lineNumber = null;
+	let file;
 	for (const line of lines) {
 		const lineMatch = line.match(lineRegex);
 		const errorMatch = line.match(errorRegex);
-		if (lineMatch) lineNumber = Number.parseInt(lineMatch[1] ?? "0", 10);
+		if (lineMatch) {
+			file = lineMatch[1] || void 0;
+			lineNumber = Number.parseInt(lineMatch[2] ?? "0", 10);
+		}
 		if (errorMatch && lineNumber !== null) {
 			diagnostics.push({
+				file,
 				line: lineNumber,
-				error: errorMatch[0]
+				error: errorMatch[0],
+				severity: "error"
 			});
 			lineNumber = null;
+			file = void 0;
 		}
 	}
 	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) {
@@ -170,6 +343,9 @@ var SourceMap = class {
 		return this.entries.length;
 	}
 	getLineIndex(address) {
+		return this.getLocation(address)?.lineIndex ?? null;
+	}
+	getLocation(address) {
 		let left = 0;
 		let right = this.entries.length - 1;
 		let match = null;
@@ -182,13 +358,19 @@ var SourceMap = class {
 				left = middle + 1;
 			} else right = middle - 1;
 		}
-		return match?.lineIndex ?? null;
+		return match ? { ...match } : null;
 	}
 	getAddressesForLine(lineIndex) {
+		return this.getAddressesForLocation(lineIndex);
+	}
+	getAddressesForLocation(lineIndex, file) {
+		return this.getAddressesMatching(lineIndex, (candidate) => file === void 0 || candidate === file);
+	}
+	getAddressesMatching(lineIndex, matchesFile) {
 		const addresses = [];
 		const seen = /* @__PURE__ */ new Set();
 		for (const entry of this.entries) {
-			if (entry.lineIndex !== lineIndex) continue;
+			if (entry.lineIndex !== lineIndex || !matchesFile(entry.file)) continue;
 			const key = entry.address.toString();
 			if (seen.has(key)) continue;
 			seen.add(key);
@@ -196,6 +378,16 @@ var SourceMap = class {
 		}
 		return addresses;
 	}
+	getAddresses() {
+		const addresses = [];
+		let previous;
+		for (const entry of this.entries) {
+			if (entry.address === previous) continue;
+			addresses.push(entry.address);
+			previous = entry.address;
+		}
+		return addresses;
+	}
 };
 function parseSourceMap(bytes) {
 	const section = findElfSection(bytes, ".debug_line");
@@ -302,7 +494,7 @@ function parseDebugLine(bytes) {
 			entries.push({
 				address,
 				lineIndex: Math.max(0, line - 1),
-				file: sourceFile?.name
+				file: dwarfSourcePath(sourceFile)
 			});
 		};
 		const advanceAddress = (operationAdvance) => {
@@ -392,6 +584,11 @@ function parseDebugLine(bytes) {
 	}
 	return entries;
 }
+function dwarfSourcePath(sourceFile) {
+	if (!sourceFile?.name) return void 0;
+	if (!sourceFile.directory || sourceFile.name.startsWith("/")) return sourceFile.name;
+	return `${sourceFile.directory.replace(/\/$/, "")}/${sourceFile.name}`;
+}
 function readU64Number(view, offset) {
 	const value = view.getBigUint64(offset, true);
 	if (value > BigInt(Number.MAX_SAFE_INTEGER)) return Number.MAX_SAFE_INTEGER;
@@ -438,6 +635,75 @@ function compareBigInt(left, right) {
 	return 0;
 }
 //#endregion
+//#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;
+}
+/**
+* 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 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;
+		}
+	}
+	const allowed = target.length <= 4 ? 1 : 2;
+	return bestDistance <= allowed ? best : null;
+}
+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 previous[right.length];
+}
+//#endregion
 //#region src/types.ts
 const X86_REGISTER_NAMES = [
 	"rax",
@@ -569,12 +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) {
@@ -621,40 +893,158 @@ 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");
 	}
 	async compileAssembly(code) {
+		return this.compileProject({
+			entry: "assembly.s",
+			files: { "assembly.s": code }
+		});
+	}
+	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 = copyX86Project(project);
+		this.sourceProject = sourceProject;
 		this.stopReason = null;
 		this.assemblerLogs = "";
 		this.assemblerErrors = [];
+		this.assemblerDiagnostics = [];
+		this.assembledObject = null;
 		this.sourceMap = null;
-		this.module.FS.writeFile("/assembly.s", code);
+		this.assembleOnly = !options.link;
+		try {
+			if (this.mode.wasmAssembler) await this.assembleWithWasmAssembler(sourceProject, options);
+			else await this.assembleInBlink(sourceProject);
+		} finally {
+			this.assembleOnly = false;
+			this.module.FS.chdir("/");
+		}
+		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.state === "PROGRAM_LOADED") {
-			this.sourceMap = this.tryReadSourceMap();
-			return {
-				ok: true,
-				report: this.assemblerLogs
-			};
+		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,
-			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");
 		this.writeExecutableSync("/program", data instanceof Uint8Array ? data : new Uint8Array(data));
 		this.stopReason = null;
 		this.sourceMap = null;
+		this.sourceProject = null;
 		this.setState("PROGRAM_LOADED");
 	}
 	starti() {
@@ -745,30 +1135,48 @@ var BlinkRuntime = class BlinkRuntime {
 		return this.module.blinkenlibResolveSymbol(address);
 	}
 	getSourceLineForAddress(address) {
-		return this.sourceMap?.getLineIndex(address) ?? null;
+		return this.getSourceLocationForAddress(address)?.line ?? null;
+	}
+	getSourceLocationForAddress(address) {
+		const location = this.sourceMap?.getLocation(address);
+		if (!location) return null;
+		return {
+			path: this.sourceProject ? x86ProjectSourcePath(location.file, this.sourceProject) : location.file ?? "assembly.s",
+			line: location.lineIndex
+		};
 	}
 	getAddressesForSourceLine(lineIndex) {
 		return this.sourceMap?.getAddressesForLine(lineIndex) ?? [];
 	}
-	pauseForBreakpoint(address, lineNumber) {
+	getAddressesForSourceLocation(location) {
+		if (!this.sourceMap || !this.sourceProject) return [];
+		return this.sourceMap.getAddressesMatching(location.line, (file) => x86ProjectSourcePath(file, this.sourceProject) === location.path);
+	}
+	getSourceMappedAddresses() {
+		return this.sourceMap?.getAddresses() ?? [];
+	}
+	pauseForBreakpoint(address, location) {
 		this.stopReason = {
 			loadFail: false,
 			exitCode: 0,
 			kind: "breakpoint",
 			details: `execution paused at breakpoint 0x${address.toString(16)}`,
 			address,
-			lineNumber
+			lineNumber: location?.line,
+			file: location?.path
 		};
 		this.setState("PROGRAM_PAUSED");
 	}
 	pauseForLimit(address, executedInstructions) {
+		const location = this.getSourceLocationForAddress(address);
 		this.stopReason = {
 			loadFail: false,
 			exitCode: 0,
 			kind: "limit",
 			details: `execution paused after ${executedInstructions.toString()} instructions`,
 			address,
-			lineNumber: this.getSourceLineForAddress(address) ?? void 0,
+			lineNumber: location?.line,
+			file: location?.path,
 			executedInstructions
 		};
 		this.setState("PROGRAM_PAUSED");
@@ -842,14 +1250,15 @@ var BlinkRuntime = class BlinkRuntime {
 		}
 		if (code === SIGTRAP_CODES.BLINK_BREAKPOINT || code === SIGTRAP_CODES.BLINK_RUN_LIMIT) {
 			const stop = this.module.blinkenlibGetRunStop();
-			const lineNumber = this.getSourceLineForAddress(stop.address) ?? void 0;
+			const location = this.getSourceLocationForAddress(stop.address);
 			this.stopReason = {
 				loadFail: false,
 				exitCode: 0,
 				kind: stop.kind === "limit" ? "limit" : "breakpoint",
 				details: stop.kind === "limit" ? `execution paused after ${stop.executedInstructions.toString()} instructions` : `execution paused at breakpoint 0x${stop.address.toString(16)}`,
 				address: stop.address,
-				lineNumber,
+				lineNumber: location?.line,
+				file: location?.path,
 				executedInstructions: stop.executedInstructions
 			};
 			this.setState("PROGRAM_PAUSED");
@@ -874,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;
 		}
@@ -969,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) {
@@ -1101,7 +1539,8 @@ function stripPrivateHistory(entry) {
 		pc: entry.pc,
 		old_ccr: entry.old_ccr,
 		new_ccr: entry.new_ccr,
-		line: entry.line
+		line: entry.line,
+		file: entry.file
 	};
 }
 function toHistoryPc(address) {
@@ -1201,9 +1640,15 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		await this.runtime.setMode(mode);
 	}
 	async compile(code) {
+		return this.compileProject({
+			entry: "assembly.s",
+			files: { "assembly.s": code }
+		});
+	}
+	async compileProject(project) {
 		this.clearExecutionTrace();
-		this.lastSourceCode = code;
-		this.lastCompileResult = await this.runtime.compileAssembly(code);
+		this.lastSourceCode = x86ProjectText(project, project.entry);
+		this.lastCompileResult = await this.runtime.compileProject(project);
 		return this.lastCompileResult;
 	}
 	loadElf(data) {
@@ -1244,19 +1689,35 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		return String(error);
 	}
 	async checkCode(code) {
-		const result = await this.compile(code);
-		const errors = result.ok === false ? result.errors : [];
-		const lines = code.split(/\r?\n/);
-		return errors.map((error) => ({
-			lineIndex: Math.max(0, error.line - 1),
-			column: 0,
-			line: {
-				line: lines[Math.max(0, error.line - 1)] ?? "",
-				line_index: Math.max(0, error.line - 1)
-			},
-			message: error.error,
-			formatted: error.error
-		}));
+		return this.checkProject({
+			entry: "assembly.s",
+			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) {
+		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: locateDiagnosticColumn(diagnostic.error, line, diagnostic.warningClass),
+				line: {
+					line,
+					line_index: lineIndex
+				},
+				message: diagnostic.error,
+				formatted: diagnostic.error,
+				severity: diagnostic.severity,
+				...diagnostic.warningClass ? { code: diagnostic.warningClass } : {}
+			};
+		});
 	}
 	undo() {
 		const entry = this.history.pop();
@@ -1329,12 +1790,24 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 	getInstructionAt(address) {
 		const instruction = this.runtime.getInstructionAt(address);
 		if (!instruction) return null;
+		const location = this.runtime.getSourceLocationForAddress(instruction.address);
 		return {
 			address: instruction.address,
-			lineNumber: this.runtime.getSourceLineForAddress(instruction.address) ?? -1,
+			lineNumber: location?.line ?? -1,
+			file: location?.path,
+			size: instruction.size,
+			bytes: this.runtime.readMemoryBytes(instruction.address, BigInt(instruction.size)),
 			code: instruction.code
 		};
 	}
+	/** Every instruction address represented in the linked program's DWARF source map. */
+	getCompiledInstructions() {
+		if (this.runtime.state === "PROGRAM_LOADED") this.runtime.pauseAtEntry();
+		return this.runtime.getSourceMappedAddresses().flatMap((address) => {
+			const instruction = this.getInstructionAt(address);
+			return instruction ? [instruction] : [];
+		});
+	}
 	getRegisterValues() {
 		return X86_REGISTER_NAMES.map((register) => this.getRegisterValue(register));
 	}
@@ -1370,9 +1843,11 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 	}
 	resolveBreakpointAddresses(breakpoints) {
 		const addresses = /* @__PURE__ */ new Map();
-		for (const lineIndex of breakpoints) {
+		for (const breakpoint of breakpoints) {
+			const lineIndex = typeof breakpoint === "number" ? breakpoint : breakpoint.line;
 			if (!Number.isSafeInteger(lineIndex) || lineIndex < 0) throw new Error(`Invalid breakpoint line index: ${lineIndex}`);
-			for (const address of this.runtime.getAddressesForSourceLine(lineIndex)) addresses.set(address.toString(), address);
+			const resolved = typeof breakpoint === "number" ? this.runtime.getAddressesForSourceLine(lineIndex) : this.runtime.getAddressesForSourceLocation(breakpoint);
+			for (const address of resolved) addresses.set(address.toString(), address);
 		}
 		return [...addresses.values()];
 	}
@@ -1384,7 +1859,7 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		while (this.runtime.state === "PROGRAM_RUNNING") {
 			const pc = this.getPc();
 			if (breakpointSet.has(pc.toString())) {
-				this.runtime.pauseForBreakpoint(pc, this.runtime.getSourceLineForAddress(pc) ?? void 0);
+				this.runtime.pauseForBreakpoint(pc, this.runtime.getSourceLocationForAddress(pc) ?? void 0);
 				return this.getStatus();
 			}
 			if (hasLimit && executedInstructions >= limit) {
@@ -1405,7 +1880,7 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		while (this.runtime.state === "PROGRAM_RUNNING") {
 			const pc = this.getPc();
 			if (breakpointSet.has(pc.toString())) {
-				this.runtime.pauseForBreakpoint(pc, this.runtime.getSourceLineForAddress(pc) ?? void 0);
+				this.runtime.pauseForBreakpoint(pc, this.runtime.getSourceLocationForAddress(pc) ?? void 0);
 				return this.getStatus();
 			}
 			if (hasLimit && executedInstructions >= limit) {
@@ -1463,12 +1938,14 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		}
 		const memoryWrites = nativeStep.valid ? this.recordMemoryMutations(nativeStep.memoryWrites, mutations) : [];
 		if (nativeStep.valid) this.recordControlFlowMutation(nativeStep, instruction, mutations);
+		const location = this.runtime.getSourceLocationForAddress(pcBefore);
 		const entry = {
 			mutations,
 			pc: toHistoryPc(pcBefore),
 			old_ccr: { bits: flagsBefore },
 			new_ccr: { bits: flagsAfter },
-			line: this.runtime.getSourceLineForAddress(pcBefore) ?? -1,
+			line: location?.line ?? -1,
+			file: location?.path,
 			registersBefore,
 			flagsBefore,
 			callStackBefore,
@@ -1506,12 +1983,14 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 			const returnAddress = instruction ? instruction.address + BigInt(instruction.size) : step.pcBefore;
 			const symbol = this.runtime.resolveSymbol(step.pcAfter);
 			const frameAddress = symbol?.address ?? step.pcAfter;
+			const location = this.runtime.getSourceLocationForAddress(frameAddress);
 			this.callStack.push({
 				name: symbol?.name ?? "",
 				address: frameAddress,
 				destination: returnAddress,
 				sp: step.spAfter,
-				line: this.runtime.getSourceLineForAddress(frameAddress) ?? -1,
+				line: location?.line ?? -1,
+				file: location?.path,
 				color: makeFrameColor(this.callStack.length, frameAddress)
 			});
 			mutations.push({
@@ -1541,6 +2020,6 @@ async function createX86Emulator(options = {}) {
 	return X86Emulator.create(options);
 }
 //#endregion
-export { BaseEmulator, BlinkRuntime, BlinkState, DEFAULT_ASSEMBLER_ID, EmulatorStatus, RegisterSize, X86Emulator, X86_REGISTER_NAMES, assemblers, createX86Emulator, defaultResourceUrl, fasmDiagnostics, gnuDiagnostics, isNodeRuntime, nasmDiagnostics, observeCallbackResult, readResourceBytes, toResourceUrl };
+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