reqcord 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71c23f11e62a357bbc63bc7479cd77d65da3245062b9c0594e4b3d3dc0421fd2
-  data.tar.gz: d20cfd0db3a617adc966f2641da79c155be232baad7fb94b47db235820da3a2d
+  metadata.gz: 87d47bb7440a886650db640312c804f7889a24420be0e1e2b81806ac4114a63c
+  data.tar.gz: d8198f3e86749a170c144bad28eae898f876c8e4a82ca933fa9d1a320204aaad
 SHA512:
-  metadata.gz: a5c2d1ebe2463d5c3647e843d4f70b04114fe3d225a8059b5e6e09d9461945305203c5bbfe4189039a8b48edc713cf39a3d0e5cafadefb6648f62f70aaff4595
-  data.tar.gz: 98406f42d54d21b3d7854a4b36960be53cfe0293be738ca1d1e64194215920b4194c30649a730662e078d4b9558298c1ec9a13d15096207bb4a99257733d4b1f
+  metadata.gz: 0f10290846b36da08d91f98998c8ef14c12427bf509bd8fb84d70a8b1f1bbec9dc389765e1b75be13d647f41000a1e295c39ffa89a70847c74ec84bb0e8ce3bf
+  data.tar.gz: e3c55c9f404b54b4ad2d284be04fc89f13ca5922c5ed52667c8ffad84fd808de3ef826e8b7ff97ad4e0dff8066a44af8122140cbfbb311257739c37b9430d088

data/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## [0.1.2] - Unreleased
+## [0.1.4] - 2026-09-16
+
+### Changed
+
+* A failing test run no longer discards the output. The docs are generated
+  from what the suite captured, the warning names the exit status and the
+  report points out that routes reached only by failing tests are listed as
+  uncovered. The previous behaviour is `test.strict: true`.
+
+### Added
+
+* `test.strict` (`REQCORD_STRICT=1`): abort on a failing suite instead of
+  documenting what it captured.
+
+## [0.1.3] - 2026-09-16
+
+### Added
+
+* `routes.prefix` accepts a list (`[/v1, /v2, /partner]`) for APIs whose
+  versions or audiences do not share a root.
+
+### Changed
+
+* The `reqcord:init` template now names test directories (`test.paths`)
+  instead of running the whole suite, and documents every key inline.
+
+## [0.1.2] - 2026-09-16
 
 ### Added
 

data/docs/configuration.md

@@ -52,6 +52,7 @@ before any test runs. YAML aliases are disabled.
 | --- | --- |
 | `REQCORD_TEST_FRAMEWORK` | `test.framework` |
 | `REQCORD_TEST_COMMAND` | `test.command` (and therefore `test.paths`) |
