rigortype 0.1.15 → 0.1.16

data/lib/rigor/plugin/base.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
 require "digest"
 require "json"
+require "prism"
 
 require_relative "manifest"
+require_relative "node_context"
+require_relative "../analysis/diagnostic"
+require_relative "../source/node_walker"
 
 module Rigor
   module Plugin
@@ -34,7 +39,7 @@ module Rigor
     #   end
     #
     #   Rigor::Plugin.register(MyRailsPlugin)
-    class Base
+    class Base # rubocop:disable Metrics/ClassLength
       class << self
         # Declares the plugin's manifest. Called once at class
         # definition time — the resulting {Manifest} is cached on
@@ -94,13 +99,168 @@ module Rigor
         def producers
           (@producers || {}).dup.freeze
         end
+
+        # ADR-37 slice 1 — declares a node-scoped diagnostic rule.
+        # The engine owns a single AST walk per file (see
+        # {#node_rule_diagnostics}) and dispatches each node to the
+        # rules registered for its type, so a plugin author writes the
+        # check, never the traversal:
+        #
+        #   class MyPlugin < Rigor::Plugin::Base
+        #     manifest(id: "demo", version: "0.1.0")
+        #
+        #     node_rule Prism::CallNode do |node, scope, path|
+        #       next [] unless node.name == :transition_to
+        #       [diagnostic(node, path: path, message: "…", rule: "x")]
+        #     end
+        #   end
+        #
+        # `node_type` is a `Prism::Node` subclass; the rule fires for
+        # every node where `node.is_a?(node_type)`. The block runs
+        # through `instance_exec` so `self` is the plugin instance —
+        # `config`, `services`, `io_boundary`, `diagnostic`, and the
+        # cross-plugin `services.fact_store` are all in scope. It
+        # receives `(node, scope, path, file_context, context)` — the
+        # fourth argument is the value built by {.node_file_context} for
+        # a two-pass plugin (`nil` otherwise); the fifth is a
+        # {Rigor::Plugin::NodeContext} carrying the node's lexical
+        # ancestors (enclosing class / method / block DSL). Trailing
+        # arguments may be omitted from the block's parameter list. The
+        # block MUST return an Array of `Rigor::Analysis::Diagnostic`
+        # (an empty array to fire nothing); the runner stamps
+        # `plugin.<id>` provenance.
+        #
+        # Multiple rules for the same `node_type` are allowed and run
+        # in declaration order. This is the {.producer}-style class DSL
+        # rather than a manifest field because a rule carries logic that
+        # needs the plugin instance, not pure data.
+        def node_rule(node_type, &block)
+          raise ArgumentError, "Plugin::Base.node_rule requires a block body" if block.nil?
+          unless node_type.is_a?(Class) && node_type <= Prism::Node
+            raise ArgumentError,
+                  "Plugin::Base.node_rule node_type must be a Prism::Node subclass, got #{node_type.inspect}"
+          end
+
+          @node_rules ||= []
+          @node_rules << { node_type: node_type, block: block }.freeze
+          node_type
+        end
+
+        # Frozen snapshot of the declared node rules, in declaration
+        # order. Not inherited from a superclass — like {.producers},
+        # the loader instantiates one subclass per registration.
+        def node_rules
+          (@node_rules || []).dup.freeze
+        end
+
+        # ADR-37 slice 1c — declares a per-file context builder for a
+        # two-pass (collect-then-validate) plugin. The block runs once
+        # per analysed file (via `instance_exec`, so the plugin instance
+        # is `self`) BEFORE any node rule fires, receives `(root, scope)`,
+        # and returns an arbitrary file-local value that is threaded to
+        # every {.node_rule} block as its fourth argument:
+        #
+        #   node_file_context do |root, _scope|
+        #     collect_declared_states(root)        # the "collect" pass
+        #   end
+        #
+        #   node_rule Prism::CallNode do |node, _scope, path, states|
+        #     next [] unless transition_call?(node)
+        #     validate(node, path, states)         # the "validate" pass
+        #   end
+        #
+        # This is what lets a same-file two-pass plugin drop its
+        # hand-rolled validate walk: the collect pass computes the closed
+        # namespace once (it MUST complete before validation because a
+        # reference may precede its declaration), and the engine owns the
+        # validate walk. A cross-file collect belongs in `#prepare` +
+        # `services.fact_store` instead — a node rule reads the fact
+        # directly and needs no per-file context.
+        #
+        # Only one builder per plugin; a second declaration replaces the
+        # first. The block result is `nil` when none is declared.
+        def node_file_context(&block)
+          raise ArgumentError, "Plugin::Base.node_file_context requires a block body" if block.nil?
+
+          @node_file_context_block = block
+        end
+
+        # The declared per-file context builder block, or nil.
+        def node_file_context_block
+          defined?(@node_file_context_block) ? @node_file_context_block : nil
+        end
+
+        # ADR-37 slice 2 — declares a per-call-site return-type
+        # contribution, receiver-gated. The narrow successor to the
+        # `return_type` slot of `flow_contribution_for`:
+        #
+        #   dynamic_return receivers: ["ActiveRecord::Base"] do |call_node, scope|
+        #     # self = plugin instance; return a Rigor::Type or nil
+        #   end
+        #
+        # `receivers:` is a non-empty Array of class names; the engine
+        # calls the block only when the call's receiver type's class
+        # equals or inherits from one of them (via
+        # `Environment#class_ordering`). Method-name and type-shape
+        # refinement stays in the block, which returns a `Rigor::Type`
+        # (or `nil` to decline). The block runs through `instance_exec`,
+        # so `config` / `services` are in scope. This is the
+        # {.producer}-style class DSL (it carries logic needing the
+        # instance, not pure data).
+        def dynamic_return(receivers:, &block)
+          raise ArgumentError, "Plugin::Base.dynamic_return requires a block body" if block.nil?
+          unless receivers.is_a?(Array) && !receivers.empty? && receivers.all? { |r| r.is_a?(String) && !r.empty? }
+            raise ArgumentError,
+                  "Plugin::Base.dynamic_return receivers: must be a non-empty Array of class-name Strings, " \
+                  "got #{receivers.inspect}"
+          end
+
+          @dynamic_returns ||= []
+          @dynamic_returns << { receivers: receivers.map { |r| r.dup.freeze }.freeze, block: block }.freeze
+          nil
+        end
+
+        # Frozen snapshot of the declared dynamic-return rules.
+        def dynamic_returns
+          (@dynamic_returns || []).dup.freeze
+        end
+
+        # ADR-37 slice 2 — declares a predicate/assertion narrowing
+        # contribution, method-gated. The narrow successor to the
+        # `post_return_facts` slot of `flow_contribution_for`:
+        #
+        #   type_specifier methods: [:assert_kind_of] do |call_node, scope|
+        #     # return an Array of post-return facts, or nil
+        #   end
+        #
+        # `methods:` is a non-empty Array of method names; the engine
+        # calls the block only when `call_node.name` is one of them. The
+        # block returns the same `post_return_facts` the merger applies.
+        def type_specifier(methods:, &block)
+          raise ArgumentError, "Plugin::Base.type_specifier requires a block body" if block.nil?
+          unless methods.is_a?(Array) && !methods.empty? &&
+                 methods.all? { |m| m.is_a?(Symbol) || (m.is_a?(String) && !m.empty?) }
+            raise ArgumentError,
+                  "Plugin::Base.type_specifier methods: must be a non-empty Array of Symbol/String, " \
+                  "got #{methods.inspect}"
+          end
+
+          @type_specifiers ||= []
+          @type_specifiers << { methods: methods.map(&:to_sym).freeze, block: block }.freeze
+          nil
+        end
+
+        # Frozen snapshot of the declared type-specifier rules.
+        def type_specifiers
+          (@type_specifiers || []).dup.freeze
+        end
       end
 
       attr_reader :services, :config
 
       def initialize(services:, config: {})
         @services = services
