xbintsc 0.3.11 → 0.3.13

package/scripts/coverage-runtime.ts

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+/**
+ * Runtime (C) coverage for xbintsc.
+ *
+ * Vitest's V8 provider only sees the compiler's TypeScript sources
+ * (the `src/` tree, see vitest.config.ts). The C runtime under `runtime/` is
+ * invisible to it, so this script drives the *other* coverage system: clang's
+ * source-based instrumentation.
+ *
+ * The lever is `CCC_OVERRIDE_OPTIONS`. Exporting
+ * `+-fprofile-instr-generate +-fcoverage-mapping` makes clang append those
+ * flags to every compile and link it performs. The driver forwards the ambient
+ * environment to clang, so no xbintsc option or source change is needed to
+ * instrument the runtime. Instrumented programs then write `.profraw` files
+ * named by `LLVM_PROFILE_FILE`, which `llvm-profdata` and `llvm-cov` turn
+ * into a per-source report.
+ *
+ * Two things make this work against the test suite:
+ *
+ *   - The e2e harness gives every suite its own temporary cache, so the
+ *     instrumented runtime objects are always compiled fresh (no stale,
+ *     un-instrumented object can be reused).
+ *   - `llvm-cov report` needs a binary that *contains* the coverage mapping,
+ *     but the harness deletes each compiled program when its suite ends. A
+ *     single reference binary, built from the same runtime sources with the
+ *     same clang and flags, carries the mapping for every runtime file, so the
+ *     merged profile can be reported against it.
+ *
+ * Usage:
+ *   npm run coverage:runtime                    instrument, run the tests, report
+ *   npm run coverage:runtime -- --report-only   report profiles from an earlier run
+ *   npm run coverage:runtime -- tests/e2e       forward args to `vitest run`
+ *
+ * Options:
+ *   --report-only        Skip the test run; merge whatever profiles already exist.
+ *   --prof-dir <dir>     Where compiled programs write .profraw (default build/runtime-prof).
+ *   --out-dir <dir>      Where the report is written (default coverage/runtime).
+ *   --threshold <pct>    Fail when total runtime line coverage is below <pct>.
+ *   --html               Also write an HTML report under <out-dir>/html.
+ *   --keep-raw           Keep the .profraw files after merging.
+ *   --strict             Fail (instead of skipping) when the LLVM tools are missing.
+ *   -h, --help           Show this help.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync, type SpawnSyncOptions } from "node:child_process";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "../src/driver/compiler.js";
+import { createDefaultRegistry } from "../src/extensions/registry.js";
+import { nodeExtension } from "../src/extensions/node/index.js";
+import { findRuntimeDir } from "../src/driver/paths.js";
+import { resolveToolchain } from "../src/driver/toolchain-provider.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Flags clang appends to every compile/link in an instrumented build. */
+const INSTRUMENT = "+-fprofile-instr-generate +-fcoverage-mapping";
+
+interface Options {
+  reportOnly: boolean;
+  profDir: string;
+  outDir: string;
+  threshold?: number;
+  html: boolean;
+  keepRaw: boolean;
+  strict: boolean;
+  testArgs: string[];
+}
+
+interface CommandResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+function fail(message: string): never {
+  console.error(`coverage-runtime: ${message}`);
+  process.exit(1);
+}
+
+function skip(message: string, strict: boolean): never {
+  if (strict) fail(message);
+  console.warn(`coverage-runtime: skipping - ${message}`);
+  process.exit(0);
+}
+
+function usage(): void {
+  process.stdout.write(
+    [
+      "Usage: npm run coverage:runtime [-- options] [-- vitest args]",
+      "",
+      "  --report-only      merge profiles from an earlier instrumented run",
+      "  --prof-dir <dir>   .profraw output directory (default build/runtime-prof)",
+      "  --out-dir <dir>    report directory (default coverage/runtime)",
+      "  --threshold <pct>  fail below this total line coverage",
+      "  --html             also write an HTML report",
+      "  --keep-raw         keep .profraw files after merging",
+      "  --strict           fail when the LLVM tools are missing",
+      "",
+    ].join("\n"),
+  );
+}
+
+function parseArgs(argv: readonly string[]): Options {
+  const options: Options = {
+    reportOnly: false,
+    profDir: join(root, "build", "runtime-prof"),
+    outDir: join(root, "coverage", "runtime"),
+    html: false,
+    keepRaw: false,
+    strict: false,
+    testArgs: [],
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--report-only") options.reportOnly = true;
+    else if (arg === "--html") options.html = true;
+    else if (arg === "--keep-raw") options.keepRaw = true;
+    else if (arg === "--strict") options.strict = true;
+    else if (arg === "--prof-dir") options.profDir = resolve(requireValue(argv, (index += 1), arg));
+    else if (arg === "--out-dir") options.outDir = resolve(requireValue(argv, (index += 1), arg));
+    else if (arg === "--threshold") {
+      const value = requireValue(argv, (index += 1), arg);
+      const parsed = Number(value);
+      if (!Number.isFinite(parsed)) fail(`--threshold expects a number, got '${value}'`);
+      options.threshold = parsed;
+    } else if (arg === "-h" || arg === "--help") {
+      usage();
+      process.exit(0);
+    } else if (arg.startsWith("--")) {
+      fail(`unknown option '${arg}' (see --help)`);
+    } else {
+      options.testArgs.push(arg);
+    }
+  }
+  return options;
+}
+
+function requireValue(argv: readonly string[], index: number, flag: string): string {
+  const value = argv[index];
+  if (value === undefined) fail(`${flag} needs a value`);
+  return value;
+}
+
+function run(command: string, args: readonly string[], options: SpawnSyncOptions = {}): CommandResult {
+  const result = spawnSync(command, [...args], { encoding: "utf8", maxBuffer: 512 * 1024 * 1024, ...options });
+  return {
+    status: result.status ?? (result.error ? 1 : 0),
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? (result.error ? String(result.error.message) : ""),
+  };
+}
+
+/** True when `command` resolves and answers `--version` successfully. */
+function runs(command: string): boolean {
+  const result = spawnSync(command, ["--version"], { encoding: "utf8" });
+  return !result.error && result.status === 0;
+}
+
+/**
+ * Locate the LLVM tool `name` (`llvm-profdata`/`llvm-cov`) that matches the
+ * clang the driver resolved. The bundled toolchains ship the tools next to
+ * clang and cover the versioned system installs, so search there first: mixing
+ * versions makes `llvm-profdata` reject the profile format.
+ */
+function findTool(clang: string, name: string): string | undefined {
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const candidates: string[] = [];
+  const directory = dirname(clang);
+  if (directory !== "." && directory !== "") candidates.push(join(directory, name + exe));
+  const version = run(clang, ["--version"]);
+  const major = /version (\d+)/.exec(`${version.stdout}${version.stderr}`)?.[1];
+  if (major) candidates.push(`${name}-${major}`, `${name}-${major}${exe}`);
+  candidates.push(name + exe, name);
+  for (const version of ["18", "19", "20", "21", "22", "23"]) {
+    candidates.push(`${name}-${version}`, `${name}-${version}${exe}`);
+  }
+  for (const candidate of candidates) {
+    if (runs(candidate)) return candidate;
+  }
+  if (process.platform === "darwin") {
+    // The Command Line Tools expose the tools through `xcrun` rather than PATH.
+    const found = spawnSync("xcrun", ["--find", name], { encoding: "utf8" });
+    const path = (found.stdout ?? "").trim();
+    if (!found.error && found.status === 0 && path.length > 0 && runs(path)) return path;
+  }
+  return undefined;
+}
+
+function collectProfiles(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory)
+    .filter((name) => name.endsWith(".profraw"))
+    .sort()
+    .map((name) => join(directory, name));
+}
+
+/** Merge profiles, chunking the input so a huge list cannot overflow argv. */
+function mergeProfiles(tool: string, inputs: readonly string[], output: string, scratch: string): void {
+  const chunkSize = 128;
+  if (inputs.length <= chunkSize) {
+    const result = run(tool, ["merge", "-sparse", ...inputs, "-o", output]);
+    if (result.status !== 0) fail(`llvm-profdata merge failed:\n${result.stderr}`);
+    return;
+  }
+  const parts: string[] = [];
+  for (let index = 0; index < inputs.length; index += chunkSize) {
+    const part = join(scratch, `part-${parts.length}.profdata`);
+    const result = run(tool, ["merge", "-sparse", ...inputs.slice(index, index + chunkSize), "-o", part]);
+    if (result.status !== 0) fail(`llvm-profdata merge failed:\n${result.stderr}`);
+    parts.push(part);
+  }
+  const result = run(tool, ["merge", "-sparse", ...parts, "-o", output]);
+  if (result.status !== 0) fail(`llvm-profdata merge failed:\n${result.stderr}`);
+  for (const part of parts) rmSync(part, { force: true });
+}
+
+/**
+ * Build the binary whose embedded coverage mapping the merged profile is
+ * reported against. It must be instrumented with the same clang and flags as
+ * the test-produced binaries, and it carries the Node extension so that
+ * extension's C sources are covered too.
+ */
+function buildReference(directory: string): string {
+  mkdirSync(directory, { recursive: true });
+  const entry = join(directory, "reference.ts");
+  writeFileSync(entry, "console.log(1);\n");
+  const registry = createDefaultRegistry().register(nodeExtension);
+  const result = build(entry, {
+    emit: "exe",
+    outDir: directory,
+    cacheDir: join(directory, "cache"),
+    extensions: registry,
+    preferPrebuilt: false,
+    force: true,
+  });
+  const errors = result.diagnostics.filter((diagnostic) => diagnostic.category === "error");
+  if (errors.length > 0) fail(`reference build failed:\n${errors.map((e) => e.message).join("\n")}`);
+  return result.outputPath;
+}
+
+function runTests(options: Options): void {
+  const vitest = join(root, "node_modules", "vitest", "vitest.mjs");
+  if (!existsSync(vitest)) fail("vitest is not installed; run 'npm install' first");
+  rmSync(options.profDir, { recursive: true, force: true });
+  mkdirSync(options.profDir, { recursive: true });
+  console.log("coverage-runtime: running the test suite with instrumented clang");
+  const result = spawnSync(process.execPath, [vitest, "run", ...options.testArgs], {
+    stdio: "inherit",
+    cwd: root,
+    env: {
+      ...process.env,
+      LLVM_PROFILE_FILE: join(options.profDir, "%p-%m.profraw"),
+      xbintsc_CACHE_DIR: join(root, "build", "runtime-cov-cache"),
+      // A prebuilt runtime/lib archive is not instrumented, so force the driver
+      // to compile (and thus instrument) the C sources instead.
+      xbintsc_PREFER_PREBUILT: "0",
+    },
+  });
+  if (result.status !== 0) fail(`tests failed (exit ${result.status ?? "unknown"})`);
+}
+
+function main(): void {
+  const options = parseArgs(process.argv.slice(2));
+
+  // Set once, before anything shells out to clang, so both the test run and the
+  // reference build are instrumented even in --report-only mode.
+  const existing = process.env.CCC_OVERRIDE_OPTIONS;
+  process.env.CCC_OVERRIDE_OPTIONS = existing ? `${existing} ${INSTRUMENT}` : INSTRUMENT;
+
+  let clang: string;
+  try {
+    clang = resolveToolchain().clang;
+  } catch (error) {
+    skip(`no clang-compatible compiler available (${String(error)})`, options.strict);
+  }
+  const profdataTool = findTool(clang, "llvm-profdata");
+  const covTool = findTool(clang, "llvm-cov");
+  if (!profdataTool || !covTool) {
+    const missing = [
+      profdataTool ? undefined : "llvm-profdata",
+      covTool ? undefined : "llvm-cov",
+    ].filter(Boolean).join(", ");
+    skip(`${missing} not found for ${clang}; install LLVM or use the bundled toolchain`, options.strict);
+  }
+
+  if (!options.reportOnly) runTests(options);
+
+  const profiles = collectProfiles(options.profDir);
+  if (profiles.length === 0) {
+    skip(`no .profraw files in ${relative(root, options.profDir)} (did the tests run?)`, options.strict);
+  }
+  console.log(`coverage-runtime: merging ${profiles.length} profile(s)`);
+
+  mkdirSync(options.outDir, { recursive: true });
+  const referenceDir = join(root, "build", "runtime-coverage");
+  const reference = buildReference(referenceDir);
+  const profdata = join(options.outDir, "runtime.profdata");
+  mergeProfiles(profdataTool!, profiles, profdata, options.outDir);
+
+  const runtimeDir = findRuntimeDir();
+  const report = run(covTool!, ["report", reference, `--instr-profile=${profdata}`, runtimeDir]);
+  if (report.status !== 0) fail(`llvm-cov report failed:\n${report.stderr}`);
+  writeFileSync(join(options.outDir, "report.txt"), report.stdout);
+  process.stdout.write(report.stdout);
+
+  const summary = run(covTool!, ["export", reference, `--instr-profile=${profdata}`, "--summary-only"]);
+  if (summary.status !== 0) fail(`llvm-cov export failed:\n${summary.stderr}`);
+  const parsed = JSON.parse(summary.stdout) as {
+    data?: { totals?: { lines?: { percent?: number } } }[];
+  };
+  const percent = parsed.data?.[0]?.totals?.lines?.percent ?? 0;
+  console.log(`coverage-runtime: runtime line coverage ${percent.toFixed(2)}%`);
+  console.log(`coverage-runtime: report -> ${relative(root, join(options.outDir, "report.txt"))}`);
+
+  if (options.html) {
+    const htmlDir = join(options.outDir, "html");
+    rmSync(htmlDir, { recursive: true, force: true });
+    const shown = run(covTool!, [
+      "show",
+      reference,
+      `--instr-profile=${profdata}`,
+      "--format=html",
+      `--output-dir=${htmlDir}`,
+      runtimeDir,
+    ]);
+    if (shown.status !== 0) fail(`llvm-cov show failed:\n${shown.stderr}`);
+    console.log(`coverage-runtime: HTML report -> ${relative(root, htmlDir)}`);
+  }
+
+  if (!options.keepRaw) rmSync(options.profDir, { recursive: true, force: true });
+  if (options.threshold !== undefined && percent < options.threshold) {
+    fail(`runtime line coverage ${percent.toFixed(2)}% is below the ${options.threshold}% threshold`);
+  }
+}
+
+main();

