8000 docs: check config comments in rule examples (#17815) · eslint/eslint@4391b71 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4391b71

Browse files
fasttimefasttime
authored
docs: check config comments in rule examples (#17815)
* docs: check config comments in rule examples * move `parseDirective` out of `SourceCode` * apply suggestions
1 parent fd28363 commit 4391b71

File tree

11 files changed

+120
-72
lines changed

11 files changed

+120
-72
lines changed

‎docs/src/rules/capitalized-comments.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Examples of **correct** code for this rule:
3333
:::correct
3434

3535
```js
36+
/* eslint capitalized-comments: error */
3637

3738
// Capitalized comment
3839

‎docs/src/rules/no-buffer-constructor.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ Examples of **incorrect** code for this rule:
2121
::: incorrect
2222

2323
```js
24+
/* eslint no-buffer-constructor: error */
25+
2426
new Buffer(5);
2527
new Buffer([1, 2, 3]);
2628

@@ -38,6 +40,8 @@ Examples of **correct** code for this rule:
3840
::: correct
3941

4042
```js
43+
/* eslint no-buffer-constructor: error */
44+
4145
Buffer.alloc(5);
4246
Buffer.allocUnsafe(5);
4347
Buffer.from([1, 2, 3]);

‎docs/src/rules/no-implicit-globals.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,7 @@ Examples of **correct** code for `/* exported variableName */` operation:
264264
::: correct { "sourceType": "script" }
265265

266266
```js
267+
/* eslint no-implicit-globals: error */
267268
/* exported global_var */
268269

269270
var global_var = 42;

‎docs/src/rules/strict.md‎

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -271,19 +271,13 @@ This option ensures that all functions are executed in strict mode. A strict mod
271271

272272
Examples of **incorrect** code for this rule with the earlier default option which has been removed:
273273

274-
::: incorrect { "sourceType": "script" }
275-
276274
```js
277275
// "strict": "error"
278276

279277
function foo() {
280278
}
281279
```
282280

283-
:::
284-
285-
::: incorrect { "sourceType": "script" }
286-
287281
```js
288282
// "strict": "error"
289283

@@ -294,12 +288,8 @@ function foo() {
294288
}());
295289
```
296290

297-
:::
298-
299291
Examples of **correct** code for this rule with the earlier default option which has been removed:
300292

301-
::: correct { "sourceType": "script" }
302-
303293
```js
304294
// "strict": "error"
305295

@@ -309,10 +299,6 @@ function foo() {
309299
}
310300
```
311301

312-
:::
313-
314-
::: correct { "sourceType": "script" }
315-
316302
```js
317303
// "strict": "error"
318304

@@ -321,10 +307,6 @@ function foo() {
321307
}
322308
```
323309

324-
:::
325-
326-
::: correct { "sourceType": "script" }
327-
328310
```js
329311
// "strict": "error"
330312

@@ -336,8 +318,6 @@ function foo() {
336318
}());
337319
```
338320

339-
:::
340-
341321
## When Not To Use It
342322

343323
In a codebase that has both strict and non-strict code, either turn this rule off, or [selectively disable it](../use/configure/rules#disabling-rules) where necessary. For example, functions referencing `arguments.callee` are invalid in strict mode. A [full list of strict mode differences](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode/Transitioning_to_strict_mode#Differences_from_non-strict_to_strict) is available on MDN.

‎lib/linter/config-comment-parser.js‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ const levn = require("levn"),
1515
Legacy: {
1616
ConfigOps
1717
}
18-
} = require("@eslint/eslintrc/universal");
18+
} = require("@eslint/eslintrc/universal"),
19+
{
20+
directivesPattern
21+
} = require("../shared/directives");
1922

2023
const debug = require("debug")("eslint:config-comment-parser");
2124

@@ -148,4 +151,35 @@ module.exports = class ConfigCommentParser {
148151
return items;
149152
}
150153

154+
/**
155+
* Extract the directive and the justification from a given directive comment and trim them.
156+
* @param {string} value The comment text to extract.
157+
* @returns {{directivePart: string, justificationPart: string}} The extracted directive and justification.
158+
*/
159+
extractDirectiveComment(value) {
160+
const match = /\s-{2,}\s/u.exec(value);
161+
162+
if (!match) {
163+
return { directivePart: value.trim(), justificationPart: "" };
164+
}
165+
166+
const directive = value.slice(0, match.index).trim();
167+
const justification = value.slice(match.index + match[0].length).trim();
168+
169+
return { directivePart: directive, justificationPart: justification };
170+
}
171+
172+
/**
173+
* Parses a directive comment into directive text and value.
174+
* @param {Comment} comment The comment node with the directive to be parsed.
175+
* @returns {{directiveText: string, directiveValue: string}} The directive text and value.
176+
*/
177+
parseDirective(comment) {
178+
const { directivePart } = this.extractDirectiveComment(comment.value);
179+
const match = directivesPattern.exec(directivePart);
180+
const directiveText = match[1];
181+
const directiveValue = directivePart.slice(match.index + directiveText.length);
182+
183+
return { directiveText, directiveValue };
184+
}
151185
};

