refactor: comprehensive source code reorganization for guessability

[robobun]

Summary

This PR reorganizes the Bun source code to make file locations guessable. The goal: Claude (or any developer) should be able to guess where code lives without searching.

Key Changes

• Renamed src/bun.js/ → src/buntime/ - More intuitive name for the JavaScript runtime
• Created src/transpiler/ - Moved JS/TS transpiler (parser, lexer, printer) from root
• Created src/test_runner/ - Moved test runner from buntime/test/
• Dissolved bindings/ - Split ~150 files into domain-specific directories
• Dissolved webcore/ - Moved to appropriate web/ subdirectories
• Organized node/ - Created subdirectories for buffer, process, vm, crypto, etc.
• Created jsc/ - Organized JSC integration into types/, global/, gc/, interop/, generated/
• Created compat/ - Grouped napi/, v8/, libuv/, windows/
• Moved event_loop/ - Now at buntime/ root level

New Directory Structure

src/
├── transpiler/           # JS/TS transpiler
├── test_runner/          # bun:test
├── bundler/              # bun build
├── install/              # Package manager
├── css/                  # CSS parser
├── shell/                # Bun.$
└── buntime/              # JavaScript runtime
    ├── api/              # Bun.* APIs (server, console, ffi, sqlite, etc.)
    ├── web/              # Web Standards (fetch, url, blob, streams, etc.)
    ├── node/             # Node.js compat (buffer, process, crypto, etc.)
    ├── compat/           # Native addons (napi, v8, libuv)
    ├── jsc/              # JSC integration (types, global, gc, interop)
    ├── module/           # Module system
    └── event_loop/       # Event loop

Guessability Table

Task	Location
Fix the transpiler	src/transpiler/
Fix Bun.serve()	src/buntime/api/server/
Fix fetch()	src/buntime/web/fetch/
Fix node:crypto	src/buntime/node/crypto/
Fix N-API	src/buntime/compat/napi/
Fix V8 compat	src/buntime/compat/v8/

Stats

• 114 commits
• 1717 files changed
• All imports and build configuration updated
• Documentation paths fixed in .md files
• CMake duplicate/invalid path issues fixed

Test plan

• bun bd builds successfully
• All directory structure matches PLAN.md
• No stray files in old locations (bindings/, webcore/)
• CLAUDE.md updated with new structure

🤖 Generated with Claude Code

[robobun]

^{Updated 2:00 AM PT - Dec 31st, 2025}

❌ Your commit c2403a8d has 7 failures in Build #33915 (All Failures):

• test/js/bun/shell/bunshell.test.ts - 1 failing on 🍎 13 aarch64
• test/js/bun/shell/bunshell.test.ts - 1 failing on 🍎 14 aarch64
• test/js/bun/shell/bunshell.test.ts - 1 failing on 🍎 14 x64
• test/js/bun/shell/bunshell.test.ts - 1 failing on 🍎 13 x64
• test/js/bun/util/zstd.test.ts - code 1 on 🍎 13 aarch64
• test/js/bun/util/zstd.test.ts - code 1 on 🍎 14 aarch64
• test/js/bun/util/zstd.test.ts - code 1 on 🍎 14 x64
• test/js/bun/util/zstd.test.ts - code 1 on 🍎 13 x64
• test/internal/ban-words.test.ts - code 1 on 🍎 13 aarch64
• test/internal/ban-words.test.ts - code 1 on 🍎 14 aarch64
• test/internal/ban-words.test.ts - code 1 on 🍎 14 x64
• test/internal/ban-words.test.ts - code 1 on 🍎 13 x64
• test/integration/next-pages/test/dev-server.test.ts - 1 failing on 🍎 13 aarch64
• test/integration/next-pages/test/dev-server.test.ts - 1 failing on 🍎 14 aarch64
• ../../../vendor/tinycc/tccasm.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/tccrun.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/i386-asm.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/tccdbg.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/x86_64-gen.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/tccpp.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/tccelf.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/tccgen.c - clang warning on 🐧 x64 - build-cpp
• ../../../vendor/tinycc/tccasm.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/i386-asm.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/tccrun.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/tccdbg.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/x86_64-gen.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/tccelf.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/tccpp.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/tccgen.c - clang warning on 🐧 x64-baseline - build-cpp
• ../../../vendor/tinycc/arm64-asm.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccrun.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccdbg.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccasm.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/arm64-gen.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccpp.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccelf.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccgen.c - clang warning on 🐧 aarch64 - build-cpp
• ../../../vendor/tinycc/tccasm.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/tccrun.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/i386-asm.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/x86_64-gen.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/tccpp.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/tccdbg.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/tccelf.c - clang warning on 🐧 x64-asan - build-cpp
• ../../../vendor/tinycc/tccgen.c - clang warning on 🐧 x64-asan - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🐧 aarch64-musl - build-cpp
• CMakeLists.txt - cmake warning on 🐧 aarch64-musl - build-cpp
• CMakeLists.txt - cmake warning on 🐧 aarch64-musl - build-cpp
• CMakeLists.txt - cmake warning on 🐧 aarch64 - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-musl - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-musl - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-musl - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-musl-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-musl-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-musl-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64 - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🪟 x64-baseline - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-asan - build-cpp
• CMakeLists.txt - cmake warning on 🐧 x64-asan - build-cpp
• scripts/build.mjs - build failed on 🐧 x64-asan - build-zig

