trane 0.1.0

data/lib/trane/route_validator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module Trane
+  # Cross-checks drawn routes against the operation registry. Two independent
+  # checks, each with its own failure message:
+  #   1. Every route declaring `_trane_operation` must reference a registered
+  #      operation (catches typos in `contract: { operation: :x }`).
+  #   2. Every such route must map to exactly one HTTP verb (a Trane operation
+  #      is one verb + one path). Rails collapses `via: [:patch, :put]` into a
+  #      single route whose #verb is "PATCH|PUT"; a `match` with no verb (or
+  #      `via: :all`) yields a blank verb matching any method. Both are rejected.
+  #
+  # Pure `(routes, registry)` function — no Rails::Application coupling — so it
+  # can be exercised with fake route doubles in unit specs and with a real
+  # route set from the Engine or the `trane:check` rake task.
+  class RouteValidator
+    # @param routes [Enumerable] route objects responding to #verb, #defaults, #path
+    # @param registry [Module, Trane::Registry::Instance] responds to #operations
+    # @raise [Trane::RoutingContractError] on an unregistered operation or a multi/any-verb route
+    def self.validate!(routes, registry)
+      validate_operations_registered!(routes, registry)
+      validate_single_verb!(routes)
+    end
+
+    class << self
+      private
+
+      def validate_operations_registered!(routes, registry)
+        orphans = {}
+
+        routes.each do |route|
+          op = route.defaults[:_trane_operation]
+          next if op.blank?
+          next if registry.operations.key?(op.to_sym)
+
+          orphans[op] ||= route
+        end
+
+        return if orphans.empty?
+
+        operation_names = registry.operations.keys
+        details = orphans.map do |op, route|
+          suggestion = Trane.spelling_suggestion(op, operation_names)
+          line = "#{describe_route(route)} references operation :#{op}, but no such operation is registered"
+          line += " (did you mean :#{suggestion}?)" if suggestion
+          line
+        end
+
+        raise Trane::RoutingContractError, "Trane route/registry cross-check failed:\n  #{details.join("\n  ")}"
+      end
+
+      def validate_single_verb!(routes)
+        offenders = {}
+
+        routes.each do |route|
+          op = route.defaults[:_trane_operation]
+          next if op.blank?
+          next if single_http_verb?(route.verb)
+
+          offenders[op] ||= route
+        end
+
+        return if offenders.empty?
+
+        details = offenders.map { |op, route| "#{describe_route(route)} → operation :#{op}" }
+        raise Trane::RoutingContractError,
+              "Trane: each route with a contract: must map to exactly one HTTP verb, " \
+              "but these map to multiple verbs (or to any verb):\n  #{details.join("\n  ")}\n  " \
+              "Split into separate operations or pick a single verb."
+      end
+
+      # Rails 8.1 exposes #verb as a String ("GET", "PATCH|PUT", or "" for ANY).
+      # `verb.to_s` also handles the Regexp form older Rails versions expose:
+      # its #to_s carries the "|" for multi-verb alternations.
+      def single_http_verb?(verb)
+        s = verb.to_s
+        !s.strip.empty? && !s.include?("|")
+      end
+
+      def describe_route(route)
+        verb = route.verb
+        verb = "ANY" if verb.blank?
+        "#{verb} #{route.path.spec}"
+      end
+    end
+  end
+end

