reqcord 0.1.0 → 0.1.2

data/lib/reqcord/capture/minitest_context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    module MinitestContext
+      def before_setup
+        file, line = reqcord_source_location
+
+        TestContext.current = {
+          test: name,
+          suite: self.class.name,
+          file: file,
+          line: line
+        }
+
+        super
+      end
+
+      def after_teardown
+        super
+      ensure
+        TestContext.clear
+      end
+
+      private
+
+      def reqcord_source_location
+        method(name).source_location
+      rescue NameError
+        [nil, nil]
+      end
+    end
+  end
+end

data/lib/reqcord/capture/rspec_context.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    # The RSpec counterpart of MinitestContext: names captured examples after
+    # the request spec that produced them.
+    module RSpecContext
+      class << self
+        def install!(rspec = ::RSpec)
+          return false if @installed
+
+          rspec.configure do |config|
+            config.before(:each) do |example|
+              TestContext.current = RSpecContext.context_for(example)
+            end
+
+            config.after(:each) do
+              TestContext.clear
+            end
+          end
+
+          @installed = true
+        end
+
+        def installed?
+          @installed == true
+        end
+
+        def context_for(example)
+          metadata = example.metadata
+
+          {
+            test: metadata[:description],
+            suite: metadata[:example_group][:description],
+            file: metadata[:file_path],
+            line: metadata[:line_number]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/capture/test_context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    # The test that is currently running, kept per thread so parallel runners
+    # do not attribute an exchange to the wrong test.
+    module TestContext
+      THREAD_KEY = :reqcord_test_context
+
+      class << self
+        def current
+          Thread.current[THREAD_KEY] || {}
+        end
+
+        def current=(value)
+          Thread.current[THREAD_KEY] = value
+        end
+
+        def clear
+          Thread.current[THREAD_KEY] = nil
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/capture.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # Capture runs inside the test process and writes to a file the generator
+  # reads afterwards. Both variables are set by `reqcord:generate`, so an
+  # ordinary test run patches nothing and writes nothing.
+  module Capture
+    class << self
+      def enabled?
+        ENV["REQCORD_CAPTURE"] == "1" &&
+          capture_file
+      end
+
+      def capture_file
+        ENV["REQCORD_CAPTURE_FILE"]
+      end
+    end
+  end
+end

data/lib/reqcord/configuration.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Reqcord
+  class Configuration
+    DEFAULTS = {
+      "version" => 1,
+
+      # No default command: with neither `command` nor `paths` the generator
+      # falls back to `bin/rails test`, and `paths` alone must be able to win.
+      "test" => {
+        "framework" => "minitest"
+      },
+
+      "routes" => {
+        "prefix" => "/api"
+      },
+
+      "output" => {
+        "directory" => "docs/api",
+
+        # A route no test exercised is reported in the index; writing a page
+        # with nothing on it only adds noise.
+        "include_uncovered" => false
+      },
+
+      "exporters" => %w[curl markdown postman],
+
+      "variables" => {
+        "base_url" => "http://localhost:3000"
+      },
+
+      "sanitize" => {
+        "headers" => {
+          "Authorization" => "Bearer {{token}}",
+          "X-Api-Key" => "{{api_key}}"
+        },
+
+        "body" => {
+          "password" => "{{password}}",
+          "password_confirmation" => "{{password}}",
+          "token" => "{{token}}",
+          "access_token" => "{{token}}",
+          "refresh_token" => "{{token}}",
+          "api_key" => "{{api_key}}",
+          "secret" => "{{secret}}",
+          "client_secret" => "{{secret}}"
+        }
+      }
+    }.freeze
+
+    # Headers that describe the transport rather than the API. A documented
+    # cURL that carries them is worse than one that does not: `Host` alone
+    # would send the reader's request to the wrong virtual host.
+    NOISY_HEADERS = %w[
+      host
+      user-agent
+      connection
+      version
+      remote-addr
+      accept-encoding
+      cache-control
+      content-length
+      date
+      etag
+      server-timing
+      transfer-encoding
+      vary
+      x-content-type-options
+      x-download-options
+      x-frame-options
+      x-permitted-cross-domain-policies
+      x-request-id
+      x-runtime
+      x-xss-protection
+      referrer-policy
+    ].freeze
+
+    attr_reader :data, :root
+
+    def self.load(root:)
+      new(root: root).load
+    end
+
+    def initialize(root:)
+      @root = Pathname(root)
+      @data = deep_dup(DEFAULTS)
+    end
+
+    def load
+      path = root.join("reqcord.yml")
+
+      return self unless path.exist?
+
+      raw = YAML.safe_load_file(
+        path,
+        aliases: false
+      ) || {}
+
+      unless raw.is_a?(Hash)
+        raise ConfigurationError,
+              "reqcord.yml must contain a YAML object"
+      end
+
+      @data = deep_merge(@data, stringify_keys(raw))
+
+      self
+    end
+
+    def test_framework
+      ENV["REQCORD_TEST_FRAMEWORK"] ||
+        data.dig("test", "framework")
+    end
+
+    # An explicit command wins; nil means "build one from test.paths".
+    def test_command
+      value = ENV["REQCORD_TEST_COMMAND"] || data.dig("test", "command")
+
+      value.to_s.empty? ? nil : value.to_s
+    end
+
+    # Directories, files or globs the suite lives in; Reqcord picks the runner.
+    def test_paths
+      Array(data.dig("test", "paths")).map(&:to_s)
+    end
+
+    def route_prefix
+      data.dig("routes", "prefix")
+    end
+
+    def output_directory
+      value =
+        ENV["REQCORD_OUTPUT"] ||
+        data.dig("output", "directory") ||
+        "docs/api"
+
+      root.join(value)
+    end
+
+    def include_uncovered?
+      data.dig("output", "include_uncovered") == true
+    end
+
+    def exporters
+      Array(data["exporters"]).map(&:to_s)
+    end
+
+    def variables
+      (data["variables"] || {}).merge(
+        "base_url" => base_url
+      )
+    end
+
+    def base_url
+      ENV["REQCORD_BASE_URL"] ||
+        data.dig("variables", "base_url") ||
+        "http://localhost:3000"
+    end
+
+    def sanitized_headers
+      data.dig("sanitize", "headers") || {}
+    end
+
+    def sanitized_body_keys
+      data.dig("sanitize", "body") || {}
+    end
+
+    def noisy_header?(key)
+      NOISY_HEADERS.include?(key.to_s.downcase)
+    end
+
+    private
+
+    def deep_merge(left, right)
+      left.merge(right) do |_key, old_value, new_value|
+        if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+          deep_merge(old_value, new_value)
+        else
+          new_value
+        end
+      end
+    end
+
+    def deep_dup(value)
+      Marshal.load(Marshal.dump(value))
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.to_s] =
+          if value.is_a?(Hash)
+            stringify_keys(value)
+          else
+            value
+          end
+      end
+    end
+  end
+end

