bulldogger 0.1.0

data/docs/evidence-schema.md

@@ -0,0 +1,388 @@
+# Evidence schema
+
+bulldogger writes one JSON evidence file for each failed test.
+The run directory also contains `index.json`, which lists the failure files.
+
+## Top-level fields
+
+| Field | Type | Presence | Meaning |
+|---|---|---|---|
+| `schema_version` | Integer | always | Schema version. Version 0.1.0 writes `1`. |
+| `tool` | Object | always | Writer name and version. |
+| `captured_at` | String | always | UTC write time in `YYYY-MM-DDTHH:MM:SSZ` format. |
+| `capture_mode` | String | always | `capture_frames`, `degraded`, or `missed`. |
+| `test` | Object | always | Framework test data. |
+| `exception` | Object | always | Exception data. |
+| `frames` | Array | always | Frames from the raise site outward. |
+| `frames_omitted` | Integer | when positive | Frames removed by `max_frames`. |
+| `frames_unavailable_reason` | String | in missed mode | Reason for an empty frame list. |
+| `limits` | Object | always | Limits used for this capture. |
+
+## Test fields
+
+The framework integration supplies all four fields.
+Each value can be `null` when the framework has no value.
+
+| Field | Type |
+|---|---|
+| `framework` | String or null |
+| `id` | String or null |
+| `file` | String or null |
+| `line` | Integer or null |
+
+## Exception fields
+
+| Field | Type | Presence | Meaning |
+|---|---|---|---|
+| `class` | String | always | Exception class name. |
+| `message` | String | always | Message with a limit of five times `max_value_length`. |
+| `message_truncated` | Boolean | when true | The message exceeded its limit. |
+| `message_original_length` | Integer | with `message_truncated` | Length before truncation. |
+| `backtrace` | Array of String | always | First `max_frames` backtrace lines. |
+
+## Frame fields
+
+| Field | Type | Presence | Meaning |
+|---|---|---|---|
+| `index` | Integer | always | Position from the raise site. |
+| `path` | String or null | always | Ruby source path. |
+| `line` | Integer or null | always | Ruby source line. |
+| `label` | String or null | always | Method or block label. |
+| `self` | String | when captured | Rendered frame receiver. |
+| `locals` | Object | when captured | Map from local names to entries. |
+| `locals_omitted` | Integer | when positive | Locals removed by `max_locals`. |
+| `locals_unavailable` | Boolean | degraded frames after frame 0 | The capture source could not read these locals. |
+
+Frame 0 is the innermost frame.
+An assertion library can raise before control returns to the test method.
+Search frame labels and paths to identify the frame that owns the needed locals.
+
+## Local entries
+
+A captured local has a String value:
+
+```json
+{"qty": {"value": "3"}}
+```
+
+A value longer than `max_value_length` also has truncation fields:
+
+```json
+{"value": "a long rendered value…", "truncated": true, "original_length": 814}
+```
+
+A local name that matches a redaction pattern has this shape:
+
+```json
+{"api_token": {"redacted": true, "reason": "name"}}
+```
+
+The redacted entry has no `value` field.
+Version 0.1.0 emits only `"name"` as the `reason` value.
+
+Hash-key redaction appears inside the parent value String:
+
+```json
+{"settings": {"value": "{\"token\" => \"[REDACTED]\", \"level\" => \"debug\"}"}}
+```
+
+## Value rendering
+
+bulldogger stores each rendered value as a JSON String.
+It uses Ruby `inspect` for scalar values and Strings.
+
+Arrays and Hashes expand one level.
+A nested Array becomes `[…]`, and a nested Hash becomes `{…}`.
+The formatter keeps 10 elements and adds `…` when more elements exist.
+
+For other objects, the formatter calls `inspect` and catches any exception.
+An object with a failing `inspect` produces `#<ClassName (inspect raised ExceptionClass)>`.
+
+## Capture modes
+
+### `capture_frames`
+
+The `debug` frame API supplies locals and `self` for each retained frame.
+This projection came from a generated Minitest failure file:
+
+```json
+{
+  "schema_version": 1,
+  "tool": {"name": "bulldogger", "version": "0.1.0"},
+  "capture_mode": "capture_frames",
+  "test": {
+    "framework": "minitest",
+    "id": "RedTest#test_deep_raise",
+    "file": "test/fixtures/minitest_red/red_test.rb",
+    "line": 19
+  },
+  "exception": {
+    "class": "ArgumentError",
+    "message": "expected 3 to equal the sum of [1, 2, 3]"
+  },
+  "frames": [
+    {
+      "index": 0,
+      "line": 9,
+      "label": "Order.total",
+      "self": "Order",
+      "locals": {
+        "qty": {"value": "3"},
+        "rows": {"value": "[1, 2, 3]"},
+        "api_token": {"redacted": true, "reason": "name"}
+      }
+    }
+  ],
+  "limits": {"max_frames": 20, "max_locals": 50, "max_value_length": 200}
+}
+```
+
+### `degraded`
+
+Frame 0 uses the raising `TracePoint` binding.
+Later frames contain positions and `locals_unavailable: true`.
+This projection came from the same fixture with `BULLDOGGER_FRAME_SOURCE=degraded`:
+
+```json
+{
+  "schema_version": 1,
+  "capture_mode": "degraded",
+  "frames": [
+    {
+      "index": 0,
+      "line": 9,
+      "label": "Order.total",
+      "locals": {
+        "qty": {"value": "3"},
+        "rows": {"value": "[1, 2, 3]"},
+        "api_token": {"redacted": true, "reason": "name"}
+      },
+      "self": "Order"
+    },
+    {
+      "index": 1,
+      "path": "test/fixtures/minitest_red/red_test.rb",
+      "line": 20,
+      "label": "RedTest#test_deep_raise",
+      "locals_unavailable": true
+    }
+  ]
+}
+```
+
+A later frame can have Ruby locals even when the evidence has no `locals` field.
+Add `gem "debug", group: :test` and repeat the failed test to capture those locals.
+
+### `missed`
+
+Missed mode has an empty frame list.
+The following complete file came from recording an exception before capture started:
+
+```json
+{
+  "schema_version": 1,
+  "tool": {"name": "bulldogger", "version": "0.1.0"},
+  "captured_at": "2026-08-28T07:58:25Z",
+  "capture_mode": "missed",
+  "test": {
+    "framework": "minitest",
+    "id": "MissedTest#test_example",
+    "file": "test/missed_test.rb",
+    "line": 7
+  },
+  "exception": {
+    "class": "ArgumentError",
+    "message": "missed example",
+    "backtrace": ["-e:1:in '<main>'"]
+  },
+  "frames": [],
+  "frames_unavailable_reason": "capture_disabled",
+  "limits": {"max_frames": 20, "max_locals": 50, "max_value_length": 200}
+}
+```
+
+The reason has one of these values:
+
+| Value | Meaning |
+|---|---|
+| `capture_disabled` | Capture was not running when Ruby raised the exception. |
+| `not_captured` | Capture was running, but the pending ring had no matching exception. |
+| `evicted` | Later exceptions removed the matching snapshot from the bounded ring. |
+
+Missed evidence retains the test data, exception message, and exception backtrace.
+
+## Limits and omission markers
+
+The default limits are 20 frames, 50 locals per frame, and 200 characters per value.
+The pending ring keeps 32 exception snapshots.
+
+The file records positive omission counts:
+
+- `frames_omitted` counts frames after `max_frames`.
+- `locals_omitted` counts locals after `max_locals`.
+- `original_length` records the rendered length before value truncation.
+- `message_original_length` records the message length before message truncation.
+
+An Array or Hash uses a trailing `…` to mark elements after the first 10.
+
+## Run index
+
+`index.json` has this shape:
+
+```json
+{
+  "schema_version": 1,
+  "run_dir": "/absolute/path/tmp/bulldogger/run-20260828-165825-28806",
+  "failures": [
+    {
+      "path": "001-RedTest-test_assertion_failure.json",
+      "test": {
+        "framework": "minitest",
+        "id": "RedTest#test_assertion_failure",
+        "file": "test/fixtures/minitest_red/red_test.rb",
+        "line": 12
+      },
+      "exception": {
+        "class": "Minitest::Assertion",
+        "message": "seeded api_token: 9 chars.\nExpected: 4\n  Actual: 9"
+      }
+    }
+  ]
+}
+```
+
+Each failure path is relative to the run directory.
+The `latest` symlink points to the last finished run when the filesystem supports symlinks.
+
+## Probe evidence
+
+`Bulldogger.probe` writes one JSON file after the observed block finishes.
+The file has `kind: "probe"` and a `methods` entry for each target.
+
+This excerpt came from a generated probe of `ProseSample#amount`:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "probe",
+  "tool": {"name": "bulldogger", "version": "0.1.0"},
+  "targets": ["ProseSample#amount"],
+  "methods": {
+    "ProseSample#amount": {
+      "calls": 3,
+      "raised_exits": 1,
+      "parameters": [["req", "mult"], ["key", "discount"], ["key", "api_token"]],
+      "params": {
+        "discount": {
+          "classes": {"NilClass": 2, "TrueClass": 1},
+          "nil_count": 2,
+          "samples": [{"value": "nil"}, {"value": "true"}, {"value": "nil"}]
+        },
+        "api_token": {
+          "classes": {"NilClass": 2, "String": 1},
+          "nil_count": 2,
+          "samples": [
+            {"redacted": true, "reason": "name"},
+            {"redacted": true, "reason": "name"},
+            {"redacted": true, "reason": "name"}
+          ]
+        }
+      },
+      "returns": {
+        "classes": {"Integer": 1, "NilClass": 1},
+        "nil_count": 1,
+        "samples": [{"value": "21"}, {"value": "nil"}]
+      },
+      "raised": {"ArgumentError": 1},
+      "callers": {"-e:1:in 'block in <main>'": 3}
+    }
+  },
+  "limits": {"max_samples": 10, "max_value_length": 200}
+}
+```
+
+### Probe method fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `calls` | Integer | Calls observed for this target. |
+| `raised_exits` | Integer | Calls that left the method through an exception. |
+| `parameters` | Array | Declared parameter kinds and names. |
+| `params` | Object | Class counts, `nil` counts, and samples for each named argument. |
+| `returns` | Object | Class counts, `nil` count, and samples for normal returns. |
+| `raised` | Object | Exception class counts for raised exits. |
+| `callers` | Object | Call-site strings and their counts. |
+
+A raised exit does not increase the return count.
+This rule distinguishes an exception exit from a normal `nil` return.
+
+Each parameter and return bucket counts every observed value.
+The `samples` array contains the first `max_samples` rendered values.
+When later values exist, `samples_omitted` gives their count.
+Redaction and value limits use the failure evidence rules.
+
+`Bulldogger.probe_compare` compares two probe files by their behavior shape.
+Its result has `identical` and `differences` fields.
+
+## jq queries
+
+These queries ran against generated evidence files.
+
+List the capture mode and test identifier:
+
+```sh
+jq '{capture_mode, test_id: .test.id}' evidence.json
+```
+
+List frame positions:
+
+```sh
+jq '[.frames[] | {index, label, path}]' evidence.json
+```
+
+Find a local in any captured frame:
+
+```sh
+jq '[.frames[] | select(.locals.qty) | {index, label, qty: .locals.qty}]' evidence.json
+```
+
+List truncated locals:
+
+```sh
+jq '[.frames[] | .index as $frame | (.locals // {}) | to_entries[]
+  | select(.value.truncated == true)
+  | {frame: $frame, name: .key, original_length: .value.original_length}]' evidence.json
+```
+
+List redacted locals:
+
+```sh
+jq '[.frames[] | .index as $frame | (.locals // {}) | to_entries[]
+  | select(.value.redacted == true)
+  | {frame: $frame, name: .key, reason: .value.reason}]' evidence.json
+```
+
+List failed test identifiers from the run index:
+
+```sh
+jq '[.failures[].test.id]' tmp/bulldogger/latest/index.json
+```
+
+List the call count, raised exits, and callers from probe evidence:
+
+```sh
+jq '.methods | to_entries[] | {
+  method: .key, calls: .value.calls,
+  raised_exits: .value.raised_exits, callers: .value.callers
+}' probe.json
+```
+
+List parameter and return `nil` counts:
+
+```sh
+jq '.methods | to_entries[] | {
+  method: .key,
+  params: (.value.params | map_values(.nil_count)),
+  returns: .value.returns.nil_count
+}' probe.json
+```

data/docs/maintenance.md

@@ -0,0 +1,92 @@
+# Maintenance
+
+## How releases work
+
+GitHub Actions publishes bulldogger through RubyGems.org Trusted
+Publishing. The release workflow holds no RubyGems.org API key. It signs
+in with a short-lived OIDC token that RubyGems.org accepts only from this
+repository, this workflow file, and this environment.
+
+`.github/workflows/release.yml` runs when a `v*` tag reaches GitHub. It
+checks that the tag version matches `Bulldogger::VERSION`, runs the
+default task and the coverage gate, builds the gem, pushes it, and
+attaches the built gem to a GitHub release.
+
+## Before the first release
+
+Two things live outside this repository, and a release fails without
+either one.
+
+### Register the pending trusted publisher
+
+RubyGems.org accepts a publisher for a gem name that does not exist yet.
+Open the [pending trusted publishers
+page](https://rubygems.org/profile/oidc/pending_trusted_publishers) and
+create one with these values:
+
+| Field | Value |
+| --- | --- |
+| Gem name | `bulldogger` |
+| Repository owner | `meganemura` |
+| Repository name | `bulldogger` |
+| Workflow filename | `release.yml` |
+| Environment | `release` |
+| Workflow repository owner | Leave this field blank. |
+| Workflow repository name | Leave this field blank. |
+
+Leave both workflow repository fields blank. Those fields name a
+reusable workflow in a different repository, and this workflow lives
+beside the gem.
+
+RubyGems.org converts the pending publisher after the first successful
+push, and adds the profile account as an owner of the new gem.
+
+For a gem that already exists, open the gem page, select **Trusted
+publishers**, select **Create**, and enter the same values.
+
+### Create the GitHub environment
+
+The workflow names `release` as its environment. Create that environment
+in the repository settings and add a required reviewer.
+
+RubyGems.org matches this name exactly. The workflow, the environment in
+the repository settings, and the trusted publisher must all use the same
+name, or the push step fails to authenticate.
+
+Without a required reviewer the environment still satisfies
+RubyGems.org, and the release proceeds with no human confirmation.
+Publishing a version cannot be undone: yanking a version does not free
+its number, and the number can never be reused. The reviewer is what
+turns a pushed tag into a decision.
+
+## Make a release
+
+1. Update the version in `lib/bulldogger/version.rb`.
+2. Complete the normal review process for the version change.
+3. Create a `vVERSION` tag, using the exact version from
+   `version.rb`. Version `0.1.0` takes the tag `v0.1.0`.
+4. Push the tag.
+5. Approve the waiting release in the GitHub Actions run.
+6. Confirm that the workflow succeeds.
+7. Confirm that RubyGems.org shows the new version.
+
+The workflow refuses a tag whose version disagrees with `version.rb`, so
+a mistyped tag stops before anything is published.
+
+Re-running a release that already pushed its gem succeeds. The push step
+treats "Repushing of gem versions is not allowed" as success, so a
+failure in a later step can be retried without the earlier step blocking
+it.
+
+## Releasing a version whose tag already exists
+
+A tag that is already on GitHub does not start a workflow by existing.
+Deleting the tag and pushing it again does:
+
+```sh
+git push origin :refs/tags/vVERSION
+git push origin vVERSION
+```
+
+Confirm the tag points at the commit intended for release before pushing
+it back.

data/docs/trace-schema.md

@@ -0,0 +1,118 @@
+# Trace schema
+
+`Bulldogger.record` writes a JSONL file named `trace-NNN.jsonl`.
+The first line is a header, and each later line is one event.
+
+## Header
+
+This header came from a generated trace:
+
+```json
+{"schema_version":1,"kind":"record","started_at":"2026-08-28T12:15:18Z","events":["call","return","raise"],"limits":{"max_value_length":200}}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `schema_version` | Integer | Schema version. Version 0.1.0 writes `1`. |
+| `kind` | String | The value is `record`. |
+| `started_at` | String | UTC start time. |
+| `events` | Array | Event kinds written after the header. |
+| `limits` | Object | Value limits used for this trace. |
+
+## Events
+
+Each event has `event`, `seq`, `depth`, `path`, `line`, and `method`.
+The sequence starts at 1 and follows write order.
+The depth is the Ruby call depth observed by this recording session.
+
+A call event has an `args` object with named arguments:
+
+```json
+{"event":"call","seq":2,"depth":2,"path":"-e","line":1,"method":"ProseTrace#inner","args":{"value":{"value":"3"}}}
+```
+
+A normal return has a rendered `return` entry:
+
+```json
+{"event":"return","seq":3,"depth":2,"path":"-e","line":1,"method":"ProseTrace#inner","return":{"value":"6"}}
+```
+
+A raise event has an exception class and message:
+
+```json
+{"event":"raise","seq":7,"depth":2,"path":"-e","line":1,"method":"ProseTrace#inner","exception":{"class":"ArgumentError","message":"negative"}}
+```
+
+Ruby emits a `:return` event when an exception leaves a method.
+That event has `raised: true` and has no `return` field:
+
+```json
+{"event":"return","seq":8,"depth":2,"path":"-e","line":1,"method":"ProseTrace#inner","raised":true}
+```
+
+The discriminator uses Ruby-level `:rescue` events.
+It distinguishes raised exits from normal `nil` returns.
+The trace uses this event for internal state and does not write it.
+
+## Event selection
+
+The default event set contains `:call`, `:return`, and `:raise`.
+The header records this set for each file.
+
+`:line` produces an event for each executed source line.
+`:b_call` produces an event for each block invocation.
+Their event counts follow executed lines and block invocations.
+The record verb keeps method boundaries and raises within a usable explicit run.
+
+## Values and secrets
+
+Argument and return entries use the bounded formatter from failure evidence.
+Named arguments also use the configured redaction patterns.
+A redacted argument has no `value` field.
+
+Exception messages use five times `max_value_length`.
+A long message has `message_truncated` and `message_original_length` fields.
+
+## jq queries
+
+These queries ran against the generated trace used for the examples.
+
+Read the header:
+
+```sh
+head -n 1 trace.jsonl | jq '{schema_version, kind, events, limits}'
+```
+
+List the event sequence:
+
+```sh
+jq -c 'select(.event) | {seq, depth, event, method}' trace.jsonl
+```
+
+List raised exits:
+
+```sh
+jq -c 'select(.event == "return" and .raised == true)
+  | {seq, depth, method, raised}' trace.jsonl
+```
+
+List raised exceptions:
+
+```sh
+jq -c 'select(.event == "raise")
+  | {seq, method, class: .exception.class, message: .exception.message}' trace.jsonl
+```
+
+Count calls by method:
+
+```sh
+jq -s 'map(select(.event == "call"))
+  | group_by(.method)
+  | map({method: .[0].method, calls: length})' trace.jsonl
+```
+
+## SQLite adapter
+
+`Bulldogger.trace_to_sqlite(jsonl_path, db_path)` converts a finished trace.
+It returns `nil` with a warning when the `sqlite3` gem is unavailable.
+The converter stores each event and its complete JSON payload.

