jade-lang 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b817b13aad1b314b6a8bf578f8a604246d19091712a77375376515732b6dcbc
-  data.tar.gz: 7be6b4091ac7c57c6befe21fb0ffbea302b9e33bd2940479b7c4227dd37cd1b6
+  metadata.gz: ba543580eec5d50cae2249c010a03f7a56a96f276705b3b87df7f25f06ff8eeb
+  data.tar.gz: 15923caf94302e7326aef6cc8a0e581c349b7b46d54ae4898e6bd8d8529657cf
 SHA512:
-  metadata.gz: 9b758da80e8b9033dd6b5ce840188f7d69a8d482cf496a3731c4a4f7b5bcb90ddd0119e5b5eb6e9b1763bddffca4f3df49b6cba7d6a26d9304538efde7a8aa49
-  data.tar.gz: 22abc8374f37d7f9ff3c03f5f2a35861322f234227c3d0932e80c56e17bb49de5ce6ac67dc7c1f0b1896ce2b9a5c3562a2d8197f697f74fdd5d18e5db64094f6
+  metadata.gz: 3906343d3094e2b9142aebc9324722c584db45dfb0951d6546d917794559a8cb9249d9ff4243bb380dc383932e78b93609455743a9e349ec3b60086450693846
+  data.tar.gz: 841c318dc43aa3e99df702eba6ffda7621b5a8c0f97e9302f2d75ef2149a36bcc19a1287d26a3cef5091c1361508d333a964f9eb70094e30a5791e8c4f8394a9

data/CHANGELOG.md

@@ -4,27 +4,396 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.10.0] - 2026-09-02
+
+### Breaking
+
+- **Division cannot divide by zero.** `a / b` used to raise Ruby's
+  `ZeroDivisionError` straight through Jade, so `Int -> Int -> Int` was not as
+  total as it read. `/` now takes a `NonZero`, which only `non_zero(n)`
+  produces, and it hands back a `Maybe` so the caller decides what an absent
+  answer means. A literal divisor is already known: `cents / 100` is unchanged,
+  and `n / 0` is a compile error rather than an expression that type checks.
+  `NonZero` has no constructor and is erased at runtime, so division costs what
+  it costs in Ruby.
+
+  ```jade
+  def each(total: Int, people: Int) -> Maybe(Int)
+    Maybe.map(non_zero(people), (d) -> { total / d })
+  end
+  ```
+
+  Implementing `Numeric` for your own type means `(/): a -> NonZero(a) -> a`,
+  with `Number.unwrap` to unwrap the divisor. `Decimal.div` takes a `NonZero`
+  for the same reason.
 
 ### Added
 
