@timmo001/oxlint-rules 0.4.0 → 0.6.0

package/src/effect/rules/no-try-catch-in-effect-generators.ts

@@ -1,104 +1,10 @@
 import { defineRule } from "@oxlint/plugins";
 
-import type { ESTree, Scope, SourceCode, Variable } from "@oxlint/plugins";
+import { nearestEnclosingFunction } from "../../shared/ast.ts";
+import { isEffectMethod } from "../../shared/effect.ts";
 
-type FunctionNode = ESTree.Function | ESTree.ArrowFunctionExpression;
-
-function resolveVariable(
-  sourceCode: SourceCode,
-  identifier: ESTree.IdentifierReference,
-): Variable | null {
-  let scope: Scope | null = sourceCode.getScope(identifier);
-
-  while (scope) {
-    const variable = scope.set.get(identifier.name);
-
-    if (variable) return variable;
-    scope = scope.upper;
-  }
-
-  return null;
-}
-
-function nearestEnclosingFunction(node: ESTree.Node): FunctionNode | null {
-  let current: ESTree.Node | null = node.parent;
-
-  while (current) {
-    if (
-      current.type === "FunctionDeclaration" ||
-      current.type === "FunctionExpression" ||
-      current.type === "ArrowFunctionExpression"
-    ) {
-      return current;
-    }
-
-    current = current.parent;
-  }
-
-  return null;
-}
-
-function staticMemberName(node: ESTree.Expression): string | null {
-  if (node.type !== "MemberExpression" || node.computed) return null;
-
-  return node.property.type === "Identifier" ? node.property.name : null;
-}
-
-function isEffectImport(
-  sourceCode: SourceCode,
-  identifier: ESTree.IdentifierReference,
-  namespace: boolean,
-): boolean {
-  const variable = resolveVariable(sourceCode, identifier);
-
-  return (
-    variable?.defs.some((definition) => {
-      if (
-        definition.type !== "ImportBinding" ||
-        definition.parent?.type !== "ImportDeclaration" ||
-        definition.parent.source.value !== "effect"
-      ) {
-        return false;
-      }
-
-      if (namespace) return definition.node.type === "ImportNamespaceSpecifier";
-
-      if (definition.node.type !== "ImportSpecifier") return false;
-      const imported = definition.node.imported;
-
-      return (
-        (imported.type === "Identifier" ? imported.name : imported.value) ===
-        "Effect"
-      );
-    }) ?? false
-  );
-}
-
-function isEffectMethod(
-  sourceCode: SourceCode,
-  node: ESTree.Expression,
-  method: "fn" | "gen",
-): boolean {
-  if (staticMemberName(node) !== method || node.type !== "MemberExpression") {
-    return false;
-  }
-
-  const object = node.object;
-
-  if (object.type === "Identifier") {
-    return isEffectImport(sourceCode, object, false);
-  }
-
-  if (
-    staticMemberName(object) !== "Effect" ||
-    object.type !== "MemberExpression" ||
-    object.object.type !== "Identifier"
-  ) {
-    return false;
-  }
-
-  return isEffectImport(sourceCode, object.object, true);
-}
+import type { FunctionNode } from "../../shared/ast.ts";
+import type { ESTree, SourceCode } from "@oxlint/plugins";
 
 function isDirectArgument(
   owner: FunctionNode,

package/src/effect/rules/prefer-platform-services.ts

@@ -0,0 +1,105 @@
+import { defineRule } from "@oxlint/plugins";
+
+import { staticMemberName } from "../../shared/ast.ts";
+import { importsEffect } from "../../shared/effect.ts";
+import { resolveVariable } from "../../shared/scope.ts";
+
+type PlatformService = "childProcess" | "fileSystem";
+
+const moduleServices = new Map<string, PlatformService>([
+  ["child_process", "childProcess"],
+  ["fs", "fileSystem"],
+  ["fs/promises", "fileSystem"],
+]);
+
+const bunServices = new Map<string, PlatformService>([
+  ["$", "childProcess"],
+  ["file", "fileSystem"],
+  ["spawn", "childProcess"],
+  ["spawnSync", "childProcess"],
+  ["write", "fileSystem"],
+]);
+
+/** Prefer Effect's platform services over direct process and file system APIs in Effect modules. */
+export const preferPlatformServicesRule = defineRule({
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer Effect's ChildProcessSpawner and FileSystem services over Node or Bun process and file system APIs in modules that use Effect.",
+    },
+    messages: {
+      childProcess:
+        "Use Effect's `ChildProcessSpawner` service (`effect/process`) instead of `{{api}}`, so scope cleanup, interruption, and test layers apply.",
+      fileSystem:
+        "Use Effect's `FileSystem` service instead of `{{api}}`, so failures stay typed and tests can provide a layer.",
+    },
+  },
+  create(context) {
+    let enabled = false;
+
+    return {
+      Program(node) {
+        enabled = importsEffect(node);
+      },
+      ImportDeclaration(node) {
+        if (!enabled || node.importKind === "type") return;
+        const source = node.source.value;
+        const service = moduleServices.get(source.replace(/^node:/u, ""));
+
+        if (service) {
+          context.report({ node, messageId: service, data: { api: source } });
+
+          return;
+        }
+
+        if (source !== "bun") return;
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type !== "ImportSpecifier" ||
+            specifier.importKind === "type"
+          ) {
+            continue;
+          }
+
+          const imported =
+            specifier.imported.type === "Identifier"
+              ? specifier.imported.name
+              : specifier.imported.value;
+
+          const bunService = bunServices.get(imported);
+
+          if (bunService) {
+            context.report({
+              node: specifier,
+              messageId: bunService,
+              data: { api: `Bun.${imported}` },
+            });
+          }
+        }
+      },
+      MemberExpression(node) {
+        const name = staticMemberName(node);
+        const service = name ? bunServices.get(name) : undefined;
+
+        if (
+          !enabled ||
+          !service ||
+          node.object.type !== "Identifier" ||
+          node.object.name !== "Bun" ||
+          (resolveVariable(context.sourceCode, node.object)?.defs.length ?? 0) >
+            0
+        ) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: service,
+          data: { api: `Bun.${name}` },
+        });
+      },
+    };
+  },
+});

