jade-lang 0.1.0

data/lib/jade/frontend/type_checking.rb

@@ -0,0 +1,129 @@
+require 'jade/frontend/type_checking/canonicalize'
+require 'jade/frontend/type_checking/constraints'
+require 'jade/frontend/type_checking/definition'
+require 'jade/frontend/type_checking/env'
+require 'jade/frontend/type_checking/error'
+require 'jade/frontend/type_checking/expected'
+require 'jade/frontend/type_checking/inference'
+require 'jade/frontend/type_checking/loader'
+require 'jade/frontend/type_checking/port_resolution'
+require 'jade/frontend/type_checking/result'
+require 'jade/frontend/type_checking/state'
+require 'jade/frontend/type_checking/substitution'
+require 'jade/frontend/type_checking/unification'
+
+require 'jade/frontend/type_checking/generalizer'
+
+module Jade
+  module Frontend
+    module TypeChecking
+      extend Inference::Helpers
+      extend self
+
+      def check(entry, registry)
+        Loader
+          .load(entry, registry)
+          .then { check_node(entry.ast, registry, State.init(it, skip_constraints: true), Expected.infer(it.fresh)) }
+          .then { Generalizer.generalize(it.first.env) }
+          .then { check_node(entry.ast, registry, State.init(it), Expected.infer(it.fresh)) }
+          .then { finalize(*it, registry) }
+          .map { Canonicalize.run(entry.ast, it, registry) }
+          .map { it.canonicalize_node_types }
+          .map { entry.with(env: it) }
+          .and_then { PortResolution.resolve(it, registry) }
+      end
+
+      def finalize(state, result, registry)
+        state.env => { bindings:, entry_name: }
+
+        errors = bindings
+          .select do |k,v|
+            # filter locals
+            b_entry_name = k.split('.')[0..-2].join(',')
+            b_entry_name == entry_name
+          end
+          .reject { |k, _| interface_function?(k, registry) }
+          .reject { |k, _| interop_function?(k, registry) }
+          .values
+          .flat_map(&:constraints)
+          .flat_map { Constraints.solve_at_finalize(it, registry, entry_name) }
+
+        # TODO: impl declarations need their own finalization pass here.
+        # Unresolved constraints from impl function bodies (e.g. Eq(a) from
+        # `one.id == other.id` inside `impl Eq for Pepe(a)`) should be promoted
+        # to impl-level requirements — making the impl an ImplementationTemplate
+        # with those constraints — rather than being dropped silently.
+
+        state
+          .with(errors: state.errors + errors)
+          .to_result
+      end
+
+      def interface_function?(qname, registry)
+        *module_parts, name = qname.split('.')
+        Symbol
+          .value_ref(module_parts.join('.'), name)
+          .then { registry.lookup(it) }
+          .is_a?(Symbol::InterfaceFunction)
+      end
+
+      # Polymorphic-port constraints represent caller requirements
+      # (resolved at each call site), not body obligations to verify here.
+      def interop_function?(qname, registry)
+        *module_parts, name = qname.split('.')
+        Symbol
+          .value_ref(module_parts.join('.'), name)
+          .then { registry.lookup(it) }
+          .is_a?(Symbol::InteropFunction)
+      end
+
+      def check_repl(node, registry, env = Env.new)
+        check_node(node, registry, env, Expected.infer(env.fresh))
+          .to_result
+      end
+
+      def check_node(node, registry, state, expected_type)
+        case node
+        in AST::Body then Inference::Body
+        in AST::CaseOf then Inference::CaseOf
+        in AST::ConstructorReference then Inference::ConstructorReference
+        in AST::FunctionCall then Inference::FunctionCall
+        in AST::FunctionDeclaration then Inference::FunctionDeclaration
+        in AST::Grouping then Inference::Grouping
+        in AST::IfThenElse then Inference::IfThenElse
+        in AST::Implementation then Inference::Implementation
+        in AST::ImportDeclaration then Inference::ImportDeclaration
+        in AST::InteropImportDeclaration then Inference::InteropImportDeclaration
+        in AST::Lambda then Inference::Lambda
+        in AST::List then Inference::List
+        in AST::Literal | AST::CharLiteral then Inference::Literal
+        in AST::Module then Inference::Module
+        in AST::QualifiedAccess then Inference::QualifiedAccess
+        in AST::RecordAccess then Inference::RecordAccess
+        in AST::StructDeclaration then Inference::StructDeclaration
+        in AST::InterfaceDeclaration then Inference::InterfaceDeclaration
+        in AST::RecordField then Inference::RecordField
+        in AST::RecordLiteral then Inference::RecordLiteral
+        in AST::RecordUpdate then Inference::RecordUpdate
+        in AST::TypeDeclaration then Inference::TypeDeclaration
+        in AST::Assign then Inference::Assign
+        in AST::VariableReference then Inference::VariableReference
+        end
+          .infer(node, registry, state, expected_type)
+          .then { |s, r| [pin_node_type(s, node, r), r] }
+      end
+
+      private
+
+      # Records the inferred type at this node so post-finalize the LSP
+      # (and anyone else) can look up `node.id -> type`. Types contain
+      # Type::Var here; `canonicalize_node_types` resolves them once the
+      # substitution is final.
+      def pin_node_type(state, node, result)
+        return state unless node.respond_to?(:id) && result.respond_to?(:type)
+
+        state.with(env: state.env.pin_type(node.id, result.type))
+      end
+    end
+  end
+end

