specy_docs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f5818e923a111c6ea1eea3993742da3e1e273f730001a9001b643a9b0bb0308
+  data.tar.gz: 170add497082a8e34fd9a58fb4e3fa29db0758c3f0989140b8222f2f1cde253c
+SHA512:
+  metadata.gz: 9d9f5595c0f2d424c51364bbe0b5611a511dd4173c607be7c2d83f7ea3d80c3e65286cd15b85a1c30b84ccdd8eac4217b820f272451821dd5590948051f7dd2e
+  data.tar.gz: 94823fe80e78e972da517fbe771b5fdededd227d4006c4c63112352858c9daac39440fd0e9c9c18b06321c2b5fcab72f56cf27203af13e10239025d86ff75d97

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-19
+
+### Added
+
+- Initial release of SpecyDocs, a mountable Rails engine for API docs from RSpec captures
+- Capture request/response examples from RSpec request specs via `SpecyDocs::Capturable`
+- `SpecyDocs.setup_rspec` helper for include filters that follow configuration
+- Opt-in (`specy: true`) and opt-out (`specy: false`) capture modes
+- Optional `capture_paths` for legacy controller specs without `type: :request`
+- Report generation via `bin/rails specy_docs:report`
+- Mountable browsable docs UI
+- Configurable title, eyebrow, paths, and masked header keys
+- Support for API-only Rails apps (`config.api_only = true`)
+
+[0.1.0]: https://github.com/thabotitus/specy_docs/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# SpecyDocs
+
+Capture RSpec request examples and serve a mountable docs UI.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'specy_docs'
+```
+
+```bash
+bundle install
+```
+
+## Mount the engine
+
+```ruby
+# config/routes.rb
+mount SpecyDocs::Engine => '/docs'
+```
+
+Any path works, e.g. `/api-docs` or `/internal/specy`.
+
+## Capture request specs
+
+Prefer the setup helper so include filters follow your configuration:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  SpecyDocs.setup_rspec(config)
+end
+```
+
+Or include manually:
+
+```ruby
+config.include SpecyDocs::Capturable, type: :request
+```
+
+### Capture folders (legacy controller specs without `type:`)
+
+If controller (or other) specs are not tagged with `type: :request`, and adding a type breaks them, set folders to capture from instead. SpecyDocs will include `Capturable` by file path for those folders. `opt_in` / `specy` tags still apply.
+
+```ruby
+# config/initializers/specy_docs.rb
+SpecyDocs.configure do |config|
+  config.capture_paths = %w[spec/controllers spec/requests]
+  config.opt_in = true
+end
+```
+
+```ruby
+# spec/rails_helper.rb — must use setup_rspec (or include by file_path yourself)
+RSpec.configure do |config|
+  SpecyDocs.setup_rspec(config)
+end
+```
+
+Only examples under those folders are candidates; then:
+
+- `opt_in: true` → capture when `specy: true`
+- `opt_in: false` → capture all in those folders except `specy: false`
+
+### Opt-in mode (default: `opt_in: true`)
+
+Only examples (or groups) tagged with `specy: true` are captured:
+
+```ruby
+RSpec.describe 'Certificates', type: :request do
+  it 'returns the certificate', specy: true do
+    get '/certificates/example.com'
+    expect(response).to have_http_status(:ok)
+  end
+
+  # Not captured
+  it 'returns not found' do
+    get '/certificates/missing.com'
+    expect(response).to have_http_status(:not_found)
+  end
+end
+```
+
+### Opt-out mode (`opt_in: false`)
+
+All matching request specs are captured unless tagged with `specy: false`:
+
+```ruby
+# config/initializers/specy_docs.rb
+SpecyDocs.configure do |config|
+  config.opt_in = false
+end
+
+RSpec.describe 'Status', type: :request do
+  it 'returns success status' do
+    get '/status' # captured
+  end
+
+  it 'skips noise', specy: false do
+    get '/status' # not captured
+  end
+end
+```
+
+## Generate the report
+
+```bash
+bin/rails specy_docs:report
+```
+
+Then open the mounted path (e.g. `http://localhost:3000/docs`).
+
+## Optional configuration
+
+```ruby
+# config/initializers/specy_docs.rb
+SpecyDocs.configure do |config|
+  config.title = 'CDN API'
+  config.eyebrow = 'cdn-api'
+  config.opt_in = true # default; set false to capture all except `specy: false`
+  config.capture_paths = %w[spec/controllers spec/requests] # optional; empty = type: :request only
+  config.capture_path = Rails.root.join('tmp/specy_docs/captures.json')
+  config.report_path = Rails.root.join('tmp/specy_docs/report.json')
+  config.masked_header_keys = %w[
+    Authorization
+  ]
+end
+```
+
+## Notes for API-only apps
+
+SpecyDocs loads Action Controller and Action View railties inside the engine, so the UI renders even when the host app uses `config.api_only = true`.