package/src/cli/main.ts

@@ -23,6 +23,7 @@ import { runtimeLibDir } from "../driver/runtime-lib.js";
 import { resolveToolchain } from "../driver/toolchain-provider.js";
 import { realRunner } from "../driver/toolchain.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
+import { bundledExtensions } from "../extensions/catalog.js";
 import { nodeExtension } from "../extensions/node/index.js";
 import { nativeExtensionFromManifest } from "../extensions/native.js";
 
@@ -112,6 +113,12 @@ function buildRegistry(flags: Map<string, string | boolean>): ExtensionRegistry
       registry.register(nativeExtensionFromManifest(manifest));
     }
   }
+  // Hint the extensions that ship with xbintsc but were not enabled, so a
+  // missing `import` of a known module points at the flag that enables it
+  // (`pass --ext node`) instead of failing later with a confusing error.
+  for (const extension of bundledExtensions()) {
+    if (!registry.has(extension.name)) registry.hintExtension(extension);
+  }
   return registry;
 }
 

package/src/codegen/generator/context.ts

@@ -26,6 +26,14 @@ export class GeneratorContext {
   readonly diagnostics: DiagnosticBag;
   readonly builtins: Readonly<Record<string, BuiltinFunction>>;
   readonly modules: Readonly<Record<string, ExtensionModule>>;
+  /** Module specifier -> extension name for known but unregistered extensions. */
+  readonly moduleHints: Readonly<Record<string, string>>;
+  /**
+   * Imported symbols whose providing module was already reported as missing
+   * (hint emitted). Referencing them is skipped so the actionable hint is the
+   * only diagnostic, instead of a second "cannot be used as a value" error.
+   */
+  readonly missingModuleSymbols = new Set<number>();
   /** Host the emitted IR targets (the process by default; see `CodegenOptions`). */
   readonly target: { readonly platform: string; readonly arch: string };
   /** Imported symbol id -> the module binding it refers to. */
@@ -59,6 +67,7 @@ export class GeneratorContext {
     this.binding = bind(sourceFile);
     this.builtins = options.builtins ?? {};
     this.modules = options.modules ?? {};
+    this.moduleHints = options.moduleHints ?? {};
     this.target = options.target ?? { platform: process.platform, arch: process.arch };
     this.resolveImports();
   }
@@ -69,14 +78,19 @@ export class GeneratorContext {
    * the namespace dispatch tables.
    */
   private resolveImports(): void {
-    if (Object.keys(this.modules).length === 0) return;
     for (const statement of this.sourceFile.statements) {
       if (statement.kind !== SyntaxKind.ImportDeclaration) continue;
       const declaration = statement as ImportDeclaration;
-      const module = this.modules[declaration.moduleSpecifier.value];
-      if (!module) continue;
       const clause = declaration.importClause;
-      if (!clause) continue;
+      // Type-only imports are erased at runtime, so a missing host module is
+      // not an error for them.
+      if (!clause || clause.isTypeOnly) continue;
+      const specifier = declaration.moduleSpecifier.value;
+      const module = this.modules[specifier];
+      if (!module) {
+        this.reportMissingModule(declaration, specifier);
+        continue;
+      }
       if (clause.name) {
         const symbol = this.binding.symbolOfDeclaration.get(clause.name);
         if (symbol) {
@@ -87,11 +101,13 @@ export class GeneratorContext {
       }
       const bindings = clause.namedBindings;
       if (bindings && bindings.kind === SyntaxKind.NamedImports) {
-        for (const specifier of bindings.elements) {
-          const importedName = specifier.propertyName?.text ?? specifier.name.text;
+        for (const specifierNode of bindings.elements) {
+          if (specifierNode.isTypeOnly) continue;
+          const importedName = specifierNode.propertyName?.text ?? specifierNode.name.text;
           const exported = module.exports?.[importedName];
-          const symbol = this.binding.symbolOfDeclaration.get(specifier.name);
-          if (symbol && exported) {
+          const symbol = this.binding.symbolOfDeclaration.get(specifierNode.name);
+          if (!symbol) continue;
+          if (exported) {
             this.importExports.set(symbol.id, exported);
             // A named constructor (`import { Buffer } from "buffer"`) also
             // inherits its module's static dispatcher, so `Buffer.from(...)`
@@ -99,6 +115,14 @@ export class GeneratorContext {
             if (exported.isConstructor && module.namespace) {
               this.importNamespaces.set(symbol.id, module.namespace);
             }
+          } else if (this.usedAsValue(symbol)) {
+            this.diagnostics.error(
+              DiagnosticCode.ModuleNotFound,
+              `Module '"${specifier}"' has no exported member '${importedName}'`,
+              specifierNode.name,
+              this.sourceFile.fileName,
+            );
+            this.missingModuleSymbols.add(symbol.id);
           }
         }
       } else if (bindings && bindings.kind === SyntaxKind.NamespaceImport) {
@@ -108,6 +132,52 @@ export class GeneratorContext {
     }
   }
 
+  /**
+   * Diagnose an import of a module the registry cannot provide.
+   *
+   * A *hinted* module belongs to an extension the caller knows about but did
+   * not enable, so point at the flag that enables it. Anything else is a bare
+   * specifier xbintsc cannot link - almost always a third-party package from
+   * `node_modules` - and must be reported at the import site rather than
+   * degrading into a downstream "cannot be used as a value" error.
+   */
+  private reportMissingModule(declaration: ImportDeclaration, specifier: string): void {
+    const provider = this.moduleHints[specifier];
+    if (provider) {
+      this.diagnostics.error(
+        DiagnosticCode.ModuleNotFound,
+        `module '${specifier}' is provided by the '${provider}' extension; pass --ext ${provider}`,
+        declaration.moduleSpecifier,
+        this.sourceFile.fileName,
+      );
+      this.markMissingModuleSymbols(declaration);
+      return;
+    }
+    // A path that is not a bare specifier is a bundling concern; the driver
+    // already reports unresolved relative imports, so stay out of the way.
+    if (!isBareSpecifier(specifier)) return;
+    // Only report when a binding is actually read: a type-only use is erased
+    // by the binder and must keep compiling.
+    const symbols = this.importBindingSymbols(declaration);
+    if (!symbols.some((symbol) => this.usedAsValue(symbol))) return;
+    this.diagnostics.error(
+      DiagnosticCode.ModuleNotFound,
+      `module '${specifier}' is not supported: xbintsc can only import built-in platform modules and ` +
+        "relative '.ts' files; third-party npm packages (node_modules) are not implemented yet",
+      declaration.moduleSpecifier,
+      this.sourceFile.fileName,
+    );
+    for (const symbol of symbols) this.missingModuleSymbols.add(symbol.id);
+  }
+
+  /**
+   * True when a binding is read as a runtime value. Type positions are not
+   * bound (the binder skips them), so a symbol with no references is erased.
+   */
+  private usedAsValue(symbol: SymbolInfo): boolean {
+    return symbol.references.length > 0;
+  }
+
   /**
    * Bind a default/namespace import to either the module's runtime namespace
    * dispatcher (when it has one) or its named exports (when it does not).
@@ -120,6 +190,31 @@ export class GeneratorContext {
     }
   }
 
+  /** Every binding an import declaration introduces (including type-only ones). */
+  private importBindingSymbols(declaration: ImportDeclaration): SymbolInfo[] {
+    const clause = declaration.importClause;
+    if (!clause) return [];
+    const names: Identifier[] = [];
+    if (clause.name) names.push(clause.name);
+    const bindings = clause.namedBindings;
+    if (bindings && bindings.kind === SyntaxKind.NamedImports) {
+      for (const specifier of bindings.elements) names.push(specifier.name);
+    } else if (bindings && bindings.kind === SyntaxKind.NamespaceImport) {
+      names.push(bindings.name);
+    }
+    const symbols: SymbolInfo[] = [];
+    for (const name of names) {
+      const symbol = this.binding.symbolOfDeclaration.get(name);
+      if (symbol) symbols.push(symbol);
+    }
+    return symbols;
+  }
+
+  /** Record every symbol introduced by an import of a missing known module. */
+  private markMissingModuleSymbols(declaration: ImportDeclaration): void {
+    for (const symbol of this.importBindingSymbols(declaration)) this.missingModuleSymbols.add(symbol.id);
+  }
+
   /** Namespace name an imported alias refers to, if any. */
   namespaceOfSymbol(symbol: SymbolInfo | undefined): string | undefined {
     if (!symbol || symbol.kind !== SymbolKind.Import) return undefined;
@@ -320,3 +415,13 @@ export class GeneratorContext {
     );
   }
 }
+
+/** A bare module specifier (`fs`, `node:fs`, `@scope/pkg`), not a file path. */
+function isBareSpecifier(specifier: string): boolean {
+  return (
+    !specifier.startsWith(".") &&
+    !specifier.startsWith("/") &&
+    !specifier.startsWith("\\") &&
+    !/^[A-Za-z]:[\\/]/.test(specifier)
+  );
+}

package/src/codegen/generator/expressions/primary.ts

@@ -166,6 +166,9 @@ export const primaryExpressionMethods: PrimaryExpressionMethods = {
         return this.emitFunctionValue(symbol);
       }
       if (symbol.kind === SymbolKind.Import) {
+        // The providing module was reported as missing (with a `pass --ext`
+        // hint) while resolving imports; don't pile on a second error.
+        if (this.missingModuleSymbols.has(symbol.id)) return i64(XT_UNDEFINED);
         // Some module bindings are plain values rather than functions
         // (`isMainThread`, `workerData`, ...). They resolve through a nullary
         // runtime getter instead of being called or namespaced.

package/src/codegen/generator/state.ts

@@ -62,6 +62,13 @@ export interface CodegenOptions {
   readonly builtins?: Readonly<Record<string, BuiltinFunction>>;
   /** Importable modules supplied by registered extensions. */
   readonly modules?: Readonly<Record<string, ExtensionModule>>;
+  /**
+   * Module specifier -> extension name for modules that a *known but
+   * unregistered* extension provides. Used to report an actionable
+   * `pass --ext node` diagnostic when such a module is imported without
+   * enabling the extension.
+   */
+  readonly moduleHints?: Readonly<Record<string, string>>;
   /**
    * Host the IR is generated for. xbintsc builds for its own host, so this
    * defaults to the running process; it is overridable for tests.

package/src/driver/compiler.ts

@@ -72,6 +72,7 @@ export function compileString(source: string, fileName = "input.ts", extensions?
   const { ir } = generate(sourceFile, diagnostics, {
     builtins: registry.builtins(),
     modules: registry.modules(),
+    moduleHints: registry.moduleHints(),
   });
   return { ir, diagnostics: diagnostics.diagnostics };
 }
@@ -101,10 +102,35 @@ export function compileEntry(entryPath: string, extensions?: ExtensionRegistry):
   const { ir } = generate(sourceFile, diagnostics, {
     builtins: registry.builtins(),
     modules: registry.modules(),
+    moduleHints: registry.moduleHints(),
   });
   return { ir, diagnostics: diagnostics.diagnostics };
 }
 
+/**
+ * Where the incremental cache lives when the caller does not name a directory:
+ * `xbintsc_CACHE_DIR` when set, otherwise `<cwd>/.xbintsc`. The override keeps
+ * an instrumented build (see `scripts/coverage-runtime.ts`) from reusing the
+ * un-instrumented objects in a normal cache, which would silently yield no
+ * profile data.
+ */
+function defaultCacheDir(): string {
+  return process.env.xbintsc_CACHE_DIR || join(process.cwd(), ".xbintsc");
+}
+
+/**
+ * Whether a build may link a prebuilt `runtime/lib` archive. The explicit option
+ * wins; otherwise `xbintsc_PREFER_PREBUILT` decides (`0`/`false` disables) and
+ * the default is to use an archive when one exists. Instrumented builds set it
+ * to `0` so the C runtime is compiled (and therefore instrumented) from source.
+ */
+export function resolvePreferPrebuilt(explicit: boolean | undefined): boolean {
+  if (explicit !== undefined) return explicit;
+  const raw = process.env.xbintsc_PREFER_PREBUILT;
+  if (raw === undefined || raw === "") return true;
+  return raw !== "0" && raw.toLowerCase() !== "false";
+}
+
 function executableName(entry: string, outDir: string, explicit: string | undefined): string {
   if (explicit) return resolve(explicit);
   const base = basename(entry, extname(entry));
@@ -116,7 +142,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   const runner = options.runner ?? realRunner;
   const registry = options.extensions ?? createDefaultRegistry();
   const outDir = resolve(options.outDir ?? join(process.cwd(), "build"));
-  const cacheDir = resolve(options.cacheDir ?? join(process.cwd(), ".xbintsc"));
+  const cacheDir = resolve(options.cacheDir ?? defaultCacheDir());
   const emit: EmitKind = options.emit ?? "exe";
   const optimize = options.optimize ?? "2";
 
@@ -173,6 +199,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   const { ir } = generate(sourceFile, diagnostics, {
     builtins: registry.builtins(),
     modules: registry.modules(),
+    moduleHints: registry.moduleHints(),
   });
 
   if (options.verbose) {
@@ -215,7 +242,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     runtimeDir,
     cacheDir,
     registry,
-    options.preferPrebuilt ?? true,
+    resolvePreferPrebuilt(options.preferPrebuilt),
     toolchain.env,
   );
 

package/src/extensions/catalog.ts

@@ -0,0 +1,19 @@
+/**
+ * Catalog of the extensions shipped with xbintsc.
+ *
+ * Callers (the CLI, embedding tools) use this to hint the compiler about
+ * modules that *would* be available if an extension were enabled, so an import
+ * of a known module without its `--ext` flag fails with an actionable message
+ * (`pass --ext node`) rather than a confusing downstream error.
+ *
+ * The core compiler stays platform agnostic: it only sees the resulting hint
+ * table, never the Node extension itself.
+ */
+
+import type { Extension } from "./registry.js";
+import { nodeExtension } from "./node/index.js";
+
+/** Every extension bundled with xbintsc, in registration order. */
+export function bundledExtensions(): readonly Extension[] {
+  return [nodeExtension];
+}