jade-lang 0.3.1 → 0.5.0

data/docs/interop.md

@@ -0,0 +1,208 @@
+# Interop with Ruby
+
+Jade has no implicit side effects. All interaction with the outside world goes
+through `uses` blocks, and every port returns a `Task`.
+
+## Declaring a port
+
+The `uses` block declares the boundary types; the names come into scope
+unqualified. **Declarations are separated by commas** — a newline alone ends
+the block, so a second entry without a comma before it reads as a parse error
+(`Unexpected token "entries", expected end`).
+
+A port takes as many arguments as its type says: `A, B -> Task(…)` is a
+two-argument port, called `entries(key, limit)`. Parenthesising the arguments
+means something else — `(A, B) -> Task(…)` is a *one*-argument port taking a
+tuple, called `entries((key, limit))`.
+
+```jade
+module Store exposing (page)
+
+uses KeyValue with
+  members : String -> Task(List(String), String),
+  entries : String, Int -> Task(List(String), String)
+end
+
+
+def page(key: String) -> Task(List(String), String)
+  entries(key, 20)
+end
+```
+
+On the Ruby side, register the port with `Jade::Port`. The block receives a
+helper `t` for `t.ok(value)` / `t.err(error)`, then one parameter per declared
+argument:
+
+```ruby
+module KeyValue
+  extend Jade::Port
+
+  task :members do |t, key|
+    t.ok(REDIS.smembers(key))
+  end
+
+  task :entries do |t, key, limit|
+    t.ok(REDIS.lrange(key, 0, limit - 1))
+  end
+end
+```
+
+The block must return `t.ok(value)` or `t.err(error)` — never another `Task`.
+Composition (`map`, `and_then`, `sequence`) lives in Jade. (Pick a port module
+name that doesn't shadow a Ruby constant you rely on — `task :members` defines
+`KeyValue.members`.)
+
+## What crosses the boundary
+
+A port is the same boundary as a Jade function called from Ruby, pointed the
+other way, and it converts in both directions: **arguments are encoded on the
+way out, and the return value is decoded on the way back**. Ruby sees wire
+values — strings, numbers, hashes, arrays — never Jade's internal
+representation.
+
+```jade
+uses Scheduling with
+  shift_months : Instant, Int -> Task(Instant, Never)
+end
+```
+
+```ruby
+module Scheduling
+  extend Jade::Port
+
+  task :shift_months do |t, iso, months|
+    # iso is "2026-08-01T12:00:00Z", not a Jade::Clock::Instant
+    t.ok(Time.iso8601(iso).then { |at| (at << -months).iso8601 })
+  end
+end
+```
+
+Every argument type therefore needs an `Encodable` instance, the same way every
+`Task` arm needs a `Decodable` one. A type with neither is a compile error
+naming the argument:
+
+```
+Port `shift_months` cannot encode argument 1 (`Shape`): no Encodable instance
+```
+
+Declare the argument as `Decode.Value` to opt out and hand Ruby the value
+untouched — the arg-side counterpart of a `Decode.Value` return arm. `Value` has
+instances on both sides, so the opt-out holds when it's nested too: a
+`List(Value)` argument, or a struct with a `Value` field, crosses element by
+element with each one left alone.
+
+## Calling Jade from Ruby
+
+An exposed function gets two callable forms:
+
+```ruby
+# Boundary form — args decoded, return encoded, Task runs eagerly
+Store.page("recent")     # => ["ok", ["a", "b"]]
+Store.page!("recent")    # => ["a", "b"]   (bang form unwraps, raises on err)
+
+# Internal form — keeps the Task as a value you can compose
+task = Store::Internal.page("recent")
+task.run                 # => Jade::Result::Ok[["a", "b"]]
+```
+
+At the boundary, Ruby values are **decoded into Jade values** on the way in and
+**encoded back to Ruby** on the way out. For `Task` functions the ok-arm decoder
+runs against whatever the port returned, so a signature like `Task(User, String)`
+keeps its declared error type — you don't thread a separate `DecodeError`
+through every call.
+
+## When a function is callable from Ruby
+
+The unit here is the **function**, not the type. A function is exposed to Ruby
+only when **all of its parameters are `Decodable` and its return type is
+`Encodable`**. If any parameter can't be decoded, or the return can't be
+encoded, that whole function isn't exposed — it compiles fine and its `Internal`
+form still works, but calling the public `Module.fn` from plain Ruby raises
+`Jade::Interop::NotExposed`. The error names the part that disqualified it
+(e.g. `argument 1 of type Shape has no Decodable instance`).
+
+What takes a function out of Ruby's reach is a parameter or return type with no
+`Decodable` / `Encodable` instance — a function value, an unbound type variable,
+or a custom union you haven't given an instance.
+
+If a port returns something that doesn't decode to the declared type, the
+boundary raises `Jade::Interop::DecodeError`. This is on purpose: a port
+returning the wrong shape is a programming bug, not a runtime condition to
+recover from, so the boundary raises rather than pass on a malformed value.
+
+```jade
+module Users exposing (fetch)
+
+struct User = {
+  id: Int,
+  name: String
+}
+
+
+uses Backend with
+  raw_fetch : Int -> Task(User, String)
+end
+
+
+def fetch(id: Int) -> Task(User, String)
+  raw_fetch(id)
+end
+```
+
+```ruby
+module Backend
+  extend Jade::Port
+
+  task :raw_fetch do |t, id|
+    t.ok({ name: "Paul" })   # oops — missing :id
+  end
+end
+
+Users.fetch(1)
+# => raises Jade::Interop::DecodeError:
+#    Port returned a value that failed to decode at value: missing field `id` ({name: "Paul"})
+```
+
+The Jade caller never sees a malformed `User` — the bug is caught at the entry
+point, and the error arm (here `String`) stays meaningful for real failures.
+
+## What the compiled boundary looks like
+
+For a function with a primitive argument:
+
+```jade
+module Sample exposing (absolute)
+
+def absolute(n: Int) -> Int
+  n < 0 ? 0 - n : n
+end
+```
+
+the compiler emits:
+
+```ruby
+module Sample
+  extend self
+
+  module Internal
+    extend self
+
+    def absolute(n)
+      if ((n < 0))
+        (0 - n)
+      else
+        n
+      end
+    end
+  end
+
+  def self.absolute(n)
+    Internal.absolute(Jade::Interop::Boundary.integer("Int", n))
+  end
+end
+```
+
+Two surface methods — `Internal.absolute` (pure) and `self.absolute` (the
+boundary). `Int` has a specialized fast-path coercion; richer types decode
+through cached `Decode` constants instead. Either way the boundary work is
+visible in the file, not hidden inside a runtime hook.

