@tcy/eslint-rules 1.12.0 → 1.13.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.
Files changed (48) hide show
  1. package/README.md +64 -11
  2. package/coverage/clover.xml +339 -120
  3. package/coverage/coverage-final.json +2 -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 +5 -2
  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 +1 -1
  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 +34 -19
  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/jsx-ref-type-match.js.html +865 -0
  26. package/coverage/lcov-report/src/no-static-key-in-map.js.html +1 -1
  27. package/coverage/lcov-report/src/no-unused-setup-return.js.html +725 -50
  28. package/coverage/lcov-report/src/no-v-model-on-prop.js.html +1 -1
  29. package/coverage/lcov-report/src/plugin.js.html +8 -2
  30. package/coverage/lcov-report/src/recommended.js.html +1 -1
  31. package/coverage/lcov-report/src/require-fragment-key.js.html +1 -1
  32. package/coverage/lcov-report/src/route-dto-required.js.html +1 -1
  33. package/coverage/lcov-report/src/v-model-name-match.js.html +1 -1
  34. package/coverage/lcov-report/src/vuejs-define-component.js.html +1 -1
  35. package/coverage/lcov-report/src/vuejs-define-workspace.js.html +1 -1
  36. package/coverage/lcov.info +761 -267
  37. package/decl/back/back.d.ts +20 -0
  38. package/decl/client/client.d.ts +21 -0
  39. package/decl/jsx-ref-type-match.d.ts +34 -0
  40. package/decl/no-unused-setup-return.d.ts +9 -0
  41. package/decl/plugin.d.ts +20 -0
  42. package/package.json +1 -1
  43. package/src/client/client.js +1 -0
  44. package/src/jsx-ref-type-match.js +260 -0
  45. package/src/no-unused-setup-return.js +235 -10
  46. package/src/plugin.js +2 -0
  47. package/tests/jsx-ref-type-match.spec.js +118 -0
  48. package/tests/no-unused-setup-return.spec.js +65 -1
package/README.md CHANGED
@@ -28,6 +28,7 @@ The plugin ships two bundles — `tcy@eslint-rules/back` and `tcy@eslint-rules/c
28
28
  | `jsx-expression-string-literals` | Suggestion | Enforce string literals instead of string expressions in JSX |
29
29
  | `jsx-boolean-shorthand` | Suggestion | Enforce shorthand boolean syntax in JSX props |
30
30
  | `jsx-ref-string-exists` | Problem | Ensure a string ref (`ref="name"`) exists on the render function's first parameter type |
31
+ | `jsx-ref-type-match` | Problem | Ensure the variable behind a string ref is typed with the element or component it is bound to |
31
32
  | `enforce-tailwind-important` | Layout | Enforce Tailwind classes end with the `!` important modifier |
32
33
  | `v-model-name-match` | Suggestion | Enforce v-model name matching variable names |
33
34
  | `vuejs-define-component` | Layout | Enforce use of `defineComponent` for Vue components |
@@ -43,8 +44,6 @@ The plugin ships two bundles — `tcy@eslint-rules/back` and `tcy@eslint-rules/c
43
44
  |-----------|------|-------------|
44
45
  | `decorator-type-enforcement` | Problem | Enforce a property's type based on its `@boolean` / `@dbIntBoolean` decorator |
45
46
 
46
- > `no-unused-setup-return` is exported by the plugin but not enabled by `client.js` (it reports public API read through a component ref, like `submit` / `reload` / `focus`, and composables shared between components) — turn it on explicitly with `'tcy/no-unused-setup-return': 'warn'`.
47
-
48
47
  > `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.
49
48
 
50
49
  ## Rule Details
@@ -296,7 +295,40 @@ function MyComponent(props: { other: unknown }) {
296
295
  }
297
296
  ```
298
297
 
299
- #### 4. enforce-tailwind-important
298
+ #### 4. jsx-ref-type-match
299
+
300
+ **Type:** Problem
301
+
302
+ **Description:** Ensures the variable behind a string ref (`ref="name"`) is typed with what it is bound to, so a call through the ref (`c.input.value?.focus()`) is checked by TypeScript. An untyped ref (`ref()` is `any`) hides it: removing `focus` from the child compiles fine and fails at runtime.
303
+
304
+ The declared type is the type of `name` on the render function's first parameter (as in `jsx-ref-string-exists`). The expected type is:
305
+ - native element (`<div>`, `<svg>`): its interface from `HTMLElementTagNameMap` / `SVGElementTagNameMap` (`HTMLDivElement`, `SVGSVGElement`)
306
+ - component: the type exported with the component's name from the file declaring it (`export type BaseInput = Context<typeof setup, Props>` next to `export default defineComponent(...)`), else the instance type of a Vue constructor (`DefineComponent`)
307
+ - dynamic tag typed `any` (`<Component>` from a slot): not checked, only an untyped ref is reported
308
+
309
+ Reports:
310
+ - `untypedRef`: the ref is `any` / `unknown` / only `null` (`ref()`, `ref(null)`)
311
+ - `refTypeMismatch`: the expected type isn't assignable to the declared one (`null` / `undefined` removed). A wider type is fine (`ref<HTMLElement>()` on a `<div>`).
312
+ - `unwrappedRef`: `ref<T>(initialValue)` types the value as `UnwrapRef<T>`, which a component instance doesn't satisfy. Use `ref<T>()` or `shallowRef<T | null>(null)`.
313
+
314
+ **Requires** TypeScript type information (`parserOptions.projectService`); without it the rule does nothing (`jsx-ref-string-exists` reports it).
315
+
316
+ **Examples:**
317
+
318
+ ```tsx
319
+ // setup
320
+ const input = ref<BaseInput>(); // valid
321
+ const root = ref<HTMLElement>(); // valid on <div>
322
+ const el = ref(); // invalid: untyped
323
+ const other = ref<HTMLInputElement>(); // invalid on <BaseInput>
324
+ const cmp = ref<BaseInput | null>(null); // invalid: unwrapped, use ref<BaseInput>()
325
+
326
+ // render
327
+ <BaseInput ref="input" />
328
+ <div ref="root" />
329
+ ```
330
+
331
+ #### 5. enforce-tailwind-important
300
332
 
