xbintsc 0.5.6 → 0.5.21

package/src/driver/compiler.ts

@@ -5,161 +5,35 @@
  * The runtime (and any registered extension sources) are compiled once and
  * cached, and the whole build is skipped when the incremental cache says
  * nothing relevant changed.
+ *
+ * This module only orchestrates the phases. The front end lives in
+ * `frontend.ts`, cache-key inputs in `build-key.ts`, runtime compilation in
+ * `runtime-objects.ts`, platform artifacts in `app-artifacts.ts`, and the
+ * version constant in `version.ts`.
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
-import { DiagnosticBag, DiagnosticCode, type Diagnostic } from "../diagnostics/diagnostic.js";
-import { SourceFile } from "../diagnostics/source.js";
-import { sourceTextBytes } from "../diagnostics/source-text.js";
-import { Parser } from "../parser/parser.js";
+import { DiagnosticBag, DiagnosticCode } from "../diagnostics/diagnostic.js";
 import { generate } from "../codegen/llvm.js";
-import { SyntaxKind } from "../ast/nodes.js";
-import { bundleModules } from "./modules.js";
-import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
-import { BuildCache, hashParts } from "./cache.js";
-import { compilerFingerprint, registryFingerprint, runtimeFingerprint } from "./fingerprint.js";
+import { createDefaultRegistry } from "../extensions/registry.js";
+import { BuildCache } from "./cache.js";
 import { findRuntimeDir } from "./paths.js";
-import { findRuntimeLibrary } from "./runtime-lib.js";
 import { resolveToolchain } from "./toolchain-provider.js";
-import { ensureIconObject, readIcon, EMPTY_ICON, IconError, type IconInfo } from "./icon.js";
-import { ensureWindowsIconResource, resolveResourceCompiler } from "./win-icon.js";
-import { ensureWindowsEntryObject } from "./win-entry.js";
+import { readIcon, IconError, type IconInfo } from "./icon.js";
 import { bundlePathFor, packageMacApp } from "./mac-bundle.js";
 import type { AppConfig } from "./config.js";
