@tcy/eslint-rules 1.10.0-beta.1 → 1.10.0-beta.2

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.
Files changed (40) hide show
  1. package/README.md +540 -6
  2. package/coverage/clover.xml +90 -75
  3. package/coverage/coverage-final.json +1 -1
  4. package/coverage/lcov-report/index.html +19 -19
  5. package/coverage/lcov-report/src/array-elements-per-line.js.html +1 -1
  6. package/coverage/lcov-report/src/back/back.js.html +1 -1
  7. package/coverage/lcov-report/src/back/http.js.html +1 -1
  8. package/coverage/lcov-report/src/back/index.html +1 -1
  9. package/coverage/lcov-report/src/back/recommended.js.html +1 -1
  10. package/coverage/lcov-report/src/bin/eslint-cache-guard.js.html +1 -1
  11. package/coverage/lcov-report/src/bin/index.html +1 -1
  12. package/coverage/lcov-report/src/client/client.js.html +1 -1
  13. package/coverage/lcov-report/src/client/index.html +1 -1
  14. package/coverage/lcov-report/src/client/recommended.js.html +1 -1
  15. package/coverage/lcov-report/src/consistent-const-scoping.js.html +237 -12
  16. package/coverage/lcov-report/src/decorator-type-enforcement.js.html +1 -1
  17. package/coverage/lcov-report/src/enforce-tailwind-important.js.html +1 -1
  18. package/coverage/lcov-report/src/export-specifiers-per-line.js.html +1 -1
  19. package/coverage/lcov-report/src/import-specifiers-per-line.js.html +1 -1
  20. package/coverage/lcov-report/src/index.html +20 -20
  21. package/coverage/lcov-report/src/index.js.html +1 -1
  22. package/coverage/lcov-report/src/jsx-boolean-shorthand.js.html +1 -1
  23. package/coverage/lcov-report/src/jsx-expression-string-literals.js.html +1 -1
  24. package/coverage/lcov-report/src/jsx-ref-string-exists.js.html +1 -1
  25. package/coverage/lcov-report/src/no-static-key-in-map.js.html +1 -1
  26. package/coverage/lcov-report/src/plugin.js.html +1 -1
  27. package/coverage/lcov-report/src/recommended.js.html +1 -1
  28. package/coverage/lcov-report/src/require-fragment-key.js.html +1 -1
  29. package/coverage/lcov-report/src/route-dto-required.js.html +1 -1
  30. package/coverage/lcov-report/src/v-model-name-match.js.html +1 -1
  31. package/coverage/lcov-report/src/vuejs-define-component.js.html +1 -1
  32. package/coverage/lcov-report/src/vuejs-define-workspace.js.html +1 -1
  33. package/coverage/lcov.info +248 -203
  34. package/decl/back/back.d.ts +14 -1
  35. package/decl/client/client.d.ts +14 -1
  36. package/decl/consistent-const-scoping.d.ts +37 -1
  37. package/decl/plugin.d.ts +14 -1
  38. package/package.json +1 -1
  39. package/src/consistent-const-scoping.js +76 -1
  40. package/tests/consistent-const-scoping.spec.js +50 -1
package/README.md CHANGED
@@ -1,25 +1,559 @@
1
- # Custom rules
1
+ # ESLint Custom Rules Documentation
2
2
 