-        @config = config.freeze
+        @config = merge_config_defaults(config).freeze
       end
 
       # Override in subclasses to wire any state the plugin needs
@@ -177,6 +337,129 @@ module Rigor
         []
       end
 
+      # ADR-37 slice 1 — runs the plugin's declared {.node_rule}s over
+      # one file and returns their diagnostics. The engine owns the
+      # single AST walk here so plugin authors never hand-roll a
+      # traversal: every node reachable from `root` is offered to each
+      # rule whose `node_type` it satisfies (`node.is_a?`), the rule's
+      # block is `instance_exec`'d on this plugin instance with
+      # `(node, scope, path)`, and the returned diagnostics are
+      # concatenated in (node, declaration) order.
+      #
+      # Returns `[]` immediately when the plugin declares no node rules,
+      # so it is a zero-cost no-op for every plugin that does not use
+      # the DSL. The runner calls it alongside `#diagnostics_for_file`
+      # and stamps `plugin.<id>` provenance on the result; a raise
+      # propagates to the runner's per-plugin isolation boundary.
+      def node_rule_diagnostics(path:, scope:, root:)
+        rules = self.class.node_rules
+        return [] if rules.empty? || root.nil?
+
+        # ADR-37 slice 1c — build the per-file context once (the
+        # "collect" pass) before the engine-owned validate walk, so a
+        # two-pass plugin sees the closed namespace at every node.
+        context_block = self.class.node_file_context_block
+        file_context = context_block ? instance_exec(root, scope, &context_block) : nil
+
+        diagnostics = []
+        Source::NodeWalker.each_with_ancestors(root) do |node, ancestors|
+          rules.each do |rule|
+            next unless node.is_a?(rule[:node_type])
+
+            context = NodeContext.new(ancestors)
+            diagnostics.concat(Array(instance_exec(node, scope, path, file_context, context, &rule[:block])))
+          end
+        end
+        diagnostics
+      end
+
+      # ADR-37 slice 2 — the return type contributed by this plugin's
+      # {.dynamic_return} rules for a call, or nil. The engine calls this
+      # from `MethodDispatcher` alongside (and ahead of) the legacy
+      # `flow_contribution_for`; a rule fires only when `receiver_type`'s
+      # class equals or inherits from one of its declared `receivers:`.
+      # First non-nil wins (declaration order). Failures isolate to nil.
+      def dynamic_return_type(call_node:, scope:, receiver_type:)
+        rules = self.class.dynamic_returns
+        return nil if rules.empty? || receiver_type.nil?
+
+        class_name = dynamic_return_receiver_class_name(receiver_type)
+        return nil if class_name.nil?
+
+        environment = scope&.environment
+        rules.each do |rule|
+          next unless rule[:receivers].any? { |c| class_matches_receiver?(class_name, c, environment) }
+
+          result = instance_exec(call_node, scope, &rule[:block])
+          return result if result
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # ADR-37 slice 2 — the post-return narrowing facts contributed by
+      # this plugin's {.type_specifier} rules for a call. The engine
+      # calls this from `StatementEvaluator` alongside the legacy
+      # `flow_contribution_for`; a rule fires only when `call_node.name`
+      # is one of its declared `methods:`. Failures isolate to [].
+      def type_specifier_facts(call_node:, scope:)
+        rules = self.class.type_specifiers
+        return [] if rules.empty? || !call_node.respond_to?(:name)
+
+        name = call_node.name
+        facts = []
+        rules.each do |rule|
+          next unless rule[:methods].include?(name)
+
+          result = instance_exec(call_node, scope, &rule[:block])
+          facts.concat(Array(result)) if result
+        end
+        facts
+      rescue StandardError
+        []
+      end
+
+      # Builds a `Rigor::Analysis::Diagnostic` positioned at a Prism
+      # `node` for return from `#diagnostics_for_file`. Internalises the
+      # 1-based `line` / `start_column + 1` convention every plugin
+      # otherwise re-derives by hand, so authors pass the node and the
+      # message/severity/rule rather than unpacking `node.location`.
+      #
+      # `source_family` is intentionally NOT accepted — the runner
+      # stamps `plugin.<manifest.id>` on every returned diagnostic
+      # (ADR-7 § "Slice 5-B"), so any value set here would be
+      # overwritten.
+      # Pass `location:` (a Prism location) to point the diagnostic at a
+      # sub-location of `node` rather than `node.location` — typically
+      # `node.message_loc` so a matcher / method-name diagnostic points
+      # at the name, not the receiver-spanning whole call. A `nil`
+      # `location:` falls back to `node.location`, so
+      # `location: node.message_loc` reproduces the common
+      # `message_loc || location` idiom.
+      def diagnostic(node, path:, message:, severity: :error, rule: nil, location: nil)
+        Analysis::Diagnostic.from_location(
+          location || node.location,
+          path: path, message: message, severity: severity, rule: rule
+        )
+      end
+
+      # Boilerplate-reduction helper (review §1.3): the "did you mean …?"
+      # suggestion every diagnostic-emitting plugin otherwise hand-rolls.
+      # Returns the closest of `candidates` to `name` via
+      # `DidYouMean::SpellChecker` (the same engine Ruby's own
+      # `NoMethodError` hints use), or `nil` when there is no good match /
+      # no candidates — replacing the per-plugin Levenshtein copies. A
+      # **class** method so it is callable both from a plugin instance
+      # (`Rigor::Plugin::Base.suggest(...)`) and from an `Analyzer` module
+      # function that has no instance.
+      def self.suggest(name, candidates)
+        dictionary = Array(candidates).map(&:to_s)
+        return nil if dictionary.empty?
+
+        DidYouMean::SpellChecker.new(dictionary: dictionary).correct(name.to_s).first
+      end
+
       # Convenience accessor — `manifest` on the instance returns
       # the class-level manifest declaration.
       def manifest
