repogenome 0.1.0
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/LICENSE +21 -0
- package/README.md +133 -0
- package/dist/cli.js +1998 -0
- package/package.json +51 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Muhammad Usman
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# RepoGenome
|
|
2
|
+
|
|
3
|
+
> Capture the architectural DNA of a codebase and track how it changes over time.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/repogenome)
|
|
6
|
+
[](https://www.npmjs.com/package/repogenome)
|
|
7
|
+
[](https://github.com/MuhammadUsmanGM/repogenome/actions)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
[](https://www.typescriptlang.org)
|
|
11
|
+
|
|
12
|
+
RepoGenome scans your source code and produces a `genome.json` — a structured snapshot of your architecture, patterns, concepts, and dependency flows. Run it again later and get a precise drift score showing exactly what changed and which directories caused it.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g repogenome
|
|
20
|
+
# or run without installing:
|
|
21
|
+
npx repogenome init
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**Requires:** Node.js ≥ 18
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Quick Start
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# 1. Create a baseline genome in your project root
|
|
32
|
+
npx repogenome init
|
|
33
|
+
|
|
34
|
+
# 2. Commit the baseline
|
|
35
|
+
git add .repogenome/genome.json
|
|
36
|
+
git commit -m "chore: add repogenome baseline"
|
|
37
|
+
|
|
38
|
+
# 3. Later — check if your architecture drifted
|
|
39
|
+
npx repogenome audit
|
|
40
|
+
|
|
41
|
+
# 4. Find which directories are responsible for the drift
|
|
42
|
+
npx repogenome blame
|
|
43
|
+
|
|
44
|
+
# 5. Compare two branches (requires git)
|
|
45
|
+
npx repogenome compare main feature/my-branch
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Commands
|
|
51
|
+
|
|
52
|
+
For full flags, options, and examples for each command see **[docs/commands.md](docs/commands.md)**.
|
|
53
|
+
|
|
54
|
+
| Command | Description |
|
|
55
|
+
|---------|-------------|
|
|
56
|
+
| [`init`](docs/commands.md#repogenome-init) | Scan repo and create architectural baseline |
|
|
57
|
+
| [`audit`](docs/commands.md#repogenome-audit) | Compare current state against baseline, report drift |
|
|
58
|
+
| [`blame`](docs/commands.md#repogenome-blame) | Attribute drift to specific directories and files |
|
|
59
|
+
| [`compare`](docs/commands.md#repogenome-compare) | Diff two git refs against each other |
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## CI Integration
|
|
64
|
+
|
|
65
|
+
Block merges that exceed your drift threshold:
|
|
66
|
+
|
|
67
|
+
```yaml
|
|
68
|
+
# .github/workflows/genome-check.yml
|
|
69
|
+
name: Genome Check
|
|
70
|
+
on: [pull_request]
|
|
71
|
+
|
|
72
|
+
jobs:
|
|
73
|
+
audit:
|
|
74
|
+
runs-on: ubuntu-latest
|
|
75
|
+
steps:
|
|
76
|
+
- uses: actions/checkout@v4
|
|
77
|
+
- uses: actions/setup-node@v4
|
|
78
|
+
with:
|
|
79
|
+
node-version: 20
|
|
80
|
+
- run: npx repogenome audit --threshold 25
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Exit code `1` when drift exceeds the threshold — CI step fails automatically.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## What Gets Detected
|
|
88
|
+
|
|
89
|
+
| Dimension | What it measures | Weight |
|
|
90
|
+
|-----------|-----------------|--------|
|
|
91
|
+
| Architecture | Layered vs modular vs flat structure change | 20% |
|
|
92
|
+
| Patterns | Repository, Service, Controller, Factory, etc. | 25% |
|
|
93
|
+
| Naming | Dominant casing, common prefixes/suffixes | 15% |
|
|
94
|
+
| Concepts | Domain vocabulary drift | 15% |
|
|
95
|
+
| Dependencies | DB access patterns, cross-layer imports | 15% |
|
|
96
|
+
| Violations | Controller→Repository direct calls, circular imports | 10% |
|
|
97
|
+
|
|
98
|
+
**Risk levels:** 🟢 Low (<10%) · 🟡 Medium (10–30%) · 🔴 High (>30%)
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Output Files
|
|
103
|
+
|
|
104
|
+
| File | Description |
|
|
105
|
+
|------|-------------|
|
|
106
|
+
| `.repogenome/genome.json` | Baseline — **commit this** |
|
|
107
|
+
| `.repogenome/history/<ts>.json` | Snapshot per audit run — add to `.gitignore` |
|
|
108
|
+
| `repogenome-report.html` | Self-contained HTML report (`--format html`) |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Supported Languages
|
|
113
|
+
|
|
114
|
+
TypeScript · JavaScript · Python · Go · Java · Kotlin
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Documentation
|
|
119
|
+
|
|
120
|
+
| Doc | Description |
|
|
121
|
+
|-----|-------------|
|
|
122
|
+
| [docs/commands.md](docs/commands.md) | Full command reference with all flags and examples |
|
|
123
|
+
| [docs/security.md](docs/security.md) | Security policy and vulnerability reporting |
|
|
124
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, project structure, PR guide |
|
|
125
|
+
| [CHANGELOG.md](CHANGELOG.md) | Release history |
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## License
|
|
130
|
+
|
|
131
|
+
MIT © [Muhammad Usman](https://github.com/MuhammadUsmanGM)
|
|
132
|
+
|
|
133
|
+
<!-- Muhammad Usman | MuhammadUsmanGM | MUGM-b4e2-7f1a-9c3d -->
|