Project

jobcompat

0.0
The project is in a healthy, maintained state
Static analysis of native Sidekiq positional arity across Git revisions and rolling deployments.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

>= 1.9, < 2
 Project Readme

jobcompat

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?

Problem

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.

Why this happens

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.

Installation

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.

Quick Start

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 --explain

Both 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.

Example output

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.

How it works

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.

Compatibility directions

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.

Rules

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.

Configuration and targeted suppression

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.

CI usage

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.

Supported Sidekiq patterns

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, ...), and Job.perform_bulk(...);
  • Job.set(...).perform_async(...), .perform_in(...), .perform_at(...), and .perform_bulk(...);
  • Sidekiq::Client.push(...) and Sidekiq::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.

Worker rename and static compatibility aliases

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 = MyNewJob

Old 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.

Limitations and non-goals

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.

Why not just tests, Sorbet, or Sidekiq strict arguments?

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.

Deployment assumptions and staged migration

For a new argument, first deploy a worker that accepts it optionally, without producing it:

def perform(user_id, format = nil)
end

After 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.

Security and offline-friendly characteristics

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.

Roadmap

Possible future work includes SARIF output and additional evidence sources. Other frameworks are not supported now.

Contributing

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.

License

MIT. See LICENSE.