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.
Files changed (2) hide show
  1. package/README.md +94 -25
  2. 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
- ## Install
5
+ ## Quick Start
6
+
7
+ Install ComplexityGuard:
6
8
 
7
9
  ```sh
8
- # Global install (CLI access from anywhere)
10
+ # npm (global install)
9
11
  npm install -g complexity-guard
10
12
 
11
- # Local/CI install (project dependency)
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
- ## Usage
33
+ Run analysis on your codebase:
16
34
 
17
35
  ```sh
18
36
  complexity-guard src/
19
37
  ```
20
38
 
21
- ### Example Output
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
- [halstead vol 843 diff 14.1 effort 11886] [length 34 params 3 depth 4]
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
- - **Multi-threaded Parallel Analysis**: Analyzes files concurrently across all CPU cores by default — 1.5–3.1x faster than FTA; use `--threads N` to control thread count
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
- - **Low Memory Footprint**: 1.2–2.2x less memory than Node.js-based tools on small and medium projects
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
- ## Links
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.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.7.0",
17
- "@complexity-guard/darwin-x64": "0.7.0",
18
- "@complexity-guard/linux-arm64": "0.7.0",
19
- "@complexity-guard/linux-x64": "0.7.0",
20
- "@complexity-guard/windows-x64": "0.7.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": {