@zgeoff/oxlint-config 0.2.13 → 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 +50 -13
- package/find-function-name.js +28 -0
- package/function-verb.js +21 -146
- package/import-zones.js +4 -4
- package/is-verb-match.js +5 -0
- package/no-class.js +40 -0
- package/no-comment-rule-override.js +2 -2
- package/no-file-snapshot.js +2 -2
- package/oxlintrc.json +2 -0
- package/package.json +6 -2
- package/plugin.js +4 -0
- package/resolve-import-target.js +7 -7
- package/{find-repo-root.js → resolve-repo-root.js} +1 -1
- package/test-beside-module.js +6 -6
- package/verb-contract.js +609 -0
package/README.md
CHANGED
|
@@ -6,13 +6,16 @@ restriction-rule cherry-picks, comment-style enforcement via `@stylistic`, and a
|
|
|
6
6
|
function declarations, bare named exports, destructured and inline-typed parameters, ternary and
|
|
7
7
|
await arguments, awaits hidden inside a control-flow condition or a `&&`/`||`/`??` chain, every
|
|
8
8
|
`switch` statement, every JSDoc block, any run of more than three line comments, and a repo config
|
|
9
|
-
that loosens either comment rule.
|
|
10
|
-
|
|
9
|
+
that loosens either comment rule.
|
|
10
|
+
|
|
11
|
+
The plugin's other rules each check one convention. `zgeoff/function-verb` bans the vague and
|
|
12
|
+
near-synonym verbs of the shared function-naming rules, `zgeoff/verb-contract` checks the promise
|
|
13
|
+
each role-table verb makes, `zgeoff/test-beside-module` keeps each test file beside the module it
|
|
11
14
|
tests, `zgeoff/import-zones` fails an import that crosses a module boundary the repo declares,
|
|
12
15
|
`zgeoff/no-restricted-words` keeps the words in its `words` option out of a path's text,
|
|
13
16
|
`zgeoff/no-abbreviated-names` reports each abbreviated value name it lists with its full word,
|
|
14
|
-
`zgeoff/no-file-snapshot` bans file snapshots,
|
|
15
|
-
|
|
17
|
+
`zgeoff/no-file-snapshot` bans file snapshots, `zgeoff/setup-test-only` keeps a test file's module
|
|
18
|
+
level to `setupTest()` and its tests, and `zgeoff/no-class` bans every class but a custom error.
|
|
16
19
|
|
|
17
20
|
## Usage
|
|
18
21
|
|
|
@@ -43,23 +46,48 @@ The plugin is addressable on its own at `@zgeoff/oxlint-config/plugin` for confi
|
|
|
43
46
|
|
|
44
47
|
## `zgeoff/function-verb`
|
|
45
48
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
`
|
|
49
|
-
|
|
50
|
-
Exempt an algorithm-native name (`walk`, `backtrack`) with a disable comment in the module
|
|
51
|
-
implementing that algorithm.
|
|
52
|
-
|
|
53
|
-
Options extend the shipped set per repo:
|
|
49
|
+
The rule reports a function, method, or function-valued variable or property whose name starts with
|
|
50
|
+
a banned verb, and it names the role-table verb to use instead (`fetchUser` → use `read`). It also
|
|
51
|
+
reports a bare template prefix, such as a function named `on`. A name that does not start with a
|
|
52
|
+
lowercase letter passes. The `exemptNames` option lists names that a library contract fixes:
|
|
54
53
|
|
|
55
54
|
```jsonc
|
|
56
55
|
{
|
|
57
56
|
"rules": {
|
|
58
|
-
"zgeoff/function-verb": ["error", { "
|
|
57
|
+
"zgeoff/function-verb": ["error", { "exemptNames": ["execute"] }],
|
|
59
58
|
},
|
|
60
59
|
}
|
|
61
60
|
```
|
|
62
61
|
|
|
62
|
+
## `zgeoff/verb-contract`
|
|
63
|
+
|
|
64
|
+
The rule reads each named function's verb and reports a body that breaks the verb's promise. It
|
|
65
|
+
reads declared return types, since it runs without type information. It runs three checks:
|
|
66
|
+
|
|
67
|
+
- **No I/O behind a no-I/O verb.** A function named with `is`, `has`, `can`, `should`, `build`,
|
|
68
|
+
`parse`, `format`, `render`, `pick`, `find`, `get`, `collect` or `to` must not be async or await.
|
|
69
|
+
It must not call `fs`, `child_process`, `Bun.spawn`, `Bun.file`, `Bun.write`, Bun's `$` shell
|
|
70
|
+
under any import form, `fetch` or a Kysely `execute`, and must not read `process.env` or
|
|
71
|
+
`Bun.env`. It must not call a function whose verb is on the rule's effectful list, such as
|
|
72
|
+
`readConfig` or `ctx.writeText`. That check skips a callee imported from a package, a global, a
|
|
73
|
+
bare method name such as `map.set`, and a method on a value the function declares itself. I/O
|
|
74
|
+
inside an unnamed callback counts against the named function around it. A local alias of an I/O
|
|
75
|
+
source, such as `const read = fs.readFileSync` or `const { spawn } = Bun`, counts as that source,
|
|
76
|
+
and a local alias of a package's callee is skipped as the callee is.
|
|
77
|
+
- **Predicates return a boolean.** A function named with `is`, `has`, `can`, `should` or `probe`
|
|
78
|
+
that declares a return type declares `boolean`, a type predicate, or a promise of one. A function
|
|
79
|
+
that declares `boolean` and does no I/O starts with one of the four no-I/O predicate verbs. That
|
|
80
|
+
check skips an effectful verb or `try`, whose function may return a success flag, and the
|
|
81
|
+
framework prefixes `use`, `on` and `handle`.
|
|
82
|
+
- **`find` can miss, and `get` cannot.** A declared `find` return type holds `null`, `undefined`,
|
|
83
|
+
`void`, `unknown` or `any`. A `get` function neither declares `null` or `undefined` nor returns
|
|
84
|
+
either one as a literal or a bare `return`. Every check follows the file's own type aliases, and a
|
|
85
|
+
type the rule cannot see, such as an import, a type parameter or an indexed access, never fails a
|
|
86
|
+
check.
|
|
87
|
+
|
|
88
|
+
A test in this package reads the role table in the shared code-style skill and fails when the
|
|
89
|
+
skill's no-I/O verbs and the rule's differ in either direction.
|
|
90
|
+
|
|
63
91
|
## `zgeoff/no-jsdoc` and `zgeoff/max-consecutive-line-comments`
|
|
64
92
|
|
|
65
93
|
A comment holds only what neither the code, a type, a test name, nor the subsystem doc can hold: the
|
|
@@ -157,6 +185,15 @@ linted file that has a `__snapshots__/<file name>.snap` beside it, at the first
|
|
|
157
185
|
file-level disable comment covers it. oxlint never visits a `.snap` file, so a snapshot file whose
|
|
158
186
|
test file is gone is not reported.
|
|
159
187
|
|
|
188
|
+
## `zgeoff/no-class`
|
|
189
|
+
|
|
190
|
+
Objects come from factory functions, as the code-style skill requires, so the rule reports every
|
|
191
|
+
class declaration and class expression, in test files too. A custom error stays a class, because
|
|
192
|
+
`instanceof` checks and stack traces need one. The rule counts a class as a custom error when its
|
|
193
|
+
`extends` clause holds `Error` or another name that ends in `Error`, bare or as a member such as
|
|
194
|
+
`errors.BrewError`. It does not check the name of the class itself, and it reports a superclass
|
|
195
|
+
reached through a computed member, such as `errors['BrewError']`.
|
|
196
|
+
|
|
160
197
|
## `zgeoff/import-zones`
|
|
161
198
|
|
|
162
199
|
Off unless a repo configures it. The options name zones (path globs, relative to the repo root) and
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
// a declaration's own name, the variable or key a function is assigned to,
|
|
2
|
+
// or else a function expression's own name; getters, setters, computed and
|
|
3
|
+
// quoted keys name nothing
|
|
4
|
+
export default function findFunctionName(node) {
|
|
5
|
+
if (node.type === 'FunctionDeclaration') {
|
|
6
|
+
return node.id;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
const parent = node.parent;
|
|
10
|
+
|
|
11
|
+
if (parent.type === 'VariableDeclarator') {
|
|
12
|
+
return parent.init === node && parent.id.type === 'Identifier' ? parent.id : null;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
if (parent.type === 'MethodDefinition') {
|
|
16
|
+
return parent.kind === 'method' ? findKeyName(parent) : null;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
if (parent.type === 'Property' && parent.parent.type === 'ObjectExpression') {
|
|
20
|
+
return parent.kind === 'init' && parent.value === node ? findKeyName(parent) : null;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
return node.id ?? null;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function findKeyName(member) {
|
|
27
|
+
return !member.computed && member.key.type === 'Identifier' ? member.key : null;
|
|
28
|
+
}
|
package/function-verb.js
CHANGED
|
@@ -1,103 +1,8 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
// the drift-guard test
|
|
4
|
-
const taxonomyVerbs = [
|
|
5
|
-
'is',
|
|
6
|
-
'has',
|
|
7
|
-
'can',
|
|
8
|
-
'should',
|
|
9
|
-
'needs',
|
|
10
|
-
'build',
|
|
11
|
-
'define',
|
|
12
|
-
'parse',
|
|
13
|
-
'encode',
|
|
14
|
-
'decode',
|
|
15
|
-
'derive',
|
|
16
|
-
'plan',
|
|
17
|
-
'pick',
|
|
18
|
-
'find',
|
|
19
|
-
'get',
|
|
20
|
-
'collect',
|
|
21
|
-
'count',
|
|
22
|
-
'split',
|
|
23
|
-
'merge',
|
|
24
|
-
'sort',
|
|
25
|
-
'format',
|
|
26
|
-
'render',
|
|
27
|
-
'normalize',
|
|
28
|
-
'sanitize',
|
|
29
|
-
'resolve',
|
|
30
|
-
'expand',
|
|
31
|
-
'compress',
|
|
32
|
-
'decompress',
|
|
33
|
-
'to',
|
|
34
|
-
'transform',
|
|
35
|
-
'apply',
|
|
36
|
-
'create',
|
|
37
|
-
'mint',
|
|
38
|
-
'open',
|
|
39
|
-
'dispose',
|
|
40
|
-
'claim',
|
|
41
|
-
'release',
|
|
42
|
-
'revoke',
|
|
43
|
-
'read',
|
|
44
|
-
'load',
|
|
45
|
-
'write',
|
|
46
|
-
'remove',
|
|
47
|
-
'update',
|
|
48
|
-
'refresh',
|
|
49
|
-
'upsert',
|
|
50
|
-
'set',
|
|
51
|
-
'toggle',
|
|
52
|
-
'reset',
|
|
53
|
-
'restore',
|
|
54
|
-
'print',
|
|
55
|
-
'record',
|
|
56
|
-
'run',
|
|
57
|
-
'spawn',
|
|
58
|
-
'schedule',
|
|
59
|
-
'check',
|
|
60
|
-
'try',
|
|
61
|
-
'register',
|
|
62
|
-
'subscribe',
|
|
63
|
-
'unsubscribe',
|
|
64
|
-
'assert',
|
|
65
|
-
'require',
|
|
66
|
-
'verify',
|
|
67
|
-
'emit',
|
|
68
|
-
'send',
|
|
69
|
-
'wait',
|
|
70
|
-
'setup',
|
|
71
|
-
'teardown',
|
|
72
|
-
'start',
|
|
73
|
-
'stop',
|
|
74
|
-
'restart',
|
|
75
|
-
'advance',
|
|
76
|
-
'drain',
|
|
77
|
-
'with',
|
|
78
|
-
'make',
|
|
79
|
-
'use',
|
|
80
|
-
'on',
|
|
81
|
-
'handle',
|
|
82
|
-
];
|
|
1
|
+
import findFunctionName from './find-function-name.js';
|
|
2
|
+
import isVerbMatch from './is-verb-match.js';
|
|
83
3
|
|
|
84
|
-
// the
|
|
85
|
-
//
|
|
86
|
-
const suffixRequiredVerbs = new Set([
|
|
87
|
-
'build',
|
|
88
|
-
'define',
|
|
89
|
-
'to',
|
|
90
|
-
'toggle',
|
|
91
|
-
'try',
|
|
92
|
-
'with',
|
|
93
|
-
'make',
|
|
94
|
-
'use',
|
|
95
|
-
'on',
|
|
96
|
-
'handle',
|
|
97
|
-
]);
|
|
98
|
-
|
|
99
|
-
// banned verb → the taxonomy verb to use instead; null means the verb is too
|
|
100
|
-
// vague to map and the name should say what the function does
|
|
4
|
+
// banned verb → the role-table verb to use instead; null means the verb is
|
|
5
|
+
// too vague to map and the name should say what the function does
|
|
101
6
|
const bannedVerbs = new Map([
|
|
102
7
|
['process', null],
|
|
103
8
|
['manage', null],
|
|
@@ -113,42 +18,33 @@ const bannedVerbs = new Map([
|
|
|
113
18
|
['lookup', 'find'],
|
|
114
19
|
]);
|
|
115
20
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
// a digit also ends the verb: acronyms like 2FA start camelCase segments
|
|
122
|
-
return name.startsWith(verb) && /[A-Z0-9]/u.test(name.charAt(verb.length));
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
function findAllowedVerb(name, verbs) {
|
|
126
|
-
return verbs.find((verb) => isVerbMatch(name, verb, !suffixRequiredVerbs.has(verb))) ?? null;
|
|
127
|
-
}
|
|
21
|
+
// the role table's template prefixes (`with<X>`, `handle<Event>`, …): each is
|
|
22
|
+
// only valid with a suffix, and a bare `handle` is the vague banned verb
|
|
23
|
+
const suffixRequiredVerbs = new Set(['to', 'with', 'make', 'use', 'on']);
|
|
128
24
|
|
|
129
25
|
function findBannedVerb(name) {
|
|
130
26
|
for (const [verb, replacement] of bannedVerbs) {
|
|
131
|
-
if (isVerbMatch(name, verb
|
|
27
|
+
if (isVerbMatch(name, verb)) {
|
|
132
28
|
return { verb, replacement };
|
|
133
29
|
}
|
|
134
30
|
}
|
|
135
31
|
|
|
136
|
-
return null;
|
|
32
|
+
return name === 'handle' ? { verb: 'handle', replacement: null } : null;
|
|
137
33
|
}
|
|
138
34
|
|
|
139
|
-
function planReport(name,
|
|
35
|
+
function planReport(name, exemptNames) {
|
|
140
36
|
if (exemptNames.has(name) || !/^[a-z]/u.test(name)) {
|
|
141
37
|
return null;
|
|
142
38
|
}
|
|
143
39
|
|
|
144
|
-
if (
|
|
145
|
-
return
|
|
40
|
+
if (suffixRequiredVerbs.has(name)) {
|
|
41
|
+
return { messageId: 'bareTemplate', data: { name } };
|
|
146
42
|
}
|
|
147
43
|
|
|
148
44
|
const banned = findBannedVerb(name);
|
|
149
45
|
|
|
150
46
|
if (banned === null) {
|
|
151
|
-
return
|
|
47
|
+
return null;
|
|
152
48
|
}
|
|
153
49
|
|
|
154
50
|
if (banned.replacement === null) {
|
|
@@ -165,16 +61,14 @@ const functionVerb = {
|
|
|
165
61
|
meta: {
|
|
166
62
|
type: 'suggestion',
|
|
167
63
|
messages: {
|
|
168
|
-
unknownVerb:
|
|
169
|
-
"'{{name}}' does not start with a taxonomy verb — pick one, or extend the taxonomy and the `verbs` option in the same PR.",
|
|
170
64
|
bannedVerb: "'{{name}}' starts with the banned verb '{{verb}}' — use `{{replacement}}`.",
|
|
171
65
|
vagueVerb: "'{{name}}' starts with the banned verb '{{verb}}' — name what the function does.",
|
|
66
|
+
bareTemplate: "'{{name}}' is a bare prefix — add what it applies to, as in `{{name}}Thing`.",
|
|
172
67
|
},
|
|
173
68
|
schema: [
|
|
174
69
|
{
|
|
175
70
|
type: 'object',
|
|
176
71
|
properties: {
|
|
177
|
-
verbs: { type: 'array', items: { type: 'string' }, uniqueItems: true },
|
|
178
72
|
exemptNames: { type: 'array', items: { type: 'string' }, uniqueItems: true },
|
|
179
73
|
},
|
|
180
74
|
additionalProperties: false,
|
|
@@ -182,13 +76,11 @@ const functionVerb = {
|
|
|
182
76
|
],
|
|
183
77
|
},
|
|
184
78
|
create(context) {
|
|
185
|
-
const
|
|
186
|
-
const verbs =
|
|
187
|
-
options.verbs === undefined ? taxonomyVerbs : [...taxonomyVerbs, ...options.verbs];
|
|
188
|
-
const exemptNames = new Set(options.exemptNames);
|
|
79
|
+
const exemptNames = new Set(context.options[0]?.exemptNames);
|
|
189
80
|
|
|
190
|
-
const
|
|
191
|
-
const
|
|
81
|
+
const checkFunction = (node) => {
|
|
82
|
+
const id = findFunctionName(node);
|
|
83
|
+
const report = id === null ? null : planReport(id.name, exemptNames);
|
|
192
84
|
|
|
193
85
|
if (report !== null) {
|
|
194
86
|
context.report({ node: id, messageId: report.messageId, data: report.data });
|
|
@@ -196,26 +88,9 @@ const functionVerb = {
|
|
|
196
88
|
};
|
|
197
89
|
|
|
198
90
|
return {
|
|
199
|
-
FunctionDeclaration
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
}
|
|
203
|
-
},
|
|
204
|
-
VariableDeclarator(node) {
|
|
205
|
-
const isFunctionInit =
|
|
206
|
-
node.init !== null &&
|
|
207
|
-
node.init !== undefined &&
|
|
208
|
-
(node.init.type === 'ArrowFunctionExpression' || node.init.type === 'FunctionExpression');
|
|
209
|
-
|
|
210
|
-
if (isFunctionInit && node.id.type === 'Identifier') {
|
|
211
|
-
checkName(node.id);
|
|
212
|
-
}
|
|
213
|
-
},
|
|
214
|
-
MethodDefinition(node) {
|
|
215
|
-
if (node.kind === 'method' && !node.computed && node.key.type === 'Identifier') {
|
|
216
|
-
checkName(node.key);
|
|
217
|
-
}
|
|
218
|
-
},
|
|
91
|
+
FunctionDeclaration: checkFunction,
|
|
92
|
+
FunctionExpression: checkFunction,
|
|
93
|
+
ArrowFunctionExpression: checkFunction,
|
|
219
94
|
};
|
|
220
95
|
},
|
|
221
96
|
};
|
package/import-zones.js
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
import { isBuiltin } from 'node:module';
|
|
2
2
|
import { relative, sep } from 'node:path';
|
|
3
|
-
import findRepoRoot from './find-repo-root.js';
|
|
4
3
|
import importZonesSchema from './import-zones-schema.js';
|
|
5
4
|
import loadWorkspaceManifests from './load-workspace-manifests.js';
|
|
6
5
|
import loadZoneOptions from './load-zone-options.js';
|
|
7
6
|
import resolveImportTarget from './resolve-import-target.js';
|
|
7
|
+
import resolveRepoRoot from './resolve-repo-root.js';
|
|
8
8
|
|
|
9
9
|
// Judges each import against named zones: path globs relative to the repo
|
|
10
10
|
// root, which may overlap. A file belongs to every zone its path matches.
|
|
11
11
|
|
|
12
|
-
function
|
|
12
|
+
function loadFileState(context) {
|
|
13
13
|
const options = loadZoneOptions(context.options[0] ?? {});
|
|
14
14
|
const filename = context.physicalFilename;
|
|
15
|
-
const root =
|
|
15
|
+
const root = resolveRepoRoot(filename) ?? context.cwd;
|
|
16
16
|
const path = toRootPath(root, filename);
|
|
17
17
|
|
|
18
18
|
const workspaces = loadWorkspaceManifests(root, options.workspaces);
|
|
@@ -298,7 +298,7 @@ const importZones = {
|
|
|
298
298
|
schema: [importZonesSchema],
|
|
299
299
|
},
|
|
300
300
|
create(context) {
|
|
301
|
-
const file =
|
|
301
|
+
const file = loadFileState(context);
|
|
302
302
|
|
|
303
303
|
return {
|
|
304
304
|
Program(node) {
|
package/is-verb-match.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
// a name starts with a verb when the verb ends at a camelCase boundary; a
|
|
2
|
+
// digit also ends it, since acronyms like 2FA start camelCase segments
|
|
3
|
+
export default function isVerbMatch(name, verb) {
|
|
4
|
+
return name === verb || (name.startsWith(verb) && /[A-Z0-9]/u.test(name.charAt(verb.length)));
|
|
5
|
+
}
|
package/no-class.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// a custom error stays a class, since `instanceof` checks and stack traces
|
|
2
|
+
// need one: its superclass is `Error` or another name that ends in `Error`,
|
|
3
|
+
// bare or as a member such as `errors.BrewError`
|
|
4
|
+
const noClass = {
|
|
5
|
+
meta: {
|
|
6
|
+
type: 'problem',
|
|
7
|
+
messages: {
|
|
8
|
+
banned:
|
|
9
|
+
'Build this with a factory function (`create<X>` or `make<X>`), not a class. Only a custom error may be a class: `class XError extends Error`.',
|
|
10
|
+
},
|
|
11
|
+
schema: [],
|
|
12
|
+
},
|
|
13
|
+
create(context) {
|
|
14
|
+
const checkClass = (node) => {
|
|
15
|
+
if (!isCustomError(node)) {
|
|
16
|
+
context.report({ node, messageId: 'banned' });
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
return { ClassDeclaration: checkClass, ClassExpression: checkClass };
|
|
21
|
+
},
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
function isCustomError(node) {
|
|
25
|
+
return findSuperclassName(node.superClass)?.endsWith('Error') ?? false;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function findSuperclassName(superClass) {
|
|
29
|
+
if (superClass?.type === 'Identifier') {
|
|
30
|
+
return superClass.name;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
if (superClass?.type === 'MemberExpression' && !superClass.computed) {
|
|
34
|
+
return superClass.property.name;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
return null;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export default noClass;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { readFileSync, readdirSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
import
|
|
3
|
+
import resolveRepoRoot from './resolve-repo-root.js';
|
|
4
4
|
|
|
5
5
|
// every repo runs the comment rules exactly as this config ships them
|
|
6
6
|
const lockedRules = ['zgeoff/no-jsdoc', 'zgeoff/max-consecutive-line-comments'];
|
|
@@ -47,7 +47,7 @@ const noCommentRuleOverride = {
|
|
|
47
47
|
schema: [],
|
|
48
48
|
},
|
|
49
49
|
create(context) {
|
|
50
|
-
const root =
|
|
50
|
+
const root = resolveRepoRoot(context.filename);
|
|
51
51
|
|
|
52
52
|
if (root === null) {
|
|
53
53
|
return {};
|
package/no-file-snapshot.js
CHANGED
|
@@ -33,7 +33,7 @@ const noFileSnapshot = {
|
|
|
33
33
|
const filename = context.physicalFilename;
|
|
34
34
|
const name = `${basename(filename)}.snap`;
|
|
35
35
|
|
|
36
|
-
if (!
|
|
36
|
+
if (!probeFile(join(dirname(filename), '__snapshots__', name))) {
|
|
37
37
|
return;
|
|
38
38
|
}
|
|
39
39
|
|
|
@@ -51,7 +51,7 @@ function getMatcherName(node) {
|
|
|
51
51
|
return node.type === 'Identifier' ? node.name : node.value;
|
|
52
52
|
}
|
|
53
53
|
|
|
54
|
-
function
|
|
54
|
+
function probeFile(path) {
|
|
55
55
|
return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
|
|
56
56
|
}
|
|
57
57
|
|
package/oxlintrc.json
CHANGED
|
@@ -26,10 +26,12 @@
|
|
|
26
26
|
"zgeoff/no-await-in-condition": "error",
|
|
27
27
|
"zgeoff/no-await-in-logical": "error",
|
|
28
28
|
"zgeoff/no-switch": "error",
|
|
29
|
+
"zgeoff/no-class": "error",
|
|
29
30
|
"zgeoff/no-jsdoc": "error",
|
|
30
31
|
"zgeoff/max-consecutive-line-comments": ["error", { "max": 3 }],
|
|
31
32
|
"zgeoff/no-comment-rule-override": "error",
|
|
32
33
|
"zgeoff/function-verb": "error",
|
|
34
|
+
"zgeoff/verb-contract": "error",
|
|
33
35
|
"zgeoff/test-beside-module": "error",
|
|
34
36
|
"zgeoff/no-file-snapshot": "error",
|
|
35
37
|
"zgeoff/setup-test-only": "error",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zgeoff/oxlint-config",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -12,9 +12,13 @@
|
|
|
12
12
|
"oxlintrc.json",
|
|
13
13
|
"plugin.js",
|
|
14
14
|
"function-verb.js",
|
|
15
|
+
"verb-contract.js",
|
|
16
|
+
"find-function-name.js",
|
|
17
|
+
"is-verb-match.js",
|
|
15
18
|
"no-restricted-words.js",
|
|
16
19
|
"no-abbreviated-names.js",
|
|
17
20
|
"max-consecutive-line-comments.js",
|
|
21
|
+
"no-class.js",
|
|
18
22
|
"no-jsdoc.js",
|
|
19
23
|
"no-comment-rule-override.js",
|
|
20
24
|
"test-beside-module.js",
|
|
@@ -22,7 +26,7 @@
|
|
|
22
26
|
"setup-test-only.js",
|
|
23
27
|
"import-zones.js",
|
|
24
28
|
"import-zones-schema.js",
|
|
25
|
-
"
|
|
29
|
+
"resolve-repo-root.js",
|
|
26
30
|
"load-workspace-manifests.js",
|
|
27
31
|
"load-zone-options.js",
|
|
28
32
|
"make-glob-matcher.js",
|
package/plugin.js
CHANGED
|
@@ -2,12 +2,14 @@ import functionVerb from './function-verb.js';
|
|
|
2
2
|
import importZones from './import-zones.js';
|
|
3
3
|
import maxConsecutiveLineComments from './max-consecutive-line-comments.js';
|
|
4
4
|
import noAbbreviatedNames from './no-abbreviated-names.js';
|
|
5
|
+
import noClass from './no-class.js';
|
|
5
6
|
import noCommentRuleOverride from './no-comment-rule-override.js';
|
|
6
7
|
import noFileSnapshot from './no-file-snapshot.js';
|
|
7
8
|
import noJSDoc from './no-jsdoc.js';
|
|
8
9
|
import noRestrictedWords from './no-restricted-words.js';
|
|
9
10
|
import setupTestOnly from './setup-test-only.js';
|
|
10
11
|
import testBesideModule from './test-beside-module.js';
|
|
12
|
+
import verbContract from './verb-contract.js';
|
|
11
13
|
|
|
12
14
|
// custom rules loaded through oxlint's jsPlugins (ESLint v9 rule API): each
|
|
13
15
|
// bans a shape no native oxlint rule can express, as an esquery selector or a
|
|
@@ -104,10 +106,12 @@ const plugin = {
|
|
|
104
106
|
'Branch with match(...).exhaustive() from ts-pattern, never switch.',
|
|
105
107
|
['SwitchStatement'],
|
|
106
108
|
),
|
|
109
|
+
'no-class': noClass,
|
|
107
110
|
'no-jsdoc': noJSDoc,
|
|
108
111
|
'max-consecutive-line-comments': maxConsecutiveLineComments,
|
|
109
112
|
'no-comment-rule-override': noCommentRuleOverride,
|
|
110
113
|
'function-verb': functionVerb,
|
|
114
|
+
'verb-contract': verbContract,
|
|
111
115
|
'no-restricted-words': noRestrictedWords,
|
|
112
116
|
'no-abbreviated-names': noAbbreviatedNames,
|
|
113
117
|
'test-beside-module': testBesideModule,
|
package/resolve-import-target.js
CHANGED
|
@@ -10,10 +10,10 @@ const sourceExtensions = { '.js': ['.ts', '.tsx'], '.mjs': ['.mts'], '.cjs': ['.
|
|
|
10
10
|
// names through `imports`, and a workspace name to a path in its folder.
|
|
11
11
|
export default function resolveImportTarget(filename, specifier, settings) {
|
|
12
12
|
if (isPathSpecifier(specifier)) {
|
|
13
|
-
return toTarget(
|
|
13
|
+
return toTarget(resolveImportedFile(filename, toFileSpecifier(specifier), settings.extensions));
|
|
14
14
|
}
|
|
15
15
|
|
|
16
|
-
const manifest =
|
|
16
|
+
const manifest = readPackageManifest(dirname(filename), settings.root);
|
|
17
17
|
|
|
18
18
|
return resolveManifestTarget(manifest, specifier, settings);
|
|
19
19
|
}
|
|
@@ -107,7 +107,7 @@ function isPathSpecifier(specifier) {
|
|
|
107
107
|
|
|
108
108
|
const manifests = new Map();
|
|
109
109
|
|
|
110
|
-
function
|
|
110
|
+
function readPackageManifest(dir, root) {
|
|
111
111
|
if (manifests.has(dir)) {
|
|
112
112
|
return manifests.get(dir);
|
|
113
113
|
}
|
|
@@ -119,7 +119,7 @@ function findPackageManifest(dir, root) {
|
|
|
119
119
|
if (existsSync(path)) {
|
|
120
120
|
manifest = { dir, ...JSON.parse(readFileSync(path, 'utf8')) };
|
|
121
121
|
} else if (dir !== root && parent !== dir) {
|
|
122
|
-
manifest =
|
|
122
|
+
manifest = readPackageManifest(parent, root);
|
|
123
123
|
}
|
|
124
124
|
|
|
125
125
|
manifests.set(dir, manifest);
|
|
@@ -211,7 +211,7 @@ function findConditionTarget(value, conditions) {
|
|
|
211
211
|
);
|
|
212
212
|
}
|
|
213
213
|
|
|
214
|
-
function
|
|
214
|
+
function resolveImportedFile(filename, specifier, extensions) {
|
|
215
215
|
const base = resolve(dirname(filename), specifier);
|
|
216
216
|
const swapped = Object.keys(sourceExtensions).flatMap((ext) =>
|
|
217
217
|
base.endsWith(ext)
|
|
@@ -226,9 +226,9 @@ function findImportedFile(filename, specifier, extensions) {
|
|
|
226
226
|
...extensions.map((ext) => join(base, `index${ext}`)),
|
|
227
227
|
];
|
|
228
228
|
|
|
229
|
-
return candidates.find((candidate) =>
|
|
229
|
+
return candidates.find((candidate) => probeFile(candidate)) ?? null;
|
|
230
230
|
}
|
|
231
231
|
|
|
232
|
-
function
|
|
232
|
+
function probeFile(path) {
|
|
233
233
|
return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
|
|
234
234
|
}
|
|
@@ -3,7 +3,7 @@ import { dirname, join } from 'node:path';
|
|
|
3
3
|
|
|
4
4
|
// the nearest ancestor holding `.git` (a directory, or a worktree's file), or
|
|
5
5
|
// null outside a repository
|
|
6
|
-
export default function
|
|
6
|
+
export default function resolveRepoRoot(filename) {
|
|
7
7
|
let dir = dirname(filename);
|
|
8
8
|
|
|
9
9
|
while (!existsSync(join(dir, '.git'))) {
|
package/test-beside-module.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { readdirSync, statSync } from 'node:fs';
|
|
2
2
|
import { basename, dirname, join, relative, sep } from 'node:path';
|
|
3
|
-
import
|
|
3
|
+
import resolveRepoRoot from './resolve-repo-root.js';
|
|
4
4
|
|
|
5
5
|
const testFilePattern = /^(?<base>.+)\.test\.tsx?$/u;
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ const exemptRootDirs = new Set(['e2e', 'evals']);
|
|
|
10
10
|
// the repo root, not oxlint's working directory, so a per-package lint
|
|
11
11
|
// script neither exempts a package's own e2e/ nor flags the root one
|
|
12
12
|
function isUnderExemptRoot(cwd, filename) {
|
|
13
|
-
const [first] = relative(
|
|
13
|
+
const [first] = relative(resolveRepoRoot(filename) ?? cwd, filename).split(sep);
|
|
14
14
|
|
|
15
15
|
return exemptRootDirs.has(first);
|
|
16
16
|
}
|
|
@@ -18,7 +18,7 @@ function isUnderExemptRoot(cwd, filename) {
|
|
|
18
18
|
// a module is `<name>.<ext>` with a single-segment extension, so a
|
|
19
19
|
// declaration file never stands in for one, and neither does another test
|
|
20
20
|
// (`foo.test.ts` beside `foo.test.test.ts`)
|
|
21
|
-
function
|
|
21
|
+
function probeModuleSibling(dir, name) {
|
|
22
22
|
return readdirSync(dir).some((entry) => {
|
|
23
23
|
const dot = entry.lastIndexOf('.');
|
|
24
24
|
|
|
@@ -26,13 +26,13 @@ function hasModuleSibling(dir, name) {
|
|
|
26
26
|
dot > 0 &&
|
|
27
27
|
entry.slice(0, dot) === name &&
|
|
28
28
|
!testFilePattern.test(entry) &&
|
|
29
|
-
|
|
29
|
+
probeFile(join(dir, entry))
|
|
30
30
|
);
|
|
31
31
|
});
|
|
32
32
|
}
|
|
33
33
|
|
|
34
34
|
// follows a symlink, so a linked module counts as the file it points at
|
|
35
|
-
function
|
|
35
|
+
function probeFile(path) {
|
|
36
36
|
return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
|
|
37
37
|
}
|
|
38
38
|
|
|
@@ -57,7 +57,7 @@ const testBesideModule = {
|
|
|
57
57
|
|
|
58
58
|
const name = match.groups.base;
|
|
59
59
|
|
|
60
|
-
if (
|
|
60
|
+
if (probeModuleSibling(dirname(filename), name)) {
|
|
61
61
|
return;
|
|
62
62
|
}
|
|
63
63
|
|
package/verb-contract.js
ADDED
|
@@ -0,0 +1,609 @@
|
|
|
1
|
+
import findFunctionName from './find-function-name.js';
|
|
2
|
+
import isVerbMatch from './is-verb-match.js';
|
|
3
|
+
|
|
4
|
+
// each named function is a frame; I/O inside an unnamed callback counts
|
|
5
|
+
// against the nearest named function around it, since that name makes the
|
|
6
|
+
// promise, while a return counts only for the function it returns from
|
|
7
|
+
const verbContract = {
|
|
8
|
+
meta: {
|
|
9
|
+
type: 'problem',
|
|
10
|
+
messages: {
|
|
11
|
+
pureVerbIO:
|
|
12
|
+
"'{{name}}' starts with '{{verb}}', which promises no I/O, but it {{reason}} — move the I/O out, or rename it with a verb that may do I/O, such as `read` or `probe`.",
|
|
13
|
+
predicateNotBoolean:
|
|
14
|
+
"'{{name}}' starts with '{{verb}}', which promises a boolean, but it declares another return type.",
|
|
15
|
+
booleanWithoutPredicate:
|
|
16
|
+
"'{{name}}' returns a boolean and does no I/O — start its name with `is`, `has`, `can` or `should`.",
|
|
17
|
+
findCannotMiss:
|
|
18
|
+
"'{{name}}' starts with 'find', which promises it can miss, but its return type holds no null or undefined — name it `get` if it cannot miss.",
|
|
19
|
+
getCanMiss:
|
|
20
|
+
"'{{name}}' starts with 'get', which promises it cannot miss, but it can return null or undefined — name it `find`.",
|
|
21
|
+
},
|
|
22
|
+
schema: [],
|
|
23
|
+
},
|
|
24
|
+
create(context) {
|
|
25
|
+
const frames = [];
|
|
26
|
+
|
|
27
|
+
const findNamedFrame = () => frames.findLast((frame) => frame.name !== null) ?? null;
|
|
28
|
+
|
|
29
|
+
const markIO = (reason) => {
|
|
30
|
+
const frame = findNamedFrame();
|
|
31
|
+
|
|
32
|
+
if (frame !== null && frame.ioReason === null) {
|
|
33
|
+
frame.ioReason = reason;
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
// a bare `return` returns undefined as `return undefined` does
|
|
38
|
+
const markReturn = (argument) => {
|
|
39
|
+
const frame = frames.at(-1);
|
|
40
|
+
|
|
41
|
+
if (frame !== undefined && (argument === null || isNullishLiteral(argument))) {
|
|
42
|
+
frame.returnsNullish = true;
|
|
43
|
+
}
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
const enterFunction = (node) => {
|
|
47
|
+
const name = findFunctionName(node);
|
|
48
|
+
|
|
49
|
+
frames.push({ node, name, ioReason: null, returnsNullish: false });
|
|
50
|
+
|
|
51
|
+
// an unnamed async callback counts only through what it awaits
|
|
52
|
+
if (node.async && name !== null) {
|
|
53
|
+
markIO('is async');
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
if (node.type === 'ArrowFunctionExpression' && node.expression) {
|
|
57
|
+
markReturn(node.body);
|
|
58
|
+
}
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
const exitFunction = () => {
|
|
62
|
+
const frame = frames.pop();
|
|
63
|
+
|
|
64
|
+
if (frame.name !== null) {
|
|
65
|
+
checkFrame(context, frame);
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
return {
|
|
70
|
+
FunctionDeclaration: enterFunction,
|
|
71
|
+
FunctionExpression: enterFunction,
|
|
72
|
+
ArrowFunctionExpression: enterFunction,
|
|
73
|
+
'FunctionDeclaration:exit': exitFunction,
|
|
74
|
+
'FunctionExpression:exit': exitFunction,
|
|
75
|
+
'ArrowFunctionExpression:exit': exitFunction,
|
|
76
|
+
ReturnStatement(node) {
|
|
77
|
+
markReturn(node.argument);
|
|
78
|
+
},
|
|
79
|
+
AwaitExpression() {
|
|
80
|
+
markIO('awaits');
|
|
81
|
+
},
|
|
82
|
+
ForOfStatement(node) {
|
|
83
|
+
if (node.await) {
|
|
84
|
+
markIO('awaits');
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
CallExpression(node) {
|
|
88
|
+
const frame = findNamedFrame();
|
|
89
|
+
const reason = frame === null ? null : findCallIO(context, node, frame.node);
|
|
90
|
+
|
|
91
|
+
if (reason !== null) {
|
|
92
|
+
markIO(reason);
|
|
93
|
+
}
|
|
94
|
+
},
|
|
95
|
+
TaggedTemplateExpression(node) {
|
|
96
|
+
if (isShellTarget(resolveCallTarget(context, node, node.tag))) {
|
|
97
|
+
markIO('runs a `$` shell command');
|
|
98
|
+
}
|
|
99
|
+
},
|
|
100
|
+
MemberExpression(node) {
|
|
101
|
+
if (isEnvRead(context, node)) {
|
|
102
|
+
markIO('reads the environment');
|
|
103
|
+
}
|
|
104
|
+
},
|
|
105
|
+
};
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
|
|
109
|
+
export default verbContract;
|
|
110
|
+
|
|
111
|
+
// the role table's verbs that promise no I/O
|
|
112
|
+
const pureVerbs = [
|
|
113
|
+
'is',
|
|
114
|
+
'has',
|
|
115
|
+
'can',
|
|
116
|
+
'should',
|
|
117
|
+
'build',
|
|
118
|
+
'parse',
|
|
119
|
+
'format',
|
|
120
|
+
'render',
|
|
121
|
+
'pick',
|
|
122
|
+
'find',
|
|
123
|
+
'get',
|
|
124
|
+
'collect',
|
|
125
|
+
'to',
|
|
126
|
+
];
|
|
127
|
+
|
|
128
|
+
const predicateVerbs = ['is', 'has', 'can', 'should', 'probe'];
|
|
129
|
+
|
|
130
|
+
// the role table's verbs that may do I/O, and common free verbs that name a
|
|
131
|
+
// change to the world; a call to a function named with one is I/O
|
|
132
|
+
const effectfulVerbs = [
|
|
133
|
+
'probe',
|
|
134
|
+
'read',
|
|
135
|
+
'write',
|
|
136
|
+
'run',
|
|
137
|
+
'create',
|
|
138
|
+
'remove',
|
|
139
|
+
'load',
|
|
140
|
+
'update',
|
|
141
|
+
'send',
|
|
142
|
+
'start',
|
|
143
|
+
'stop',
|
|
144
|
+
'wait',
|
|
145
|
+
'set',
|
|
146
|
+
'apply',
|
|
147
|
+
'record',
|
|
148
|
+
'claim',
|
|
149
|
+
'open',
|
|
150
|
+
'close',
|
|
151
|
+
'spawn',
|
|
152
|
+
'print',
|
|
153
|
+
'emit',
|
|
154
|
+
'release',
|
|
155
|
+
'register',
|
|
156
|
+
'upsert',
|
|
157
|
+
'insert',
|
|
158
|
+
'refresh',
|
|
159
|
+
'restart',
|
|
160
|
+
];
|
|
161
|
+
|
|
162
|
+
// a function returning a success flag, such as `removeFile` or `tryLock`,
|
|
163
|
+
// rightly returns a boolean without a predicate verb, and a framework prefix
|
|
164
|
+
// such as a React hook's `use` wins over the predicate verbs
|
|
165
|
+
const flagVerbs = [...effectfulVerbs, 'try', 'use', 'on', 'handle'];
|
|
166
|
+
|
|
167
|
+
function checkFrame(context, frame) {
|
|
168
|
+
const name = frame.name.name;
|
|
169
|
+
const returnType = frame.node.returnType?.typeAnnotation ?? null;
|
|
170
|
+
const pureVerb = findVerb(name, pureVerbs);
|
|
171
|
+
const predicateVerb = findVerb(name, predicateVerbs);
|
|
172
|
+
const report = (messageId, data) =>
|
|
173
|
+
context.report({ node: frame.name, messageId, data: { name, ...data } });
|
|
174
|
+
|
|
175
|
+
if (pureVerb !== null && frame.ioReason !== null) {
|
|
176
|
+
report('pureVerbIO', { verb: pureVerb, reason: frame.ioReason });
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
const localTypes = collectLocalTypes(context.sourceCode.ast);
|
|
180
|
+
const declared = returnType === null ? null : collectTypeKinds(returnType, localTypes);
|
|
181
|
+
const resolved = returnType === null ? null : collectTypeKinds(returnType, localTypes, true);
|
|
182
|
+
|
|
183
|
+
if (predicateVerb !== null && resolved !== null && !isBooleanOrOpen(resolved)) {
|
|
184
|
+
report('predicateNotBoolean', { verb: predicateVerb });
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
const isUnnamedFlag =
|
|
188
|
+
predicateVerb === null &&
|
|
189
|
+
frame.ioReason === null &&
|
|
190
|
+
declared !== null &&
|
|
191
|
+
declared.every((kind) => kind === 'boolean') &&
|
|
192
|
+
findVerb(name, flagVerbs) === null;
|
|
193
|
+
|
|
194
|
+
if (isUnnamedFlag) {
|
|
195
|
+
report('booleanWithoutPredicate', {});
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
const missKinds = new Set(['nullish', 'void', 'open']);
|
|
199
|
+
|
|
200
|
+
if (pureVerb === 'find' && resolved !== null && !resolved.some((kind) => missKinds.has(kind))) {
|
|
201
|
+
report('findCannotMiss', {});
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
const declaresMiss = resolved !== null && resolved.includes('nullish');
|
|
205
|
+
|
|
206
|
+
if (pureVerb === 'get' && (frame.returnsNullish === true || declaresMiss)) {
|
|
207
|
+
report('getCanMiss', {});
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function findVerb(name, verbs) {
|
|
212
|
+
return verbs.find((verb) => isVerbMatch(name, verb)) ?? null;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function isBooleanOrOpen(kinds) {
|
|
216
|
+
return kinds.every((kind) => kind === 'boolean' || kind === 'open');
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// the kind of each member of a declared type, read without type information:
|
|
220
|
+
// a union splits into its members, a reference follows the file's own type
|
|
221
|
+
// aliases, and `resolvePromise` reads a promise as the value it resolves to
|
|
222
|
+
function collectTypeKinds(type, localTypes, resolvePromise = false, seen = new Set()) {
|
|
223
|
+
if (type.type === 'TSUnionType') {
|
|
224
|
+
return type.types.flatMap((member) =>
|
|
225
|
+
collectTypeKinds(member, localTypes, resolvePromise, seen),
|
|
226
|
+
);
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
if (type.type === 'TSParenthesizedType' || isReadonlyOperator(type)) {
|
|
230
|
+
return collectTypeKinds(type.typeAnnotation, localTypes, resolvePromise, seen);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
if (type.type !== 'TSTypeReference') {
|
|
234
|
+
return [pickTypeKind(type)];
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
const name = type.typeName.type === 'Identifier' ? type.typeName.name : null;
|
|
238
|
+
const alias = name === null ? undefined : localTypes.aliases.get(name);
|
|
239
|
+
|
|
240
|
+
if (alias !== undefined && !seen.has(name)) {
|
|
241
|
+
return collectTypeKinds(alias, localTypes, resolvePromise, new Set([...seen, name]));
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
const typeArguments = type.typeArguments ?? type.typeParameters;
|
|
245
|
+
|
|
246
|
+
if (resolvePromise && name === 'Promise' && typeArguments?.params.length === 1) {
|
|
247
|
+
const [value] = typeArguments.params;
|
|
248
|
+
|
|
249
|
+
return collectTypeKinds(value, localTypes, resolvePromise, seen);
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
// an interface never holds null; any other reference, such as an import or
|
|
253
|
+
// a type parameter, is a type the rule cannot read
|
|
254
|
+
return [localTypes.interfaces.has(name) ? 'value' : 'open'];
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
function isReadonlyOperator(type) {
|
|
258
|
+
return type.type === 'TSTypeOperator' && type.operator === 'readonly';
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
// a type whose members the rule can see and that never holds null; any other
|
|
262
|
+
// shape, such as an indexed access or a conditional type, is open
|
|
263
|
+
const valueTypes = new Set([
|
|
264
|
+
'TSStringKeyword',
|
|
265
|
+
'TSNumberKeyword',
|
|
266
|
+
'TSBigIntKeyword',
|
|
267
|
+
'TSSymbolKeyword',
|
|
268
|
+
'TSObjectKeyword',
|
|
269
|
+
'TSNeverKeyword',
|
|
270
|
+
'TSLiteralType',
|
|
271
|
+
'TSTemplateLiteralType',
|
|
272
|
+
'TSArrayType',
|
|
273
|
+
'TSTupleType',
|
|
274
|
+
'TSTypeLiteral',
|
|
275
|
+
'TSFunctionType',
|
|
276
|
+
'TSConstructorType',
|
|
277
|
+
]);
|
|
278
|
+
|
|
279
|
+
function pickTypeKind(type) {
|
|
280
|
+
if (
|
|
281
|
+
type.type === 'TSBooleanKeyword' ||
|
|
282
|
+
(type.type === 'TSTypePredicate' && !type.asserts) ||
|
|
283
|
+
(type.type === 'TSLiteralType' && typeof type.literal.value === 'boolean')
|
|
284
|
+
) {
|
|
285
|
+
return 'boolean';
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
if (type.type === 'TSNullKeyword' || type.type === 'TSUndefinedKeyword') {
|
|
289
|
+
return 'nullish';
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
if (type.type === 'TSVoidKeyword') {
|
|
293
|
+
return 'void';
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
// `asserts value is T` throws instead of returning a boolean
|
|
297
|
+
if (type.type === 'TSTypePredicate' || valueTypes.has(type.type)) {
|
|
298
|
+
return 'value';
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
return 'open';
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
const localTypesByProgram = new WeakMap();
|
|
305
|
+
|
|
306
|
+
function collectLocalTypes(program) {
|
|
307
|
+
const cached = localTypesByProgram.get(program);
|
|
308
|
+
|
|
309
|
+
if (cached !== undefined) {
|
|
310
|
+
return cached;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
const localTypes = { aliases: new Map(), interfaces: new Set() };
|
|
314
|
+
|
|
315
|
+
for (const statement of program.body) {
|
|
316
|
+
const declaration =
|
|
317
|
+
statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
|
|
318
|
+
|
|
319
|
+
if (
|
|
320
|
+
declaration?.type === 'TSTypeAliasDeclaration' &&
|
|
321
|
+
(declaration.typeParameters ?? null) === null
|
|
322
|
+
) {
|
|
323
|
+
localTypes.aliases.set(declaration.id.name, declaration.typeAnnotation);
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
if (declaration?.type === 'TSInterfaceDeclaration') {
|
|
327
|
+
localTypes.interfaces.add(declaration.id.name);
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
localTypesByProgram.set(program, localTypes);
|
|
332
|
+
|
|
333
|
+
return localTypes;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
function isNullishLiteral(node) {
|
|
337
|
+
return (
|
|
338
|
+
(node.type === 'Literal' && node.raw === 'null') ||
|
|
339
|
+
(node.type === 'Identifier' && node.name === 'undefined')
|
|
340
|
+
);
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
const kyselyRunMethods = new Set(['execute', 'executeTakeFirst', 'executeTakeFirstOrThrow']);
|
|
344
|
+
const bunIOMembers = new Set(['spawn', 'spawnSync', 'file', 'write', '$']);
|
|
345
|
+
|
|
346
|
+
function findCallIO(context, node, frameNode) {
|
|
347
|
+
const callee = node.callee;
|
|
348
|
+
const rootName = findRootName(callee);
|
|
349
|
+
const memberName = callee.type === 'MemberExpression' ? findMemberName(callee) : null;
|
|
350
|
+
const binding = rootName === null ? null : findBinding(context, node, rootName);
|
|
351
|
+
const target = resolveCallTarget(context, node, callee);
|
|
352
|
+
const targetSource = findImportSource(target.binding);
|
|
353
|
+
|
|
354
|
+
if (isShellTarget(target)) {
|
|
355
|
+
return 'runs a `$` shell command';
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
if (target.rootName === 'fetch' && target.binding === null && target.memberName === null) {
|
|
359
|
+
return 'calls `fetch`';
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
if (memberName !== null && kyselyRunMethods.has(memberName)) {
|
|
363
|
+
return 'runs a database query';
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
if (isBunGlobal(target) && bunIOMembers.has(target.memberName)) {
|
|
367
|
+
return `calls \`Bun.${target.memberName}\``;
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
if (targetSource !== null && isIOImport(targetSource, target)) {
|
|
371
|
+
return `calls \`${rootName}\` from \`${targetSource}\``;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
const isOwn =
|
|
375
|
+
isOwnCallee({ rootName, binding, source: findImportSource(binding), memberName }, frameNode) &&
|
|
376
|
+
isOwnCallee({ ...target, source: targetSource }, frameNode);
|
|
377
|
+
|
|
378
|
+
if (!isOwn) {
|
|
379
|
+
return null;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
// a bare method name such as `map.set` or `fn.apply` is a built-in that a
|
|
383
|
+
// name cannot tell from I/O, whether the call names it or an alias holds it
|
|
384
|
+
const names = [
|
|
385
|
+
{
|
|
386
|
+
name: callee.type === 'Identifier' ? callee.name : memberName,
|
|
387
|
+
isMethod: memberName !== null,
|
|
388
|
+
},
|
|
389
|
+
{ name: target.memberName ?? target.rootName, isMethod: target.memberName !== null },
|
|
390
|
+
];
|
|
391
|
+
|
|
392
|
+
const effectful = names.find((entry) => {
|
|
393
|
+
const verb = entry.name === null ? null : findVerb(entry.name, effectfulVerbs);
|
|
394
|
+
|
|
395
|
+
return verb !== null && !(entry.isMethod && entry.name === verb);
|
|
396
|
+
});
|
|
397
|
+
|
|
398
|
+
return effectful === undefined ? null : `calls '${effectful.name}', whose verb may do I/O`;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
// the source a call reaches: its root binding and the member taken straight
|
|
402
|
+
// off the root, as `spawn` in `Bun.spawn(...)`, followed through each local
|
|
403
|
+
// alias such as `const read = fs.readFileSync` or `const { spawn } = Bun`
|
|
404
|
+
function resolveCallTarget(context, node, callee) {
|
|
405
|
+
const rootName = findRootName(callee);
|
|
406
|
+
let current = {
|
|
407
|
+
rootName,
|
|
408
|
+
binding: rootName === null ? null : findBinding(context, node, rootName),
|
|
409
|
+
memberName: findRootMemberName(callee),
|
|
410
|
+
};
|
|
411
|
+
|
|
412
|
+
for (let depth = 0; depth < 8; depth++) {
|
|
413
|
+
const declarator = findAliasDeclarator(current.binding);
|
|
414
|
+
|
|
415
|
+
if (declarator === null) {
|
|
416
|
+
return current;
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
const init = declarator.init;
|
|
420
|
+
const initRoot = findRootName(init);
|
|
421
|
+
|
|
422
|
+
current = {
|
|
423
|
+
rootName: initRoot,
|
|
424
|
+
binding: initRoot === null ? null : findBinding(context, init, initRoot),
|
|
425
|
+
memberName:
|
|
426
|
+
findRootMemberName(init) ??
|
|
427
|
+
findPatternKey(declarator.id, current.rootName) ??
|
|
428
|
+
current.memberName,
|
|
429
|
+
};
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
return current;
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
// the member read straight off a chain's root: `$` in `bun.$.cwd('a')`
|
|
436
|
+
function findRootMemberName(node) {
|
|
437
|
+
let current = node;
|
|
438
|
+
let memberName = null;
|
|
439
|
+
|
|
440
|
+
while (current.type === 'MemberExpression' || current.type === 'CallExpression') {
|
|
441
|
+
if (current.type === 'MemberExpression') {
|
|
442
|
+
memberName = findMemberName(current);
|
|
443
|
+
current = current.object;
|
|
444
|
+
} else {
|
|
445
|
+
current = current.callee;
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
return memberName;
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
function findAliasDeclarator(binding) {
|
|
453
|
+
const definition = binding?.defs[0];
|
|
454
|
+
const declarator = definition?.type === 'Variable' ? definition.node : null;
|
|
455
|
+
const init = declarator?.init ?? null;
|
|
456
|
+
|
|
457
|
+
return init !== null && (init.type === 'Identifier' || init.type === 'MemberExpression')
|
|
458
|
+
? declarator
|
|
459
|
+
: null;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
// the key a destructured binding takes, as `spawn` in `const { spawn: run } = Bun`
|
|
463
|
+
function findPatternKey(pattern, name) {
|
|
464
|
+
if (pattern.type !== 'ObjectPattern') {
|
|
465
|
+
return null;
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
const property = pattern.properties.find(
|
|
469
|
+
(entry) =>
|
|
470
|
+
entry.type === 'Property' && entry.value.type === 'Identifier' && entry.value.name === name,
|
|
471
|
+
);
|
|
472
|
+
|
|
473
|
+
return property === undefined ? null : findKeyName(property);
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
function findKeyName(property) {
|
|
477
|
+
return !property.computed && property.key.type === 'Identifier' ? property.key.name : null;
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
function isBunGlobal(target) {
|
|
481
|
+
return target.rootName === 'Bun' && target.binding === null;
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
// Bun's shell: the `$` export of `bun` under any import form or alias, or
|
|
485
|
+
// `Bun.$`; a parameter or local named `$` is some other function
|
|
486
|
+
function isShellTarget(target) {
|
|
487
|
+
if (isBunGlobal(target)) {
|
|
488
|
+
return target.memberName === '$';
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
if (findImportSource(target.binding) !== 'bun') {
|
|
492
|
+
return false;
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
const specifier = target.binding.defs[0].node;
|
|
496
|
+
|
|
497
|
+
return specifier.type === 'ImportSpecifier'
|
|
498
|
+
? specifier.imported.name === '$'
|
|
499
|
+
: target.memberName === '$';
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
function findMemberName(member) {
|
|
503
|
+
return !member.computed && member.property.type === 'Identifier' ? member.property.name : null;
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
function findRootName(node) {
|
|
507
|
+
let current = node;
|
|
508
|
+
|
|
509
|
+
while (current.type === 'MemberExpression' || current.type === 'CallExpression') {
|
|
510
|
+
current = current.type === 'MemberExpression' ? current.object : current.callee;
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
if (current.type === 'ThisExpression') {
|
|
514
|
+
return 'this';
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
return current.type === 'Identifier' ? current.name : null;
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
// the global itself, so a local binding of the same name passes
|
|
521
|
+
function isGlobalName(context, node, name) {
|
|
522
|
+
return (
|
|
523
|
+
node !== undefined &&
|
|
524
|
+
node.type === 'Identifier' &&
|
|
525
|
+
node.name === name &&
|
|
526
|
+
findBinding(context, node, name) === null
|
|
527
|
+
);
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
function findBinding(context, node, name) {
|
|
531
|
+
let scope = context.sourceCode.getScope(node);
|
|
532
|
+
|
|
533
|
+
while (scope !== null) {
|
|
534
|
+
const variable = scope.set.get(name);
|
|
535
|
+
|
|
536
|
+
if (variable !== undefined && variable.defs.length > 0) {
|
|
537
|
+
return variable;
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
scope = scope.upper;
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
return null;
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
function findImportSource(variable) {
|
|
547
|
+
if (variable === null) {
|
|
548
|
+
return null;
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
const [definition] = variable.defs;
|
|
552
|
+
|
|
553
|
+
return definition.type === 'ImportBinding' ? definition.parent.source.value : null;
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
const ioModules = new Set(['fs', 'fs/promises', 'child_process']);
|
|
557
|
+
|
|
558
|
+
function isIOImport(source, target) {
|
|
559
|
+
if (ioModules.has(source.replace(/^node:/u, ''))) {
|
|
560
|
+
return true;
|
|
561
|
+
}
|
|
562
|
+
|
|
563
|
+
if (source !== 'bun') {
|
|
564
|
+
return false;
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
const specifier = target.binding.defs[0].node;
|
|
568
|
+
const imported =
|
|
569
|
+
specifier.type === 'ImportSpecifier' ? specifier.imported.name : target.memberName;
|
|
570
|
+
|
|
571
|
+
return bunIOMembers.has(imported);
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
// a callee declared in the file or imported by a relative or aliased path; a
|
|
575
|
+
// package keeps its own naming, and a method on a value the function makes
|
|
576
|
+
// itself, such as `date.setUTCDate`, changes only that value
|
|
577
|
+
function isOwnCallee(callee, frameNode) {
|
|
578
|
+
if (callee.rootName === 'this') {
|
|
579
|
+
return true;
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
if (callee.binding === null) {
|
|
583
|
+
return false;
|
|
584
|
+
}
|
|
585
|
+
|
|
586
|
+
if (callee.source !== null) {
|
|
587
|
+
return ['.', '/', '#', '~/', '@/'].some((prefix) => callee.source.startsWith(prefix));
|
|
588
|
+
}
|
|
589
|
+
|
|
590
|
+
return callee.memberName === null || !isLocalVariable(callee.binding, frameNode);
|
|
591
|
+
}
|
|
592
|
+
|
|
593
|
+
function isLocalVariable(binding, frameNode) {
|
|
594
|
+
const [definition] = binding.defs;
|
|
595
|
+
const [start, end] = frameNode.range;
|
|
596
|
+
|
|
597
|
+
return (
|
|
598
|
+
definition.type === 'Variable' &&
|
|
599
|
+
definition.name.range[0] >= start &&
|
|
600
|
+
definition.name.range[1] <= end
|
|
601
|
+
);
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
function isEnvRead(context, node) {
|
|
605
|
+
return (
|
|
606
|
+
findMemberName(node) === 'env' &&
|
|
607
|
+
(isGlobalName(context, node.object, 'process') || isGlobalName(context, node.object, 'Bun'))
|
|
608
|
+
);
|
|
609
|
+
}
|