Catch Sidekiq job argument changes that break queued jobs before deploy.
-def perform(user_id)
+def perform(user_id, format)ERROR JC001 ExportJob
Base emits 1 argument, but the HEAD worker accepts 2.
Risk: Jobs queued by the base revision may fail after deployment.
No schemas. No annotations. No committed snapshots. No Redis connection. No Rails boot. jobcompat compares existing Ruby source across Git commits.
Your API has a schema. Your database has migrations. What protects your queued jobs?
A Sidekiq producer can enqueue arguments today that a different worker version executes later. Changing perform can break jobs retained in queues, retry sets, or scheduled sets, and a rolling deploy can run old and new processes together.
Sidekiq persists a worker class and an args array. The worker receives those positional arguments through perform(*args). A source change to the method's accepted arity can make a previously valid array invalid.
Ruby 3.3 or newer is required. Install with gem install jobcompat, or add gem "jobcompat", require: false to your Gemfile, run bundle install, and use bundle exec jobcompat. prism is the only runtime dependency; jobcompat does not require the Sidekiq gem to inspect source.
From a Git repository containing native Sidekiq jobs:
jobcompat check --base origin/main
jobcompat check --base v0.1.0 --head HEAD --format json
jobcompat check --base origin/main --explainBoth refs resolve to commits. Staged and uncommitted changes are ignored. The command never checks out another revision or changes the working tree.
--explain appends an Explanation section—evidence, decision, and boundary—to each remaining finding in text output. It shows why a rule fired from the static evidence jobcompat already collected: it runs no additional compatibility checks, cannot be combined with --format json (exit 2 config error), reports only static source evidence, and never turns an unknown result into a safety claim.
For a base one-argument producer and a HEAD worker that requires two arguments, text output includes:
ERROR JC001 ExportJob
Base emits 1 argument, but the HEAD worker accepts 2.
Revisions: base, head
Affected directions:
base producer -> HEAD consumer
HEAD producer -> HEAD consumer
Risk: Jobs queued by the base revision may fail after deployment.
The second direction appears only when HEAD also has a one-argument producer. Output includes source locations, suggested migration steps, resolved commit SHAs, and a summary. JSON output uses schema_version: 3 and includes per-serialized-identity compatibility matrices and alias provenance.
jobcompat reads committed Ruby blobs through Git, parses each selected file with Prism, groups reopened class fragments by canonical name, normalizes supported Sidekiq producer syntax into worker/arity facts, then compares positional-arity intervals. Application code is never loaded or executed.
Its separate DefinedConstantIndex checks tracked Ruby class declarations and named bindings before declaring a worker class absent. A class that remains in an excluded file or stops using a direct Sidekiq include produces a warning rather than a removal error.
| Direction | Question |
|---|---|
base_to_head |
Can the new worker execute a payload produced by the base revision? |
head_to_base |
Can an old worker execute a payload enqueued by a new application node? |
head_to_head |
Does HEAD's own producer match its worker? |
The model assumes rolling deployment with old and new processes potentially overlapping. A discovered callsite is treated as potentially reachable; jobcompat does not evaluate feature flags or deployment sequencing.
| Rule | Severity | Meaning |
|---|---|---|
| JC001 | ERROR | Base payload accepted by base worker is rejected by HEAD worker |
| JC002 | ERROR | HEAD payload accepted by HEAD worker is rejected by base worker |
| JC003 | ERROR | HEAD producer and HEAD worker disagree |
| JC004 | ERROR | Base worker class is proven absent from HEAD tracked Ruby source |
| JC005 | ERROR | HEAD enqueues a new worker whose class is proven absent from base source |
| JC006 | WARNING | Contract narrowed without a qualifying producer witness |
| JC007 | WARNING | Visible evidence is unsupported or cannot prove compatibility |
One JC001 can cover both base_to_head and head_to_head; the same mismatch is not repeated as JC003. The same unsupported source evidence in both revisions is one JC007 finding.
Create .jobcompat.yml at the Git root when defaults are insufficient:
version: 1
scan:
include:
- "**/*.rb"
exclude:
- "vendor/**"
- "tmp/**"
- "log/**"
- "coverage/**"
- ".bundle/**"
- "test/**"
- "spec/**"
- "features/**"
- "examples/**"
ignore:
- rule: JC005
worker: ExperimentalJob
reason: "Enqueue starts after deployment completes"Each configured include or exclude list replaces its default list, so copy the defaults you still want. --config PATH selects another YAML file; a relative path is resolved from the invocation directory. Unknown keys and unsafe YAML aliases fail with exit 2. An ignore entry must have an exact rule, canonical worker name, and non-blank reason. ignore[].worker uses the same canonical Ruby constant-name rules as exact Client String worker targets, including valid Unicode identifiers; matching is exact and not Unicode-normalized. Matched suppressions appear in text and JSON audit output.
Run jobcompat check --base origin/main --format json after fetching the comparison ref in CI. Exit 0 means no unsuppressed compatibility errors (warnings may exist), exit 1 means one or more errors, and exit 2 means the analysis could not complete because of CLI, config, Git, parse, or tool failure. A warning never becomes a pass claim for the affected evidence.
Direct include Sidekiq::Job and legacy include Sidekiq::Worker are recognized in top-level and supported namespaced classes. Reopened fragments may split the include and perform across files. Supported producer APIs are:
Job.perform_async(...),Job.perform_in(schedule, ...),Job.perform_at(time, ...), andJob.perform_bulk(...);Job.set(...).perform_async(...),.perform_in(...),.perform_at(...), and.perform_bulk(...);Sidekiq::Client.push(...)andSidekiq::Client.push_bulk(...)with a static Hash payload using string"class"and"args"keys.
Client Hash entries are resolved per key in source order. A later explicit "class" or "args" overrides earlier writes; a later unknown Hash splat or dynamic key makes only the keys it may replace uncertain. Static unrelated keys do not affect certainty. A statically known worker is preserved when only args may be replaced; an uncertain class is not attributed to an earlier worker and cannot produce JC005 for it.
Hash and Array expressions each count as one ordinary payload argument. Bulk calls produce one fact per distinct statically known inner Array arity:
ExportJob.perform_bulk([
[1],
[2, "csv"]
])jobcompat sees payload arities 1 and 2. A dynamic bulk row is retained as dynamic_bulk_arguments uncertainty without discarding known rows from the same callsite. A Client class String is an exact canonical Ruby constant name; it is never resolved relative to the surrounding Ruby namespace or Unicode-normalized. Malformed names produce JC007 warnings.
Positional perform parameters may be required, optional, rest, post-rest, or forwarding. Keyword parameters make the worker contract unknown in v0.2.
jobcompat recognizes plain static constant aliases to directly recognized jobs, including finite chains and supported namespaces:
class MyNewJob
include Sidekiq::Job
def perform(id); end
end
MyOldJob = MyNewJobOld queued "MyOldJob" payloads can resolve through the alias to the new worker contract, so this rename does not produce JC004. Arity incompatibilities still produce the normal findings under the persisted name.
MyOldJob.perform_async(1) uses the aliased Class object: Sidekiq serializes its canonical name MyNewJob, not the source alias token. This also applies to scheduling, bulk, Setter calls, and Client constant payloads. During a rolling deployment, activating that producer can still cause JC005 MyNewJob if old processes cannot resolve the new identity. A compatibility alias alone does not make immediate new-name producer activation safe.
By contrast, an explicit Client String keeps its exact identity:
Sidekiq::Client.push("class" => "MyOldJob", "args" => [1])jobcompat models that producer as MyOldJob, then follows the alias on the consumer side. This describes identity behavior; Client Strings also have different job-option/default semantics.
Only unconditional plain constant assignments are trusted. Cycles, conflicting or repeated bindings, dynamic assignments, and conditional aliases warn when relevant. Excluded aliases can block an absence proof but are not trusted as compatibility paths. There is no const_set/autoload/const_missing support, conditional alias proof, runtime load-order proof, or heuristic rename detection. Recognition assumes successful application boot, just as direct worker recognition does.
jobcompat checks positional arity only. It does not check value types, Hash internals, keyword compatibility, or JSON serialization. It supports native Sidekiq, not ActiveJob. Dynamic bulk collections are warning/unknown, Client payload variables are not followed, and custom wrappers are not analyzed. ActiveJob, arbitrary Client instances, Hash internal schemas, general Ruby aliases beyond the static subset above, inheritance, concerns, arbitrary metaprogramming, feature flags, and general Ruby class/module or superclass conflict analysis remain outside scope.
No repository producer callsite does not prove an empty queue: queued, scheduled, retried, historical, and external jobs may exist. JC004 requires a completed static absence proof across tracked .rb source. An excluded or unrecognized declaration warns. JC005 is a structural rolling-deploy error conditional on an old Sidekiq process being able to consume the new job's queue. Queue isolation and feature flags are not analyzed. Dynamic source may warn or be missed. Working-tree edits are ignored.
Tests usually run one revision at a time. Sorbet and Sidekiq's strict argument checking address different contracts, such as types or JSON-safe values. jobcompat checks source-derived positional arity across committed revisions and rolling deployment directions. It complements those tools.
For a new argument, first deploy a worker that accepts it optionally, without producing it:
def perform(user_id, format = nil)
endAfter old workers have left the fleet, begin enqueueing format. Make the argument required only after jobs with the old shape can no longer be retained or retried. If an external rollout gate makes a reported risk impossible, use a targeted suppression with its reason.
Analysis reads local Git objects only. It does not connect to Redis, boot Rails, load application code, invoke Git hooks, or upload source. Git commands use argv arguments and resolved immutable commit SHAs. It needs no network once Ruby dependencies and Git objects are available.
Possible future work includes SARIF output and additional evidence sources. Other frameworks are not supported now.
Run bundle exec rake test and gem build jobcompat.gemspec with Ruby 3.3 or newer. Tests create temporary Git repositories and need no Redis or Sidekiq server. The v0.1 specification remains the baseline; the normative v0.2 delta defines the added producer coverage, the v0.2.1 delta defines shared canonical worker-name validation, and the v0.3 delta defines static compatibility aliases and serialized identity resolution.
MIT. See LICENSE.