@zgeoff/oxlint-config 0.3.0 → 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 CHANGED
@@ -6,8 +6,11 @@ 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. `zgeoff/function-verb` enforces the function-naming taxonomy from
10
- the shared agent guidelines, `zgeoff/test-beside-module` keeps each test file beside the module it
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,
@@ -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
- Every function declaration, function-valued variable, and class method must start with a verb from
47
- the function-naming taxonomy. Banned verbs report their taxonomy replacement (`fetchUser` → use
48
- `read`). Object-literal properties are exempt — they overwhelmingly implement externally-defined
49
- shapes whose names the author doesn't choose — as are names not starting with a lowercase letter.
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", { "verbs": ["walk"], "exemptNames": ["main"] }],
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
@@ -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
- // the closed verb list from the shared function-naming taxonomy, one entry
2
- // per table row; extending it here without the matching taxonomy edit fails
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 templated taxonomy entries (`with<X>`, `handle<Event>`, …): the verb is
85
- // only valid with a suffix, so the bare word is not a function name
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
- function isVerbMatch(name, verb, bareAllowed) {
117
- if (name === verb) {
118
- return bareAllowed;
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, true)) {
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, verbs, exemptNames) {
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 (findAllowedVerb(name, verbs) !== null) {
145
- return null;
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 { messageId: 'unknownVerb', data: { name } };
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 options = context.options[0] ?? {};
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 checkName = (id) => {
191
- const report = planReport(id.name, verbs, exemptNames);
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(node) {
200
- if (node.id !== null) {
201
- checkName(node.id);
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 buildFileState(context) {
12
+ function loadFileState(context) {
13
13
  const options = loadZoneOptions(context.options[0] ?? {});
14
14
  const filename = context.physicalFilename;
15
- const root = findRepoRoot(filename) ?? context.cwd;
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 = buildFileState(context);
301
+ const file = loadFileState(context);
302
302
 
303
303
  return {
304
304
  Program(node) {
@@ -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
+ }
@@ -1,6 +1,6 @@
1
1
  import { readFileSync, readdirSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import findRepoRoot from './find-repo-root.js';
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 = findRepoRoot(context.filename);
50
+ const root = resolveRepoRoot(context.filename);
51
51
 
52
52
  if (root === null) {
53
53
  return {};
@@ -33,7 +33,7 @@ const noFileSnapshot = {
33
33
  const filename = context.physicalFilename;
34
34
  const name = `${basename(filename)}.snap`;
35
35
 
36
- if (!isFile(join(dirname(filename), '__snapshots__', name))) {
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 isFile(path) {
54
+ function probeFile(path) {
55
55
  return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
56
56
  }
57
57
 
package/oxlintrc.json CHANGED
@@ -31,6 +31,7 @@
31
31
  "zgeoff/max-consecutive-line-comments": ["error", { "max": 3 }],
32
32
  "zgeoff/no-comment-rule-override": "error",
33
33
  "zgeoff/function-verb": "error",
34
+ "zgeoff/verb-contract": "error",
34
35
  "zgeoff/test-beside-module": "error",
35
36
  "zgeoff/no-file-snapshot": "error",
36
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.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,6 +12,9 @@
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",
@@ -23,7 +26,7 @@
23
26
  "setup-test-only.js",
24
27
  "import-zones.js",
25
28
  "import-zones-schema.js",
26
- "find-repo-root.js",
29
+ "resolve-repo-root.js",
27
30
  "load-workspace-manifests.js",
28
31
  "load-zone-options.js",
29
32
  "make-glob-matcher.js",
package/plugin.js CHANGED
@@ -9,6 +9,7 @@ import noJSDoc from './no-jsdoc.js';
9
9
  import noRestrictedWords from './no-restricted-words.js';
10
10
  import setupTestOnly from './setup-test-only.js';
11
11
  import testBesideModule from './test-beside-module.js';
12
+ import verbContract from './verb-contract.js';
12
13
 
13
14
  // custom rules loaded through oxlint's jsPlugins (ESLint v9 rule API): each
14
15
  // bans a shape no native oxlint rule can express, as an esquery selector or a
@@ -110,6 +111,7 @@ const plugin = {
110
111
  'max-consecutive-line-comments': maxConsecutiveLineComments,
111
112
  'no-comment-rule-override': noCommentRuleOverride,
112
113
  'function-verb': functionVerb,
114
+ 'verb-contract': verbContract,
113
115
  'no-restricted-words': noRestrictedWords,
114
116
  'no-abbreviated-names': noAbbreviatedNames,
115
117
  'test-beside-module': testBesideModule,
@@ -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(findImportedFile(filename, toFileSpecifier(specifier), settings.extensions));
13
+ return toTarget(resolveImportedFile(filename, toFileSpecifier(specifier), settings.extensions));
14
14
  }
15
15
 
16
- const manifest = findPackageManifest(dirname(filename), settings.root);
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 findPackageManifest(dir, root) {
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 = findPackageManifest(parent, root);
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 findImportedFile(filename, specifier, extensions) {
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) => isFile(candidate)) ?? null;
229
+ return candidates.find((candidate) => probeFile(candidate)) ?? null;
230
230
  }
231
231
 
232
- function isFile(path) {
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 findRepoRoot(filename) {
6
+ export default function resolveRepoRoot(filename) {
7
7
  let dir = dirname(filename);
8
8
 
9
9
  while (!existsSync(join(dir, '.git'))) {
@@ -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 findRepoRoot from './find-repo-root.js';
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(findRepoRoot(filename) ?? cwd, filename).split(sep);
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 hasModuleSibling(dir, name) {
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
- isFile(join(dir, entry))
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 isFile(path) {
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 (hasModuleSibling(dirname(filename), name)) {
60
+ if (probeModuleSibling(dirname(filename), name)) {
61
61
  return;
62
62
  }
63
63
 
@@ -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
+ }