Skip to content

Commit

Permalink
Fix and improve docs (#18)
Browse files Browse the repository at this point in the history
* Fix an improve docs

* Fix an improve docs

* Fix an improve docs
  • Loading branch information
dormeiri authored Mar 3, 2023
1 parent b634e17 commit 873ba6a
Show file tree
Hide file tree
Showing 11 changed files with 125 additions and 116 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/npm-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ name: Node.js Package

on:
release:
types: [created]
types: [ created ]

jobs:
publish-npm:
Expand Down
78 changes: 46 additions & 32 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

First, thanks for considering contributing to the project! 🤩

If you have any question, feel free to [reach out](https://github.com/dormeiri).

- [Setup locally](#setup-locally)
- [Useful commands](#useful-commands)
- [Common](#common)
Expand All @@ -22,6 +24,41 @@ First, thanks for considering contributing to the project! 🤩
npm install
```

Make sure you can have the environment variables for running [automated tests](#automated-tests).

To validate the setup, run the following commands:

1. `nx run-many --target=test`
2. `nx run-many --target=lint`
3. `nx run-many --target=build`

## Automated tests

Where available, you can run only unit tests with:

```bash
nx test:unit <project name>
```

And only integration tests with:

```bash
nx test:integration <project name>
```

The integration tests need the following environment variables:

- `NOODLE_GITHUB_TOKEN` -- Some GitHub token for cloning this repo when scanning.

_NOTE:_ Code that requires integration should be separated from code that doesn't.
That will help keeping the separation in tests as well.

All projects have a `test` command that tests both unit and integration:

```bash
nx test <project name>
```

## Useful commands

### Common
Expand Down Expand Up @@ -97,33 +134,33 @@ yarn add @noodle-graph/<package name>@local --registry=http://localhost:4873
nx build:global cli
```

That will build and install the CLI globally on your local machine. Then you can run the CLI, for example:

```bash
noodle run
```
That will build and install the CLI globally on your local machine. Then you can run the CLI.

Be aware that this will also `npm link @noodle-graph/scanner` the global CLI module. To avoid that, you can do:

```bash
nx build cli
cd dist
cd packages/cli/dist
npm i -g .
```

#### Using link in the global CLI installation

You can also `npm link` packages in the global CLI by changing the directory of the global module.

For me it is `cd /usr/local/lib/node_modules/@noodle-graph/cli`.

For example:

```bash
cd /usr/local/lib/node_modules/@noodle-graph/cli
cd $(npm root -g)/@noodle-graph/cli
npm link @noodle-graph/scanner
```

To print out linked packages you can run:

```bash
npm list -g --depth=0
```

### Testing the UI locally

1. Run a scan somewhere, for example in [the basic example](./examples/basic)
Expand All @@ -132,26 +169,3 @@ npm link @noodle-graph/scanner
4. Run `nx start ui`, you should see the scan results. Changes you do in the `src` files, will change the UI.

_Make sure you don't push the `scanOutput.js` file_

## Automated tests

All projects have a `test` command that you can run with:

```bash
nx test <project name>
```

Where available, you can run only unit tests with:

```bash
nx test:unit <project name>
```

And only integration tests with:

```bash
nx test:integration <project name>
```

Code that requires integration should be separated from code that doesn't.
That will help keeping the separation in tests as well.
24 changes: 13 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# Noodle 🍜 (UNDER CONSTRUCTION 🏗️)
# Noodle 🍜

Architecture diagram that maintains itself.
***Architecture diagram that maintains itself.***

Noodle is an open-source project designed to simplify the process of understanding and visualizing complex system architectures.
It offers automated architecture diagram generation, graph filtering, user-friendly UI features, and a friendly CLI, making it easy to deploy and use.
Additionally, Noodle is reliant on the best source of truth, which is the code itself, by linking to the source code of the relationships.

<img src="https://github.com/noodle-graph/monorepo/blob/master/docs/img/basicExampleGraph.png" width="400" alt="example"/>

Expand Down Expand Up @@ -29,18 +33,16 @@ Architecture diagram that maintains itself.
npm install --location=global @noodle-graph/cli
```

### 2. Add [Noodle comments](./packages/scanner/README.md#noodle-comment)
### 2. Add [Noodle comments](https://github.com/noodle-graph/monorepo/packages/scanner/README.md#noodle-comment)

[Simple example](./examples/basic/someService/index.js)
[Simple example](https://github.com/noodle-graph/monorepo/examples/basic/someService/index.js)

### 3. Create [config file](./packages/cli/README.md#scan-config-file)
### 3. Create [config file](https://github.com/noodle-graph/monorepo/packages/cli/README.md#scan-config-file)

[Simple example](./examples/basic/noodle.json)
[Simple example](https://github.com/noodle-graph/monorepo/examples/basic/noodle.json)

### 4. `noodle run --open`

See more in the [CLI package](./packages/cli).

## Commands

### `run`
Expand All @@ -49,7 +51,7 @@ See more in the [CLI package](./packages/cli).
noodle run
```

Using the [scanner](../scanner) to search resources relationships and bundles a UI with the results.
Using the [scanner](https://github.com/noodle-graph/monorepo/packages/scanner) to search resources relationships and bundles a UI with the results.

#### Parameters

Expand All @@ -64,7 +66,7 @@ Using the [scanner](../scanner) to search resources relationships and bundles a

### Scan config file

You can find example of a config file in the [basic example](../../examples/basic/noodle.json)
You can find example of a config file in the [basic example](https://github.com/noodle-graph/monorepo/examples/basic/noodle.json)

| Field | Required | Description |
|-|-|-|
Expand All @@ -84,4 +86,4 @@ You can find example of a config file in the [basic example](../../examples/basi

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md)
See [CONTRIBUTING.md](https://github.com/noodle-graph/monorepo/CONTRIBUTING.md)
28 changes: 15 additions & 13 deletions packages/cli/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# Noodle 🍜 (UNDER CONSTRUCTION 🏗️)
# Noodle 🍜

Architecture diagram that maintains itself.
***Architecture diagram that maintains itself.***

Noodle is an open-source project designed to simplify the process of understanding and visualizing complex system architectures.
It offers automated architecture diagram generation, graph filtering, user-friendly UI features, and a friendly CLI, making it easy to deploy and use.
Additionally, Noodle is reliant on the best source of truth, which is the code itself, by linking to the source code of the relationships.

<img src="https://github.com/noodle-graph/monorepo/blob/master/docs/img/basicExampleGraph.png" width="400" alt="example"/>

Expand Down Expand Up @@ -29,18 +33,16 @@ Architecture diagram that maintains itself.
npm install --location=global @noodle-graph/cli
```

### 2. Add [Noodle comments](./packages/scanner/README.md#noodle-comment)
### 2. Add [Noodle comments](https://github.com/noodle-graph/monorepo/packages/scanner/README.md#noodle-comment)

[Simple example](./examples/basic/someService/index.js)
[Simple example](https://github.com/noodle-graph/monorepo/examples/basic/someService/index.js)

### 3. Create [config file](./packages/cli/README.md#scan-config-file)
### 3. Create [config file](https://github.com/noodle-graph/monorepo/packages/cli/README.md#scan-config-file)

[Simple example](./examples/basic/noodle.json)
[Simple example](https://github.com/noodle-graph/monorepo/examples/basic/noodle.json)

### 4. `noodle run --open`

See more in the [CLI package](./packages/cli).

## Commands

### `run`
Expand All @@ -49,7 +51,7 @@ See more in the [CLI package](./packages/cli).
noodle run
```

Using the [scanner](../scanner) to search resources relationships and bundles a UI with the results.
Using the [scanner](https://github.com/noodle-graph/monorepo/packages/scanner) to search resources relationships and bundles a UI with the results.

#### Parameters

Expand All @@ -59,12 +61,12 @@ Using the [scanner](../scanner) to search resources relationships and bundles a
| `--output`, `-o` | `NOODLE_OUTPUT` | `./noodleScanOutput` | Path to the UI bundle output folder. |
| `--githubToken` | `NOODLE_GITHUB_TOKEN` | - | GitHub access token. Required for GitHub resources. |
| `--open` | - | `false` | Whether to open in the browser the bundled UI when finished. |
| `--workers` | - | `8` | Amount of workers that will scan files in parallel. |
| `--verbose` | - | `false` | If true, Noodle will print more logs. |
| `--workers` | - | TODO | TODO |
| `--verbose` | - | TODO | TODO |

### Scan config file

You can find example of a config file in the [basic example](../../examples/basic/noodle.json)
You can find example of a config file in the [basic example](https://github.com/noodle-graph/monorepo/examples/basic/noodle.json)

| Field | Required | Description |
|-|-|-|
Expand All @@ -84,4 +86,4 @@ You can find example of a config file in the [basic example](../../examples/basi

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md)
See [CONTRIBUTING.md](https://github.com/noodle-graph/monorepo/CONTRIBUTING.md)
6 changes: 3 additions & 3 deletions packages/cli/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@
"type": "git",
"url": "git+https://github.com/noodle-graph/monorepo.git"
},
"main": "index.js",
"main": "src/index.js",
"bin": {
"noodle": "./index.js"
"noodle": "src/index.js"
},
"scripts": {
"build": "tsc --project tsconfig.lib.json && cp package.json dist && cp README.md dist && node scripts/copyUi.mjs",
"build": "tsc --project tsconfig.lib.json && cp README.md dist && node scripts/copyUi.mjs",
"lint": "eslint .",
"test": "jest --passWithNoTests",
"build:global": "nx build && cd ../scanner/dist && npm link && cd ../../cli/dist && npm i -g . && cd $(npm root -g)/@noodle-graph/cli && npm link @noodle-graph/scanner"
Expand Down
37 changes: 19 additions & 18 deletions packages/cli/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,25 +1,26 @@
#! /usr/bin/env node

import { DEFAULT_FILES_WORKERS_NUM } from '@noodle-graph/scanner';
import { Command } from 'commander';
import { Command, Option } from 'commander';
import figlet from 'figlet';

import { run } from './run';

export const program = new Command();
import packageJson from '../package.json';

program.name('noodle').version('0.0.5').description(figlet.textSync('Noodle'));

program.addCommand(
new Command('run')
.description('Using the scanner to search resources relationships.')
.option('--config, -c <string>', 'Path to the scan configuration file.', process.env.NOODLE_CONFIG ?? 'noodle.json')
.option('--output, -o <string>', 'Path the the bundle output directory.', process.env.NOODLE_OUTPUT ?? './noodleScanOutput')
.option('--githubToken <string>', 'GitHub access token.', process.env.NOODLE_GITHUB_TOKEN)
.option('--open', 'Whether to open in the browser the bundled UI when finished.')
.option('--workers', 'Number of scanner workers', DEFAULT_FILES_WORKERS_NUM.toString())
.option('--verbose', 'Print debug logs')
.action(run)
);
import { run } from './run';

program.parse();
new Command()
.name('noodle')
.version(packageJson.version)
.description(figlet.textSync('Noodle'))
.addCommand(
new Command('run')
.description('Using the scanner to search resources relationships.')
.addOption(new Option('--config, -c <string>', 'Path to the scan configuration file.').default('noodle.json').env('NOODLE_CONFIG'))
.addOption(new Option('--output, -o <string>', 'Path the the bundle output directory.').default('./noodleScanOutput').env('NOODLE_OUTPUT'))
.addOption(new Option('--githubToken <string>', 'GitHub access token.').env('NOODLE_GITHUB_TOKEN'))
.addOption(new Option('--open', 'Whether to open in the browser the bundled UI when finished.'))
.addOption(new Option('--workers <number>', 'Number of scanner workers').default(DEFAULT_FILES_WORKERS_NUM).env('NOODLE_WORKERS').argParser(parseFloat))
.addOption(new Option('--verbose', 'Print debug logs.'))
.action(run)
)
.parse();
7 changes: 5 additions & 2 deletions packages/cli/src/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import { join, isAbsolute } from 'path';
import { scan } from '@noodle-graph/scanner';
import loggerConstructor from 'pino';

const UI_BUILD_DIR_PATH = 'ui/build';
const UI_BUILD_DIR_PATH = '../ui/build';
const SCAN_OUTPUT_JS_FILENAME = 'scanOutput.js';
const SCAN_OUTPUT_JS_PLACEHOLDER = "'%SCAN_OUTPUT_PLACEHOLDER%'";
const INDEX_HTML_FILENAME = 'index.html';
Expand All @@ -25,7 +25,7 @@ export async function run(scanAttributes): Promise<void> {
{
config: JSON.parse((await readFile(configPath)).toString()),
github: { token: scanAttributes.githubToken },
scanWorkersNum: Number(scanAttributes.workers),
scanWorkersNum: scanAttributes.workers,
},
logger
);
Expand All @@ -47,6 +47,9 @@ function createLogger(level: 'debug' | 'info') {
level,
transport: {
target: 'pino-pretty',
options: {
ignore: 'pid,githubToken',
},
},
});
}
1 change: 1 addition & 0 deletions packages/cli/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,6 @@
"extends": "../../tsconfig.base.json",
"include": [
"src/**/*.ts",
"package.json",
]
}
Loading

0 comments on commit 873ba6a

Please sign in to comment.