karst 0.1.0

data/lib/karst/spec/catalog.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "principal"
+require_relative "scenario"
+
+module Karst
+  module Spec
+    # Read-only index over the JSON artifact Karst::Spec::Observer writes,
+    # answering "what scenarios have been observed for this controller/action"
+    # without requiring RSpec, Rails, or the host application's database to be
+    # loaded. This is pure data ingestion: JSON primitives in, immutable
+    # Scenario objects out. It never deserializes arbitrary Ruby objects,
+    # never constantizes a principal type, and never queries anything.
+    #
+    # A Catalog is always in exactly one of three states:
+    #
+    # - :missing -- the artifact does not exist yet (the suite has never
+    #   been run with the observer installed).
+    # - :invalid -- the artifact exists but could not be read as the expected
+    #   JSON array (empty file, malformed JSON, or an incompatible top-level
+    #   shape). `error` holds a human-readable reason.
+    # - :ready -- the artifact was a valid JSON array. `scenarios` may still
+    #   be empty (a suite that observed zero browser-facing requests), which
+    #   is deliberately distinct from :missing: "no scenarios cover this
+    #   route" is not the same claim as "the catalog was never generated."
+    #
+    # Malformed individual entries inside an otherwise valid array (a request
+    # missing its controller, an example with no requests at all) are skipped
+    # individually rather than invalidating the whole artifact.
+    # rubocop:disable Metrics/ClassLength
+    class Catalog
+      DEFAULT_RELATIVE_PATH = File.join("tmp", "karst", "scenarios.json")
+      private_constant :DEFAULT_RELATIVE_PATH
+
+      EMPTY = [].freeze
+      private_constant :EMPTY
+
+      OUTCOMES = %w[passed failed pending].freeze
+      private_constant :OUTCOMES
+
+      class << self
+        # Rails' own tmp/ convention when available, otherwise a plain
+        # relative path so this stays usable from a bare Ruby process (tests,
+        # a future CLI) with no Rails loaded.
+        def default_path
+          return DEFAULT_RELATIVE_PATH unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+          File.join(Rails.root.to_s, DEFAULT_RELATIVE_PATH)
+        end
+
+        def load(path: default_path)
+          new(*read(path))
+        end
+
+        private
+
+        def read(path)
+          return [:missing, EMPTY, nil] unless File.exist?(path)
+
+          raw = File.read(path)
+          return [:invalid, EMPTY, "scenario artifact at #{path} is empty"] if raw.strip.empty?
+
+          parse(raw, path)
+        rescue SystemCallError => e
+          [:invalid, EMPTY, "scenario artifact at #{path} could not be read: #{e.message}"]
+        end
+
+        def parse(raw, path)
+          parsed = JSON.parse(raw)
+          return [:invalid, EMPTY, "scenario artifact at #{path} is not a JSON array"] unless parsed.is_a?(Array)
+
+          [:ready, build_scenarios(parsed), nil]
+        rescue JSON::ParserError => e
+          [:invalid, EMPTY, "scenario artifact at #{path} is not valid JSON: #{e.message}"]
+        end
+
+        # Ordered deterministically so two reads of an unchanged artifact
+        # agree: passed examples before failed/pending ones, then file path,
+        # line number, example id, and finally request sequence (the
+        # tie-breaker that keeps multiple scenarios from the same example in
+        # their original request order). Explicitly labelled QA scenarios lead
+        # discovered scenarios while preserving those guarantees within each
+        # group.
+        def build_scenarios(examples)
+          scenarios = examples.flat_map { |example| scenarios_from_example(example) }
+          scenarios.sort_by { |scenario| sort_key(scenario) }.freeze
+        end
+
+        def sort_key(scenario)
+          [scenario.explicit? ? 0 : 1, scenario.passed? ? 0 : 1, scenario.file_path, scenario.line_number,
+           scenario.example_id, scenario.sequence]
+        end
+
+        def scenarios_from_example(example)
+          return EMPTY unless example.is_a?(Hash) && valid_example?(example)
+
+          example["requests"].filter_map { |request| scenario_from_request(request, example) }
+        end
+
+        def valid_example?(example)
+          example["example_id"].is_a?(String) && example["file_path"].is_a?(String) &&
+            example["line_number"].is_a?(Integer) && example["description_parts"].is_a?(Array) &&
+            example["full_description"].is_a?(String) && example["requests"].is_a?(Array)
+        end
+
+        # A request only becomes a Scenario once it carries enough evidence to
+        # be indexed and shown: a browser-facing (HTML) response, a resolved
+        # controller/action, an HTTP method, and its position within the
+        # example. Everything else observed about the request (route pattern,
+        # path, status, redirect target, principal before/after) is retained
+        # as-is, including nil, since a nil there is itself real evidence
+        # (e.g. the request never reached `process_action`).
+        def scenario_from_request(request, example)
+          return nil unless request.is_a?(Hash) && request["format"] == "html" && valid_request?(request)
+
+          build_scenario(request, example)
+        rescue StandardError
+          nil
+        end
+
+        def valid_request?(request)
+          required = %w[controller action method].all? { |key| non_empty_string?(request[key]) }
+          required && request["sequence"].is_a?(Integer)
+        end
+
+        def non_empty_string?(value)
+          value.is_a?(String) && !value.empty?
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def build_scenario(request, example)
+          Scenario.new(
+            example_id: example["example_id"], file_path: example["file_path"], line_number: example["line_number"],
+            description_parts: example["description_parts"].freeze, full_description: example["full_description"],
+            karst_explicit: example["karst_explicit"] == true,
+            karst_name: non_empty_string?(example["karst_name"]) ? example["karst_name"] : nil,
+            example_outcome: outcome_for(example["outcome"]),
+            controller: request["controller"], action: request["action"], http_method: request["method"],
+            route_pattern: request["route_pattern"], observed_path: request["path"],
+            observed_status: request["status"], observed_redirect: request["redirect_location"],
+            principal_before: principal_from(request["principal_before"]),
+            principal_after: principal_from(request["principal_after"]),
+            principal_changed: request["principal_changed"] == true, sequence: request["sequence"]
+          ).freeze
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        def outcome_for(raw)
+          OUTCOMES.include?(raw) ? raw.to_sym : :unknown
+        end
+
+        def principal_from(raw)
+          return nil unless raw.is_a?(Hash)
+
+          Principal.new(type: raw["type"], id: raw["id"], scope: raw["scope"])
+        end
+      end
+      private_class_method :new
+
+      attr_reader :status, :scenarios, :error
+
+      def initialize(status, scenarios, error)
+        @status = status
+        @scenarios = scenarios
+        @error = error
+        @index = build_index(scenarios)
+        freeze
+      end
+
+      def ready?
+        status == :ready
+      end
+
+      # Indexed primarily by controller/action -- Rails' own stable routing
+      # identity -- so "/things/1" and "/things/2" report as the same
+      # capability instead of fragmenting by dynamic id. `http_method`
+      # narrows further for the (uncommon) case where one controller/action
+      # legitimately answers more than one verb; omitted, every scenario for
+      # that controller/action is returned regardless of method.
+      def scenarios_for(controller:, action:, http_method: nil)
+        matches = @index.fetch([controller, action], EMPTY)
+        return matches if http_method.nil?
+
+        normalized = http_method.to_s.upcase
+        matches.select { |scenario| scenario.http_method == normalized }.freeze
+      end
+
+      private
+
+      def build_index(scenarios)
+        scenarios.group_by { |scenario| [scenario.controller, scenario.action] }
+                 .transform_values(&:freeze)
+                 .freeze
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/karst/spec/example_observation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Karst
+  module Spec
+    # One RSpec example's complete observed request history: every request it
+    # issued, in order, plus enough of RSpec's own metadata (file/line,
+    # nested description, stable example id, pass/fail outcome) to present
+    # and re-locate the example without re-parsing spec source.
+    ExampleObservation = Value.define(
+      :example_id,
+      :file_path,
+      :line_number,
+      :spec_type,
+      :description_parts,
+      :full_description,
+      :karst_explicit,
+      :karst_name,
+      :outcome,
+      :requests
+    ) do
+      # An example is part of Karst's route/page catalog only if at least one
+      # of its requests rendered HTML -- an examples whose only requests are
+      # JSON API calls has nothing to show a person exercising a page.
+      def browser_facing?
+        requests.any? { |request| request.format == "html" }
+      end
+    end
+  end
+end

data/lib/karst/spec/observer.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "logger" # see lib/karst.rb for why this must precede active_support on Rails 6.1
+require "active_support"
+require "active_support/notifications"
+require_relative "../execution_context"
+require_relative "principal"
+require_relative "request_observation"
+require_relative "example_observation"
+require_relative "reporter"
+
+module Karst
+  module Spec
+    class InvalidMetadataError < StandardError; end
+
+    # Turns real RSpec execution into Karst's route/scenario catalog.
+    #
+    # Karst never parses spec source, route-helper arguments, or FactoryBot
+    # calls to build this catalog. It observes the same runtime facts the
+    # request-evidence engine already relies on -- ActiveSupport::Notifications
+    # for controller/render events, and Warden's public hooks for the
+    # authenticated principal -- while an example actually runs, and records
+    # only what those events say. An example that never issues an HTTP
+    # request produces no observation at all.
+    #
+    # Explicitly out of scope here: provisioning scenario state, database
+    # cloning or isolation, browser/session switching, source analysis, and
+    # any UI. This module only builds and writes the catalog artifact.
+    # rubocop:disable Metrics/ModuleLength
+    module Observer
+      KEY = :karst_spec_observer_current
+      private_constant :KEY
+
+      # Mutable accumulator for the example currently running. `principal` is
+      # updated in place by the Warden hooks as the example progresses, so
+      # each request observes the principal that was active when it happened.
+      Current = Struct.new(:requests, :principal, keyword_init: true)
+      private_constant :Current
+
+      # Mutable request-in-progress. Frozen into a RequestObservation once the
+      # example finishes; never exposed outside this module. Named
+      # `http_method`, not `method`, so it never shadows Object#method.
+      RequestBuilder = Struct.new(
+        :sequence, :http_method, :path, :route_pattern, :controller, :action, :format,
+        :status, :redirect_location, :principal_before, :principal_after,
+        keyword_init: true
+      )
+      private_constant :RequestBuilder
+
+      # rubocop:disable Metrics/ClassLength
+      class << self
+        attr_reader :reporter, :output_path
+
+        # rubocop:disable Metrics/MethodLength
+        def install!(output:)
+          @install_mutex ||= Mutex.new
+          @install_mutex.synchronize do
+            return @reporter if @installed
+
+            raise "Karst::Spec::Observer requires RSpec to already be loaded" unless defined?(RSpec)
+
+            @output_path = output
+            @reporter = Reporter.new
+            subscribe_notifications
+            subscribe_warden
+            configure_rspec
+            @installed = true
+            @reporter
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        # The one seam RSpec's `around` hook calls into: start tracking,
+        # run the example, then convert whatever was tracked into an
+        # immutable ExampleObservation and hand it to the Reporter.
+        def wrap_example(example)
+          karst_explicit, karst_name = karst_metadata(example)
+          start_example!
+          yield
+        ensure
+          finish_and_record!(example, karst_explicit: karst_explicit, karst_name: karst_name)
+        end
+
+        private
+
+        def current
+          Karst::ExecutionContext[KEY]
+        end
+
+        def start_example!
+          Karst::ExecutionContext[KEY] = Current.new(requests: [], principal: nil)
+        end
+
+        def finish_example!
+          state = current
+          Karst::ExecutionContext.delete(KEY)
+          state
+        end
+
+        def subscribe_notifications
+          ActiveSupport::Notifications.subscribe("start_processing.action_controller") do |*args|
+            on_start_processing(args.last)
+          end
+          ActiveSupport::Notifications.subscribe("redirect_to.action_controller") do |*args|
+            on_redirect(args.last)
+          end
+          ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+            on_process_action(args.last)
+          end
+        end
+
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def on_start_processing(payload)
+          state = current
+          return unless state
+
+          state.requests << RequestBuilder.new(
+            sequence: state.requests.size,
+            http_method: payload[:method],
+            path: strip_query(payload[:path]),
+            route_pattern: route_pattern_for(payload[:request]),
+            controller: payload[:controller],
+            action: payload[:action],
+            format: payload[:format]&.to_s,
+            status: nil,
+            redirect_location: nil,
+            principal_before: state.principal,
+            principal_after: state.principal
+          )
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+        def on_redirect(payload)
+          builder = current&.requests&.last
+          return unless builder
+
+          builder.redirect_location = strip_query(strip_host(payload[:location]))
+        end
+
+        def on_process_action(payload)
+          state = current
+          builder = state&.requests&.last
+          return unless builder
+
+          builder.status = payload[:status]
+          builder.principal_after = state.principal
+        end
+
+        # Query strings can carry tokens (password resets, OAuth callbacks,
+        # signed URLs) and are never retained, on request paths or on
+        # redirect targets below -- either can leak the same class of secret
+        # into the catalog artifact.
+        def strip_query(value)
+          value.to_s.split("?").first
+        end
+
+        def strip_host(location)
+          location.to_s.sub(%r{\Ahttps?://[^/]+}, "")
+        end
+
+        # Uses Rails' own routing engine to recover the declared path pattern
+        # (e.g. "/things/:id(.:format)") for the exact request that was
+        # already routed, rather than guessing from route-helper call sites
+        # in spec source. Falls back to nil -- never a guess -- if routing
+        # metadata is unavailable.
+        def route_pattern_for(request)
+          return nil unless request && defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+          pattern = nil
+          Rails.application.routes.router.recognize(request) do |route, _params|
+            pattern = route.path.spec.to_s
+            break
+          end
+          pattern
+        rescue StandardError
+          nil
+        end
+
+        # Warden is optional: an application with no Warden-based
+        # authentication simply never populates `principal`, and every
+        # request is recorded with `principal: nil` and role :subject.
+        # rubocop:disable Metrics/MethodLength
+        def subscribe_warden
+          return unless defined?(Warden::Manager)
+
+          Warden::Manager.after_set_user do |user, _auth, opts|
+            state = current
+            next unless state
+
+            state.principal = Principal.new(type: user.class.name, id: user.id, scope: opts[:scope])
+          end
+
+          Warden::Manager.before_logout do |_user, _auth, _opts|
+            state = current
+            next unless state
+
+            state.principal = nil
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def configure_rspec
+          RSpec.configure do |config|
+            config.around do |example|
+              Observer.wrap_example(example) { example.run }
+            end
+
+            config.after(:suite) do
+              Observer.reporter.write(Observer.output_path)
+            end
+          end
+        end
+
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def finish_and_record!(example, karst_explicit:, karst_name:)
+          state = finish_example!
+          return unless state
+          return if state.requests.empty?
+
+          reporter.record(
+            ExampleObservation.new(
+              example_id: example.id,
+              file_path: example.metadata[:file_path],
+              line_number: example.metadata[:line_number],
+              spec_type: example.metadata[:type],
+              description_parts: description_parts(example),
+              full_description: example.full_description,
+              karst_explicit: karst_explicit,
+              karst_name: karst_name,
+              outcome: outcome_for(example),
+              requests: freeze_requests(state.requests)
+            ).freeze
+          )
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+        # RSpec finalizes `execution_result.status` in Example#finish, which
+        # runs strictly after the around-hook chain returns -- it is always
+        # nil at this point, however this method is reached. `exception` and
+        # `pending_message` are set earlier, before `run_after_example`, so
+        # this mirrors RSpec's own status derivation instead of reading a
+        # field that has not been assigned yet.
+        def outcome_for(example)
+          return :failed if example.exception
+          return :pending if example.execution_result.pending_message
+
+          :passed
+        end
+
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def freeze_requests(builders)
+          builders.map do |builder|
+            RequestObservation.new(
+              sequence: builder.sequence,
+              http_method: builder.http_method,
+              path: builder.path,
+              route_pattern: builder.route_pattern,
+              controller: builder.controller,
+              action: builder.action,
+              format: builder.format,
+              status: builder.status,
+              redirect_location: builder.redirect_location,
+              principal_before: builder.principal_before,
+              principal_after: builder.principal_after,
+              principal_changed: builder.principal_after != builder.principal_before
+            ).freeze
+          end.freeze
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+        def description_parts(example)
+          outer = example.example_group.parent_groups.reverse.map(&:description)
+          (outer + [example.description]).freeze
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        def karst_metadata(example)
+          return [false, nil] unless example.metadata.key?(:karst)
+
+          value = example.metadata[:karst]
+          name = if value.is_a?(String)
+                   value
+                 elsif value.is_a?(Hash) && value.keys == [:name]
+                   value[:name]
+                 end
+
+          unless name.is_a?(String) && !name.strip.empty?
+            raise InvalidMetadataError,
+                  "Invalid karst: metadata for #{example.id}; expected a non-empty String or { name: non_empty_string }"
+          end
+
+          [true, name]
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/karst/spec/principal.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Karst
+  module Spec
+    # Minimal principal evidence observed via Warden's public hooks during an
+    # RSpec example: class name and primary key only, never a serialized user
+    # object, mirroring Karst's runtime-evidence principal model.
+    Principal = Value.define(:type, :id, :scope)
+  end
+end

data/lib/karst/spec/reporter.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Karst
+  module Spec
+    # Collects ExampleObservation instances as the suite runs and serializes
+    # them to one deterministic JSON artifact on disk. Never touches the host
+    # application's database: this is the only persistence Reporter performs.
+    class Reporter
+      def initialize
+        @examples = []
+        @mutex = Mutex.new
+      end
+
+      def record(example_observation)
+        @mutex.synchronize { @examples << example_observation }
+        self
+      end
+
+      def to_a
+        @mutex.synchronize { @examples.dup }
+      end
+
+      # Ordered by file path then line number, independent of RSpec run order
+      # (`--order random` reshuffles examples but must not reshuffle the
+      # artifact), so two runs of an unchanged suite produce identical JSON.
+      def write(path)
+        browser_facing = @mutex.synchronize { @examples.select(&:browser_facing?) }
+        ordered = browser_facing.sort_by { |example| [example.file_path.to_s, example.line_number.to_i] }
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(ordered.map { |example| serialize(example) })}\n")
+        path
+      end
+
+      private
+
+      # rubocop:disable Metrics/MethodLength
+      def serialize(example)
+        {
+          "example_id" => example.example_id,
+          "file_path" => example.file_path,
+          "line_number" => example.line_number,
+          "spec_type" => example.spec_type&.to_s,
+          "description_parts" => example.description_parts,
+          "full_description" => example.full_description,
+          "karst_explicit" => example.karst_explicit,
+          "karst_name" => example.karst_name,
+          "outcome" => example.outcome.to_s,
+          "requests" => example.requests.map { |request| serialize_request(request) }
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength
+      def serialize_request(request)
+        {
+          "sequence" => request.sequence,
+          "method" => request.http_method,
+          "path" => request.path,
+          "route_pattern" => request.route_pattern,
+          "controller" => request.controller,
+          "action" => request.action,
+          "format" => request.format,
+          "status" => request.status,
+          "redirect_location" => request.redirect_location,
+          "principal_before" => serialize_principal(request.principal_before),
+          "principal_after" => serialize_principal(request.principal_after),
+          "principal_changed" => request.principal_changed
+        }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def serialize_principal(principal)
+        return nil unless principal
+
+        { "type" => principal.type, "id" => principal.id, "scope" => principal.scope&.to_s }
+      end
+    end
+  end
+end

data/lib/karst/spec/request_observation.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Karst
+  module Spec
+    # One HTTP request observed during a single RSpec example.
+    #
+    # `principal_before`/`principal_after` are the active Warden principal
+    # immediately before and immediately after this request was processed;
+    # `principal_changed` is true when they differ -- a login, a logout, or a
+    # switch from one principal to another. This is raw observed evidence,
+    # not an interpretation of what the request was FOR. Karst does not
+    # classify a request as "setup" or "the subject under test": a signup
+    # route, an invitation-acceptance route, or a checkout-completion route
+    # that happens to establish a session is a legitimate subject request,
+    # not authentication plumbing, and a single request carries no reliable
+    # signal for telling those apart. That classification, if Karst ever
+    # offers one, belongs to catalog-building logic downstream of this
+    # observer, informed by more context than one request can supply.
+    #
+    # Named `http_method`, not `method`, so it never shadows Object#method.
+    RequestObservation = Value.define(
+      :sequence,
+      :http_method,
+      :path,
+      :route_pattern,
+      :controller,
+      :action,
+      :format,
+      :status,
+      :redirect_location,
+      :principal_before,
+      :principal_after,
+      :principal_changed
+    )
+  end
+end