moonscratch 0.1.1 → 0.1.2

package/.agents/skills/moonbit-practice/reference/testing.md

@@ -1,228 +0,0 @@
----
-title: 'MoonBit Testing Reference'
----
-
-# MoonBit Testing Reference
-
-## Doc Tests
-
-Doc tests can be written in `.mbt.md` files or inline docstrings.
-
-### Code Block Types
-
-| Block            | Behavior                             |
-| ---------------- | ------------------------------------ |
-| ` ```mbt check ` | Type-checked by LSP and `moon check` |
-| ` ```mbt test `  | Executed as `test {...}` block       |
-| ` ```moonbit `   | Display only (not executed)          |
-
-### Inline Docstring Example
-
-````moonbit
-///|
-/// Get the largest element of a non-empty `Array`.
-///
-/// # Example
-/// ```mbt test
-/// test {
-///   inspect(sum_array([1, 2, 3, 4, 5, 6]), content="21")
-/// }
-/// ```
-///
-/// # Panics
-/// Panics if the `xs` is empty.
-pub fn sum_array(xs : Array[Int]) -> Int {
-  xs.fold(init=0, fn(a, b) { a + b })
-}
-````
-
-### README.mbt.md
-
-Create `README.mbt.md` in your package directory with tested code examples:
-
-````markdown
-# My Package
-
-## Usage
-
-```mbt test
-test {
-  inspect(@mypackage.hello(), content="Hello, World!")
-}
-```
-````
-
-Symlink to `README.md` for GitHub compatibility:
-
-```bash
-ln -s README.mbt.md README.md
-```
-
-## Snapshot Tests
-
-Use `inspect()` for snapshot testing. Run `moon test -u` to auto-update.
-
-```moonbit
-test "snapshot" {
-  inspect([1, 2, 3], content="")  // Empty initially
-}
-```
-
-After `moon test -u`:
-
-```moonbit
-test "snapshot" {
-  inspect([1, 2, 3], content="[1, 2, 3]")
-}
-```
-
-### inspect vs @json.inspect
-
-- `inspect()` - Uses `Show` trait, good for simple values
-- `@json.inspect()` - Uses `ToJson` trait, better for complex nested structures
-
-```moonbit
-test "complex structure" {
-  let data = { "name": "Alice", "scores": [90, 85, 92] }
-  @json.inspect(data, content={"name":"Alice","scores":[90,85,92]})
-}
-```
-
-## Benchmarks with moon bench
-
-### Basic Benchmark
-
-```moonbit
-///|
-bench "array_sum" {
-  let arr = Array::make(1000, 1)
-  arr.fold(init=0, fn(a, b) { a + b })
-}
-
-///|
-bench "array_sum_iter" {
-  let arr = Array::make(1000, 1)
-  let mut sum = 0
-  for v in arr {
-    sum = sum + v
-  }
-  sum
-}
-```
-
-### Running Benchmarks
-
-```bash
-moon bench                    # Run all benchmarks
-moon bench --target js        # JS backend
-moon bench --target wasm-gc   # Wasm backend
-```
-
-### Benchmark Best Practices
-
-1. **Isolate the operation**: Only measure the code you want to benchmark
-2. **Use realistic data sizes**: Small inputs may not reveal performance issues
-3. **Compare alternatives**: Benchmark multiple approaches side by side
-4. **Consider different backends**: Performance varies between JS, Wasm, and Native
-
-## QuickCheck (Property-Based Testing)
-
-QuickCheck generates random test inputs automatically.
-
-### Setup
-
-Add to `moon.pkg.json`:
-
-```json
-{
-  "test-import": ["moonbitlang/quickcheck"]
-}
-```
-
-### Basic Usage
-
-```moonbit
-///|
-test "reverse twice is identity" {
-  @quickcheck.check(fn(arr : Array[Int]) {
-    arr.rev().rev() == arr
-  })
-}
-
-///|
-test "sort is idempotent" {
-  @quickcheck.check(fn(arr : Array[Int]) {
-    let sorted = arr.copy()
-    sorted.sort()
-    let sorted_again = sorted.copy()
-    sorted_again.sort()
-    sorted == sorted_again
-  })
-}
-```
-
-### Custom Generators
-
-```moonbit
-///|
-test "custom generator" {
-  // Generate positive integers only
-  @quickcheck.check(fn(n : Int) {
-    let positive = n.abs() + 1
-    positive > 0
-  })
-}
-```
-
-### Shrinking
-
-QuickCheck automatically shrinks failing inputs to find minimal counterexamples:
-
-```moonbit
-///|
-test "finds minimal counterexample" {
-  // If this fails, QuickCheck will find the smallest failing input
-  @quickcheck.check(fn(arr : Array[Int]) {
-    arr.length() < 100  // Will fail and shrink to length=100
-  })
-}
-```
-
-## Test Organization
-
-### File Naming
-
-- `*_test.mbt` - Black-box tests (only public API)
-- `*_wbtest.mbt` - White-box tests (can access private members)
-- `*.mbt.md` - Documentation with tested examples
-
-### Test Filtering
-
-```bash
-moon test --filter "Array::*"           # Run tests matching pattern
-moon test src/parser_test.mbt           # Run specific file
-moon test -v                            # Verbose output
-```
-
-### Panic Tests
-
-Name tests with `panic` prefix:
-
-```moonbit
-///|
-test "panic on empty array" {
-  ignore(@mypackage.head([]))  // Should panic
-}
-```
-
-### Error Tests
-
-Use `try?` to convert errors to `Result`:
-
-```moonbit
-///|
-test "parse error" {
-  let result = try? parse("invalid")
-  inspect(result, content="Err(ParseError::InvalidInput)")
-}
-```