‎lib/linter/linter.js‎

Lines changed: 3 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -316,24 +316,6 @@ function createDisableDirectives(options) {
316316
return result;
317317
}
318318

319-
/**
320-
* Extract the directive and the justification from a given directive comment and trim them.
321-
* @param {string} value The comment text to extract.
322-
* @returns {{directivePart: string, justificationPart: string}} The extracted directive and justification.
323-
*/
324-
function extractDirectiveComment(value) {
325-
const match = /\s-{2,}\s/u.exec(value);
326-
327-
if (!match) {
328-
return { directivePart: value.trim(), justificationPart: "" };
329-
}
330-
331-
const directive = value.slice(0, match.index).trim();
332-
const justification = value.slice(match.index + match[0].length).trim();
333-
334-
return { directivePart: directive, justificationPart: justification };
335-
}
336-
337319
/**
338320
* Parses comments in file to extract file-specific config of rules, globals
339321
* and environments and merges them with global config; also code blocks
@@ -355,7 +337,7 @@ function getDirectiveComments(sourceCode, ruleMapper, warnInlineConfig) {
355337
});
356338

357339
sourceCode.getInlineConfigNodes().filter(token => token.type !== "Shebang").forEach(comment => {
358-
const { directivePart, justificationPart } = extractDirectiveComment(comment.value);
340+
const { directivePart, justificationPart } = commentParser.extractDirectiveComment(comment.value);
359341

360342
const match = directivesPattern.exec(directivePart);
361343

@@ -500,7 +482,7 @@ function getDirectiveCommentsForFlatConfig(sourceCode, ruleMapper) {
500482
const disableDirectives = [];
501483

502484
sourceCode.getInlineConfigNodes().filter(token => token.type !== "Shebang").forEach(comment => {
503-
const { directivePart, justificationPart } = extractDirectiveComment(comment.value);
485+
const { directivePart, justificationPart } = commentParser.extractDirectiveComment(comment.value);
504486

505487
const match = directivesPattern.exec(directivePart);
506488

@@ -620,7 +602,7 @@ function findEslintEnv(text) {
620602
if (match[0].endsWith("*/")) {
621603
retv = Object.assign(
622604
retv || {},
623-
commentParser.parseListConfig(extractDirectiveComment(match[1]).directivePart)
605+
commentParser.parseListConfig(commentParser.extractDirectiveComment(match[1]).directivePart)
624606
);
625607
}
626608
}

‎lib/source-code/source-code.js‎