-- **`Jade::Extensions`, where a gem hooks into compilation.** Two kinds, both
-  read-only: a *deriver* builds an implementation for an interface it owns,
-  and a *check* reads a call site and returns errors. Checks register against
-  a named phase — `:call` today — and receive the call's AST node alongside
-  its resolved argument types, because types alone cannot see a raw SQL
-  string's placeholders or a constant predicate. Only gems named in
-  `Extensions::ALLOWED` may register, so the compiler knows who extends it and
-  nothing about what they do.
+- **An anonymous record crosses to Ruby.** `def origin -> { x: Int, y: Int }`
+  returned `NotExposed`: `Encodable` derived for a `struct` but not for the
+  same shape written inline, so a function returning one was unreachable from
+  Ruby though every field was encodable. It now derives structurally, the way
+  `Decodable` already did, and a record with a field that has no instance
+  still refuses.
+
+- **`type alias Name = T`.** A structural name for a type that already exists:
+  `type alias UserId = Int`, `type alias Point = (Float, Float)`,
+  `type alias User = { name: String, age: Int }`. The alias and its body are
+  the same type, so a record literal satisfies a record alias directly and no
+  constructor is introduced. Aliases take parameters
+  (`type alias Pair(a) = (a, a)`). An alias without parameters is expanded
+  during forward declaration and a parameterised one when its arguments are
+  known, which is what makes `UserId` and `Int` interchangeable everywhere.
+
+  An alias has no identity of its own, so it carries no implementations:
+  `implements Show(UserId)` is rejected rather than silently attaching to
+  `Int`, where it would collide with every other alias over `Int`. What an
+  alias *inherits* needs no declaring — `Encode.encode` on a `UserId` is
+  `Encode.encode` on an `Int`. A recursive alias is rejected too. Reach for
+  `struct` when you want a distinct type, or a single-variant `type` for a
+  newtype around an inner shape.
+
+  `jade fmt` breaks a record alias past one field the way it breaks the
+  `struct` beside it, and `alias` is a contextual keyword — read as one only
+  directly after `type` — so a record field or argument may still be called
+  `alias`.
+
+  Expansion reaches the edges too: an alias over a `Task` is a port return
+  type and cannot hide a nested one, a function type behind an alias is still
+  refused for interop, an alias cannot stand between a type and itself and
+  hide that there is no way to build one, `implements` on an *imported* alias
+  is reported rather than reaching codegen, and `exposing (UserId(..))` says
+  an alias has no constructors instead of accepting it silently.
+
+  The name survives expansion for the sake of reading: a mismatch against a
+  `UserId` says `should be UserId (= Int)` rather than `should be Int`, and
+  keeps the short name in a nested position (`List(UserId)`). `jade api`
+  reports an alias as an alias rather than as a function, and hovering one in
+  an editor gives its declaration — on the declaration itself and on every use
+  in a signature.
+
+- **`jade eject`.** Writes the project as Ruby that runs without the gem: every
+  compiled module, the runtime they call, and requires pointing at each other
+  rather than at a load path. What it vendors is whatever a booted runtime
+  loads, asked at eject time rather than kept as a list, so it cannot drift.
+  The exit was a promise before this; now it is a command with a spec that
+  runs the ejected tree in a process that has no jade on its load path.
+
+- **A guard on what the runtime loads.** Compiled code requires
+  `jade/runtime` and nothing else, so whatever that pulls in ships in every
+  production image and has to be vendored by an eject. A spec now pins the
+  set to seven files and fails if the parser, the AST, the frontend, the
+  formatter, the LSP or the CLI appear. Booting the intrinsics still does
+  pull the compiler in, and that example is pending rather than passing.
+
+- **The LSP indents while you type.** It advertised `documentFormattingProvider`
+  and nothing else, so an editor without the tree-sitter grammar left the cursor
+  at column 0 after every Enter. `documentOnTypeFormatting` now indents the line
+  Enter opened, and puts `end` back where its opener sits, from the text above
+  the cursor rather than a parse, which a half-written file will not give.
+
+- **`_` works in a tuple or record literal.** `5 |> (_, "five")` and
+  `{ w: _, h: 2 }` make a function of the hole, the way `f(_, y)` already did.
+  A variant carrying a record gets it too, since that is what a keyed call
+  lowers to: `Rect(w: _, h: 4)` was the one shape with no way to express it
+  short of writing the lambda out.
+
+- **`(x, y) = p` destructures a tuple.** A tuple's arity is fixed by its type,
+  so the binding is irrefutable exactly as `T(x, y) = t` already was; the
+  workaround was a three-line `case` for a destructure that cannot fail. The
+  pattern was accepted all along, but a `(` opening a line was read as a call
+  on whatever the line above ended with, so the binding never got the chance.
+
+- **`List.sum` and `List.product`.** Both fold over `Numeric`, which gained
+  `from_int : Int -> a` so the seed can come from the interface rather than the
+  list: `sum([])` is `0`, not "nothing", so a `Maybe` return would have modelled
+  a non-problem as a failure. `Int` implements it with `identity`, `Float` with
+  `to_float`, `Decimal` by scaling. A type of your own that implements `Numeric`
+  needs the new member.
+
+- **A call short of its arguments says so.** `Rec(id: 1, status: Issued)`,
+  where `Issued` carries an `Int`, reported `expected (Int, Status) -> Rec but
+  found (Int, (Int) -> Status) -> Rec` and left the reader to notice which slot
+  had become a function. It now adds ``help: `Issued` needs 1 argument``, and a
+  call with the wrong number of arguments outright reads ``help: `add` takes 2
+  arguments, 1 given``.
+
+- **A call with a hole and one argument too many says so.** `xs |> f(_, y)`
+  reads as though the `_` marks where the piped value goes, but `|>` has
+  already put it in front. The message now names the shape and the fix
+  instead of leaving a unification failure to be decoded.
+
+- **The `module` snippet fills in the name.** A module's name is fixed by its
+  path, so the placeholder was offering a decision with one right answer;
+  completion now derives it from the document URI, turning `sql/mutation.jd`
+  into `module Sql.Mutation exposing (...)`.
 
 ### Changed
 
