@nodesecure/js-x-ray 7.1.0 → 7.2.0

package/README.md

@@ -67,11 +67,13 @@ require(Buffer.from("6673", "hex").toString());
 
 Then use `js-x-ray` to run an analysis of the JavaScript code:
 ```js
-import { runASTAnalysis } from "@nodesecure/js-x-ray";
+import { AstAnalyser } from "@nodesecure/js-x-ray";
 import { readFileSync } from "node:fs";
 
-const { warnings, dependencies } = runASTAnalysis(
-  readFileSync("./file.js", "utf-8")
+const scanner = new AstAnalyser();
+
+const { warnings, dependencies } = await scanner.analyseFile(
+  "./file.js"
 );
 
 console.log(dependencies);
@@ -174,11 +176,16 @@ You can pass an array of probes to the `runASTAnalysis/runASTAnalysisOnFile` fun
 Here using the example probe upper:
 
 ```ts
-import { runASTAnalysis } from "@nodesecure/js-x-ray";
+import { AstAnalyser } from "@nodesecure/js-x-ray";
 
 // add your customProbes here (see example above)
 
-const result = runASTAnalysis("const danger = 'danger';", { customProbes, skipDefaultProbes: true });
+const scanner = new AstAnalyser({
+  customProbes,
+  skipDefaultProbes: true
+});
+
+const result = scanner.analyse("const danger = 'danger';");
 
 console.log(result);
 ```
@@ -202,6 +209,12 @@ Congrats, you have created your first custom probe! 🎉
 > Check the types in [index.d.ts](index.d.ts) and [types/api.d.ts](types/api.d.ts) for more details about the `options`
 
 ## API
+
+- [AstAnalyser](./docs/api/AstAnalyser.md)
+- [EntryFilesAnalyser](./docs/api/EntryFilesAnalyser.md)
+
+Legacy APIs waiting to be deprecated;
+
 <details>
 <summary>runASTAnalysis(str: string, options?: RuntimeOptions & AstAnalyserOptions): Report</summary>
 
@@ -210,6 +223,8 @@ interface RuntimeOptions {
   module?: boolean;
   removeHTMLComments?: boolean;
   isMinified?: boolean;
+  initialize?: (sourceFile: SourceFile) => void;
+  finalize?: (sourceFile: SourceFile) => void;
 }
 ```
 
