moonscratch 0.1.0-alpha.0

package/.agents/skills/moonbit-agent-guide/ide.md

@@ -0,0 +1,116 @@
+## Code Navigation with `moon ide`
+
+**ALWAYS use `moon ide` for code navigation in MoonBit projects instead of manual file searching, grep, or semantic search.**
+
+This tool provides two essential commands for precise code exploration:
+
+### Core Commands
+
+- `moon ide goto-definition` - Find where a symbol is defined
+- `moon ide find-references` - Find all usages of a symbol
+
+### Query System
+
+Symbol lookup uses a two-part query system for precise results:
+
+#### 1. Symbol Name Query (`-query`)
+
+Fuzzy search for symbol names with package filtering support:
+
+```bash
+# Find any symbol named 'symbol'
+moon ide goto-definition -query 'symbol'
+
+# Find methods of a specific type
+moon ide goto-definition -query 'Type::method'
+
+# Find trait method implementations
+moon ide goto-definition -query 'Trait for Type with method'
+
+# Find symbol in specific package using @pkg prefix
+moon ide goto-definition -query '@moonbitlang/x encode'
+
+# Find symbol in multiple packages (searches in pkg1 OR pkg2)
+moon ide goto-definition -query '@username/mymodule/pkg1 @username/mymodule/pkg2 helper'
+
+# Find symbol in nested package
+moon ide goto-definition -query '@username/mymodule/mypkg helper'
+```
+
+**Supported symbols**: functions, constants, let bindings, types, structs, enums, traits
+
+**Package filtering**: Prefix your query with `@package_name` to scope the search. Multiple `@pkg` prefixes create an OR condition.
+
+#### 2. Tag-based Filtering (`-tags`)
+
+Pre-filter symbols by characteristics before name matching:
+
+**Visibility tags**:
+
+- `pub` - Public symbols
+- `pub all` - Public structs with all public fields
+- `pub open` - Public traits with all methods public
+- `priv` - Private symbols
+
+**Symbol type tags**:
+
+- `type` - Type definitions (struct, enum, typealias, abstract)
+- `error` - Error type definitions
+- `enum` - Enum definitions and variants
+- `struct` - Struct definitions
+- `alias` - Type/function/trait aliases
+- `let` - Top-level let bindings
+- `const` - Constant definitions
+- `fn` - Function definitions
+- `trait` - Trait definitions
+- `impl` - Trait implementations
+- `test` - Named test functions
+
+**Combine tags with logical operators**:
+
+```bash
+# Public functions only
+moon ide goto-definition -tags 'pub fn' -query 'my_func'
+
+# Functions or constants
+moon ide goto-definition -tags 'fn | const' -query 'helper'
+
+# Public functions or constants
+moon ide goto-definition -tags 'pub (fn | const)' -query 'api'
+
+# Public types or traits
+moon ide goto-definition -tags 'pub (type | trait)' -query 'MyType'
+```
+
+### Practical Examples
+
+```bash
+# Find public function definition
+moon ide goto-definition -tags 'pub fn' -query 'maximum'
+
+# Find all references to a struct
+moon ide find-references -tags 'struct' -query 'Rectangle'
+
+# Find trait implementations
+moon ide goto-definition -tags 'impl' -query 'Show for MyType'
+
+# Find errors in specific package
+moon ide goto-definition -tags 'error' -query '@mymodule/parser ParseError'
+
+# Find symbol across multiple packages
+moon ide goto-definition -query '@moonbitlang/x @moonbitlang/core encode'
+
+# Combine package filtering with tags
+moon ide goto-definition -tags 'pub fn' -query '@username/myapp helper'
+```
+
+### Query Processing
+
+The tool processes queries in this order:
+
+1. Filter symbols by `-tags` conditions
+2. Extract package scope from `@pkg` prefixes in `-query`
+3. Fuzzy match remaining symbols by name
+4. Return top 3 best matches with location information
+
+**Best Practice**: Start with `-tags` to reduce noise, then use `@pkg` prefixes in `-query` to scope by package for precise navigation.

package/.agents/skills/moonbit-agent-guide/references/advanced-moonbit-build.md