-- **The `Sql.Assignable` deriver moves to jade-sql.** The deriver list named
-  jade-sql's interface outright, with a comment apologising for it; it now
-  holds only the built-ins and whatever an allowed gem registers.
+- **A crossing does less on the way in.** An argument with a specialized
+  decoder now carries its own name, in a string constant it was passing
+  anyway, so the wrapper no longer opens a block per argument just to label a
+  failure. And a hash is no longer scanned for symbol keys before its fields
+  are read: symbol keys make every field missing at once, which the rescue
+  around the fields already notices, so the message is unchanged and the check
+  is gone from the success path. A struct argument goes from 772ns to 724ns, a
+  scalar argument from 158ns to 127ns, and decoding a list of 1500 structs
+  from 940us to 820us.
+
+- **A dictionary built from concrete implementations is built once.** Calling
+  a function with an interface constraint at a known type emitted the whole
+  dictionary as a literal at the point of use, so `List.sum(xs)` on a
+  `List(Int)` allocated a 5-entry Hash, an Array and two lambdas on every
+  call, 522ns before any adding happened. Inside a fold the literal landed in
+  the block and was rebuilt per element. Dictionaries that name no dict
+  parameter now become frozen module constants, shared by every call site
+  that wants the same one, and referencing an interface method as a value no
+  longer builds a Hash to index it once. A fold over 5000 values goes from
+  7.3x the equivalent Ruby to 3.3x, a per-row `List.sum` from 2.8x to 2.0x.
+
+- **A variant with no fields is one object, not a new one per construction.**
+  `compare` allocated a fresh `GT` on every call, which cost more than the
+  comparison: 214ns against Ruby's 23ns for `<=>`. Nullary variants carry no
+  state, so nothing can tell two instances apart, and every construction now
+  hands back the same object. `compare` drops to 87ns, and a function
+  returning a three-arm enum over 5000 values goes from 5.7x the equivalent
+  Ruby to 2.7x. Applies to `Maybe.Nothing`, `Result` arms, `Order` and every
+  user enum.
+
+- **A rejected value says where in the value the problem is.** A field that
+  did not decode reads `Shop.total(items)[0].cents: expected Int, got String
+  ("lots")` rather than blaming the argument as a whole, and a field the hash
+  never had reads `missing field \`cents\`` rather than `expected Int, got
+  nil`. Paths cost nothing on the way in: the segments are constants in the
+  generated code, and the index of a bad element is found only when one is.
+
+- **A build left by another version of the compiler is rebuilt.** Generated
+  Ruby calls the runtime by name, so a build made by a different version can
+  call a helper this one no longer has. `.jade/build` now carries the
+  fingerprint that `.jade/cache` already used, and is dropped when it does not
+  match. No source changes in that case, so mtimes could not see it.
+
+- **A value Ruby cannot pass says which call and which argument rejected it.**
+  `Ruby passed a value that failed to decode at value: expected Int, got null
+  (nil)` is now `Shop.price(item): expected Int, got nil`. The caller may not
+  know Jade, so the message names the function, the argument it came in as, and
+  types in Ruby's vocabulary rather than the wire's.
+
+- **`jade fmt` hugs a trailing block argument.** A call whose last argument is
+  a lambda, list or record literal keeps its head on one line and lets that
+  argument grow a body, the way a Ruby block reads:
+
+  ```jade
+  describe("Math", [
+    it("adds", -> { Expect.equal(1 + 1, 2) }),
+  ])
+  ```
+
+  It previously broke every argument onto its own line, burying the call the
+  body belonged to. The head still breaks when it cannot fit, or when an
+  earlier argument is the one that grew.
+
+  Two shapes that left output hanging go with it: a lambda whose inline body
+  broke anyway (`-> { Decode.map(` … `}) }`) now uses the block form, and a
+  `|>` or `++` operand that breaks across lines keeps its continuation under
+  the operator that introduced it rather than at column zero. **Formatted
+  output differs from 0.4.0** — a format check in CI reports diffs on the
+  first run after upgrading. Over 65 real modules, 25 reformat; formatting is
+  idempotent on all of them.
+
+- **A `(` that opens a line starts a statement rather than continuing the one
+  above.** `foo` on one line and `(1, 2)` on the next is now two statements, not
+  a call. The same rule applies to a type's arguments, so a return type no
+  longer reaches across a newline to swallow the body's first line.
+
+### Removed
+
+- The error saying a record literal has no placeholder, which is no longer
+  true. `Name(field: _)` on a *positional* variant still reports: there are no
+  field names there to refer to.
 
 ### Fixed
 