@@ -337,6 +620,42 @@ module Rigor
 
       private
 
+      # ADR-40 — merge the manifest's declared `config_schema`
+      # `default:` values *under* the user-supplied config (user wins),
+      # so a plugin reads `config.fetch("key")` and gets the declared
+      # default with no `DEFAULT_*` constant. A class declared without a
+      # manifest (test doubles) keeps the raw config unchanged.
+      def merge_config_defaults(config)
+        unless self.class.instance_variable_defined?(:@manifest) && self.class.instance_variable_get(:@manifest)
+          return config
+        end
+
+        self.class.manifest.config_defaults.merge(config)
+      end
+
+      # ADR-37 slice 2 — the class name to match a `dynamic_return`
+      # `receivers:` entry against, from a receiver `Type`. Covers the
+      # instance (`Nominal[X]`) and class (`Singleton[X]`) shapes; other
+      # carriers decline (nil → no match).
+      def dynamic_return_receiver_class_name(receiver_type)
+        case receiver_type
+        when Rigor::Type::Nominal, Rigor::Type::Singleton then receiver_type.class_name
+        end
+      end
+
+      # True when `class_name` equals or inherits from `constraint`,
+      # matched through `Environment#class_ordering` (the mechanism
+      # `MacroBlockSelfType` / `additional_initializers` use). Degrades to
+      # "no match" on any resolution failure (false-positive-safe).
+      def class_matches_receiver?(class_name, constraint, environment)
+        return true if class_name == constraint
+        return false if environment.nil?
+
+        %i[equal subclass].include?(environment.class_ordering(class_name, constraint))
+      rescue StandardError
+        false
+      end
+
       def collect_glob_files(roots, patterns)
         matched = roots.flat_map do |root|
           absolute = File.expand_path(root.to_s)

