complexity-guard 0.9.1 → 0.9.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/README.md +90 -19
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -2,23 +2,47 @@
|
|
|
2
2
|
|
|
3
3
|
Fast complexity analysis for TypeScript/JavaScript — single static binary built with Rust, zero dependencies.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
Install ComplexityGuard:
|
|
6
8
|
|
|
7
9
|
```sh
|
|
8
|
-
#
|
|
10
|
+
# npm (global install)
|
|
9
11
|
npm install -g complexity-guard
|
|
10
12
|
|
|
11
|
-
#
|
|
13
|
+
# npm (local/CI install)
|
|
12
14
|
npm install --save-dev complexity-guard
|
|
15
|
+
|
|
16
|
+
# Direct download (Rust binary — all platforms)
|
|
17
|
+
# Download the archive for your platform from GitHub Releases:
|
|
18
|
+
# https://github.com/benvds/complexity-guard/releases
|
|
19
|
+
#
|
|
20
|
+
# Available platforms:
|
|
21
|
+
# complexity-guard-linux-x86_64-musl.tar.gz (Linux x86_64)
|
|
22
|
+
# complexity-guard-linux-aarch64-musl.tar.gz (Linux ARM64)
|
|
23
|
+
# complexity-guard-macos-x86_64.tar.gz (macOS Intel)
|
|
24
|
+
# complexity-guard-macos-aarch64.tar.gz (macOS Apple Silicon)
|
|
25
|
+
# complexity-guard-windows-x86_64.zip (Windows x64)
|
|
26
|
+
#
|
|
27
|
+
# Extract and install (macOS/Linux):
|
|
28
|
+
tar xzf complexity-guard-*.tar.gz
|
|
29
|
+
chmod +x complexity-guard
|
|
30
|
+
sudo mv complexity-guard /usr/local/bin/
|
|
13
31
|
```
|
|
14
32
|
|
|
15
|
-
|
|
33
|
+
Run analysis on your codebase:
|
|
16
34
|
|
|
17
35
|
```sh
|
|
18
36
|
complexity-guard src/
|
|
19
37
|
```
|
|
20
38
|
|
|
21
|
-
|
|
39
|
+
Set up health score tracking (analyzes your code, suggests weights, saves baseline):
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
complexity-guard --init src/
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Example Output
|
|
22
46
|
|
|
23
47
|
```
|
|
24
48
|
src/auth/login.ts
|
|
@@ -45,22 +69,59 @@ Top Halstead volume hotspots:
|
|
|
45
69
|
✗ 4 problems (1 errors, 3 warnings)
|
|
46
70
|
```
|
|
47
71
|
|
|
72
|
+
## Benchmarks
|
|
73
|
+
|
|
74
|
+
Analyzed across 83 open-source projects (107k files, 321k functions). Selection of results on Apple M1 Max with parallel analysis:
|
|
75
|
+
|
|
76
|
+
| Project | Files | Functions | Time (ms) | Health Score |
|
|
77
|
+
|---------|------:|----------:|----------:|-------------:|
|
|
78
|
+
| lodash | 26 | 79 | 13 ± 1 | 92.4 |
|
|
79
|
+
| axios | 160 | 472 | 22 ± 2 | 95.8 |
|
|
80
|
+
| excalidraw | 380 | 1,909 | 74 ± 6 | 92.0 |
|
|
81
|
+
| tanstack-query | 721 | 1,371 | 86 ± 5 | 95.0 |
|
|
82
|
+
| vite | 1,182 | 2,639 | 83 ± 4 | 95.4 |
|
|
83
|
+
| three.js | 1,537 | 10,133 | 705 ± 190 | 93.2 |
|
|
84
|
+
| vscode | 5,071 | 59,316 | 3,281 ± 418 | 94.1 |
|
|
85
|
+
|
|
86
|
+
See the [full benchmark results](https://github.com/benvds/complexity-guard/blob/main/docs/benchmarks.md) for all 83 projects.
|
|
87
|
+
|
|
48
88
|
## Features
|
|
49
89
|
|
|
50
90
|
- **Cyclomatic Complexity**: McCabe metric counting independent code paths — measures testability
|
|
51
91
|
- **Cognitive Complexity**: SonarSource-based metric with nesting depth penalties — measures understandability
|
|
52
92
|
- **Halstead Metrics**: Information-theoretic vocabulary density, volume, difficulty, effort, and estimated bugs
|
|
53
93
|
- **Structural Metrics**: Function length, parameter count, nesting depth, file length, and export count
|
|
54
|
-
- **Duplication Detection**: Rabin-Karp rolling hash detects Type 1 and Type 2 code clones across files — enable with `--duplication`
|
|
94
|
+
- **Duplication Detection**: Rabin-Karp rolling hash detects Type 1 and Type 2 code clones across files — enable with `--duplication` (see [duplication docs](https://github.com/benvds/complexity-guard/blob/main/docs/duplication-detection.md))
|
|
55
95
|
- **Composite Health Score**: Single 0–100 score combining all metric families with configurable weights — enforce in CI with `--fail-health-below`
|
|
56
96
|
- **Console + JSON + SARIF + HTML Output**: Human-readable terminal display, machine-readable JSON, SARIF 2.1.0 for GitHub Code Scanning, and self-contained HTML reports with interactive dashboard, treemap visualization, and sortable metric tables
|
|
57
|
-
- **
|
|
97
|
+
- **Parallel Analysis**: Analyzes files concurrently across all CPU cores by default — use `--threads N` to control thread count or `--threads 1` for single-threaded mode
|
|
58
98
|
- **Configurable Thresholds**: Warning and error levels for all metric families, customizable per project
|
|
59
99
|
- **Selective Metrics**: Use `--metrics cyclomatic,halstead` to compute only specific families
|
|
60
100
|
- **Zero Config**: Works out of the box with sensible defaults, optional `.complexityguard.json` for customization
|
|
61
|
-
- **Single Binary**: No runtime dependencies, runs offline, fast startup
|
|
62
|
-
- **
|
|
101
|
+
- **Single Binary**: No runtime dependencies, runs offline, fast startup — under 300ms on mid-size projects
|
|
102
|
+
- **Fast**: Analyzes thousands of files in seconds with parallel analysis across all CPU cores (see [benchmarks](https://github.com/benvds/complexity-guard/blob/main/docs/benchmarks.md))
|
|
103
|
+
- **Low Memory Footprint**: 1.2–2.2x less memory than Node.js-based tools on small and medium projects (see [benchmarks](https://github.com/benvds/complexity-guard/blob/main/docs/benchmarks.md))
|
|
63
104
|
- **Error-Tolerant Parsing**: Tree-sitter based parser handles syntax errors gracefully, continues analysis on remaining files
|
|
105
|
+
- **Automatic Safety Limits**: Files > 10,000 lines and functions > 5,000 lines are skipped and reported in output — prevents crashes on auto-generated code or minified bundles (see [Size Limits](https://github.com/benvds/complexity-guard/blob/main/docs/cli-reference.md#size-limits))
|
|
106
|
+
|
|
107
|
+
## Documentation
|
|
108
|
+
|
|
109
|
+
- **[Getting Started](https://github.com/benvds/complexity-guard/blob/main/docs/getting-started.md)** — Installation, first analysis, configuration basics
|
|
110
|
+
- **[CLI Reference](https://github.com/benvds/complexity-guard/blob/main/docs/cli-reference.md)** — All flags, config options, exit codes
|
|
111
|
+
- **[Examples](https://github.com/benvds/complexity-guard/blob/main/docs/examples.md)** — Real-world usage patterns, CI integration recipes
|
|
112
|
+
- **[SARIF Output](https://github.com/benvds/complexity-guard/blob/main/docs/sarif-output.md)** — GitHub Code Scanning integration with inline PR annotations
|
|
113
|
+
- **[HTML Reports](https://github.com/benvds/complexity-guard/blob/main/docs/examples.md#html-reports)** — Self-contained interactive reports for sharing with stakeholders
|
|
114
|
+
- **[Performance Benchmarks](https://github.com/benvds/complexity-guard/blob/main/docs/benchmarks.md)** — Speed and memory benchmarks across real-world projects
|
|
115
|
+
- **[Claude Code Skill](https://github.com/benvds/complexity-guard/blob/main/docs/claude-code-skill.md)** — Use ComplexityGuard with Claude Code AI agents
|
|
116
|
+
|
|
117
|
+
### Metrics
|
|
118
|
+
|
|
119
|
+
- **[Health Score](https://github.com/benvds/complexity-guard/blob/main/docs/health-score.md)** — Composite 0–100 score, formula, weights, and baseline + ratchet workflow
|
|
120
|
+
- **[Cyclomatic Complexity](https://github.com/benvds/complexity-guard/blob/main/docs/cyclomatic-complexity.md)** — Path counting for testability, ESLint-aligned rules
|
|
121
|
+
- **[Cognitive Complexity](https://github.com/benvds/complexity-guard/blob/main/docs/cognitive-complexity.md)** — Nesting-aware readability metric from SonarSource
|
|
122
|
+
- **[Halstead Metrics](https://github.com/benvds/complexity-guard/blob/main/docs/halstead-metrics.md)** — Vocabulary density, volume, difficulty, effort, estimated bugs
|
|
123
|
+
- **[Structural Metrics](https://github.com/benvds/complexity-guard/blob/main/docs/structural-metrics.md)** — Function length, parameters, nesting depth, file length, exports
|
|
124
|
+
- **[Duplication Detection](https://github.com/benvds/complexity-guard/blob/main/docs/duplication-detection.md)** — Rabin-Karp clone detection, Type 1/2 clones, thresholds (opt-in)
|
|
64
125
|
|
|
65
126
|
## Configuration
|
|
66
127
|
|
|
@@ -76,28 +137,38 @@ Create a `.complexityguard.json` file in your project root to customize behavior
|
|
|
76
137
|
"cyclomatic": { "warning": 10, "error": 20 },
|
|
77
138
|
"cognitive": { "warning": 15, "error": 25 },
|
|
78
139
|
"halstead_volume": { "warning": 500, "error": 1000 },
|
|
140
|
+
"halstead_difficulty": { "warning": 10, "error": 20 },
|
|
79
141
|
"halstead_effort": { "warning": 5000, "error": 10000 },
|
|
142
|
+
"halstead_bugs": { "warning": 0.5, "error": 2.0 },
|
|
80
143
|
"function_length": { "warning": 25, "error": 50 },
|
|
81
144
|
"params": { "warning": 3, "error": 6 },
|
|
82
|
-
"nesting": { "warning": 3, "error": 5 }
|
|
145
|
+
"nesting": { "warning": 3, "error": 5 },
|
|
146
|
+
"file_length": { "warning": 300, "error": 600 },
|
|
147
|
+
"exports": { "warning": 15, "error": 30 },
|
|
148
|
+
"duplication": { "file_warning": 15.0, "file_error": 25.0, "project_warning": 5.0, "project_error": 10.0 }
|
|
83
149
|
},
|
|
84
150
|
"counting_rules": {
|
|
85
151
|
"logical_operators": true,
|
|
86
152
|
"nullish_coalescing": true,
|
|
87
153
|
"optional_chaining": true,
|
|
88
154
|
"switch_case_mode": "perCase"
|
|
89
|
-
}
|
|
155
|
+
},
|
|
156
|
+
"weights": {
|
|
157
|
+
"cognitive": 0.30,
|
|
158
|
+
"cyclomatic": 0.20,
|
|
159
|
+
"halstead": 0.15,
|
|
160
|
+
"structural": 0.15
|
|
161
|
+
},
|
|
162
|
+
"analysis": {
|
|
163
|
+
"threads": 4,
|
|
164
|
+
"duplication_enabled": false
|
|
165
|
+
},
|
|
166
|
+
"baseline": 73.2
|
|
90
167
|
}
|
|
91
168
|
```
|
|
92
169
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
- [GitHub](https://github.com/benvds/complexity-guard)
|
|
96
|
-
- [Documentation](https://github.com/benvds/complexity-guard#documentation)
|
|
97
|
-
- [SARIF Output / GitHub Code Scanning](https://github.com/benvds/complexity-guard/blob/main/docs/sarif-output.md)
|
|
98
|
-
- [HTML Reports](https://github.com/benvds/complexity-guard/blob/main/docs/examples.md#html-reports)
|
|
99
|
-
- [Performance Benchmarks](https://github.com/benvds/complexity-guard/blob/main/docs/benchmarks.md)
|
|
170
|
+
See the [CLI Reference](https://github.com/benvds/complexity-guard/blob/main/docs/cli-reference.md) for complete configuration options.
|
|
100
171
|
|
|
101
172
|
## License
|
|
102
173
|
|
|
103
|
-
MIT
|
|
174
|
+
[MIT](https://github.com/benvds/complexity-guard/blob/main/LICENSE)
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"name": "Ben van de Sande",
|
|
5
5
|
"email": "info@getlean.digital"
|
|
6
6
|
},
|
|
7
|
-
"version": "0.9.
|
|
7
|
+
"version": "0.9.2",
|
|
8
8
|
"description": "Fast complexity analysis for TypeScript/JavaScript — single static binary",
|
|
9
9
|
"bin": {
|
|
10
10
|
"complexity-guard": "bin/complexity-guard.js"
|
|
@@ -13,11 +13,11 @@
|
|
|
13
13
|
"bin/"
|
|
14
14
|
],
|
|
15
15
|
"optionalDependencies": {
|
|
16
|
-
"@complexity-guard/darwin-arm64": "0.9.
|
|
17
|
-
"@complexity-guard/darwin-x64": "0.9.
|
|
18
|
-
"@complexity-guard/linux-arm64": "0.9.
|
|
19
|
-
"@complexity-guard/linux-x64": "0.9.
|
|
20
|
-
"@complexity-guard/windows-x64": "0.9.
|
|
16
|
+
"@complexity-guard/darwin-arm64": "0.9.2",
|
|
17
|
+
"@complexity-guard/darwin-x64": "0.9.2",
|
|
18
|
+
"@complexity-guard/linux-arm64": "0.9.2",
|
|
19
|
+
"@complexity-guard/linux-x64": "0.9.2",
|
|
20
|
+
"@complexity-guard/windows-x64": "0.9.2"
|
|
21
21
|
},
|
|
22
22
|
"license": "MIT",
|
|
23
23
|
"repository": {
|