repo-blueprint 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +72 -37
- package/package.json +1 -1
- package/skills/repo-blueprint/SKILL.md +2 -2
package/README.md
CHANGED
|
@@ -1,58 +1,93 @@
|
|
|
1
|
-
# repo-blueprint
|
|
1
|
+
# repo-blueprint [](https://www.npmjs.com/package/repo-blueprint)
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A clearer way to see how a repository is built. repo-blueprint maps a codebase into layers, with each part placed above its dependencies. Detail is handled by zoom: the top level shows packages, and zooming in reveals folders, then files.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Works with TypeScript, JavaScript and Python, monorepos included
|
|
8
|
+
- Draws imports, RPC and HTTP calls, events, and external systems such as databases and queues
|
|
9
|
+
- Flags import cycles, unused packages and orphan files
|
|
10
|
+
- Produces one self-contained HTML file
|
|
11
|
+
- Uses static analysis only, so the output is deterministic
|
|
8
12
|
|
|
9
|
-
|
|
10
|
-
2. Ask for "a blueprint of this repo", or "a live blueprint I can keep open while I work".
|
|
13
|
+
## Usage
|
|
11
14
|
|
|
12
|
-
|
|
15
|
+
Requires Node.js 18.17+. Python projects also need Python 3.10+ or [uv](https://docs.astral.sh/uv/).
|
|
13
16
|
|
|
14
|
-
|
|
17
|
+
```sh
|
|
18
|
+
npx repo-blueprint build [repo]
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Writes `~/.repo-blueprint/<repo>.blueprint.html` and prints a short summary.
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npx repo-blueprint watch [repo]
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Serves the map on localhost and rebuilds it when files change.
|
|
28
|
+
|
|
29
|
+
| Option | Description |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `--out`, `-o` | Output file (`build` only) |
|
|
32
|
+
| `--port`, `-p` | Port for `watch`, default 4321 |
|
|
33
|
+
| `--open` | Open the result in a browser |
|
|
34
|
+
|
|
35
|
+
`repo` defaults to the current directory.
|
|
15
36
|
|
|
16
|
-
|
|
37
|
+
## Supported projects
|
|
17
38
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
39
|
+
- **TypeScript and JavaScript:** any folder with a `package.json` and a `tsconfig.json`, at any depth. Imports are resolved through the project's tsconfig paths.
|
|
40
|
+
- **Python:** any folder with a `pyproject.toml`.
|
|
41
|
+
|
|
42
|
+
Each package is shown as an app, a service or a library. A declared type is used when there is one (Backstage `catalog-info.yaml`, Nx `project.json`). Otherwise the role is inferred: an entry file that mounts a UI makes an app, one that starts a server or worker makes a service, and anything else is a library.
|
|
43
|
+
|
|
44
|
+
## Agent skill
|
|
45
|
+
|
|
46
|
+
The package includes a skill for Claude Code and other agents:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
npx skills add MohGanji/repo-blueprint
|
|
21
50
|
```
|
|
22
51
|
|
|
23
|
-
|
|
24
|
-
- `watch` serves the page on localhost and rebuilds it whenever source files change.
|
|
52
|
+
You can also copy [`SKILL.md`](https://github.com/MohGanji/repo-blueprint/blob/main/skills/repo-blueprint/SKILL.md) into your agent's skills folder. Then ask for "a blueprint of this repo", or a live one to keep open while you work. The skill runs this package through `npx`, pinned to an exact version.
|
|
25
53
|
|
|
26
|
-
|
|
54
|
+
## Configuration
|
|
27
55
|
|
|
28
|
-
|
|
56
|
+
Put a `.blueprint.json` in the root of the repo being mapped to extend the [defaults](https://github.com/MohGanji/repo-blueprint/blob/main/src/blueprint.config.json). For example, to detect an extra external system:
|
|
29
57
|
|
|
30
|
-
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"externalSystems": { "Stripe": ["stripe"] }
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
| Key | Description |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `externalSystems` | System names and the packages that indicate them |
|
|
67
|
+
| `messaging` | Method and property names for RPC calls, publishes and subscriptions |
|
|
68
|
+
| `folderRoles` | Folder names that imply a role, used by the role-mismatch finding |
|
|
69
|
+
| `sdkDirs` | Folders whose subfolders are generated API clients, named after the services they call |
|
|
31
70
|
|
|
32
|
-
|
|
33
|
-
- `messaging`: method and property names for RPC calls, publishes and subscriptions.
|
|
34
|
-
- `folderRoles`: folder names that imply a role, used for the role-mismatch finding.
|
|
35
|
-
- `sdkDirs`: folder names whose subfolders are generated API clients named after the services they call.
|
|
71
|
+
## How it works
|
|
36
72
|
|
|
37
|
-
|
|
73
|
+
The TypeScript compiler API and Python's `ast` module extract facts from the source. Those become a model of packages, folders, edges and findings, which is rendered as one diagram per folder.
|
|
38
74
|
|
|
39
75
|
```
|
|
40
|
-
bin/repo-blueprint.mjs
|
|
41
|
-
src/
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
skills/repo-blueprint/
|
|
49
|
-
.claude-plugin/plugin.json Claude Code plugin manifest
|
|
76
|
+
bin/repo-blueprint.mjs CLI
|
|
77
|
+
src/
|
|
78
|
+
├── extract-ts.mjs TypeScript extractor
|
|
79
|
+
├── extract-py.py Python extractor
|
|
80
|
+
├── model.mjs packages, edges, roles, findings
|
|
81
|
+
├── views.mjs one diagram per folder
|
|
82
|
+
├── build.mjs writes the HTML
|
|
83
|
+
└── template.html the page
|
|
84
|
+
skills/repo-blueprint/ agent skill
|
|
50
85
|
```
|
|
51
86
|
|
|
52
|
-
##
|
|
87
|
+
## Contributing
|
|
88
|
+
|
|
89
|
+
Bug reports and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/MohGanji/repo-blueprint/blob/main/CONTRIBUTING.md).
|
|
53
90
|
|
|
54
|
-
|
|
91
|
+
## License
|
|
55
92
|
|
|
56
|
-
|
|
57
|
-
2. Update the `repo-blueprint@x.y.z` references in `skills/repo-blueprint/SKILL.md`.
|
|
58
|
-
3. `npm publish`, then commit and tag the release.
|
|
93
|
+
MIT
|
package/package.json
CHANGED
|
@@ -14,13 +14,13 @@ The skill runs the `repo-blueprint` npm package, pinned to the version it was wr
|
|
|
14
14
|
One-time build, writes the HTML and prints its path plus a summary:
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
npx -y repo-blueprint@0.1.
|
|
17
|
+
npx -y repo-blueprint@0.1.2 build <repo> --open
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
Live mode, serves the page and rebuilds it when source files change (run it in the background; it keeps running until stopped):
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
|
-
npx -y repo-blueprint@0.1.
|
|
23
|
+
npx -y repo-blueprint@0.1.2 watch <repo> --open
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
Keep the pinned version as written, even if a newer one exists: the same commit and the same version always produce the same page, so users can compare blueprints over time.
|