data/lib/rigor/plugin/box.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # ADR-39 slice 5 — the isolation boundary for target-library
+    # invocation. When Rigor is launched with `RUBY_BOX=1` (opt-in; the
+    # launcher re-execs only when a project opts in), a target library is
+    # loaded and called inside a `Ruby::Box` so its **core-class
+    # monkey-patches and gem version cannot contaminate Rigor's main
+    # space**. `Ruby::Box` is not a security sandbox (the gem's code still
+    # runs in-process) — it is the *contamination* boundary the rule
+    # needs, which is sufficient because the rule only ever invokes a
+    # declared, trusted, pure target library.
+    #
+    # **Disabled by default.** {enabled?} is false unless the experimental
+    # `Ruby::Box` feature is active, so every consumer keeps a non-box
+    # path and the default behaviour (loading the trusted library into the
+    # main space, per slices 2/4) is unchanged. The box only ever holds
+    # the trusted, project-agnostic target libraries (inflection rules,
+    # the Rack status table); per-project / exact-version boxes are a
+    # later slice.
+    module Box
+      module_function
+
+      # True only when the experimental `Ruby::Box` feature is present and
+      # active (the process was started with `RUBY_BOX=1`). Any error
+      # answers false so a consumer silently keeps its non-box path.
+      def enabled?
+        defined?(::Ruby::Box) && ::Ruby::Box.respond_to?(:enabled?) && ::Ruby::Box.enabled?
+      rescue StandardError
+        false
+      end
+
+      # The process-shared box for trusted, project-agnostic target
+      # libraries. Built lazily on first use.
+      def shared
+        @shared ||= ::Ruby::Box.new
+      end
+
+      # Requires `feature` into the shared box exactly once. Returns true
+      # when the feature is available in the box, false when it could not
+      # be loaded (the caller then declines — never falls back to loading
+      # into the main space, which would defeat the boundary).
+      def require_feature(feature)
+        @required ||= {}
+        return @required[feature] if @required.key?(feature)
+
+        shared.require(feature)
+        @required[feature] = true
+      rescue StandardError
+        @required[feature] = false
+      end
+
+      # Evaluates `code` inside the shared box and returns the result
+      # across the box boundary. The caller MUST build `code` safely —
+      # interpolate value arguments through `String#inspect` (which
+      # round-trips as a safe Ruby literal) and only ever interpolate
+      # method names from a fixed allow-list, never free user input.
+      def eval(code)
+        shared.eval(code)
+      end
+    end
+  end
+end