+| `REQCORD_STRICT` | `test.strict` (`1` or `true`) |
 | `REQCORD_OUTPUT` | `output.directory` |
 | `REQCORD_BASE_URL` | `variables.base_url` |
 | `RESOURCE`, `VERSION` | run-time filters, see [Filtering a run](#filtering-a-run) |
@@ -123,9 +124,23 @@ absent.
 
 With neither `paths` nor `command`, Reqcord runs `bin/rails test`.
 
-Whatever runs must exit successfully. A failing suite aborts the run with
-`Reqcord::GenerationError` and nothing is written — documentation is only
-generated from a green suite.
+### `test.strict`
+
+Default `false`. What happens when the suite does not exit successfully:
+
+* `false` — the run continues and documents what the tests captured. A
+  warning names the exit status, and the report reminds you that routes
+  exercised only by failing tests show up as *uncovered*. A test that failed
+  on an assertion after its request got a `2xx` still counts: the request
+  and response are what the application really did.
+* `true` (or `REQCORD_STRICT=1`) — a failing suite aborts the run with
+  `Reqcord::GenerationError` and nothing is written. Use it in CI when the
+  generated docs are an artifact that must come from a green build.
+
+```yaml
+test:
+  strict: true
+```
 
 ---
 
@@ -146,6 +161,20 @@ routes:
   prefix: /api/v2
 ```
 
+A list documents routes under any of the prefixes — for APIs whose versions
+or audiences do not share a root:
+
+```yaml
+routes:
+  prefix:
+    - /v1
+    - /v2
+    - /partner
+```
+
+One prefix already covers every version beneath it (`/api` includes `/api/v1`
+and `/api/v2`); use `VERSION=v2` to generate for one of them.
+
 Rails' own routes (`rails/…`, Active Storage, Action Mailbox, Turbo) are always
 left out. `redirect(...)` routes and plain Rack mounts cannot be documented from
 a test; they are counted as *skipped* in the report rather than dropped.

data/examples/reqcord.yml

@@ -19,9 +19,16 @@ test:
   # Or spell the command out yourself; it wins over `paths`. Globs expand.
   # command: bin/rails test test/integration test/api
 
+  # A failing suite still documents what it captured; routes reached only by
+  # failing tests are listed as uncovered. `true` aborts instead
+  # (REQCORD_STRICT=1 per run).
+  # strict: false
+
 routes:
-  # Only routes under this prefix are documented. Filter a single run with
-  # RESOURCE=customers,cart or VERSION=v2 instead of editing this file.
+  # Only routes under this prefix are documented; a list works too:
+  #   prefix: [/api, /partner]
+  # Filter a single run with RESOURCE=customers,cart or VERSION=v2 instead of
+  # editing this file.
   prefix: /api
 
 output:

data/lib/reqcord/configuration.rb

@@ -8,7 +8,11 @@ module Reqcord
       # 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"
+        "framework" => "minitest",
+
+        # A red suite still documents what its green tests captured; strict
+        # runs abort instead, for CI that treats the docs as an artifact.
+        "strict" => false
       },
 
       "routes" => {
@@ -123,8 +127,21 @@ module Reqcord
       Array(data.dig("test", "paths")).map(&:to_s)
     end
 
+    # Abort on a failing suite instead of documenting what was captured.
+    def strict_tests?
+      value = ENV.fetch("REQCORD_STRICT") { data.dig("test", "strict") }
+
+      [true, "true", "1"].include?(value)
+    end
+
+    # `prefix: /api` or `prefix: [/v1, /v2]`; a route under any of them is
+    # documented. Empty means every route.
+    def route_prefixes
+      Array(data.dig("routes", "prefix")).map(&:to_s).reject(&:empty?)
+    end
+
     def route_prefix
-      data.dig("routes", "prefix")
+      route_prefixes.first
     end
 
     def output_directory

data/lib/reqcord/generator.rb

@@ -56,6 +56,14 @@ module Reqcord
     # run can say why a request did not turn into documentation.
     attr_reader :unmatched_paths
 
+    # Exit status of the test run, so a caller can tell a fully green run
+    # from documentation generated out of a partly failing suite.
+    attr_reader :test_status
+
+    def tests_passed?
+      test_status.nil? || test_status.success?
+    end
+
     # Routes seen in the table but not documentable, by reason (redirect,
     # mount). Set by collect_routes; exposed so a run can be reconciled.
     attr_accessor :skipped_routes
@@ -161,6 +169,10 @@ module Reqcord
         Reqcord.log("skipped #{skipped_total} route(s) that cannot be documented: #{reasons}")
       end
 
+      unless tests_passed?
+        Reqcord.warn("the test run failed: routes exercised only by failing tests are listed as uncovered")
+      end
+
       return if unmatched_paths.empty?
 
       shown = unmatched_paths.uniq.first(5)
@@ -187,7 +199,7 @@ module Reqcord
       collector = RouteCollector.new(
         resources: resources,
         version: version,
-        prefix: configuration.route_prefix
+        prefix: configuration.route_prefixes
       )
 
       routes = collector.call
@@ -254,10 +266,19 @@ module Reqcord
           wait_thread.value
         end
 
+      @test_status = status
+
       return if status.success?
 
-      raise GenerationError,
-            "Test suite failed while generating Reqcord documentation"
+      if configuration.strict_tests?
+        raise GenerationError,
+              "Test suite failed while generating Reqcord documentation (test.strict is on)"
+      end
+
+      # A red suite still tells the truth about the requests that passed;
+      # dropping everything would hide the docs behind an unrelated failure.
+      Reqcord.warn("test run exited with status #{status.exitstatus}; documenting what it captured anyway")
+      Reqcord.warn("  set test.strict: true (or REQCORD_STRICT=1) to abort on a failing suite")
     end
 
     def read_exchanges(capture_file)

data/lib/reqcord/route_collector.rb

@@ -211,10 +211,12 @@ module Reqcord
       )
     end
 
+    # `prefix` is one string or a list; nothing configured means every route.
     def matches_prefix?(path)
-      return true if prefix.nil? || prefix.empty?
+      prefixes = Array(prefix).map(&:to_s).reject(&:empty?)
+      return true if prefixes.empty?
 
-      path.start_with?(prefix)
+      prefixes.any? { |candidate| path.start_with?(candidate) }
     end
 
     # `RESOURCE=customers`, `RESOURCE=cart` (a singular resource is served by

data/lib/reqcord/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reqcord
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/tasks/reqcord.rake

@@ -11,31 +11,62 @@ namespace :reqcord do
     end
 
     content = <<~YAML
+      # Reqcord configuration. Every key is documented in the gem's
+      # docs/configuration.md. Precedence: environment > this file > defaults.
       version: 1
 
       test:
+        # minitest or rspec
         framework: minitest
-        command: bin/rails test
+
+        # The tests that exercise your API. Reqcord runs `bin/rails test <paths>`
+        # (or `rspec <paths>`) with capture enabled; a directory is enough.
+        paths:
+          - test/integration
+
+        # Or spell the command out yourself; it wins over `paths`.
+        # command: bin/rails test test/integration test/api
+
+        # A failing suite still documents what it captured. Set true to abort
+        # instead (or run with REQCORD_STRICT=1).
+        # strict: false
 
       routes:
+        # Only routes under this prefix are documented; a list works too
+        # (`prefix: [/v1, /v2]`). Filter a single run with
+        # RESOURCE=customers,cart or VERSION=v2.
         prefix: /api
 
       output:
         directory: docs/api
+
+        # Routes no test reached with a 2xx are listed in the index either
+        # way; `true` also writes a page for each of them.
         include_uncovered: false
 
+      # markdown: pages under docs/api, curl: one runnable .sh per endpoint,
+      # postman: postman/collection.json (import into Postman or Hoppscotch).
       exporters:
         - curl
         - markdown
         - postman
 
       variables:
+        # Host of every generated cURL and the Postman `base_url` variable.
         base_url: http://localhost:3000
 
       sanitize:
+        # Header values are replaced verbatim. Authorization, Cookie and
+        # X-Api-Key are always redacted, configured here or not.
         headers:
           Authorization: "Bearer {{token}}"
           X-Api-Key: "{{api_key}}"
+
+        # Body keys, matched at any depth in requests and responses. password,
+        # token, access_token, api_key, secret are always redacted; add the
+        # fields your API exposes (a signed payment link, for example).
+        body:
+          password: "{{password}}"
     YAML
 
     File.write(path, content)
@@ -82,7 +113,7 @@ namespace :reqcord do
       Reqcord::RouteCollector.call(
         resources: ENV.fetch("RESOURCE", "").split(",").map(&:strip).reject(&:empty?),
         version: ENV["VERSION"],
-        prefix: Reqcord.configuration.route_prefix
+        prefix: Reqcord.configuration.route_prefixes
       )
 
     if routes.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reqcord
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Ahmet Saridogan