permittable 0.1.2 → 0.3.0

data/lib/permittable/json_schema.rb

@@ -0,0 +1,196 @@
+module Permittable
+  # Converts frozen contract data — the rule and field hashes built by
+  # ContractBuilder — into JSON Schema (draft 2020-12, the dialect OpenAPI 3.1
+  # request bodies use). This is the third reader of the contract registry,
+  # after the request validator and the column guard: because a contract is
+  # data, a schema exported from it cannot drift from what the server
+  # actually enforces.
+  #
+  # The exported schema describes the DECLARED INPUT SHAPE in its canonical
+  # JSON encoding. Two deliberate consequences:
+  #   * Coercion additionally accepts string-encoded scalars ("42", "true")
+  #     for form/query payloads; the schema documents the JSON types only.
+  #   * `validate:`/`transform:`/`finalize` are opaque callables — they never
+  #     change what a client may SEND, so fields carrying them are flagged
+  #     with `x-permittable-*` extensions rather than mistranslated.
+  #
+  # Emission is deterministic (fixed key insertion order, declaration-order
+  # properties) so generated documents are committable and diff-stable.
+  module JsonSchema
+    module_function
+
+    SCALAR_SCHEMAS = {
+      string: { "type" => "string" },
+      integer: { "type" => "integer" },
+      float: { "type" => "number" },
+      # Coercion accepts Numeric or String for :decimal; string is the
+      # precision-safe form, so both encodings are documented.
+      decimal: { "type" => %w[string number], "format" => "decimal" },
+      boolean: { "type" => "boolean" },
+      date: { "type" => "string", "format" => "date" },
+      datetime: { "type" => "string", "format" => "date-time" }
+    }.freeze
+
+    # Ruby regexp constructs with no ECMA-262 equivalent (\Z, \h, \K, \R, \G,
+    # inline flag groups, absence operator, conditionals, POSIX classes,
+    # possessive quantifiers). A source matching this is left untranslated —
+    # the scan is deliberately over-eager on escaped lookalikes because a
+    # wrong pattern in published docs is worse than a missing one.
+    UNTRANSLATABLE = /
+      \\[ZhHKRG]          |
+      \(\?[a-z-]+[:)]     |
+      \(\?~               |
+      \(\?\(              |
+      \[\[:               |
+      [*+?]\+
+    /x
+
+    # Request-body schema for one rule from `permittable_contracts` /
+    # `permit_rule_for`: the object schema of its fields, wrapped in the
+    # `root:` envelope when the rule declares one. The wrapper itself stays
+    # permissive even under `unknown: :error` — the runtime never inspects
+    # sibling keys outside the root.
+    def rule(permit_rule)
+      schema = object(permit_rule[:fields], unknown: permit_rule[:unknown])
+      return schema unless permit_rule[:root]
+
+      root = permit_rule[:root].to_s
+      { "type" => "object", "properties" => { root => schema }, "required" => [root] }
+    end
+
+    # Object schema for a field list; `unknown:` applies at every nesting
+    # level, exactly like the runtime check.
+    def object(fields, unknown: :ignore)
+      schema = {
+        "type" => "object",
+        "properties" => fields.to_h { |f| [f[:name].to_s, field(f, unknown: unknown)] }
+      }
+      required = fields.select { |f| f[:required] }.map { |f| f[:name].to_s }
+      schema["required"] = required unless required.empty?
+      schema["additionalProperties"] = false if unknown == :error
+      schema
+    end
+
+    # Schema fragment for one field hash of any kind.
+    def field(field, unknown: :ignore)
+      schema = case field[:kind]
+               when :scalar then scalar_schema(field)
+               when :nested then object(field[:fields], unknown: unknown)
+               when :array then array_schema(field, unknown: unknown)
+               end
+      annotate(schema, field)
+    end
+
+    def scalar_schema(field)
+      schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
+      apply_in!(schema, field[:in])
+      apply_string_bounds!(schema, field)
+      apply_pattern!(schema, field[:format])
+      schema
+    end
+
+    def array_schema(field, unknown:)
+      schema = { "type" => "array" }
+      min, max = length_bounds(field[:length])
+      schema["minItems"] = min if min
+      schema["maxItems"] = max if max
+      schema["items"] = field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).dup
+      schema
+    end
+
+    def apply_in!(schema, allowed)
+      return unless allowed
+
+      unless allowed.is_a?(Range)
+        schema["enum"] = allowed.map { |v| json_value(v) }
+        return
+      end
+      # Runtime bounds-checks Ranges with cover?; numeric endpoints map onto
+      # minimum/maximum, anything else (a Range of strings) has no JSON
+      # Schema equivalent and is carried as an extension.
+      unless allowed.begin.is_a?(Numeric) || allowed.end.is_a?(Numeric)
+        schema["x-permittable-range"] = allowed.inspect
+        return
+      end
+      schema["minimum"] = json_value(allowed.begin) if allowed.begin
+      schema[allowed.exclude_end? ? "exclusiveMaximum" : "maximum"] = json_value(allowed.end) if allowed.end
+    end
+
+    def apply_string_bounds!(schema, field)
+      return unless field[:type] == :string
+
+      min, max = length_bounds(field[:length])
+      # "" is ABSENT and an absent required field violates, so a required
+      # string can never validly be empty — the schema says so.
+      min = 1 if field[:required] && min.to_i < 1
+      schema["minLength"] = min if min
+      schema["maxLength"] = max if max
+    end
+
+    def apply_pattern!(schema, regexp)
+      return unless regexp
+
+      pattern = ecma_pattern(regexp)
+      if pattern
+        schema["pattern"] = pattern
+      else
+        schema["x-permittable-pattern"] = regexp.inspect
+      end
+    end
+
+    # Conservative Ruby → ECMA-262 translation: \A/\z anchors become ^/$.
+    # Flagged regexps bail entirely (JSON Schema's `pattern` has no flag
+    # slot, and /x//m/i all change semantics), as does any source containing
+    # an untranslatable construct.
+    def ecma_pattern(regexp)
+      return nil unless regexp.options.zero?
+
+      source = regexp.source
+      return nil if source.match?(UNTRANSLATABLE)
+
+      source.gsub('\A', "^").gsub('\z', "$")
+    end
+
+    # length: reasons about characters on strings and element count on
+    # arrays; either way it is an exact Integer or a Range (possibly endless
+    # / beginless, possibly exclusive).
+    def length_bounds(spec)
+      case spec
+      when Integer then [spec, spec]
+      when Range
+        max = spec.end && spec.exclude_end? ? spec.end - 1 : spec.end
+        [spec.begin, max]
+      else [nil, nil]
+      end
+    end
+
+    # Documentation keys shared by every field kind. `default:`/`example:`
+    # are authored values (possibly Date/Time/BigDecimal literals), so they
+    # are re-encoded as JSON scalars.
+    def annotate(schema, field)
+      schema["default"] = json_value(field[:default]) if field.key?(:default)
+      schema["examples"] = [json_value(field[:example])] if field.key?(:example)
+      schema["description"] = field[:desc] if field[:desc]
+      if field[:sensitive]
+        schema["writeOnly"] = true
+        schema["x-permittable-sensitive"] = true
+      end
+      schema["x-permittable-custom-validation"] = true if field[:validate]
+      schema["x-permittable-transformed"] = true if field[:transform]
+      schema
+    end
+
+    def json_value(value)
+      case value
+      when Array then value.map { |v| json_value(v) }
+      when BigDecimal then value.to_s("F")
+      when Time then value.utc.iso8601
+      # DateTime subclasses Date, so it must match first.
+      when DateTime then value.to_time.utc.iso8601
+      when Date then value.iso8601
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end

data/lib/permittable/open_api.rb

@@ -0,0 +1,212 @@
+require "permittable/version"
+require "permittable/json_schema"
+
+module Permittable
+  # Assembles OpenAPI 3.1 fragments and documents from Permittable contracts.
+  # Plain Ruby over the frozen contract registry — Rails is not required; the
+  # `permittable:openapi` rake task (loaded by the Railtie) supplies the
+  # Rails-only parts: eager loading, controller discovery, and the route
+  # descriptors that turn operations into real `paths` entries.
+  #
+  # Everything the exporter cannot know is left visible rather than guessed:
+  # actions covered only by a catch-all rule on a host without
+  # `action_methods` appear under the "*" key with `x-permittable-catch-all`,
+  # and operations with no matching route land in `x-permittable-controllers`
+  # instead of being dropped silently.
+  module OpenAPI
+    module_function
+
+    # The error envelope rendered by render_invalid_parameters (see
+    # ErrorEnvelope): code/details are present on every violation this gem
+    # raises, message always.
+    ERROR_SCHEMA = {
+      "type" => "object",
+      "properties" => {
+        "success" => { "type" => "boolean", "enum" => [false] },
+        "error" => {
+          "type" => "object",
+          "properties" => {
+            "message" => { "type" => "string" },
+            "code" => { "type" => "string", "enum" => ["invalid_parameters"] },
+            "details" => {
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "properties" => {
+                  "param" => {
+                    "type" => "string",
+                    "description" => "Fully-qualified parameter path, e.g. user.address.zip or line_items[1].sku"
+                  },
+                  "code" => {
+                    "type" => "string",
+                    "description" => "missing / invalid_type / inclusion / format / length / unknown / invalid, " \
+                                     "or a contract-specific symbol"
+                  }
+                },
+                "required" => %w[param code]
+              }
+            }
+          },
+          "required" => %w[message]
+        }
+      },
+      "required" => %w[success error]
+    }.freeze
+
+    # Instance methods the concern itself adds to every including controller;
+    # action_methods reports them as actions (they are public by design), but
+    # they are never routed and must not be documented as endpoints. Resolved
+    # lazily — at file-load time the concern's module body may not have run.
+    def concern_methods
+      @concern_methods ||= Permittable.public_instance_methods(false).map(&:to_s).freeze
+    end
+
+    # Shared `components` for any document referencing Permittable responses.
+    def components
+      {
+        "schemas" => { "PermittableInvalidParameters" => ERROR_SCHEMA },
+        "responses" => {
+          "PermittableBadRequest" => error_response(
+            "The root: key is missing or not an object — the request envelope itself is malformed."
+          ),
+          "PermittableUnprocessableEntity" => error_response(
+            "One or more parameters violated the action's contract; details names each offender."
+          )
+        }
+      }
+    end
+
+    def error_response(description)
+      {
+        "description" => description,
+        "content" => {
+          "application/json" => {
+            "schema" => { "$ref" => "#/components/schemas/PermittableInvalidParameters" }
+          }
+        }
+      }
+    end
+
+    # OpenAPI requestBody object for the contract covering `action`, nil when
+    # no contract does. `required` mirrors the runtime: a rooted contract
+    # rejects a bodyless request outright (400), and so does any top-level
+    # required field (missing).
+    def request_body_for(controller, action)
+      rule = controller.permit_rule_for(action)
+      rule && rule_request_body(rule)
+    end
+
+    def rule_request_body(rule)
+      {
+        "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
+        "content" => { "application/json" => { "schema" => JsonSchema.rule(rule) } }
+      }
+    end
+
+    # { action => operation } for every action the controller's contracts
+    # cover, resolved through permit_rule_for so last-matching-rule-wins holds
+    # in the documentation exactly as it does at request time.
+    def operations_for(controller)
+      documented_actions(controller).to_h { |action| [action, operation_for(controller, action)] }
+    end
+
+    # Explicitly-declared actions in declaration order; when a catch-all rule
+    # exists, the controller's remaining action_methods (sorted) follow — or
+    # the literal "*" on hosts without action_methods (plain-Ruby params
+    # ducks), where the covered action set is unknowable.
+    def documented_actions(controller)
+      contracts = controller.permittable_contracts
+      explicit = contracts.flat_map { |rule| rule[:actions] }.uniq
+      return explicit unless contracts.any? { |rule| rule[:actions].empty? }
+      return explicit + ["*"] unless controller.respond_to?(:action_methods)
+
+      explicit + (controller.action_methods.map(&:to_s).sort - explicit - concern_methods)
+    end
+
+    def operation_for(controller, action)
+      rule = if action == "*"
+               controller.permittable_contracts.reverse_each.find { |r| r[:actions].empty? }
+             else
+               controller.permit_rule_for(action)
+             end
+      operation = {}
+      key = controller_key(controller)
+      operation["operationId"] = "#{key.tr('/', '_')}_#{action}" if key && action != "*"
+      operation["description"] = rule[:desc] if rule[:desc]
+      operation["requestBody"] = rule_request_body(rule)
+      operation["responses"] = responses_for(rule)
+      operation["x-permittable-catch-all"] = true if action == "*"
+      operation
+    end
+
+    def responses_for(rule)
+      responses = {}
+      responses["400"] = { "$ref" => "#/components/responses/PermittableBadRequest" } if rule[:root]
+      responses["422"] = { "$ref" => "#/components/responses/PermittableUnprocessableEntity" }
+      responses
+    end
+
+    # A complete OpenAPI 3.1 document. `routes:` is an optional array of
+    # { controller:, action:, verb:, path: } descriptors (see rails_routes);
+    # operations with a matching descriptor become `paths` entries, the rest
+    # are grouped by controller under `x-permittable-controllers`.
+    def document(controllers:, info: {}, routes: nil)
+      paths = {}
+      unrouted = {}
+      controllers.each do |controller|
+        operations = operations_for(controller)
+        next if operations.empty?
+
+        place_operations(controller, operations, routes, paths, unrouted)
+      end
+      doc = {
+        "openapi" => "3.1.0",
+        "info" => { "title" => "Permittable contracts", "version" => VERSION }.merge(info),
+        "paths" => paths,
+        "components" => components
+      }
+      doc["x-permittable-controllers"] = unrouted unless unrouted.empty?
+      doc
+    end
+
+    def place_operations(controller, operations, routes, paths, unrouted)
+      key = controller_key(controller) || controller.inspect
+      operations.each do |action, operation|
+        matched = routes_for(routes, key, action)
+        if matched.empty?
+          (unrouted[key] ||= {})[action] = operation
+        else
+          matched.each { |route| (paths[route[:path]] ||= {})[route[:verb].to_s.downcase] = operation }
+        end
+      end
+    end
+
+    def routes_for(routes, controller_key, action)
+      return [] if routes.nil? || action == "*"
+
+      routes.select { |r| r[:controller].to_s == controller_key && r[:action].to_s == action }
+    end
+
+    # { controller:, action:, verb:, path: } descriptors from a Rails
+    # application's route set. Duck-typed against Journey routes (each one
+    # responds to requirements / verb / path.spec) so it stays unit-testable
+    # without Rails; Rails path params (:id) become OpenAPI templates ({id}).
+    def rails_routes(app)
+      app.routes.routes.filter_map do |route|
+        requirements = route.requirements
+        verb = route.verb.to_s
+        next if requirements[:controller].nil? || requirements[:action].nil? || verb.empty?
+
+        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/:(\w+)/) { "{#{Regexp.last_match(1)}}" }
+        { controller: requirements[:controller], action: requirements[:action],
+          verb: verb.split("|").first.downcase, path: path }
+      end
+    end
+
+    def controller_key(controller)
+      return controller.controller_path if controller.respond_to?(:controller_path)
+
+      controller.name
+    end
+  end
+end

data/lib/permittable/railtie.rb

@@ -12,5 +12,9 @@ module Permittable
       filter = ::Permittable.filter_parameter_registry.to_proc
       app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
     end
+
+    rake_tasks do
+      load File.expand_path("tasks/openapi.rake", __dir__)
+    end
   end
 end

data/lib/permittable/tasks/openapi.rake

@@ -0,0 +1,44 @@
+# Exports every Permittable contract in the app as an OpenAPI 3.1 document —
+# the docs-that-cannot-drift counterpart to the schema-drift guard. Eager
+# loading makes every controller's permit_params macro run (also exercising
+# the drift guard), then the route set maps documented actions onto paths.
+#
+#   bin/rails permittable:openapi                       # JSON to stdout
+#   bin/rails "permittable:openapi[openapi/api.json]"   # write to a file
+#
+# OPENAPI_TITLE / OPENAPI_VERSION override the document's info block.
+require "json"
+require "fileutils"
+
+namespace :permittable do
+  desc "Export an OpenAPI 3.1 document generated from every Permittable contract"
+  task :openapi, [:output] => :environment do |_t, task_args|
+    Rails.application.eager_load!
+
+    bases = []
+    bases << ActionController::Base if defined?(ActionController::Base)
+    bases << ActionController::API if defined?(ActionController::API)
+    controllers = bases.flat_map(&:descendants).uniq.select do |controller|
+      controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any?
+    end
+
+    document = Permittable::OpenAPI.document(
+      controllers: controllers,
+      routes: Permittable::OpenAPI.rails_routes(Rails.application),
+      info: {
+        "title" => ENV.fetch("OPENAPI_TITLE") { "#{Rails.application.class.module_parent_name} API" },
+        "version" => ENV.fetch("OPENAPI_VERSION", "1.0.0")
+      }
+    )
+
+    json = "#{JSON.pretty_generate(document)}\n"
+    if task_args[:output]
+      FileUtils.mkdir_p(File.dirname(task_args[:output]))
+      File.write(task_args[:output], json)
+      puts "Permittable: wrote #{task_args[:output]} " \
+           "(#{controllers.length} controller#{'s' unless controllers.length == 1})"
+    else
+      puts json
+    end
+  end
+end

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.1.2".freeze
+  VERSION = "0.3.0".freeze
 end