pretty-git 0.1.1 → 0.1.3

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1c00f6c3da7b91643351da8e2af40157ce5bc7e32948df975e93f08b0f87f8d2
4
- data.tar.gz: c2e42b369d5c1bbda73dc33ae13bd35893619b572f26f6c50f8bdff4abd35f35
3
+ metadata.gz: 84571ab2bdd16f92dc31c1883a70433a140253ee0d0c66f1079453fc30f34419
4
+ data.tar.gz: 532ee3a2e436163f12821073297dc013e874746c5ac269f89c455826566c9f27
5
5
  SHA512:
6
- metadata.gz: 149db95a428adbffe290dc4b1ef72351375d3cb7130cf59c0f9c98a467a6863874e5ae440120ef448cfa70938cb1274c91e999d568266c255d5985962fd04e25
7
- data.tar.gz: 6c420e0e7144c3325610b26e81e7c30f37851b49443f55f70c6bf6808f0e6ee83b5ff3440f9bb077dc104f036298a44086147bfde4205d5a38b9abd8826784d7
6
+ metadata.gz: a0ba7918e1179ebfe3c4771c995b8b0eda978263be1fc6484f0f913e7b2129472272660e3c6dfb24a11f9d64300c26748d0b01fc14f0594e04e9b88cf244b96c
7
+ data.tar.gz: afaa201615eff920f1af0b86384964437fe7a119fc0d43d2a5ae10ee36211215b84c9607b92354646a20d691f0382f0b5d214385a214e8107596cdcf06eefcb2
data/CHANGELOG.md ADDED
@@ -0,0 +1,66 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
6
+
7
+ ## [Unreleased]
8
+
9
+
10
+ ## [0.1.3] - 2025-08-14
11
+ ### Added
12
+ - New analytics reports: `hotspots`, `churn`, `ownership` with sorting, scoring, and limits.
13
+ - Exporters: CSV and Markdown support for new reports with dynamic headers via mapping constants.
14
+ - Docs: Detailed sections for new reports in `README.md` and `README.ru.md` with usage and examples (CSV/JSON/YAML/XML).
15
+
16
+ ### Changed
17
+ - Console: dispatching and rendering wired for new reports; consistent theming and width handling.
18
+ - CLI/App: unified analytics dispatch for all reports.
19
+ - Docs: public READMEs cleaned up from internal DR-* mentions; anchors and headings aligned (CSV).
20
+
21
+ ### Fixed
22
+ - Minor documentation inaccuracies and anchor mismatches.
23
+
24
+
25
+ ## [0.1.2] - 2025-08-13
26
+ ### Added
27
+ - Languages report: support multiple metrics — `bytes`, `files`, `loc`; dynamic columns in Console/CSV/Markdown; color and percent fields in output.
28
+ - CLI: `--metric` option for the `languages` report with value validation.
29
+
30
+ ### Changed
31
+ - Languages: JSON language reinstated in the mapping and color scheme; sorting and percent calculations are based on the selected metric; percentages rounded to two decimals.
32
+ - Renderers: updated `csv`, `markdown`, and console renderers to work with dynamic metrics.
33
+ - Internal specs updated: `specs/output_formats.md`, `specs/cli_spec.md`, `specs/languages_map.md`.
34
+
35
+ ### Fixed
36
+ - Git provider: correct commit counting — emit a new commit when a header is read and remove the record separator from the subject (`lib/pretty_git/git/provider.rb`).
37
+ - RuboCop: targeted suppressions for complex methods/classes and style fixes in `cli_helpers.rb`.
38
+
39
+ ## [0.1.1] - 2025-08-13
40
+ ### Changed
41
+ - Release automation: added GitHub Actions workflow to publish gem on tags and open PR to Homebrew tap (`.github/workflows/release.yml`).
42
+ - Documentation: README badges and installation instructions for Homebrew and RubyGems in `README.md` and `README.ru.md`.
43
+ - Gemspec: bounded runtime dependencies for `csv` and `rexml` to satisfy RubyGems recommendations.
44
+
45
+ ### Fixed
46
+ - Homebrew formula installation stability: formula installs gem into `libexec/vendor` and wraps `pretty-git` binary to avoid file collisions on reinstall.
47
+
48
+ ## [0.1.0] - 2025-08-13
49
+ ### Added
50
+ - Languages report: bytes per language, percentages, sorting, limit.
51
+ - Console: colorized languages section; terminal width handling via `TerminalWidth`.
52
+ - Export: languages in Markdown/CSV/JSON/YAML/XML.
53
+ - CLI: `languages` report wired into App and renderers.
54
+ - Tests: analytics/languages specs (aggregation, globs, filename detection, limit).
55
+ - Docs: English primary `README.md` + `README.ru.md` with language switcher.
56
+ - Docs: Ignored directories and binary extensions list.
57
+ - Docs: Added screenshot `PrettyGitConsoleLanguages.png`.
58
+
59
+ ### Changed
60
+ - Analytics: exclude JSON from language mapping by default to avoid data skew.
61
+ - Analytics: ignore Python env/cache directories by default.
62
+ - Refactor: `ConsoleRenderer` split (LanguagesSection, TerminalWidth); reduced complexity.
63
+ - App: extracted `analytics_for` from `App#run`.
64
+
65
+ ### Fixed
66
+ - RuboCop violations in new specs and minor guard clause spacing.
data/README.md CHANGED
@@ -14,7 +14,7 @@
14
14
  <br>