+- **Generated Ruby no longer makes Ruby complain.** An interop import emitted
+  its `rescue LoadError` indented as though it were part of the `begin` body,
+  which Ruby warns about under `-w`, and the runtime had a circular require
+  between `jade/task` and `jade/tasks` that neither file needed at load time.
+  The ejected examples are now loaded in a fresh process under `-w` and the
+  suite fails if Ruby says anything at all, which is the check that would have
+  caught a module and a type sharing a constant on its own.
+
+- **A type that contains itself no longer exhausts the stack at compile
+  time.** `type Tree = Leaf | Node(Tree, Tree)` compared with `==` raised
+  `SystemStackError` from the compiler, naming a Ruby frame rather than
+  anything you wrote: deriving an instance asks for its components'
+  instances, and `Tree`'s component is `Tree`. So did a struct that reaches
+  itself, `struct Pepe = { pepe: Maybe(Pepe) }`, on `==` or at the Ruby
+  boundary.
+
+  Equality now works on both: a derived `Eq` is structural, and Ruby's `==`
+  computes exactly that, dispatching to whatever each component defines — so a
+  component with a hand-written `implements Eq` is still asked. `Encodable`
+  and `Decodable` say `cannot be derived for Pepe because it contains itself`
+  and point at writing the implementation by hand, which was always the answer
+  and used to arrive as a crash.
+
+- **A recursive type with nothing to stop it is reported where it is written.**
+  `struct Pepe = { pepe: Pepe }` declared fine and read fine; you found out at
+  the use site, in a message about the argument you passed rather than about
+  the declaration that can never be satisfied. It now says so at the
+  declaration, along with the way out:
+
+  ```
+  error: `Pepe` can never be built: every `Pepe` needs a `Pepe` inside it first
+    --> src/pepe.jd:3:1
+    |
+  3 | struct Pepe = { pepe: Pepe }
+    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ nothing here stops the recursion
+    |
+    = note: a type may refer to itself; `Pepe` just has no case that stops,
+            so there is no smallest `Pepe` to start from
+    = help: wrap the field in something that has an empty case:
+            `Maybe(Pepe)` can be `Nothing`, `List(Pepe)` can be empty
+  ```
+
+  A type referring to itself is the point of a union, so what is checked is
+  whether there is a way out: `Maybe` has `Nothing`, `List` has `[]`, `Result`
+  has its `Err` arm, a union has any variant that does not lead back. All of
+  those still compile, `struct Pepe = { pepe: Maybe(Pepe) }` included, and so
+  does a field holding a function that returns the type, since the function
+  itself can be written. `type T = A(T)`, two declarations that need each
+  other, and a struct reaching itself through a tuple do not.
+
+- **A module may be named after a type in its parent.** `module Sql.Expr`
+  beside `type Expr` in `Sql` compiled without complaint and then emitted two
+  definitions of one Ruby constant, so whichever file loaded second silently
+  took the name and calls into the other failed with a `NoMethodError` and a
+  Ruby warning. The module now reopens the type's class rather than defining a
+  module beside it, which is what Ruby wants and what Elixir does with the
+  same pair. Constructing, pattern matching and the module's own functions all
+  work together.
+
+- **A list from Ruby is copied, not borrowed.** A `List(Int)` argument came
+  through as the caller's own Array, so pushing to it after the call changed a
+  value Jade had already taken. Lists of structs were copied already, by the
+  decoder that builds them; only the scalar fast path handed the object
+  straight through. The copy costs 0.3us for 1500 elements against the 46us
+  the element check already spends, so under 1% of a crossing that was already
+  paying to look at every element.
+
+- **A Jade name that is a Ruby keyword compiles.** `begin`, `next`, `class`,
+  `self`, `return` and 20-odd others are ordinary Jade identifiers, and
+  emitting them verbatim produced Ruby that would not parse — a local or
+  parameter called `next` was a syntax error in the generated file, not a
+  message from the compiler. Bindings now carry a trailing underscore
+  (`next_`), and a name that already ends in one gains another so `next` and
+  `next_` stay distinct.
+
+  Only bindings are rewritten. Ruby accepts its keywords as method names and
+  as `Data` members, so a function called `next` is still `Mod.next` from Ruby
+  and a field called `class` is still `class` on the wire.
+
+- **`examples/records.jd` compiles.** `update_email` built an anonymous record
+  where a `Person` was wanted, and nothing compiled the file: the examples
+  suite skipped it. It now uses a record update, and the suite covers it.
+
+- **A running app no longer loads the compiler.** `Runtime.boot!` read the
+  stdlib files for their implementations and got their declarations too, so
+  every production image carried the parser, the AST and the type checker:
+  301 files, 22k LOC, 171 ms. Those files are now read in a mode that
+  registers the intrinsics and skips the declarations, which is 53 files and
+  23 ms, and the compiler reads them again in full when it arrives. It also
+  fixes a latent break: `require 'jade/runtime'` followed by `boot!`, with no
+  `require 'jade'` first, used to raise.
+
+- **A mismatch spanning a mismatch already reported is dropped.** Cascade
+  suppression caught the case where both errors mention the same inference
+  variable; where the outer one had resolved to concrete types it named no
+  variable, and the same fault was still reported twice, at the call and at the
+  body around it.
+
+- **A module whose only declaration is half-written no longer crashes the
+  tolerant parser.** Recovery drops a declaration it cannot parse, and the
+  module node took its span from the last one, so a file with nothing left
+  raised `undefined method 'range' for nil` inside the parser. In the editor
+  that surfaced as a crash notice on a file you were part-way through typing,
+  which is the state it exists to cope with.
+
+- **The LSP reports errors in files you do not have open.** It compiled from
+  each open buffer, so a module nobody had opened was only ever reached as
+  someone else's import, and a broken one that nothing imports was reported
+  nowhere. Opening or closing a file now compiles every module under the source
+  root, starting from the modules nothing imports so the pass covers the project
+  once, and diagnostics published for a file are cleared when it is fixed even
+  if it was never open. Typing still recompiles only what is open, and the LSP
+  now reads and writes the project's compile cache the way the CLI does.
+
+- **`List.range` returns `List(Int)`.** Its signature said `List(a)`, with the
+  `a` free and bound by nothing, so `List.range(1, 3)` type-checked as a list
+  of anything the caller happened to want.
+
+- **Parse errors no longer name `lbrace` where a `{` could never go.** An
+  alternation reported whichever branch it tried last, and a record literal is
+  last in several chains, so `module Pepe exposing`, `def f -> Int end`, and
+  `(x, y) = p` all came back as "expected lbrace". A failure on the token the
+  alternation started from now says what the position wanted (an expression, a
+  type, a declaration), while a failure further in, which got somewhere, is
+  still the one reported. `exposing` also commits on its keyword, so a header
+  stopped after it asks for `(` rather than blaming the body.
+
+- **An empty body says so.** `def f -> Int end` reported `expected lbrace` and
+  underlined the `end`, the one token there that was certainly right. It now
+  reads `expected an expression (a body has to produce a value)` and underlines
+  the construct the body belongs to. Every function passes through that state
+  while it is being typed.
+
+- **`Name(field: _)` on a variant explains which variant you have.** The
+  message stated the rule; it now says whether the arguments have no names at
+  all (offering the `|>` form, which needs no placeholder) or carry a record
+  (offering the lambda). A positional variant no longer also reports every key as an
+  unknown field.
+
+- **The LSP reads `jade.json`.** `on_initialize` took the editor's root as the
+  source root, so in a project with `"source_roots": ["lib"]` every module was
+  named from the project root: the editor demanded `Lib.Test` while the
+  compiler compiled `Test`. Reading the manifest also loads the extension gems
+  whose modules a project imports.
+
+- **A crashed compile publishes a diagnostic instead of silence.** Zero
+  diagnostics is indistinguishable from a clean file, so an LSP bug looked
+  exactly like working code.
+
+- **One mistake, one message.** `t |> Plan(_, 150)` reported four errors: the
+  call that failed to unify, the expression around it, and the body that
+  returned it, each wearing the type the one below left behind. Mismatches on a
+  single span are now read as one failure: the most specific of them survives,
+  since a subclass exists for no other reason. A later error naming an
+  inference variable an earlier one already named is downstream of it, so it
+  goes too. Errors that share nothing still both appear.
+
+- **Inference ids no longer leak into messages.** `t8894` is a counter: it
+  means nothing to a reader, it changes between compiles, and two occurrences
+  of one variable look unrelated unless you notice the digits match. Within a
+  message they render as `a`, `b`, `c`, the letters the signature syntax
+  already uses. The ids stay internal.
+
+- **A module named after its principal type loads.** `module Plan` holding
+  `type Plan` emitted `Plan::Building` and `Plan::Internal`, which Ruby resolves
+  lexically: inside `module Plan` the constant `Plan` is the *type*, so those
+  became `Plan::Plan::Building` and died at load with `uninitialized constant`,
+  after compiling clean. Every reference to generated code is now rooted;
+  constructor calls already were, patterns and `Internal` calls were not.
+  Naming a module after its type (`Plan`, `Member`, `Money`) is ordinary, so
+  this would have kept happening.
+
+- **The same type declared twice is an error.** Two `type AgeTiers` blocks in
+  one module compiled, emitted both, and left the *Ruby interpreter* to mention
+  it with `warning: already initialized constant`, naming the generated file
+  rather than the `.jd`. The clash check only fired between kinds (a `struct` against a
+  `type`); it now fires within a kind too, and moved to the pass that can still
+  see both declarations, so the error lands on the second and points at the
+  first.
+
 - **A long chain of `Task.and_then` no longer exhausts the Ruby stack.** Each
   `and_then` ran the next task from inside the previous one's `run`, so depth
   cost a stack frame and anything built by recursion, a batch loop or a retry,
