reqcord 0.1.0 → 0.1.2

data/lib/reqcord/schema.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # Describes what an endpoint accepts, inferred from the requests that
+  # actually worked. One test sends status "active", another "passive", a third
+  # sends "inactive" and gets a 422: the documentation should say the field
+  # takes "active" | "passive", not list three requests.
+  class Schema
+    # Beyond this many distinct values a field is an open set, not a choice.
+    ENUM_LIMIT = 6
+
+    Field = Struct.new(:path, :types, :values, :present_count, :total_count, :repetition, keyword_init: true) do
+      def type
+        types.to_a.sort.join(" | ")
+      end
+
+      # A field missing from a working request cannot be required.
+      def required?
+        present_count == total_count
+      end
+
+      # Telling a closed set from free text: either a value came back in more
+      # than one request, or every value reads like a token ("active"), not
+      # like content ("Ada Lovelace", "ada@example.com").
+      def enum?
+        return false unless values.size.between?(2, ENUM_LIMIT)
+        return false unless values.all? { |value| scalar?(value) }
+        return false if identifier?
+
+        # Repetition only counts among the requests that carried the field:
+        # two requests, two different values, is not a set.
+        return true if repetition && values.size < present_count
+
+        values.all? { |value| token?(value) }
+      end
+
+      def example
+        values.first
+      end
+
+      # Test order is not stable, so a listed set must be ordered by something
+      # that is.
+      def listed_values
+        values.sort_by { |value| [value.to_s, value.class.name] }
+      end
+
+      def to_h
+        {
+          path: path,
+          type: type,
+          required: required?,
+          values: listed_values
+        }
+      end
+
+      private
+
+      def scalar?(value)
+        value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+      end
+
+      # Every record has a different one, so listing the ones a test happened
+      # to use would read as if those were the only allowed values.
+      def identifier?
+        path.to_s.split(/[.\[\]]/).last.to_s.match?(/\A(id|uuid|.*_id|.*_uuid|.*_key|token|slug)\z/i)
+      end
+
+      # A word, not content: "active", "pending_review", "USD". Digits and
+      # dashes usually mean a generated value ("e-00056197", "safari-859f04").
+      def token?(value)
+        case value
+        when true, false then true
+        when String then value.match?(/\A[a-z][a-z_]*\z/) || value.match?(/\A[A-Z_]{2,}\z/)
+        else false
+        end
+      end
+    end
+
+    # `payloads` are request bodies, query hashes or path parameter hashes from
+    # successful captures. With `repetition: true` a value seen in more than
+    # one payload marks a closed set — right for what tests *send*, wrong for
+    # what an application *returns*, where fixtures repeat by nature; response
+    # bodies are inferred with `repetition: false`, so only token-like values
+    # ("open", "done") are listed as a set.
+    def self.infer(payloads, repetition: true)
+      new(payloads, repetition: repetition).call
+    end
+
+    # Empty payloads are kept: a request that was accepted without any
+    # parameters is the proof that every parameter is optional.
+    def initialize(payloads, repetition: true)
+      @payloads = Array(payloads)
+      @repetition = repetition
+    end
+
+    def call
+      return self.class.empty if @payloads.empty?
+
+      fields = {}
+
+      @payloads.each do |payload|
+        flatten(payload).each do |path, value|
+          field = fields[path] ||= Field.new(
+            path: path,
+            types: [],
+            values: [],
+            present_count: 0,
+            total_count: @payloads.size,
+            repetition: @repetition
+          )
+
+          field.types |= [type_of(value)]
+          field.values |= [value] unless value.nil? || value.is_a?(Hash) || value.is_a?(Array)
+          field.present_count += 1
+        end
+      end
+
+      Result.new(fields.values)
+    end
+
+    def self.empty
+      Result.new([])
+    end
+
+    # The inferred description of one payload shape.
+    class Result
+      include Enumerable
+
+      attr_reader :fields
+
+      def initialize(fields)
+        @fields = fields
+      end
+
+      def each(&block)
+        fields.each(&block)
+      end
+
+      def empty?
+        fields.empty?
+      end
+
+      def size
+        fields.size
+      end
+
+      def [](path)
+        fields.find { |field| field.path == path }
+      end
+
+      def to_a
+        fields.map(&:to_h)
+      end
+    end
+
+    private
+
+    # { "customer" => { "tags" => ["a"] } } -> { "customer.tags[]" => "a" }
+    def flatten(value, prefix = nil, result = {})
+      case value
+      when Hash
+        value.each { |key, nested| flatten(nested, prefix ? "#{prefix}.#{key}" : key.to_s, result) }
+      when Array
+        # An empty array still tells the reader the field is a list.
+        result[prefix] = [] if value.empty? && prefix
+        value.each { |item| flatten(item, "#{prefix}[]", result) }
+      else
+        result[prefix] = value if prefix
+      end
+
+      result
+    end
+
+    def type_of(value)
+      case value
+      when String then "string"
+      when Integer then "integer"
+      when Float then "number"
+      when true, false then "boolean"
+      when nil then "null"
+      when Array then "array"
+      when Hash then "object"
+      else value.class.name.downcase
+      end
+    end
+  end
+end