data/lib/trane/routing_extension.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Trane
+  # Prepended globally onto ActionDispatch::Routing::Mapper by the Engine
+  # initializer `trane.prepend_routing_extension`. Available in all
+  # `routes.draw` blocks. Routes without `contract:` pass through unchanged
+  # in O(1).
+  #
+  # Uses `*path_or_actions, **kwargs` to mirror Rails' own `Mapper::Resources#match`
+  # signature and handle every internal calling convention (normal path, hash-
+  # shorthand `"up" => "ctrl#action"`, zero-positional-arg `match` calls, etc.).
+  module RoutingExtension
+    # Single source of truth for the keys accepted inside `contract: { ... }`.
+    # Anything else is a typo and must fail loud at route-draw time rather
+    # than being silently ignored or deferred to request time.
+    CONTRACT_KEYS = %i[operation].freeze
+
+    # Intercepts route declarations that carry `contract: { operation: name }`.
+    # Strips the key, injects the operation name into `defaults[:_trane_operation]`
+    # (used at request time to resolve the contract), and sets `as: name` so the
+    # operation is discoverable as a named-route prefix in `bin/rails routes`.
+    #
+    # Routes without `contract:` are forwarded to super unchanged.
+    #
+    # Rails 7.x / 8.0 call match(*args, options_hash) via map_method — a plain
+    # Hash as the last positional argument. Rails 8.1+ uses proper keyword
+    # arguments. Both conventions must be handled here.
+    def match(*path_or_actions, **kwargs)
+      if kwargs.key?(:contract)
+        # Rails 8.1+ keyword-argument path
+        kwargs = kwargs.dup
+        contract = kwargs.delete(:contract)
+        _inject_trane_contract!(nil, kwargs, contract)
+      elsif path_or_actions.last.is_a?(Hash) && path_or_actions.last.key?(:contract)
+        # Rails 7.x / 8.0 positional-hash path (map_method calls match(*args, opts))
+        path_or_actions = path_or_actions.dup
+        options = path_or_actions.last.dup
+        path_or_actions[-1] = options
+        contract = options.delete(:contract)
+        _inject_trane_contract!(options, nil, contract)
+      end
+
+      super(*path_or_actions, **kwargs)
+    end
+
+    private
+
+    # Mutates either +options+ (positional hash) or +kwargs+ (keyword hash) in-place.
+    def _inject_trane_contract!(options, kwargs, contract)
+      _validate_contract_hash!(contract)
+
+      target = options || kwargs
+      operation = contract[:operation].to_s
+      defaults = target[:defaults] || {}
+      target[:defaults] = defaults.merge(_trane_operation: operation)
+      # Set :as to the operation name unless the caller already provided an
+      # explicit Symbol or String. ActionDispatch::Routing::Mapper uses a
+      # private DEFAULT = Object.new sentinel for "not set by user", which is
+      # truthy, so `target[:as] ||= operation` would silently skip it.
+      user_as = target[:as]
+      target[:as] = operation unless user_as.is_a?(Symbol) || user_as.is_a?(String)
+    end
+
+    # Fails loud on malformed `contract:` metadata: unknown keys (typos) are
+    # reported first — with a "Did you mean?" suggestion when one is close —
+    # followed by a check that :operation is present and non-blank. Checking
+    # unknown keys first means a typo like `operaton:` is reported as an
+    # unknown key (with a suggestion) rather than as a missing :operation.
+    def _validate_contract_hash!(contract)
+      contract = {} unless contract.is_a?(Hash)
+
+      unknown = contract.keys - CONTRACT_KEYS
+      unless unknown.empty?
+        bad = unknown.first
+        message = "Unknown key `#{bad}` in contract:."
+        suggestion = Trane.spelling_suggestion(bad, CONTRACT_KEYS)
+        message += " Did you mean `#{suggestion}`?" if suggestion
+        raise Trane::RoutingContractError, message
+      end
+
+      op = contract[:operation]
+      raise Trane::RoutingContractError, "contract: requires a non-empty :operation" if op.nil? || op.to_s.strip.empty?
+    end
+  end
+end

