Class: Rigor::FlowContribution

Inherits:
Object
  • Object
show all
Defined in:
lib/rigor/flow_contribution.rb

Overview

The public packaging of a flow contribution at a single call edge. Plugins, ‘RBS::Extended` annotations, and built-in narrowing rules all hand the analyzer this same bundle shape; the inference engine merges contributions through the policy described in [ADR-2 § “Plugin Contribution Merging”](../../docs/adr/2-extension-api.md) rather than letting any one source override another silently.

Eight content slots plus a Provenance block. A slot left as ‘nil` (or, for collection-shaped slots, an empty collection) means the contribution does not assert anything in that dimension; the merge policy treats it as absent.

The struct is the only shape plugin authors need to learn. Richer or more permissive shapes are not part of the first public contract — see ADR-2 § “Flow Contribution Bundle” for the binding definition.

The element-list flattening (‘to_element_list`) ADR-2 mentions is intentionally not implemented yet: it is the analyzer-internal bookkeeping behind the merge policy and will land alongside the plugin contribution merger in v0.1.0. Plugin authors should not rely on it.

Defined Under Namespace

Classes: Provenance

Constant Summary collapse

SLOT_NAMES = 
%i[
  return_type
  truthy_facts
  falsey_facts
  post_return_facts
  mutations
  invalidations
  exceptional
  role_conformance
].freeze

Instance Method Summary collapse

Constructor Details

#initialize(return_type: nil, truthy_facts: nil, falsey_facts: nil, post_return_facts: nil, mutations: nil, invalidations: nil, exceptional: nil, role_conformance: nil, provenance: Provenance.builtin) ⇒ FlowContribution

rubocop:disable Metrics/ParameterLists

Parameters:

  • return_type (Object, nil) (defaults to: nil) —

    normal-edge return type. Use ‘nil` when the contribution does not refine the return type selected from the RBS contract.

  • truthy_facts (Array, nil) (defaults to: nil) —

    facts that hold only on the truthy control-flow edge. Edge-local: a truthy-edge fact does NOT imply its falsey-edge complement (ADR-2 § “Plugin Contribution Merging”).

  • falsey_facts (Array, nil) (defaults to: nil) —

    dual of ‘truthy_facts`.

  • post_return_facts (Array, nil) (defaults to: nil) —

    facts that hold after the call returns normally on every edge — the carrier for assertion-style contributions.

  • mutations (Array, nil) (defaults to: nil) —

    receiver and argument mutation effects.

  • invalidations (Array, nil) (defaults to: nil) —

    targeted fact invalidations beyond what mutation effects already imply.

  • exceptional (Object, nil) (defaults to: nil) —

    non-returning, raising, or unreachable effect.

  • role_conformance (Array, nil) (defaults to: nil) —

    capability-role conformance facts the contribution provides.

  • provenance (Provenance) (defaults to: Provenance.builtin) —

    source-family, plugin-id, node, and cache-descriptor metadata. Defaults to ‘Provenance.builtin`.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/rigor/flow_contribution.rb', line 74

def initialize(return_type: nil, truthy_facts: nil, falsey_facts: nil,
               post_return_facts: nil, mutations: nil, invalidations: nil,
               exceptional: nil, role_conformance: nil,
               provenance: Provenance.builtin)
  # rubocop:enable Metrics/ParameterLists
  @return_type = return_type
  @truthy_facts = freeze_collection(truthy_facts)
  @falsey_facts = freeze_collection(falsey_facts)
  @post_return_facts = freeze_collection(post_return_facts)
  @mutations = freeze_collection(mutations)
  @invalidations = freeze_collection(invalidations)
  @exceptional = exceptional
  @role_conformance = freeze_collection(role_conformance)
  @provenance = provenance
  freeze
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



104
105
106
 
# File 'lib/rigor/flow_contribution.rb', line 104

def ==(other)
  other.is_a?(FlowContribution) && to_h == other.to_h
end

#empty? ⇒ Boolean

Returns true when every content slot is unset (nil or an empty collection). Provenance does not count toward emptiness — an empty bundle still carries source attribution.

Returns:

  • (Boolean) —

    true when every content slot is unset (nil or an empty collection). Provenance does not count toward emptiness — an empty bundle still carries source attribution.



94
95
96
 
# File 'lib/rigor/flow_contribution.rb', line 94

def empty?
  SLOT_NAMES.all? { |slot| slot_empty?(public_send(slot)) }
end

#hash ⇒ Object 



109
110
111
 
# File 'lib/rigor/flow_contribution.rb', line 109

def hash
  to_h.hash
end

#to_h ⇒ Object 



98
99
100
101
102
 
# File 'lib/rigor/flow_contribution.rb', line 98

def to_h
  SLOT_NAMES.each_with_object(provenance: provenance.to_h) do |slot, acc|
    acc[slot] = public_send(slot)
  end
end