Moonbit Refactoring

MoonBit Refactoring Skill

Intent

• Preserve behavior and public contracts unless explicitly changed.
• Minimize the public API to what callers require.
• Prefer declarative style and pattern matching over incidental mutation.
• Use view types (ArrayView/StringView/BytesView) to avoid copies.
• Add tests and docs alongside refactors.

Workflow

Start broad, then refine locally:

1. Architecture first: Review package structure, dependencies, and API boundaries.
2. Inventory public APIs and call sites (moon ide doc, moon ide find-references).
3. Pick one refactor theme (API minimization, package splits, pattern matching, loop style).
4. Apply the smallest safe change.
5. Update docs/tests in the same patch.
6. Run moon check, then moon test.
7. Use coverage to target missing branches.

Avoid local cleanups (renaming, pattern matching) until the high-level structure is sound.

Improve Package Architecture

• Keep packages focused: aim for <10k lines per package.
• Keep files manageable: aim for <2k lines per file.
• Keep functions focused: aim for <200 lines per function.

Splitting Files

Treat files in MoonBit as organizational units; move code freely within a package as long as each file stays focused on one concept.

Splitting Packages

When spinning off package A into A and B:

1. Create the new package and re-export temporarily:

   // In package B
   using @A { ... }  // re-export A's APIs

   Ensure moon check passes before proceeding.

2. Find and update all call sites:

   moon ide find-references <symbol>

   Replace bare f with @B.f.

3. Remove the use statement once all call sites are updated.

4. Audit and remove newly-unused pub APIs from both packages.

Guidelines

• Prefer acyclic dependencies: lower-level packages should not import higher-level ones.
• Only expose what downstream packages actually need.
• Consider an internal/ package for helpers that shouldn't leak.

Minimize Public API and Modularize

• Remove pub from helpers; keep only required exports.
• Move helpers into internal/ packages to block external imports.
• Split large files by feature; files do not define modules in MoonBit.

Local refactoring

Convert Free Functions to Methods + Chaining

• Move behavior onto the owning type for discoverability.
• Use .. for fluent, mutating chains when it reads clearly.

Example:

// Before
fn reader_next(r : Reader) -> Char? { ... }
let ch = reader_next(r)

// After
#as_free_fn(reader_next, deprecated="Use Reader::next instead")
fn Reader::next(self : Reader) -> Char? { ... }
let ch = r.next()

To make the transition smooth, place #as_free_fn(old_name, ...) on the method; it emits a deprecated free function old_name that forwards to the method. Then you can check call sites and update them gradually by looking at warnings. Example (chaining):

buf..write_string("#\\")..write_char(ch)

Prefer Explicit Qualification

• Use @pkg.fn instead of using when clarity matters.
• Keep call sites explicit during wide refactors.

Example:

let n = @parser.parse_number(token)

Simplify Enum Constructors When Type Is Known

When the expected type is known from context, you can omit the full package path for enum constructors:

• Pattern matching: Annotate the matched value; constructors need no path.
• Nested constructors: Only the outermost needs the full path.
• Return values: The return type provides context for constructors in the body.
• Collections: Type-annotate the collection; elements inherit the type.

Examples:

// Pattern matching - annotate the value being matched
let tree : @pkga.Tree = ...
match tree {
  Leaf(x) => x
  Node(left~, x, right~) => left.sum() + x + right.sum()
}

// Nested constructors - only outer needs full path
let x = @pkga.Tree::Node(left=Leaf(1), x=2, right=Leaf(3))

// Return type provides context
fn make_tree() -> @pkga.Tree {
  Node(left=Leaf(1), x=2, right=Leaf(3))
}

// Collections - type annotation on the array
let trees : Array[@pkga.Tree] = [Leaf(1), Node(left=Leaf(2), x=3, right=Leaf(4))]