pretty-git 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c00f6c3da7b91643351da8e2af40157ce5bc7e32948df975e93f08b0f87f8d2
-  data.tar.gz: c2e42b369d5c1bbda73dc33ae13bd35893619b572f26f6c50f8bdff4abd35f35
+  metadata.gz: 84571ab2bdd16f92dc31c1883a70433a140253ee0d0c66f1079453fc30f34419
+  data.tar.gz: 532ee3a2e436163f12821073297dc013e874746c5ac269f89c455826566c9f27
 SHA512:
-  metadata.gz: 149db95a428adbffe290dc4b1ef72351375d3cb7130cf59c0f9c98a467a6863874e5ae440120ef448cfa70938cb1274c91e999d568266c255d5985962fd04e25
-  data.tar.gz: 6c420e0e7144c3325610b26e81e7c30f37851b49443f55f70c6bf6808f0e6ee83b5ff3440f9bb077dc104f036298a44086147bfde4205d5a38b9abd8826784d7
+  metadata.gz: a0ba7918e1179ebfe3c4771c995b8b0eda978263be1fc6484f0f913e7b2129472272660e3c6dfb24a11f9d64300c26748d0b01fc14f0594e04e9b88cf244b96c
+  data.tar.gz: afaa201615eff920f1af0b86384964437fe7a119fc0d43d2a5ae10ee36211215b84c9607b92354646a20d691f0382f0b5d214385a214e8107596cdcf06eefcb2

data/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
+
+## [Unreleased]
+ 
+
+## [0.1.3] - 2025-08-14
+### Added
+- New analytics reports: `hotspots`, `churn`, `ownership` with sorting, scoring, and limits.
+- Exporters: CSV and Markdown support for new reports with dynamic headers via mapping constants.
+- Docs: Detailed sections for new reports in `README.md` and `README.ru.md` with usage and examples (CSV/JSON/YAML/XML).
+
+### Changed
+- Console: dispatching and rendering wired for new reports; consistent theming and width handling.
+- CLI/App: unified analytics dispatch for all reports.
+- Docs: public READMEs cleaned up from internal DR-* mentions; anchors and headings aligned (CSV).
+
+### Fixed
+- Minor documentation inaccuracies and anchor mismatches.
+
+
+## [0.1.2] - 2025-08-13
+### Added
+- Languages report: support multiple metrics — `bytes`, `files`, `loc`; dynamic columns in Console/CSV/Markdown; color and percent fields in output.
+- CLI: `--metric` option for the `languages` report with value validation.
+
+### Changed
+- 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.
+- Renderers: updated `csv`, `markdown`, and console renderers to work with dynamic metrics.
+- Internal specs updated: `specs/output_formats.md`, `specs/cli_spec.md`, `specs/languages_map.md`.
+
+### Fixed
+- 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`).
+- RuboCop: targeted suppressions for complex methods/classes and style fixes in `cli_helpers.rb`.
+
+## [0.1.1] - 2025-08-13
+### Changed
+- Release automation: added GitHub Actions workflow to publish gem on tags and open PR to Homebrew tap (`.github/workflows/release.yml`).
+- Documentation: README badges and installation instructions for Homebrew and RubyGems in `README.md` and `README.ru.md`.
+- Gemspec: bounded runtime dependencies for `csv` and `rexml` to satisfy RubyGems recommendations.
+
+### Fixed
+- Homebrew formula installation stability: formula installs gem into `libexec/vendor` and wraps `pretty-git` binary to avoid file collisions on reinstall.
+
+## [0.1.0] - 2025-08-13
+### Added
+- Languages report: bytes per language, percentages, sorting, limit.
+- Console: colorized languages section; terminal width handling via `TerminalWidth`.
+- Export: languages in Markdown/CSV/JSON/YAML/XML.
+- CLI: `languages` report wired into App and renderers.
+- Tests: analytics/languages specs (aggregation, globs, filename detection, limit).
+- Docs: English primary `README.md` + `README.ru.md` with language switcher.
+- Docs: Ignored directories and binary extensions list.
+- Docs: Added screenshot `PrettyGitConsoleLanguages.png`.
+
+### Changed
+- Analytics: exclude JSON from language mapping by default to avoid data skew.
+- Analytics: ignore Python env/cache directories by default.
+- Refactor: `ConsoleRenderer` split (LanguagesSection, TerminalWidth); reduced complexity.
+- App: extracted `analytics_for` from `App#run`.
+
+### Fixed
+- RuboCop violations in new specs and minor guard clause spacing.

