@zgeoff/oxlint-config 0.5.2 → 0.6.1

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
@@ -5,8 +5,8 @@ restriction-rule cherry-picks, comment-style enforcement via `@stylistic`, and a
5
5
  (`zgeoff/*` rules) banning shapes no native oxlint rule can express — top-level arrows, nested
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
- `switch` statement, every JSDoc block, any run of more than three line comments, and a repo config
9
- that loosens either comment rule.
8
+ `switch` statement, every JSDoc block, any run of more than three line comments, a type claim with
9
+ no `as`, and a repo config that loosens a comment rule or a type-assertion rule.
10
10
 
11
11
  The plugin's other rules each check one convention. `zgeoff/function-verb` bans the vague and
12
12
  near-synonym verbs of the shared function-naming rules, `zgeoff/verb-contract` checks the promise
@@ -45,6 +45,37 @@ import config from '@zgeoff/oxlint-config';
45
45
  The plugin is addressable on its own at `@zgeoff/oxlint-config/plugin` for configs that want the
46
46
  `zgeoff/*` rules without the rest.
47
47
 
48
+ ## Type assertions
49
+
50
+ `typescript/consistent-type-assertions` runs with `assertionStyle: "never"`, so every type assertion
51
+ fails: `x as T`, `<T>x` and `x as unknown as T`. `as const` and `satisfies` pass, because neither
52
+ claims a type the checker cannot prove. `typescript/no-unsafe-type-assertion` is off, because the
53
+ ban reports every assertion that rule checks.
54
+
55
+ Replace an assertion with a type guard, a type annotation, `satisfies`, or a typed helper from
56
+ `@zgeoff/std`. An assertion that survives carries a disable comment on the line above it, with its
57
+ approval and reason after `--`:
58
+
59
+ ```ts
60
+ // oxlint-disable-next-line typescript/consistent-type-assertions -- approved <issue>: <reason>
61
+ ```
62
+
63
+ `zgeoff/no-hidden-cast` reports a claim of a type that has no `as` for the ban to see:
64
+
65
+ - a type argument on a `sql` tagged template, such as Kysely's `sql<T>`;
66
+ - a call to Kysely's `$castTo()`, `$narrowType()` or `$assertType()`;
67
+ - a type argument on a `query()` or `prepare()` call, such as bun:sqlite's;
68
+ - a type argument on Pulumi `Config`'s `getObject()`, `requireObject()`, `getSecretObject()` or
69
+ `requireSecretObject()`.
70
+
71
+ The rule needs no type information, so it matches by name: a method of another library with the same
72
+ name and a type argument is reported too. Read such a value as `unknown` and parse it with zod, or
73
+ query through Kysely over declared table types.
74
+
75
+ Every repo runs both rules as this config ships them. `zgeoff/no-comment-rule-override` reports a
76
+ repo-root `.oxlintrc*.json` that sets either rule under any plugin prefix, so a disable comment on
77
+ the line is the only way to keep an assertion.
78
+
48
79
  ## `zgeoff/function-verb`
49
80
 
50
81
  The rule reports a function, method, or function-valued variable or property whose name starts with
