rigortype 0.0.9 → 0.1.1

data/lib/rigor/plugin/base.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "manifest"
+
+module Rigor
+  module Plugin
+    # Base class every Rigor plugin subclasses. The plugin gem
+    # subclasses {Base}, declares its identity through {.manifest},
+    # registers the subclass with {Rigor::Plugin.register}, and
+    # overrides {#init} to wire up any state it needs from the
+    # injected service container.
+    #
+    # Slice 1 ships only the registration / loading plumbing. The
+    # protocol hooks (dynamic-return contributions, type-specifying
+    # contributions, dynamic reflection) land in subsequent v0.1.0
+    # slices and arrive as additional methods on this class.
+    #
+    # Example plugin:
+    #
+    #   class MyRailsPlugin < Rigor::Plugin::Base
+    #     manifest(
+    #       id: "rails",
+    #       version: "0.1.0",
+    #       description: "Rails framework support for Rigor"
+    #     )
+    #
+    #     def init(services)
+    #       @reflection = services.reflection
+    #       @type = services.type
+    #     end
+    #   end
+    #
+    #   Rigor::Plugin.register(MyRailsPlugin)
+    class Base
+      class << self
+        # Declares the plugin's manifest. Called once at class
+        # definition time — the resulting {Manifest} is cached on
+        # the class so {Rigor::Plugin::Loader} reads it without
+        # constructing the plugin.
+        def manifest(**fields)
+          if fields.empty?
+            raise ArgumentError, "plugin #{self} did not declare a manifest" unless defined?(@manifest) && @manifest
+
+            return @manifest
+          end
+
+          @manifest = Manifest.new(**fields)
+        end
+
+        # ADR-7 § "Slice 6-A" — DSL declaration of a cached
+        # producer. Plugin authors write
+        #
+        #   class MyPlugin < Rigor::Plugin::Base
+        #     manifest(id: "rails", version: "0.1.0")
+        #
+        #     producer :schema_table do |params|
+        #       schema = io_boundary.read_file("db/schema.rb")
+        #       parse(schema, params)
+        #     end
+        #   end
+        #
+        # The block runs through `instance_exec` so `self` inside
+        # the body is the plugin instance — `io_boundary`,
+        # `services`, `manifest`, `config` are all in scope. The
+        # block receives the call-site `params` Hash as its sole
+        # argument; the same params Hash mixes into the cache
+        # key per `Cache::Descriptor#cache_key_for`.
+        #
+        # `serialize:` / `deserialize:` are forwarded verbatim to
+        # `Cache::Store#fetch_or_compute`. Default round-trip is
+        # `Marshal.dump` / `Marshal.load` per the v0.0.9 callable
+        # surface; producers whose return values are not Marshal-
+        # clean must supply their own pair.
+        #
+        # Producer ids are auto-prefixed `plugin.<manifest.id>.`
+        # at the cache layer (slice 6-C) so plugin-side ids cannot
+        # collide with built-in producers.
+        def producer(id, serialize: nil, deserialize: nil, &block)
+          raise ArgumentError, "Plugin::Base.producer requires a block body" if block.nil?
+
+          @producers ||= {}
+          @producers[id.to_sym] = { block: block, serialize: serialize, deserialize: deserialize }.freeze
+          id.to_sym
+        end
+
+        # Frozen snapshot of the producer table. Inherited
+        # producers from a superclass are intentionally NOT
+        # surfaced — Plugin::Base subclasses do not chain
+        # producers, and the loader instantiates one
+        # subclass per registration.
+        def producers
+          (@producers || {}).dup.freeze
+        end
+      end
+
+      attr_reader :services, :config
+
+      def initialize(services:, config: {})
+        @services = services
+        @config = config.freeze
+      end
+
+      # Override in subclasses to wire any state the plugin needs
+      # from the injected service container. Default is a no-op so
+      # plugins that only contribute through later-slice protocol
+      # hooks do not have to define an explicit body.
+      def init(services) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+
+      # ADR-2 § "Flow Contribution Bundle" / v0.1.1 Track 2
+      # slice 7 — per-call return-type contribution hook. When
+      # the inference engine dispatches a `Prism::CallNode` and
+      # neither the precision tiers nor RBS resolve a result,
+      # `MethodDispatcher` consults each loaded plugin via this
+      # hook ahead of `RbsDispatch`. Plugins that override the
+      # default return a {Rigor::FlowContribution} bundle whose
+      # `return_type` slot pins the call site's result type.
+      #
+      # Default returns nil — plugins that don't refine return
+      # types skip the override. Failures are isolated: a hook
+      # that raises gets its contribution dropped silently for
+      # this call so the rest of the dispatch chain continues.
+      def flow_contribution_for(call_node:, scope:) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+
+      # ADR-9 slice 3 — per-run preparation hook. The runner
+      # invokes `#prepare(services)` on every loaded plugin once
+      # per `Analysis::Runner.run`, after `#init` has run on every
+      # plugin and before any `#diagnostics_for_file` call.
+      # Plugins use this hook to compute and publish facts other
+      # plugins consume:
+      #
+      #   def prepare(services)
+      #     services.fact_store.publish(
+      #       plugin_id: manifest.id, name: :model_index, value: model_index
+      #     )
+      #   end
+      #
+      # Default no-op so plugins without facts to publish leave
+      # `#prepare` unimplemented. Failures isolate as
+      # `:plugin_loader runtime-error` diagnostics; a plugin that
+      # raises in `#prepare` has its facts considered un-published
+      # and downstream consumers see `nil` from `fact_store.read`.
+      #
+      # Slice 3 calls plugins in registration order. ADR-9 slice 5
+      # introduces topological ordering by `consumes:` so producers
+      # always run before consumers.
+      def prepare(services) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+
+      # ADR-7 § "Slice 5-A" — per-file diagnostic emission hook.
+      # Override in plugin subclasses to return an array of
+      # `Rigor::Analysis::Diagnostic` rows for the analysed file.
+      # The runner stamps each returned diagnostic with
+      # `source_family: "plugin.<manifest.id>"` automatically per
+      # ADR-7 § "Slice 5-B"; plugin authors should construct
+      # diagnostics without setting `source_family` (any value
+      # they pass is overwritten).
+      #
+      # `path` is the analysed file path; `scope` is the entry
+      # `Rigor::Scope` after `ScopeIndexer` ran; `root` is the
+      # parsed `Prism::Node` root. Plugin authors traverse `root`
+      # themselves if they need node-scoped rules — the
+      # `Rule<TNode>` API ADR-2 § "Custom rules" mentions stays
+      # deferred to v0.1.x.
+      #
+      # Default returns `[]` so plugins that contribute through
+      # other channels (e.g. slice-4 narrowing contributions,
+      # slice-6 cache producers) do not have to override.
+      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
+        []
+      end
+
+      # Convenience accessor — `manifest` on the instance returns
+      # the class-level manifest declaration.
+      def manifest
+        self.class.manifest
+      end
+
+      # ADR-7 § "Slice 6-A/6-B" — per-plugin {IoBoundary}.
+      # Memoised so the boundary's accumulated `FileEntry`
+      # rows persist across producer invocations within the
+      # same plugin instance and feed cache invalidation
+      # via `cache_for`.
+      def io_boundary
+        @io_boundary ||= services.io_boundary_for(manifest.id)
+      end
+
+      # ADR-7 § "Slice 6-A" — returns a callable that performs
+      # a `Cache::Store#fetch_or_compute` round-trip for the
+      # named producer. The descriptor (per ADR-7 § "Slice
+      # 6-B") is auto-assembled from the plugin's
+      # `PluginEntry` template (id, version, config_hash) and
+      # the {IoBoundary} read history. The producer id is
+      # auto-prefixed `plugin.<manifest.id>.` per ADR-7 §
+      # "Slice 6-C" so plugin caches stay sandboxed from
+      # built-in producers.
+      #
+      # When `services.cache_store` is `nil` (e.g. CLI
+      # `--no-cache`), the callable bypasses the cache and
+      # runs the producer block every time — same semantics
+      # as the v0.0.9 cache surface for built-in producers.
+      #
+      # `descriptor:` (optional, ADR-7 § "Slice 6" follow-up)
+      # supplies extra `Cache::Descriptor` rows the plugin
+      # author wants to compose into the auto-built descriptor
+      # — typically gem-version `GemEntry`, configuration-file
+      # `FileEntry` digests, or `ConfigEntry` rows for external
+      # state the {IoBoundary} cannot capture itself. The
+      # passed descriptor composes via `Cache::Descriptor.compose`
+      # with the auto-built one (PluginEntry template + boundary
+      # reads); per-slot conflicts raise
+      # `Cache::Descriptor::Conflict` to make divergent inputs
+      # visible rather than silently shadowing.
+      def cache_for(producer_id, params: {}, descriptor: nil)
+        producer = self.class.producers[producer_id.to_sym]
+        unless producer
+          raise ArgumentError,
+                "plugin #{manifest.id.inspect} did not declare producer #{producer_id.inspect}"
+        end
+
+        compute = -> { instance_exec(params, &producer[:block]) }
+        store = services.cache_store
+        return compute unless store
+
+        prefixed_id = "plugin.#{manifest.id}.#{producer_id}"
+        composed_descriptor = compose_cache_descriptor(descriptor)
+        lambda do
+          store.fetch_or_compute(
+            producer_id: prefixed_id,
+            params: params,
+            descriptor: composed_descriptor,
+            serialize: producer[:serialize],
+            deserialize: producer[:deserialize],
+            &compute
+          )
+        end
+      end
+
+      private
+
+      # ADR-7 § "Slice 6-B" — composes the per-call cache
+      # descriptor from (1) the plugin's PluginEntry template
+      # and (2) the IoBoundary's accumulated FileEntry rows.
+      def build_plugin_cache_descriptor
+        plugin_entry = Cache::Descriptor::PluginEntry.new(
+          id: manifest.id,
+          version: manifest.version,
+          config_hash: digest_config(config)
+        )
+        boundary_descriptor = io_boundary.cache_descriptor
+        Cache::Descriptor.new(
+          plugins: [plugin_entry],
+          files: boundary_descriptor.files
+        )
+      end
+
+      # ADR-7 § "Slice 6" follow-up — composes the auto-built
+      # cache descriptor with an optional plugin-author-supplied
+      # extension. Extra `GemEntry` / `FileEntry` / `ConfigEntry`
+      # rows the plugin needs (gem-version pins, external
+      # configuration files, sibling-plugin state) flow through
+      # `Cache::Descriptor.compose`; the union behaviour matches
+      # built-in producers (`RbsConstantTable`, `RbsEnvironment`).
+      def compose_cache_descriptor(extra)
+        auto_built = build_plugin_cache_descriptor
+        return auto_built if extra.nil?
+
+        Cache::Descriptor.compose(auto_built, extra)
+      end
+
+      def digest_config(config)
+        canonical = Cache::Descriptor.canonicalize_value(config || {})
+        Digest::SHA256.hexdigest(JSON.generate(canonical))
+      end
+    end
+  end
+end

