moonscratch 0.1.0-alpha.0

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

@@ -0,0 +1,217 @@
+---
+title: 'MoonBit Performance Tuning'
+---
+
+# MoonBit Performance Tuning
+
+## View Types Overview
+
+View types are **zero-copy, non-owning, read-only slices**. They don't allocate memory and are ideal for passing sub-sequences without copying data.
+
+| Original Type   | View Type      | Slice Syntax           |
+| --------------- | -------------- | ---------------------- |
+| `String`        | `StringView`   | `s[:]`, `s[start:end]` |
+| `Bytes`         | `BytesView`    | `b[:]`, `b[start:end]` |
+| `Array[T]`      | `ArrayView[T]` | `a[:]`, `a[start:end]` |
+| `FixedArray[T]` | `ArrayView[T]` | `a[:]`, `a[start:end]` |
+
+## StringView
+
+### Creating StringView
+
+```moonbit
+let s = "hello world"
+let view : StringView = s[:]           // Entire string
+let hello : StringView = s[0:5]        // "hello"
+let world : StringView = s[6:]         // "world"
+let partial : StringView = s[:5]       // "hello"
+```
+
+### StringView for Function Parameters
+
+```moonbit
+///|
+/// BAD: Takes ownership, may copy
+fn process_string(s : String) -> Unit {
+  // ...
+}
+
+///|
+/// Good: Zero-copy, no allocation
+fn process_string_view(s : StringView) -> Unit {
+  // ...
+}
+
+// Both work - implicit conversion
+process_string_view("hello")
+process_string_view(some_string[:])
+```
+
+### Unicode Safety
+
+StringView slicing may raise at surrogate boundaries (UTF-16 edge case):
+
+```moonbit
+fn safe_slice(s : String, start : Int, end : Int) -> StringView raise {
+  s[start:end]  // May raise on invalid boundaries
+}
+
+// Or use try! if you're certain
+let view = try! s[start:end]
+```
+
+### StringView Methods
+
+```bash
+moon doc StringView
+```
+
+Common operations:
+
+- `view.length()` - Length in code units
+- `view.to_string()` - Convert back to owned String
+- `view.iter()` - Iterate over characters
+
+## ArrayView
+
+### Creating ArrayView
+
+```moonbit
+let arr = [1, 2, 3, 4, 5]
+let view : ArrayView[Int] = arr[:]      // Entire array
+let first3 : ArrayView[Int] = arr[0:3]  // [1, 2, 3]
+let last2 : ArrayView[Int] = arr[3:]    // [4, 5]
+```
+
+### ArrayView for Function Parameters
+
+```moonbit
+///|
+/// BAD: Takes ownership
+fn sum_array(arr : Array[Int]) -> Int {
+  arr.fold(init=0, fn(a, b) { a + b })
+}
+
+///|
+/// Good: Zero-copy, accepts slices
+fn sum_view(arr : ArrayView[Int]) -> Int {
+  arr.fold(init=0, fn(a, b) { a + b })
+}
+
+// Both work
+sum_view([1, 2, 3])        // Array literal
+sum_view(arr[:])           // Full array
+sum_view(arr[1:4])         // Slice
+```
+
+### Pattern Matching with Views
+
+```moonbit
+fn process(view : ArrayView[Int]) -> Unit {
+  match view {
+    [] => println("empty")
+    [x] => println("single: \{x}")
+    [first, ..rest] => {
+      println("first: \{first}")
+      process(rest)  // rest is ArrayView
+    }
+  }
+}
+```
+
+### ArrayView Methods
+
+```bash
+moon doc ArrayView
+```
+
+Common operations:
+
+- `view.length()` - Number of elements
+- `view[i]` - Index access
+- `view.iter()` - Iterator
+- `view.to_array()` - Convert to owned Array
+
+## BytesView
+
+### Creating BytesView
+
+```moonbit
+let bytes : Bytes = b"hello"
+let view : BytesView = bytes[:]
+let first2 : BytesView = bytes[0:2]
+```
+
+### BytesView for Binary Data
+
+```moonbit
+///|
+/// Good: Zero-copy binary parsing
+fn parse_header(data : BytesView) -> Header raise ParseError {
+  guard data.length() >= 4 else { raise ParseError::TooShort }
+  let magic = data[0:2]
+  let version = data[2:4]
+  // ...
+}
+```
+
+## Performance Patterns
+
+### Avoid Unnecessary Allocations
+
+```moonbit
+///|
+/// BAD: Creates intermediate strings
+fn join_with_separator(parts : Array[String], sep : String) -> String {
+  let mut result = ""
+  for i, part in parts {
+    if i > 0 { result = result + sep }
+    result = result + part  // Allocates each time!
+  }
+  result
+}
+
+///|
+/// Good: Use StringBuilder
+fn join_with_separator(parts : Array[String], sep : String) -> String {
+  let sb = StringBuilder::new()
+  for i, part in parts {
+    if i > 0 { sb.write_string(sep) }
+    sb.write_string(part)
+  }
+  sb.to_string()
+}
+```
+
+### Use Views in Recursive Functions
+
+```moonbit
+///|
+/// Good: No copying in recursion
+fn binary_search(arr : ArrayView[Int], target : Int) -> Int? {
+  guard arr.length() > 0 else { None }
+  let mid = arr.length() / 2
+  if arr[mid] == target {
+    Some(mid)
+  } else if arr[mid] > target {
+    binary_search(arr[:mid], target)
+  } else {
+    binary_search(arr[mid + 1:], target).map(fn(i) { i + mid + 1 })
+  }
+}
+```
+
+## Converting Back to Owned Types
+
+When you need ownership:
+
+```moonbit
+let string_view : StringView = "hello"[:]
+let owned_string : String = string_view.to_string()
+
+let array_view : ArrayView[Int] = [1, 2, 3][:]
+let owned_array : Array[Int] = array_view.to_array()
+
+let bytes_view : BytesView = b"data"[:]
+let owned_bytes : Bytes = bytes_view.to_bytes()
+```

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