Lines changed: 2 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -212,24 +212,6 @@ function isSpaceBetween(sourceCode, first, second, checkInsideOfJSXText) {
212212
// Directive Comments
213213
//-----------------------------------------------------------------------------
214214

215-
/**
216-
* Extract the directive and the justification from a given directive comment and trim them.
217-
* @param {string} value The comment text to extract.
218-
* @returns {{directivePart: string, justificationPart: string}} The extracted directive and justification.
219-
*/
220-
function extractDirectiveComment(value) {
221-
const match = /\s-{2,}\s/u.exec(value);
222-
223-
if (!match) {
224-
return { directivePart: value.trim(), justificationPart: "" };
225-
}
226-
227-
const directive = value.slice(0, match.index).trim();
228-
const justification = value.slice(match.index + match[0].length).trim();
229-
230-
return { directivePart: directive, justificationPart: justification };
231-
}
232-
233215
/**
234216
* Ensures that variables representing built-in properties of the Global Object,
235217
* and any globals declared by special block comments, are present in the global
@@ -921,7 +903,7 @@ class SourceCode extends TokenStore {
921903
return false;
922904
}
923905

924-
const { directivePart } = extractDirectiveComment(comment.value);
906+
const { directivePart } = commentParser.extractDirectiveComment(comment.value);
925907

926908
const directiveMatch = directivesPattern.exec(directivePart);
927909

@@ -977,10 +959,7 @@ class SourceCode extends TokenStore {
977959

978960
this.getInlineConfigNodes().forEach(comment => {
979961

980-
const { directivePart } = extractDirectiveComment(comment.value);
981-
const match = directivesPattern.exec(directivePart);
982-
const directiveText = match[1];
983-
const directiveValue = directivePart.slice(match.index + directiveText.length);
962+
const { directiveText, directiveValue } = commentParser.parseDirective(comment);
984963

985964
switch (directiveText) {
986965
case "exported":

‎tests/fixtures/bad-examples.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Lorem Ipsum
2+
title: no-restricted-syntax
33
---
44

55
This file contains rule example code with syntax errors.
@@ -24,3 +24,11 @@ const foo = "baz";
2424
````
2525

2626
:::
27+
28+
:::correct
29+
30+
```js
31+
/* eslint another-rule: error */
32+
```
33+
34+
:::

‎tests/lib/linter/config-comment-parser.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,4 +248,28 @@ describe("ConfigCommentParser", () => {
248248
});
249249
});
250250

251+
describe("parseDirective", () => {
252+
253+
it("should parse a directive comment with a justification", () => {
254+
const comment = { value: " eslint no-unused-vars: error -- test " };
255+
const result = commentParser.parseDirective(comment);
256+
257+
assert.deepStrictEqual(result, {
258+
directiveText: "eslint",
259+
directiveValue: " no-unused-vars: error"
260+
});
261+
});
262+
263+
it("should parse a directive comment without a justification", () => {
264+
const comment = { value: "global foo" };
265+
const result = commentParser.parseDirective(comment);
266+
267+
assert.deepStrictEqual(result, {
268+
directiveText: "global",
269+
directiveValue: " foo"
270+
});
271+
});
272+
273+
});
274+
251275
});

‎tests/tools/check-rule-examples.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,9 @@ describe("check-rule-examples", () => {
6161
"\x1B[0m \x1B[2m12:1\x1B[22m \x1B[31merror\x1B[39m Syntax error: 'import' and 'export' may appear only with 'sourceType: module'\x1B[0m\n" +
6262
"\x1B[0m \x1B[2m20:5\x1B[22m \x1B[31merror\x1B[39m Nonstandard language tag 'ts': use one of 'javascript', 'js' or 'jsx'\x1B[0m\n" +
6363
"\x1B[0m \x1B[2m23:7\x1B[22m \x1B[31merror\x1B[39m Syntax error: Identifier 'foo' has already been declared\x1B[0m\n" +
64+
"\x1B[0m \x1B[2m31:1\x1B[22m \x1B[31merror\x1B[39m Example code should contain a configuration comment like /* eslint no-restricted-syntax: \"error\" */\x1B[0m\n" +
6465
"\x1B[0m\x1B[0m\n" +
65-
"\x1B[0m\x1B[31m\x1B[1m✖ 4 problems (4 errors, 0 warnings)\x1B[22m\x1B[39m\x1B[0m\n" +
66+
"\x1B[0m\x1B[31m\x1B[1m✖ 5 problems (5 errors, 0 warnings)\x1B[22m\x1B[39m\x1B[0m\n" +
6667
"\x1B[0m\x1B[31m\x1B[1m\x1B[22m\x1B[39m\x1B[0m\n"
6768
}
6869
);

0 commit comments

Comments
 (0)
0