Continue resolving cargo-semver-checks blockers for merging into cargo

[nikomatsakis]

Metadata
Point of contact	@obi1kenobi
Team(s)	cargo, rustdoc
Goal document	2025h1/cargo-semver-checks

Summary

Design and implement cargo-semver-checks functionality that lies on the critical path for merging the tool into cargo itself. Continues the work of the 2024h2 goal.

Tasks and status

• Prototype cross-crate linting using workarounds (@obi1kenobi)
• Allow linting generic types, lifetimes, bounds (@obi1kenobi)
• Handle "special cases" like 'static and ?Sized (@obi1kenobi)
• Handle #[doc(hidden)] in sealed trait analysis (@obi1kenobi)
• Discussion and moral support (cargo, rustdoc )

[nikomatsakis]

This issue is intended for status updates only.

For general questions or comments, please contact the owner(s) directly.

[obi1kenobi]

Status update as of September 1.

Key developments: We've laid a lot of the groundwork to make manifest linting possible.

• In preparation for the significant expansion of our CLI, we now have the ability to test how CLI invocations get interpreted internally. We can also now snapshot the output of any CLI invocation over a given workspace, allowing us to proceed with refactoring the implementation without breaking existing use cases.
• We have a concrete design for the expansion of the CLI, and for the Trustfall schema changes that will be necessary to enable manifest linting.

Not blocked on anything. No opportunities to contribute yet, but stay tuned — there will be some in future updates!

[obi1kenobi]

Status update as of September 17.

Key developments: Working prototype of manifest querying.

WIP branch here: https://github.com/obi1kenobi/trustfall-rustdoc-adapter/compare/manifest_querying

An example SemVer lint this enables would be: "a non-nightly, non-underscore-prefixed feature has been removed from the package between releases."

{
    CrateDiff {
        baseline {
            feature {
                feature: name
                    @filter(op: "!=", value: ["$nightly"])
                    @tag
                    @output
            }
        }

        current {
            feature @fold @transform(op: "count") @filter(op: "=", value: ["$zero"]) {
                name @filter(op: "=", value: ["%feature"])
            }
        }
    }
}

# args:
{
    "nightly": "nightly",
    "zero": 0
}

This is SemVer-major because it'll break uses like: my_dep = { version = "1.0", features = ["removed_feature"] }. We're ignoring any features named nightly because community consensus is that such features are unstable — I'll do some more research on other expected-unstable feature patterns in the community before we ship any lints around this.

Not blocked on anything. No opportunities to contribute yet, but stay tuned — there will be some in future updates!

[obi1kenobi]

No major updates to report. Preparing my talk for next week's EuroRust has taken away most of my free time.

[obi1kenobi]

Key developments:

• Partial schema design and implementation of type information in lints
• Resolved multi-team questions that were blocking cross-crate checking
• Refactor of cargo-semver-checks data handling to enable supporting manifest information

Partial schema design and implementation of type information in lints

The schema we use for writing lints now contains information on:

• generic parameters (lifetime, type, or const) on structs, enums, unions, traits, and impl blocks
• trait bounds on generic type parameters

This newly allows the implementation of breaking-change lints such as "generic const parameter no longer has default value" or "trait bound removed from generic parameter in trait method."

Additionally, @suaviloquence has implemented the ability to print rustdoc JSON type information into human-readable source code form, which will allow us to produce higher-quality diagnostics for type-related breaking changes. This required a lot of care, perseverance, and testing — thank you 🙏

Resolved multi-team questions that were blocking cross-crate checking

For a long time, cross-crate checking was blocked on a multi-team coordination problem: cargo-semver-checks needs more data from rustdoc, which in turn needs more data from rustc. This was a classic "everyone's third-most important thing" problem: important, but not critical and therefore never top of the agenda for resolving the open questions there.

In-person meetings with Rust Project members during my trips to RustConf and EuroRust helped nudge this forward:

• The compiler team MCP intended to provide additional data to rustdoc was merged and can now be implemented.
• I synced up with T-rustdoc members on how rustdoc would then present that data to cargo-semver-checks in rustdoc JSON. Along the way, we were able to discuss and agree on several additional improvements to rustdoc JSON that improved performance in cargo-semver-checks.

Refactor of cargo-semver-checks data handling

Plumbing in manifest information was proving challenging due to a significant amount of tech debt accrued in the cargo-semver-checks code that loads the data of scanned crates. This PR is a significant clean-up and refactor of that portion of the tool, allowing us to move forward with retrieving manifest information while also supporting other quality-of-life improvements.

With the mountain of tech debt largely resolved, I expect that adding manifest information should be relatively straightforward from here.

This portion of the goal also greatly benefited from the Google Summer of Code work that @suaviloquence did — it wouldn't have been possible without the significant effort he put into improving our test suites and harnesses.

[obi1kenobi]

Key developments:

• Support for cargo manifest linting is now merged: Support linting breaking changes in manifests & add feature_missing lint obi1kenobi/cargo-semver-checks#1007

Cargo manifest linting

As a recap, the idea here is catching breakage caused by manifest (Cargo.toml) changes, not just source code changes.

An example of such breakage is the removal of a package feature: any crates that enabled the removed feature will no longer build.

The PR above builds upon the data-handling refactor from the previous update post, and makes it possible to lint manifests for breaking changes. The PR includes the feature_missing lint that checks for the exact case mentioned above. That is but one of many new lints that are now possible with this feature. Hooray! 🎉

[nikomatsakis]

This is a continuing project goal, and the updates below this comment will be for the new period 2025h1

[obi1kenobi]

Thanks, Niko! Copying in the new tasks from the 2025h1 period:

• Prototype cross-crate linting using workarounds (@obi1kenobi)
• Allow linting generic types, lifetimes, bounds (@obi1kenobi)
• Handle "special cases" like 'static and ?Sized (@obi1kenobi)
• Handle #[doc(hidden)] in sealed trait analysis (@obi1kenobi)
• Discussion and moral support (cargo, [rustdoc]

[obi1kenobi]

Key developments:

• Sealed trait analysis correctly handles #[doc(hidden)] items. This completes one checkbox of this goal!
• We shipped a series of lints detecting breakage in generic types, lifetimes, and const generics. One of them has already caught accidental breakage in the real world!

cargo-semver-checks v0.40, released today, includes a variety of improvements to sealed trait analysis. They can be summarized as "smarter, faster, more correct," and will have an immediate positive impact on popular crates such as diesel and zerocopy.

While we already shipped a series of lints detecting generics-related breakage, more work is needed to complete that checkbox. This, and the "special cases like 'static and ?Sized", will be the focus of upcoming work.

[obi1kenobi]

TL;DR:

Earlier this month, we completed one checkbox of the goal: #[doc(hidden)] in sealed trait analysis, live in cargo-semver-checks v0.40. We also made significant progress on type system modeling, which is part of two more checkboxes.

• We shipped method receiver types in our schema, enabling more than a dozen new lints.
• We have a draft schema for ?Sized bounds, and are putting the finishing touches on 'static and "outlives" bounds. More lints will follow here.
• We also have a draft schema for the new use<> precise capturing syntax.

Additionally, cargo-semver-checks is participating in Google Summer of Code, so this month we had the privilege of merging many contributions from new contributors who are considering applying for GSoC with us! We're looking forward to this summer, and would like to wish the candidates good luck in the application process!