xbintsc 0.5.6 → 0.5.21

package/runtime/xt_weak.c

@@ -0,0 +1,281 @@
+/*
+ * xbintsc runtime — weak collections.
+ *
+ * `WeakMap`, `WeakSet` and `WeakRef` are the only values whose references the
+ * mark-sweep collector must *not* follow unconditionally. Their keys (and the
+ * target of a WeakRef) are excluded from the ordinary trace; instead the
+ * collector runs an ephemeron fixed point after marking:
+ *
+ *     repeat
+ *       for every live WeakMap entry whose key is marked:
+ *         mark the value
+ *     until nothing new is marked
+ *
+ * A value is therefore retained only while its key is otherwise reachable, and
+ * a key/value cycle that is only reachable through the WeakMap is collected.
+ * WeakRef targets that stay unmarked after that fixed point are cleared.
+ *
+ * WeakMap/WeakSet entries are removed at sweep time, so a later `has()` never
+ * observes a key whose object has been collected.
+ */
+
+#include "rt_internal.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+static int xt_is_weak_target(xt_value value) {
+  return XT_IS_OBJECT(value) || XT_IS_ARRAY(value) || XT_IS_FUNCTION(value);
+}
+
+static void xt_weak_key_error(void) {
+  xt_throw(xt_error_from_message("TypeError: Invalid value used as weak map key"));
+}
+
+int xt_is_weak_map(xt_value value) {
+  return XT_IS_OBJECT(value) &&
+         ((xt_header *)XT_GET_PTR(value))->kind == XT_OBJECT_KIND_WEAK_MAP;
+}
+
+int xt_is_weak_set(xt_value value) {
+  return XT_IS_OBJECT(value) &&
+         ((xt_header *)XT_GET_PTR(value))->kind == XT_OBJECT_KIND_WEAK_SET;
+}
+
+int xt_is_weak_ref(xt_value value) {
+  return XT_IS_OBJECT(value) &&
+         ((xt_header *)XT_GET_PTR(value))->kind == XT_OBJECT_KIND_WEAK_REF;
+}
+
+/* -- WeakMap -------------------------------------------------------------- */
+
+static int32_t xt_weak_map_index(xt_weak_map *map, xt_value key) {
+  for (uint32_t i = 0; i < map->count; i++) {
+    if (xt_value_equals(map->keys[i], key)) return (int32_t)i;
+  }
+  return -1;
+}
+
+static void xt_weak_map_set(xt_weak_map *map, xt_value key, xt_value value) {
+  int32_t index = xt_weak_map_index(map, key);
+  if (index >= 0) {
+    map->values[index] = value;
+    return;
+  }
+  if (map->count >= map->capacity) {
+    uint32_t capacity = map->capacity == 0 ? 8 : map->capacity * 2;
+    map->keys = (xt_value *)realloc(map->keys, sizeof(xt_value) * capacity);
+    map->values = (xt_value *)realloc(map->values, sizeof(xt_value) * capacity);
+    if (!map->keys || !map->values) abort();
+    map->capacity = capacity;
+  }
+  map->keys[map->count] = key;
+  map->values[map->count] = value;
+  map->count++;
+}
+
+static int xt_weak_map_delete(xt_weak_map *map, xt_value key) {
+  int32_t index = xt_weak_map_index(map, key);
+  if (index < 0) return 0;
+  for (uint32_t i = (uint32_t)index + 1; i < map->count; i++) {
+    map->keys[i - 1] = map->keys[i];
+    map->values[i - 1] = map->values[i];
+  }
+  map->count--;
+  return 1;
+}
+
+xt_value xt_weak_map_ctor(int32_t argc, xt_value *argv) {
+  xt_weak_map *map = (xt_weak_map *)xt_alloc(sizeof(xt_weak_map), XT_OBJECT_KIND_WEAK_MAP);
+  map->keys = NULL;
+  map->values = NULL;
+  map->count = 0;
+  map->capacity = 0;
+  xt_value iterable = xt_arg_at(argc, argv, 0);
+  if (XT_IS_ARRAY(iterable)) {
+    xt_array *array = (xt_array *)XT_GET_PTR(iterable);
+    for (uint32_t i = 0; i < array->length; i++) {
+      xt_array *pair = xt_as_array(array->items[i]);
+      if (!pair || pair->length < 2) {
+        xt_throw(xt_error_from_message("TypeError: Iterator value is not an entry object"));
+        return XT_UNDEFINED;
+      }
+      if (!xt_is_weak_target(pair->items[0])) {
+        xt_weak_key_error();
+        return XT_UNDEFINED;
+      }
+      xt_weak_map_set(map, pair->items[0], pair->items[1]);
+    }
+  }
+  return XT_FROM_PTR(XT_TAG_OBJECT, map);
+}
+
+/* -- WeakSet -------------------------------------------------------------- */
+
+static int32_t xt_weak_set_index(xt_weak_set *set, xt_value value) {
+  for (uint32_t i = 0; i < set->count; i++) {
+    if (xt_value_equals(set->values[i], value)) return (int32_t)i;
+  }
+  return -1;
+}
+
+static void xt_weak_set_add(xt_weak_set *set, xt_value value) {
+  if (xt_weak_set_index(set, value) >= 0) return;
+  if (set->count >= set->capacity) {
+    uint32_t capacity = set->capacity == 0 ? 8 : set->capacity * 2;
+    set->values = (xt_value *)realloc(set->values, sizeof(xt_value) * capacity);
+    if (!set->values) abort();
+    set->capacity = capacity;
+  }
+  set->values[set->count++] = value;
+}
+
+static int xt_weak_set_delete(xt_weak_set *set, xt_value value) {
+  int32_t index = xt_weak_set_index(set, value);
+  if (index < 0) return 0;
+  for (uint32_t i = (uint32_t)index + 1; i < set->count; i++) {
+    set->values[i - 1] = set->values[i];
+  }
+  set->count--;
+  return 1;
+}
+
+xt_value xt_weak_set_ctor(int32_t argc, xt_value *argv) {
+  xt_weak_set *set = (xt_weak_set *)xt_alloc(sizeof(xt_weak_set), XT_OBJECT_KIND_WEAK_SET);
+  set->values = NULL;
+  set->count = 0;
+  set->capacity = 0;
+  xt_value iterable = xt_arg_at(argc, argv, 0);
+  if (XT_IS_ARRAY(iterable)) {
+    xt_array *array = (xt_array *)XT_GET_PTR(iterable);
+    for (uint32_t i = 0; i < array->length; i++) {
+      if (!xt_is_weak_target(array->items[i])) {
+        xt_weak_key_error();
+        return XT_UNDEFINED;
+      }
+      xt_weak_set_add(set, array->items[i]);
+    }
+  }
+  return XT_FROM_PTR(XT_TAG_OBJECT, set);
+}
+
+/* -- WeakRef -------------------------------------------------------------- */
+
+xt_value xt_weak_ref_ctor(int32_t argc, xt_value *argv) {
+  xt_value target = xt_arg_at(argc, argv, 0);
+  if (!xt_is_weak_target(target)) {
+    xt_throw(xt_error_from_message("TypeError: WeakRef target must be an object"));
+    return XT_UNDEFINED;
+  }
+  xt_weak_ref *ref = (xt_weak_ref *)xt_alloc(sizeof(xt_weak_ref), XT_OBJECT_KIND_WEAK_REF);
+  ref->target = target;
+  return XT_FROM_PTR(XT_TAG_OBJECT, ref);
+}
+
+xt_value xt_weak_method(xt_value target, const char *method, int32_t argc, xt_value *argv,
+                        int *handled) {
+  *handled = 1;
+  if (xt_is_weak_map(target)) {
+    xt_weak_map *map = (xt_weak_map *)XT_GET_PTR(target);
+    xt_value key = xt_arg_at(argc, argv, 0);
+    if (strcmp(method, "set") == 0) {
+      if (!xt_is_weak_target(key)) {
+        xt_weak_key_error();
+        return XT_UNDEFINED;
+      }
+      xt_weak_map_set(map, key, xt_arg_at(argc, argv, 1));
+      return target;
+    }
+    if (strcmp(method, "get") == 0) {
+      if (!xt_is_weak_target(key)) return XT_UNDEFINED;
+      int32_t index = xt_weak_map_index(map, key);
+      return index >= 0 ? map->values[index] : XT_UNDEFINED;
+    }
+    if (strcmp(method, "has") == 0) {
+      return xt_bool(xt_is_weak_target(key) && xt_weak_map_index(map, key) >= 0);
+    }
+    if (strcmp(method, "delete") == 0) {
+      return xt_bool(xt_is_weak_target(key) && xt_weak_map_delete(map, key));
+    }
+  } else if (xt_is_weak_set(target)) {
+    xt_weak_set *set = (xt_weak_set *)XT_GET_PTR(target);
+    xt_value value = xt_arg_at(argc, argv, 0);
+    if (strcmp(method, "add") == 0) {
+      if (!xt_is_weak_target(value)) {
+        xt_weak_key_error();
+        return XT_UNDEFINED;
+      }
+      xt_weak_set_add(set, value);
+      return target;
+    }
+    if (strcmp(method, "has") == 0) {
+      return xt_bool(xt_is_weak_target(value) && xt_weak_set_index(set, value) >= 0);
+    }
+    if (strcmp(method, "delete") == 0) {
+      return xt_bool(xt_is_weak_target(value) && xt_weak_set_delete(set, value));
+    }
+  } else if (xt_is_weak_ref(target)) {
+    if (strcmp(method, "deref") == 0) return ((xt_weak_ref *)XT_GET_PTR(target))->target;
+  }
+  *handled = 0;
+  return XT_UNDEFINED;
+}
+
+/* -- collector integration ------------------------------------------------ */
+
+static int xt_weak_heap_value(xt_value value) {
+  return XT_IS_STRING(value) || XT_IS_OBJECT(value) || XT_IS_ARRAY(value) ||
+         XT_IS_FUNCTION(value) || XT_IS_BIGINT(value);
+}
+
+int xt_weak_gc_process_once(void) {
+  int changed = 0;
+  for (xt_header *header = xt_gc_heap_head(); header; header = header->gc_next) {
+    if ((header->flags & XT_GC_MARK) == 0) continue;
+    if (header->kind != XT_OBJECT_KIND_WEAK_MAP) continue;
+    xt_weak_map *map = (xt_weak_map *)header;
+    for (uint32_t i = 0; i < map->count; i++) {
+      if (!xt_gc_value_is_marked(map->keys[i])) continue;
+      xt_value value = map->values[i];
+      if (!xt_weak_heap_value(value)) continue;
+      if (xt_gc_value_is_marked(value)) continue;
+      xt_gc_mark_value(value);
+      changed = 1;
+    }
+  }
+  return changed;
+}
+
+void xt_weak_gc_clear(void) {
+  for (xt_header *header = xt_gc_heap_head(); header; header = header->gc_next) {
+    if ((header->flags & XT_GC_MARK) == 0) continue;
+    if (header->kind != XT_OBJECT_KIND_WEAK_REF) continue;
+    xt_weak_ref *ref = (xt_weak_ref *)header;
+    if (!xt_gc_value_is_marked(ref->target)) ref->target = XT_UNDEFINED;
+  }
+}
+
+void xt_weak_gc_compact(void) {
+  for (xt_header *header = xt_gc_heap_head(); header; header = header->gc_next) {
+    if ((header->flags & XT_GC_MARK) == 0) continue;
+    if (header->kind == XT_OBJECT_KIND_WEAK_MAP) {
+      xt_weak_map *map = (xt_weak_map *)header;
+      uint32_t write = 0;
+      for (uint32_t read = 0; read < map->count; read++) {
+        if (!xt_gc_value_is_marked(map->keys[read])) continue;
+        map->keys[write] = map->keys[read];
+        map->values[write] = map->values[read];
+        write++;
+      }
+      map->count = write;
+    } else if (header->kind == XT_OBJECT_KIND_WEAK_SET) {
+      xt_weak_set *set = (xt_weak_set *)header;
+      uint32_t write = 0;
+      for (uint32_t read = 0; read < set->count; read++) {
+        if (!xt_gc_value_is_marked(set->values[read])) continue;
+        set->values[write++] = set->values[read];
+      }
+      set->count = write;
+    }
+  }
+}

