complexity-guard 0.7.0 → 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 +94 -25
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,36 +1,58 @@
|
|
|
1
1
|
# ComplexityGuard
|
|
2
2
|
|
|
3
|
-
Fast complexity analysis for TypeScript/JavaScript — single static binary, zero dependencies.
|
|
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
|
|
25
49
|
42:0 ✓ ok Function 'validateCredentials' cyclomatic 3 cognitive 2
|
|
26
|
-
67:0 ⚠ warning Function 'processLoginFlow' cyclomatic 12 cognitive 18
|
|
27
|
-
|
|
28
|
-
89:2 ✗ error Method 'handleComplexAuthFlow' cyclomatic 25 cognitive 32
|
|
29
|
-
[halstead vol 1244 diff 18.6 effort 23135 bugs 0.41] [length 62 params 4 depth 6]
|
|
50
|
+
67:0 ⚠ warning Function 'processLoginFlow' cyclomatic 12 cognitive 18 [halstead vol 843] [length 34] [params 3] [depth 4]
|
|
51
|
+
89:2 ✗ error Function 'handleComplexAuthFlow' cyclomatic 25 cognitive 32 [halstead vol 1244] [length 62] [params 4] [depth 6]
|
|
30
52
|
|
|
31
53
|
Analyzed 12 files, 47 functions
|
|
32
|
-
Found 3 warnings, 1 errors
|
|
33
54
|
Health: 73
|
|
55
|
+
Found 3 warnings, 1 errors
|
|
34
56
|
|
|
35
57
|
Top cyclomatic hotspots:
|
|
36
58
|
1. handleComplexAuthFlow (src/auth/login.ts:89) complexity 25
|
|
@@ -47,22 +69,59 @@ Top Halstead volume hotspots:
|
|
|
47
69
|
✗ 4 problems (1 errors, 3 warnings)
|
|
48
70
|
```
|
|
49
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
|
+
|
|
50
88
|
## Features
|
|
51
89
|
|
|
52
90
|
- **Cyclomatic Complexity**: McCabe metric counting independent code paths — measures testability
|
|
53
91
|
- **Cognitive Complexity**: SonarSource-based metric with nesting depth penalties — measures understandability
|
|
54
92
|
- **Halstead Metrics**: Information-theoretic vocabulary density, volume, difficulty, effort, and estimated bugs
|
|
55
93
|
- **Structural Metrics**: Function length, parameter count, nesting depth, file length, and export count
|
|
56
|
-
- **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))
|
|
57
95
|
- **Composite Health Score**: Single 0–100 score combining all metric families with configurable weights — enforce in CI with `--fail-health-below`
|
|
58
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
|
|
59
|
-
- **
|
|
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
|
|
60
98
|
- **Configurable Thresholds**: Warning and error levels for all metric families, customizable per project
|
|
61
99
|
- **Selective Metrics**: Use `--metrics cyclomatic,halstead` to compute only specific families
|
|
62
100
|
- **Zero Config**: Works out of the box with sensible defaults, optional `.complexityguard.json` for customization
|
|
63
|
-
- **Single Binary**: No runtime dependencies, runs offline, fast startup
|
|
64
|
-
- **
|
|
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))
|
|
65
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)
|
|
66
125
|
|
|
67
126
|
## Configuration
|
|
68
127
|
|
|
@@ -78,28 +137,38 @@ Create a `.complexityguard.json` file in your project root to customize behavior
|
|
|
78
137
|
"cyclomatic": { "warning": 10, "error": 20 },
|
|
79
138
|
"cognitive": { "warning": 15, "error": 25 },
|
|
80
139
|
"halstead_volume": { "warning": 500, "error": 1000 },
|
|
140
|
+
"halstead_difficulty": { "warning": 10, "error": 20 },
|
|
81
141
|
"halstead_effort": { "warning": 5000, "error": 10000 },
|
|
142
|
+
"halstead_bugs": { "warning": 0.5, "error": 2.0 },
|
|
82
143
|
"function_length": { "warning": 25, "error": 50 },
|
|
83
144
|
"params": { "warning": 3, "error": 6 },
|
|
84
|
-
"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 }
|
|
85
149
|
},
|
|
86
150
|
"counting_rules": {
|
|
87
151
|
"logical_operators": true,
|
|
88
152
|
"nullish_coalescing": true,
|
|
89
153
|
"optional_chaining": true,
|
|
90
154
|
"switch_case_mode": "perCase"
|
|
91
|
-
}
|
|
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
|
|
92
167
|
}
|
|
93
168
|
```
|
|
94
169
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- [GitHub](https://github.com/benvds/complexity-guard)
|
|
98
|
-
- [Documentation](https://github.com/benvds/complexity-guard#documentation)
|
|
99
|
-
- [SARIF Output / GitHub Code Scanning](https://github.com/benvds/complexity-guard/blob/main/docs/sarif-output.md)
|
|
100
|
-
- [HTML Reports](https://github.com/benvds/complexity-guard/blob/main/docs/examples.md#html-reports)
|
|
101
|
-
- [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.
|
|
102
171
|
|
|
103
172
|
## License
|
|
104
173
|
|
|
105
|
-
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.
|
|
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.
|
|
17
|
-
"@complexity-guard/darwin-x64": "0.
|
|
18
|
-
"@complexity-guard/linux-arm64": "0.
|
|
19
|
-
"@complexity-guard/linux-x64": "0.
|
|
20
|
-
"@complexity-guard/windows-x64": "0.
|
|
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": {
|