@nodesecure/js-x-ray 7.1.1 → 7.3.0

package/README.md

@@ -223,6 +223,8 @@ interface RuntimeOptions {
   module?: boolean;
   removeHTMLComments?: boolean;
   isMinified?: boolean;
+  initialize?: (sourceFile: SourceFile) => void;
+  finalize?: (sourceFile: SourceFile) => void;
 }
 ```
 
@@ -256,6 +258,8 @@ interface RuntimeFileOptions {
   module?: boolean;
   removeHTMLComments?: boolean;
   packageName?: string;
+  initialize?: (sourceFile: SourceFile) => void;
+  finalize?: (sourceFile: SourceFile) => void;
 }
 ```
 
@@ -303,7 +307,7 @@ $ yarn add @nodesecure/estree-ast-util
 ## Contributors ✨
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-18-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -335,6 +339,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/FredGuiou"><img src="https://avatars.githubusercontent.com/u/99122562?v=4?s=100" width="100px;" alt="FredGuiou"/><br /><sub><b>FredGuiou</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=FredGuiou" title="Documentation">📖</a> <a href="https://github.com/NodeSecure/js-x-ray/commits?author=FredGuiou" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/madina0801"><img src="https://avatars.githubusercontent.com/u/101329759?v=4?s=100" width="100px;" alt="Madina"/><br /><sub><b>Madina</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=madina0801" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/sairuss7"><img src="https://avatars.githubusercontent.com/u/87803528?v=4?s=100" width="100px;" alt="SairussDev"/><br /><sub><b>SairussDev</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=sairuss7" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/fless-lab"><img src="https://avatars.githubusercontent.com/u/71844440?v=4?s=100" width="100px;" alt="Abdou-Raouf ATARMLA"/><br /><sub><b>Abdou-Raouf ATARMLA</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=fless-lab" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package/index.js

