Skip to content

Commit 2370b46

Browse files
JoshuaKGoldbergbmish
JoshuaKGoldberg
and
bmish
authored
feat: add require-meta-docs-recommended rule (#447)
* feat: add require-meta-docs-recommended rule * Apply suggestions from code review Co-authored-by: Bryan Mishkin <[email protected]> * Apply rename * Fix lint complaints * Added allowNonBoolean opt-in option * Unit test for unknown value --------- Co-authored-by: Bryan Mishkin <[email protected]>
1 parent 95b1980 commit 2370b46

9 files changed

+397
-44
lines changed

Diff for: ‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ module.exports = [
9898
| [prefer-replace-text](docs/rules/prefer-replace-text.md) | require using `replaceText()` instead of `replaceTextRange()` | | | | |
9999
| [report-message-format](docs/rules/report-message-format.md) | enforce a consistent format for rule report messages | | | | |
100100
| [require-meta-docs-description](docs/rules/require-meta-docs-description.md) | require rules to implement a `meta.docs.description` property with the correct format | | | | |
101+
| [require-meta-docs-recommended](docs/rules/require-meta-docs-recommended.md) | require rules to implement a `meta.docs.recommended` property | | | | |
101102
| [require-meta-docs-url](docs/rules/require-meta-docs-url.md) | require rules to implement a `meta.docs.url` property | | 🔧 | | |
102103
| [require-meta-fixable](docs/rules/require-meta-fixable.md) | require rules to implement a `meta.fixable` property | ✅ | | | |
103104
| [require-meta-has-suggestions](docs/rules/require-meta-has-suggestions.md) | require suggestable rules to implement a `meta.hasSuggestions` property | ✅ | 🔧 | | |

Diff for: ‎docs/rules/require-meta-docs-recommended.md

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Require rules to implement a `meta.docs.recommended` property (`eslint-plugin/require-meta-docs-recommended`)
2+
3+
<!-- end auto-generated rule header -->
4+
5+
Utilizing `meta.docs.recommended` makes it clear from each rule implementation whether a rule is part of the `recommended` config. Some plugins also have scripting for conveniently generating their config based on this flag.
6+
7+
However, this flag may not be appropriate for all plugins:
8+
9+
- Extra scripting/tooling is needed to keep the flags in sync with the config
10+
- The flag may not scale to plugins that have multiple/many configs or don't have a recommended config
11+
- Or some may simply prefer to keep the source of truth solely in the config rather than duplicating config membership data in the rules
12+
13+
By default, this rule enforces a `recommended` property be set to a `boolean` value.
14+
15+
## Rule Details
16+
17+
This rule requires ESLint rules to have a valid `meta.docs.recommended` property.
18+
19+
Examples of **incorrect** code for this rule:
20+
21+
```js
22+
/* eslint eslint-plugin/require-meta-docs-recommended: error */
23+
24+
module.exports = {
25+
meta: {},
26+
create(context) {
27+
/* ... */
28+
},
29+
};
30+
```
31+
32+
Examples of **correct** code for this rule:
33+
34+
```js
35+
/* eslint eslint-plugin/require-meta-docs-recommended: error */
36+
37+
module.exports = {
38+
meta: { recommended: true },
39+
create(context) {
40+
/* ... */
41+
},
42+
};
43+
```
44+
45+
## Options
46+
47+
<!-- begin auto-generated rule options list -->
48+
49+
| Name | Description | Type | Default |
50+
| :---------------- | :--------------------------------------------------- | :------ | :------ |
51+
| `allowNonBoolean` | Whether to allow values of types other than boolean. | Boolean | `false` |
52+
53+
<!-- end auto-generated rule options list -->
54+
55+
### `allowNonBoolean`
56+
57+
Some plugins require `meta.docs.recommended` values but allow value types other than `boolean`.
58+
This option changes the rule to only enforce that the values exist.
59+
60+
Example of **correct** code for this rule with `allowNonBoolean`:
61+
62+
```js
63+
/* eslint eslint-plugin/require-meta-docs-recommended: ["error", { "allowNonBoolean": true }] */
64+
65+
module.exports = {
66+
meta: { recommended: 'strict' },
67+
create(context) {
68+
/* ... */
69+
},
70+
};
71+
```
72+
73+
## Further Reading
74+
75+
- [Rule Structure](https://eslint.org/docs/latest/extend/custom-rules#rule-structure)

Diff for: ‎lib/rules/require-meta-docs-description.js

+16-15
Original file line numberDiff line numberDiff line change
@@ -56,22 +56,19 @@ module.exports = {
5656
const scope = sourceCode.getScope?.(ast) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
5757
const { scopeManager } = sourceCode;
5858

59-
const pattern =
60-
context.options[0] && context.options[0].pattern
61-
? new RegExp(context.options[0].pattern)
62-
: DEFAULT_PATTERN;
59+
const {
60+
docsNode,
61+
metaNode,
62+
metaPropertyNode: descriptionNode,
63+
} = utils.getMetaDocsProperty('description', ruleInfo, scopeManager);
6364

64-
const metaNode = ruleInfo.meta;
65-
const docsNode = utils
66-
.evaluateObjectProperties(metaNode, scopeManager)
67-
.find((p) => p.type === 'Property' && utils.getKeyName(p) === 'docs');
68-
69-
const descriptionNode = utils
70-
.evaluateObjectProperties(docsNode && docsNode.value, scopeManager)
71-
.find(
72-
(p) =>
73-
p.type === 'Property' && utils.getKeyName(p) === 'description',
74-
);
65+
if (!descriptionNode) {
66+
context.report({
67+
node: docsNode || metaNode || ruleInfo.create,
68+
messageId: 'missing',
69+
});
70+
return;
71+
}
7572

7673
if (!descriptionNode) {
7774
context.report({
@@ -87,6 +84,10 @@ module.exports = {
8784
return;
8885
}
8986

87+
const pattern = context.options[0]?.pattern
88+
? new RegExp(context.options[0].pattern)
89+
: DEFAULT_PATTERN;
90+
9091
if (typeof staticValue.value !== 'string' || staticValue.value === '') {
9192
context.report({
9293
node: descriptionNode.value,

Diff for: ‎lib/rules/require-meta-docs-recommended.js

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
'use strict';
2+
3+
const { getStaticValue } = require('eslint-utils');
4+
const utils = require('../utils');
5+
6+
/** @type {import('eslint').Rule.RuleModule} */
7+
module.exports = {
8+
meta: {
9+
type: 'suggestion',
10+
docs: {
11+
description:
12+
'require rules to implement a `meta.docs.recommended` property',
13+
category: 'Rules',
14+
recommended: false,
15+
url: 'https://github.com/eslint-community/eslint-plugin-eslint-plugin/tree/HEAD/docs/rules/require-meta-docs-recommended.md',
16+
},
17+
fixable: null,
18+
schema: [
19+
{
20+
type: 'object',
21+
properties: {
22+
allowNonBoolean: {
23+
default: false,
24+
description: 'Whether to allow values of types other than boolean.',
25+
type: 'boolean',
26+
},
27+
},
28+
additionalProperties: false,
29+
},
30+
],
31+
messages: {
32+
incorrect: '`meta.docs.recommended` is required to be a boolean.',
33+
missing: '`meta.docs.recommended` is required.',
34+
},
35+
},
36+
37+
create(context) {
38+
const sourceCode = context.sourceCode || context.getSourceCode(); // TODO: just use context.sourceCode when dropping eslint < v9
39+
const ruleInfo = utils.getRuleInfo(sourceCode);
40+
if (!ruleInfo) {
41+
return {};
42+
}
43+
44+
const { scopeManager } = sourceCode;
45+
const {
46+
docsNode,
47+
metaNode,
48+
metaPropertyNode: descriptionNode,
49+
} = utils.getMetaDocsProperty('recommended', ruleInfo, scopeManager);
50+
51+
if (!descriptionNode) {
52+
context.report({
53+
node: docsNode || metaNode || ruleInfo.create,
54+
messageId: 'missing',
55+
});
56+
return {};
57+
}
58+
59+
if (context.options[0]?.allowNonBoolean) {
60+
return {};
61+
}
62+
63+
const staticValue = utils.isUndefinedIdentifier(descriptionNode.value)
64+
? { value: undefined }
65+
: getStaticValue(descriptionNode.value);
66+
67+
if (staticValue && typeof staticValue.value !== 'boolean') {
68+
context.report({
69+
node: descriptionNode.value,
70+
messageId: 'incorrect',
71+
});
72+
return {};
73+
}
74+
75+
return {};
76+
},
77+
};

Diff for: ‎lib/rules/require-meta-docs-url.js

+14-23
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
// -----------------------------------------------------------------------------
1010

1111
const path = require('path');
12-
const util = require('../utils');
12+
const utils = require('../utils');
1313
const { getStaticValue } = require('eslint-utils');
1414

1515
// -----------------------------------------------------------------------------
@@ -77,7 +77,7 @@ module.exports = {
7777
}
7878

7979
const sourceCode = context.sourceCode || context.getSourceCode(); // TODO: just use context.sourceCode when dropping eslint < v9
80-
const ruleInfo = util.getRuleInfo(sourceCode);
80+
const ruleInfo = utils.getRuleInfo(sourceCode);
8181
if (!ruleInfo) {
8282
return {};
8383
}
@@ -87,16 +87,11 @@ module.exports = {
8787
const scope = sourceCode.getScope?.(ast) || context.getScope(); // TODO: just use sourceCode.getScope() when we drop support for ESLint < v9.0.0
8888
const { scopeManager } = sourceCode;
8989

90-
const metaNode = ruleInfo.meta;
91-
const docsPropNode = util
92-
.evaluateObjectProperties(metaNode, scopeManager)
93-
.find((p) => p.type === 'Property' && util.getKeyName(p) === 'docs');
94-
const urlPropNode = util
95-
.evaluateObjectProperties(
96-
docsPropNode && docsPropNode.value,
97-
scopeManager,
98-
)
99-
.find((p) => p.type === 'Property' && util.getKeyName(p) === 'url');
90+
const {
91+
docsNode,
92+
metaNode,
93+
metaPropertyNode: urlPropNode,
94+
} = utils.getMetaDocsProperty('url', ruleInfo, scopeManager);
10095

10196
const staticValue = urlPropNode
10297
? getStaticValue(urlPropNode.value, scope)
@@ -113,7 +108,7 @@ module.exports = {
113108
context.report({
114109
node:
115110
(urlPropNode && urlPropNode.value) ||
116-
(docsPropNode && docsPropNode.value) ||
111+
(docsNode && docsNode.value) ||
117112
metaNode ||
118113
ruleInfo.create,
119114

@@ -138,27 +133,23 @@ module.exports = {
138133
if (urlPropNode) {
139134
if (
140135
urlPropNode.value.type === 'Literal' ||
141-
(urlPropNode.value.type === 'Identifier' &&
142-
urlPropNode.value.name === 'undefined')
136+
utils.isUndefinedIdentifier(urlPropNode.value)
143137
) {
144138
return fixer.replaceText(urlPropNode.value, urlString);
145139
}
146-
} else if (
147-
docsPropNode &&
148-
docsPropNode.value.type === 'ObjectExpression'
149-
) {
150-
return util.insertProperty(
140+
} else if (docsNode && docsNode.value.type === 'ObjectExpression') {
141+
return utils.insertProperty(
151142
fixer,
152-
docsPropNode.value,
143+
docsNode.value,
153144
`url: ${urlString}`,
154145
sourceCode,
155146
);
156147
} else if (
157-
!docsPropNode &&
148+
!docsNode &&
158149
metaNode &&
159150
metaNode.type === 'ObjectExpression'
160151
) {
161-
return util.insertProperty(
152+
return utils.insertProperty(
162153
fixer,
163154
metaNode,
164155
`docs: {\nurl: ${urlString}\n}`,

Diff for: ‎lib/rules/require-meta-has-suggestions.js

+1-2
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,7 @@ module.exports = {
139139
fix(fixer) {
140140
if (
141141
hasSuggestionsProperty.value.type === 'Literal' ||
142-
(hasSuggestionsProperty.value.type === 'Identifier' &&
143-
hasSuggestionsProperty.value.name === 'undefined')
142+
utils.isUndefinedIdentifier(hasSuggestionsProperty.value)
144143
) {
145144
return fixer.replaceText(
146145
hasSuggestionsProperty.value,

Diff for: ‎lib/rules/require-meta-schema.js

+1-4
Original file line numberDiff line numberDiff line change
@@ -106,10 +106,7 @@ module.exports = {
106106
hasEmptySchema = true;
107107
}
108108

109-
if (
110-
value.type === 'Literal' ||
111-
(value.type === 'Identifier' && value.name === 'undefined')
112-
) {
109+
if (value.type === 'Literal' || utils.isUndefinedIdentifier(value)) {
113110
context.report({ node: value, messageId: 'wrongType' });
114111
}
115112
},

Diff for: ‎lib/utils.js

+28
Original file line numberDiff line numberDiff line change
@@ -832,6 +832,26 @@ module.exports = {
832832
});
833833
},
834834

835+
getMetaDocsProperty(propertyName, ruleInfo, scopeManager) {
836+
const metaNode = ruleInfo.meta;
837+
838+
const docsNode = module.exports
839+
.evaluateObjectProperties(metaNode, scopeManager)
840+
.find(
841+
(p) => p.type === 'Property' && module.exports.getKeyName(p) === 'docs',
842+
);
843+
844+
const metaPropertyNode = module.exports
845+
.evaluateObjectProperties(docsNode?.value, scopeManager)
846+
.find(
847+
(p) =>
848+
p.type === 'Property' &&
849+
module.exports.getKeyName(p) === propertyName,
850+
);
851+
852+
return { docsNode, metaNode, metaPropertyNode };
853+
},
854+
835855
/**
836856
* Get the `meta.messages` node from a rule.
837857
* @param {RuleInfo} ruleInfo
@@ -919,6 +939,14 @@ module.exports = {
919939
});
920940
},
921941

942+
/**
943+
* @param {Node} node
944+
* @returns {boolean} Whether the node is an Identifier with name `undefined`.
945+
*/
946+
isUndefinedIdentifier(node) {
947+
return node.type === 'Identifier' && node.name === 'undefined';
948+
},
949+
922950
/**
923951
* Check whether a variable's definition is from a function parameter.
924952
* @param {Node} node - the Identifier node for the variable.

0 commit comments

Comments
 (0)