conformance-kit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e74bc1ed523498fd8aa7cd04191a6b13b690568c21a5a16627c0d2d147afb15
-  data.tar.gz: 9138ad7259e5f81442f50c9fab3e6a9b3fd08a3569a4861f27e62bc945f446b5
+  metadata.gz: 6f0701a2aba3683c8dff95e66fb8721c6a5dc51211e3afdb10ab30eaf8dae480
+  data.tar.gz: def47390a131f01068f3da132c1054ba763ceff96a64a103d7b39064e4d60f7b
 SHA512:
-  metadata.gz: acb89af04013c0b5e8efc69da423c53f794c9305359c0f7dfe131066cfa9f47f6436e586c6de74d80272a25a3f8f29deab16831045c37971d30815968b6286e0
-  data.tar.gz: 4ac36fc7dbef17b06b1c2fd7bca8c38ee6f915a910324f1173602af05d51ed571207c2f02536cd8d926adebe2d9e54a3c484dc606976d1bf199424860cedb209
+  metadata.gz: b875f57d615bb14cfe2bbb42f0250409c3dcf91e30c344d44a59f3dc3a71a8ed4c7ddb64dc56972db6bf86292a4ee049483c9ee89fb49ad568fc0f3a6cd1e3d1
+  data.tar.gz: 6b52bcfc88febff716fa8554ab6b4c44c3729b8762d94151f48c535a0af6d5207fa27db63e5e64a10d879fda0bf96653f3b7f2e10626df770342abb502c99eed

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.0
+
+- `main_only:` takes `ancestor:` rules (with optional `ivars:`): framework class state on the gem's own subclasses (ActiveRecord, ActionController, Rails::Engine, ActiveSupport::Concern, ...) in one entry per framework instead of one per ivar per class. Constants are never covered; unused rules are listed as stale; an entry with an unknown key, or an ancestor every module has (`Object`, `Module`, ...), is a config error. `Audit::Finding` gains a `rule` member (the covering rule, or nil).
+- `conformance-audit` no longer crashes on a `BasicObject` value (ActiveRecord keeps one in an unresolved model's `@primary_key`): the finding names its class through `Kernel#class`.
+
 ## 0.3.0
 
 Breaking (pre-1.0): `conformance.yml` is a reusable workflow that each repo calls, instead of one an org ruleset requires. It runs on `workflow_call` only. A repo adds a caller pinned to a release tag (`uses: zoolutions/conformance-kit/.github/workflows/conformance.yml@vX.Y.Z`, see the README) and makes `conformance / Conformance settings` and `conformance / Conformance (Ruby 4.0)` required checks in its own branch ruleset. Repos outside zoolutions can use it the same way.

data/README.md

@@ -152,11 +152,18 @@ main_only:
     reason: guards boot-time registration; no non-main Ractor ever registers
   - name: MyGem::LOCK                          # constant: Owner::NAME
     reason: ...
+  - ancestor: Rails::Engine                    # framework state on the gem's own subclasses
+    ivars: ["@called_from", "@initializers", "@instance"]  # only the framework's ivars
+    reason: Rails::Engine's own class state, set by Rails at boot on the main Ractor
+  - ancestor: ActionController::Base           # without ivars: every ivar on its subclasses
+    reason: ActionController's own class state, set by Rails on the main Ractor
 ```
 
 `main_only:` is state that is deliberately main-only: every entry needs a `reason:`. Entries inside the audited namespaces that no longer turn up are listed as stale, and so are `audit.skip_autoloads` entries that are no longer unloaded autoloads.
 
-`strict_autoloads: true` needs `audit.require` to load everything, e.g. a file that calls your Zeitwerk loader's `eager_load!`.
+An `ancestor:` entry covers the class state a framework keeps on the gem's own classes, which would otherwise take one `name:` entry per ivar per class (a Rails engine easily needs a hundred): every class/module ivar on a module that inherits from, includes or is extended with that constant. It never covers a constant. Prefer `ivars:`: it narrows the rule to the framework's own ivars, so state the gem keeps on the same classes is still audited. Without `ivars:`, that state is allowlisted too, so use the bare form only for classes the gem adds no state to. A `name:` entry for an ivar a rule also covers keeps its own reason. A rule that covered nothing, or whose constant isn't loaded (never loaded by the audit, even if it is a declared autoload), is listed as stale. `BasicObject`, `Object`, `Kernel`, `Module` and `Class` are rejected as ancestors (every module has them), and so is any unknown key in an entry, so a typo cannot widen a rule. `audit.skip_autoloads` takes `name:` entries only.
+
+`strict_autoloads: true` needs `audit.require` to load everything, e.g. a file that calls your Zeitwerk loader's `eager_load!`. In a Rails engine, `MyGem::Engine.eager_load!` is a no-op (Rails 7+): call `Zeitwerk::Loader.eager_load_namespace(MyGem)` after booting the dummy app instead, and reference constants in `autoload_once_paths` explicitly.
 
 ## RuboCop
 
@@ -205,22 +212,29 @@ The workflow has three jobs:
 
 ### Staying current
 
-Dependabot bumps both pins: the `uses:` tag (`github-actions`) and the gem (`bundler`), in separate pull requests.
+Dependabot bumps both pins, the `uses:` tag (`github-actions`) and the gem (`bundler`), in **one** pull request through a multi-ecosystem group. It can still open one with a single pin when only one ecosystem has an update so far (the tag is out but RubyGems hasn't published the gem yet): the version handshake then fails that pull request until the other pin catches up, so check both before merging. The `allow` lists keep it to the kit; drop them to have Dependabot maintain everything else too.
 
 ```yaml
 # .github/dependabot.yml
 version: 2
+multi-ecosystem-groups:
+  conformance-kit:
+    schedule: { interval: weekly }
 updates:
   - package-ecosystem: github-actions
     directory: /
-    schedule: { interval: weekly }
+    multi-ecosystem-group: conformance-kit
+    patterns: ["zoolutions/conformance-kit*"]
+    allow:
+      - dependency-name: "zoolutions/conformance-kit*"
   - package-ecosystem: bundler
     directory: /
-    schedule: { interval: weekly }
+    multi-ecosystem-group: conformance-kit
+    patterns: ["conformance-kit"]
+    allow:
+      - dependency-name: conformance-kit
 ```
 
-Merge the gem bump first: after a minor or major release the workflow bump fails the version handshake until the lockfile has caught up.
-
 ### `conformance-kit check`, the local equivalent
 
 ```bash
@@ -243,7 +257,7 @@ bundle exec conformance-kit config probes.gem_name
 
 ### The version handshake
 
-The behaviour a repo is held to comes from the `conformance-kit` in its lockfile; only the plumbing comes from the workflow tag. So that a stale lockfile cannot pass a newer workflow vacuously, the workflow reads its own tag from `job.workflow_ref` (the called workflow's ref; `github.workflow_ref` is the caller's) and fails with "bump conformance-kit to ~> X.Y" when the repo resolves anything older than `X.Y`. The version is derived, never stored. When the caller pins anything other than a `vX.Y.Z` tag (a branch, a commit SHA, or this repo's own `./` caller) the handshake is skipped with a notice, and so it is on GitHub Enterprise Server, which has no `job.workflow_ref`. That a tag-pinned call carries the tag is GitHub's documented behaviour; it has not been seen on a run yet, since v0.3.0 is the first tag that can be called. Until it has, treat the handshake as pending validation.
+The behaviour a repo is held to comes from the `conformance-kit` in its lockfile; only the plumbing comes from the workflow tag. So that a stale lockfile cannot pass a newer workflow vacuously, the workflow reads its own tag from `job.workflow_ref` (the called workflow's ref; `github.workflow_ref` is the caller's) and fails with "bump conformance-kit to ~> X.Y" when the repo resolves anything older than `X.Y`. The version is derived, never stored. When the caller pins anything other than a `vX.Y.Z` tag (a branch, a commit SHA, or this repo's own `./` caller) the handshake is skipped with a notice, and so it is on GitHub Enterprise Server, which has no `job.workflow_ref`.
 
 ## Development
 

data/lib/conformance_kit/audit/allowlist.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "ancestor_rule"
 
 module ConformanceKit
   class Audit
@@ -14,8 +15,10 @@ module ConformanceKit
     #       reason: guards boot-time registration; never touched by a non-main Ractor
     #     - name: MyGem::LOCK                # a constant: Owner::NAME
     #       reason: ...
+    #     - ancestor: Rails::Engine          # framework state on the gem's subclasses
+    #       reason: ...                      # (see AncestorRule)
     #
-    # `audit.skip_autoloads:` entries have the same shape (`key:` names the list).
+    # `audit.skip_autoloads:` entries have the name:/reason: shape (`key:` names the list).
     class Allowlist
       def self.empty = new([])
 
@@ -28,37 +31,96 @@ module ConformanceKit
         raise AllowlistError, "#{path}: #{e.message}"
       end
 
-      attr_reader :entries
+      attr_reader :entries, :ancestor_rules
 
       def initialize(entries, source: "the allowlist", key: "main_only")
         @key = key
         raise AllowlistError, "#{source}: #{key}: must be a list" unless entries.is_a?(Array)
 
         @entries = entries.map { validate(_1, source) }
+        @ancestor_rules = @entries.select { _1.key?("ancestor") }.map { AncestorRule.new(_1) }.freeze
       end
 
-      def names = entries.map { _1["name"] }
+      def names = entries.filter_map { _1["name"] }
       def include?(name) = names.include?(name)
       def reason_for(name) = entries.find { _1["name"] == name }&.fetch("reason")
 
+      # Ancestors every module has: a rule naming one would cover every ivar.
+      EVERY_MODULE = %w[BasicObject Object Kernel Module Class].freeze
+
       private
 
       def validate(entry, source)
         unless entry.is_a?(Hash)
           raise AllowlistError,
-                "#{source}: each #{@key} entry needs a name: and a reason:, got #{entry.inspect}"
+                "#{source}: each #{@key} entry needs a name: (or, in main_only, an ancestor:) and a reason:, " \
+                "got #{entry.inspect}"
         end
 
-        name = entry["name"]
-        raise AllowlistError, "#{source}: a #{@key} entry has no name: (#{entry.inspect})" if blank?(name)
-        if blank?(entry["reason"])
-          raise AllowlistError,
-                "#{source}: #{name} has no reason: (say why it is safe)"
-        end
+        validate_keys(entry, source)
+        label = validate_target(entry, source)
+        raise AllowlistError, "#{source}: #{label} has no reason: (say why it is safe)" if blank?(entry["reason"])
 
         entry
       end
 
+      # Every key is known, so a typo (ivar: for ivars:) cannot quietly widen a rule.
+      def validate_keys(entry, source)
+        if @key != "main_only" && entry.key?("ancestor")
+          raise AllowlistError, "#{source}: #{@key} entries take a name:, not an ancestor: (#{entry['ancestor']})"
+        end
+
+        known = @key == "main_only" ? %w[name ancestor ivars reason] : %w[name reason]
+        unknown = entry.keys - known
+        return if unknown.empty?
+
+        raise AllowlistError, "#{source}: a #{@key} entry has an unknown key #{unknown.first} " \
+                              "(one of #{known.join(', ')}): #{entry.inspect}"
+      end
+
+      # An entry names one constant or ivar (name:), or, in main_only, a
+      # framework ancestor (ancestor:, optional ivars:). Returns its label.
+      def validate_target(entry, source)
+        targets = %w[name ancestor].select { entry.key?(_1) }
+        unless targets.size == 1
+          raise AllowlistError, "#{source}: each #{@key} entry needs a name: or an ancestor:, not both " \
+                                "(#{entry.inspect})"
+        end
+
+        key = targets.first
+        raise AllowlistError, "#{source}: a #{@key} entry has a blank #{key}: (#{entry.inspect})" if blank?(entry[key])
+        return validate_name(entry, source) if key == "name"
+
+        validate_ancestor(entry, entry["ancestor"], source)
+        "ancestor #{entry['ancestor']}"
+      end
+
+      def validate_name(entry, source)
+        return entry["name"] unless entry.key?("ivars")
+
+        raise AllowlistError, "#{source}: #{entry['name']}: ivars: only goes with an ancestor:"
+      end
+
+      # Ruby's constant rule, Unicode included: each segment starts with an uppercase letter.
+      CONSTANT_PATH = /\A(?:::)?\p{Upper}\p{Word}*(?:::\p{Upper}\p{Word}*)*\z/
+      private_constant :CONSTANT_PATH
+
+      def validate_ancestor(entry, ancestor, source)
+        unless ancestor.match?(CONSTANT_PATH)
+          raise AllowlistError, "#{source}: ancestor #{ancestor.inspect} is not a constant path (e.g. Rails::Engine)"
+        end
+        if EVERY_MODULE.include?(ancestor.delete_prefix("::"))
+          raise AllowlistError, "#{source}: ancestor #{ancestor} matches every module: name the framework's own class"
+        end
+        return unless entry.key?("ivars")
+
+        ivars = entry["ivars"]
+        return if ivars.is_a?(Array) && !ivars.empty? && ivars.all? { _1.is_a?(String) && _1.match?(/\A@\w+\z/) }
+
+        raise AllowlistError,
+              "#{source}: ancestor #{ancestor}: ivars: must be a non-empty list of @names, got #{ivars.inspect}"
+      end
+
       def blank?(value) = !value.is_a?(String) || value.strip.empty?
     end
   end

data/lib/conformance_kit/audit/ancestor_rule.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ConformanceKit
+  class Audit
+    # A `main_only:` entry that names a framework class or module instead of
+    # one ivar: every class/module ivar (or only the listed `ivars:`) on a
+    # module that inherits from, includes or is extended with `ancestor` is
+    # main-only, for one reason. Constants are never covered: they are the
+    # gem's own.
+    #
+    #   main_only:
+    #     - ancestor: ActiveRecord::Base
+    #       ivars: ["@primary_key"]      # optional; omit to cover every ivar
+    #       reason: ActiveRecord's own class state, set by Rails at boot on the main Ractor
+    class AncestorRule
+      attr_reader :ancestor, :ivars, :reason
+
+      def initialize(entry)
+        @ancestor = entry.fetch("ancestor").delete_prefix("::")
+        @ivars = entry["ivars"]&.dup&.freeze
+        @reason = entry.fetch("reason")
+        freeze
+      end
+
+      def label = ivars ? "ancestor #{ancestor} (#{ivars.join(', ')})" : "ancestor #{ancestor}"
+
+      # The loaded module +ancestor+ names, or nil when it isn't loaded: not
+      # defined, or only a declared autoload (never loaded here: loading it
+      # mid-audit would change what is being audited). A nil rule covers
+      # nothing and is listed as stale. Called once per audit, after audit.require.
+      #
+      # Raises AllowlistError when the path resolves to a module every module
+      # has (Object::Kernel is Kernel): the name check alone can't see aliases.
+      def resolve
+        target = walk
+        return target unless target && EVERY_MODULE.any? { target.equal?(_1) }
+
+        raise AllowlistError, "ancestor #{ancestor} resolves to #{target}, which every module has: " \
+                              "name the framework's own class"
+      end
+
+      # Whether this rule covers +ivar+ on +mod+, given its resolved +target+.
+      def covers?(mod, ivar, target)
+        return false if ivars && !ivars.include?(ivar.to_s)
+        return false if target.equal?(mod)
+
+        [mod, core(::Kernel, :singleton_class, mod)].any? do |owner|
+          core(::Module, :ancestors, owner).any? { _1.equal?(target) }
+        end
+      end
+
+      EVERY_MODULE = [::BasicObject, ::Object, ::Kernel, ::Module, ::Class].freeze
+      private_constant :EVERY_MODULE
+
+      private
+
+      def walk
+        ancestor.split("::").reduce(Object) do |scope, segment|
+          return nil unless core(::Module, :const_defined?, scope, segment, false)
+          return nil if core(::Module, :autoload?, scope, segment, false)
+
+          value = core(::Module, :const_get, scope, segment, false)
+          return nil unless ::Module === value # rubocop:disable Style/CaseEquality -- a BasicObject has no is_a?
+
+          value
+        end
+      end
+
+      # The core reflection methods, bound directly, as in Audit.
+      def core(owner, method, receiver, *) = owner.instance_method(method).bind_call(receiver, *)
+    end
+  end
+end

data/lib/conformance_kit/audit/cli.rb

@@ -112,9 +112,9 @@ module ConformanceKit
       end
 
       def details(audit, strict_autoloads)
-        allowlisted = audit.allowlisted.map { "#{_1.name} — #{audit.allowlist.reason_for(_1.name)}" }
+        allowlisted = audit.allowlisted.map { "#{_1.name} — #{audit.reason_for(_1)}" }
         section("allowlisted main-only:", allowlisted)
-        section("stale allowlist entries (no longer found):", audit.stale)
+        section("stale allowlist entries (no longer found, or rules that covered nothing):", audit.stale)
         skipped = audit.skipped_autoloads - audit.unexpected_autoloads
         section("unloaded autoloads skipped by audit.skip_autoloads:",
                 skipped.map { "#{_1} — #{audit.skip_autoloads.reason_for(_1)}" })

data/lib/conformance_kit/audit.rb

@@ -12,7 +12,8 @@ module ConformanceKit
   # eager-load) everything the audit should see, and list deliberate exceptions
   # in `skip_autoloads` (`audit.skip_autoloads:` in .conformance.yml).
   class Audit
-    Finding = Data.define(:name, :kind, :value_class, :path, :reason) do
+    # +rule+: the main_only ancestor: rule that covers it, or nil.
+    Finding = Data.define(:name, :kind, :value_class, :path, :reason, :rule) do
       def to_s
         where = path.empty? ? "" : " #{path} is"
         "#{name} (#{kind}) #{value_class}:#{where} #{reason}"
@@ -42,10 +43,16 @@ module ConformanceKit
     # Skipped autoloads not listed in skip_autoloads: what strict_autoloads fails on.
     def unexpected_autoloads = skipped_autoloads - @skip_autoloads.names
 
-    # Allowlisted names inside the audited namespaces that no longer turn up.
+    # Why an allowlisted finding is main-only: its own name: entry's reason, else its ancestor: rule's.
+    def reason_for(finding) = @allowlist.reason_for(finding.name) || finding.rule&.reason
+
+    # Allowlisted names inside the audited namespaces that no longer turn up,
+    # and ancestor: rules that covered nothing.
     def stale
       found = scan.map(&:name)
-      @allowlist.names.select { in_namespace?(_1) && !found.include?(_1) }
+      used = scan.filter_map(&:rule)
+      @allowlist.names.select { in_namespace?(_1) && !found.include?(_1) } +
+        @allowlist.ancestor_rules.reject { |rule| used.any? { _1.equal?(rule) } }.map(&:label)
     end
 
     # skip_autoloads names inside the audited namespaces that are no longer unloaded autoloads.
@@ -57,7 +64,7 @@ module ConformanceKit
     private
 
     def partitioned
-      @partitioned ||= scan.partition { !@allowlist.include?(_1.name) }
+      @partitioned ||= scan.partition { !_1.rule && !@allowlist.include?(_1.name) }
     end
 
     def scan
@@ -82,14 +89,14 @@ module ConformanceKit
       constants_of(mod).filter_map do |constant|
         next if autoload?(mod, constant)
 
-        finding("#{name}::#{constant}", "constant", core(::Module, :const_get, mod, constant, false))
+        finding("#{name}::#{constant}", "constant", core(::Module, :const_get, mod, constant, false), nil)
       end
     end
 
     def ivar_findings(mod, name)
       core(::Kernel, :instance_variables, mod).filter_map do |ivar|
         kind = mod.is_a?(Class) ? "class ivar" : "module ivar"
-        finding("#{name}.#{ivar}", kind, core(::Kernel, :instance_variable_get, mod, ivar))
+        finding("#{name}.#{ivar}", kind, core(::Kernel, :instance_variable_get, mod, ivar), mod, ivar)
       end
     end
 
@@ -99,11 +106,19 @@ module ConformanceKit
     def constants_of(mod) = core(::Module, :constants, mod, false)
     def autoload?(mod, constant) = core(::Module, :autoload?, mod, constant)
 
-    def finding(name, kind, value)
+    # +mod+ and +ivar+ (an ivar finding only) are what an ancestor: rule matches on.
+    def finding(name, kind, value, mod, ivar = nil)
       culprit = Shareability.culprit(value)
       return nil unless culprit
 
-      Finding.new(name: name, kind: kind, value_class: value.class.name, path: culprit.path, reason: culprit.reason)
+      Finding.new(name: name, kind: kind, value_class: core(::Kernel, :class, value).name, path: culprit.path,
+                  reason: culprit.reason, rule: ivar && rule_for(mod, ivar))
     end
+
+    # The first ancestor: rule covering +ivar+ on +mod+, or nil.
+    def rule_for(mod, ivar) = rule_targets.find { |rule, target| target && rule.covers?(mod, ivar, target) }&.first
+
+    # Each ancestor: rule with the module it names, resolved once, after audit.require.
+    def rule_targets = @rule_targets ||= @allowlist.ancestor_rules.map { [_1, _1.resolve] }
   end
 end

data/lib/conformance_kit/config.rb

@@ -117,7 +117,7 @@ module ConformanceKit
       string: "a string (quote it)",
       boolean: "true or false",
       string_map: "a mapping of names to string values (quote numbers)",
-      entries: "a list of name:/reason: entries"
+      entries: "a list of name:/reason: (or, in main_only, ancestor:/reason:) entries"
     }.freeze
     private_constant :EXPECTED
 

data/lib/conformance_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConformanceKit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conformance-kit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - mhenrixon
@@ -30,6 +30,7 @@ files:
 - lib/conformance_kit.rb
 - lib/conformance_kit/audit.rb
 - lib/conformance_kit/audit/allowlist.rb
+- lib/conformance_kit/audit/ancestor_rule.rb
 - lib/conformance_kit/audit/cli.rb
 - lib/conformance_kit/checks/boot_finalized.rb
 - lib/conformance_kit/checks/consistency.rb