rails_contract_sync 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 751fea8841b43d6858240cdfdda225ac84208f87c189983bf5cdefbda6f8e8c1
+  data.tar.gz: '088b08bbfc5150f9831121f9009bfe8bd07858ca399c73eefc84768790d93a71'
+SHA512:
+  metadata.gz: e247f9f52088a834beb06a5f9b934ac42c5d9bc3fbc9ae7086a0b8e85c2141ad9813d066fc45e7a71397aa62a31fb314a134e7eff4cc258d89beb4768bd01bf9
+  data.tar.gz: 6d5aa091d2897944443ee56f301cdd72d482230634dbe87856dca1ebe76abe35429871df16f24f8e067458c363fe9886f0bfee0c616faa2d83f56d94af681151

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# RailsSync
+
+**Keep an OpenAPI 3.1 contract for your Rails JSON API in sync — automatically.**
+
+RailsSync produces and maintains a single committed `openapi.yml` for your Rails API by combining two sources of truth:
+
+- **Static introspection** — reads your routes and `params.require/permit` declarations (via [Prism](https://github.com/ruby/prism)) to lay down the endpoint + request-parameter skeleton, with zero test runs.
+- **Runtime observation** — a lightweight Rack middleware records the *actual* JSON responses your app returns (in your test suite, or while you click around in development) and fills in real response schemas.
+
+The two are merged into one committed file that is:
+
+- **Idempotent** — re-run it anytime; the output is byte-stable, so diffs show only real API changes.
+- **Prose-preserving** — your hand-written `summary`/`description`/`tags` are never clobbered by a regeneration.
+- **Honest** — endpoints you haven't exercised yet are flagged, not faked.
+
+Because the runtime layer reads the response *bytes*, RailsSync is **serializer-agnostic** — it doesn't care whether you use ActiveModel::Serializers, Jbuilder, Blueprinter, Alba, or plain `render json:`.
+
+## Why
+
+You changed an endpoint. Now your OpenAPI doc is a lie — until someone remembers to hand-edit it. Hand-written API specs rot; fully manual DSLs are tedious; and pure static analysis can't see what your serializers actually emit at runtime. RailsSync splits the difference: static analysis gives you an instant, zero-setup skeleton, and your existing tests (or a few minutes of clicking) supply the real response shapes.
+
+## Installation
+
+Add it to your Gemfile — typically in the development and test groups, since that's where the contract is generated:
+
+```ruby
+group :development, :test do
+  gem "rails_sync"
+end
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Three steps.
+
+### 1. Generate the static skeleton
+
+```bash
+bin/rails rails_sync:generate
+```
+
+Reads your routes and strong-params and writes `openapi.yml` with paths, HTTP verbs, and request-body parameters. No response schemas yet — that's the next step.
+
+### 2. Capture real responses
+
+Run your app with `RAILS_SYNC=1` so the capture middleware is active:
+
+```bash
+RAILS_SYNC=1 bundle exec rspec     # capture from your request/system specs
+# or
+RAILS_SYNC=1 bin/rails server      # then exercise the app by hand
+```
+
+Every JSON response is recorded to `tmp/rails_sync/observations.jsonl`. The middleware only mounts when `RAILS_SYNC` is set, so it never runs in production by accident.
+
+### 3. Build the full contract
+
+```bash
+bin/rails rails_sync:build
+```
+
+Infers response schemas from the captured traffic, merges them with the static skeleton **and** with any descriptions you've added to `openapi.yml` by hand, and writes the result back. Commit `openapi.yml`.
+
+Re-run `rails_sync:build` whenever your API changes. Stale endpoints (present in the file but no longer in your routes) are tagged `x-rails-sync-stale: true` rather than silently deleted.
+
+## What the output looks like
+
+```yaml
+openapi: 3.1.0
+info:
+  title: API
+  version: 1.0.0
+paths:
+  "/users":
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                user:
+                  type: object
+                  properties:
+                    name:
+                      type: string
+      responses:
+        "201":
+          description: ""        # add your own prose here — it survives rebuilds
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: integer }
+                  name: { type: string }
+                required: [id, name]
+  "/users/{id}":
+    get:
+      responses:
+        "200":
+          description: ""
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: integer }
+                  name: { type: string }
+                required: [id, name]
+```
+
+Point Swagger UI, `openapi-typescript`, Postman, or any OpenAPI 3.1 tool at this file.
+
+## How it works
+
+| Layer | What it does |
+|---|---|
+| `Static::RouteExtractor` | Maps `Rails.application.routes` to OpenAPI paths (`/users/:id` → `/users/{id}`). |
+| `Static::ParamsExtractor` | Parses controllers with Prism to read `params.require(...).permit(...)` (best-effort). |
+| `Runtime::Middleware` | Env-gated Rack middleware; records real request params + response bodies. |
+| `SchemaInferrer` | Turns observed JSON into JSON Schema, widening types across observations. |
+| `Merger` | Reconciles static + observed + your existing file; preserves prose; idempotent. |
+
+## Configuration
+
+```ruby
+RailsSync.configuration.output_path        # default: "openapi.yml"
+RailsSync.configuration.observations_path  # default: "tmp/rails_sync/observations.jsonl"
+RailsSync.configuration.enabled?           # true when ENV["RAILS_SYNC"] is truthy
+```
+
+## Scope & limitations (v1)
+
+RailsSync is deliberately focused. It does **not** try to do everything:
+
+- **JSON REST controllers only** (`ActionController` / `ActionController::API`). No GraphQL or Grape.
+- **Static strong-params reading is best-effort.** It handles literal `permit` arguments; conditional or metaprogrammed params are simply filled in by the runtime layer the first time a request hits that endpoint.
+- **Response schemas reflect the traffic you capture.** Coverage equals what your tests or manual usage exercise — an endpoint you never call won't get a response schema.
+- **Not in scope (yet):** breaking-change / contract diffing in CI, and over-the-air bundle delivery. The committed `openapi.yml` is designed to be the seed for the former.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/rails_contract_sync/builder.rb

@@ -0,0 +1,90 @@
+require "fileutils"
+
+module RailsContractSync
+  class Builder
+    def initialize(route_set:, controller_sources: {}, observations: [])
+      @route_set = route_set
+      @controller_sources = controller_sources
+      @observations = observations
+    end
+
+    def build_fresh
+      doc = OpenAPIDocument.new
+      routes = Static::RouteExtractor.new(@route_set).extract
+      params_by_controller = extract_params
+
+      routes.each do |route|
+        op = { "responses" => {} }
+        add_request_body(op, route, params_by_controller)
+        add_observed(op, route)
+        op["responses"]["default"] = { "description" => "" } if op["responses"].empty?
+        doc.set_operation(route[:path], route[:verb], op)
+      end
+      doc
+    end
+
+    private
+
+    def extract_params
+      @controller_sources.transform_values { |src| Static::ParamsExtractor.extract(src) }
+    end
+
+    def add_request_body(op, route, params_by_controller)
+      tree = params_by_controller.dig(route[:controller], route[:action])
+      static_schema = tree ? tree_to_schema(tree) : nil
+      runtime_schema = observed_request_schema(route)
+      schema = [static_schema, runtime_schema].compact.reduce(nil) { |a, s| a ? SchemaInferrer.merge(a, s) : s }
+      return if schema.nil?
+
+      op["requestBody"] = { "content" => { "application/json" => { "schema" => schema } } }
+    end
+
+    def observed_request_schema(route)
+      bodies = matching(route).map { |o| o.dig("request", "params") }.compact
+      bodies.empty? ? nil : SchemaInferrer.infer_all(bodies)
+    end
+
+    def add_observed(op, route)
+      matching(route).group_by { |o| o.dig("response", "status") }.each do |status, group|
+        bodies = group.map { |o| o.dig("response", "body") }
+        op["responses"][status.to_s] = {
+          "description" => "",
+          "content" => { "application/json" => { "schema" => SchemaInferrer.infer_all(bodies) } }
+        }
+      end
+    end
+
+    def matching(route)
+      @observations.select { |o| o["verb"] == route[:verb] && o["path_template"] == route[:path] }
+    end
+
+    def tree_to_schema(tree)
+      case tree
+      when nil then {}
+      when Array then { "type" => "array", "items" => tree_to_schema(tree.first) }
+      when Hash
+        props = tree.transform_values { |v| tree_to_schema(v) }
+        { "type" => "object", "properties" => props }
+      end
+    end
+  end
+
+  module_function
+
+  def generate(route_set:, controller_sources:, output_path:, prune: false)
+    write_merged(route_set: route_set, controller_sources: controller_sources, observations: [], output_path: output_path, prune: prune)
+  end
+
+  def build(route_set:, controller_sources:, observation_store:, output_path:, prune: false)
+    write_merged(route_set: route_set, controller_sources: controller_sources, observations: observation_store.all, output_path: output_path, prune: prune)
+  end
+
+  def write_merged(route_set:, controller_sources:, observations:, output_path:, prune:)
+    fresh = Builder.new(route_set: route_set, controller_sources: controller_sources, observations: observations).build_fresh
+    existing = File.exist?(output_path) ? OpenAPIDocument.load_file(output_path) : nil
+    merged = Merger.merge(existing, fresh, prune: prune)
+    FileUtils.mkdir_p(File.dirname(File.expand_path(output_path)))
+    merged.write(output_path)
+    merged
+  end
+end

data/lib/rails_contract_sync/configuration.rb

@@ -0,0 +1,25 @@
+module RailsContractSync
+  class Configuration
+    attr_accessor :output_path, :observations_path
+
+    def initialize
+      @output_path = "openapi.yml"
+      @observations_path = "tmp/rails_contract_sync/observations.jsonl"
+    end
+
+    def enabled?
+      v = ENV["RAILS_CONTRACT_SYNC"]
+      !v.nil? && !v.empty? && v != "0" && v.downcase != "false"
+    end
+
+    def observation_store
+      Runtime::ObservationStore.new(observations_path)
+    end
+  end
+
+  module_function
+
+  def configuration
+    @configuration ||= Configuration.new
+  end
+end

data/lib/rails_contract_sync/merger.rb

@@ -0,0 +1,42 @@
+module RailsContractSync
+  module Merger
+    HUMAN_OP_KEYS = %w[summary description tags].freeze
+
+    module_function
+
+    def merge(existing, fresh, prune: false)
+      result = fresh.to_h
+      result_paths = result["paths"] ||= {}
+      return OpenAPIDocument.new(result) if existing.nil?
+
+      existing_h = existing.to_h
+      result["info"] = existing_h["info"] if existing_h["info"]
+
+      (existing_h["paths"] || {}).each do |path, ops|
+        ops.each do |verb, existing_op|
+          target = result_paths.dig(path, verb)
+          if target
+            HUMAN_OP_KEYS.each { |k| target[k] = existing_op[k] if existing_op.key?(k) }
+            preserve_descriptions(existing_op["responses"], target["responses"])
+          elsif !prune
+            (result_paths[path] ||= {})[verb] = existing_op.merge("x-rails-contract-sync-stale" => true)
+          end
+        end
+      end
+
+      OpenAPIDocument.new(result)
+    end
+
+    # Recursively copy "description" from old schema nodes onto matching new ones.
+    def preserve_descriptions(old_node, new_node)
+      return unless old_node.is_a?(Hash) && new_node.is_a?(Hash)
+
+      new_node["description"] = old_node["description"] if old_node.key?("description")
+      old_node.each do |key, old_child|
+        next if key == "description"
+
+        preserve_descriptions(old_child, new_node[key])
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/openapi_document.rb

@@ -0,0 +1,62 @@
+require "yaml"
+
+module RailsContractSync
+  class OpenAPIDocument
+    def self.load_file(path)
+      return new unless File.exist?(path)
+
+      new(YAML.safe_load_file(path))
+    end
+
+    def initialize(hash = nil)
+      @doc = deep_dup(hash) || skeleton
+      @doc["paths"] ||= {}
+    end
+
+    def paths
+      @doc["paths"]
+    end
+
+    def operation(path, verb)
+      paths.dig(path, verb.to_s.downcase)
+    end
+
+    def set_operation(path, verb, op_hash)
+      (paths[path] ||= {})[verb.to_s.downcase] = op_hash
+    end
+
+    def to_h
+      deep_sort(deep_dup(@doc))
+    end
+
+    def to_yaml
+      to_h.to_yaml
+    end
+
+    def write(path)
+      File.write(path, to_yaml)
+    end
+
+    private
+
+    def skeleton
+      { "openapi" => "3.1.0", "info" => { "title" => "API", "version" => "1.0.0" }, "paths" => {} }
+    end
+
+    def deep_dup(obj)
+      case obj
+      when Hash then obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+      when Array then obj.map { |v| deep_dup(v) }
+      else obj
+      end
+    end
+
+    def deep_sort(obj)
+      case obj
+      when Hash then obj.keys.sort.each_with_object({}) { |k, h| h[k] = deep_sort(obj[k]) }
+      when Array then obj.map { |v| deep_sort(v) }
+      else obj
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/railtie.rb

@@ -0,0 +1,19 @@
+module RailsContractSync
+  class Railtie < Rails::Railtie
+    initializer "rails_contract_sync.middleware" do |app|
+      if RailsContractSync.configuration.enabled?
+        resolver = Runtime::RouteResolver.new(app.routes)
+        app.middleware.use(
+          Runtime::Middleware,
+          store: RailsContractSync.configuration.observation_store,
+          route_resolver: resolver,
+          enabled: true
+        )
+      end
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/rails_contract_sync.rake", __dir__)
+    end
+  end
+end

data/lib/rails_contract_sync/runtime/middleware.rb

@@ -0,0 +1,75 @@
+require "json"
+
+module RailsContractSync
+  module Runtime
+    class Middleware
+      def initialize(app, store:, route_resolver:, enabled: true)
+        @app = app
+        @store = store
+        @route_resolver = route_resolver
+        @enabled = enabled
+      end
+
+      def call(env)
+        status, headers, response = @app.call(env)
+        return [status, headers, response] unless enabled?
+
+        content_type = headers["Content-Type"] || headers["content-type"]
+        return [status, headers, response] unless content_type&.include?("application/json")
+
+        # Buffer the body so both the recorder and the downstream server can read it.
+        parts = []
+        response.each { |part| parts << part }
+        response.close if response.respond_to?(:close)
+
+        record(env, status, headers, content_type, parts)
+        [status, headers, parts]
+      end
+
+      private
+
+      def enabled?
+        @enabled
+      end
+
+      def record(env, status, headers, content_type, parts)
+        template = @route_resolver.call(env)
+        return if template.nil?
+
+        @store.append(
+          "verb" => env["REQUEST_METHOD"],
+          "path_template" => template,
+          "request" => {
+            "content_type" => env["CONTENT_TYPE"],
+            "params" => request_params(env)
+          },
+          "response" => {
+            "status" => status,
+            "content_type" => content_type,
+            "body" => safe_parse(parts.join)
+          }
+        )
+      rescue StandardError
+        nil
+      end
+
+      def request_params(env)
+        input = env["rack.input"]
+        return {} unless input
+
+        raw = input.read
+        input.rewind if input.respond_to?(:rewind)
+        return {} if raw.nil? || raw.empty?
+
+        parsed = safe_parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+
+      def safe_parse(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/runtime/observation_store.rb

@@ -0,0 +1,27 @@
+require "json"
+require "fileutils"
+
+module RailsContractSync
+  module Runtime
+    class ObservationStore
+      def initialize(path)
+        @path = path
+      end
+
+      def append(hash)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, "a") { |f| f.puts(JSON.generate(hash)) }
+      end
+
+      def all
+        return [] unless File.exist?(@path)
+
+        File.readlines(@path, chomp: true).reject(&:empty?).map { |line| JSON.parse(line) }
+      end
+
+      def clear
+        File.delete(@path) if File.exist?(@path)
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/runtime/route_resolver.rb

@@ -0,0 +1,21 @@
+module RailsContractSync
+  module Runtime
+    class RouteResolver
+      def initialize(route_set)
+        @routes = Static::RouteExtractor.new(route_set).extract
+      end
+
+      def call(env)
+        params = env["action_dispatch.request.path_parameters"]
+        return nil unless params
+
+        controller = params[:controller]
+        action = params[:action]
+        match = @routes.find do |r|
+          r[:controller] == controller && r[:action] == action && r[:verb] == env["REQUEST_METHOD"]
+        end
+        match&.fetch(:path)
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/schema_inferrer.rb

@@ -0,0 +1,64 @@
+module RailsContractSync
+  module SchemaInferrer
+    module_function
+
+    def infer(value)
+      case value
+      when nil then { "type" => "null" }
+      when true, false then { "type" => "boolean" }
+      when Integer then { "type" => "integer" }
+      when Float then { "type" => "number" }
+      when String then { "type" => "string" }
+      when Array then infer_array(value)
+      when Hash then infer_object(value)
+      else { "type" => "string" }
+      end
+    end
+
+    def infer_array(array)
+      { "type" => "array", "items" => infer_all(array) }
+    end
+
+    def infer_object(hash)
+      props = {}
+      hash.each { |k, v| props[k.to_s] = infer(v) }
+      { "type" => "object", "properties" => props, "required" => hash.keys.map(&:to_s).sort }
+    end
+
+    def infer_all(values)
+      values.map { |v| infer(v) }.reduce(nil) { |acc, s| acc ? merge(acc, s) : s } || {}
+    end
+
+    def merge(a, b)
+      a ||= {}
+      b ||= {}
+      return b if a.empty?
+      return a if b.empty?
+
+      types = (Array(a["type"]) | Array(b["type"])).sort
+      # Widen integer + number to just number
+      if types == ["integer", "number"]
+        types = ["number"]
+      end
+      result = { "type" => types.length == 1 ? types.first : types }
+      result.merge!(merge_object(a, b)) if types.include?("object")
+      result["items"] = merge(a["items"] || {}, b["items"] || {}) if types.include?("array")
+      result
+    end
+
+    def merge_object(a, b)
+      props_a = a["properties"] || {}
+      props_b = b["properties"] || {}
+      merged = {}
+      (props_a.keys | props_b.keys).each do |k|
+        merged[k] = if props_a[k] && props_b[k]
+          merge(props_a[k], props_b[k])
+        else
+          props_a[k] || props_b[k]
+        end
+      end
+      required = ((a["required"] || []) & (b["required"] || [])).sort
+      { "properties" => merged, "required" => required }
+    end
+  end
+end

data/lib/rails_contract_sync/static/params_extractor.rb

@@ -0,0 +1,78 @@
+require "prism"
+
+module RailsContractSync
+  module Static
+    module ParamsExtractor
+      module_function
+
+      def extract(source)
+        program = Prism.parse(source).value
+        actions = {}
+        each_def(program) do |def_node|
+          tree = first_permit_tree(def_node.body)
+          actions[def_node.name.to_s] = tree if tree
+        end
+        actions
+      end
+
+      def each_def(node, &block)
+        return unless node
+
+        yield node if node.is_a?(Prism::DefNode)
+        node.compact_child_nodes.each { |child| each_def(child, &block) }
+      end
+
+      # Depth-first: return the tree for the first `permit` call found.
+      def first_permit_tree(node)
+        return nil unless node
+
+        if node.is_a?(Prism::CallNode) && node.name == :permit
+          tree = permit_args_to_tree(node.arguments)
+          key = require_key(node.receiver)
+          return key ? { key => tree } : tree
+        end
+
+        node.compact_child_nodes.each do |child|
+          found = first_permit_tree(child)
+          return found if found
+        end
+        nil
+      end
+
+      def require_key(receiver)
+        return nil unless receiver.is_a?(Prism::CallNode) && receiver.name == :require
+
+        arg = receiver.arguments&.arguments&.first
+        arg.is_a?(Prism::SymbolNode) ? arg.unescaped : nil
+      end
+
+      def permit_args_to_tree(arguments_node)
+        tree = {}
+        (arguments_node&.arguments || []).each do |arg|
+          case arg
+          when Prism::SymbolNode
+            tree[arg.unescaped] = nil
+          when Prism::KeywordHashNode, Prism::HashNode
+            arg.elements.each do |assoc|
+              next unless assoc.is_a?(Prism::AssocNode) && assoc.key.is_a?(Prism::SymbolNode)
+
+              tree[assoc.key.unescaped] = value_to_tree(assoc.value)
+            end
+          end
+        end
+        tree
+      end
+
+      def value_to_tree(value)
+        return nil unless value.is_a?(Prism::ArrayNode)
+        return [nil] if value.elements.empty?
+
+        nested = {}
+        value.elements.each do |el|
+          nested[el.unescaped] = nil if el.is_a?(Prism::SymbolNode)
+        end
+        nested.empty? ? nil : nested
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/static/route_extractor.rb

@@ -0,0 +1,29 @@
+module RailsContractSync
+  module Static
+    class RouteExtractor
+      VERBS = %w[GET POST PUT PATCH DELETE].freeze
+
+      def initialize(route_set)
+        @route_set = route_set
+      end
+
+      def extract
+        @route_set.routes.filter_map do |route|
+          controller = route.defaults[:controller]
+          action = route.defaults[:action]
+          next if controller.nil? || action.nil?
+
+          verb = VERBS.find { |m| route.verb.to_s.include?(m) }
+          next if verb.nil?
+
+          spec = route.path.spec.to_s.sub(/\(\.:format\)\z/, "")
+          { verb: verb,
+            path: spec.gsub(/:([a-z_]+)/) { "{#{Regexp.last_match(1)}}" },
+            controller: controller,
+            action: action,
+            path_params: spec.scan(/:([a-z_]+)/).flatten - ["format"] }
+        end
+      end
+    end
+  end
+end

data/lib/rails_contract_sync/version.rb

@@ -0,0 +1,3 @@
+module RailsContractSync
+  VERSION = "0.2.0"
+end

data/lib/rails_contract_sync.rb

@@ -0,0 +1,15 @@
+require_relative "rails_contract_sync/version"
+require_relative "rails_contract_sync/schema_inferrer"
+require_relative "rails_contract_sync/openapi_document"
+require_relative "rails_contract_sync/static/route_extractor"
+require_relative "rails_contract_sync/static/params_extractor"
+require_relative "rails_contract_sync/runtime/observation_store"
+require_relative "rails_contract_sync/runtime/middleware"
+require_relative "rails_contract_sync/merger"
+require_relative "rails_contract_sync/builder"
+require_relative "rails_contract_sync/configuration"
+require_relative "rails_contract_sync/runtime/route_resolver"
+require_relative "rails_contract_sync/railtie" if defined?(Rails::Railtie)
+
+module RailsContractSync
+end

data/lib/tasks/rails_contract_sync.rake

@@ -0,0 +1,44 @@
+namespace :rails_contract_sync do
+  def rails_contract_sync_controller_sources
+    Dir[Rails.root.join("app/controllers/**/*.rb").to_s].each_with_object({}) do |path, h|
+      name = path.sub("#{Rails.root.join('app/controllers')}/", "").sub(/_controller\.rb\z/, "")
+      h[name] = File.read(path)
+    end
+  end
+
+  desc "Generate the static OpenAPI skeleton"
+  task generate: :environment do
+    sources = rails_contract_sync_controller_sources
+    output = RailsContractSync.configuration.output_path
+
+    result = RailsContractSync.generate(
+      route_set: Rails.application.routes,
+      controller_sources: sources,
+      output_path: output
+    )
+
+    paths = result.paths.keys
+    puts "rails_contract_sync: wrote #{output} (#{paths.size} paths from #{sources.size} controllers)"
+  end
+
+  desc "Build the contract from static analysis + captured observations"
+  task build: :environment do
+    sources = rails_contract_sync_controller_sources
+    store = RailsContractSync.configuration.observation_store
+    output = RailsContractSync.configuration.output_path
+    observations = store.all
+
+    result = RailsContractSync.build(
+      route_set: Rails.application.routes,
+      controller_sources: sources,
+      observation_store: store,
+      output_path: output
+    )
+
+    paths = result.paths.keys
+    puts "rails_contract_sync: wrote #{output} (#{paths.size} paths, #{observations.size} observations, #{sources.size} controllers)"
+    if observations.empty?
+      puts "rails_contract_sync: hint — run your test suite with RAILS_CONTRACT_SYNC=1 to capture response observations"
+    end
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: rails_contract_sync
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- dani
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: |-
+  RailsContractSync produces and maintains a single committed openapi.yml for a Rails
+  JSON API by combining static route/strong-params introspection with runtime
+  observation of real responses via a Rack middleware. The result is idempotent,
+  preserves hand-written documentation, and is serializer-agnostic.
+email:
+- danielsilas23@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rails_contract_sync.rb
+- lib/rails_contract_sync/builder.rb
+- lib/rails_contract_sync/configuration.rb
+- lib/rails_contract_sync/merger.rb
+- lib/rails_contract_sync/openapi_document.rb
+- lib/rails_contract_sync/railtie.rb
+- lib/rails_contract_sync/runtime/middleware.rb
+- lib/rails_contract_sync/runtime/observation_store.rb
+- lib/rails_contract_sync/runtime/route_resolver.rb
+- lib/rails_contract_sync/schema_inferrer.rb
+- lib/rails_contract_sync/static/params_extractor.rb
+- lib/rails_contract_sync/static/route_extractor.rb
+- lib/rails_contract_sync/version.rb
+- lib/tasks/rails_contract_sync.rake
+homepage: https://github.com/yv-soft/rails-sync
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/yv-soft/rails-sync
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.5
+specification_version: 4
+summary: Generate and maintain an OpenAPI 3.1 contract for a Rails JSON API.
+test_files: []