Lint the loader name list in bun-types and the docs against src/ast/loader.rs

[robobun]

Problem

• The public loader name list is hand-copied into packages/bun-types/bun.d.ts (type Loader, line 5555) and into three docs snippets (docs/runtime/plugins.mdx, docs/bundler/plugins.mdx, docs/bundler/index.mdx), and nothing checks the copies against pub enum Loader in src/ast/loader.rs.
• Every recent loader shipped with some copy stale: json5 (feat: add native JSON5 parser (Bun.JSON5) #26439) and md (feat(md): Zig markdown parser with Bun.markdown API #26440) never reached the union, xml (Add Bun.XML (parse/stringify) and an .xml loader #37048) reached the union but none of the docs snippets. On main today the union is missing json5 and md, and all three snippets are missing json5, md and xml, although bun build --loader .x:json5, Bun.build({ loader }) and BuildArtifact.loader all accept or produce those names on 1.4.0 (run in the details block).
• The open bundler: implement dataurl and base64 loaders #36327 repeats the pattern: it adds base64/dataurl to the union and to docs/bundler/index.mdx, not to the two plugins.mdx snippets.

Fix

• test/internal/source-lints/loader-names.test.ts derives the public names from the enum variants (strum's snake_case spelling, which is what BuildArtifact.loader reports) minus notPublic, a commented list of the variants deliberately absent from the union: base64 and dataurl (the bundler emits an empty module for them), bunsh (backs bun run x.sh), sqlite and sqlite_embedded (not declared yet; bundler: honor jsonc and sqlite_embedded in loader maps, accept every loader name in Bun.build #38247 adds them). It then asserts that LOADER_NAMES accepts each public name, that the bun.d.ts union equals the set, and that every type Loader = declaration found under docs/**/*.mdx equals it (docs/runtime/transpiler.mdx is skipped: its type Loader is the JavaScriptLoader subset). Each notPublic entry must still name a variant, so the exclusions cannot go stale either.
• Adding a loader to the union later (bundler: honor jsonc and sqlite_embedded in loader maps, accept every loader name in Bun.build #38247, bundler: implement dataurl and base64 loaders #36327) therefore fails the union check until its notPublic entry is removed, and removing the entry fails the docs check until every snippet lists it. Adding an enum variant fails all three checks until it is either listed everywhere or excluded with a reason. Each failure is a sorted-array diff naming the file.
• The stale copies are brought up to date in this PR so the lint passes: json5 and md in bun.d.ts, json5, xml and md in the three snippets. These hunks are the same lines as in bun-types: add json5 and md to the Loader union, document both loaders #38267 (and the bun.d.ts hunk as in Delete the schema::api mirror types and bun_api; one loader numbering across Rust/C++/JS #37095), so the PRs merge cleanly in either order; bun-types: add json5 and md to the Loader union, document both loaders #38267 still carries the loader documentation sections, this PR only carries what the lint needs.
• .github/workflows/source-lints.yml gains packages/bun-types/bun.d.ts and docs/**/*.mdx as triggers, because the lint reads them and the workflow is path-filtered (the whole directory runs in about 12 s). The directory README notes that a lint has to add whatever it reads there. A comment next to the enum points at the lint.
• Verified: on main's copies (git stash push -- packages/ or the unmodified docs) the lint fails with the diffs in the details block; with this PR bun test test/internal/source-lints/loader-names.test.ts passes (4 tests) and bun test test/internal/source-lints/ is 150+ green. Simulated a new variant (three failures naming it), a stale exclusion (one failure), and bundler: honor jsonc and sqlite_embedded in loader maps, accept every loader name in Bun.build #38247's union hunk with its JSDoc member comment (union failure until the exclusions go, then docs failures until the snippets list it). No runtime code changes; the src/ast/loader.rs hunk is a comment.

Background

• A loader is how Bun turns a file into a module. Its name is what users write in bun build --loader .ext:name, Bun.build({ loader: { ".ext": "name" } }), bunfig [loader] and plugin onLoad results, and what BuildArtifact.loader / OnLoadArgs.loader return. The Loader union in bun-types is the type of all of those.
• src/ast/loader.rs holds the enum (#[strum(serialize_all = "snake_case")], so SqliteEmbedded is the name sqlite_embedded) and LOADER_NAMES, the table Loader::from_string accepts. The table also has aliases (mjs, node, txt, markdown, ...), which is why the lint derives the list from the variants and only looks the canonical name up in the table.
• test/internal/source-lints/ holds tests that only read the source tree; .buildkite/ci.mjs excludes them from the binary lanes and .github/workflows/source-lints.yml runs them against a released bun, so this needs no build. Delete the schema::api mirror types and bun_api; one loader numbering across Rust/C++/JS #37095 adds loader-numbering.test.ts to the same directory for the numeric discriminant copies (C header, Rust plugin crate); this lint covers the names and does not overlap with it.

Lint output against main's copies, and the 1.4.0 runs behind the synced names

(pass) src/ast/loader.rs: notPublic only names variants of the Loader enum
(pass) src/ast/loader.rs: LOADER_NAMES accepts every public loader under its own name
(fail) packages/bun-types/bun.d.ts: the Loader union lists the public loaders
    -   "json5",
    -   "md",
(fail) docs: every `type Loader` snippet lists the public loaders
    docs/bundler/index.mdx      -  "json5",  -  "md",  -  "xml",
    docs/bundler/plugins.mdx    -  "json5",  -  "md",  -  "xml",
    docs/runtime/plugins.mdx    -  "json5",  -  "md",  -  "xml",

$ bun --version
1.4.0
$ bun build ./e.mjs --loader .j5:json5 --loader .mdx2:md --loader .xm:xml --outdir out && bun out/e.js
{"a":1,"b":[1,2]} "<h1>Title</h1>\n<p>hello</p>\n" {"r":{"a":{"@v":"1"}}}
$ # Bun.build({ entrypoints: ["./data.json5", "./doc.md", "./conf.xml"] }) -> outputs.map(o => o.loader)
[["data.js","json5"],["doc.js","md"],["conf.js","xml"]]

Why the excluded names are excluded, on 1.4.0 (Bun.build({ loader: { ".sh": name }, target: "bun" })):

base64          -> bundles, module is `var s_default = "";`      (empty-module stub, src/bundler/ParseTask.rs)
dataurl         -> bundles, module is `var s_default = "";`      (same)
sh              -> bundles as the file loader (asset copied)
bunsh           -> rejected as a loader name
sqlite          -> bundles as import.meta.require(path, { type: "sqlite" }).db, but is not in the union (#38247)
sqlite_embedded -> rejected as a loader name today (#38247)

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: df7833f6-697e-4ff0-b020-a6d3b8d98bef

📥 Commits

Reviewing files that changed from the base of the PR and between 01aa7cd and c10cd0a.

📒 Files selected for processing (8)

• .github/workflows/source-lints.yml
• docs/bundler/index.mdx
• docs/bundler/plugins.mdx
• docs/runtime/plugins.mdx
• packages/bun-types/bun.d.ts
• src/ast/loader.rs
• test/internal/source-lints/README.md
• test/internal/source-lints/loader-names.test.ts

---

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

[robobun]

Status: the lint in this PR fails against main's copies of the loader list (bun.d.ts union missing json5 and md; the three docs snippets missing json5, md and xml) and passes with the copies synced here. Run with bun test test/internal/source-lints/loader-names.test.ts, no build needed. Related in-flight PRs: #38267 (same sync hunks plus docs sections), #38247 and #36327 (each adds names to the union and will need to drop the matching notPublic entries and update the snippets once this lands), #37095 (the numbering lint in the same directory).

[claude]

LGTM — docs/types sync plus a source-lint that keeps them synced; no runtime code changes.

What was reviewed

• Verified the new lint passes locally (4 tests, 17 expects) and that its enum/table regexes match src/ast/loader.rs as written; the [^}]* bodies have no nested braces.
• Confirmed the added names (json5, md, xml) are real Loader variants and that docs/runtime/transpiler.mdx's skipped type Loader is genuinely a different (JS-only) subset.
• Checked bun.d.ts has exactly one type Loader = declaration and the docs glob finds exactly the three snippets the test expects.
• Workflow path triggers added symmetrically to both push and pull_request; the loader.rs hunk is comment-only.

Extended reasoning...

Overview

This PR adds a source-tree lint (test/internal/source-lints/loader-names.test.ts) that parses pub enum Loader and LOADER_NAMES from src/ast/loader.rs, derives the set of public loader names (enum variants minus a documented notPublic exclusion list), and asserts that the Loader string-literal union in packages/bun-types/bun.d.ts and every type Loader = snippet under docs/**/*.mdx equal that set. It also brings the currently-stale copies up to date (json5/md in bun.d.ts; json5/xml/md in three docs files), adds packages/bun-types/bun.d.ts and docs/**/*.mdx to the source-lints workflow's path filters, adds a pointer comment above the enum, and documents the path-filter requirement in the source-lints README.

Security risks

None. No runtime code is touched: the .rs hunk is a comment, the .d.ts hunk adds string-literal union members, the docs hunks are prose snippets, and the test only reads files from the repo tree. The workflow change only widens which paths trigger an existing read-only test job.

Level of scrutiny

Low. This is test + docs + type-declaration + CI-trigger territory with no compiled-code changes. The test follows the established pattern of the ~20 other regex-based lints already in test/internal/source-lints/. I ran it locally against the checked-out tree and it passes cleanly. The regex parsers are guarded against silent breakage (toBeGreaterThan(10) on the enum and table sizes, snippets.length > 0 on the docs scan, and an explicit assertion that the union body contains only string literals and |), so a future refactor of loader.rs or the docs that breaks the parser will fail loudly rather than pass vacuously.

Other factors

• Verified via grep that bun.d.ts has exactly one type Loader = (line 5555), that the three docs files listed are the only full-union snippets, and that the skipped docs/runtime/transpiler.mdx declares the unrelated four-member JavaScriptLoader subset — the skip is correct.
• The snakeCase helper correctly reproduces strum's snake_case for every current variant (checked SqliteEmbedded -> sqlite_embedded, Json5 -> json5).
• The notPublic exclusions each carry a reason and are themselves asserted to name real variants, so they cannot go stale silently.
• No prior human review comments; only bot noise (CodeRabbit rate-limit notice, robobun status).

[robobun]

^{Updated 5:05 AM PT - Aug 14th, 2026}

❌ @robobun, your commit c10cd0a has some failures in Build #95677 (All Failures)

---

🧪   To try this PR locally:

bunx bun-pr 38424

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

bun-38424 --bun