data/docs/json.md

@@ -0,0 +1,163 @@
+# Decoding and encoding
+
+`Decode` turns untyped JSON / Ruby data into typed Jade values; `Encode` turns
+typed values back into JSON. Both are explicit pipelines, and both auto-derive
+for `struct` types so the common case needs no hand-written decoder or encoder.
+
+## Decoding
+
+A decoder is a value; `Decode.decode_string(decoder, json)` runs one and returns
+a `Result(a, DecodeError)`. The combinators compose:
+
+```jade
+module DecodeJson exposing (
+  age,
+  coords,
+  tags,
+  user,
+)
+
+import Decode exposing (DecodeError)
+
+
+struct User = {
+  name: String,
+  age: Int
+}
+
+
+def age(json: String) -> Result(Int, DecodeError)
+  Decode.decode_string(Decode.field("age", Decode.int), json)
+end
+
+
+def tags(json: String) -> Result(List(String), DecodeError)
+  Decode.decode_string(Decode.list(Decode.string), json)
+end
+
+
+def coords(json: String) -> Result(Maybe(Int), DecodeError)
+  Decode.decode_string(Decode.nullable(Decode.int), json)
+end
+
+
+def user(json: String) -> Result(User, DecodeError)
+  decoder = Decode.succeed(User(_, _))
+    |> Decode.required("name", Decode.string)
+    |> Decode.required("age", Decode.int)
+
+  Decode.decode_string(decoder, json)
+end
+```
+
+```ruby
+DecodeJson::Internal.age('{"age":40}')             # => Ok(40)
+DecodeJson::Internal.tags('["a","b"]')             # => Ok(["a", "b"])
+DecodeJson::Internal.coords('null')                # => Ok(Nothing)
+DecodeJson::Internal.coords('7')                   # => Ok(Just(7))
+DecodeJson::Internal.user('{"name":"Ada","age":40}')
+# => Ok(User(name: "Ada", age: 40))
+DecodeJson::Internal.user('{"name":"Ada"}')
+# => Err(MissingField("age"))
+```
+
+The struct decoder is `Decode.succeed(User(_, _))` piped through one
+`Decode.required` per field — the `_` placeholders are the constructor's holes,
+filled left to right as each field decodes.
+
+## Encoding
+
+`Encode.encode_to_string(value)` serializes; the combinators mirror `Decode`:
+
+```jade
+module EncodeJson exposing (n, point, user, xs)
+
+import Encode
+
+
+struct User = {
+  name: String,
+  age: Int
+}
+
+
+def n -> String
+  Encode.encode_to_string(Encode.int(42))
+end
+
+
+def xs -> String
+  Encode.encode_to_string(Encode.list(Encode.int, [1, 2, 3]))
+end
+
+
+def point -> String
+  pairs = [
+    Encode.field("x", Encode.int, 1),
+    Encode.field("y", Encode.int, 2),
+  ]
+
+  Encode.encode_to_string(Encode.object(pairs))
+end
+
+
+def user(u: User) -> String
+  Encode.encode_to_string(Encode.encode(u))
+end
+```
+
+```ruby
+EncodeJson.n                  # => "42"
+EncodeJson.xs                 # => "[1,2,3]"
+EncodeJson.point              # => '{"x":1,"y":2}'
+EncodeJson::Internal.user(user)
+# => '{"name":"Ada","age":40}'
+```
+
+## Auto-derivation
+
+`Encode.encode(value)` derives the encoder from the value's type, and
+`Decode.from_json(json)` derives the decoder from the **return type** — so a
+struct round-trips without writing either by hand:
+
+```jade
+module Api exposing (parse, render)
+
+import Encode
+import Decode exposing (DecodeError)
+
+
+struct User = {
+  name: String,
+  age: Int
+}
+
+
+def parse(json: String) -> Result(User, DecodeError)
+  Decode.from_json(json)
+end
+
+
+def render(user: User) -> String
+  Encode.encode_to_string(Encode.encode(user))
+end
+```
+
+Reach for the explicit combinators above when the JSON shape doesn't match the
+struct one-to-one — renamed keys, nested lookups, optional fields.
+
+Derivation reaches through the structural types to their elements, so anything
+built out of encodable parts is itself encodable:
+
+| Type | Wire form |
+|------|-----------|
+| `List(a)`, `Set(a)` | array — a set drops duplicates on the way back |
+| `Maybe(a)` | the value, or `null` |
+| `(a, b)` … `(a, b, c, d)` | array, positional |
+| `Dict(k, v)` | array of `[key, value]` pairs — a JSON object only admits string keys |
+| a `struct` | object, keyed by field name |
+| a union whose variants take no arguments | string, the variant name in snake_case |
+
+A type outside that list needs its own `implements Encodable(T)` /
+`Decodable(T)` — a union carrying arguments, say, where nothing but you knows
+which shape it should take.

