fix(ci): unblock releases by cutting usage-derive's dev-dependency

[jdx]

This is the failure you linked, and it's mine. The release job has failed on every run since usage-derive became publishable:

failed to select a version for `usage-argv`
  ... required by package `usage-derive v5.1.0`
package `usage-derive` depends on `usage-argv` with feature `spec`
  but `usage-argv` does not have that feature

What happened

usage-argv 5.1.0 was published in #798, before #801 added its spec feature. crates.io versions are immutable, so no crate at 5.1.0 can ever depend on that feature — and cargo publish resolves dev-dependencies against the registry, so usage-derive could not be packaged at all.

Worse than a delay: the failure happens in the catch-up publish, before the step that opens the release PR — so the version never bumps, and the pipeline stays stuck instead of fixing itself on the next run.

The fix

The dev-dependency is gone, not worked around. A proc-macro that dev-depends on the runtime it emits code for recreates this cycle every time that runtime gains a feature mid-version, and serde_derive avoids it the same way. This crate emits tokens and links nothing, so it now depends on usage-argv not at all.

Its crate-level example would have become an ignore block nobody checks, so it moved to conformance/tests/derive.rs as a real test — compiled and run, with both sides pointing at each other so they cannot drift.

Verified the actual thing that was broken:

$ cargo publish -p usage-derive --dry-run
   Packaged 7 files, 49.6KiB
   Verifying usage-derive v5.1.0
    Finished

Worth knowing for next time

The general trap is shared-version publishing plus "publish whatever is not yet on crates.io": a feature added to a crate after its version was published is invisible to the registry, so any dependent needing that feature is unpublishable until the version moves. It bit a dev-dependency this time, which is why cutting it is a complete fix — but a real dependency in the same position would need the bump.

AI-assisted — Tool: Claude Code; model: anthropic/claude-fable-5; version: unavailable.

---

Note

^{Cursor Bugbot is generating a summary for commit da8aa07. Configure here.}

Summary by CodeRabbit

• Tests

  • Added conformance coverage for derived command-line interfaces, including jobs, verbosity, color options, positional files, and generated flag specifications.
  • Added validation for the crate-level documentation example through the conformance test suite.

• Documentation

  • Clarified that the documentation example is verified externally rather than compiled directly in the crate.
  • Documented dependency and publishing constraints affecting the example setup.

[coderabbitai]

📝 Walkthrough

Walkthrough

The derive documentation example is marked as ignored and validated through a new conformance test. The derive crate no longer declares the usage-argv dev-dependency or its spec feature.

Changes

Derive documentation example validation

Layer / File(s)	Summary
Documentation example setup derive/src/lib.rs, derive/Cargo.toml	The crate documentation marks the example as ignored and points to the conformance test. The manifest documents the dependency-cycle constraint and removes the unused dev-dependency configuration.
Conformance example test conformance/tests/derive.rs	A docs_example test defines a derived CLI and verifies parsing, defaults, color negation, positional files, and generated KDL output.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• jdx/usage#803: Adds the derive functionality that this conformance example tests.

Poem

A rabbit checks each flag in line,
With files collected, neat and fine.
The ignored docs now point the way,
While conformance tests hold sway.
Hop, parse, and specs align!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the CI fix and removal of the dev-dependency that unblocks releases.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███	148,237,887 → 148,172,794	-0.04%	14.18 → 13.97ms	-1.49%
startup	▁██▁▁▄▄▅▃▃▃▃▃▃▃▃▃▇▇▇	1,203,985 → 1,204,005	+0.00%	0.97 → 0.97ms	-0.08%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{da8aa0757213 vs e27df4f91c2c · measured on the runner, not pushed to the history.}

[coderabbitai]

🧹 Nitpick comments (1)

conformance/tests/derive.rs (1)

496-505: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Cover the untested derive attributes.

The test always supplies -j8, so it never exercises env = "EX_JOBS" or default = "4". It only checks verbose == 0, so it does not verify repeated -v values for count. --no-color also bypasses the color default. Add isolated cases for these paths. Restore or isolate EX_JOBS so the test remains deterministic.

Also applies to: 511-518

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@conformance/tests/derive.rs` around lines 496 - 505, Expand the derive tests
around the jobs, verbose, and color fields to independently exercise the EX_JOBS
environment fallback, the jobs default of "4", repeated -v counting, and the
color default versus --no-color behavior. Ensure EX_JOBS is cleared or scoped
per case so environment state cannot affect test results, while preserving the
existing explicit argument coverage.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@conformance/tests/derive.rs`:
- Around line 496-505: Expand the derive tests around the jobs, verbose, and
color fields to independently exercise the EX_JOBS environment fallback, the
jobs default of "4", repeated -v counting, and the color default versus
--no-color behavior. Ensure EX_JOBS is cleared or scoped per case so environment
state cannot affect test results, while preserving the existing explicit
argument coverage.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 47875ef4-e296-4c76-9654-ed3251d05435

📥 Commits

Reviewing files that changed from the base of the PR and between e27df4f and da8aa07.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (3)

• conformance/tests/derive.rs
• derive/Cargo.toml
• derive/src/lib.rs

[greptile-apps]

Greptile Summary

The PR removes usage-derive's publish-blocking development dependency on usage-argv and relocates its documentation example into the conformance suite.

• Removes usage-argv from usage-derive's development dependencies and lockfile entry.
• Marks the derive crate's example as ignored so packaging does not resolve the runtime crate.
• Adds an equivalent, executable conformance test covering parsing and KDL generation.

Confidence Score: 5/5

The PR appears safe to merge, with the removed dependency adequately replaced by an executable conformance test.

The derive crate has no remaining compiled test or build target requiring usage-argv, while the moved example has the required runtime feature and is exercised by the workspace CI test command.

Important Files Changed

Filename	Overview
derive/Cargo.toml	Removes the registry-resolved development dependency that blocked packaging; no remaining derive-local target requires it.
derive/src/lib.rs	Converts the crate-level example to an ignored documentation block and points maintainers to its executable conformance counterpart.
conformance/tests/derive.rs	Adds a CI-covered test reproducing the documented derive declaration and validating parsing, defaults, negation, positional arguments, and spec generation.
Cargo.lock	Correctly removes usage-argv from usage-derive's resolved dependency list.

_{Reviews (1): Last reviewed commit: "fix(ci): unblock releases by cutting usa..." | Re-trigger Greptile}