@@ -43,6 +412,25 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   only arise within one module: the orphan rule and cycle detection between
   them rule out the cross-module case.
 
+## [0.9.0] - 2026-08-21
+
+### Added
+
+- **`Jade::Extensions`, where a gem hooks into compilation.** Two kinds, both
+  read-only: a *deriver* builds an implementation for an interface it owns,
+  and a *check* reads a call site and returns errors. Checks register against
+  a named phase — `:call` today — and receive the call's AST node alongside
+  its resolved argument types, because types alone cannot see a raw SQL
+  string's placeholders or a constant predicate. Only gems named in
+  `Extensions::ALLOWED` may register, so the compiler knows who extends it and
+  nothing about what they do.
+
+### Changed
+
+- **The `Sql.Assignable` deriver moves to jade-sql.** The deriver list named
+  jade-sql's interface outright, with a comment apologising for it; it now
+  holds only the built-ins and whatever an allowed gem registers.
+
 ## [0.8.0]
 
 ### Added

data/docs/interop.md

@@ -166,6 +166,21 @@ Users.fetch(1)
 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.
 
+## Reading a rejection
+
+A value that does not cross is reported at the path where it went wrong,
+starting from the call the Ruby caller made:
+
+```
+Shop.price(item).cents: expected Int, got String ("lots")
+Shop.total(items)[0].cents: missing field `cents`
+```
+
+`missing field` means the key was absent, as opposed to present and holding
+something of the wrong type. Only the failing call pays for any of this: the
+path segments are constants in the generated code, and the index of a bad
+element is searched for only once an element has failed.
+
 ## What the compiled boundary looks like
 
 For a function with a primitive argument:
