eslint-plugin-ocavue 0.2.0 → 0.3.0

package/src/rules/prefer-sleep.test.ts

@@ -0,0 +1,194 @@
+import { RuleTester } from 'eslint'
+import tseslint from 'typescript-eslint'
+import { test } from 'vitest'
+
+import { useUtilsProjects } from '../utils/test-projects'
+
+import rule from './prefer-sleep'
+
+const js = useUtilsProjects('js')
+const ts = useUtilsProjects('ts')
+
+const IMPORT = "import { sleep } from '@ocavue/utils'\n"
+
+test('prefer-sleep', () => {
+  const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+  })
+  const filename = js.withUtils
+
+  tester.run('prefer-sleep', rule, {
+    valid: [
+      // The project does not depend on `@ocavue/utils`.
+      { code: 'await new Promise((r) => setTimeout(r, 100))', filename: js.withoutUtils },
+      // `@ocavue/utils` itself.
+      { code: 'await new Promise((r) => setTimeout(r, 100))', filename: js.utilsRepo },
+
+      // Not a plain delay.
+      { code: 'new Promise((r) => setTimeout(r))', filename },
+      { code: 'new Promise((r) => setTimeout(r, 100, value))', filename },
+      { code: 'new Promise((r) => setTimeout(() => r(value), 100))', filename },
+      { code: 'new Promise((r) => setTimeout(() => { g(); r() }, 100))', filename },
+      { code: 'new Promise((r) => setTimeout(other, 100))', filename },
+      { code: 'new Promise((r) => { g(); setTimeout(r, 100) })', filename },
+      { code: 'new Promise((r, reject) => setTimeout(reject, 100))', filename },
+      { code: 'new Promise(async (r) => setTimeout(r, 100))', filename },
+      { code: 'new Promise(({ r }) => setTimeout(r, 100))', filename },
+      { code: 'new Promise(() => setTimeout(g, 100))', filename },
+      { code: 'new Promise((r) => setTimeout(...args))', filename },
+      { code: 'new Promise((r) => setInterval(r, 100))', filename },
+      { code: 'new Promise((r) => foo.setTimeout(r, 100))', filename },
+
+      // The delay uses the executor's parameters, `this` or `arguments`.
+      { code: 'new Promise((r) => setTimeout(r, r.length))', filename },
+      { code: 'new Promise((r, reject) => setTimeout(r, reject.length))', filename },
+      { code: 'new Promise(function (r) { setTimeout(r, this.ms) })', filename },
+      { code: 'new Promise(function (r) { setTimeout(r, arguments.length) })', filename },
+
+      // Local bindings that shadow globals.
+      { code: 'const Promise = P\nnew Promise((r) => setTimeout(r, 100))', filename },
+      { code: 'const setTimeout = t\nnew Promise((r) => setTimeout(r, 100))', filename },
+
+      // Already uses `sleep`.
+      { code: `${IMPORT}await sleep(100)`, filename },
+    ],
+    invalid: [
+      {
+        code: 'await new Promise((resolve) => setTimeout(resolve, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise(r => setTimeout(r, ms))',
+        output: `${IMPORT}await sleep(ms)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((resolve) => { setTimeout(resolve, 100) })',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((resolve) => { return setTimeout(resolve, 100) })',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((resolve) => setTimeout(() => resolve(), 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((resolve) => setTimeout(() => { resolve() }, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise(function (resolve) { setTimeout(resolve, 100) })',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((resolve, _reject) => setTimeout(resolve, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((r) => globalThis.setTimeout(r, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((r) => window.setTimeout(r, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((r) => setTimeout(r, this.delay * 2))',
+        output: `${IMPORT}await sleep(this.delay * 2)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((r) => setTimeout(r, (a, b)))',
+        output: `${IMPORT}await sleep((a, b))`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'const wait = () => new Promise((r) => setTimeout(r, 0))',
+        output: `${IMPORT}const wait = () => sleep(0)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: "import { noop } from '@ocavue/utils'\nawait new Promise((r) => setTimeout(r, 100))",
+        output: "import { noop, sleep } from '@ocavue/utils'\nawait sleep(100)",
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        // Reported without a fix.
+        code: 'const sleep = 1\nawait new Promise((r) => setTimeout(r, 100))',
+        output: null,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((r) => setTimeout(r, 100 /* ms */))',
+        output: null,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise((r) => setTimeout(r, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename: js.withoutUtils,
+        options: [{ checkDependency: false }],
+        errors: [{ messageId: 'preferSleep' }],
+      },
+    ],
+  })
+})
+
+test('prefer-sleep with TypeScript', () => {
+  const tester = new RuleTester({
+    languageOptions: {
+      parser: tseslint.parser,
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+  })
+  const filename = ts.withUtils
+
+  tester.run('prefer-sleep', rule, {
+    valid: [
+      // `sleep` returns `Promise<void>`.
+      { code: 'await new Promise<number>((r) => setTimeout(r, 100))', filename },
+    ],
+    invalid: [
+      {
+        code: 'await new Promise<void>((resolve) => setTimeout(resolve, 100))',
+        output: `${IMPORT}await sleep(100)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+      {
+        code: 'await new Promise<undefined>((r) => setTimeout(r, ms as number))',
+        output: `${IMPORT}await sleep(ms as number)`,
+        filename,
+        errors: [{ messageId: 'preferSleep' }],
+      },
+    ],
+  })
+})