@@ -0,0 +1,89 @@
1
+ // the kind of each member of a declared type, read without type information:
2
+ // a union splits into its members, a reference follows the file's own type
3
+ // aliases, and `resolvePromise` reads a promise as the value it resolves to
4
+ export default function collectTypeKinds(
5
+ type,
6
+ localTypes,
7
+ resolvePromise = false,
8
+ seen = new Set(),
9
+ ) {
10
+ if (type.type === 'TSUnionType') {
11
+ return type.types.flatMap((member) =>
12
+ collectTypeKinds(member, localTypes, resolvePromise, seen),
13
+ );
14
+ }
15
+
16
+ if (type.type === 'TSParenthesizedType' || isReadonlyOperator(type)) {
17
+ return collectTypeKinds(type.typeAnnotation, localTypes, resolvePromise, seen);
18
+ }
19
+
20
+ if (type.type !== 'TSTypeReference') {
21
+ return [pickTypeKind(type)];
22
+ }
23
+
24
+ const name = type.typeName.type === 'Identifier' ? type.typeName.name : null;
25
+ const alias = name === null ? undefined : localTypes.aliases.get(name);
26
+
27
+ if (alias !== undefined && !seen.has(name)) {
28
+ return collectTypeKinds(alias, localTypes, resolvePromise, new Set([...seen, name]));
29
+ }
30
+
31
+ const typeArguments = type.typeArguments ?? type.typeParameters;
32
+
33
+ if (resolvePromise && name === 'Promise' && typeArguments?.params.length === 1) {
34
+ const [value] = typeArguments.params;
35
+
36
+ return collectTypeKinds(value, localTypes, resolvePromise, seen);
37
+ }
38
+
39
+ // an interface never holds null; any other reference, such as an import or
40
+ // a type parameter, is a type the rule cannot read
41
+ return [localTypes.interfaces.has(name) ? 'value' : 'open'];
42
+ }
43
+
44
+ function isReadonlyOperator(type) {
45
+ return type.type === 'TSTypeOperator' && type.operator === 'readonly';
46
+ }
47
+
48
+ // a type whose members the rule can see and that never holds null; any other
49
+ // shape, such as an indexed access or a conditional type, is open
50
+ const valueTypes = new Set([
51
+ 'TSStringKeyword',
52
+ 'TSNumberKeyword',
53
+ 'TSBigIntKeyword',
54
+ 'TSSymbolKeyword',
55
+ 'TSObjectKeyword',
56
+ 'TSNeverKeyword',
57
+ 'TSLiteralType',
58
+ 'TSTemplateLiteralType',
59
+ 'TSArrayType',
60
+ 'TSTupleType',
61
+ 'TSTypeLiteral',
62
+ 'TSFunctionType',
63
+ 'TSConstructorType',
64
+ ]);
65
+
66
+ function pickTypeKind(type) {
67
+ if (
68
+ type.type === 'TSBooleanKeyword' ||
69
+ (type.type === 'TSTypePredicate' && !type.asserts) ||
70
+ (type.type === 'TSLiteralType' && typeof type.literal.value === 'boolean')
71
+ ) {
72
+ return 'boolean';
73
+ }
74
+
75
+ if (type.type === 'TSNullKeyword' || type.type === 'TSUndefinedKeyword') {
76
+ return 'nullish';
77
+ }
78
+
79
+ if (type.type === 'TSVoidKeyword') {
80
+ return 'void';
81
+ }
82
+
83
+ // `asserts value is T` throws instead of returning a boolean
84
+ if (type.type === 'TSTypePredicate' || valueTypes.has(type.type)) {
85
+ return 'value';
86
+ }
87
+
88
+ return 'open';
89
+ }
@@ -12,7 +12,7 @@ const noCommentRuleOverride = {
12
12
  type: 'problem',
13
13
  messages: {
14
14
  override:
15
- '{{config}} sets {{rule}}. Delete the setting: every repo runs the comment rules as @zgeoff/oxlint-config ships them.',
15
+ '{{config}} sets {{rule}}. Delete the setting: every repo runs {{rule}} as @zgeoff/oxlint-config ships it.',
16
16
  },
17
17
  schema: [],
18
18
  },
@@ -45,14 +45,21 @@ export default noCommentRuleOverride;
45
45
 
46
46
  const configPattern = /^\.oxlintrc(?:\.[\w-]+)?\.jsonc?$/u;
47
47
 
48
- // every repo runs the comment rules exactly as this config ships them
49
- const lockedRules = ['zgeoff/no-jsdoc', 'zgeoff/max-consecutive-line-comments'];
48
+ // every repo runs the comment rules and the type-assertion rules exactly as
49
+ // this config ships them, each named here without its plugin prefix
50
+ const lockedRules = [
51
+ 'no-jsdoc',
52
+ 'max-consecutive-line-comments',
53
+ 'consistent-type-assertions',
54
+ 'no-hidden-cast',
55
+ ];
50
56
 
51
- // a rule key, as opposed to the same text inside a comment or a string value
52
- const keyPatterns = lockedRules.map((rule) => ({
53
- rule,
54
- pattern: new RegExp(`"${rule}"\\s*:`, 'u'),
55
- }));
57
+ // a rule key under any plugin prefix or none, since oxlint also reads
58
+ // `@typescript-eslint/consistent-type-assertions` and the bare name, as
59
+ // opposed to the same text inside a comment or a string value
60
+ const keyPatterns = lockedRules.map(
61
+ (rule) => new RegExp(`"(?<key>(?:[^"/\\s]+/)?${rule})"\\s*:`, 'gu'),
62
+ );
56
63
 