@@ -0,0 +1,154 @@
+---
+title: 'MoonBit Refactoring Patterns'
+---
+
+# MoonBit Refactoring Patterns
+
+## Prefer match-if Pattern for Two-way Branches with No-op
+
+```moonbit
+let opt : Int? = Some(1)
+
+///|
+/// BAD
+match opt {
+  Some(v) => println("hello")
+  None => ()
+}
+
+///|
+/// Good
+if opt is Some(v) {
+  println("hello")
+}
+```
+
+## Prefer guard for Early Returns
+
+Use `guard` when you want to exit early if a condition is not met.
+
+```moonbit
+///|
+/// BAD: Deep nesting
+fn get_value(array : Array[Int], index : Int) -> Int? {
+  if index >= 0 && index < array.length() {
+    Some(array[index])
+  } else {
+    None
+  }
+}
+
+///|
+/// Good: Early return with guard
+fn get_value(array : Array[Int], index : Int) -> Int? {
+  guard index >= 0 && index < array.length() else { None }
+  Some(array[index])
+}
+```
+
+Combine with pattern matching:
+
+```moonbit
+///|
+/// BAD: Deep nesting with match
+fn process(resources : Map[String, Resource], path : String) -> String raise Error {
+  match resources.get(path) {
+    Some(resource) => {
+      match resource {
+        PlainText(text) => process(text)
+        _ => fail("\{path} is not plain text")
+      }
+    }
+    None => fail("\{path} not found")
+  }
+}
+
+///|
+/// Good: Flatten with guard is
+fn process(resources : Map[String, Resource], path : String) -> String raise Error {
+  guard resources.get(path) is Some(resource) else { fail("\{path} not found") }
+  guard resource is PlainText(text) else { fail("\{path} is not plain text") }
+  process(text)
+}
+```
+
+## Prefer StringView for String Performance
+
+```moonbit
+///|
+/// BAD: String concatenation creates new strings each time
+fn process_string(s : String) -> String {
+  ...
+}
+
+///|
+/// Good: StringView avoids copying
+fn process_string_view(s : StringView) -> Unit {
+  ...
+}
+```
+
+## Prefer for-in over C-style for
+
+```moonbit
+///|
+/// BAD: C-style for
+for i = 0; i < items.length(); i = i + 1 {
+  println(items[i])
+}
+
+///|
+/// Good: for-in
+for item in items {
+  println(item)
+}
+
+///|
+/// Good: When index is needed
+for i, item in items {
+  println("\{i}: \{item}")
+}
+```
+
+## Prefer Arrow Functions for Single Expressions
+
+```moonbit
+///|
+/// BAD: Verbose
+let f = fn(x) { x + 1 }
+arr.map(fn(x) { x * 2 })
+
+///|
+/// Good: Arrow function
+let f = fn { x => x + 1 }
+arr.map(fn { x => x * 2 })
+```
+
+## Use else with for Loops to Return Values
+
+```moonbit
+///|
+/// BAD: Using variable to hold result
+fn find_first(arr : Array[Int], target : Int) -> Int? {
+  let mut result : Int? = None
+  for i in arr {
+    if i == target {
+      result = Some(i)
+      break
+    }
+  }
+  result
+}
+
+///|
+/// Good: Return directly with for-else
+fn find_first(arr : Array[Int], target : Int) -> Int? {
+  for i in arr {
+    if i == target {
+      break Some(i)
+    }
+  } else {
+    None
+  }
+}
+```

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

