Skip to content

feat(kotlin)!: replace TeaVM-compiled ktfmt with ktrs - #62

Merged
amritk merged 6 commits into
mainfrom
claude/exciting-goldberg-drycfy
Nov 13, 2026
Merged

amritk merged 6 commits into
mainfrom
claude/exciting-goldberg-drycfy

Conversation

@amritk

@amritk amritk commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

What & why

Replaces the artifact behind @scalar/kotlin-fmt: ktfmt 0.64 compiled to WasmGC by the patched TeaVM fork is replaced by ktrs 0.5.3, a Rust reimplementation of ktfmt (0.65), compiled to wasm.

  • Build: build/kotlin_fmt/build.sh clones ktrs at the v0.5.3 release commit and builds a small entry crate (build/kotlin_fmt/entry) over ktrs-fmt. The result is an import-free wasm32-unknown-unknown module that takes options as integers, with a negative value meaning "inherit from the style". The artifact goes from 0.82 MB to 0.20 MB brotli (864 KB raw).
  • Package: the package now has the same shape as @scalar/ruby-fmt. It uses plain WebAssembly APIs: no TeaVM runtime, no exnref probe, and no Node 24.15 floor (engines is now >=18). Booting under Node is synchronous, so formatSync needs no init() there. A cold boot takes about 15 ms; okhttp formats at about 1.5 ms per file. After a trap (a panic, or input nested deeper than the engine's call stack, which is deeper than ktfmt's own JVM goes), the instance is dropped and the next call re-instantiates the cached module.
  • Retired: build/java_fmt_teavm/kotlin-probe and patches/ktfmt.patch are deleted. The TeaVM fork in build/teavm stays, patches included, because @scalar/java-fmt is built with it; its docs now point at the retired build in git history.
  • Docs: updated the README status table, .claude/architecture.md, CLAUDE.md, AGENTS.md, CONTRIBUTING, SECURITY, the issue template, the CI comments and the package README.

Licensing

  • Kotlin: licenses/NOTICE.md is rewritten for what the new artifact embeds: ktrs, ec4rs, text-size and the Rust standard library (with dlmalloc and compiler_builtins), all distributed under Apache-2.0. It reproduces the Apache-2.0 §4(d) attribution notices from ktrs's NOTICE for the code it ports from the Kotlin compiler, IntelliJ, ktfmt, google-java-format and ec4j. The ktlint, ktfmt-gradle and ktlint-maven-plugin code that ktrs credits lives in crates that are not compiled in; the notice says so. There is no copyleft component.
  • Java (audit, no artifact change): commonmark-java 0.28.0 (BSD-2-Clause) is compiled into java_fmt.wasm, because google-java-format bundles it for Markdown doc comments, but it was not listed. It is now listed, with its license text taken from its tagged release. TeaVM's upstream NOTICE, which Apache-2.0 §4(d) asks a distribution to carry, is added as teavm-NOTICE. The shims and the bundled annotation libraries are named.

Which packages

packages/kotlin (minor), packages/java (patch, notices only), build/kotlin_fmt (new), the TeaVM build docs, CI, docs.

Exactness

ktrs is a reimplementation, so under the exactness rule the status moves from exact to exact by test, the same as Ruby/rbcop. test/ktfmt-conformance.test.ts runs the real ktfmt 0.65 release jar and asserts byte-identical output, and identical diagnostics for rejected input. It covers samples in meta, google and kotlinlang styles and with --do-not-remove-unused-imports, plus any corpus named by KOTLIN_FMT_CONFORMANCE_CORPUS. build/kotlin_fmt/ktfmt.sh downloads the jar and checks it against a pinned checksum, and CI now runs that script so the test runs rather than skips.

