@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 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` holds a comment to a short why. By default a comment gets 30 words, a doc
44
- comment on an export 45, and it may cite one issue. It also reports section dividers, test step
45
- labels, commented-out code, TODOs without a link, JSDoc types in TypeScript, empty `@param` and
46
- `@returns` (or `@return`) tags, and comments that only repeat the name below them. `forbidden` adds
47
- patterns of your own:
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
- 'anti-slop/comments': ['error', {
51
- maxWords: 30,
52
- forbidden: [{ pattern: '\\b\\d{4}-\\d{2}-\\d{2}\\b', message: 'Leave dates to git.' }],
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
- * Hold comments to a short why: a word budget, at most one cited issue, configured patterns, and
3
- * no dividers, step labels, commented-out code, untracked TODOs, JSDoc types or comments that only
4
- * repeat the name below them. `tagged-only` keeps just directives, licence headers, docs on exports
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
- * Hold comments to a short why: a word budget, at most one cited issue, configured patterns, and
163
- * no dividers, step labels, commented-out code, untracked TODOs, JSDoc types or comments that only
164
- * repeat the name below them. `tagged-only` keeps just directives, licence headers, docs on exports
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: 'Hold comments to a short why, or with the tagged-only policy, to tagged comments and docs on exports.',
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
- maxExportDocWords: { type: 'integer', minimum: 1 },
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
- maxExportDocWords: 45,
197
+ multilineExportDocs: false,
199
198
  allow: ['SAFETY', 'SYNC', 'WARNING'],
200
- forbidden: [],
201
199
  },
202
200
  ],
203
201
  messages: {
204
- tooLong: "This comment has {{words}} words; the limit is {{max}}. Keep the why the code can't say, and leave the history to git and the PR.",
205
- issueChain: 'This comment cites {{count}} issues. Cite the one that decided the code; git has the rest.',
206
- forbidden: 'This comment has `{{match}}` in it. {{message}}',
207
- divider: "Drop the section divider. Split the file, or let the code's structure show the grouping.",
208
- stepLabel: 'Drop the test step label.',
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 = (group, lines, exportDoc, explainsSuppression) => {
276
- const isLine = group[0]?.type === 'Line';
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
- const isDoc = group[0]?.type === 'Block' && group[0].value.startsWith('*');
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
- const exportDocs = new Set();
338
- const addDoc = (node) => {
339
- const doc = docBefore(node, sourceCode);
340
- if (doc !== undefined)
341
- exportDocs.add(doc.start);
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 explainsSuppression = options.policy === 'tagged-only' &&
365
- ownLine(first) &&
366
- suppressionFollows(groups, index, ownLine);
367
- const found = problem(group, lines, group.length === 1 && exportDocs.has(first.start), explainsSuppression);
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@siim-m/config",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Shared oxlint, oxfmt and tsconfig settings, with the anti-slop oxlint plugins and a React preset",
5
5
  "license": "MIT",
6
6
  "repository": "github:siim-m/config",