data/lib/jade/frontend/unused_analysis.rb

@@ -0,0 +1,41 @@
+module Jade
+  module Frontend
+    # Emits a warning per module-private function that no reference in
+    # the module's own usage_index touches. Runs after UsageAnalysis so
+    # it can read the index. Never fails; only appends to diagnostics.
+    #
+    # Scope is intentionally narrow: only Symbol::Function for now. Other
+    # kinds (Constructor, Variant, Union, Struct, InterfaceFunction) need
+    # separate filter rules — e.g. variants are reachable via pattern
+    # match, interface fns are dispatched, not directly called — and are
+    # deferred.
+    module UnusedAnalysis
+      extend self
+
+      def analyze(entry, _registry)
+        entry
+          .defined_values
+          .values
+          .select { unused?(it, entry) }
+          .reduce(entry.diagnostics) { |list, sym| list.add(warning(sym, entry)) }
+          .then { entry.with(diagnostics: it) }
+      end
+
+      private
+
+      def unused?(symbol, entry)
+        symbol.is_a?(Jade::Symbol::Function) &&
+          symbol.decl_span &&
+          !entry.exposed_value(symbol.name) &&
+          !entry.usage_index.ever_referenced?(symbol)
+      end
+
+      def warning(symbol, entry)
+        Diagnostics::Diagnostic.warning(
+          "unused function `#{symbol.name}`",
+          primary: Diagnostics::Label[entry.source, symbol.decl_span, 'never used'],
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module Jade
+  module Frontend
+    module UsageAnalysis
+      Reference = Data.define(:symbol_key, :kind, :range)
+
+      ReferenceIndex = Data.define(:references) do
+        def initialize(references: {})
+          super
+        end
+
+        def self.empty
+          new(references: {})
+        end
+
+        def for(symbol)
+          references[ReferenceIndex.key_for(symbol)] || []
+        end
+
+        def passed_as_value?(symbol)
+          self.for(symbol).any? { it.kind == :as_value }
+        end
+
+        def ever_referenced?(symbol)
+          self.for(symbol).any?
+        end
+
+        def references_in(module_name)
+          references
+            .values
+            .flatten
+            .select { it.symbol_key.first == module_name }
+        end
+
+        # Locals key on `decl_span`; module-level symbols on
+        # `[module_name, name]`. NOTE: when `:type_annotation` refs land
+        # they may point at a `Symbol::Variable` that's a *type*
+        # variable, which would collide with value-level locals under
+        # `[:local, decl_span]`. Revisit the keying scheme then —
+        # likely split into `[:local_value, ...]` vs `[:local_type, ...]`.
+        def self.key_for(symbol)
+          case symbol
+          in Symbol::Variable
+            [:local, symbol.decl_span]
+          in Symbol::ValueRef | Symbol::TypeRef
+            [symbol.module_name, symbol.name]
+          else
+            [symbol.module_name, symbol.name]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jade/frontend/usage_analysis.rb

@@ -0,0 +1,195 @@
+require 'jade/frontend/usage_analysis/reference_index'
+
+module Jade
+  module Frontend
+    # Walks a resolved AST and builds a ReferenceIndex of where each
+    # symbol is used. Runs after SemanticAnalysis (which attaches symbols)
+    # and before TypeChecking. Never fails — attaches `usage_index` to
+    # the entry and returns it.
+    #
+    # Reference kinds:
+    #   :called           - in callee position of a FunctionCall
+    #   :as_value         - bare reference (passed as value, returned, etc.)
+    #   :constructed      - constructor applied with args
+    #   :pattern_match    - constructor used in a pattern match
+    #   :type_annotation  - type appearing in a signature, variant args,
+    #                       struct fields, interface signatures, etc.
+    #   :exposed          - name listed in `module M exposing (...)`
+    module UsageAnalysis
+      extend self
+
+      def analyze(entry, _registry)
+        walk(entry.ast, :as_value, entry)
+          .group_by(&:symbol_key)
+          .freeze
+          .then { entry.with(usage_index: ReferenceIndex.new(references: it)) }
+      end
+
+      private
+
+      def walk(node, ctx, entry)
+        case node
+        in AST::Module(exposing:, body:)
+          walk_exposing(exposing, entry) + walk(body, :as_value, entry)
+
+        in AST::Body(expressions:)
+          expressions.flat_map { walk(it, :as_value, entry) }
+
+        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::FunctionCall(callee:, args:)
+          walk(callee, :called, entry) + args.flat_map { walk(it, :as_value, entry) }
+
+        in AST::VariableReference(symbol:, range:)
+          ref(symbol, ctx, range)
+
+        in AST::ConstructorReference(symbol:, range:)
+          ref(symbol, ctx == :called ? :constructed : :as_value, range)
+
+        in AST::QualifiedAccess(symbol:, range:)
+          ref(symbol, ctx, range)
+
+        in AST::Lambda(body:, params:)
+          walk(body, :as_value, entry) +
+            params.flat_map { walk(it, :as_value, entry) }
+
+        in AST::Assign(pattern:, expression:)
+          walk(expression, :as_value, entry) + walk(pattern, :as_value, entry)
+
+        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)
+
+        in AST::CaseOf(expression:, branches:)
+          walk(expression, :as_value, entry) +
+            branches.flat_map { walk(it, :as_value, entry) }
+
+        in AST::CaseOfBranch(pattern:, body:)
+          walk(pattern, :as_value, entry) + walk(body, :as_value, entry)
+
+        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) }
+
+        in AST::Pattern::List(patterns:, rest:)
+          rest_refs = rest ? walk(rest, :as_value, entry) : []
+          patterns.flat_map { walk(it, :as_value, entry) } + rest_refs
+
+        in AST::Pattern::Record(fields:)
+          fields.flat_map { walk(it.pattern, :as_value, entry) }
+
+        in AST::Pattern::Literal | AST::Pattern::Binding | AST::Pattern::Wildcard
+          []
+
+        in AST::Grouping(expression:)
+          walk(expression, ctx, entry)
+
+        in AST::List(items:)
+          items.flat_map { walk(it, :as_value, entry) }
+
+        in AST::RecordLiteral(fields:)
+          fields.flat_map { walk(it, :as_value, entry) }
+
+        in AST::RecordUpdate(base:, fields:)
+          walk(base, :as_value, entry) + fields.flat_map { walk(it, :as_value, entry) }
+
+        in AST::RecordField(value:)
+          walk(value, :as_value, entry)
+
+        in AST::RecordAccess(target:)
+          walk(target, :as_value, entry)
+
+        in AST::Implementation(applied_type:, functions:)
+          walk_type(applied_type, entry) +
+            functions.flat_map { walk(it, :as_value, entry) }
+
+        in AST::ImplementationFunction(fn:)
+          walk(fn, :as_value, entry)
+
+        in AST::TypeDeclaration(variants:)
+          variants.flat_map { it.args.flat_map { walk_type(it, entry) } }
+
+        in AST::StructDeclaration(record_type:)
+          walk_type(record_type, entry)
+
+        in AST::InterfaceDeclaration(functions:)
+          functions.flat_map { walk_type(it.type, entry) }
+
+        in AST::InteropImportDeclaration(functions:)
+          functions.flat_map { walk_type(it.type, entry) }
+
+        in AST::ImportDeclaration | AST::VariantDeclaration |
+           AST::Literal | AST::CharLiteral |
+           AST::MemberAccess | AST::KeyedCall
+          # ImportDeclaration's exposing list is handled when we land
+          # in importer modules — see walk_exposing. KeyedCall and
+          # MemberAccess are lowered away during semantic_analysis, so
+          # the branches are defensive against partial ASTs.
+          []
+        end
+      end
+
+      def walk_type(node, entry)
+        case node
+        in nil
+          []
+
+        in AST::TypeName(type:, range:)
+          entry.types[type]
+            .then { it ? [Reference[ReferenceIndex.key_for(it), :type_annotation, range]] : [] }
+
+        in AST::TypeApplication(constructor:, args:)
+          walk_type(constructor, entry) + args.flat_map { walk_type(it, entry) }
+
+        in AST::TypeFunction(params:, return_type:)
+          params.flat_map { walk_type(it, entry) } + walk_type(return_type, entry)
+
+        in AST::TypeRecord(fields:)
+          fields.values.flat_map { walk_type(it, entry) }
+
+        in AST::TypeTuple(items:)
+          items.flat_map { walk_type(it, entry) }
+
+        in AST::TypeVar | AST::TypeUnit | AST::QualifiedTypeName |
+           AST::TypeParam
+          []
+        end
+      end
+
+      def walk_exposing(node, entry)
+        case node
+        in AST::ExposeList(items:)
+          items.flat_map { walk_expose_item(it, entry) }
+
+        in AST::ExposeAll | AST::ExposeNone
+          []
+        end
+      end
+
+      def walk_expose_item(item, entry)
+        case item
+        in AST::ExposeValue(name:, range:)
+          exposed_ref(entry.lookup_value(name), range)
+
+        in AST::ExposeType | AST::ExposeTypeExpand
+          exposed_ref(entry.lookup_type(item.name), item.range)
+        end
+      end
+
+      def exposed_ref(symbol, range)
+        symbol ? [Reference[ReferenceIndex.key_for(symbol), :exposed, range]] : []
+      end
+
+      def ref(symbol, kind, range)
+        [Reference[ReferenceIndex.key_for(symbol), kind, range]]
+      end
+    end
+  end
+end

