One bindgen: replace bindgen v1 and v2, add classes, generate the Rust side

.claude/skills/implementing-jsc-classes-rust/SKILL.md

@@ -18,7 +18,7 @@ Bridge JavaScript and Rust through `.classes.ts` definitions and Rust implementa
 ```typescript
 export default [
   define({
-    name: "Glob",
+    name: "Matcher",
     construct: true,
     finalize: true,
     hasPendingActivity: true,
@@ -45,16 +45,16 @@ use bun_jsc::{CallFrame, JSGlobalObject, JSValue, JsResult};
 use std::sync::atomic::{AtomicUsize, Ordering};
 
 #[bun_jsc::JsClass]
-pub struct Glob {
+pub struct Matcher {
     pattern: Box<[u8]>,
     has_pending_activity: AtomicUsize,
 }
 
-impl Glob {
-    pub fn constructor(global: &JSGlobalObject, frame: &CallFrame) -> JsResult<Box<Glob>> {
+impl Matcher {
+    pub fn constructor(global: &JSGlobalObject, frame: &CallFrame) -> JsResult<Box<Matcher>> {
         let arg = frame.argument(0);
         let pattern = bun_core::String::from_js(arg, global)?.to_utf8_bytes().into();
-        Ok(Box::new(Glob { pattern, has_pending_activity: AtomicUsize::new(0) }))
+        Ok(Box::new(Matcher { pattern, has_pending_activity: AtomicUsize::new(0) }))
     }
 
     #[bun_jsc::host_fn(method)]
@@ -88,7 +88,7 @@ A missing or mis-typed hook is a **compile error** in `cargo check -p bun_runtim
 The codegen also emits a `js_$T` module with the cached-value accessors. Re-export it when you need `*_set_cached` / `*_get_cached` or `detach_ptr`:
 
 ```rust
-pub use crate::generated_classes::js_Glob as js;
+pub use crate::generated_classes::js_Image as js;
 // or
 bun_jsc::impl_js_class_via_generated!(Archive => crate::generated_classes::js_Archive);
 ```
