specy_docs 0.1.0

data/app/frontend/styles.css

@@ -0,0 +1,383 @@
+:root {
+  --bg: #0f1419;
+  --surface: #1a222c;
+  --surface-2: #243040;
+  --border: #2f3d4d;
+  --text: #e7eef6;
+  --muted: #8fa3b8;
+  --accent: #5ec8c0;
+  --get: #3d9a6a;
+  --put: #3b7dd8;
+  --post: #c48a2a;
+  --delete: #c45a5a;
+  --status-success: #2f8f5b;
+  --status-redirect: #3b7dd8;
+  --status-client-error: #c48a2a;
+  --status-server-error: #c45a5a;
+  --status-unknown: #6b7c8f;
+  --font: "IBM Plex Sans", "Segoe UI", sans-serif;
+  --mono: "IBM Plex Mono", "SF Mono", Menlo, monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: var(--font);
+  color: var(--text);
+  background:
+    radial-gradient(circle at top left, #1b2a33 0%, transparent 40%),
+    var(--bg);
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: minmax(260px, 320px) 1fr;
+  min-height: 100vh;
+}
+
+.sidebar {
+  border-right: 1px solid var(--border);
+  background: color-mix(in srgb, var(--surface) 92%, black);
+  padding: 1.5rem 1rem;
+}
+
+.sidebar__header {
+  padding: 0 0.5rem 1.25rem;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 1rem;
+}
+
+.eyebrow {
+  margin: 0 0 0.35rem;
+  color: var(--accent);
+  font-size: 0.75rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.sidebar__header h1 {
+  margin: 0;
+  font-size: 1.25rem;
+  font-weight: 600;
+}
+
+.endpoint-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+
+.endpoint-group__title {
+  margin: 0 0 0.45rem;
+  padding: 0 0.5rem;
+  color: var(--muted);
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+  text-transform: uppercase;
+}
+
+.endpoint-group__list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.endpoint-button {
+  appearance: none;
+  width: 100%;
+  text-align: left;
+  border: 1px solid transparent;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: var(--text);
+  padding: 0.7rem 0.75rem;
+  cursor: pointer;
+  font: inherit;
+}
+
+.endpoint-button:hover,
+.endpoint-button[aria-current="true"] {
+  background: var(--surface-2);
+  border-color: var(--border);
+}
+
+.endpoint-button__path {
+  display: block;
+  font-family: var(--mono);
+  font-size: 0.82rem;
+  word-break: break-all;
+}
+
+.endpoint-button__methods {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem;
+  margin-top: 0.45rem;
+}
+
+.main {
+  padding: 2rem;
+}
+
+.status {
+  color: var(--muted);
+}
+
+.detail[hidden] {
+  display: none;
+}
+
+.detail__path {
+  margin: 0 0 1.5rem;
+  font-family: var(--mono);
+  font-size: 1.35rem;
+  word-break: break-all;
+}
+
+.method-tabs {
+  border: 1px solid var(--border);
+  border-radius: 0.75rem;
+  background: var(--surface);
+  overflow: hidden;
+}
+
+.method-tabs__list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  padding: 0.65rem 0.75rem 0;
+  border-bottom: 1px solid var(--border);
+  background: color-mix(in srgb, var(--surface-2) 70%, transparent);
+}
+
+.method-tabs__tab {
+  appearance: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  margin-bottom: -1px;
+  padding: 0.55rem 0.85rem;
+  border: 1px solid transparent;
+  border-bottom: none;
+  border-radius: 0.2rem 0.2rem 0 0;
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+  font: inherit;
+  font-family: var(--mono);
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+}
+
+.method-tabs__tab:hover {
+  color: var(--text);
+  background: color-mix(in srgb, var(--surface) 80%, transparent);
+}
+
+.method-tabs__tab[aria-selected="true"] {
+  color: var(--text);
+  background: var(--surface);
+  border-color: var(--border);
+}
+
+.method-tabs__tab--get[aria-selected="true"] { box-shadow: inset 0 4px 0 var(--get); }
+.method-tabs__tab--put[aria-selected="true"] { box-shadow: inset 0 4px 0 var(--put); }
+.method-tabs__tab--post[aria-selected="true"] { box-shadow: inset 0 4px 0 var(--post); }
+.method-tabs__tab--delete[aria-selected="true"] { box-shadow: inset 0 4px 0 var(--delete); }
+
+.method-tabs__count {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.35rem;
+  padding: 0.05rem 0.35rem;
+  border-radius: 0px;
+  background: var(--surface-2);
+  color: var(--muted);
+  font-size: 0.68rem;
+  font-weight: 600;
+}
+
+.method-tabs__tab[aria-selected="true"] .method-tabs__count {
+  color: var(--text);
+}
+
+.method-tabs__panel {
+  padding: 0;
+}
+
+.method-tabs__panel[hidden] {
+  display: none;
+}
+
+.method-tabs__panel .capture-accordion:first-child {
+  border-top: 0;
+}
+
+.method-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 3.5rem;
+  padding: 0.15rem 0.45rem;
+  border-radius: 0.3rem;
+  font-family: var(--mono);
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: #fff;
+}
+
+.method-badge--get { background: var(--get); }
+.method-badge--put { background: var(--put); }
+.method-badge--post { background: var(--post); }
+.method-badge--delete { background: var(--delete); }
+
+.capture-list {
+  display: flex;
+  flex-direction: column;
+}
+
+.capture-accordion {
+  border-top: 1px solid var(--border);
+}
+
+.capture-accordion__summary {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  grid-template-rows: auto auto;
+  column-gap: 0.75rem;
+  row-gap: 0.35rem;
+  align-items: start;
+  padding: 0.9rem 1rem;
+  cursor: pointer;
+  list-style: none;
+}
+
+.capture-accordion__summary::-webkit-details-marker {
+  display: none;
+}
+
+.capture-accordion__summary::after {
+  content: "▸";
+  grid-column: 2;
+  grid-row: 1 / span 2;
+  align-self: center;
+  color: var(--muted);
+}
+
+.capture-accordion[open] > .capture-accordion__summary::after {
+  content: "▾";
+}
+
+.capture-accordion__description {
+  grid-column: 1;
+  grid-row: 1;
+  font-size: 0.95rem;
+  font-weight: 600;
+  line-height: 1.35;
+}
+
+.capture-accordion__meta {
+  grid-column: 1;
+  grid-row: 2;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.capture-accordion__path {
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: 0.78rem;
+  word-break: break-all;
+}
+
+.status-pill {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2.75rem;
+  padding: 0.12rem 0.45rem;
+  border-radius: 999px;
+  font-family: var(--mono);
+  font-size: 0.72rem;
+  font-weight: 700;
+  color: #fff;
+}
+
+.status-pill--success { background: var(--status-success); }
+.status-pill--redirect { background: var(--status-redirect); }
+.status-pill--client-error { background: var(--status-client-error); }
+.status-pill--server-error { background: var(--status-server-error); }
+.status-pill--unknown { background: var(--status-unknown); }
+
+.capture-accordion__body {
+  padding: 0 1rem 1rem;
+}
+
+.capture__grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 1rem;
+}
+
+.panel h3 {
+  margin: 0 0 0.5rem;
+  font-size: 0.8rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+
+.panel pre,
+.panel .code-block {
+  margin: 0;
+  padding: 0.85rem;
+  border-radius: 0.5rem;
+  background: #0b1015;
+  border: 1px solid var(--border);
+  overflow: auto;
+  font-family: var(--mono);
+  font-size: 0.78rem;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.token-key {
+  color: #7dcfff;
+}
+
+.token-string {
+  color: #9ece6a;
+}
+
+.token-number {
+  color: #ff9e64;
+}
+
+.token-literal {
+  color: #bb9af7;
+}
+
+@media (max-width: 900px) {
+  .layout {
+    grid-template-columns: 1fr;
+  }
+
+  .sidebar {
+    border-right: 0;
+    border-bottom: 1px solid var(--border);
+  }
+}

data/app/views/specy_docs/docs/show.html.erb

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en-GB">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title><%= @config.title %></title>
+    <link rel="stylesheet" href="<%= app_css_path %>" />
+  </head>
+  <body>
+    <div class="layout">
+      <aside class="sidebar">
+        <header class="sidebar__header">
+          <p class="eyebrow"><%= @config.eyebrow %></p>
+          <h1><%= @config.title %></h1>
+        </header>
+        <nav id="endpoint-list" class="endpoint-list" aria-label="Endpoints"></nav>
+      </aside>
+
+      <main class="main">
+        <p id="status" class="status">Loading report…</p>
+        <article id="detail" class="detail" hidden></article>
+      </main>
+    </div>
+
+    <script>
+      window.SPECY_DOCS_CONFIG = {
+        reportPath: <%= raw report_path.to_json %>,
+        maskedHeaderKeys: <%= raw @config.masked_header_keys.to_json %>,
+        rakeTaskHint: "bin/rails specy_docs:report"
+      };
+    </script>
+    <script src="<%= app_js_path %>" type="module"></script>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+SpecyDocs::Engine.routes.draw do
+  root to: 'docs#show'
+  get 'report.json', to: 'docs#report', as: :report
+  get 'app.js', to: 'docs#javascript', as: :app_js
+  get 'styles.css', to: 'docs#stylesheet', as: :app_css
+end

data/lib/specy_docs/capturable.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'digest'
+
+module SpecyDocs
+  module Capturable
+    def self.included(base)
+      base.after(:each) do |example|
+        next unless SpecyDocs::Capturable.should_capture?(example)
+        next unless defined?(response) && response.present?
+
+        SpecyDocs::Capturable.record(example, request, response)
+      end
+    end
+
+    def self.should_capture?(example)
+      return false unless matches_capture_path?(example)
+
+      if SpecyDocs.configuration.opt_in
+        !!example.metadata[:specy]
+      else
+        example.metadata[:specy] != false
+      end
+    end
+
+    def self.matches_capture_path?(example)
+      configured = Array(SpecyDocs.configuration.capture_paths).map(&:to_s).reject(&:empty?)
+      return true if configured.empty?
+
+      file_path = example.metadata[:absolute_file_path].presence || example.metadata[:file_path]
+      return false if file_path.blank?
+
+      absolute = Pathname(file_path).expand_path.to_s
+
+      configured.any? do |capture_path|
+        base = Pathname(capture_path)
+        base = Rails.root.join(capture_path) unless base.absolute?
+        prefix = "#{base.expand_path}#{File::SEPARATOR}"
+        absolute == base.expand_path.to_s || absolute.start_with?(prefix)
+      end
+    end
+
+    def self.record(example, request, response)
+      capture_file = SpecyDocs.configuration.resolved_capture_path
+      FileUtils.mkdir_p(capture_file.dirname)
+
+      key = example.id
+      captures = load_captures(capture_file)
+      captures[key] = {
+        description: example.full_description,
+        location: "#{example.metadata[:file_path]}:#{example.metadata[:line_number]}",
+        request: {
+          method: request.request_method,
+          path: request.path,
+          query_string: request.query_string.presence,
+          headers: filtered_headers(request),
+          body: raw_body(request)
+        },
+        response: {
+          status: response.status,
+          headers: response.headers.slice('Content-Type', 'Location'),
+          body: parsed_body(response)
+        },
+        captured_at: Time.current.iso8601
+      }
+
+      File.write(capture_file, JSON.pretty_generate(captures))
+    end
+
+    def self.load_captures(capture_file = SpecyDocs.configuration.resolved_capture_path)
+      return {} unless capture_file.exist?
+
+      JSON.parse(File.read(capture_file))
+    rescue JSON::ParserError
+      {}
+    end
+
+    def self.raw_body(request)
+      request_body = request.body
+      return nil unless request_body
+
+      body = request_body.read
+      request_body.rewind
+      body.presence
+    end
+
+    def self.filtered_headers(request)
+      request.headers.env
+             .select { |k, _| k.start_with?('HTTP_') || k == 'CONTENT_TYPE' }
+    end
+
+    def self.parsed_body(response)
+      return nil if response.body.blank?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+  end
+end

data/lib/specy_docs/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SpecyDocs
+  class Configuration
+    attr_accessor :capture_path,
+                  :report_path,
+                  :masked_header_keys,
+                  :title,
+                  :eyebrow,
+                  :opt_in,
+                  :capture_paths
+
+    def initialize
+      @capture_path = nil
+      @report_path = nil
+      @masked_header_keys = []
+      @title = 'API Docs'
+      @eyebrow = 'specy-docs'
+      @opt_in = true
+      @capture_paths = []
+    end
+
+    def resolved_capture_path
+      Pathname(capture_path || Rails.root.join('tmp/specy_docs/captures.json'))
+    end
+
+    def resolved_report_path
+      Pathname(report_path || Rails.root.join('tmp/specy_docs/report.json'))
+    end
+  end
+end

data/lib/specy_docs/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails'
+require 'action_controller/railtie'
+require 'action_view/railtie'
+
+module SpecyDocs
+  class Engine < ::Rails::Engine
+    isolate_namespace SpecyDocs
+
+    rake_tasks do
+      load File.expand_path('tasks/specy_docs_tasks.rake', __dir__)
+    end
+  end
+end

data/lib/specy_docs/report_generator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module SpecyDocs
+  class ReportGenerator
+    class InvalidCaptureFileError < StandardError; end
+
+    HTTP_METHODS = %w[get put post delete].freeze
+
+    def self.call(capture_file: nil, output_file: nil)
+      new(
+        capture_file: capture_file || SpecyDocs.configuration.resolved_capture_path,
+        output_file: output_file || SpecyDocs.configuration.resolved_report_path
+      ).call
+    end
+
+    def initialize(capture_file:, output_file:)
+      @capture_file = Pathname(capture_file)
+      @output_file = Pathname(output_file)
+    end
+
+    def call
+      report = build_report
+      write_report(report)
+      report
+    end
+
+    private
+
+    attr_reader :capture_file, :output_file
+
+    def build_report
+      return {} unless capture_file.exist?
+
+      grouped_captures = captures.each_value.with_object({}) do |capture, grouped|
+        path = capture.dig('request', 'path')
+        method = capture.dig('request', 'method')&.downcase
+        next unless path.present? && HTTP_METHODS.include?(method)
+
+        template = route_template(path, method)
+        grouped[template] ||= HTTP_METHODS.index_with { [] }
+        grouped[template][method] << capture
+      end
+
+      grouped_captures.sort.to_h
+    end
+
+    def write_report(report)
+      FileUtils.mkdir_p(output_file.dirname)
+      File.write(output_file, JSON.pretty_generate(report))
+    end
+
+    def captures
+      JSON.parse(capture_file.read)
+    rescue JSON::ParserError => e
+      raise InvalidCaptureFileError, "Invalid capture file: #{e.message}"
+    end
+
+    # Resolves a concrete path to its Rails route template via the route's path.spec.
+    # Domain-like params with dots are matched as [^/]+ so (.:format) does not steal TLDs.
+    def route_template(path, method)
+      route = Rails.application.routes.routes.find do |candidate|
+        next if catch_all_route?(candidate)
+        next unless verb_matches?(candidate, method)
+
+        path_matches_template?(path, candidate)
+      end
+
+      return path unless route
+
+      strip_optional_format(route.path.spec.to_s)
+    end
+
+    def verb_matches?(route, method)
+      verb = route.verb
+      verb.blank? || verb.match?(method.upcase)
+    end
+
+    def path_matches_template?(path, route)
+      template = strip_optional_format(route.path.spec.to_s)
+      pattern = template.split('/').map do |segment|
+        segment.start_with?(':') ? '[^/]+' : Regexp.escape(segment)
+      end.join('/')
+
+      /\A#{pattern}\z/.match?(path)
+    end
+
+    def strip_optional_format(spec)
+      spec.sub(/\(\.:format\)\z/, '')
+    end
+
+    def catch_all_route?(route)
+      route.path.spec.to_s.include?('*')
+    end
+  end
+end

data/lib/specy_docs/tasks/specy_docs_tasks.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+namespace :specy_docs do
+  desc 'Build SpecyDocs report JSON from captured request specs'
+  task report: :environment do
+    output_file = SpecyDocs.configuration.resolved_report_path
+    SpecyDocs::ReportGenerator.call
+    puts "Wrote SpecyDocs report to #{output_file}"
+  end
+end

data/lib/specy_docs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SpecyDocs
+  VERSION = '0.1.0'
+end