reqcord 0.1.0 → 0.1.1

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

data/lib/reqcord/endpoint.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Reqcord
+  class Endpoint
+    ACTION_TITLES = {
+      "index" => "List %<plural>s",
+      "show" => "Get %<singular>s",
+      "create" => "Create %<singular>s",
+      "update" => "Update %<singular>s",
+      "destroy" => "Delete %<singular>s",
+      "new" => "New %<singular>s",
+      "edit" => "Edit %<singular>s"
+    }.freeze
+
+    # One status the endpoint was seen to return, described by every body
+    # captured with that status; the first capture stands as the example.
+    Response = Struct.new(:status, :schema, :examples, keyword_init: true) do
+      def example
+        examples.first
+      end
+
+      def to_h
+        {
+          status: status,
+          schema: schema.to_a,
+          example: example.body,
+          headers: example.headers,
+          content_type: example.content_type
+        }
+      end
+    end
+
+    attr_accessor :name,
+                  :method,
+                  :path,
+                  :controller,
+                  :action,
+                  :resource,
+                  :api_version,
+                  :route_name,
+                  :also_methods,
+                  :request_examples,
+                  :response_examples
+
+    def initialize(
+      method:,
+      path:,
+      controller:,
+      action:,
+      name: nil,
+      resource: nil,
+      api_version: nil,
+      route_name: nil,
+      also_methods: [],
+      request_examples: [],
+      response_examples: []
+    )
+      @method = method.to_s.upcase
+      @path = path
+      @controller = controller
+      @action = action
+      @resource = resource || infer_resource(controller)
+      @api_version = api_version
+      @route_name = route_name
+      @also_methods = also_methods
+      @request_examples = request_examples
+      @response_examples = response_examples
+      @name = name || default_name
+    end
+
+    def http_method
+      method
+    end
+
+    def key
+      "#{method} #{path}"
+    end
+
+    # A request only counts as successful through the status it received, so
+    # the pair is what tells us; callers should not have to set it by hand.
+    def add_exchange(request:, response:)
+      request.response_status ||= response.status if request && response
+
+      add_request_example(request)
+      add_response_example(response)
+    end
+
+    def add_request_example(example)
+      return if example.nil?
+      return if request_examples.any? { |candidate| candidate.signature == example.signature }
+
+      reset_schemas!
+      request_examples << example
+    end
+
+    def add_response_example(example)
+      return if example.nil?
+      return if response_examples.any? { |candidate| candidate.signature == example.signature }
+
+      response_examples << example
+    end
+
+    def documented?
+      !request_examples.empty? || !response_examples.empty?
+    end
+
+    # cURL examples must come from a request that the application actually
+    # accepted. Error-case payloads are valuable response examples, but they
+    # must never become the endpoint's canonical request example.
+    def primary_request_example
+      successful_request_examples.first
+    end
+
+    def curl_ready?
+      !primary_request_example.nil?
+    end
+
+    def successful_request_examples
+      request_examples.select(&:successful?)
+    end
+
+    def documented_request_examples
+      successful = successful_request_examples
+      successful.empty? ? request_examples : successful
+    end
+
+    def responses_by_status
+      response_examples.group_by(&:status).sort_by { |status, _| status }.to_h
+    end
+
+    # Every status seen, each with a schema inferred from all of its bodies.
+    # Non-JSON bodies (plain text, HTML) carry no fields to describe.
+    def responses
+      responses_by_status.map do |status, examples|
+        bodies = examples.map(&:body).select { |body| body.is_a?(Hash) || body.is_a?(Array) }
+
+        Response.new(status: status, schema: Schema.infer(bodies, repetition: false), examples: examples)
+      end
+    end
+
+    # What the endpoint accepts, described only by requests the application
+    # accepted: a rejected payload says what the API refuses, not what it takes.
+    def body_schema
+      @body_schema ||= Schema.infer(successful_request_examples.map(&:body))
+    end
+
+    def query_schema
+      @query_schema ||= Schema.infer(successful_request_examples.map(&:query_params))
+    end
+
+    def path_param_schema
+      @path_param_schema ||= Schema.infer(successful_request_examples.map(&:path_params))
+    end
+
+    # A member route addresses one record: a required `:param` follows the
+    # resource segment. Optional groups (`/items(/:id)`) and globs
+    # (`/files/*path`) do not make a route a member route.
+    def member?
+      segments = required_path.split("/").reject(&:empty?)
+      singular = Support.singularize(resource.to_s)
+      index = segments.rindex { |segment| segment == resource.to_s || segment == singular }
+
+      # `resource :cart` is served by CartsController at /cart: one record,
+      # so its custom actions (/cart/checkout) address that one record.
+      return true if index && segments[index] == singular && singular != resource.to_s
+
+      candidates = index ? segments[(index + 1)..] : segments
+
+      candidates.any? { |segment| segment.start_with?(":") }
+    end
+
+    # Every dynamic segment, including globs and those inside optional groups.
+    def path_params
+      path.scan(/[:*]([a-zA-Z_][a-zA-Z0-9_]*)/).flatten
+    end
+
+    # The path with its optional groups removed: what a request must carry.
+    def required_path
+      stripped = path.to_s
+
+      stripped = stripped.gsub(/\([^()]*\)/, "") while stripped.match?(/\([^()]*\)/)
+
+      stripped
+    end
+
+    def slug
+      Support.parameterize(action.to_s.empty? ? key : action)
+    end
+
+    def to_h
+      {
+        name: name,
+        method: method,
+        path: path,
+        controller: controller,
+        action: action,
+        resource: resource,
+        api_version: api_version,
+        route_name: route_name,
+        also_methods: also_methods,
+        path_params: path_params,
+        parameters: {
+          path: path_param_schema.to_a,
+          query: query_schema.to_a,
+          body: body_schema.to_a
+        },
+        responses: responses.map(&:to_h),
+        request_examples: request_examples.map(&:to_h),
+        response_examples: response_examples.map(&:to_h)
+      }
+    end
+
+    private
+
+    def reset_schemas!
+      @body_schema = nil
+      @query_schema = nil
+      @path_param_schema = nil
+    end
+
+    def infer_resource(controller)
+      controller.to_s.split("/").last
+    end
+
+    def default_name
+      label = resource.to_s.empty? ? "resource" : resource.to_s.tr("/", " ")
+      plural = Support.titleize(Support.pluralize(label))
+      singular = Support.titleize(Support.singularize(label))
+
+      # `root to: "home#index"` is a page, not a list of homes.
+      return singular if action.to_s == "index" && !resource_in_path?
+
+      template = ACTION_TITLES[action.to_s]
+      return format(template, plural: plural, singular: singular) if template
+      return plural if action.to_s.empty?
+
+      # `post "auth/login", to: "auth#login"`: the action is the page, the
+      # controller is only where it lives — "Login", not "Login Auths".
+      return Support.titleize(action) if singular_resource? && action_in_path?
+
+      "#{Support.titleize(action)} #{member? || singular_resource? ? singular : plural}".strip
+    end
+
+    # A controller named for one thing (auth, home, health) rather than a
+    # collection (customers).
+    def singular_resource?
+      Support.pluralize(resource.to_s) != resource.to_s
+    end
+
+    def action_in_path?
+      required_path.split("/").last.to_s == action.to_s
+    end
+
+    # Whether the path itself names the resource (/customers, /cart), as
+    # opposed to a route like `/` or `/dashboard` served by some controller.
+    def resource_in_path?
+      static = required_path.split("/").reject { |segment| segment.empty? || segment.start_with?(":", "*") }
+      names = [resource.to_s, Support.singularize(resource.to_s)]
+
+      static.any? { |segment| names.include?(segment) }
+    end
+  end
+end

