@timmo001/oxlint-rules 0.3.6 → 0.5.0

package/src/generic/index.ts

@@ -1,11 +1,22 @@
 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

@@ -0,0 +1,39 @@
+import { defineRule } from "@oxlint/plugins";
+
+import { assertedEventParameter } from "./prefer-event-parameter-type.ts";
+
+import type { TypeAssertion } from "../../shared/ast.ts";
+
+/** Prefer typing values at their source over asserting them at use sites. */
+export const preferTypesOverAssertionsRule = defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Prefer typing a value at its source over a TypeScript type assertion.",
+    },
+    messages: {
+      avoidAssertion:
+        "Type this value at its source, such as a function parameter or DOM lookup, instead of asserting it here. A SAFETY comment is not a fix.",
+    },
+  },
+  create(context) {
+    const checkAssertion = (node: TypeAssertion) => {
+      if (
+        (node.typeAnnotation.type === "TSTypeReference" &&
+          node.typeAnnotation.typeName.type === "Identifier" &&
+          node.typeAnnotation.typeName.name === "const") ||
+        assertedEventParameter(node)
+      ) {
+        return;
+      }
+
+      context.report({ node, messageId: "avoidAssertion" });
+    };
+
+    return {
+      TSAsExpression: checkAssertion,
+      TSTypeAssertion: checkAssertion,
+    };
+  },
+});

package/src/shared/ast.ts

@@ -0,0 +1,31 @@
+import type { ESTree } from "@oxlint/plugins";
+
+export type FunctionNode = ESTree.Function | ESTree.ArrowFunctionExpression;
+
+export type TypeAssertion = ESTree.TSAsExpression | ESTree.TSTypeAssertion;
+
+export 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;
+}
+
+export function staticMemberName(node: ESTree.Node): string | null {
+  if (node.type !== "MemberExpression" || node.computed) return null;
+
+  return node.property.type === "Identifier" ? node.property.name : null;
+}

package/src/shared/effect.ts

@@ -0,0 +1,72 @@
+import { staticMemberName } from "./ast.ts";
+import { resolveVariable } from "./scope.ts";
+
+import type { ESTree, SourceCode } from "@oxlint/plugins";
+
+export 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
+  );
+}
+
+export 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);
+}
+
+/** Whether a module imports Effect or one of its platform packages. */
+export function importsEffect(program: ESTree.Program): boolean {
+  return program.body.some(
+    (statement) =>
+      statement.type === "ImportDeclaration" &&
+      statement.importKind !== "type" &&
+      (statement.source.value === "effect" ||
+        statement.source.value.startsWith("effect/") ||
+        statement.source.value.startsWith("@effect/")),
+  );
+}

package/src/shared/json.ts

@@ -0,0 +1,11 @@
+import type { Settings } from "@oxlint/plugins";
+
+/** Narrow a rule option or setting, which Oxlint passes as untyped JSON. */
+export function jsonObject(
+  value: Settings[string] | undefined,
+): Readonly<Settings> | null {
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Oxlint settings and options are the JSON input boundary.
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+}