xbintsc 0.5.6 → 0.5.21

package/src/driver/index.ts

@@ -36,6 +36,5 @@ export {
   ensureWindowsIconResource,
   resolveResourceCompiler,
   type ResourceCompiler,
-  type ResourceCompilerKind,
 } from "./win-icon.js";
 export { bundlePathFor, infoPlist, packageMacApp, type MacBundleOptions } from "./mac-bundle.js";

package/src/driver/options.ts

@@ -0,0 +1,70 @@
+/**
+ * Public option and result types for the build driver.
+ *
+ * They live apart from the orchestration in `compiler.ts` so a feature that
+ * adds one option touches this file (and the phase that consumes it) without
+ * colliding with unrelated driver work.
+ */
+
+import type { Diagnostic } from "../diagnostics/diagnostic.js";
+import type { ExtensionRegistry } from "../extensions/registry.js";
+import type { AppConfig } from "./config.js";
+import type { PgoMode, Runner } from "./toolchain.js";
+
+/** What `build` produces: an executable, an object file or LLVM IR only. */
+export type EmitKind = "exe" | "obj" | "ir";
+
+export interface BuildOptions {
+  /** Explicit output path (defaults to the source base name in `outDir`). */
+  readonly output?: string;
+  readonly outDir?: string;
+  readonly optimize?: "0" | "1" | "2" | "3";
+  readonly emit?: EmitKind;
+  readonly force?: boolean;
+  readonly verbose?: boolean;
+  readonly cacheDir?: string;
+  readonly extensions?: ExtensionRegistry;
+  readonly runner?: Runner;
+  readonly clang?: string;
+  /** Prefer a prebuilt `runtime/lib/<os>-<arch>/*.a` archive when present (default true). */
+  readonly preferPrebuilt?: boolean;
+  readonly write?: boolean;
+  /** Application icon embedded into the binary (shorthand for `app.icon`). */
+  readonly icon?: string;
+  /** Application metadata: name, icon and macOS bundle settings. */
+  readonly app?: AppConfig;
+  /** Emit LLVM debug metadata so `-g` produces DWARF/CodeView (default false). */
+  readonly debug?: boolean;
+  /** Compile the program and runtime to LTO bitcode and link with lld. */
+  readonly lto?: boolean;
+  /**
+   * Profile-guided optimization. `generate` builds an instrumented binary that
+   * writes `.profraw` files into `pgoDir`; `use` consumes them.
+   */
+  readonly pgo?: PgoMode;
+  /** Profile directory (default: `<outDir>/pgo`). */
+  readonly pgoDir?: string;
+}
+
+/** One phase of a build, in milliseconds (reported by `--time`). */
+export interface PhaseTiming {
+  readonly phase: "frontend" | "codegen" | "runtime" | "clang" | "link";
+  readonly ms: number;
+}
+
+export interface BuildResult {
+  readonly outputPath: string;
+  readonly irPath?: string;
+  readonly cached: boolean;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly ir?: string;
+  /** macOS `.app` bundle produced by `app.bundle` (darwin only). */
+  readonly bundlePath?: string;
+  /** Per-phase timings, collected for `xbintsc build --time`. */
+  readonly timings?: readonly PhaseTiming[];
+}
+
+export interface CompileStringResult {
+  readonly ir: string;
+  readonly diagnostics: readonly Diagnostic[];
+}

package/src/driver/runtime-objects.ts

