xbintsc 0.3.12 → 0.3.14

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/codegen/generator/calls/access.ts

@@ -106,6 +106,21 @@ export const accessCallMethods: AccessCallMethods = {
         }
       }
     }
+    // Modules with no namespace dispatcher (`fs`, ...) can still expose value
+    // getters (`fs.constants`, `fs.promises`). Lower `fs.constants` the same
+    // way a named `import { constants } from "fs"` is lowered.
+    if (node.expression.kind === SyntaxKind.Identifier) {
+      const moduleExports = this.moduleExportsOfSymbol(
+        this.binding.symbolOfIdentifier.get(node.expression as Identifier),
+      );
+      const exported = moduleExports?.[node.name.text];
+      if (exported?.valueSymbol) {
+        this.extraDeclarations.add(`declare i64 @${exported.valueSymbol}(i32, i64*)`);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${exported.valueSymbol}(i32 0, i64* null)`);
+        return result;
+      }
+    }
     const object = this.emitExpression(node.expression);
     return this.emitPropertyGet(object, node.name.text);
   },

package/src/codegen/generator/calls/invocation.ts

@@ -91,8 +91,14 @@ export const invocationCallMethods: InvocationCallMethods = {
       return result;
     }
     if (callee.kind === SyntaxKind.Identifier) {
-      if ((callee as Identifier).text === "super") return this.emitSuperConstructor(node);
-      const symbol = this.binding.symbolOfIdentifier.get(callee as Identifier);
+      const identifier = callee as Identifier;
+      if (identifier.text === "super") return this.emitSuperConstructor(node);
+      const symbol = this.binding.symbolOfIdentifier.get(identifier);
+      // `require("x")` is CommonJS; the ESM form is the only supported import.
+      if (!symbol && identifier.text === "require") {
+        this.reportRequireUse(node);
+        return i64(XT_UNDEFINED);
+      }
       if (symbol && symbol.kind === SymbolKind.Import) {
         const exported = this.importExports.get(symbol.id);
         if (exported) return this.emitModuleExport(node, exported);

package/src/codegen/generator/context.ts

@@ -78,7 +78,6 @@ export class GeneratorContext {
    * the namespace dispatch tables.
    */
   private resolveImports(): void {
-    if (Object.keys(this.modules).length === 0 && Object.keys(this.moduleHints).length === 0) return;
     for (const statement of this.sourceFile.statements) {
       if (statement.kind !== SyntaxKind.ImportDeclaration) continue;
       const declaration = statement as ImportDeclaration;
@@ -86,18 +85,10 @@ export class GeneratorContext {
       // Type-only imports are erased at runtime, so a missing host module is
       // not an error for them.
       if (!clause || clause.isTypeOnly) continue;
-      const module = this.modules[declaration.moduleSpecifier.value];
+      const specifier = declaration.moduleSpecifier.value;
+      const module = this.modules[specifier];
       if (!module) {
-        const provider = this.moduleHints[declaration.moduleSpecifier.value];
-        if (provider) {
-          this.diagnostics.error(
-            DiagnosticCode.ModuleNotFound,
-            `module '${declaration.moduleSpecifier.value}' is provided by the '${provider}' extension; pass --ext ${provider}`,
-            declaration.moduleSpecifier,
-            this.sourceFile.fileName,
-          );
-          this.markMissingModuleSymbols(declaration);
-        }
+        this.reportMissingModule(declaration, specifier);
         continue;
       }
       if (clause.name) {
@@ -110,12 +101,13 @@ export class GeneratorContext {
       }
       const bindings = clause.namedBindings;
       if (bindings && bindings.kind === SyntaxKind.NamedImports) {
-        for (const specifier of bindings.elements) {
-          if (specifier.isTypeOnly) continue;
-          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(...)`
@@ -123,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) {
@@ -132,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 import built-in platform modules, ` +
+        "relative '.ts' files and ESM packages under node_modules; CommonJS packages are not supported",
+      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).
@@ -144,10 +190,10 @@ export class GeneratorContext {
     }
   }
 
-  /** Record every symbol introduced by an import of a missing known module. */
-  private markMissingModuleSymbols(declaration: ImportDeclaration): void {
+  /** Every binding an import declaration introduces (including type-only ones). */
+  private importBindingSymbols(declaration: ImportDeclaration): SymbolInfo[] {
     const clause = declaration.importClause;
-    if (!clause) return;
+    if (!clause) return [];
     const names: Identifier[] = [];
     if (clause.name) names.push(clause.name);
     const bindings = clause.namedBindings;
@@ -156,10 +202,17 @@ export class GeneratorContext {
     } 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) this.missingModuleSymbols.add(symbol.id);
+      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. */
@@ -361,4 +414,42 @@ export class GeneratorContext {
       this.sourceFile.fileName,
     );
   }
+
+  /**
+   * Report a CommonJS `require(...)` use. xbintsc has no CommonJS module
+   * runtime, so point the user at the ESM `import` form (with the requested
+   * module in the hint when it is a string literal).
+   */
+  reportRequireUse(node: Node): void {
+    const specifier = requireSpecifier(node);
+    const replacement = specifier
+      ? `use an ESM import instead, e.g. \`import value from ${JSON.stringify(specifier)}\``
+      : "use an ESM `import` statement instead";
+    this.diagnostics.error(
+      DiagnosticCode.UnsupportedFeature,
+      `CommonJS \`require()\` is not supported; ${replacement}`,
+      node,
+      this.sourceFile.fileName,
+    );
+  }
+}
+
+/** The string literal passed to `require("...")`, when there is one. */
+function requireSpecifier(node: Node): string | undefined {
+  if (node.kind !== SyntaxKind.CallExpression) return undefined;
+  const first = (node as { arguments?: readonly Node[] }).arguments?.[0];
+  if (first && first.kind === SyntaxKind.StringLiteral) {
+    return (first as unknown as { value: string }).value;
+  }
+  return undefined;
+}
+
+/** 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

@@ -235,6 +235,11 @@ export const primaryExpressionMethods: PrimaryExpressionMethods = {
           const nameValue = this.stringValue(identifier.text);
           return this.runtimeCall("xt_error_constructor", [nameValue]);
         }
+        // A bare `require` reference is CommonJS; steer the user to `import`.
+        if (identifier.text === "require") {
+          this.reportRequireUse(identifier);
+          return i64(XT_UNDEFINED);
+        }
         this.diagnostics.error(
           DiagnosticCode.CannotFindName,
           `Cannot find name '${identifier.text}'`,

package/src/driver/compiler.ts

@@ -77,6 +77,19 @@ export function compileString(source: string, fileName = "input.ts", extensions?
   return { ir, diagnostics: diagnostics.diagnostics };
 }
 
+/**
+ * Every module specifier the registry can resolve at code generation time (the
+ * registered platform modules plus the hints for known-but-disabled
+ * extensions). Bare imports outside this set are looked up in `node_modules`
+ * and bundled as source.
+ */
+function externalModuleSpecifiers(registry: ExtensionRegistry): Set<string> {
+  return new Set([
+    ...Object.keys(registry.modules()),
+    ...Object.keys(registry.moduleHints()),
+  ]);
+}
+
 /**
  * Compile a file to LLVM IR, bundling every reachable relative module first so
  * that imports from other TypeScript sources resolve exactly like `build`.
@@ -88,6 +101,7 @@ export function compileEntry(entryPath: string, extensions?: ExtensionRegistry):
   const diagnostics = new DiagnosticBag();
   const parser = new Parser(file, diagnostics);
   let sourceFile = parser.parseSourceFile();
+  const registry = extensions ?? createDefaultRegistry();
   const isModule = sourceFile.statements.some(
     (statement) =>
       statement.kind === SyntaxKind.ImportDeclaration ||
@@ -95,10 +109,9 @@ export function compileEntry(entryPath: string, extensions?: ExtensionRegistry):
       statement.kind === SyntaxKind.ExportAssignment,
   );
   if (isModule) {
-    const bundled = bundleModules(absoluteEntry, diagnostics);
+    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry));
     if (bundled) sourceFile = bundled.sourceFile;
   }
-  const registry = extensions ?? createDefaultRegistry();
   const { ir } = generate(sourceFile, diagnostics, {
     builtins: registry.builtins(),
     modules: registry.modules(),
@@ -107,6 +120,30 @@ export function compileEntry(entryPath: string, extensions?: ExtensionRegistry):
   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));
@@ -118,7 +155,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";
 
@@ -148,7 +185,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   );
   let cacheText = sourceText;
   if (isModule) {
-    const bundled = bundleModules(absoluteEntry, diagnostics);
+    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry));
     if (bundled) {
       sourceFile = bundled.sourceFile;
       cacheText = bundled.text;
@@ -218,7 +255,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     runtimeDir,
     cacheDir,
     registry,
-    options.preferPrebuilt ?? true,
+    resolvePreferPrebuilt(options.preferPrebuilt),
     toolchain.env,
   );