@@ -0,0 +1,106 @@
+## Conditional Compilation
+
+Target specific backends/modes in `moon.pkg.json`:
+
+```json
+{
+  "targets": {
+    "wasm_only.mbt": ["wasm"],
+    "js_only.mbt": ["js"],
+    "debug_only.mbt": ["debug"],
+    "wasm_or_js.mbt": ["wasm", "js"], // for wasm or js backend
+    "not_js.mbt": ["not", "js"], // for nonjs backend
+    "complex.mbt": ["or", ["and", "wasm", "release"], ["and", "js", "debug"]] // more complex conditions
+  }
+}
+```
+
+**Available conditions:**
+
+- **Backends**: `"wasm"`, `"wasm-gc"`, `"js"`, `"native"`
+- **Build modes**: `"debug"`, `"release"`
+- **Logical operators**: `"and"`, `"or"`, `"not"`
+
+## Link Configuration
+
+### Basic Linking
+
+```json
+{
+  "link": true, // Enable linking for this package
+  // OR for advanced cases:
+  "link": {
+    "wasm": {
+      "exports": ["hello", "foo:bar"], // Export functions
+      "heap-start-address": 1024, // Memory layout
+      "import-memory": {
+        // Import external memory
+        "module": "env",
+        "name": "memory"
+      },
+      "export-memory-name": "memory" // Export memory with name
+    },
+    "wasm-gc": {
+      "exports": ["hello"],
+      "use-js-builtin-string": true, // JS String Builtin support
+      "imported-string-constants": "_" // String namespace
+    },
+    "js": {
+      "exports": ["hello"],
+      "format": "esm" // "esm", "cjs", or "iife"
+    },
+    "native": {
+      "cc": "gcc", // C compiler
+      "cc-flags": "-O2 -DMOONBIT", // Compile flags
+      "cc-link-flags": "-s" // Link flags
+    }
+  }
+}
+```
+
+## Warning Control
+
+Disable specific warnings in `moon.mod.json` or `moon.pkg.json`:
+
+```json
+{
+  "warn-list": "-2-29" // Disable unused variable (2) & unused package (29)
+}
+```
+
+**Common warning numbers:**
+
+- `1` - Unused function
+- `2` - Unused variable
+- `11` - Partial pattern matching
+- `12` - Unreachable code
+- `29` - Unused package
+
+Use `moonc build-package -warn-help` to see all available warnings.
+
+## Pre-build Commands
+
+Embed external files as MoonBit code:
+
+```json
+{
+  "pre-build": [
+    {
+      "input": "data.txt",
+      "output": "embedded.mbt",
+      "command": ":embed -i $input -o $output --name data --text"
+    },
+    ... // more embed commands
+  ]
+}
+```
+
+Generated code example:
+
+```mbt check
+///|
+let data : String =
+  #|hello,
+  #|world
+  #|
+```

package/.agents/skills/moonbit-agent-guide/references/moonbit-language-fundamentals.mbt.md