data/lib/jade/frontend.rb

@@ -0,0 +1,101 @@
+require 'jade/registry'
+require 'jade/symbol'
+require 'jade/type'
+require 'jade/stdlib'
+require 'jade/did_you_mean'
+
+require 'jade/frontend/comment_attacher'
+require 'jade/frontend/forward_declaration'
+require 'jade/frontend/semantic_analysis'
+require 'jade/frontend/usage_analysis'
+require 'jade/frontend/unused_analysis'
+require 'jade/frontend/type_checking'
+require 'jade/frontend/fixity_fixer'
+require 'jade/frontend/desugaring'
+require 'jade/frontend/desugaring/resolved'
+
+module Jade
+  module Frontend
+    extend self
+
+    # On error, wraps the failure as `[latest_processed_entry, errors]` so
+    # tolerant callers can recover the AST as of the last successful stage
+    # instead of falling back to the original pre-frontend entry.
+    def run_entry(initial, registry)
+      latest = initial
+      capture = ->(entry) { latest = entry }
+
+      initial
+        .then { FixityFixer.fix_entry(it).tap(&capture) }
+        .then { Desugaring.desugar_entry(it).tap(&capture) }
+        .then { ForwardDeclaration.declare_entry(it, registry).map { it.tap(&capture) } }
+        .and_then { SemanticAnalysis.analyze(it, registry.update_module(it)).map { it.tap(&capture) } }
+        .map { Desugaring.desugar_resolved_entry(it, registry.update_module(it)).tap(&capture) }
+        .map { UsageAnalysis.analyze(it, registry.update_module(it)).tap(&capture) }
+        .map { UnusedAnalysis.analyze(it, registry.update_module(it)).tap(&capture) }
+        .and_then { TypeChecking.check(it, registry.update_module(it)).map { it.tap(&capture) } }
+        .map_error { |errs| [latest, errs] }
+    end
+
+    def run(ast)
+      run_up_to_semantic_analysis(ast)
+        .and_then do |(entry, registry)|
+          TypeChecking
+            .check(entry, registry)
+            .map { [it.ast, registry.update_module(it)] }
+       end
+    end
+
+    def run_repl(ast, registry, current_entry, scope, env, var_gen)
+      registry ||= registry_with_basics
+      current_entry ||= entry_with_basics('JadeRepl')
+      scope ||= SemanticAnalysis::Scope.new
+      env ||= TypeChecking::Env.new
+      var_gen ||= TypeChecking::VarGen.new
+
+      ForwardDeclaration
+        .declare(ast, registry, current_entry)
+        .then { |entry| FixityFixer.fix(ast).then { [it, entry] } }
+        .then do |fixed_ast, updated_entry|
+          updated_registry = registry.update_module(updated_entry)
+          SemanticAnalysis
+            .analyze_repl(fixed_ast, updated_registry, scope, updated_entry)
+            .and_then do |(enhanced_ast, new_scope)|
+              enhanced_ast = Desugaring.desugar_resolved(enhanced_ast, updated_registry)
+              TypeChecking.check_repl(enhanced_ast, updated_registry, env, var_gen)
+                .map { |type, new_env| [enhanced_ast, type, updated_registry, updated_entry, new_scope, new_env] }
+            end
+        end
+    end
+
+    def run_up_to_semantic_analysis(ast)
+      registry, current_entry = entry_with_basics(ast)
+
+      FixityFixer.fix(ast)
+        .then { Desugaring.desugar(it) }
+        .then { |enh_ast| ForwardDeclaration.declare(enh_ast, registry, current_entry).map { [enh_ast, it] } }
+        .and_then do |enh_ast, entry|
+          SemanticAnalysis.analyze(entry.with(ast: enh_ast), registry.update_module(entry))
+        end
+        .map { Desugaring.desugar_resolved_entry(it, registry.update_module(it)) }
+        .map { UsageAnalysis.analyze(it, registry.update_module(it)) }
+        .map { [it, registry.update_module(it)] }
+    end
+
+    def entry_with_basics(ast)
+      entry =
+        case ast
+        in AST::Module(name:)
+          name
+        else
+          '__Test__'
+        end
+          .then { Registry.entry(it).with(ast:) }
+
+      Stdlib.load(Registry.new)
+        .add_module(entry)
+        .then { Stdlib.apply(it) }
+        .then { [it, it.modules[entry.name]] }
+    end
+  end
+end

