docs: correct Bun.semver.satisfies invalid range text and the escapeHTML hardware name

[robobun]

Problem

• docs/runtime/semver.mdx says Bun.semver.satisfies returns false when range is invalid. It does not. Bun.semver.satisfies("1.0.0", "!!not-a-range!!") returns true on bun 1.4.1. Only an invalid version returns false.
• docs/runtime/utils.mdx names an "M1X" processor in the Bun.escapeHTML benchmark text. That chip does not exist. The benchmark ran on an M1 Max (Docs: Bun.escapeHTML() references non-existent processor #13342).

Fix

• Rewrite the satisfies sentence. Bun skips the parts of range it cannot parse. A range with no parseable part behaves like *. An invalid version, or a non-ASCII character in either argument, returns false.
• Replace "M1X" with "M1 Max" on the docs page.
• Verified: every claim in the new sentence by execution on bun 1.4.1 (see Notes). Prettier is clean.

Fixes #13342

Background

• Bun.semver.satisfies is src/semver_jsc/SemverObject.rs. It parses range with bun_semver::query::parse. That parser drops tokens it does not recognize and never fails on bad input. Group::is_empty documents this: "the input was only unrecognised words".
• An empty comparator group matches every non-prerelease version. That is the same behavior as the * range in node-semver.
• This PR carries the two items from docs: residual corrections from fact-check sweep #33709 that are still valid on main. The rest of that PR landed in docs: fix the factual errors found while rewording the docs #38899, docs: audit guides and Node.js compatibility page #38441, and install: pnpm parity — dedupe, prune, pm licenses, audit fix, add --filter/--catalog, nested overrides, transitive update, and workspace fixes #38333, or is no longer correct after jsx: honor tsconfig "react-jsx" vs "react-jsxdev" for the automatic runtime #34422.
• The Bun.escapeHTML JSDoc in packages/bun-types/bun.d.ts (line 2397) has the same "M1X" text. This PR is scoped to docs/. That copy is for a types change.

Notes

Probe on bun 1.4.1:

satisfies("1.0.0", "^1.0.0")             true
satisfies("1.0.0", "!!not-a-range!!")    true   (docs said false)
satisfies("1.0.0", "")                   true
satisfies("1.0.0-alpha", "garbage")      false  (same as "*": prereleases excluded)
satisfies("1.0.0-alpha", "*")            false
satisfies("2.0.0", "garbage || ^2.0.0")  true   (unparseable part dropped)
satisfies("2.0.0", "garbage ^1.0.0")     false
satisfies("!!not-a-version!!", "^1.0.0") false
satisfies("!!not-a-version!!", "*")      false
satisfies("1.x", "^1.0.0")               false  (wildcard in version)
satisfies("1.0.0", "^1.0.0 café")        false  (non-ASCII short-circuits to false)
satisfies("café", "*")                   false

The version half of the sentence is unchanged from main. It is not exact for every input: satisfies("", "*") and satisfies("1.0.0.0", "^1.0.0") return true because satisfies does not check the parser's valid flag, while order does. Those are degenerate inputs and the sentence describes the common case, as before.

Not included: #33709 also removed the "Export condition macro" section from docs/bundler/macros.mdx. On bun 1.4.1, import { macro } from "my-package" with { type: "macro" } resolves through the normal conditions, not the "macro" condition, so that section documents a behavior the bundler does not have. Whether the docs or the resolver changes is a maintainer decision. See the closing comment on #33709.

---

no test proof · iteration 1 · docs-only change; test-proof not applicable

[robobun]

^{Updated 7:08 AM PT - Aug 31st, 2026}

✅ @robobun, your commit 0f399a7dc87061cf7f72e71e59bb51e3c80f4990 passed in Build #108859! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 41052

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

bun-41052 --bun

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: da20a888-5947-4ab5-827e-f0fb347456ac

📥 Commits

Reviewing files that changed from the base of the PR and between 8985f0e and 0f399a7.

📒 Files selected for processing (1)

• docs/runtime/semver.mdx

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

Walkthrough

The runtime documentation clarifies Bun.semver.satisfies() parsing behavior and corrects the Bun.escapeHTML() benchmark processor from M1X to M1 Max.

Changes

Documentation updates

Layer / File(s)	Summary
Semver parsing documentation docs/runtime/semver.mdx	The documentation states that invalid versions and non-ASCII arguments return false. It also describes handling for unparseable range portions and empty parseable ranges.
escapeHTML benchmark documentation docs/runtime/utils.mdx	The performance example identifies the processor as an M1 Max while retaining the 480 MB/s throughput.

Suggested reviewers: alii

Merge Risk: ⚪ Minimal · up to 0f399

This PR corrects documented semver behavior and a benchmark hardware name without changing runtime code or product behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The Bun.semver.satisfies documentation change is not covered by the directly linked issue #13342, which only concerns the escapeHTML hardware reference.	Link the issue that covers the semver documentation correction, provide explicit scope approval, or move the semver change into a separate pull request.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR satisfies issue #13342 by changing the escapeHTML benchmark hardware reference from “M1X” to “M1 Max”.
Title check	✅ Passed	The title clearly identifies both documentation corrections: the Bun.semver.satisfies invalid-range text and the escapeHTML hardware name.
Description check	✅ Passed	The description explains the problem, the fixes, verification steps, scope, and linked issue. It uses Problem and Fix headings instead of the template headings, but it provides the required informatio…

Full details: Description check

Explanation

The description explains the problem, the fixes, verification steps, scope, and linked issue. It uses Problem and Fix headings instead of the template headings, but it provides the required information.

• Fix all pre-merge checks with AI

---

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

[robobun]

On the out-of-scope check: the Bun.semver.satisfies sentence has no issue of its own. It comes from the fact-check sweep in #33709, which is now closed, and this PR carries the two items from that sweep that are still valid on main. The PR body names the source.

The PR is now scoped to docs/ only. The Bun.escapeHTML JSDoc in packages/bun-types/bun.d.ts has the same "M1X" text. That copy is for a types change, as noted in the body.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[robobun]

Took the optional note on the non-ASCII case. Bun.semver.satisfies returns false when either argument contains a non-ASCII character, before it parses anything. satisfies("1.0.0", "^1.0.0 café") is false while satisfies("1.0.0", "^1.0.0 garbage") is true. Commit 0f399a7 adds that condition to the sentence. The PR body lists the probes.

[claude]

LGTM — thanks for adding the non-ASCII carve-out; the satisfies sentence now matches the short-circuit in SemverObject.rs.

What was reviewed:

• Verified each new satisfies claim against src/semver_jsc/SemverObject.rs (non-ASCII guards at 81-86, query::parse only failing on OOM, wildcard-in-version → false).
• Checked prose against the docs voice rules — short sentences, active voice, present tense, "Bun" as the actor.
• The "M1X" → "M1 Max" fix is a straight hardware-name correction.

Extended reasoning...

Overview

This PR touches two documentation files only. docs/runtime/semver.mdx rewrites one sentence describing Bun.semver.satisfies error handling to match actual runtime behavior: invalid version or any non-ASCII byte in either argument returns false; unparseable parts of range are dropped; a fully-unparseable range acts like *. docs/runtime/utils.mdx corrects "M1X" to "M1 Max" in the Bun.escapeHTML benchmark blurb. No source, type, or test files change.

Security risks

None. Prose-only edits to published docs; no code, config, or build changes.

Level of scrutiny

Low, but per the "Docs, types, and comments" rule every published claim must be verified against the implementation. I read src/semver_jsc/SemverObject.rs end-to-end: lines 81-86 return JSValue::FALSE when either argument contains a non-ASCII byte; lines 88-90 return false for wildcard-bearing versions; lines 96-102 confirm query::parse on the range can only fail with OOM, so garbage tokens are silently dropped and an empty group falls through to Group::satisfies, which matches non-prerelease versions like *. Every claim in the new sentence checks out. The prose also passes the voice rules in docs/project/contributing.mdx.

Other factors

My prior inline comment on this PR flagged that the earlier draft did not account for the non-ASCII short-circuit on range. Commit 0f399a7 addressed it by adding "or if either argument contains a non-ASCII character", which correctly scopes the remaining claims to ASCII input. No CODEOWNERS entry covers docs/. No outstanding third-party CHANGES_REQUESTED reviews. The change is small, self-contained, and now accurate.

[robobun]

Thanks for the review and merge.