@@ -0,0 +1,422 @@
+# MoonBit Language Fundamentals
+
+## Quick reference:
+
+```mbt check
+///|
+/// comments doc string
+pub fn sum(x : Int, y : Int) -> Int {
+  x + y
+}
+
+///|
+struct Rect {
+  width : Int
+  height : Int
+}
+
+///|
+fn Rect::area(self : Rect) -> Int {
+  self.width * self.height
+}
+
+///|
+pub impl Show for Rect with output(_self, logger) {
+  logger.write_string("Rect")
+}
+
+///|
+enum MyOption {
+  MyNone
+  MySome(Int)
+} derive(Show, ToJson, Eq, Compare)
+
+///|
+///  match + loops are expressions
+test "everything is expression in MoonBit" {
+  // tuple
+  let (n, opt) = (1, MySome(2))
+  // if expressions return values
+  let msg : String = if n > 0 { "pos" } else { "non-pos" }
+  let res = match opt {
+    MySome(x) => {
+      inspect(x, content="2")
+      1
+    }
+    MyNone => 0
+  }
+  let status : Result[Int, String] = Ok(10)
+  // match expressions return values
+  let description = match status {
+    Ok(value) => "Success: \{value}"
+    Err(error) => "Error: \{error}"
+  }
+  let array = [1, 2, 3, 4, 5]
+  let mut i = 0 // mutable bindings (local only, globals are immutable)
+  let target = 3
+  // loops return values with 'break'
+  let found : Int? = while i < array.length() {
+    if array[i] == target {
+      break Some(i) // Exit with value
+    }
+    i = i + 1
+  } else { // Value when loop completes normally
+    None
+  }
+  assert_eq(found, Some(2)) // Found at index 2
+}
+
+///|
+/// global bindings
+pub let my_name : String = "MoonBit"
+
+///|
+pub const PI : Double = 3.14159 // constants use UPPER_SNAKE or PascalCase
+
+///|
+pub fn maximum(xs : Array[Int]) -> Int raise {
+  // Toplevel functions are *mutually recursive* by default
+  // `raise` annotation means the function would raise any Error
+  //  Only add `raise XXError` when you do need track the specific error type
+  match xs {
+    [] => fail("Empty array") // fail() is built-in for generic errors
+    [x] => x
+    // pattern match over array, the `.. rest` is a rest pattern
+    // it is of type `ArrayView[Int]` which is a slice
+    [x, .. rest] => {
+      let mut max_val = x // `mut` only allowed in local bindings
+      for y in rest {
+        if y > max_val {
+          max_val = y
+        }
+      }
+      max_val // return can be omitted if the last expression is the return value
+    }
+  }
+}
+
+///|
+/// pub(all) means it can be both read and created outside the package
+pub(all) struct Point {
+  x : Int
+  mut y : Int
+} derive(Show, ToJson)
+
+///|
+pub enum MyResult[T, E] {
+  MyOk(T) // semicolon `;` is optional when we have a newline
+  MyErr(E) // Enum variants must start uppercase
+} derive(Show, Eq, ToJson)
+// pub means it can only be pattern matched outside the package
+// but it can not be created outside the package, use `pub(all)` otherwise
+
+///|
+/// pub (open) means the trait can be implemented for outside packages
+pub(open) trait Comparable {
+  compare(Self, Self) -> Int // `Self` refers to the implementing type
+}
+
+///|
+test "inspect test" {
+  let result = sum(1, 2)
+  inspect(result, content="3")
+  // The `content` can be auto-corrected by running `moon test --update`
+  let point = Point::{ x: 10, y: 20 }
+  // For complex structures, use @json.inspect for better readability:
+  @json.inspect(point, content={ "x": 10, "y": 20 })
+}
+```
+
+## Complex Types
+
+```mbt check
+///|
+pub type UserId = Int // Int is aliased to UserId - like symlink
+
+///|
+///  Tuple-struct for callback
+pub struct Handler((String) -> Unit) // A newtype wrapper
+
+///|
+/// Tuple-struct syntax for single-field newtypes
+struct Meters(Int) // Tuple-struct syntax
+
+///|
+let distance : Meters = Meters(100)
+
+///|
+let raw : Int = distance.0 // Access first field with .0
+
+///|
+struct Addr {
+  host : String
+  port : Int
+} derive(Show, Eq, ToJson, FromJson)
+
+///|
+/// Structural types with literal syntax
+let config : Addr = Addr::{
+  // `Type::` can be omitted since the type is already known
+  host: "localhost",
+  port: 8080,
+}
+
+
+```
+
+## Common Derivable Traits
+
+Most types can automatically derive standard traits using the `derive(...)` syntax:
+
+- **`Show`** - Enables `to_string()` and string interpolation with `\{value}`
+- **`Eq`** - Enables `==` and `!=` equality operators
+- **`Compare`** - Enables `<`, `>`, `<=`, `>=` comparison operators
+- **`ToJson`** - Enables `@json.inspect()` for readable test output
+- **`Hash`** - Enables use as Map keys
+
+```mbt check
+///|
+struct Coordinate {
+  x : Int
+  y : Int
+} derive(Show, Eq, ToJson)
+
+///|
+enum Status {
+  Active
+  Inactive
+} derive(Show, Eq, Compare)
+```
+
+**Best practice**: Always derive `Show` and `Eq` for data types. Add `ToJson` if you plan to test them with `@json.inspect()`.
+
+## Reference Semantics by Default
+
+MoonBit passes most types by reference semantically (the optimizer may copy
+immutables):
+
+```mbt check
+///|
+///  Structs with 'mut' fields are always passed by reference
+struct Counter {
+  mut value : Int
+}
+
+///|
+fn increment(c : Counter) -> Unit {
+  c.value += 1 // Modifies the original
+}
+
+///|
+/// Arrays and Maps are mutable references
+fn modify_array(arr : Array[Int]) -> Unit {
+  arr[0] = 999 // Modifies original array
+}
+
+///|
+test "reference semantics" {
+  let counter : Ref[Int] = Ref::{ val: 0 }
+  counter.val += 1
+  assert_true(counter.val is 1)
+  let arr : Array[Int] = [1, 2, 3] // unlike Rust, no `mut` keyword needed
+  modify_array(arr)
+  assert_true(arr[0] is 999)
+  let mut x = 3 // `mut` neeed for re-assignment to the bindings
+  x += 2
+  assert_true(x is 5)
+}
+```
+
+## Pattern Matching
+
+```mbt check
+///|
+#warnings("-unused_value")
+test "pattern match over Array, struct and StringView" {
+  let arr : Array[Int] = [10, 20, 25, 30]
+  match arr {
+    [] => ... // empty array
+    [single] => ... // single element
+    [first, .. middle, rest] => {
+      let _ : ArrayView[Int] = middle // middle is ArrayView[Int]
+      assert_true(first is 10 && middle is [20, 25] && rest is 30)
+    }
+  }
+  fn process_point(point : Point) -> Unit {
+    match point {
+      { x: 0, y: 0 } => ...
+      { x, y } if x == y => ...
+      { x, .. } if x < 0 => ...
+      ...
+    }
+  }
+  /// StringView pattern matching for parsing
+  fn is_palindrome(s : StringView) -> Bool {
+    loop s {
+      [] | [_] => true
+      [a, .. rest, b] if a == b => continue rest
+      // a is of type Char, rest is of type StringView
+      _ => false
+    }
+  }
+
+
+}
+```
+
+## Functional `loop` control flow
+
+The `loop` construct is unique to MoonBit:
+
+```mbt check
+///|
+/// Functional loop with pattern matching on loop variables
+/// @list.List is from the standard library
+fn sum_list(list : @list.List[Int]) -> Int {
+  loop (list, 0) {
+    (Empty, acc) => acc // Base case returns accumulator
+    (More(x, tail=rest), acc) => continue (rest, x + acc) // Recurse with new values
+  }
+}
+
+///|
+///  Multiple loop variables with complex control flow
+fn find_pair(arr : Array[Int], target : Int) -> (Int, Int)? {
+  loop (0, arr.length() - 1) {
+    (i, j) if i >= j => None
+    (i, j) => {
+      let sum = arr[i] + arr[j]
+      if sum == target {
+        Some((i, j)) // Found pair
+      } else if sum < target {
+        continue (i + 1, j) // Move left pointer
+      } else {
+        continue (i, j - 1) // Move right pointer
+      }
+    }
+  }
+}
+```
+
+**Note**: You must provide a payload to `loop`. If you want an infinite loop, use `while true { ... }` instead. The syntax `loop { ... }` without arguments is invalid.
+
+## Methods and Traits
+
+Methods use `Type::method_name` syntax, traits require explicit implementation:
+
+```mbt check
+///|
+struct Rectangle {
+  width : Double
+  height : Double
+}
+
+///|
+// Methods are prefixed with Type::
+fn Rectangle::area(self : Rectangle) -> Double {
+  self.width * self.height
+}
+
+///|
+/// Static methods don't need self
+fn Rectangle::new(w : Double, h : Double) -> Rectangle {
+  { width: w, height: h }
+}
+
+///|
+/// Show trait now uses output(self, logger) for custom formatting
+/// to_string() is automatically derived from this
+pub impl Show for Rectangle with output(self, logger) {
+  logger.write_string("Rectangle(\{self.width}x\{self.height})")
+}
+
+///|
+/// Traits can have non-object-safe methods
+trait Named {
+  name() -> String // No 'self' parameter - not object-safe
+}
+
+///|
+/// Trait bounds in generics
+fn[T : Show + Named] describe(value : T) -> String {
+  "\{T::name()}: \{value.to_string()}"
+}
+
+///|
+///  Trait implementation
+impl Hash for Rectangle with hash_combine(self, hasher) {
+  hasher..combine(self.width)..combine(self.height)
+}
+```
+
+## Operator Overloading
+
+MoonBit supports operator overloading through traits:
+
+```mbt check
+///|
+struct Vector(Int, Int)
+
+///|
+/// Implement arithmetic operators
+pub impl Add for Vector with add(self, other) {
+  Vector(self.0 + other.0, self.1 + other.1)
+}
+
+///|
+struct Person {
+  age : Int
+} derive(Eq)
+
+///|
+/// Comparison operators
+pub impl Compare for Person with compare(self, other) {
+  self.age.compare(other.age)
+}
+
+///|
+test "overloading" {
+  let v1 : Vector = Vector(1, 2)
+  let v2 : Vector = Vector(3, 4)
+  let _v3 : Vector = v1 + v2
+
+}
+```
+
+## Access Control Modifiers
+
+MoonBit has fine-grained visibility control:
+
+```mbt check
+///|
+/// `fn` defaults to Private - only visible in current package
+fn internal_helper() -> Unit {
+  ...
+}
+
+///|
+pub fn get_value() -> Int {
+  ...
+}
+
+///|
+// Struct (default) - type visible, implementation hidden
+struct DataStructure {}
+
+///|
+/// `pub struct` defaults to readonly - can read, pattern match, but not create
+pub struct Config {}
+
+///|
+///  Public all - full access
+pub(all) struct Config2 {}
+
+///|
+/// Abstract trait (default) - cannot be implemented by
+/// types outside this package
+pub trait MyTrait {}
+
+///|
+///  Open for extension
+pub(open) trait Extendable {}
+```