@@ -197,7 +212,9 @@ module Sample
   end
 
   def self.absolute(n)
-    Internal.absolute(Jade::Interop::Boundary.integer("Int", n))
+    Internal.absolute(
+      Jade::Interop::Boundary.arg("Sample.absolute(n)") { Jade::Interop::Boundary.integer("Int", n) },
+    )
   end
 end
 ```

data/docs/stdlib.md

@@ -47,6 +47,7 @@ readable Ruby. This is a map of the territory; `jade q api` is the atlas.
 |--------|--------------|
 | `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`. |
+| `Number` | `non_zero(n)`, the only way to hold the `NonZero` that `/` asks for. A literal divisor other than zero is one already, so `cents / 100` needs nothing; a divisor that is a value goes through `non_zero` and comes back a `Maybe`. `unwrap` gives back the plain number, for anyone implementing `Numeric` themselves. |
 | `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`. |
@@ -63,7 +64,8 @@ readable Ruby. This is a map of the territory; `jade q api` is the atlas.
 | `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. |
+| `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, taking a `NonZero`), `round`, `to_i`, `to_float`. JSON-encodes to a `<mantissa>e<exponent>` string. |
+| `Range` | An inclusive span over any `Comparable`, open at either end or both. Opaque; build with `a..b` or `between` / `from` / `to` / `empty` / `all`, where `between` reads a descending pair as `empty` rather than as a range. Ask with `contains?`, `overlaps?`, `intersect`, `clamp`, `lower`, `upper`, `bounded?`, `empty?`. Not the same thing as a range pattern: `in 0..3` is checked for coverage when the code is compiled, and a `Range` is a value. |
 
 Stdlib operations compile inline rather than through a runtime dispatch layer,
 so the generated Ruby calls the underlying operation directly.

data/docs/syntax.md

@@ -90,6 +90,57 @@ Anonymous records do not coerce into nominal structs: passing
 
 → [`examples/records.jd`](../examples/records.jd)
 
+## Type aliases
+
+A name for another type, with no runtime identity of its own:
+
+```jade
+type alias UserId = Int
+type alias Point = (Float, Float)
+type alias Handler = Int -> Int
+type alias Pair(a) = (a, a)
+
+type alias User = {
+  name: String,
+  age: Int
+}
+```
+
+`UserId` and `Int` are the same type, and a record literal satisfies `User`
+directly:
+
+```jade
+u1 = { name: "Paul", age: 55 }
+u2 = { u1 | age: 56 }
+name = u1.name
+```
+
+An alias never has its own constructors or interface implementations, so
+`implements Show(UserId)` is a compile error — two aliases over the same body
+are the same type, so the implementation would land on `Int` and collide with
+every other one. Reach for `struct` when you want a distinct type, or a
+single-variant `type` when you want a newtype around an inner shape.
+
+Interfaces an alias *inherits* work as you would expect, because the alias is
+gone by the time they are resolved: `Encode.encode` on a `UserId` is
+`Encode.encode` on an `Int`, and on a `User` it encodes the record.
+
+| | identity | construct with |
+| --- | --- | --- |
+| `struct User = { … }` | nominal, distinct from a same-shaped record | `User("Paul", 55)` |
+| `type User = User({ … })` | nominal newtype wrapping an inner shape | `User({ … })` |
+| `type alias User = { … }` | structural, a readability name | `{ … }` |
+
+Recursive aliases are rejected: use a `type` for a recursive shape. A cycle is
+reported once, against the first alias in it that was declared.
+
+`alias` is only a keyword directly after `type`, so a field or argument may
+still be called `alias`.
+
+The name survives into messages — a mismatch against a `UserId` reads
+`should be UserId (= Int)` — and hovering one in an editor gives its
+declaration.
+
 ## Anonymous records and tuples
 
 ```jade
