churn_vs_complexity 1.6.0 → 1.6.1
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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +7 -0
- data/README.md +60 -14
- data/lib/churn_vs_complexity/version.rb +1 -1
- metadata +8 -8
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6dfa844a5bcd2fe116001652410d39f802c64623be5ec588afcc6ed331b9aac9
|
|
4
|
+
data.tar.gz: 42c5d56c7b4c6640bd4040f7f5d8b35ea6acac0aae9285be4c6cb1aaf860f0fb
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 0ad833af0897a784aa0499d277884e011e9be71142d343c441ef0a12b1185c27f18c09b0b7780a3f8493e3ef0399faff5f97b252f51fb4713f3dd98d11b666a7
|
|
7
|
+
data.tar.gz: 19cf09a9777aa06a4772fae21fee5a4043ba034efde9d2af13618461b20a602270879438c4aa626463c3ea14054bf1dc8a7b9a25cde09c9636439d9d567a30f3
|
data/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,10 @@
|
|
|
1
|
+
## [1.6.1] - 2026-02-19
|
|
2
|
+
|
|
3
|
+
### Changed
|
|
4
|
+
- Updated gemspec summary and description to reflect all supported languages and modes
|
|
5
|
+
- Updated README with current usage, all languages (Ruby, JS/TS, Java, Python, Go), all modes, and new examples
|
|
6
|
+
- Added external dependency documentation for Python (radon) and Go (gocyclo)
|
|
7
|
+
|
|
1
8
|
## [1.6.0] - 2026-02-19
|
|
2
9
|
|
|
3
10
|
### Added
|
data/README.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
# ChurnVsComplexity
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Correlates file churn (how often files change) with complexity scores to identify refactoring hotspots and track codebase health over time. Supports Ruby, JavaScript/TypeScript, Java, Python, and Go.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Modes include hotspots ranking, triage assessment, CI quality gate, diff comparison, focus sessions, and timetravel history.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Inspired by [Michael Feathers' article "Getting Empirical about Refactoring"](https://www.agileconnection.com/article/getting-empirical-about-refactoring).
|
|
10
10
|
|
|
11
11
|
## Installation
|
|
12
12
|
|
|
@@ -26,30 +26,52 @@ Or install it yourself as:
|
|
|
26
26
|
|
|
27
27
|
This gem depends on git for churn analysis.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
External tool dependencies per language:
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
- **Ruby**: None (uses [Flog](https://rubygems.org/gems/flog), bundled as a gem dependency).
|
|
32
|
+
- **Java**: Requires [PMD](https://pmd.github.io) on the search path as `pmd`. On macOS: `brew install pmd`.
|
|
33
|
+
- **JavaScript/TypeScript**: Requires [Node.js](https://nodejs.org) (uses ESLint internally).
|
|
34
|
+
- **Python**: Requires [Radon](https://radon.readthedocs.io) on the search path as `radon`. Install with `pip install radon`.
|
|
35
|
+
- **Go**: Requires [gocyclo](https://github.com/fzipp/gocyclo) on the search path. Install with `go install github.com/fzipp/gocyclo/cmd/gocyclo@latest`.
|
|
32
36
|
|
|
33
37
|
## Usage
|
|
34
38
|
|
|
35
|
-
Execute
|
|
39
|
+
Execute `churn_vs_complexity` with the applicable arguments. Output in the requested format will be directed to stdout.
|
|
36
40
|
|
|
37
41
|
```
|
|
38
|
-
Usage: churn_vs_complexity [options] folder
|
|
42
|
+
Usage: churn_vs_complexity [options] folder|file...
|
|
43
|
+
|
|
44
|
+
Languages:
|
|
39
45
|
--java Check complexity of java classes
|
|
40
46
|
--ruby Check complexity of ruby files
|
|
41
47
|
--js, --ts, --javascript, --typescript
|
|
42
48
|
Check complexity of javascript and typescript files
|
|
49
|
+
--python Check complexity of python files
|
|
50
|
+
--go Check complexity of go files
|
|
51
|
+
|
|
52
|
+
Modes (mutually exclusive):
|
|
53
|
+
--timetravel N Calculate summary for all commits at intervals of N days throughout project history or from the date specified with --since
|
|
54
|
+
--triage Assess risk of files based on churn and complexity. Accepts file paths or a folder as arguments.
|
|
55
|
+
--hotspots Generate ranked list of files by risk
|
|
56
|
+
--gate Pass/fail quality check against gamma threshold (exits 0 on pass, 1 on fail)
|
|
57
|
+
--focus start|end Capture complexity snapshot before (start) and after (end) a coding session
|
|
58
|
+
--diff REF Compare codebase health between REF and HEAD
|
|
59
|
+
--delta SHA Identify changes between the specified commit (SHA) and the previous commit and annotate changed files with complexity score. SHA can be a full or short commit hash, or the value HEAD. Can be used multiple times to specify multiple commits.
|
|
60
|
+
|
|
61
|
+
Output formats:
|
|
43
62
|
--csv Format output as CSV
|
|
44
63
|
--graph Format output as HTML page with Churn vs Complexity graph
|
|
45
64
|
--summary Output summary statistics (mean and median) for churn and complexity
|
|
65
|
+
--json Format output as JSON
|
|
66
|
+
--markdown Format output as Markdown
|
|
67
|
+
|
|
68
|
+
Modifiers:
|
|
46
69
|
--excluded PATTERN Exclude file paths including this string. Can be used multiple times.
|
|
47
70
|
--since YYYY-MM-DD Normal mode: Calculate churn after this date. Timetravel mode: calculate summaries from this date
|
|
48
71
|
-m, --month Calculate churn for the month leading up to the most recent commit
|
|
49
72
|
-q, --quarter Calculate churn for the quarter leading up to the most recent commit
|
|
50
73
|
-y, --year Calculate churn for the year leading up to the most recent commit
|
|
51
|
-
--
|
|
52
|
-
--delta SHA Identify changes between the specified commit (SHA) and the previous commit and annotate changed files with complexity score. SHA can be a full or short commit hash, or the value HEAD. Can be used multiple times to specify multiple commits.
|
|
74
|
+
--max-gamma N Maximum gamma score threshold for gate mode (default: 25)
|
|
53
75
|
--dry-run Echo the chosen options from the CLI
|
|
54
76
|
-h, --help Display help
|
|
55
77
|
--version Display version
|
|
@@ -67,15 +89,39 @@ Summaries in normal mode include a gamma score, which is an unnormalised harmoni
|
|
|
67
89
|
Summary points in timetravel mode instead include an alpha score, which is the same harmonic mean of churn and complexity, where churn and complexity values are normalised to a 0-1 range to avoid either churn or complexity dominating the score. The summary points also include a beta score, which is the geometric mean of the normalised churn and complexity values.
|
|
68
90
|
## Examples
|
|
69
91
|
|
|
70
|
-
|
|
92
|
+
```bash
|
|
93
|
+
# CSV churn vs complexity report for a Ruby project
|
|
94
|
+
churn_vs_complexity --ruby --csv my_ruby_project > ~/Desktop/ruby-demo.csv
|
|
95
|
+
|
|
96
|
+
# Interactive HTML graph for a Java project (excluding generated code)
|
|
97
|
+
churn_vs_complexity --java --graph --excluded generated-sources --since 2023-01-01 my_java_project > ~/Desktop/java-demo.html
|
|
98
|
+
|
|
99
|
+
# Monthly summary for a Python project
|
|
100
|
+
churn_vs_complexity --python --summary -m my_python_project
|
|
101
|
+
|
|
102
|
+
# Top refactoring hotspots ranked by risk
|
|
103
|
+
churn_vs_complexity --ruby --hotspots -q my_ruby_project
|
|
71
104
|
|
|
72
|
-
|
|
105
|
+
# CI quality gate (exits 1 if gamma exceeds threshold)
|
|
106
|
+
churn_vs_complexity --ruby --gate --max-gamma 30 my_ruby_project
|
|
73
107
|
|
|
74
|
-
|
|
108
|
+
# Triage specific files before a code review
|
|
109
|
+
churn_vs_complexity --go --triage src/server.go src/handler.go
|
|
75
110
|
|
|
76
|
-
|
|
111
|
+
# Compare codebase health between a branch and HEAD
|
|
112
|
+
churn_vs_complexity --ruby --diff origin/main --summary my_ruby_project
|
|
77
113
|
|
|
78
|
-
|
|
114
|
+
# Focus session: snapshot before and after a coding session
|
|
115
|
+
churn_vs_complexity --ruby --focus start my_ruby_project
|
|
116
|
+
# ... do some coding ...
|
|
117
|
+
churn_vs_complexity --ruby --focus end my_ruby_project
|
|
118
|
+
|
|
119
|
+
# Timetravel: track quality over time at 30-day intervals
|
|
120
|
+
churn_vs_complexity --java -m --since 2019-03-01 --timetravel 30 --graph my_java_project > ~/Desktop/timetravel.html
|
|
121
|
+
|
|
122
|
+
# Analyse complexity of specific commits
|
|
123
|
+
churn_vs_complexity --js --delta HEAD --summary my_js_project
|
|
124
|
+
```
|
|
79
125
|
|
|
80
126
|
## Development
|
|
81
127
|
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: churn_vs_complexity
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.6.
|
|
4
|
+
version: 1.6.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Erik T. Madsen
|
|
@@ -37,11 +37,11 @@ dependencies:
|
|
|
37
37
|
- - "~>"
|
|
38
38
|
- !ruby/object:Gem::Version
|
|
39
39
|
version: '2.1'
|
|
40
|
-
description:
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
40
|
+
description: Correlates file churn (how often files change) with complexity scores
|
|
41
|
+
to identify refactoring hotspots. Supports Ruby, JavaScript/TypeScript, Java, Python,
|
|
42
|
+
and Go. Modes include hotspots ranking, triage assessment, CI quality gate, diff
|
|
43
|
+
comparison, focus sessions, and timetravel history. Inspired by Michael Feathers'
|
|
44
|
+
article "Getting Empirical about Refactoring".
|
|
45
45
|
email:
|
|
46
46
|
- beatmadsen@gmail.com
|
|
47
47
|
executables:
|
|
@@ -181,6 +181,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
181
181
|
requirements: []
|
|
182
182
|
rubygems_version: 3.6.7
|
|
183
183
|
specification_version: 4
|
|
184
|
-
summary:
|
|
185
|
-
|
|
184
|
+
summary: Analyse churn vs complexity to find refactoring hotspots, gate CI quality,
|
|
185
|
+
triage risky files, and track codebase health over time.
|
|
186
186
|
test_files: []
|