data/lib/trane/serializer.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Trane
+  class Serializer
+    # @param response_definition [ResponseDefinition]
+    # @param registry [Module] Trane::Registry
+    # @param strict_mode [Symbol] :raise, :log, or :ignore
+    # Instances are frozen post-init; share freely across threads.
+    def initialize(response_definition, registry, strict_mode: :ignore)
+      @response_definition = response_definition
+      @registry            = registry
+      @strict_mode         = strict_mode
+      freeze
+    end
+
+    # Serialize data according to the response definition.
+    #
+    # @param data [Hash, Object] the data to serialize (hash of root-level keys)
+    # @param extra_attributes [Set<String>] dot-notation paths of extra fields to include
+    # @return [Hash] serialized result
+    def serialize(data, extra_attributes: ExtraAttributesFilter::EMPTY)
+      result = serialize_fields(@response_definition.fields, data, extra_attributes: extra_attributes, prefix: "")
+
+      if @strict_mode != :ignore
+        ContractValidator.validate_response!(
+          @response_definition, result, @registry, mode: @strict_mode
+        )
+      end
+
+      result
+    end
+
+    private
+
+    # Serialize a list of fields against a data source.
+    #
+    # @param fields [Array<FieldNode>] field definitions
+    # @param data [Hash, Object] the data to extract values from
+    # @param extra_attributes [Set<String>] extra attribute paths
+    # @param prefix [String] current dot-notation prefix
+    # @return [Hash]
+    def serialize_fields(fields, data, extra_attributes:, prefix:)
+      result = {}
+
+      fields.each do |field|
+        if field.extra
+          path = build_path(prefix, field.name)
+          next unless extra_attributes.include?(path)
+        end
+
+        value = extract_value(data, field.name)
+        result[field.name] = serialize_value(field, value, extra_attributes: extra_attributes, prefix: prefix)
+      end
+
+      result
+    end
+
+    # Serialize a single field value.
+    def serialize_value(field, value, extra_attributes:, prefix:)
+      return nil if value.nil?
+
+      if field.type == :array
+        return serialize_array(field, value, extra_attributes: extra_attributes, prefix: prefix)
+      end
+
+      unless field.children.empty?
+        new_prefix = build_path(prefix, field.name)
+        return serialize_fields(field.children, value, extra_attributes: extra_attributes, prefix: new_prefix)
+      end
+
+      rep = @registry.representations[field.type]
+      if rep
+        new_prefix = build_path(prefix, field.name)
+        return serialize_fields(rep.fields, value, extra_attributes: extra_attributes, prefix: new_prefix)
+      end
+
+      if field.format == :iso8601 && value.respond_to?(:iso8601)
+        return value.iso8601
+      end
+
+      value
+    end
+
+    # Serialize an array field.
+    def serialize_array(field, value, extra_attributes:, prefix:)
+      unless array_like?(value)
+        handle_non_iterable_array(value, build_path(prefix, field.name))
+        return []
+      end
+
+      if field.array_of || !field.children.empty?
+        element_prefix = build_path(prefix, field.name)
+        value.map do |element|
+          if field.array_of
+            rep = @registry.representations[field.array_of]
+            rep ? serialize_fields(rep.fields, element, extra_attributes: extra_attributes, prefix: element_prefix) : element
+          else
+            serialize_fields(field.children, element, extra_attributes: extra_attributes, prefix: element_prefix)
+          end
+        end
+      else
+        # Fresh Array in both branches: never alias the caller's collection
+        # into the result, and normalize non-Array Enumerables (Set, lazy
+        # enumerators) into something JSON.generate can serialize. dup/to_a
+        # instead of an identity map: same semantics without dispatching a
+        # block per element (memcpy vs O(n) yields on large scalar arrays).
+        value.is_a?(Array) ? value.dup : value.to_a
+      end
+    end
+
+    def array_like?(value)
+      value.is_a?(Array) || (value.is_a?(Enumerable) && !value.is_a?(Hash))
+    end
+
+    def handle_non_iterable_array(value, path)
+      return if @strict_mode == :ignore
+
+      message = "Trane: expected Array at #{path}, got #{value.class}"
+      case @strict_mode
+      when :raise
+        raise ContractViolation, message
+      when :log
+        Trane.log_warning(message)
+      end
+    end
+
+    # Lazily compose dot-notation path; allocates only when a consumer
+    # (extras gate, nested-rep recursion, or strict-mode violation) needs it.
+    def build_path(prefix, leaf_sym)
+      prefix.empty? ? leaf_sym.name : "#{prefix}.#{leaf_sym}"
+    end
+
+    # Extract a value from data (supports both Hash and objects).
+    #
+    # For objects, only fields the receiver explicitly responds to are
+    # extracted; anything else returns nil. NoMethodError raised inside a
+    # getter is left to propagate so genuine bugs aren't swallowed.
+    def extract_value(data, field_name)
+      if data.is_a?(Hash)
+        return data[field_name] if data.key?(field_name)
+        data[field_name.name]
+      elsif data.respond_to?(field_name)
+        data.public_send(field_name)
+      end
+    end
+  end
+end