data/docs/lsp.md

@@ -0,0 +1,105 @@
+# Language server
+
+Jade ships a language server, run as `jade lsp`. It speaks LSP over stdio and
+works in any editor with an LSP client.
+
+## What it does
+
+- **Diagnostics.** Type and parse errors are streamed to the editor as you type.
+- **Hover.** Hover any name, local, or expression to see its inferred type.
+- **Go to definition.** Jump from a use site to where a name is declared —
+  across modules, into the stdlib, and to interface implementations.
+- **Find references.** Every use of a name across the project, declaration
+  included.
+- **Document symbols.** The editor's outline ("show all functions in this
+  file") works.
+
+## Editor setup
+
+The server is `jade lsp` on stdio. Point your editor's LSP client at it for
+files matching `*.jd`.
+
+### Neovim
+
+```lua
+-- Treat *.jd files as filetype "jd"
+vim.filetype.add({ extension = { jd = 'jd' } })
+
+vim.lsp.start({
+  name = 'jade-lsp',
+  cmd = { 'jade', 'lsp' },
+  root_dir = vim.fs.dirname(vim.fs.find({ 'Gemfile', '.git' }, { upward = true })[1]),
+  filetypes = { 'jd' },
+})
+```
+
+### VS Code
+
+No published extension yet. The server works with any LSP-client extension that
+lets you point at a custom command (e.g. `vscode-languageclient` with a small
+wrapper that runs `jade lsp`).
+
+### Other editors
+
+If your editor speaks LSP, it'll work — the server depends on no editor-specific
+bridge.
+
+## For agents that don't speak LSP
+
+`jade q` exposes the same compiler intelligence as one-shot JSON over stdout —
+handy for agents and scripts that don't want to manage a JSON-RPC session:
+
+```
+jade q hover    file.jd:LINE:COL   # type info at a position
+jade q defn     file.jd:LINE:COL   # goto-definition target
+jade q refs     file.jd:LINE:COL   # all references (incl. declaration)
+jade q symbols  file.jd            # document outline
+jade q api      [MODULE|NAME]      # signatures, by module or symbol
+jade q find     TERM               # every symbol matching TERM
+jade q syntax   [FORM]             # how a form is written
+```
+
+`LINE` and `COL` are 0-indexed (LSP convention). Paths are relative to the
+project root; compile results are cached at `.jade/cache`, so repeat queries are
+fast.
+
+`api` and `find` cover the stdlib, the project's own modules, and any extension
+gem's — each tagged with its `origin`. Without a `jade.json` they fall back to
+the stdlib alone, so they still answer from any directory. See
+[stdlib.md](stdlib.md#finding-a-function).
+
+`syntax` answers the other half. A signature says a function exists and what it
+takes; it never says how a lambda or an `implements` block is written:
+
+```
+$ jade q syntax lambda
+{ "form": "lambda", "detail": "anonymous function", "source": "(args) -> { body }" }
+```
+
+The forms are `def`, `type`, `struct`, `case`, `if`, `module`, `import`,
+`interface`, `implements`, `uses`, `lambda` — the same corpus the editor
+offers as completions, so the two can't drift. They're templates, not
+compilable programs. It reads no files and needs no project.
+
+## Checking without an editor
+
+`jade check` type-checks and prints diagnostics, generating nothing:
+
+```
+jade check                 # every .jd under the source root
+jade check lib/orders.jd   # that file and everything it imports
+```
+
+Exit 1 if there were errors, 0 otherwise. This is the loop to close after
+editing a file — it's the same front end the LSP runs, so an invented function
+or a wrong argument order surfaces immediately instead of at the next build.
+
+## What it doesn't do yet
+
+- Autocomplete
+- Refactor / rename
+- Code actions (e.g. "add the missing case to this `case`")
+- Workspace-wide symbol search
+
+These are the natural next features; the current server is the minimum useful
+surface.

data/docs/stdlib.md

@@ -0,0 +1,69 @@
+# Standard library
+
+## Finding a function
+
+Ask the compiler, don't grep:
+
+```
+jade q api                 # every module, and where it came from
+jade q api Dict            # one module, with signatures
+jade q api List.fold       # one symbol
+jade q find fold           # everything named `fold`
+```
+
+Grep is the wrong tool here, and quietly so. Stdlib modules are written two
+ways — Jade source in a heredoc (`Maybe`, `Result`, `Decimal`, …) and a Ruby
+DSL (`List`, `String`, `Dict`, `Decode`, …) — so half of them never spell `def`
+at all, and none of them contains the string `List.map` you'd search for.
+Extension modules aren't in your tree at all; they live in a gem. A grep that
+comes back empty means nothing.
+
+`jade q api` reads the registry the compiler itself resolves against, so it
+can't drift from what exists. It answers what grep can't: the argument order
+(`List.fold` folds with `(b, a) -> b`, `Dict.fold` with `(k, v, b) -> b`), the
+interface constraints (`List.sort : Comparable a => …`), a struct's fields
+(`struct Date = { year : Int, month : Month, day : Int }`), and which types
+implement `Decodable` or `Encodable`.
+
+Run inside a project and it covers three origins, each tagged in the output:
+
+| `origin` | what |
+|---|---|
+| `stdlib` | the modules below |
+| `project` | your own `.jd` files, under the source root |
+| `extension` | modules an extension gem ships (`jade-sql`'s `Sql.Query`, …) |
+
+Without a `jade.json` it falls back to the stdlib alone, so the query still
+works from anywhere. A file that won't compile is named under `skipped` rather
+than quietly missing — an absent module reads as "that function doesn't
+exist", which is the failure this is here to prevent.
+
+## What's where
+
+Every module's source lives in [`lib/jade/stdlib/`](../lib/jade/stdlib/) — short,
+readable Ruby. This is a map of the territory; `jade q api` is the atlas.
+
+| Module | What's there |
+|--------|--------------|
+| `Basics` | The built-in interfaces — `Eq`, `Comparable`, `Appendable`, `Mappable`, `Chainable` — plus the `Ordering` type (`LT` / `EQ` / `GT`) and `Never`. `++` works on `String`, `List`, and `Bytes` via `Appendable`. |
+| `Maybe` | Optional values without `nil`: `Just(a)` / `Nothing`, with `map`, `and_then`, `with_default`. |
+| `Result` | Errors as values, no exceptions: `Ok(a)` / `Err(e)`, with `map`, `and_then`, `map_error`, `on_error`, `sequence`. |
+| `List` | Immutable lists: `map`, `filter`, `fold`, `zip`, `sort`, `length`, `range`, `head`, `tail`, `take`, `drop`, … |
+| `String` | Text: `length`, `reverse`, `split`, `trim`, `to_int`, `contains?`, `uncons`, `cons`, `from_char`, `map`. |
+| `Char` | Character predicates and codes: `to_code`, `from_code`, `digit?`, `alpha?`, `alpha_numeric?`, `upper?`, `lower?`. |
+| `Tuple` | Pair accessors: `first`, `second`, `pair`. |
+| `Task` | Side-effecting actions: `succeed`, `fail`, `map`, `and_then`, `on_error`, `sequence`. See [interop.md](interop.md) for how Tasks cross the Ruby boundary. |
+| `Decode` | Parse JSON / Ruby data into typed values: `string`, `int`, `float`, `bool`, `list`, `field`, `index`, `succeed`, `required`, `optional`, `nullable`, `map`, `and_then`. Auto-derived for `struct` types. See [json.md](json.md). |
+| `Decode.Params` | PATCH-style decoders: only fields present in the input appear in the output, missing fields don't error. For partial-update endpoints. |
+| `Encode` | Symmetric to `Decode`: `string`, `int`, `float`, `bool`, `list`, `object`. Auto-derived for `struct` types via `Encodable`. |
+| `Dict` | Immutable key-value map with structural equality: `empty`, `get`, `member?`, `insert`, `update`, `remove`, `keys`, `values`, `to_list`, `from_list`, `map`, `filter`, `fold`, `union`, `merge`. |
+| `Set` | Immutable set: `empty`, `insert`, `remove`, `member?`, `to_list`, `from_list`, `map`, `filter`, `fold`, `union`, `intersect`, `diff`. |
+| `Bytes` | Opaque byte buffer: `empty`, `width`, `from_list` / `to_list`, `from_string` / `to_string`. Implements `Eq` and `Appendable`. |
+| `Calendar` | Dates and date arithmetic: `Date`, `today`. Days, months, years; no time of day — use `Clock`. |
+| `Clock` | Timestamps and monotonic timing: `Instant`, `now`. Sub-second precision; the bridge to wall-clock time. |
+| `Show` | Renders a value the way Jade writes it: `show(Just(7))` is `"Just(7)"`, `show(Point(3, 4))` is `"Point { x: 3, y: 4 }"`. Instances for the primitives; derives for unions, structs, records and lists. A function shows as `<function>`, and `Never` raises — it has no values. |
+| `Debug` | `log(label, value)` prints `label: value` to stderr and returns the value untouched, so it drops into a pipeline. Unconstrained, unlike `Show`. |
+| `Decimal` | Exact base-10 decimals (`coefficient * 10 ^ exponent`) — money and rates without `Float` rounding. Opaque; build with `of` / `scaled` / `parse`. Arithmetic via `Numeric` (`+` `-` `*` `/`), plus `div` (scaled, half-up), `round`, `to_i`, `to_float`. JSON-encodes to a `<mantissa>e<exponent>` string. |
+
+Stdlib operations compile inline rather than through a runtime dispatch layer,
+so the generated Ruby calls the underlying operation directly.