Add lint group infra #960

suaviloquence · 2024-10-01T07:17:27Z

Adds:

the Identifier enum for consistent configuration with lint groups and lints
OverrideStack::try_push which tries to compile a Map<Identifier, Override> to a Map<String (= lint id), Override>, and errors on a conflict
the must_use_added lint group
currently the lint_group field on SemverQuery is optional while we figure out what lints go in what groups (and what groups to include). must_use_added is an example from my design draft, but we can definitely go in a different direction. Eventually the goal is to make lint_group not an Option, so every lint is associated with exactly one lint group
some tests + documentation, and user documentation in the README

suaviloquence · 2024-10-01T07:19:22Z

src/query.rs

+impl Identifier {
+    /// Returns a list of lint ids that this identifier refers to, given the set of
+    /// all queries.
+    pub(crate) fn lints<'a>(


If/when we add dynamic groups like warnings, major, and minor, this will need an extra &OverrideStack argument to determine this. We call this method in OverrideStack::try_push, so this will be an easy change.

Notes like this are excellent candidates to put into the source code directly. We won't remember to check this PR if/when we add groups like warnings/major/minor, but we'll probably find the note in the source code.

Suggested change

pub(crate) fn lints<'a>(

//

// N.B.: If we add dynamic groups like `warnings`, `major`, or `minor`, this function

// will require an additional `&OverrideStack` argument.

pub(crate) fn lints<'a>(

If possible, expand the above suggestion with more detail on what that extra argument would be used for and how. Right now, it isn't immediately clear to me what it would do.

suaviloquence · 2024-10-01T07:20:11Z

src/query.rs

+    pub(crate) fn lints<'a>(
+        &'a self,
+        all_queries: &'a BTreeMap<String, SemverQuery>,
+    ) -> Vec<&'a str> {


We could also make this a Vec<&'a SemverQuery>, but we would need to handle the case where an unknown lint id was provided (but this may be a good thing, currently there is no warning for this). This would cause a slight mismatch in the overridestack API though, which currently works off of lint ids.