---

🧪   To try this PR locally:

bunx bun-pr 25781

That installs a local version of the PR into your bun-25781 executable, so you can run:

bun-25781 --bun

[coderabbitai]

Walkthrough

Large-scale repository reorganization: files and imports moved from src/bun.js/... into a new src/buntime/... tree; src/transpiler/ and src/test_runner/ subtrees added. Numerous Zig, C/C++, CMake, and JS paths updated to the new layout; no substantive logic changes reported.

Changes

Cohort / File(s)	Summary
Planning & Documentation PLAN.md, CLAUDE.md, .claude/commands/upgrade-nodejs.md, .claude/skills/implementing-jsc-classes-cpp/SKILL.md, .claude/skills/implementing-jsc-classes-zig/SKILL.md, src/AGENTS.md, src/buntime/STREAMS.md	Adds reorg plan and docs; updates many docs/comments to reference buntime and new top-level layout.
Build config & source lists cmake/Sources.json, cmake/analysis/RunClangFormat.cmake, cmake/targets/BuildBun.cmake, cmake/targets/BuildSQLite.cmake, cmake/tools/SetupBun.cmake, build.zig	Redirects build globs, include groups and CMake targets from src/bun.js/... to src/buntime/...; adjusts source lists and clang-format globs.
Package scripts package.json	Updates uv-posix-stubs script to point at src/buntime/compat/libuv/generate_uv_posix_stubs.ts.
Core Zig entrypoints & exports src/bun.zig, src/bun.js.zig, src/ast.zig	Public imports/exports repointed to buntime and transpiler subpaths (jsc, webcore, api, bindgen, transpiler, parser/printer/lexer).
Transpiler & bundler imports src/ast/Expr.zig, src/bundler/LinkerContext.zig, src/bundler/bundle_v2.zig	Moves js_printer/js_parser/js_lexer imports into transpiler/ subdirectory; updates exported constants to new import paths.
BoringSSL / crypto imports src/boringssl.zig	X509 import path updated to ./buntime/api/bun/x509.zig.
Buntime API & JS bindings src/buntime/api.zig, src/buntime/api/BunObject.zig, src/buntime/api/FFI.h, src/buntime/api/ffi.zig, src/buntime/api/ffi/FFI.zig, src/buntime/api/BunProcess.cpp, src/buntime/api/s3/*.classes.ts	Adjusts many API import paths and local includes/comments to reflect new nested layout (BuildMessage, ResolveMessage, Sizes, Jest.call, FFI comments, etc.).
Timer / Inspector / IPC / Spawn modules src/buntime/api/Timer/*.zig, src/buntime/api/inspector/Debugger.zig, src/buntime/api/bun/js_bun_spawn_bindings.zig, src/buntime/api/bun/subprocess.zig, src/buntime/api/ipc/ipc.zig	Updates Debugger, agent, and IPC/spawn module import paths into inspector/, server/, and ipc/ subtrees.
Console / test-runner references src/buntime/api/console/ConsoleObject.zig, src/buntime/api/BunObject.zig	Repoints Visited.ObjectPool, CLI, JestPrettyFormat, and BunObject.jest to relocated test_runner and pool/cli modules.
Libuv headers rework src/bun.js/bindings/libuv/* (many removed), src/buntime/compat/libuv/uv.h, src/buntime/compat/libuv/*	Removes old bun.js libuv headers and platform-specific trees; adds comprehensive new src/buntime/compat/libuv/uv.h and platform headers (aix, etc.).
Stdatomic replacement src/bun.js/api/ffi-stdatomic.h (removed), src/buntime/api/ffi-stdatomic.h (added)	Deletes old stdatomic header under bun.js and adds a self-contained stdatomic-like header under buntime/api.
Clang-format ignore / cleanup src/bun.js/bindings/.clang-format-ignore, src/bun.js/bindings/v8/AGENTS.md	Removes two ignore patterns and deletes an obsolete doc file in the old bun.js tree.
Misc path fixes & formatting cmake/Sources.json (JS/C/Cxx lists), src/buntime/api/ffi-stddef.h, src/buntime/compat/libuv/aix.h, various Zig files	Formatting tweaks and numerous relative-import path adjustments across Zig/C headers (no behavioral changes).

Possibly related PRs

• Implement isolated event loop for spawnSync #24436 — touches spawn/SpawnSync and event-loop spawn bindings that this PR relocates into src/buntime/api/bun/ (strong code-level overlap).
• gitignore the sources text files #22408 — modifies build source lists/CMake source enumeration; overlaps with this PR's cmake/Sources.json and build-list changes.
• Implement --cpu-prof CLI flag #24112 — modifies CPU profiler integration; overlaps with this PR's BunCPUProfiler import/path moves into buntime/api/inspector/.

Suggested reviewers

• alii
• pfgithub
• taylordotfish
• zackradisic
• Jarred-Sumner

Pre-merge checks

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'refactor: comprehensive source code reorganization for guessability' is specific, clear, and directly reflects the main objective of the PR—a major reorganization of source code structure for improved navigability.
Description check	✅ Passed	The description comprehensively covers all required sections: it explains what the PR does (source reorganization for guessability), includes a detailed guessability table mapping tasks to locations, documents the new directory structure with a visual tree, and provides test/verification evidence (build success, directory structure validation).

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add languages to new fenced code blocks to satisfy markdownlint

markdownlint is flagging several of the newly-added fenced blocks (directory tree and command snippets) for missing languages (MD040). To keep docs lint‑clean and improve rendering, consider:

• Using ```text (or ```plaintext) for the directory tree under “Top-Level Source Organization”.
• Using ```bash for shell command examples (e.g., the bun bd verification snippet).
• Using an appropriate language (e.g., ```zig) if you later add Zig examples to these sections.

This is purely documentation hygiene; structure and content look good.

Also applies to: 220-229

🧰 Tools

🪛 markdownlint-cli2 (0.18.1)

164-164: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

176-176: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

185-185: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

196-196: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

208-208: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

In CLAUDE.md around lines 140-218 (and also lines 220-229), the newly added
fenced code blocks lack language tags which triggers markdownlint MD040; update
the blocks by adding appropriate language identifiers — use ```text or
```plaintext for the directory tree block, use ```bash for any shell/command
snippets (e.g., bun bd verification), and use ```zig (or another specific
language) if you later add Zig examples — apply these changes to each offending
fenced block in the specified ranges.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Confirm clang-format header coverage after tree move

BUN_H_SOURCES now globs only:

• src/buntime/bindings/*.h
• src/bruntime/modules/*.h

This matches the new layout, but any headers in other new trees (e.g. api/, jsc/, compat/, etc.) will not be picked up by clang-format via this target. Please double‑check that these are the only header roots you intend to format here, or expand the glob patterns if more .h locations exist.

🤖 Prompt for AI Agents

In cmake/analysis/RunClangFormat.cmake around lines 4-5, the current globs only
include ${CWD}/src/buntime/bindings/*.h and ${CWD}/src/buntime/modules/*.h which
will miss headers moved into other roots (api/, jsc/, compat/, etc.); verify the
full set of header root directories that should be formatted and either add
explicit glob entries for each missing root (for example api/**/*.h, jsc/**/*.h,
compat/**/*.h) or broaden the pattern (e.g., src/**/*.h) to cover all expected
.h locations, ensuring the paths match the actual directory names in the tree.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Tighten a couple of path references for consistency in the plan

