Add docs to plugin (#33)

* source bugfix * docs * CLI README
noodle-graph · Mar 9, 2023 · 6f69b4e · 6f69b4e
1 parent e124e6f
commit 6f69b4e
Show file tree

Hide file tree

Showing 16 changed files with 100 additions and 61 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -9,6 +9,8 @@ If you have any question, feel free to [reach out](https://github.com/dormeiri).
 - [Useful commands](#useful-commands)
   - [Common](#common)
   - [Generating a new package](#generating-a-new-package)
+- [Plugins](#plugins)
+  - [Plugin Lifecycle](#plugin-lifecycle)
 - [Testing packages locally](#testing-packages-locally)
   - [With link](#with-link)
   - [With local registry](#with-local-registry)
@@ -78,6 +80,18 @@ _Read more about [running tasks with Nx](https://nx.dev/core-features/run-tasks)
 npm run generate:package <project name>
 ```
 
+## Plugins
+
+To add a plugin, you just need to implement the [NoodlePlugin](https://github.com/noodle-graph/monorepo/blob/master/packages/types/src/index.ts#L1) interface.
+
+Check [Type Evaluator Plugin](https://github.com/noodle-graph/monorepo/blob/master/packages/plugin-type-evaluator/src/index.ts) for example.
+
+For contributing a new plugin to the ecosystem, feel free to add it to this repository by [generating a new package](#generating-a-new-package).
+
+### Plugin Lifecycle
+
+For now there is only one phase in the lifecycle, which is `enrich`. That happens after the scan is finished and you have a list of resources with relationships.
+
 ## Testing packages locally
 
 ### With link

diff --git a/README.md b/README.md
@@ -20,9 +20,10 @@ Additionally, Noodle is reliant on the best source of truth, which is the code i
   - [4. `noodle run --open`](#4-noodle-run---open)
 - [Commands](#commands)
   - [`run`](#run)
-    - [Parameters](#parameters)
+    - [Options](#options)
   - [Scan config file](#scan-config-file)
     - [Resource object](#resource-object)
+- [Plugins](#plugins)
 - [Contributing](#contributing)
 
 ## Quick start
@@ -53,11 +54,11 @@ noodle run
 
 Using the [scanner](https://github.com/noodle-graph/monorepo/tree/master/packages/scanner) to search resources relationships and bundles a UI with the results.
 
-#### Parameters
+#### Options
 
-| Command Argument | Environment Variable | Default | Description |
+| Option | Environment Variable | Default | Description |
 |-|-|-|-|
-| `--config`, `-c` | `NOODLE_CONFIG` | `./noodle.json` | Path to the scan configuration file. |
+| `--config`, `-c` | `NOODLE_CONFIG` | `./noodle.json` | Path to the [scan configuration file](#scan-config-file). |
 | `--output`, `-o` | `NOODLE_OUTPUT` | `./noodleScanOutput` | Path to the UI bundle output folder. |
 | `--githubToken` | `NOODLE_GITHUB_TOKEN` | `null` | GitHub access token. Required for GitHub resources. |
 | `--open` | - | `false` | Whether to open in the browser the bundled UI when finished. |
@@ -70,6 +71,7 @@ You can find example of a config file in the [basic example](https://github.com/
 
 | Field | Required | Description |
 |-|-|-|
+| `plugins` | No | List of plugin import names. See [`examples/basic/noodleWithPlugin.json`](https://github.com/noodle-graph/monorepo/blob/master/examples/basic/noodleWithPlugin.json) |
 | `resources` | Yes | List of [resources objects](#resource-object) to scan or declare. |
 
 #### Resource object
@@ -82,7 +84,16 @@ You can find example of a config file in the [basic example](https://github.com/
 | `type` | See [UI icons](https://github.com/noodle-graph/monorepo/tree/master/packages/ui/public/img) | No | `null` | The type of the resource is deployed on |
 | `tags` | a-z, number, forward slash, underscore, dash. RegEx: `[a-z\d-_/]+` | No | `[]` | Tags of the resource. For the UI view and filtering. |
 | `url` | `null` if `source` is `config`, otherwise a valid URL. | Yes, except if `source` is `config`. | `null` | The URL of the source to scan. |
-| `source` | `github`, `local`, `config` | No | `github` if `url` starts with `https://github.com`, `config` if `url` is `null`, otherwise `local`. | The type of the source to scan. `config` sources won't get scanned. |
+| `source` | `github`, `local`, `config` | No | `github` if `url` starts with `https://`, `config` if `url` is `null`, otherwise `local`. | The type of the source to scan. `config` sources won't get scanned. |
+| `relationships` | [Relationship](https://github.com/noodle-graph/monorepo/blob/master/packages/scanner/README.md#relationship-object) array | No | `null` | List of relationship to added regardless of scanning. |
+
+## Plugins
+
+You can enrich the resource object in the output with plugins.
+
+See [`examples/basic/noodleWithPlugin.json`](https://github.com/noodle-graph/monorepo/blob/master/examples/basic/noodleWithPlugin.json) for example.
+
+For implementing a plugin, see the [CONTRIBUTING.md](https://github.com/noodle-graph/monorepo/blob/master/CONTRIBUTING.md#plugins) file.
 
 ## Contributing
 

diff --git a/docs/ecosystem.md b/docs/ecosystem.md
@@ -2,6 +2,8 @@
 
 ## Components
 
-* [cli](../packages/cli)
-* [scanner](../packages/scanner)
-* [ui](../packages/ui)
+* [CLI](https://github.com/noodle-graph/monorepo/tree/master/packages/cli)
+* [Scanner](https://github.com/noodle-graph/monorepo/tree/master/packages/scanner)
+* [UI](https://github.com/noodle-graph/monorepo/tree/master/packages/ui)
+* [Type evaluator plugin](https://github.com/noodle-graph/monorepo/tree/master/packages/plugin-type-evaluator)
+* [Type Google search plugin](https://github.com/noodle-graph/monorepo/tree/master/packages/plugin-type-google)
diff --git a/examples/basic/anotherService/index.js b/examples/basic/anotherService/index.js
@@ -1,4 +1,4 @@
-// noodle --> some-db (feature2)
+// noodle --> some-rds-db (feature2)
 // noodle --> some-undeclared-service
 // noodle --some label-- some-undeclared-service (feature3)
 // noodle <-- some-undeclared-service

diff --git a/examples/basic/noodle.json b/examples/basic/noodle.json
@@ -17,7 +17,7 @@
             "source": "local"
         },
         {
-            "id": "some-db",
+            "id": "some-rds-db",
             "name": "Some DB",
             "tags": ["db"],
             "type": "aws/aurora"

diff --git a/examples/basic/noodleGitHub.json b/examples/basic/noodleGitHub.json
@@ -21,7 +21,7 @@
             "include": "examples/basic/anotherService/.*\\.(js|py)$"
         },
         {
-            "id": "some-db",
+            "id": "some-rds-db",
             "name": "Some DB",
             "tags": ["feature1", "feature2", "db"],
             "type": "aws/aurora"

diff --git a/examples/basic/noodleInclude.json b/examples/basic/noodleInclude.json
@@ -17,7 +17,7 @@
             "include": "anotherService/.*\\.js"
         },
         {
-            "id": "some-db",
+            "id": "some-rds-db",
             "name": "Some DB",
             "tags": ["feature1", "feature2", "db"],
             "type": "aws/aurora"

diff --git a/examples/basic/noodleOnlyPython.json b/examples/basic/noodleOnlyPython.json
@@ -16,7 +16,7 @@
             "type": "aws/ecs"
         },
         {
-            "id": "some-db",
+            "id": "some-rds-db",
             "name": "Some DB",
             "tags": ["feature1", "feature2", "db"],
             "type": "aws/aurora"

diff --git a/examples/basic/noodleWithPlugin.json b/examples/basic/noodleWithPlugin.json
@@ -1,29 +1,27 @@
 {
     "plugins": [
-        "@noodle-graph/plugin-type-google"
+        "@noodle-graph/plugin-type-evaluator",
+        "../../../packages/plugin-type-google/dist"
     ],
     "resources": [
         {
             "id": "some-service",
             "url": "./someService",
             "name": "Some Service",
             "tags": ["feature1"],
-            "type": "aws/ecs",
-            "source": "local"
+            "type": "aws/ecs"
         },
         {
             "id": "another-service",
             "url": "./anotherService",
             "name": "Another Service",
             "tags": ["feature1", "service"],
-            "type": "aws/ecs",
-            "source": "local"
+            "type": "aws/ecs"
         },
         {
-            "id": "some-db",
+            "id": "some-rds-db",
             "name": "Some DB",
-            "tags": ["db"],
-            "type": "aws/aurora"
+            "tags": ["db"]
         }
     ]
 }
diff --git a/package.json b/package.json
@@ -1,5 +1,5 @@
 {
-    "name": "nodejs-packages",
+    "name": "monorepo",
     "version": "0.0.0",
     "scripts": {
         "postinstall": "husky install && nx run-many --target=install",
@@ -11,29 +11,28 @@
     },
     "private": true,
     "devDependencies": {
-        "@nrwl/devkit": "^15.1.1",
-        "@types/jest": "29.4.0",
-        "@types/prettier": "2.7.2",
-        "@typescript-eslint/eslint-plugin": "5.52.0",
-        "@typescript-eslint/parser": "5.52.0",
-        "eslint": "8.34.0",
-        "eslint-config-prettier": "8.6.0",
-        "eslint-config-standard-with-typescript": "34.0.0",
-        "eslint-plugin-import": "2.27.5",
-        "eslint-plugin-json": "3.1.0",
-        "eslint-plugin-n": "15.6.1",
-        "eslint-plugin-node": "11.1.0",
-        "eslint-plugin-prettier": "4.2.1",
-        "eslint-plugin-promise": "6.1.1",
-        "husky": "8.0.3",
-        "jest": "29.4.3",
-        "nx": "15.7.0",
-        "prettier": "2.8.4",
-        "ts-jest": "29.0.5",
-        "typescript": "4.9.5",
-        "verdaccio": "5.21.1"
-    },
-    "dependencies": {
-        "@noodle-graph/cli": "^0.0.15"
+        "@noodle-graph/cli": "^0.0.15",
+        "@noodle-graph/plugin-type-evaluator": "^0.0.1",
+        "@nrwl/devkit": "15.1.1",
+        "@types/jest": "^29.4.0",
+        "@types/prettier": "^2.7.2",
+        "@typescript-eslint/eslint-plugin": "^5.52.0",
+        "@typescript-eslint/parser": "^5.52.0",
+        "eslint": "^8.34.0",
+        "eslint-config-prettier": "^8.6.0",
+        "eslint-config-standard-with-typescript": "^34.0.0",
+        "eslint-plugin-import": "^2.27.5",
+        "eslint-plugin-json": "^3.1.0",
+        "eslint-plugin-n": "^15.6.1",
+        "eslint-plugin-node": "^11.1.0",
+        "eslint-plugin-prettier": "^4.2.1",
+        "eslint-plugin-promise": "^6.1.1",
+        "husky": "^8.0.3",
+        "jest": "^29.4.3",
+        "nx": "^15.7.0",
+        "prettier": "^2.8.4",
+        "ts-jest": "^29.0.5",
+        "typescript": "^4.9.5",
+        "verdaccio": "^5.21.1"
     }
 }
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -20,9 +20,10 @@ Additionally, Noodle is reliant on the best source of truth, which is the code i
   - [4. `noodle run --open`](#4-noodle-run---open)
 - [Commands](#commands)
   - [`run`](#run)
-    - [Parameters](#parameters)
+    - [Options](#options)
   - [Scan config file](#scan-config-file)
     - [Resource object](#resource-object)
+- [Plugins](#plugins)
 - [Contributing](#contributing)
 
 ## Quick start
@@ -53,11 +54,11 @@ noodle run
 
 Using the [scanner](https://github.com/noodle-graph/monorepo/tree/master/packages/scanner) to search resources relationships and bundles a UI with the results.
 
-#### Parameters
+#### Options
 
-| Command Argument | Environment Variable | Default | Description |
+| Option | Environment Variable | Default | Description |
 |-|-|-|-|
-| `--config`, `-c` | `NOODLE_CONFIG` | `./noodle.json` | Path to the scan configuration file. |
+| `--config`, `-c` | `NOODLE_CONFIG` | `./noodle.json` | Path to the [scan configuration file](#scan-config-file). |
 | `--output`, `-o` | `NOODLE_OUTPUT` | `./noodleScanOutput` | Path to the UI bundle output folder. |
 | `--githubToken` | `NOODLE_GITHUB_TOKEN` | `null` | GitHub access token. Required for GitHub resources. |
 | `--open` | - | `false` | Whether to open in the browser the bundled UI when finished. |
@@ -70,6 +71,7 @@ You can find example of a config file in the [basic example](https://github.com/
 
 | Field | Required | Description |
 |-|-|-|
+| `plugins` | No | List of plugin import names. See [`examples/basic/noodleWithPlugin.json`](https://github.com/noodle-graph/monorepo/blob/master/examples/basic/noodleWithPlugin.json) |
 | `resources` | Yes | List of [resources objects](#resource-object) to scan or declare. |
 
 #### Resource object
@@ -82,9 +84,16 @@ You can find example of a config file in the [basic example](https://github.com/
 | `type` | See [UI icons](https://github.com/noodle-graph/monorepo/tree/master/packages/ui/public/img) | No | `null` | The type of the resource is deployed on |
 | `tags` | a-z, number, forward slash, underscore, dash. RegEx: `[a-z\d-_/]+` | No | `[]` | Tags of the resource. For the UI view and filtering. |
 | `url` | `null` if `source` is `config`, otherwise a valid URL. | Yes, except if `source` is `config`. | `null` | The URL of the source to scan. |
-| `source` | `github`, `local`, `config` | No | `github` if `url` starts with `https://github.com`, `config` if `url` is `null`, otherwise `local`. | The type of the source to scan. `config` sources won't get scanned. |
-| `include` | Any RegEx | No | `/(.ts|.tsx|.js|.jsx|.java|.py|.go|.tf)$/` | RegEx for matching which files to scan. |
-| `relationships` | Array of [relationships](https://github.com/noodle-graph/monorepo/blob/master/packages/scanner/README.md#relationship-object) | No | `[]` | For declaring relationships that are not in the code. Useful for third-parties relationships. |
+| `source` | `github`, `local`, `config` | No | `github` if `url` starts with `https://`, `config` if `url` is `null`, otherwise `local`. | The type of the source to scan. `config` sources won't get scanned. |
+| `relationships` | [Relationship](https://github.com/noodle-graph/monorepo/blob/master/packages/scanner/README.md#relationship-object) array | No | `null` | List of relationship to added regardless of scanning. |
+
+## Plugins
+
+You can enrich the resource object in the output with plugins.
+
+See [`examples/basic/noodleWithPlugin.json`](https://github.com/noodle-graph/monorepo/blob/master/examples/basic/noodleWithPlugin.json) for example.
+
+For implementing a plugin, see the [CONTRIBUTING.md](https://github.com/noodle-graph/monorepo/blob/master/CONTRIBUTING.md#plugins) file.
 
 ## Contributing
 

diff --git a/packages/plugin-type-evaluator/README.md b/packages/plugin-type-evaluator/README.md
@@ -1 +1,3 @@
-# plugin-type-evaluator
+# Type Evaluator Plugin for Noodle
+
+The plugin set the type of resources with no types based on some evaluation login.
diff --git a/packages/plugin-type-evaluator/package.json b/packages/plugin-type-evaluator/package.json
@@ -2,7 +2,7 @@
     "name": "@noodle-graph/plugin-type-evaluator",
     "version": "0.0.0",
     "scripts": {
-        "build": "tsc --project tsconfig.lib.json && cp package.json dist",
+        "build": "tsc --project tsconfig.lib.json && cp package.json dist && cp README.md dist",
         "lint": "eslint .",
         "test": "jest"
     },

diff --git a/packages/plugin-type-google/README.md b/packages/plugin-type-google/README.md
@@ -1,2 +1,3 @@
-# plugin-type-google
+# Search the type in Google (plugin for Noodle)
 
+This plugin adds to the `additionalLinks` a URL for searching the type in Google.
diff --git a/packages/scanner/README.md b/packages/scanner/README.md
@@ -62,7 +62,8 @@ Here is a sample of scan output:
           "from":false,
           "to":true
         }
-      ]
+      ],
+      "additionalLinks": []
     },
     {
       "id":"another-service",
@@ -85,7 +86,8 @@ Here is a sample of scan output:
           "from":false,
           "to":true
         }
-      ]
+      ],
+      "additionalLinks": []
     },
     {
       "id":"some-db",
@@ -95,7 +97,8 @@ Here is a sample of scan output:
         "feature2",
         "service"
       ],
-      "type":"aws/aurora"
+      "type":"aws/aurora",
+      "additionalLinks": []
     }
   ]
 }

diff --git a/packages/scanner/src/scanner.ts b/packages/scanner/src/scanner.ts
@@ -49,10 +49,10 @@ export class Scanner {
     private async scanResource(resource: Resource): Promise<Resource> {
         const resourceCopy = {
             ...resource,
-            source: inferSource(resource),
+            source: resource.source ?? inferSource(resource),
         };
 
-        if (resourceCopy.source === 'config') return resource;
+        if (resourceCopy.source === 'config') return resourceCopy;
 
         this.context.logger?.debug({ id: resourceCopy.id, url: resourceCopy.url, source: resourceCopy.source }, 'Scanning resource...');