actionable-rb 1.9.0

data/lib/actionable/result.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Actionable
+  # The single value object a run returns. {Success} and {Failure} are the
+  # concrete subclasses; +Result+ itself is abstract and defines the shared,
+  # FieldStruct-backed shape (decision D5).
+  #
+  # @abstract Instantiate {Success} or {Failure}, not +Result+ directly.
+  class Result < FieldStruct::Base
+    # @return [Symbol] +:success+ for a {Success}; the error symbol for a {Failure}
+    required :code, :symbol
+
+    # @return [String, nil] human-readable description of the outcome
+    optional :message, :string
+
+    # NOTE: +errors+ is intentionally NOT a declared field. It is FieldStruct's
+    # own per-instance, Hash-like {FieldStruct::Errors} collection (decision D5,
+    # "integrates with FieldStruct"); declaring a field of the same name would
+    # shadow the framework's validation machinery.
+
+    # @return [Object] the run's declared, typed output payload (empty by default).
+    #   Firms up into an output FieldStruct once output schemas land (D6).
+    optional :output, :value, default: -> { {} }
+
+    # @return [Object] the run's execution history (empty by default).
+    #   Firms up into a +History+ once measurement lands (D10).
+    optional :history, :value, default: -> { [] }
+
+    # The output fields the run actually set (captured instance variables and
+    # +succeed+/+skip+ kwargs), as opposed to fields left nil or at their
+    # default. A parent absorbing a nested action's output copies only these
+    # (decision D3). +nil+ when unknown, e.g. a hand-built result.
+    #
+    # @api private
+    # @return [Array<Symbol>, nil]
+    attr_accessor :output_fields_set
+
+    # @return [Boolean] whether the run succeeded. Abstract here; each
+    #   subclass flips the predicate that applies to it.
+    def success?
+      false
+    end
+
+    # @return [Boolean] whether the run failed.
+    def failure?
+      false
+    end
+
+    # @return [Boolean] whether the run was skipped — nothing to do, neither a
+    #   success nor a failure (decision D17). Abstract here; {Skipped} flips it.
+    def skipped?
+      false
+    end
+
+    # @return [Boolean] alias of {#success?}
+    def successful?
+      success?
+    end
+
+    # @return [Boolean] alias of {#failure?}
+    def failed?
+      failure?
+    end
+
+    # @return [Boolean] whether the run did not fail — true for both a
+    #   {Success} and a {Skipped}. The "happy path didn't error" check.
+    def ok?
+      !failure?
+    end
+
+    # @return [String] a compact, field-sorted, deterministic representation —
+    #   the declared attributes plus the +errors+ collection, sorted by name,
+    #   so equal results always render identically.
+    def inspect
+      pairs = attributes.merge(errors: errors.to_h)
+        .sort_by { |name, _| name.to_s }
+        .map { |name, value| "#{name}=#{value.inspect}" }
+      "#<#{self.class.name} #{pairs.join(" ")}>"
+    end
+
+    # @return [String] same deterministic representation as {#inspect}
+    def to_s
+      inspect
+    end
+
+    # @return [Symbol] the outcome as a single symbol — +:success+, +:failure+,
+    #   or +:skipped+. The coarse-grained companion to the specific {#code}.
+    def status
+      return :success if success?
+      return :skipped if skipped?
+
+      :failure
+    end
+
+    # A plain-Hash view of the result — +code+, +message+, the +output+ and
+    # +history+ rendered to primitives, and the +errors+ collection as a Hash
+    # (decision D19). The serializable companion to {#inspect}.
+    #
+    # @return [Hash{Symbol=>Object}]
+    def to_h
+      {
+        code: code,
+        message: message,
+        output: output.respond_to?(:to_h) ? output.to_h : output,
+        history: history.is_a?(History) ? history.as_json : history,
+        errors: errors.to_h
+      }
+    end
+
+    # A compact element for an HTTP/batch response: the item's position, its
+    # {#status}, the id read off the typed output, and its errors (decision
+    # D19). Lets a controller map a batch of results without hand-rolling the
+    # shape.
+    #
+    #   results.each_with_index.map { |r, i| r.to_api_h(index: i) }
+    #
+    # @param index [Integer, nil] the element's position in a batch
+    # @param id_field [Symbol] the output field to surface as +:id+ (default +:id+)
+    # @return [Hash{Symbol=>Object}]
+    def to_api_h(index: nil, id_field: :id)
+      {index: index, status: status, id: output_field(id_field), errors: errors.to_h}
+    end
+
+    # Convenience delegation: a declared output field is readable straight off
+    # the result (+result.invoice+ → +result.output.invoice+). Only fields
+    # declared on a typed output schema delegate; incidental data never does
+    # (decision D6).
+    #
+    # @param name [Symbol] the method name asked about (Ruby passes a Symbol)
+    # @param include_private [Boolean] whether private methods count
+    # @return [Boolean]
+    def respond_to_missing?(name, include_private = false)
+      delegates_to_output?(name) || super
+    end
+
+    # @see #respond_to_missing?
+    # @param name [Symbol] the method called
+    # @param args [Object] its arguments, forwarded to the output
+    # @return [undefined] the output field's value: left untyped on purpose,
+    #   like any field reader whose type the schema decides
+    def method_missing(name, *args, &block)
+      return output.public_send(name, *args, &block) if delegates_to_output?(name)
+
+      super
+    end
+
+    private
+
+    # @param name [Symbol]
+    # @return [Boolean] whether +name+ is a declared field on a typed output
+    def delegates_to_output?(name)
+      output.is_a?(FieldStruct::Base) && output.attribute_names.include?(name)
+    end
+
+    # Read +name+ off the output — a declared field on a typed output, a key on
+    # a Hash output, or +nil+ when absent.
+    #
+    # @param name [Symbol]
+    # @return [Object, nil]
+    def output_field(name)
+      return output.public_send(name) if delegates_to_output?(name)
+
+      output[name] if output.respond_to?(:[])
+    end
+  end
+end

