refactor(estree-ast-utils): enhance input and output types using Meriyah ESTree defs

Author: fraxken

.changeset/mean-waves-retire.md

@@ -0,0 +1,5 @@
+---
+"@nodesecure/estree-ast-utils": minor
+---
+
+Enhance input and output types using Meriyah ESTree defs

workspaces/estree-ast-utils/README.md

@@ -20,7 +20,7 @@ $ yarn add @nodesecure/estree-ast-utils
 
 ## API
 
-<details><summary>arrayExpressionToString(node): IterableIterator< string ></summary>
+<details><summary>arrayExpressionToString(node: ESTree.Node | null): IterableIterator< string ></summary>
 
 Translate an ESTree ArrayExpression into an iterable of Literal value.
 
@@ -32,7 +32,7 @@ will return `"foo"` then `"bar"`.
 
 </details>
 
-<details><summary>concatBinaryExpression(node, options): IterableIterator< string ></summary>
+<details><summary>concatBinaryExpression(node: ESTree.BinaryExpression, options?: ConcatBinaryExpressionOptions): IterableIterator< string ></summary>
 
 Return all Literal part of a given Binary Expression.
 
@@ -42,11 +42,17 @@ Return all Literal part of a given Binary Expression.
 
 will return `"foo"` then `"bar"`.
 
-One of the options of the method is `stopOnUnsupportedNode`, if true it will throw an Error if the left or right side of the Expr is not a supported type.
+```ts
+export interface ConcatBinaryExpressionOptions extends TracerOptions {
+  stopOnUnsupportedNode?: boolean;
+}
+```
+
+If `stopOnUnsupportedNode` option is enabled it will throw an Error if the left or right side of the Expr is not a supported type.
 
 </details>
 
-<details><summary>getCallExpressionIdentifier(node, options): string | null</summary>
+<details><summary>getCallExpressionIdentifier(node: ESTree.Node, options?: GetCallExpressionIdentifierOptions): string | null</summary>
 
 Return the identifier name of the CallExpression (or null if there is none).
 
@@ -69,7 +75,7 @@ With **resolveCallExpression** equal to **false** the function return `null`.
 
 </details>
 
-<details><summary>getMemberExpressionIdentifier(node): IterableIterator< string ></summary>
+<details><summary>getMemberExpressionIdentifier(node: ESTree.MemberExpression, options?: TracerOptions): IterableIterator< string ></summary>
 
 Return the identifier name of the CallExpression (or null if there is none).
 
@@ -81,7 +87,7 @@ will return `"foo"` then `"bar"`.
 
 </details>
 
-<details><summary>getVariableDeclarationIdentifiers(node): IterableIterator< string ></summary>
+<details><summary>getVariableDeclarationIdentifiers(node: any, options?: GetVariableDeclarationIdentifiersOptions): IterableIterator< string ></summary>
 
 Get all variables identifier name.
 
@@ -93,17 +99,7 @@ will return `"foo"` then `"bar"`.
 
 </details>
 
-<details><summary>isLiteralRegex(node): boolean</summary>
-
-Return `true` if the given Node is a Literal Regex Node.
-
-```js
-/^hello/g;
-```
-
-</details>
-
-<details><summary>extractLogicalExpression(node)</summary>
+<details><summary>extractLogicalExpression(node: ESTree.Node): IterableIterator< { operator: string; node: ESTree.Expression; } ></summary>
 
 Extract all LogicalExpression recursively and return an IterableIterator of 
 

workspaces/estree-ast-utils/package.json

@@ -30,6 +30,7 @@
   },
   "homepage": "https://github.com/NodeSecure/js-x-ray/tree/master/workspaces/estree-ast-utils#readme",
   "dependencies": {
-    "@nodesecure/sec-literal": "^1.1.0"
+    "@nodesecure/sec-literal": "^1.1.0",
+    "meriyah": "^6.1.3"
   }
 }

workspaces/estree-ast-utils/src/arrayExpressionToString.ts

@@ -1,8 +1,11 @@
+// Import Third-party Dependencies
+import type { ESTree } from "meriyah";
+
 // Import Internal Dependencies
