jade-lang 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15e51e91117f799dec4acda81faa5fd62f8f75190570cebc69d69e0c588481cb
-  data.tar.gz: 1bd08d32f23d5b0e3f184f04d72aa1b44fd391bea3536ff2630ea93b1480f179
+  metadata.gz: 6886eb468004c2c500090b0a919a1a369e31b36039b3a6ef583bb74bc5e7326b
+  data.tar.gz: eaa9bb82c455efa0ca5c9e86eefe7d6ae6a56b1a9c8d695ae484500b69c1e049
 SHA512:
-  metadata.gz: fcb1ae0703cdcd8c29c618b7aaf36d90c1f5b7eb4b95a1ee5f6dd6e4fd81d172977b3786442c1f1635e0ade323ff94a82fd95ee331a23f53459581966d08a346
-  data.tar.gz: 4208a71d7852def7334d49142dc7aea3b4f6344941a9e66cbc9d544b8f877d84680c7206518d61aaeb35d6ecd8eec9261f7a1adf5d64fe6346020e775fadaaae
+  metadata.gz: 5a27df2bd32afa406b3205ca40ea047231cfe95c169cc38918b453278675d889ff9038ef93a2d08fd5caeb94683cc47cc5d498c8a5daa0e086a7f98630f733d7
+  data.tar.gz: e7fd05fc7622d6268f6ad109e8c6ad2b44df4961f668515d4eafb69767fa437d9b34d13276946723b58486d1393698fb713dba7a484965524753d913e779a9ee

data/CHANGELOG.md

@@ -6,6 +6,63 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Changed
+
+- `jade fmt` keeps blank lines between leading comment blocks. A section
+  banner separated from the declaration below it stays separated, where it
+  used to be pulled into that declaration's doc comment. **Formatted output
+  differs from 0.2.0**, so a format check in CI reports diffs on the first
+  run after upgrading.
+- `jade q` requires a `jade.json` and reports what to write when there isn't
+  one. It previously assumed the source root was the working directory, which
+  could not work for a project whose imports come from extension gems — it
+  failed later, inside the loader, instead.
+- `Compiler::Config#source_root=` takes one root and refuses a list of more
+  than one. A list was accepted before but only its first entry was ever
+  read.
+
+### Added
+
+- `jade.json` manifest, read by `Jade::Project`, giving tools that run
+  outside the application — the CLI, an editor's language server, a codegen
+  task — the source roots and extension gems that previously existed only as
+  Ruby run at boot. `Compiler::Config` seeds from it, and a `Jade.setup`
+  block still wins.
+- `Encodable` and `Decodable` derive for unions whose variants take no
+  arguments, using the variant name in snake_case as the wire form. A union
+  mixing nullary and argument-carrying variants does not derive: adding an
+  argument to one variant would otherwise change the encoding of all of them.
+- `SqlMapper` derives for unions whose variants each carry exactly one value,
+  naming the column after the variant. Inert unless jade-sql is loaded.
+- Placeholders in keyed calls: `Point(x: _, y: n)` partially applies the way
+  `Point(_, n)` already did. Blanks bind in the order the fields are written.
+- `Source` records the root it was loaded from, so an application module and
+  one shipped by an extension gem can be told apart without a name list.
+- `UsageAnalysis::Reference` records the declaration each reference was made
+  from, including references with no source range and those inside an
+  `implements` block.
+
+### Fixed
+
+- An interface method can be referenced as a value where the expected type
+  determines the instance. `Decode.field("k", Decode.decoder)` type-checked
+  and then failed in codegen, because the method's constraint named a
+  variable that appeared in nothing and so could never be bound.
+- A constraint that resolves to a concrete type is discharged rather than
+  dropped when a binding is generalized. An interface method referenced
+  outside an argument position previously compiled to a bare name and failed
+  at runtime.
+- Deriving reports which type it could not derive instead of raising through
+  the compiler. A struct with one un-derivable field took the whole run down
+  with a Ruby backtrace, which `tolerant: true` did not contain.
+- `jade fmt` no longer drops comments. A comment above the first declaration
+  in a module attached to a node nothing renders, so a module's first
+  declaration could never carry a doc comment.
+- A type sharing its name with its module no longer generates code that
+  resolves the wrong constant.
+
 ## [0.2.0]
 
 ### Added
@@ -42,7 +99,8 @@ Initial release.
 - `jade` CLI dispatcher: `fmt`, `lsp`, `q`.
 - Language server and headless query interface for editor/agent tooling.
 
-[Unreleased]: https://github.com/agustinrhcp/jade/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/agustinrhcp/jade/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/agustinrhcp/jade/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/agustinrhcp/jade/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/agustinrhcp/jade/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/agustinrhcp/jade/releases/tag/v0.1.0

data/lib/jade/ast/node.rb

@@ -16,6 +16,22 @@ module Jade
         @@_next_id += 1
       end
 
+      # The comment block touching this node. A blank line above it means
+      # a section banner, which documents the region and not this node.
+      def doc(source)
+        leading_comment_groups(source)
+          .last
+          &.then { follows_directly?(it.last, self, source) ? it : nil }
+          &.then { it.map(&:value).join("\n") }
+      end
+
+      # Split wherever a blank line separates one block from the next.
+      def leading_comment_groups(source)
+        leading_comments
+          .slice_when { |a, b| !follows_directly?(a, b, source) }
+          .to_a
+      end
+
       # Deepest descendant whose range covers `offset`, or self if no child
       # matches. Returns nil if this node's range is missing or doesn't
       # cover the offset.
@@ -39,6 +55,20 @@ module Jade
           .first
           .then { [self] + (it || []) }
       end
+
+      private
+
+      def follows_directly?(first, second, source)
+        line_of(second.range.begin, source) -
+          line_of(first.range.end - 1, source) == 1
+      end
+
+      def line_of(pos, source)
+        source
+          .line_starts
+          .bsearch_index { it > pos }
+          .then { it ? it - 1 : source.line_starts.length - 1 }
+      end
     end
   end
 end

