jade-lang 0.9.0 → 0.10.1

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
 

data/lib/jade/ast.rb

@@ -32,6 +32,7 @@ module Jade
     define(:TypeParam, :name)
     define(:ImportDeclaration, :module_name, :as, :exposing)
     define(:StructDeclaration, :name, :type_params, :record_type)
+    define(:TypeAliasDeclaration, :name, :type_params, :body_type)
 
     define(:ExposeAll)
     define(:ExposeNone)
@@ -84,6 +85,7 @@ module Jade
 
       define(:Wildcard)
       define(:Literal, :literal)
+      define(:Range, :from, :to)
       define(:Binding, :name)
       define(:Constructor, :constructor, :patterns)
       define(:Record, :fields)
@@ -364,11 +366,17 @@ module Jade
           module_parts.map(&:value).join('.'),
           exposing,
           body,
-          module_parts.first.range.begin...(body.expressions.last.range.end),
+          module_parts.first.range.begin...module_end(module_parts, body),
         ]
       end
     end
 
+    # Tolerant mode drops a declaration it cannot parse, so a module whose
+    # only declaration is half-written has an empty body.
+    def module_end(module_parts, body)
+      body.expressions.last&.range&.end || module_parts.last.range.end
+    end
+
     def if_then_else
       ->((if_token, condition, if_branch, else_branch, end_token)) do
         IfThenElse[
@@ -442,6 +450,22 @@ module Jade
       end
     end
 
+    def range_pattern
+      ->((from, dotdot, to)) do
+        Pattern::Range[
+          from,
+          to,
+          from.range.begin...(to&.range&.end || dotdot.range.end),
+        ]
+      end
+    end
+
+    def unbounded_below_pattern
+      ->((dotdot, to)) do
+        Pattern::Range[nil, to, dotdot.range.begin...to.range.end]
+      end
+    end
+
     def binding_pattern
       ->(identifier) do
         Pattern::Binding[identifier.value, identifier.range]
@@ -676,6 +700,18 @@ module Jade
       end
     end
 
+    def type_alias_declaration
+      ->((type_token, name, type_params_list, body_type)) do
+        TypeAliasDeclaration.new(
+          name: name.value,
+          type_params: type_params_list.items,
+          body_type:,
+          trailing_comma: type_params_list.trailing_comma,
+          range: type_token.range.begin...body_type.range.end,
+        )
+      end
+    end
+
     def implementation
       ->((implements_token, interface, applied_type, extends, functions, end_token)) do
         Implementation[

data/lib/jade/cli/eject.rb

@@ -0,0 +1,132 @@
+require 'fileutils'
+require 'rbconfig'
+
+require 'jade'
+require 'jade/module_loader'
+
+module Jade
+  module CLI
+    # Writes the project as Ruby that runs without the gem: the compiled
+    # modules, the runtime they call, and requires that point at each other
+    # rather than at a load path.
+    module Eject
+      module_function
+
+      DEFAULT_OUT = 'ejected'.freeze
+
+      def run(argv)
+        usage if argv.any? { it == '-h' || it == '--help' }
+
+        Project
+          .find!
+          .then { [it, out_dir(argv, it)] }
+          .then { |project, out| eject(project, out) }
+      end
+
+      def eject(project, out)
+        FileUtils.rm_rf(out)
+
+        compile_all(project, out)
+        vendor_runtime(out)
+        rewrite_requires(out)
+
+        report(out)
+      end
+
+      # Every module, not only the ones something imports: an ejected tree
+      # that drops a file is not the project.
+      def compile_all(project, out)
+        sources(project).each do |entry|
+          ModuleLoader
+            .load(project.source_root, entry, cache_dir: project.cache_path)
+            .then { ModuleLoader.emit(it, path: out) }
+        end
+      end
+
+      def sources(project)
+        Dir
+          .glob(File.join(project.source_root, '**', '*.jd'))
+          .map { Pathname.new(it).relative_path_from(Pathname.new(project.source_root)).to_s }
+          .sort
+      end
+
+      # Whatever a booted runtime loads is what the ejected code needs, so
+      # ask one rather than keeping a list here.
+      def vendor_runtime(out)
+        runtime_files.each do |file|
+          File.join(out, file)
+            .tap { FileUtils.mkdir_p(File.dirname(it)) }
+            .then { FileUtils.cp(File.join(gem_lib, file), it) }
+        end
+      end
+
+      def runtime_files
+        [RbConfig.ruby, '-I', gem_lib, '-e', BOOT]
+          .then { IO.popen(it, err: [:child, :out], &:read) }
+          .lines(chomp: true)
+          .select { it.start_with?("#{gem_lib}/") }
+          .map { it.delete_prefix("#{gem_lib}/") }
+      end
+
+      BOOT = "require 'jade/runtime'; Jade::Runtime.boot!; puts $LOADED_FEATURES".freeze
+
+      def gem_lib
+        File.expand_path('../../..', __dir__).then { File.join(it, 'lib') }
+      end
+
+      # `require 'jade/x'` finds the gem; the point is not to have one.
+      def rewrite_requires(out)
+        Dir
+          .glob(File.join(out, '**', '*.rb'))
+          .each { rewrite(it, out) }
+      end
+
+      def rewrite(path, out)
+        File
+          .read(path)
+          .gsub(/^\$LOAD_PATH\.push\(File\.expand_path\("lib"\)\)\.uniq!\n/, '')
+          .gsub(/require ['"](jade\/[a-z_\/]+)['"]/) { "require_relative '#{up_to(path, out)}#{$1}'" }
+          .then { File.write(path, it) }
+      end
+
+      def up_to(path, out)
+        Pathname
+          .new(out)
+          .expand_path
+          .relative_path_from(Pathname.new(File.dirname(File.expand_path(path))))
+          .then { it.to_s == '.' ? '' : "#{it}/" }
+      end
+
+      def report(out)
+        puts <<~TXT
+          Ejected to #{out}/ (#{Dir.glob(File.join(out, '**', '*.rb')).size} files).
+
+          Nothing under #{out}/ requires the jade gem. To leave:
+
+            1. point your app at #{out}/ instead of the build directory
+            2. run your suite
+            3. drop jade-lang from your Gemfile and delete the .jd sources
+        TXT
+      end
+
+      def out_dir(argv, project)
+        argv
+          .each_cons(2)
+          .find { |flag, _| flag == '--out' }
+          &.last
+          .then { File.expand_path(it || DEFAULT_OUT, project.root) }
+      end
+
+      def usage
+        warn <<~USAGE
+          Usage: jade eject [--out DIR]
+
+          Compiles the project and writes it, plus the runtime it calls, as
+          Ruby that does not require the jade gem. Writes to ./ejected by
+          default. The directory is replaced if it exists.
+        USAGE
+        exit 1
+      end
+    end
+  end
+end

data/lib/jade/cli/init.rb

@@ -0,0 +1,86 @@
+require 'fileutils'
+require 'json'
+
+require 'jade'
+
+module Jade
+  module CLI
+    # Writes the manifest every tool outside the app reads. Without one,
+    # the CLI and the language server have to guess where the sources are,
+    # which is why `Project::NotFound` says to write this file by hand.
+    module Init
+      module_function
+
+      IGNORED = '.jade/'.freeze
+
+      def run(argv)
+        usage if argv.any? { it == '-h' || it == '--help' }
+
+        source_root(argv)
+          .then { [it, File.expand_path(Project::MANIFEST)] }
+          .then { |root, manifest| write(root, manifest) }
+      end
+
+      def write(root, manifest)
+        refuse(manifest) if File.exist?(manifest)
+
+        File.write(manifest, "#{JSON.pretty_generate(config(root))}\n")
+        FileUtils.mkdir_p(root)
+
+        report(root, manifest)
+      end
+
+      # Only what the defaults do not already say. A manifest naming every
+      # setting reads as though each were a decision.
+      def config(root)
+        { 'source_roots' => [root], 'extensions' => [] }
+      end
+
+      def source_root(argv)
+        argv
+          .each_cons(2)
+          .find { |flag, _| flag == '--source-root' }
+          &.last || Project::DEFAULTS[:source_roots].first
+      end
+
+      def refuse(manifest)
+        warn "jade: #{File.basename(manifest)} already exists in #{File.dirname(manifest)}"
+        exit 1
+      end
+
+      def report(root, manifest)
+        puts <<~TXT
+          Wrote #{File.basename(manifest)} and #{root}/.
+
+          Put a module in #{root}/, then:
+
+            jade check              type-check it
+            jade fmt #{root}/x.jd#{' ' * [0, 7 - root.length].max}   format it
+
+          #{gitignore_note}
+        TXT
+      end
+
+      # Build and cache output, which nobody wants in a diff.
+      def gitignore_note
+        path = File.expand_path('.gitignore')
+        return "Add #{IGNORED} to .gitignore." unless File.exist?(path)
+        return "#{IGNORED} is already ignored." if File.read(path).match?(/^\.jade\b/)
+
+        File.write(path, "#{File.read(path).chomp}\n#{IGNORED}\n")
+        "Added #{IGNORED} to .gitignore."
+      end
+
+      def usage
+        warn <<~USAGE
+          Usage: jade init [--source-root DIR]
+
+          Writes jade.json, which is how every tool outside the app finds
+          your sources, and creates the source directory. Refuses to
+          overwrite an existing manifest.
+        USAGE
+        exit 1
+      end
+    end
+  end
+end

data/lib/jade/cli.rb

@@ -4,7 +4,9 @@ module Jade
   module CLI
     SUBCOMMANDS = {
       'check' => 'Check',
+      'eject' => 'Eject',
       'fmt' => 'Fmt',
+      'init' => 'Init',
       'lsp' => 'Lsp',
       'q' => 'Q',
     }.freeze
@@ -37,7 +39,9 @@ module Jade
         Usage: jade COMMAND [ARGS]
 
           check  Type-check the project (or the given files).
+          eject  Write the project as Ruby that runs without the gem.
           fmt    Format .jd source (stdin or file).
+          init   Write jade.json and the source directory.
           lsp    Run the language server (stdio JSON-RPC).
           q      Headless query interface (hover/symbols/defn/refs/api).
 

data/lib/jade/codegen/boundary/specialized/list.rb

@@ -11,11 +11,11 @@ module Jade
         module List
           extend self
 
-          def decode(type, input, registry)
+          def decode(type, input, registry, where = nil)
             inner = inner_of(type) or return nil
 
-            scalar_optimized(inner, input) ||
-              generic_decode(type, inner, input, registry)
+            scalar_optimized(inner, input, where) ||
+              generic_decode(type, inner, input, registry, where)
           end
 
           def encode(type, value_expr, registry)
@@ -51,17 +51,21 @@ module Jade
 
           # `List(scalar)` fast path: validate elements with a single
           # C-loop `all?` check, no per-element decoder call.
-          def scalar_optimized(inner, input)
+          def scalar_optimized(inner, input, where)
             qname = Scalar.qname_for(inner) or return nil
             klass = Scalar::LIST_ELEM_CLASS[qname]
             label = "List(#{Scalar::LABEL[qname]})".inspect
-            "Jade::Interop::Boundary.list_of(#{klass}, #{label}, #{input})"
+            "Jade::Interop::Boundary.list_of(#{klass}, #{label}, #{input}#{Specialized.where_arg(where)})"
           end
 
-          def generic_decode(type, inner, input, registry)
+          # The index comes from `elements`, so the element decoder itself
+          # carries no path of its own.
+          def generic_decode(type, inner, input, registry, where)
             elem = Specialized.decode_expr(inner, '_1', registry) or return nil
             label = "List(#{Specialized.type_label(inner)})".inspect
-            "Jade::Interop::Boundary.array(#{label}, #{input}).map { #{elem} }"
+            at = Specialized.where_arg(where)
+            array = "Jade::Interop::Boundary.array(#{label}, #{input}#{at})"
+            "Jade::Interop::Boundary.elements(#{array}#{at}) { #{elem} }"
           end
         end
       end

data/lib/jade/codegen/boundary/specialized/maybe.rb

@@ -9,9 +9,9 @@ module Jade
         module Maybe
           extend self
 
-          def decode(type, input, registry)
+          def decode(type, input, registry, where = nil)
             inner = inner_of(type) or return nil
-            elem = Specialized.decode_expr(inner, 'it', registry) or return nil
+            elem = Specialized.decode_expr(inner, 'it', registry, where) or return nil
 
             "#{input}.then { it.nil? ? Jade::Maybe::Nothing[] : Jade::Maybe::Just[#{elem}] }"
           end

data/lib/jade/codegen/boundary/specialized/record.rb

@@ -16,9 +16,13 @@ module Jade
           extend self
           extend Helpers
 
-          def decode(type, input, registry)
+          # The helper is shared across call sites, so its fields can only
+          # know where they sit inside the struct: the segment that leads
+          # to the struct itself goes on at the call site.
+          def decode(type, input, registry, where = nil)
             struct = struct_for(type, registry) or return nil
-            "#{decode_helper_name(struct)}(#{input})"
+            call = "#{decode_helper_name(struct)}(#{input})"
+            where ? "Jade::Interop::Boundary.at(#{where.inspect}) { #{call} }" : call
           end
 
           def encode(type, value_expr, registry)
@@ -132,7 +136,7 @@ module Jade
             struct.record_type.fields
               .map { |k, t| field_decode(k, t, registry) }
               .then { Pretty.call(ctor, it, open: '[', close: ']') }
-              .then { Pretty.block("#{hash_call}.then do |h|", it) }
+              .then { Pretty.block("#{hash_call}.then do |h|", it, blaming_the_key(struct)) }
               .then { Pretty.block("def self.#{decode_helper_name(struct)}(value)", it) }
           end
 
@@ -144,7 +148,7 @@ module Jade
           end
 
           def field_decode(key, type, registry)
-            Specialized.decode_expr(type, "h[#{key.to_s.inspect}]", registry) ||
+            Specialized.decode_expr(type, "h[#{key.to_s.inspect}]", registry, ".#{key}") ||
               fail("non-specializable field type for #{key}: #{type}")
           end
 
@@ -156,6 +160,17 @@ module Jade
             end
           end
 
+          # A field the hash never had reads as nil to its decoder, which
+          # blames the type. The key it sat under is right here, and so is
+          # the hash that was supposed to hold it.
+          def blaming_the_key(struct)
+            [
+              'rescue Jade::Interop::DecodeError => e',
+              "  raise Jade::Interop::Boundary.blame(e, h, #{struct.name.inspect})",
+              'end',
+            ].join("\n")
+          end
+
           def snake(name)
             name
               .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')

data/lib/jade/codegen/boundary/specialized/scalar.rb

@@ -31,10 +31,10 @@ module Jade
             'String.String' => '::String',
           }.freeze
 
-          def decode(type, input)
+          def decode(type, input, where = nil)
             qname = qname_for(type) or return nil
             label = LABEL[qname].inspect
-            "Jade::Interop::Boundary.#{HELPER[qname]}(#{label}, #{input})"
+            "Jade::Interop::Boundary.#{HELPER[qname]}(#{label}, #{input}#{Specialized.where_arg(where)})"
           end
 
           # Scalar encoders are identity (Ruby int IS the JSON int, etc.),

data/lib/jade/codegen/boundary/specialized.rb

@@ -21,11 +21,13 @@ module Jade
 
         # Ruby expression that validates `input` and yields the decoded
         # value, or `nil` if `type` isn't specializable.
-        def decode_expr(type, input, registry)
-          Scalar.decode(type, input) ||
-            List.decode(type, input, registry) ||
-            Maybe.decode(type, input, registry) ||
-            Record.decode(type, input, registry)
+        # `where` is the path segment this value sits at, `".cents"`,
+        # baked into the emitted call so a failure can name it.
+        def decode_expr(type, input, registry, where = nil)
+          Scalar.decode(type, input, where) ||
+            List.decode(type, input, registry, where) ||
+            Maybe.decode(type, input, registry, where) ||
+            Record.decode(type, input, registry, where)
         end
 
         # How to encode `value_expr` to the wire form:
@@ -66,6 +68,12 @@ module Jade
           Record.emit_helpers(structs, registry)
         end
 
+        # Trailing argument for the runtime helpers, which all take the
+        # path segment last and default it to nil.
+        def where_arg(where)
+          where ? ", #{where.inspect}" : ''
+        end
+
         # --- type-shape helpers shared across shape modules ---
 
         # Both `Type::Application` (from inferred boundary types) and

data/lib/jade/codegen/boundary.rb

@@ -18,6 +18,9 @@ module Jade
         in Type::Application(constructor: Type::Constructor(name:), args:)
           decode_app(name, args, registry)
 
+        in Type::AnonymousRecord
+          derived_for(DECODABLE, type, registry)&.dig('decoder')
+
         else
           nil
         end
@@ -28,6 +31,9 @@ module Jade
         in Type::Application(constructor: Type::Constructor(name:), args:)
           encode_app(name, args, registry)
 
+        in Type::AnonymousRecord
+          derived_for(ENCODABLE, type, registry)&.dig('encoder')
+
         else
           nil
         end
@@ -153,7 +159,11 @@ module Jade
       end
 
       def derived_dispatch(interface_qname, type_qname, args, registry)
-        type       = Type.constructor(type_qname).apply(args)
+        type = Type.constructor(type_qname).apply(args)
+        derived_for(interface_qname, type, registry)
+      end
+
+      def derived_for(interface_qname, type, registry)
         constraint = Type.constraint(interface_qname, type, nil)
 
         case Frontend::TypeChecking::Constraints.resolve(constraint, registry, nil)
@@ -175,7 +185,7 @@ module Jade
 
         case fn_sym
         in Symbol::Function
-          "#{to_qualified(fn_sym.module_name)}::Internal.method(:#{fn_sym.name})"
+          "#{internal(fn_sym.module_name)}.method(:#{fn_sym.name})"
 
         in Symbol::StdlibFunction(codegen:) if codegen.is_a?(String)
           codegen

data/lib/jade/codegen/context.rb

@@ -22,6 +22,23 @@ module Jade
         @dict_env = prev
       end
 
+      # Dictionary source => constant name, filled while a module emits.
+      # A dictionary built entirely from concrete implementations depends
+      # on nothing at the call site, so it is built once at load instead
+      # of on every call. Nil outside a module: bare expressions have no
+      # constants to reference.
+      def dict_consts
+        @dict_consts
+      end
+
+      def with_dict_consts(table)
+        prev = @dict_consts
+        @dict_consts = table
+        yield
+      ensure
+        @dict_consts = prev
+      end
+
       # When set, references with this name emit as `self` (and field accesses
       # on them as bare method calls). Used to rewrite operator-impl lambda
       # bodies — `(a, b) -> { a.amount == b.amount }` becomes

data/lib/jade/codegen/error.rb

@@ -4,5 +4,6 @@ module Jade
     # this is a bug in jade, not in the source. RuntimeError so the CLI
     # reports it as a message rather than a backtrace.
     MissingDictionary = Class.new(RuntimeError)
+    UnrepresentableType = Class.new(RuntimeError)
   end
 end