data/lib/rigor/plugin/inflector.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # ADR-39 — the shared inflection helper for the Rails-family plugins
+    # (`rigor-rails-routes`, `rigor-activerecord`, `rigor-actionpack`).
+    #
+    # Inflection (`posts` ↔ `post`, `BlogPost` → `blog_posts`) drives
+    # route-helper and model-name resolution, so an inflection that
+    # diverges from Rails' *actual* rules produces a wrong helper / model
+    # name and therefore a **false positive on working code** (a bogus
+    # `unknown-helper` / `unknown-permit-key`). Rigor therefore inflects
+    # **only** with the real `ActiveSupport::Inflector` — the authority
+    # Rails itself uses — and carries **no built-in approximation**: an
+    # approximation would be exactly the source of wrong facts the
+    # false-positive discipline forbids.
+    #
+    # Per ADR-39 this is a permitted *target-library* invocation: the
+    # methods called are a fixed, pure, allow-listed set
+    # ({ALLOWED_METHODS}) on a trusted gem the consuming plugins declare
+    # as a dependency. (`ActiveSupport::Inflector` is loaded, not the
+    # analyzed application's code; project-specific inflection rules are
+    # ingested by *statically parsing* `config/initializers/inflections.rb`
+    # in a later slice, never by executing it.)
+    #
+    # **Absence is silence, never a guess.** When `ActiveSupport::Inflector`
+    # cannot be loaded (a misconfiguration — the consuming plugins declare
+    # it as a dependency, so it is present in practice), the inflection
+    # methods raise {Unavailable} rather than approximate. That raise
+    # propagates to the caller's per-plugin rescue boundary, so the
+    # inflection-dependent check degrades to **no diagnostics** — reduced
+    # coverage, never a wrong fact. A consumer that wants to fail cleanly
+    # up front can gate on {available?} and emit a single load-error.
+    module Inflector
+      # The pure, side-effect-free `ActiveSupport::Inflector` methods this
+      # helper is permitted to call (ADR-39 § "safety harness"). The set
+      # is fixed and greppable — never a dynamic `public_send`.
+      #
+      # `tableize` is deliberately NOT delegated: `ActiveSupport::Inflector.
+      # tableize("Admin::User")` returns `"admin/users"`, but ActiveRecord's
+      # *actual* table name flattens the namespace to `"admin_users"` (the
+      # table-name computation does more than the pure `tableize` string
+      # method). So {.tableize} composes the AS-backed `underscore` /
+      # `pluralize` with the `::`→`_` flattening AR really uses.
+      ALLOWED_METHODS = %i[underscore camelize singularize pluralize classify].freeze
+
+      # The target library + the constant the allow-listed methods are
+      # called on. Passed to {Isolation} so the call runs under the
+      # configured isolation strategy (none / ruby_box / process).
+      FEATURE = "active_support/inflector"
+      RECEIVER = "ActiveSupport::Inflector"
+
+      # Raised when `ActiveSupport::Inflector` is required for an
+      # inflection but cannot be loaded. Caught by the per-plugin isolation
+      # boundary, so it surfaces as "this plugin produced no diagnostics"
+      # rather than a wrong inflection.
+      class Unavailable < StandardError
+      end
+
+      module_function
+
+      # `BlogPost` → `blog_post`; `Admin::Foo` → `admin/foo`.
+      def underscore(word)
+        invoke(:underscore, word)
+      end
+
+      # `blog_post` → `BlogPost`; `admin/foo` → `Admin::Foo`.
+      def camelize(term)
+        invoke(:camelize, term)
+      end
+
+      # `posts` → `post`; `categories` → `category`.
+      def singularize(word)
+        invoke(:singularize, word)
+      end
+
+      # `post` → `posts`; `category` → `categories`.
+      def pluralize(word)
+        invoke(:pluralize, word)
+      end
+
+      # `posts` → `Post`; `blog_posts` → `BlogPost`.
+      def classify(table_name)
+        invoke(:classify, table_name)
+      end
+
+      # `BlogPost` → `blog_posts`; `Admin::User` → `admin_users`.
+      # Composed (not delegated) so the namespace flattens with `_` the
+      # way ActiveRecord's table naming does — see {ALLOWED_METHODS}.
+      def tableize(class_name)
+        underscored = underscore(class_name.to_s.gsub("::", "/")).tr("/", "_")
+        pluralize(underscored)
+      end
+
+      # Whether inflection is available under the configured isolation
+      # strategy. A consumer can gate inflection-dependent work on this to
+      # emit a single clean load-error instead of letting the first
+      # inflection raise. Probes with a trivial pluralization.
+      def available?
+        invoke(:pluralize, "rigor_inflector_probe")
+        true
+      rescue Unavailable
+        false
+      end
+
+      # Delegates an allow-listed method to the real
+      # `ActiveSupport::Inflector` through the configured isolation
+      # strategy ({Isolation}: none / ruby_box / process). Raises
+      # {Unavailable} (never approximates) when the library cannot be
+      # reached in that strategy — the caller's per-plugin rescue turns
+      # that into silence, never a wrong inflection.
+      def invoke(name, arg)
+        raise ArgumentError, "method not allow-listed: #{name}" unless ALLOWED_METHODS.include?(name)
+
+        Isolation.call(feature: FEATURE, receiver: RECEIVER, method: name, args: [arg.to_s])
+      rescue Isolation::Unavailable => e
+        raise Unavailable, e.message
+      end
+    end
+  end
+end