data/lib/jade/cli/q.rb

@@ -88,18 +88,22 @@ module Jade
       class Context
         attr_reader :file, :source_root, :registry, :entry
 
+        # jade.json is what says where sources live and which extension gems
+        # ship the modules they import. Without it `Sql.Uuid` resolves
+        # against cwd and the load dies.
         def initialize(file)
-          @file = file
-          @source_root = Dir.pwd
+          project = Jade::Project.find!
+          @file = project.source_relative(file)
+          @source_root = project.source_root
           @registry = Jade::ModuleLoader.load(
-            @source_root, file,
-            cache_dir: File.join(@source_root, '.jade/cache'),
+            @source_root, @file,
+            cache_dir: project.cache_path,
             tolerant: true,
           )
           @entry = @registry
             .modules
             .each_value
-            .find { it.source&.uri == file } || fail("no module at #{file}")
+            .find { it.source&.uri == @file } || fail("no module at #{@file}")
         end
 
         def path_at(line, col)

data/lib/jade/cli.rb

@@ -26,6 +26,9 @@ module Jade
         usage($stderr)
         exit 1
       end
+    rescue Project::NotFound => e
+      warn "jade: #{e.message}"
+      exit 1
     end
 
     def usage(io = $stdout)

data/lib/jade/codegen/emitter.rb

@@ -48,7 +48,7 @@ module Jade
           "Jade::Runtime.intr(#{name.inspect})"
 
         in [:struct_constructor, qualified_name, arity]
-          "Jade::Runtime.curry(#{to_qualified(qualified_name)}.method(:[]), #{arity})"
+          "Jade::Runtime.curry(::#{to_qualified(qualified_name)}.method(:[]), #{arity})"
 
         in [:anon_record_constructor, keys]
           "Jade::Runtime.curry(#{data_define(keys)}.method(:[]), #{keys.size})"
@@ -68,7 +68,7 @@ module Jade
           args
             .map { "#{it}" }
             .join(',')
-            .then { "#{to_qualified(name)}(#{it})" }
+            .then { "::#{to_qualified(name)}(#{it})" }
 
         in [:_]
           '_'

data/lib/jade/codegen/inlines.rb

@@ -192,6 +192,7 @@ module Jade
         Decode.required
         Decode.sequence
         Decode.string
+        Decode.string_enum
         Decode.succeed
         Decode.tuple
         Decode.tuple3

data/lib/jade/compiler.rb

@@ -11,7 +11,7 @@ module Jade
 
       if needs_rebuild?(target)
         ModuleLoader
-          .load(config.source_root.first, path + '.jd', cache_dir: cache_root)
+          .load(config.source_root, path + '.jd', cache_dir: cache_root)
           .tap { render_diagnostics(it) }
           .then { ModuleLoader.emit(it, path: build_root) }
       end
@@ -47,22 +47,31 @@ module Jade
 
       target_mtime = File.mtime(target)
       Dir
-        .glob(File.join(config.source_root.first, '**/*.jd'))
+        .glob(File.join(config.source_root, '**/*.jd'))
         .any? { |src| File.mtime(src) > target_mtime }
     end
 
     class Config
       attr_accessor :project_root, :source_root, :build_dir, :cache_dir
 
-      def initialize
-        @project_root = Dir.pwd
-        @source_root = []
-        @build_dir   = ".jade/build"
-        @cache_dir   = ".jade/cache"
+      # Seeded from jade.json when there is one, so `Jade.setup` needs only
+      # what the manifest doesn't say. A setup block still wins — it runs
+      # after this.
+      def initialize(project = Project.find)
+        @project_root = project&.root || Dir.pwd
+        @source_root = project&.source_root
+        @build_dir = project&.build_dir || ".jade/build"
+        @cache_dir = project&.cache_dir || ".jade/cache"
       end
 
+      # One root. A list was accepted but only ever read at `.first`, so
+      # anything past the first was silently dropped — say so instead.
       def source_root=(root)
-        @source_root = Array(root)
+        Array(root).then do
+          fail ArgumentError, "source_root takes one root, got #{it.size}" if it.size > 1
+
+          @source_root = it.first
+        end
       end
     end
   end

data/lib/jade/formatter/helper.rb

@@ -13,7 +13,7 @@ module Jade
     #     walks delegated to their own modules.
     module Helper
       def format_node(node, indent: 0, source: nil)
-        leading  = format_leading_comments(node, indent)
+        leading  = format_leading_comments(node, indent, source)
         trailing = format_trailing_comment(node)
 
         dispatch_for(node)
@@ -75,15 +75,21 @@ module Jade
         (INDENT * indent).length + line.length > LINE_LIMIT
       end
 
-      def format_leading_comments(node, indent)
+      # The blank line between blocks is load-bearing: collapsing it turns
+      # a section banner into the next declaration's doc comment.
+      def format_leading_comments(node, indent, source = nil)
         return "" if node.leading_comments.empty?
 
-        node.leading_comments
-          .map { |tok| tok.value.then(&and_indent(indent)) }
-          .join("\n")
+        leading_comment_blocks(node, source)
+          .map { |block| block.map { it.value.then(&and_indent(indent)) }.join("\n") }
+          .join("\n\n")
           .then { it + "\n" }
       end
 
+      def leading_comment_blocks(node, source)
+        source ? node.leading_comment_groups(source) : [node.leading_comments]
+      end
+
       def format_trailing_comment(node)
         return "" if node.trailing_comments.empty?
 

data/lib/jade/frontend/comment_attacher.rb

@@ -10,7 +10,9 @@ module Jade
 
         collect_nodes(ast)
           .reject { |n| n.range.nil? }
-          .sort_by { |n| n.range.begin }
+          # Outermost first, so `x = f(y)` anchors on the Assign rather
+          # than the pattern nested inside it.
+          .sort_by { |n| [n.range.begin, -n.range.size] }
           .then { build_map(comments, it, source) }
           .then { reattach(ast, it) }
       end
@@ -70,7 +72,16 @@ module Jade
       end
 
       def first_node_starting_after(pos, sorted_nodes)
-        sorted_nodes.bsearch { |n| n.range.begin >= pos }
+        sorted_nodes
+          .bsearch_index { |n| n.range.begin >= pos }
+          &.then { |from| (from...sorted_nodes.size).find { renders_own_comments?(sorted_nodes[it]) } }
+          &.then { sorted_nodes[it] }
+      end
+
+      # ModuleNode walks `body.expressions` directly, so a Body's own
+      # leading comments reach no formatter and would be lost.
+      def renders_own_comments?(node)
+        !node.is_a?(AST::Body)
       end
 
       def smallest_enclosing(pos, sorted_nodes)

data/lib/jade/frontend/semantic_analysis/error/placeholder_not_allowed.rb

@@ -0,0 +1,22 @@
+module Jade
+  module Frontend
+    module SemanticAnalysis
+      module Error
+        class PlaceholderNotAllowed < Jade::Error
+          def initialize(entry, span, field:)
+            @field = field
+            super(entry:, span:)
+          end
+
+          def message
+            "`#{@field}: _` is only allowed when constructing a struct"
+          end
+
+          def label
+            "not allowed here"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jade/frontend/semantic_analysis/error.rb

@@ -5,6 +5,7 @@ require 'jade/frontend/semantic_analysis/error/constant_not_callable'
 require 'jade/frontend/semantic_analysis/error/constructor_not_found'
 require 'jade/frontend/semantic_analysis/error/constructor_pattern_arity_mismatch'
 require 'jade/frontend/semantic_analysis/error/duplicate_field'
+require 'jade/frontend/semantic_analysis/error/placeholder_not_allowed'
 require 'jade/frontend/semantic_analysis/error/duplicate_function_declaration'
 require 'jade/frontend/semantic_analysis/error/duplicate_record_field'
 require 'jade/frontend/semantic_analysis/error/invalid_list_rest_pattern'

data/lib/jade/frontend/semantic_analysis/keyed_call.rb

@@ -16,6 +16,12 @@ module Jade
           constructor = constructor_symbol(callee_resolved, registry)
           parent = constructor && registry.lookup(constructor.parent)
 
+          if fields.any? { it.value.is_a?(AST::Placeholder) }
+            return partially_applied(
+              node, callee, fields, parent, constructor, registry, scope, entry, callee_r
+            )
+          end
+
           fields_r = analyze_in_parallel(fields, registry, scope, entry)
           fields_resolved = fields_r.node
 
@@ -34,6 +40,55 @@ module Jade
 
         private
 
+        # Lowered before the fields are analyzed, so the placeholders are
+        # still bare AST and `Placeholder.lift` can turn the call into a
+        # lambda — the same route a positional partial application takes.
+        def partially_applied(node, callee, fields, parent, constructor, registry, scope, entry, callee_r)
+          errors = Validation.errors(node, fields, parent, constructor, registry, entry) +
+            placeholder_errors(fields, parent, entry)
+
+          return Result[node, callee_r.errors + errors, scope] if errors.any?
+
+          named, params = name_placeholders(fields)
+
+          lower(node, callee, named, parent, constructor, registry)
+            .then { wrap_in_lambdas(it, params, node.range) }
+            .then { analyze_node(it, registry, scope, entry) }
+            .then { Result[it.node, callee_r.errors + it.errors, scope] }
+        end
+
+        # Named in the order the fields were written, not the order the
+        # struct declares them, so `Point(y: _, x: _)` takes y first.
+        def name_placeholders(fields)
+          fields.reduce([[], []]) do |(named, params), field|
+            case field.value
+            in AST::Placeholder
+              Codegen::Helpers.param_synthetic_name(params.size).then do |name|
+                [named + [field.with(value: AST::VariableReference[name, nil])], params + [name]]
+              end
+
+            else
+              [named + [field], params]
+            end
+          end
+        end
+
+        def wrap_in_lambdas(call, params, range)
+          params
+            .reverse
+            .reduce(call) do |body, name|
+              AST::Lambda[[AST::Pattern::Binding[name, nil]], AST::Body[[body], nil], range]
+            end
+        end
+
+        def placeholder_errors(fields, parent, entry)
+          return [] if parent.is_a?(Symbol::Struct)
+
+          fields
+            .select { it.value.is_a?(AST::Placeholder) }
+            .map { Error::PlaceholderNotAllowed.new(entry.name, it.range, field: it.key) }
+        end
+
         def lower(node, callee, fields, parent, constructor, registry)
           case parent
           in Symbol::Struct

data/lib/jade/frontend/type_checking/constraints/deriving/decodable.rb

@@ -28,6 +28,9 @@ module Jade
                 in Symbol::Struct
                   derive_struct(constraint, resolved_sym, args, registry, lookup, entry_name)
 
+                in Symbol::Union if nullary?(resolved_sym, registry)
+                  derive_nullary_union(constraint, resolved_sym, registry)
+
                 else
                   failed(constraint, entry_name)
                 end
@@ -87,14 +90,32 @@ module Jade
                 Type.constraint(INTERFACE, field_type, nil)
               end
 
-              resolved_deps = field_deps.map do |dep|
-                resolve_dep(dep, lookup, entry_name) => Ok[impl]
-                impl
-              end
+              field_deps
+                .map { resolve_dep(it, lookup, entry_name) }
+                .then { Results.sequence(it) }
+                .map { implementation(constraint, record_body(fields, constructor_ref), it) }
+            end
+
+            def derive_nullary_union(constraint, union_sym, registry)
+              variants(union_sym, registry)
+                .then { nullary_union_body(it) }
+                .then { Ok[implementation(constraint, it, [])] }
+            end
 