3
+ This document provides detailed information about all custom ESLint rules included in this package.
4
+
5
+ The plugin ships two bundles — `tcy@eslint-rules/back` and `tcy@eslint-rules/client` — each enabling a different subset of rules by default (see [Usage](#usage)). Both bundles register the *full* rule set under `plugins.tcy.rules`, so any rule can still be turned on manually even if its bundle doesn't enable it by default.
6
+
7
+ ## Rules Overview
8
+
9
+ ### Shared rules (enabled by both `back` and `client`)
10
+
11
+ | Rule Name | Type | Description |
12
+ |-----------|------|-------------|
13
+ | `import-specifiers-per-line` | Layout | Enforce one import specifier per line when there are more than 4 specifiers |
14
+ | `export-specifiers-per-line` | Layout | Enforce one export specifier per line when there are more than 4 specifiers |
15
+ | `array-elements-per-line` | Layout | Enforce one array element per line when the array is multiline |
16
+ | `consistent-const-scoping` | Suggestion | Disallow a `const` inside a function when its value does not depend on that function's scope |
17
+
18
+ ### Backend-only rules (`tcy@eslint-rules/back`)
19
+
20
+ | Rule Name | Type | Description |
21
+ |-----------|------|-------------|
22
+ | `route-dto-required` | Problem | Enforce Dto declaration in `@route` decorator when a Dto is used as a method parameter |
23
+
24
+ ### Client-only rules (`tcy@eslint-rules/client`)
25
+
26
+ | Rule Name | Type | Description |
27
+ |-----------|------|-------------|
28
+ | `jsx-expression-string-literals` | Suggestion | Enforce string literals instead of string expressions in JSX |
29
+ | `jsx-boolean-shorthand` | Suggestion | Enforce shorthand boolean syntax in JSX props |
30
+ | `jsx-ref-string-exists` | Problem | Ensure a string ref (`ref="name"`) exists on the render function's first parameter type |
31
+ | `enforce-tailwind-important` | Layout | Enforce Tailwind classes end with the `!` important modifier |
32
+ | `v-model-name-match` | Suggestion | Enforce v-model name matching variable names |
33
+ | `vuejs-define-component` | Layout | Enforce use of `defineComponent` for Vue components |
34
+ | `vuejs-define-workspace` | Problem | Require a `route` property in `defineComponent` for `Workspace*` / `Page*` files |
35
+ | `require-fragment-key` | Problem | Require a `key` on a Fragment only where an un-keyed children diff can misalign |
36
+ | `no-static-key-in-map` | Problem | Disallow a static `key` on the root element returned from `.map()` / `.flatMap()` |
37
+
38
+ ### Other rules (registered, but not enabled by either bundle by default)
39
+
40
+ | Rule Name | Type | Description |
41
+ |-----------|------|-------------|
42
+ | `decorator-type-enforcement` | Problem | Enforce a property's type based on its `@boolean` / `@dbIntBoolean` decorator |
43
+
44
+ > `decorator-type-enforcement` is exported by the plugin but isn't listed in either `src/back/back.js` or `src/client/client.js` — turn it on explicitly (see [Usage](#usage)) if you want it.
45
+
46
+ ## Rule Details
47
+
48
+ ### Shared rules
49
+
50
+ #### 1. import-specifiers-per-line
51
+
52
+ **Type:** Layout
53
+
54
+ **Description:** Enforces one import specifier per line when there are more than 4 specifiers.
55
+
56
+ **Options:**
57
+ - `maxSpecifiers` (number, default: 4) - Maximum number of specifiers before enforcing line separation
58
+ - `maxLen` (number, optional) - Maximum line length before enforcing line separation
59
+
60
+ **Examples:**
61
+
62
+ Valid:
63
+ ```javascript
64
+ import { a } from 'module';
65
+ import { a, b } from 'module';
66
+ import {
67
+ a,
68
+ b,
69
+ c,
70
+ d,
71
+ } from 'module';
72
+ ```
73
+
74
+ Invalid:
75
+ ```javascript
76
+ import { a, b, c, d, e } from 'module';
77
+ ```
78
+
79
+ Automatically fixes to:
80
+ ```javascript
81
+ import {
82
+ a,
83
+ b,
84
+ c,
85
+ d,
86
+ e,
87
+ } from 'module';
88
+ ```
89
+
90
+ #### 2. export-specifiers-per-line
91
+
92
+ **Type:** Layout
93
+
94
+ **Description:** Enforces one export specifier per line when there are more than 4 specifiers.
95
+
96
+ **Examples:**
97
+
98
+ Valid:
99
+ ```javascript
100
+ export { a };
101
+ export { a, b };
102
+ export {
103
+ a,
104
+ b,
105
+ c,
106
+ d,
107
+ };
108
+ ```
109
+
110
+ Invalid:
111
+ ```javascript
112
+ export { a, b, c, d, e };
113
+ ```
114
+
115
+ Automatically fixes to:
116
+ ```javascript
117
+ export {
118
+ a,
119
+ b,
120
+ c,
121
+ d,
122
+ e,
123
+ };
124
+ ```
125
+
126
+ #### 3. array-elements-per-line
127
+
128
+ **Type:** Layout
129
+
130
+ **Description:** Enforces one array element per line when the first element is on a new line.
131
+
132
+ **Examples:**
133
+
134
+ Valid:
135
+ ```javascript
136
+ const arr = [1, 2, 3];
137
+ const arr = [
138
+ 1,
139
+ 2,
140
+ 3,
141
+ ];
142
+ ```
143
+
144
+ Invalid:
145
+ ```javascript
146
+ const arr = [
147
+ 1, 2, 3,
148
+ ];
149
+ ```
150
+
151
+ Automatically fixes to:
152
+ ```javascript
153
+ const arr = [
154
+ 1,
155
+ 2,
156
+ 3,
157
+ ];
158
+ ```
159
+
160
+ #### 4. consistent-const-scoping
161
+
162
+ **Type:** Suggestion
163
+
164
+ **Description:** Disallows a `const` declared inside a function when its (side-effect-free) initializer does not depend on that function's parameters, locals, `this`, `super`, or `arguments` — such a value is rebuilt identically on every call, so it should be declared outside the function instead.
165
+
166
+ **Options:**
167
+ - `types` (array, default: `['arrow-function']`) - which shapes of initializer to flag: `'primitive'`, `'template-literal'`, `'expression'` (identifier / unary / binary / logical / conditional / member access), `'array'`, `'object'`, `'arrow-function'`, `'function-expression'`
168
+
169
+ **Examples:**
170
+
171
+ Valid:
172
+ ```javascript
173
+ const hello = () => console.log('hello');
174
+ function makeGreeter() {
175
+ return { hello };
176
+ }
177
+
178
+ function makeGreeter(name) {
179
+ // depends on a param — stays put
180
+ const hello = () => console.log(`hello ${name}`);
181
+ return { hello };
182
+ }
183
+ ```
184
+
185
+ Invalid:
186
+ ```javascript
187
+ function makeGreeter() {
188
+ const hello = () => console.log('hello'); // recreated every call
189
+ return { hello };
190
+ }
191
+ ```
192
+
193
+ ### Backend-only rules
194
+
195
+ #### 1. route-dto-required
196
+
197
+ **Type:** Problem
198
+
199
+ **Description:** Enforces that a Dto used as a method parameter is also declared in that method's `@route` decorator, either as the second argument or as the `dto` property of the options object.
200
+
201
+ **Examples:**
202
+
203
+ Valid:
204
+ ```typescript
205
+ class UserController {
206
+ @route('/users', CreateUserDto)
207
+ create(body: CreateUserDto) {}
208
+
209
+ @route({ path: '/users', dto: CreateUserDto })
210
+ update(body: CreateUserDto) {}
211
+ }
212
+ ```
213
+
214
+ Invalid:
3
215
  ```typescript
216
+ class UserController {
217
+ @route('/users')
218
+ create(body: CreateUserDto) {}
219
+ }
220
+ ```
221
+
222
+ ### Client-only rules
223
+
224
+ #### 1. jsx-expression-string-literals
225
+
226
+ **Type:** Suggestion
227
+
228
+ **Description:** Enforces string literals instead of string expressions in JSX.
229
+
230
+ **Examples:**
231
+
232
+ Valid:
233
+ ```javascript
234
+ <Component title="hello" />
235
+ <Component title={someVariable} />
236
+ ```
237
+
238
+ Invalid:
239
+ ```javascript
240
+ <Component title={'hello'} />
241
+ ```
242
+
243
+ Automatically fixes to:
244
+ ```javascript
245
+ <Component title="hello" />
246
+ ```
247
+
248
+ #### 2. jsx-boolean-shorthand
249
+
250
+ **Type:** Suggestion
251
+
252
+ **Description:** Enforces shorthand boolean syntax in JSX props.
253
+
254
+ **Examples:**
255
+
256
+ Valid:
257
+ ```javascript
258
+ <Component disabled />
259
+ <Component disabled={false} />
260
+ <Component disabled={someCondition} />
261
+ ```
262
+
263
+ Invalid:
264
+ ```javascript
265
+ <Component disabled={true} />
266
+ ```
267
+
268
+ Automatically fixes to:
269
+ ```javascript
270
+ <Component disabled />
271
+ ```
272
+
273
+ #### 3. jsx-ref-string-exists
274
+
275
+ **Type:** Problem
276
+
277
+ **Description:** Ensures string refs in TSX (`ref="name"`) exist as properties on the render function's first parameter type. Requires type information — set `parserOptions.projectService` (or `project`) in your ESLint config, otherwise every string ref is flagged with a `noServices` warning instead.
278
+
279
+ **Examples:**
280
+
281
+ Valid:
282
+ ```tsx
283
+ function MyComponent(props: { myRef: unknown }) {
284
+ return <div ref="myRef" />;
285
+ }
286
+ ```
287
+
288
+ Invalid:
289
+ ```tsx
290
+ function MyComponent(props: { other: unknown }) {
291
+ return <div ref="myRef" />;
292
+ }
293
+ ```
294
+
295
+ #### 4. enforce-tailwind-important
296
+
297
+ **Type:** Layout
298
+
299
+ **Description:** Enforces every Tailwind utility class to end with the `!` important modifier (e.g. `text-red-500!`) — this is Tailwind's own suffix syntax, not CSS's `!important`. Each whitespace-separated class token is checked independently. Checks JSX `class`/`className` attributes — plain string literals as well as expressions built from them (arrays, object keys, template literals, conditional/logical expressions) — and `const xxxClass`/`xxxCls = '...'` variable declarations.
300
+
301
+ **Options:**
302
+ - `ignore` (array, optional) - extra class names that are allowed to stay without the `!` modifier, on top of the defaults (`row`, `no-gutters`, `container`, `container-fluid` — non-Tailwind, Bootstrap-style grid classes that would silently stop matching any CSS rule if suffixed).
303
+
304
+ **Examples:**
305
+
306
+ Valid:
307
+ ```jsx
308
+ <div className="text-red-500! p-4!" />
309
+ <div className={cond ? 'text-red-500!' : 'text-blue-500!'} />
310
+ const cardCls = 'rounded-lg! shadow!';
311
+ ```
312
+
313
+ With `{ ignore: ['my-legacy-class'] }`:
314
+ ```jsx
315
+ <div className="my-legacy-class text-red-500!" />
316
+ ```
317
+
318
+ Invalid:
319
+ ```jsx
320
+ <div className="text-red-500 p-4" />
321
+ const cardCls = 'rounded-lg shadow';
322
+ ```
323
+
324
+ Automatically fixes to:
325
+ ```jsx
326
+ <div className="text-red-500! p-4!" />
327
+ const cardCls = 'rounded-lg! shadow!';
328
+ ```
329
+
330
+ #### 5. v-model-name-match
331
+
332
+ **Type:** Suggestion
333
+
334
+ **Description:** Enforces v-model name matching variable names.
335
+
336
+ **Examples:**
337
+
338
+ Valid:
339
+ ```javascript
340
+ <input v-model="value" />
341
+ <input v-model="formData.value" />
342
+ ```
343
+
344
+ Invalid:
345
+ ```javascript
346
+ <input v-model="value" />
347
+ ```
348
+
349
+ #### 6. vuejs-define-component
350
+
351
+ **Type:** Layout
352
+
353
+ **Description:** Enforces use of `defineComponent` for Vue components.
354
+
355
+ **Examples:**
356
+
357
+ Valid:
358
+ ```javascript
359
+ export default defineComponent({});
360
+ export default {
361
+ name: 'MyComponent',
362
+ };
363
+ ```
364
+
365
+ Invalid:
366
+ ```javascript
367
+ export default {
368
+ name: 'MyComponent',
369
+ };
370
+ ```
371
+
372
+ Automatically fixes to:
373
+ ```javascript
374
+ export default defineComponent({
375
+ name: 'MyComponent',
376
+ });
377
+ ```
378
+
379
+ #### 7. vuejs-define-workspace
380
+
381
+ **Type:** Problem
382
+
383
+ **Description:** Requires a `route` property in the `defineComponent({ ... })` object exported by default from any file whose basename starts with `Workspace` or `Page` (e.g. `WorkspaceSettings.vue.ts`, `PageHome.tsx`). Files that don't match that naming pattern are not checked at all. There is no autofix — the rule can't infer what the route path should be.
384
+
385
+ **Examples:**
386
+
387
+ Valid (`WorkspaceSettings.vue.ts`):
388
+ ```javascript
389
+ export default defineComponent({
390
+ route: { path: '/settings' },
391
+ name: 'WorkspaceSettings',
392
+ });
393
+ ```
394
+
395
+ Invalid (`WorkspaceSettings.vue.ts`):
396
+ ```javascript
397
+ export default defineComponent({
398
+ name: 'WorkspaceSettings',
399
+ });
400
+ ```
401
+
402
+ Not checked at all (filename doesn't start with `Workspace`/`Page`):
403
+ ```javascript
404
+ // Settings.vue.ts
405
+ export default defineComponent({
406
+ name: 'Settings',
407
+ });
408
+ ```
409
+
410
+ #### 8. require-fragment-key
411
+
412
+ **Type:** Problem
413
+
414
+ **Description:** Requires a `key` on a Fragment (`<>…</>` or `<Fragment>`) only in the positions where an un-keyed children diff can actually misalign at runtime: a list item (`.map`/`.flatMap`) or a conditional sibling sharing a child list with another dynamically-rendered sibling. Stays silent for a sole return/child or a static sibling, where no key is needed.
415
+
416
+ **Options:**
417
+ - `strict` (boolean, default: `true`) - when `true`, a conditional sibling only requires a key if at least one other sibling in the same list is also dynamically rendered (another conditional or a `.map`)
418
+
419
+ **Examples:**
420
+
421
+ Valid:
422
+ ```jsx
423
+ // sole return — no key needed
424
+ const Comp = () => <>{children}</>;
425
+
426
+ // already keyed
427
+ list.map((item) => <Fragment key={item.id}>{item.label}</Fragment>);
428
+ ```
429
+
430
+ Invalid:
431
+ ```jsx
432
+ list.map((item) => <>{item.label}</>);
433
+
434
+ <div>
435
+ {cond && <>{a}</>}
436
+ {otherCond && <span>{b}</span>}
437
+ </div>
438
+ ```
439
+
440
+ #### 9. no-static-key-in-map
441
+
442
+ **Type:** Problem
443
+
444
+ **Description:** Disallows a static `key` (a string / number / boolean literal, or a template literal with no interpolation) on the root element returned from a `.map()` / `.flatMap()` callback — every iteration would render the same key, so the list is diffed by position instead of identity.
445
+
446
+ **Examples:**
447
+
448
+ Valid:
449
+ ```jsx
450
+ list.map((item) => <Row key={item.id} />);
451
+ list.map((item, i) => <Row key={i} />);
452
+ ```
453
+
454
+ Invalid:
455
+ ```jsx
456
+ list.map((item) => <Row key="row" />);
457
+ list.map(() => <Fragment key="rows">…</Fragment>);
458
+ ```
459
+
460
+ ### Other rules
461
+
462
+ #### 1. decorator-type-enforcement
463
+
464
+ **Type:** Problem
465
+
466
+ **Description:** Enforces a decorated class property's TypeScript type based on which decorator it carries:
467
+ - `@boolean` — the property's type must be exactly `boolean` (auto-fixed by replacing the type).
468
+ - `@dbIntBoolean` — the property's type must be (or include, in a union) `number` or `boolean` — modeling a DB column stored as an int-backed boolean.
469
+
470
+ > **Note:** in the current implementation, the `@dbIntBoolean` autofix always rewrites the type to `boolean`, even though the reported message says the type "must be of type `number`" — this looks like a leftover bug in the rule rather than intended behavior. Flagging it here rather than silently documenting it as correct; happy to fix the rule if you want.
471
+
472
+ **Examples:**
473
+
474
+ Valid:
475
+ ```typescript
476
+ class Entity {
477
+ @boolean
478
+ isActive: boolean;
479
+
480
+ @dbIntBoolean
481
+ isEnabled: number;
482
+
483
+ @dbIntBoolean
484
+ isEnabled: number | boolean;
485
+ }
486
+ ```
487
+
488
+ Invalid:
489
+ ```typescript
490
+ class Entity {
491
+ @boolean
492
+ isActive: string;
493
+
494
+ @dbIntBoolean
495
+ isEnabled: string;
496
+ }
497
+ ```
498
+
499
+ Automatically fixes `@boolean` mismatches to:
500
+ ```typescript
501
+ class Entity {
502
+ @boolean
503
+ isActive: boolean;
504
+ }
505
+ ```
506
+
507
+ ## Usage
508
+
509
+ ### Backend
510
+
511
+ ```javascript
512
+ import backCustomRules from 'tcy@eslint-rules/back';
513
+
514
+ const backConfig = [
515
+ backCustomRules,
516
+ {
517
+ files: ['**/*.+(ts|tsx|mts|cts)'],
518
+ rules: {
519
+ // `types`: which initializer shapes to flag; defaults to `['arrow-function']`.
520
+ 'tcy/consistent-const-scoping': ['error', { types: ['arrow-function', 'primitive'] }],
521
+ // registered by the plugin but not enabled by `back` — opt in explicitly:
522
+ 'tcy/decorator-type-enforcement': 'error',
523
+ },
524
+ },
525
+ ];
526
+
527
+ export default [
528
+ ...backConfig,
529
+ ];
530
+ ```
531
+
532
+ ### Client
533
+
534
+ ```javascript
4
535
  import clientCustomRules from 'tcy@eslint-rules/client';
5
536
 
6
- const customConfig = [
537
+ const clientConfig = [
7
538
  clientCustomRules,
8
539
  {
9
540
  files: ['**/*.+(ts|tsx|mts|cts)'],
10
541
  rules: {
11
- 'tcy/import-specifiers-per-line': ['error', { maxSpecifiers: 4 }],
12
- 'tcy/export-specifiers-per-line': 'error',
13
- 'tcy/array-elements-per-line': 'error',
14
542
  // `ignore`: extra class names that may stay without the `!` modifier
15
543
  // (non-Tailwind classes such as Bootstrap-style grid helpers).
16
544
  // `row`, `no-gutters`, `container`, `container-fluid` are ignored by default.
17
545
  'tcy/enforce-tailwind-important': ['error', { ignore: ['my-legacy-class'] }],
546
+ // `strict: false` also flags a lone conditional sibling with no other dynamic sibling.
547
+ 'tcy/require-fragment-key': ['error', { strict: true }],
548
+ // `types`: which initializer shapes to flag; defaults to `['arrow-function']`.
549
+ 'tcy/consistent-const-scoping': ['error', { types: ['arrow-function', 'primitive'] }],
550
+ // `jsx-ref-string-exists` requires `parserOptions.projectService` (or `project`)
551
+ // for type information to be set elsewhere in this config.
18
552
  },
19
553
  },
20
554
  ];
21
555
 
22
556
  export default [
23
- ...customConfig,
557
+ ...clientConfig,
24
558
  ];
25
559
  ```