package/scripts/build-gui.ts

@@ -20,24 +20,28 @@
  *      `gui.lib` on Windows, built from MSVC-compatible COFF objects).
  *
  * Environment:
- *   xbintsc_CXX    C++ compiler override (default: clang++/c++/g++)
+ *   xbintsc_CXX    C++ compiler override (default: clang++ next to the resolved clang)
  *   xbintsc_CMAKE  CMake override (default: a vendored CMake, then `cmake`)
- *   xbintsc_AR     archiver override (default: llvm-ar, then ar)
+ *   xbintsc_AR     archiver override (default: llvm-ar next to clang, then llvm-ar)
  *   SDL3_TAG       SDL3 git tag to check out (default: release-3.2.10)
  *   FREETYPE_VERSION  FreeType version (default: 2.13.3)
  *   HARFBUZZ_VERSION  HarfBuzz version (default: 10.1.0)
  *
- * On Windows the engine is compiled with `clang++` against the MSVC ABI (run
- * from a Visual Studio developer prompt so `INCLUDE`/`LIB` are set) and merged
- * into a COFF `gui.lib` with `llvm-ar`.
+ * The C/C++ compiler is the same clang the driver resolves (see
+ * `src/driver/toolchain-provider.ts`), so the archive always matches the ABI of
+ * the runtime and emitted objects. On Windows that is an MSVC-targeting clang,
+ * normally the LLVM bundled with Visual Studio, and the result is a COFF
+ * `gui.lib`.
  */
 
