@specy/x86 2.0.4 → 2.1.0

package/dist/index.mjs

@@ -49,12 +49,13 @@ 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): (.*)$/;
 	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()
+			file: match[1] || void 0,
+			line: Number.parseInt(match[2] ?? "0", 10),
+			error: (match[4] ?? "").trim()
 		});
 	}
 	return diagnostics;
@@ -62,32 +63,39 @@ function nasmDiagnostics(str) {
 function gnuDiagnostics(str) {
 	const diagnostics = [];
 	const lines = str.split("\n");
-	const regex = /\/assembly\.s:(\d+): (Error: .+)/;
+	const regex = /^(.*):(\d+): (Error: .+)$/;
 	for (const line of lines) {
 		const match = line.match(regex);
 		if (match) diagnostics.push({
-			line: Number.parseInt(match[1] ?? "0", 10),
-			error: match[2] ?? ""
+			file: match[1] || void 0,
+			line: Number.parseInt(match[2] ?? "0", 10),
+			error: match[3] ?? ""
 		});
 	}
 	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]
 			});
 			lineNumber = null;
+			file = void 0;
 		}
 	}
 	return diagnostics;
@@ -170,6 +178,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 +193,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 +213,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 +329,7 @@ function parseDebugLine(bytes) {
 			entries.push({
 				address,
 				lineIndex: Math.max(0, line - 1),
-				file: sourceFile?.name
+				file: dwarfSourcePath(sourceFile)
 			});
 		};
 		const advanceAddress = (operationAdvance) => {
@@ -392,6 +419,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 +470,87 @@ 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}`);
+	}
+}
+/**
+* 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/types.ts
 const X86_REGISTER_NAMES = [
 	"rax",
@@ -575,6 +688,7 @@ var BlinkRuntime = class BlinkRuntime {
 	stateWaiters = [];
 	stdinBytes = [];
 	sourceMap = null;
+	sourceProject = null;
 	defaultArgc = "/program";
 	defaultArgv = "";
 	constructor(module, mode, callbacks, scheduler) {
@@ -626,17 +740,32 @@ var BlinkRuntime = class BlinkRuntime {
 		this.setState("READY");
 	}
 	async compileAssembly(code) {
+		return this.compileProject({
+			entry: "assembly.s",
+			files: { "assembly.s": code }
+		});
+	}
+	async compileProject(project) {
 		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);
+		this.sourceProject = sourceProject;
 		this.stopReason = null;
 		this.assemblerLogs = "";
 		this.assemblerErrors = [];
 		this.sourceMap = null;
-		this.module.FS.writeFile("/assembly.s", code);
 		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");
+		try {
+			await defer();
+			this.setEmulationArgs("/assembler", this.mode.binaries.assembler.commands, "");
+			this.module._blinkenlib_run_fast();
+			await this.waitForState((state) => state !== "ASSEMBLING" && state !== "LINKING");
+		} finally {
+			this.module.FS.chdir("/");
+		}
 		if (this.state === "PROGRAM_LOADED") {
 			this.sourceMap = this.tryReadSourceMap();
 			return {
@@ -646,7 +775,10 @@ var BlinkRuntime = class BlinkRuntime {
 		}
 		return {
 			ok: false,
-			errors: this.assemblerErrors,
+			errors: this.assemblerErrors.map((error) => ({
+				...error,
+				file: x86ProjectSourcePath(error.file, sourceProject)
+			})),
 			report: this.assemblerLogs
 		};
 	}
@@ -655,6 +787,7 @@ var BlinkRuntime = class BlinkRuntime {
 		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 +878,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 +993,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");
@@ -1101,14 +1253,15 @@ 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) {
 	return Number(address);
 }
 function makeFrameColor(index, address) {
-	return `hsl(${(index + Number(address & 255n) * 137) % 360}, 40%, 60%)`;
+	return `hsl(${index * 137 % 360}, 40%, 60%)`;
 }
 function maskForSize(size) {
 	return (1n << BigInt(size * 8)) - 1n;
@@ -1201,9 +1354,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 +1403,28 @@ 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 }
+		});
+	}
+	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 {
+				file: path,
+				lineIndex,
+				column: 0,
+				line: {
+					line: x86ProjectText(project, path).split(/\r?\n/)[lineIndex] ?? "",
+					line_index: lineIndex
+				},
+				message: error.error,
+				formatted: error.error
+			};
+		});
 	}
 	undo() {
 		const entry = this.history.pop();
@@ -1329,12 +1497,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 +1550,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 +1566,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 +1587,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 +1645,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 +1690,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 +1727,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, nasmDiagnostics, observeCallbackResult, readResourceBytes, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
 
 //# sourceMappingURL=index.mjs.map