rspec-tracer 1.2.3 → 2.0.0.pre.2

data/lib/rspec_tracer/reporters/html_reporter.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'fileutils'
+require 'json'
+
+require_relative 'base'
+require_relative 'payload_builder'
+
+module RSpecTracer
+  # Internal Reporters — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Reporters
+    # Renders a single-page HTML report at `<report_dir>/index.html`
+    # consuming the canonical payload built by `PayloadBuilder`
+    # (shared with `JsonReporter`).
+    #
+    # Build output - the frontend bundle at
+    # `lib/rspec_tracer/reporters/html/dist/` - is committed to the
+    # repo; users never run npm. At emit time this reporter:
+    #
+    #   1. Reads the template at `html/dist/index.html`.
+    #   2. Replaces the `<!-- RSPEC_TRACER_FALLBACK -->` marker with
+    #      server-rendered `<table>` HTML for each of the 5 report
+    #      types (satisfies the "works without JavaScript" AC; the
+    #      Preact bundle removes these on hydrate).
+    #   3. Replaces the body of `<script id="report-data">` with the
+    #      full payload JSON.
+    #   4. Copies `html/dist/assets/` next to the output.
+    #   5. Writes the finished file.
+    #
+    # Failure modes are graceful: the Registry wraps `#generate` in
+    # an isolated rescue, so a template-missing or template-corrupt
+    # condition logs a warning and returns nil rather than propagating
+    # a non-zero exit into the user's test suite.
+    class HtmlReporter < Base
+      # Internal constant.
+      # @api private
+      FILENAME = 'index.html'
+      # Internal constant.
+      # @api private
+      ASSETS_DIR = 'assets'
+      # Internal constant.
+      # @api private
+      FALLBACK_MARKER = '<!-- RSPEC_TRACER_FALLBACK -->'
+      # Internal constant.
+      # @api private
+      REPORT_DATA_REGEX = %r{<script id="report-data" type="application/json">.*?</script>}m
+
+      # Absolute path to the committed frontend build under
+      # `lib/rspec_tracer/reporters/html/dist/`. Computed once at load
+      # time so tests can stub `DIST_DIR` if they need a different
+      # template root.
+      DIST_DIR = File.expand_path('html/dist', __dir__)
+
+      # Concrete implementation of {RSpecTracer::Reporters::Base#generate}.
+      # Renders the bundled HTML template with the run payload and writes
+      # `index.html` (plus the asset directory) under {#report_dir}.
+      #
+      # @return [String, nil] absolute path of the written index, or nil
+      #   when there is nothing to render.
+      def generate
+        return nil if no_op?
+
+        template = read_template
+        return nil if template.nil?
+
+        payload_json = PayloadBuilder.build(
+          snapshot: snapshot,
+          run_metadata: run_metadata,
+          generated_at: generated_at_override
+        )
+        rendered = inject(template, payload_json)
+
+        FileUtils.mkdir_p(report_dir)
+        copy_assets
+        path = File.join(report_dir, FILENAME)
+        File.write(path, rendered, encoding: 'UTF-8')
+        logger&.debug("rspec-tracer: wrote HTML report to #{path}")
+        path
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def read_template
+        path = File.join(dist_dir, FILENAME)
+        return File.read(path, encoding: 'UTF-8') if File.file?(path)
+
+        logger&.warn("rspec-tracer: HTML template missing at #{path}; HTML report not emitted")
+        nil
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def inject(template, payload)
+        with_payload = template.sub(
+          REPORT_DATA_REGEX,
+          %(<script id="report-data" type="application/json">#{escape_payload(payload)}</script>)
+        )
+        with_payload.sub(FALLBACK_MARKER, render_fallback(payload))
+      end
+
+      # The payload sits inside a `<script>` tag. To make it inert as
+      # HTML we escape `<`, `>`, and `&` with JSON-safe `\uXXXX`
+      # escapes. The string remains valid JSON on round-trip because
+      # JSON accepts `\u003c` etc. for any code point.
+      def escape_payload(payload)
+        JSON.generate(payload).gsub('<', '\\u003c').gsub('>', '\\u003e').gsub('&', '\\u0026')
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def render_fallback(payload)
+        sections = fallback_sections(payload[:reports] || {})
+        %(<div id="fallback" class="fallback-root">#{sections.join("\n")}</div>)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_sections(reports)
+        dups = reports[:duplicate_examples] || []
+        flakies = reports[:flaky_examples] || []
+        sections = [fallback_all_examples(reports[:all_examples] || [])]
+        sections << fallback_duplicate_examples(dups) if dups.any?
+        sections << fallback_flaky_examples(flakies) if flakies.any?
+        sections << fallback_examples_dependency(reports[:examples_dependency] || [])
+        sections << fallback_files_dependency(reports[:files_dependency] || [])
+        sections
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_all_examples(items)
+        headers = ['Description', 'Location', 'Status', 'Run reason', 'Result', 'Duration']
+        rows = items.map do |item|
+          result = item[:execution_result] || {}
+          cells = [
+            cell(item[:description]), cell_code(item[:location]),
+            cell(item[:status]), cell(item[:run_reason]),
+            cell(result[:status]), cell(format_duration(result[:run_time]))
+          ].join
+          "<tr>#{cells}</tr>"
+        end
+        fallback_table('all-examples', 'All Examples', headers, rows)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_duplicate_examples(items)
+        headers = ['Example ID', 'Occurrences', 'Description', 'Location']
+        rows = items.flat_map do |group|
+          (group[:entries] || []).map do |entry|
+            cells = [cell_code(group[:id]), cell(group[:count]),
+                     cell(entry[:description]), cell_code(entry[:location])].join
+            "<tr>#{cells}</tr>"
+          end
+        end
+        fallback_table('duplicate-examples', 'Duplicate Examples', headers, rows)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_flaky_examples(items)
+        headers = ['Example ID', 'Description', 'Location']
+        rows = items.map do |item|
+          cells = [cell_code(item[:id]), cell(item[:description]), cell_code(item[:location])].join
+          "<tr>#{cells}</tr>"
+        end
+        fallback_table('flaky-examples', 'Flaky Examples', headers, rows)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_examples_dependency(items)
+        headers = ['Example ID', 'Files', 'Env keys', 'Dependencies']
+        rows = items.map do |item|
+          files = item[:files] || []
+          env_keys = item[:env_keys] || []
+          deps = (files + env_keys.map { |k| "env:#{k}" }).map { |d| CGI.escapeHTML(d.to_s) }.join('<br>')
+          cells = [cell_code(item[:example_id]), cell(files.size), cell(env_keys.size),
+                   %(<td class="cell-deps">#{deps}</td>)].join
+          "<tr>#{cells}</tr>"
+        end
+        fallback_table('examples-dependency', 'Examples Dependency', headers, rows)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_files_dependency(items)
+        headers = ['File', 'Examples', 'Spec files', 'Dependent spec files']
+        rows = items.map do |item|
+          spec_files = item[:spec_files] || {}
+          deps = spec_files.map { |spec, count| "#{CGI.escapeHTML(spec.to_s)} (#{count})" }.join('<br>')
+          cells = [cell_code(item[:file_name]), cell(item[:example_count]), cell(spec_files.size),
+                   %(<td class="cell-deps">#{deps}</td>)].join
+          "<tr>#{cells}</tr>"
+        end
+        fallback_table('files-dependency', 'Files Dependency', headers, rows)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def fallback_table(id, title, headers, rows)
+        header_cells = headers.map { |h| "<th scope=\"col\">#{CGI.escapeHTML(h)}</th>" }.join
+        body = rows.empty? ? %(<tr><td colspan="#{headers.size}">No rows.</td></tr>) : rows.join
+        <<~HTML
+          <section class="fallback-section" id="fallback-#{id}">
+            <h2>#{CGI.escapeHTML(title)}</h2>
+            <table class="fallback-table">
+              <thead><tr>#{header_cells}</tr></thead>
+              <tbody>#{body}</tbody>
+            </table>
+          </section>
+        HTML
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def cell(value)
+        "<td>#{CGI.escapeHTML(value.to_s)}</td>"
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def cell_code(value)
+        "<td><code>#{CGI.escapeHTML(value.to_s)}</code></td>"
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def format_duration(seconds)
+        return '' unless seconds.is_a?(::Numeric)
+        return format('%d us', (seconds * 1_000_000).round) if seconds < 0.001
+        return format('%.1f ms', seconds * 1000) if seconds < 1
+
+        format('%.3f s', seconds)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def copy_assets
+        src = File.join(dist_dir, ASSETS_DIR)
+        return unless File.directory?(src)
+
+        dest = File.join(report_dir, ASSETS_DIR)
+        FileUtils.rm_rf(dest)
+        FileUtils.mkdir_p(dest)
+        FileUtils.cp_r(Dir[File.join(src, '*')], dest)
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def dist_dir
+        options[:dist_dir] || DIST_DIR
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def generated_at_override
+        options[:generated_at]
+      end
+    end
+  end
+end

data/lib/rspec_tracer/reporters/json_reporter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+require_relative 'base'
+require_relative 'payload_builder'
+
+module RSpecTracer
+  # Internal Reporters — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Reporters
+    # Machine-readable summary of a tracer run. Writes
+    # `<report_dir>/report.json` containing a stable, schema-versioned
+    # envelope around the 5 report types that 1.x's HTML reporter
+    # surfaced (All, Duplicate, Flaky, Examples Dependency, Files
+    # Dependency) plus a run summary block.
+    #
+    # Payload shape lives in `PayloadBuilder` (shared with
+    # `HtmlReporter` so the two never drift). Schema contract docs for
+    # version 1:
+    #
+    #   {
+    #     "schema_version": 1,
+    #     "run_id": <hex md5 of sorted example ids>,
+    #     "generated_at": <ISO-8601 UTC timestamp at emit time>,
+    #     "summary": {
+    #       "total_examples": <Integer>,
+    #       "passed_examples": <Integer>,
+    #       "failed_examples": <Integer>,
+    #       "pending_examples": <Integer>,
+    #       "skipped_examples": <Integer>,
+    #       "interrupted_examples": <Integer>,
+    #       "flaky_examples": <Integer>,
+    #       "duplicate_examples": <Integer>,
+    #       "tracked_env_keys": <Integer>,
+    #       "run_time": <Float|null>,
+    #       "started_at": <ISO-8601|null>,
+    #       "pid": <Integer|null>,
+    #       "parallel_tests": <Boolean>
+    #     },
+    #     "reports": {
+    #       "all_examples": [ {id, description, location, status, run_reason, execution_result}, ... ],
+    #       "duplicate_examples": [ {id, count, entries: [{description, location}, ...]}, ... ],
+    #       "flaky_examples": [ {id, description, location}, ... ],
+    #       "examples_dependency": [ {example_id, files: [...], env_keys: [...]}, ... ],
+    #       "files_dependency": [ {file_name, example_count, spec_files: {path => count}}, ... ]
+    #     }
+    #   }
+    #
+    # Breaking schema changes bump `SCHEMA_VERSION`. Additive fields
+    # (new keys in an existing object) are NOT breaking. Removed or
+    # renamed keys ARE. Downstream consumers (HTML reporter, user CI
+    # dashboards) should branch on the top-level version.
+    class JsonReporter < Base
+      # Internal constant.
+      # @api private
+      SCHEMA_VERSION = PayloadBuilder::SCHEMA_VERSION
+      # Internal constant.
+      # @api private
+      FILENAME = 'report.json'
+
+      # Concrete implementation of {RSpecTracer::Reporters::Base#generate}.
+      # Serializes the canonical payload via {PayloadBuilder} and writes
+      # `report.json` under {#report_dir}.
+      #
+      # @return [String, nil] absolute path of the written file, or nil
+      #   when the run had no examples to report.
+      def generate
+        return nil if no_op?
+
+        FileUtils.mkdir_p(report_dir)
+        path = File.join(report_dir, FILENAME)
+        File.write(path, JSON.pretty_generate(build_payload), encoding: 'UTF-8')
+        logger&.debug("rspec-tracer: wrote report JSON to #{path}")
+        path
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def build_payload
+        PayloadBuilder.build(snapshot: snapshot, run_metadata: run_metadata)
+      end
+    end
+  end
+end

data/lib/rspec_tracer/reporters/payload_builder.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module RSpecTracer
+  # Internal Reporters — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module Reporters
+    # Builds the canonical reporter payload (schema v1) from a
+    # finalized `Storage::Snapshot` plus a `run_metadata` Hash. Shared
+    # by `JsonReporter` (which `JSON.pretty_generate`s the output) and
+    # `HtmlReporter` (which embeds it in a `<script id="report-data">`
+    # tag). One source of truth for the 5-report shape so JSON and
+    # HTML never drift.
+    #
+    # `generated_at` is accepted as a kwarg so callers (especially the
+    # golden-file spec for HtmlReporter) can stub it for deterministic
+    # output; defaults to `Time.now.utc` to preserve JsonReporter's
+    # 1.x-era emit-time semantics.
+    #
+    # Schema changes are additive by default: new keys on an existing
+    # object are non-breaking and do NOT bump `SCHEMA_VERSION`.
+    # Removed or renamed keys bump `SCHEMA_VERSION` and require a
+    # downstream coordination pass.
+    class PayloadBuilder
+      # Internal constant.
+      # @api private
+      SCHEMA_VERSION = 1
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.build(snapshot:, run_metadata:, generated_at: nil)
+        new(snapshot: snapshot, run_metadata: run_metadata, generated_at: generated_at).build
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def initialize(snapshot:, run_metadata:, generated_at: nil)
+        @snapshot = snapshot
+        @run_metadata = run_metadata || {}
+        @generated_at = generated_at || ::Time.now.utc
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def build
+        {
+          schema_version: SCHEMA_VERSION,
+          run_id: @snapshot.run_id,
+          generated_at: stringify_time(@generated_at),
+          summary: summary_block,
+          reports: {
+            all_examples: all_examples_report,
+            duplicate_examples: duplicate_examples_report,
+            flaky_examples: flaky_examples_report,
+            examples_dependency: examples_dependency_report,
+            files_dependency: files_dependency_report
+          }
+        }
+      end
+
+      private
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def summary_block
+        {
+          total_examples: @snapshot.all_examples.size,
+          passed_examples: count_status(:passed),
+          failed_examples: @snapshot.failed_examples.size,
+          pending_examples: @snapshot.pending_examples.size,
+          skipped_examples: @snapshot.skipped_examples.size,
+          interrupted_examples: @snapshot.interrupted_examples.size,
+          flaky_examples: @snapshot.flaky_examples.size,
+          duplicate_examples: @snapshot.duplicate_examples.size,
+          tracked_env_keys: (@snapshot.env_snapshot || {}).size,
+          run_time: @run_metadata[:run_time],
+          started_at: stringify_time(@run_metadata[:started_at]),
+          pid: @run_metadata[:pid],
+          parallel_tests: @run_metadata[:parallel_tests] == true
+        }
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def count_status(status)
+        status_str = status.to_s
+        @snapshot.all_examples.count do |_, meta|
+          next false unless meta.is_a?(::Hash)
+
+          result = meta[:execution_result] || meta['execution_result']
+          next false unless result.is_a?(::Hash)
+
+          (result[:status] || result['status']).to_s == status_str
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def all_examples_report
+        @snapshot.all_examples.map do |id, meta|
+          meta = {} unless meta.is_a?(::Hash)
+          {
+            id: id,
+            description: meta[:full_description] || meta[:description],
+            location: location_for(meta),
+            status: status_for(id, meta),
+            run_reason: meta[:run_reason],
+            execution_result: normalize_execution_result(meta[:execution_result])
+          }
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def duplicate_examples_report
+        @snapshot.duplicate_examples.map do |id, entries|
+          list = entries.is_a?(::Array) ? entries : []
+          {
+            id: id,
+            count: list.size,
+            entries: list.map do |entry|
+              entry = {} unless entry.is_a?(::Hash)
+              { description: entry[:full_description] || entry[:description], location: location_for(entry) }
+            end
+          }
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def flaky_examples_report
+        @snapshot.flaky_examples.to_a.sort.map do |id|
+          meta = @snapshot.all_examples[id]
+          meta = {} unless meta.is_a?(::Hash)
+          { id: id, description: meta[:full_description] || meta[:description], location: location_for(meta) }
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def examples_dependency_report
+        env_map = @snapshot.env_dependency || {}
+        @snapshot.dependency.keys.sort.map do |id|
+          files = @snapshot.dependency[id]
+          files_array = files.is_a?(::Set) ? files.to_a : Array(files)
+          {
+            example_id: id,
+            files: files_array.sort,
+            env_keys: Array(env_map[id]).sort
+          }
+        end
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def files_dependency_report
+        entries = @snapshot.reverse_dependency.map do |file_name, example_ids|
+          ids_array = example_ids.is_a?(::Set) ? example_ids.to_a : Array(example_ids)
+          spec_counts = aggregate_spec_counts(ids_array)
+          {
+            file_name: file_name,
+            example_count: ids_array.size,
+            spec_files: spec_counts
+          }
+        end
+        entries.sort_by { |e| [-e[:example_count], e[:file_name].to_s] }
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def aggregate_spec_counts(example_ids)
+        counts = ::Hash.new(0)
+        example_ids.each do |id|
+          meta = @snapshot.all_examples[id]
+          next unless meta.is_a?(::Hash)
+
+          spec = meta[:rerun_file_name] || meta[:file_name]
+          next if spec.nil? || spec.to_s.empty?
+
+          counts[spec.to_s] += 1
+        end
+        counts.sort_by { |name, count| [-count, name] }.to_h
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def location_for(meta)
+        file = meta[:rerun_file_name] || meta[:file_name]
+        line = meta[:rerun_line_number] || meta[:line_number]
+        return nil if file.nil?
+
+        trimmed = file.to_s.sub(%r{^/}, '')
+        line.nil? ? trimmed : "#{trimmed}:#{line}"
+      end
+
+      # Ordering: interrupted > flaky > failed > pending > skipped >
+      # execution_result.status. Matches 1.x HTML reporter's status
+      # precedence so downstream consumers see the same labels.
+      def status_for(id, meta)
+        return 'interrupted' if @snapshot.interrupted_examples.include?(id)
+        return 'flaky' if @snapshot.flaky_examples.include?(id)
+        return 'failed' if @snapshot.failed_examples.include?(id)
+        return 'pending' if @snapshot.pending_examples.include?(id)
+        return 'skipped' if @snapshot.skipped_examples.include?(id)
+
+        result = meta[:execution_result]
+        result.is_a?(::Hash) ? (result[:status] || 'unknown').to_s : 'unknown'
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def normalize_execution_result(result)
+        return nil unless result.is_a?(::Hash)
+
+        {
+          started_at: stringify_time(result[:started_at]),
+          finished_at: stringify_time(result[:finished_at]),
+          run_time: result[:run_time],
+          status: (result[:status] || 'unknown').to_s
+        }
+      end
+
+      # Internal method on the tracer pipeline.
+      # @api private
+      def stringify_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(::String)
+        return value.iso8601 if value.respond_to?(:iso8601)
+
+        value.to_s
+      end
+    end
+  end
+end