package/.agents/skills/moonbit-refactoring/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 bobzhang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/.agents/skills/moonbit-refactoring/SKILL.md

@@ -1,323 +0,0 @@
----
-name: moonbit-refactoring
-description: 'Refactor MoonBit code to be idiomatic: shrink public APIs, convert functions to methods, use pattern matching with views, add loop invariants, and ensure test coverage without regressions. Use when updating MoonBit packages or refactoring MoonBit APIs, modules, or tests.'
----
-
-# 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 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:
-
-   ```mbt
-   // In package B
-   using @A { ... }  // re-export A's APIs
-   ```
-
-   Ensure `moon check` passes before proceeding.
-
-2. Find and update all call sites:
-
-   ```bash
-   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:
-
-```mbt nocheck
-// 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):
-
-```mbt nocheck
-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:
-
-```mbt nocheck
-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:
-
-```mbt
-// 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))]
-```
-
-### Pattern Matching and Views
-
-- Pattern match arrays directly; the compiler inserts ArrayView implicitly.
-- Use `..` in the middle to match prefix and suffix at once.
-- Pattern match strings directly; avoid converting to `Array[Char]`.
-- `String`/`StringView` indexing yields `UInt16` code units. Use `for ch in s` for Unicode-aware iteration.
-
-#### we prefer pattern matching over small functions
-
-For example,
-
-```mbt
- match gen_results.get(0) {
-   Some(value) => Iter::singleton(value)
-   None => Iter::empty()
- }
-```
-
-We can pattern match directly, it is more efficient and as readable:
-
-```mbt
- match gen_results {
-   [value, ..] => Iter::singleton(value)
-   [] => Iter::empty()
- }
-```
-
-MoonBit pattern matching is pretty expressive, here are some more examples:
-
-```mbt
-match items {
-  [] => ()
-  [head, ..tail] => handle(head, tail)
-  [..prefix, mid, ..suffix] => handle_mid(prefix, mid, suffix)
-}
-```
-
-```mbt
-match s {
-  "" => ()
-  [.."let", ..rest] => handle_let(rest)
-  _ => ()
-}
-```
-
-#### Char literal matching
-
-Use char literal overloading for `Char`, `UInt16`, and `Int`; the examples below rely on it. This is handy when matching `String` indexing results (`UInt16`) against a char range.
-
-```mbt
-test {
-  let a_int : Int = 'b'
-  if (a_int is 'a'..<'z') { () } else { () }
-  let a_u16 : UInt16 = 'b'
-  if (a_u16 is 'a'..<'z') { () } else { () }
-  let a_char : Char = 'b'
-  if (a_char is 'a'..<'z') { () } else { () }
-}
-```
-
-#### Use Nested Patterns and `is`
-
-- Use `is` patterns inside `if`/`guard` to keep branches concise.
-
-Example:
-
-```mbt
-match token {
-  Some(Ident([.."@", ..rest])) if process(rest) is Some(x) => handle_at(rest)
-  Some(Ident(name)) => handle_ident(name)
-  None => ()
-}
-```
-
-#### Prefer Range Loops for Simple Indexing
-
-- Use `for i in start..<end { ... }`, `for i in start..<=end { ... }`, `for i in large>..small`, or `for i in large>=..small` for simple index loops.
-- Keep functional-state `for` loops for algorithms that update state.
-
-Example:
-
-```mbt
-// Before
-for i = 0; i < len; {
-  items.push(fill)
-  continue i + 1
-}
-
-// After
-for i in 0..<len {
-  items.push(fill)
-}
-```
-
-## Loop Specs (Dafny-Style Comments)
-
-- Add specs for functional-state loops.
-- Skip invariants for simple `for x in xs` loops.
-- Add TODO when a decreases clause is unclear (possible bug).
-
-Example:
-
-```mbt
-for i = 0, acc = 0; i < xs.length(); {
-  acc = acc + xs[i]
-  i = i + 1
-} else { acc }
-where {
-  invariant: 0 <= i <= xs.length(),
-  reasoning: (
-    #| ... rigorous explanation ...
-    #| ...
-  )
-}
-```
-
-### Tests and Docs
-
-- Prefer black-box tests in `*_test.mbt` or `*.mbt.md`.
-- Add docstring tests with `mbt check` for public APIs.
-
-Example:
-
-````mbt
-///|
-/// Return the last element of a non-empty array.
-///
-/// # Example
-/// ```mbt check
-/// test {
-///   inspect(last([1, 2, 3]), content="3")
-/// }
-/// ```
-pub fn last(xs : Array[Int]) -> Int { ... }
-````
-
-## Coverage-Driven Refactors
-
-- Use coverage to target missing branches through public APIs.
-- Prefer small, focused tests over white-box checks.
-
-Commands:
-
-```bash
-moon coverage analyze -- -f summary
-moon coverage analyze -- -f caret -F path/to/file.mbt
-```
-
-## Moon IDE Commands
-
-```bash
-moon doc "<query>"
-moon ide outline <dir|file>
-moon ide find-references <symbol>
-moon ide peek-def <symbol>
-moon ide rename <symbol> -new-name <new_name>
-moon check
-moon test
-moon info
-```
-
-Use these commands for reliable refactoring.
-
-Example: spinning off `package_b` from `package_a`.
-
-Temporary import in `package_b`:
-
-```mbt
-using @package_a { a, type B }
-```
-
-Steps:
-
-1. Use `moon ide find-references <symbol>` to find all call sites of `a` and `B`.
-2. Replace them with `@package_a.a` and `@package_a.B`.
-3. Remove the `using` statement and run `moon check`.

