feat: allow running programmatically (#54)

Author: mihkeleidast

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.18.2]
+        node-version: [16.17.0]
 
     steps:
       - name: Checkout

.nvmrc

@@ -1 +1 @@
-v14.16.1
+v16.17.0

README.md

@@ -44,7 +44,7 @@ Running `react-scanner` on it will create the following JSON report:
 
 <details>
   <summary>Click to see it</summary>
-  
+
 ```json
 {
   "BasisProvider": {
@@ -157,6 +157,7 @@ Running `react-scanner` on it will create the following JSON report:
   }
 }
 ```
+
 </details>
 
 This raw JSON report is used then to generate something that is useful to you. For example, you might want to know:
@@ -179,7 +180,7 @@ npm install --save-dev react-scanner
 npx react-scanner -c /path/to/react-scanner.config.js
 ```
 
-## Config file
+### Config file
 
 Everything that `react-scanner` does is controlled by a config file.
 
@@ -220,10 +221,23 @@ Running `react-scanner` with this config would output something like this to the
 }
 ```
 
+### Running programmatically
+
+It is also possible to run the scanner programmatically. In this case, the config options should be passed directly to the `run` function.
+
+```js
+import scanner from "react-scanner";
+
+const output = await scanner.run(config);
+```
+
+## Config options
+
 Here are all the available config options:
 
 | Option                 | Type              | Description                                                                                                                                                                                                                                                                                                                                          |
 | ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootDir`              | string            | The path to the root directory of your project. <br>If using a config file, this defaults to the config directory.                                                                                                                                                                                                                                   |
 | `crawlFrom`            | string            | The path of the directory to start crawling from.<br>Absolute or relative to the config file location.                                                                                                                                                                                                                                               |
 | `exclude`              | array or function | Each array item should be a string or a regex. When crawling, if directory name matches exactly the string item or matches the regex item, it will be excluded from crawling.<br>For more complex scenarios, `exclude` can be a a function that accepts a directory name and should return `true` if the directory should be excluded from crawling. |
 | `globs`                | array             | Only files matching these globs will be scanned. See [here](https://github.com/micromatch/picomatch#globbing-features) for glob syntax.<br>Default: `["**/!(*.test\|*.spec).@(js\|ts)?(x)"]`                                                                                                                                                         |
@@ -258,9 +272,9 @@ processors: [
 
 All the built-in processors support the following options:
 
-| Option     | Type   | Description                                                                                                                                 |
-| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `outputTo` | string | Where to output the result.<br>Absolute or relative to the config file location.<br>When omitted, the result is printed out to the console. |
+| Option     | Type   | Description                                                                                                                           |
+| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `outputTo` | string | Where to output the result.<br>Absolute or relative to the root directory.<br>When omitted, the result is printed out to the console. |
 
 Here are the built-in processors that `react-scanner` comes with:
 

package.json

@@ -3,6 +3,7 @@
   "version": "1.0.4",
   "description": "Extract React components and props usage from code.",
   "bin": "bin/react-scanner",
+  "main": "src/scanner.js",
   "scripts": {
     "prepare": "husky install",
     "build": "node scripts/processors.js",

src/index.js

@@ -1,9 +1,6 @@
-const startTime = process.hrtime.bigint();
-
 const path = require("path");
 const sade = require("sade");
-const { validateConfig } = require("./utils");
-const run = require("./run");
+const { run } = require("./scanner");
 const packageJson = require("../package.json");
 
 sade("react-scanner", true)
@@ -15,23 +12,6 @@ sade("react-scanner", true)
     const configPath = path.resolve(process.cwd(), options.config);
     const configDir = path.dirname(configPath);
     const config = require(configPath);
-    const { crawlFrom, errors } = validateConfig(config, configDir);
-
-    if (errors.length === 0) {
-      run({
-        config,
-        configDir,
-        crawlFrom,
-        startTime,
-      });
-    } else {
-      console.error(`Config errors:`);
-
-      errors.forEach((error) => {
-        console.error(`- ${error}`);
-      });
-
-      process.exit(1);
-    }
+    run(config, configDir, "cli");
   })
   .parse(process.argv);

src/run.js

@@ -13,7 +13,14 @@ const {
 const DEFAULT_GLOBS = ["**/!(*.test|*.spec).@(js|ts)?(x)"];
 const DEFAULT_PROCESSORS = ["count-components-and-props"];
 
-async function run({ config, configDir, crawlFrom, startTime }) {
+async function run({
+  config,
+  configDir,
+  crawlFrom,
+  startTime,
+  method = "cli",
+}) {
+  const rootDir = config.rootDir || configDir;
   const globs = config.globs || DEFAULT_GLOBS;
   const files = new fdir()
     .glob(...globs)
@@ -66,19 +73,28 @@ async function run({ config, configDir, crawlFrom, startTime }) {
       ? config.processors
       : DEFAULT_PROCESSORS;
   const prevResults = [];
-  const output = (data, destination = "stdout") => {
+  const output = (data, destination) => {
+    const defaultDestination = method === "cli" ? "stdout" : "return";
+    const dest = destination || defaultDestination;
     const dataStr = isPlainObject(data)
       ? JSON.stringify(data, null, 2)
       : String(data);
 
-    if (destination === "stdout") {
-      // eslint-disable-next-line no-console
-      console.log(dataStr);
-    } else {
-      const filePath = path.resolve(configDir, destination);
-
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, dataStr);
+    switch (dest) {
+      case "stdout": {
+        // eslint-disable-next-line no-console
+        console.log(dataStr);
+        break;
+      }
+      case "return": {
+        break;
+      }
+      default: {
+        const filePath = path.resolve(rootDir, destination);
+
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, dataStr);
+      }
     }
   };
 
@@ -104,6 +120,8 @@ async function run({ config, configDir, crawlFrom, startTime }) {
 
     prevResults.push(result);
   }
+
+  return prevResults[prevResults.length - 1];
 }
 
 module.exports = run;

src/scanner.js

@@ -0,0 +1,30 @@
+const startTime = process.hrtime.bigint();
+
+const { validateConfig } = require("./utils");
+const runScan = require("./run");
+
+const scanner = {
+  run: async function run(config, configDir, method = "programmatic") {
+    const { crawlFrom, errors } = validateConfig(config, configDir);
+
+    if (errors.length === 0) {
+      return await runScan({
+        config,
+        configDir,
+        crawlFrom,
+        startTime,
+        method: method,
+      });
+    } else {
+      console.error(`Config errors:`);
+
+      errors.forEach((error) => {
+        console.error(`- ${error}`);
+      });
+
+      process.exit(1);
+    }
+  },
+};
+
+module.exports = scanner;

src/scanner.test.js

@@ -0,0 +1,84 @@
+const path = require("path");
+const { suite } = require("uvu");
+const assert = require("uvu/assert");
+
+const scanner = require("./scanner");
+
+const Scanner = suite("Scanner");
+
+Scanner("no processors", async () => {
+  const output = await scanner.run({
+    crawlFrom: "code",
+    rootDir: path.resolve("./test"),
+  });
+
+  assert.snapshot(
+    JSON.stringify(output, undefined, 2),
+    JSON.stringify(
+      {
+        Text: {
+          instances: 2,
+          props: {
+            margin: 1,
+            textStyle: 1,
+          },
+        },
+        App: {
+          instances: 1,
+          props: {},
+        },
+        BasisProvider: {
+          instances: 1,
+          props: {
+            theme: 1,
+          },
+        },
+        Home: {
+          instances: 1,
+          props: {},
+        },
+        Link: {
+          instances: 1,
+          props: {
+            href: 1,
+            newTab: 1,
+          },
+        },
+        div: {
+          instances: 1,
+          props: {
+            style: 1,
+          },
+        },
+      },
+      null,
+      2
+    )
+  );
+});
+
+Scanner("single processor", async () => {
+  const output = await scanner.run({
+    crawlFrom: "code",
+    rootDir: path.resolve("./test"),
+    processors: ["count-components"],
+  });
+
+  assert.snapshot(
+    JSON.stringify(output, undefined, 2),
+    JSON.stringify(
+      {
+        Text: 2,
+        App: 1,
+        BasisProvider: 1,
+        Home: 1,
+        Link: 1,
+        div: 1,
+      },
+      null,
+      2
+    )
+  );
+});
+
+Scanner.run();

src/utils.js

@@ -17,7 +17,10 @@ function validateConfig(config, configDir) {
   } else if (typeof config.crawlFrom !== "string") {
     result.errors.push(`crawlFrom should be a string`);
   } else {
-    const crawlFrom = path.resolve(configDir, config.crawlFrom);
+    const crawlFrom = path.resolve(
+      config.rootDir || configDir,
+      config.crawlFrom
+    );
 
     if (fs.existsSync(crawlFrom)) {
       result.crawlFrom = crawlFrom;