-import type { TracerOptions, NodeAst } from "./types.js";
+import type { TracerOptions } from "./types.js";
 
 export function* arrayExpressionToString(
-  node: NodeAst,
+  node: ESTree.Node | null,
   options: TracerOptions = {}
 ): IterableIterator<string> {
   const { tracer = null } = options;
@@ -12,18 +15,26 @@ export function* arrayExpressionToString(
   }
 
   for (const row of node.elements) {
+    if (row === null) {
+      continue;
+    }
+
     switch (row.type) {
       case "Literal": {
-        if (row.value === "") {
+        if (
+          row.value === ""
+        ) {
           continue;
         }
 
         const value = Number(row.value);
-        yield Number.isNaN(value) ? row.value : String.fromCharCode(value);
+        yield Number.isNaN(value) ?
+          String(row.value) :
+          String.fromCharCode(value);
         break;
       }
       case "Identifier": {
-        if (tracer !== null && tracer.literalIdentifiers.has(row.name)) {
+        if (tracer?.literalIdentifiers.has(row.name)) {
           yield tracer.literalIdentifiers.get(row.name);
         }
         break;

workspaces/estree-ast-utils/src/concatBinaryExpression.ts

@@ -1,6 +1,9 @@
+// Import Third-party Dependencies
+import type { ESTree } from "meriyah";
+
 // Import Internal Dependencies
 import { arrayExpressionToString } from "./arrayExpressionToString.js";
-import type { TracerOptions, NodeAst } from "./types.js";
+import type { TracerOptions } from "./types.js";
 
 // CONSTANTS
 const kBinaryExprTypes = new Set([
@@ -11,11 +14,19 @@ const kBinaryExprTypes = new Set([
 ]);
 
 export interface ConcatBinaryExpressionOptions extends TracerOptions {
+  /**
+   * When set to true, the function will throw an error if it encounters
+   * a node type that is not supported (i.e., not a Literal, BinaryExpr, ArrayExpr or Identifier).
+   *
+   * @default false
+   * @example
+   * "foo" + fn() + "bar" // <- will throw an error if `stopOnUnsupportedNode` is true
+   */
   stopOnUnsupportedNode?: boolean;
 }
 
 export function* concatBinaryExpression(
-  node: NodeAst,
+  node: ESTree.BinaryExpression,
   options: ConcatBinaryExpressionOptions = {}
 ): IterableIterator<string> {
   const {
@@ -45,7 +56,9 @@ export function* concatBinaryExpression(
         break;
       }
       case "Literal":
-        yield childNode.value;
+        if (typeof childNode.value === "string") {
+          yield childNode.value;
+        }
         break;
       case "Identifier":
         if (tracer !== null && tracer.literalIdentifiers.has(childNode.name)) {

workspaces/estree-ast-utils/src/extractLogicalExpression.ts

@@ -1,11 +1,9 @@
-// Import Internal Dependencies
-import type { NodeAst } from "./types.js";
-
-export type LogicalExpressionOperators = "||" | "&&" | "??";
+// Import Third-party Dependencies
+import type { ESTree } from "meriyah";
 
 export function* extractLogicalExpression(
-  node: NodeAst
-): IterableIterator<{ operator: LogicalExpressionOperators; node: NodeAst; }> {
+  node: ESTree.Node
+): IterableIterator<{ operator: string; node: ESTree.Expression; }> {
   if (node.type !== "LogicalExpression") {
     return;
   }

workspaces/estree-ast-utils/src/getCallExpressionArguments.ts

@@ -1,12 +1,13 @@
 // Import Third-party Dependencies
 import { Hex } from "@nodesecure/sec-literal";
+import type { ESTree } from "meriyah";
 
 // Import Internal Dependencies
 import { concatBinaryExpression } from "./concatBinaryExpression.js";
-import type { TracerOptions, NodeAst } from "./types.js";
+import type { TracerOptions } from "./types.js";
 
 export function getCallExpressionArguments(
-  node: NodeAst,
+  node: ESTree.Node,
   options: TracerOptions = {}
 ): string[] | null {
   const { tracer = null } = options;
@@ -26,7 +27,9 @@ export function getCallExpressionArguments(
         break;
       }
       case "Literal": {
-        literalsNode.push(hexToString(arg.value));
+        if (typeof arg.value === "string") {
+          literalsNode.push(hexToString(arg.value));
+        }
 
         break;
       }

workspaces/estree-ast-utils/src/getCallExpressionIdentifier.ts

@@ -1,13 +1,24 @@
+// Import Third-party Dependencies
+import type { ESTree } from "meriyah";
+
 // Import Internal Dependencies
 import { getMemberExpressionIdentifier } from "./getMemberExpressionIdentifier.js";
-import type { TracerOptions, NodeAst } from "./types.js";
+import type { TracerOptions } from "./types.js";
 
 export interface GetCallExpressionIdentifierOptions extends TracerOptions {
+  /**
+   * Resolve the CallExpression callee if it is a MemberExpression.
+   *
+   * @default true
+   * @example
+   * require('./file.js')();
+            ^ Second     ^ First
+   */
   resolveCallExpression?: boolean;
 }
 
 export function getCallExpressionIdentifier(
-  node: NodeAst,
+  node: ESTree.Node,
   options: GetCallExpressionIdentifierOptions = {}
 ): string | null {
   if (node.type !== "CallExpression") {

workspaces/estree-ast-utils/src/getMemberExpressionIdentifier.ts

@@ -1,15 +1,16 @@
 // Import Third-party Dependencies
+import type { ESTree } from "meriyah";
 import { Hex } from "@nodesecure/sec-literal";
 
 // Import Internal Dependencies
 import { concatBinaryExpression } from "./concatBinaryExpression.js";
-import type { TracerOptions, NodeAst } from "./types.js";
+import type { TracerOptions } from "./types.js";
 
 /**
  * Return the complete identifier of a MemberExpression
  */
 export function* getMemberExpressionIdentifier(
-  node: NodeAst,
+  node: ESTree.MemberExpression,
   options: TracerOptions = {}
 ): IterableIterator<string> {
   const { tracer = null } = options;
@@ -24,7 +25,9 @@ export function* getMemberExpressionIdentifier(
       break;
     // Literal is used when the property is computed
     case "Literal":
-      yield node.object.value;
+      if (typeof node.object.value === "string") {
+        yield node.object.value;
+      }
       break;
   }
 
@@ -41,13 +44,20 @@ export function* getMemberExpressionIdentifier(
     }
     // Literal is used when the property is computed
     case "Literal":
-      yield node.property.value;
+      if (typeof node.property.value === "string") {
+        yield node.property.value;
+      }
       break;
 
     // foo.bar[callexpr()]
     case "CallExpression": {
       const args = node.property.arguments;
-      if (args.length > 0 && args[0].type === "Literal" && Hex.isHex(args[0].value)) {
+      if (
+        args.length > 0 &&
+        args[0].type === "Literal" &&
+        typeof args[0].value === "string" &&
+        Hex.isHex(args[0].value)
+      ) {
         yield Buffer.from(args[0].value, "hex").toString();
       }
       break;

workspaces/estree-ast-utils/src/getVariableDeclarationIdentifiers.ts

@@ -1,16 +1,20 @@
-// Import Internal Dependencies
-import type { NodeAst } from "./types.js";
+// Import Third-party Dependencies
+import type { ESTree } from "meriyah";
 
 export interface GetVariableDeclarationIdentifiersOptions {
+  /**
+   * Prefix to add to the variable name.
+   * @default void
+   */
   prefix?: string;
 }
 
 export function* getVariableDeclarationIdentifiers(
-  node: NodeAst,
+  node: ESTree.Node,
   options: GetVariableDeclarationIdentifiersOptions = {}
 ): IterableIterator<{
     name: string;
-    assignmentId: NodeAst;
+    assignmentId: ESTree.Identifier;
   }> {
   const { prefix = null } = options;
 
@@ -34,11 +38,14 @@ export function* getVariableDeclarationIdentifiers(
       break;
 
     case "Property": {
-      if (node.kind !== "init") {
+      if (node.kind !== "init" || node.key.type !== "Identifier") {
         break;
       }
 
-      if (node.value.type === "ObjectPattern" || node.value.type === "ArrayPattern") {
+      if (
+        node.value.type === "ObjectPattern" ||
+        node.value.type === "ArrayPattern"
+      ) {
         yield* getVariableDeclarationIdentifiers(node.value, {
           prefix: autoPrefix(node.key.name, prefix)
         });
@@ -50,10 +57,14 @@ export function* getVariableDeclarationIdentifiers(
         assignmentId = node.value;
       }
       else if (node.value.type === "AssignmentPattern") {
+        // @ts-ignore
         assignmentId = node.value.left;
       }
 
-      yield { name: autoPrefix(node.key.name, prefix), assignmentId };
+      yield {
+        name: autoPrefix(node.key.name, prefix),
+        assignmentId
+      };
 
       break;
     }
@@ -64,7 +75,12 @@ export function* getVariableDeclarationIdentifiers(
      * const {...foo} = {}
      */
     case "RestElement":
-      yield { name: autoPrefix(node.argument.name, prefix), assignmentId: node.argument };
+      if (node.argument.type === "Identifier") {
+        yield {
+          name: autoPrefix(node.argument.name, prefix),
+          assignmentId: node.argument
+        };
+      }
 
       break;
 
@@ -83,7 +99,7 @@ export function* getVariableDeclarationIdentifiers(
      */
     case "AssignmentPattern":
       if (node.left.type === "Identifier") {
-        yield node.left.name;
+        yield { name: node.left.name, assignmentId: node.left };
       }
       else {
         yield* getVariableDeclarationIdentifiers(node.left);