15
15
  </p>
16
16
 
17
- Generator of rich reports for a local Git repository: summary, activity, authors, files, heatmap, languages. Output to Console and formats: JSON, CSV, Markdown, YAML, XML.
17
+ Generator of rich reports for a local Git repository: summary, activity, authors, files, heatmap, languages, hotspots, churn, ownership. Output to Console and formats: JSON, CSV, Markdown, YAML, XML.
18
18
 
19
19
  — License: MIT.
20
20
 
@@ -35,10 +35,13 @@ Generator of rich reports for a local Git repository: summary, activity, authors
35
35
  - [files — by files](#files--by-files)
36
36
  - [heatmap — commit heatmap](#heatmap--commit-heatmap)
37
37
  - [languages — languages](#languages--languages)
38
+ - [hotspots — hotspots (risky files)](#hotspots--hotspots-risky-files)
39
+ - [churn — code churn by file](#churn--code-churn-by-file)
40
+ - [ownership — code ownership](#ownership--code-ownership)
38
41
  - [Exports](#exports)
39
42
  - [Console](#console)
40
43
  - [JSON](#json)
41
- - [CSV (DR-001)](#csv-dr-001)
44
+ - [CSV](#csv)
42
45
  - [Markdown](#markdown)
43
46
  - [YAML](#yaml)
44
47
  - [XML](#xml)
@@ -49,31 +52,31 @@ Generator of rich reports for a local Git repository: summary, activity, authors
49
52
  - [Development](#development)
50
53
  - [License](#license)
51
54
 
52
- ## Features
53
- * **Reports**: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`.
55
+ ## Features
56
+ * **Reports**: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`, `hotspots`, `churn`, `ownership`.
54
57
  * **Filters**: branches, authors, paths, time period.
55
58
  * **Exports**: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
56
59
  * **Output**: to stdout or file via `--out`.
57
60
 
58
- ## Requirements
61
+ ## ⚙️ Requirements
59
62
  * **Ruby**: >= 3.4 (recommended 3.4.x)
60
63
  * **Git**: installed and available in `PATH`
61
64
 
62
- ## Installation
65
+ ## 📦 Installation
63
66
 
64
- ### Homebrew (recommended)
67
+ ### 🍺 Homebrew (recommended)
65
68
  ```bash
66
69
  brew tap MikoMikocchi/tap
67
70
  brew install pretty-git
68
71
  ```
69
72
 
70
- ### RubyGems
73
+ ### ♦️ RubyGems
71
74
  ```bash
72
75
  gem install pretty-git
73
76
  ```
74
77
  Choose one:
75
78
 
76
- 1) From source (recommended for development)
79
+ 1) 🛠️ From source (recommended for development)
77
80
 
78
81
  ```bash
79
82
  git clone <repo_url>
@@ -83,14 +86,14 @@ bin/setup
83
86
  bundle exec bin/pretty-git --help
84
87
  ```
85
88
 
86
- 2) As a gem (after the first release)
89
+ 2) ♦️ As a gem (after the first release)
87
90
 
88
91
  ```bash
89
92
  gem install pretty-git
90
93
  pretty-git --version
91
94
  ```
92
95
 
93
- 3) Via Bundler
96
+ 3) 📦 Via Bundler
94
97
 
95
98
  ```ruby
96
99
  # Gemfile
@@ -101,7 +104,7 @@ bundle install
101
104
  bundle exec pretty-git --help
102
105
  ```
103
106
 
104
- ## Quick Start
107
+ ## 🚀 Quick Start
105
108
  ```bash
106
109
  # Repository summary to console
107
110
  bundle exec bin/pretty-git summary .
@@ -114,26 +117,27 @@ bundle exec bin/pretty-git activity . --time-bucket week --since 2025-01-01 \
114
117
  --paths app,lib --format csv --out activity.csv
115
118
  ```
116
119
 
117
- ## CLI and Options
120
+ ## 🧰 CLI and Options
118
121
  General form:
119
122
 
120
123
  ```bash
121
124
  pretty-git <report> <repo_path> [options]
122
125
  ```
123
126
 
124
- Available reports: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`.
127
+ Available reports: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`, `hotspots`, `churn`, `ownership`.
125
128
 
126
129
  Key options:
127
130
  * **--format, -f** `console|json|csv|md|yaml|xml` (default `console`)
128
131
  * **--out, -o** Path to write output file
129
132
  * **--limit, -l** Number of items shown; `all` or `0` — no limit
130
133
  * **--time-bucket** `day|week|month` (for `activity`)
131
- * **--since/--until** Date/time in ISO8601 or `YYYY-MM-DD` (DR-005)
134
+ * **--since/--until** Date/time in ISO8601 or `YYYY-MM-DD`
132
135
  * **--branch** Multi-option, can be specified multiple times
133
136
  * **--author/--exclude-author** Filter by authors
134
137
  * **--path/--exclude-path** Filter by paths (comma-separated or repeated option)
135
138
  * **--no-color** Disable colors in console
136
139
  * **--theme** `basic|bright|mono` — console theme (default `basic`; `mono` forces monochrome)
140
+ * **--metric** `bytes|files|loc` — metric for `languages` report (default `bytes`)
137
141
 
138
142
  Examples with multiple values:
139
143
 
@@ -164,15 +168,15 @@ pretty-git authors . --format csv --out authors.csv
164
168
  * `1` — user error (unknown report/format, bad arguments)
165
169
  * `2` — system error (git error etc.)
166
170
 
167
- ## Reports and Examples
171
+ ## 📊 Reports and Examples
168
172
 
169
- ### summary — repository summary
173
+ ### 🧭 summary — repository summary
170
174
  ```bash
171
175
  pretty-git summary . --format json
172
176
  ```
173
177
  Contains totals (commits, authors, additions, deletions) and top authors/files.
174
178
 
175
- ### activity — activity (day/week/month)
179
+ ### 📆 activity — activity (day/week/month)
176
180
  ```bash
177
181
  pretty-git activity . --time-bucket week --format csv
178
182
  ```
@@ -185,7 +189,7 @@ JSON example:
185
189
  ]
186
190
  ```
187
191
 
188
- ### authors — by authors
192
+ ### 👤 authors — by authors
189
193
  ```bash
190
194
  pretty-git authors . --format md --limit 10
191
195
  ```
@@ -198,7 +202,7 @@ Markdown example:
198
202
  | Bob | b@example.com | 1 | 2 | 0 | 2.0 |
199
203
  ```
200
204
 
201
- ### files — by files
205
+ ### 📁 files — by files
202
206
  ```bash
203
207
  pretty-git files . --paths app,lib --format csv
204
208
  ```
@@ -218,7 +222,7 @@ XML example:
218
222
  </files>
219
223
  ```
220
224
 
221
- ### heatmap — commit heatmap
225
+ ### 🔥 heatmap — commit heatmap
222
226
  ```bash
223
227
  pretty-git heatmap . --format json
224
228
  ```
@@ -230,11 +234,11 @@ dow,hour,commits
230
234
  1,11,7
231
235
  ```
232
236
 
233
- ### languages — languages
237
+ ### 🈺 languages — languages
234
238
  ```bash
235
239
  pretty-git languages . --format md --limit 10
236
240
  ```
237
- Determines language distribution in a repository by summing file bytes per language (similar to GitHub Linguist). Output includes language, total size (bytes) and percent share.
241
+ Determines language distribution in a repository. Supports multiple metrics: `bytes`, `files`, `loc` (default: `bytes`). Output includes language, selected metric column, and percent share; console shows language colors.
238
242
 
239
243
  Console example:
240
244
  ```text
@@ -252,7 +256,7 @@ Markdown 1200 1.7
252
256
  Notes:
253
257
  - **Detection**: by file extensions and certain filenames (`Makefile`, `Dockerfile`).
254
258
  - **Exclusions**: binary files and "vendor"-like directories are ignored. By default `vendor/`, `node_modules/`, `.git/`, build artifacts and caches are skipped. For Python projects additional directories are skipped: `.venv/`, `venv/`, `env/`, `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.tox/`, `.eggs/`, `.ruff_cache/`, `.ipynb_checkpoints/`.
255
- - **JSON**: JSON is not counted as a language by default to avoid data files skewing statistics.
259
+ - **JSON**: JSON is included as a language. If large data files skew results, consider narrowing with `--path/--exclude-path`.
256
260
  - **Path filters**: use `--path/--exclude-path` (glob patterns supported) to focus on relevant areas.
257
261
  - **Limit**: `--limit N` restricts number of rows; `0`/`all` — no limit.
258
262
  - **Console colors**: language names use approximate GitHub colors; `--no-color` disables, `--theme mono` makes output monochrome.
@@ -260,14 +264,95 @@ Notes:
260
264
  See also: [Ignored directories and files](#ignored-directories-and-files).
261
265
 
262
266
  Export:
263
- - CSV/MD: columns — `language,bytes,percent`.
264
- - JSON/YAML/XML: full report structure including metadata (`report`, `generated_at`, `repo_path`).
267
+ - CSV/MD: columns are dynamic — `language,<metric>,percent`. Markdown also includes a `color` column.
268
+ - JSON/YAML/XML: full report structure including per-language `color` and metadata (`report`, `generated_at`, `repo_path`).
265
269
 
266
- ## Exports
270
+ ### ⚠️ hotspots — hotspots (risky files)
271
+ ```bash
272
+ pretty-git hotspots . --format csv --limit 20
273
+ ```
274
+ Highlights riskier files combining change frequency and magnitude.
275
+
276
+ CSV columns: `path,score,commits,additions,deletions,changes`.
277
+
278
+ Example:
279
+ ```csv
280
+ path,score,commits,additions,deletions,changes
281
+ lib/a.rb,9.5,12,300,220,520
282
+ app/b.rb,7.1,8,140,60,200
283
+ ```
284
+
285
+ JSON example:
286
+ ```json
287
+ {
288
+ "report": "hotspots",
289
+ "generated_at": "2025-01-31T00:00:00Z",
290
+ "repo_path": ".",
291
+ "items": [
292
+ {"path": "lib/a.rb", "score": 9.5, "commits": 12, "additions": 300, "deletions": 220, "changes": 520}
293
+ ]
294
+ }
295
+ ```
296
+
297
+ ### 🔄 churn — code churn by file
298
+ ```bash
299
+ pretty-git churn . --format md --limit 20
300
+ ```
301
+ Measures code churn (amount of code changing frequently).
302
+
303
+ CSV columns: `path,churn,commits,additions,deletions`.
304
+
305
+ Markdown example:
306
+ ```markdown
307
+ | path | churn | commits | additions | deletions |
308
+ |---|---:|---:|---:|---:|
309
+ | lib/a.rb | 520 | 12 | 300 | 220 |
310
+ ```
311
+
312
+ YAML example:
313
+ ```yaml
314
+ report: churn
315
+ generated_at: '2025-01-31T00:00:00Z'
316
+ repo_path: .
317
+ items:
318
+ - path: lib/a.rb
319
+ churn: 520
320
+ commits: 12
321
+ additions: 300
322
+ deletions: 220
323
+ ```
324
+
325
+ ### 🏷️ ownership — code ownership
326
+ ```bash
327
+ pretty-git ownership . --format csv --limit 50
328
+ ```
329
+ Shows file ownership concentration per primary owner.
330
+
331
+ CSV columns: `path,owner,owner_share,authors`.
332
+
333
+ Notes:
334
+ - `owner`: author identifier (name/email) with the largest share of edits.
335
+ - `owner_share`: percent of edits by the owner (0..100).
336
+ - `authors`: total unique authors who edited the file.
337
+
338
+ XML example:
339
+ ```xml
340
+ <ownership>
341
+ <report>ownership</report>
342
+ <generated_at>2025-01-31T00:00:00Z</generated_at>
343
+ <repo_path>.</repo_path>
344
+ <items>
345
+ <item path="lib/a.rb" owner="Alice <a@example.com>" owner_share="82.5" authors="2"/>
346
+ </items>
347
+
348
+ </ownership>
349
+ ```
350
+
351
+ ## 📤 Exports
267
352
 
268
353
  Below are exact serialization rules for each format to ensure compatibility with common tools (Excel, BI, CI, etc.).
269
354
 
270
- ### Console
355
+ ### 🖥️ Console
271
356
  ![Console output — basic theme](docs/images/PrettyGitConsole.png)
272
357
  _Example terminal output (theme: basic)._
273
358
  * **Colors**: headers and table heads highlighted; totals: `commits` — yellow, `+additions` — green, `-deletions` — red. `--no-color` fully disables coloring.
@@ -278,7 +363,7 @@ _Example terminal output (theme: basic)._
278
363
  * **Purpose**: human-readable terminal output.
279
364
  * **Layout**: boxed tables, auto-truncation of long values.
280
365
 
281
- ### JSON
366
+ ### 🧾 JSON
282
367
  * **Keys**: `snake_case`.
283
368
  * **Numbers**: integers/floats without localization (dot decimal separator).
284
369
  * **Boolean**: `true/false`; **null**: `null`.
@@ -291,7 +376,7 @@ _Example terminal output (theme: basic)._
291
376
  {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
292
377
  ```
293
378
 
294
- ### CSV (DR-001)
379
+ ### CSV
295
380
  * **Structure**: flat table, first line is header.
296
381
  * **Encoding**: UTF‑8 without BOM.
297
382
  * **Delimiter**: comma `,`.
@@ -310,7 +395,7 @@ _Example terminal output (theme: basic)._
310
395
  Bob,b@example.com,1,2,0,2.0
311
396
  ```
312
397
 
313
- ### Markdown
398
+ ### 📝 Markdown
314
399
  * **Tables**: GitHub Flavored Markdown.
315
400
  * **Alignment**: numeric columns are right-aligned (`---:`).
316
401
  * **Encoding/line endings**: UTF‑8, LF.
@@ -323,7 +408,7 @@ _Example terminal output (theme: basic)._
323
408
  | app/models/user.rb | 42 | 2100 | 1400 |
324
409
  ```
325
410
 
326
- ### YAML
411
+ ### 📄 YAML
327
412
  * **Structure**: full result hierarchy.
328
413
  * **Keys**: serialized as strings.
329
414
  * **Numbers/boolean/null**: standard YAML (`123`, `true/false`, `null`).
@@ -343,7 +428,7 @@ _Example terminal output (theme: basic)._
343
428
  commits: 1
344
429
  ```
345
430
 
346
- ### XML
431
+ ### 🗂️ XML
347
432
  * **Structure**: elements correspond to keys; arrays — repeated `<item>` or specialized tags.
348
433
  * **Attributes**: for compact rows (e.g., files report) main fields may be attributes.
349
434
  * **Text nodes**: used for scalar values when needed.
@@ -361,7 +446,7 @@ _Example terminal output (theme: basic)._
361
446
  </authors>
362
447
  ```
363
448
 
364
- ## Ignored directories and files
449
+ ## 🚫 Ignored directories and files
365
450
 
366
451
  To keep language statistics meaningful, certain directories and file types are skipped by default.
367
452
 
@@ -386,16 +471,16 @@ vendor, node_modules, .git, .bundle, dist, build, out, target, coverage,
386
471
 
387
472
  These lists mirror the implementation in `lib/pretty_git/analytics/languages.rb` and may evolve.
388
473
 
389
- ## Determinism and Sorting
474
+ ## 🔁 Determinism and Sorting
390
475
  Output is deterministic given the same input. Sorting for files/authors: by changes (desc), then by commits (desc), then by path/name (asc). Limits are applied after sorting; `all` or `0` means no limit.
391
476
 
392
- ## Windows Notes
477
+ ## 🪟 Windows Notes
393
478
  Primary targets — macOS/Linux. Windows is supported best‑effort:
394
479
  * Running via Git Bash/WSL is OK
395
480
  * Colors can be disabled by `--no-color`
396
481
  * Carefully quote arguments when working with paths
397
482
 
398
- ## Diagnostics and Errors
483
+ ## 🩺 Diagnostics and Errors
399
484
  Typical issues and solutions:
400
485
 
401
486
  * **Unknown report/format** — check the first argument and `--format`.
@@ -404,12 +489,12 @@ Typical issues and solutions:
404
489
  * **Empty result** — check your filters (`--since/--until`, `--branch`, `--path`); your selection might be too narrow.
405
490
  * **CSV encoding issues** — files are saved as UTF‑8; when opening in Excel, pick UTF‑8.
406
491
 
407
- ## FAQ
492
+ ## FAQ
408
493
  * **Why Ruby 3.4+?** The project uses dependencies aligned with Ruby 3.4+ and targets the current ecosystem.
409
494
  * **New formats?** Yes, add a renderer under `lib/pretty_git/render/` and wire it in the app.
410
495
  * **Where does data come from?** From system `git` via CLI calls.
411
496
 
412
- ## Development
497
+ ## 🛠️ Development
413
498
  ```bash
414
499
  # Install deps
415
500
  bin/setup
@@ -421,5 +506,5 @@ bundle exec rubocop
421
506
 
422
507
  Style — RuboCop clean. Tests cover aggregators, renderers, CLI, and integration scenarios (determinism, format correctness).
423
508
 
424
- ## License
509
+ ## 📄 License
425
510
  MIT © Contributors