• In the “Fix S3” row, all other locations are rooted at src/…, but the second location is buntime/api/s3/. Consider making it src/buntime/api/s3/ so it visually matches the rest of the table and CLAUDE.md.
• In the “Don’t Forget” section, bun-spawn.cpp, spawn.cpp → api/bun/spawn/ doesn’t correspond to a documented subdirectory in the buntime/api tree above. If the intent is to eventually have src/buntime/api/bun/spawn/, it may help to spell that out explicitly; otherwise, rephrase to match the actual destination directory name you plan to use.

Also applies to: 1107-1112

🤖 Prompt for AI Agents

In PLAN.md around lines 15 to 21 (and also apply same change to lines 1107 to
1112), tighten path references for consistency by changing the “Fix S3” second
location from buntime/api/s3/ to src/buntime/api/s3/ so it matches the other
src/... roots and CLAUDE.md, and update the “Don’t Forget” entry mapping
bun-spawn.cpp, spawn.cpp → api/bun/spawn/ to the explicit intended destination
(for example src/buntime/api/bun/spawn/) or rephrase it to match the actual
directory you plan to use; make the edits so all table rows and the “Don’t
Forget” line use consistent src/ rooted paths and accurate target directories.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, let's check if SerializedScriptValue.h exists and where it's located
find . -name "SerializedScriptValue.h" -type f 2>/dev/null