data/lib/jade/interop/boundary.rb

@@ -0,0 +1,68 @@
+require 'jade/decode'
+require 'jade/result'
+require 'jade/interop/error'
+
+module Jade
+  module Interop
+    module Boundary
+      extend self
+
+    # Boundary-side decode: succeed → return the value, fail → raise. The
+    # Result wrap/unwrap that user-level Decode.from_value uses is dead
+    # weight at the boundary because failure always raises anyway. Skipping
+    # it removes one allocation per arg per Ruby→Jade call.
+      def decode_or_raise(decoder, value)
+        case Jade::Decode::Runner.run(decoder, value)
+        in Jade::Result::Ok[v]  then v
+        in Jade::Result::Err[e] then raise Jade::Interop::DecodeError.new(e, value)
+        end
+      end
+
+      # Specialized fast-path validators. Emitted by codegen for known-shape
+      # argument types in place of the generic `decode_or_raise` path —
+      # avoids constructing a Decoder descriptor and walking the
+      # interpreter for primitives.
+      def integer(label, v)
+        ::Integer === v ? v : type_error!(label, v)
+      end
+
+      def string(label, v)
+        ::String === v ? v.dup : type_error!(label, v)
+      end
+
+      def bool(label, v)
+        v == true || v == false ? v : type_error!(label, v)
+      end
+
+      def float(label, v)
+        ::Numeric === v ? v.to_f : type_error!(label, v)
+      end
+
+      def list_of(klass, label, v)
+        v.is_a?(::Array) && v.all? { klass === _1 } ? v : type_error!(label, v)
+      end
+
+      # Validates that v is an Array but doesn't check element types — used
+      # when the per-element decoder isn't a simple `is_a?` (e.g. nested
+      # structs). The caller maps a decoder over the result.
+      def array(label, v)
+        v.is_a?(::Array) ? v : type_error!(label, v)
+      end
+
+      def hash(label, v)
+        case v
+        when ::Hash then v
+        when ::Data then v.to_h.transform_keys(&:to_s)
+        else type_error!(label, v)
+        end
+      end
+
+      def type_error!(label, v)
+        raise Jade::Interop::DecodeError.new(
+          Jade::Decode::WrongType[label, Jade::Decode.type_name(v)],
+          v,
+        )
+      end
+    end
+  end
+end

