@zukhruf/eslint 0.3.54 → 0.3.55

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
@@ -218,3 +218,21 @@ npx nx run eslint:test # builds, then runs the rule and composition tests
218
218
  ```
219
219
 
220
220
  The composition tests run the real ESLint CLI on temporary workspaces. They load the built package, which is what consumers install.
221
+
222
+ ### Add a check
223
+
224
+ A check is a rule under its own key ([ADR 0001](./docs/adr/0001-one-key-per-check.md)). Before you write a visitor by hand, use the builders in `src/authoring/`:
225
+
226
+ - `importBanRule()` bans packages and their subpaths. It reports static imports, re-exports and literal dynamic imports, type-only ones included.
227
+ - `selectorRule()` reports each node that one of its esquery selectors matches. The substring operator `*=` never matches a Literal's `value`, so write a regex selector (`[value=/…/]`).
228
+ - `scopedRule()` turns a rule on only for the files that its function accepts. Build that function from `isTestFile()`, `inRoots()` and `matchesAnyGlob()` in `path-scope.ts`. A rule finds its scope from the linted file, not from a config glob ([ADR 0002](./docs/adr/0002-scope-from-the-linted-file.md)).
229
+ - `ast.ts` has the type guards for a visitor: `isAstNode()`, `isType()` and `identifierName()`.
230
+
231
+ Folders that differ from repo to repo are `roots` options. A fact about the repo is a repo setting. A rule whose options a repo extends gets an option factory ([ADR 0004](./docs/adr/0004-option-factories.md)).
232
+
233
+ 1. Put the rule in the folder of the subject that it checks, such as `src/async-values/` or `src/imports/`. The file exports the rule as its default.
234
+ 2. Put `<rule>.test.ts` next to it. Use `typescriptRuleTester()` from `src/testing/rule-tester.ts`, or `typedRuleTester(root)` when the rule reads types. Call `run()` inside a node:test `test()`.
235
+ 3. Add the rule to the `rules` map in the `config.ts` of its concept, and turn on `zukhruf/<rule>` in that concept's config. A new concept also goes into the `concepts` list in `src/plugin.ts`. The composition tests fail when not exactly one config turns on a rule, when a config sets a repo-owned rule, or when a shipped glob does not start with `**`.
236
+ 4. Add the rule to its concept's row in the Configs table. Below the table, write a paragraph that tells why the check exists.
237
+ 5. Fix the findings that the new rule reports in the other packages of this workspace, in the same commit (for example 20b34e0). The workspace lints itself with this source. When a package must keep its code, turn the rule off for those files in the root `eslint.config.mjs`, with a comment that tells why (for example 495f19d).
238
+ 6. Run `npx nx run eslint:test` and `npx nx run eslint:typecheck`.
@@ -1 +1 @@
1
- {"version":3,"file":"no-test-lifecycle-hooks.d.ts","sourceRoot":"","sources":["../../src/test-files/no-test-lifecycle-hooks.ts"],"names":[],"mappings":";AAEA,wBAQG"}
1
+ {"version":3,"file":"no-test-lifecycle-hooks.d.ts","sourceRoot":"","sources":["../../src/test-files/no-test-lifecycle-hooks.ts"],"names":[],"mappings":";AA+KA,wBAAgC"}
@@ -1,9 +1,132 @@
1
- import { selectorRule } from "../authoring/selector-rule.js";
2
- export default selectorRule({
3
- description: 'Disallow test lifecycle hooks; each test arranges and tears down its own state',
4
- selectors: [
5
- 'CallExpression[callee.name=/^(before|after|beforeEach|afterEach|beforeAll|afterAll)$/]',
6
- ],
7
- message: 'No test lifecycle hooks. Write self-contained AAA tests: inline arrange in each test and run teardown (cleanup, mock restore, resource stop) in a per-test try/finally.',
1
+ import { ASTUtils, ESLintUtils, } from '@typescript-eslint/utils';
2
+ import { eslintRule } from "../authoring/rule-module.js";
3
+ const HOOKS = new Set([
4
+ 'before',
5
+ 'after',
6
+ 'beforeEach',
7
+ 'afterEach',
8
+ 'beforeAll',
9
+ 'afterAll',
10
+ ]);
11
+ const NODE_TEST = /^(node:)?test$/;
12
+ const TEST_FUNCTIONS = new Set(['test', 'it']);
13
+ const MODIFIERS = new Set(['only', 'skip', 'todo']);
14
+ function importClause(resolve, node) {
15
+ if (node.type !== 'Identifier')
16
+ return undefined;
17
+ const definition = resolve(node)?.defs[0];
18
+ return definition?.type === 'ImportBinding' &&
19
+ definition.node.type !== 'TSImportEqualsDeclaration'
20
+ ? definition.node
21
+ : undefined;
22
+ }
23
+ function importedName(specifier) {
24
+ return specifier.imported.type === 'Identifier'
25
+ ? specifier.imported.name
26
+ : specifier.imported.value;
27
+ }
28
+ function nodeTestImport(resolve, node) {
29
+ const clause = importClause(resolve, node);
30
+ return clause?.parent.type === 'ImportDeclaration' &&
31
+ NODE_TEST.test(clause.parent.source.value)
32
+ ? clause
33
+ : undefined;
34
+ }
35
+ function isNodeTestNamespace(resolve, node) {
36
+ return nodeTestImport(resolve, node)?.type === 'ImportNamespaceSpecifier';
37
+ }
38
+ /** `test` or `it` of node:test, also as `ns.test`, `test.only`, or the subtest `t.test`. */
39
+ function isTestFunction(resolve, node) {
40
+ if (node.type === 'Identifier') {
41
+ const clause = nodeTestImport(resolve, node);
42
+ return (clause?.type === 'ImportDefaultSpecifier' ||
43
+ (clause?.type === 'ImportSpecifier' &&
44
+ TEST_FUNCTIONS.has(importedName(clause))));
45
+ }
46
+ if (node.type !== 'MemberExpression' || node.property.type !== 'Identifier') {
47
+ return false;
48
+ }
49
+ const property = node.property.name;
50
+ return ((MODIFIERS.has(property) && isTestFunction(resolve, node.object)) ||
51
+ (TEST_FUNCTIONS.has(property) &&
52
+ isNodeTestNamespace(resolve, node.object)) ||
53
+ (property === 'test' && isTestContext(resolve, node.object)));
54
+ }
55
+ function isTestContextType(resolve, annotation) {
56
+ if (annotation.type !== 'TSTypeReference')
57
+ return false;
58
+ const clause = nodeTestImport(resolve, annotation.typeName);
59
+ return (clause?.type === 'ImportSpecifier' && importedName(clause) === 'TestContext');
60
+ }
61
+ /** A parameter typed `TestContext`, or the first parameter of a test function's callback. */
62
+ function isTestContext(resolve, node) {
63
+ if (node.type !== 'Identifier')
64
+ return false;
65
+ const definition = resolve(node)?.defs[0];
66
+ if (definition?.type !== 'Parameter')
67
+ return false;
68
+ const parameter = definition.name;
69
+ if (parameter.typeAnnotation &&
70
+ isTestContextType(resolve, parameter.typeAnnotation.typeAnnotation)) {
71
+ return true;
72
+ }
73
+ const callback = definition.node;
74
+ const call = callback.parent;
75
+ return (callback.params[0] === parameter &&
76
+ call.type === 'CallExpression' &&
77
+ call.arguments.some((argument) => argument === callback) &&
78
+ isTestFunction(resolve, call.callee));
79
+ }
80
+ function isHook(resolve, callee) {
81
+ if (callee.type === 'Identifier') {
82
+ const variable = resolve(callee);
83
+ if (!variable || variable.defs.length === 0)
84
+ return HOOKS.has(callee.name);
85
+ const clause = importClause(resolve, callee);
86
+ return (clause !== undefined &&
87
+ (HOOKS.has(callee.name) ||
88
+ (clause.type === 'ImportSpecifier' && HOOKS.has(importedName(clause)))));
89
+ }
90
+ return (callee.type === 'MemberExpression' &&
91
+ callee.property.type === 'Identifier' &&
92
+ HOOKS.has(callee.property.name) &&
93
+ (isTestFunction(resolve, callee.object) ||
94
+ isNodeTestNamespace(resolve, callee.object) ||
95
+ isTestContext(resolve, callee.object)));
96
+ }
97
+ /**
98
+ * A lifecycle hook moves arrange or teardown out of the test that needs it:
99
+ * the reader no longer sees the whole test in one place, and state that one
100
+ * test leaves behind reaches the next. A per-test `t.after()` of node:test has
101
+ * the same cost, because the teardown is out of the test's own flow. The rule
102
+ * reads a hook from Vitest, Jest or Mocha globals, from an import (also under
103
+ * another name), from node:test's `test`, `it` or namespace (`test.after`), and
104
+ * from a TestContext: the first parameter of a node:test test or subtest
105
+ * callback, or a parameter typed `TestContext`. A function of the file that is
106
+ * named `after` is not a hook.
107
+ */
108
+ const rule = ESLintUtils.RuleCreator.withoutDocs({
109
+ meta: {
110
+ type: 'problem',
111
+ docs: {
112
+ description: 'Disallow test lifecycle hooks; each test arranges and tears down its own state',
113
+ },
114
+ schema: [],
115
+ messages: {
116
+ matched: 'No test lifecycle hooks. Write self-contained AAA tests: inline arrange in each test and run teardown (cleanup, mock restore, resource stop) in a per-test try/finally or with `await using` a disposable.',
117
+ },
118
+ },
119
+ defaultOptions: [],
120
+ create(context) {
121
+ const resolve = (identifier) => ASTUtils.findVariable(context.sourceCode.getScope(identifier), identifier);
122
+ return {
123
+ CallExpression(node) {
124
+ if (isHook(resolve, node.callee)) {
125
+ context.report({ node, messageId: 'matched' });
126
+ }
127
+ },
128
+ };
129
+ },
8
130
  });
131
+ export default eslintRule(rule);
9
132
  //# sourceMappingURL=no-test-lifecycle-hooks.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"no-test-lifecycle-hooks.js","sourceRoot":"","sources":["../../src/test-files/no-test-lifecycle-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,eAAe,YAAY,CAAC;IAC1B,WAAW,EACT,gFAAgF;IAClF,SAAS,EAAE;QACT,wFAAwF;KACzF;IACD,OAAO,EACL,yKAAyK;CAC5K,CAAC,CAAC"}
1
+ {"version":3,"file":"no-test-lifecycle-hooks.js","sourceRoot":"","sources":["../../src/test-files/no-test-lifecycle-hooks.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/eslint",
3
- "version": "0.3.54",
3
+ "version": "0.3.55",
4
4
  "description": "ESLint rules and configs shared across workspaces. Every check is its own named rule, so a repo's own config cannot silently erase it.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -56,7 +56,7 @@
56
56
  "ts-api-utils": "^2.5.0"
57
57
  },
58
58
  "devDependencies": {
59
- "@zukhruf/testing": "^0.3.54"
59
+ "@zukhruf/testing": "^0.3.55"
60
60
  },
61
61
  "peerDependencies": {
62
62
  "@eslint/js": "^9.30.0 || ^10.0.0",