Repository: oven-sh/bun

Length of output: 110

---

🏁 Script executed:

# Check the BunProcess.cpp file, specifically lines 50-55 and around line 208
wc -l src/buntime/api/process/BunProcess.cpp

Repository: oven-sh/bun

Length of output: 98

---

🏁 Script executed:

# If it's not too large, read the relevant sections
head -220 src/buntime/api/process/BunProcess.cpp | tail -175

Repository: oven-sh/bun

Length of output: 6683

---

🏁 Script executed:

# Check for llhttp directory structure
find . -type d -name "llhttp" 2>/dev/null | head -20

Repository: oven-sh/bun

Length of output: 85

---

🏁 Script executed:

# Look for CMakeLists.txt files that might configure include directories
find . -name "CMakeLists.txt" -type f 2>/dev/null | grep -E "(api|process)" | head -10

Repository: oven-sh/bun

Length of output: 94

---

🏁 Script executed:

# Find CMakeLists.txt near BunProcess.cpp
find ./src/buntime/api -name "CMakeLists.txt" -type f

Repository: oven-sh/bun

Length of output: 94

---

🏁 Script executed:

# Check if there's a CMakeLists.txt in the process directory
find ./src/buntime/api/process -type f | head -20

Repository: oven-sh/bun

Length of output: 1052

---

🏁 Script executed:

# Search for how the include directories are set up - look for files that might include BunProcess
rg "BunProcess.cpp" --type cmake

Repository: oven-sh/bun

Length of output: 131

---

🏁 Script executed:

# Verify the exact line 208 to confirm the comment
sed -n '205,210p' src/buntime/api/process/BunProcess.cpp

Repository: oven-sh/bun

Length of output: 644