data/app/controllers/specy_docs/application_controller.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SpecyDocs
+  class ApplicationController < ActionController::Base
+    # Docs UI is read-only static assets + JSON; CSRF / same-origin JS checks
+    # block <script src> loads when serving application/javascript via the controller.
+    skip_forgery_protection
+  end
+end

data/app/controllers/specy_docs/docs_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SpecyDocs
+  class DocsController < ApplicationController
+    layout false
+    skip_after_action :verify_same_origin_request, only: %i[javascript stylesheet]
+
+    def show
+      @config = SpecyDocs.configuration
+    end
+
+    def report
+      path = SpecyDocs.configuration.resolved_report_path
+      if path.exist?
+        send_file path, type: 'application/json', disposition: 'inline'
+      else
+        render json: {}
+      end
+    end
+
+    def javascript
+      send_frontend('app.js', 'application/javascript')
+    end
+
+    def stylesheet
+      send_frontend('styles.css', 'text/css')
+    end
+
+    private
+
+    def send_frontend(filename, content_type)
+      file = SpecyDocs::Engine.root.join('app/frontend', filename)
+      raise ActionController::RoutingError, 'Not Found' unless file.exist?
+
+      send_file file, type: content_type, disposition: 'inline'
+    end
+  end
+end

data/app/frontend/app.js