data/lib/actionable/results/failure.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Actionable
+  # A failed run's result. Its +code+ is the error symbol describing why the
+  # run failed (e.g. +:not_found+, +:invalid_input+), defaulting to +:error+.
+  class Failure < Result
+    # @return [Symbol] the error code; defaults to +:error+
+    required :code, :symbol, default: :error
+
+    # @return [Hash{Symbol=>Object}] the metadata the action declared for this
+    #   code with {Action.fails} (decision D20), so an adapter can read it off the
+    #   result without the action class. Empty when the code isn't declared.
+    #   The gem stores and passes it through but never interprets it.
+    optional :metadata, :value, default: -> { {} }
+
+    # @return [true]
+    def failure?
+      true
+    end
+
+    # A plain-Hash view of the failure: {Result#to_h} plus its declared
+    # +metadata+ (decision D20).
+    #
+    # @return [Hash{Symbol=>Object}]
+    def to_h
+      super.merge(metadata: metadata)
+    end
+
+    # Copy another object's FieldStruct-style errors onto this failure's own
+    # errors collection. The shared mechanism behind +Failure(:invalid_input)+,
+    # +Failure(:invalid_output)+, and the {Action#fail_with} verb (decision D19).
+    #
+    # @param source [#errors] any object whose +errors+ responds to +to_h+
+    #   (a +FieldStruct::Base+ instance, or another result)
+    # @return [self] so callers can build-and-absorb in one expression
+    def absorb_errors_from(source)
+      source.errors.to_h.each do |field, messages|
+        Array(messages).each { |message| errors.add(field, message) }
+      end
+      self
+    end
+  end
+end

