bulldogger 0.1.0

data/lib/bulldogger/record/sqlite_converter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bulldogger
+  module Record
+    # Converts an existing trace-NNN.jsonl into a SQLite database, one
+    # row per event line.
+    #
+    # sqlite3 is required here, and only inside #convert (soft
+    # require) -- never at the top of this file. The design principle
+    # is "CLI and any servers are thin adapters over the files": a
+    # live SQLite writer running alongside the JSONL writer would make
+    # SQLite a second product instead of an adapter, and requiring the
+    # gem unconditionally would add a runtime dependency the core does
+    # not carry. When sqlite3 is not installed, this returns nil
+    # rather than raising, so a caller that never asked for SQL access
+    # is never broken by its absence.
+    module SqliteConverter
+      class << self
+        def convert(jsonl_path, db_path)
+          require "sqlite3"
+        rescue LoadError => e
+          # Unconditional, not gated by BULLDOGGER_DEBUG: the contract
+          # requires an explicit signal, not a silent nil, when sqlite3
+          # is unavailable ("使えないことを明示的に伝えて nil を返す").
+          # The debug gate elsewhere in this codebase exists for the
+          # :call/:return/:raise hooks, which fire on every traced
+          # event and must stay silent by default; to_sqlite is a
+          # single explicit call a caller made on purpose, never a hot
+          # path, so warning every time costs nothing worth hiding.
+          warn("bulldogger: sqlite3 not available (#{e.class}: #{e.message}); to_sqlite returning nil")
+          nil
+        else
+          write_database(jsonl_path, db_path)
+          db_path
+        end
+
+        private
+
+        def write_database(jsonl_path, db_path)
+          File.delete(db_path) if File.exist?(db_path)
+          db = SQLite3::Database.new(db_path)
+          create_table(db)
+          insert_events(db, jsonl_path)
+        ensure
+          db&.close
+        end
+
+        def create_table(db)
+          db.execute(<<~SQL)
+            CREATE TABLE events (
+              seq INTEGER,
+              event TEXT,
+              depth INTEGER,
+              path TEXT,
+              line INTEGER,
+              method TEXT,
+              payload TEXT
+            )
+          SQL
+        end
+
+        # One row per JSONL line after the header. payload keeps the
+        # full original JSON object (args/return/exception vary by
+        # event kind and do not fit fixed columns without inventing a
+        # shape the JSONL schema itself does not have); the other
+        # columns exist so a caller can filter and order with plain
+        # SQL instead of parsing payload on every row.
+        def insert_events(db, jsonl_path)
+          db.transaction do
+            File.foreach(jsonl_path).with_index do |line, index|
+              next if index.zero? # header line, not an event
+
+              row = JSON.parse(line)
+              db.execute(
+                "INSERT INTO events (seq, event, depth, path, line, method, payload) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                [row["seq"], row["event"], row["depth"], row["path"], row["line"], row["method"], line.chomp]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bulldogger/record/writer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Bulldogger
+  module Record
+    # Appends one JSON object per line to trace-NNN.jsonl, plus a
+    # header line written once at construction.
+    #
+    # The NNN is picked by scanning the run directory for existing
+    # trace-*.jsonl files, not an in-memory counter: Run (owned
+    # elsewhere) already hands out its own NNN-slug.json sequence for
+    # evidence files, and a Record session has no access to that
+    # counter -- nor should it share one, since "trace-NNN" and
+    # "NNN-slug" are different filename shapes with no shared meaning
+    # to a reader comparing NNN values across them.
+    class Writer
+      FILENAME_PATTERN = /\Atrace-(\d+)\.jsonl\z/
+
+      @reserve_mutex = Mutex.new
+
+      attr_reader :path
+
+      def initialize(run_dir:, header:)
+        @path = self.class.reserve_path(run_dir)
+        @io = File.open(@path, "w")
+        write_line(header)
+      end
+
+      def write_event(event)
+        write_line(event)
+      end
+
+      def close
+        @io.close
+        @path
+      end
+
+      class << self
+        # Reserves the next trace-NNN.jsonl name under a process-wide
+        # lock. Two sessions starting back to back (or on two threads)
+        # must never both see the same "no trace-*.jsonl yet" listing
+        # and pick the same NNN, so the file is created (empty) while
+        # still holding the lock -- closing the window where a second
+        # scan could run before the first session's file exists on
+        # disk. The lock only spans this rare, brief start-up step,
+        # never a per-event write.
+        def reserve_path(run_dir)
+          @reserve_mutex.synchronize do
+            existing = Dir.children(run_dir).filter_map { |name| name[FILENAME_PATTERN, 1]&.to_i }
+            next_n = (existing.max || 0) + 1
+            path = File.join(run_dir, format("trace-%03d.jsonl", next_n))
+            FileUtils.touch(path)
+            path
+          end
+        end
+      end
+
+      private
+
+      def write_line(hash)
+        @io.write("#{JSON.generate(hash)}\n")
+      end
+    end
+  end
+end

data/lib/bulldogger/record.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../bulldogger"
+require_relative "record/session"
+require_relative "record/sqlite_converter"
+
+module Bulldogger
+  # Full, unfiltered method-call recording, as an explicit verb rather
+  # than an ambient default. Where Capture answers "what failed" from
+  # a single :raise, Record answers "what happened" across a block:
+  # every :call, :return, and :raise event in the process while the
+  # block runs, one JSON object per line. This is the heavy path
+  # AGENTS.md reserves for an explicit request -- see
+  # tasks/record.rake for the measured cost of turning it on.
+  #
+  # This is a thin facade over Session (the TracePoint subscription
+  # and JSONL writer) and SqliteConverter (the optional, offline
+  # sqlite adapter), the same shape lib/bulldogger.rb uses for
+  # Capture/Run/Evidence.
+  module Record
+    class << self
+      # Runs the block with recording on. The block runs whether or
+      # not recording actually started: an app calling Record.run must
+      # see its own code execute the same way with or without
+      # Bulldogger, so only the trace file -- never the block -- is
+      # conditional on config.enabled.
+      def run
+        session = start
+        path = nil
+        begin
+          yield
+        ensure
+          path = session.stop
+        end
+        path
+      end
+
+      # config and run_dir come from the shared Bulldogger facade
+      # (already public API), not a Record-owned copy: one process has
+      # one run directory and one kill switch, shared by failure
+      # capture, probe, and record alike.
+      def start
+        Session.new(config: Bulldogger.config, run_dir: Bulldogger.run_dir)
+      end
+
+      def to_sqlite(jsonl_path, db_path)
+        SqliteConverter.convert(jsonl_path, db_path)
+      end
+    end
+  end
+end

data/lib/bulldogger/redactor.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bulldogger
+  # Decides whether a name (a local variable, a Hash key) should hide
+  # its value. This check runs on the name alone, before any value is
+  # touched: calling `inspect` on a secret-shaped object and then
+  # discarding the result still risks the secret leaking (into a log,
+  # into a raised error from a hostile #inspect), so the name check
+  # must gate the inspect call, not follow it.
+  class Redactor
+    def initialize(patterns)
+      @patterns = patterns
+    end
+
+    def redact_name?(name)
+      matches?(name)
+    end
+
+    def redact_key?(key)
+      matches?(key)
+    end
+
+    private
+
+    def matches?(name)
+      text = name.to_s
+      @patterns.any? { |pattern| pattern.match?(text) }
+    end
+  end
+end

data/lib/bulldogger/rspec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# The one line a spec_helper.rb adds to turn Bulldogger on for RSpec.
+# Kept separate from lib/bulldogger/integrations/rspec.rb so that file
+# can stay organized by framework alongside minitest.rb, while this
+# stays the short, memorable require path.
+require_relative "integrations/rspec"

data/lib/bulldogger/run.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Bulldogger
+  # Owns the on-disk run directory: its lazy creation, evidence file
+  # sequence numbers, and the index.json/latest written at the end.
+  #
+  # The directory is created lazily, on first use, not at
+  # construction. A fully green test suite must never touch the
+  # filesystem -- that is what "costs nothing while tests are green"
+  # means in practice -- so nothing here may mkdir until a caller
+  # actually asks for a path to write to.
+  class Run
+    def initialize(config:)
+      @config = config
+      @dir = nil
+      @sequence = 0
+      @failures = []
+      @finished = false
+      @mutex = Mutex.new
+    end
+
+    # Returns nil when the switch is off. A kill switch earns its name
+    # only if every public path honours it, so this one refuses even
+    # though record_failure and finish already refuse on their own: a
+    # caller who reads the API and asks for the run directory directly
+    # must not be the one hole that still writes to disk.
+    def dir
+      return nil unless @config.enabled
+
+      @mutex.synchronize { ensure_dir }
+    end
+
+    def next_path(slug)
+      @mutex.synchronize do
+        ensure_dir
+        @sequence += 1
+        File.join(@dir, format("%03d-%s.json", @sequence, slug))
+      end
+    end
+
+    def record(path, test:, exception_summary:)
+      @mutex.synchronize do
+        @failures << {
+          "path" => File.basename(path),
+          "test" => test,
+          "exception" => exception_summary
+        }
+      end
+    end
+
+    def finish
+      @mutex.synchronize do
+        return if @finished
+
+        @finished = true
+        # A disabled switch must produce nothing, even if some other
+        # caller reached run_dir directly and already created @dir --
+        # this guard does not depend on record_failure's own refusal
+        # to touch @dir being the only path here.
+        return unless @config.enabled
+        # No @dir means record was never called: a green run. Writing
+        # an index for zero failures would create the very directory
+        # the zero-cost-when-green claim says must not exist.
+        return unless @dir
+
+        write_index
+        write_latest_symlink
+      end
+    end
+
+    private
+
+    def ensure_dir
+      return @dir if @dir
+
+      @dir = File.join(base_output_dir, run_dir_name)
+      FileUtils.mkdir_p(@dir)
+      @dir
+    end
+
+    def base_output_dir
+      path = @config.output_dir
+      File.absolute_path?(path) ? path : File.join(Dir.pwd, path)
+    end
+
+    def run_dir_name
+      "run-#{Time.now.strftime('%Y%m%d-%H%M%S')}-#{Process.pid}"
+    end
+
+    def write_index
+      index = {
+        "schema_version" => 1,
+        "run_dir" => @dir,
+        "failures" => @failures
+      }
+      File.write(File.join(@dir, "index.json"), "#{JSON.pretty_generate(index)}\n")
+    end
+
+    def write_latest_symlink
+      link_path = File.join(base_output_dir, "latest")
+      File.delete(link_path) if File.symlink?(link_path) || File.exist?(link_path)
+      File.symlink(@dir, link_path)
+    rescue SystemCallError, NotImplementedError
+      # Not every filesystem supports symlinks. index.json and the
+      # evidence files are the source of truth; "latest" is a
+      # convenience an agent can lose without losing any evidence.
+      nil
+    end
+  end
+end

data/lib/bulldogger/version.rb

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

data/lib/bulldogger.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "bulldogger/version"
+require_relative "bulldogger/config"
+require_relative "bulldogger/capture"
+require_relative "bulldogger/run"
+require_relative "bulldogger/evidence"
+require_relative "bulldogger/probe"
+
+# Ruby execution evidence for coding agents, as files: a failing test
+# writes a structured snapshot of its own failure, so an agent can read
+# runtime values instead of guessing them from source.
+#
+# This module is a thin facade. It wires Capture (the :raise
+# subscription and its ring of pending snapshots), Run (the on-disk
+# run directory), and Evidence (assembling and writing one failure's
+# JSON) together, and holds the process-global state a test run needs
+# -- one TracePoint, one run directory. No capture, formatting, or
+# redaction logic lives here; see capture.rb, formatter.rb, and
+# redactor.rb.
+module Bulldogger
+  # Autoloaded rather than required at the top of this file, because
+  # record.rb requires this file back: Record.start reads
+  # Bulldogger.config and Bulldogger.run_dir, so `require
+  # "bulldogger/record"` on its own has to work. Requiring in both
+  # directions makes a cycle, and Ruby warns that one file will see
+  # the other half-defined. Deferring until Bulldogger::Record is first
+  # named breaks it -- by then this file has finished loading, so
+  # record.rb's require of it is a no-op.
+  autoload :Record, File.expand_path("bulldogger/record", __dir__)
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+      self
+    end
+
+    def start
+      return self unless config.enabled
+
+      capture.start
+      self
+    end
+
+    def stop
+      capture.stop
+      self
+    end
+
+    def running?
+      capture.running?
+    end
+
+    def snapshot_for(exception)
+      capture.snapshot_for(exception)
+    end
+
+    def record_failure(exception:, test:)
+      evidence.record_failure(exception: exception, test: test)
+    end
+
+    def run_dir
+      run.dir
+    end
+
+    def finish
+      run.finish
+    end
+
+    # Watches target_strings (each "Klass#method" or "Klass.method")
+    # for the life of the block and writes one evidence file
+    # summarizing every call's argument/return shape. See
+    # lib/bulldogger/probe.rb. Returns the written path, or nil if the
+    # switch is off -- the block still runs either way, only the
+    # observing and writing are skipped.
+    def probe(*target_strings, &block)
+      Probe.call(target_strings, config: config, run: run, &block)
+    end
+
+    # Explicit-session counterpart to #probe: call session.finish to
+    # stop watching and write the evidence file. Returns nil, not a
+    # session, when the switch is off -- callers must guard the same
+    # way every other disabled-switch return value here is guarded.
+    def probe_start(*target_strings)
+      Probe.start(target_strings, config: config, run: run)
+    end
+
+    def probe_compare(path_a, path_b)
+      Probe.compare(path_a, path_b)
+    end
+
+    # Traces every call, return, and raise in the block to a JSONL
+    # file. See lib/bulldogger/record.rb. Returns the written path, or
+    # nil if the switch is off. This is the expensive verb, which is
+    # why it is a verb: it costs roughly 4500ns per traced call, on
+    # every call rather than on a named few.
+    def record(&block)
+      Record.run(&block)
+    end
+
+    # Explicit-session counterpart to #record: call session.stop to
+    # finish the trace and get its path.
+    def record_start
+      Record.start
+    end
+
+    # Converts a written trace into SQLite for indexed querying.
+    # Returns nil when the sqlite3 gem is absent, which is the normal
+    # case -- JSONL is the canonical format and this is an adapter over
+    # it, so bulldogger never depends on sqlite3 at runtime.
+    def trace_to_sqlite(jsonl_path, db_path)
+      Record.to_sqlite(jsonl_path, db_path)
+    end
+
+    private
+
+    def capture
+      @capture ||= Capture.new(config: config)
+    end
+
+    def run
+      @run ||= Run.new(config: config)
+    end
+
+    def evidence
+      @evidence ||= Evidence.new(config: config, run: run, capture: capture)
+    end
+  end
+end

data/skills/bulldogger/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: bulldogger
+description: Use bulldogger failure evidence, targeted probes, and full records to inspect Ruby runtime behavior or verify a code change.
+compatibility: Uses files from bulldogger 0.1.0. The query examples require jq. SQLite conversion requires the optional sqlite3 gem.
+license: MIT
+---
+
+# Use bulldogger evidence
+
+Choose the smallest evidence source that answers the question:
+
+- Read an existing failure file when test output has `bulldogger evidence:`.
+- Use `probe` for one method or for a before-and-after behavior check.
+- Use `record` when you must follow the full call sequence.
+
+Use the available evidence before you add logging or infer values from source.
+
+Read [failure evidence](references/failure-evidence.md) for snapshot modes, frames, limits, and missing values.
+Read [probe evidence](references/probe.md) for method shapes, raised exits, samples, and comparisons.
+Read [record traces](references/record.md) for JSONL events, limits, and queries.
+
+`probe` and `record` are explicit, expensive verbs for one focused run.
+The environment disable switches stop all three approaches.
+
+## Start from a failure
+
+1. Find the `bulldogger evidence:` line in the test output.
+2. Open the absolute JSON path from that line.
+3. Read `capture_mode` before you inspect `frames`.
+
+If the output is unavailable, inspect `tmp/bulldogger/latest/index.json`.
+Each `failures[].path` value is relative to the run directory.
+If no evidence exists, check for `BULLDOGGER_DISABLE=1` or `BULLDOGGER_DISABLED=1`.
+Either switch prevents file output, so no `frames_unavailable_reason` exists.
+
+Read `capture_mode` before you infer what the file can show.
+Then follow the failure reference.

data/skills/bulldogger/references/failure-evidence.md

@@ -0,0 +1,56 @@
+# Read failure evidence
+
+## Interpret the capture mode
+
+- `capture_frames`: Each retained frame has `locals` and `self`.
+- `degraded`: Frame 0 has `locals` and `self`.
+  Later frames have `locals_unavailable: true` and location data.
+- `missed`: `frames` is empty, and `frames_unavailable_reason` explains the capture failure.
+
+In degraded evidence, a missing `locals` field does not describe the Ruby frame.
+It means the capture source could not read that frame's locals.
+
+Add `gem "debug", group: :test` to the application Gemfile for complete frame locals.
+Then install the bundle and run the failed test again.
+
+Missed evidence still contains the test, exception message, and exception backtrace.
+Use `frames_unavailable_reason` to distinguish disabled capture, an uncaptured exception, and ring eviction.
+The values are `capture_disabled`, `not_captured`, and `evicted`.
+
+## Find the useful frame
+
+Frame 0 is the raise site.
+For assertion failures, framework assertion code can occupy the first frames.
+A generated Minitest failure placed the test method at index 2.
+
+List the frame labels and paths:
+
+```sh
+jq '[.frames[] | {index, label, path}]' /absolute/path/to/evidence.json
+```
+
+Choose the application or test frame that owns the values you need.
+Then read its locals:
+
+```sh
+jq '.frames[2].locals' /absolute/path/to/evidence.json
+```
+
+Find one local across all captured frames:
+
+```sh
+jq '[.frames[] | select(.locals.qty) | {index, label, qty: .locals.qty}]' /absolute/path/to/evidence.json
+```
+
+## Read missing values correctly
+
+A local with `redacted: true` was hidden because its name matched a redaction pattern.
+It has no `value` field.
+
+A value with `truncated: true` was cut to the configured character limit.
+Use `original_length` to see the length before truncation.
+
+`locals_omitted` and `frames_omitted` give the numbers removed by capture limits.
+An Array or Hash ending in `…` had more than 10 elements.
+
+See [`docs/evidence-schema.md`](../../../docs/evidence-schema.md) for each field and more queries.

data/skills/bulldogger/references/probe.md

@@ -0,0 +1,36 @@
+# Use a targeted probe
+
+Use a probe when one method defines the behavior you need to inspect.
+
+```ruby
+path = Bulldogger.probe("Billing::Invoice#amount") do
+  run_related_test
+end
+```
+
+Read `methods` by target name.
+Each target has call counts, parameters, argument shapes, return shapes, raised exits, and callers.
+
+`raised_exits` counts calls that left through an exception.
+Those calls do not increase the return `nil_count`.
+The distinction prevents a raised exit from appearing as a normal `nil` return.
+
+The class, `nil`, and caller counts include every observed call.
+The `samples` arrays contain the first `limits.max_samples` values.
+`samples_omitted` counts later values that were not serialized.
+
+Run the same probe before and after a change:
+
+```ruby
+before_path = Bulldogger.probe("Billing::Invoice#amount") { run_related_test }
+# Apply the change.
+after_path = Bulldogger.probe("Billing::Invoice#amount") { run_related_test }
+comparison = Bulldogger.probe_compare(before_path, after_path)
+```
+
+`comparison["identical"] == true` shows behavior preservation for the compared shape.
+Read each item in `differences` when the value is false.
+
+Redacted samples have no value.
+Truncated samples include their original length.
+See [`docs/evidence-schema.md`](../../../docs/evidence-schema.md) for all probe fields.

data/skills/bulldogger/references/record.md

@@ -0,0 +1,28 @@
+# Read a full record
+
+Use a record when the relevant method is unknown or the full call sequence matters.
+
+```ruby
+path = Bulldogger.record do
+  run_related_test
+end
+```
+
+The JSONL first line is a header.
+It gives the schema version, event set, start time, and limits.
+Each later line is one call, return, or raise event.
+
+```sh
+head -n 1 "$path" | jq '{schema_version, kind, events, limits}'
+jq -c 'select(.event) | {seq, depth, event, method}' "$path"
+jq -c 'select(.event == "raise") | {method, exception}' "$path"
+```
+
+A return with `raised: true` represents an exception exit.
+It has no `return` field.
+The trace does not contain `:line`, `:b_call`, or `:rescue` lines.
+
+Arguments and return values use redaction and length limits.
+Read `redacted`, `truncated`, and a trailing `…` before you infer that a value did not occur.
+
+See [`docs/trace-schema.md`](../../../docs/trace-schema.md) for all event fields and tested queries.