@@ -124,7 +124,7 @@ Never store raw `JSValue` in a struct field. Declare a slot in `.classes.ts` (`v
 
 ## Reference implementations
 
-- `src/runtime/api/glob.rs` + `Glob.classes.ts` — constructor, methods, `hasPendingActivity`, default finalize
+- `src/runtime/api/Shell.classes.ts` — constructor, methods, `hasPendingActivity`
 - `src/runtime/api/cron.rs` + `cron.classes.ts` — `noConstructor`, cached getter, `values: [...]`, custom finalize
 - `src/runtime/image/Image.rs:56` — the `pub use crate::generated_classes::js_Image as js;` one-liner
 - `src/jsc/host_fn.rs` — the host-fn adapters the codegen dispatches through

.github/workflows/rust-lints.yml

@@ -10,6 +10,7 @@ on:
       - "src/**/*.rs"
       - "src/**/Cargo.toml"
       - "src/**/*.classes.ts"
+      - "src/**/*.bind.ts"
       - "src/codegen/**"
       - "scripts/build/**"
       - "scripts/build.ts"

.prettierrc

@@ -20,12 +20,6 @@
         "printWidth": 80
       }
     },
-    {
-      "files": ["src/codegen/bindgenv2/**/*.ts", "*.bindv2.ts"],
-      "options": {
-        "printWidth": 100
-      }
-    },
     {
       "files": ["src/runtime/cli/init/**"],
       "options": {

CLAUDE.md

@@ -165,6 +165,7 @@ When implementing JavaScript classes in C++:
 
 Code generation happens automatically as part of the build process. The main scripts are:
 
+- `src/codegen/bindgen.ts` - Generates Rust, C++ & TypeScript bindings from `*.bind.ts` files (`docs/project/bindgen.mdx`)
 - `src/codegen/generate-classes.ts` - Generates Rust & C++ bindings from `*.classes.ts` files
 - `src/codegen/generate-jssink.ts` - Generates stream-related classes
 - `src/codegen/bundle-modules.ts` - Bundles built-in modules like `node:fs`

mordant-baseline.toml

@@ -67,7 +67,6 @@
 "defaulted_failure:src/jsc/ConsoleObject.rs" = 4
 "generic_body_not_generic:src/jsc/ConsoleObject.rs" = 6
 "generic_body_not_generic:src/jsc/JSPropertyIterator.rs" = 1
-"unused_pub:src/jsc/bindgen.rs" = 6
 "unused_pub:src/jsc/host_fn.rs" = 2
 "unused_pub:src/jsc/lib.rs" = 1
 

scripts/build/CLAUDE.md

@@ -185,7 +185,7 @@ CI's `build-bun` step builds the same graph (`ci-build` profile: release, prebui
 
 `--mode=codegen` configures a graph of the codegen steps only, default target `codegen`, for what needs their outputs and no binary. It has a build directory of its own (`build/debug-codegen`): its manifest and `compile_commands.json` have no native edges in them, and `build/debug` is where clangd reads `compile_commands.json`. `bun run build:types` (`--mode=codegen --target=generated-types`) is what `lint.yml` runs before typechecking `src/js`.
 
-**`build/types/` (`cfg.typesDir`)** holds the type declarations `src/js/builtins.d.ts` references: `generated.d.ts`, `ErrorCode.d.ts`, `ZigGeneratedClasses.d.ts`, `WebCoreJSBuiltins.d.ts`. They are made from source alone (byte-identical between debug and release), so they do not live under a profile's build directory: every profile's graph declares the same files there, the way a dep's `vendor/<name>/.ref` is, and any build keeps them current for the editor. They are declared outputs of the edges that write them (`CodegenOutputs.generatedTypes`, target `generated-types`), so ninja regenerates one that is deleted or whose edge inputs changed. `src/runtime/bake/generated.ts` (the dev server's message enums, which the bake project imports) is in the same target, declared by the bake codegen edge that writes it.
+**`build/types/` (`cfg.typesDir`)** holds the type declarations `src/js/builtins.d.ts` references: `generated.d.ts`, `ErrorCode.d.ts`, `ZigGeneratedClasses.d.ts`, `WebCoreJSBuiltins.d.ts`, `Bindgen.d.ts`. They are made from source alone (byte-identical between debug and release), so they do not live under a profile's build directory: every profile's graph declares the same files there, the way a dep's `vendor/<name>/.ref` is, and any build keeps them current for the editor. They are declared outputs of the edges that write them (`CodegenOutputs.generatedTypes`, target `generated-types`), so ninja regenerates one that is deleted or whose edge inputs changed. `src/runtime/bake/generated.ts` (the dev server's message enums, which the bake project imports) is in the same target, declared by the bake codegen edge that writes it.
 
 It is configured by `configureCodegen()`, not `configure()`, and resolves a `CodegenConfig`, not a `Config`:
 

scripts/build/bun.ts

@@ -316,7 +316,6 @@ export function emitBun(n: Ninja, cfg: Config, sources: Sources): BunOutput {
 
   // Codegen .cpp files — compiled like regular sources.
   cxxSources.push(...codegen.cppSources);
-  cxxSources.push(...codegen.bindgenV2Cpp);
 
   // All deps must be ready (headers extracted, libs built) before compile.
   //

scripts/build/codegen.ts

@@ -10,10 +10,6 @@
  * configure time via `globAllSources()`. The expanded
  * paths are baked into build.ninja; adding a file picks up on next configure.
  *
- * bindgenv2 is special: its output set is dynamic (depends on which types
- * the .bindv2.ts files export). We invoke it with `--command=list-outputs`
- * at CONFIGURE time to get the actual output paths.
- *
  * ## Undeclared outputs
  *
  * Every generated file that is compiled or #included must be a declared
@@ -22,7 +18,7 @@
  * depfile entry does that within the same run only if it names a declared
  * output, which ninja re-stats after the step ran. A file no edge declares
  * is stat'd once at startup, so a compile that includes it picks up a rerun
- * of the step one build late. That is why emitBindgen/emitBindgenV2 declare
+ * of the step one build late. That is why emitBindgen declares
  * the per-file Generated*.h headers and not just the .cpp that gets compiled.
  *
  * Files nothing compiles may stay undeclared (bundle-modules' eval/ dir,
@@ -32,8 +28,7 @@
  * reached through the PCH.
  */
 
-import { spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, dirname, relative, resolve } from "node:path";
 import type { Sources } from "../glob-sources.ts";
 import { generateBuildOptionsRs } from "./buildOptionsRs.ts";
@@ -245,8 +240,8 @@ export interface CodegenOutputs {
   cppHeaders: string[];
 
   /**
-   * ALL cpp-relevant codegen outputs — the union of cppHeaders, cppSources,
-   * bindgenV2Cpp. cxx compilation order-depends on THIS (not `all`): cxx
+   * ALL cpp-relevant codegen outputs — the union of cppHeaders and
+   * cppSources. cxx compilation order-depends on THIS (not `all`): cxx
    * doesn't need bake.*.js, runtime.out.js, or any other rust-side embedded
    * outputs: those are inputs of the Rust crates, not of any C++ object.
    *
@@ -256,9 +251,6 @@ export interface CodegenOutputs {
    */
   cppAll: string[];
 
-  /** The bindgenv2 .cpp outputs (compiled separately from handwritten C++). */
-  bindgenV2Cpp: string[];
-
   /**
    * The InternalModuleRegistryConstants.S path — compiled via cc() in bun.ts
    * and linked alongside the C++ objects. Carries the concatenated JS module
@@ -299,7 +291,6 @@ export function emitCodegen(n: Ninja, cfg: CodegenFields, sources: Sources): Cod
     cppSources: [],
     cppHeaders: [],
     cppAll: [],
-    bindgenV2Cpp: [],
     internalModulesAsm: resolve(cfg.codegenDir, "InternalModuleRegistryConstants.S"),
     internalModulesBin: resolve(cfg.codegenDir, "InternalModuleRegistryConstants.bin"),
     rootInstall,
@@ -335,7 +326,6 @@ export function emitCodegen(n: Ninja, cfg: CodegenFields, sources: Sources): Cod
   emitCppBind(ctx);
   emitJsModules(ctx);
   emitBakeCodegen(ctx);
-  emitBindgenV2(ctx);
   emitBindgen(ctx);
   emitJsSink(ctx);
   emitObjectLuts(ctx);
@@ -347,7 +337,7 @@ export function emitCodegen(n: Ninja, cfg: CodegenFields, sources: Sources): Cod
   n.blank();
 
   // Assemble cppAll — the cxx-relevant subset. See field docstring.
-  o.cppAll = [...new Set([...o.cppHeaders, ...o.cppSources, ...o.bindgenV2Cpp])];
+  o.cppAll = [...new Set([...o.cppHeaders, ...o.cppSources])];
 
   return o;
 }
@@ -880,7 +870,7 @@ function emitJsModules({ n, cfg, sources, o, dirStamp }: Ctx): void {
       desc: "JS modules (bundle-modules)",
       // Note: arg is BUILD_PATH (buildDir), not CODEGEN_PATH. The script
       // derives CODEGEN_DIR = join(BUILD_PATH, "codegen") internally.
-      args: shJoin(cfg, ["run", script, debugFlag(cfg), cfg.buildDir, cfg.typesDir]),
+      args: shJoin(cfg, ["run", script, debugFlag(cfg), cfg.buildDir, cfg.typesDir, typesOnlyFlag(cfg, sources)]),
     },
   });
 
@@ -931,99 +921,85 @@ function emitBakeCodegen({ n, cfg, sources, o, dirStamp }: Ctx): void {
   o.rustInputs.push(...outputs);
 }
 
-/** Exported (with emitBindgen) for test/internal/build-codegen-declared-outputs.test.ts. */
-export function emitBindgenV2({ n, cfg, sources, o, dirStamp }: Ctx): void {
-  const script = resolve(cfg.cwd, "src", "codegen", "bindgenv2", "script.ts");
-
-  // The script's output set depends on which NamedTypes the .bindv2.ts files
-  // export. We run `--command=list-outputs` SYNCHRONOUSLY at configure time
-  // to get the real list. This is a configure-time dependency on the
-  // sources — same tradeoff CMake makes with execute_process().
-  //
-  // It runs with cfg.jsRuntime, the runtime that runs configure. It is a
-  // child process, not an import: in this process, node would print
-  // MODULE_TYPELESS_PACKAGE_JSON for the .ts files under src/. cfg.jsRuntime
-  // is a shell command prefix, so the command goes through the host shell.
-  //
-  // If list-outputs fails (e.g. syntax error in a .bindv2.ts file), we fail
-  // configure immediately with a clear error. Better to catch that here than
-  // get a cryptic "multiple rules generate <unknown>" from ninja.
-  const sourcesArg = sources.bindgenV2.join(",");
-  const listArgs = [script, "--command=list-outputs", `--sources=${sourcesArg}`, `--codegen-path=${cfg.codegenDir}`];
-  const listResult = spawnSync(`${cfg.jsRuntime} ${shJoin(cfg, listArgs)}`, {
-    cwd: cfg.cwd,
-    encoding: "utf8",
-    shell: true,
-  });
-  if (listResult.status !== 0) {
-    throw new BuildError(`bindgenv2 list-outputs failed (exit ${listResult.status})`, {
-      file: script,
-      hint: listResult.stderr?.trim(),
-    });
-  }
-  // Output is semicolon-separated (CMake list format).
-  const allOutputs = listResult.stdout
-    .trim()
-    .split(";")
-    .filter(p => p.length > 0);
-
-  assert(allOutputs.length > 0, "bindgenv2 list-outputs returned no files");
-
-  const cppOutputs = allOutputs.filter(p => p.endsWith(".cpp"));
-  const headerOutputs = allOutputs.filter(p => p.endsWith(".h"));
-  const other = allOutputs.filter(p => !p.endsWith(".cpp") && !p.endsWith(".h"));
-  assert(other.length === 0, `bindgenv2 emitted unexpected output type: ${other.join(", ")}`);
-
-  n.build({
-    outputs: allOutputs,
-    rule: "codegen",
-    inputs: [script, ...sources.bindgenV2, ...sources.bindgenV2Internal],
-    orderOnlyInputs: [dirStamp],
-    vars: {
-      cwd: cfg.cwd,
-      desc: "bindgenv2",
-      args: shJoin(cfg, [script, "--command=generate", `--codegen-path=${cfg.codegenDir}`, `--sources=${sourcesArg}`]),
-    },
-  });
+/** A `*_test.bind.ts` binds what exists for tests. Only a build where Rust has `debug_assertions` has it, and none ships. */
+function isCompiled(cfg: CodegenFields, src: string): boolean {
+  return cfg.debug || cfg.assertions || !src.endsWith("_test.bind.ts");
+}
 
-  o.all.push(...allOutputs);
-  o.bindgenV2Cpp.push(...cppOutputs);
-  o.cppHeaders.push(...headerOutputs);
+function typesOnlyFlag(cfg: CodegenFields, sources: Sources): string {
+  return `--types-only=${sources.bindgen
+    .filter(src => !isCompiled(cfg, src))
+    .map(src => basename(src))
+    .join(",")}`;
 }
 
+/** Exported for test/internal/build-codegen-declared-outputs.test.ts. */
 export function emitBindgen({ n, cfg, sources, o, dirStamp }: Ctx): void {
   const script = resolve(cfg.cwd, "src", "codegen", "bindgen.ts");
-
-  const cppOut = resolve(cfg.codegenDir, "GeneratedBindings.cpp");
-  // Plus one header per .bind.ts (node_os.bind.ts → GeneratedNodeOs.h), which
-  // hand-written .cpp files include; see "Undeclared outputs" above.
-  const headers = sources.bindgen.map(src =>
-    resolve(cfg.codegenDir, `Generated${pascalCase(basename(src, ".bind.ts"))}.h`),
+  const crates = new Map(sources.bindgen.map(src => [src, crateOf(src)]));
+  const compiled = sources.bindgen.filter(src => isCompiled(cfg, src));
+
+  // What bindgen.ts writes follows from the names and places of its inputs alone.
+  const outputNames = compiled.map(src => `Generated${pascalCase(basename(src, ".bind.ts"))}`);
+  outputNames.forEach((name, i) => {
+    const first = outputNames.indexOf(name);
+    if (first !== i) throw new BuildError(`${compiled[first]} and ${compiled[i]} both generate ${name}.h`);
+  });
+  const cpp = outputNames.map(name => resolve(cfg.codegenDir, `${name}.cpp`));
+  const headers = [
+    ...outputNames.map(name => resolve(cfg.codegenDir, `${name}.h`)),
+    resolve(cfg.codegenDir, "GeneratedBindings+Tables.h"),
+    resolve(cfg.codegenDir, "GeneratedBindings+Counts.h"),
+  ];
+  const rust = [...new Set(compiled.map(src => crates.get(src)))].map(crate =>
+    resolve(cfg.codegenDir, `generated_bindgen_${crate}.rs`),
   );
+  const types = resolve(cfg.typesDir, "Bindgen.d.ts");
 
-  // bindgen.ts scans src/ for .bind.ts files itself; this list only tells
-  // ninja the inputs and which headers come out. New .bind.ts files need a
-  // reconfigure to be picked up (next glob gets them).
   n.build({
-    outputs: [cppOut, ...headers],
-    rule: "codegen_bun",
-    inputs: [script, ...sources.bindgen],
+    outputs: [...cpp, ...headers, ...rust, types],
+    rule: "codegen",
+    inputs: [...sources.bindgen, ...sources.bindgenCodegen],
     orderOnlyInputs: [dirStamp],
     vars: {
       cwd: cfg.cwd,
-      desc: ".bind.ts → GeneratedBindings.cpp",
-      args: shJoin(cfg, ["run", script, debugFlag(cfg), `--codegen-root=${cfg.codegenDir}`]),
+      desc: ".bind.ts → Generated*.{cpp,h}, generated_bindgen_*.rs",
+      args: shJoin(cfg, [
+        script,
+        // Every schema: build/types is shared by every profile, so Bindgen.d.ts describes them all.
+        `--sources=${sources.bindgen.map(src => `${crates.get(src)}=${src}`).join(",")}`,
+        typesOnlyFlag(cfg, sources),
+        `--codegen-path=${cfg.codegenDir}`,
+        `--types-path=${cfg.typesDir}`,
+      ]),
     },
   });
 
-  o.all.push(cppOut, ...headers);
-  o.cppSources.push(cppOut);
+  o.all.push(...cpp, ...headers, ...rust, types);
+  o.generatedTypes.push(types);
+  o.rustInputs.push(...rust);
+  o.cppSources.push(...cpp);
   o.cppHeaders.push(...headers);
 }
 
-/** Same transform as `pascal()` in src/codegen/bindgen-lib-internal.ts: `node_os` → `NodeOs`. */
+/** `node_os` → `NodeOs`. A copy of `pascalCase()` in src/codegen/bindgen-lib-internal.ts, which node warns about importing here (MODULE_TYPELESS_PACKAGE_JSON). build-codegen-declared-outputs.test.ts holds the two together. */
 function pascalCase(s: string): string {
-  return s[0]!.toUpperCase() + s.slice(1).replace(/[_-](\w)?/g, (_, c?: string) => c?.toUpperCase() ?? "");
+  return s
+    .split(/[^A-Za-z0-9]+/)
+    .filter(part => part.length > 0)
+    .map(part => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/** The Cargo package whose directory contains `file`. */
+function crateOf(file: string): string {
+  for (let dir = dirname(file); dir !== dirname(dir); dir = dirname(dir)) {
+    const manifest = resolve(dir, "Cargo.toml");
+    if (!existsSync(manifest)) continue;
+    const name = /^\s*name\s*=\s*"([^"]+)"/m.exec(readFileSync(manifest, "utf8"));
+    if (name) return name[1]!;
+  }
+  throw new BuildError(`${file} is not inside a Cargo package`);
 }
 
 function emitJsSink({ n, cfg, o, dirStamp }: Ctx): void {

scripts/glob-sources.ts

@@ -67,17 +67,13 @@ const patterns = {
     paths: ["src/runtime/bake/*.ts", "src/runtime/bake/*/*.{ts,css}", "src/runtime/bake/dev_server/mod.rs"],
     exclude: ["src/runtime/bake/generated.ts"],
   },
-  /** legacy bindgen input */
+  /** bindgen input */
   bindgen: {
     paths: ["src/**/*.bind.ts"],
   },
-  /** v2 bindgen input */
-  bindgenV2: {
-    paths: ["src/**/*.bindv2.ts"],
-  },
-  /** bindgen v2 generator code */
-  bindgenV2Internal: {
-    paths: ["src/codegen/bindgenv2/**/*.ts"],
+  /** bindgen generator code */
+  bindgenCodegen: {
+    paths: ["src/codegen/bindgen*.ts", "src/codegen/helpers.ts"],
   },
   /**
    * all `*.rs` + workspace manifests — implicit inputs to the cargo step.
@@ -101,6 +97,7 @@ const patterns = {
       "src/io/*.cpp",
       "src/jsc/modules/*.cpp",
       "src/jsc/bindings/*.cpp",
+      "src/jsc/bindings/Bindgen/*.cpp",
       "src/jsc/bindings/webcore/*.cpp",
       "src/jsc/bindings/webcore/streams/*.cpp",
       "src/jsc/bindings/sqlite/*.cpp",