data/lib/actionable/results/skipped.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Actionable
+  # A skipped run's result (decision D17): the action had nothing to do — not a
+  # success (no real work), but not a failure either. Its +code+ is the skip
+  # reason (e.g. +:not_ready+), defaulting to +:skipped+.
+  class Skipped < Result
+    # @return [Symbol] the skip reason; defaults to +:skipped+
+    required :code, :symbol, default: :skipped
+
+    # @return [Hash{Symbol=>Object}] the metadata the action declared for this
+    #   code with {Action.skips} (decision D21), so an adapter can read it off the
+    #   result without the action class. Empty when the code isn't declared.
+    #   The gem stores and passes it through but never interprets it.
+    optional :metadata, :value, default: -> { {} }
+
+    # @return [true]
+    def skipped?
+      true
+    end
+
+    # A plain-Hash view of the skip: {Result#to_h} plus its declared +metadata+
+    # (decision D21).
+    #
+    # @return [Hash{Symbol=>Object}]
+    def to_h
+      super.merge(metadata: metadata)
+    end
+  end
+end

data/lib/actionable/results/success.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Actionable
+  # A successful run's result. Its +code+ defaults to +:success+.
+  class Success < Result
+    # @return [Symbol] always +:success+ unless explicitly overridden
+    required :code, :symbol, default: :success
+
+    # @return [true]
+    def success?
+      true
+    end
+  end
+end