package/src/generic/index.ts

@@ -1,12 +1,21 @@
 import { eslintCompatPlugin } from "@oxlint/plugins";
 
+import { noExplicitInferableTypePredicateRule } from "./rules/no-explicit-inferable-type-predicate.ts";
+import { noUncheckedQuerySelectorTypeRule } from "./rules/no-unchecked-query-selector-type.ts";
+import { noUntypedCustomEventRule } from "./rules/no-untyped-custom-event.ts";
 import { preferEventParameterTypeRule } from "./rules/prefer-event-parameter-type.ts";
+import { preferLitQueryDecoratorsRule } from "./rules/prefer-lit-query-decorators.ts";
 import { preferTypesOverAssertionsRule } from "./rules/prefer-types-over-assertions.ts";
 
 const timmoPlugin = eslintCompatPlugin({
   meta: { name: "timmo" },
   rules: {
+    "no-explicit-inferable-type-predicate":
+      noExplicitInferableTypePredicateRule,
+    "no-unchecked-query-selector-type": noUncheckedQuerySelectorTypeRule,
+    "no-untyped-custom-event": noUntypedCustomEventRule,
     "prefer-event-parameter-type": preferEventParameterTypeRule,
+    "prefer-lit-query-decorators": preferLitQueryDecoratorsRule,
     "prefer-types-over-assertions": preferTypesOverAssertionsRule,
   },
 });

package/src/generic/rules/no-explicit-inferable-type-predicate.ts