@@ -243,6 +258,8 @@ interface RuntimeFileOptions {
   module?: boolean;
   removeHTMLComments?: boolean;
   packageName?: string;
+  initialize?: (sourceFile: SourceFile) => void;
+  finalize?: (sourceFile: SourceFile) => void;
 }
 ```
 

package/index.d.ts

@@ -6,6 +6,7 @@ import {
   EntryFilesAnalyserOptions,
 
   SourceParser,
+  JsSourceParser,
   runASTAnalysis,
   runASTAnalysisOnFile,
   Report,
@@ -31,6 +32,7 @@ export {
   AstAnalyserOptions,
   EntryFilesAnalyser,
   EntryFilesAnalyserOptions,
+  JsSourceParser,
   SourceParser,
   runASTAnalysis,
   runASTAnalysisOnFile,

package/index.js

@@ -2,6 +2,7 @@
 import { warnings } from "./src/warnings.js";
 import { JsSourceParser } from "./src/JsSourceParser.js";
 import { AstAnalyser } from "./src/AstAnalyser.js";
+import { EntryFilesAnalyser } from "./src/EntryFilesAnalyser.js";
 
 function runASTAnalysis(
   str,
@@ -28,8 +29,8 @@ async function runASTAnalysisOnFile(
   options = {}
 ) {
   const {
-    customParser = new JsSourceParser(),
     customProbes = [],
+    customParser = new JsSourceParser(),
     skipDefaultProbes = false,
     ...opts
   } = options;
@@ -46,6 +47,8 @@ async function runASTAnalysisOnFile(
 export {
   warnings,
   AstAnalyser,
+  EntryFilesAnalyser,
+  JsSourceParser,
   runASTAnalysis,
   runASTAnalysisOnFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodesecure/js-x-ray",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "JavaScript AST XRay analysis",
   "type": "module",
   "exports": "./index.js",

package/src/AstAnalyser.js

@@ -31,15 +31,25 @@ export class AstAnalyser {
     const {
       isMinified = false,
       module = true,
-      removeHTMLComments = false
+      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) {
@@ -55,6 +65,15 @@ export class AstAnalyser {
       }
     });
 
+    // 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,
@@ -70,7 +89,9 @@ export class AstAnalyser {
       const {
         packageName = null,
         module = true,
-        removeHTMLComments = false
+        removeHTMLComments = false,
+        initialize,
+        finalize
       } = options;
 
       const str = await fs.readFile(pathToFile, "utf-8");
@@ -80,7 +101,9 @@ export class AstAnalyser {
       const data = this.analyse(str, {
         isMinified: isMin,
         module: path.extname(filePathString) === ".mjs" ? true : module,
-        removeHTMLComments
+        removeHTMLComments,
+        initialize,
+        finalize
       });
 
       if (packageName !== null) {

package/src/EntryFilesAnalyser.js

@@ -1,10 +1,12 @@
 // 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 {
@@ -16,9 +18,11 @@ export class EntryFilesAnalyser {
   */
   constructor(options = {}) {
     this.astAnalyzer = options.astAnalyzer ?? new AstAnalyser();
-    this.allowedExtensions = options.loadExtensions
+    const rawAllowedExtensions = options.loadExtensions
       ? options.loadExtensions(kDefaultExtensions)
       : kDefaultExtensions;
+
+    this.allowedExtensions = new Set(rawAllowedExtensions);
   }
 
   /**
@@ -36,7 +40,7 @@ export class EntryFilesAnalyser {
   }
 
   async* #analyzeFile(file) {
-    const filePath = file instanceof URL ? file.pathname : file;
+    const filePath = file instanceof URL ? fileURLToPath(file) : file;
     const report = await this.astAnalyzer.analyseFile(file);
 
     yield { url: filePath, ...report };
@@ -45,12 +49,16 @@ export class EntryFilesAnalyser {
       return;
     }
 
-    yield* this.#analyzeDeps(report.dependencies, path.dirname(filePath));
+    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);
 
@@ -62,20 +70,25 @@ export class EntryFilesAnalyser {
   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;
+    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;
+      }
 
-    for (const ext of this.allowedExtensions) {
-      const depPathWithExt = `${depPath}.${ext}`;
-      if (await this.#fileExists(depPathWithExt)) {
-        return depPathWithExt;
+      const fileExist = await this.#fileExists(depPath);
+      if (fileExist) {
+        return depPath;
       }
     }
 
@@ -84,7 +97,7 @@ export class EntryFilesAnalyser {
 
   async #fileExists(path) {
     try {
-      await fs.access(path, fs.constants.F_OK);
+      await fs.access(path, fs.constants.R_OK);
 
       return true;
     }

package/types/api.d.ts

@@ -4,8 +4,11 @@ import { Statement } from "meriyah/dist/src/estree.js";
 export {
   AstAnalyser,
   AstAnalyserOptions,
+
   EntryFilesAnalyser,
   EntryFilesAnalyserOptions,
+
+  JsSourceParser,
   SourceParser,
   runASTAnalysis,
   runASTAnalysisOnFile,
@@ -50,6 +53,8 @@ interface RuntimeOptions {
    * @default false
    */
   isMinified?: boolean;
+  initialize?: (sourceFile: SourceFile) => void;
+  finalize?: (sourceFile: SourceFile) => void;
 }
 
 interface RuntimeFileOptions extends Omit<RuntimeOptions, "isMinified"> {
@@ -101,7 +106,7 @@ interface SourceParser {
 declare class AstAnalyser {
   constructor(options?: AstAnalyserOptions);
   analyse: (str: string, options?: RuntimeOptions) => Report;
-  analyzeFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
+  analyseFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
 }
 
 interface EntryFilesAnalyserOptions {
@@ -118,5 +123,7 @@ declare class EntryFilesAnalyser {
   analyse(entryFiles: (string | URL)[]): AsyncGenerator<ReportOnFile & { url: string }>;
 }
 
+declare class JsSourceParser implements SourceParser {}
+
 declare function runASTAnalysis(str: string, options?: RuntimeOptions & AstAnalyserOptions): Report;
 declare function runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions & AstAnalyserOptions): Promise<ReportOnFile>;