data/lib/rigor/plugin/fact_store.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Per-run cross-plugin fact store. ADR-9 § "Plugin::FactStore".
+    #
+    # A plugin publishes typed `(plugin_id, name) -> value` tuples
+    # in its `Plugin::Base#prepare(services)` hook (slice 3); other
+    # plugins read them in `#diagnostics_for_file` via
+    # `services.fact_store.read(plugin_id:, name:)`. The store is
+    # constructed fresh at the start of every `Analysis::Runner.run`
+    # and discarded at the end — caching the underlying expensive
+    # computation is the producer's job (`Plugin::Base.producer`);
+    # the FactStore just publishes a *reference* to that
+    # already-cached result.
+    #
+    # `(plugin_id, name)` is a unique key. A second `publish` with
+    # the same value is a no-op (`==` comparison); a second
+    # `publish` with a different value raises {Conflict}. Since
+    # `plugin_id` namespaces the key, a real conflict only happens
+    # when a single plugin publishes twice with differing values —
+    # the conflict signals a plugin-author bug, never a load-time
+    # interaction between unrelated plugins.
+    class FactStore
+      Fact = Data.define(:plugin_id, :name, :value)
+
+      class Conflict < StandardError
+        attr_reader :plugin_id, :name, :existing, :incoming
+
+        def initialize(plugin_id:, name:, existing:, incoming:)
+          @plugin_id = plugin_id
+          @name = name
+          @existing = existing
+          @incoming = incoming
+          super(
+            "fact store conflict: plugin #{plugin_id.inspect} published " \
+            "two different values for #{name.inspect} " \
+            "(existing: #{existing.inspect}, incoming: #{incoming.inspect})"
+          )
+        end
+      end
+
+      def initialize
+        @facts = {}
+        @mutex = Mutex.new
+      end
+
+      # Writes a `(plugin_id, name) -> value` triple. Idempotent if
+      # the same value is published twice (`==`); raises
+      # {Conflict} if the values differ.
+      #
+      # @param plugin_id [String] producing plugin's manifest id.
+      # @param name [Symbol, String] fact name (canonicalised to
+      #   Symbol for lookup).
+      # @param value [Object] frozen-shape value object the
+      #   producer chose to publish. The value is stored as-is.
+      def publish(plugin_id:, name:, value:)
+        plugin_id = plugin_id.to_s
+        name = name.to_sym
+        @mutex.synchronize do
+          existing = @facts[[plugin_id, name]]
+          if existing && existing.value != value
+            raise Conflict.new(plugin_id: plugin_id, name: name, existing: existing.value, incoming: value)
+          end
+
+          @facts[[plugin_id, name]] = Fact.new(plugin_id: plugin_id, name: name, value: value)
+        end
+        nil
+      end
+
+      # @return [Object, nil] the published value, or `nil` when no
+      #   fact is registered. Reads do NOT establish a dependency —
+      #   `manifest(consumes:)` (slice 4) is the dependency
+      #   declaration mechanism.
+      def read(plugin_id:, name:)
+        fact = @mutex.synchronize { @facts[[plugin_id.to_s, name.to_sym]] }
+        fact&.value
+      end
+
+      # @return [Boolean] whether a fact is registered.
+      def published?(plugin_id:, name:)
+        @mutex.synchronize { @facts.key?([plugin_id.to_s, name.to_sym]) }
+      end
+
+      # @yield [Fact] every published fact in publication order.
+      def each_fact(&)
+        snapshot = @mutex.synchronize { @facts.values }
+        snapshot.each(&)
+      end
+    end
+  end
+end

data/lib/rigor/plugin/io_boundary.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "access_denied_error"
+
+module Rigor
+  module Plugin
+    # Analyzer-side helper plugins go through to read files and
+    # (eventually) reach the network. The boundary enforces the
+    # active {TrustPolicy} and accumulates a {Cache::Descriptor}
+    # of every read so plugin contributions stay invalidatable
+    # alongside their inputs.
+    #
+    # ADR-2 § "Plugin Trust and I/O Policy" is the binding
+    # contract. The boundary is **not** a sandbox: a plugin that
+    # uses `File.read` directly bypasses everything here, and the
+    # ADR explicitly accepts that trade-off. The discipline is:
+    # when plugin code goes through this surface, reads stay
+    # within the trust scope and feed the cache descriptor;
+    # contributions built on top of out-of-scope reads will not
+    # invalidate correctly.
+    #
+    # Slice 2 ships a minimal surface:
+    #
+    # - `#read_file(path)` — validates against the policy, returns
+    #   the file's contents, and adds a digest-keyed
+    #   {Cache::Descriptor::FileEntry} to the boundary's
+    #   accumulated descriptor.
+    # - `#open_url(url)` — always raises {AccessDeniedError} while
+    #   `network_policy` is `:disabled` (the only setting in slice
+    #   2). The hook exists so slices 3-6 can layer richer access
+    #   policy without re-defining the API.
+    # - `#cache_descriptor` — flushes the accumulated entries into
+    #   a fresh {Cache::Descriptor} for the contribution that
+    #   built it.
+    class IoBoundary
+      attr_reader :policy, :plugin_id
+
+      def initialize(policy:, plugin_id:)
+        @policy = policy
+        @plugin_id = plugin_id.to_s.dup.freeze
+        @file_entries = {}
+        @mutex = Mutex.new
+      end
+
+      # Reads the file at `path` after validating it against the
+      # policy. Raises {AccessDeniedError} when the path is outside
+      # every allowed read root. Records a `:digest` {FileEntry}
+      # so the resulting cache slice invalidates on content change.
+      def read_file(path)
+        absolute = File.expand_path(path.to_s)
+        unless @policy.allow_read?(absolute)
+          raise AccessDeniedError.new(
+            "plugin #{@plugin_id.inspect} cannot read #{absolute.inspect}: " \
+            "path is outside the trusted-read scope",
+            reason: :read_outside_scope,
+            resource: absolute
+          )
+        end
+
+        contents = File.binread(absolute)
+        record_file_entry(absolute, contents)
+        contents
+      end
+
+      # Slice 2 stub: every URL access is denied while
+      # `network_policy` is `:disabled`. Slices that need to relax
+      # the rule (e.g. for opt-in offline-replay caches) will lift
+      # the policy gate; the API does not change.
+      def open_url(url)
+        unless @policy.network_allowed?
+          raise AccessDeniedError.new(
+            "plugin #{@plugin_id.inspect} cannot open URL #{url.inspect}: " \
+            "network access is disabled during analysis",
+            reason: :network_disabled,
+            resource: url.to_s
+          )
+        end
+
+        raise NotImplementedError, "URL fetch surface is reserved; slice 2 only ships the deny path"
+      end
+
+      # @return [Rigor::Cache::Descriptor] frozen snapshot of every
+      #   file the boundary has read so far. Calling this multiple
+      #   times yields equal descriptors; subsequent reads expand
+      #   the underlying record table.
+      def cache_descriptor
+        entries = @mutex.synchronize { @file_entries.values.dup }
+        Cache::Descriptor.new(files: entries)
+      end
+
+      private
+
+      def record_file_entry(path, contents)
+        digest = Digest::SHA256.hexdigest(contents)
+        entry = Cache::Descriptor::FileEntry.new(path: path, comparator: :digest, value: digest)
+        @mutex.synchronize { @file_entries[path] = entry }
+      end
+    end
+  end
+end