@@ -0,0 +1,146 @@
+import { defineRule } from "@oxlint/plugins";
+
+import type { FunctionNode } from "../../shared/ast.ts";
+import type { ESTree } from "@oxlint/plugins";
+
+function isNamed(node: ESTree.Node, name: string): boolean {
+  return node.type === "Identifier" && node.name === name;
+}
+
+function isNullish(node: ESTree.Node): boolean {
+  return (
+    (node.type === "Literal" && node.value === null) ||
+    isNamed(node, "undefined")
+  );
+}
+
+function isNullishExclusion(node: ESTree.Node, name: string): boolean {
+  return (
+    node.type === "BinaryExpression" &&
+    (node.operator === "!==" || node.operator === "!=") &&
+    ((isNamed(node.left, name) && isNullish(node.right)) ||
+      (isNullish(node.left) && isNamed(node.right, name)))
+  );
+}
+
+function isTypeofCheck(node: ESTree.Node, name: string): boolean {
+  if (
+    node.type !== "BinaryExpression" ||
+    (node.operator !== "===" && node.operator !== "==")
+  ) {
+    return false;
+  }
+
+  const isTypeof = (side: ESTree.Node) =>
+    side.type === "UnaryExpression" &&
+    side.operator === "typeof" &&
+    isNamed(side.argument, name);
+
+  const isLiteral = (side: ESTree.Node) => side.type === "Literal";
+
+  return (
+    (isTypeof(node.left) && isLiteral(node.right)) ||
+    (isLiteral(node.left) && isTypeof(node.right))
+  );
+}
+
+function isInferableCheck(node: ESTree.Node, name: string): boolean {
+  if (node.type === "LogicalExpression") {
+    return (
+      node.operator === "&&" &&
+      isNullishExclusion(node.left, name) &&
+      isNullishExclusion(node.right, name)
+    );
+  }
+
+  return (
+    isNullishExclusion(node, name) ||
+    isTypeofCheck(node, name) ||
+    (node.type === "BinaryExpression" &&
+      node.operator === "instanceof" &&
+      isNamed(node.left, name))
+  );
+}
+
+function returnedExpression(owner: FunctionNode): ESTree.Node | null {
+  const body = owner.body;
+
+  if (!body) return null;
+
+  if (body.type !== "BlockStatement") return body;
+
+  const [statement] = body.body;
+
+  return body.body.length === 1 && statement?.type === "ReturnStatement"
+    ? statement.argument
+    : null;
+}
+
+function isPublicSignature(owner: FunctionNode): boolean {
+  const parent = owner.parent;
+
+  if (
+    parent.type === "MethodDefinition" ||
+    parent.type === "ExportNamedDeclaration" ||
+    parent.type === "ExportDefaultDeclaration"
+  ) {
+    return true;
+  }
+
+  return (
+    parent.type === "VariableDeclarator" &&
+    parent.parent.parent?.type === "ExportNamedDeclaration"
+  );
+}
+
+/** Flag explicit type predicates that TypeScript would infer from a simple check. */
+export const noExplicitInferableTypePredicateRule = defineRule({
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow explicit type predicates on simple null, typeof, or instanceof checks that TypeScript 5.5+ infers.",
+    },
+    messages: {
+      removeTypePredicate:
+        "TypeScript infers the type predicate for `{{parameter}}` from this check, while an explicit predicate is never checked against the body. Remove the annotation and rely on the inferred predicate.",
+    },
+  },
+  create(context) {
+    const check = (owner: FunctionNode) => {
+      const annotation = owner.returnType?.typeAnnotation;
+
+      if (
+        annotation?.type !== "TSTypePredicate" ||
+        annotation.asserts ||
+        annotation.parameterName.type !== "Identifier" ||
+        isPublicSignature(owner)
+      ) {
+        return;
+      }
+
+      const parameter = annotation.parameterName.name;
+      const expression = returnedExpression(owner);
+
+      if (
+        !owner.params.some((param) => isNamed(param, parameter)) ||
+        !expression ||
+        !isInferableCheck(expression, parameter)
+      ) {
+        return;
+      }
+
+      context.report({
+        node: annotation,
+        messageId: "removeTypePredicate",
+        data: { parameter },
+      });
+    };
+
+    return {
+      ArrowFunctionExpression: check,
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+    };
+  },
+});

package/src/generic/rules/no-unchecked-query-selector-type.ts

@@ -0,0 +1,48 @@
+import { defineRule } from "@oxlint/plugins";
+
+import { staticMemberName } from "../../shared/ast.ts";
+import {
+  isLitRenderRootQuery,
+  litElementBaseClasses,
+} from "../../shared/lit.ts";
+
+const queryMethods = new Set(["closest", "querySelector", "querySelectorAll"]);
+
+/** Disallow type arguments that silently cast DOM query results. */
+export const noUncheckedQuerySelectorTypeRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow type arguments on `querySelector`, `querySelectorAll`, and `closest`, which cast the result without checking it.",
+    },
+    messages: {
+      checkQueryResult:
+        "`{{method}}<T>` casts the result without checking it. Check it with `instanceof`, use a checked lookup helper, or query a tag name so TypeScript infers the element type.",
+    },
+  },
+  create(context) {
+    const bases = litElementBaseClasses(context.settings);
+
+    return {
+      CallExpression(node) {
+        const method = staticMemberName(node.callee);
+
+        if (
+          !node.typeArguments ||
+          !method ||
+          !queryMethods.has(method) ||
+          isLitRenderRootQuery(node, bases)
+        ) {
+          return;
+        }
+
+        context.report({
+          node: node.typeArguments,
+          messageId: "checkQueryResult",
+          data: { method },
+        });
+      },
+    };
+  },
+});

