reqcord 0.2.0 → 0.3.0

data/lib/reqcord/file_value.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # How an uploaded file travels through the dataset. The capture cannot keep
+  # the bytes (and the documentation must not), so a file becomes a small
+  # marker hash — `{"$file" => "avatar.png", "content_type" => "image/png"}` —
+  # that every renderer recognizes: `--form avatar=@avatar.png` in cURL, a
+  # `file` entry in Postman, `format: binary` in OpenAPI, type `file` in the
+  # parameter tables.
+  module FileValue
+    KEY = "$file"
+
+    module_function
+
+    def marker(filename, content_type = nil)
+      { KEY => filename.to_s, "content_type" => content_type.to_s.empty? ? nil : content_type.to_s }.compact
+    end
+
+    def file?(value)
+      value.is_a?(Hash) && value.key?(KEY)
+    end
+
+    def filename(value)
+      value[KEY].to_s
+    end
+
+    def content_type(value)
+      value["content_type"]
+    end
+
+    # "avatar.png (image/png)" — how a page shows the upload.
+    def describe(value)
+      type = content_type(value)
+
+      type ? "#{filename(value)} (#{type})" : filename(value)
+    end
+
+    # True when any value, at any depth, is a file marker.
+    def any?(value)
+      case value
+      when Hash then file?(value) || value.values.any? { |nested| any?(nested) }
+      when Array then value.any? { |item| any?(item) }
+      else false
+      end
+    end
+
+    # Returns a copy of `value` with every marker replaced by the block's
+    # result; used to render the body for a reader.
+    def map(value, &block)
+      case value
+      when Hash
+        return yield(value) if file?(value)
+
+        value.transform_values { |nested| map(nested, &block) }
+      when Array
+        value.map { |item| map(item, &block) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/reqcord/generator.rb

@@ -11,11 +11,13 @@ module Reqcord
   class Generator
     def self.call(
       resources: [],
-      version: nil
+      version: nil,
+      configuration: Reqcord.configuration
     )
       new(
         resources: resources,
-        version: version
+        version: version,
+        configuration: configuration
       ).call
     end
 
@@ -102,7 +104,7 @@ module Reqcord
         endpoints[[route, route.method]] = route.endpoint unless route.any_verb?
       end
 
-      exchanges.each do |raw_exchange|
+      ordered_exchanges(exchanges).each do |raw_exchange|
         sanitized =
           Sanitizers::Sanitizer.call(
             raw_exchange,
@@ -309,6 +311,18 @@ module Reqcord
       raise GenerationError, "could not match #{method} #{path} against the route table: #{e.message}"
     end
 
+    # Test suites run in random order, and "the first example captured" is
+    # what every page leads with. Ordering by where the test lives makes the
+    # output a function of the code, so regenerating never produces a diff
+    # by itself. Requests inside one test keep their execution order.
+    def ordered_exchanges(exchanges)
+      exchanges.each_with_index.sort_by do |exchange, index|
+        source = exchange["source"] || {}
+
+        [source["file"].to_s, source["line"].to_i, source["test"].to_s, index]
+      end.map(&:first)
+    end
+
     def attach_exchange(endpoint, exchange)
       request_data = exchange.fetch("request")
       response_data = exchange.fetch("response")

data/lib/reqcord/renderers/curl.rb

@@ -22,10 +22,14 @@ module Reqcord
         ]
 
         request.headers.each do |key, value|
+          next if key.to_s.casecmp?("Content-Type") && Payload.multipart?(request)
+
           parts << %(--header "#{key}: #{escape_header(value)}")
         end
 
-        parts << data_argument if request.body?
+        if request.body?
+          parts.concat(Payload.multipart?(request) ? form_arguments : [data_argument])
+        end
 
         parts.join(" \\\n  ")
       end
@@ -42,6 +46,23 @@ module Reqcord
         "--data '#{shell_single_quote(Payload.raw_body(request))}'"
       end
 
+      # One --form per part; a file is `@name`, relative to where the reader
+      # runs the command. curl sets the multipart Content-Type itself, so a
+      # captured one would only get in the way.
+      def form_arguments
+        Payload.form_pairs(request).map do |key, value|
+          part =
+            if FileValue.file?(value)
+              type = FileValue.content_type(value)
+              "#{key}=@#{FileValue.filename(value)}#{type ? ";type=#{type}" : ''}"
+            else
+              "#{key}=#{value}"
+            end
+
+          "--form '#{shell_single_quote(part)}'"
+        end
+      end
+
       def shell_single_quote(value)
         value.to_s.gsub("'", %q('"'"'))
       end

data/lib/reqcord/renderers/payload.rb

@@ -3,9 +3,9 @@
 module Reqcord
   module Renderers
     # The wire-level decisions every output format has to agree on: whether a
-    # request is JSON, how a nested query flattens, what the body looks like
-    # as text. cURL, Postman and any later exporter read these, never their
-    # own copy.
+    # request is JSON, a form or a multipart upload, how a nested query
+    # flattens, what the body looks like as text. cURL, Postman and any later
+    # exporter read these, never their own copy.
     module Payload
       module_function
 
@@ -16,18 +16,26 @@ module Reqcord
           end
       end
 
+      # A body with a file in it can only travel as multipart/form-data,
+      # whatever the captured content type says.
+      def multipart?(request)
+        request.content_type.to_s.include?("multipart/form-data") ||
+          FileValue.any?(request.body)
+      end
+
       # Rails bracket notation: { filter: { status: "a" }, ids: [1, 2] } becomes
-      # [["filter[status]", "a"], ["ids[]", 1], ["ids[]", 2]].
+      # [["filter[status]", "a"], ["ids[]", 1], ["ids[]", 2]]. A file marker is
+      # a leaf: the pair's value is the marker itself.
       def flatten_query(hash, prefix = nil)
         hash.flat_map do |key, value|
           current = prefix ? "#{prefix}[#{key}]" : key.to_s
 
           case value
           when Hash
-            flatten_query(value, current)
+            FileValue.file?(value) ? [[current, value]] : flatten_query(value, current)
           when Array
             value.flat_map do |item|
-              if item.is_a?(Hash)
+              if item.is_a?(Hash) && !FileValue.file?(item)
                 flatten_query(item, "#{current}[]")
               else
                 [["#{current}[]", item]]
@@ -54,7 +62,8 @@ module Reqcord
       end
 
       # The body as it goes on the wire: pretty JSON, a form string, or the
-      # raw text the test sent.
+      # raw text the test sent. Multipart has no single string; callers use
+      # form_pairs and render each part.
       def raw_body(request)
         if json?(request)
           JSON.pretty_generate(request.body)
@@ -64,6 +73,15 @@ module Reqcord
           request.body.to_s
         end
       end
+
+      # The body as a reader should see it: file markers replaced by their
+      # description ("avatar.png (image/png)"), or by whatever the block
+      # returns.
+      def display_body(request, &block)
+        block ||= FileValue.method(:describe)
+
+        FileValue.map(request.body, &block)
+      end
     end
   end
 end

data/lib/reqcord/route_collector.rb

@@ -216,7 +216,16 @@ module Reqcord
       prefixes = Array(prefix).map(&:to_s).reject(&:empty?)
       return true if prefixes.empty?
 
-      prefixes.any? { |candidate| path.start_with?(candidate) }
+      # Segment-wise: `/api` covers `/api`, `/api/v1/…` and `/api(/:id)`, not
+      # `/api-docs`.
+      prefixes.any? do |candidate|
+        candidate = candidate.chomp("/")
+        next true if candidate.empty?
+        next false unless path.start_with?(candidate)
+
+        rest = path.delete_prefix(candidate)
+        rest.empty? || rest.start_with?("/", "(")
+      end
     end
 
     # `RESOURCE=customers`, `RESOURCE=cart` (a singular resource is served by

data/lib/reqcord/schema.rb

@@ -110,7 +110,7 @@ module Reqcord
           )
 
           field.types |= [type_of(value)]
-          field.values |= [value] unless value.nil? || value.is_a?(Hash) || value.is_a?(Array)
+          field.values |= [example_value(value)] unless value.nil? || value.is_a?(Array) || (value.is_a?(Hash) && !FileValue.file?(value))
           field.present_count += 1
         end
       end
@@ -159,6 +159,9 @@ module Reqcord
     def flatten(value, prefix = nil, result = {})
       case value
       when Hash
+        # An upload is one field of type "file", not an object with two keys.
+        return result[prefix] = value if FileValue.file?(value) && prefix
+
         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.
@@ -171,7 +174,14 @@ module Reqcord
       result
     end
 
+    # The file name stands for an upload in the Values column.
+    def example_value(value)
+      FileValue.file?(value) ? FileValue.filename(value) : value
+    end
+
     def type_of(value)
+      return "file" if FileValue.file?(value)
+
       case value
       when String then "string"
       when Integer then "integer"

data/lib/reqcord/version.rb

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

data/lib/reqcord.rb

@@ -11,6 +11,7 @@ require "pathname"
 require_relative "reqcord/version"
 require_relative "reqcord/errors"
 require_relative "reqcord/support"
+require_relative "reqcord/file_value"
 require_relative "reqcord/configuration"
 
 require_relative "reqcord/request_example"
@@ -34,6 +35,7 @@ require_relative "reqcord/exporters/markdown"
 require_relative "reqcord/exporters/postman"
 require_relative "reqcord/exporters/openapi"
 require_relative "reqcord/generator"
+require_relative "reqcord/check"
 require_relative "reqcord/web"
 
 require_relative "reqcord/railtie" if defined?(Rails::Railtie)

data/lib/tasks/reqcord.rake

@@ -109,6 +109,29 @@ namespace :reqcord do
     puts "Output: #{Reqcord.configuration.output_directory}"
   end
 
+  desc "Fail when the committed documentation is behind the tests"
+  task check: :environment do
+    Reqcord.reload_configuration!
+
+    result =
+      Reqcord::Check.call(
+        resources: ENV.fetch("RESOURCE", "").split(",").map(&:strip).reject(&:empty?),
+        version: ENV["VERSION"].to_s.strip.then { |value| value.empty? ? nil : value }
+      )
+
+    output = Reqcord.configuration.output_directory
+
+    if result.clean?
+      puts "Reqcord: #{output} is up to date."
+    else
+      puts "Reqcord: #{output} is out of date."
+      puts
+      result.lines.each { |line| puts "  #{line}" }
+      puts
+      abort "Run `bin/rails reqcord:generate` and commit the result."
+    end
+  end
+
   desc "List the routes Reqcord would document"
   task routes: :environment do
     routes =

data/reqcord.gemspec

@@ -20,7 +20,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.2"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "#{spec.homepage}/tree/master/docs"
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["rubygems_mfa_required"] = "true"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reqcord
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ahmet Saridogan
@@ -145,7 +145,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/architecture.md
+- docs/capture.md
 - docs/configuration.md
+- docs/exporters.md
+- docs/getting-started.md
+- docs/route-coverage.md
+- docs/troubleshooting.md
+- docs/web.md
 - examples/reqcord.yml
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_7.2.gemfile
@@ -158,6 +165,7 @@ files:
 - lib/reqcord/capture/minitest_context.rb
 - lib/reqcord/capture/rspec_context.rb
 - lib/reqcord/capture/test_context.rb
+- lib/reqcord/check.rb
 - lib/reqcord/configuration.rb
 - lib/reqcord/dataset.rb
 - lib/reqcord/endpoint.rb
@@ -167,6 +175,7 @@ files:
 - lib/reqcord/exporters/markdown.rb
 - lib/reqcord/exporters/openapi.rb
 - lib/reqcord/exporters/postman.rb
+- lib/reqcord/file_value.rb
 - lib/reqcord/generator.rb
 - lib/reqcord/railtie.rb
 - lib/reqcord/renderers/curl.rb
@@ -186,7 +195,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ahmetsaridogan/reqcord
-  changelog_uri: https://github.com/ahmetsaridogan/reqcord
+  changelog_uri: https://github.com/ahmetsaridogan/reqcord/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/ahmetsaridogan/reqcord/tree/master/docs
   source_code_uri: https://github.com/ahmetsaridogan/reqcord
   rubygems_mfa_required: 'true'
 rdoc_options: []