data/lib/jade/interop/error.rb

@@ -0,0 +1,84 @@
+module Jade
+  module Interop
+    class Error < StandardError; end
+
+    class PortNotRegistered < Error
+      def initialize(module_name, function_name)
+        super(
+          "Port `#{function_name}` on `#{module_name}` is not a Jade port. " \
+            "Add `extend Jade::Port` to `#{module_name}` and declare it with " \
+            "`task :#{function_name} do |t, ...| ... end`."
+        )
+      end
+    end
+
+    # Raised when a Ruby caller invokes a Jade function whose signature
+    # has no public boundary — typically a polymorphic fn, a fn with
+    # function-typed args, or a fn over a type whose Decodable/Encodable
+    # can't be derived. The user's options are to add an explicit
+    # `implements Decodable/Encodable`, restructure the signature with
+    # decodable types, or accept that the fn is Jade-internal only.
+    class NotExposed < Error
+      def initialize(module_name:, function_name:, hint: nil)
+        ["#{module_name}.#{function_name} is not exposed to Ruby.", hint]
+          .compact
+          .join(' ')
+          .then { super(it) }
+      end
+    end
+
+    # Raised by bang-suffixed Task wrappers when the underlying Task ran
+    # to the Err arm. The encoded err value is available on `.error` for
+    # structured handling — pattern-match on it for shape-specific
+    # recovery, or just inspect for logging.
+    class TaskError < Error
+      attr_reader :error
+
+      def initialize(error)
+        @error = error
+        super("Task returned an error: #{error.inspect}")
+      end
+    end
+
+    class DecodeError < Error
+      attr_reader :decode_error, :value
+
+      def initialize(decode_error, value)
+        @decode_error = decode_error
+        @value = value
+        super(format(decode_error, value))
+      end
+
+      private
+
+      def format(error, value)
+        path, leaf = unwind(error)
+        location = path.empty? ? "value" : path.join
+
+        case leaf
+        in Jade::Decode::WrongType[expected, got]
+          "Port returned a value that failed to decode at #{location}: expected #{expected}, got #{got} (#{value.inspect})"
+
+        in Jade::Decode::MissingField[key]
+          "Port returned a value that failed to decode at #{location}: missing field `#{key}` (#{value.inspect})"
+
+        in Jade::Decode::Custom[msg]
+          "Port returned a value that failed to decode at #{location}: #{msg} (#{value.inspect})"
+
+        in Jade::Decode::Multiple[errors]
+          errors
+            .map { format(it, value) }
+            .join("; ")
+        end
+      end
+
+      def unwind(error, path = [])
+        case error
+        in Jade::Decode::AtField[key, inner] then unwind(inner, path + [".#{key}"])
+        in Jade::Decode::AtIndex[idx, inner] then unwind(inner, path + ["[#{idx}]"])
+        else [path, error]
+        end
+      end
+    end
+  end
+end