@@ -0,0 +1,134 @@
+/**
+ * Compiling the C runtime (and every extension's C sources) into linkable
+ * objects, reusing cached objects keyed by the source/header content hash.
+ *
+ * `RUNTIME_SOURCES` is the list of core translation units. A feature that adds
+ * a runtime file adds one line here and nowhere else.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import type { ExtensionRegistry } from "../extensions/registry.js";
+import { hashParts } from "./cache.js";
+import { findRuntimeLibrary } from "./runtime-lib.js";
+import { compileC, optimizationFlags, RUNTIME_CFLAGS, type PgoMode, type Runner } from "./toolchain.js";
+import { COMPILER_VERSION } from "./version.js";
+
+/** Core runtime translation units (each compiled and cached independently). */
+export const RUNTIME_SOURCES = [
+  "xt_alloc.c",
+  "xt_values.c",
+  "xt_bigint.c",
+  "xt_containers.c",
+  "xt_weak.c",
+  "xt_typed_array.c",
+  "xt_stdlib.c",
+  "xt_stdlib2.c",
+  "xt_promise.c",
+  "xt_async.c",
+  "xt_loop.c",
+  "xt_async_io.c",
+  "xt_generator.c",
+  "xt_coroutine.c",
+  "xt_fetch.c",
+  "xt_symbol.c",
+  "xt_builtins.c",
+  "xt_constructors.c",
+  "xt_structured_clone.c",
+  "xt_performance.c",
+  "xt_text_codec.c",
+  "xt_url.c",
+  "xt_array_buffer.c",
+  "xt_io.c",
+] as const;
+
+export interface RuntimeObjects {
+  readonly runtimeObjects: readonly string[];
+  readonly extensionObjects: readonly string[];
+  /** Pre-built C++/Rust objects and archives contributed by native extensions. */
+  readonly nativeObjects: readonly string[];
+}
+
+export interface RuntimeObjectsOptions {
+  readonly runner: Runner;
+  readonly clang: string;
+  readonly runtimeDir: string;
+  readonly cacheDir: string;
+  readonly registry: ExtensionRegistry;
+  readonly preferPrebuilt: boolean;
+  readonly env: Record<string, string>;
+  readonly lto: boolean;
+  readonly pgo: PgoMode | undefined;
+  readonly pgoDir: string;
+}
+
+/**
+ * Compile the core runtime and every extension source, reusing cached object
+ * files keyed on the C source hash. Returns the object paths to link.
+ *
+ * When `preferPrebuilt` is set, a shipped static archive
+ * (`runtime/lib/<os>-<arch>/{core,ext_<name>}.a`) is used instead of compiling
+ * that group's C sources. Missing archives fall back to compiling the sources.
+ */
+export function ensureRuntimeObjects(options: RuntimeObjectsOptions): RuntimeObjects {
+  const { runner, clang, runtimeDir, cacheDir, registry, preferPrebuilt, env, lto, pgo, pgoDir } = options;
+  const optimization = optimizationFlags(lto, pgo, pgoDir);
+  /* Runtime objects depend on the shared headers (rt.h/rt_internal.h/...) and
+     the `#include`d implementation fragments (`.inc`), so any change to them
+     must invalidate every cached object. Hash them all. */
+  const headerParts: string[] = [];
+  const collectHeaders = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) collectHeaders(full);
+      else if (entry.name.endsWith(".h") || entry.name.endsWith(".inc")) headerParts.push(readFileSync(full, "utf8"));
+    }
+  };
+  collectHeaders(runtimeDir);
+  const headerStamp = hashParts(headerParts);
+
+  const compileOne = (sourcePath: string, tag: string): string => {
+    const body = readFileSync(sourcePath, "utf8");
+    const key = hashParts([
+      "runtime",
+      COMPILER_VERSION,
+      RUNTIME_CFLAGS.join(" "),
+      optimization.join(" "),
+      tag,
+      headerStamp,
+      body,
+      clang,
+      process.platform,
+    ]);
+    const objectPath = join(cacheDir, `${tag}-${key}.o`);
+    if (!existsSync(objectPath)) {
+      compileC(runner, clang, sourcePath, objectPath, runtimeDir, env, optimization);
+    }
+    return objectPath;
+  };
+
+  const coreArchive = preferPrebuilt ? findRuntimeLibrary("core") : undefined;
+  const runtimeObjects = coreArchive
+    ? [coreArchive]
+    : RUNTIME_SOURCES.map((source) => compileOne(join(runtimeDir, source), basename(source, ".c")));
+
+  const extensionObjects: string[] = [];
+  const seen = new Set<string>();
+  for (const extension of registry.all()) {
+    const sources = extension.runtimeSources ? extension.runtimeSources() : [];
+    if (sources.length === 0) continue;
+    const archive = preferPrebuilt ? findRuntimeLibrary(`ext_${extension.name}`) : undefined;
+    if (archive) {
+      extensionObjects.push(archive);
+      continue;
+    }
+    for (const sourcePath of sources) {
+      const dedupeKey = resolve(sourcePath);
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      extensionObjects.push(compileOne(sourcePath, `ext_${extensionObjects.length}_${basename(sourcePath, ".c")}`));
+    }
+  }
+  // A native archive may be shared by several manifests; link each once.
+  return { runtimeObjects, extensionObjects, nativeObjects: [...new Set(registry.nativeObjects())] };
+}