data/lib/trane/testing.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "trane"
+
+module Trane
+  # Test helper for temporarily reconfiguring Trane.
+  # Opt-in via: require "trane/testing"
+  module Testing
+    # Resets Configuration to the given attrs, freezes it, yields, then
+    # restores the original state. Guarantees restore even when the block
+    # raises.
+    #
+    # This helper does not touch the route set: `strict_mode` — the only
+    # attribute settable via `Trane.configure` — is read when a response is
+    # rendered (Trane::Controller::Renderer), never when routes are drawn. The
+    # API name is not configurable at all; it is Rails.application.name.
+    #
+    # `contracts_paths` is also configuration state (set from
+    # `config/application.rb` via the internal `_set_contracts_paths!`, not
+    # via `Trane.configure`), and `config.reset!` clears it along with
+    # `strict_mode`. This helper snapshots and restores both, so a host with a
+    # custom `contracts_paths` does not lose it across a call to this helper.
+    def self.with_configuration(**attrs)
+      raise Trane::Error, "Trane::Testing.with_configuration requires Rails.application" unless defined?(Rails) && Rails.application
+
+      config = Trane.configuration
+      snapshot = config._dump_state
+
+      config.reset!
+      attrs.each { |k, v| config.public_send(:"#{k}=", v) }
+      config.freeze!
+
+      yield config
+    ensure
+      # `config` is nil when the guard above raised; without this check the
+      # ensure block would replace that error with a NoMethodError.
+      config._restore_state!(snapshot) if config
+    end
+  end
+end

data/lib/trane/types.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "set"
+require "date"
+
+module Trane
+  module Types
+    PRIMITIVES = Set[
+      :string, :integer, :float, :boolean,
+      :date, :datetime, :object, :array
+    ].freeze
+
+    # Types that support enum: (scalar primitives only)
+    ENUMERABLE_TYPES = Set[
+      :string, :integer, :float, :boolean, :date, :datetime
+    ].freeze
+
+    HTTP_STATUS_RANGE = (100..599).freeze
+
+    def self.representation_reference?(type)
+      !type.nil? && !PRIMITIVES.include?(type)
+    end
+
+    # Strict type-match: each value must be EXACTLY of the declared type's class.
+    # No coercion (Integer not accepted for :float, DateTime not accepted for :date, etc).
+    def self.value_matches_type?(value, type)
+      case type
+      when :string   then value.is_a?(String)
+      when :integer  then value.is_a?(Integer)
+      when :float    then value.is_a?(Float)
+      when :boolean  then value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      when :date     then value.is_a?(Date) && !value.is_a?(DateTime)
+      # !! keeps the return strictly boolean: `defined?` yields nil (not
+      # false) when TimeWithZone isn't loaded, and nil would leak out.
+      when :datetime then value.is_a?(DateTime) || value.is_a?(Time) ||
+                          (!!defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone))
+      else false
+      end
+    end
+
+    # Validates the structure and content of an enum: declaration. Raises ArgumentError if invalid.
+    def self.validate_enum!(name:, type:, enum:)
+      return if enum.nil?
+
+      unless enum.is_a?(Array)
+        raise ArgumentError, "field/param :#{name} enum: must be an Array (got #{enum.class})"
+      end
+
+      if enum.empty?
+        raise ArgumentError, "field/param :#{name} enum: must be a non-empty Array"
+      end
+
+      unless ENUMERABLE_TYPES.include?(type)
+        raise ArgumentError,
+              "field/param :#{name} enum: is only supported for scalar primitive types " \
+              "(#{ENUMERABLE_TYPES.to_a.map { |t| ":#{t}" }.join(', ')}). Got :#{type}."
+      end
+
+      enum.each do |value|
+        unless value_matches_type?(value, type)
+          raise ArgumentError,
+                "field/param :#{name} enum value #{value.inspect} (#{value.class}) is not coherent with type :#{type}"
+        end
+      end
+    end
+  end
+end