package/src/rules/prefer-sleep.ts

@@ -0,0 +1,228 @@
+import type { Rule, Scope } from 'eslint'
+import type {
+  ArrowFunctionExpression,
+  CallExpression,
+  Expression,
+  FunctionExpression,
+  Node,
+  SpreadElement,
+} from 'estree'
+
+import {
+  createImportFix,
+  findVariable,
+  isPackageAvailable,
+  packageRuleSchema,
+  UTILS_PACKAGE,
+} from '../utils/package-import'
+
+type FunctionNode = ArrowFunctionExpression | FunctionExpression
+
+function isFunction(node: Node): node is FunctionNode {
+  return node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression'
+}
+
+/**
+ * Returns true when `name` refers to a global variable, not a local binding.
+ */
+function isGlobal(scope: Scope.Scope, name: string): boolean {
+  const variable = findVariable(scope, name)
+  return !variable || variable.defs.length === 0
+}
+
+/**
+ * Returns the only expression that a function body evaluates, for bodies
+ * such as `x`, `{ x }` and `{ return x }`.
+ */
+function getOnlyExpression(node: FunctionNode): Expression | undefined {
+  const body = node.body
+  if (body.type !== 'BlockStatement') {
+    return body
+  }
+  if (body.body.length !== 1) {
+    return undefined
+  }
+  const statement = body.body[0]
+  if (statement.type === 'ExpressionStatement') {
+    return statement.expression
+  }
+  if (statement.type === 'ReturnStatement' && statement.argument) {
+    return statement.argument
+  }
+  return undefined
+}
+
+function isIdentifier(node: Node | SpreadElement, name: string): boolean {
+  return node.type === 'Identifier' && node.name === name
+}
+
+/**
+ * Returns true for `setTimeout`, `globalThis.setTimeout` and
+ * `window.setTimeout`.
+ */
+function isSetTimeout(node: Expression, scope: Scope.Scope): boolean {
+  if (node.type === 'Identifier') {
+    return node.name === 'setTimeout' && isGlobal(scope, 'setTimeout')
+  }
+  return (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    isIdentifier(node.property, 'setTimeout') &&
+    node.object.type === 'Identifier' &&
+    (node.object.name === 'globalThis' || node.object.name === 'window') &&
+    isGlobal(scope, node.object.name)
+  )
+}
+
+/**
+ * Returns true for `resolve` and `() => resolve()`.
+ */
+function isResolveCallback(node: Expression | SpreadElement, resolve: string): boolean {
+  if (isIdentifier(node, resolve)) {
+    return true
+  }
+  if (!isFunction(node) || node.async || node.generator || node.params.length > 0) {
+    return false
+  }
+  const expression = getOnlyExpression(node)
+  return (
+    expression?.type === 'CallExpression' &&
+    isIdentifier(expression.callee, resolve) &&
+    expression.arguments.length === 0
+  )
+}
+
+/**
+ * Returns true for no type argument, `<void>` and `<undefined>`.
+ */
+function hasVoidTypeArgument(node: Node): boolean {
+  const typeArguments = (node as { typeArguments?: { params: { type: string }[] } }).typeArguments
+  if (!typeArguments) {
+    return true
+  }
+  return (
+    typeArguments.params.length === 1 &&
+    (typeArguments.params[0].type === 'TSVoidKeyword' ||
+      typeArguments.params[0].type === 'TSUndefinedKeyword')
+  )
+}
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description:
+        'enforce `sleep` from `@ocavue/utils` instead of `new Promise` with `setTimeout`',
+      url: 'https://github.com/ocavue/eslint-plugin-ocavue#prefer-sleep',
+    },
+    messages: {
+      preferSleep: 'Use `sleep` from `@ocavue/utils` instead of `new Promise` with `setTimeout`.',
+    },
+    schema: packageRuleSchema,
+  },
+  create(context) {
+    if (!isPackageAvailable(context, UTILS_PACKAGE)) {
+      return {}
+    }
+
+    const sourceCode = context.sourceCode
+
+    /**
+     * Returns the delay expression of `new Promise((resolve) =>
+     * setTimeout(resolve, delay))`, or `undefined` when the node does not
+     * match.
+     */
+    function getDelay(node: Node): Expression | undefined {
+      if (
+        node.type !== 'NewExpression' ||
+        !isIdentifier(node.callee, 'Promise') ||
+        node.arguments.length !== 1 ||
+        !hasVoidTypeArgument(node)
+      ) {
+        return undefined
+      }
+      if (!isGlobal(sourceCode.getScope(node), 'Promise')) {
+        return undefined
+      }
+
+      const executor = node.arguments[0]
+      if (!isFunction(executor) || executor.async || executor.generator) {
+        return undefined
+      }
+      if (!executor.params.every((param) => param.type === 'Identifier')) {
+        return undefined
+      }
+      const resolveParam = executor.params[0]
+      if (resolveParam?.type !== 'Identifier') {
+        return undefined
+      }
+
+      const call = getOnlyExpression(executor)
+      if (call?.type !== 'CallExpression' || call.optional) {
+        return undefined
+      }
+      const executorScope = sourceCode.getScope(executor)
+      if (!isSetTimeout(call.callee as Expression, executorScope)) {
+        return undefined
+      }
+
+      const [callback, delay] = (call as CallExpression).arguments
+      if (call.arguments.length !== 2 || !delay || delay.type === 'SpreadElement') {
+        return undefined
+      }
+      if (!isResolveCallback(callback, resolveParam.name)) {
+        return undefined
+      }
+
+      // The delay moves out of the executor, so it must not use the
+      // executor's parameters, `this` or `arguments`.
+      const usesExecutorParams = executorScope.variables.some((variable) => {
+        return variable.references.some((reference) => {
+          const range = reference.identifier.range!
+          return range[0] >= delay.range![0] && range[1] <= delay.range![1]
+        })
+      })
+      if (usesExecutorParams) {
+        return undefined
+      }
+      if (
+        executor.type === 'FunctionExpression' &&
+        sourceCode.getTokens(delay).some((token) => {
+          return token.value === 'this' || token.value === 'arguments'
+        })
+      ) {
+        return undefined
+      }
+
+      return delay
+    }
+
+    return {
+      NewExpression(node) {
+        const delay = getDelay(node)
+        if (!delay) {
+          return
+        }
+        const delayText = sourceCode.getText(delay)
+        context.report({
+          node,
+          messageId: 'preferSleep',
+          fix: createImportFix({
+            context,
+            node,
+            name: 'sleep',
+            packageName: UTILS_PACKAGE,
+            replace: (local) => {
+              return delay.type === 'SequenceExpression'
+                ? `${local}((${delayText}))`
+                : `${local}(${delayText})`
+            },
+          }),
+        })
+      },
+    }
+  },
+}
+
+export default rule