57
64
  function loadOverrides(root) {
58
65
  const configs = readdirSync(root).filter((name) => configPattern.test(name));
@@ -60,9 +67,11 @@ function loadOverrides(root) {
60
67
  return configs.flatMap((name) => {
61
68
  const text = buildCommentFreeText(readFileSync(join(root, name), 'utf8'));
62
69
 
63
- return keyPatterns
64
- .filter((entry) => entry.pattern.test(text))
65
- .map((entry) => ({ config: name, rule: entry.rule }));
70
+ return keyPatterns.flatMap((pattern) => {
71
+ const keys = new Set(Array.from(text.matchAll(pattern), (match) => match.groups.key));
72
+
73
+ return [...keys].map((rule) => ({ config: name, rule }));
74
+ });
66
75
  });
67
76
  }
68
77
 
@@ -0,0 +1,71 @@
1
+ // a plain lint run has no types to tell Kysely's `sql` or bun:sqlite's
2
+ // `query` from another library's of the same name, so the rule matches by name
3
+ const castMethods = new Set(['$castTo', '$narrowType', '$assertType']);
4
+ const rowMethods = new Set(['query', 'prepare']);
5
+ const configMethods = new Set([
6
+ 'getObject',
7
+ 'requireObject',
8
+ 'getSecretObject',
9
+ 'requireSecretObject',
10
+ ]);
11
+
12
+ const noHiddenCast = {
13
+ meta: {
14
+ type: 'problem',
15
+ messages: {
16
+ sqlType:
17
+ 'A type argument on `sql` claims a result type that the database never checks. Drop it, read the result as `unknown`, and parse it with zod or narrow it with a guard.',
18
+ castMethod:
19
+ '`{{method}}()` claims a type that Kysely never checks. Declare the type in the table types, or narrow the result with a guard.',
20
+ rowType:
21
+ 'A type argument on `{{method}}()` claims a row type that the database never checks. Query through Kysely over declared table types, or parse each row with zod.',
22
+ configType:
23
+ 'A type argument on `{{method}}()` claims a config shape that Pulumi never checks. Drop it and parse the value with zod.',
24
+ },
25
+ schema: [],
26
+ },
27
+ create(context) {
28
+ return {
29
+ TaggedTemplateExpression(node) {
30
+ if (node.typeArguments && findName(node.tag) === 'sql') {
31
+ context.report({ node, messageId: 'sqlType' });
32
+ }
33
+ },
34
+ CallExpression(node) {
35
+ const method = node.callee.type === 'MemberExpression' ? findName(node.callee) : null;
36
+
37
+ if (method === null) {
38
+ return;
39
+ }
40
+
41
+ if (castMethods.has(method)) {
42
+ context.report({ node, messageId: 'castMethod', data: { method } });
43
+ } else if (node.typeArguments && rowMethods.has(method)) {
44
+ context.report({ node, messageId: 'rowType', data: { method } });
45
+ } else if (node.typeArguments && configMethods.has(method)) {
46
+ context.report({ node, messageId: 'configType', data: { method } });
47
+ }
48
+ },
49
+ };
50
+ },
51
+ };
52
+
53
+ // the name an identifier or a member access ends in, `sql` for both `sql` and
54
+ // `db.sql`, or null for a computed member that is not a string literal
55
+ function findName(node) {
56
+ if (node.type === 'Identifier') {
57
+ return node.name;
58
+ }
59
+
60
+ if (node.type !== 'MemberExpression') {
61
+ return null;
62
+ }
63
+
64
+ if (!node.computed) {
65
+ return node.property.name;
66
+ }
67
+
68
+ return typeof node.property.value === 'string' ? node.property.value : null;
69
+ }
70
+
71
+ export default noHiddenCast;
package/oxlintrc.json CHANGED
@@ -27,6 +27,7 @@
27
27
  "zgeoff/no-await-in-logical": "error",
28
28
  "zgeoff/no-switch": "error",
29
29
  "zgeoff/no-class": "error",
30
+ "zgeoff/no-hidden-cast": "error",
30
31
  "zgeoff/no-jsdoc": "error",
31
32
  "zgeoff/max-consecutive-line-comments": ["error", { "max": 3 }],
32
33
  "zgeoff/no-comment-rule-override": "error",
@@ -96,6 +97,12 @@
96
97
  // restriction-category cherry-picks
97
98
  "typescript/no-explicit-any": "error",
98
99
  "typescript/no-non-null-assertion": "error",
100
+
101
+ // every type assertion other than `as const` fails; one that survives
102
+ // carries a disable comment naming this rule, which already covers each
103
+ // assertion the type-aware no-unsafe-type-assertion would check
104
+ "typescript/consistent-type-assertions": ["error", { "assertionStyle": "never" }],
105
+ "typescript/no-unsafe-type-assertion": "off",
99
106
  "import/no-cycle": "error",
100
107
 
101
108
  "no-shadow": "error",
@@ -215,8 +222,7 @@
215
222
  "typescript/no-unsafe-assignment": "off",
216
223
  "typescript/no-unsafe-call": "off",
217
224
  "typescript/no-unsafe-member-access": "off",
218
- "typescript/no-unsafe-return": "off",
219
- "typescript/no-unsafe-type-assertion": "off"
225
+ "typescript/no-unsafe-return": "off"
220
226
  }
