From 98160545bf769c68fe87a02ed00fb79484ac2d7f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 19:34:15 +0000 Subject: [PATCH] docs: bring the README up to date List rbcop as Ruby's reference in the package table, add the missing Kotlin section, drop wording left over from the CRuby VM (boot, leaks, recycling), note that Ruby under Node needs no init() for formatSync, and correct the Java and Kotlin artifact sizes to the committed files. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01L7QsVKNxGFqNgbZxECZBkR --- .changeset/chubby-books-know.md | 4 +++ README.md | 57 ++++++++++++++++++++++++--------- packages/java/README.md | 6 ++-- packages/kotlin/README.md | 4 +-- 4 files changed, 51 insertions(+), 20 deletions(-) create mode 100644 .changeset/chubby-books-know.md diff --git a/.changeset/chubby-books-know.md b/.changeset/chubby-books-know.md new file mode 100644 index 0000000..6e8d99b --- /dev/null +++ b/.changeset/chubby-books-know.md @@ -0,0 +1,4 @@ +--- +--- + +README: list rbcop as the Ruby reference, add a Kotlin section, drop leftover Ruby VM wording, and correct the Java and Kotlin artifact sizes. diff --git a/README.md b/README.md index 8ec3afd..d8ac486 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,9 @@ Composer, no native binaries, no postinstall downloads. | Package | Reference | Artifact | Status | Browser | |:---|:---|---:|:---|:---| -| [`@scalar/ruby-fmt`](packages/ruby) | RuboCop (Layout) | 2.2 MB | ✅ exact by test | ✅ | -| [`@scalar/java-fmt`](packages/java) | google-java-format | 0.77 MB | ✅ exact | ✅ | -| [`@scalar/kotlin-fmt`](packages/kotlin) | ktfmt | 0.82 MB | ✅ exact | ✅ | +| [`@scalar/ruby-fmt`](packages/ruby) | rbcop | 2.2 MB | ✅ exact by test | ✅ | +| [`@scalar/java-fmt`](packages/java) | google-java-format | 0.76 MB | ✅ exact | ✅ | +| [`@scalar/kotlin-fmt`](packages/kotlin) | ktfmt | 0.81 MB | ✅ exact | ✅ | | [`@scalar/csharp-fmt`](packages/csharp) | CSharpier | 4.2 MB | ✅ exact | ✅ | | [`@scalar/swift-fmt`](packages/swift) | swift-format | 12.5 MB | ✅ exact | ✅ | | [`@scalar/php-fmt`](packages/php) | PHP CS Fixer | 0.45 MB | ✅ exact | — | @@ -36,10 +36,11 @@ Composer, no native binaries, no postinstall downloads. Artifact is the brotli-compressed module as committed and published — the whole tool, its parser and its language runtime in one file. The JavaScript that loads -it is small by comparison: nothing for Ruby, Swift, PHP and Rust, a 16 KB +it is small by comparison: nothing for Ruby, Swift, PHP and Rust, a 17 KB generated runtime for Java and Kotlin, and 0.46 MB of .NET loader scripts for C#. -Ruby's reference is `rubocop --autocorrect --only Layout`: the package corrects +Ruby runs rbcop, and the reference it is held to is +`rubocop --autocorrect --only Layout`: the package corrects Layout within the line structure it is handed and does not reprint, which suits line-structured input such as generated code. See [`packages/ruby`](packages/ruby#what-it-does-and-what-it-does-not). @@ -84,8 +85,8 @@ const formatted: string = await format('x=[1,2,3].map{|n| n*2}', options) // x = [1, 2, 3].map { |n| n * 2 } ``` -`format` is async because the first call boots a Ruby VM. The VM is cached, so -every later call is milliseconds. +`format` is async because the first call has to load and compile the wasm. That +work is cached, so every later call is milliseconds. ### Formatting without awaiting @@ -106,8 +107,9 @@ until it has. Everything after that already was synchronous; `format` was only ever awaiting the boot. Prefer `format` where you can await: it needs no setup call and cannot throw that -error. Ruby carries one extra caveat — see [its README](packages/ruby#readme) — -because recycling its VM is asynchronous too. +error. The one exception to the `init` rule is Ruby under Node, whose module +boots synchronously, so there `formatSync` works straight away — see +[its README](packages/ruby#formatting-without-awaiting). ## Browsers @@ -254,7 +256,7 @@ reproduces that at every pass, which means formatting here and then verifying with the jar compares pass one against pass two and looks like a divergence that is not one. `packages/java/README.md` has the detail and the two ways out. -It ships as a 0.77 MB `java_fmt.wasm.br` plus TeaVM's generated runtime, which +It ships as a 0.76 MB `java_fmt.wasm.br` plus TeaVM's generated runtime, which supplies the module's imports. Both are committed, so a fresh clone needs nothing extra; `bun run java:build:teavm` rebuilds them from a JDK 21, Maven, git and Node. @@ -276,6 +278,31 @@ exception handling TeaVM emits. bun is unaffected. And the module has no filesystem and no stdin, so source goes in as a string and comes back as one - enough for `format()`, but it rules out shipping the CLI itself. +## Kotlin + +See [`packages/kotlin`](packages/kotlin). It runs the real ktfmt 0.64 - the +Kotlin compiler's own PSI parser included - compiled to WasmGC by +[TeaVM](https://teavm.org), with the same patched TeaVM as the Java package. +The claim is checked in two halves over 589 real Kotlin files (kotlin-stdlib, +kotlinx-coroutines and ktfmt itself) in all three styles: the one patched file +leaves ktfmt's output unchanged on a JVM, and compiling that to wasm leaves it +unchanged again - 1767 of 1767 identical at each step, diagnostics included. A +conformance test asserts byte-identical output against the real ktfmt jar. + +The patch is 20 lines of ktfmt's `Parser`. ktfmt parses through the compiler's +`KotlinCoreEnvironment`, which resolves a JVM classpath, opens jars and registers +extension points named in XML - none of which an ahead-of-time compiler can +follow, and none of which parsing needs - so the patch builds the smaller +container that environment builds underneath, and everything below it is +ktfmt's own. + +Like Java it exports the release it carries, as `ktfmtVersion`, and a test reads +the build script so that export cannot go stale across a bump. It ships as a +0.81 MB `kotlin_fmt.wasm.br` plus the same TeaVM runtime as Java, both committed; +`bun run kotlin:build` rebuilds them from a JDK 21, Maven, git and Node. It shares +Java's caveat too: **Node 24.15 or newer**, for the same exception-handling +reason. + ## C# See [`packages/csharp`](packages/csharp). It runs the real CSharpier 1.3.0 - @@ -324,14 +351,14 @@ read and passed in. It ships as a 12.5 MB `swift_fmt.wasm.br`, built by [`build/swift_fmt/build.sh`](build/swift_fmt/build.sh), which downloads its own Swift toolchain and SDK. It is committed, so a fresh clone needs nothing extra; -`bun run swift:build` rebuilds it. Three times the size of the other packages, +`bun run swift:build` rebuilds it. Three times the size of the next largest package, almost all of it swift-syntax - `-Osize` and `wasm-opt -Oz` were both tried and moved the compressed total by under 60KB, so it is built with `-O` instead, which spends about 20% less time formatting. Two caveats worth knowing. The module is a **WASI reactor**: instantiated once, then `run` per format, which measured 2.5x faster than a fresh instance each -time and, unlike the Ruby VM, does not leak - memory plateaus at 75MB and stays +time and does not leak - memory plateaus at 75MB and stays there. And **the licence is unrestricted**, unlike the Java package: everything embedded is Apache-2.0 with the Runtime Library Exception, so a paid product may ship a copy. @@ -346,8 +373,8 @@ sources and the Symfony, ReactPHP and PSR components vendored into its phar), all of which came out identical - 1100 of them files the fixer actually rewrote. -It is also the one package with a synchronous entry point. PHP on wasm has none -and cannot be given one - both builds suspend through Asyncify or JSPI, so every +It is also the one package whose `formatSync()` cannot just run the module +synchronously. PHP on wasm has no synchronous entry point and cannot be given one - both builds suspend through Asyncify or JSPI, so every export returns a promise - so `formatSync()` gets its synchrony from the thread instead: PHP runs in a worker and the calling thread parks on `Atomics.wait` until the result lands in shared memory. Same fixer, byte-identical output, and @@ -425,7 +452,7 @@ trap on deeply nested expressions native handles fine. bun install bun run build # compile each package's TypeScript to dist/ bun run test # bun test suite -bun run test:node # load the built packages under plain Node (24+ for Java) +bun run test:node # load the built packages under plain Node (24.15+ for Java and Kotlin) bun run test:browser # load the built browser packages in real Chromium bun run check # biome lint + format check bun run types:check diff --git a/packages/java/README.md b/packages/java/README.md index 914f3d5..d9a0479 100644 --- a/packages/java/README.md +++ b/packages/java/README.md @@ -124,14 +124,14 @@ await init({ url: '/assets/java_fmt.wasm.br' }) await format(source) ``` -Run it in a worker. Booting compiles 3.3 MB of wasm, which is a visibly frozen +Run it in a worker. Booting compiles 3.2 MB of wasm, which is a visibly frozen tab if it happens on the main thread. The engine floor is checked at boot and is real: the module uses the final wasm exception-handling opcodes, so Chrome 137, Firefox 131 or Safari 18.4 at the earliest. -The browser reads the same brotli artifact as Node (0.77 MB over the wire) and +The browser reads the same brotli artifact as Node (0.76 MB over the wire) and expands it with `DecompressionStream('brotli')` where the engine has it, or a 208 KB wasm decoder where it does not — Chrome, today. Serving the artifact with `Content-Encoding: br`, or serving an uncompressed `.wasm`, skips the decoder @@ -202,7 +202,7 @@ replicates all four, in that order. `build/java_fmt_teavm/build.sh` produces two files, both committed: -- `java_fmt.wasm.br` — the module, 0.77MB brotli-compressed (3.3MB raw) +- `java_fmt.wasm.br` — the module, 0.76MB brotli-compressed (3.2MB raw) - `java_fmt.runtime.mjs` — TeaVM's generated runtime, which supplies the module's imports and the string and exception bridges diff --git a/packages/kotlin/README.md b/packages/kotlin/README.md index 4e9cddb..17500a5 100644 --- a/packages/kotlin/README.md +++ b/packages/kotlin/README.md @@ -129,14 +129,14 @@ await init({ url: '/assets/kotlin_fmt.wasm.br' }) await format(source) ``` -Run it in a worker. Booting compiles 3.5 MB of wasm, which is a visibly frozen +Run it in a worker. Booting compiles 3.4 MB of wasm, which is a visibly frozen tab if it happens on the main thread. The engine floor is checked at boot and is real: the module uses the final wasm exception-handling opcodes, so Chrome 137, Firefox 131 or Safari 18.4 at the earliest. -The browser reads the same brotli artifact as Node (0.82 MB over the wire) and +The browser reads the same brotli artifact as Node (0.81 MB over the wire) and expands it with `DecompressionStream('brotli')` where the engine has it, or a 208 KB wasm decoder where it does not — Chrome, today. Serving the artifact with `Content-Encoding: br`, or serving an uncompressed `.wasm`, skips the decoder