301
333
  **Type:** Layout
302
334
 
@@ -331,7 +363,7 @@ Automatically fixes to:
331
363
  const cardCls = 'rounded-lg! shadow!';
332
364
  ```
333
365
 
334
- #### 5. v-model-name-match
366
+ #### 6. v-model-name-match
335
367
 
336
368
  **Type:** Suggestion
337
369
 
@@ -350,7 +382,7 @@ Invalid:
350
382
  <input v-model="value" />
351
383
  ```
352
384
 
353
- #### 6. vuejs-define-component
385
+ #### 7. vuejs-define-component
354
386
 
355
387
  **Type:** Layout
356
388
 
@@ -380,7 +412,7 @@ export default defineComponent({
380
412
  });
381
413
  ```
382
414
 
383
- #### 7. vuejs-define-workspace
415
+ #### 8. vuejs-define-workspace
384
416
 
385
417
  **Type:** Problem
386
418
 
@@ -411,7 +443,7 @@ export default defineComponent({
411
443
  });
412
444
  ```
413
445
 
414
- #### 8. require-fragment-key
446
+ #### 9. require-fragment-key
415
447
 
416
448
  **Type:** Problem
417
449
 
@@ -441,7 +473,7 @@ list.map((item) => <>{item.label}</>);
441
473
  </div>
442
474
  ```
443
475
 
444
- #### 9. no-static-key-in-map
476
+ #### 10. no-static-key-in-map
445
477
 
446
478
  **Type:** Problem
447
479
 
@@ -461,7 +493,7 @@ list.map((item) => <Row key="row" />);
461
493
  list.map(() => <Fragment key="rows">…</Fragment>);
462
494
  ```
463
495
 
464
- #### 10. no-v-model-on-prop
496
+ #### 11. no-v-model-on-prop
465
497
 
466
498
  **Type:** Problem
467
499
 
@@ -606,10 +638,28 @@ export default [
606
638
 
607
639
  The check is by name: it can miss an unused key sharing its name with something else, but doesn't report a used one. The component is skipped when a render spreads (`...c`) or passes (`foo(c)`) its whole context.
608
640
 
609
- Doesn't need TypeScript type information.
641
+ **Read from another component, through a ref.** With TypeScript type information (`parserOptions.projectService`), a key not found by name is searched in the whole program: an identifier resolving to the returned property is a use. It finds the public API called by a parent through a typed ref:
642
+
643
+ ```ts
644
+ // grid/cell/editable/boolean/useVGridCellEditableBoolean.ts
645
+ const vInputCheckboxBoolean = ref<VInputCheckboxBoolean>(); // type Context<typeof setup, Props>
646
+ onMounted(() => vInputCheckboxBoolean.value?.focus()); // `focus` of useVInputCheckboxBoolean is used
647
+ ```
648
+
649
+ The ref must be typed: `ref()` is `any` and hides the call (see `jsx-ref-type-match`). Without type information, only the check by name runs.
650
+
651
+ **Public API.** A key read by another app (a library) can't be found: mark it `@public` in a comment before the key, or after it on the same line:
652
+
653
+ ```ts
654
+ return {
655
+ /** @public */
656
+ focus,
657
+ reload, // @public
658
+ };
659
+ ```
610
660
 
611
661
  **Options:**
612
- - `ignore` (string[], default: `[]`) - keys never reported (public API called through a component ref)
662
+ - `ignore` (string[], default: `[]`) - keys never reported, in every composable (prefer `@public` on the key)
613
663
 
614
664
  ```ts
615
665
  // useDailyPL.ts
@@ -617,6 +667,9 @@ export default function (props: Props) {
617
667
  return {
618
668
  series, // ✓ c.series in useRender.tsx
619
669
  isPending, // ✗ not read anywhere else
670
+ focus, // ✓ read by a parent: `cmp.value?.focus()` with `cmp = ref<MyCmp>()`
671
+ /** @public */
672
+ reload, // ✓ public API
620
673
  };
621
674
  }
622
675
  ```