package/src/utils/constant-function.ts

@@ -0,0 +1,102 @@
+import type { Rule } from 'eslint'
+import type { ArrowFunctionExpression, Expression, FunctionExpression, Node } from 'estree'
+
+export type FunctionNode = (ArrowFunctionExpression | FunctionExpression) & Rule.NodeParentExtension
+
+/**
+ * The value that a constant function returns.
+ */
+export type ConstantValue = 'undefined' | 'true' | 'false' | 'null'
+
+function getConstantValue(node: Expression): ConstantValue | undefined {
+  if (node.type === 'Literal') {
+    switch (node.raw) {
+      case 'true':
+      case 'false':
+      case 'null':
+        return node.raw
+    }
+    return undefined
+  }
+  if (node.type === 'Identifier' && node.name === 'undefined') {
+    return 'undefined'
+  }
+  if (
+    node.type === 'UnaryExpression' &&
+    node.operator === 'void' &&
+    node.argument.type === 'Literal'
+  ) {
+    return 'undefined'
+  }
+  return undefined
+}
+
+function getReturnedValue(node: FunctionNode): ConstantValue | undefined {
+  const body = node.body
+  if (body.type !== 'BlockStatement') {
+    return getConstantValue(body)
+  }
+  if (body.body.length === 0) {
+    return 'undefined'
+  }
+  if (body.body.length === 1) {
+    const statement = body.body[0]
+    if (statement.type === 'ReturnStatement') {
+      return statement.argument ? getConstantValue(statement.argument) : 'undefined'
+    }
+  }
+  return undefined
+}
+
+/**
+ * Returns true when the function can be swapped with a function reference
+ * without changing runtime behavior.
+ */
+function isReplaceable(node: FunctionNode): boolean {
+  if (node.async || node.generator) {
+    return false
+  }
+  if ((node as { typeParameters?: unknown }).typeParameters) {
+    return false
+  }
+
+  // Every parameter must be a plain identifier. Default values may have side
+  // effects, and destructuring may throw.
+  const hasPlainParams = node.params.every((param) => {
+    return (
+      param.type === 'Identifier' ||
+      (param.type === 'RestElement' && param.argument.type === 'Identifier')
+    )
+  })
+  if (!hasPlainParams) {
+    return false
+  }
+
+  if (node.type === 'FunctionExpression') {
+    if (node.id) {
+      return false
+    }
+    const parent: Node = node.parent
+    if (parent.type === 'Property' && (parent.method || parent.kind !== 'init')) {
+      return false
+    }
+    if (parent.type === 'MethodDefinition') {
+      return false
+    }
+    if (parent.type === 'NewExpression' && parent.callee === node) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Returns the value that an inline function always returns, such as
+ * `'true'` for `() => true` or `'undefined'` for `() => {}`. Returns
+ * `undefined` when the function does more than that, or when replacing it
+ * could change runtime behavior.
+ */
+export function getConstantFunctionValue(node: FunctionNode): ConstantValue | undefined {
+  return isReplaceable(node) ? getReturnedValue(node) : undefined
+}

package/src/utils/has-dependency.ts

@@ -0,0 +1,81 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+interface PackageJson {
+  name?: string
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  peerDependencies?: Record<string, string>
+}
+
+// Maps a directory to its nearest `package.json`, or `null` when there is none.
+const cache = new Map<string, PackageJson | null>()
+
+function readPackageJson(dir: string): PackageJson | undefined {
+  let text: string
+  try {
+    text = fs.readFileSync(path.join(dir, 'package.json'), 'utf8')
+  } catch {
+    return undefined
+  }
+  try {
+    const json: unknown = JSON.parse(text)
+    return json && typeof json === 'object' ? json : {}
+  } catch {
+    return {}
+  }
+}
+
+function findNearestPackageJson(startDir: string): PackageJson | null {
+  const visited: string[] = []
+  let dir = startDir
+  let result: PackageJson | null = null
+
+  while (true) {
+    const cached = cache.get(dir)
+    if (cached !== undefined) {
+      result = cached
+      break
+    }
+    visited.push(dir)
+
+    const pkg = readPackageJson(dir)
+    if (pkg) {
+      result = pkg
+      break
+    }
+
+    const parent = path.dirname(dir)
+    if (parent === dir) {
+      break
+    }
+    dir = parent
+  }
+
+  for (const visitedDir of visited) {
+    cache.set(visitedDir, result)
+  }
+  return result
+}
+
+/**
+ * Returns true when the nearest `package.json` of `filename` lists
+ * `packageName` in `dependencies`, `devDependencies` or `peerDependencies`.
+ *
+ * A package never depends on itself, so this returns false inside the
+ * package named `packageName`.
+ */
+export function hasDependency(filename: string, packageName: string): boolean {
+  if (!path.isAbsolute(filename)) {
+    return false
+  }
+
+  const pkg = findNearestPackageJson(path.dirname(filename))
+  if (!pkg || pkg.name === packageName) {
+    return false
+  }
+
+  return [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies].some(
+    (deps) => deps != null && typeof deps === 'object' && Object.hasOwn(deps, packageName),
+  )
+}