-import {
-  compileC,
-  compileIr,
-  link,
-  realRunner,
-  RUNTIME_CFLAGS,
-  type Runner,
-} from "./toolchain.js";
-
-/**
- * The compiler's own version. It is part of the incremental cache key, so it
- * must be bumped for every release (a test enforces that it matches
- * `package.json`); a stale version would let an upgraded compiler reuse binaries
- * produced by the previous one.
- */
-export const COMPILER_VERSION = "0.5.6";
-
-export type EmitKind = "exe" | "obj" | "ir";
-
-export interface BuildOptions {
-  /** Explicit output path (defaults to the source base name in `outDir`). */
-  readonly output?: string;
-  readonly outDir?: string;
-  readonly optimize?: "0" | "1" | "2" | "3";
-  readonly emit?: EmitKind;
-  readonly force?: boolean;
-  readonly verbose?: boolean;
-  readonly cacheDir?: string;
-  readonly extensions?: ExtensionRegistry;
-  readonly runner?: Runner;
-  readonly clang?: string;
-  /** Prefer a prebuilt `runtime/lib/<os>-<arch>/*.a` archive when present (default true). */
-  readonly preferPrebuilt?: boolean;
-  readonly write?: boolean;
-  /** Application icon embedded into the binary (shorthand for `app.icon`). */
-  readonly icon?: string;
-  /** Application metadata: name, icon and macOS bundle settings. */
-  readonly app?: AppConfig;
-  /** Emit LLVM debug metadata so `-g` produces DWARF/CodeView (default false). */
-  readonly debug?: boolean;
-}
-
-/** One phase of a build, in milliseconds (reported by `--time`). */
-export interface PhaseTiming {
-  readonly phase: "frontend" | "codegen" | "runtime" | "clang" | "link";
-  readonly ms: number;
-}
-
-export interface BuildResult {
-  readonly outputPath: string;
-  readonly irPath?: string;
-  readonly cached: boolean;
-  readonly diagnostics: readonly Diagnostic[];
-  readonly ir?: string;
-  /** macOS `.app` bundle produced by `app.bundle` (darwin only). */
-  readonly bundlePath?: string;
-  /** Per-phase timings, collected for `xbintsc build --time`. */
-  readonly timings?: readonly PhaseTiming[];
-}
-
-export interface CompileStringResult {
-  readonly ir: string;
-  readonly diagnostics: readonly Diagnostic[];
-}
-
-/** Compile TypeScript source text to LLVM IR without touching the toolchain. */
-export function compileString(
-  source: string,
-  fileName = "input.ts",
-  extensions?: ExtensionRegistry,
-  options: { readonly debug?: boolean } = {},
-): CompileStringResult {
-  const file = new SourceFile(fileName, source);
-  const diagnostics = new DiagnosticBag();
-  const parser = new Parser(file, diagnostics);
-  const sourceFile = parser.parseSourceFile();
-  const registry = extensions ?? createDefaultRegistry();
-  const { ir } = generate(sourceFile, diagnostics, {
-    builtins: registry.builtins(),
-    modules: registry.modules(),
-    moduleHints: registry.moduleHints(),
-    debug: options.debug === true,
-  });
-  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`.
- */
-export function compileEntry(
-  entryPath: string,
-  extensions?: ExtensionRegistry,
-  options: { readonly debug?: boolean } = {},
-): CompileStringResult {
-  const absoluteEntry = resolve(entryPath);
-  const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
-  const file = new SourceFile(absoluteEntry, sourceText);
-  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 ||
-      statement.kind === SyntaxKind.ExportDeclaration ||
-      statement.kind === SyntaxKind.ExportAssignment,
-  );
-  if (isModule) {
-    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry), registry.assetLoaders());
-    if (bundled) sourceFile = bundled.sourceFile;
-  }
-  const { ir } = generate(sourceFile, diagnostics, {
-    builtins: registry.builtins(),
-    modules: registry.modules(),
-    moduleHints: registry.moduleHints(),
-    debug: options.debug === true,
-  });
-  return { ir, diagnostics: diagnostics.diagnostics };
-}
+import { compileIr, link, mergeProfileData, realRunner, ToolchainError } from "./toolchain.js";
+import { parseEntry } from "./frontend.js";
+import { ensureRuntimeObjects } from "./runtime-objects.js";
+import { ensureAppArtifacts } from "./app-artifacts.js";
+import { buildCacheKey } from "./build-key.js";
+import type { BuildOptions, BuildResult, EmitKind, PhaseTiming } from "./options.js";
+
+export { COMPILER_VERSION } from "./version.js";
+export { compileString, compileEntry, parseEntry, type ParsedEntry } from "./frontend.js";
+export { RUNTIME_SOURCES, type RuntimeObjects } from "./runtime-objects.js";
+export type { BuildOptions, BuildResult, CompileStringResult, EmitKind, PhaseTiming } from "./options.js";
 
 /**
  * Where the incremental cache lives when the caller does not name a directory:
@@ -199,9 +73,12 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   const cacheDir = resolve(options.cacheDir ?? defaultCacheDir());
   const emit: EmitKind = options.emit ?? "exe";
   const optimize = options.optimize ?? "2";
+  const lto = options.lto === true;
+  const pgo = options.pgo;
+  const pgoDir = resolve(options.pgoDir ?? join(outDir, "pgo"));
+  if (pgo) mkdirSync(pgoDir, { recursive: true });
 
   const absoluteEntry = resolve(entryPath);
-  const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
   const buildStarted = Date.now();
   const timings: PhaseTiming[] = [];
 
@@ -214,29 +91,17 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
         : executableName(absoluteEntry, outDir, options.output);
 
   // -- front end -----------------------------------------------------------
-  const file = new SourceFile(absoluteEntry, sourceText);
   const diagnostics = new DiagnosticBag();
-  const parser = new Parser(file, diagnostics);
-  let sourceFile = parser.parseSourceFile();
+  const parsed = parseEntry(absoluteEntry, registry, diagnostics);
+  timings.push({ phase: "frontend", ms: Date.now() - buildStarted });
 
-  // Lower `import`/`export` by merging every reachable module into one file.
-  const isModule = sourceFile.statements.some(
-    (statement) =>
-      statement.kind === SyntaxKind.ImportDeclaration ||
-      statement.kind === SyntaxKind.ExportDeclaration ||
-      statement.kind === SyntaxKind.ExportAssignment,
-  );
-  let cacheText = sourceText;
-  if (isModule) {
-    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry), registry.assetLoaders());
-    if (bundled) {
-      sourceFile = bundled.sourceFile;
-      cacheText = bundled.text;
-    }
+  /* Parse (or module-graph) errors leave missing nodes in the tree. Stop before
+   * code generation instead of letting the binder crash on them. */
+  if (diagnostics.hasErrors) {
+    return { outputPath, cached: false, diagnostics: diagnostics.diagnostics, timings };
   }
-  timings.push({ phase: "frontend", ms: Date.now() - buildStarted });
 
-  const app = options.app ?? {};
+  const app: AppConfig = options.app ?? {};
   const iconPath = options.icon ?? app.icon;
   let icon: IconInfo | undefined;
   if (iconPath) {
@@ -252,21 +117,19 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   }
 
   const runtimeDir = findRuntimeDir();
-  const cacheKey = hashParts([
-    COMPILER_VERSION,
-    compilerFingerprint(),
-    cacheText,
+  const cacheKey = buildCacheKey({
+    sourceText: parsed.cacheText,
     emit,
     optimize,
-    process.platform,
-    registryFingerprint(registry),
-    runtimeFingerprint(runtimeDir),
-    icon ? hashParts(["icon", icon.format, Buffer.from(icon.bytes).toString("base64")]) : "",
-    app.name ?? "",
-    String(app.bundle ?? false),
-    app.bundleId ?? "",
-    String(options.debug === true),
-  ]);
+    registry,
+    runtimeDir,
+    icon,
+    app,
+    debug: options.debug === true,
+    lto,
+    pgo,
+    pgoDir,
+  });
 
   // A `.app` bundle is deterministic from the output path and name, so it can be
   // part of the cache key before the bundle actually exists.
@@ -276,12 +139,14 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
       : undefined;
   const cache = new BuildCache(cacheDir);
   const outputs = bundle ? [outputPath, bundle] : [outputPath];
-  if (!options.force && !diagnostics.hasErrors && cache.isFresh(cacheKey, outputs)) {
+  /* PGO profile data can change without the cache key changing, so always
+   * rebuild a `--pgo-use` binary; it is an explicit optimization step. */
+  if (!options.force && pgo !== "use" && !diagnostics.hasErrors && cache.isFresh(cacheKey, outputs)) {
     return { outputPath, cached: true, diagnostics: [], timings, ...(bundle ? { bundlePath: bundle } : {}) };
   }
 
   const codegenStarted = Date.now();
-  const { ir } = generate(sourceFile, diagnostics, {
+  const { ir } = generate(parsed.sourceFile, diagnostics, {
     builtins: registry.builtins(),
     modules: registry.modules(),
     moduleHints: registry.moduleHints(),
@@ -318,10 +183,30 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     ? { clang: options.clang, linkerArgs: [] as string[], env: {} as Record<string, string> }
     : resolveToolchain(runner);
   const clang = toolchain.clang;
+  if (pgo === "use") {
+    try {
+      mergeProfileData(runner, pgoDir, clang, toolchain.env);
+    } catch (error) {
+      if (error instanceof ToolchainError) {
+        diagnostics.error(DiagnosticCode.ToolchainError, error.message);
+        return { outputPath, irPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
+      }
+      throw error;
+    }
+  }
   mkdirSync(cacheDir, { recursive: true });
 
   const objectPath = emit === "obj" ? outputPath : resolve(outDir, baseName + ".o");
-  compileIr(runner, { clang, irPath, objectPath, optimize, env: toolchain.env, debug: options.debug === true });
+  compileIr(runner, {
+    clang,
+    irPath,
+    objectPath,
+    optimize,
+    env: toolchain.env,
+    debug: options.debug === true,
+    lto,
+    ...(pgo ? { pgo, pgoDir } : {}),
+  });
   timings.push({ phase: "clang", ms: Date.now() - clangStarted });
 
   if (emit === "obj") {
@@ -331,50 +216,33 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   }
 
   const runtimeStarted = Date.now();
-  const { runtimeObjects, extensionObjects, nativeObjects } = ensureRuntimeObjects(
+  const { runtimeObjects, extensionObjects, nativeObjects } = ensureRuntimeObjects({
     runner,
     clang,
     runtimeDir,
     cacheDir,
     registry,
-    resolvePreferPrebuilt(options.preferPrebuilt),
-    toolchain.env,
-  );
+    preferPrebuilt: resolvePreferPrebuilt(options.preferPrebuilt) && !lto && pgo === undefined,
+    env: toolchain.env,
+    lto,
+    pgo,
+    pgoDir,
+  });
   timings.push({ phase: "runtime", ms: Date.now() - runtimeStarted });
 
-  /* On Windows a GUI program links as a **Windows-subsystem** executable, so
-   * launching it does not flash a console window. That subsystem's C runtime
-   * wants `WinMain`, so a tiny shim object bridges it to the runtime's `main`.
-   * `app.console: true` keeps the console subsystem instead (useful while
-   * debugging, because stdout and stderr only exist there). Other platforms
-   * have no equivalent. */
-  const windowsSubsystem = process.platform === "win32" && registry.has("gui") && app.console !== true;
-  const consoleSubsystem = windowsSubsystem ? ["-Wl,/SUBSYSTEM:WINDOWS"] : [];
-  const entryObject = windowsSubsystem
-    ? ensureWindowsEntryObject(runner, clang, cacheDir, toolchain.env)
-    : undefined;
-
-  const iconObjects: string[] = [];
-  // The GUI extension references the icon symbols unconditionally, so a GUI
-  // program gets an (empty) icon object even with no icon configured.
-  if (icon !== undefined || registry.has("gui")) {
-    try {
-      iconObjects.push(ensureIconObject(runner, clang, cacheDir, icon ?? EMPTY_ICON, toolchain.env));
-      if (icon && process.platform === "win32") {
-        const resourceCompiler = resolveResourceCompiler(runner, clang);
-        if (resourceCompiler) {
-          iconObjects.push(ensureWindowsIconResource(runner, cacheDir, icon, resourceCompiler, toolchain.env));
-        } else if (options.verbose) {
-          process.stderr.write("xbintsc: no llvm-rc/windres found; skipping the embedded .exe icon\n");
-        }
-      }
-    } catch (error) {
-      if (error instanceof IconError) {
-        diagnostics.error(DiagnosticCode.ToolchainError, error.message);
-        return { outputPath, irPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
-      }
-      throw error;
-    }
+  const artifacts = ensureAppArtifacts({
+    runner,
+    clang,
+    cacheDir,
+    registry,
+    app,
+    icon,
+    env: toolchain.env,
+    verbose: options.verbose,
+  });
+  if (artifacts.iconError !== undefined) {
+    diagnostics.error(DiagnosticCode.ToolchainError, artifacts.iconError);
+    return { outputPath, irPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
   }
 
   const linkStarted = Date.now();
@@ -385,22 +253,24 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
       ...runtimeObjects,
       ...extensionObjects,
       ...nativeObjects,
-      ...(entryObject !== undefined ? [entryObject] : []),
-      ...iconObjects,
+      ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
+      ...artifacts.iconObjects,
     ],
     outputPath,
     linkerFlags: [
       ...toolchain.linkerArgs,
-      ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm"]),
+      ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm", "-pthread"]),
       ...registry.linkerFlags(),
       /* A GUI program is a Windows-subsystem executable: no console window is
        * created when it is launched. Console output (stdout/stderr) is lost in
        * that subsystem, so a program that wants to report things opts back in
        * with `app.console: true`. */
-      ...consoleSubsystem,
+      ...artifacts.linkerFlags,
     ],
     optimize,
     env: toolchain.env,
+    lto,
+    ...(pgo ? { pgo, pgoDir } : {}),
   });
   timings.push({ phase: "link", ms: Date.now() - linkStarted });
 
@@ -426,107 +296,3 @@ function defaultBundleId(name: string): string {
   const sanitized = name.replace(/[^A-Za-z0-9.-]/g, "");
   return `com.xbintsc.${sanitized || "app"}`;
 }
-
-interface RuntimeObjects {
-  readonly runtimeObjects: readonly string[];
-  readonly extensionObjects: readonly string[];
-  /** Pre-built C++/Rust objects and archives contributed by native extensions. */
-  readonly nativeObjects: readonly string[];
-}
-
-/** Core runtime translation units (each compiled and cached independently). */
-export const RUNTIME_SOURCES = [
-  "xt_alloc.c",
-  "xt_values.c",
-  "xt_bigint.c",
-  "xt_containers.c",
-  "xt_typed_array.c",
-  "xt_stdlib.c",
-  "xt_stdlib2.c",
-  "xt_promise.c",
-  "xt_async.c",
-  "xt_loop.c",
-  "xt_generator.c",
-  "xt_coroutine.c",
-  "xt_fetch.c",
-  "xt_symbol.c",
-  "xt_builtins.c",
-  "xt_constructors.c",
-  "xt_io.c",
-] as const;
-
-/**
- * Compile the core runtime and every extension source, reusing cached object
- * files keyed on the C source hash. Returns the object paths to link.
- *
- * When `preferPrebuilt` is set, a shipped static archive
- * (`runtime/lib/<os>-<arch>/{core,ext_<name>}.a`) is used instead of compiling
- * that group's C sources. Missing archives fall back to compiling the sources.
- */
-function ensureRuntimeObjects(
-  runner: Runner,
-  clang: string,
-  runtimeDir: string,
-  cacheDir: string,
-  registry: ExtensionRegistry,
-  preferPrebuilt: boolean,
-  env: Record<string, string>,
-): RuntimeObjects {
-  /* Runtime objects depend on the shared headers (rt.h/rt_internal.h/...) and
-     the `#include`d implementation fragments (`.inc`), so any change to them
-     must invalidate every cached object. Hash them all. */
-  const headerParts: string[] = [];
-  const collectHeaders = (dir: string): void => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) collectHeaders(full);
-      else if (entry.name.endsWith(".h") || entry.name.endsWith(".inc")) headerParts.push(readFileSync(full, "utf8"));
-    }
-  };
-  collectHeaders(runtimeDir);
-  const headerStamp = hashParts(headerParts);
-
-  const compileOne = (sourcePath: string, tag: string): string => {
-    const body = readFileSync(sourcePath, "utf8");
-    const key = hashParts([
-      "runtime",
-      COMPILER_VERSION,
-      RUNTIME_CFLAGS.join(" "),
-      tag,
-      headerStamp,
-      body,
-      clang,
-      process.platform,
-    ]);
-    const objectPath = join(cacheDir, `${tag}-${key}.o`);
-    if (!existsSync(objectPath)) {
-      compileC(runner, clang, sourcePath, objectPath, runtimeDir, env);
-    }
-    return objectPath;
-  };
-
-  const coreArchive = preferPrebuilt ? findRuntimeLibrary("core") : undefined;
-  const runtimeObjects = coreArchive
-    ? [coreArchive]
-    : RUNTIME_SOURCES.map((source) => compileOne(join(runtimeDir, source), basename(source, ".c")));
-
-  const extensionObjects: string[] = [];
-  const seen = new Set<string>();
-  for (const extension of registry.all()) {
-    const sources = extension.runtimeSources ? extension.runtimeSources() : [];
-    if (sources.length === 0) continue;
-    const archive = preferPrebuilt ? findRuntimeLibrary(`ext_${extension.name}`) : undefined;
-    if (archive) {
-      extensionObjects.push(archive);
-      continue;
-    }
-    for (const sourcePath of sources) {
-      const dedupeKey = resolve(sourcePath);
-      if (seen.has(dedupeKey)) continue;
-      seen.add(dedupeKey);
-      extensionObjects.push(compileOne(sourcePath, `ext_${extensionObjects.length}_${basename(sourcePath, ".c")}`));
-    }
-  }
-  // A native archive may be shared by several manifests; link each once.
-  return { runtimeObjects, extensionObjects, nativeObjects: [...new Set(registry.nativeObjects())] };
-}