@@ -8,6 +8,14 @@ function runASTAnalysis(
   str,
   options = Object.create(null)
 ) {
+  process.emitWarning(
+    'The runASTAnalysis API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.',
+    {
+      code: 'DeprecationWarning',
+      detail: 'The runASTAnalysis API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.'
+    }
+  );
+
   const {
     customParser = new JsSourceParser(),
     customProbes = [],
@@ -28,6 +36,14 @@ async function runASTAnalysisOnFile(
   pathToFile,
   options = {}
 ) {
+  process.emitWarning(
+    'The runASTAnalysisOnFile API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.',
+    {
+      code: 'DeprecationWarning',
+      detail: 'The runASTAnalysisOnFile API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.'
+    }
+  );
+
   const {
     customProbes = [],
     customParser = new JsSourceParser(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodesecure/js-x-ray",
-  "version": "7.1.1",
+  "version": "7.3.0",
   "description": "JavaScript AST XRay analysis",
   "type": "module",
   "exports": "./index.js",
@@ -56,10 +56,10 @@
   "devDependencies": {
     "@nodesecure/eslint-config": "^1.6.0",
     "@types/node": "^20.6.2",
-    "c8": "^9.0.0",
+    "c8": "^10.1.2",
     "cross-env": "^7.0.3",
     "eslint": "^9.0.0",
-    "glob": "^10.3.4",
+    "glob": "^11.0.0",
     "iterator-matcher": "^2.1.0",
     "pkg-ok": "^3.0.0"
   }

package/src/AstAnalyser.js

@@ -1,137 +1,207 @@
-// Import Node.js Dependencies
-import fs from "node:fs/promises";
-import path from "node:path";
-
-// Import Third-party Dependencies
-import { walk } from "estree-walker";
-import isMinified from "is-minified-code";
-
-// Import Internal Dependencies
-import { SourceFile } from "./SourceFile.js";
-import { isOneLineExpressionExport } from "./utils/index.js";
-import { JsSourceParser } from "./JsSourceParser.js";
-
-export class AstAnalyser {
-  /**
-   * @constructor
-   * @param {object} [options={}]
-   * @param {SourceParser} [options.customParser]
-   * @param {Array<object>} [options.customProbes]
-   * @param {boolean} [options.skipDefaultProbes=false]
-   */
-  constructor(options = {}) {
-    this.parser = options.customParser ?? new JsSourceParser();
-    this.probesOptions = {
-      customProbes: options.customProbes ?? [],
-      skipDefaultProbes: options.skipDefaultProbes ?? false
-    };
-  }
-
-  analyse(str, options = Object.create(null)) {
-    const {
-      isMinified = false,
-      module = true,
-      removeHTMLComments = false
-    } = options;
-
-    const body = this.parser.parse(this.prepareSource(str, { removeHTMLComments }), {
-      isEcmaScriptModule: Boolean(module)
-    });
-
-    const source = new SourceFile(str, this.probesOptions);
-
-    // we walk each AST Nodes, this is a purely synchronous I/O
-    walk(body, {
-      enter(node) {
-        // Skip the root of the AST.
-        if (Array.isArray(node)) {
-          return;
-        }
-
-        const action = source.walk(node);
-        if (action === "skip") {
-          this.skip();
-        }
-      }
-    });
-
-    return {
-      ...source.getResult(isMinified),
-      dependencies: source.dependencies,
-      isOneLineRequire: isOneLineExpressionExport(body)
-    };
-  }
-
-  async analyseFile(
-    pathToFile,
-    options = {}
-  ) {
-    try {
-      const {
-        packageName = null,
-        module = true,
-        removeHTMLComments = false
-      } = options;
-
-      const str = await fs.readFile(pathToFile, "utf-8");
-      const filePathString = pathToFile instanceof URL ? pathToFile.href : pathToFile;
-
-      const isMin = filePathString.includes(".min") || isMinified(str);
-      const data = this.analyse(str, {
-        isMinified: isMin,
-        module: path.extname(filePathString) === ".mjs" ? true : module,
-        removeHTMLComments
-      });
-
-      if (packageName !== null) {
-        data.dependencies.delete(packageName);
-      }
-
-      return {
-        ok: true,
-        dependencies: data.dependencies,
-        warnings: data.warnings,
-        isMinified: !data.isOneLineRequire && isMin
-      };
-    }
-    catch (error) {
-      return {
-        ok: false,
-        warnings: [
-          { kind: "parsing-error", value: error.message, location: [[0, 0], [0, 0]] }
-        ]
-      };
-    }
-  }
-
-  /**
-   * @param {!string} source
-   * @param {object} options
-   * @param {boolean} [options.removeHTMLComments=false]
-   */
-  prepareSource(source, options = {}) {
-    if (typeof source !== "string") {
-      throw new TypeError("source must be a string");
-    }
-    const { removeHTMLComments = false } = options;
-
-    /**
-     * if the file start with a shebang then we remove it because meriyah.parseScript fail to parse it.
-     * @example
-     * #!/usr/bin/env node
-     */
-    const rawNoShebang = source.startsWith("#") ?
-      source.slice(source.indexOf("\n") + 1) : source;
-
-    return removeHTMLComments ?
-      this.#removeHTMLComment(rawNoShebang) : rawNoShebang;
-  }
-
-  /**
-   * @param {!string} str
-   * @returns {string}
-   */
-  #removeHTMLComment(str) {
-    return str.replaceAll(/<!--[\s\S]*?(?:-->)/g, "");
-  }
-}
+// Import Node.js Dependencies
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+
+// Import Third-party Dependencies
+import { walk } from "estree-walker";
+import isMinified from "is-minified-code";
+
+// Import Internal Dependencies
+import { SourceFile } from "./SourceFile.js";
+import { isOneLineExpressionExport } from "./utils/index.js";
+import { JsSourceParser } from "./JsSourceParser.js";
+
+export class AstAnalyser {
+  /**
+   * @constructor
+   * @param {object} [options={}]
+   * @param {SourceParser} [options.customParser]
+   * @param {Array<object>} [options.customProbes]
+   * @param {boolean} [options.skipDefaultProbes=false]
+   */
+  constructor(options = {}) {
+    this.parser = options.customParser ?? new JsSourceParser();
+    this.probesOptions = {
+      customProbes: options.customProbes ?? [],
+      skipDefaultProbes: options.skipDefaultProbes ?? false
+    };
+  }
+
+  analyse(str, options = Object.create(null)) {
+    const {
+      isMinified = false,
+      module = true,
+      removeHTMLComments = false,
+      initialize,
+      finalize
+    } = options;
+
+    const body = this.parser.parse(this.prepareSource(str, { removeHTMLComments }), {
+      isEcmaScriptModule: Boolean(module)
+    });
+    const source = new SourceFile(str, this.probesOptions);
+
+    // TODO: this check should be factorized in a way that we reuse it
+    // on analyze and anlyseFile
+    if (initialize) {
+      if (typeof initialize !== "function") {
+        throw new TypeError("options.initialize must be a function");
+      }
+      initialize(source);
+    }
+
+    // we walk each AST Nodes, this is a purely synchronous I/O
+    walk(body, {
+      enter(node) {
+        // Skip the root of the AST.
+        if (Array.isArray(node)) {
+          return;
+        }
+
+        const action = source.walk(node);
+        if (action === "skip") {
+          this.skip();
+        }
+      }
+    });
+
+    // TODO: this check should be factorized in a way that we reuse it
+    // on analyze and anlyseFile
+    if (finalize) {
+      if (typeof finalize !== "function") {
+        throw new TypeError("options.finalize must be a function");
+      }
+      finalize(source);
+    }
+
+    return {
+      ...source.getResult(isMinified),
+      dependencies: source.dependencies,
+      isOneLineRequire: isOneLineExpressionExport(body)
+    };
+  }
+
+  async analyseFile(
+    pathToFile,
+    options = {}
+  ) {
+    try {
+      const {
+        packageName = null,
+        module = true,
+        removeHTMLComments = false,
+        initialize,
+        finalize
+      } = options;
+
+      const str = await fs.readFile(pathToFile, "utf-8");
+      const filePathString = pathToFile instanceof URL ? pathToFile.href : pathToFile;
+
+      const isMin = filePathString.includes(".min") || isMinified(str);
+      const data = this.analyse(str, {
+        isMinified: isMin,
+        module: path.extname(filePathString) === ".mjs" ? true : module,
+        removeHTMLComments,
+        initialize,
+        finalize
+      });
+
+      if (packageName !== null) {
+        data.dependencies.delete(packageName);
+      }
+
+      return {
+        ok: true,
+        dependencies: data.dependencies,
+        warnings: data.warnings,
+        isMinified: !data.isOneLineRequire && isMin
+      };
+    }
+    catch (error) {
+      return {
+        ok: false,
+        warnings: [
+          { kind: "parsing-error", value: error.message, location: [[0, 0], [0, 0]] }
+        ]
+      };
+    }
+  }
+
+  analyseFileSync(
+    pathToFile,
+    options = {}
+  ) {
+    try {
+      const {
+        packageName = null,
+        module = true,
+        removeHTMLComments = false,
+        initialize,
+        finalize
+      } = options;
+
+      const str = fsSync.readFileSync(pathToFile, "utf-8");
+      const filePathString = pathToFile instanceof URL ? pathToFile.href : pathToFile;
+
+      const isMin = filePathString.includes(".min") || isMinified(str);
+      const data = this.analyse(str, {
+        isMinified: isMin,
+        module: path.extname(filePathString) === ".mjs" ? true : module,
+        removeHTMLComments,
+        initialize,
+        finalize
+      });
+
+      if (packageName !== null) {
+        data.dependencies.delete(packageName);
+      }
+
+      return {
+        ok: true,
+        dependencies: data.dependencies,
+        warnings: data.warnings,
+        isMinified: !data.isOneLineRequire && isMin
+      };
+    }
+    catch (error) {
+      return {
+        ok: false,
+        warnings: [
+          { kind: "parsing-error", value: error.message, location: [[0, 0], [0, 0]] }
+        ]
+      };
+    }
+  }
+
+  /**
+   * @param {!string} source
+   * @param {object} options
+   * @param {boolean} [options.removeHTMLComments=false]
+   */
+  prepareSource(source, options = {}) {
+    if (typeof source !== "string") {
+      throw new TypeError("source must be a string");
+    }
+    const { removeHTMLComments = false } = options;
+
+    /**
+     * if the file start with a shebang then we remove it because meriyah.parseScript fail to parse it.
+     * @example
+     * #!/usr/bin/env node
+     */
+    const rawNoShebang = source.startsWith("#") ?
+      source.slice(source.indexOf("\n") + 1) : source;
+
+    return removeHTMLComments ?
+      this.#removeHTMLComment(rawNoShebang) : rawNoShebang;
+  }
+
+  /**
+   * @param {!string} str
+   * @returns {string}
+   */
+  #removeHTMLComment(str) {
+    return str.replaceAll(/<!--[\s\S]*?(?:-->)/g, "");
+  }
+}

package/src/EntryFilesAnalyser.js

@@ -1,99 +1,112 @@
-// Import Node.js Dependencies
-import fs from "node:fs/promises";
-import path from "node:path";
-
-// Import Internal Dependencies
-import { AstAnalyser } from "./AstAnalyser.js";
-
-const kDefaultExtensions = ["js", "cjs", "mjs", "node"];
-
-export class EntryFilesAnalyser {
-  /**
-   * @constructor
-   * @param {object} [options={}]
-   * @param {AstAnalyser} [options.astAnalyzer=new AstAnalyser()]
-   * @param {function} [options.loadExtensions]
-  */
-  constructor(options = {}) {
-    this.astAnalyzer = options.astAnalyzer ?? new AstAnalyser();
-    this.allowedExtensions = options.loadExtensions
-      ? options.loadExtensions(kDefaultExtensions)
-      : kDefaultExtensions;
-  }
-
-  /**
-   * Asynchronously analyze a set of entry files yielding analysis reports.
-   *
-   * @param {(string | URL)[]} entryFiles
-   * @yields {Object} - Yields an object containing the analysis report for each file.
-  */
-  async* analyse(entryFiles) {
-    this.analyzedDeps = new Set();
-
-    for (const file of entryFiles) {
-      yield* this.#analyzeFile(file);
-    }
-  }
-
-  async* #analyzeFile(file) {
-    const filePath = file instanceof URL ? file.pathname : file;
-    const report = await this.astAnalyzer.analyseFile(file);
-
-    yield { url: filePath, ...report };
-
-    if (!report.ok) {
-      return;
-    }
-
-    yield* this.#analyzeDeps(report.dependencies, path.dirname(filePath));
-  }
-
-  async* #analyzeDeps(deps, basePath) {
-    for (const [name] of deps) {
-      const depPath = await this.#getInternalDepPath(name, basePath);
-      if (depPath && !this.analyzedDeps.has(depPath)) {
-        this.analyzedDeps.add(depPath);
-
-        yield* this.#analyzeFile(depPath);
-      }
-    }
-  }
-
-  async #getInternalDepPath(name, basePath) {
-    const depPath = path.join(basePath, name);
-    const existingExt = path.extname(name);
-    if (existingExt !== "") {
-      if (!this.allowedExtensions.includes(existingExt.slice(1))) {
-        return null;
-      }
-
-      if (await this.#fileExists(depPath)) {
-        return depPath;
-      }
-    }
-
-    for (const ext of this.allowedExtensions) {
-      const depPathWithExt = `${depPath}.${ext}`;
-      if (await this.#fileExists(depPathWithExt)) {
-        return depPathWithExt;
-      }
-    }
-
-    return null;
-  }
-
-  async #fileExists(path) {
-    try {
-      await fs.access(path, fs.constants.F_OK);
-
-      return true;
-    }
-    catch (error) {
-      if (error.code !== "ENOENT") {
-        throw error;
-      }
-
-      return false;
-    }
-  }
-}
+// Import Node.js Dependencies
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Import Internal Dependencies
+import { AstAnalyser } from "./AstAnalyser.js";
+
+// CONSTANTS
+const kDefaultExtensions = ["js", "cjs", "mjs", "node"];
+
+export class EntryFilesAnalyser {
+  /**
+   * @constructor
+   * @param {object} [options={}]
+   * @param {AstAnalyser} [options.astAnalyzer=new AstAnalyser()]
+   * @param {function} [options.loadExtensions]
+  */
+  constructor(options = {}) {
+    this.astAnalyzer = options.astAnalyzer ?? new AstAnalyser();
+    const rawAllowedExtensions = options.loadExtensions
+      ? options.loadExtensions(kDefaultExtensions)
+      : kDefaultExtensions;
+
+    this.allowedExtensions = new Set(rawAllowedExtensions);
+  }
+
+  /**
+   * Asynchronously analyze a set of entry files yielding analysis reports.
+   *
+   * @param {(string | URL)[]} entryFiles
+   * @yields {Object} - Yields an object containing the analysis report for each file.
+  */
+  async* analyse(entryFiles) {
+    this.analyzedDeps = new Set();
+
+    for (const file of entryFiles) {
+      yield* this.#analyzeFile(file);
+    }
+  }
+
+  async* #analyzeFile(file) {
+    const filePath = file instanceof URL ? fileURLToPath(file) : file;
+    const report = await this.astAnalyzer.analyseFile(file);
+
+    yield { url: filePath, ...report };
+
+    if (!report.ok) {
+      return;
+    }
+
+    yield* this.#analyzeDeps(
+      report.dependencies,
+      path.dirname(filePath)
+    );
+  }
+
+  async* #analyzeDeps(deps, basePath) {
+    for (const [name] of deps) {
+      const depPath = await this.#getInternalDepPath(name, basePath);
+
+      if (depPath && !this.analyzedDeps.has(depPath)) {
+        this.analyzedDeps.add(depPath);
+
+        yield* this.#analyzeFile(depPath);
+      }
+    }
+  }
+
+  async #getInternalDepPath(name, basePath) {
+    const depPath = path.join(basePath, name);
+    const existingExt = path.extname(name);
+
+    if (existingExt === "") {
+      for (const ext of this.allowedExtensions) {
+        const depPathWithExt = `${depPath}.${ext}`;
+
+        const fileExist = await this.#fileExists(depPathWithExt);
+        if (fileExist) {
+          return depPathWithExt;
+        }
+      }
+    }
+    else {
+      if (!this.allowedExtensions.has(existingExt.slice(1))) {
+        return null;
+      }
+
+      const fileExist = await this.#fileExists(depPath);
+      if (fileExist) {
+        return depPath;
+      }
+    }
+
+    return null;
+  }
+
+  async #fileExists(path) {
+    try {
+      await fs.access(path, fs.constants.R_OK);
+
+      return true;
+    }
+    catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+
+      return false;
+    }
+  }
+}

