kensho-rspec 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b97dc4db016aa21aa420a9b63740cabe981c268aae5327934f4ee2e3df61d7ab
+  data.tar.gz: 9a93a8174851bc749cb9a645ad50a981cb649773ca4e88735fd83f1b63e6e995
+SHA512:
+  metadata.gz: 0143d4de5952dcaefa21537e0a7a99b473c67eacff4fd8d77490dbb4e8becbab56039df5461bd4b62cdfb4a6bc5f6b157cb450e5b763eb268e483acbb9e783be
+  data.tar.gz: 9af59332e7f1687b4368bd28d6873dc5dbbe3e3d41e5da2823ef548732f8ed0edfc8a0c5b33ea8ffae72f159158e9d952286b783d587b69aae659c82268092b3

data/README.md

@@ -0,0 +1,177 @@
+# kensho-rspec
+
+An RSpec 3+ formatter that emits the canonical [Kensho v1](../schema) JSON
+format. Run your spec, point the `kensho` CLI at `kensho-results/`, and
+get a self-contained static HTML report.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'kensho-rspec', require: false, group: :test
+```
+
+```bash
+bundle install
+```
+
+## Run
+
+```bash
+# minimal — adds the formatter alongside whatever you already use
+bundle exec rspec --format Kensho::RSpec::Formatter
+
+# combine with the default progress formatter
+bundle exec rspec --format documentation --format Kensho::RSpec::Formatter
+
+# render the HTML report (uses the JS CLI from the same monorepo):
+npx kensho generate
+npx kensho open
+```
+
+You can also pin the formatter from `.rspec`:
+
+```
+--require kensho/rspec
+--format Kensho::RSpec::Formatter
+--format documentation
+```
+
+## What it produces
+
+- `kensho-results/run.json` — run manifest (project, env, totals, timing).
+- `kensho-results/cases/<stableId>.json` — one file per example.
+- `kensho-results/attachments/<caseId>/...` — files registered via `Kensho.attach`.
+
+Each case gets a **stable id** (`tc_<16 hex>`) hashed from its full
+description + file path so test history correlates across runs and
+across adapters (the JS adapters use the same FNV-1a-based hash).
+
+## Metadata we read
+
+| Metadata                                       | Effect                                                    |
+| ---------------------------------------------- | --------------------------------------------------------- |
+| `it 'foo', severity: :critical do`             | Sets `case.severity`. Allowed: `blocker`, `critical`, `normal`, `minor`, `trivial`. |
+| `it 'foo', :critical do`                       | Symbol shorthand. Same five severity names work.          |
+| `it 'foo', severity_blocker: true do`          | Long-form alias.                                          |
+| `Kensho::Feature('Cart')` (inside `describe`)  | Sets `case.behavior.feature`.                             |
+| `Kensho::Epic('Checkout')`                     | Sets `case.behavior.epic`.                                |
+| `Kensho::Story('Empty cart shows CTA')`        | Sets `case.behavior.scenario`.                            |
+| `it 'foo', owner: 'alice' do`                  | Sets `case.owner`.                                        |
+| `it 'foo', kensho_labels: { team: 'cart' } do` | Free-form `key=value` → `case.labels`.                    |
+| `it 'foo', kensho_links: [{ kind: 'jira', url: '…', label: 'PROJ-123' }]` | Adds entries to `case.links`. |
+| Any other symbol metadata (e.g. `:smoke`)      | Becomes a tag on `case.tags`.                             |
+| `it 'foo', tags: %w[smoke regression]`         | Adds explicit tags.                                       |
+| `with_them` rows (rspec-parameterized)         | Each row's variables → `case.parameters[]`.               |
+
+```ruby
+require 'kensho/rspec'
+
+RSpec.describe 'Cart' do
+  Kensho::Feature('Cart')
+  Kensho::Epic('Checkout')
+
+  it 'totals correctly', :critical, owner: 'alice',
+     kensho_labels: { team: 'growth' },
+     kensho_links: [{ kind: 'jira', url: 'https://jira.example.com/browse/PROJ-123', label: 'PROJ-123' }] do
+    expect(1 + 1).to eq(2)
+  end
+end
+```
+
+## Helper API
+
+```ruby
+require 'kensho/rspec'
+
+RSpec.describe 'Login' do
+  it 'submits credentials' do
+    Kensho.step('open the login page') do
+      visit '/login'
+    end
+
+    Kensho.step('submit credentials') do
+      fill_in 'user', with: 'demo'
+      click_button 'Sign in'
+
+      Kensho.step('verify redirect') do
+        expect(page.current_url).to end_with('/home')
+      end
+    end
+
+    Kensho.label('team', 'growth')
+    Kensho.link('https://jira.example.com/browse/PROJ-123',
+                kind: 'jira', label: 'PROJ-123')
+
+    page.save_screenshot('/tmp/login.png')
+    Kensho.attach('/tmp/login.png', kind: 'screenshot')
+  end
+end
+```
+
+| Helper                                          | What it does                                            |
+| ----------------------------------------------- | ------------------------------------------------------- |
+| `Kensho.step(title, action: nil) { ... }`       | Opens a Kensho step, nesting automatically. On exception the step is marked `fail` and the exception re-raises. |
+| `Kensho.attach(path, kind: nil, name: nil, mime_type: nil)` | Copies the file into `kensho-results/attachments/<caseId>/` and registers it on the current case (or current step if one is open). |
+| `Kensho.label(key, value)`                      | Adds a string label to the case.                        |
+| `Kensho.link(url, kind: nil, label: nil)`       | Adds a hyperlink to the case.                           |
+| `Kensho.current_case_id`                        | Returns the stable case id of the running test, or `nil`. |
+
+All five are no-ops outside a running example.
+
+## Captured stdout / stderr → logs
+
+Every `puts` (or `$stderr.write`) the example emits is captured and
+forwarded into `case.logs[]`. The `t` field is currently always `0`
+(per-line offsets are coming).
+
+## Status mapping
+
+| RSpec outcome              | Kensho status |
+| -------------------------- | ------------- |
+| passed                     | `pass`        |
+| failed (Expectation error) | `fail`        |
+| failed (other exception)   | `broken`      |
+| pending / skipped          | `skip`        |
+
+A pending example's `pending_message` becomes the first entry in
+`case.logs[]`.
+
+## Environment auto-detected
+
+GitHub Actions, CircleCI, GitLab CI, Jenkins, Buildkite, Azure DevOps —
+CI provider, branch, commit, run URL, OS, architecture, Ruby version.
+
+Pass `KR_AUTHOR`, `KR_COMMIT_MSG`, `KR_STAGE`, `KR_BASE_URL`,
+`KR_APP_VERSION`, `KR_BUILD_NUMBER`, `KR_RELEASE`, `KR_REGION`,
+`KR_LOCALE`, `KR_TRIGGER`, or `KR_FEATURE` as env vars to populate the
+matching fields on `run.env`.
+
+## CLI / env flags
+
+There is no formatter-options DSL because RSpec doesn't pass formatter
+arguments through reliably across versions. Configuration goes through
+env vars:
+
+```
+KENSHO_OUTPUT                 output dir (default ./kensho-results)
+KENSHO_PROJECT_NAME           project name in run.json
+KENSHO_PROJECT_SLUG           project slug
+KENSHO_RUN_ID                 override the auto-generated run id
+KENSHO_NO_SEVERITY_FROM_META  set to "1" to disable severity-from-meta
+```
+
+## Design notes
+
+- Zero runtime dependencies beyond `rspec-core` itself. The schema lives
+  in the JS workspace; we vendor the minimum (id-hashing, status
+  mapping, env capture) inline so the gem installs in seconds.
+- The formatter never raises out of a hook — a broken adapter must not
+  break a test run.
+- IDs are stable across adapters: the FNV-1a hash matches the JS
+  `stableCaseId` byte-for-byte, so `rspec` and `playwright` runs of the
+  same suite roll up to the same history on the platform.
+
+## License
+
+Apache-2.0.

data/lib/kensho/_schema.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+# Vendored slice of the Kensho v1 schema contract.
+#
+# We deliberately do not depend on the JS @kaizenreport/kensho-schema package.
+# Adapters need to stay tiny and standalone, so we re-implement the few things
+# the formatter cares about: the stable case-id hash, the status enum, the
+# attachment kind/MIME tables, and the environment-capture function.
+
+require 'rbconfig'
+
+module Kensho
+  module Schema
+    SCHEMA_VERSION = 'kensho/v1'
+
+    STATUS = %w[pass fail broken skip].freeze
+    STEP_STATUS = %w[pass fail skip].freeze
+    SEVERITY = %w[blocker critical normal minor trivial].freeze
+    ATTACHMENT_KINDS = %w[
+      screenshot video trace har text json html dom-snapshot log
+    ].freeze
+
+    MIME_BY_EXT = {
+      '.png'  => 'image/png',
+      '.jpg'  => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.webp' => 'image/webp',
+      '.webm' => 'video/webm',
+      '.mp4'  => 'video/mp4',
+      '.zip'  => 'application/zip',
+      '.html' => 'text/html',
+      '.json' => 'application/json',
+      '.txt'  => 'text/plain',
+      '.log'  => 'text/plain',
+      '.har'  => 'application/json'
+    }.freeze
+
+    KIND_BY_EXT = {
+      '.png'  => 'screenshot',
+      '.jpg'  => 'screenshot',
+      '.jpeg' => 'screenshot',
+      '.webp' => 'screenshot',
+      '.webm' => 'video',
+      '.mp4'  => 'video',
+      '.zip'  => 'trace',
+      '.html' => 'html',
+      '.json' => 'json',
+      '.txt'  => 'text',
+      '.log'  => 'log',
+      '.har'  => 'har'
+    }.freeze
+
+    FNV_OFFSET_1 = 0x811c9dc5
+    FNV_OFFSET_2 = 0x01000193
+    FNV_PRIME_1  = 0x01000193
+    FNV_PRIME_2  = 0x85ebca6b
+    MASK32       = 0xffffffff
+
+    # Mirrors stableCaseId from packages/schema/index.js byte-for-byte:
+    # double FNV-1a with two different secondary primes so the two 32-bit
+    # chunks come from independent rolling states. Must stay byte-compatible
+    # with the JS implementation or test history won't line up across
+    # adapters.
+    def self.stable_case_id(full_name, file_path)
+      s = "#{full_name || ''}::#{file_path || ''}"
+      h1 = FNV_OFFSET_1
+      h2 = FNV_OFFSET_2
+      s.each_codepoint do |c|
+        h1 = ((h1 ^ c) * FNV_PRIME_1) & MASK32
+        h2 = ((h2 ^ c) * FNV_PRIME_2) & MASK32
+      end
+      format('tc_%08x%08x', h1, h2)
+    end
+
+    def self.kind_and_mime_for(path)
+      ext = File.extname(path.to_s).downcase
+      [KIND_BY_EXT[ext] || 'text', MIME_BY_EXT[ext] || 'application/octet-stream']
+    end
+
+    def self.normalize_os
+      host = RbConfig::CONFIG['host_os'].to_s.downcase
+      return 'linux'  if host.include?('linux')
+      return 'darwin' if host.include?('darwin')
+      return 'win32'  if host.include?('mswin') || host.include?('mingw') || host.include?('cygwin')
+
+      host
+    end
+
+    # Normalize SSH-style git URLs to https. ``git@github.com:foo/bar.git``
+    # becomes ``https://github.com/foo/bar``; trailing ``.git`` is dropped.
+    def self.normalize_git_url(u)
+      return nil if u.nil? || u.empty?
+
+      m = u.match(%r{^(?:ssh://)?git@([^:/]+)[:/](.+?)(?:\.git)?$})
+      return "https://#{m[1]}/#{m[2]}" if m
+
+      u.sub(/\.git\z/, '')
+    end
+
+    # CI / environment metadata for run.env. Matches the helpers in the JS
+    # adapters so a Kensho report looks the same regardless of language.
+    def self.env_info(framework_version: nil)
+      ci_env = ENV['CI']
+      ci =
+        if ci_env && ENV['GITHUB_ACTIONS']
+          'github-actions'
+        elsif ci_env && ENV['CIRCLECI']
+          'circleci'
+        elsif ci_env && ENV['GITLAB_CI']
+          'gitlab'
+        elsif ci_env && ENV['JENKINS_URL']
+          'jenkins'
+        elsif ci_env && ENV['BUILDKITE']
+          'buildkite'
+        elsif ci_env && ENV['TF_BUILD']
+          'azure-devops'
+        elsif ci_env
+          'unknown'
+        else
+          'local'
+        end
+
+      branch = ENV['GITHUB_REF_NAME'] || ENV['CIRCLE_BRANCH'] ||
+               ENV['CI_COMMIT_REF_NAME'] || ENV['BUILDKITE_BRANCH']
+      commit = ENV['GITHUB_SHA'] || ENV['CIRCLE_SHA1'] ||
+               ENV['CI_COMMIT_SHA'] || ENV['BUILDKITE_COMMIT']
+      author = ENV['KR_AUTHOR'] || ENV['GITHUB_ACTOR']
+      commit_msg = ENV['KR_COMMIT_MSG']
+
+      run_url = ENV['KR_RUN_URL'] ||
+        if ENV['GITHUB_SERVER_URL'] && ENV['GITHUB_REPOSITORY'] && ENV['GITHUB_RUN_ID']
+          "#{ENV['GITHUB_SERVER_URL']}/#{ENV['GITHUB_REPOSITORY']}/actions/runs/#{ENV['GITHUB_RUN_ID']}"
+        elsif ENV['CIRCLE_BUILD_URL']
+          ENV['CIRCLE_BUILD_URL']
+        elsif ENV['CI_JOB_URL']
+          ENV['CI_JOB_URL']
+        elsif ENV['BUILD_URL']
+          ENV['BUILD_URL']
+        elsif ENV['BUILDKITE_BUILD_URL']
+          ENV['BUILDKITE_BUILD_URL']
+        end
+
+      # repoUrl — KR_REPO_URL override → GitHub Actions / GitLab / Bitbucket /
+      # Azure / SSH-style URLs from CircleCI / Buildkite / Jenkins (normalized).
+      gh_server = ENV['GITHUB_SERVER_URL']
+      gh_repo   = ENV['GITHUB_REPOSITORY']
+      repo_url = ENV['KR_REPO_URL'] ||
+                 (gh_server && gh_repo ? "#{gh_server}/#{gh_repo}" : nil) ||
+                 ENV['CI_PROJECT_URL'] ||
+                 ENV['BITBUCKET_GIT_HTTP_ORIGIN'] ||
+                 normalize_git_url(ENV['BUILD_REPOSITORY_URI']) ||
+                 normalize_git_url(ENV['CIRCLE_REPOSITORY_URL'] ||
+                                   ENV['BUILDKITE_REPO'] ||
+                                   ENV['GIT_URL'])
+
+      info = {
+        'ci' => ci,
+        'os' => normalize_os,
+        'arch' => RbConfig::CONFIG['host_cpu'].to_s
+      }
+
+      ruby_version = "#{RUBY_VERSION}p#{defined?(RUBY_PATCHLEVEL) ? RUBY_PATCHLEVEL : '0'}"
+      info['vars'] = { 'rubyVersion' => ruby_version }
+      info['vars']['frameworkVersion'] = framework_version if framework_version
+
+      info['branch']     = branch     if branch
+      info['commit']     = commit     if commit
+      info['commitMsg']  = commit_msg if commit_msg
+      info['author']     = author     if author
+      info['runUrl']     = run_url    if run_url
+      info['repoUrl']    = repo_url   if repo_url
+      os_version = RbConfig::CONFIG['host_os']
+      info['osVersion'] = os_version if os_version
+
+      [
+        ['KR_STAGE', 'stage'],
+        ['KR_BASE_URL', 'baseUrl'],
+        ['KR_APP_VERSION', 'appVersion'],
+        ['KR_BUILD_NUMBER', 'buildNumber'],
+        ['KR_RELEASE', 'release'],
+        ['KR_REGION', 'region'],
+        ['KR_LOCALE', 'locale'],
+        ['KR_TRIGGER', 'trigger'],
+        ['KR_FEATURE', 'feature']
+      ].each do |env_var, key|
+        v = ENV[env_var]
+        info[key] = v if v && !v.empty?
+      end
+
+      info
+    end
+
+    def self.iso_now
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+    end
+
+    def self.iso_from_seconds(secs)
+      Time.at(secs).utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ')
+    end
+
+    def self.slugify(name)
+      s = name.to_s.downcase.strip
+      s = s.gsub(/[^a-z0-9_-]+/, '-').gsub(/\A-+|-+\z/, '')
+      s.empty? ? 'unknown' : s
+    end
+
+    def self.default_run_id
+      "run_#{Time.now.utc.strftime('%Y%m%d%H%M%S')}"
+    end
+  end
+end

data/lib/kensho/rspec/formatter.rb

@@ -0,0 +1,559 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'fileutils'
+require 'stringio'
+require 'set'
+require_relative '../_schema'
+require_relative 'state'
+require_relative 'helpers'
+
+# RSpec formatter that emits a Kensho v1 result bundle.
+#
+# Layout written under KENSHO_OUTPUT (default ./kensho-results):
+#
+#   kensho-results/
+#     run.json                 manifest (project, env, totals, framework, timing)
+#     cases/<stableId>.json    one file per example
+#     attachments/<caseId>/    files registered via Kensho.attach
+#
+# Register with RSpec:
+#
+#   rspec --format Kensho::RSpec::Formatter
+#
+# CLI flags / env vars (the formatter has no rspec-options DSL since
+# RSpec doesn't pass those through formatter args reliably; we use env
+# vars + the `.kensho.yml`-free philosophy of the JS adapters):
+#
+#   KENSHO_OUTPUT             output directory (default ./kensho-results)
+#   KENSHO_PROJECT_NAME       project name in run.json
+#   KENSHO_PROJECT_SLUG       project slug
+#   KENSHO_RUN_ID             override the auto-generated run id
+#   KENSHO_NO_SEVERITY_FROM_META  set to "1" to disable severity-from-metadata
+
+require 'rspec/core/formatters/base_formatter' unless defined?(::RSpec::Core::Formatters::BaseFormatter)
+
+module Kensho
+  module RSpec
+    class Formatter < ::RSpec::Core::Formatters::BaseFormatter
+      ::RSpec::Core::Formatters.register self,
+                                         :start,
+                                         :example_group_started,
+                                         :example_started,
+                                         :example_passed,
+                                         :example_failed,
+                                         :example_pending,
+                                         :stop
+
+      SEVERITY_KEYS = Kensho::Schema::SEVERITY.map(&:to_sym).freeze
+
+      # Metadata keys that aren't user tags. We prune these from the tag
+      # list so RSpec's housekeeping (location, type, file_path, etc.)
+      # doesn't pollute case.tags.
+      META_BLOCKLIST = %i[
+        absolute_file_path block default_path described_class description
+        described_class_name described_class_name described_at description_args
+        execution_result file_path file_path_proc full_description
+        kensho_feature kensho_epic kensho_story
+        last_run_status line_number location parent_example_group
+        rerun_file_path scoped_id severity shared_group_inclusions
+        shared_group_metadata shared_group_inclusion_backtrace
+        skip stack_frames type variants
+      ].to_set
+
+      def initialize(output = nil)
+        # RSpec's BaseFormatter wants an output IO; we never write to it,
+        # but we still hand one up so RSpec doesn't blow up.
+        super(output || StringIO.new)
+        @output_dir = File.expand_path(ENV['KENSHO_OUTPUT'] || (defined?(Kensho::RSpec::DEFAULT_OUTPUT) ? Kensho::RSpec::DEFAULT_OUTPUT : 'kensho-results'))
+        @cases_dir = File.join(@output_dir, 'cases')
+        @attachments_dir = File.join(@output_dir, 'attachments')
+        @project = {
+          'name' => ENV['KENSHO_PROJECT_NAME'] || 'Unknown project',
+          'slug' => ENV['KENSHO_PROJECT_SLUG'] || Kensho::Schema.slugify(ENV['KENSHO_PROJECT_NAME'] || 'unknown')
+        }
+        @run_id = ENV['KENSHO_RUN_ID'] || Kensho::Schema.default_run_id
+        @severity_from_meta = ENV['KENSHO_NO_SEVERITY_FROM_META'].to_s.empty?
+        @started_at = Kensho::Schema.iso_now
+        @started_perf = monotonic_now
+        @rootpath = Dir.pwd
+
+        @cases_by_id = {}
+        @ids_seen = Hash.new(0)
+        @groups = {}
+
+        FileUtils.mkdir_p(@cases_dir)
+        FileUtils.mkdir_p(@attachments_dir)
+
+        Kensho::RSpec::State.formatter = self
+        install_capture_hook!
+      end
+
+      # Tee stdout/stderr around each example into the per-case scratch so
+      # case.logs[] picks up `puts` calls without the user having to do
+      # anything. RSpec doesn't expose a "captured output" API for
+      # arbitrary formatters, so we install a global before/after hook.
+      def install_capture_hook!
+        return if @capture_installed
+
+        @capture_installed = true
+        ::RSpec.configure do |config|
+          config.before(:each) do
+            scratch = Kensho::RSpec::State.current
+            next unless scratch
+
+            stdout_io = StringIO.new
+            stderr_io = StringIO.new
+            scratch.instance_variable_set(:@orig_stdout, $stdout)
+            scratch.instance_variable_set(:@orig_stderr, $stderr)
+            scratch.instance_variable_set(:@stdout_io, stdout_io)
+            scratch.instance_variable_set(:@stderr_io, stderr_io)
+            $stdout = stdout_io
+            $stderr = stderr_io
+          end
+
+          config.after(:each) do
+            scratch = Kensho::RSpec::State.current
+            next unless scratch
+
+            stdout_io = scratch.instance_variable_get(:@stdout_io)
+            stderr_io = scratch.instance_variable_get(:@stderr_io)
+            orig_out = scratch.instance_variable_get(:@orig_stdout)
+            orig_err = scratch.instance_variable_get(:@orig_stderr)
+            $stdout = orig_out if orig_out
+            $stderr = orig_err if orig_err
+            scratch.instance_variable_set(:@stdout_text, stdout_io.string) if stdout_io
+            scratch.instance_variable_set(:@stderr_text, stderr_io.string) if stderr_io
+          end
+        end
+      end
+
+      # ----- lifecycle hooks ----- #
+
+      def start(_notification); end
+
+      def example_group_started(notification)
+        group = notification.group
+        @groups[group.metadata[:scoped_id] || group.object_id] = collect_group_meta(group)
+      end
+
+      def example_started(notification)
+        example = notification.example
+        case_obj = build_case(example)
+        scratch = CaseScratch.new(
+          case_id: case_obj['id'],
+          example_id: example.id,
+          started_at_ms: (Time.now.to_f * 1000.0)
+        )
+        scratch.instance_variable_set(:@case_obj, case_obj)
+        scratch.instance_variable_set(:@stdout_capture, StringIO.new)
+        scratch.instance_variable_set(:@stderr_capture, StringIO.new)
+        State.current = scratch
+
+        @cases_by_id[case_obj['id']] = case_obj
+      end
+
+      def example_passed(notification)
+        finalize(notification.example, 'pass', nil)
+      end
+
+      def example_failed(notification)
+        ex = notification.example.execution_result.exception
+        status =
+          if ex && (ex.class.name == 'RSpec::Expectations::ExpectationNotMetError')
+            'fail'
+          elsif ex
+            'broken'
+          else
+            'fail'
+          end
+        finalize(notification.example, status, ex)
+      end
+
+      def example_pending(notification)
+        finalize(notification.example, 'skip', nil)
+      end
+
+      def stop(_notification)
+        write_run_json
+      ensure
+        State.formatter = nil
+      end
+
+      # ----- internals ----- #
+
+      def register_attachment(scratch, src_path, kind:, name:, mime_type:)
+        return nil unless File.file?(src_path)
+
+        attachments_root = File.join(@attachments_dir, scratch.case_id)
+        FileUtils.mkdir_p(attachments_root)
+        att_id = "att_#{SecureRandom.hex(4)}"
+        dest_name = name || File.basename(src_path)
+        dest = File.join(attachments_root, "#{att_id}_#{dest_name}")
+        begin
+          FileUtils.cp(src_path, dest)
+        rescue StandardError => e
+          warn "[kensho] failed to copy #{src_path}: #{e.message}"
+          return nil
+        end
+
+        guessed_kind, guessed_mime = Kensho::Schema.kind_and_mime_for(src_path)
+        rel = relpath(dest, @output_dir)
+        record = {
+          'id'           => att_id,
+          'kind'         => kind || guessed_kind,
+          'relativePath' => rel,
+          'mimeType'     => mime_type || guessed_mime
+        }
+        begin
+          record['sizeBytes'] = File.size(dest)
+        rescue StandardError
+          # best-effort
+        end
+        record
+      end
+
+      private
+
+      def build_case(example)
+        full_name = example.full_description
+        file_path = relpath(example.metadata[:file_path] || example.metadata[:absolute_file_path], @rootpath)
+        line = example.metadata[:line_number]
+
+        base_id = Kensho::Schema.stable_case_id(full_name, file_path)
+        seen = @ids_seen[base_id]
+        case_id = seen.zero? ? base_id : "#{base_id}_#{seen + 1}"
+        @ids_seen[base_id] = seen + 1
+
+        suite = collect_suite_chain(example)
+        name = example.description.to_s
+
+        meta = example.metadata
+        tags = collect_tags(meta)
+        labels = collect_labels(meta)
+        links = collect_links(meta)
+        params = collect_parameters(meta)
+
+        severity = collect_severity(meta) if @severity_from_meta
+
+        behavior = {}
+        feature = walk_meta(meta, :kensho_feature) || walk_meta(meta, :feature)
+        epic = walk_meta(meta, :kensho_epic) || walk_meta(meta, :epic)
+        story = walk_meta(meta, :kensho_story) || walk_meta(meta, :story)
+        behavior['feature']  = feature.to_s if feature
+        behavior['epic']     = epic.to_s    if epic
+        behavior['scenario'] = story.to_s   if story
+
+        owner = meta[:owner]
+        description = meta[:kensho_description] || meta[:description_text]
+
+        case_obj = {
+          'id'        => case_id,
+          'name'      => name,
+          'fullName'  => full_name,
+          'status'    => 'skip',
+          'startedAt' => @started_at,
+          'duration'  => 0,
+          'retries'   => 0
+        }
+        case_obj['filePath']    = file_path if file_path
+        case_obj['line']        = line.to_i if line
+        case_obj['suite']       = suite     unless suite.empty?
+        case_obj['tags']        = tags      unless tags.empty?
+        case_obj['severity']    = severity  if severity
+        case_obj['owner']       = owner.to_s if owner
+        case_obj['behavior']    = behavior  unless behavior.empty?
+        case_obj['labels']      = labels    unless labels.empty?
+        case_obj['links']       = links     unless links.empty?
+        case_obj['parameters']  = params    unless params.empty?
+        case_obj['description'] = description.to_s if description && !description.to_s.empty?
+        case_obj['platform']    = Kensho::Schema.normalize_os
+        case_obj
+      end
+
+      def finalize(example, status, exception)
+        scratch = State.current
+        return unless scratch
+
+        case_obj = scratch.instance_variable_get(:@case_obj)
+        result = example.execution_result
+
+        started_ms = scratch.started_at_ms
+        finished_ms = (result.finished_at || Time.now).to_f * 1000.0
+        duration_secs = result.run_time
+        duration_ms =
+          if duration_secs.is_a?(Numeric)
+            (duration_secs * 1000.0).round
+          else
+            (finished_ms - started_ms).round
+          end
+        duration_ms = 0 if duration_ms.negative?
+
+        case_obj['status']     = status
+        case_obj['startedAt']  = Kensho::Schema.iso_from_seconds(started_ms / 1000.0)
+        case_obj['finishedAt'] = Kensho::Schema.iso_from_seconds(finished_ms / 1000.0)
+        case_obj['duration']   = duration_ms
+
+        # Pending/skip messages from RSpec become a log entry so the report
+        # surfaces the reason.
+        if status == 'skip' && result.pending_message
+          case_obj['logs'] ||= []
+          case_obj['logs'] << { 't' => 0, 'level' => 'info', 'msg' => result.pending_message.to_s }
+        end
+
+        if exception
+          err = { 'message' => first_line(exception.message.to_s) || exception.class.name.to_s }
+          stack_text = format_exception(exception)
+          err['stack'] = stack_text if stack_text && !stack_text.empty?
+          err['type']  = exception.class.name.to_s
+          case_obj['errors'] = [err]
+        end
+
+        # Auto-close any steps the user forgot to exit. Mark them broken so
+        # the report makes the leak visible.
+        until scratch.step_stack.empty?
+          leaked = scratch.step_stack.pop
+          leaked['status'] ||= 'broken'
+          leaked['duration'] ||= 0
+          leaked.delete('_started_perf')
+        end
+
+        case_obj['steps']       = scratch.steps       unless scratch.steps.empty?
+        case_obj['attachments'] = scratch.attachments unless scratch.attachments.empty?
+        if !scratch.labels.empty?
+          existing = case_obj['labels'] || {}
+          case_obj['labels'] = existing.merge(scratch.labels)
+        end
+        if !scratch.links.empty?
+          existing = case_obj['links'] || []
+          case_obj['links'] = existing + scratch.links
+        end
+
+        # Stdout/stderr captured by RSpec is wired up by an around-each
+        # hook (see Kensho::RSpec::Formatter.install_capture_hook) — see
+        # below.
+        captured_stdout = scratch.instance_variable_get(:@stdout_text)
+        captured_stderr = scratch.instance_variable_get(:@stderr_text)
+        capture_logs = []
+        if captured_stdout && !captured_stdout.empty?
+          captured_stdout.each_line { |ln| capture_logs << { 't' => 0, 'level' => 'info', 'msg' => ln.rstrip } }
+        end
+        if captured_stderr && !captured_stderr.empty?
+          captured_stderr.each_line { |ln| capture_logs << { 't' => 0, 'level' => 'warn', 'msg' => ln.rstrip } }
+        end
+        unless capture_logs.empty?
+          case_obj['logs'] = (case_obj['logs'] || []) + capture_logs
+        end
+
+        write_case(case_obj)
+      ensure
+        State.current = nil
+      end
+
+      def write_case(case_obj)
+        path = File.join(@cases_dir, "#{case_obj['id']}.json")
+        File.write(path, JSON.pretty_generate(case_obj))
+      rescue StandardError => e
+        warn "[kensho] could not write #{File.basename(path)}: #{e.message}"
+      end
+
+      def write_run_json
+        finished_at = Kensho::Schema.iso_now
+        cases = @cases_by_id.values
+        totals = { 'pass' => 0, 'fail' => 0, 'broken' => 0, 'skip' => 0 }
+        cases.each { |c| totals[c['status']] += 1 if totals.key?(c['status']) }
+        duration_ms = [((monotonic_now - @started_perf) * 1000.0).round, 0].max
+        framework_version = (defined?(::RSpec::Core::Version) ? ::RSpec::Core::Version::STRING : 'unknown')
+
+        run = {
+          'schemaVersion' => Kensho::Schema::SCHEMA_VERSION,
+          'id'            => @run_id,
+          'project'       => @project,
+          'framework'     => { 'name' => 'rspec', 'version' => framework_version },
+          'env'           => Kensho::Schema.env_info(framework_version: framework_version),
+          'startedAt'     => @started_at,
+          'finishedAt'    => finished_at,
+          'totals'        => totals,
+          'durationMs'    => duration_ms,
+          'testCases'     => cases
+        }
+        File.write(File.join(@output_dir, 'run.json'), JSON.pretty_generate(run))
+      rescue StandardError => e
+        warn "[kensho] failed to write run.json: #{e.message}"
+      end
+
+      # ----- metadata extraction ----- #
+
+      def collect_severity(meta)
+        sev = meta[:severity]
+        return sev.to_s if sev.is_a?(String) && Kensho::Schema::SEVERITY.include?(sev.to_s)
+        return sev.to_s if sev.is_a?(Symbol) && Kensho::Schema::SEVERITY.include?(sev.to_s)
+
+        # `it 'foo', :critical do ... end` style — RSpec stores those as
+        # `meta[:critical] = true`.
+        SEVERITY_KEYS.each do |key|
+          return key.to_s if meta[key] == true
+        end
+        # `severity_blocker: true` style.
+        SEVERITY_KEYS.each do |key|
+          composite = "severity_#{key}".to_sym
+          return key.to_s if meta[composite] == true
+        end
+        nil
+      end
+
+      def collect_tags(meta)
+        tags = []
+        meta.each do |k, v|
+          next if META_BLOCKLIST.include?(k)
+          next if k.to_s.start_with?('rerun_', 'shared_', 'kensho_')
+
+          if v == true && k.is_a?(Symbol)
+            next if SEVERITY_KEYS.include?(k)
+
+            tags << k.to_s
+          end
+        end
+        # `tags: [...]` explicit array.
+        if meta[:tags].is_a?(Array)
+          meta[:tags].each { |t| tags << t.to_s unless tags.include?(t.to_s) }
+        end
+        tags
+      end
+
+      def collect_labels(meta)
+        labels = {}
+        if meta[:kensho_labels].is_a?(Hash)
+          meta[:kensho_labels].each { |k, v| labels[k.to_s] = v.to_s unless v.nil? }
+        end
+        labels
+      end
+
+      def collect_links(meta)
+        links = []
+        raw = meta[:kensho_links]
+        Array(raw).each do |entry|
+          case entry
+          when Hash
+            url = entry[:url] || entry['url']
+            next unless url
+
+            link = { 'url' => url.to_s }
+            kind = entry[:kind] || entry['kind']
+            label = entry[:label] || entry['label']
+            link['kind']  = kind.to_s  if kind
+            link['label'] = label.to_s if label
+            links << link
+          when String
+            links << { 'url' => entry }
+          end
+        end
+        links
+      end
+
+      def collect_parameters(meta)
+        params = []
+        # rspec-parameterized's with_them puts data row in :variants.
+        if meta[:variants].is_a?(Hash)
+          meta[:variants].each do |k, v|
+            params << { 'name' => k.to_s, 'value' => stringify(v), 'kind' => 'data-row' }
+          end
+        end
+        # Conventional `it 'does X', params: { foo: 1 } do` shape.
+        if meta[:params].is_a?(Hash)
+          meta[:params].each do |k, v|
+            next if params.any? { |p| p['name'] == k.to_s }
+
+            params << { 'name' => k.to_s, 'value' => stringify(v), 'kind' => 'argument' }
+          end
+        end
+        params
+      end
+
+      def collect_group_meta(group)
+        m = group.metadata
+        {
+          feature: m[:kensho_feature] || m[:feature],
+          epic:    m[:kensho_epic]    || m[:epic],
+          story:   m[:kensho_story]   || m[:story]
+        }
+      end
+
+      def walk_meta(meta, key)
+        return meta[key] if meta[key]
+
+        parent = meta[:parent_example_group]
+        return nil unless parent
+
+        walk_meta(parent, key)
+      end
+
+      def collect_suite_chain(example)
+        chain = []
+        group = example.example_group
+        if group.respond_to?(:parent_groups)
+          # parent_groups[0] is `group` itself, last is the outermost group.
+          group.parent_groups.each do |g|
+            desc = g.metadata[:description]
+            chain.unshift(desc.to_s) if desc && !desc.to_s.empty?
+          end
+        else
+          desc = group.metadata[:description]
+          chain << desc.to_s if desc
+        end
+        chain
+      end
+
+      def relpath(path, root)
+        return nil unless path
+
+        absolute_path = File.absolute_path(path.to_s)
+        absolute_root = File.absolute_path(root.to_s)
+        if absolute_path.start_with?(absolute_root + File::SEPARATOR)
+          absolute_path[(absolute_root.length + 1)..]
+        else
+          path.to_s.sub(%r{\A\./}, '')
+        end
+      end
+
+      def stringify(v)
+        case v
+        when String then v
+        when Symbol then v.to_s
+        when Numeric, TrueClass, FalseClass, NilClass then v.inspect
+        else
+          begin
+            v.inspect
+          rescue StandardError
+            '<unrepr>'
+          end
+        end
+      end
+
+      def format_exception(exception)
+        return nil unless exception
+
+        lines = [exception.message.to_s]
+        if exception.backtrace
+          lines.concat(exception.backtrace.first(20))
+        end
+        lines.join("\n")
+      end
+
+      def first_line(s)
+        return nil unless s
+
+        s.to_s.each_line do |line|
+          stripped = line.strip
+          return stripped unless stripped.empty?
+        end
+        nil
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/kensho/rspec/helpers.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'fileutils'
+
+# Public helper API used inside RSpec examples.
+#
+#   Kensho.step('open the login page') { ... }       # nests automatically
+#   Kensho.attach('/tmp/login.png', kind: 'screenshot')
+#   Kensho.label('team', 'growth')
+#   Kensho.link('https://jira.example.com/browse/PROJ-123', kind: 'jira', label: 'PROJ-123')
+#   Kensho.current_case_id  # stable id of the running test, or nil
+#
+# All helpers are no-ops outside an example so they're safe to call from
+# shared utility code that may run outside a test context.
+#
+# Top-level Kensho::Feature/Epic/Story sugar lets the spec author tag an
+# example group without typing :metadata twice. They mirror how the
+# pytest plugin exposes @feature/@epic/@story marks.
+
+module Kensho
+  class << self
+    def step(title, action: nil)
+      scratch = Kensho::RSpec::State.current
+      unless scratch
+        return yield({}) if block_given?
+
+        return {}
+      end
+
+      started_perf = monotonic_now
+      step_obj = {
+        'id'        => "step_#{SecureRandom.hex(5)}",
+        'title'     => title.to_s,
+        'status'    => 'pass',
+        'startedAt' => Kensho::Schema.iso_now,
+        'duration'  => 0,
+        '_started_perf' => started_perf
+      }
+      step_obj['action'] = action.to_s if action
+
+      parent = scratch.step_stack.last
+      if parent
+        (parent['children'] ||= []) << step_obj
+      else
+        scratch.steps << step_obj
+      end
+      scratch.step_stack << step_obj
+
+      result = nil
+      begin
+        result = block_given? ? yield(step_obj) : nil
+      rescue StandardError, ::RSpec::Expectations::ExpectationNotMetError => e
+        step_obj['status'] = 'fail'
+        close_step!(step_obj, started_perf)
+        scratch.step_stack.pop if scratch.step_stack.last.equal?(step_obj)
+        raise e
+      end
+
+      close_step!(step_obj, started_perf)
+      scratch.step_stack.pop if scratch.step_stack.last.equal?(step_obj)
+      result
+    end
+
+    def attach(path, kind: nil, name: nil, mime_type: nil)
+      scratch = Kensho::RSpec::State.current
+      formatter = Kensho::RSpec::State.formatter
+      return nil unless scratch && formatter
+
+      record = formatter.register_attachment(
+        scratch,
+        path.to_s,
+        kind: kind,
+        name: name,
+        mime_type: mime_type
+      )
+      return nil unless record
+
+      if scratch.step_stack.last
+        (scratch.step_stack.last['attachments'] ||= []) << record
+      else
+        scratch.attachments << record
+      end
+      record
+    end
+
+    def label(key, value)
+      scratch = Kensho::RSpec::State.current
+      return if scratch.nil? || key.nil? || key.to_s.empty?
+
+      scratch.labels[key.to_s] = value.to_s
+      nil
+    end
+
+    def link(url, kind: nil, label: nil)
+      scratch = Kensho::RSpec::State.current
+      return if scratch.nil? || url.nil? || url.to_s.empty?
+
+      entry = { 'url' => url.to_s }
+      entry['kind']  = kind.to_s  if kind
+      entry['label'] = label.to_s if label
+      scratch.links << entry
+      nil
+    end
+
+    def current_case_id
+      scratch = Kensho::RSpec::State.current
+      scratch ? scratch.case_id : nil
+    end
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def close_step!(step_obj, started_perf)
+      step_obj['duration'] = [(((monotonic_now - started_perf) * 1000.0).round), 0].max
+      step_obj.delete('_started_perf')
+    end
+  end
+
+  # Top-level sugar so spec authors can write `Kensho::Feature('Cart')` etc.
+  # inside a describe block. These are module methods (uppercase method
+  # names are legal in Ruby) that walk the binding to find the example
+  # group whose `describe` block is currently executing and set metadata
+  # on it.
+  def self.Feature(name)
+    apply_behavior(:kensho_feature, name)
+  end
+
+  def self.Epic(name)
+    apply_behavior(:kensho_epic, name)
+  end
+
+  def self.Story(name)
+    apply_behavior(:kensho_story, name)
+  end
+
+  def self.apply_behavior(key, value)
+    group = Kensho::RSpec::State.current_group
+    return unless group
+
+    group.metadata[key] = value.to_s
+    nil
+  end
+
+  # Lowercase aliases for callers who'd rather not use uppercase methods.
+  class << self
+    alias_method :feature, :Feature
+    alias_method :epic,    :Epic
+    alias_method :story,   :Story
+  end
+end
+
+# Hook into RSpec's example-group definition so we can track the
+# currently-defining group. RSpec calls `subclass` for every nested
+# describe; we wrap it to push/pop a stack on the State module.
+module Kensho
+  module RSpec
+    # Hook RSpec's example-group definition so Kensho::Feature/Epic/Story
+    # can find the group whose describe block is currently executing.
+    # We override `module_exec` on the freshly-built subclass to push the
+    # class onto a tracking stack while RSpec evaluates the user body.
+    module GroupTracker
+      def subclass(parent, description, args, registration_collection, &example_group_block)
+        wrapped = nil
+        if example_group_block
+          tracker = Kensho::RSpec::State
+          wrapped = lambda do |*lambda_args|
+            tracker.push_group(self)
+            begin
+              instance_exec(*lambda_args, &example_group_block)
+            ensure
+              tracker.pop_group
+            end
+          end
+        end
+        super(parent, description, args, registration_collection, &(wrapped || example_group_block))
+      end
+    end
+  end
+end
+
+if defined?(::RSpec::Core::ExampleGroup)
+  ::RSpec::Core::ExampleGroup.singleton_class.prepend(Kensho::RSpec::GroupTracker)
+end

data/lib/kensho/rspec/state.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Per-example mutable state used by the public helper API.
+#
+# The formatter sets the current scratch on each example_started and clears
+# it on example_passed/failed/pending. While an example is running, the
+# Kensho.step / Kensho.attach / Kensho.label / Kensho.link helpers mutate
+# the scratch directly so the formatter can pick up the data when it
+# finalizes the case.
+#
+# RSpec runs examples sequentially within a worker by default; we still use
+# Thread.current so threaded fixtures (rare) don't race.
+
+module Kensho
+  module RSpec
+    class CaseScratch
+      attr_accessor :case_id, :example_id, :started_at_ms,
+                    :steps, :step_stack, :attachments, :logs, :labels, :links
+
+      def initialize(case_id:, example_id:, started_at_ms:)
+        @case_id = case_id
+        @example_id = example_id
+        @started_at_ms = started_at_ms
+        @steps = []
+        @step_stack = []
+        @attachments = []
+        @logs = []
+        @labels = {}
+        @links = []
+      end
+    end
+
+    module State
+      THREAD_KEY = :__kensho_rspec_scratch__
+      GROUP_STACK_KEY = :__kensho_rspec_group_stack__
+
+      def self.current
+        Thread.current[THREAD_KEY]
+      end
+
+      def self.current=(scratch)
+        Thread.current[THREAD_KEY] = scratch
+      end
+
+      def self.push_group(group)
+        (Thread.current[GROUP_STACK_KEY] ||= []) << group
+      end
+
+      def self.pop_group
+        stack = Thread.current[GROUP_STACK_KEY]
+        stack&.pop
+      end
+
+      def self.current_group
+        stack = Thread.current[GROUP_STACK_KEY]
+        stack ? stack.last : nil
+      end
+
+      class << self
+        attr_accessor :formatter
+      end
+    end
+  end
+end

data/lib/kensho/rspec/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kensho
+  module RSpec
+    VERSION = '0.1.1'
+  end
+end

data/lib/kensho/rspec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Public entrypoint for kensho-rspec.
+#
+# Usage:
+#   require 'kensho/rspec'
+#   rspec --format Kensho::RSpec::Formatter
+#
+# The helper API (Kensho.step, Kensho.attach, Kensho.label, Kensho.link,
+# Kensho.current_case_id) is wired up here so test code only needs one
+# `require`. All four helpers are no-ops outside a running example, so it
+# is safe to call them from shared utility code.
+
+require_relative '_schema'
+require_relative 'rspec/version'
+require_relative 'rspec/state'
+require_relative 'rspec/helpers'
+require_relative 'rspec/formatter'
+
+module Kensho
+  module RSpec
+    DEFAULT_OUTPUT = 'kensho-results'
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: kensho-rspec
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- KaizenReport
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  RSpec 3+ formatter that writes a Kensho v1 result bundle (run.json +
+  cases/<id>.json + attachments/) into ./kensho-results. Plus a tiny
+  helper API (Kensho.step / Kensho.attach / Kensho.label / Kensho.link)
+  for surfacing structured metadata from inside examples.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/kensho/_schema.rb
+- lib/kensho/rspec.rb
+- lib/kensho/rspec/formatter.rb
+- lib/kensho/rspec/helpers.rb
+- lib/kensho/rspec/state.rb
+- lib/kensho/rspec/version.rb
+homepage: https://github.com/brandon1794/kensho
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/brandon1794/kensho
+  source_code_uri: https://github.com/brandon1794/kensho
+  bug_tracker_uri: https://github.com/brandon1794/kensho/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Kensho reporter for RSpec — emits Kensho v1 results that the Kensho CLI can
+  render into a static HTML report.
+test_files: []