data/lib/bulldogger/capture.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "redactor"
+require_relative "formatter"
+require_relative "frame_source"
+require_relative "pending"
+
+module Bulldogger
+  # Subscribes to :raise globally and turns every raised exception into
+  # a bounded, already-serialized snapshot before the hook returns.
+  #
+  # Serialization happens here, inside the hook, rather than later from
+  # whatever holds the frame data: a DEBUGGER__::FrameInfo keeps its
+  # frame's Binding alive, and a live Binding keeps every object
+  # reachable from that frame alive too (measured: the TracePoint
+  # block's own captured-array local was still reachable through a
+  # retained Binding). Rendering every value to a String and dropping
+  # the FrameInfo/Binding before this method returns is what makes the
+  # Pending ring's size an actual memory bound, not just a count of
+  # references to unbounded object graphs.
+  class Capture
+    def initialize(config:)
+      @config = config
+      @redactor = Redactor.new(config.redact_patterns)
+      @formatter = Formatter.new(config: config, redactor: @redactor)
+      @frame_source = FrameSource.new(config: config, formatter: @formatter, redactor: @redactor)
+      @pending = Pending.new(config.max_pending)
+      @trace_point = nil
+      @start_mutex = Mutex.new
+    end
+
+    def start
+      @start_mutex.synchronize do
+        return self if @trace_point
+
+        @frame_source.resolve!
+        trace_point = TracePoint.new(:raise) { |tp| handle_raise(tp) }
+        trace_point.enable
+        @trace_point = trace_point
+      end
+      self
+    end
+
+    def stop
+      @start_mutex.synchronize do
+        @trace_point&.disable
+        @trace_point = nil
+      end
+      self
+    end
+
+    def running?
+      !@trace_point.nil?
+    end
+
+    def snapshot_for(exception)
+      @pending.get(exception)
+    end
+
+    def reason_for_missing(exception)
+      return "capture_disabled" unless running?
+      return "evicted" if @pending.evicted?(exception)
+
+      "not_captured"
+    end
+
+    private
+
+    # :raise fires for every exception, including ones the app rescues
+    # and handles without incident. This hook must never let an
+    # exception escape: doing so would replace the app's real raise
+    # with one from inside our own hook, corrupting the very failure
+    # the app was raising. `rescue Exception`, not `StandardError`,
+    # because even a NoMemoryError or SystemStackError surfacing from
+    # our own code here must not propagate into the app's raise path.
+    def handle_raise(tp)
+      exception = tp.raised_exception
+      frames, frames_omitted = @frame_source.capture(tp)
+      snapshot = {
+        "capture_mode" => @frame_source.mode.to_s,
+        "frames" => frames
+      }
+      # frames_omitted only appears when something was actually cut, so
+      # its presence alone tells a reader "frames were dropped here" --
+      # the same rule build_frame already applies to locals_omitted.
+      snapshot["frames_omitted"] = frames_omitted if frames_omitted.positive?
+      @pending.put(exception, snapshot)
+      nil
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      warn("bulldogger: capture failed: #{e.class}: #{e.message}") if debug?
+      nil
+    end
+
+    def debug?
+      ENV["BULLDOGGER_DEBUG"] == "1"
+    end
+  end
+end