data/lib/reqcord/support.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # Minimal inflection helpers. ActiveSupport is used when it is available so
+  # that generated titles match the host application's inflections.
+  module Support
+    module_function
+
+    def underscore(value)
+      string = value.to_s.dup
+      return ActiveSupport::Inflector.underscore(string) if defined?(ActiveSupport::Inflector)
+
+      string.gsub("::", "/")
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr("-", "_")
+            .downcase
+    end
+
+    def humanize(value)
+      underscore(value).tr("_", " ").strip
+    end
+
+    def titleize(value)
+      humanize(value).split(/\s+/).map { |word| word.empty? ? word : word[0].upcase + word[1..] }.join(" ")
+    end
+
+    def singularize(value)
+      string = value.to_s
+      return ActiveSupport::Inflector.singularize(string) if defined?(ActiveSupport::Inflector)
+
+      case string
+      when /ies\z/i then string.sub(/ies\z/i, "y")
+      when /(ss|sh|ch|x|z)es\z/i then string.sub(/es\z/i, "")
+      when /ss\z/i then string
+      when /s\z/i then string.sub(/s\z/i, "")
+      else string
+      end
+    end
+
+    def pluralize(value)
+      string = value.to_s
+      return ActiveSupport::Inflector.pluralize(string) if defined?(ActiveSupport::Inflector)
+
+      case string
+      when /(ss|sh|ch|x|z)\z/i then "#{string}es"
+      when /[^aeiou]y\z/i then string.sub(/y\z/i, "ies")
+      # Already plural, as resource names usually are.
+      when /s\z/i then string
+      else "#{string}s"
+      end
+    end
+
+    def parameterize(value)
+      underscore(value).gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+  end
+end

data/lib/reqcord/version.rb

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

data/lib/reqcord.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "time"
+require "uri"
+require "rack/utils"
+require "fileutils"
+require "pathname"
+
+require_relative "reqcord/version"
+require_relative "reqcord/errors"
+require_relative "reqcord/support"
+require_relative "reqcord/configuration"
+
+require_relative "reqcord/request_example"
+require_relative "reqcord/response_example"
+require_relative "reqcord/schema"
+require_relative "reqcord/endpoint"
+require_relative "reqcord/dataset"
+
+require_relative "reqcord/route_collector"
+
+require_relative "reqcord/capture"
+require_relative "reqcord/capture/test_context"
+require_relative "reqcord/capture/collector"
+
+require_relative "reqcord/sanitizers/sanitizer"
+require_relative "reqcord/renderers/payload"
+require_relative "reqcord/renderers/curl"
+require_relative "reqcord/exporters"
+require_relative "reqcord/exporters/curl"
+require_relative "reqcord/exporters/markdown"
+require_relative "reqcord/exporters/postman"
+require_relative "reqcord/generator"
+
+require_relative "reqcord/railtie" if defined?(Rails::Railtie)
+
+module Reqcord
+  class << self
+    attr_writer :root
+
+    def root
+      return @root if @root
+
+      if defined?(Rails) &&
+         Rails.respond_to?(:root) &&
+         Rails.root
+
+        Rails.root
+      else
+        Pathname(Dir.pwd)
+      end
+    end
+
+    def configuration
+      @configuration ||=
+        Configuration.load(
+          root: root
+        )
+    end
+
+    def reload_configuration!
+      @configuration =
+        Configuration.load(
+          root: root
+        )
+    end
+
+    def log(message)
+      $stdout.puts("[reqcord] #{message}")
+    end
+
+    def warn(message)
+      $stderr.puts("[reqcord] #{message}")
+    end
+  end
+end