package/src/driver/config.ts

@@ -39,6 +39,9 @@ export interface ProjectConfig {
   readonly outDir?: string;
   readonly output?: string;
   readonly optimize?: "0" | "1" | "2" | "3";
+  readonly lto?: boolean;
+  readonly pgo?: "generate" | "use";
+  readonly pgoDir?: string;
   readonly extensions?: readonly string[];
   readonly extNative?: readonly string[];
   readonly force?: boolean;
@@ -103,6 +106,10 @@ export function parseProjectConfig(text: string, where: string = CONFIG_FILE_NAM
   if (optimize !== undefined && !["0", "1", "2", "3"].includes(optimize)) {
     throw new ProjectConfigError(`${where}: 'optimize' must be one of "0", "1", "2", "3"`);
   }
+  const pgo = readString(root, "pgo", where);
+  if (pgo !== undefined && pgo !== "generate" && pgo !== "use") {
+    throw new ProjectConfigError(`${where}: 'pgo' must be "generate" or "use"`);
+  }
 
   let app: AppConfig | undefined;
   if (root.app !== undefined) {
@@ -123,6 +130,9 @@ export function parseProjectConfig(text: string, where: string = CONFIG_FILE_NAM
     outDir: readString(root, "outDir", where),
     output: readString(root, "output", where),
     optimize: optimize as ProjectConfig["optimize"],
+    lto: readBoolean(root, "lto", where),
+    pgo: pgo as ProjectConfig["pgo"],
+    pgoDir: readString(root, "pgoDir", where),
     extensions: readStringArray(root, "extensions", where),
     extNative: readStringArray(root, "extNative", where),
     force: readBoolean(root, "force", where),
@@ -174,6 +184,7 @@ export function resolveConfigPaths(loaded: LoadedProjectConfig): ProjectConfig {
     ...(config.entry ? { entry: resolvePath(directory, config.entry) } : {}),
     ...(config.outDir ? { outDir: resolvePath(directory, config.outDir) } : {}),
     ...(config.output ? { output: resolvePath(directory, config.output) } : {}),
+    ...(config.pgoDir ? { pgoDir: resolvePath(directory, config.pgoDir) } : {}),
     ...(config.extNative ? { extNative: config.extNative.map((path) => resolvePath(directory, path)) } : {}),
     ...(app ? { app } : {}),
   };

package/src/driver/frontend.ts

@@ -0,0 +1,120 @@
+/**
+ * Front end: source text in, LLVM IR out (no toolchain involved).
+ *
+ * `compileString` compiles one in-memory source text; `compileEntry` reads a
+ * file and first bundles every reachable module. `build` reuses the same
+ * `parseEntry` step so the module graph is resolved identically for `emit`,
+ * `run` and `build`.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { DiagnosticBag } from "../diagnostics/diagnostic.js";
+import { SourceFile } from "../diagnostics/source.js";
+import { sourceTextBytes } from "../diagnostics/source-text.js";
+import { Parser } from "../parser/parser.js";
+import { generate } from "../codegen/llvm.js";
+import { SyntaxKind, type SourceFileNode } from "../ast/nodes.js";
+import { bundleModules } from "./modules.js";
+import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
+import type { CompileStringResult } from "./options.js";
+
+/**
+ * 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()),
+  ]);
+}
+
+/** A parsed (and, for module entries, already bundled) entry file. */
+export interface ParsedEntry {
+  readonly absoluteEntry: string;
+  readonly sourceText: string;
+  readonly sourceFile: SourceFileNode;
+  /** The text the incremental cache hashes (the bundled text for modules). */
+  readonly cacheText: string;
+}
+
+/**
+ * Parse an entry file, bundling its module graph first when it uses
+ * `import`/`export`. The caller owns `diagnostics` and must not run code
+ * generation when it has errors (the tree would be missing nodes).
+ */
+export function parseEntry(
+  entryPath: string,
+  registry: ExtensionRegistry,
+  diagnostics: DiagnosticBag,
+): ParsedEntry {
+  const absoluteEntry = resolve(entryPath);
+  const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
+  const file = new SourceFile(absoluteEntry, sourceText);
+  const parser = new Parser(file, diagnostics);
+  let sourceFile = parser.parseSourceFile();
+  const isModule = sourceFile.statements.some(
+    (statement) =>
+      statement.kind === SyntaxKind.ImportDeclaration ||
+      statement.kind === SyntaxKind.ExportDeclaration ||
+      statement.kind === SyntaxKind.ExportAssignment,
+  );
+  let cacheText = sourceText;
+  if (isModule) {
+    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry), registry.assetLoaders());
+    if (bundled) {
+      sourceFile = bundled.sourceFile;
+      cacheText = bundled.text;
+    }
+  }
+  return { absoluteEntry, sourceText, sourceFile, cacheText };
+}
+
+/** Compile TypeScript source text to LLVM IR without touching the toolchain. */
+export function compileString(
+  source: string,
+  fileName = "input.ts",
+  extensions?: ExtensionRegistry,
+  options: { readonly debug?: boolean } = {},
+): CompileStringResult {
+  const file = new SourceFile(fileName, source);
+  const diagnostics = new DiagnosticBag();
+  const parser = new Parser(file, diagnostics);
+  const sourceFile = parser.parseSourceFile();
+  const registry = extensions ?? createDefaultRegistry();
+  /* Code generation assumes a well-formed tree (binder and codegen both read
+   * required children), so never lower a file that already failed to parse. */
+  if (diagnostics.hasErrors) return { ir: "", diagnostics: diagnostics.diagnostics };
+  const { ir } = generate(sourceFile, diagnostics, {
+    builtins: registry.builtins(),
+    modules: registry.modules(),
+    moduleHints: registry.moduleHints(),
+    debug: options.debug === true,
+  });
+  return { ir, diagnostics: diagnostics.diagnostics };
+}
+
+/**
+ * Compile a file to LLVM IR, bundling every reachable relative module first so
+ * that imports from other TypeScript sources resolve exactly like `build`.
+ */
+export function compileEntry(
+  entryPath: string,
+  extensions?: ExtensionRegistry,
+  options: { readonly debug?: boolean } = {},
+): CompileStringResult {
+  const registry = extensions ?? createDefaultRegistry();
+  const diagnostics = new DiagnosticBag();
+  const parsed = parseEntry(entryPath, registry, diagnostics);
+  if (diagnostics.hasErrors) return { ir: "", diagnostics: diagnostics.diagnostics };
+  const { ir } = generate(parsed.sourceFile, diagnostics, {
+    builtins: registry.builtins(),
+    modules: registry.modules(),
+    moduleHints: registry.moduleHints(),
+    debug: options.debug === true,
+  });
+  return { ir, diagnostics: diagnostics.diagnostics };
+}