New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix: Warn for deprecation in Node output (fixes #7443) #10953
Conversation
8f95777
to
f30fb69
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for contributing!
The code here LGTM, but I wanted to ask about the additional properties mentioned in the implementation described in this comment (usedRemovedRules
and usedNotFoundRules
). Did we decide not to implement those? Regardless, I'd be fine with merging this as is and adding the other two properties in a follow up PR, if we decide those would still be nice to have.
lib/cli-engine.js
Outdated
function createRuleWarnings(rules, loadedRules) { | ||
const ruleWarnings = { usedDeprecatedRules: [] }; | ||
|
||
if (!rules) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I know this isn't a terribly complex function, but I wonder if we could reduce the complexity a bit by restructuring it as:
const ruleWarnings = { usedDeprecatedRules: [] };
if (rules) {
Object.keys(rules).forEach(name => {
const loadedRule = loadedRules.get(name);
if (loadedRule.meta && loadedRule.meta.deprecated) {
ruleWarnings.usedDeprecatedRules.push({ ruleId: name, replacedBy: loadedRule.meta.docs.replacedBy });
}
});
}
return ruleWarnings;
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No problem!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks for contributing!
@kaicataldo I'm also unsure the outcome of the discussion w.r.t. those other two properties ( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the PR! I left a few minor suggestions, but overall this approach seems good to me.
lib/cli-engine.js
Outdated
const loadedRule = loadedRules.get(name); | ||
|
||
if (loadedRule.meta && loadedRule.meta.deprecated) { | ||
ruleWarnings.usedDeprecatedRules.push({ ruleId: name, replacedBy: loadedRule.meta.docs.replacedBy }); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will this work correctly if a rule doesn't have a meta.docs
property (e.g. a rule from a plugin)?
More generally, I'm wondering if we should move meta.docs.replacedBy
to just meta.replacedBy
, since the replacedBy
field doesn't really relate to documentation in this context. (I know it's currently meta.docs.replacedBy
on existing core rules, but it's easier to change that now than later since it's not a public API yet.)
edit: In either case, I think we should also update the Working with Rules page to note the new available options in the rule API.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a great point about meta.docs
not necessarily existing. The "Working with Rules" page explicitly says that meta.docs
is optional for custom rules and plugins: "In a custom rule or plugin, you can omit docs or include any properties that you need in it".
I'm happy to move replacedBy
up to meta
or I can add a property check (and document it either way), but I think where replacedBy
should hang is best decided by the maintainers?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My personal preference would be to move it to meta.replacedBy
rather than meta.docs.replacedBy
, but let's see what other team members think.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Moving replacedBy
to meta.replacedBy
makes sense to me 👍
docs/developer-guide/nodejs-api.md
Outdated
@@ -516,7 +519,7 @@ The top-level report object has a `results` array containing all linting results | |||
* `source` - The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present. | |||
* `output` - The source code for the given file with as many fixes applied as possible, so you can use that to rewrite the files if necessary. This property is omitted if no fix is available. | |||
|
|||
The top-level report object also has `errorCount` and `warningCount` which give the exact number of errors and warnings respectively on all the files. | |||
The top-level report object also has `errorCount` and `warningCount` which give the exact number of errors and warnings respectively on all the files. Additionally, `usedDeprecatedRules` signals any deprecated rules used and their replacement (if available). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could you be more specific in this documentation about what the shape of an object in usedDeprecatedRules
would look like (namely, that it has a ruleId
and replacedBy
property)?
lib/cli-engine.js
Outdated
const loadedRule = loadedRules.get(name); | ||
|
||
if (loadedRule.meta && loadedRule.meta.deprecated) { | ||
ruleWarnings.usedDeprecatedRules.push({ ruleId: name, replacedBy: loadedRule.meta.docs.replacedBy }); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should only include the replacedBy
key if it's a string, and omit it otherwise. If a rule from a plugin does something weird and uses a different type of object as a replacedBy
value, it could have the effect of crashing an integration/formatter.
Regarding |
@not-an-aardvark it looks like your changes may have been addressed. Can you take another look? |
I agree it would be nice to move to |
Seems like the enough folks want |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM. Thanks for contributing!
@not-an-aardvark looks like we just need an approval from you to move this forward. Can you take another look? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks!
Merged, thanks for the contribution. This will be super helpful to users. |
What is the purpose of this pull request? (put an "X" next to item)
[ ] Documentation update
[x] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofixing to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:
#7443
What changes did you make? (Give an overview)
Added a property
usedDeprecatedRules
to the output of the Node API that flags usage of deprecated rules.Is there anything you'd like reviewers to focus on?
The issue touched on other possible work (i.e. formatter changes,
usedRemovedRules
,usedNotFoundRules
). From reading the issue, I think the group settled on only implementingusedDeprecatedRules
, but please check my understanding.