package/src/driver/toolchain-provider.ts

@@ -17,6 +17,10 @@
  * The version is checked here, not left to the first failed C compile: the
  * emitted IR needs LLVM 16+ (opaque pointers), and a "clang 15 is too old"
  * error up front is far more actionable than a wall of IR type errors later.
+ * On Windows the target is checked as well: only an MSVC-targeting clang can
+ * link against the runtime, so a compiler built for another Windows ABI is
+ * skipped (or rejected, when named explicitly) instead of producing objects
+ * the linker cannot mix.
  *
  * Extra linker arguments (for example `-fuse-ld=lld`) can be supplied through
  * `xbintsc_LINKER_ARGS`.

package/src/driver/toolchain.ts

@@ -6,8 +6,8 @@
  */
 
 import { spawnSync, type SpawnSyncOptions } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 export interface CommandResult {
   readonly status: number;
@@ -75,6 +75,8 @@ export interface ClangProbe {
   /** True when the command ran and exited 0. */
   readonly responds: boolean;
   readonly version?: ClangVersion;
+  /** The `Target:` triple clang was built for, when it prints one. */
+  readonly target?: string;
   /** First line of the version output, for diagnostics. */
   readonly summary: string;
 }
@@ -98,6 +100,22 @@ export function parseClangVersion(output: string): ClangVersion | undefined {
   return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
 }
 
+/**
+ * Extract the `Target:` triple from `clang --version` output. Windows builds
+ * must target the MSVC ABI; clang built for a GNU/Windows or other triple emits
+ * objects that cannot be linked into an xbintsc executable (see
+ * {@link isMsvcTarget}).
+ */
+export function parseClangTarget(output: string): string | undefined {
+  const match = /^\s*Target:\s*(\S+)/m.exec(output);
+  return match?.[1];
+}
+
+/** True when a clang target triple uses the MSVC ABI on Windows. */
+export function isMsvcTarget(target: string): boolean {
+  return /-windows-msvc/i.test(target);
+}
+
 function firstLineOf(text: string): string {
   const end = text.indexOf("\n");
   return (end === -1 ? text : text.slice(0, end)).trim();
@@ -113,10 +131,12 @@ export function probeClang(
     const result = runner.run(command, ["--version"], env ? { env } : undefined);
     const output = `${result.stdout}\n${result.stderr}`;
     const version = parseClangVersion(output);
+    const target = parseClangTarget(output);
     return {
       command,
       responds: result.status === 0,
       ...(version ? { version } : {}),
+      ...(target ? { target } : {}),
       summary: firstLineOf(result.stdout) || firstLineOf(result.stderr),
     };
   } catch {
@@ -171,23 +191,57 @@ function tooOldError(probe: ClangProbe): ToolchainError {
   );
 }
 
+/**
+ * Windows links against the MSVC ABI, so a clang built for another Windows ABI
+ * (or for a different OS) cannot be used: its objects would not link with the
+ * MSVC runtime. This turns that mismatch into an actionable error instead of a
+ * wall of unresolved symbols.
+ */
+function wrongTargetError(probe: ClangProbe): ToolchainError {
+  return new ToolchainError(
+    "clang --version",
+    1,
+    `${probe.command} targets ${probe.target}, but xbintsc on Windows requires a clang whose default ` +
+      "target is the MSVC ABI (for example x86_64-pc-windows-msvc).\n" +
+      "Install the Visual Studio C++ build tools and use the LLVM bundled with Visual Studio " +
+      "(VC\\Tools\\Llvm\\<arch>\\bin\\clang.exe), or set xbintsc_CLANG to an MSVC-targeting clang.",
+  );
+}
+
+function hasWrongWindowsTarget(probe: ClangProbe): boolean {
+  return process.platform === "win32" && probe.target !== undefined && !isMsvcTarget(probe.target);
+}
+
 function noCompilerError(tried: readonly ClangProbe[]): ToolchainError {
   const responded = tried.filter((probe) => probe.responds);
   const details = responded.map((probe) => {
     const version = probe.version
       ? `clang ${probe.version.major}.${probe.version.minor}.${probe.version.patch}`
       : probe.summary || "unknown version";
-    return `  ${probe.command}: ${version}`;
+    const target = probe.target ? ` (target ${probe.target})` : "";
+    return `  ${probe.command}: ${version}${target}`;
   });
+  const wrongTarget = responded.some(hasWrongWindowsTarget);
   const tooOld = responded.some((probe) => probe.version !== undefined && probe.version.major < MINIMUM_CLANG_MAJOR);
-  const reason = tooOld
-    ? `Only clang older than ${MINIMUM_CLANG_MAJOR} was found; xbintsc requires clang ${MINIMUM_CLANG_MAJOR}+ ` +
-      "(the emitted LLVM IR uses opaque pointers)."
-    : `No clang ${MINIMUM_CLANG_MAJOR}+ was found.`;
+  const reasons: string[] = [];
+  if (tooOld) {
+    reasons.push(
+      `Only clang older than ${MINIMUM_CLANG_MAJOR} was found; xbintsc requires clang ${MINIMUM_CLANG_MAJOR}+ ` +
+        "(the emitted LLVM IR uses opaque pointers).",
+    );
+  }
+  if (wrongTarget) {
+    reasons.push(
+      "Only clang targeting a non-MSVC Windows ABI was found; the Windows build links against the MSVC ABI.",
+    );
+  }
+  if (reasons.length === 0) reasons.push(`No clang ${MINIMUM_CLANG_MAJOR}+ was found.`);
   return new ToolchainError(
     "clang --version",
     1,
-    [reason, ...(details.length > 0 ? ["Tested:", ...details] : []), "Set xbintsc_CLANG to a clang binary."].join("\n"),
+    [...reasons, ...(details.length > 0 ? ["Tested:", ...details] : []), "Set xbintsc_CLANG to a clang binary."].join(
+      "\n",
+    ),
   );
 }
 
@@ -207,6 +261,7 @@ export function locateClang(runner: Runner = realRunner): ClangLocation {
   if (explicit) {
     const probe = probeClang(runner, explicit);
     if (probe.responds) {
+      if (hasWrongWindowsTarget(probe)) throw wrongTargetError(probe);
       if (probe.version && probe.version.major < MINIMUM_CLANG_MAJOR) throw tooOldError(probe);
       return { command: explicit, source: "env", ...(probe.version ? { version: probe.version } : {}) };
     }
@@ -216,6 +271,7 @@ export function locateClang(runner: Runner = realRunner): ClangLocation {
     const probe = probeClang(runner, command);
     tried.push(probe);
     if (!probe.responds || !probe.version) continue;
+    if (hasWrongWindowsTarget(probe)) continue;
     if (probe.version.major < MINIMUM_CLANG_MAJOR) continue;
     return { command, source: "system", version: probe.version };
   }
@@ -227,6 +283,22 @@ export function findClang(runner: Runner = realRunner): string {
   return locateClang(runner).command;
 }
 
+/** Profile-guided optimization stage (`--pgo-generate` / `--pgo-use`). */
+export type PgoMode = "generate" | "use";
+
+/** clang flags for LTO and the selected PGO stage. */
+export function optimizationFlags(
+  lto: boolean | undefined,
+  pgo: PgoMode | undefined,
+  pgoDir: string | undefined,
+): string[] {
+  const flags: string[] = [];
+  if (lto) flags.push("-flto");
+  if (pgo === "generate") flags.push(`-fprofile-generate=${pgoDir ?? "pgo"}`);
+  else if (pgo === "use") flags.push(`-fprofile-use=${pgoDir ?? "pgo"}`);
+  return flags;
+}
+
 export interface CompileIrOptions {
   readonly clang: string;
   readonly irPath: string;
@@ -235,6 +307,11 @@ export interface CompileIrOptions {
   readonly env?: Record<string, string>;
   /** Emit debug info (`-g`) and keep frame pointers for crash backtraces. */
   readonly debug?: boolean;
+  /** Compile to LTO bitcode and let the linker optimize across units. */
+  readonly lto?: boolean;
+  /** Instrument (`generate`) or consume (`use`) an LLVM profile. */
+  readonly pgo?: PgoMode;
+  readonly pgoDir?: string;
 }
 
 /**
@@ -247,9 +324,19 @@ const SECTION_FLAGS = ["-ffunction-sections", "-fdata-sections"];
 /** Compile an LLVM IR file to a native object file. */
 export function compileIr(runner: Runner, options: CompileIrOptions): void {
   const debugFlags = options.debug ? ["-g", "-fno-omit-frame-pointer"] : [];
+  const profileFlags = optimizationFlags(options.lto, options.pgo, options.pgoDir);
   const result = runner.run(
     options.clang,
-    [`-O${options.optimize}`, ...SECTION_FLAGS, ...debugFlags, "-c", options.irPath, "-o", options.objectPath],
+    [
+      `-O${options.optimize}`,
+      ...SECTION_FLAGS,
+      ...debugFlags,
+      ...profileFlags,
+      "-c",
+      options.irPath,
+      "-o",
+      options.objectPath,
+    ],
     { env: options.env },
   );
   if (result.status !== 0) throw new ToolchainError(`${options.clang} ${options.irPath}`, result.status, result.stderr);
@@ -262,6 +349,9 @@ export interface LinkOptions {
   readonly linkerFlags: readonly string[];
   readonly optimize: string;
   readonly env?: Record<string, string>;
+  readonly lto?: boolean;
+  readonly pgo?: PgoMode;
+  readonly pgoDir?: string;
 }
 
 /** Platform flag that drops unreferenced sections (paired with {@link SECTION_FLAGS}). */
@@ -272,8 +362,14 @@ function deadStripFlag(): string[] {
 }
 
 export function link(runner: Runner, options: LinkOptions): void {
+  const profileFlags = optimizationFlags(options.lto, options.pgo, options.pgoDir);
   const args = [
     `-O${options.optimize}`,
+    ...profileFlags,
+    /* LTO bitcode needs a linker with an LTO plugin. lld ships with LLVM and
+     * understands both ELF/Mach-O and COFF; without it MSVC link.exe rejects
+     * the bitcode object on Windows. */
+    ...(options.lto ? ["-fuse-ld=lld"] : []),
     ...options.objectPaths,
     "-o",
     options.outputPath,
@@ -305,11 +401,59 @@ export function compileC(
   objectPath: string,
   includeDir: string,
   env?: Record<string, string>,
+  extraFlags: readonly string[] = [],
 ): void {
   const result = runner.run(
     clang,
-    [...RUNTIME_CFLAGS, "-c", sourcePath, "-o", objectPath, `-I${includeDir}`],
+    [...RUNTIME_CFLAGS, ...extraFlags, "-c", sourcePath, "-o", objectPath, `-I${includeDir}`],
     { env },
   );
   if (result.status !== 0) throw new ToolchainError(`${clang} ${sourcePath}`, result.status, result.stderr);
 }
+
+/**
+ * Merge the `.profraw` files written by an instrumented binary into the
+ * `default.profdata` that `-fprofile-use=<dir>` expects. Clang's `-fprofile-use`
+ * does not read raw profiles directly; this runs `llvm-profdata merge`.
+ *
+ * `xbintsc_LLVM_PROFDATA` selects the tool when it is not on `PATH`.
+ */
+export function mergeProfileData(
+  runner: Runner,
+  directory: string,
+  clang: string,
+  env?: Record<string, string>,
+): void {
+  const profdata = join(directory, "default.profdata");
+  if (existsSync(profdata)) return;
+  let raw: string[];
+  try {
+    raw = readdirSync(directory)
+      .filter((name) => name.endsWith(".profraw"))
+      .map((name) => join(directory, name));
+  } catch {
+    raw = [];
+  }
+  if (raw.length === 0) {
+    throw new ToolchainError(
+      "llvm-profdata merge",
+      1,
+      `no .profraw files found in ${directory}; run the --pgo-generate binary before --pgo-use.`,
+    );
+  }
+  /* Prefer the llvm-profdata shipped next to clang: a system-wide copy from a
+   * different LLVM version rejects newer raw profile formats. */
+  const suffix = process.platform === "win32" ? ".exe" : "";
+  const adjacent = join(dirname(clang), `llvm-profdata${suffix}`);
+  const tool =
+    process.env.xbintsc_LLVM_PROFDATA ??
+    (existsSync(adjacent) ? adjacent : "llvm-profdata");
+  const result = runner.run(tool, ["merge", "-o", profdata, ...raw], env ? { env } : undefined);
+  if (result.status !== 0) {
+    throw new ToolchainError(
+      `${tool} merge`,
+      result.status,
+      `${result.stderr}\nInstall LLVM's llvm-profdata or set xbintsc_LLVM_PROFDATA to it.`,
+    );
+  }
+}

package/src/driver/version.ts

@@ -0,0 +1,12 @@
+/**
+ * The compiler's own version.
+ *
+ * It is part of the incremental cache key, so it must be bumped for every
+ * release (a test enforces that it matches `package.json`); a stale version
+ * would let an upgraded compiler reuse binaries produced by the previous one.
+ *
+ * Keep this constant in its own module: the pre-commit hook bumps it on
+ * `main`/`master` only (see `.githooks/pre-commit`), so feature branches never
+ * change this line and merging two of them cannot conflict here.
+ */
+export const COMPILER_VERSION = "0.5.21";

package/src/driver/win-icon.ts

@@ -4,9 +4,8 @@
  * Windows reads the application icon from a resource section in the `.exe`, so
  * an embedded blob is not enough: the icon is wrapped in a `.rc` script and
  * compiled to a resource object that is linked into the executable. `llvm-rc`
- * (shipping with clang) is preferred; MinGW `windres` is the fallback. Both are
- * optional — a missing resource compiler degrades to the runtime window icon
- * instead of failing the build.
+ * (shipping with LLVM/clang, and next to the clang xbintsc resolves) produces
+ * the MSVC-compatible `.res` object the linker expects.
  */
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -15,51 +14,56 @@ import { hashParts } from "./cache.js";
 import { IconError, toIcoBytes, type IconInfo } from "./icon.js";
 import type { Runner } from "./toolchain.js";
 
-export type ResourceCompilerKind = "llvm-rc" | "windres";
-
 export interface ResourceCompiler {
   readonly tool: string;
-  readonly kind: ResourceCompilerKind;
 }
 
 /**
- * Locate a resource compiler. `xbintsc_RC` wins, then `llvm-rc` next to the
- * resolved clang, then `llvm-rc` and `windres` on `PATH`.
+ * Probe `llvm-rc`.
+ *
+ * It has no `--version` flag: any invocation that is not a valid conversion
+ * exits non-zero, but a usage-only run (`/?`) prints the tool name, which is
+ * what identifies it. Treat a usage banner as success so a real `llvm-rc`
+ * installed next to clang is not skipped.
+ */
+function isLlvmRc(runner: Runner, tool: string): boolean {
+  try {
+    const result = runner.run(tool, ["/?"]);
+    if (result.status === 0) return true;
+    return /LLVM Resource Converter/i.test(result.stdout + result.stderr);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate `llvm-rc`. `xbintsc_RC` wins, then `llvm-rc` next to the resolved
+ * clang, then `llvm-rc` on `PATH`. Returns `undefined` when none exists; the
+ * caller then builds without the embedded icon.
  */
 export function resolveResourceCompiler(runner: Runner, clang: string): ResourceCompiler | undefined {
   const exe = process.platform === "win32" ? ".exe" : "";
   // An explicit override is trusted: probe it and fall back rather than
   // rejecting it on a path prefix check (it may be a bare command on PATH).
   const override = process.env.xbintsc_RC;
-  if (override) {
-    const kind: ResourceCompilerKind = /windres/i.test(override) ? "windres" : "llvm-rc";
-    try {
-      if (runner.run(override, ["--version"]).status === 0) return { tool: override, kind };
-    } catch {
-      // Fall through to the discovered compilers.
-    }
-  }
-  const candidates: ResourceCompiler[] = [];
+  if (override && isLlvmRc(runner, override)) return { tool: override };
+
+  const candidates: string[] = [];
   if (clang && (clang.includes("/") || clang.includes("\\"))) {
-    candidates.push({ tool: join(dirname(clang), `llvm-rc${exe}`), kind: "llvm-rc" });
+    candidates.push(join(dirname(clang), `llvm-rc${exe}`));
   }
-  candidates.push({ tool: `llvm-rc${exe}`, kind: "llvm-rc" });
-  candidates.push({ tool: `windres${exe}`, kind: "windres" });
+  candidates.push(`llvm-rc${exe}`);
 
-  for (const candidate of candidates) {
-    if ((candidate.tool.includes("/") || candidate.tool.includes("\\")) && !existsSync(candidate.tool)) continue;
-    try {
-      if (runner.run(candidate.tool, ["--version"]).status === 0) return candidate;
-    } catch {
-      // Not runnable; try the next candidate.
-    }
+  for (const tool of candidates) {
+    if ((tool.includes("/") || tool.includes("\\")) && !existsSync(tool)) continue;
+    if (isLlvmRc(runner, tool)) return { tool };
   }
   return undefined;
 }
 
 /**
- * Compile the icon into a linkable PE resource object (`.res` for llvm-rc, a
- * COFF `.o` for windres). Cached by contents and compiler kind.
+ * Compile the icon into a linkable PE resource object (`.res`, cached by
+ * contents).
  */
 export function ensureWindowsIconResource(
   runner: Runner,
@@ -69,11 +73,11 @@ export function ensureWindowsIconResource(
   env?: Record<string, string>,
 ): string {
   const icoBytes = toIcoBytes(icon);
-  const key = hashParts(["icon-res", compiler.kind, Buffer.from(icoBytes).toString("base64")]);
+  const key = hashParts(["icon-res", Buffer.from(icoBytes).toString("base64")]);
   const icoName = `icon-${key}.ico`;
   const icoPath = join(cacheDir, icoName);
   const rcPath = join(cacheDir, `icon-${key}.rc`);
-  const objectPath = join(cacheDir, `icon-${key}.${compiler.kind === "windres" ? "o" : "res"}`);
+  const objectPath = join(cacheDir, `icon-${key}.res`);
   if (existsSync(objectPath)) return objectPath;
 
   mkdirSync(cacheDir, { recursive: true });
@@ -82,11 +86,7 @@ export function ensureWindowsIconResource(
   // its working directory so the relative path resolves.
   writeFileSync(rcPath, `1 ICON "${icoName}"\n`);
 
-  const args =
-    compiler.kind === "windres"
-      ? [rcPath, "-O", "coff", "-o", objectPath]
-      : ["/fo", objectPath, rcPath];
-  const result = runner.run(compiler.tool, args, { cwd: cacheDir, env });
+  const result = runner.run(compiler.tool, ["/fo", objectPath, rcPath], { cwd: cacheDir, env });
   if (result.status !== 0 || !existsSync(objectPath)) {
     throw new IconError(
       `Failed to compile the Windows icon resource with ${compiler.tool}:\n${result.stderr || result.stdout}`,

package/src/extensions/node/fs/index.ts

@@ -1,8 +1,9 @@
 /**
  * Node's `fs` module: synchronous file and directory operations backed by
- * `runtime/ext_node/fs`. Asynchronous callbacks are not supported (xbintsc has
- * no event loop), so the API is the `*Sync` surface plus `watch`/`watchFile`
- * (which return API-shaped watchers that never emit).
+ * `runtime/ext_node/fs`, plus the `fs.promises` namespace (implemented in
+ * `async_*.c` on top of the asynchronous I/O pool). The callback-style
+ * `readFile`/`writeFile` forms are not supported; `*Sync` and `fs.promises` are.
+ * `watch`/`watchFile` return API-shaped watchers that never emit.
  *
  * `fs.constants` and `fs.promises` are exposed as value getters, so both
  * `import { constants } from "fs"` and the `fs.constants.F_OK` property form
@@ -40,6 +41,14 @@ export const fsModule: NodeModule = {
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/watch.c"),
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/constants.c"),
     resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/streams.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_job.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_worker.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_worker_dir.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_worker_fd.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_complete.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_api.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/async_fh.c"),
+    resolveFrom(import.meta.url, "../../../../runtime/ext_node/fs/promises.c"),
   ],
   builtins: () => builtins,
   exports: () => exports,