@tcy/eslint-rules 1.7.0 → 1.8.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 (39) hide show
  1. package/coverage/clover.xml +76 -4
  2. package/coverage/coverage-final.json +1 -0
  3. package/coverage/lcov-report/index.html +19 -19
  4. package/coverage/lcov-report/src/array-elements-per-line.js.html +1 -1
  5. package/coverage/lcov-report/src/back/back.js.html +1 -1
  6. package/coverage/lcov-report/src/back/http.js.html +1 -1
  7. package/coverage/lcov-report/src/back/index.html +1 -1
  8. package/coverage/lcov-report/src/back/recommended.js.html +1 -1
  9. package/coverage/lcov-report/src/bin/eslint-cache-guard.js.html +1 -1
  10. package/coverage/lcov-report/src/bin/index.html +1 -1
  11. package/coverage/lcov-report/src/client/client.js.html +5 -2
  12. package/coverage/lcov-report/src/client/index.html +1 -1
  13. package/coverage/lcov-report/src/client/recommended.js.html +1 -1
  14. package/coverage/lcov-report/src/decorator-type-enforcement.js.html +1 -1
  15. package/coverage/lcov-report/src/enforce-tailwind-important.js.html +1 -1
  16. package/coverage/lcov-report/src/export-specifiers-per-line.js.html +1 -1
  17. package/coverage/lcov-report/src/import-specifiers-per-line.js.html +1 -1
  18. package/coverage/lcov-report/src/index.html +24 -9
  19. package/coverage/lcov-report/src/index.js.html +1 -1
  20. package/coverage/lcov-report/src/jsx-boolean-shorthand.js.html +1 -1
  21. package/coverage/lcov-report/src/jsx-expression-string-literals.js.html +1 -1
  22. package/coverage/lcov-report/src/jsx-ref-string-exists.js.html +1 -1
  23. package/coverage/lcov-report/src/plugin.js.html +8 -2
  24. package/coverage/lcov-report/src/recommended.js.html +1 -1
  25. package/coverage/lcov-report/src/require-fragment-key.js.html +787 -0
  26. package/coverage/lcov-report/src/route-dto-required.js.html +1 -1
  27. package/coverage/lcov-report/src/v-model-name-match.js.html +1 -1
  28. package/coverage/lcov-report/src/vuejs-define-component.js.html +1 -1
  29. package/coverage/lcov-report/src/vuejs-define-workspace.js.html +1 -1
  30. package/coverage/lcov.info +201 -0
  31. package/decl/back/back.d.ts +26 -0
  32. package/decl/client/client.d.ts +27 -0
  33. package/decl/plugin.d.ts +26 -0
  34. package/decl/require-fragment-key.d.ts +69 -0
  35. package/package.json +9 -9
  36. package/src/client/client.js +1 -0
  37. package/src/plugin.js +2 -0
  38. package/src/require-fragment-key.js +234 -0
  39. package/tests/require-fragment-key.spec.js +160 -0
