refactor: implement API exports & minimal docs (#264)

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>
 

docs/api/AstAnalyser.md

@@ -0,0 +1,66 @@
+# AstAnalyser
+
+```js
+import { AstAnalyser } from "@nodesecure/js-x-ray";
+import { TsSourceParser } from "@nodesecure/ts-source-parser";
+
+const scanner = new AstAnalyser({
+  customParser: new TsSourceParser()
+});
+
+const result = scanner.analyse("const x: number = 5;");
+console.log(result);
+```
+
+AstAnalyser options is described by the following TS interface:
+
+```ts
+interface AstAnalyserOptions {
+  /**
+   * @default JsSourceParser
+   */
+  customParser?: SourceParser;
+  /**
+   * @default []
+   */
+  customProbes?: Probe[];
+  /**
+   * @default false
+   */
+  skipDefaultProbes?: boolean;
+}
+```
+
+By default the AstAnalyser class is capable of parsing JavaScript source code using Meriyah.
+
+## API
+
+```ts
+declare class AstAnalyser {
+  constructor(options?: AstAnalyserOptions);
+  analyse: (str: string, options?: RuntimeOptions) => Report;
+  analyseFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
+}
+```
+
+The `analyseFile` method is a superset of `analyse` with the ability to read the file on the local filesystem with additional features like detecting if the file is ESM or CJS.
+
+```ts
+interface Report {
+  dependencies: Map<string, Dependency>;
+  warnings: Warning[];
+  idsLengthAvg: number;
+  stringScore: number;
+  isOneLineRequire: boolean;
+}
+
+type ReportOnFile = {
+  ok: true,
+  warnings: Warning[];
+  dependencies: Map<string, Dependency>;
+  isMinified: boolean;
+} | {
+  ok: false,
+  warnings: Warning[];
+}
+```

docs/api/EntryFilesAnalyser.md

@@ -0,0 +1,38 @@
+# EntryFilesAnalyser
+
+```js
+import { EntryFilesAnalyser } from "@nodesecure/js-x-ray";
+
+const efa = new EntryFilesAnalyser();
+
+// Either a string path or a WHAWG URL
+const entryFiles = [
+  "./path/to/file.js"
+];
+
+for await (const report of efa.analyse(entryFiles)) {
+  console.log(report);
+}
+```
+
+The constructor options is described by the following TS interface
+
+```ts
+interface EntryFilesAnalyserOptions {
+  astAnalyzer?: AstAnalyser;
+  loadExtensions?: (defaults: string[]) => string[];
+}
+```
+
+Default files extensions are `.js`, `.cjs`, `.mjs` and `.node`
+
+## API
+
+```ts
+declare class EntryFilesAnalyser {
+  constructor(options?: EntryFilesAnalyserOptions);
+  analyse(entryFiles: (string | URL)[]): AsyncGenerator<ReportOnFile & { url: string }>;
+}
+```
+
+For more informations about `Report` and `ReportOnFile` interfaces please see [AstAnalyser documentation](./AstAnalyser.md)

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,

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
 };

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,
@@ -101,7 +104,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 +121,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>;