+            def nullary_union_body(variants)
+              [:call,
+                [:stdlib_fn, 'Decode.string_enum'],
+                [
+                  [:list, variants.map { wire_name(it) }],
+                  [:list, variants.map { [:call, [:struct_constructor, it.qualified_name, 0], []] }],
+                ],
+              ]
+            end
+
+            def record_body(fields, constructor_ref)
               seed = [:call, [:stdlib_fn, 'Decode.succeed'], [constructor_ref]]
 
-              body = fields.each_with_index.reduce(seed) do |acc, ((field_name, _), idx)|
+              fields.each_with_index.reduce(seed) do |acc, ((field_name, _), idx)|
                 field_decoder = [:call,
                   [:stdlib_fn, 'Decode.field'],
                   [
@@ -105,8 +126,6 @@ module Jade
 
                 [:call, [:stdlib_fn, 'Decode.and_map'], [acc, field_decoder]]
               end
-
-              Ok[implementation(constraint, body, resolved_deps)]
             end
 
             # Free-var inner constraints fall back to the constraint marker

data/lib/jade/frontend/type_checking/constraints/deriving/encodable.rb

@@ -30,6 +30,9 @@ module Jade
                 in Symbol::Struct
                   derive_struct(constraint, resolved_sym, args, registry, lookup, entry_name)
 
+                in Symbol::Union if nullary?(resolved_sym, registry)
+                  derive_nullary_union(constraint, resolved_sym, registry)
+
                 else
                   failed(constraint, entry_name)
                 end
@@ -84,18 +87,25 @@ module Jade
               end
             end
 
+            def derive_nullary_union(constraint, union_sym, registry)
+              body = variants(union_sym, registry)
+                .map { |v|
+                  [
+                    [:constructor, v.qualified_name, []],
+                    [[:call, [:stdlib_fn, 'Encode.string'], [wire_name(v)]]],
+                  ]
+                }
+                .then { [:case, [:var, 'v'], it] }
+
+              Ok[implementation(constraint, params: ['v'], body:, deps: [])]
+            end
+
             def derive_struct(constraint, struct_sym, type_args, registry, lookup, entry_name)
               fields = struct_fields(struct_sym, type_args, registry)
 
               field_deps = fields
                 .map { |_, field_type| Type.constraint(INTERFACE, field_type, nil) }
 
-              resolved_deps = field_deps
-                .map do |dep|
-                  lookup.call(dep) => Ok[impl]
-                  impl
-                end
-
               pair_irs = fields
                 .each_with_index
                 .map do |(field_name, _), idx|
@@ -118,7 +128,10 @@ module Jade
                 ],
               ]
 
-              Ok[implementation(constraint, params: ['rec'], body:, deps: resolved_deps)]
+              field_deps
+                .map { lookup.call(it) }
+                .then { Results.sequence(it) }
+                .map { implementation(constraint, params: ['rec'], body:, deps: it) }
             end
 
             def implementation(constraint, params:, body:, deps:)

data/lib/jade/frontend/type_checking/constraints/deriving/eq.rb