-import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { platformSlug } from "../src/driver/paths.js";
+import { isMsvcTarget, probeClang, realRunner } from "../src/driver/toolchain.js";
+import { resolveToolchain } from "../src/driver/toolchain-provider.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const runtimeDir = join(root, "runtime");
@@ -81,18 +85,27 @@ const output = join(outDir, isWindows ? "gui.lib" : "gui.a");
  * `LNK2038: mismatch detected for 'RuntimeLibrary'`. The variable only takes
  * effect when policy CMP0091 is NEW, but FreeType and HarfBuzz declare
  * `cmake_minimum_required` below 3.15, which defaults the policy to OLD and
- * silently ignores it — hence `CMAKE_POLICY_DEFAULT_CMP0091`. The C/C++ compilers
- * are pinned to the same clang the engine is compiled with, so every object in
- * `gui.a` shares one ABI and optimization behaviour. */
-const cmakeGeneratorArgs: readonly string[] = isWindows
-  ? [
-      "-G", "Ninja",
-      "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded",
-      "-DCMAKE_POLICY_DEFAULT_CMP0091=NEW",
-      "-DCMAKE_C_COMPILER=clang",
-      "-DCMAKE_CXX_COMPILER=clang++",
-    ]
-  : [];
+ * silently ignores it — hence `CMAKE_POLICY_DEFAULT_CMP0091`.
+ *
+ * The tool paths are absolute and come from the same clang the driver resolves
+ * (on Windows, the LLVM bundled with Visual Studio when no newer one is on
+ * `PATH`), so every object merged into the archive shares one ABI and one
+ * optimization behaviour. Never leave these as bare `clang`/`clang++`: an older
+ * compiler earlier on `PATH` may be picked up at build time. */
+function cmakeToolchainArgs(): string[] {
+  const compilers = [
+    `-DCMAKE_C_COMPILER=${clang}`,
+    `-DCMAKE_CXX_COMPILER=${clangxx}`,
+  ];
+  if (!isWindows) return compilers;
+  return [
+    "-G", "Ninja",
+    "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded",
+    "-DCMAKE_POLICY_DEFAULT_CMP0091=NEW",
+    ...compilers,
+    `-DCMAKE_AR=${llvmAr}`,
+  ];
+}
 
 const SDL_TAG = process.env.SDL3_TAG || "release-3.2.10";
 const FREETYPE_VERSION = process.env.FREETYPE_VERSION || "2.13.3";