221
227
  }
222
228
  ]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zgeoff/oxlint-config",
3
- "version": "0.5.2",
3
+ "version": "0.6.1",
4
4
  "description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -13,6 +13,7 @@
13
13
  "plugin.js",
14
14
  "function-verb.js",
15
15
  "verb-contract.js",
16
+ "collect-type-kinds.js",
16
17
  "module-order.js",
17
18
  "collect-module-entries.js",
18
19
  "build-module-order-fix.js",
@@ -25,6 +26,7 @@
25
26
  "no-class.js",
26
27
  "no-jsdoc.js",
27
28
  "no-comment-rule-override.js",
29
+ "no-hidden-cast.js",
28
30
  "test-beside-module.js",
29
31
  "no-file-snapshot.js",
30
32
  "setup-test-only.js",
package/plugin.js CHANGED
@@ -6,6 +6,7 @@ import noAbbreviatedNames from './no-abbreviated-names.js';
6
6
  import noClass from './no-class.js';
7
7
  import noCommentRuleOverride from './no-comment-rule-override.js';
8
8
  import noFileSnapshot from './no-file-snapshot.js';
9
+ import noHiddenCast from './no-hidden-cast.js';
9
10
  import noJSDoc from './no-jsdoc.js';
10
11
  import noRestrictedWords from './no-restricted-words.js';
11
12
  import setupTestOnly from './setup-test-only.js';
@@ -90,6 +91,7 @@ const plugin = {
90
91
  ['SwitchStatement'],
91
92
  ),
92
93
  'no-class': noClass,
94
+ 'no-hidden-cast': noHiddenCast,
93
95
  'no-jsdoc': noJSDoc,
94
96
  'max-consecutive-line-comments': maxConsecutiveLineComments,
95
97
  'no-comment-rule-override': noCommentRuleOverride,
package/verb-contract.js CHANGED
@@ -1,3 +1,4 @@
1
+ import collectTypeKinds from './collect-type-kinds.js';
1
2
  import findFunctionName from './find-function-name.js';
2
3
  import isVerbMatch from './is-verb-match.js';
3
4
 
@@ -251,91 +252,6 @@ function collectLocalTypes(program) {
251
252
  return localTypes;
252
253
  }
253
254
 