package/src/utils/isOneLineExpressionExport.js

@@ -2,17 +2,23 @@
 import { exportAssignmentHasRequireLeave } from "./exportAssignmentHasRequireLeave.js";
 
 export function isOneLineExpressionExport(body) {
-  if (body.length > 1) {
+  if (body.length === 0 || body.length > 1) {
     return false;
   }
 
-  if (body[0].type !== "ExpressionStatement") {
+  const [firstNode] = body;
+  if (firstNode.type !== "ExpressionStatement") {
     return false;
   }
 
-  if (body[0].expression.type !== "AssignmentExpression") {
-    return false;
+  switch (firstNode.expression.type) {
+    // module.exports = require('...');
+    case "AssignmentExpression":
+      return exportAssignmentHasRequireLeave(firstNode.expression.right);
+    // require('...');
+    case "CallExpression":
+      return exportAssignmentHasRequireLeave(firstNode.expression);
+    default:
+      return false;
   }
-
-  return exportAssignmentHasRequireLeave(body[0].expression.right);
 }

package/types/api.d.ts

@@ -53,6 +53,8 @@ interface RuntimeOptions {
    * @default false
    */
   isMinified?: boolean;
+  initialize?: (sourceFile: SourceFile) => void;
+  finalize?: (sourceFile: SourceFile) => void;
 }
 
 interface RuntimeFileOptions extends Omit<RuntimeOptions, "isMinified"> {