data/lib/tasks/reqcord.rake

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+namespace :reqcord do
+  desc "Create reqcord.yml"
+  task init: :environment do
+    path = Rails.root.join("reqcord.yml")
+
+    if path.exist?
+      puts "reqcord.yml already exists."
+      next
+    end
+
+    content = <<~YAML
+      version: 1
+
+      test:
+        framework: minitest
+        command: bin/rails test
+
+      routes:
+        prefix: /api
+
+      output:
+        directory: docs/api
+        include_uncovered: false
+
+      exporters:
+        - curl
+        - markdown
+        - postman
+
+      variables:
+        base_url: http://localhost:3000
+
+      sanitize:
+        headers:
+          Authorization: "Bearer {{token}}"
+          X-Api-Key: "{{api_key}}"
+    YAML
+
+    File.write(path, content)
+
+    FileUtils.mkdir_p(
+      Rails.root.join("docs", "api")
+    )
+
+    puts "Created reqcord.yml"
+    puts "Created docs/api/"
+  end
+
+  desc "Generate API documentation from Rails integration tests"
+  task generate: :environment do
+    resources =
+      ENV.fetch("RESOURCE", "")
+         .split(",")
+         .map(&:strip)
+         .reject(&:empty?)
+
+    version = ENV["VERSION"]&.strip
+
+    version = nil if version&.empty?
+
+    Reqcord.reload_configuration!
+
+    dataset =
+      Reqcord::Generator.call(
+        resources: resources,
+        version: version
+      )
+
+    documented = dataset.curl_ready_endpoints.size
+
+    puts
+    puts "Reqcord generated API documentation."
+    puts "Endpoints: #{dataset.endpoints.size} (#{documented} with successful 2xx request)"
+    puts "Output: #{Reqcord.configuration.output_directory}"
+  end
+
+  desc "List the routes Reqcord would document"
+  task routes: :environment do
+    routes =
+      Reqcord::RouteCollector.call(
+        resources: ENV.fetch("RESOURCE", "").split(",").map(&:strip).reject(&:empty?),
+        version: ENV["VERSION"],
+        prefix: Reqcord.configuration.route_prefix
+      )
+
+    if routes.empty?
+      puts "No routes matched the configured prefix."
+      next
+    end
+
+    width = routes.map { |route| route.method.length }.max
+
+    routes.each do |route|
+      puts format("%-#{width}s %s  (%s#%s)", route.method, route.path, route.controller, route.action)
+    end
+  end
+end

data/reqcord.gemspec

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "lib/reqcord/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "reqcord"
+  spec.version = Reqcord::VERSION
+
+  spec.authors = ["Ahmet Saridogan"]
+
+  spec.summary = "Generate living API documentation from Rails integration tests"
+  spec.description = <<~DESC
+    Reqcord captures HTTP requests and responses from Rails integration tests
+    and generates static API documentation with executable cURL examples.
+  DESC
+
+  spec.homepage = "https://github.com/ahmetsaridogan/reqcord"
+  spec.license = "MIT"
+
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # What ships: lib/, the rake task, the docs and the annotated config. Tests,
+  # CI files and the example apps (with their generated output) stay on
+  # GitHub — `git ls-files` runs against the checkout, so `gem build` must be
+  # run from the repository root.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |file|
+      file.start_with?(
+        "test/",
+        "spec/",
+        "features/",
+        "examples/",
+        ".git",
+        ".github/"
+      ) || file.end_with?(".gem")
+    end + ["examples/reqcord.yml"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Rails 7.1 through 8.x; every version is exercised in CI (see gemfiles/).
+  spec.add_dependency "railties", ">= 7.1", "< 9.0"
+  spec.add_dependency "actionpack", ">= 7.1", "< 9.0"
+
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "rake"
+
+  # The test suite serves the dummy app over HTTP to replay the generated
+  # cURL and Postman collection, validates the collection against the
+  # Postman schema, and runs the RSpec example apps.
+  spec.add_development_dependency "puma"
+  spec.add_development_dependency "json-schema"
+  spec.add_development_dependency "rspec-core"
+  spec.add_development_dependency "rspec-expectations"
+end

metadata

@@ -1,14 +1,138 @@
 --- !ruby/object:Gem::Specification
 name: reqcord
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Ahmet Saridogan
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Reqcord captures HTTP requests and responses from Rails integration tests
   and generates static API documentation with executable cURL examples.
@@ -16,14 +140,52 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
 - README.md
+- Rakefile
+- docs/configuration.md
+- examples/reqcord.yml
+- gemfiles/rails_7.1.gemfile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/reqcord.rb
+- lib/reqcord/capture.rb
+- lib/reqcord/capture/collector.rb
+- lib/reqcord/capture/integration_patch.rb
+- lib/reqcord/capture/minitest_context.rb
+- lib/reqcord/capture/rspec_context.rb
+- lib/reqcord/capture/test_context.rb
+- lib/reqcord/configuration.rb
+- lib/reqcord/dataset.rb
+- lib/reqcord/endpoint.rb
+- lib/reqcord/errors.rb
+- lib/reqcord/exporters.rb
+- lib/reqcord/exporters/curl.rb
+- lib/reqcord/exporters/markdown.rb
+- lib/reqcord/exporters/postman.rb
+- lib/reqcord/generator.rb
+- lib/reqcord/railtie.rb
+- lib/reqcord/renderers/curl.rb
+- lib/reqcord/renderers/payload.rb
+- lib/reqcord/request_example.rb
+- lib/reqcord/response_example.rb
+- lib/reqcord/route_collector.rb
+- lib/reqcord/sanitizers/sanitizer.rb
+- lib/reqcord/schema.rb
+- lib/reqcord/support.rb
+- lib/reqcord/version.rb
+- lib/tasks/reqcord.rake
+- reqcord.gemspec
 homepage: https://github.com/ahmetsaridogan/reqcord
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ahmetsaridogan/reqcord
+  changelog_uri: https://github.com/ahmetsaridogan/reqcord
   source_code_uri: https://github.com/ahmetsaridogan/reqcord
-  changelog_uri: https://github.com/ahmetsaridogan/reqcord/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: