karst 0.1.0 → 0.2.0

data/lib/karst/access/population_preview.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../value"
-require_relative "candidate_population"
-
-module Karst
-  module Access
-    # The explicit, bounded "does this discovered candidate actually work"
-    # step -- deliberately separate from Karst::Access::PopulationDiscovery,
-    # which never executes anything. Only ever resolves a model/method pair
-    # that a given Karst::Access::PopulationDiscovery::Result itself already
-    # discovered; a submitted name that is not on that list is rejected
-    # without calling anything, so this can never become a general "call any
-    # class method by name" endpoint. Every resolution is bounded to
-    # PREVIEW_LIMIT rows via Karst::Access::CandidatePopulation.resolve --
-    # never a COUNT, never full materialization.
-    class PopulationPreview
-      PREVIEW_LIMIT = 3
-
-      Result = Value.define(:model_name, :method_name, :resolved, :records, :error)
-
-      def self.call(model_name:, method_name:, discovery_result:)
-        new(model_name: model_name, method_name: method_name, discovery_result: discovery_result).call
-      end
-
-      def initialize(model_name:, method_name:, discovery_result:)
-        @model_name = model_name.to_s
-        @method_name = method_name.to_s
-        @discovery_result = discovery_result
-      end
-
-      def call
-        return unresolved("this is not a discovered candidate") unless known_candidate?
-
-        klass = model_class
-        return unresolved("the model could not be resolved") unless klass
-
-        resolve(klass)
-      end
-
-      private
-
-      def known_candidate?
-        @discovery_result.candidates.any? do |candidate|
-          candidate.model_name == @model_name && candidate.method_name.to_s == @method_name
-        end
-      end
-
-      def model_class
-        return nil unless defined?(ActiveRecord::Base)
-
-        ActiveRecord::Base.descendants.find { |klass| klass.name == @model_name }
-      end
-
-      def resolve(klass)
-        method_name = @method_name
-        return missing_scope unless scope_exists?(klass, method_name)
-
-        population = CandidatePopulation.resolve(
-          name: method_name.to_sym, callable: -> { klass.public_send(method_name) },
-          source_klass: klass, limit: PREVIEW_LIMIT
-        )
-        return unresolved("did not resolve to a usable ActiveRecord::Relation for #{@model_name}") unless population
-
-        Result.new(model_name: @model_name, method_name: @method_name, resolved: true, records: population.records,
-                   error: nil)
-      end
-
-      def scope_exists?(klass, method_name)
-        klass.respond_to?(method_name)
-      end
-
-      def missing_scope
-        unresolved("the discovered scope no longer exists on #{@model_name}")
-      end
-
-      def unresolved(error)
-        Result.new(model_name: @model_name, method_name: @method_name, resolved: false, records: [].freeze,
-                   error: error)
-      end
-    end
-  end
-end

data/lib/karst/access/resource_evidence.rb

@@ -1,233 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/core_ext/string/inflections"
-require_relative "../value"
-require_relative "../identity"
-
-module Karst
-  module Access
-    # Given one exact resource (the specific record a route addresses by id)
-    # and one specific principal (typically the successful outcome from an
-    # Access::Sweep), reports simple, directly observed foreign-key
-    # relationships between those two records. This is evidence, not an
-    # authorization claim: it never states or implies *why* an outcome
-    # occurred, only which foreign-key columns, if any, point from one given
-    # record to the other's id.
-    #
-    # Deliberately narrow, matching the v1 scope this class was built for:
-    # - only foreign-key-shaped columns (ending in "_id") on the two given
-    #   records are ever inspected -- never an arbitrary attribute, so no
-    #   other column value (name, email, token, ...) is ever read or shown;
-    # - only a direct column-value comparison between the two given records,
-    #   never a join, a has_many traversal, or any multi-hop graph walk;
-    # - resource resolution from a route path is attempted only through
-    #   Rails' own route recognition plus its controller-to-model naming
-    #   convention, and only trusted when every step succeeds unambiguously
-    #   (a recognized route with an :id segment, a controller name that
-    #   classifies to a real loaded Active Record class, and a record that
-    #   actually exists for that id). Anything softer -- an unrecognized
-    #   route, a controller with no conventional model, a missing record --
-    #   is reported as a limitation rather than guessed at.
-    # rubocop:disable Metrics/ClassLength
-    class ResourceEvidence
-      class Error < StandardError; end
-
-      # The resource side never gets Identity::PrincipalDescriptor's
-      # configurable display_label hook -- there is no equivalent concept
-      # for "the current route's resource" -- so it gets its own minimal,
-      # equally attribute-free descriptor.
-      ResourceDescriptor = Value.define(:model_name, :id)
-
-      # from_model/from_id is whichever of the resource/principal actually
-      # holds the foreign-key column; to_model/to_id is the other side.
-      Relationship = Value.define(:column, :from_model, :from_id, :to_model, :to_id)
-
-      Result = Value.define(:principal, :resource, :relationships, :observed_status, :observed_redirect,
-                            :limitation) do
-        # Plain-text rendering deliberately kept free of causal wording
-        # ("owns", "is authorized", "grants") -- see class comment above.
-        def to_text
-          lines = [principal.display_label]
-          lines << observed_line if observed_status || observed_redirect
-          lines << "" << "Related state:"
-          lines.concat(related_state_lines)
-          lines.join("\n")
-        end
-
-        private
-
-        def observed_line
-          observed_redirect ? "Observed #{observed_status} → #{observed_redirect}" : "Observed #{observed_status}"
-        end
-
-        def related_state_lines
-          return ["  Unavailable: #{limitation}"] if limitation
-          return [no_relationship_line] if relationships.empty?
-
-          grouped_relationship_lines
-        end
-
-        def no_relationship_line
-          "  No observed foreign-key relationship to #{resource.model_name} ##{resource.id}."
-        end
-
-        def grouped_relationship_lines
-          relationships.group_by { |rel| [rel.from_model, rel.from_id] }.flat_map do |(model, id), grouped|
-            ["#{model} ##{id}"] + grouped.map { |rel| "  #{rel.column} → #{rel.to_model} ##{rel.to_id}" }
-          end
-        end
-      end
-
-      class << self
-        # Resolves the resource, resolves the principal (from a
-        # Sweep::Outcome's PrincipalDescriptor), and reports relationships in
-        # one call. Either resolution step may fail safely -- see
-        # #resolve_resource and #resolve_principal -- in which case the
-        # Result carries a limitation instead of relationships.
-        def for_outcome(outcome:, path:, http_method: "GET", application: nil)
-          resource, resource_limitation = resolve_resource(path: path, http_method: http_method,
-                                                           application: application)
-          principal, principal_limitation = resolve_principal(outcome.principal)
-          limitation = [resource_limitation, principal_limitation].compact.join("; ")
-
-          return unresolved_result(outcome, limitation) if resource.nil? || principal.nil?
-
-          new(resource: resource, principal: principal).call(
-            observed_status: outcome.status, observed_redirect: outcome.redirect
-          )
-        end
-
-        # Attempts to resolve the exact record a route addresses, trusting
-        # only Rails' own route recognition and controller naming
-        # convention, and only when every step is unambiguous. Returns
-        # [record, nil] on success or [nil, reason] when any step is not
-        # reliable -- never a guessed record.
-        def resolve_resource(path:, http_method: "GET", application: nil)
-          app = application || rails_application
-          return [nil, "no Rails application is available to recognize the route"] unless app
-
-          params = recognize(app, path, http_method)
-          return [nil, "the route could not be recognized"] unless params
-
-          id = params[:id]
-          return [nil, "the recognized route has no :id segment addressing one specific resource"] unless id
-
-          find_by_controller(params[:controller], id)
-        end
-
-        # Resolves the actual record behind a Karst::Identity::PrincipalDescriptor
-        # only through the configured principal source. A valid model/id outside
-        # that source is deliberately unresolved.
-        def resolve_principal(descriptor)
-          record = Identity.resolve(model_name: descriptor.model_name, id: descriptor.id)
-          return [nil, "principal is not available from the configured principal source"] unless record
-
-          [record, nil]
-        rescue Identity::Error
-          [nil, "the configured principal source is unavailable"]
-        end
-
-        private
-
-        def rails_application
-          defined?(Rails) && Rails.respond_to?(:application) && Rails.application
-        end
-
-        def find_by_controller(controller, id)
-          klass = active_record_class(controller.to_s.classify)
-          return [nil, "the route's controller does not map to a loaded Active Record model by convention"] unless klass
-
-          record = klass.find_by(klass.primary_key => id)
-          return [nil, "no #{klass.name} record exists for id #{id.inspect}"] unless record
-
-          [record, nil]
-        end
-
-        def unresolved_result(outcome, limitation)
-          Result.new(principal: outcome.principal, resource: nil, relationships: [].freeze,
-                     observed_status: outcome.status, observed_redirect: outcome.redirect,
-                     limitation: limitation.empty? ? "the resource or principal could not be resolved" : limitation)
-        end
-
-        def recognize(app, path, http_method)
-          app.routes.recognize_path(path, method: http_method)
-        rescue StandardError
-          nil
-        end
-
-        def active_record_class(name)
-          klass = name.to_s.safe_constantize
-          return nil unless defined?(ActiveRecord::Base) && klass.is_a?(Class) && klass < ActiveRecord::Base
-
-          klass
-        end
-      end
-
-      def initialize(resource:, principal:)
-        @resource = resource
-        @principal = principal
-      end
-
-      def call(observed_status: nil, observed_redirect: nil)
-        Result.new(
-          principal: Identity.describe(@principal),
-          resource: ResourceDescriptor.new(model_name: model_name(@resource), id: primary_key_value(@resource)),
-          relationships: relationships.freeze,
-          observed_status: observed_status,
-          observed_redirect: observed_redirect,
-          limitation: nil
-        )
-      end
-
-      private
-
-      def relationships
-        foreign_keys_from(@resource, @principal) + foreign_keys_from(@principal, @resource)
-      end
-
-      def foreign_keys_from(source, target)
-        return [] unless active_record?(source) && active_record?(target)
-
-        source.class.columns_hash.values.filter_map { |column| relationship_for(source, target, column) }
-      end
-
-      def relationship_for(source, target, column)
-        return unless foreign_key_column?(source.class, column)
-        return unless targets?(column, target.class)
-
-        value = source.public_send(column.name)
-        return if value.nil? || value != primary_key_value(target)
-
-        Relationship.new(column: column.name, from_model: model_name(source), from_id: primary_key_value(source),
-                         to_model: model_name(target), to_id: primary_key_value(target))
-      end
-
-      def foreign_key_column?(klass, column)
-        column.name.end_with?("_id") && column.name != klass.primary_key
-      end
-
-      # "Obvious" is judged purely from the column's own name against the
-      # target's actual class (including its Active Record ancestry, so a
-      # single-table-inherited subclass still matches its base class's
-      # conventional foreign key) -- never a declared association, never any
-      # other column's value, and never a second hop through another model.
-      def targets?(column, target_klass)
-        candidate = column.name.delete_suffix("_id").classify.safe_constantize
-        candidate.is_a?(Class) && (target_klass <= candidate || candidate <= target_klass)
-      end
-
-      def active_record?(record)
-        defined?(ActiveRecord::Base) && record.is_a?(ActiveRecord::Base)
-      end
-
-      def model_name(record)
-        record.class.respond_to?(:model_name) ? record.class.model_name.name.to_s : record.class.name.to_s
-      end
-
-      def primary_key_value(record)
-        record.public_send(record.class.primary_key)
-      end
-    end
-    # rubocop:enable Metrics/ClassLength
-  end
-end

data/lib/karst/spec/catalog.rb

@@ -1,199 +0,0 @@
-# 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

@@ -1,31 +0,0 @@
-# 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