kensho-cucumber-ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0c834a2f3e16b91817b5ff5a0f3501db6a4bce89b6be298daa6c276cc1a3c29
+  data.tar.gz: 1de5746a0de6e3df020b69d13b34ec7d40c9d428afe1d4ec5e5f0ad09b9bbcd1
+SHA512:
+  metadata.gz: 24e3668821a7b5c15a5cd615c1ff0ccc1c0a4ccdc7ef1354c15cca658a8778b4160b7ca9490cd80f591984dcfd26c4a3e005e46c85429866fcc6f559257ec47d
+  data.tar.gz: eb708f88ed8a8764587979513f8162af62ee9ecd7ed77c71f3e305d00c87d1cc2356872eb249b32e2fdc3aa2fb8440edfc86f7a2f8125883b79c42a2a90cbf69

data/README.md

@@ -0,0 +1,117 @@
+# kensho-cucumber-ruby
+
+A Cucumber 7+ formatter that emits the canonical [Kensho v1](../schema)
+JSON format. Run your suite, point the `kensho` CLI at `kensho-results/`,
+and get a self-contained static HTML report.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'cucumber'
+gem 'kensho-cucumber-ruby', require: false, group: :test
+```
+
+```bash
+bundle install
+```
+
+## Run
+
+```bash
+bundle exec cucumber --require kensho/cucumber --format Kensho::Cucumber::Formatter
+
+# render the HTML report (uses the JS CLI from the same monorepo):
+npx kensho generate
+npx kensho open
+```
+
+You can pin the formatter from `cucumber.yml`:
+
+```yaml
+default: --require kensho/cucumber --format Kensho::Cucumber::Formatter --format pretty
+```
+
+## What it produces
+
+- `kensho-results/run.json` — run manifest (project, env, totals, timing).
+- `kensho-results/cases/<stableId>.json` — one file per scenario.
+- `kensho-results/attachments/<caseId>/...` — anything `attach`ed in a step.
+
+Each case gets a **stable id** (`tc_<16 hex>`) hashed from
+`feature › scenario` + file path so test history correlates across runs
+and across adapters (the JS adapters use the same FNV-1a-based hash).
+
+## Mapping
+
+| Gherkin                                   | Kensho field                              |
+| ----------------------------------------- | ----------------------------------------- |
+| Feature                                   | `case.behavior.feature` and `case.suite[0]` |
+| Rule (parent of the scenario)             | `case.behavior.epic`                      |
+| Scenario name                             | `case.name` and `case.behavior.scenario`  |
+| Each Given/When/Then                      | one entry in `case.steps[]` (`title` includes the keyword) |
+| Data table on a step                      | `step.parameters[]` (kind: data-row)      |
+| Doc string on a step                      | `step.parameters[]` (kind: argument)      |
+
+## Tag conventions
+
+| Tag                                    | Effect                                                 |
+| -------------------------------------- | ------------------------------------------------------ |
+| `@critical`, `@blocker`, `@normal`, `@minor`, `@trivial` | Sets `case.severity`.                  |
+| `@severity:critical`                   | Same as above, explicit form.                          |
+| `@kensho.label.<key>=<value>`          | Adds `case.labels.<key> = '<value>'`.                  |
+| `@kensho.link.<kind>=<label>`          | Adds `case.links += { kind, label, url: label }`. Use for ticket IDs. |
+| `@kensho.url.<kind>=<https://…>`       | Adds `case.links += { kind, url }`. Use for full URLs. |
+| any other `@tag`                       | Becomes a tag on `case.tags`.                          |
+
+```gherkin
+@critical @smoke @kensho.label.team=growth @kensho.link.jira=PROJ-123
+Scenario: User can log in
+  Given a registered user
+  When  they submit valid credentials
+  Then  they land on the home page
+```
+
+## Status mapping
+
+| Cucumber outcome              | Kensho status |
+| ----------------------------- | ------------- |
+| passed                        | `pass`        |
+| failed                        | `fail`        |
+| pending                       | `skip`        |
+| skipped                       | `skip`        |
+| undefined / ambiguous         | `broken`      |
+
+## 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
+
+```
+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
+```
+
+## Design notes
+
+- Zero runtime dependencies beyond `cucumber` itself. The schema lives
+  in the JS workspace; we vendor the minimum (id-hashing, env capture)
+  inline so the gem installs in seconds.
+- The formatter never raises — broken adapters must not break a test
+  run.
+- Stable IDs match the JS `stableCaseId` byte-for-byte, so
+  `cucumber-ruby` and `cucumber-js` runs of the same `.feature` file
+  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/cucumber/formatter.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'securerandom'
+require_relative '../_schema'
+
+# Cucumber 7+ formatter that emits Kensho v1 results.
+#
+# Cucumber-Ruby's formatter API gives us a `Cucumber::Configuration` and a
+# `config.on_event(:event_name)` event bus. We subscribe to:
+#
+#   :test_run_started        — open the output dir
+#   :test_case_started       — start accumulating per-scenario data
+#   :test_step_finished      — append a step result
+#   :test_case_finished      — write cases/<id>.json
+#   :test_run_finished       — write run.json
+#
+# Each scenario becomes a Kensho case; each Gherkin step becomes a Kensho
+# step. Data tables on a step are emitted as `step.parameters[]`. The
+# scenario's `attach` calls (Cucumber's built-in attachment API) are
+# routed into `case.attachments[]`.
+#
+# Tags drive metadata:
+#
+#   @severity:critical          → case.severity
+#   @critical / @blocker / ...  → case.severity (shorthand)
+#   @kensho.label.team=growth   → case.labels.team = 'growth'
+#   @kensho.link.jira=PROJ-123  → case.links += { kind: 'jira', label: 'PROJ-123', url: 'PROJ-123' }
+#   @kensho.url.jira=https://…  → case.links (full url form)
+#   any other @tag              → case.tags
+
+module Kensho
+  module Cucumber
+    class Formatter
+      SEVERITY_TAGS = Kensho::Schema::SEVERITY.dup.freeze
+
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+        @ast_lookup = nil
+        if defined?(::Cucumber::Formatter::AstLookup)
+          begin
+            @ast_lookup = ::Cucumber::Formatter::AstLookup.new(config)
+          rescue StandardError
+            @ast_lookup = nil
+          end
+        end
+        @output_dir = File.expand_path(ENV['KENSHO_OUTPUT'] || (defined?(Kensho::Cucumber::DEFAULT_OUTPUT) ? Kensho::Cucumber::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
+        @started_at = Kensho::Schema.iso_now
+        @started_perf = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @rootpath = Dir.pwd
+        @cases_by_id = {}
+        @ids_seen = Hash.new(0)
+
+        # Per-test-case scratch keyed by test_case (Cucumber's TestCase obj).
+        @scratch = {}
+
+        FileUtils.mkdir_p(@cases_dir)
+        FileUtils.mkdir_p(@attachments_dir)
+
+        bind_events!
+      end
+
+      def bind_events!
+        return unless @config.respond_to?(:on_event)
+
+        @config.on_event(:test_case_started)  { |event| on_test_case_started(event) }
+        @config.on_event(:test_step_finished) { |event| on_test_step_finished(event) }
+        @config.on_event(:test_case_finished) { |event| on_test_case_finished(event) }
+        @config.on_event(:test_run_finished)  { |_event| on_test_run_finished }
+      end
+
+      # ------- per-event handlers ------- #
+
+      def on_test_case_started(event)
+        test_case = event.test_case
+        @current_test_case = test_case
+        scenario_name = test_case.name.to_s
+        feature_uri = test_case.location.file rescue nil
+        feature_uri ||= (test_case.respond_to?(:source_location) ? test_case.source_location.file : nil)
+        feature_name, rule_name = feature_and_rule(test_case)
+
+        full_name = [feature_name, scenario_name].compact.reject(&:empty?).join(' › ')
+        file_path = relpath(feature_uri, @rootpath)
+        line = (test_case.location.lines.first rescue nil) || (test_case.location.line rescue nil)
+
+        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
+
+        tags = (test_case.tags || []).map { |t| t.respond_to?(:name) ? t.name.to_s : t.to_s }
+        clean_tags = tags.map { |t| t.start_with?('@') ? t[1..] : t }
+
+        severity = severity_from_tags(clean_tags)
+        labels = labels_from_tags(clean_tags)
+        links = links_from_tags(clean_tags)
+
+        plain_tags = clean_tags.reject do |t|
+          t.start_with?('kensho.label.') || t.start_with?('kensho.link.') ||
+            t.start_with?('kensho.url.') || t.start_with?('severity:') ||
+            SEVERITY_TAGS.include?(t)
+        end
+
+        behavior = {}
+        behavior['feature']  = feature_name.to_s if feature_name && !feature_name.empty?
+        behavior['epic']     = rule_name.to_s    if rule_name && !rule_name.empty?
+        behavior['scenario'] = scenario_name     if scenario_name && !scenario_name.empty?
+
+        case_obj = {
+          'id'        => case_id,
+          'name'      => scenario_name,
+          'fullName'  => full_name,
+          'status'    => 'skip',
+          'startedAt' => Kensho::Schema.iso_now,
+          'duration'  => 0,
+          'retries'   => 0,
+          'platform'  => Kensho::Schema.normalize_os
+        }
+        case_obj['filePath'] = file_path if file_path
+        case_obj['line']     = line.to_i if line
+        case_obj['suite']    = [feature_name].compact.reject(&:empty?)
+        case_obj.delete('suite') if case_obj['suite'].empty?
+        case_obj['tags']     = plain_tags unless plain_tags.empty?
+        case_obj['severity'] = severity if severity
+        case_obj['labels']   = labels   unless labels.empty?
+        case_obj['links']    = links    unless links.empty?
+        case_obj['behavior'] = behavior unless behavior.empty?
+
+        scratch = {
+          case_obj: case_obj,
+          started_perf: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          started_iso: case_obj['startedAt'],
+          steps: [],
+          step_index: 0,
+          worst_status: 'pass',
+          first_error: nil,
+          first_exception: nil,
+          attachments: []
+        }
+        @scratch[test_case.object_id] = scratch
+      end
+
+      def on_test_step_finished(event)
+        test_case = @current_test_case
+        return unless test_case
+
+        scratch = @scratch[test_case.object_id]
+        return unless scratch
+
+        step = event.test_step
+        result = event.result
+
+        title, parameters = step_title_and_params(step)
+        # Cucumber emits hooks as test steps with no Gherkin source; skip
+        # those from the timeline so the report shows just the user steps.
+        return if title.nil?
+
+        status = map_step_status(result)
+        case_status = map_case_status(result)
+        if case_status == 'fail' || case_status == 'broken'
+          scratch[:worst_status] = case_status
+        elsif case_status == 'skip' && scratch[:worst_status] == 'pass'
+          scratch[:worst_status] = 'skip'
+        end
+
+        if (result.respond_to?(:failed?) && result.failed?) ||
+           (result.respond_to?(:exception) && result.exception)
+          scratch[:first_exception] ||= result.exception if result.respond_to?(:exception)
+          scratch[:first_error] ||= (result.respond_to?(:exception) && result.exception) ?
+                                    result.exception.message.to_s :
+                                    result.to_s
+        end
+
+        duration_ms = duration_ms_from_result(result)
+        idx = scratch[:step_index]
+        scratch[:step_index] += 1
+
+        step_obj = {
+          'id'        => "step_#{idx}_#{SecureRandom.hex(3)}",
+          'title'     => title,
+          'status'    => status,
+          'startedAt' => Kensho::Schema.iso_now,
+          'duration'  => duration_ms
+        }
+        step_obj['parameters'] = parameters unless parameters.empty?
+        scratch[:steps] << step_obj
+      end
+
+      def on_test_case_finished(event)
+        test_case = event.test_case
+        scratch = @scratch.delete(test_case.object_id)
+        return unless scratch
+
+        case_obj = scratch[:case_obj]
+        result = event.result
+
+        status =
+          if result.respond_to?(:passed?) && result.passed?
+            scratch[:worst_status] == 'pass' ? 'pass' : scratch[:worst_status]
+          elsif result.respond_to?(:failed?) && result.failed?
+            'fail'
+          elsif result.respond_to?(:undefined?) && result.undefined?
+            'broken'
+          elsif result.respond_to?(:skipped?) && result.skipped?
+            'skip'
+          elsif result.respond_to?(:pending?) && result.pending?
+            'skip'
+          else
+            scratch[:worst_status]
+          end
+
+        duration_ms = [(((Process.clock_gettime(Process::CLOCK_MONOTONIC) - scratch[:started_perf]) * 1000.0).round), 0].max
+
+        case_obj['status']     = status
+        case_obj['finishedAt'] = Kensho::Schema.iso_now
+        case_obj['duration']   = duration_ms
+        case_obj['steps']      = scratch[:steps] unless scratch[:steps].empty?
+
+        if scratch[:first_exception] || scratch[:first_error]
+          ex = scratch[:first_exception]
+          message = ex ? ex.message.to_s.lines.first.to_s.strip : scratch[:first_error].to_s.lines.first.to_s.strip
+          err = { 'message' => message.empty? ? 'failure' : message }
+          if ex
+            err['type']  = ex.class.name.to_s
+            stack = [ex.message.to_s]
+            stack.concat(Array(ex.backtrace).first(20))
+            err['stack'] = stack.join("\n")
+          elsif scratch[:first_error] && scratch[:first_error].to_s != message
+            err['stack'] = scratch[:first_error].to_s
+          end
+          case_obj['errors'] = [err]
+        end
+
+        case_obj['attachments'] = scratch[:attachments] unless scratch[:attachments].empty?
+
+        @cases_by_id[case_obj['id']] = case_obj
+        write_case(case_obj)
+      end
+
+      def on_test_run_finished
+        write_run_json
+      rescue StandardError => e
+        warn "[kensho] failed to write run.json: #{e.message}"
+      end
+
+      # ------- helpers ------- #
+
+      def step_title_and_params(step)
+        return [nil, []] if step.respond_to?(:hook?) && step.hook?
+
+        text =
+          if step.respond_to?(:text)
+            step.text.to_s
+          elsif step.respond_to?(:name)
+            step.name.to_s
+          else
+            ''
+          end
+        return [nil, []] if text.empty?
+
+        keyword = ''
+        gherkin_step = nil
+        if @ast_lookup
+          begin
+            src = @ast_lookup.step_source(step)
+            gherkin_step = src && src.respond_to?(:step) ? src.step : nil
+          rescue StandardError
+            gherkin_step = nil
+          end
+          keyword = gherkin_step.keyword.to_s if gherkin_step && gherkin_step.respond_to?(:keyword)
+        end
+        title = keyword && !keyword.empty? ? "#{keyword}#{text}" : text
+
+        params = []
+        if gherkin_step && gherkin_step.respond_to?(:data_table) && gherkin_step.data_table
+          rows = gherkin_step.data_table.rows
+          rows.each_with_index do |row, ri|
+            cells = row.respond_to?(:cells) ? row.cells : []
+            cells.each_with_index do |cell, ci|
+              value = cell.respond_to?(:value) ? cell.value.to_s : cell.to_s
+              params << {
+                'name' => "row#{ri}.col#{ci}",
+                'value' => value,
+                'kind' => 'data-row'
+              }
+            end
+          end
+        end
+        if gherkin_step && gherkin_step.respond_to?(:doc_string) && gherkin_step.doc_string
+          ds = gherkin_step.doc_string
+          params << {
+            'name' => 'docstring',
+            'value' => ds.respond_to?(:content) ? ds.content.to_s : ds.to_s,
+            'kind' => 'argument'
+          }
+        end
+
+        [title, params]
+      end
+
+      def feature_and_rule(test_case)
+        feature = nil
+        rule = nil
+        if @ast_lookup
+          uri = test_case.location.file rescue nil
+          if uri
+            doc = nil
+            begin
+              doc = @ast_lookup.gherkin_document(uri)
+            rescue StandardError
+              doc = nil
+            end
+            if doc && doc.respond_to?(:feature) && doc.feature
+              feature = doc.feature.name.to_s if doc.feature.respond_to?(:name)
+              rule = walk_for_rule(doc.feature, test_case.location.lines.max) if doc.feature.respond_to?(:children)
+            end
+          end
+        end
+        [feature, rule]
+      end
+
+      def walk_for_rule(feature, line)
+        feature.children.each do |child|
+          next unless child.respond_to?(:rule) && child.rule
+
+          rule = child.rule
+          # Lines covered by this rule include all its scenarios.
+          covered = false
+          if rule.respond_to?(:children)
+            rule.children.each do |sc_child|
+              next unless sc_child.respond_to?(:scenario) && sc_child.scenario
+
+              if sc_child.scenario.location.line == line ||
+                 sc_child.scenario.steps.any? { |s| s.location.line == line }
+                covered = true
+                break
+              end
+            end
+          end
+          return rule.name.to_s if covered && rule.respond_to?(:name)
+        end
+        nil
+      end
+
+      def severity_from_tags(tags)
+        tags.each do |t|
+          return t.split(':', 2)[1].to_s.downcase if t.start_with?('severity:') &&
+                                                     SEVERITY_TAGS.include?(t.split(':', 2)[1].to_s.downcase)
+          return t.downcase if SEVERITY_TAGS.include?(t.downcase)
+        end
+        nil
+      end
+
+      def labels_from_tags(tags)
+        labels = {}
+        tags.each do |t|
+          next unless t.start_with?('kensho.label.')
+
+          rest = t.sub('kensho.label.', '')
+          key, value = rest.split('=', 2)
+          next if key.nil? || key.empty?
+
+          labels[key] = (value || 'true').to_s
+        end
+        labels
+      end
+
+      def links_from_tags(tags)
+        links = []
+        tags.each do |t|
+          if t.start_with?('kensho.url.')
+            rest = t.sub('kensho.url.', '')
+            kind, url = rest.split('=', 2)
+            next if url.nil? || url.empty?
+
+            link = { 'url' => url }
+            link['kind'] = kind if kind && !kind.empty?
+            links << link
+          elsif t.start_with?('kensho.link.')
+            rest = t.sub('kensho.link.', '')
+            kind, label = rest.split('=', 2)
+            next if label.nil? || label.empty?
+
+            link = { 'url' => label, 'label' => label }
+            link['kind'] = kind if kind && !kind.empty?
+            links << link
+          end
+        end
+        links
+      end
+
+      def map_case_status(result)
+        return 'pass' if result.respond_to?(:passed?) && result.passed?
+        return 'fail' if result.respond_to?(:failed?) && result.failed?
+        return 'broken' if result.respond_to?(:undefined?) && result.undefined?
+        return 'broken' if result.class.name.to_s.end_with?('::Undefined', '::Ambiguous')
+        return 'skip'   if result.respond_to?(:skipped?) && result.skipped?
+        return 'skip'   if result.respond_to?(:pending?) && result.pending?
+
+        'pass'
+      end
+
+      def map_step_status(result)
+        s = map_case_status(result)
+        s == 'broken' ? 'fail' : s
+      end
+
+      def duration_ms_from_result(result)
+        return 0 unless result.respond_to?(:duration) && result.duration
+
+        d = result.duration
+        if d.respond_to?(:nanoseconds)
+          (d.nanoseconds / 1_000_000.0).round
+        elsif d.respond_to?(:to_f)
+          (d.to_f * 1000.0).round
+        else
+          0
+        end
+      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 = [((Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_perf) * 1000.0).round, 0].max
+        framework_version = cucumber_version
+
+        run = {
+          'schemaVersion' => Kensho::Schema::SCHEMA_VERSION,
+          'id'            => @run_id,
+          'project'       => @project,
+          'framework'     => { 'name' => 'cucumber-ruby', '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))
+      end
+
+      def cucumber_version
+        if defined?(::Cucumber::VERSION)
+          ::Cucumber::VERSION.to_s
+        else
+          'unknown'
+        end
+      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
+    end
+  end
+end

data/lib/kensho/cucumber/version.rb

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

data/lib/kensho/cucumber.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Public entrypoint for kensho-cucumber-ruby.
+#
+# Usage:
+#   bundle exec cucumber --format Kensho::Cucumber::Formatter
+
+require_relative '_schema'
+require_relative 'cucumber/version'
+require_relative 'cucumber/formatter'
+
+module Kensho
+  module Cucumber
+    DEFAULT_OUTPUT = 'kensho-results'
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: kensho-cucumber-ruby
+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: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  Cucumber 7+ formatter that writes a Kensho v1 result bundle
+  (run.json + cases/<id>.json + attachments/) into ./kensho-results.
+  Each scenario becomes a Kensho case; each Gherkin step becomes a
+  Kensho step.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/kensho/_schema.rb
+- lib/kensho/cucumber.rb
+- lib/kensho/cucumber/formatter.rb
+- lib/kensho/cucumber/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 Cucumber-Ruby — emits Kensho v1 results.
+test_files: []