data/lib/actionable/rspec/coverage/report.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'oj'
+require 'yaml'
+require_relative 'tracker'
+
+module Actionable
+  module Coverage
+    # Raised when the outcomes no spec reached differ from the committed
+    # baseline (decision D22). Its message says exactly what to change.
+    class BaselineMismatch < Actionable::Error; end
+
+    class << self
+      # Build the {Report}, print it to +io+, and hold it to the baseline: the
+      # end-of-suite step, and the merge step of a sharded suite.
+      #
+      # With +ACTIONABLE_COVERAGE_JSON+ set, also writes the JSON report to
+      # that path. With +ACTIONABLE_COVERAGE_UPDATE_BASELINE=true+, rewrites
+      # {.baseline} from the current gaps instead of checking it.
+      #
+      # @param files [Array<String>, String] shard files from {.write}, or a glob
+      # @param io [IO] where the text report goes
+      # @raise [BaselineMismatch] when the gaps differ from the baseline
+      # @return [Report]
+      def report!(files: [], io: $stdout)
+        report = Report.new(files: files)
+        io.puts report.to_s
+        json_path = ENV['ACTIONABLE_COVERAGE_JSON'].to_s
+        File.write(json_path, report.to_json) unless json_path.empty?
+
+        if ENV['ACTIONABLE_COVERAGE_UPDATE_BASELINE'].to_s == 'true'
+          io.puts "Actionable outcome coverage: wrote the baseline to #{report.write_baseline}"
+        elsif !report.passed?
+          raise BaselineMismatch, report.baseline_message
+        end
+        report
+      end
+    end
+
+    # The outcome-coverage report (decision D22): for each reported action
+    # ({Coverage.actions}), the outcomes it can end with
+    # ({Coverage.expected_outcomes}) against the outcomes real runs reached.
+    # A text table for people, JSON for machines, and a check against the
+    # baseline of known gaps in {Coverage.baseline}.
+    class Report
+      # @param files [Array<String>, String] shard files written by
+      #   {Coverage.write}, or a glob for them, merged with +observed+ and
+      #   +stubbed+
+      # @param observed [Enumerable<Array(String, Symbol, Symbol)>] real runs,
+      #   as +[class name, outcome, code]+; defaults to {Coverage.observed}
+      # @param stubbed [Enumerable<Array(String, Symbol, Symbol)>] runs answered
+      #   by a stub helper; defaults to {Coverage.stubbed}
+      # @raise [Actionable::Error] when +files+ is a glob that matches nothing
+      def initialize(files: [], observed: Coverage.observed, stubbed: Coverage.stubbed)
+        observed = observed.to_set
+        stubbed = stubbed.to_set
+        shard_files(files).each do |path|
+          shard = Coverage.read(path)
+          observed.merge(shard[:observed])
+          stubbed.merge(shard[:stubbed])
+        end
+        @observed = keys_by_action(observed)
+        @stubbed = keys_by_action(stubbed)
+      end
+
+      # One row per reported action. Under {Coverage.only_observed}, only
+      # actions with at least one real run are reported.
+      #
+      # @return [Array<Hash{Symbol=>Object}>] +{action:, expected:, reached:,
+      #   missing:, stubbed_only:}+, outcome lists as outcome keys
+      def rows
+        @rows ||= reported_actions.map do |klass|
+          expected = Coverage.expected_outcomes(klass)
+          seen = @observed.fetch(klass.name, Set.new)
+          stubbed = @stubbed.fetch(klass.name, Set.new)
+          missing = expected.reject { |key| seen.include?(key) }
+          {
+            action: klass.name,
+            expected: expected,
+            reached: expected.select { |key| seen.include?(key) },
+            missing: missing,
+            stubbed_only: missing.select { |key| stubbed.include?(key) }
+          }
+        end
+      end
+
+      # @return [Hash{Symbol=>Integer}] +{actions:, expected:, reached:, missing:}+
+      def totals
+        {
+          actions: rows.size,
+          expected: rows.sum { |row| row[:expected].size },
+          reached: rows.sum { |row| row[:reached].size },
+          missing: rows.sum { |row| row[:missing].size }
+        }
+      end
+
+      # A text table of each action with never-reached outcomes, the subset
+      # only ever stubbed, and the totals.
+      #
+      # @return [String]
+      def to_s
+        lines = ['Actionable outcome coverage']
+        gaps = rows.reject { |row| row[:missing].empty? }
+        if gaps.empty?
+          lines << '  every expected outcome was reached'
+        else
+          table = [['Action', 'Never reached', 'Stubbed only']] +
+            gaps.map { |row| [row[:action], row[:missing].join(', '), row[:stubbed_only].join(', ')] }
+          widths = table.transpose.map { |column| column.map(&:length).max }
+          table.each { |cells| lines << "  #{cells.each_with_index.map { |cell, i| cell.ljust(widths[i]) }.join("  ").rstrip}" }
+        end
+        t = totals
+        lines << "Actions: #{t[:actions]}  Expected outcomes: #{t[:expected]}  " \
+                 "Reached: #{t[:reached]}  Missing: #{t[:missing]}"
+        lines.join("\n")
+      end
+
+      # @return [Hash{Symbol=>Object}] +{actions: rows, totals:}+
+      def to_h
+        {actions: rows, totals: totals}
+      end
+
+      # @return [String] {#to_h} as JSON
+      def to_json(*)
+        Oj.dump(to_h, mode: :compat)
+      end
+
+      # The current gaps in baseline form: each action with never-reached
+      # outcomes, mapped to them.
+      #
+      # @return [Hash{String=>Array<String>}]
+      def to_baseline
+        rows.reject { |row| row[:missing].empty? }.to_h { |row| [row[:action], row[:missing]] }
+      end
+
+      # Write {#to_baseline} to +path+, as YAML for a +.yml+ / +.yaml+ path
+      # and JSON otherwise. For adoption day, and for accepting a change in
+      # the gaps deliberately.
+      #
+      # @param path [String]
+      # @return [String] +path+
+      def write_baseline(path = Coverage.baseline)
+        raise ArgumentError, 'no baseline path given and Coverage.baseline is not set' if path.nil?
+
+        contents = yaml?(path) ? YAML.dump(to_baseline) : "#{Oj.dump(to_baseline, mode: :compat, indent: 2)}\n"
+        File.write(path, contents)
+        path
+      end
+
+      # The differences from {Coverage.baseline}: never-reached outcomes it
+      # doesn't list (+new_gaps+), and entries that are now reached, no longer
+      # expected, or name an action that no longer exists (+stale+). Under
+      # {Coverage.only_observed}, an existing action with no run is not
+      # judged. Both empty without a baseline.
+      #
+      # @return [Hash{Symbol=>Hash{String=>Array<String>}}] +{new_gaps:, stale:}+
+      # @raise [Actionable::Error] when the baseline file doesn't exist
+      def baseline_problems
+        @baseline_problems ||= compare_with_baseline
+      end
+
+      # Whether the report agrees with {Coverage.baseline}. Always true
+      # without a baseline: missing outcomes alone never fail.
+      #
+      # @return [Boolean]
+      def passed?
+        baseline_problems.values.all?(&:empty?)
+      end
+
+      # What to change so the report agrees with the baseline, or +nil+ when
+      # it already does.
+      #
+      # @return [String, nil]
+      def baseline_message
+        return if passed?
+
+        problems = baseline_problems
+        lines = ["Actionable outcome coverage differs from the baseline in #{Coverage.baseline}."]
+        unless problems[:new_gaps].empty?
+          lines << "New untested outcomes. #{Coverage.new_gap_hint}"
+          lines.concat(entry_lines(problems[:new_gaps]))
+        end
+        unless problems[:stale].empty?
+          lines << 'Covered, or no longer declared. Remove each one from the baseline:'
+          lines.concat(entry_lines(problems[:stale]))
+        end
+        lines << 'To rewrite the baseline from the current gaps, run the report with ' \
+                 'ACTIONABLE_COVERAGE_UPDATE_BASELINE=true.'
+        lines.join("\n")
+      end
+
+      private
+
+      # An empty merge would report every outcome missing, so a glob that
+      # matches nothing is an error rather than a report.
+      def shard_files(files)
+        return Array(files) unless files.is_a?(String)
+
+        paths = Dir.glob(files)
+        raise Actionable::Error, "no coverage files match #{files}" if paths.empty?
+
+        paths
+      end
+
+      # @return [Hash{String=>Set<String>}] outcome keys reached, by action name
+      def keys_by_action(observations)
+        observations.each_with_object({}) do |(name, outcome, code), by_action|
+          (by_action[name.to_s] ||= Set.new) << Coverage.outcome_key(outcome, code)
+        end
+      end
+
+      def all_actions
+        @all_actions ||= Coverage.actions
+      end
+
+      def reported_actions
+        return all_actions unless Coverage.only_observed
+
+        all_actions.select { |klass| @observed.key?(klass.name) }
+      end
+
+      def compare_with_baseline
+        return {new_gaps: {}, stale: {}} if Coverage.baseline.nil?
+
+        baseline = load_baseline(Coverage.baseline)
+        gaps = to_baseline
+        new_gaps = gaps.filter_map do |action, missing|
+          added = missing - baseline.fetch(action, [])
+          [action, added] unless added.empty?
+        end.to_h
+        {new_gaps: new_gaps, stale: stale_entries(baseline, gaps)}
+      end
+
+      # Baseline entries to remove: the action is gone, or it is reported and
+      # the outcome is no longer a gap (reached, or no longer expected).
+      def stale_entries(baseline, gaps)
+        known = all_actions.map(&:name)
+        reported = rows.map { |row| row[:action] }
+        baseline.filter_map do |action, keys|
+          stale = if !known.include?(action) then keys
+                  elsif reported.include?(action) then keys - gaps.fetch(action, [])
+                  else []
+                  end
+          [action, stale] unless stale.empty?
+        end.to_h
+      end
+
+      def load_baseline(path)
+        raise Actionable::Error, "Coverage.baseline #{path} does not exist; write it with Report#write_baseline" unless File.exist?(path)
+
+        data = yaml?(path) ? YAML.safe_load_file(path) : Oj.load(File.read(path), mode: :compat)
+        (data || {}).to_h { |action, keys| [action.to_s, Array(keys).map(&:to_s)] }
+      end
+
+      def entry_lines(entries)
+        entries.map { |action, keys| "  #{action}: #{keys.join(", ")}" }
+      end
+
+      def yaml?(path)
+        path.to_s.end_with?('.yml', '.yaml')
+      end
+    end
+  end
+end