@@ -168,27 +181,103 @@ function findCmake(): string {
   return cmake;
 }
 
-function findCxx(): string {
-  const cxx = firstAvailable([process.env.xbintsc_CXX, "clang++", "c++", "g++"]);
-  if (!cxx) fail("no C++ compiler found; install clang++ or set xbintsc_CXX");
-  return cxx;
+/** The tool that sits next to `clang` in the same LLVM installation. */
+function siblingTool(clangPath: string, name: string): string | undefined {
+  if (!clangPath.includes("/") && !clangPath.includes("\\")) return undefined;
+  const candidate = join(dirname(clangPath), `${name}${isWindows ? ".exe" : ""}`);
+  return existsSync(candidate) ? candidate : undefined;
 }
 
-function findCc(): string {
-  const cc = firstAvailable([process.env.xbintsc_CC, process.env.CC, "clang", "cc", "gcc"]);
-  if (!cc) fail("no C compiler found; install clang or set xbintsc_CC");
-  return cc;
+/** Resolve `clang++` from the same LLVM as the driver's clang. */
+function findClangxx(clangPath: string): string {
+  const override = process.env.xbintsc_CXX;
+  if (override) {
+    const probe = probeClang(realRunner, override);
+    if (!probe.responds) fail(`xbintsc_CXX ${override} does not respond to --version`);
+    if (isWindows && (probe.version === undefined || (probe.target !== undefined && !isMsvcTarget(probe.target)))) {
+      fail(
+        `xbintsc_CXX ${override} is not an MSVC-targeting clang++ ` +
+          `(target ${probe.target ?? "unknown"}); the Windows GUI build requires one, for example ` +
+          "x86_64-pc-windows-msvc.",
+      );
+    }
+    return override;
+  }
+  const sibling = siblingTool(clangPath, "clang++");
+  if (sibling) return sibling;
+  const onPath = firstAvailable(["clang++"]);
+  if (onPath) return onPath;
+  fail("no clang++ found next to the resolved clang or on PATH; install LLVM or set xbintsc_CXX");
+}
+
+/** Resolve the archiver that matches the compiler, preferring LLVM's own. */
+function findArchiver(clangPath: string): string {
+  const sibling = siblingTool(clangPath, "llvm-ar");
+  const archiver = firstAvailable([process.env.xbintsc_AR, sibling, "llvm-ar", isWindows ? undefined : "ar"]);
+  if (!archiver) fail("no archiver found; install llvm-ar or set xbintsc_AR");
+  return archiver;
 }
 
-function findArchiver(): string {
-  const ar = firstAvailable([process.env.xbintsc_AR, "llvm-ar", "ar"]);
-  if (!ar) fail("no archiver found; set xbintsc_AR to llvm-ar or ar");
-  return ar;
+/* One toolchain for the whole archive: the same clang the driver uses, its
+ * sibling clang++, and the matching llvm-ar. No `gcc`/`g++` fallbacks, and
+ * Windows never falls back to a non-LLVM archiver — mixing another C++ runtime
+ * or object format would break the final link. */
+function driverClang(): string {
+  try {
+    return resolveToolchain().clang;
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+const clang = driverClang();
+const clangxx = findClangxx(clang);
+const llvmAr = findArchiver(clang);
+
+
+/** The compiler a previous CMake configure recorded for `buildDir`. */
+function cachedCompiler(buildDir: string, variable: string): string | undefined {
+  const cache = join(buildDir, "CMakeCache.txt");
+  if (!existsSync(cache)) return undefined;
+  const match = new RegExp(`^${variable}:[^=]*=(.*)$`, "m").exec(readFileSync(cache, "utf8"));
+  return match?.[1]?.trim();
+}
+
+function sameToolPath(a: string, b: string): boolean {
+  const normalize = (value: string): string => value.replace(/\\/g, "/").replace(/\/+$/, "");
+  return process.platform === "win32"
+    ? normalize(a).toLowerCase() === normalize(b).toLowerCase()
+    : normalize(a) === normalize(b);
+}
+
+/**
+ * Configure a vendored CMake project, discarding a build tree whose cached
+ * compiler no longer matches the resolved toolchain. CMake refuses to switch
+ * compilers in place, and a tree configured by another clang would mix ABIs in
+ * the final archive.
+ */
+function configureCmake(
+  name: string,
+  source: string,
+  build: string,
+  extraArgs: readonly string[],
+): string {
+  const cachedC = cachedCompiler(build, "CMAKE_C_COMPILER");
+  const cachedCxx = cachedCompiler(build, "CMAKE_CXX_COMPILER");
+  const stale =
+    (cachedC !== undefined && !sameToolPath(cachedC, clang)) ||
+    (cachedCxx !== undefined && !sameToolPath(cachedCxx, clangxx));
+  if (stale) {
+    console.log(`xbintsc: toolchain changed; reconfiguring ${name}`);
+    rmSync(build, { recursive: true, force: true });
+  }
+  const cmake = findCmake();
+  run(cmake, ["-S", source, "-B", build, ...cmakeToolchainArgs(), ...extraArgs]);
+  return cmake;
 }
 
 /** Directories a CMake `find_path` would search, relative to the filesystem
- * root, used to check that a development package is installed. */
-const HEADER_PREFIXES = ["/usr/include", "/usr/local/include", "/opt/homebrew/include"];
+ * root, used to check that a development package is installed. */const HEADER_PREFIXES = ["/usr/include", "/usr/local/include", "/opt/homebrew/include"];
 
 /** True on Debian and its derivatives, where the message below can name the
  * packages to install. Anywhere else the headers may well live under a prefix
@@ -300,19 +389,14 @@ if (!existingSdlArchive) {
   requireHeaders("SDL3's Wayland video driver", ["wayland-client-core.h"],
     "libwayland-dev libxkbcommon-dev libdecor-0-dev");
 
-  const cmake = findCmake();
-  console.log(`xbintsc: building static SDL3 with ${cmake}`);
-  const configureArgs = [
-    "-S", sdlSrc,
-    "-B", sdlBuild,
-    ...cmakeGeneratorArgs,
+  const cmake = configureCmake("SDL3", sdlSrc, sdlBuild, [
     "-DCMAKE_BUILD_TYPE=Release",
     "-DSDL_SHARED=OFF",
     "-DSDL_STATIC=ON",
     "-DSDL_TESTS=OFF",
     "-DSDL_EXAMPLES=OFF",
-  ];
-  run(cmake, configureArgs);
+  ]);
+  console.log(`xbintsc: building static SDL3 with ${cmake}`);
   run(cmake, ["--build", sdlBuild, "--config", "Release", "--target", "SDL3-static", "--parallel"]);
 } else {
   console.log(`xbintsc: reusing existing ${existingSdlArchive}`);
@@ -345,12 +429,7 @@ ensureTarballSource("freetype", FREETYPE_URL, `freetype-${FREETYPE_VERSION}`);
 ensureTarballSource("harfbuzz", HARFBUZZ_URL, `harfbuzz-${HARFBUZZ_VERSION}`);
 
 if (!existsSync(freetypeArchive() ?? "")) {
-  const cmake = findCmake();
-  console.log("xbintsc: building static FreeType");
-  run(cmake, [
-    "-S", freetypeSrc,
-    "-B", freetypeBuild,
-    ...cmakeGeneratorArgs,
+  const cmake = configureCmake("FreeType", freetypeSrc, freetypeBuild, [
     "-DCMAKE_BUILD_TYPE=Release",
     "-DBUILD_SHARED_LIBS=OFF",
     /* We only need TrueType/OpenType outlines; skip the optional codecs. */
@@ -360,18 +439,14 @@ if (!existsSync(freetypeArchive() ?? "")) {
     "-DFT_DISABLE_HARFBUZZ=TRUE",
     "-DFT_DISABLE_BROTLI=TRUE",
   ]);
+  console.log("xbintsc: building static FreeType");
   run(cmake, ["--build", freetypeBuild, "--config", "Release", "--parallel"]);
 } else {
   console.log(`xbintsc: reusing existing ${freetypeArchive()}`);
 }
 
 if (!existsSync(harfbuzzArchive() ?? "")) {
-  const cmake = findCmake();
-  console.log("xbintsc: building static HarfBuzz");
-  run(cmake, [
-    "-S", harfbuzzSrc,
-    "-B", harfbuzzBuild,
-    ...cmakeGeneratorArgs,
+  const cmake = configureCmake("HarfBuzz", harfbuzzSrc, harfbuzzBuild, [
     "-DCMAKE_BUILD_TYPE=Release",
     "-DBUILD_SHARED_LIBS=OFF",
     "-DHB_BUILD_UTILS=OFF",
@@ -382,6 +457,7 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
     "-DHB_HAVE_ICU=OFF",
     "-DHB_HAVE_GRAPHITE2=OFF",
   ]);
+  console.log("xbintsc: building static HarfBuzz");
   run(cmake, ["--build", harfbuzzBuild, "--config", "Release", "--parallel"]);
 } else {
   console.log(`xbintsc: reusing existing ${harfbuzzArchive()}`);
@@ -398,9 +474,7 @@ if (isWindows) {
   ensureTarballSource("ffmpeg", FFMPEG_URL, `ffmpeg-${FFMPEG_VERSION}`, "configure");
   ffmpegLibraries = ffmpegStaticLibraries();
   if (!ffmpegLibraries) {
-    const cc = findCc();
-    const ccxx = findCxx();
-    console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with ${cc}`);
+    console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with ${clang}`);
     mkdirSync(ffmpegBuild, { recursive: true });
     run(join(ffmpegSrc, "configure"), [
       `--prefix=${ffmpegInstall}`,
@@ -411,8 +485,8 @@ if (isWindows) {
       "--disable-everything",
       "--enable-avformat", "--enable-avcodec", "--enable-avutil", "--enable-swscale", "--enable-swresample",
       "--disable-network", "--disable-autodetect", "--disable-x86asm", "--disable-debug", "--enable-pic",
-      `--cc=${cc}`,
-      `--cxx=${ccxx}`,
+      `--cc=${clang}`,
+      `--cxx=${clangxx}`,
       ...FFMPEG_COMPONENTS,
     ], { cwd: ffmpegBuild });
     run("make", ["-j", String(availableParallelism())], { cwd: ffmpegBuild });
@@ -426,7 +500,6 @@ if (isWindows) {
 
 /* -- 3. engine objects ---------------------------------------------------- */
 
-const cxx = findCxx();
 mkdirSync(objDir, { recursive: true });
 const includeFlags = [
   "-I", runtimeDir,
@@ -454,7 +527,7 @@ if (!isWindows) cxxFlags.splice(3, 0, "-fPIC");
 for (const source of sources) {
   const object = join(objDir, source.replace(/\.cpp$/, objectSuffix));
   console.log(`xbintsc: compiling ${source}`);
-  run(cxx, [...cxxFlags, "-c", join(engineDir, source), "-o", object]);
+  run(clangxx, [...cxxFlags, "-c", join(engineDir, source), "-o", object]);
   objects.push(object);
 }
 
@@ -480,7 +553,7 @@ if (process.platform === "darwin") {
   /* `ar -M` (GNU/LLVM) merges archives through an MRI script. Windows paths are
    * normalised to `/` so the MRI parser does not read `\` as an escape. */
   const mri = (path: string): string => path.replace(/\\/g, "/");
-  const ar = findArchiver();
+  const ar = llvmAr;
   const script = [
     `create ${mri(output)}`,
     ...objects.map((object) => `addmod ${mri(object)}`),

package/scripts/check-version.ts

@@ -15,9 +15,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** Read the version literal from the compiler source. */
 export function compilerVersionOf(root: string): string {
-  const text = readFileSync(join(root, "src", "driver", "compiler.ts"), "utf8");
+  const text = readFileSync(join(root, "src", "driver", "version.ts"), "utf8");
   const match = /export const COMPILER_VERSION = "([^"]+)"/.exec(text);
-  if (!match) throw new Error("COMPILER_VERSION is not declared in src/driver/compiler.ts");
+  if (!match) throw new Error("COMPILER_VERSION is not declared in src/driver/version.ts");
   return match[1]!;
 }
 
@@ -35,7 +35,7 @@ export function checkCompilerVersion(root: string): string | undefined {
   if (packageVersion === compilerVersion) return undefined;
   return (
     `COMPILER_VERSION is "${compilerVersion}" but package.json is "${packageVersion}".\n` +
-    'Update COMPILER_VERSION in src/driver/compiler.ts (it keys the incremental cache), or fix package.json.'
+    'Update COMPILER_VERSION in src/driver/version.ts (it keys the incremental cache), or fix package.json.'
   );
 }
 

package/src/binder/declarations.ts

@@ -98,9 +98,15 @@ export const declarationMethods: DeclarationMethods = {
         case SyntaxKind.FunctionDeclaration:
           this.declare((statement as FunctionDeclaration).name?.text ?? "(anonymous)", SymbolKind.Function, statement, scope, true);
           break;
-        case SyntaxKind.ClassDeclaration:
-          this.declare((statement as { name: Identifier }).name.text, SymbolKind.Class, statement, scope, false);
+        case SyntaxKind.ClassDeclaration: {
+          /* `export default class {}` has no binding name; the bundler maps the
+           * default export, so there is nothing to pre-declare. */
+          const className = (statement as { name?: Identifier }).name?.text;
+          if (className !== undefined) {
+            this.declare(className, SymbolKind.Class, statement, scope, false);
+          }
           break;
+        }
         case SyntaxKind.InterfaceDeclaration:
           this.declare((statement as { name: Identifier }).name.text, SymbolKind.Interface, statement, scope, false);
           break;
@@ -191,7 +197,12 @@ export const declarationMethods: DeclarationMethods = {
         statement.kind === SyntaxKind.FunctionDeclaration ||
         statement.kind === SyntaxKind.ClassDeclaration
       ) {
-        const name = (statement as { name: Identifier }).name.text;
+        const name = (statement as { name?: Identifier }).name?.text;
+        if (name === undefined) {
+          /* `export default function () {}` / `export default class {}` have no
+           * binding name; the default export is handled by the bundler. */
+          continue;
+        }
         if (!fn.scope.symbols.has(name)) {
           this.declare(name, statement.kind === SyntaxKind.FunctionDeclaration ? SymbolKind.Function : SymbolKind.Class, statement, fn.scope, statement.kind === SyntaxKind.FunctionDeclaration);
         }

package/src/cli/hints.ts

@@ -122,6 +122,7 @@ export function documentationFor(diagnostic: Diagnostic): DocumentationPointer |
     case DiagnosticCode.InvalidAssignmentTarget:
     case DiagnosticCode.DuplicateDefault:
     case DiagnosticCode.InvalidTypeSyntax:
+    case DiagnosticCode.NestingTooDeep:
     case DiagnosticCode.DuplicateIdentifier:
     case DiagnosticCode.CannotFindName:
     case DiagnosticCode.IllegalRedeclaration:
@@ -136,7 +137,7 @@ export function documentationFor(diagnostic: Diagnostic): DocumentationPointer |
 
     case DiagnosticCode.ModuleNotFound:
       return {
-        text: "Node modules need the `node` extension (`--ext node`); third-party npm packages are not supported",
+        text: "Node built-ins need the `node` extension (`--ext node`); a package in `node_modules` is bundled at build time — check its name and exports map",
         path: DOC_EXTENSIONS,
       };
 
@@ -155,6 +156,12 @@ export function documentationFor(diagnostic: Diagnostic): DocumentationPointer |
         path: DOC_CLI,
       };
 
+    case DiagnosticCode.CircularDependency:
+      return {
+        text: "xbintsc does not support circular imports; move the shared binding into a third module",
+        path: "doc/unimplemented/modules.md",
+      };
+
     // The checker codes are defined but never emitted today.
     case DiagnosticCode.TypeMismatch:
     case DiagnosticCode.NotCallable: