Merge upstream/main into perf/stringbuilder-reset

Author: mizchi

AGENTS.md

@@ -32,3 +32,80 @@ Each package has its files and blackbox test files (common, ending in `_test.mbt
   like `assert_eq` when you are in some loops where each snapshot may vary. You can use `moon coverage analyze > uncovered.log` to see which parts of your code are not covered by tests.
 
 - agent-todo.md has some small tasks that are easy for AI to pick up, agent is welcome to finish the tasks and check the box when you are done
+
+# Trait-method promotion (`extend`)
+
+When a type `impl`s a trait, the trait's methods can be *promoted* to inherent
+methods (`x.method(..)`) via an explicit `pub extend` block in the package's
+`extends.mbt`. The rule for what we promote vs. deprecate
+(`#deprecated(.., skip_current_package=true)` + `#doc(hidden)`) is driven by
+**where the trait lives** — because promoting a method couples the type's
+package to the trait's package:
+
+- **Traits whose home is `builtin`** (`Add`…`Sub`, `Compare`, `Eq`, `Hash`,
+  `Show`, `Default`, `Logger`, `ToStringView`): every package already depends on
+  `builtin`, so promoting them creates **no cycle** — safe on any type.
+- **Traits whose home is a higher package** (`@json.FromJson`,
+  `@quickcheck.Arbitrary`, `@debug.Debug`): promoting them on a lower-level type
+  would form a cycle (`builtin → json` etc.), so they are **never promoted** —
+  always use the free function (`@json.from_json`, `@quickcheck.…`,
+  `@debug.Debug`).
+
+This is about the trait's *logical* home, not the file it currently sits in:
+**`ToJson` lives in `builtin` today only for bootstrapping but belongs in
+`@json`**, so it is treated as a higher-package trait (not promoted) — promoting
+it would have to be ripped out the day it moves.
+
+Within the "safe to promote" set:
+
+- **Operators** (`add`, `sub`, `mul`, `div`, `mod`, `neg`, `land`, `lor`, `lxor`,
+  `shl`, `shr`): promoted on every type — the named method is a first-class value
+  the operator syntax can't give you.
+- **`Compare::compare`, `Eq::equal`, `Hash::hash`**: promoted **uniformly on
+  every type** that impls them (they're all in `builtin`, no cycle, and it keeps
+  the surface uniform). Exactly **one** method per trait is promoted — the
+  user-facing primary one. Its *derivatives* stay deprecated:
+  - `Compare::{op_lt, op_le, op_ge, op_gt}` → use `<` `<=` `>=` `>`
+  - `Eq::not_equal` → use `!=`
+  - `Hash::hash_combine` → implementer-facing, use it via the trait
+
+  (`compare` and `equal` are still worth promoting even though `<` and `==`
+  exist, because they're the *required* trait methods and the only way to pass
+  the operation as a first-class value — e.g. `Int::equal` into a fold. The
+  derivatives above are defaulted members that add nothing over the operator.)
+
+  **Tuples** get the same promotions but with `#doc(hidden)` (the synthetic
+  `Tuple(N)::…` names are ugly in the interface; the methods still work without
+  a warning).
+- **`Show::to_string`**: promoted only for types with a **canonical string
+  representation** (scalars, strings). Collections deprecate it toward
+  `@debug.Debug` (there's no single canonical `Show` for a collection).
+  `Show::output` is never promoted (use `to_string` / `"\{x}"`).
+- **`Default::default`**: **deprecated** — a literal (`0`, `[]`, `None`, `""`,
+  `b'\x00'`) or `Default::default()` via the trait bound is clearer, and it keeps
+  the interface lean. (Exception: `Byte::default()` is kept promoted **for now** —
+  Moon's generated test drivers call `FixedArray::make(512, Byte::default())`, so
+  deprecating it breaks `moon test --build-only --deny-warn`. moonbitlang/moon#1938
+  removes that call; deprecate `Byte` like the rest once a moon release ships.)
+- **`ToJson::to_json`**: **not promoted** — use **`Json(x)`**, the constructor of
+  `Json` (re-exported by the prelude, so it needs no import and works from every
+  package, `builtin` included). Between that and `Json`'s literal sugar
+  (`([x, y] : Json)`, `({ "k": v } : Json)`) you rarely need `x.to_json()` at
+  all, and serialization is cold, so nothing is lost by going through the
+  constructor. Because `Json(x)` is spelled the same regardless of which package
+  `Json` lives in, moving `Json`/`ToJson` to `@json` later would not churn call
+  sites — exactly how `to_repr(x)` is spelled the same though `Debug`/`Repr` live
+  in `@debug`.
+
+This policy governs a package's own `extends.mbt` (its public API surface).
+
+**Test fixtures should be `priv`.** A type declared in a `_test.mbt` file with no
+visibility modifier is *abstract-public*, so `implicit_impl_as_method` fires for
+its derived impls and you end up writing `pub extend` ceremony that has nothing
+to do with the test. Declare such types `priv` instead — then they need no
+`extend` at all. If a test needs to call a promoted method on one, use the trait
+form (`ToJson::to_json(x)`, `Default::default()`).
+
+After editing `extends.mbt`, run `moon info && moon fmt` and check the `.mbti`
+diff. `#doc(hidden)` alone (no `#deprecated`) keeps a promotion working but hides
+it from the generated interface — that's how tuples stay usable but tidy.

NOTICE

@@ -116,3 +116,26 @@ Developed at SunPro, a Sun Microsystems, Inc. business.
 Permission to use, copy, modify, and distribute this
 software is freely granted, provided that this notice
 is preserved.
+
+Copyright (c) 1992-2026 The FreeBSD Project.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

argparse/extends.mbt

@@ -0,0 +1,131 @@
+// Copyright 2026 International Digital Economy Academy
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// --- promoted: kept as regular methods ---
+
+///|
+pub extend FlagAction with Eq::{equal}
+
+///|
+pub extend FlagAction with Show::{to_string}
+
+///|
+pub extend OptionAction with Eq::{equal}
+
+///|
+pub extend OptionAction with Show::{to_string}
+
+///|
+pub extend ValueRange with Eq::{equal}
+
+///|
+pub extend ValueRange with Show::{to_string}
+
+///|
+pub extend ValueSource with Eq::{equal}
+
+///|
+pub extend ValueSource with Show::{to_string}
+
+// --- deprecated: hidden from the generated interface ---
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ArgGroup with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend Command with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend FlagAction with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `!=` instead", skip_current_package=true)
+#doc(hidden)
+pub extend FlagAction with Eq::{not_equal}
+
+///|
+#deprecated("Use `Show::output` via the trait or `to_string` instead", skip_current_package=true)
+#doc(hidden)
+pub extend FlagAction with Show::{output}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend FlagArg with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend Matches with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend OptionAction with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `!=` instead", skip_current_package=true)
+#doc(hidden)
+pub extend OptionAction with Eq::{not_equal}
+
+///|
+#deprecated("Use `Show::output` via the trait or `to_string` instead", skip_current_package=true)
+#doc(hidden)
+pub extend OptionAction with Show::{output}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend OptionArg with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend PositionArg with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ValueRange with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `!=` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ValueRange with Eq::{not_equal}
+
+///|
+#deprecated("Use `Show::output` via the trait or `to_string` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ValueRange with Show::{output}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ValueSource with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `!=` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ValueSource with Eq::{not_equal}
+
+///|
+#deprecated("Use `Show::output` via the trait or `to_string` instead", skip_current_package=true)
+#doc(hidden)
+pub extend ValueSource with Show::{output}

argparse/pkg.generated.mbti

@@ -32,6 +32,8 @@ pub(all) enum FlagAction {
   Help
   Version
 } derive(Eq, Show, @debug.Debug)
+pub fn FlagAction::equal(Self, Self) -> Bool
+pub fn FlagAction::to_string(Self) -> String
 
 pub struct FlagArg {
   // private fields
@@ -52,6 +54,8 @@ pub(all) enum OptionAction {
   Set
   Append
 } derive(Eq, Show, @debug.Debug)
+pub fn OptionAction::equal(Self, Self) -> Bool
+pub fn OptionAction::to_string(Self) -> String
 
 pub struct OptionArg {
   // private fields
@@ -70,13 +74,17 @@ pub struct ValueRange {
 } derive(Eq, Show, @debug.Debug)
 #alias(new, deprecated)
 pub fn ValueRange::ValueRange(lower? : Int, upper? : Int) -> Self
+pub fn ValueRange::equal(Self, Self) -> Bool
 pub fn ValueRange::single() -> Self
+pub fn ValueRange::to_string(Self) -> String
 
 pub enum ValueSource {
   Argv
   Env
   Default
 } derive(Eq, Show, @debug.Debug)
+pub fn ValueSource::equal(Self, Self) -> Bool
+pub fn ValueSource::to_string(Self) -> String
 
 // Type aliases
 

bench/README.mbt.md

@@ -19,7 +19,7 @@ test "basic benchmarking" {
   })
 
   // The benchmark ran successfully (we can't inspect exact timing)
-  inspect(summary.to_json().stringify().length() > 0, content="true")
+  inspect(@json.to_json(summary).stringify().length() > 0, content="true")
 }
 ```
 

bench/debug.mbt

@@ -16,7 +16,7 @@
 pub impl @debug.Debug for Bench with fn to_repr(self) {
   @debug.Repr::opaque_(
     "Bench",
-    @debug.Repr::array(self.summaries.map(s => @debug.to_repr(s))),
+    @debug.Repr::array(self.summaries.map(s => Repr(s))),
   )
 }
 

bench/extends.mbt

@@ -0,0 +1,37 @@
+// Copyright 2026 International Digital Economy Academy
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Bench, Summary and Timestamp have no promoted trait methods; every promotion below is deprecated.
+
+// --- deprecated: hidden from the generated interface ---
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend Bench with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend Summary with @debug.Debug::{to_repr}
+
+///|
+#deprecated("Use `@json.to_json` instead", skip_current_package=true)
+#doc(hidden)
+pub extend Summary with ToJson::{to_json}
+
+///|
+#deprecated("Use `Debug::to_repr` instead", skip_current_package=true)
+#doc(hidden)
+pub extend Timestamp with @debug.Debug::{to_repr}

bigint/bigint_js.mbt

@@ -283,21 +283,21 @@ pub fn BigInt::to_octets(self : BigInt, length? : Int) -> Bytes {
 }
 
 ///|
-extern "js" fn BigInt::compare(self : BigInt, other : BigInt) -> Int =
+extern "js" fn BigInt::compare_js(self : BigInt, other : BigInt) -> Int =
   #|(x, y) => x < y ? -1 : x > y ? 1 : 0
 
 ///|
 pub impl Compare for BigInt with fn compare(self, other) {
-  self.compare(other)
+  self.compare_js(other)
 }
 
 ///|
-extern "js" fn BigInt::equal(self : BigInt, other : BigInt) -> Bool =
+extern "js" fn BigInt::equal_js(self : BigInt, other : BigInt) -> Bool =
   #|(x, y) => x === y
 
 ///|
 pub impl Eq for BigInt with fn equal(self, other) {
-  self.equal(other)
+  self.equal_js(other)
 }
 
 ///|

bigint/bigint_nonjs.mbt

@@ -47,9 +47,9 @@ priv enum Sign {
 test "internal repr" {
   fn convert(b : BigInt) -> @debug.Repr {
     @debug.Repr::record({
-      "limbs": @debug.to_repr(b.limbs),
-      "sign": @debug.to_repr(b.sign),
-      "len": @debug.to_repr(b.len),
+      "limbs": Repr(b.limbs),
+      "sign": Repr(b.sign),
+      "len": Repr(b.len),
     })
   }
   @debug.debug_inspect(
@@ -1527,7 +1527,7 @@ pub fn BigInt::to_octets(self : BigInt, length? : Int) -> Bytes {
   let tail_len = self.len - 1
   let len = (head_bits + 7) / 8 + tail_len * (RADIX_BIT_LEN / 8)
   let len = max(length, len)
-  let result = FixedArray::make(len, Byte::default())
+  let result = FixedArray::make(len, b'\x00')
   for i in 0..<len {
     if i / 4 >= self.len {
       break