@siim-m/config 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -14
- package/dist/anti-slop/rules/comments.d.ts +3 -4
- package/dist/anti-slop/rules/comments.js +59 -146
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -40,24 +40,23 @@ them too, and oxlint gives a rule no way to report that, so catch one in review.
|
|
|
40
40
|
|
|
41
41
|
## Comments
|
|
42
42
|
|
|
43
|
-
`anti-slop/comments`
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
43
|
+
`anti-slop/comments` keeps only the comments the code can't replace: directives, licence headers,
|
|
44
|
+
doc comments on exports, the reason above a suppression and comments that start with an `allow`
|
|
45
|
+
prefix. Each gets one line of at most 30 words (`maxWords`), and a doc comment that only repeats the
|
|
46
|
+
name below it is reported. The prefixes default to `SAFETY`, `SYNC` and `WARNING`. An `allow` list
|
|
47
|
+
replaces them, so keep `SAFETY` and `SYNC` in it: the type-assertion and React effect rules ask for
|
|
48
|
+
those.
|
|
49
|
+
|
|
50
|
+
A file whose exports need longer docs, such as a library's public API, turns on
|
|
51
|
+
`multilineExportDocs` in an override. The override replaces the rule's options, so repeat any others
|
|
52
|
+
you set:
|
|
48
53
|
|
|
49
54
|
```ts
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
}],
|
|
55
|
+
overrides: [
|
|
56
|
+
{ files: ['src/api.ts'], rules: { 'anti-slop/comments': ['error', { multilineExportDocs: true }] } },
|
|
57
|
+
],
|
|
54
58
|
```
|
|
55
59
|
|
|
56
|
-
`policy: 'tagged-only'` goes further: only directives, licence headers, doc comments on exports, the
|
|
57
|
-
reason above a suppression and comments that start with an `allow` prefix stay. The prefixes default
|
|
58
|
-
to `SAFETY`, `SYNC` and `WARNING`. An `allow` list replaces them, so keep `SAFETY` and `SYNC` in it:
|
|
59
|
-
the type-assertion and React effect rules ask for those.
|
|
60
|
-
|
|
61
60
|
## Tests and shortcuts
|
|
62
61
|
|
|
63
62
|
Ten rules from two npm packages report tests that pass whatever the code does or lean on time, and
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
* and comments that start with an allowed prefix such as `SAFETY:`.
|
|
2
|
+
* Keep only comments that carry what the code can't: directives, licence headers, docs on exports,
|
|
3
|
+
* the reason above a suppression and comments that start with an allowed prefix such as `SAFETY:`.
|
|
4
|
+
* Each gets one line, a word limit and no doc that only repeats the name below it.
|
|
6
5
|
*/
|
|
7
6
|
export declare const commentsRule: import("@oxlint/plugins").Rule;
|
|
@@ -3,19 +3,6 @@ const DIRECTIVE = /^(?:(?:oxlint|eslint)-(?:disable|enable|env)\b|eslint\s+[\w@/
|
|
|
3
3
|
const LICENSE = /@license\b|\bSPDX-License-Identifier\b/u;
|
|
4
4
|
const COPYRIGHT = /\bcopyright\b/iu;
|
|
5
5
|
const SUPPRESSION = /^\s*\*?\s*(?:(?:oxlint|eslint)-disable|@ts-(?:expect-error|ignore|nocheck))/u;
|
|
6
|
-
const URL = /\bhttps?:\/\/\S+/gu;
|
|
7
|
-
const CODE_SPAN = /`[^`]*`/gu;
|
|
8
|
-
const ISSUE = /(?<![\w&/])#\d+\b(?![a-f])/giu;
|
|
9
|
-
const DIVIDER = /^(?:[-=*#~_/+\u2500-\u257F]{3,}(?:\s.*)?|.*[-=*#~_\u2500-\u257F]{3,})$/u;
|
|
10
|
-
const STEP_LABEL = /^(?:arrange|act|assert|given|when|then)\s*[:.]?$/iu;
|
|
11
|
-
const TASK_MARKER = /\b(?:TODO|FIXME|HACK)\b|(?<!-)\bXXX\b(?!-)/u;
|
|
12
|
-
/** A markdown heading, which a doc comment may use: `### Example`. */
|
|
13
|
-
const HEADING = /^#{1,6}\s+\S/u;
|
|
14
|
-
const TASK_LINK = /#\d+|\b[A-Z][A-Z\d]*-\d+\b|https?:\/\//u;
|
|
15
|
-
const JSDOC_TYPE = /^@(?:param|returns?|type|typedef)\s+\{/u;
|
|
16
|
-
const EMPTY_JSDOC_TAG = /^@(?:param(?:\s+\[?[\w$.]+\]?)?|returns?)$/u;
|
|
17
|
-
const COMMENTED_CODE = /^(?:(?:(?:const|let|var)\s+[\w${}[\], ]+=.*|import\s.+\sfrom\s+["'].+["']|(?:await\s+|return\s+)?[\w$.]+\(.*\)|[\w$.[\]]+\s*=\s*.+);|(?:if|for|while|switch)\s*\(.*\)\s*\{|\}(?:\s*else\s*\{)?)$/u;
|
|
18
|
-
const TYPESCRIPT_FILE = /\.[cm]?tsx?$/u;
|
|
19
6
|
const FILLER = new Set('a an the of for to in on at by with from and or is are be this that it its as'.split(' '));
|
|
20
7
|
/** The words a comment or name carries once filler words go and plurals fold. */
|
|
21
8
|
const contentWords = (text) => (text.toLowerCase().match(/[a-z0-9]+/gu) ?? [])
|
|
@@ -23,6 +10,14 @@ const contentWords = (text) => (text.toLowerCase().match(/[a-z0-9]+/gu) ?? [])
|
|
|
23
10
|
.map((word) => (word.length > 3 ? word.replace(/([^s])s$/u, '$1') : word))
|
|
24
11
|
.filter((word) => !FILLER.has(word));
|
|
25
12
|
const nameWords = (name) => new Set(contentWords(name.replace(/([a-z0-9])([A-Z])/gu, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/gu, '$1 $2')));
|
|
13
|
+
/** Whether a doc says nothing but the words of the name it documents. */
|
|
14
|
+
function restatesName(lines, name) {
|
|
15
|
+
if (lines.some((line) => line.startsWith('@')))
|
|
16
|
+
return false;
|
|
17
|
+
const words = contentWords(lines.join(' '));
|
|
18
|
+
const fromName = nameWords(name);
|
|
19
|
+
return words.length > 0 && words.length <= 6 && words.every((word) => fromName.has(word));
|
|
20
|
+
}
|
|
26
21
|
const isDoc = (comment) => comment.type === 'Block' && comment.value.startsWith('*');
|
|
27
22
|
/** A comment's lines of prose: no doc-comment stars, blank lines or directives. */
|
|
28
23
|
const textLines = (comment) => {
|
|
@@ -110,6 +105,22 @@ function exportedStatements(program, sourceCode) {
|
|
|
110
105
|
}
|
|
111
106
|
/** The statement a doc comment for an exported node sits above. */
|
|
112
107
|
const docTarget = (node) => node.type === 'VariableDeclarator' && node.parent !== null ? node.parent : node;
|
|
108
|
+
/** The name a declaration or member declares, for the doc comment above it. */
|
|
109
|
+
function nameOf(node) {
|
|
110
|
+
let target = node;
|
|
111
|
+
if (target.type === 'ExportNamedDeclaration' || target.type === 'ExportDefaultDeclaration')
|
|
112
|
+
target = target.declaration;
|
|
113
|
+
if (target?.type === 'VariableDeclaration')
|
|
114
|
+
target = target.declarations[0] ?? null;
|
|
115
|
+
if (target === null)
|
|
116
|
+
return undefined;
|
|
117
|
+
const id = 'key' in target ? target.key : 'id' in target ? target.id : undefined;
|
|
118
|
+
if (id?.type === 'Identifier')
|
|
119
|
+
return id.name;
|
|
120
|
+
if (id?.type === 'Literal' && typeof id.value === 'string')
|
|
121
|
+
return id.value;
|
|
122
|
+
return undefined;
|
|
123
|
+
}
|
|
113
124
|
/**
|
|
114
125
|
* Whether a suppression directive follows a comment group on the next lines, past other
|
|
115
126
|
* directives, so the group is its reason, as `require-suppression-reason` reads it.
|
|
@@ -159,158 +170,66 @@ function isExposedMember(member, exported) {
|
|
|
159
170
|
}
|
|
160
171
|
}
|
|
161
172
|
/**
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
* and comments that start with an allowed prefix such as `SAFETY:`.
|
|
173
|
+
* Keep only comments that carry what the code can't: directives, licence headers, docs on exports,
|
|
174
|
+
* the reason above a suppression and comments that start with an allowed prefix such as `SAFETY:`.
|
|
175
|
+
* Each gets one line, a word limit and no doc that only repeats the name below it.
|
|
166
176
|
*/
|
|
167
177
|
export const commentsRule = defineRule({
|
|
168
178
|
meta: {
|
|
169
179
|
type: 'suggestion',
|
|
170
180
|
docs: {
|
|
171
|
-
description: '
|
|
181
|
+
description: 'Keep only tagged comments, docs on exports and suppression reasons, each on one line.',
|
|
172
182
|
},
|
|
173
183
|
schema: [
|
|
174
184
|
{
|
|
175
185
|
type: 'object',
|
|
176
186
|
properties: {
|
|
177
|
-
policy: { enum: ['budget', 'tagged-only'] },
|
|
178
187
|
maxWords: { type: 'integer', minimum: 1 },
|
|
179
|
-
|
|
188
|
+
multilineExportDocs: { type: 'boolean' },
|
|
180
189
|
allow: { type: 'array', items: { type: 'string', minLength: 1 } },
|
|
181
|
-
forbidden: {
|
|
182
|
-
type: 'array',
|
|
183
|
-
items: {
|
|
184
|
-
type: 'object',
|
|
185
|
-
properties: { pattern: { type: 'string' }, message: { type: 'string' } },
|
|
186
|
-
required: ['pattern', 'message'],
|
|
187
|
-
additionalProperties: false,
|
|
188
|
-
},
|
|
189
|
-
},
|
|
190
190
|
},
|
|
191
191
|
additionalProperties: false,
|
|
192
192
|
},
|
|
193
193
|
],
|
|
194
194
|
defaultOptions: [
|
|
195
195
|
{
|
|
196
|
-
policy: 'budget',
|
|
197
196
|
maxWords: 30,
|
|
198
|
-
|
|
197
|
+
multilineExportDocs: false,
|
|
199
198
|
allow: ['SAFETY', 'SYNC', 'WARNING'],
|
|
200
|
-
forbidden: [],
|
|
201
199
|
},
|
|
202
200
|
],
|
|
203
201
|
messages: {
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
commentedOutCode: 'Delete the commented-out code; git keeps it.',
|
|
210
|
-
restatesName: 'This comment only repeats the name below it. Say why, or say nothing.',
|
|
211
|
-
untrackedTask: 'Link the issue that tracks this, or drop the marker.',
|
|
212
|
-
jsdocType: 'Drop the JSDoc type; TypeScript has it.',
|
|
213
|
-
emptyJsdocTag: 'Drop the JSDoc tag that has no description.',
|
|
214
|
-
untagged: 'Remove this comment: put the meaning in names and the rationale in the PR. Comments that start with {{prefixes}}, directives and docs on exports stay.',
|
|
202
|
+
untagged: 'Remove this comment: put the meaning in names and the rationale in the PR. Comments that start with {{prefixes}}, directives, docs on exports and the reason above a suppression stay.',
|
|
203
|
+
multiLine: 'Keep this comment to one line. Leave the history to git and the PR.',
|
|
204
|
+
multiLineDoc: 'Keep this doc to one line. A file whose exports need longer docs sets `multilineExportDocs` in an override.',
|
|
205
|
+
tooLong: 'This comment has {{words}} words; the limit is {{max}}.',
|
|
206
|
+
restatesName: 'This doc only repeats the name below it. Say why, or say nothing.',
|
|
215
207
|
},
|
|
216
208
|
},
|
|
217
209
|
create(context) {
|
|
218
210
|
// SAFETY: oxlint validates the options against the schema above and fills in defaultOptions.
|
|
219
211
|
const [options] = context.options;
|
|
220
212
|
const { sourceCode } = context;
|
|
221
|
-
const typescript = TYPESCRIPT_FILE.test(context.filename);
|
|
222
|
-
const forbidden = options.forbidden.map(({ pattern, message }) => ({
|
|
223
|
-
pattern: new RegExp(pattern, 'u'),
|
|
224
|
-
message,
|
|
225
|
-
}));
|
|
226
213
|
const isTagged = (line) => options.allow.some((prefix) => line.startsWith(`${prefix}:`) && line.slice(prefix.length + 1).trim() !== '');
|
|
227
214
|
const prefixes = options.allow.map((prefix) => `\`${prefix}:\``).join(', ');
|
|
228
215
|
const members = [];
|
|
229
|
-
/** Declarations and members by where they start, for the name a comment sits above. */
|
|
230
|
-
const named = new Map();
|
|
231
|
-
const name = (node, id) => {
|
|
232
|
-
if (id?.type === 'Identifier')
|
|
233
|
-
named.set(node.start, id.name);
|
|
234
|
-
else if (id?.type === 'Literal' && typeof id.value === 'string')
|
|
235
|
-
named.set(node.start, id.value);
|
|
236
|
-
};
|
|
237
216
|
const collect = (node) => {
|
|
238
217
|
members.push(node);
|
|
239
|
-
if ('key' in node)
|
|
240
|
-
name(node, node.key);
|
|
241
|
-
else if ('id' in node)
|
|
242
|
-
name(node, node.id);
|
|
243
|
-
};
|
|
244
|
-
const declaration = (node) => {
|
|
245
|
-
if (node.type === 'VariableDeclaration')
|
|
246
|
-
name(node, node.declarations[0]?.id);
|
|
247
|
-
else if ('id' in node)
|
|
248
|
-
name(node, node.id);
|
|
249
|
-
};
|
|
250
|
-
const exported = (node) => {
|
|
251
|
-
const inner = node.declaration;
|
|
252
|
-
if (inner === null)
|
|
253
|
-
return;
|
|
254
|
-
if (inner.type === 'VariableDeclaration')
|
|
255
|
-
name(node, inner.declarations[0]?.id);
|
|
256
|
-
else if ('id' in inner)
|
|
257
|
-
name(node, inner.id);
|
|
258
|
-
};
|
|
259
|
-
const restatesName = (last, lines) => {
|
|
260
|
-
if (lines.some((line) => line.startsWith('@')))
|
|
261
|
-
return false;
|
|
262
|
-
// A trailing comment belongs to the code before it on its line.
|
|
263
|
-
const before = (sourceCode.lines[last.loc.start.line - 1] ?? '').slice(0, last.loc.start.column);
|
|
264
|
-
if (before.trim() !== '')
|
|
265
|
-
return false;
|
|
266
|
-
const next = sourceCode.getTokenAfter(last);
|
|
267
|
-
const name = next === null ? undefined : named.get(next.start);
|
|
268
|
-
if (name === undefined)
|
|
269
|
-
return false;
|
|
270
|
-
const words = contentWords(lines.join(' '));
|
|
271
|
-
const fromName = nameWords(name);
|
|
272
|
-
return words.length > 0 && words.length <= 6 && words.every((word) => fromName.has(word));
|
|
273
218
|
};
|
|
274
219
|
/** The first problem with a comment, as a message id and its data. */
|
|
275
|
-
const problem = (
|
|
276
|
-
|
|
277
|
-
const body = lines.join('\n');
|
|
278
|
-
const prose = body.replace(URL, '');
|
|
279
|
-
if (options.policy === 'tagged-only' &&
|
|
280
|
-
!exportDoc &&
|
|
281
|
-
!explainsSuppression &&
|
|
282
|
-
!isTagged(lines[0] ?? '')) {
|
|
220
|
+
const problem = (lines, kind, name) => {
|
|
221
|
+
if (kind === 'other' && !isTagged(lines[0] ?? ''))
|
|
283
222
|
return ['untagged', { prefixes }];
|
|
223
|
+
const exempt = kind === 'exportDoc' && options.multilineExportDocs;
|
|
224
|
+
if (!exempt) {
|
|
225
|
+
if (lines.length > 1)
|
|
226
|
+
return [kind === 'exportDoc' ? 'multiLineDoc' : 'multiLine'];
|
|
227
|
+
const words = lines.join(' ').split(/\s+/u).filter((word) => word !== '').length;
|
|
228
|
+
if (words > options.maxWords)
|
|
229
|
+
return ['tooLong', { words, max: options.maxWords }];
|
|
284
230
|
}
|
|
285
|
-
|
|
286
|
-
if (lines.some((line) => DIVIDER.test(line) && !(isDoc && HEADING.test(line))))
|
|
287
|
-
return ['divider'];
|
|
288
|
-
if (isLine && lines.length === 1 && STEP_LABEL.test(body))
|
|
289
|
-
return ['stepLabel'];
|
|
290
|
-
if (isLine && lines.every((line) => COMMENTED_CODE.test(line)))
|
|
291
|
-
return ['commentedOutCode'];
|
|
292
|
-
if (TASK_MARKER.test(body) && !TASK_LINK.test(body))
|
|
293
|
-
return ['untrackedTask'];
|
|
294
|
-
const issues = new Set(prose.replace(CODE_SPAN, '').match(ISSUE) ?? []);
|
|
295
|
-
if (issues.size > 1)
|
|
296
|
-
return ['issueChain', { count: issues.size }];
|
|
297
|
-
if (typescript && lines.some((line) => JSDOC_TYPE.test(line)))
|
|
298
|
-
return ['jsdocType'];
|
|
299
|
-
const describedLater = (index) => (lines[index + 1] ?? '@').startsWith('@') === false;
|
|
300
|
-
if (lines.some((line, index) => EMPTY_JSDOC_TAG.test(line) && !describedLater(index)))
|
|
301
|
-
return ['emptyJsdocTag'];
|
|
302
|
-
const last = group.at(-1);
|
|
303
|
-
if (last !== undefined && restatesName(last, lines))
|
|
231
|
+
if (name !== undefined && restatesName(lines, name))
|
|
304
232
|
return ['restatesName'];
|
|
305
|
-
const words = body.split(/\s+/u).filter((word) => word !== '').length;
|
|
306
|
-
const max = exportDoc ? options.maxExportDocWords : options.maxWords;
|
|
307
|
-
if (words > max)
|
|
308
|
-
return ['tooLong', { words, max }];
|
|
309
|
-
for (const { pattern, message } of forbidden) {
|
|
310
|
-
const match = pattern.exec(prose)?.[0];
|
|
311
|
-
if (match !== undefined)
|
|
312
|
-
return ['forbidden', { match, message }];
|
|
313
|
-
}
|
|
314
233
|
return undefined;
|
|
315
234
|
};
|
|
316
235
|
return {
|
|
@@ -323,28 +242,20 @@ export const commentsRule = defineRule({
|
|
|
323
242
|
PropertyDefinition: collect,
|
|
324
243
|
MethodDefinition: collect,
|
|
325
244
|
Property: collect,
|
|
326
|
-
VariableDeclaration: declaration,
|
|
327
|
-
FunctionDeclaration: declaration,
|
|
328
|
-
ClassDeclaration: declaration,
|
|
329
|
-
TSDeclareFunction: declaration,
|
|
330
|
-
TSInterfaceDeclaration: declaration,
|
|
331
|
-
TSTypeAliasDeclaration: declaration,
|
|
332
|
-
TSEnumDeclaration: declaration,
|
|
333
|
-
ExportNamedDeclaration: exported,
|
|
334
|
-
ExportDefaultDeclaration: exported,
|
|
335
245
|
'Program:exit'(program) {
|
|
336
246
|
const exportedNodes = exportedStatements(program, sourceCode);
|
|
337
|
-
|
|
338
|
-
const
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
247
|
+
/** Export docs by where they start, with the name each documents: the first, when one declaration exports several. */
|
|
248
|
+
const exportDocs = new Map();
|
|
249
|
+
const addDoc = (target, name) => {
|
|
250
|
+
const doc = docBefore(target, sourceCode);
|
|
251
|
+
if (doc !== undefined && !exportDocs.has(doc.start))
|
|
252
|
+
exportDocs.set(doc.start, name);
|
|
342
253
|
};
|
|
343
254
|
for (const node of exportedNodes)
|
|
344
|
-
addDoc(docTarget(node));
|
|
255
|
+
addDoc(docTarget(node), nameOf(node));
|
|
345
256
|
for (const member of members)
|
|
346
257
|
if (isExposedMember(member, exportedNodes))
|
|
347
|
-
addDoc(member);
|
|
258
|
+
addDoc(member, nameOf(member));
|
|
348
259
|
const codeStart = program.body[0]?.start ?? sourceCode.text.length;
|
|
349
260
|
const groups = commentGroups(sourceCode.getAllComments(), sourceCode.text);
|
|
350
261
|
const ownLine = (comment) => (sourceCode.lines[comment.loc.start.line - 1] ?? '')
|
|
@@ -361,10 +272,12 @@ export const commentsRule = defineRule({
|
|
|
361
272
|
const lines = group.flatMap(textLines);
|
|
362
273
|
if (licence || lines.length === 0)
|
|
363
274
|
continue;
|
|
364
|
-
const
|
|
365
|
-
|
|
366
|
-
suppressionFollows(groups, index, ownLine)
|
|
367
|
-
|
|
275
|
+
const kind = exportDocs.has(first.start)
|
|
276
|
+
? 'exportDoc'
|
|
277
|
+
: ownLine(first) && suppressionFollows(groups, index, ownLine)
|
|
278
|
+
? 'reason'
|
|
279
|
+
: 'other';
|
|
280
|
+
const found = problem(lines, kind, exportDocs.get(first.start));
|
|
368
281
|
if (found === undefined)
|
|
369
282
|
continue;
|
|
370
283
|
const [messageId, data] = found;
|
package/package.json
CHANGED