jobcompat 0.2.1 → 0.3.1

data/lib/jobcompat/analysis.rb

@@ -1,5 +1,6 @@
 require "prism"
 require_relative "canonical_worker_name"
+require_relative "aliases"
 
 module Jobcompat
   Location = Data.define(:revision, :path, :line, :column, :role, :excerpt) do
@@ -56,14 +57,32 @@ module Jobcompat
   end
 
   class RevisionSnapshot
-    attr_reader :label, :ref, :sha, :workers, :calls, :unknowns, :index, :files_scanned, :tracked_ruby
+    attr_reader :label, :ref, :sha, :workers, :aliases, :bindings, :calls, :unknowns, :index, :files_scanned, :tracked_ruby
 
-    def initialize(label:, ref:, sha:, workers:, calls:, unknowns:, index:, files_scanned:, tracked_ruby:)
+    def initialize(label:, ref:, sha:, workers:, calls:, unknowns:, index:, files_scanned:, tracked_ruby:, aliases: {}, bindings: [])
       @label, @ref, @sha, @workers, @calls, @unknowns, @index, @files_scanned, @tracked_ruby = label, ref, sha, workers, calls, unknowns, index, files_scanned, tracked_ruby
+      @aliases = aliases
+      @bindings = bindings.group_by(&:name).freeze
+    end
+
+    def consumer(name)
+      binding = aliases[name]
+      return workers[name] unless binding
+      return unless binding.resolved?
+      terminal = workers.fetch(binding.target)
+      terminal.with(name: name, locations: (binding.locations + terminal.locations).uniq,
+                    declaration_locations: (binding.locations + terminal.declaration_locations).uniq,
+                    fingerprint_parts: [binding.fingerprint_parts, terminal.fingerprint_parts])
+    end
+
+    def presence(name)
+      binding = aliases[name]
+      return binding.resolved? ? "resolved_alias" : "defined_unrecognized" if binding
+      index.status(name, recognized: workers.key?(name))
     end
 
     def check_presence(names, repository, config)
-      unresolved = names.reject { |name| index.status(name, recognized: workers.key?(name)) != "absent" }
+      unresolved = names.select { |name| presence(name) == "absent" }
       return if unresolved.empty?
       consumed = 0
       eligible = []
@@ -105,11 +124,12 @@ module Jobcompat
     PATH_CONSTANT_BINDINGS = [Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode,
                               Prism::ConstantPathAndWriteNode, Prism::ConstantPathOperatorWriteNode,
                               Prism::ConstantPathTargetNode].freeze
-    attr_reader :fragments, :calls, :unknowns
+    attr_reader :fragments, :calls, :unknowns, :bindings, :alias_candidates, :ambiguous_bindings
 
     def initialize(revision, path, source, index:, presence_only: false)
       @revision, @path, @source, @index, @presence_only = revision, path, source, index, presence_only
       @fragments, @calls, @unknowns = [], [], []
+      @bindings, @alias_candidates, @ambiguous_bindings = [], [], []
     end
 
     def analyze
@@ -122,7 +142,7 @@ module Jobcompat
         end
         raise Error.new(diagnostics.first[:message], category: "parse_error", location: diagnostics.first[:location], diagnostics: diagnostics)
       end
-      walk(result.value, [], [], nil)
+      walk(result.value, [], [], nil, true)
       self
     end
 
@@ -156,19 +176,30 @@ module Jobcompat
 
     private
 
-    def walk(node, namespace, scope, statement)
+    def walk(node, namespace, scope, statement, alias_context = false, alias_statement = nil)
       return unless node.is_a?(Prism::Node)
       case node
+      when Prism::ProgramNode
+        walk(node.statements, namespace, scope, nil, alias_context)
       when Prism::StatementsNode
-        node.body.each { |child| walk(child, namespace, scope, child) }
+        node.body.each { |child| walk(child, namespace, scope, child, alias_context, alias_context ? child : (alias_statement || child)) }
       when Prism::ClassNode, Prism::ModuleNode
         constant = self.class.constant(node.constant_path)
         name, valid = declaration_name(constant, namespace)
         location = loc(node, "worker_declaration")
         @index.add(name, location, selected: !@presence_only, ambiguous: !valid) if name
+        if name && !@presence_only
+          @bindings << ConstantBinding.new(name, "declaration", location,
+                                            [scope, self.class.normalize(node.constant_path.location.slice), node.class.name])
+        end
         if !name && node.constant_path.is_a?(Prism::ConstantPathNode)
           @index.add(node.constant_path.name.to_s.encode(Encoding::UTF_8), location, selected: !@presence_only, ambiguous: true)
         end
+        unless valid || @presence_only
+          leaf = name&.split("::")&.last || node.constant_path.name.to_s.encode(Encoding::UTF_8)
+          @ambiguous_bindings << ConstantBinding.new(leaf, "declaration", location,
+                                                     [scope, self.class.normalize(node.constant_path.location.slice), node.class.name])
+        end
         new_scope = scope + [name || "<unsupported_class>"]
         if node.is_a?(Prism::ClassNode) && valid && !@presence_only
           body = node.body.is_a?(Prism::StatementsNode) ? node.body.body : []
@@ -185,24 +216,25 @@ module Jobcompat
                                    [@path, new_scope, self.class.normalize(node.constant_path.location.slice), include_tokens])
         end
         child_namespace = valid && namespace ? namespace + [name] : nil
-        walk(node.superclass, namespace, scope, statement) if node.is_a?(Prism::ClassNode) && node.superclass
-        walk(node.body, child_namespace, new_scope, nil) if node.body
+        walk(node.superclass, namespace, scope, statement, false, alias_statement) if node.is_a?(Prism::ClassNode) && node.superclass
+        body_context = alias_context && node.equal?(statement) && valid
+        walk(node.body, child_namespace, new_scope, nil, body_context, body_context ? nil : alias_statement) if node.body
       when Prism::DefNode
         method_scope = node.receiver ? [self.class.normalize(node.receiver.location.slice), node.name.to_s] : node.name.to_s
         child_scope = scope + [method_scope]
-        walk(node.receiver, namespace, scope, statement) if node.receiver
-        walk(node.parameters, namespace, child_scope, node.parameters) if node.parameters
-        walk(node.body, namespace, child_scope, nil) if node.body
+        walk(node.receiver, namespace, scope, statement, false, alias_statement) if node.receiver
+        walk(node.parameters, namespace, child_scope, node.parameters, false, alias_statement) if node.parameters
+        walk(node.body, namespace, child_scope, nil, false, alias_statement) if node.body
       when Prism::SingletonClassNode
-        walk(node.expression, namespace, scope, statement)
+        walk(node.expression, namespace, scope, statement, false, alias_statement)
         singleton_scope = scope + [["singleton_class", self.class.normalize(node.expression.location.slice)]]
-        walk(node.body, namespace, singleton_scope, nil) if node.body
+        walk(node.body, namespace, singleton_scope, nil, false, alias_statement) if node.body
       when Prism::CallNode
         extract_call(node, namespace, scope, statement) unless @presence_only
-        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement) }
+        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement, false, alias_statement || statement) }
       else
-        constant_write(node, namespace) if SIMPLE_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) } || PATH_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) }
-        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement) }
+        constant_write(node, namespace, scope, alias_statement || statement, alias_context && node.equal?(statement)) if SIMPLE_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) } || PATH_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) }
+        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement, false, alias_statement || statement) }
       end
     end
 
@@ -214,10 +246,12 @@ module Jobcompat
       [((rooted || segments.length > 1) ? segments : (namespace.empty? ? [] : namespace.last.split("::")) + segments).join("::"), true]
     end
 
-    def constant_write(node, namespace)
+    def constant_write(node, namespace, scope, statement, alias_context)
       if SIMPLE_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) }
         prefix = namespace.nil? || namespace.empty? ? [] : namespace.last.split("::")
-        @index.add((prefix + [node.name.to_s.encode(Encoding::UTF_8)]).join("::"), loc(node, "worker_declaration"),
+        name = (prefix + [node.name.to_s.encode(Encoding::UTF_8)]).join("::")
+        valid = !namespace.nil?
+        @index.add(name, loc(node, "worker_declaration"),
                    selected: !@presence_only, ambiguous: namespace.nil?)
       else
         target = node.is_a?(Prism::ConstantPathTargetNode) ? node : node.target
@@ -228,6 +262,22 @@ module Jobcompat
           @index.add(target.name.to_s.encode(Encoding::UTF_8), loc(node, "worker_declaration"), selected: !@presence_only, ambiguous: true)
         end
       end
+      return if @presence_only
+      unless valid
+        leaf = name&.split("::")&.last || target.name.to_s.encode(Encoding::UTF_8)
+        @ambiguous_bindings << ConstantBinding.new(leaf, "write", loc(node, "worker_declaration"),
+                                                   [scope, self.class.normalize(node.location.slice), self.class.normalize((statement || node).location.slice)])
+      end
+      return if name.nil?
+      plain = node.is_a?(Prism::ConstantWriteNode) || node.is_a?(Prism::ConstantPathWriteNode)
+      reference = self.class.constant(node.value) if node.respond_to?(:value)
+      supported = plain && valid && alias_context && reference &&
+                  (reference.last || reference.first.length == 1 || namespace.empty?)
+      location = loc(node, "worker_declaration")
+      parts = [scope, self.class.normalize(node.location.slice), self.class.normalize((statement || node).location.slice), reference]
+      @bindings << ConstantBinding.new(name, "write", location, parts)
+      @alias_candidates << AliasCandidate.new(name, reference && reference.first.join("::"), reference && reference.last,
+                                              namespace, !!supported, location, parts)
     end
 
     def sidekiq_include?(node)
@@ -421,7 +471,7 @@ module Jobcompat
       selected = entries.select { |entry| @config.scan?(entry.path) }
       tracked = entries.select { |entry| entry.path.end_with?(".rb") }
       index = DefinedConstantIndex.new
-      fragments, calls, unknowns, errors = [], [], [], []
+      fragments, calls, unknowns, errors, bindings, alias_candidates, ambiguous_bindings = [], [], [], [], [], [], []
       @repository.each_blob(selected) do |entry, bytes|
         path = entry.path
         begin
@@ -429,6 +479,9 @@ module Jobcompat
           fragments.concat(result.fragments)
           calls.concat(result.calls)
           unknowns.concat(result.unknowns)
+          bindings.concat(result.bindings)
+          alias_candidates.concat(result.alias_candidates)
+          ambiguous_bindings.concat(result.ambiguous_bindings)
         rescue Error => error
           errors << error
         end
@@ -470,8 +523,9 @@ module Jobcompat
           workers[name] = Contract.new(name, required, rest ? nil : required + optional, forwarding ? "forwarding" : "positional", signature, nil, locations, declarations, fingerprint_parts)
         end
       end
-      RevisionSnapshot.new(label: label, ref: ref, sha: sha, workers: workers, calls: calls, unknowns: unknowns, index: index,
-                           files_scanned: selected.length, tracked_ruby: tracked)
+      aliases = AliasResolver.new(workers, bindings, alias_candidates, ambiguous_bindings).resolve
+      RevisionSnapshot.new(label: label, ref: ref, sha: sha, workers: workers, aliases: aliases, calls: calls, unknowns: unknowns, index: index,
+                           files_scanned: selected.length, tracked_ruby: tracked, bindings: bindings)
     end
   end
 end

data/lib/jobcompat/cli.rb

@@ -9,6 +9,7 @@ module Jobcompat
     def initialize(args, stdout, stderr, directory)
       @args, @stdout, @stderr, @directory = args.dup, stdout, stderr, directory
       @base, @head, @format, @config_path = nil, "HEAD", "text", nil
+      @explain = false
       @base_sha = @head_sha = @loaded_config = nil
     end
 
@@ -22,12 +23,14 @@ module Jobcompat
         options.on("--head REF", "Head commit-ish (default HEAD)") { |value| @head = value }
         options.on("--format FORMAT", "text or json") { |value| @format = value }
         options.on("--config PATH", "Config YAML path") { |value| @config_path = value }
+        options.on("--explain", "Explain the evidence behind each finding (text only)") { @explain = true }
         options.on("-h", "--help", "Show help") { @stdout.puts(options); return 0 }
       end
       parser.parse!(@args)
       raise Error.new("Unexpected arguments: #{@args.join(' ')}", category: "config_error") unless @args.empty?
       raise Error.new("--base is required", category: "config_error") unless @base && !@base.empty?
       raise Error.new("--format must be text or json", category: "config_error") unless %w[text json].include?(@format)
+      raise Error.new("--explain is supported only with --format text", category: "config_error") if @explain && @format != "text"
       repository = GitRepository.new(@directory)
       config = Config.load(root: repository.root, explicit: @config_path, invocation_dir: @directory)
       @loaded_config = config.display_path
@@ -57,7 +60,7 @@ module Jobcompat
       requests = engine.presence_requests
       head.check_presence(requests["head"], repository, config)
       base.check_presence(requests["base"], repository, config)
-      result = engine.evaluate
+      result = engine.evaluate(with_explanations: @explain)
       findings, suppressions = config.suppressions(result[:findings])
       summary = {
         errors: findings.count { |item| item[:severity] == "error" }, warnings: findings.count { |item| item[:severity] == "warning" },
@@ -67,7 +70,13 @@ module Jobcompat
         enqueue_calls: {base: base.calls.length, head: head.calls.length,
                         unknown: engine.calls.values.flatten.count { |call| call[:reason] }}
       }
-      @stdout.write(Formatter.public_send(@format, envelope("completed", findings, suppressions, result[:workers], [], summary)))
+      completed = envelope("completed", findings, suppressions, result[:workers], [], summary)
+      output = if @format == "json"
+        Formatter.json(completed)
+      else
+        Formatter.text(completed, explanations: @explain ? result[:explanations] : nil)
+      end
+      @stdout.write(output)
       summary[:errors].positive? ? 1 : 0
     rescue OptionParser::ParseError => error
       failure(Error.new(error.message, category: "config_error"))
@@ -98,7 +107,7 @@ module Jobcompat
     end
 
     def envelope(status, findings, suppressions, workers, diagnostics, summary)
-      {schema_version: 2, tool: {name: "jobcompat", version: VERSION}, status: status,
+      {schema_version: 3, tool: {name: "jobcompat", version: VERSION}, status: status,
        comparison: {deployment_model: "rolling", base: {ref: @base, sha: @base_sha}, head: {ref: @head, sha: @head_sha}},
        configuration: {path: @loaded_config}, findings: findings, suppressions: suppressions, workers: workers,
        diagnostics: diagnostics, summary: summary}

data/lib/jobcompat/engine.rb

@@ -4,7 +4,7 @@ module Jobcompat
     REVISIONS = %w[base head].freeze
     TITLES = {
       "JC001" => "Old payload rejected by new worker", "JC002" => "New payload rejected by old worker",
-      "JC003" => "Current producer/consumer mismatch", "JC004" => "Worker class absent from HEAD source",
+      "JC003" => "Current producer/consumer mismatch", "JC004" => "Worker identity absent from HEAD source",
       "JC005" => "New worker enqueued before old fleet can understand it", "JC006" => "Worker contract narrowed without sufficient producer evidence",
       "JC007" => "Compatibility could not be proven"
     }.freeze
@@ -13,13 +13,18 @@ module Jobcompat
 
     def initialize(base, head)
       @base, @head = base, head
-      @names = (base.workers.keys + head.workers.keys).uniq.sort
-      @calls = {"base" => resolve(base.calls), "head" => resolve(head.calls)}
+      @lookup_names = (base.workers.keys + head.workers.keys + base.aliases.keys + head.aliases.keys).uniq
+      @calls = {"base" => resolve(base), "head" => resolve(head)}
+      referenced = calls.values.flatten.flat_map { |call| [call[:worker], call[:attributed_worker]] }.compact
+      shared_aliases = (base.aliases.keys & head.aliases.keys).select { |name| base.aliases[name].static_reference || head.aliases[name].static_reference }
+      @names = (base.workers.keys + head.workers.keys +
+                base.aliases.values.select(&:resolved?).map(&:name) +
+                shared_aliases + referenced).uniq.sort
       @calls_by_worker = {"base" => calls["base"].group_by { |call| call[:worker] },
                           "head" => calls["head"].group_by { |call| call[:worker] }}
       @presence_requests = {
-        "head" => (base.workers.keys - head.workers.keys).sort,
-        "base" => (head.workers.keys - base.workers.keys).select { |name| @calls_by_worker["head"].key?(name) }.sort
+        "head" => @names.select { |name| base.consumer(name) && !head.consumer(name) },
+        "base" => @names.select { |name| head.consumer(name) && !base.consumer(name) && @calls_by_worker["head"].key?(name) }
       }
     end
 
@@ -27,33 +32,44 @@ module Jobcompat
       @presence_requests
     end
 
-    def evaluate
+    def evaluate(with_explanations: false)
       findings = []
+      explanations = {}.compare_by_identity
       workers = @names.map do |name|
-        b = base.workers[name]
-        h = head.workers[name]
+        b = base.consumer(name)
+        h = head.consumer(name)
         bc = @calls_by_worker["base"].fetch(name, [])
         hc = @calls_by_worker["head"].fetch(name, [])
         base_presence = presence(base, name, b, presence_requests["base"].include?(name))
         head_presence = presence(head, name, h, presence_requests["head"].include?(name))
         if b && !h
           if head_presence == "absent"
-            findings << finding("JC004", name, ["base", "head"], ["base_to_head"], nil, nil,
-                                "The worker class is absent from HEAD tracked Ruby source.",
-                                "Queued, retried, or scheduled jobs may still reference this class name.",
-                                ["Keep a compatibility class until retained jobs can no longer run."],
-                                b.declaration_locations + b.locations.select { |loc| loc.role == "consumer" } + hc.map { |call| call[:location] })
-          else
-            findings << presence_unknown(name, head_presence, b.declaration_locations + head.index.locations(name), "base_to_head", "head")
+            item = finding("JC004", name, ["base", "head"], ["base_to_head"], nil, nil,
+                           "The serialized worker identity is absent from HEAD tracked Ruby source.",
+                           "Queued, retried, or scheduled jobs may still reference this class name.",
+                           ["Keep the worker class or a supported compatibility alias until retained jobs can no longer run."],
+                           b.declaration_locations + contract_proof(b) + producer_proof(hc))
+            findings << item
+            explanations[item] = ExplanationBuilder.jc004(worker: name, base_contract: b, head_producers: hc,
+                                                           aliases: alias_provenance(name)) if with_explanations
+          elsif !head.aliases.key?(name)
+            item = presence_unknown(name, head_presence, b.declaration_locations + head.index.locations(name), "base_to_head", "head")
+            findings << item
+            explanations[item] = ExplanationBuilder.presence_unknown(worker: name, status: head_presence, revision: "head") if with_explanations
           end
         elsif h && !b && !hc.empty?
           if base_presence == "absent"
-            findings << finding("JC005", name, ["base", "head"], ["head_to_base"], nil, nil,
-                                "HEAD can enqueue a worker class absent from base tracked Ruby source.",
-                                "If an old Sidekiq process can consume this job during the rolling deployment, it cannot resolve the new worker class.",
-                                ["Deploy the worker class before activating its producer."], h.declaration_locations + hc.map { |call| call[:location] })
-          else
-            findings << presence_unknown(name, base_presence, h.declaration_locations + base.index.locations(name), "head_to_base", "base")
+            item = finding("JC005", name, ["base", "head"], ["head_to_base"], nil, nil,
+                           "HEAD can enqueue a serialized worker identity absent from base tracked Ruby source.",
+                           "If an old Sidekiq process can consume this job during the rolling deployment, it cannot resolve the new worker class.",
+                           ["Deploy the worker class or compatibility alias before activating its producer."], h.declaration_locations + producer_proof(hc))
+            findings << item
+            explanations[item] = ExplanationBuilder.jc005(worker: name, head_contract: h, head_calls: hc,
+                                                          aliases: alias_provenance(name)) if with_explanations
+          elsif !base.aliases.key?(name)
+            item = presence_unknown(name, base_presence, h.declaration_locations + base.index.locations(name), "head_to_base", "base")
+            findings << item
+            explanations[item] = ExplanationBuilder.presence_unknown(worker: name, status: base_presence, revision: "base") if with_explanations
           end
         end
 
@@ -66,11 +82,14 @@ module Jobcompat
             head_same = head_groups.fetch(arity, []).select { |call| !h.accepts?(call[:arity]) }
             directions = ["base_to_head"]
             directions << "head_to_head" unless head_same.empty?
-            locations = group.map { |call| call[:location] } + b.locations.select { |loc| loc.role == "consumer" } + h.locations.select { |loc| loc.role == "consumer" } + head_same.map { |call| call[:location] }
-            findings << finding("JC001", name, head_same.empty? ? ["base", "head"] : ["base", "head"], directions, arity, nil,
-                                "Base emits #{arity} #{argument_word(arity)}, but the HEAD worker accepts #{h.display_range}.",
-                                "Jobs queued by the base revision may fail after deployment.",
-                                ["Make the HEAD worker accept old payloads.", "Narrow only after queue, retry, and schedule retention is handled."], locations)
+            locations = producer_proof(group) + contract_proof(b) + contract_proof(h) + producer_proof(head_same)
+            item = finding("JC001", name, head_same.empty? ? ["base", "head"] : ["base", "head"], directions, arity, nil,
+                           "Base emits #{arity} #{argument_word(arity)}, but the HEAD worker accepts #{h.display_range}.",
+                           "Jobs queued by the base revision may fail after deployment.",
+                           ["Make the HEAD worker accept old payloads.", "Narrow only after queue, retry, and schedule retention is handled."], locations)
+            findings << item
+            explanations[item] = ExplanationBuilder.jc001(arity: arity, base_contract: b, head_contract: h, head_witness: !head_same.empty?,
+                                                          aliases: alias_provenance(name)) if with_explanations
             proven_narrow = true
           end
         end
@@ -79,17 +98,23 @@ module Jobcompat
           head_groups.sort.each do |arity, group|
             if !h.accepts?(arity)
               next if findings.any? { |item| item[:rule_id] == "JC001" && item[:worker] == name && item[:payload_arity] == arity }
-              findings << finding("JC003", name, ["head"], ["head_to_head"], arity, nil,
-                                  "HEAD emits #{arity} #{argument_word(arity)}, but its worker accepts #{h.display_range}.",
-                                  "Current HEAD jobs can fail when executed.", ["Align the enqueue payload with the HEAD perform signature."],
-                                  group.map { |call| call[:location] } + h.locations.select { |loc| loc.role == "consumer" })
+              item = finding("JC003", name, ["head"], ["head_to_head"], arity, nil,
+                             "HEAD emits #{arity} #{argument_word(arity)}, but its worker accepts #{h.display_range}.",
+                             "Current HEAD jobs can fail when executed.", ["Align the enqueue payload with the HEAD perform signature."],
+                             producer_proof(group) + contract_proof(h))
+              findings << item
+              explanations[item] = ExplanationBuilder.jc003(arity: arity, head_contract: h,
+                                                            aliases: alias_provenance(name, head)) if with_explanations
               current_removed_witness ||= b&.known? && b.accepts?(arity)
             elsif b&.known? && !b.accepts?(arity)
-              findings << finding("JC002", name, ["base", "head"], ["head_to_base"], arity, nil,
-                                  "HEAD emits #{arity} #{argument_word(arity)}, but the base worker accepts #{b.display_range}.",
-                                  "A new producer can enqueue work that an old worker cannot execute during a rolling deploy.",
-                                  ["Deploy the optional worker argument first.", "Start enqueueing the new argument in a later release."],
-                                  group.map { |call| call[:location] } + b.locations.select { |loc| loc.role == "consumer" } + h.locations.select { |loc| loc.role == "consumer" })
+              item = finding("JC002", name, ["base", "head"], ["head_to_base"], arity, nil,
+                             "HEAD emits #{arity} #{argument_word(arity)}, but the base worker accepts #{b.display_range}.",
+                             "A new producer can enqueue work that an old worker cannot execute during a rolling deploy.",
+                             ["Deploy the optional worker argument first.", "Start enqueueing the new argument in a later release."],
+                             producer_proof(group) + contract_proof(b) + contract_proof(h))
+              findings << item
+              explanations[item] = ExplanationBuilder.jc002(arity: arity, base_contract: b, head_contract: h,
+                                                            aliases: alias_provenance(name)) if with_explanations
             end
           end
         end
@@ -97,16 +122,20 @@ module Jobcompat
           unless h.superset_of?(b) || proven_narrow || current_removed_witness
             removed = removed_arity_ranges(b, h)
             label = removed.length == 1 && removed.first.match?(/\A\d+\z/) ? "arity" : "arities"
-            findings << finding("JC006", name, ["base", "head"], ["base_to_head"], nil, nil,
-                                "The HEAD worker removed #{label} #{removed.join(', ')} from the base contract; no qualifying producer witness was found.",
-                                "No repository producer callsite found does not prove that no queued, scheduled, retried, historical, or externally enqueued payload exists.",
-                                ["Keep the broader signature through the retention window, or document a proven drain."],
-                                b.locations.select { |loc| loc.role == "consumer" } + h.locations.select { |loc| loc.role == "consumer" })
+            item = finding("JC006", name, ["base", "head"], ["base_to_head"], nil, nil,
+                           "The HEAD worker removed #{label} #{removed.join(', ')} from the base contract; no qualifying producer witness was found.",
+                           "No repository producer callsite found does not prove that no queued, scheduled, retried, historical, or externally enqueued payload exists.",
+                           ["Keep the broader signature through the retention window, or document a proven drain."],
+                           contract_proof(b) + contract_proof(h))
+            findings << item
+            explanations[item] = ExplanationBuilder.jc006(worker: name, base_contract: b, head_contract: h, removed: removed,
+                                                          aliases: alias_provenance(name)) if with_explanations
           end
         end
 
         {
           name: name, base_presence: base_presence, head_presence: head_presence,
+          base_alias: base.aliases[name]&.as_json, head_alias: head.aliases[name]&.as_json,
           base_contract: b&.as_json, head_contract: h&.as_json,
           producer_arities: {base: bc.filter_map { |call| call[:arity] unless call[:reason] }.uniq.sort,
                              head: hc.filter_map { |call| call[:arity] unless call[:reason] }.uniq.sort,
@@ -115,42 +144,92 @@ module Jobcompat
                           head_to_base: cell(hc, b, base_presence), head_to_head: cell(hc, h, head_presence)}
         }
       end
-      findings.concat(unknown_findings)
+      findings.concat(unknown_findings(explanations: with_explanations ? explanations : nil))
       findings = findings.sort_by { |item| finding_sort_key(item) }
-      {findings: findings, workers: workers}
+      result = {findings: findings, workers: workers}
+      result[:explanations] = explanations if with_explanations
+      result
     end
 
     private
 
-    def resolve(raw_calls)
-      raw_calls.sort_by { |call| [call.path, call.location.line, call.location.column, call.method,
+    def resolve(snapshot)
+      snapshot.calls.sort_by { |call| [call.path, call.location.line, call.location.column, call.method,
                                   call.arity.nil? ? Float::INFINITY : call.arity, call.unknown_reason.to_s] }.filter_map do |call|
         worker = nil
+        attributed_worker = nil
+        binding = nil
+        binding_locations = []
+        identity_reason = nil
         if call.receiver
           candidates = if call.resolution_mode == "exact_string" || call.root
                          [call.receiver]
-                       elsif call.namespace.nil?
-                         []
                        else
-                         (call.namespace.reverse.map { |prefix| "#{prefix}::#{call.receiver}" } + [call.receiver]).uniq
+                         ConstantLookup.candidates(call.receiver, false, call.namespace)
                        end
-          worker = candidates.find { |name| @names.include?(name) }
+          worker = producer_identity(snapshot, candidates, call.resolution_mode)
+          attributed_worker = worker
+          if worker && call.resolution_mode != "exact_string" && snapshot.aliases.key?(worker)
+            binding = snapshot.aliases[worker]
+            worker = binding.resolved? ? binding.target : nil if binding
+            binding_locations = snapshot.workers.fetch(binding.target).locations if binding.resolved?
+          elsif worker && alias_lookup?(candidates, call.resolution_mode) && snapshot.bindings.key?(worker) && !snapshot.workers.key?(worker)
+            binding_locations = snapshot.bindings.fetch(worker).map(&:location)
+            identity_reason = "worker_not_recognized"
+            worker = nil
+          elsif worker && call.resolution_mode != "exact_string" && !snapshot.workers.key?(worker) && (base.aliases.key?(worker) || head.aliases.key?(worker))
+            worker = nil
+          end
           client_target = %w[client_constant exact_string].include?(call.resolution_mode)
-          next unless worker || client_target || (!call.root && call.namespace.nil?)
+          next unless worker || attributed_worker || client_target || (!call.root && call.namespace.nil?)
         end
-        reason = call.unknown_reason
+        identity_reason ||= binding && !binding.resolved? ? binding.unknown_reason : nil
+        identity_reason ||= "alias_target_unresolved" if worker.nil? && attributed_worker
+        reason = identity_reason || call.unknown_reason
         reason ||= "dynamic_client_class" if call.receiver && worker.nil? && %w[client_constant exact_string].include?(call.resolution_mode)
         reason ||= call.namespace.nil? ? "unsupported_constant_path" : "dynamic_receiver" if worker.nil?
-        {worker: worker, location: call.location, arity: call.arity, reason: reason, raw: call}
+        {worker: worker, attributed_worker: attributed_worker, identity_known: !worker.nil?, identity_reason: identity_reason,
+         location: call.location, locations: [call.location] + (binding&.locations || []) + binding_locations,
+         arity: call.arity, reason: reason, raw: call}
+      end
+    end
+
+    def producer_identity(snapshot, candidates, mode)
+      if alias_lookup?(candidates, mode)
+        local = candidates.find { |name| snapshot.bindings.key?(name) || snapshot.workers.key?(name) || snapshot.aliases.key?(name) }
+        return local if local
       end
+      candidates.find { |name| @lookup_names.include?(name) }
+    end
+
+    def alias_lookup?(candidates, mode)
+      mode != "exact_string" && candidates.any? { |name| base.aliases.key?(name) || head.aliases.key?(name) }
     end
 
     def presence(snapshot, name, contract, queried)
-      return "recognized_worker" if contract
+      return snapshot.presence(name) if contract || snapshot.aliases.key?(name)
       return "not_checked" unless queried
       snapshot.index.status(name)
     end
 
+    def producer_proof(group) = group.flat_map { |call| call[:locations] }
+
+    def alias_provenance(name, *snapshots)
+      snapshots = [base, head] if snapshots.empty?
+      snapshots.filter_map do |snapshot|
+        binding = snapshot.aliases[name]
+        next unless binding
+        chain = binding.chain.join(" -> ")
+        binding.resolved? ? "Alias (#{snapshot.label.upcase}): #{chain} (resolved)." :
+          "Alias (#{snapshot.label.upcase}): #{chain.length > 1 ? chain : "unresolved"} (#{binding.unknown_reason})."
+      end
+    end
+
+    def contract_proof(contract)
+      return contract.locations if base.aliases.key?(contract.name) || head.aliases.key?(contract.name)
+      contract.locations.select { |location| location.role == "consumer" }
+    end
+
     def cell(producers, consumer, status)
       return "not_applicable" if producers.empty?
       known = producers.filter_map { |call| call[:arity] unless call[:reason] }
@@ -193,25 +272,36 @@ module Jobcompat
               ["Restore a directly recognized worker declaration, or inspect the deployment manually."], locations)
     end
 
-    def unknown_findings
+    def unknown_findings(explanations: nil)
       roots = []
       [base, head].each do |snapshot|
-        snapshot.workers.each do |name, contract|
-          next if contract.known?
+        @names.each do |name|
+          contract = snapshot.consumer(name)
+          next if !contract || contract.known?
           parts = ["consumer_contract", contract.unknown_reason, name, contract.fingerprint_parts]
           roots << {revision: snapshot.label, kind: "consumer_contract", reason: contract.unknown_reason, worker: name,
                     locations: contract.locations, parts: parts, offset: contract.locations.first&.line || 0}
         end
+        snapshot.aliases.each do |name, binding|
+          next if binding.resolved? || !@names.include?(name)
+          producer_locations = calls[snapshot.label].select { |call| call[:identity_reason] && call[:attributed_worker] == name }.flat_map { |call| call[:locations] }
+          roots << {revision: snapshot.label, kind: "consumer_alias", reason: binding.unknown_reason, worker: name,
+                    locations: binding.locations + producer_locations,
+                    parts: ["consumer_alias", binding.unknown_reason, name, binding.fingerprint_parts, binding.chain],
+                    chain: binding.chain, offset: 0}
+        end
         snapshot.unknowns.each do |item|
           roots << {revision: snapshot.label, kind: item.kind, reason: item.reason, worker: item.worker,
                     locations: item.locations, parts: [item.kind, item.reason, item.worker, item.fingerprint_parts], offset: item.locations.first&.line || 0}
         end
         calls[snapshot.label].each do |call|
           next unless call[:reason]
+          next if call[:identity_reason] && snapshot.aliases.key?(call[:attributed_worker])
           raw = call[:raw]
-          kind = %w[dynamic_receiver unsupported_constant_path safe_navigation_receiver].include?(call[:reason]) ? "producer_receiver" : "producer_arity"
-          roots << {revision: snapshot.label, kind: kind, reason: call[:reason], worker: call[:worker],
-                    locations: [call[:location]], parts: [kind, call[:reason], call[:worker], raw.fingerprint_parts],
+          kind = call[:identity_reason] || %w[dynamic_receiver unsupported_constant_path safe_navigation_receiver].include?(call[:reason]) ? "producer_receiver" : "producer_arity"
+          diagnostic_worker = call[:worker] || (call[:identity_reason] && call[:attributed_worker])
+          roots << {revision: snapshot.label, kind: kind, reason: call[:reason], worker: diagnostic_worker,
+                    locations: call[:locations], parts: [kind, call[:reason], diagnostic_worker, raw.fingerprint_parts],
                     offset: [call[:location].line, call[:location].column]}
         end
       end
@@ -227,17 +317,34 @@ module Jobcompat
           when ["producer_arity", "base"], ["producer_receiver", "base"] then ["base_to_head"]
           when ["producer_arity", "head"], ["producer_receiver", "head"] then ["head_to_base", "head_to_head"]
           when ["consumer_contract", "base"], ["worker_identity", "base"] then ["head_to_base"]
+          when ["consumer_alias", "base"] then ["head_to_base"]
+          when ["consumer_alias", "head"]
+            @calls_by_worker["head"].key?(root[:worker]) ? ["base_to_head", "head_to_head"] : ["base_to_head"]
           else ["base_to_head", "head_to_head"]
           end
         end.uniq
         if first[:kind] == "producer_arity" && first[:worker]
-          head_only_new = head.workers.key?(first[:worker]) && !base.workers.key?(first[:worker])
+          head_only_new = head.consumer(first[:worker]) && !base.consumer(first[:worker])
           directions.delete("head_to_base") if head_only_new && group.any? { |root| root[:revision] == "head" } && base.index.status(first[:worker]) == "absent"
         end
-        finding("JC007", first[:worker], group.map { |root| root[:revision] }.uniq, directions, nil, first[:reason],
-                "#{first[:reason]} prevents a complete positional compatibility check.",
-                "The affected producer or consumer contract is unknown.", ["Use supported explicit syntax or inspect this call manually."],
-                group.flat_map { |root| root[:locations] })
+        alias_reason = %w[alias_target_unresolved alias_cycle alias_binding_conflict unsupported_alias_assignment].include?(first[:reason])
+        message = alias_reason ? alias_message(first[:worker], first[:reason]) : "#{first[:reason]} prevents a complete positional compatibility check."
+        risk = alias_reason ? "Compatibility for jobs serialized as #{first[:worker]} cannot be proven from selected source." : "The affected producer or consumer contract is unknown."
+        remediation = alias_reason ? ["Use one explicit static alias if it matches runtime behavior, or inspect the deployment manually."] : ["Use supported explicit syntax or inspect this call manually."]
+        item = finding("JC007", first[:worker], group.map { |root| root[:revision] }.uniq, directions, nil, first[:reason],
+                       message, risk, remediation,
+                       group.flat_map { |root| root[:locations] })
+        explanations[item] = ExplanationBuilder.unknown_group(roots: group, message: message) if explanations
+        item
+      end
+    end
+
+    def alias_message(name, reason)
+      case reason
+      when "alias_target_unresolved" then "#{name} is bound as a compatibility alias, but its target cannot be resolved to a supported Sidekiq worker."
+      when "alias_cycle" then "Compatibility alias resolution for #{name} enters a constant-alias cycle."
+      when "alias_binding_conflict" then "#{name} has multiple or conflicting constant bindings, so its runtime job class cannot be proven."
+      when "unsupported_alias_assignment" then "#{name} is assigned through syntax or control flow that does not prove one unconditional static compatibility alias."
       end
     end