chore: add few jsdoc to probes (with links to estree and code examples)

src/probes/isArrayExpression.js

@@ -1,4 +1,10 @@
-// Search for Array
+/**
+ * @description Search for ArrayExpression AST Node (Commonly known as JS Arrays)
+ *
+ * @see https://github.com/estree/estree/blob/master/es5.md#arrayexpression
+ * @example
+ * ["foo", "bar", 1]
+ */
 function validateNode(node) {
   return [
     node.type === "ArrayExpression"

src/probes/isAssignmentExpression.js

@@ -1,6 +1,13 @@
 // Import Internal Dependencies
 import { getIdName } from "../utils.js";
 
+/**
+ * @description Search for AssignmentExpression (Not to be confused with AssignmentPattern).
+ *
+ * @see https://github.com/estree/estree/blob/master/es5.md#assignmentexpression
+ * @example
+ * (foo = 5)
+ */
 function validateNode(node) {
   return [
     node.type === "AssignmentExpression"

src/probes/isBinaryExpression.js

@@ -1,3 +1,10 @@
+/**
+ * @description Search for BinaryExpression AST Node.
+ *
+ * @see https://github.com/estree/estree/blob/master/es5.md#binaryexpression
+ * @example
+ * 5 + 5 + 10
+ */
 function validateNode(node) {
   return [
     node.type === "BinaryExpression"
@@ -13,6 +20,13 @@ function main(node, options) {
   }
 }
 
+/**
+ * @description Look for suspicious BinaryExpression (read the Obfuscator.io section of the linked G.Doc)
+ * @see https://docs.google.com/document/d/11ZrfW0bDQ-kd7Gr_Ixqyk8p3TGvxckmhFH3Z8dFoPhY/edit?usp=sharing
+ * @see https://github.com/estree/estree/blob/master/es5.md#unaryexpression
+ * @example
+ * 0x1*-0x12df+-0x1fb9*-0x1+0x2*-0x66d
+ */
 function walkBinaryExpression(expr, level = 1) {
   const [lt, rt] = [expr.left.type, expr.right.type];
   let hasUnaryExpression = lt === "UnaryExpression" || rt === "UnaryExpression";

src/probes/isFunctionDeclaration.js

@@ -1,3 +1,10 @@
+/**
+ * @description Search for FunctionDeclaration AST Node.
+ *
+ * @see https://github.com/estree/estree/blob/master/es5.md#functiondeclaration
+ * @example
+ * function foo() {}
+ */
 function validateNode(node) {
   return [
     node.type === "FunctionDeclaration"

src/probes/isImportDeclaration.js

@@ -1,10 +1,17 @@
 // Require Internal Dependencies
 import { warnings } from "../constants.js";
 
-// Looking for ESM ImportDeclaration
-// see: https://github.com/estree/estree/blob/master/es2015.md#importdeclaration
+/**
+ * @description Search for ESM ImportDeclaration
+ * @see https://github.com/estree/estree/blob/master/es2015.md#importdeclaration
+ * @example
+ * import * as foo from "bar";
+ * import fs from "fs";
+ * import "make-promises-safe";
+ */
 function validateNode(node) {
   return [
+    // Note: the source property is the right-side Literal part of the Import
     node.type === "ImportDeclaration" && node.source.type === "Literal"
   ];
 }

src/probes/isLiteral.js

@@ -10,7 +10,12 @@ import { globalParts, warnings } from "../constants.js";
 // CONSTANTS
 const kNodeDeps = new Set(builtinModules);
 
-// Check all 'string' Literal values
+/**
+ * @description Search for Literal AST Node
+ * @see https://github.com/estree/estree/blob/master/es5.md#literal
+ * @example
+ * "foobar"
+ */
 function validateNode(node) {
   return [
     node.type === "Literal" && typeof node.value === "string"

src/probes/isLiteralRegex.js

@@ -5,8 +5,12 @@ import { warnings } from "../constants.js";
 // Require Third-party Dependencies
 import safeRegex from "safe-regex";
 
-// Search for Literal Regex.
-// then we use the safe-regex package to detect whether or not regex is safe!
+/**
+ * @description Search for RegExpLiteral AST Node
+ * @see https://github.com/estree/estree/blob/master/es5.md#regexpliteral
+ * @example
+ * /hello/
+ */
 function validateNode(node) {
   return [
     isLiteralRegex(node)
@@ -16,6 +20,7 @@ function validateNode(node) {
 function main(node, options) {
   const { analysis } = options;
 
+  // We use the safe-regex package to detect whether or not regex is safe!
   if (!safeRegex(node.regex.pattern)) {
     analysis.addWarning(warnings.unsafeRegex, node.regex.pattern, node.loc);
   }

src/probes/isObjectExpression.js

@@ -1,3 +1,9 @@
+/**
+ * @description Search for ObjectExpression AST Node (commonly known as Object).
+ * @see https://github.com/estree/estree/blob/master/es5.md#objectexpression
+ * @example
+ * { foo: "bar" }
+ */
 function validateNode(node) {
   return [
     node.type === "ObjectExpression"

src/probes/isRegexObject.js

@@ -5,8 +5,12 @@ import { warnings } from "../constants.js";
 // Import Third-party Dependencies
 import safeRegex from "safe-regex";
 
-// Search for Regex Object constructor.
-// then we use the safe-regex package to detect whether or not regex is safe!
+/**
+ * @description Search for Regex Object constructor.
+ * @see https://github.com/estree/estree/blob/master/es5.md#newexpression
+ * @example
+ * new RegExp("...");
+ */
 function validateNode(node) {
   return [
     isRegexConstructor(node) && node.arguments.length > 0
@@ -19,6 +23,7 @@ function main(node, options) {
   const arg = node.arguments[0];
   const pattern = isLiteralRegex(arg) ? arg.regex.pattern : arg.value;
 
+  // We use the safe-regex package to detect whether or not regex is safe!
   if (!safeRegex(pattern)) {
     analysis.addWarning(warnings.unsafeRegex, pattern, node.loc);
   }

src/probes/isUnaryExpression.js

@@ -1,3 +1,9 @@
+/**
+ * @description Search for UnaryExpression AST Node
+ * @see https://github.com/estree/estree/blob/master/es5.md#unaryexpression
+ * @example
+ * -2
+ */
 function validateNode(node) {
   return [
     node.type === "UnaryExpression"
@@ -7,6 +13,8 @@ function validateNode(node) {
 function main(node, options) {
   const { analysis } = options;
 
+  // Example: !![]
+  // See: https://docs.google.com/document/d/11ZrfW0bDQ-kd7Gr_Ixqyk8p3TGvxckmhFH3Z8dFoPhY/edit#
   if (node.argument.type === "UnaryExpression" && node.argument.argument.type === "ArrayExpression") {
     analysis.counter.doubleUnaryArray++;
   }

src/probes/isUnsafeCallee.js

@@ -2,7 +2,12 @@
 import { isUnsafeCallee } from "../utils.js";
 import { warnings } from "../constants.js";
 
-// Detect unsafe statement like eval("this") or Function("return this")();
+/**
+ * @description Detect unsafe statement
+ * @example
+ * eval("this");
+ * Function("return this")();
+ */
 function validateNode(node) {
   return isUnsafeCallee(node);
 }