data/lib/rigor/plugin/load_error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Raised inside the loader (and surfaced as a diagnostic by the
+    # analyzer) when a plugin entry cannot be resolved or
+    # instantiated. Carries the failing plugin reference plus the
+    # underlying cause so the diagnostic message stays precise.
+    #
+    # ADR-2 § "Plugin Trust and I/O Policy" requires plugin failures
+    # to be isolated at the analyzer boundary; this class is the
+    # carrier for that contract on the loading side.
+    class LoadError < StandardError
+      attr_reader :plugin_ref, :cause_class, :reason
+
+      # ADR-9 slice 5 introduces two new reason codes alongside the
+      # implicit "load failure" used for require / configuration /
+      # init failures:
+      #
+      #   - `:missing-producer` — a non-optional `manifest(consumes:)`
+      #     entry names a `(plugin_id, name)` no loaded plugin
+      #     produces.
+      #   - `:dependency-cycle` — the consumes graph forms a cycle.
+      #
+      # Older callers omit `reason:` and the field defaults to nil
+      # (the legacy "load failure" envelope).
+      def initialize(message, plugin_ref:, cause: nil, reason: nil)
+        super(message)
+        @plugin_ref = plugin_ref
+        @cause_class = cause&.class
+        @reason = reason&.to_sym
+      end
+    end
+  end
+end