reqcord 0.1.0 → 0.1.2

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

data/lib/reqcord/exporters/markdown.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Exporters
+    class Markdown
+      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)
+        @configuration = configuration
+      end
+
+      # Returns every written path.
+      def call
+        FileUtils.mkdir_p(output_dir)
+
+        written = [write(output_dir.join("README.md"), index_document)]
+
+        written_resources.each do |resource|
+          directory = output_dir.join(resource.slug)
+
+          FileUtils.mkdir_p(directory)
+
+          written << write(
+            directory.join("index.md"),
+            resource_document(resource)
+          )
+
+          filenames(resource).each do |endpoint, filename|
+            next unless documented?(endpoint)
+
+            written << write(
+              directory.join(filename),
+              endpoint_document(resource, endpoint)
+            )
+          end
+        end
+
+        written
+      end
+
+      private
+
+      attr_reader :dataset, :output_dir, :configuration
+
+      # An endpoint gets a page when a test reached it, or when the project
+      # asked for the gaps to be written out too.
+      def documented?(endpoint)
+        endpoint.curl_ready? || configuration.include_uncovered?
+      end
+
+      # A resource with nothing to show gets no directory, so the index never
+      # links to a page that was not written.
+      def written_resources
+        @written_resources ||= dataset.resources.select do |resource|
+          resource.endpoints.any? { |endpoint| documented?(endpoint) }
+        end
+      end
+
+      def written?(resource)
+        written_resources.include?(resource)
+      end
+
+      def write(path, content)
+        File.write(path, content)
+
+        path.to_s
+      end
+
+      def filenames(resource)
+        resource.file_basenames.transform_values { |basename| "#{basename}.md" }
+      end
+
+      def index_document
+        lines = ["# API Documentation", ""]
+        lines << "Generated by Reqcord from the application's integration tests."
+        lines << ""
+        lines << "Base URL: `#{configuration.base_url}`"
+        lines << ""
+        lines.concat(placeholders_section)
+
+        dataset.resources.each do |resource|
+          lines << if written?(resource)
+                     "## [#{resource.title}](#{resource.slug}/index.md)"
+                   else
+                     "## #{resource.title}"
+                   end
+          lines << ""
+          lines.concat(namespace_line(resource))
+          lines.concat(endpoint_table(resource, prefix: "#{resource.slug}/"))
+          lines << ""
+        end
+
+        undocumented = dataset.endpoints.reject(&:curl_ready?)
+
+        unless undocumented.empty?
+          lines << "## No Successful Request Captured"
+          lines << ""
+          lines << "No successful 2xx request was captured for these routes:"
+          lines << ""
+          undocumented.each { |endpoint| lines << "- `#{endpoint.method} #{endpoint.path}`" }
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      # Sanitized values are written as placeholders; the reader has to know
+      # what to substitute.
+      def placeholders_section
+        placeholders = configuration.sanitized_headers.values.grep(/\{\{.+\}\}/)
+
+        return [] if placeholders.empty?
+
+        rows = configuration.sanitized_headers.filter_map do |header, value|
+          "| #{header} | `#{value}` |" if value.to_s.match?(/\{\{.+\}\}/)
+        end
+
+        ["## Placeholders", "", "| Header | Replace with |", "| --- | --- |", *rows, ""]
+      end
+
+      # Two resources can share a title (admin/customers, api/v2/customers);
+      # the namespace tells them apart.
+      def namespace_line(resource)
+        return [] if resource.namespace.empty?
+
+        ["Namespace: `#{resource.namespace}`", ""]
+      end
+
+      def resource_document(resource)
+        lines = ["# #{resource.title}", ""]
+        lines.concat(namespace_line(resource))
+
+        versions = resource.api_versions
+
+        unless versions.empty?
+          lines << "API version: #{versions.map { |version| "`#{version}`" }.join(', ')}"
+          lines << ""
+        end
+
+        lines.concat(endpoint_table(resource))
+        lines << ""
+        lines.join("\n")
+      end
+
+      def endpoint_table(resource, prefix: "")
+        rows = filenames(resource).map do |endpoint, filename|
+          path =
+            if documented?(endpoint)
+              "[`#{endpoint.path}`](#{prefix}#{filename})"
+            else
+              "`#{endpoint.path}`"
+            end
+
+          covered = endpoint.curl_ready? ? "" : " _(no successful request captured)_"
+
+          "| `#{endpoint.method}` | #{path} | #{endpoint.name}#{covered} |"
+        end
+
+        ["| Method | Path | Description |", "| --- | --- | --- |", *rows]
+      end
+
+      def endpoint_document(resource, endpoint)
+        example = endpoint.primary_request_example
+
+        lines = ["# #{endpoint.name}", "", endpoint_line(endpoint), ""]
+        lines.concat(namespace_line(resource))
+
+        unless endpoint.curl_ready?
+          lines << "_No successful 2xx request was captured for this endpoint yet._"
+          lines << ""
+        end
+
+        lines.concat(headers_section(example))
+        lines.concat(schema_section("Path Parameters", endpoint.path_param_schema))
+        lines.concat(schema_section("Query Parameters", endpoint.query_schema))
+        lines.concat(schema_section("Body Parameters", endpoint.body_schema))
+        lines.concat(request_body_section(example))
+        lines.concat(curl_section(example))
+        lines.concat(responses_section(endpoint))
+        lines.concat(["---", "", "Resource: [#{resource.title}](index.md)", ""])
+
+        lines.join("\n")
+      end
+
+      # Field, type, whether every accepted request carried it, and the values
+      # those requests used. Values are listed only when they look like a
+      # closed set; otherwise one of them stands as an example.
+      def schema_section(title, schema, level: 2)
+        return [] if schema.empty?
+
+        rows = schema.map do |field|
+          "| `#{field.path}` | #{field.type} | #{field.required? ? 'yes' : 'no'} | #{values_cell(field)} |"
+        end
+
+        ["#{'#' * level} #{title}", "", "| Field | Type | Required | Values |", "| --- | --- | --- | --- |", *rows, ""]
+      end
+
+      def values_cell(field)
+        return "-" if field.values.empty?
+        return field.listed_values.map { |value| "`#{value.inspect}`" }.join(" \\| ") if field.enum?
+
+        "`#{field.example.inspect}`"
+      end
+
+      # `PATCH /api/cart` (also `PUT`)
+      def endpoint_line(endpoint)
+        line = "`#{endpoint.method} #{endpoint.path}`"
+
+        return line if endpoint.also_methods.empty?
+
+        "#{line} (also #{endpoint.also_methods.map { |method| "`#{method}`" }.join(', ')})"
+      end
+
+      def headers_section(example)
+        return [] if example.nil? || example.headers.empty?
+
+        rows = example.headers.map { |name, value| "| #{name} | `#{value}` |" }
+
+        ["## Headers", "", "| Header | Value |", "| --- | --- |", *rows, ""]
+      end
+
+      # A form body is shown as the key/value structure the test built, which
+      # reads better than the encoded string; the note says how it travels.
+      def request_body_section(example)
+        return [] unless example&.body?
+
+        lines = ["## Example Request", ""]
+
+        unless Renderers::Payload.json?(example) || example.content_type.to_s.empty?
+          lines << "Sent as `#{example.content_type}`; the cURL below carries it in that encoding."
+          lines << ""
+        end
+
+        lines.concat([*code_block(example.body, example.content_type), ""])
+      end
+
+      def curl_section(example)
+        return [] if example.nil?
+
+        ["## cURL", "", "```bash", curl_for(example), "```", ""]
+      end
+
+      def responses_section(endpoint)
+        return [] if endpoint.response_examples.empty?
+
+        lines = ["## Responses", ""]
+
+        endpoint.responses.each do |response|
+          lines << "### #{response.example.title}"
+          lines << ""
+          lines.concat(schema_section("Fields", response.schema, level: 4))
+          lines.concat(response_body(response.example))
+        end
+
+        lines
+      end
+
+      def response_body(example)
+        return ["_No response body._", ""] unless example.body?
+
+        [*code_block(example.body, example.content_type), ""]
+      end
+
+      def curl_for(example)
+        Renderers::Curl.call(
+          example,
+          base_url: configuration.base_url
+        )
+      end
+
+      def code_block(value, content_type)
+        case value
+        when Hash, Array then ["```json", pretty_json(value), "```"]
+        else ["```#{content_type.to_s.include?('json') ? 'json' : 'text'}", value.to_s, "```"]
+        end
+      end
+
+      def pretty_json(value)
+        JSON.pretty_generate(value)
+      rescue JSON::GeneratorError
+        value.to_s
+      end
+    end
+
+    register("markdown", Markdown)
+  end
+end