feat: add a queue reset so a repeated push cannot enqueue work twice

[beagleknight]

Mirrors specbandit#27 (Ruby gem). Both are needed: factorial pushes backend specs through the gem and everything else through this package.

Problem

A backend spec failed in factorial CI with a T::Struct prop redefinition error. It looked like a Sorbet/Tapioca problem. It was not: the same spec file was loaded twice in one process.

The queue key is scoped by CI run, not by CI attempt. That is deliberate. Re-running a single failed runner does not re-run the job that pushed, so the runner must still find the queue and the published marker that the first attempt created.

The cost is that the producer is not idempotent:

• A producer that pushes and then fails leaves the work list orphaned, because its runners never start.
• A producer that runs again (whole-workflow re-run, or a failed-jobs re-run that includes it) appends a second copy on top.

Every file is then enqueued twice. The suite runs twice, and any two copies that reach the same worker are loaded twice in one process.

Change

RedisQueue.clear removes the queue and its <key>:published marker in a single DEL. It is exposed two ways:

specbandit push --key KEY --reset    # empty the key, then push
specbandit reset --key KEY           # standalone

Reset is opt-in. push keeps its current meaning and appending to a queue stays possible.

reset is registered as a boolean flag in the argument parser. A flag missing from that list consumes the next token as its value, so push --reset a.test.ts would otherwise lose the file.

What reset does not touch

Per-runner rerun keys and failed keys. A runner's replay memory has to survive a re-run of that runner. A runner that finds data in both the shared queue and its rerun key is the full-rerun case, already handled in v1.3.0: it resets its own memory and steals.

Nothing is cleared when there is nothing to push in its place. Dropping the marker on its own would make every worker on that key crash as "never published".

Version drift, fixed here too

VERSION in src/configuration.ts said 0.10.0 while package.json was at 1.3.0, so specbandit --version and the specbandit_version field in --report JSON both reported a version nobody shipped. The constant cannot import package.json, because tsconfig rootDir is src, so the release workflow now rewrites it alongside the package.json bump and fails loudly if the constant moves.

Tests

• RedisQueue.clear issues one DEL with both key names.
• Publisher: clear happens before the push, only with reset: true, never on an empty push, and the leftover count is reported.
• New E2E scenario 8 against the real Redis service: two plain pushes stack 14 entries, a third push with --reset leaves 7, the marker survives, a worker sees each file exactly once, and a standalone reset removes the marker. Verified locally against a real Redis before pushing.

Two pre-existing test failures (jestAdapter / cypressAdapter "throws when not installed") reproduce on unmodified main in a local checkout where those optional peers are present. They pass in CI.

Follow-up, not in this PR

The flaky-retry pass consumes <key>-failed-<n>, which is written by work, not push, so a re-run can still leave stale entries there. The blast radius is re-running an already-failed spec, not a double load.

Next

Needs a Release dispatch (bump: minor → v1.4.0) before factorial can adopt it.

[jacobobq]

Looking good!