data/lib/reqcord/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Reqcord
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class GenerationError < Error; end
+end

data/lib/reqcord/exporters/curl.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Exporters
+    # Writes one runnable .sh file per covered endpoint. The command is always
+    # rendered from the endpoint's successful captured request when available.
+    class Curl
+      def self.call(dataset:, output_dir:, configuration:)
+        new(
+          dataset: dataset,
+          output_dir: output_dir,
+          configuration: configuration
+        ).call
+      end
+
+      def initialize(dataset:, output_dir:, configuration:)
+        @dataset = dataset
+        @output_dir = Pathname(output_dir).join("curl")
+        @configuration = configuration
+      end
+
+      def call
+        FileUtils.mkdir_p(output_dir)
+
+        dataset.resources.flat_map do |resource|
+          basenames = resource.file_basenames
+
+          resource.endpoints.filter_map do |endpoint|
+            next unless endpoint.curl_ready?
+
+            example = endpoint.primary_request_example
+
+            directory = output_dir.join(resource.slug)
+            FileUtils.mkdir_p(directory)
+
+            path = directory.join("#{basenames.fetch(endpoint)}.sh")
+            File.write(path, script(endpoint, example))
+            File.chmod(0o755, path)
+
+            path.to_s
+          end
+        end
+      end
+
+      private
+
+      attr_reader :dataset, :output_dir, :configuration
+
+      def script(endpoint, example)
+        command = Renderers::Curl.call(
+          example,
+          base_url: configuration.base_url
+        )
+
+        <<~SH
+          #!/usr/bin/env bash
+          set -euo pipefail
+
+          # #{endpoint.name}
+          # #{endpoint.method} #{endpoint.path}
+          #{command}
+        SH
+      end
+    end
+
+    register("curl", Curl)
+  end
+end