package/src/generic/rules/no-untyped-custom-event.ts

@@ -0,0 +1,31 @@
+import { defineRule } from "@oxlint/plugins";
+
+/** Require a detail type wherever `CustomEvent` is used as a type. */
+export const noUntypedCustomEventRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow `CustomEvent` type references without a detail type, which leave `detail` as `any`.",
+    },
+    messages: {
+      typeCustomEventDetail:
+        "`CustomEvent` without a type argument leaves `detail` as `any`. Reuse the project's typed event helper if one fits, or add one, instead of a bare `CustomEvent`.",
+    },
+  },
+  create(context) {
+    return {
+      TSTypeReference(node) {
+        if (
+          node.typeName.type !== "Identifier" ||
+          node.typeName.name !== "CustomEvent" ||
+          node.typeArguments
+        ) {
+          return;
+        }
+
+        context.report({ node, messageId: "typeCustomEventDetail" });
+      },
+    };
+  },
+});

package/src/generic/rules/prefer-event-parameter-type.ts

@@ -1,76 +1,77 @@
 import { defineRule } from "@oxlint/plugins";
 
-import type { ESTree } from "@oxlint/plugins";
+import { nearestEnclosingFunction } from "../../shared/ast.ts";
 
-type FunctionNode = ESTree.Function | ESTree.ArrowFunctionExpression;
+import type { TypeAssertion } from "../../shared/ast.ts";
+import type { ESTree } from "@oxlint/plugins";
 
