xbintsc 0.3.87 → 0.5.20

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:

package/src/cli/main.ts

@@ -30,7 +30,6 @@ import {
   thrownFailure,
   toolchainPointer,
   UNEXPECTED_FAILURE_HINT,
-  type DocumentationPointer,
 } from "./hints.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
 import { bundledExtensions } from "../extensions/catalog.js";
@@ -44,6 +43,10 @@ import {
   type AppConfig,
   type ProjectConfig,
 } from "../driver/config.js";
+import { fingerprintTree, startWatching } from "./watch.js";
+
+/** Sentinel: watch mode keeps the process alive instead of exiting. */
+const KEEP_RUNNING = -1;
 
 export interface CliIo {
   readonly stdout: (text: string) => void;
@@ -80,6 +83,8 @@ const VALUE_FLAGS = new Set([
   "icon",
   "app-id",
   "app-name",
+  "pgo-generate",
+  "pgo-use",
 ]);
 
 function parseArgs(argv: readonly string[]): ParsedArgs {
@@ -200,22 +205,29 @@ function emitHint(io: CliIo, line: string): void {
  * the question.
  */
 function reportThrown(error: unknown, io: CliIo): number {
-  const message =
-    error instanceof ToolchainError
-      ? `xbintsc: ${error.message}`
-      : `xbintsc: ${error instanceof Error ? error.message : String(error)}`;
-  io.stderr(`${message.trimEnd()}\n`);
-  const text = error instanceof ToolchainError ? error.message : message;
-  const pointer = error instanceof ToolchainError ? toolchainPointer(text) : thrownPointer(text);
-  emitHint(io, `hint: ${pointer.text} — see ${pointer.path}`);
+  if (error instanceof ToolchainError) {
+    io.stderr(`xbintsc: ${error.message.trimEnd()}\n`);
+    const pointer = toolchainPointer(error.message);
+    emitHint(io, `hint: ${pointer.text} — see ${pointer.path}`);
+    return 1;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const failure = thrownFailure(message);
+  if (failure === undefined) {
+    /* An uncaught exception that is not a known toolchain/setup failure is a
+     * compiler bug: say so instead of blaming the user's source or toolchain. */
+    io.stderr(`xbintsc: internal error: ${message.trimEnd()}\n`);
+    emitHint(
+      io,
+      `hint: this is a bug in xbintsc, not in your program — please report it with the input that triggered it — see ${UNEXPECTED_FAILURE_HINT.path}`,
+    );
+    return 1;
+  }
+  io.stderr(`xbintsc: ${message.trimEnd()}\n`);
+  emitHint(io, `hint: ${failure.pointer.text} — see ${failure.pointer.path}`);
   return 1;
 }
 
-/** The document that explains a failure the CLI reports as a plain message. */
-function thrownPointer(message: string): DocumentationPointer {
-  return thrownFailure(message)?.pointer ?? UNEXPECTED_FAILURE_HINT;
-}
-
 /** Report a project-config failure, which never becomes a diagnostic bag. */
 function reportConfigError(error: string, io: CliIo): number {
   io.stderr(`xbintsc: ${error}\n`);
@@ -231,6 +243,8 @@ const HELP = `xbintsc ${COMPILER_VERSION} - TypeScript binary compiler
 Usage:
   xbintsc build <file.ts> [options]   Compile to a native binary
   xbintsc run <file.ts> [-- args]     Compile and execute
+  xbintsc check <file.ts>             Parse and bind without linking
+  xbintsc watch <file.ts> [options]   Rebuild whenever the source tree changes
   xbintsc emit <file.ts>              Print LLVM IR
   xbintsc doctor                      Report the resolved toolchain
   xbintsc version                     Print the version
@@ -255,11 +269,15 @@ Options:
       --verbose         Print progress information
       --time            Print per-phase build timings
       --debug           Emit debug info (DWARF/CodeView) and keep frame pointers
+      --lto             Compile program and runtime to LTO bitcode; link with lld
+      --pgo-generate [dir]  Build an instrumented binary writing profiles to dir
+      --pgo-use [dir]   Build with the profiles collected from --pgo-generate
+      --json            Print diagnostics as a JSON array on stdout
       --no-hints        Do not append the "hint: … see <doc>" line to failures
 
 xbintsc compiles a subset of TypeScript to a native binary. Types are erased
-(never checked), Node modules need --ext node, third-party npm imports are not
-supported, and clang 16+ is required to link.
+(never checked), Node built-ins need --ext node, packages in node_modules are
+bundled at build time, and clang 16+ is required to link.
 
 Docs: doc/ai/README.md (task guide) - doc/ai/language-support.md (subset) -
 doc/ai/troubleshooting.md (failures) - llms.txt (index of every document)
@@ -323,7 +341,7 @@ function doctor(io: CliIo): number {
   try {
     if (!toolchain) throw new Error("no toolchain");
     const resource = resolveResourceCompiler(realRunner, toolchain.clang);
-    io.stdout(`icon res   : ${resource ? `${resource.tool} (${resource.kind})` : "none (.exe icon disabled)"}\n`);
+    io.stdout(`icon res   : ${resource ? resource.tool : "none (.exe icon disabled)"}\n`);
   } catch {
     io.stdout("icon res   : unknown\n");
   }
@@ -414,6 +432,57 @@ function dispatch(argv: readonly string[], io: CliIo): number {
     return 0;
   }
 
+  if (command === "check") {
+    const cliEntry = args.positionals[0];
+    const resolved = resolveProjectConfig(args.flags, cliEntry);
+    if (!resolved.ok) return reportConfigError(resolved.error, io);
+    const entry = cliEntry ?? resolved.config.entry;
+    if (!entry) {
+      io.stderr(`xbintsc: check requires a source file (or 'entry' in ${CONFIG_FILE_NAME})\n`);
+      emitHint(io, `hint: pass the entry file, or set 'entry' in ${CONFIG_FILE_NAME} — see ${DOC_CLI}`);
+      return 1;
+    }
+    const extNames = listFlag(args.flags, "ext") ?? resolved.config.extensions ?? [];
+    const nativeManifests = listFlag(args.flags, "ext-native") ?? resolved.config.extNative ?? [];
+    const registry = buildRegistry(extNames, nativeManifests);
+    /* Front-end only: parse, bundle and lower far enough to report binder /
+     * unsupported-feature diagnostics, but never invoke clang or write output. */
+    const { diagnostics } = compileEntry(entry, registry);
+    const failed = diagnostics.some((diagnostic) => diagnostic.category === "error");
+    if (args.flags.has("json")) {
+      io.stdout(`${JSON.stringify(diagnostics)}\n`);
+    } else if (failed) {
+      printDiagnostics(diagnostics, entry, io);
+    }
+    return failed ? 1 : 0;
+  }
+
+  if (command === "watch") {
+    const cliEntry = args.positionals[0];
+    const resolved = resolveProjectConfig(args.flags, cliEntry);
+    if (!resolved.ok) return reportConfigError(resolved.error, io);
+    const entry = cliEntry ?? resolved.config.entry;
+    if (!entry) {
+      io.stderr(`xbintsc: watch requires a source file (or 'entry' in ${CONFIG_FILE_NAME})\n`);
+      emitHint(io, `hint: pass the entry file, or set 'entry' in ${CONFIG_FILE_NAME} — see ${DOC_CLI}`);
+      return 1;
+    }
+    /* Re-enter the normal build path with the same flags, exactly as if the
+     * user had typed `build`; the config is re-read on every rebuild too. */
+    const forwarded = ["build", ...argv.slice(1)];
+    run(forwarded, io);
+    const root = dirname(resolve(entry));
+    startWatching({
+      scan: () => fingerprintTree(root),
+      onRebuild: () => {
+        io.stdout("\n");
+        run(forwarded, io);
+      },
+    });
+    io.stdout(`xbintsc: watching ${root} for changes (Ctrl+C to stop)\n`);
+    return KEEP_RUNNING;
+  }
+
   if (command === "emit") {
     const cliEntry = args.positionals[0];
     const resolved = resolveProjectConfig(args.flags, cliEntry);
@@ -429,6 +498,10 @@ function dispatch(argv: readonly string[], io: CliIo): number {
     const registry = buildRegistry(extNames, nativeManifests);
     const { ir, diagnostics } = compileEntry(entry, registry, { debug: Boolean(args.flags.get("debug")) });
     if (diagnostics.some((d) => d.category === "error")) {
+      if (args.flags.has("json")) {
+        io.stdout(`${JSON.stringify(diagnostics)}\n`);
+        return 1;
+      }
       printDiagnostics(diagnostics, entry, io);
       return 1;
     }
@@ -452,6 +525,24 @@ function dispatch(argv: readonly string[], io: CliIo): number {
     const extNames = listFlag(args.flags, "ext") ?? config.extensions ?? [];
     const nativeManifests = listFlag(args.flags, "ext-native") ?? config.extNative ?? [];
     const registry = buildRegistry(extNames, nativeManifests);
+    const pgoGenerate = args.flags.get("pgo-generate");
+    const pgoUse = args.flags.get("pgo-use");
+    if (pgoGenerate !== undefined && pgoUse !== undefined) {
+      io.stderr("xbintsc: --pgo-generate and --pgo-use are mutually exclusive\n");
+      return 1;
+    }
+    const pgo =
+      pgoGenerate !== undefined
+        ? ("generate" as const)
+        : pgoUse !== undefined
+          ? ("use" as const)
+          : config.pgo;
+    const pgoDir =
+      typeof pgoGenerate === "string"
+        ? pgoGenerate
+        : typeof pgoUse === "string"
+          ? pgoUse
+          : config.pgoDir;
 
     const result = build(entry, {
       output: typeof args.flags.get("output") === "string" ? (args.flags.get("output") as string) : config.output,
@@ -463,9 +554,16 @@ function dispatch(argv: readonly string[], io: CliIo): number {
       extensions: registry,
       app: mergeAppConfig(args.flags, config),
       debug: Boolean(args.flags.get("debug")),
+      lto: Boolean(args.flags.get("lto")) || config.lto === true,
+      ...(pgo ? { pgo } : {}),
+      ...(pgoDir ? { pgoDir } : {}),
     });
 
     if (result.diagnostics.some((d) => d.category === "error")) {
+      if (args.flags.has("json")) {
+        io.stdout(`${JSON.stringify(result.diagnostics)}\n`);
+        return 1;
+      }
       printDiagnostics(result.diagnostics, entry, io);
       return 1;
     }
@@ -493,5 +591,8 @@ function dispatch(argv: readonly string[], io: CliIo): number {
 const isMain =
   process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isMain) {
-  process.exit(run(process.argv.slice(2)));
+  const status = run(process.argv.slice(2));
+  /* Watch mode returns KEEP_RUNNING; the polling interval keeps the process
+   * alive, so calling process.exit here would stop it immediately. */
+  if (status !== KEEP_RUNNING) process.exit(status);
 }