@@ -0,0 +1,351 @@
+---
+title: 'MoonBit Standard Library and External Packages'
+---
+
+# MoonBit Standard Library
+
+The standard library (`moonbitlang/core`) is **automatically available** - no need to add it to dependencies.
+
+## Important Rules
+
+- ❌ **DO NOT** use `moon add moonbitlang/core/*`
+- ❌ **DO NOT** add to `"deps"` in `moon.mod.json`
+- ❌ **DO NOT** add to `"import"` in `moon.pkg.json`
+- ✅ **DO** use directly: `@strconv.parse_int()`, `@json.parse()`, etc.
+
+## Exploring the Standard Library
+
+```bash
+# List all available packages
+moon doc ''
+
+# Explore specific package
+moon doc "@json"
+moon doc "@buffer"
+moon doc "@encoding/utf8"
+
+# Find specific function
+moon doc "@strconv.parse_int"
+
+# Search with glob
+moon doc "String::*find*"
+```
+
+## Common Packages
+
+### @json - JSON Parsing and Serialization
+
+```moonbit
+// Parse JSON
+let value : @json.JsonValue = @json.parse("{\"name\": \"Alice\"}")!
+
+// Access fields
+match value {
+  { "name": String(name) } => println(name)
+  _ => ()
+}
+
+// Serialize to JSON (derive ToJson)
+struct User { name: String; age: Int } derive(ToJson)
+
+let user = { name: "Bob", age: 30 }
+let json_str = user.to_json().stringify()
+```
+
+### @buffer - Mutable Byte Buffer
+
+```moonbit
+let buf = @buffer.new()
+buf.write_string("Hello")
+buf.write_byte(b' ')
+buf.write_string("World")
+let result = buf.to_string()  // "Hello World"
+```
+
+### @strconv - String Conversion
+
+```moonbit
+// Parse integers
+let n : Int = @strconv.parse_int("42")!
+let hex : Int = @strconv.parse_int("ff", base=16)!
+
+// Parse floats
+let f : Double = @strconv.parse_double("3.14")!
+```
+
+### @encoding/utf8 - UTF-8 Encoding
+
+```moonbit
+// Encode string to UTF-8 bytes
+let bytes : Bytes = @encoding/utf8.encode("Hello 世界")
+
+// Decode UTF-8 bytes to string
+let s : String = @encoding/utf8.decode(bytes)
+```
+
+### @hashmap - Hash Map (Alternative to Map)
+
+```moonbit
+let map : @hashmap.HashMap[String, Int] = @hashmap.new()
+map.set("a", 1)
+map.set("b", 2)
+let value = map.get("a")  // Some(1)
+```
+
+### @hashset - Hash Set
+
+```moonbit
+let set : @hashset.HashSet[Int] = @hashset.new()
+set.insert(1)
+set.insert(2)
+set.contains(1)  // true
+```
+
+### @sorted_map / @sorted_set - Sorted Collections
+
+```moonbit
+// Keys are kept in sorted order
+let map : @sorted_map.T[String, Int] = @sorted_map.new()
+map.insert("b", 2)
+map.insert("a", 1)
+// Iteration: a, b (sorted)
+```
+
+### @random - Random Number Generation
+
+```moonbit
+let rng = @random.new()
+let n = rng.int()           // Random Int
+let f = rng.double()        // Random Double [0, 1)
+let arr = [1, 2, 3, 4, 5]
+rng.shuffle(arr)            // Shuffle in place
+```
+
+### @time - Time and Duration
+
+```moonbit
+let now = @time.now()
+let duration = @time.Duration::from_seconds(5)
+```
+
+### @result - Result Utilities
+
+```moonbit
+let ok : Result[Int, String] = Ok(42)
+let err : Result[Int, String] = Err("failed")
+
+// Map over success
+ok.map(fn(n) { n * 2 })  // Ok(84)
+
+// Unwrap with default
+err.unwrap_or(0)  // 0
+```
+
+### @option - Option Utilities
+
+```moonbit
+let some : Int? = Some(42)
+let none : Int? = None
+
+some.map(fn(n) { n * 2 })  // Some(84)
+some.unwrap_or(0)          // 42
+none.unwrap_or(0)          // 0
+```
+
+## Collections Overview
+
+| Type                     | Description        | Use Case                       |
+| ------------------------ | ------------------ | ------------------------------ |
+| `Array[T]`               | Resizable array    | General purpose                |
+| `FixedArray[T]`          | Fixed-size array   | Known size, no resize          |
+| `Map[K, V]`              | Ordered hash map   | Key-value with insertion order |
+| `@hashmap.HashMap[K, V]` | Hash map           | Fast lookup                    |
+| `@sorted_map.T[K, V]`    | Sorted map         | Ordered by keys                |
+| `@list.T[T]`             | Linked list        | Functional programming         |
+| `@deque.T[T]`            | Double-ended queue | Queue/stack operations         |
+
+## Traits in Standard Library
+
+### Show - String Representation
+
+```moonbit
+struct Point { x: Int; y: Int } derive(Show)
+
+let p = { x: 1, y: 2 }
+println(p.to_string())  // "{x: 1, y: 2}"
+```
+
+### ToJson / FromJson - JSON Serialization
+
+```moonbit
+struct Config {
+  name: String
+  value: Int
+} derive(ToJson, FromJson)
+
+let config : Config = @json.from_json(@json.parse(json_str)!)!
+```
+
+### Eq / Compare - Equality and Ordering
+
+```moonbit
+struct Version { major: Int; minor: Int } derive(Eq, Compare)
+
+let v1 = { major: 1, minor: 0 }
+let v2 = { major: 1, minor: 1 }
+v1 < v2  // true
+```
+
+### Hash - Hashing
+
+```moonbit
+struct Key { id: Int; name: String } derive(Hash, Eq)
+
+// Can be used as HashMap key
+let map : @hashmap.HashMap[Key, String] = @hashmap.new()
+```
+
+### Default - Default Values
+
+```moonbit
+struct Config {
+  timeout: Int
+  retries: Int
+} derive(Default)
+
+let config = Config::default()  // { timeout: 0, retries: 0 }
+```
+
+## Iterators
+
+```moonbit
+let arr = [1, 2, 3, 4, 5]
+
+// Map
+arr.map(fn(x) { x * 2 })  // [2, 4, 6, 8, 10]
+
+// Filter
+arr.filter(fn(x) { x % 2 == 0 })  // [2, 4]
+
+// Fold
+arr.fold(init=0, fn(acc, x) { acc + x })  // 15
+
+// Find
+arr.find(fn(x) { x > 3 })  // Some(4)
+
+// Any / All
+arr.any(fn(x) { x > 3 })  // true
+arr.all(fn(x) { x > 0 })  // true
+
+// Chaining
+arr.filter(fn(x) { x % 2 == 0 })
+   .map(fn(x) { x * 2 })  // [4, 8]
+```
+
+## String Operations
+
+```moonbit
+let s = "hello world"
+
+s.length()                    // 11
+s.contains("world")           // true
+s.starts_with("hello")        // true
+s.ends_with("world")          // true
+s.split(" ")                  // ["hello", "world"]
+s.replace("world", "MoonBit") // "hello MoonBit"
+s.trim()                      // Remove whitespace
+s.to_upper()                  // "HELLO WORLD"
+s.to_lower()                  // "hello world"
+```
+
+## Discovering APIs
+
+Always use `moon doc` to discover available APIs:
+
+```bash
+# What methods does Array have?
+moon doc "Array"
+
+# What's in the json package?
+moon doc "@json"
+
+# Find all parse functions
+moon doc "*parse*"
+```
+
+---
+
+# External Packages
+
+Unlike `moonbitlang/core`, these packages require explicit installation.
+
+## moonbitlang/x - Extended Utilities
+
+Experimental and extended utilities not yet in core.
+
+### Installation
+
+```bash
+moon add moonbitlang/x
+```
+
+### Common Packages
+
+```moonbit
+// @x/fs - File system operations (native/node backend)
+let content = @x/fs.read_to_string("file.txt")
+
+// @x/sys - System operations
+let args = @x/sys.get_args()
+let env = @x/sys.get_env()
+```
+
+### Exploring
+
+```bash
+moon doc "@x/fs"
+moon doc "@x/sys"
+```
+
+## moonbitlang/async - Asynchronous Programming
+
+Async/await support for MoonBit.
+
+### Installation
+
+```bash
+moon add moonbitlang/async
+```
+
+### Important: Import Required for async main/test
+
+To use `async fn main` or `async test`, you **must** import `moonbitlang/async` in your `moon.pkg.json`:
+
+```json
+{
+  "import": ["moonbitlang/async"]
+}
+```
+
+Without this import, `async fn main` and `async test` will not work.
+
+### Basic Usage
+
+```moonbit
+// Define async function
+async fn fetch_data(url : String) -> String raise {
+  // async operations
+}
+
+// Run async code
+@async.run(async fn() {
+  let data = fetch_data("https://example.com")!
+  println(data)
+})
+```
+
+### Exploring
+
+```bash
+moon doc "@async"
+```