-type TypeAssertion = ESTree.TSAsExpression | ESTree.TSTypeAssertion;
+function staticMemberPath(
+  node: ESTree.Expression,
+): { readonly root: string; readonly path: readonly string[] } | null {
+  const path: string[] = [];
 
-function nearestEnclosingFunction(node: ESTree.Node): FunctionNode | null {
-  let current: ESTree.Node | null = node.parent;
+  let current: ESTree.Node =
+    node.type === "ChainExpression" ? node.expression : node;
 
-  while (current) {
-    if (
-      current.type === "FunctionDeclaration" ||
-      current.type === "FunctionExpression" ||
-      current.type === "ArrowFunctionExpression"
-    ) {
-      return current;
+  while (current.type === "MemberExpression") {
+    if (current.computed || current.property.type !== "Identifier") {
+      return null;
     }
 
-    current = current.parent;
+    path.unshift(current.property.name);
+    current = current.object;
   }
 
-  return null;
+  return current.type === "Identifier" && path.length > 0
+    ? { root: current.name, path }
+    : null;
+}
+
+function isEventMemberPath(path: readonly string[]): boolean {
+  const [first] = path;
+
+  if (first === "detail") return true;
+
+  return path.length === 1 && (first === "currentTarget" || first === "target");
 }
 
-function assertedEventParameter(node: TypeAssertion): {
+/** Find an assertion of an event parameter's target, current target, or detail. */
+export function assertedEventParameter(node: TypeAssertion): {
   readonly parameter: string;
-  readonly property: "currentTarget" | "target";
+  readonly property: string;
 } | null {
-  const expression = node.expression;
+  const member = staticMemberPath(node.expression);
 
-  if (
-    expression.type !== "MemberExpression" ||
-    expression.computed ||
-    expression.object.type !== "Identifier" ||
-    expression.property.type !== "Identifier" ||
-    (expression.property.name !== "currentTarget" &&
-      expression.property.name !== "target")
-  ) {
-    return null;
-  }
+  if (!member || !isEventMemberPath(member.path)) return null;
 
-  const parameterName = expression.object.name;
-  const property = expression.property.name;
   const owner = nearestEnclosingFunction(node);
 
   if (
     !owner?.params.some(
       (parameter) =>
-        parameter.type === "Identifier" && parameter.name === parameterName,
+        parameter.type === "Identifier" && parameter.name === member.root,
     )
   ) {
     return null;
   }
 
   return {
-    parameter: parameterName,
-    property,
+    parameter: member.root,
+    property: member.path.join("."),
   };
 }
 
-/** Prefer expressing an event target type in its handler parameter signature. */
+/** Prefer expressing an event's target or detail type in its handler parameter signature. */
 export const preferEventParameterTypeRule = defineRule({
   meta: {
     type: "suggestion",
     docs: {
       description:
-        "Prefer typing event target properties in the handler parameter instead of asserting them at use sites.",
+        "Prefer typing event target and detail properties in the handler parameter instead of asserting them at use sites.",
     },
     messages: {
       typeEventParameter:
-        "Type `{{parameter}}.{{property}}` in the function signature instead of asserting it at the use site.",
+        "Type `{{parameter}}.{{property}}` in the function signature instead of asserting it at the use site. Reuse the project's typed event helper if one fits, or add one.",
     },
   },
   create(context) {

package/src/generic/rules/prefer-lit-query-decorators.ts

@@ -0,0 +1,84 @@
+import { defineRule } from "@oxlint/plugins";
+
+import { jsonObject } from "../../shared/json.ts";
+import {
+  litElementBaseClasses,
+  litQueryDecoratorCall,
+} from "../../shared/lit.ts";
+
+import type { LitQueryMethod } from "../../shared/lit.ts";
+
+const messageIds = {
+  assignedElements: "preferQueryAssignedElements",
+  assignedNodes: "preferQueryAssignedNodes",
+  querySelector: "preferQuery",
+  querySelectorAll: "preferQueryAll",
+} as const satisfies Record<LitQueryMethod, string>;
+
+/**
+ * Prefer Lit query decorators over manual render-root queries. Follows
+ * eslint-plugin-lit's `prefer-query-decorators` and also matches non-null,
+ * optional, and asserted render roots.
+ */
+export const preferLitQueryDecoratorsRule = defineRule({
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Require Lit query decorators instead of static render-root queries in Lit elements.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          querySelector: { type: "boolean" },
+          querySelectorAll: { type: "boolean" },
+          assignedElements: { type: "boolean" },
+          assignedNodes: { type: "boolean" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    defaultOptions: [
+      {
+        querySelector: true,
+        querySelectorAll: true,
+        assignedElements: true,
+        assignedNodes: true,
+      },
+    ],
+    messages: {
+      preferQuery:
+        "Use the @query decorator instead of this.{{root}}.querySelector().",
+      preferQueryAll:
+        "Use the @queryAll decorator instead of this.{{root}}.querySelectorAll().",
+      preferQueryAssignedElements:
+        "Use the @queryAssignedElements decorator instead of this.{{root}}.querySelector().assignedElements().",
+      preferQueryAssignedNodes:
+        "Use the @queryAssignedNodes decorator instead of this.{{root}}.querySelector().assignedNodes().",
+    },
+  },
+  create(context) {
+    const bases = litElementBaseClasses(context.settings);
+    const options = jsonObject(context.options[0]);
+
+    const disabled = new Set(
+      options
+        ? Object.keys(options).filter((method) => options[method] === false)
+        : [],
+    );
+
+    return {
+      CallExpression(node) {
+        const query = litQueryDecoratorCall(node, bases);
+
+        if (!query || disabled.has(query.method)) return;
+        context.report({
+          node,
+          messageId: messageIds[query.method],
+          data: { root: query.root },
+        });
+      },
+    };
+  },
+});

package/src/generic/rules/prefer-types-over-assertions.ts

@@ -1,8 +1,8 @@
 import { defineRule } from "@oxlint/plugins";
 
-import type { ESTree } from "@oxlint/plugins";
+import { assertedEventParameter } from "./prefer-event-parameter-type.ts";
 
-type TypeAssertion = ESTree.TSAsExpression | ESTree.TSTypeAssertion;
+import type { TypeAssertion } from "../../shared/ast.ts";
 
 /** Prefer typing values at their source over asserting them at use sites. */
 export const preferTypesOverAssertionsRule = defineRule({
@@ -20,9 +20,10 @@ export const preferTypesOverAssertionsRule = defineRule({
   create(context) {
     const checkAssertion = (node: TypeAssertion) => {
       if (
-        node.typeAnnotation.type === "TSTypeReference" &&
-        node.typeAnnotation.typeName.type === "Identifier" &&
-        node.typeAnnotation.typeName.name === "const"
+        (node.typeAnnotation.type === "TSTypeReference" &&
+          node.typeAnnotation.typeName.type === "Identifier" &&
+          node.typeAnnotation.typeName.name === "const") ||
+        assertedEventParameter(node)
       ) {
         return;
       }