Identifier doesn't quite strike me as the right place for this logic. We're giving the larger pool of data (&'a BTreeMap<String, SemverQuery>) to the smaller type (a two-variant enum) and asking it to figure it out.

Also, I feel like we want the "resolve the identifiers" logic to have Result types so we can complain about bad IDs more explicitly. And we really need to test those cases before someone gets bitten by a silent bug around bad IDs...

suaviloquence · 2024-10-01T07:21:07Z

src/query.rs

+            for lint in lints {
+                if let Some(entry) = compiled_map.get_mut(lint) {
+                    if let Some(lint_level) = overrides.lint_level {
+                        if let Some(old) = entry.lint_level {


Currently it is an error even if lint_level == old. Should this be the case? Maybe just a warning?

When might this happen?

If I'm understanding it correctly, there's no conflict since both sides are setting the same value, no?

obi1kenobi

Unfortunately, I think this needs a lot more design on the UX side of things first, before we get into the weeds of how it's implemented under the hood.

We need to explicitly enumerate which error cases happen when.
We need super high-quality error messages in each case, pointing to the specific places that caused the problem and offering concrete next steps.
We need to consider what happens when we add more lint groups, add new lints to various combinations of lint groups, or newly add existing lints to existing groups. Edge cases are everywhere!
We need to consider the "upgrade experience" of `cargo-semver-checks. If we aren't extremely careful, adding a new lint will be a major breaking change and will anger our biggest users first — the people we want to keep the most happy.

I think taking a step back from the code and producing something more akin to a design doc would be a great next step.

obi1kenobi · 2024-10-01T17:54:56Z

src/query.rs

+impl Identifier {
+    /// Returns a list of lint ids that this identifier refers to, given the set of
+    /// all queries.
+    pub(crate) fn lints<'a>(


Notes like this are excellent candidates to put into the source code directly. We won't remember to check this PR if/when we add groups like warnings/major/minor, but we'll probably find the note in the source code.

Suggested change

pub(crate) fn lints<'a>(

//

// N.B.: If we add dynamic groups like `warnings`, `major`, or `minor`, this function

// will require an additional `&OverrideStack` argument.

pub(crate) fn lints<'a>(

If possible, expand the above suggestion with more detail on what that extra argument would be used for and how. Right now, it isn't immediately clear to me what it would do.

obi1kenobi · 2024-10-01T17:56:10Z

src/query.rs

@@ -103,6 +103,10 @@ pub struct SemverQuery {
    /// The default lint level for when this lint occurs.
    pub lint_level: LintLevel,

+    /// The [`LintGroup`] that this query is a member of (currently optional).


Suggested change

/// The [`LintGroup`] that this query is a member of (currently optional).

/// The [`LintGroup`] that this query is a member of, if any.

Also, should this be a Vec<LintGroup> by any chance?

Might there be a situation where we want more than one group per lint? And if so, is the existing priority system sufficient to handle group conflicts?

obi1kenobi · 2024-10-01T18:09:00Z

README.md

+Note that `function_must_use_added` still has a `major` required update bump, because the entry with
+priority -1 left the `required-update` to its default value, so `cargo-semver-checks` will use the
+entry with less precedence to calculate the required version bump.


We need a succinct, memorable way to describe this algorithm.

How about something like:

Suggested change

Note that `function_must_use_added` still has a `major` required update bump, because the entry with

priority -1 left the `required-update` to its default value, so `cargo-semver-checks` will use the

entry with less precedence to calculate the required version bump.

The final values for the `level` and `required-update` fields are computed separately, each in priority order.

If the entry with the most-negative `priority` doesn't set both `level` and `required-update` values, the final configuration may have elements of multiple config entries. This happens

in the above example, where `function_must_use_added` still has a `major` required update bump:

- The entry with priority -1 did not override the `required-update` field. We keep looking.

- In priority order, the next entry is the one with priority 0. It set `required-update = "major"`.

- The lint uses `required-update = "major"`.

obi1kenobi · 2024-10-01T18:12:32Z

README.md

+When there are multiple conflicting entries for a given lint (for example, configuring the
+`must_use_added` group containing the `function_must_use_added` lint and `function_must_use_added` itself),
+`cargo-semver-checks` needs more information to determine which configuration entry takes
+precedence. Like the Cargo `[lints]` table, each configuration entry has an optional
+`priority` field that defines the order of configuration entries. If an entry has no
+`priority` key, its priority is 0 by default. Entries with a lower (more negative)
+`priority` override those with a higher `priority` when there is a conflict.


Consider explaining first, then providing an example, rather that doing both at once. Weaving lint groups and a specific lint into the middle of the explanation leaves readers with a lot of information to track.

Consider adapting the explanation I used below if you decide you like it. Something along the lines of "for each setting in each lint, we inspect config items in priority order and pick the first one that sets a value for that setting."

obi1kenobi · 2024-10-01T18:13:58Z

src/query.rs

+// TODO: replace with LazyLock once MSRV is >= 1.80
+pub(crate) static ALL_QUERIES: OnceLock<BTreeMap<String, SemverQuery>> = OnceLock::new();


I really dislike globals like this. They make testing a mess.

Can you think of any reasonable way we can avoid this?

obi1kenobi · 2024-10-01T18:19:22Z

src/query.rs

+            for lint in lints {
+                if let Some(entry) = compiled_map.get_mut(lint) {
+                    if let Some(lint_level) = overrides.lint_level {
+                        if let Some(old) = entry.lint_level {


When might this happen?

If I'm understanding it correctly, there's no conflict since both sides are setting the same value, no?

obi1kenobi · 2024-10-01T18:20:34Z

src/query.rs

+    ///
+    /// Returns an `Err` if there is a configuration conflict in the passed map: when
+    /// multiple entries in `item` configure the same entry for the same lint. To handle
+    /// configuration precedence in a defined way, call this function multiple times, and


defined way is ominously vague here, and it's in the middle of a very long sentence which makes me feel it's unlikely I'd manage to use this function properly =/

obi1kenobi · 2024-10-01T18:21:58Z

src/query.rs

+                if let Some(entry) = compiled_map.get_mut(lint) {
+                    if let Some(lint_level) = overrides.lint_level {
+                        if let Some(old) = entry.lint_level {
+                            anyhow::bail!("Configuration conflict detected for lint `{lint}`:\n\


I think our bail errors are generally lowercase since bail!(<stuff>) gets printed as error: <stuff> when the program exits. If I'm right about that, any capitalized error messages should be tested + changed.

obi1kenobi · 2024-10-01T18:23:12Z

src/query.rs

+                    if let Some(lint_level) = overrides.lint_level {
+                        if let Some(old) = entry.lint_level {
+                            anyhow::bail!("Configuration conflict detected for lint `{lint}`:\n\
+                                lint level is set to `{old:?}` and {lint_level:?} at the same config priority.");


This is unfortunately a supremely non-useful error message: it tells the user "go figure it out" without actually saying which entries are the ones at that priority. The entries might not be easy to find, since they might be on the lint itself, or any of its groups.

This would be very frustrating to encounter.

obi1kenobi · 2024-10-01T18:27:06Z

...tputs/snapshot_tests/cargo_semver_checks__snapshot_tests__configuration_conflict-output.snap

+expression: result
+---
+--- error ---
+add a `priority` key to the entries in [package.metadata.cargo-semver-checks.lints].


Not a great error message.

Imagine the user's Cargo.toml has 100 config entries. Suddenly, one of them caused a conflict. (Maybe it's because we added a new lint that is the first one to be in a particular combination of two groups simultaneously? The user had specified settings for each group, and they didn't conflict in our previous release. In the new release with the new lint, they do! Oops!)

Now we just told the user "hey please add priority to all your 100 config entries." They'll uninstall the tool immediately.

suaviloquence added 3 commits September 17, 2024 16:22

handle priority in the lint table

aaf6d61

lint groups

dae826d

Merge remote-tracking branch 'upstream/main' into lint-group

46404a0

suaviloquence commented Oct 1, 2024

View reviewed changes

suaviloquence added 2 commits October 1, 2024 00:24

i messed up the merge

829fdab

fix snapshot

a8816a7

obi1kenobi reviewed Oct 1, 2024

View reviewed changes

obi1kenobi linked an issue Oct 1, 2024 that may be closed by this pull request

Create configurable groups of lints #835

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add lint group infra #960

Add lint group infra #960

suaviloquence commented Oct 1, 2024

suaviloquence Oct 1, 2024

obi1kenobi Oct 1, 2024

suaviloquence Oct 1, 2024 •

edited

Loading

obi1kenobi Oct 1, 2024

suaviloquence Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi left a comment •

edited

Loading

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

obi1kenobi Oct 1, 2024

	/// The [`LintGroup`] that this query is a member of (currently optional).
	/// The [`LintGroup`] that this query is a member of, if any.

-Note that `function_must_use_added` still has a `major` required update bump, because the entry with
-priority -1 left the `required-update` to its default value, so `cargo-semver-checks` will use the
-entry with less precedence to calculate the required version bump.
+The final values for the `level` and `required-update` fields are computed separately, each in priority order.
+If the entry with the most-negative `priority` doesn't set both `level` and `required-update` values, the final configuration may have elements of multiple config entries. This happens
+in the above example, where `function_must_use_added` still has a `major` required update bump:
+- The entry with priority -1 did not override the `required-update` field. We keep looking.
+- In priority order, the next entry is the one with priority 0. It set `required-update = "major"`.
+- The lint uses `required-update = "major"`.

		// TODO: replace with LazyLock once MSRV is >= 1.80
		pub(crate) static ALL_QUERIES: OnceLock<BTreeMap<String, SemverQuery>> = OnceLock::new();

Add lint group infra #960

Are you sure you want to change the base?

Add lint group infra #960

Conversation

suaviloquence commented Oct 1, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

suaviloquence Oct 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

obi1kenobi left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

suaviloquence Oct 1, 2024 •

edited

Loading

obi1kenobi left a comment •

edited

Loading