---

🏁 Script executed:

# Check if README.md exists at the current path vs old path
ls -la ./src/buntime/node/http/llhttp/README.md 2>/dev/null || echo "File not found at current path"
ls -la ./src/buntime/bindings/node/http/llhttp/README.md 2>/dev/null || echo "File not found at old path"

Repository: oven-sh/bun

Length of output: 170

---

🏁 Script executed:

# Check the BuildBun.cmake file to see how include directories are set
grep -A 20 -B 5 "BunProcess.cpp" cmake/targets/BuildBun.cmake | head -50

Repository: oven-sh/bun

Length of output: 1110

---

🏁 Script executed:

# Look for include_directories or target_include_directories in BuildBun.cmake that might handle SerializedScriptValue.h
rg "include_directories|target_include_directories" cmake/targets/BuildBun.cmake -A 3 | head -60

Repository: oven-sh/bun

Length of output: 730

---

🏁 Script executed:

# Search for where SerializedScriptValue.h include paths are configured
rg "SerializedScriptValue" . --type cmake

Repository: oven-sh/bun

Length of output: 37

---

🏁 Script executed:

# Check if there's a CMakeLists.txt that might set up include paths for src/buntime/api/process
find ./src/buntime -name "CMakeLists.txt" | xargs grep -l "api/process" 2>/dev/null

Repository: oven-sh/bun

Length of output: 39

---

🏁 Script executed:

# Look for any include path configurations for web/serialization
rg "web/serialization|web.*include" . --type cmake | head -20

Repository: oven-sh/bun

Length of output: 124

---

🏁 Script executed:

# Verify the exact include directory configuration in BuildBun.cmake for web/serialization
grep -B 5 -A 5 "src/buntime/web/serialization" cmake/targets/BuildBun.cmake

Repository: oven-sh/bun

Length of output: 371

---

🏁 Script executed:

# Check if there are any other references to the old bindings path in comments
rg "bindings/node/http/llhttp" . --type cpp --type cmake | head -20

Repository: oven-sh/bun

Length of output: 168

---

🏁 Script executed:

# Verify that the new llhttp path matches the directory structure
ls -la ./src/buntime/node/http/llhttp/ | head -20

Repository: oven-sh/bun

Length of output: 524

---

Fix stale llhttp README path in comment at line 208

The comment references src/buntime/bindings/node/http/llhttp/README.md, but the file is now at src/buntime/node/http/llhttp/README.md. Update the comment to point to the correct location.

The #include "SerializedScriptValue.h" at line 52 is correct; the directory src/buntime/web/serialization is explicitly in the CMake include path for this target.

🧰 Tools

🪛 Cppcheck (2.19.0)

[information] 52-52: Include file

(missingInclude)

🤖 Prompt for AI Agents

In src/buntime/api/process/BunProcess.cpp around lines 52-52, leave the #include
"SerializedScriptValue.h" unchanged (it's correct), but update the stale comment
at line ~208 that references src/buntime/bindings/node/http/llhttp/README.md to
the new path src/buntime/node/http/llhttp/README.md; open the file, locate the
comment at line 208, replace the old path with the new one, and save the file.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Style‑only edits in vendored libuv header

These changes are purely formatting/pointer‑style; the macros still expand identically and won’t affect behavior. To keep future libuv updates straightforward, consider avoiding style‑only edits in vendored headers unless you’re standardizing on a repo‑wide C style here.

🤖 Prompt for AI Agents

In src/buntime/compat/libuv/uv/aix.h around lines 25 to 30, the PR contains
style-only edits to macro formatting/pointer style in vendored libuv headers;
revert these changes so the macros exactly match the upstream libuv file
(restore original whitespace and pointer style for UV_PLATFORM_LOOP_FIELDS and
UV_PLATFORM_FS_EVENT_FIELDS) and avoid touching other vendored headers unless
you intend a repo-wide C style standardization and provide a separate, tracked
change for that.

[github-actions]

Closing this PR because it has been inactive for more than 90 days.