@@ -184,6 +235,51 @@ def area(shape: Shape) -> Float
 end
 ```
 
+**Ranges** match a span of `Int`, with `..` including both bounds. Either
+bound may be left off to run to infinity:
+
+```jade
+module Bands exposing (band)
+
+def band(age: Int) -> String
+  case age
+  in ..-1 then "unborn"
+  in 0..2 then "infant"
+  in 3..12 then "child"
+  in 13.. then "adult"
+  end
+end
+```
+
+Those four arms partition `Int`, so the `case` needs no `else`. A range that
+leaves a gap is reported with the gap named — omitting `in 3..12` above gives
+*Missing cases: `3..12`* — and one already covered by an earlier arm is
+reported as unreachable.
+
+There is no exclusive form. Over `Int` every half-open range has an exact
+inclusive spelling (`3...12` is `3..11`), so a second operator would buy
+nothing and cost a lifetime of remembering which is which. Ranges are `Int`
+only for the same reason: `0..2` and `3..12` sit next to each other with
+nothing in between them to be missed, which is not true of `Float`.
+
+The same spelling builds a `Range` value in expression position, where the
+bounds are ordinary expressions rather than literals:
+
+```jade
+module Bookings exposing (clashes?)
+
+def clashes?(check_in: Date, check_out: Date, other: Range(Date)) -> Bool
+  Range.overlaps?(check_in..check_out, other)
+end
+```
+
+`..` binds looser than `+` and `-`, so `0..n - 1` is `0..(n - 1)`. It is
+non-associative — `a..b..c` is an error, not a nesting — and it is infix
+only: the endless forms are `Range.from(a)` and `Range.to(b)`, because a
+token that is prefix, infix and postfix by turns costs more to read than two
+names do. A descending pair is `Range.empty` rather than an error, since
+`0..(n - 1)` with `n = 0` is the ordinary way an empty range arises.
+
 **Lists** match with `[]` and `[head | tail]`; the rest after `|` must be a
 name or wildcard:
 

data/lib/jade/api.rb

@@ -70,6 +70,7 @@ module Jade
     KIND_ORDER = {
       'type' => 0,
       'struct' => 0,
+      'alias' => 0,
       'interface' => 1,
       'constructor' => 2,
       'function' => 3,
@@ -153,6 +154,7 @@ module Jade
       case symbol
       in Symbol::Union then 'type'
       in Symbol::Struct then 'struct'
+      in Symbol::Alias then 'alias'
       in Symbol::Interface then 'interface'
       in Symbol::Constructor | Symbol::Variant then 'constructor'
       else 'function'
@@ -167,6 +169,9 @@ module Jade
       in Symbol::Struct
         "struct #{symbol.name}#{type_params(symbol.type_params)}#{fields(symbol)}"
 
+      in Symbol::Alias
+        "type alias #{symbol.name}#{type_params(symbol.type_params)} = #{body(symbol)}"
+
       in Symbol::Interface
         "interface #{symbol.name}(#{symbol.type_param.name})"
 
@@ -192,6 +197,10 @@ module Jade
       end
     end
 
+    def body(symbol)
+      declared(symbol.body).then { |(type, _)| type }
+    end
+
     def fields(symbol)
       return '' unless symbol.record_type