Corpus runs (ktrs's own pinned revisions), all four configurations:

Corpus Files Identical
square/okhttp 617 617 in each configuration
Kotlin/kotlinx.coroutines 1,082 1,082 in each configuration

Sources are parsed as scripts, which is how ktfmt reads stdin and how the previous package parsed them (ktfmt 0.64 always parsed temp.kts). The conformance test writes .kts files to match. The width, indent, trailing-comma and lambda options set apart from a style have no ktfmt CLI flags, so the jar can't be the oracle for them; the unit tests cover them.

How it was validated

  • bun run check
  • bun run types:check
  • bun run test, all 7 packages
  • bun run test:node, run on Node 22 here
  • bun run test:browser, all 6 packages in Chromium
  • Rebuilt the wasm artifact and re-ran its conformance test, including the two corpora above

Changeset

  • @scalar/kotlin-fmt minor, with the breaking changes listed (the ./runtime export and some types removed, the diagnostic prefix changed, unknown options now throw)
  • @scalar/java-fmt patch, for the notices

Swap the artifact behind @scalar/kotlin-fmt for ktrs 0.5.3, a Rust
reimplementation of ktfmt, compiled to an import-free wasm32-unknown-unknown
module through a small entry crate in build/kotlin_fmt/entry. The package now
hosts it with plain WebAssembly APIs, mirroring the Ruby package: synchronous
boot under Node, trap recovery by re-instantiating the compiled module.

ktrs is not ktfmt compiled, so the claim moves from "exact" to "exact by
test": test/ktfmt-conformance.test.ts runs the real ktfmt 0.65 jar
(downloaded and checksum-verified by build/kotlin_fmt/ktfmt.sh, which CI now
runs) and asserts byte-identical output and diagnostics.

The third-party notice is rewritten for what the new artifact embeds: ktrs,
ec4rs, text-size and the Rust standard library, plus the Apache-2.0
attribution notices for the Kotlin compiler, IntelliJ, ktfmt,
google-java-format and ec4j code ktrs ports.
Delete build/java_fmt_teavm/kotlin-probe and patches/ktfmt.patch, which
built the previous artifact. The TeaVM fork patches stay: the Java package
is built with them, and removing one changes its module. The TeaVM docs now
point at the retired build in git history.

Update the README status table (Kotlin is exact by test), the architecture
notes, CLAUDE.md and AGENTS.md (Kotlin's formatSync boots synchronously
under Node), the package README, and the Node 24.15 mentions that applied to
Kotlin.
…tices

commonmark-java 0.28.0 (BSD-2-Clause), which google-java-format bundles for
Markdown doc comments, is compiled into the Java artifact but was not
listed. Add it with its license text. Add TeaVM's NOTICE file, which
Apache-2.0 4(d) asks a distribution to carry, and name the shims and the
bundled annotation libraries.

Note in the Kotlin notice that the lexer's Unicode tables come from the
Kotlin compiler's JFlex-generated lexers.
- The conformance test accepts only ktfmt's jar as the oracle, never a
  ktfmt on PATH: ktrs's drop-in binary reports the same version string,
  and comparing ktrs with itself would pass vacuously. It also reads
  ktfmt's "Error formatting ...; skipping." lines as rejections.
- Unknown style and trailingCommas values are looked up in Maps, so names
  on Object.prototype (toString, constructor) are refused like any other.
- The entry crate allocates the source buffer as a boxed slice, so it is
  freed with the exact layout it was allocated with, and the host encodes
  straight into it with encodeInto.
- The Node artifact source moves into src/index.ts, the one file allowed
  to import node: built-ins.
- The README states the real engine floor (reference types: Chrome 96,
  Firefox 79, Safari 15).
- CI caches the ktfmt jar, and the download retries.
@amritk
amritk marked this pull request as ready for review November 13, 2026 20:13
…erg-drycfy

# Conflicts:
#	README.md
#	packages/kotlin/README.md
@amritk
amritk merged commit 39bf384 into main Nov 13, 2026
8 checks passed
@amritk
amritk deleted the claude/exciting-goldberg-drycfy branch November 13, 2026 20:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants