jobcompat 0.2.0 → 0.3.0

data/docs/spec-v0.2.1.md

@@ -0,0 +1,65 @@
+# jobcompat v0.2.1 normative delta specification
+
+Status: normative for `0.2.1`
+
+This document is a small delta from [`spec-v0.2.md`](spec-v0.2.md), which remains the normative `0.2.0` delta from [`spec-v0.1.md`](spec-v0.1.md). **All v0.1 and v0.2 rules remain normative unless explicitly overridden here.** v0.2.1 is a maintenance release: it adds no producer syntax, rule, finding field, uncertainty reason, or configuration key.
+
+## 1. Versioned contracts
+
+- Gem and CLI version: `0.2.1`.
+- JSON `schema_version`: `2` (unchanged).
+- `.jobcompat.yml` version: `1` (unchanged; `version: 2` remains a config error).
+
+No user migration is required.
+
+## 2. Canonical worker-name validation
+
+A canonical String worker name is a String that:
+
+1. converts safely to valid UTF-8;
+2. parses with the supported Prism (`>= 1.9, < 2`) without diagnostics;
+3. contains exactly one expression;
+4. is a static `ConstantReadNode` or `ConstantPathNode` chain, not root-qualified with a leading `::`;
+5. when flattened and joined with `::`, equals the complete String exactly.
+
+Prism is the only grammar authority; jobcompat defines no handwritten identifier, case, combining-mark, or Unicode-range rules. Input is never trimmed. Whitespace, comments, newlines, parentheses, calls, operators, extra statements, `self::`, and any other syntax make the String non-canonical.
+
+One internal validator applies this definition to both Client class Strings (`Sidekiq::Client.push` / `push_bulk`) and `.jobcompat.yml` `ignore[].worker`.
+
+**Invariant:** any worker name accepted as an exact canonical String worker name by producer analysis MUST also be valid as `.jobcompat.yml` `ignore[].worker`, subject to the same canonical textual identity rules. Conversely, a configured worker name that producer analysis could not accept as a canonical String is invalid configuration.
+
+Constant AST resolution (for example `"class" => ExportJob`, `ExportJob.perform_async`, and worker declarations) is unchanged and is not governed by this section.
+
+## 3. Suppression semantics
+
+Matching remains exact on `rule_id` plus the worker String. There is no Unicode normalization (no NFC, NFD, NFKC, or NFKD), case folding, namespace inference, partial, glob, or regex matching. Configured names are stored and reported exactly as written.
+
+Visually similar but codepoint-distinct valid names remain different worker identities. For example, `ÁJob` written as `U+00C1 J o b` and as `U+0041 U+0301 J o b` are distinct: a suppression for one does not suppress a finding for the other, and the two entries are not duplicates of each other. Two entries with the same rule and exactly the same worker String remain a duplicate-entry config error.
+
+A qualified name such as `Admin::ÁJob` suppresses only the finding whose worker is exactly that qualified name; `ÁJob` alone does not match it.
+
+A matched suppression keeps the existing audit record (`rule_id`, exact `worker`, `reason`, `finding_count`) in JSON and text output, and a suppressed compatibility ERROR no longer contributes to exit 1.
+
+## 4. Invalid worker-name behavior
+
+The shared validator only decides validity. Each caller owns its failure surface:
+
+- **Config:** a non-canonical, non-String, or invalid-encoding `ignore[].worker` is a `config_error` with the existing message `ignore[N].worker is invalid`, JSON `status: "failed"`, and exit 2. A document whose bytes Psych rejects before validation is also a `config_error` with exit 2. No raw `ArgumentError` or `EncodingError`, `internal_error`, or stack trace is produced.
+- **Producer analysis:** a non-canonical or invalid-encoding Client class String remains `unsupported_client_payload` JC007 evidence, as in v0.2.0.
+
+Inside the validator only expected encoding failures are treated as unsupported input; unexpected parser or implementation failures stay visible as tool failures.
+
+Compatibility note: v0.2.0 also accepted some configured names that Ruby does not parse as constants, such as `管理::輸出` (segments that do not start with an uppercase letter). No finding could ever carry such a worker name, so those entries never suppressed anything; v0.2.1 reports them as `config_error`.
+
+## 5. Compatibility invariants
+
+- JC001–JC007 semantics, severities, and precedence are unchanged; there is no JC008.
+- Exit codes are unchanged: 0 no unsuppressed compatibility ERROR, 1 compatibility ERROR, 2 tool/config/Git/parser/usage failure.
+- JSON schema 2 structure and `unknown_reason` vocabulary are unchanged.
+- Runtime dependencies remain `prism >= 1.9, < 2`; Ruby `>= 3.3`.
+- Validation parses text only: no eval, `const_get`, constantize, application `require`, Rails or Sidekiq boot, Redis, source execution, or analysis-time network.
+- Output remains byte-deterministic, including exact Unicode codepoints.
+
+## 6. Non-goals
+
+New Sidekiq producer APIs, SARIF, ActiveJob, keyword compatibility, payload type or Hash schema checking, Redis inspection, wrapper tracking, aliases, inheritance analysis, general dataflow, feature-flag analysis, new suppression syntax, wildcard suppressions, and regex suppressions.

data/docs/spec-v0.3.md

@@ -0,0 +1,238 @@
+# jobcompat v0.3.0 delta specification
+
+Status: normative for 0.3.0. This document extends `spec-v0.2.1.md`,
+which retains the v0.2 and v0.1 contracts except where overridden here.
+MUST and MUST NOT state requirements. No application Ruby is executed.
+
+## Versioned and frozen contracts
+
+Gem and CLI version: 0.3.0. Completed and failed JSON envelopes MUST use
+`schema_version: 3`. Configuration version remains exactly 1; version 2 is
+invalid. Ruby >= 3.3 and Prism >= 1.9, < 2 remain unchanged. No dependency
+on Sidekiq is introduced. JC001-JC007 IDs, severities (JC001-JC005 ERROR,
+JC006-JC007 WARNING), exit policy, suppression identity, and deployment
+directions remain unchanged. ERROR requires provable structural
+incompatibility. Unknown and unsupported evidence never establishes
+compatibility; missing producers never establishes an empty queue.
+Analysis reads committed Git objects and ignores working-tree edits.
+
+## Terminology and serialization
+
+**Serialized worker identity** is the exact String in a Sidekiq payload's
+`"class"` field. All compatibility comparisons use that identity.
+**Direct worker** is a canonical class recognized through the existing
+direct `Sidekiq::Job` or legacy `Sidekiq::Worker` include and reopened-class
+discovery. **Compatibility alias** is a statically provable constant
+binding to another constant whose graph terminates in one recognized
+direct worker in the same revision. **Alias terminal** is that final
+direct worker after zero or more supported edges.
+**Class-object producer** passes a Ruby Class object (worker APIs,
+Setter APIs, or Client constant payloads). **Exact-string producer** passes
+an already serialized identity through Client push or push_bulk.
+
+For `OldJob = NewJob`, Ruby retains the Class object's canonical name
+`NewJob`. Class-object producers through OldJob MUST therefore normalize
+to NewJob. This applies to perform_async, perform_in, perform_at,
+perform_bulk, all four `.set(...)` forms, and Client push/push_bulk with a
+constant. A Client `"class" => "OldJob"` MUST retain exactly OldJob on the
+producer side; consumer lookup MAY resolve OldJob through its alias.
+There is no namespace prefixing or Unicode normalization of exact Strings.
+
+The model freezes Sidekiq's Class-to-String normalization as observed in
+[Sidekiq 8.1.6 JobUtil](https://github.com/sidekiq/sidekiq/blob/v8.1.6/lib/sidekiq/job_util.rb#L38-L55)
+and its [Class-object producer path](https://github.com/sidekiq/sidekiq/blob/v8.1.6/lib/sidekiq/job.rb#L191-L196).
+The [official rename FAQ](https://github.com/sidekiq/sidekiq/wiki/FAQ#how-do-i-safely-rename-a-worker)
+describes a compatibility alias for retained old payloads. Client Strings
+have different job-option/default semantics; their identity behavior is
+documented here without recommending them as a migration strategy.
+
+## Supported syntax and namespace semantics
+
+Only Prism ConstantWriteNode and ConstantPathWriteNode with plain `=`
+and a ConstantReadNode or static ConstantPathNode RHS after safe
+single-expression parentheses unwrapping prove an alias. The assignment
+MUST be a direct unconditional statement in the Program body or a valid
+Class/Module body, with all enclosing contexts supported.
+
+Supported examples are `OldJob = NewJob`, `OldJob = (NewJob)`,
+`::OldJob = ::NewJob`, top-level `Admin::OldJob = Admin::NewJob`, and
+`module Admin; OldJob = NewJob; end`. Existing declaration rules determine
+the LHS canonical name. An unrooted qualified LHS in lexical nesting or
+an unsupported namespace MUST NOT prove an alias. An unrooted qualified
+RHS inside lexical nesting is unsupported_alias_assignment. Rooted RHS
+references and qualified top-level RHS references are exact.
+
+Unqualified RHS lookup uses the existing lexical namespace stack in
+reverse order, then the root name. For nested Admin/Jobs, NewJob candidates
+are Admin::Jobs::NewJob, Admin::NewJob, NewJob. The first selected-source
+binding wins lookup; a binding with an unknown value MUST block fallback
+to a farther known worker. No inherited-constant lookup is added.
+
+Assignments below if/unless/case/loops/blocks/lambdas/begin/rescue/ensure,
+modifier conditions, singleton classes, methods, or expression wrappers
+are unsupported. Even an unconditional begin wrapper is unsupported.
+Or/and/operator writes, multiple assignment targets, dynamic RHS,
+ternary RHS, calls, and Class.new MUST NOT become resolved aliases.
+Named unsupported writes enter the inventory so relevant identities can
+warn and conflicts cannot be hidden. const_set/autoload/const_missing
+remain outside alias discovery.
+
+## Selected binding inventory and graph
+
+During the existing Prism traversal, record selected-source class/module
+declarations and named writes, plus alias candidates. Presence facts in
+DefinedConstantIndex MUST remain separate from alias graph facts.
+Exactly one supported alias binding and no other binding to its LHS is
+required. Duplicate aliases, even identical ones, alias plus class/module,
+or alias plus unsupported writes produce alias_binding_conflict. No
+source-order winner is selected. Existing reopened direct class fragments
+are allowed and merged as before; they are not conflicts by themselves.
+An alias that reaches a conflicting binding MUST remain unknown.
+Selected ambiguous constant paths also retain leaf-name conflict evidence:
+an assignment or declaration such as `self::OldJob = OtherJob` cannot be
+ignored when its leaf may affect an alias or a reached terminal. These
+facts conservatively block resolution without evaluating the receiver.
+Excluded or differently named ambiguous facts do not enter this proof.
+
+Each revision resolves its own graph independently. Finite chains have
+no arbitrary length cap. Iterative traversal detects cycles without
+recursive stack overflow. Resolved chain order follows edges, for example
+`[OldJob, MiddleJob, NewJob]`. A cycle chain closes with its repeated
+identity, for example `[OldJob, MiddleJob, OldJob]`. A missing or
+unrecognized terminal is alias_target_unresolved. Failed suffixes
+propagate their reason and proof to aliases depending on them.
+
+Only selected files supply trusted edges. Excluded declarations/writes
+may block absence through the presence pass, but MUST NOT resolve aliases.
+An excluded OldJob alias yields outside_analysis_scope for a removal
+transition; a selected alias targeting an excluded worker yields
+alias_target_unresolved. File movement alone does not alter identity
+compatibility. All keys preserve Prism's exact UTF-8 codepoints.
+
+## Effective consumers and relevant identities
+
+Snapshot workers remain directly recognized workers. An effective
+consumer map resolves serialized identity S to either direct worker S or
+the terminal contract of supported alias S. A conflicting alias masks an
+otherwise recognized direct consumer at the same identity. Resolved
+aliases retain resolution status even when the terminal signature is
+unknown (keyword_parameters, missing_perform, multiple_perform_definitions).
+Effective alias contracts carry every edge location and the terminal's
+declaration/include/perform proof. No new location role is introduced.
+
+Comparison identities MUST include all direct workers in either revision,
+all resolved BASE aliases (historical queues may retain their names),
+aliases present in both revisions, aliases matching an opposite direct
+worker, and aliases referenced by visible producers or needed to explain
+unknown producer identity. A dormant HEAD-only alias is not automatically
+a worker result or standalone warning. The full graph may still be built.
+The common-alias criterion refers to constant-to-constant candidates,
+including unsupported static forms; unrelated dynamic/literal writes such
+as VERSION = "1" do not become relevant merely by existing in both
+revisions. They still block conflicting bindings and are diagnosed when
+referenced by a producer or matched to an opposite worker identity.
+
+## Producer resolution
+
+Class-object resolution first performs existing lexical/root lookup in
+the producer's own snapshot, including alias bindings. A resolved alias
+normalizes to its terminal direct identity. An unknown alias MUST NOT
+guess its syntactic name as a serialized identity. Such a call retains a
+separate attributed alias name for diagnostics and comparison relevance,
+but cannot drive JC005. Existing cross-revision non-alias attribution
+remains available only when no local alias/binding narrows that proof.
+When alias lookup applies, a nearer selected non-worker class/module
+binding stops fallback and leaves producer identity unknown. Opposite
+revision names cannot override a selected local binding. Normalized
+Class-object alias producers retain edge and terminal declaration,
+include, and perform locations; unresolved targets retain any selected
+declaration that prevents recognition.
+
+Exact-string resolution remains exact and does not canonicalize aliases.
+Producer identity certainty and arity certainty MUST be distinct:
+resolved alias plus `*args` retains the terminal identity and splat_arguments;
+unknown alias plus literal args retains unknown identity. Known identity
+with unknown arity can still drive JC005. Existing Hash source-order,
+dynamic-key, bulk-row, lexical producer, and Client String rules persist.
+
+## Rules, unknown reasons, and proof
+
+JC001: old serialized payload accepted by BASE but rejected by HEAD,
+including alias consumers. JC002: HEAD accepted payload rejected by BASE,
+under its serialized identity. JC003: HEAD producer/consumer mismatch.
+JC001 owns a repeated HEAD mismatch at the same identity/arity before
+JC003. JC001 OldJob and JC003 NewJob from a Class alias producer remain
+distinct findings. JC006 narrowing/witness precedence remains unchanged.
+
+JC004 requires absence of a BASE effective serialized identity in HEAD.
+A resolved alias blocks removal; a relevant unknown alias warns rather
+than passing or proving absence. Removing a BASE resolved alias can cause
+JC004 even if its terminal still exists. JC005 requires HEAD known
+serialized producer identity with an effective HEAD consumer and proven
+BASE absence, conditional on old processes consuming that queue. An
+exact-string alias producer can cause JC005 for the alias; a Class-object
+alias producer can cause JC005 only for the terminal. BASE resolved aliases
+block absence; unresolved aliases warn. Existing presence budget/error
+behavior and conservative absence proof remain frozen.
+
+JC007 adds exactly four reasons: alias_target_unresolved (supported edge
+does not reach a recognized worker), alias_cycle, alias_binding_conflict,
+and unsupported_alias_assignment. Existing contract/arity reasons retain
+their meanings. Alias warning messages describe the unresolved binding
+and risk to the persisted identity; remediation suggests an explicit
+static alias only if it matches runtime behavior, or manual inspection.
+
+BASE alias uncertainty affects head_to_base. HEAD alias uncertainty affects
+base_to_head and additionally head_to_head only with a HEAD producer for
+that same serialized identity. A Class call normalizing to another name
+does not manufacture head_to_head for its source alias. Alias evidence
+fingerprints contain reason, exact identity, lexical scope, normalized
+assignment/enclosing tokens, target reference, and structural chain, but
+exclude revision, paths, lines, and columns. Stable binding/occurrence
+ordering preserves distinct evidence and cross-revision aggregation.
+
+## JSON schema 3 and determinism
+
+workers[] now represents compared serialized identities, sorted by exact
+name. Every result has base_alias and head_alias, null for a direct or
+absent binding, otherwise an object with exactly status, target, chain,
+unknown_reason. Resolved status has terminal target and null reason;
+unknown status has null target and its alias reason. Conflict or unsupported
+assignment chains start with the alias alone; unresolved target chains
+include the missing target, and cycle chains close the cycle.
+
+Presence values are recognized_worker, resolved_alias,
+defined_unrecognized, outside_scan_scope, absent, unverified, not_checked.
+Unknown aliases use defined_unrecognized even in a direct binding conflict.
+Effective contracts appear in base_contract/head_contract for resolved
+aliases; unresolved aliases have null contracts. Producer arities and
+matrix statuses use known serialized identity and effective consumers.
+summary.workers continues to count direct worker facts only, never aliases.
+Suppressions match the finding's exact serialized worker identity.
+
+Inputs and graph processing use stable sorting. Chains follow structural
+edge order. Repeated text/JSON for identical refs/config/toolchain MUST be
+byte-identical, including cycles, conflicts, and Unicode names.
+
+## Boundaries and acceptance
+
+Recognition assumes normal successful application boot, as direct worker
+recognition already does; it does not prove file load order or Zeitwerk
+behavior. No general constant evaluator/dataflow, inheritance/concerns,
+source execution, Rails/Sidekiq boot, Redis/network access, keyword
+compatibility, value/Hash schema analysis, ActiveJob, Client instances,
+wrappers, queue/feature-flag simulation, manual alias config, heuristic
+rename detection, JC008, SARIF, --explain, or coverage report is added.
+
+Acceptance requires supported AST/context and namespace tests, finite and
+cross-file graph tests, cycles/conflicts/unknown terminals, reopened and
+unknown-contract targets, all Class-object and exact-string producer
+families, separate identity/arity uncertainty, every JC rule and precedence,
+staged rename and alias removal, excluded-source presence proof, exact
+Unicode/suppression behavior, schema 3 (success and failure), unchanged
+config version 1, deterministic output, existing regressions, source
+non-execution/worktree/index immutability, offline tests, gem packaging,
+isolated CLI install/scenarios, and full validation in UTF-8 locale.
+Locally unavailable Ruby 3.3/4.0 matrix entries remain official CI work.
+The implementation phase MUST leave an uncommitted candidate and MUST NOT
+commit, push, tag, release, publish, or alter historical v0.2.1 artifacts.

data/lib/jobcompat/aliases.rb

@@ -0,0 +1,86 @@
+module Jobcompat
+  ConstantBinding = Data.define(:name, :kind, :location, :fingerprint_parts)
+  AliasCandidate = Data.define(:name, :reference, :root, :namespace, :supported, :location, :fingerprint_parts)
+  AliasResolution = Data.define(:name, :status, :target, :chain, :unknown_reason, :locations, :fingerprint_parts, :static_reference) do
+    def resolved? = status == "resolved"
+    def as_json
+      {status: status, target: target, chain: chain, unknown_reason: unknown_reason}
+    end
+  end
+
+  module ConstantLookup
+    def self.candidates(reference, root, namespace)
+      return [reference] if root
+      return [] if namespace.nil?
+      (namespace.reverse.map { |prefix| "#{prefix}::#{reference}" } + [reference]).uniq
+    end
+  end
+
+  class AliasResolver
+    def initialize(workers, bindings, candidates, ambiguous_bindings = [])
+      @workers = workers
+      @bindings = bindings.group_by(&:name)
+      @candidates = candidates.group_by(&:name)
+      @ambiguous_bindings = ambiguous_bindings.group_by(&:name)
+    end
+
+    def resolve
+      @candidates.keys.sort.to_h { |name| [name, resolve_identity(name)] }.freeze
+    end
+
+    private
+
+    def resolve_identity(name)
+      chain, locations, parts, visited = [], [], [], {}
+      current = name
+      reason = nil
+      loop do
+        chain << current
+        if visited[current]
+          reason = "alias_cycle"
+          break
+        end
+        visited[current] = true
+        candidates = @candidates.fetch(current, [])
+        bindings = @bindings.fetch(current, []).sort_by { |item| [item.location.path, item.location.line, item.location.column] }
+        ambiguous = @ambiguous_bindings.fetch(current.split("::").last, []).reject { |item| bindings.any? { |binding| binding.location == item.location } }
+        if candidates.empty? && @workers.key?(current) && ambiguous.empty?
+          return resolution(name, current, chain, nil, locations, parts)
+        end
+        locations.concat((bindings + ambiguous).map(&:location))
+        parts << [current, (bindings + ambiguous).map(&:fingerprint_parts).sort_by(&:inspect)]
+        unless ambiguous.empty?
+          reason = "alias_binding_conflict"
+          break
+        end
+        if candidates.empty?
+          reason = "alias_target_unresolved"
+          break
+        end
+        if bindings.length != 1
+          reason = "alias_binding_conflict"
+          break
+        end
+        candidate = candidates.first
+        unless candidate.supported
+          reason = "unsupported_alias_assignment"
+          break
+        end
+        lookup = ConstantLookup.candidates(candidate.reference, candidate.root, candidate.namespace)
+        target = lookup.find { |identity| @bindings.key?(identity) || @workers.key?(identity) }
+        unless target
+          chain << lookup.first
+          reason = "alias_target_unresolved"
+          break
+        end
+        current = target
+      end
+      resolution(name, nil, chain, reason, locations, parts)
+    end
+
+    def resolution(name, target, chain, reason, locations, parts)
+      AliasResolution.new(name, reason ? "unknown" : "resolved", target, chain.freeze, reason,
+                          locations.uniq.freeze, parts.freeze, @candidates.fetch(name).any? { |candidate| candidate.reference })
+    end
+  end
+end

data/lib/jobcompat/analysis.rb

@@ -1,4 +1,6 @@
 require "prism"
+require_relative "canonical_worker_name"
+require_relative "aliases"
 
 module Jobcompat
   Location = Data.define(:revision, :path, :line, :column, :role, :excerpt) do
@@ -55,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 = []
@@ -104,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
@@ -121,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
 
@@ -155,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 : []
@@ -184,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
 
@@ -213,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
@@ -227,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)
@@ -387,28 +438,13 @@ module Jobcompat
       constant = self.class.constant(node)
       return [constant.first.join("::"), "client_constant", constant.last, nil] if constant
       if node.is_a?(Prism::StringNode)
-        name = canonical_client_string_worker_name(node.unescaped)
+        name = CanonicalWorkerName.parse(node.unescaped)
         return [name, "exact_string", false, nil] if name
         return [nil, nil, nil, "unsupported_client_payload"]
       end
       [nil, nil, nil, "dynamic_client_class"]
     end
 
-    def canonical_client_string_worker_name(value)
-      name = value.encode(Encoding::UTF_8)
-      return unless name.valid_encoding?
-      result = Prism.parse(name)
-      return unless result.errors.empty? && result.value.statements.body.one?
-      node = result.value.statements.body.first
-      return unless node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
-      constant = self.class.constant(node)
-      return unless constant && !constant.last
-      canonical_name = constant.first.join("::")
-      canonical_name if canonical_name == name
-    rescue EncodingError
-      nil
-    end
-
     def emit_call(node, namespace, scope, statement, method, receiver, resolution_mode, root, arity, reason)
       expression = self.class.normalize(node.location.slice)
       enclosing = self.class.normalize((statement || node).location.slice)
@@ -435,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
@@ -443,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
@@ -484,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/canonical_worker_name.rb

@@ -0,0 +1,35 @@
+require "prism"
+
+module Jobcompat
+  # Internal: the single authority for canonical String worker names, shared by
+  # producer analysis (Client String "class" values) and Config (ignore[].worker).
+  # Prism decides what a Ruby constant path is; no handwritten identifier grammar.
+  module CanonicalWorkerName
+    # Returns the canonical UTF-8 name when value is exactly one complete,
+    # non-root-qualified static constant path, or nil otherwise. The input is
+    # never trimmed or Unicode-normalized.
+    def self.parse(value)
+      return unless value.is_a?(String)
+      name = value.encode(Encoding::UTF_8)
+      return unless name.valid_encoding?
+      result = Prism.parse(name)
+      return unless result.errors.empty? && result.value.statements.body.one?
+      segments = segments(result.value.statements.body.first)
+      return unless segments
+      canonical = segments.join("::")
+      canonical if canonical == name
+    rescue EncodingError
+      nil
+    end
+
+    def self.segments(node)
+      case node
+      when Prism::ConstantReadNode then [node.name.to_s.encode(Encoding::UTF_8)]
+      when Prism::ConstantPathNode
+        parent = node.parent && segments(node.parent)
+        parent && parent + [node.name.to_s.encode(Encoding::UTF_8)]
+      end
+    end
+    private_class_method :segments
+  end
+end