data/lib/reqcord/dataset.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Reqcord
+  class Dataset
+    # 2: endpoints carry `parameters` (path/query/body schemas), `responses`
+    # (one schema + example per status), `route_name` and `also_methods`.
+    SCHEMA_VERSION = 2
+
+    # An endpoint page must not overwrite the resource or dataset pages.
+    RESERVED_BASENAMES = {
+      "index" => "list",
+      "readme" => "readme-endpoint",
+      "dataset" => "dataset-endpoint"
+    }.freeze
+
+    # Endpoints served by one controller, as the exporters walk them. Keyed by
+    # the full controller path so `admin/users` and `api/v1/users` stay apart.
+    class Resource
+      attr_reader :name, :endpoints
+
+      def initialize(name)
+        @name = name.to_s
+        @endpoints = []
+      end
+
+      def segments
+        name.split("/")
+      end
+
+      def short_name
+        segments.last.to_s
+      end
+
+      def namespace
+        segments[0...-1].join("/")
+      end
+
+      # Nested directories / folders: api/v2/customers.
+      def slug
+        segments.map { |segment| Support.parameterize(segment) }.join("/")
+      end
+
+      def title
+        Support.titleize(short_name)
+      end
+
+      def api_versions
+        endpoints.map(&:api_version).compact.uniq.sort
+      end
+
+      # One stable file name per endpoint. Two routes sharing an action
+      # (`match … via: [:get, :post]`) are told apart by verb, never by a
+      # bare counter.
+      def file_basenames
+        bases = endpoints.to_h { |endpoint| [endpoint, RESERVED_BASENAMES.fetch(endpoint.slug, endpoint.slug)] }
+        shared = bases.values.tally
+        seen = Hash.new(0)
+
+        bases.to_h do |endpoint, base|
+          basename = shared[base] > 1 ? "#{base}-#{endpoint.method.downcase}" : base
+          seen[basename] += 1
+          basename = "#{basename}-#{seen[basename]}" if seen[basename] > 1
+
+          [endpoint, basename]
+        end
+      end
+    end
+
+    # Rails emits both PATCH and PUT for `update`; one page serves both. The
+    # verb a test used wins, PATCH when neither or both did.
+    def self.fold_method_twins(endpoints)
+      groups = endpoints.group_by { |endpoint| [endpoint.path, endpoint.controller, endpoint.action] }
+
+      endpoints.filter_map do |endpoint|
+        next endpoint unless %w[PATCH PUT].include?(endpoint.method)
+
+        twins = groups.fetch([endpoint.path, endpoint.controller, endpoint.action])
+                      .select { |candidate| %w[PATCH PUT].include?(candidate.method) }
+
+        next endpoint unless twins.size == 2
+
+        primary = twins.find(&:curl_ready?) || twins.find { |candidate| candidate.method == "PATCH" }
+
+        next nil unless endpoint.equal?(primary)
+
+        twin = twins.find { |candidate| !candidate.equal?(primary) }
+        twin.request_examples.each { |example| primary.add_request_example(example) }
+        twin.response_examples.each { |example| primary.add_response_example(example) }
+        primary.also_methods = [twin.method]
+
+        primary
+      end
+    end
+
+    attr_reader :schema_version, :endpoints
+
+    def initialize(
+      schema_version: SCHEMA_VERSION,
+      endpoints: []
+    )
+      @schema_version = schema_version
+      @endpoints = endpoints
+    end
+
+    def add(endpoint)
+      endpoints << endpoint
+    end
+
+    def empty?
+      endpoints.empty?
+    end
+
+    # Endpoints for which Reqcord captured at least one successful 2xx
+    # request. These are safe to use as canonical cURL/documentation examples.
+    def curl_ready_endpoints
+      endpoints.select(&:curl_ready?)
+    end
+
+    # Backwards-compatible alias for callers that previously asked for
+    # documented endpoints. In the cURL-first MVP, documented means a
+    # successful request was actually captured.
+    def documented_endpoints
+      curl_ready_endpoints
+    end
+
+    def uncovered_endpoints
+      endpoints.reject(&:curl_ready?)
+    end
+
+    def resources
+      grouped = endpoints.each_with_object({}) do |endpoint, memo|
+        key = endpoint.controller.to_s.empty? ? endpoint.resource : endpoint.controller
+        resource = memo[key] ||= Resource.new(key)
+        resource.endpoints << endpoint
+      end
+
+      grouped.values.sort_by(&:name).each do |resource|
+        resource.endpoints.sort_by! { |endpoint| [endpoint.path, endpoint.method] }
+      end
+    end
+
+    def to_h
+      {
+        schema_version: schema_version,
+        generated_at: Time.now.utc.iso8601,
+        endpoints: curl_ready_endpoints.map(&:to_h),
+        uncovered_routes: uncovered_endpoints.map do |endpoint|
+          {
+            name: endpoint.name,
+            method: endpoint.method,
+            path: endpoint.path,
+            controller: endpoint.controller,
+            action: endpoint.action,
+            resource: endpoint.resource,
+            api_version: endpoint.api_version,
+            route_name: endpoint.route_name,
+            also_methods: endpoint.also_methods
+          }
+        end
+      }
+    end
+
+    def write(path)
+      path = Pathname(path)
+
+      FileUtils.mkdir_p(path.dirname)
+
+      File.write(
+        path,
+        JSON.pretty_generate(to_h)
+      )
+
+      path.to_s
+    end
+  end
+end