@@ -0,0 +1,234 @@
1
+ /**
2
+ * @fileoverview require-fragment-key
3
+ *
4
+ * Reports a key-less Fragment (`<>…</>` or `<Fragment>` without `key`) *only* in
5
+ * the positions where Vue's children diff can actually misalign without it:
6
+ *
7
+ * A. list item — `list.map(() => <>…</>)`
8
+ * B. conditional sibling — `{cond && <>…</>}` / `cond ? <>…</> : x`, when the
9
+ * conditional is one of several children in a JSX element / fragment / array
10
+ * (the surrounding child list can change shape at runtime).
11
+ *
12
+ * It stays silent where a key is not required:
13
+ *
14
+ * C. sole return / sole child — `() => <>…</>`, `render() { return <>…</> }`,
15
+ * `default: () => <>…</>`, `<Parent><>…</></Parent>`
16
+ * D. static (non-conditional) sibling
17
+ * E. the Fragment already carries a `key`
18
+ *
19
+ * With `{ strict: true }` (the default) case B fires only when at least one
20
+ * sibling is *also* dynamically rendered (another conditional or a `.map`) —
21
+ * a lone conditional in an otherwise static list cannot drift the diff.
22
+ */
23
+
24
+ const ITERATOR_METHODS = new Set(['map', 'flatMap']);
25
+
26
+ const TRANSPARENT_EXPRESSIONS = new Set([
27
+ 'JSXExpressionContainer',
28
+ 'ParenthesizedExpression',
29
+ 'TSAsExpression',
30
+ 'TSNonNullExpression',
31
+ 'TSSatisfiesExpression',
32
+ ]);
33
+
34
+ /** A `<>…</>` node, or a `<Fragment>` / `<X.Fragment>` element with no `key`. */
35
+ export const isKeylessFragment = (node) => {
36
+ if (!node) return false;
37
+ if (node.type === 'JSXFragment') return true;
38
+ if (node.type !== 'JSXElement') return false;
39
+
40
+ const { name } = node.openingElement;
41
+ const local = name.type === 'JSXMemberExpression' ? name.property.name : name.name;
42
+ if (local !== 'Fragment') return false;
43
+
44
+ return !node.openingElement.attributes.some(
45
+ (attr) => (attr.type === 'JSXAttribute' && attr.name.name === 'key')
46
+ // a spread might carry a key — don't guess, treat as keyed
47
+ || attr.type === 'JSXSpreadAttribute',
48
+ );
49
+ };
50
+
51
+ const isSignificantChild = (child) => {
52
+ if (child.type === 'JSXText') return child.value.trim() !== '';
53
+ if (child.type === 'JSXExpressionContainer') return child.expression.type !== 'JSXEmptyExpression';
54
+ return true; // JSXElement | JSXFragment | JSXSpreadChild
55
+ };
56
+
57
+ const containsJsx = (node) => {
58
+ if (!node) return false;
59
+ if (node.type === 'JSXElement' || node.type === 'JSXFragment') return true;
60
+ if (node.type === 'ConditionalExpression') {
61
+ return containsJsx(node.consequent) || containsJsx(node.alternate);
62
+ }
63
+ if (node.type === 'LogicalExpression') {
64
+ return containsJsx(node.left) || containsJsx(node.right);
65
+ }
66
+ if (TRANSPARENT_EXPRESSIONS.has(node.type)) return containsJsx(node.expression);
67
+ return false;
68
+ };
69
+
70
+ /** Is this JSX child rendered *dynamically* (a condition or an iterator)? */
71
+ const isDynamicChild = (child) => {
72
+ if (child.type !== 'JSXExpressionContainer') return false;
73
+
74
+ const expr = child.expression;
75
+ if (expr.type === 'LogicalExpression' || expr.type === 'ConditionalExpression') {
76
+ return containsJsx(expr);
77
+ }
78
+ return (
79
+ expr.type === 'CallExpression'
80
+ && expr.callee.type === 'MemberExpression'
81
+ && expr.callee.property.type === 'Identifier'
82
+ && ITERATOR_METHODS.has(expr.callee.property.name)
83
+ );
84
+ };
85
+
86
+ const isIteratorCallback = (fnNode) => {
87
+ const call = fnNode.parent;
88
+ return (
89
+ call
90
+ && call.type === 'CallExpression'
91
+ && call.arguments[0] === fnNode
92
+ && call.callee.type === 'MemberExpression'
93
+ && call.callee.property.type === 'Identifier'
94
+ && ITERATOR_METHODS.has(call.callee.property.name)
95
+ );
96
+ };
97
+
98
+ /**
99
+ * Walk outward from the fragment through transparent wrappers and conditional
100
+ * operators, and classify the first structural ancestor.
101
+ *
102
+ * @returns {{ kind: string, conditional?: boolean, siblingCount?: number, dynamicSibling?: boolean }}
103
+ */
104
+ export const classifyFragment = (fragment) => {
105
+ let cur = fragment;
106
+ let node = fragment.parent;
107
+ let conditional = false;
108
+
109
+ while (node) {
110
+ switch (node.type) {
111
+ case 'JSXExpressionContainer':
112
+ case 'ParenthesizedExpression':
113
+ case 'TSAsExpression':
114
+ case 'TSNonNullExpression':
115
+ case 'TSSatisfiesExpression':
116
+ case 'BlockStatement':
117
+ case 'ReturnStatement':
118
+ cur = node;
119
+ node = node.parent;
120
+ break;
121
+
122
+ case 'LogicalExpression':
123
+ if (node.right === cur || node.operator === '??') conditional = true;
124
+ cur = node;
125
+ node = node.parent;
126
+ break;
127
+
128
+ case 'ConditionalExpression':
129
+ if (node.consequent === cur || node.alternate === cur) conditional = true;
130
+ cur = node;
131
+ node = node.parent;
132
+ break;
133
+
134
+ case 'JSXElement':
135
+ case 'JSXFragment': {
136
+ // `cur` is the entry in `node.children` that holds our fragment
137
+ const others = node.children.filter((c) => c !== cur && isSignificantChild(c));
138
+ return {
139
+ kind: 'jsx-child',
140
+ conditional,
141
+ siblingCount: others.length,
142
+ dynamicSibling: others.some(isDynamicChild),
143
+ };
144
+ }
145
+
146
+ case 'ArrayExpression': {
147
+ const others = node.elements.filter((el) => el && el !== cur);
148
+ return {
149
+ kind: 'jsx-child',
150
+ conditional,
151
+ siblingCount: others.length,
152
+ dynamicSibling: others.some(containsJsx),
153
+ };
154
+ }
155
+
156
+ case 'ArrowFunctionExpression':
157
+ case 'FunctionExpression':
158
+ case 'FunctionDeclaration':
159
+ return { kind: isIteratorCallback(node) ? 'map-callback' : 'return' };
160
+
161
+ default:
162
+ return { kind: 'other' };
163
+ }
164
+ }
165
+ return { kind: 'other' };
166
+ };
167
+
168
+ /**
169
+ * @returns {'listItem' | 'conditionalSibling' | null}
170
+ */
171
+ export const analyzeFragment = (node, { strict = true } = {}) => {
172
+ if (!isKeylessFragment(node)) return null;
173
+
174
+ const {
175
+ kind,
176
+ conditional = false,
177
+ siblingCount = 0,
178
+ dynamicSibling = false,
179
+ } = classifyFragment(node);
180
+
181
+ if (kind === 'map-callback') return 'listItem';
182
+
183
+ if (
184
+ kind === 'jsx-child'
185
+ && conditional
186
+ && siblingCount >= 1
187
+ && (!strict || dynamicSibling)
188
+ ) {
189
+ return 'conditionalSibling';
190
+ }
191
+
192
+ return null;
193
+ };
194
+
195
+ export default {
196
+ meta: {
197
+ type: 'problem',
198
+ docs: {
199
+ description:
200
+ 'Require a `key` on a Fragment only when it is a list item or a conditional sibling '
201
+ + "(positions where Vue's un-keyed children diff can misalign).",
202
+ recommended: false,
203
+ },
204
+ schema: [
205
+ {
206
+ type: 'object',
207
+ properties: { strict: { type: 'boolean' } },
208
+ additionalProperties: false,
209
+ },
210
+ ],
211
+ messages: {
212
+ listItem:
213
+ 'This Fragment is a list item (`.map`). Give it a keyed root: `<Fragment key={…}>…</Fragment>`.',
214
+ conditionalSibling:
215
+ 'This conditional Fragment shares a child list with other dynamic siblings. '
216
+ + 'Vue diffs those children by position — give it `<Fragment key="…">…</Fragment>` '
217
+ + '(a stable literal is enough).',
218
+ },
219
+ },
220
+
221
+ create(context) {
222
+ const options = context.options[0] || {};
223
+
224
+ const check = (node) => {
225
+ const messageId = analyzeFragment(node, options);
226
+ if (messageId) context.report({ node, messageId });
227
+ };
228
+
229
+ return {
230
+ JSXFragment: check,
231
+ JSXElement: check,
232
+ };
233
+ },
234
+ };
@@ -0,0 +1,160 @@
1
+ import { parse } from '@babel/parser';
2
+ import { analyzeFragment, classifyFragment, isKeylessFragment } from '../src/require-fragment-key';
3
+
4
+ // ─── helpers ────────────────────────────────────────────────────────────────
5
+
6
+ const linkParents = (node, parent = null) => {
7
+ if (!node || typeof node.type !== 'string') return;
8
+ node.parent = parent;
9
+ Object.keys(node).forEach((key) => {
10
+ if (key === 'parent') return;
11
+ const value = node[key];
12
+ if (Array.isArray(value)) {
13
+ value.forEach((child) => linkParents(child, node));
14
+ } else if (value && typeof value.type === 'string') {
15
+ linkParents(value, node);
16
+ }
17
+ });
18
+ };
19
+
20
+ const collectFragments = (node, out = []) => {
21
+ if (!node || typeof node.type !== 'string') return out;
22
+ if (node.type === 'JSXFragment' || node.type === 'JSXElement') out.push(node);
23
+ Object.keys(node).forEach((key) => {
24
+ if (key === 'parent') return;
25
+ const value = node[key];
26
+ if (Array.isArray(value)) value.forEach((child) => collectFragments(child, out));
27
+ else if (value && typeof value.type === 'string') collectFragments(value, out);
28
+ });
29
+ return out;
30
+ };
31
+
32
+ /** Parse `code`, return every messageId the rule would emit (in source order). */
33
+ const lint = (code, options) => {
34
+ const ast = parse(code, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
35
+ linkParents(ast.program);
36
+ return collectFragments(ast.program)
37
+ .map((node) => analyzeFragment(node, options))
38
+ .filter(Boolean);
39
+ };
40
+
41
+ // ─── isKeylessFragment ──────────────────────────────────────────────────────
42
+
43
+ describe('GIVEN "require-fragment-key" / isKeylessFragment', () => {
44
+ const first = (code) => {
45
+ const ast = parse(code, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
46
+ return collectFragments(ast.program).find(
47
+ (n) => n.type === 'JSXFragment'
48
+ || (n.type === 'JSXElement' && n.openingElement.name.name === 'Fragment'),
49
+ );
50
+ };
51
+
52
+ it('THEN a shorthand fragment is key-less', () => {
53
+ expect(isKeylessFragment(first('const x = <><A/></>;'))).toBe(true);
54
+ });
55
+
56
+ it('THEN a <Fragment> without key is key-less', () => {
57
+ expect(isKeylessFragment(first('const x = <Fragment><A/></Fragment>;'))).toBe(true);
58
+ });
59
+
60
+ it('THEN a <Fragment key=…> is NOT key-less', () => {
61
+ expect(isKeylessFragment(first('const x = <Fragment key="k"><A/></Fragment>;'))).toBe(false);
62
+ });
63
+
64
+ it('THEN a <Fragment {...spread}> is treated as keyed (no guessing)', () => {
65
+ expect(isKeylessFragment(first('const x = <Fragment {...p}><A/></Fragment>;'))).toBe(false);
66
+ });
67
+ });
68
+
69
+ // ─── positions that DO require a key ────────────────────────────────────────
70
+
71
+ describe('GIVEN "require-fragment-key" / required positions', () => {
72
+ it('THEN a fragment returned from .map is a list item', () => {
73
+ expect(lint('const x = list.map((i) => (<><A/><B/></>));')).toEqual(['listItem']);
74
+ });
75
+
76
+ it('THEN a conditional fragment inside .map is a list item', () => {
77
+ expect(lint('const x = list.map((i) => i.ok && (<><A/></>));')).toEqual(['listItem']);
78
+ });
79
+
80
+ it('THEN a fragment returned from a .map block statement is a list item', () => {
81
+ expect(lint('const x = list.map((i) => { return <><A/></>; });')).toEqual(['listItem']);
82
+ });
83
+
84
+ it('THEN a conditional fragment beside another dynamic sibling must be keyed', () => {
85
+ const code = 'const x = (<P><L/>{a && <X/>}{c && (<><A/><B/></>)}<S/></P>);';
86
+ expect(lint(code)).toEqual(['conditionalSibling']);
87
+ });
88
+
89
+ it('THEN a v-if / v-else pair of fragments must both be keyed', () => {
90
+ const code = 'const x = (<P>{c ? (<><A/></>) : (<><B/></>)}{other && <Y/>}</P>);';
91
+ expect(lint(code)).toEqual(['conditionalSibling', 'conditionalSibling']);
92
+ });
93
+
94
+ it('THEN a conditional fragment beside a .map sibling must be keyed', () => {
95
+ const code = 'const x = (<P><L/>{c && (<><A/></>)}{rows.map((r) => <Row />)}</P>);';
96
+ expect(lint(code)).toEqual(['conditionalSibling']);
97
+ });
98
+
99
+ it('THEN a lone conditional fragment in a static list is flagged only when strict:false', () => {
100
+ const code = 'const x = (<P><L/>{c && (<><A/><B/></>)}</P>);';
101
+ expect(lint(code)).toEqual([]);
102
+ expect(lint(code, { strict: false })).toEqual(['conditionalSibling']);
103
+ });
104
+ });
105
+
106
+ // ─── positions that do NOT require a key ────────────────────────────────────
107
+
108
+ describe('GIVEN "require-fragment-key" / allowed positions', () => {
109
+ it('THEN the sole return of an arrow is fine', () => {
110
+ expect(lint('const f = () => (<><A/><B/></>);')).toEqual([]);
111
+ });
112
+
113
+ it('THEN the sole return of a render function is fine', () => {
114
+ expect(lint('function r() { return (<><A/><B/></>); }')).toEqual([]);
115
+ });
116
+
117
+ it('THEN a slot function returning a fragment is fine', () => {
118
+ expect(lint('const s = { default: () => (<><A/><B/></>) };')).toEqual([]);
119
+ });
120
+
121
+ it('THEN a conditional fragment that is the whole return is fine', () => {
122
+ expect(lint('const f = () => cond && (<><A/><B/></>);')).toEqual([]);
123
+ expect(lint('const f = () => (cond ? (<><A/></>) : (<><B/></>));')).toEqual([]);
124
+ });
125
+
126
+ it('THEN a fragment that is the only child of a parent is fine', () => {
127
+ expect(lint('const x = (<Parent>{cond && (<><A/><B/></>)}</Parent>);')).toEqual([]);
128
+ });
129
+
130
+ it('THEN an already-keyed fragment is fine', () => {
131
+ const code = 'const x = (<P><L/>{c && (<Fragment key="k"><A/></Fragment>)}{d && <Y/>}</P>);';
132
+ expect(lint(code)).toEqual([]);
133
+ });
134
+
135
+ it('THEN a static (non-conditional) sibling fragment is fine', () => {
136
+ expect(lint('const x = (<Parent><Legend/><><A/><B/></></Parent>);')).toEqual([]);
137
+ });
138
+ });
139
+
140
+ // ─── classifyFragment (white-box) ──────────────────────────────────────────
141
+
142
+ describe('GIVEN "require-fragment-key" / classifyFragment', () => {
143
+ const classifyFirst = (code) => {
144
+ const ast = parse(code, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
145
+ linkParents(ast.program);
146
+ return classifyFragment(collectFragments(ast.program).find((n) => n.type === 'JSXFragment'));
147
+ };
148
+
149
+ it('THEN it counts significant siblings and dynamic siblings', () => {
150
+ const info = classifyFirst('const x = (<P><L/>{a && <X/>}{c && (<><A/></>)}<S/></P>);');
151
+ expect(info.kind).toBe('jsx-child');
152
+ expect(info.conditional).toBe(true);
153
+ expect(info.siblingCount).toBe(3);
154
+ expect(info.dynamicSibling).toBe(true);
155
+ });
156
+
157
+ it('THEN a sole return classifies as "return"', () => {
158
+ expect(classifyFirst('const f = () => (<><A/></>);').kind).toBe('return');
159
+ });
160
+ });