jobcompat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c7ba60ac1a983ea795999572de4a8e670986f6b8ed6d5a05433f21a81ca8d03
+  data.tar.gz: ba82835508ec2d1e056eeb71a94ec51af5cf5696aa53046b6912c50281640221
+SHA512:
+  metadata.gz: bc94f38e9c059633c5701bc11982298f0d4786b8b58ff11494b0233a6de9f8f5a11e7e3e05ddae563a16773094be3ff410eff881e319cd3b1d8d8a0b336518a1
+  data.tar.gz: bb16e4959a69dde9a1aac0fbaff894aa3291009d538927a83a721d7a64bfee67ef804a978d5044ed7c4f7ed8fda66aa09b4a7a8caccf2da1bb1b25a44a5c89c3

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-09-26
+
+- Extract positional `perform` contracts from native `Sidekiq::Job` and `Sidekiq::Worker` classes, including reopened classes.
+- Discover direct Sidekiq enqueue calls and compare Git base and head snapshots in all three rolling deployment directions.
+- Report JC001–JC007 in text or JSON schema version 1, with targeted `.jobcompat.yml` suppression.
+- Check tracked Ruby declarations through a separate `DefinedConstantIndex` before reporting class removal.
+- Provide a Prism based static CLI and RubyGem for Ruby 3.3 or newer without booting Rails or connecting to Redis.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jobcompat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# jobcompat
+
+Catch Sidekiq job argument changes that break queued jobs before deploy.
+
+```diff
+-def perform(user_id)
++def perform(user_id, format)
+```
+
+```text
+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. After release, 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:
+
+```sh
+jobcompat check --base origin/main
+jobcompat check --base v0.1.0 --head HEAD --format json
+```
+
+Both refs resolve to commits. Staged and uncommitted changes are ignored. The command never checks out another revision or changes the working tree.
+
+## Example output
+
+For a base one-argument producer and a HEAD worker that requires two arguments, text output includes:
+
+```text
+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: 1` and includes per-worker compatibility matrices.
+
+## How it works
+
+jobcompat reads committed Ruby blobs through Git, parses each selected file with Prism, groups reopened class fragments by canonical name, discovers direct Sidekiq includes and enqueue calls, 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:
+
+```yaml
+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. 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. The producer forms are `Job.perform_async(...)`, `Job.perform_in(schedule, ...)`, `Job.perform_at(time, ...)`, and `Job.set(...).perform_async(...)`. Hash and Array expressions each count as one payload argument. A splat or forwarded producer argument makes arity unknown.
+
+Positional `perform` parameters may be required, optional, rest, post-rest, or forwarding. Keyword parameters make the worker contract unknown for v0.1.
+
+## Limitations and v0.1 non-goals
+
+v0.1 checks **positional arity only**. It does not check value types, Hash internals, keyword compatibility, or JSON serialization. It supports native Sidekiq, not ActiveJob. Only direct includes and the documented direct producer calls are analyzed. `Sidekiq::Client.push`, bulk APIs, wrappers, aliases, inheritance, concerns, arbitrary metaprogramming, feature flags, and general Ruby class/module or superclass conflict analysis are 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:
+
+```ruby
+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 additional native Sidekiq producer APIs and SARIF output. Other frameworks would be considered only after v0.1 usage evidence; they 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. See [the normative v0.1 spec](docs/spec-v0.1.md) before changing rule behavior.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+If you find a vulnerability, use this repository's GitHub private vulnerability reporting. Please avoid posting an exploitable report in a public issue.
+
+Supported release: 0.1.x after publication. Security fixes will be released as a new gem version rather than replacing an existing one.