rigortype 0.0.9 → 0.1.1

data/lib/rigor/cli.rb

@@ -70,11 +70,11 @@ module Rigor
 
       options = parse_check_options
 
-      cache_root = ".rigor/cache"
+      configuration = Configuration.load(options.fetch(:config))
+      cache_root = configuration.cache_path
       handle_clear_cache(cache_root) if options.fetch(:clear_cache)
       cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
 
-      configuration = Configuration.load(options.fetch(:config))
       paths = @argv.empty? ? configuration.paths : @argv
       runner = Analysis::Runner.new(
         configuration: configuration,
@@ -90,7 +90,9 @@ module Rigor
 
     def parse_check_options
       options = {
-        config: Configuration::DEFAULT_PATH,
+        # `nil` triggers `Configuration.discover` (`.rigor.yml` then
+        # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
+        config: nil,
         format: "text",
         explain: false,
         cache_stats: false,
@@ -170,9 +172,14 @@ module Rigor
     end
 
     def run_init
+      # Default destination is `.rigor.dist.yml` — the
+      # project-default config that gets committed. Developers
+      # who want a personal override layer create `.rigor.yml`
+      # alongside it (auto-discovery prefers `.rigor.yml` when
+      # both are present; no implicit merge).
       options = {
         force: false,
-        path: Configuration::DEFAULT_PATH
+        path: ".rigor.dist.yml"
       }
 
       parser = OptionParser.new do |opts|
@@ -211,9 +218,15 @@ module Rigor
         #                (no plugins are loaded today).
         # - disable:     list of `rigor check` rule identifiers to
         #                silence project-wide. The shipped rules are
-        #                undefined-method, wrong-arity,
-        #                argument-type-mismatch, possible-nil-receiver,
-        #                dump-type, assert-type. In-source
+        #                call.undefined-method, call.wrong-arity,
+        #                call.argument-type-mismatch,
+        #                call.possible-nil-receiver, dump.type,
+        #                assert.type-mismatch, flow.always-raises.
+        #                A bare family token (`call`, `flow`,
+        #                `assert`, `dump`, `def`) wildcards every
+        #                rule under that prefix. Legacy unprefixed
+        #                names (`undefined-method`, …) still
+        #                resolve. In-source
         #                `# rigor:disable <rule>` comments at the end
         #                of an offending line silence per-line; use
         #                `# rigor:disable all` to suppress every rule.

data/lib/rigor/configuration/severity_profile.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Configuration
+    # ADR-8 § "Severity profile" — three named profiles tune the
+    # severity of every built-in `Analysis::CheckRules` rule for
+    # the run. Profiles are applied as a **final filter** on
+    # `Diagnostic#severity`: rules emit with their authored
+    # severity, then `Analysis::Runner` re-stamps the severity
+    # from the active profile before adding the diagnostic to
+    # the result.
+    #
+    # Three profiles:
+    #
+    # - `lenient`: Only proven (`:no`) diagnostics are errors;
+    #   uncertain (`:maybe`) drop to `:warning`. Useful for
+    #   incremental adoption on legacy code.
+    # - `balanced` (**default**): Current Rigor stance — most
+    #   rules `:error`; `dump.type` `:info`; uncertain rules
+    #   `:warning`.
+    # - `strict`: Every rule is `:error`. CI-friendly.
+    #
+    # The profile resolution order:
+    #
+    # 1. Profile-specific entry for the canonical rule id.
+    # 2. The diagnostic's own authored severity (the rule's
+    #    default).
+    # 3. `:error` (catch-all so an unrecognised rule still emits
+    #    visibly — the public-API drift spec catches the
+    #    bookkeeping gap separately).
+    module SeverityProfile
+      VALID_PROFILES = %i[lenient balanced strict].freeze
+      VALID_SEVERITIES = %i[error warning info off].freeze
+
+      DEFAULT_PROFILE = :balanced
+
+      # Per-profile severity tables. Missing keys fall back to
+      # the diagnostic's authored severity (typically `:error`).
+      PROFILES = {
+        lenient: {
+          "call.undefined-method" => :error,
+          "call.wrong-arity" => :error,
+          "call.argument-type-mismatch" => :warning,
+          "call.possible-nil-receiver" => :warning,
+          "flow.always-raises" => :warning,
+          "assert.type-mismatch" => :error,
+          "dump.type" => :info,
+          "def.return-type-mismatch" => :warning
+        }.freeze,
+        balanced: {
+          "call.undefined-method" => :error,
+          "call.wrong-arity" => :error,
+          "call.argument-type-mismatch" => :error,
+          "call.possible-nil-receiver" => :error,
+          "flow.always-raises" => :error,
+          "assert.type-mismatch" => :error,
+          "dump.type" => :info,
+          "def.return-type-mismatch" => :warning
+        }.freeze,
+        strict: {
+          "call.undefined-method" => :error,
+          "call.wrong-arity" => :error,
+          "call.argument-type-mismatch" => :error,
+          "call.possible-nil-receiver" => :error,
+          "flow.always-raises" => :error,
+          "assert.type-mismatch" => :error,
+          "dump.type" => :error,
+          "def.return-type-mismatch" => :error
+        }.freeze
+      }.freeze
+
+      module_function
+
+      # Resolves the configured severity for a diagnostic given
+      # the active profile and any per-rule overrides.
+      #
+      # @param rule [String, nil] canonical rule id (`call.undefined-method`).
+      # @param authored_severity [Symbol] severity the rule emitted
+      #   the diagnostic with (`:error`, `:warning`, `:info`).
+      # @param profile [Symbol] one of {VALID_PROFILES}; falls back
+      #   to {DEFAULT_PROFILE} for unknown values.
+      # @param overrides [Hash{String => Symbol}] per-rule severity
+      #   overrides from `.rigor.yml`'s `severity_overrides:` map.
+      #   Keys are canonical rule ids; values are
+      #   {VALID_SEVERITIES} symbols. Family-wildcard keys
+      #   (`call`) match every rule under that prefix.
+      # @return [Symbol] the resolved severity. Returns `:off` to
+      #   mean "drop the diagnostic entirely".
+      def resolve(rule:, authored_severity:, profile: DEFAULT_PROFILE, overrides: {})
+        return authored_severity if rule.nil?
+
+        override = overrides[rule] || family_override(rule, overrides)
+        return override.to_sym if override
+
+        profile_table = PROFILES[profile] || PROFILES.fetch(DEFAULT_PROFILE)
+        profile_table.fetch(rule, authored_severity)
+      end
+
+      def family_override(rule, overrides)
+        family = rule.split(".").first
+        return nil if family.nil?
+
+        overrides[family]
+      end
+
+      private_class_method :family_override
+    end
+  end
+end

data/lib/rigor/configuration.rb

@@ -2,12 +2,48 @@
 
 require "yaml"
 
+require_relative "configuration/severity_profile"
+
 module Rigor
-  class Configuration
-    DEFAULT_PATH = ".rigor.yml"
+  class Configuration # rubocop:disable Metrics/ClassLength
+    # File-discovery order for `Configuration.load(nil)`.
+    #
+    # The first file present is loaded; the others are NOT
+    # implicitly merged. To extend a base config explicitly the
+    # winning file MUST list the base via `includes:`.
+    #
+    # `.rigor.yml` is a developer-local override (typically
+    # gitignored); `.rigor.dist.yml` is the project default
+    # (committed to the repo). When both are present the
+    # developer's local override wins outright — there is no
+    # implicit auto-merge.
+    DISCOVERY_ORDER = %w[.rigor.yml .rigor.dist.yml].freeze
+    # Back-compat alias. Keep here so external callers that read
+    # `Configuration::DEFAULT_PATH` for help text / fixture paths
+    # still work; the discovery list is the canonical source.
+    DEFAULT_PATH = DISCOVERY_ORDER.first
+
+    # Built-in exclusion patterns appended to `exclude:` so vendored
+    # dependencies, Bundler artefacts, and JavaScript node_modules are
+    # never analysed by accident when a directory glob expands. Users
+    # cannot disable these defaults; the trade-off is that analysing
+    # any of these paths is essentially never what the user wants
+    # (they're build outputs / external dependencies, not source).
+    #
+    # We deliberately keep this list narrow. `tmp/` and similar
+    # directories vary across project layouts (Rails has `tmp/`,
+    # libraries usually don't); user-supplied `exclude:` entries
+    # in `.rigor.yml` cover the project-specific cases.
+    BUILTIN_EXCLUDES = %w[
+      **/vendor/bundle/**
+      **/.bundle/**
+      **/node_modules/**
+    ].freeze
+
     DEFAULTS = {
       "target_ruby" => "4.0",
       "paths" => ["lib"],
+      "exclude" => [],
       "plugins" => [],
       "disable" => [],
       "libraries" => [],
@@ -15,28 +51,148 @@ module Rigor
       "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache"
-      }
+      },
+      "plugins_io" => {
+        "network" => "disabled",
+        "allowed_paths" => []
+      },
+      "severity_profile" => "balanced",
+      "severity_overrides" => {}
     }.freeze
 
-    attr_reader :target_ruby, :paths, :plugins, :cache_path, :disabled_rules,
-                :libraries, :signature_paths, :fold_platform_specific_paths
+    # Top-level keys whose values are file/directory paths that
+    # MUST be resolved relative to the config file's directory.
+    # `exclude:` is intentionally NOT in this list — its entries
+    # are glob patterns (`**/vendor/**`), not paths.
+    PATH_KEYS = %w[paths signature_paths].freeze
+    private_constant :PATH_KEYS
+
+    attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :disabled_rules,
+                :libraries, :signature_paths, :fold_platform_specific_paths,
+                :plugins_io_network, :plugins_io_allowed_paths,
+                :severity_profile, :severity_overrides
 
-    def self.load(path = DEFAULT_PATH)
-      data = if File.exist?(path)
-               YAML.safe_load_file(path, aliases: false) || {}
-             else
-               {}
-             end
+    # Loads a configuration file.
+    #
+    # `path == nil` triggers auto-discovery against
+    # {DISCOVERY_ORDER}. The first present file in that list is
+    # loaded; if none exist the built-in {DEFAULTS} are used.
+    #
+    # When a path is supplied (whether by auto-discovery or by
+    # the caller) the YAML body is processed for `includes:`
+    # recursively, and every relative path inside path-bearing
+    # keys (`paths:`, `signature_paths:`, `plugins_io.allowed_paths:`,
+    # `includes:`) is resolved against THAT file's directory.
+    # The resolution is per-file: an included file's relative
+    # paths resolve against the included file's directory, not
+    # the top-level file. Path resolution mirrors
+    # [PHPStan](https://phpstan.org/config-reference#paths).
+    def self.load(path = nil)
+      resolved = path || discover
+      return new(DEFAULTS) if resolved.nil? || !File.exist?(resolved)
 
+      data = load_with_includes(resolved)
       new(DEFAULTS.merge(data))
     end
 
-    def initialize(data = DEFAULTS) # rubocop:disable Metrics/AbcSize
+    # Returns the path to the config file Rigor would load
+    # under auto-discovery, or `nil` when neither candidate
+    # exists. Public so the CLI / spec drift checks can
+    # introspect the resolved file.
+    def self.discover
+      DISCOVERY_ORDER.find { |candidate| File.exist?(candidate) }
+    end
+
+    # Reads `path` (which MUST exist) plus every file listed in
+    # its `includes:` chain, merging them under the order:
+    # included files first (in declaration order), then the
+    # current file's own keys override. Relative paths inside
+    # each file are resolved against that file's directory.
+    def self.load_with_includes(path, visited: Set.new)
+      absolute = File.expand_path(path)
+      raise ArgumentError, "circular include: #{absolute}" if visited.include?(absolute)
+
+      raw = YAML.safe_load_file(absolute, aliases: false) || {}
+      raise ArgumentError, "config file must be a YAML mapping: #{absolute}" unless raw.is_a?(Hash)
+
+      base_dir = File.dirname(absolute)
+      includes = Array(raw.delete("includes") || [])
+      data = resolve_paths_in(raw, base_dir)
+      next_visited = visited + [absolute]
+      merge_includes(data, includes, base_dir, next_visited)
+    end
+
+    def self.merge_includes(data, includes, base_dir, visited)
+      return data if includes.empty?
+
+      accumulated = {}
+      includes.each do |inc|
+        inc_path = File.expand_path(inc.to_s, base_dir)
+        unless File.exist?(inc_path)
+          raise ArgumentError, "include not found: #{inc.inspect} (referenced from #{base_dir})"
+        end
+
+        accumulated = deep_merge(accumulated, load_with_includes(inc_path, visited: visited))
+      end
+      deep_merge(accumulated, data)
+    end
+
+    # Per-file path resolution. Each path-bearing key listed in
+    # {PATH_KEYS} plus the nested `plugins_io.allowed_paths:`
+    # entries get their relative paths expanded against the
+    # config file's directory. `cache.path:` is intentionally
+    # left as-is so end-user messages (e.g. `--cache-stats`
+    # output) keep the project-relative form the user wrote.
+    def self.resolve_paths_in(data, base_dir)
+      return data unless data.is_a?(Hash)
+
+      out = data.dup
+      PATH_KEYS.each { |key| resolve_path_key!(out, key, base_dir) }
+      resolve_plugins_io_paths!(out, base_dir)
+      out
+    end
+
+    def self.resolve_path_key!(out, key, base_dir)
+      return unless out.key?(key) && !out[key].nil?
+
+      out[key] = Array(out[key]).map { |p| File.expand_path(p.to_s, base_dir) }
+    end
+
+    def self.resolve_plugins_io_paths!(out, base_dir)
+      plugins_io = out["plugins_io"]
+      return unless plugins_io.is_a?(Hash) && plugins_io["allowed_paths"]
+
+      duped = plugins_io.dup
+      duped["allowed_paths"] = Array(plugins_io["allowed_paths"]).map { |p| File.expand_path(p.to_s, base_dir) }
+      out["plugins_io"] = duped
+    end
+
+    def self.deep_merge(left, right)
+      return right unless left.is_a?(Hash) && right.is_a?(Hash)
+
+      merged = left.dup
+      right.each do |key, value|
+        merged[key] = if merged.key?(key) && merged[key].is_a?(Hash) && value.is_a?(Hash)
+                        deep_merge(merged[key], value)
+                      else
+                        value
+                      end
+      end
+      merged
+    end
+    private_class_method :load_with_includes, :merge_includes, :resolve_paths_in, :deep_merge
+
+    def initialize(data = DEFAULTS) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
+      plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
-      @target_ruby = data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")).to_s
+      @target_ruby = coerce_target_ruby(data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")))
       @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
-      @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map(&:to_s)
+      user_excludes = Array(data.fetch("exclude", DEFAULTS.fetch("exclude"))).map(&:to_s)
+      @exclude_patterns = (BUILTIN_EXCLUDES + user_excludes).uniq.freeze
+      @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map do |entry|
+        coerce_plugin_entry(entry)
+      end.freeze
       @disabled_rules = Array(data.fetch("disable", DEFAULTS.fetch("disable"))).map(&:to_s).freeze
       @libraries = Array(data.fetch("libraries", DEFAULTS.fetch("libraries"))).map(&:to_s).freeze
       sig_paths = data.fetch("signature_paths", DEFAULTS.fetch("signature_paths"))
@@ -45,12 +201,21 @@ module Rigor
         "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
       ) == true
       @cache_path = cache.fetch("path").to_s
+      @plugins_io_network = coerce_network_policy(plugins_io.fetch("network"))
+      @plugins_io_allowed_paths = Array(plugins_io.fetch("allowed_paths")).map(&:to_s).freeze
+      @severity_profile = coerce_severity_profile(
+        data.fetch("severity_profile", DEFAULTS.fetch("severity_profile"))
+      )
+      @severity_overrides = coerce_severity_overrides(
+        data.fetch("severity_overrides", DEFAULTS.fetch("severity_overrides"))
+      )
     end
 
     def to_h
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
+        "exclude" => exclude_patterns - BUILTIN_EXCLUDES,
         "plugins" => plugins,
         "disable" => disabled_rules,
         "libraries" => libraries,
@@ -58,8 +223,114 @@ module Rigor
         "fold_platform_specific_paths" => fold_platform_specific_paths,
         "cache" => {
           "path" => cache_path
-        }
+        },
+        "plugins_io" => {
+          "network" => plugins_io_network.to_s,
+          "allowed_paths" => plugins_io_allowed_paths
+        },
+        "severity_profile" => severity_profile.to_s,
+        "severity_overrides" => severity_overrides.to_h { |k, v| [k, v.to_s] }
       }
     end
+
+    private
+
+    # Accepts either `"rigor-foo"` (gem-name shorthand) or
+    # `{ "gem" => "rigor-foo", "id" => "foo", "config" => {...} }`
+    # (full form). Returns the canonical hash form so the loader
+    # works against a single shape.
+    def coerce_plugin_entry(entry)
+      case entry
+      when String
+        entry.dup.freeze
+      when Hash
+        entry.to_h { |k, v| [k.to_s, v] }.freeze
+      else
+        raise ArgumentError,
+              "plugin configuration entry must be a String or Hash, got #{entry.inspect}"
+      end
+    end
+
+    # `target_ruby` is passed to `Prism.parse_file(path, version:)` at
+    # the analyser's three parse sites (`Analysis::Runner`,
+    # `CLI::TypeOfCommand`, `CLI::TypeScanCommand`) so projects that
+    # target an older Ruby get parse errors for syntax their target
+    # doesn't support. Format validation here is loose — accepts
+    # any `<major>.<minor>` or `<major>.<minor>.<patch>` form, plus
+    # the literal `"latest"`. Prism itself enforces the supported
+    # set and raises `ArgumentError` for versions it does not
+    # recognise (e.g. `"1.0"`); the parse-time error message names
+    # the version, so the user can correct the setting.
+    TARGET_RUBY_FORMAT = /\A(?:\d+\.\d+(?:\.\d+)?|latest)\z/
+    private_constant :TARGET_RUBY_FORMAT
+
+    def coerce_target_ruby(value)
+      s = value.to_s
+      unless s.match?(TARGET_RUBY_FORMAT)
+        raise ArgumentError,
+              "target_ruby must be a version (e.g. \"3.4\", \"4.0\", \"3.4.0\") or \"latest\", got #{value.inspect}"
+      end
+
+      s.dup.freeze
+    end
+
+    # Slice 2 only accepts `:disabled` for the network policy. The
+    # YAML scalar may arrive as a String (`"disabled"`) or already
+    # as the Symbol; coerce to the canonical Symbol shape so the
+    # downstream `TrustPolicy` constructor stays strict.
+    #
+    # The accepted set is duplicated from
+    # {Rigor::Plugin::TrustPolicy::VALID_NETWORK_POLICIES} so
+    # `Configuration` does not require the plugin namespace at
+    # load time (Configuration is loaded before Plugin in
+    # `lib/rigor.rb`); the two stay in lockstep via spec.
+    VALID_NETWORK_POLICIES = %i[disabled].freeze
+    private_constant :VALID_NETWORK_POLICIES
+
+    def coerce_network_policy(value)
+      sym = value.to_sym
+      unless VALID_NETWORK_POLICIES.include?(sym)
+        raise ArgumentError,
+              "plugins_io.network must be one of #{VALID_NETWORK_POLICIES.inspect}, got #{value.inspect}"
+      end
+
+      sym
+    end
+
+    # ADR-8 § "Severity profile" — accepts the canonical Symbol
+    # form or its String spelling; rejects unknown profile names
+    # so typos fail loudly.
+    def coerce_severity_profile(value)
+      sym = value.to_sym
+      unless SeverityProfile::VALID_PROFILES.include?(sym)
+        raise ArgumentError,
+              "severity_profile must be one of " \
+              "#{SeverityProfile::VALID_PROFILES.inspect}, got #{value.inspect}"
+      end
+
+      sym
+    end
+
+    # ADR-8 § "Severity profile" — `severity_overrides:` is a
+    # `{ rule => severity }` map. Keys are canonical rule ids
+    # (`call.undefined-method`) or family wildcards (`call`).
+    # Values are {SeverityProfile::VALID_SEVERITIES} symbols
+    # (`:error` / `:warning` / `:info` / `:off`). Unknown
+    # severities raise; unknown rule ids are silently kept (the
+    # override is inert until the rule lands).
+    def coerce_severity_overrides(value)
+      raise ArgumentError, "severity_overrides must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)
+
+      value.to_h do |k, v|
+        sym = v.to_sym
+        unless SeverityProfile::VALID_SEVERITIES.include?(sym)
+          raise ArgumentError,
+                "severity_overrides[#{k.inspect}] must be one of " \
+                "#{SeverityProfile::VALID_SEVERITIES.inspect}, got #{v.inspect}"
+        end
+
+        [k.to_s, sym]
+      end.freeze
+    end
   end
 end