@@ -0,0 +1,398 @@
+const CONFIG = window.SPECY_DOCS_CONFIG || {};
+const REPORT_PATH = CONFIG.reportPath || './report.json';
+const MASKED_HEADER_KEYS = CONFIG.maskedHeaderKeys || [
+  'Authorization'
+];
+const RAKE_TASK_HINT = CONFIG.rakeTaskHint || 'bin/rails specy_docs:report';
+
+const MASKED_VALUE = '*****';
+const HTTP_METHODS = ['get', 'put', 'post', 'delete'];
+
+const endpointList = document.getElementById('endpoint-list');
+const detail = document.getElementById('detail');
+const status = document.getElementById('status');
+
+let report = {};
+
+async function loadReport() {
+  const response = await fetch(REPORT_PATH);
+  if (!response.ok) {
+    throw new Error(`Failed to load ${REPORT_PATH} (${response.status})`);
+  }
+
+  report = await response.json();
+  const paths = Object.keys(report);
+
+  if (paths.length === 0) {
+    status.textContent = `No captures in report.json. Run: ${RAKE_TASK_HINT}`;
+    return;
+  }
+
+  status.hidden = true;
+  renderEndpointList(paths);
+  selectPath(paths[0]);
+}
+
+function renderEndpointList(paths) {
+  endpointList.innerHTML = '';
+
+  const groups = groupPathsByTopLevel(paths);
+
+  Object.entries(groups).forEach(([group, groupPaths]) => {
+    const section = document.createElement('section');
+    section.className = 'endpoint-group';
+
+    const heading = document.createElement('h2');
+    heading.className = 'endpoint-group__title';
+    heading.textContent = group;
+    section.appendChild(heading);
+
+    const list = document.createElement('div');
+    list.className = 'endpoint-group__list';
+
+    groupPaths.forEach((path) => {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'endpoint-button';
+      button.dataset.path = path;
+
+      const pathEl = document.createElement('span');
+      pathEl.className = 'endpoint-button__path';
+      pathEl.textContent = pathWithinGroup(path, group);
+
+      const methodsEl = document.createElement('span');
+      methodsEl.className = 'endpoint-button__methods';
+      availableMethods(path).forEach((method) => {
+        methodsEl.appendChild(methodBadge(method));
+      });
+
+      button.append(pathEl, methodsEl);
+      button.addEventListener('click', () => selectPath(path));
+      list.appendChild(button);
+    });
+
+    section.appendChild(list);
+    endpointList.appendChild(section);
+  });
+}
+
+function groupPathsByTopLevel(paths) {
+  return paths.reduce((groups, path) => {
+    const group = topLevelGroup(path);
+    groups[group] ||= [];
+    groups[group].push(path);
+    return groups;
+  }, {});
+}
+
+function topLevelGroup(path) {
+  return path.split('/').filter(Boolean)[0] || '/';
+}
+
+function pathWithinGroup(path, group) {
+  const prefix = `/${group}`;
+  if (path === prefix) return '/';
+  return path.startsWith(`${prefix}/`) ? path.slice(prefix.length) : path;
+}
+
+function availableMethods(path) {
+  return HTTP_METHODS.filter((method) => (report[path]?.[method] || []).length > 0);
+}
+
+function selectPath(path) {
+  endpointList.querySelectorAll('.endpoint-button').forEach((button) => {
+    button.setAttribute('aria-current', button.dataset.path === path ? 'true' : 'false');
+  });
+
+  detail.hidden = false;
+  detail.innerHTML = '';
+
+  const heading = document.createElement('h2');
+  heading.className = 'detail__path';
+  heading.textContent = path;
+  detail.appendChild(heading);
+
+  const methods = availableMethods(path);
+  if (methods.length === 0) {
+    const empty = document.createElement('p');
+    empty.className = 'status';
+    empty.textContent = 'No examples for this path.';
+    detail.appendChild(empty);
+    return;
+  }
+
+  detail.appendChild(renderMethodTabs(path, methods));
+}
+
+function renderMethodTabs(path, methods) {
+  const root = document.createElement('div');
+  root.className = 'method-tabs';
+
+  const tabList = document.createElement('div');
+  tabList.className = 'method-tabs__list';
+  tabList.setAttribute('role', 'tablist');
+  tabList.setAttribute('aria-label', 'HTTP methods');
+
+  const panels = document.createElement('div');
+  panels.className = 'method-tabs__panels';
+
+  methods.forEach((method, index) => {
+    const captures = report[path][method];
+    const selected = index === 0;
+    const tabId = `method-tab-${method}`;
+    const panelId = `method-panel-${method}`;
+
+    const tab = document.createElement('button');
+    tab.type = 'button';
+    tab.className = `method-tabs__tab method-tabs__tab--${method}`;
+    tab.id = tabId;
+    tab.setAttribute('role', 'tab');
+    tab.setAttribute('aria-selected', selected ? 'true' : 'false');
+    tab.setAttribute('aria-controls', panelId);
+    tab.tabIndex = selected ? 0 : -1;
+
+    const label = document.createElement('span');
+    label.className = 'method-tabs__label';
+    label.textContent = method.toUpperCase();
+
+    const count = document.createElement('span');
+    count.className = 'method-tabs__count';
+    count.textContent = String(captures.length);
+
+    tab.append(label, count);
+    tab.addEventListener('click', () => activateMethodTab(root, method));
+    tabList.appendChild(tab);
+
+    const panel = document.createElement('div');
+    panel.className = 'method-tabs__panel';
+    panel.id = panelId;
+    panel.setAttribute('role', 'tabpanel');
+    panel.setAttribute('aria-labelledby', tabId);
+    panel.hidden = !selected;
+
+    const accordions = document.createElement('div');
+    accordions.className = 'capture-list';
+    const accordionGroup = `${path}::${method}`;
+    captures.forEach((capture, captureIndex) => {
+      accordions.appendChild(renderCaptureAccordion(capture, captureIndex, accordionGroup));
+    });
+    panel.appendChild(accordions);
+    panels.appendChild(panel);
+  });
+
+  root.append(tabList, panels);
+  return root;
+}
+
+function activateMethodTab(root, method) {
+  root.querySelectorAll('[role="tab"]').forEach((tab) => {
+    const selected = tab.id === `method-tab-${method}`;
+    tab.setAttribute('aria-selected', selected ? 'true' : 'false');
+    tab.tabIndex = selected ? 0 : -1;
+  });
+
+  root.querySelectorAll('[role="tabpanel"]').forEach((panel) => {
+    panel.hidden = panel.id !== `method-panel-${method}`;
+  });
+}
+
+function renderCaptureAccordion(capture, index, accordionGroup) {
+  const details = document.createElement('details');
+  details.className = 'capture-accordion';
+  details.name = accordionGroup;
+  if (index === 0) {
+    details.open = true;
+  }
+
+  const summary = document.createElement('summary');
+  summary.className = 'capture-accordion__summary';
+
+  const description = document.createElement('span');
+  description.className = 'capture-accordion__description';
+  description.textContent = shortenDescription(capture.description) || `Example ${index + 1}`;
+
+  const meta = document.createElement('span');
+  meta.className = 'capture-accordion__meta';
+
+  const pathEl = document.createElement('span');
+  pathEl.className = 'capture-accordion__path';
+  pathEl.textContent = capture.request?.path || 'unknown path';
+
+  meta.append(pathEl, statusPill(capture.response?.status));
+
+  summary.append(description, meta);
+  details.appendChild(summary);
+
+  const body = document.createElement('div');
+  body.className = 'capture-accordion__body';
+
+  const grid = document.createElement('div');
+  grid.className = 'capture__grid';
+  grid.appendChild(
+    renderPanel('Request', {
+      method: capture.request?.method,
+      path: capture.request?.path,
+      query_string: capture.request?.query_string,
+      headers: maskHeaders(capture.request?.headers),
+      body: capture.request?.body
+    })
+  );
+
+  const queryParams = parseQueryString(capture.request?.query_string);
+  if (queryParams) {
+    grid.appendChild(renderPanel('Query', queryParams));
+  }
+
+  const requestBody = parseJsonLike(capture.request?.body);
+  if (requestBody !== null && requestBody !== undefined && requestBody !== '') {
+    grid.appendChild(renderPanel('Body', requestBody));
+  }
+
+  grid.appendChild(
+    renderPanel('Response', {
+      status: capture.response?.status,
+      headers: maskHeaders(capture.response?.headers),
+      body: capture.response?.body
+    })
+  );
+  body.appendChild(grid);
+  details.appendChild(body);
+
+  return details;
+}
+
+function parseQueryString(queryString) {
+  if (!queryString || typeof queryString !== 'string') {
+    return null;
+  }
+
+  const params = {};
+  new URLSearchParams(queryString).forEach((value, key) => {
+    if (Object.prototype.hasOwnProperty.call(params, key)) {
+      params[key] = Array.isArray(params[key]) ? [...params[key], value] : [params[key], value];
+    } else {
+      params[key] = value;
+    }
+  });
+
+  return Object.keys(params).length > 0 ? params : null;
+}
+
+function parseJsonLike(value) {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function maskHeaders(headers) {
+  if (!headers || typeof headers !== 'object') {
+    return headers;
+  }
+
+  const maskedKeys = new Set(MASKED_HEADER_KEYS.map((key) => key.toLowerCase()));
+
+  return Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [
+      key,
+      maskedKeys.has(key.toLowerCase()) ? MASKED_VALUE : value
+    ])
+  );
+}
+
+function renderPanel(title, data) {
+  const panel = document.createElement('div');
+  panel.className = 'panel';
+
+  const heading = document.createElement('h3');
+  heading.textContent = title;
+
+  const pre = document.createElement('pre');
+  pre.className = 'code-block';
+  pre.innerHTML = highlightJson(JSON.stringify(data, null, 2));
+
+  panel.append(heading, pre);
+  return panel;
+}
+
+function highlightJson(json) {
+  const escaped = escapeHtml(json);
+
+  return escaped.replace(
+    /("(?:\\.|[^"\\])*")\s*:|\b(true|false|null)\b|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|("(?:\\.|[^"\\])*")/g,
+    (match, key, literal, number, string) => {
+      if (key) {
+        return `<span class="token token-key">${key}</span>:`;
+      }
+      if (literal) {
+        return `<span class="token token-literal">${literal}</span>`;
+      }
+      if (number) {
+        return `<span class="token token-number">${number}</span>`;
+      }
+      return `<span class="token token-string">${string}</span>`;
+    }
+  );
+}
+
+function escapeHtml(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function methodBadge(method) {
+  const badge = document.createElement('span');
+  badge.className = `method-badge method-badge--${method}`;
+  badge.textContent = method;
+  return badge;
+}
+
+// Prefer starting at the HTTP verb in RSpec descriptions, e.g.
+// "behaves like … ReportBaseController GET /show with valid params …"
+// → "GET /show with valid params …"
+function shortenDescription(description) {
+  if (!description) return '';
+
+  const methodMatch = description.match(/\b(GET|PUT|POST|DELETE)\b/);
+  if (methodMatch) {
+    return description.slice(methodMatch.index).trim();
+  }
+
+  return description
+    .replace(/^(?:[A-Z][\w]*)(?:::[A-Z][\w]*)*Controller\s+/, '')
+    .trim();
+}
+
+function statusPill(statusCode) {
+  const pill = document.createElement('span');
+  const tone = statusTone(statusCode);
+  pill.className = `status-pill status-pill--${tone}`;
+  pill.textContent = statusCode ?? '—';
+  return pill;
+}
+
+function statusTone(statusCode) {
+  const code = Number(statusCode);
+  if (!Number.isFinite(code)) return 'unknown';
+  if (code >= 200 && code <= 299) return 'success';
+  if (code >= 300 && code <= 399) return 'redirect';
+  if (code >= 400 && code <= 499) return 'client-error';
+  if (code >= 500 && code <= 599) return 'server-error';
+  return 'unknown';
+}
+
+loadReport().catch((error) => {
+  status.hidden = false;
+  status.textContent = `${error.message}. Generate with ${RAKE_TASK_HINT}.`;
+});