254
- // the kind of each member of a declared type, read without type information:
255
- // a union splits into its members, a reference follows the file's own type
256
- // aliases, and `resolvePromise` reads a promise as the value it resolves to
257
- function collectTypeKinds(type, localTypes, resolvePromise = false, seen = new Set()) {
258
- if (type.type === 'TSUnionType') {
259
- return type.types.flatMap((member) =>
260
- collectTypeKinds(member, localTypes, resolvePromise, seen),
261
- );
262
- }
263
-
264
- if (type.type === 'TSParenthesizedType' || isReadonlyOperator(type)) {
265
- return collectTypeKinds(type.typeAnnotation, localTypes, resolvePromise, seen);
266
- }
267
-
268
- if (type.type !== 'TSTypeReference') {
269
- return [pickTypeKind(type)];
270
- }
271
-
272
- const name = type.typeName.type === 'Identifier' ? type.typeName.name : null;
273
- const alias = name === null ? undefined : localTypes.aliases.get(name);
274
-
275
- if (alias !== undefined && !seen.has(name)) {
276
- return collectTypeKinds(alias, localTypes, resolvePromise, new Set([...seen, name]));
277
- }
278
-
279
- const typeArguments = type.typeArguments ?? type.typeParameters;
280
-
281
- if (resolvePromise && name === 'Promise' && typeArguments?.params.length === 1) {
282
- const [value] = typeArguments.params;
283
-
284
- return collectTypeKinds(value, localTypes, resolvePromise, seen);
285
- }
286
-
287
- // an interface never holds null; any other reference, such as an import or
288
- // a type parameter, is a type the rule cannot read
289
- return [localTypes.interfaces.has(name) ? 'value' : 'open'];
290
- }
291
-
292
- function isReadonlyOperator(type) {
293
- return type.type === 'TSTypeOperator' && type.operator === 'readonly';
294
- }
295
-
296
- // a type whose members the rule can see and that never holds null; any other
297
- // shape, such as an indexed access or a conditional type, is open
298
- const valueTypes = new Set([
299
- 'TSStringKeyword',
300
- 'TSNumberKeyword',
301
- 'TSBigIntKeyword',
302
- 'TSSymbolKeyword',
303
- 'TSObjectKeyword',
304
- 'TSNeverKeyword',
305
- 'TSLiteralType',
306
- 'TSTemplateLiteralType',
307
- 'TSArrayType',
308
- 'TSTupleType',
309
- 'TSTypeLiteral',
310
- 'TSFunctionType',
311
- 'TSConstructorType',
312
- ]);
313
-
314
- function pickTypeKind(type) {
315
- if (
316
- type.type === 'TSBooleanKeyword' ||
317
- (type.type === 'TSTypePredicate' && !type.asserts) ||
318
- (type.type === 'TSLiteralType' && typeof type.literal.value === 'boolean')
319
- ) {
320
- return 'boolean';
321
- }
322
-
323
- if (type.type === 'TSNullKeyword' || type.type === 'TSUndefinedKeyword') {
324
- return 'nullish';
325
- }
326
-
327
- if (type.type === 'TSVoidKeyword') {
328
- return 'void';
329
- }
330
-
331
- // `asserts value is T` throws instead of returning a boolean
332
- if (type.type === 'TSTypePredicate' || valueTypes.has(type.type)) {
333
- return 'value';
334
- }
335
-
336
- return 'open';
337
- }
338
-
339
255
  function isBooleanOrOpen(kinds) {
340
256
  return kinds.every((kind) => kind === 'boolean' || kind === 'open');
341
257
  }
@@ -386,7 +302,7 @@ function findCallIO(context, node, frameNode) {
386
302
  name: callee.type === 'Identifier' ? callee.name : memberName,
387
303
  isMethod: memberName !== null,
388
304
  },
389
- { name: target.memberName ?? target.rootName, isMethod: target.memberName !== null },
305
+ buildCalledName(context, node, callee),
390
306
  ];
391
307
 
392
308
  const effectful = names.find((entry) => {
@@ -591,6 +507,36 @@ function isLocalVariable(binding, frameNode) {
591
507
  );
592
508
  }
593
509
 
510
+ function buildCalledName(context, node, callee) {
511
+ let current = callee;
512
+ let scopeNode = node;
513
+
514
+ for (let depth = 0; depth < 8; depth++) {
515
+ if (current.type === 'MemberExpression') {
516
+ return { name: findMemberName(current), isMethod: true };
517
+ }
518
+
519
+ if (current.type !== 'Identifier') {
520
+ break;
521
+ }
522
+
523
+ const declarator = findAliasDeclarator(findBinding(context, scopeNode, current.name));
524
+
525
+ if (declarator === null) {
526
+ return { name: current.name, isMethod: false };
527
+ }
528
+
529
+ if (declarator.id.type !== 'Identifier') {
530
+ return { name: findPatternKey(declarator.id, current.name), isMethod: true };
531
+ }
532
+
533
+ current = declarator.init;
534
+ scopeNode = declarator.init;
535
+ }
536
+
537
+ return { name: null, isMethod: false };
538
+ }
539
+
594
540
  function isEnvRead(context, node) {
595
541
  return (
596
542
  findMemberName(node) === 'env' &&