rtk-ai / rtk-ai/rtk

feat(devex): raise the quality bar for AI-assisted contributions

Open
#747 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

area:ci effort-large enhancement help wanted priority:medium
Dominant language
Rust
Stars
81.1k
Forks
5.1k
Avg merge
4d 21h
Merged PRs (30d)
35

Description

Motivation

RTK contributions are mainly delegated to AI coding agents (Claude Code, Cursor, Copilot, etc.). In that context, the quality of the Rust codebase matters more than usual — the agent can't visually review its output, it relies entirely on static analysis to catch issues.

The current lint pipeline (cargo clippy --all-targets -- -D warnings) only covers Clippy's default group. Three high-value groups are completely invisible today, and two common supply chain checks are absent. This means an AI agent generating a PR can introduce idiomatic Rust violations, unused deps, broken doc links, or even a CVE — and nothing in CI will catch it.

Proposed changes

1. clippy::pedantic + clippy::nursery

Enable the two opt-in Clippy groups that catch idiomatic Rust violations:

```
cargo clippy --all-targets -- -D warnings -W clippy::pedantic -W clippy::nursery
```

The first run surfaces ~2,100 warnings. Most are mechanical fixes (format string inlining, unnecessary raw string hashes, redundant closures, single-char patterns) applied automatically.

Lints that are legitimately inapplicable to a CLI proxy are suppressed in a single #![allow(...)] block at the top of src/main.rs, each with a comment explaining why:

Category Lints Reason
Cast lints cast_precision_loss, cast_possible_truncation, cast_sign_loss, cast_possible_wrap Intentional usize→f64 for percentage calculations and i64→usize for SQLite results — controlled, small-value casts
Doc lints doc_markdown, missing_errors_doc, missing_panics_doc RTK is a CLI tool, not a library — library-style doc requirements don't apply
Naming module_name_repetitions git::GitArgs is the natural naming for CLI arg structs
Style option_if_let_else, cognitive_complexity, too_many_lines, missing_const_for_fn, suboptimal_flops, float_cmp Reduce readability in filter parsing code; missing_const_for_fn is a nursery lint with many false positives
Signatures must_use_candidate, needless_pass_by_value, unnecessary_wraps, fn_params_excessive_bools, trivially_copy_pass_by_ref, return_self_not_must_use Cosmetic on 50+ run() entry points; not worth changing across all modules
Established patterns format_push_string, non_std_lazy_statics 263 push_str(&format!(...)) and 23 lazy_static! usages — migrating these is tracked as follow-up (see below)
Minor style use_self, manual_let_else, items_after_statements, similar_names, map_unwrap_or, or_fun_call, match_same_arms, branches_sharing_code, struct_field_names, comparison_chain, redundant_pub_crate, used_underscore_binding Idiomatic alternatives are less readable in RTK's filter pattern code

Open to discussing any of these before landing — especially the "established patterns" row, which represents real technical debt rather than genuine false positives.

2. cargo-deny — supply chain security

Add a deny.toml covering:

  • Advisories: deny known CVEs and yanked crates
  • Licenses: explicit allowlist (MIT, Apache-2.0, BSD-*, ISC, MPL-2.0, Zlib…)
  • Bans: deny tokio, async-std, futures — enforces RTK's no-async rule at tooling level, not just documentation
  • Sources: crates.io only, deny unknown registries and git deps
3. cargo-machete — unused dependencies

Detects unused entries in Cargo.toml. On RTK's current dep tree nothing is removed (all 21 deps are in use), but the check catches future drift.

4. rustdoc -D warnings

```
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
```

Catches broken intra-doc links and malformed doc comments. One issue found in the current codebase (<path> in a doc comment interpreted as an HTML tag).

Integration

All four checks wired into CI and a local task:

```
mise run qa → fmt:check + lint + test + doc + machete + deny
```

Questions for discussion

  • Crate-level #![allow(...)]: is the table above acceptable as-is, or do you want to address some of these before landing?
  • multiple-versions = "warn" vs "deny": the windows-sys family ships 4 simultaneous versions via transitive deps (dirs, ring, colored, clap). Worth trying to reduce, or skip and warn?
  • clippy::nursery: some nursery lints are experimental and occasionally noisy. Open to dropping it and sticking with just pedantic if you'd prefer a more stable baseline.

Out of scope for this PR

  • lazy_static!std::sync::LazyLock migration (23 usages — separate modernization task)
  • push_str(&format!(...))write!() migration (263 usages — separate task)
  • Fixing too_many_arguments on run() entry points (requires API design decisions)

A working implementation is available on branch devex/alignment-claude-hook.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the proposed quality checks in src/main.rs, Cargo.toml, deny.toml, and the existing CI and mise configuration, then inspect the available chore/quality-gate branch. Run the listed Clippy, cargo-deny, cargo-machete, and rustdoc commands to identify remaining warnings and policy decisions. Done means all four checks are wired into CI and mise run qa without warnings, while documented exceptions and out-of-scope migrations remain excluded.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
ci-cd, developer-experience, security, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.