@@ -34,7 +34,8 @@ module Jade
                   deps = dependencies_of(impl, args)
                   resolved_deps = deps.filter_map { |dep|
                     next if dep.type in Type::Var
-                    lookup.call(dep) => Ok[resolved]; resolved
+                    lookup.call(dep).on_err { return Err[it] } => Ok[resolved]
+                    resolved
                   }
 
                   Symbol::Implementation.new(

data/lib/jade/frontend/type_checking/constraints/deriving/helpers.rb

@@ -6,6 +6,23 @@ module Jade
           module Helpers
             extend self
 
+            # `union :Int` and friends are variant-less unions standing in
+            # for native types, so an empty variant list is not an enum.
+            def nullary?(union_sym, registry)
+              variants(union_sym, registry)
+                .then { it.any? && it.all? { it.args.empty? } }
+            end
+
+            def variants(union_sym, registry)
+              union_sym.variants.map { registry.lookup(it) }
+            end
+
+            # The wire name a variant carries when nothing says otherwise.
+            # Matches what hand-written mappings already use.
+            def wire_name(variant)
+              Source.snake_case(variant.name)
+            end
+
             def struct_fields(struct_sym, type_args, registry)
               record = struct_sym.record_type
               type_param_names = struct_sym.type_params.map(&:name)

data/lib/jade/frontend/type_checking/constraints/deriving/sql_mapper.rb

@@ -0,0 +1,130 @@
+module Jade
+  module Frontend
+    module TypeChecking
+      module Constraints
+        module Deriving
+          # jade-sql's interface, derived here rather than there: the
+          # deriving framework is not extensible, and this stays inert
+          # without jade-sql, since nothing else names the interface.
+          module SqlMapper
+            extend self
+            include Helpers
+
+            INTERFACE = 'Sql.SqlMapper'
+            ASSIGNMENT = 'Sql.Assignment'
+            ASSIGNMENT_FIELDS = %w[col value_sql params].freeze
+
+            def supports?(interface) = interface == INTERFACE
+
+            def derive(constraint, registry, entry_name, &lookup)
+              return failed(constraint, entry_name) unless assignment_matches?(registry)
+
+              case constraint.type
+              in Type::Application(constructor: Type::Constructor(name:), args: [])
+                Symbol
+                  .type_ref_from_qualified_name(name)
+                  .then { registry.lookup(it) }
+                  .then { derive_for(constraint, it, registry, lookup, entry_name) }
+
+              else
+                failed(constraint, entry_name)
+              end
+            end
+
+            private
+
+            # The interface is matched by name, so some other module called
+            # `Sql` would otherwise be derived against as though it were
+            # jade-sql — building its Assignment with the wrong arity, and
+            # failing at runtime rather than here.
+            def assignment_matches?(registry)
+              Symbol
+                .type_ref_from_qualified_name(ASSIGNMENT)
+                .then { registry.lookup(it) }
+                .then do
+                  it in Symbol::Struct(record_type: { fields: }) and
+                    fields.keys.map(&:to_s) == ASSIGNMENT_FIELDS
+                end
+            end
+
+            def derive_for(constraint, symbol, registry, lookup, entry_name)
+              case symbol
+              in Symbol::Union if single_payload?(symbol, registry)
+                derive_union(constraint, symbol, registry, lookup, entry_name)
+
+              else
+                failed(constraint, entry_name)
+              end
+            end
+
+            # One column per variant, so each variant carries exactly the
+            # value that column is set to.
+            def single_payload?(union_sym, registry)
+              variants(union_sym, registry)
+                .then { it.any? && it.all? { it.args.size == 1 } }
+            end
+
+            def derive_union(constraint, union_sym, registry, lookup, entry_name)
+              vs = variants(union_sym, registry)
+
+              vs
+                .map { encodable_dep(it, registry) }
+                .map { lookup.call(it) }
+                .then { Results.sequence(it) }
+                .map { implementation(constraint, union_body(vs), it) }
+            end
+
+            def encodable_dep(variant, registry)
+              variant
+                .args
+                .first
+                .then { instantiate(it, {}, registry) }
+                .then { Type.constraint('Encode.Encodable', it, nil) }
+            end
+
+            def union_body(variants)
+              variants
+                .each_with_index
+                .map { |v, idx| [[:constructor, v.qualified_name, ['x']], [assignment(v, idx)]] }
+                .then { [:case, [:var, 'f'], it] }
+            end
+
+            def assignment(variant, idx)
+              [:call,
+                [:struct_constructor, ASSIGNMENT, 3],
+                [
+                  wire_name(variant),
+                  '?',
+                  [:list, [[:call, [:impl_arg, idx, 'encoder'], [[:var, 'x']]]]],
+                ],
+              ]
+                .then { [:list, [it]] }
+            end
+
+            def failed(constraint, entry_name)
+              Err[
+                Error::DerivationFailed.new(
+                  entry_name, constraint.origin&.range, constraint:, trace: [],
+                )
+              ]
+            end
+
+            def implementation(constraint, body, deps)
+              Symbol::Implementation.new(
+                module_name: nil,
+                interface: Symbol.type_ref_from_qualified_name(constraint.interface),
+                type: constraint.type,
+                type_params: [],
+                constraints: [],
+                functions: { 'to_assigns' => Symbol::DerivedFunction.new(params: ['f'], body:) },
+                deps:,
+                extends: [],
+                decl_span: nil,
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jade/frontend/type_checking/constraints/deriving.rb

@@ -2,6 +2,7 @@ require_relative './deriving/helpers.rb'
 require_relative './deriving/eq.rb'
 require_relative './deriving/decodable.rb'
 require_relative './deriving/encodable.rb'
+require_relative './deriving/sql_mapper.rb'
 
 module Jade
   module Frontend
@@ -10,7 +11,7 @@ module Jade
         module Deriving
           extend self
 
-          DERIVERS = [Eq, Decodable, Encodable]
+          DERIVERS = [Eq, Decodable, Encodable, SqlMapper]
 
           def derivable?(interface)
             DERIVERS.any? { it.supports?(interface) }

data/lib/jade/frontend/type_checking/generalizer.rb

@@ -14,7 +14,6 @@ module Jade
                 unbound_cs = constraints
                   .map { e.substitution.apply(it) }
                   .uniq
-                  .select { it.unbound_vars.any? }
 
                 Generalization.
                   generalize(

data/lib/jade/frontend/usage_analysis/reference_index.rb

@@ -1,7 +1,11 @@
 module Jade
   module Frontend
     module UsageAnalysis
-      Reference = Data.define(:symbol_key, :kind, :range)
+      # `owner` is the key of the enclosing declaration or implementation,
+      # `nil` only at module level. Declaration owners share the
+      # `symbol_key` namespace, so a reference's owner can be looked up in
+      # the index that produced it.
+      Reference = Data.define(:symbol_key, :kind, :range, :owner)
 
       ReferenceIndex = Data.define(:references) do
         def initialize(references: {})
@@ -41,6 +45,8 @@ module Jade
           case symbol
           in Symbol::Variable
             [:local, symbol.decl_span]
+          in Symbol::Implementation
+            [:impl, symbol.interface.qname, symbol.type.qname]
           in Symbol::ValueRef | Symbol::TypeRef
             [symbol.module_name, symbol.name]
           else

data/lib/jade/frontend/usage_analysis.rb

@@ -15,11 +15,14 @@ module Jade
     #   :type_annotation  - type appearing in a signature, variant args,
     #                       struct fields, interface signatures, etc.
     #   :exposed          - name listed in `module M exposing (...)`
+    #
+    # Every reference also carries the `owner` it was made from — see
+    # ReferenceIndex. Only `:exposed` has none.
     module UsageAnalysis
       extend self
 
       def analyze(entry, _registry)
-        walk(entry.ast, :as_value, entry)
+        walk(entry.ast, :as_value, entry, nil)
           .group_by(&:symbol_key)
           .freeze
           .then { entry.with(usage_index: ReferenceIndex.new(references: it)) }
@@ -27,103 +30,123 @@ module Jade
 
       private
 
-      def walk(node, ctx, entry)
+      # `owner` is the key of the enclosing declaration or implementation,
+      # threaded down rather than recovered afterwards by range
+      # containment: desugared nodes carry `range == nil`, and references
+      # inside an `implements` block sit in no declaration's span, so
+      # both are unbucketable.
+      def walk(node, ctx, entry, owner)
         case node
         in AST::Module(exposing:, body:)
-          walk_exposing(exposing, entry) + walk(body, :as_value, entry)
+          walk_exposing(exposing, entry) + walk(body, :as_value, entry, owner)
 
         in AST::Body(expressions:)
-          expressions.flat_map { walk(it, :as_value, entry) }
+          expressions.flat_map { walk(it, :as_value, entry, owner) }
 
-        in AST::FunctionDeclaration(body:, params:, return_type:)
-          walk(body, :as_value, entry) +
-            params.flat_map { walk_type(it.type, entry) } +
-            walk_type(return_type, entry)
+        in AST::FunctionDeclaration(body:, params:, return_type:, symbol:)
+          ReferenceIndex.key_for(symbol).then do |declared|
+            walk(body, :as_value, entry, declared) +
+              params.flat_map { walk_type(it.type, entry, declared) } +
+              walk_type(return_type, entry, declared)
+          end
 
         in AST::FunctionCall(callee:, args:)
-          walk(callee, :called, entry) + args.flat_map { walk(it, :as_value, entry) }
+          walk(callee, :called, entry, owner) +
+            args.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::VariableReference(symbol:, range:)
-          ref(symbol, ctx, range)
+          ref(symbol, ctx, range, owner)
 
         in AST::ConstructorReference(symbol:, range:)
-          ref(symbol, ctx == :called ? :constructed : :as_value, range)
+          ref(symbol, ctx == :called ? :constructed : :as_value, range, owner)
 
         in AST::QualifiedAccess(symbol:, range:)
-          ref(symbol, ctx, range)
+          ref(symbol, ctx, range, owner)
 
         in AST::Lambda(body:, params:)
-          walk(body, :as_value, entry) +
-            params.flat_map { walk(it, :as_value, entry) }
+          walk(body, :as_value, entry, owner) +
+            params.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::Assign(pattern:, expression:)
-          walk(expression, :as_value, entry) + walk(pattern, :as_value, entry)
+          walk(expression, :as_value, entry, owner) +
+            walk(pattern, :as_value, entry, owner)
 
         in AST::IfThenElse(condition:, if_branch:, else_branch:)
-          walk(condition, :as_value, entry) +
-            walk(if_branch, :as_value, entry) +
-            walk(else_branch, :as_value, entry)
+          walk(condition, :as_value, entry, owner) +
+            walk(if_branch, :as_value, entry, owner) +
+            walk(else_branch, :as_value, entry, owner)
 
         in AST::CaseOf(expression:, branches:)
-          walk(expression, :as_value, entry) +
-            branches.flat_map { walk(it, :as_value, entry) }
+          walk(expression, :as_value, entry, owner) +
+            branches.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::CaseOfBranch(pattern:, body:)
-          walk(pattern, :as_value, entry) + walk(body, :as_value, entry)
+          walk(pattern, :as_value, entry, owner) + walk(body, :as_value, entry, owner)
 
         in AST::Pattern::Constructor(constructor:, patterns:, symbol:)
           # Don't walk `constructor` — it's a bare ConstructorReference
           # and walking it would record a spurious :as_value for every
           # pattern match.
-          ref(symbol, :pattern_match, constructor.range) +
-            patterns.flat_map { walk(it, :as_value, entry) }
+          ref(symbol, :pattern_match, constructor.range, owner) +
+            patterns.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::Pattern::List(patterns:, rest:)
-          rest_refs = rest ? walk(rest, :as_value, entry) : []
-          patterns.flat_map { walk(it, :as_value, entry) } + rest_refs
+          rest_refs = rest ? walk(rest, :as_value, entry, owner) : []
+          patterns.flat_map { walk(it, :as_value, entry, owner) } + rest_refs
 
         in AST::Pattern::Record(fields:)
-          fields.flat_map { walk(it.pattern, :as_value, entry) }
+          fields.flat_map { walk(it.pattern, :as_value, entry, owner) }
 
         in AST::Pattern::Literal | AST::Pattern::Binding | AST::Pattern::Wildcard
           []
 
         in AST::Grouping(expression:)
-          walk(expression, ctx, entry)
+          walk(expression, ctx, entry, owner)
 
         in AST::List(items:)
-          items.flat_map { walk(it, :as_value, entry) }
+          items.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::RecordLiteral(fields:)
-          fields.flat_map { walk(it, :as_value, entry) }
+          fields.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::RecordUpdate(base:, fields:)
-          walk(base, :as_value, entry) + fields.flat_map { walk(it, :as_value, entry) }
+          walk(base, :as_value, entry, owner) +
+            fields.flat_map { walk(it, :as_value, entry, owner) }
 
         in AST::RecordField(value:)
-          walk(value, :as_value, entry)
+          walk(value, :as_value, entry, owner)
 
         in AST::RecordAccess(target:)
-          walk(target, :as_value, entry)
+          walk(target, :as_value, entry, owner)
 
-        in AST::Implementation(applied_type:, functions:)
-          walk_type(applied_type, entry) +
-            functions.flat_map { walk(it, :as_value, entry) }
+        in AST::Implementation(applied_type:, functions:, symbol:)
+          # `implements X with f: <lambda>` has no enclosing declaration,
+          # so the implementation itself owns what its functions call.
+          ReferenceIndex.key_for(symbol).then do |impl|
+            walk_type(applied_type, entry, impl) +
+              functions.flat_map { walk(it, :as_value, entry, impl) }
+          end
 
         in AST::ImplementationFunction(fn:)
-          walk(fn, :as_value, entry)
+          walk(fn, :as_value, entry, owner)
 
-        in AST::TypeDeclaration(variants:)
-          variants.flat_map { it.args.flat_map { walk_type(it, entry) } }
+        in AST::TypeDeclaration(variants:, symbol:)
+          ReferenceIndex.key_for(symbol).then do |declared|
+            variants.flat_map { it.args.flat_map { walk_type(it, entry, declared) } }
+          end
 
-        in AST::StructDeclaration(record_type:)
-          walk_type(record_type, entry)
+        in AST::StructDeclaration(record_type:, symbol:)
+          walk_type(record_type, entry, ReferenceIndex.key_for(symbol))
 
-        in AST::InterfaceDeclaration(functions:)
-          functions.flat_map { walk_type(it.type, entry) }
+        in AST::InterfaceDeclaration(functions:, symbol:)
+          ReferenceIndex.key_for(symbol).then do |declared|
+            functions.flat_map { walk_type(it.type, entry, declared) }
+          end
 
         in AST::InteropImportDeclaration(functions:)
-          functions.flat_map { walk_type(it.type, entry) }
+          # Owned per port, not per `uses` block — the port is what a
+          # caller names and what carries the effect boundary.
+          functions.flat_map { walk_type(it.type, entry, ReferenceIndex.key_for(it.symbol)) }
 
         in AST::ImportDeclaration | AST::VariantDeclaration |
            AST::Literal | AST::CharLiteral |
@@ -136,26 +159,28 @@ module Jade
         end
       end
 
-      def walk_type(node, entry)
+      def walk_type(node, entry, owner)
         case node
         in nil
           []
 
         in AST::TypeName(type:, range:)
           entry.types[type]
-            .then { it ? [Reference[ReferenceIndex.key_for(it), :type_annotation, range]] : [] }
+            .then { it ? ref(it, :type_annotation, range, owner) : [] }
 
         in AST::TypeApplication(constructor:, args:)
-          walk_type(constructor, entry) + args.flat_map { walk_type(it, entry) }
+          walk_type(constructor, entry, owner) +
+            args.flat_map { walk_type(it, entry, owner) }
 
         in AST::TypeFunction(params:, return_type:)
-          params.flat_map { walk_type(it, entry) } + walk_type(return_type, entry)
+          params.flat_map { walk_type(it, entry, owner) } +
+            walk_type(return_type, entry, owner)
 
         in AST::TypeRecord(fields:)
-          fields.values.flat_map { walk_type(it, entry) }
+          fields.values.flat_map { walk_type(it, entry, owner) }
 
         in AST::TypeTuple(items:)
-          items.flat_map { walk_type(it, entry) }
+          items.flat_map { walk_type(it, entry, owner) }
 
         in AST::TypeVar | AST::TypeUnit | AST::QualifiedTypeName |
            AST::TypeParam
@@ -183,12 +208,13 @@ module Jade
         end
       end
 
+      # The exposing list is module level, so these have no owner.
       def exposed_ref(symbol, range)
-        symbol ? [Reference[ReferenceIndex.key_for(symbol), :exposed, range]] : []
+        symbol ? ref(symbol, :exposed, range, nil) : []
       end
 
-      def ref(symbol, kind, range)
-        [Reference[ReferenceIndex.key_for(symbol), kind, range]]
+      def ref(symbol, kind, range, owner)
+        [Reference[ReferenceIndex.key_for(symbol), kind, range, owner]]
       end
     end
   end

data/lib/jade/parsing.rb

@@ -362,11 +362,17 @@ module Jade
     parser(:keyed_call_postfix) {
       (
         type(:lparen) >>
-          comma_sequence(record_field) >>
+          comma_sequence(keyed_call_field) >>
           type(:rparen)
       ).map { |(lparen, fields, rparen)| KeyedCallPostfix[lparen, fields, rparen] }
     }
 
+    # Like a record field, but a value may be `_`, so a keyed call can be
+    # partially applied the way a positional one can.
+    parser(:keyed_call_field) {
+      (identifier >> type(:colon).skip >> function_call_arg).map(&AST.record_field)
+    }
+
     parser(:function_call_arg) { placeholder | lazy { expression } }
 
     parser(:placeholder) { type(:wildcard).map(&AST.placeholder) }

data/lib/jade/project.rb

@@ -0,0 +1,100 @@
+require 'json'
+require 'pathname'
+
+module Jade
+  # A project's compiler settings, read from `jade.json` at its root.
+  #
+  # Without this, project config only exists as Ruby executed at app boot
+  # (`Jade.setup`), so every tool that runs outside the app — the CLI, an
+  # editor's LSP, a codegen task — is blind to it and has to guess the
+  # source root and which extension gems to load.
+  #
+  # Subclassed rather than `Project = Data.define(...) do ... end` because
+  # constants in that block land in `Jade`, not on the class — which would
+  # put `Jade::DEFAULTS` in the gem's top namespace.
+  class Project < Data.define(
+    :root, :source_roots, :build_dir, :cache_dir, :extensions, :entries, :map
+  )
+    MANIFEST = 'jade.json'.freeze
+
+    DEFAULTS = {
+      source_roots: ['lib'],
+      build_dir: '.jade/build',
+      cache_dir: '.jade/cache',
+      extensions: [],
+      entries: [],
+      map: {},
+    }.freeze
+
+    class NotFound < StandardError
+      def initialize(from)
+        super(<<~MSG)
+          no #{MANIFEST} in #{from} or any parent directory
+
+          Tools that run outside the app can't see a `Jade.setup` block, so
+          they need the manifest to find your sources and load the gems
+          that ship the modules you import. Write one at the project root:
+
+            { "source_roots": ["lib"], "extensions": ["jade-sql"] }
+        MSG
+      end
+    end
+
+    # nil when there's no manifest — a project predating one is a legitimate
+    # state, not a failure. Callers that need it say so with `find!`.
+    def self.find(from = Dir.pwd)
+      Pathname
+        .new(from)
+        .expand_path
+        .ascend
+        .find { (it + MANIFEST).file? }
+        &.then { load(it) }
+    end
+
+    def self.find!(from = Dir.pwd)
+      find(from) || fail(NotFound.new(from))
+    end
+
+    def self.load(root)
+      (root + MANIFEST)
+        .read
+        .then { JSON.parse(it, symbolize_names: true) }
+        .then { new(root: root.to_s, **DEFAULTS.merge(it)) }
+        .tap { it.require_extensions }
+    end
+
+    def source_root
+      File.expand_path(source_roots.first, root)
+    end
+
+    def build_path
+      File.expand_path(build_dir, root)
+    end
+
+    def cache_path
+      File.expand_path(cache_dir, root)
+    end
+
+    # Modules are addressed relative to the source root, but a path typed at
+    # a shell or sent by an editor is relative to the project root. Accept
+    # either, and say so when it's neither.
+    def source_relative(path)
+      [source_root, root]
+        .map { File.expand_path(path, it) }
+        .find { File.file?(it) }
+        .then { it || fail("no such file: #{path}") }
+        .then { Pathname.new(it).relative_path_from(source_root).to_s }
+    end
+
+    # Extensions register their search root when required, so this is what
+    # lets a standalone tool resolve `Sql.Uuid` to the gem that ships it.
+    #
+    # Plain `require`, not `Kernel.require`: RubyGems overrides the private
+    # instance method and leaves the module function alone, so
+    # `Kernel.require` finds only what is already on the load path — never
+    # an installed gem, which is the whole point here.
+    def require_extensions
+      extensions.each { require(it) }
+    end
+  end
+end

data/lib/jade/source.rb

@@ -1,8 +1,12 @@
 module Jade
-  Source = Data.define(:uri, :text, :line_starts) do
+  # `root` is the directory `uri` is relative to — the app's source root
+  # for its own modules, an extension gem's for the modules it ships. It
+  # is what makes "app or gem?" structural instead of a name list. `nil`
+  # for sources that never came off disk: buffers, stdin, the stdlib.
+  Source = Data.define(:uri, :text, :line_starts, :root) do
     def self.load(source_root, uri, overlays: {})
       text = overlays[uri] || File.read(File.join(source_root, uri))
-      new(uri, text)
+      new(uri:, text:, root: source_root)
     end
 
     def self.load_from_module_name(source_root, name, overlays: {})
@@ -26,7 +30,7 @@ module Jade
       end
     end
 
-    def initialize(uri:, text:, line_starts: calculate_line_starts(text))
+    def initialize(uri:, text:, line_starts: calculate_line_starts(text), root: nil)
       super
     end
 

data/lib/jade/stdlib/decode.rb

@@ -182,6 +182,24 @@ module Jade
         Jade::Decode::Decoder[Jade::Decode::Desc::Fail[msg]]
       }
 
+      # Backs derived Decodable for unions whose variants take no
+      # arguments. `names` and `values` are positionally paired.
+      function(
+        'string_enum',
+        { names: 'List(String)', values: 'List(a)' },
+        'Decoder(a)',
+      ) { |names, values|
+        table = names.zip(values).to_h
+
+        ->(s) {
+          table.key?(s) \
+            ? Jade::Decode::Decoder[Jade::Decode::Desc::Succeed[table[s]]]
+            : Jade::Decode::Decoder[Jade::Decode::Desc::Fail["expected one of #{names.join(', ')}, got #{s.inspect}"]]
+        }
+          .then { Jade::Decode::Desc::AndThen[it, Jade::Decode::Desc::Str[]] }
+          .then { Jade::Decode::Decoder[it] }
+      }
+
       function(
         'from_result',
         { r: 'Result(a, String)' },

data/lib/jade/type.rb

@@ -168,12 +168,15 @@ module Jade
           end
 
         interface = registry.lookup(symbol.interface)
+
+        # Keep the map the type param lands in: the return type has to see
+        # the same variable, or the constraint ends up on a variable that
+        # appears in no type and nothing can ever bind it.
+        param_type, _, local_map =
+          from_symbol_r(interface.type_param, registry, var_gen, local_map)
+
         constraint = Type
-          .constraint(
-            symbol.interface.qualified_name,
-            from_symbol_r(interface.type_param, registry, var_gen, local_map).first,
-            nil,
-          )
+          .constraint(symbol.interface.qualified_name, param_type, nil)
 
         from_symbol_r(symbol.return_type, registry, var_gen, local_map)
           .then { |(t, c, _)| [args.empty? ? t : Type.function(args, t), c + arg_cs + [constraint]] }

data/lib/jade/version.rb

@@ -1,3 +1,3 @@
 module Jade
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/jade.rb

@@ -1,4 +1,5 @@
 require 'jade/version'
+require 'jade/project'
 require 'jade/did_you_mean'
 require 'jade/symbol'
 require 'jade/registry'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jade-lang
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Agustin Cornu
 bindir: exe
 cert_chain: []
-date: 2026-06-17 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -157,6 +157,7 @@ files:
 - lib/jade/frontend/semantic_analysis/error/nested_task_port.rb
 - lib/jade/frontend/semantic_analysis/error/non_task_port.rb
 - lib/jade/frontend/semantic_analysis/error/orphan_implementation.rb
+- lib/jade/frontend/semantic_analysis/error/placeholder_not_allowed.rb
 - lib/jade/frontend/semantic_analysis/error/predicate_must_return_bool.rb
 - lib/jade/frontend/semantic_analysis/error/predicate_name_not_allowed.rb
 - lib/jade/frontend/semantic_analysis/error/shadowing_error.rb
@@ -210,6 +211,7 @@ files:
 - lib/jade/frontend/type_checking/constraints/deriving/encodable.rb
 - lib/jade/frontend/type_checking/constraints/deriving/eq.rb
 - lib/jade/frontend/type_checking/constraints/deriving/helpers.rb
+- lib/jade/frontend/type_checking/constraints/deriving/sql_mapper.rb
 - lib/jade/frontend/type_checking/definition.rb
 - lib/jade/frontend/type_checking/env.rb
 - lib/jade/frontend/type_checking/error.rb
@@ -297,6 +299,7 @@ files:
 - lib/jade/parsing/token.rb
 - lib/jade/parsing/type.rb
 - lib/jade/port.rb
+- lib/jade/project.rb
 - lib/jade/registry.rb
 - lib/jade/result.rb
 - lib/jade/runtime.rb