feat: add helpers to extract class methods, validator direct usage and method arguments

Author: thetutlage

package.json

@@ -59,6 +59,7 @@
   "dependencies": {
     "@adonisjs/env": "^6.2.0",
     "@antfu/install-pkg": "^1.1.0",
+    "@ast-grep/napi": "^0.39.3",
     "@poppinss/cliui": "^6.4.4",
     "@poppinss/hooks": "^7.2.6",
     "@poppinss/utils": "^7.0.0-next.3",
@@ -69,6 +70,7 @@
     "get-port": "^7.1.0",
     "junk": "^4.0.1",
     "open": "^10.2.0",
+    "parse-imports": "^2.2.1",
     "picomatch": "^4.0.3",
     "pretty-hrtime": "^1.0.3",
     "tmp-cache": "^1.1.0",

src/types/common.ts

@@ -8,14 +8,26 @@
  */
 
 import type { Logger } from '@poppinss/cliui'
-
 import {
   type BundlerHooks,
   type DevServerHooks,
   type TestRunnerHooks,
   type WatcherHooks,
 } from './hooks.ts'
 
+/**
+ * Represents an import statement
+ */
+export type Import = {
+  specifier: string
+  isConstant: boolean
+  clause: {
+    type: 'namespace' | 'default' | 'named'
+    value: string
+    alias?: string
+  }
+}
+
 /**
  * File inspected by the filesystem based upon the provided globs
  * and the current file path

src/utils.ts

@@ -16,6 +16,8 @@ import getRandomPort from 'get-port'
 import type tsStatic from 'typescript'
 import { fileURLToPath } from 'node:url'
 import { execaNode, execa } from 'execa'
+import { parseImports } from 'parse-imports'
+import { type SgNode } from '@ast-grep/napi'
 import { importDefault } from '@poppinss/utils'
 import { copyFile, mkdir } from 'node:fs/promises'
 import { EnvLoader, EnvParser } from '@adonisjs/env'
@@ -24,7 +26,7 @@ import { type UnWrapLazyImport } from '@poppinss/utils/types'
 import { basename, dirname, isAbsolute, join, relative } from 'node:path'
 
 import debug from './debug.ts'
-import type { RunScriptOptions } from './types/common.ts'
+import type { Import, RunScriptOptions } from './types/common.ts'
 import {
   type WatcherHooks,
   type BundlerHooks,
@@ -318,3 +320,181 @@ export function throttle<Args extends any[]>(
 
   return throttled
 }
+
+/**
+ * Finds an import reference inside a code snippet
+ */
+export async function findImport(code: string, importReference: string): Promise<Import | null> {
+  const importIdentifier = importReference.split('.')[0]
+
+  for (const $import of await parseImports(code, {})) {
+    /**
+     * An import without any clause
+     */
+    if (!$import.importClause) {
+      continue
+    }
+
+    /**
+     * An import without any clause
+     */
+    if (!$import.moduleSpecifier.value) {
+      continue
+    }
+
+    /**
+     * Import identifier matches a default import
+     */
+    if ($import.importClause.default === importIdentifier) {
+      return {
+        specifier: $import.moduleSpecifier.value,
+        isConstant: $import.moduleSpecifier.isConstant,
+        clause: {
+          type: 'default',
+          value: importIdentifier,
+        },
+      } satisfies Import
+    }
+
+    /**
+     * Import identifier matches a namespace import
+     */
+    if ($import.importClause.namespace === importIdentifier) {
+      return {
+        specifier: $import.moduleSpecifier.value,
+        isConstant: $import.moduleSpecifier.isConstant,
+        clause: {
+          type: 'namespace',
+          value: importIdentifier,
+        },
+      } satisfies Import
+    }
+
+    const namedImport = $import.importClause.named.find(({ binding }) => {
+      return binding === importIdentifier
+    })
+
+    /**
+     * Import identifier matches a named import
+     */
+    if (namedImport) {
+      return {
+        specifier: $import.moduleSpecifier.value,
+        isConstant: $import.moduleSpecifier.isConstant,
+        clause: {
+          type: 'named',
+          value: namedImport.specifier,
+          ...(namedImport.binding !== namedImport.specifier
+            ? {
+                alias: namedImport.binding,
+              }
+            : {}),
+        },
+      } satisfies Import
+    }
+  }
+
+  return null
+}
+
+/**
+ * Returns an array of SgNodes for class methods. The class name
+ * could be fetched using the `KCLASS` identifier.
+ */
+export function inspectClassMethods(node: SgNode): SgNode[] {
+  return node.findAll({
+    rule: {
+      kind: 'method_definition',
+      inside: {
+        pattern: {
+          selector: 'class_declaration',
+          context: 'class $KCLASS {$$$}',
+        },
+        stopBy: 'end',
+      },
+    },
+  })
+}
+
+/**
+ * Converts an array of SgNode to plain text by removing whitespaces,
+ * identation and comments in between. Tested with the following
+ * children nodes only.
+ *
+ * - MemberExpression
+ * - Identifer
+ */
+export function nodeToPlainText(node: SgNode) {
+  let out: string[] = []
+  function toText(one: SgNode) {
+    const children = one.children()
+    if (!children.length) {
+      out.push(one.text())
+    } else {
+      children.forEach((child) => toText(child))
+    }
+  }
+
+  toText(node)
+  return out.join('')
+}
+
+/**
+ * Inspects arguments for one or more method calls. If you want to
+ * scope the search within a specific context, then make sure to
+ * first narrow down the AST and pass a specific SgNode.
+ *
+ * For example: In case of validators, we will first find the Controller
+ * method for which we want the validation method calls.
+ */
+export function inspectMethodArguments(node: SgNode, methodCalls: string[]): SgNode[] {
+  const matchingExpressions = node.findAll({
+    rule: {
+      any: methodCalls.map((methodCall) => {
+        return {
+          pattern: {
+            context: `${methodCall}($$$ARGUMENTS)`,
+            selector: 'call_expression',
+          },
+        }
+      }),
+    },
+  })
+
+  return matchingExpressions.flatMap((matchingExpression) => {
+    return matchingExpression.findAll({ rule: { kind: 'arguments' } })
+  })
+}
+
+/**
+ * Inspect the validator direct usage code snippets. A member expression
+ * calling the ".validate" method is considered as direct usage of
+ * the validator.
+ */
+export function searchValidatorDirectUsage(node: SgNode): SgNode[] {
+  const matchingExpressions = node.findAll({
+    rule: {
+      pattern: {
+        context: '$$$VALIDATOR.validate($$$)',
+        selector: 'call_expression',
+      },
+    },
+  })
+
+  return matchingExpressions.flatMap((expression) => {
+    /**
+     * Since we capture all "$$$.validate" calls, the first node
+     * within the call expression will be a member expression
+     * and its property identifier will be "validate".
+     *
+     * What we need is the text of this member expression without the
+     * comments
+     */
+    const firstMemberExpression = expression.getMultipleMatches('VALIDATOR')
+    return firstMemberExpression.flatMap((exp) => {
+      return exp.find({
+        rule: { any: [{ kind: 'identifier' }, { kind: 'member_expression' }] },
+      })!
+    })
+  })
+}