package/.githooks/README.md

@@ -1,23 +0,0 @@
-# Git Hooks
-
-## Pre-commit Hook
-
-This pre-commit hook performs automatic checks before finalizing your commit.
-
-### Usage Instructions
-
-To use this pre-commit hook:
-
-1. Make the hook executable if it isn't already:
-
-   ```bash
-   chmod +x .githooks/pre-commit
-   ```
-
-2. Configure Git to use the hooks in the .githooks directory:
-
-   ```bash
-   git config core.hooksPath .githooks
-   ```
-
-3. The hook will automatically run when you execute `git commit`

package/.githooks/pre-commit

@@ -1,3 +0,0 @@
-#!/bin/sh
-
-moon check

package/.github/workflows/copilot-setup-steps.yml

@@ -1,40 +0,0 @@
-# Reference: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment
-name: 'Copilot Setup Steps'
-
-# Automatically run the setup steps when they are changed to allow for easy validation, and
-# allow manual testing through the repository's "Actions" tab
-on:
-  workflow_dispatch:
-  push:
-    paths:
-      - .github/workflows/copilot-setup-steps.yml
-  pull_request:
-    paths:
-      - .github/workflows/copilot-setup-steps.yml
-
-jobs:
-  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
-  copilot-setup-steps:
-    runs-on: ubuntu-latest
-
-    # Set the permissions to the lowest permissions possible needed for your steps.
-    # Copilot will be given its own token for its operations.
-    permissions:
-      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
-      contents: read
-
-    # You can define any steps you want, and they will run before the agent starts.
-    # If you do not check out your code, Copilot will do this for you.
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v5
-
-      - name: Set up MoonBit
-        run: |
-          curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
-          echo "$HOME/.moon/bin" >> $GITHUB_PATH
-
-      - name: Update MoonBit dependencies
-        run: |
-          moon version --all
-          moon update