data/README.md

@@ -14,7 +14,7 @@
   <br>
 </p>
 
-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.
+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.
 
 — License: MIT.
 
@@ -35,10 +35,13 @@ Generator of rich reports for a local Git repository: summary, activity, authors
   - [files — by files](#files--by-files)
   - [heatmap — commit heatmap](#heatmap--commit-heatmap)
   - [languages — languages](#languages--languages)
+  - [hotspots — hotspots (risky files)](#hotspots--hotspots-risky-files)
+  - [churn — code churn by file](#churn--code-churn-by-file)
+  - [ownership — code ownership](#ownership--code-ownership)
 - [Exports](#exports)
   - [Console](#console)
   - [JSON](#json)
-  - [CSV (DR-001)](#csv-dr-001)
+  - [CSV](#csv)
   - [Markdown](#markdown)
   - [YAML](#yaml)
   - [XML](#xml)
@@ -49,31 +52,31 @@ Generator of rich reports for a local Git repository: summary, activity, authors
 - [Development](#development)
 - [License](#license)
 
-## Features
-* **Reports**: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`.
+## ✨ Features
+* **Reports**: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`, `hotspots`, `churn`, `ownership`.
 * **Filters**: branches, authors, paths, time period.
 * **Exports**: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
 * **Output**: to stdout or file via `--out`.
 
-## Requirements
+## ⚙️ Requirements
 * **Ruby**: >= 3.4 (recommended 3.4.x)
 * **Git**: installed and available in `PATH`
 
-## Installation
+## 📦 Installation
 
-### Homebrew (recommended)
+### 🍺 Homebrew (recommended)
 ```bash
 brew tap MikoMikocchi/tap
 brew install pretty-git
 ```
 
-### RubyGems
+### ♦️ RubyGems
 ```bash
 gem install pretty-git
 ```
 Choose one:
 
-1) From source (recommended for development)
+1) 🛠️ From source (recommended for development)
 
 ```bash
 git clone <repo_url>
@@ -83,14 +86,14 @@ bin/setup
 bundle exec bin/pretty-git --help
 ```
 
-2) As a gem (after the first release)
+2) ♦️ As a gem (after the first release)
 
 ```bash
 gem install pretty-git
 pretty-git --version
 ```
 
-3) Via Bundler
+3) 📦 Via Bundler
 
 ```ruby
 # Gemfile
@@ -101,7 +104,7 @@ bundle install
 bundle exec pretty-git --help
 ```
 
-## Quick Start
+## 🚀 Quick Start
 ```bash
 # Repository summary to console
 bundle exec bin/pretty-git summary .
@@ -114,26 +117,27 @@ bundle exec bin/pretty-git activity . --time-bucket week --since 2025-01-01 \
   --paths app,lib --format csv --out activity.csv
 ```
 
-## CLI and Options
+## 🧰 CLI and Options
 General form:
 
 ```bash
 pretty-git <report> <repo_path> [options]
 ```
 
-Available reports: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`.
+Available reports: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`, `hotspots`, `churn`, `ownership`.
 
 Key options:
 * **--format, -f** `console|json|csv|md|yaml|xml` (default `console`)
 * **--out, -o** Path to write output file
 * **--limit, -l** Number of items shown; `all` or `0` — no limit
 * **--time-bucket** `day|week|month` (for `activity`)
-* **--since/--until** Date/time in ISO8601 or `YYYY-MM-DD` (DR-005)
+* **--since/--until** Date/time in ISO8601 or `YYYY-MM-DD`
 * **--branch** Multi-option, can be specified multiple times
 * **--author/--exclude-author** Filter by authors
 * **--path/--exclude-path** Filter by paths (comma-separated or repeated option)
 * **--no-color** Disable colors in console
 * **--theme** `basic|bright|mono` — console theme (default `basic`; `mono` forces monochrome)
+* **--metric** `bytes|files|loc` — metric for `languages` report (default `bytes`)
 
 Examples with multiple values:
 
@@ -164,15 +168,15 @@ pretty-git authors . --format csv --out authors.csv
 * `1` — user error (unknown report/format, bad arguments)
 * `2` — system error (git error etc.)
 
-## Reports and Examples
+## 📊 Reports and Examples
 
-### summary — repository summary
+### 🧭 summary — repository summary
 ```bash
 pretty-git summary . --format json
 ```
 Contains totals (commits, authors, additions, deletions) and top authors/files.
 
-### activity — activity (day/week/month)
+### 📆 activity — activity (day/week/month)
 ```bash
 pretty-git activity . --time-bucket week --format csv
 ```
@@ -185,7 +189,7 @@ JSON example:
 ]
 ```
 
-### authors — by authors
+### 👤 authors — by authors
 ```bash
 pretty-git authors . --format md --limit 10
 ```
@@ -198,7 +202,7 @@ Markdown example:
 | Bob   | b@example.com | 1 | 2 | 0 | 2.0 |
 ```
 
-### files — by files
+### 📁 files — by files
 ```bash
 pretty-git files . --paths app,lib --format csv
 ```
@@ -218,7 +222,7 @@ XML example:
 </files>
 ```
 
-### heatmap — commit heatmap
+### 🔥 heatmap — commit heatmap
 ```bash
 pretty-git heatmap . --format json
 ```
@@ -230,11 +234,11 @@ dow,hour,commits
 1,11,7
 ```
 
-### languages — languages
+### 🈺 languages — languages
 ```bash
 pretty-git languages . --format md --limit 10
 ```
-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.
+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.
 
 Console example:
 ```text
@@ -252,7 +256,7 @@ Markdown      1200     1.7
 Notes:
 - **Detection**: by file extensions and certain filenames (`Makefile`, `Dockerfile`).
 - **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/`.
-- **JSON**: JSON is not counted as a language by default to avoid data files skewing statistics.
+- **JSON**: JSON is included as a language. If large data files skew results, consider narrowing with `--path/--exclude-path`.
 - **Path filters**: use `--path/--exclude-path` (glob patterns supported) to focus on relevant areas.
 - **Limit**: `--limit N` restricts number of rows; `0`/`all` — no limit.
 - **Console colors**: language names use approximate GitHub colors; `--no-color` disables, `--theme mono` makes output monochrome.
@@ -260,14 +264,95 @@ Notes:
 See also: [Ignored directories and files](#ignored-directories-and-files).
 
 Export:
-- CSV/MD: columns — `language,bytes,percent`.
-- JSON/YAML/XML: full report structure including metadata (`report`, `generated_at`, `repo_path`).
+- CSV/MD: columns are dynamic — `language,<metric>,percent`. Markdown also includes a `color` column.
+- JSON/YAML/XML: full report structure including per-language `color` and metadata (`report`, `generated_at`, `repo_path`).
 
-## Exports
+### ⚠️ hotspots — hotspots (risky files)
+```bash
+pretty-git hotspots . --format csv --limit 20
+```
+Highlights riskier files combining change frequency and magnitude.
+
+CSV columns: `path,score,commits,additions,deletions,changes`.
+
+Example:
+```csv
+path,score,commits,additions,deletions,changes
+lib/a.rb,9.5,12,300,220,520
+app/b.rb,7.1,8,140,60,200
+```
+
+JSON example:
+```json
+{
+  "report": "hotspots",
+  "generated_at": "2025-01-31T00:00:00Z",
+  "repo_path": ".",
+  "items": [
+    {"path": "lib/a.rb", "score": 9.5, "commits": 12, "additions": 300, "deletions": 220, "changes": 520}
+  ]
+}
+```
+
+### 🔄 churn — code churn by file
+```bash
+pretty-git churn . --format md --limit 20
+```
+Measures code churn (amount of code changing frequently).
+
+CSV columns: `path,churn,commits,additions,deletions`.
+
+Markdown example:
+```markdown
+| path | churn | commits | additions | deletions |
+|---|---:|---:|---:|---:|
+| lib/a.rb | 520 | 12 | 300 | 220 |
+```
+
+YAML example:
+```yaml
+report: churn
+generated_at: '2025-01-31T00:00:00Z'
+repo_path: .
+items:
+  - path: lib/a.rb
+    churn: 520
+    commits: 12
+    additions: 300
+    deletions: 220
+```
+
+### 🏷️ ownership — code ownership
+```bash
+pretty-git ownership . --format csv --limit 50
+```
+Shows file ownership concentration per primary owner.
+
+CSV columns: `path,owner,owner_share,authors`.
+
+Notes:
+- `owner`: author identifier (name/email) with the largest share of edits.
+- `owner_share`: percent of edits by the owner (0..100).
+- `authors`: total unique authors who edited the file.
+
+XML example:
+```xml
+<ownership>
+  <report>ownership</report>
+  <generated_at>2025-01-31T00:00:00Z</generated_at>
+  <repo_path>.</repo_path>
+  <items>
+    <item path="lib/a.rb" owner="Alice <a@example.com>" owner_share="82.5" authors="2"/>
+  </items>
+  
+</ownership>
+```
+
+## 📤 Exports
 
 Below are exact serialization rules for each format to ensure compatibility with common tools (Excel, BI, CI, etc.).
 
-### Console
+### 🖥️ Console
 ![Console output — basic theme](docs/images/PrettyGitConsole.png)
 _Example terminal output (theme: basic)._ 
 * **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)._
 * **Purpose**: human-readable terminal output.
 * **Layout**: boxed tables, auto-truncation of long values.
 
-### JSON
+### 🧾 JSON
 * **Keys**: `snake_case`.
 * **Numbers**: integers/floats without localization (dot decimal separator).
 * **Boolean**: `true/false`; **null**: `null`.
@@ -291,7 +376,7 @@ _Example terminal output (theme: basic)._
   {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
   ```
 
-### CSV (DR-001)
+### CSV
 * **Structure**: flat table, first line is header.
 * **Encoding**: UTF‑8 without BOM.
 * **Delimiter**: comma `,`.
@@ -310,7 +395,7 @@ _Example terminal output (theme: basic)._
   Bob,b@example.com,1,2,0,2.0
   ```
 
-### Markdown
+### 📝 Markdown
 * **Tables**: GitHub Flavored Markdown.
 * **Alignment**: numeric columns are right-aligned (`---:`).
 * **Encoding/line endings**: UTF‑8, LF.
@@ -323,7 +408,7 @@ _Example terminal output (theme: basic)._
   | app/models/user.rb | 42 | 2100 | 1400 |
   ```
 
-### YAML
+### 📄 YAML
 * **Structure**: full result hierarchy.
 * **Keys**: serialized as strings.
 * **Numbers/boolean/null**: standard YAML (`123`, `true/false`, `null`).
@@ -343,7 +428,7 @@ _Example terminal output (theme: basic)._
       commits: 1
   ```
 
-### XML
+### 🗂️ XML
 * **Structure**: elements correspond to keys; arrays — repeated `<item>` or specialized tags.
 * **Attributes**: for compact rows (e.g., files report) main fields may be attributes.
 * **Text nodes**: used for scalar values when needed.
@@ -361,7 +446,7 @@ _Example terminal output (theme: basic)._
   </authors>
   ```
 
-## Ignored directories and files
+## 🚫 Ignored directories and files
 
 To keep language statistics meaningful, certain directories and file types are skipped by default.
 
@@ -386,16 +471,16 @@ vendor, node_modules, .git, .bundle, dist, build, out, target, coverage,
 
 These lists mirror the implementation in `lib/pretty_git/analytics/languages.rb` and may evolve.
 
-## Determinism and Sorting
+## 🔁 Determinism and Sorting
 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.
 
-## Windows Notes
+## 🪟 Windows Notes
 Primary targets — macOS/Linux. Windows is supported best‑effort:
 * Running via Git Bash/WSL is OK
 * Colors can be disabled by `--no-color`
 * Carefully quote arguments when working with paths
 
-## Diagnostics and Errors
+## 🩺 Diagnostics and Errors
 Typical issues and solutions:
 
 * **Unknown report/format** — check the first argument and `--format`.
@@ -404,12 +489,12 @@ Typical issues and solutions:
 * **Empty result** — check your filters (`--since/--until`, `--branch`, `--path`); your selection might be too narrow.
 * **CSV encoding issues** — files are saved as UTF‑8; when opening in Excel, pick UTF‑8.
 
-## FAQ
+## ❓ FAQ
 * **Why Ruby 3.4+?** The project uses dependencies aligned with Ruby 3.4+ and targets the current ecosystem.
 * **New formats?** Yes, add a renderer under `lib/pretty_git/render/` and wire it in the app.
 * **Where does data come from?** From system `git` via CLI calls.
 
-## Development
+## 🛠️ Development
 ```bash
 # Install deps
 bin/setup
@@ -421,5 +506,5 @@ bundle exec rubocop
 
 Style — RuboCop clean. Tests cover aggregators, renderers, CLI, and integration scenarios (determinism, format correctness).
 
-## License
+## 📄 License
 MIT © Contributors