data/lib/trane/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Trane
+  VERSION = "0.1.0"
+end

data/lib/trane.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Trane
+  class Error < StandardError; end
+
+  # Raised when a route's `contract:` metadata is malformed (unknown key,
+  # missing/blank :operation) or when a route's declared operation has no
+  # matching entry in the registry. Fails loud at boot/draw time instead of
+  # deferring the mistake to request time.
+  class RoutingContractError < Error; end
+end
+
+require_relative "trane/version"
+require_relative "trane/configuration"
+require_relative "trane/types"
+require_relative "trane/field_node"
+require_relative "trane/field_builder"
+require_relative "trane/param_definition"
+require_relative "trane/operation_definition"
+require_relative "trane/representation_definition"
+require_relative "trane/error_registry"
+require_relative "trane/registry"
+require_relative "trane/serializer"
+require_relative "trane/extra_attributes_filter"
+require_relative "trane/boot_validator"
+require_relative "trane/contract_loader"
+require_relative "trane/route_validator"
+require_relative "trane/contract_validator"
+require_relative "trane/controller"
+require_relative "trane/routing_extension"
+
+module Trane
+  # Process-level Trane state. Trane supports exactly one Rails application
+  # per Ruby process — the standard Rails deployment model. The registry and
+  # configuration are created eagerly at require time so pre-boot DSL
+  # registrations (e.g. unit specs calling Trane.operation before Rails
+  # boots) land in the same objects the booted application later uses.
+  @registry      = Registry::Instance.new
+  @configuration = Configuration.new
+
+  def self.configure
+    yield configuration
+  end
+
+  # Returns the process-level Configuration.
+  def self.configuration
+    @configuration
+  end
+
+  # Returns the process-level Registry::Instance.
+  def self.registry
+    @registry
+  end
+
+  # Restores Trane to a pristine state: empties the registry (snapshot and
+  # derived caches), clears the configuration (values and frozen flag), and
+  # invalidates the docs cache. Intended for test suites that need isolation
+  # between examples or that boot throwaway Rails applications.
+  def self.reset!
+    registry.reset!
+    configuration.reset!
+    Docs::Cache.invalidate!
+    nil
+  end
+
+  def self.operation(name, &block)
+    builder = OperationBuilder.new(name)
+    builder.instance_eval(&block)
+    registry.register_operation(builder.build)
+  end
+
+  def self.representation(name, &block)
+    builder = RepresentationBuilder.new(name)
+    builder.instance_eval(&block)
+    registry.register_representation(builder.build)
+  end
+
+  def self.errors(&block)
+    builder = ErrorsBuilder.new
+    builder.instance_eval(&block)
+    builder.definitions.each { |d| registry.register_error(d) }
+  end
+
+  # Logs a warning through Rails.logger when available, falling back to
+  # Kernel#warn (stderr) outside Rails. Single home for the guard chain so
+  # every warn-level message in the gem routes identically.
+  def self.log_warning(message)
+    if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+      Rails.logger.warn(message)
+    else
+      warn(message)
+    end
+  end
+
+  # Returns the closest spelling match for term among candidates, or nil
+  # when no candidate is close enough. Backs the "Did you mean?" hints in
+  # both the routing contract: hash validator and the route/registry
+  # cross-check, so the two validations never drift on suggestion logic.
+  def self.spelling_suggestion(term, candidates)
+    require "did_you_mean"
+    DidYouMean::SpellChecker.new(dictionary: candidates.map(&:to_s)).correct(term.to_s).first
+  end
+end
+
+require_relative "trane/docs/service_definition"
+require_relative "trane/docs/html_renderer"
+require_relative "trane/docs/cache"
+
+if defined?(Rails::Engine)
+  require_relative "trane/engine"
+end