pretty-git 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c00f6c3da7b91643351da8e2af40157ce5bc7e32948df975e93f08b0f87f8d2
-  data.tar.gz: c2e42b369d5c1bbda73dc33ae13bd35893619b572f26f6c50f8bdff4abd35f35
+  metadata.gz: 2200709c51eb32592b4fe79a3acea35178fab498dbd781edcc4237ceabfa00c7
+  data.tar.gz: c83bdd9cb01c5b345dfa52f0f1d35a03ed167a78307a6a085819453d96c88293
 SHA512:
-  metadata.gz: 149db95a428adbffe290dc4b1ef72351375d3cb7130cf59c0f9c98a467a6863874e5ae440120ef448cfa70938cb1274c91e999d568266c255d5985962fd04e25
-  data.tar.gz: 6c420e0e7144c3325610b26e81e7c30f37851b49443f55f70c6bf6808f0e6ee83b5ff3440f9bb077dc104f036298a44086147bfde4205d5a38b9abd8826784d7
+  metadata.gz: 1d23439b48405024896bec5e173a8573ce0b8fb1b8d1872b98d0201d4cceb85bd07f246f0d2e0a406d1c9f25d40f903280536b32e8dd030dfb04f801bc617d32
+  data.tar.gz: 3137c6d5b19ecbc496f14c9db9395a598d7e7bb8f33f5863db6eb8f3bf9141db141bd2429b8346101a53d79b4a4d687a4b430ad252e1f99bc58f1f2ea0bc6ac4

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# 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.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

@@ -61,19 +61,19 @@ Generator of rich reports for a local Git repository: summary, activity, authors
 
 ## 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 +83,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
@@ -134,6 +134,7 @@ Key options:
 * **--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:
 
@@ -234,7 +235,7 @@ dow,hour,commits
 ```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 +253,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,8 +261,8 @@ 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
 
@@ -291,7 +292,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 `,`.

data/README.ru.md

@@ -0,0 +1,427 @@
+# Pretty Git
+
+[![CI](https://github.com/MikoMikocchi/pretty-git/actions/workflows/ci.yml/badge.svg)](https://github.com/MikoMikocchi/pretty-git/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/pretty-git)](https://rubygems.org/gems/pretty-git)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Ruby 3.4+](https://img.shields.io/badge/ruby-3.4%2B-red)
+
+<p align="right">
+  <a href="./README.md">English</a> | <b>Русский</b>
+</p>
+
+<p align="center">
+  <img src="docs/images/PrettyGitIcon.png" alt="Pretty Git Logo" width="200">
+  <br>
+</p>
+
+Генератор отчётов по локальному Git-репозиторию: сводка, активность, авторы, файлы, тепловая карта. Вывод в консоль и форматы: JSON, CSV, Markdown, YAML, XML.
+
+— Лицензия: MIT.
+
+## Содержание
+- [Возможности](#возможности)
+- [Требования](#требования)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [CLI и параметры](#cli-и-параметры)
+  - [Фильтры](#фильтры)
+  - [Формат вывода](#формат-вывода)
+  - [Вывод в файл](#вывод-в-файл)
+  - [Коды возврата](#коды-возврата)
+- [Отчёты и примеры](#отчёты-и-примеры)
+  - [summary — сводка](#summary--сводка)
+  - [activity — активность (day/week/month)](#activity--активность-dayweekmonth)
+  - [authors — по авторам](#authors--по-авторам)
+  - [files — по файлам](#files--по-файлам)
+  - [heatmap — тепловая карта](#heatmap--тепловая-карта)
+  - [languages — языки](#languages--языки)
+- [Экспорт в форматы](#экспорт-в-форматы)
+  - [Console](#console)
+  - [JSON](#json)
+  - [CSV (DR-001)](#csv-dr-001)
+  - [Markdown](#markdown)
+  - [YAML](#yaml)
+  - [XML](#xml)
+- [Детерминизм и сортировка](#детерминизм-и-сортировка)
+- [Советы по Windows](#советы-по-windows)
+- [Диагностика и ошибки](#диагностика-и-ошибки)
+- [FAQ](#faq)
+- [Разработка](#разработка)
+- [Лицензия](#лицензия)
+
+## Возможности
+* __Отчёты__: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`.
+* __Фильтры__: ветки, авторы, пути, период времени.
+* __Экспорт__: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
+* __Вывод__: в stdout или файл через `--out`.
+
+## Требования
+* __Ruby__: >= 3.4 (рекомендуется 3.4.x)
+* __Git__: установлен и доступен в `PATH`
+
+## Установка
+
+### 🍺 Homebrew (рекомендуется)
+```bash
+brew tap MikoMikocchi/tap
+brew install pretty-git
+```
+
+### ♦️ RubyGems
+```bash
+gem install pretty-git
+```
+Выберите один из вариантов:
+
+1) 🛠️ Локально из исходников (рекомендуется для разработки)
+
+```bash
+git clone <repo_url>
+cd pretty-git
+bin/setup
+# запуск:
+bundle exec bin/pretty-git --help
+```
+
+2) ♦️ Как gem (после первого релиза)
+
+```bash
+gem install pretty-git
+pretty-git --version
+```
+
+3) 📦 Использование через Bundler
+
+```ruby
+# Gemfile
+gem 'pretty-git', '~> 0.1'
+```
+```bash
+bundle install
+bundle exec pretty-git --help
+```
+
+## Быстрый старт
+```bash
+# Сводка репозитория в консоль
+bundle exec bin/pretty-git summary .
+
+# Авторы в JSON и запись в файл
+bundle exec bin/pretty-git authors . --format json --out authors.json
+
+# Активность по неделям за период и только по указанным путям
+bundle exec bin/pretty-git activity . --time-bucket week --since 2025-01-01 \
+  --paths app,lib --format csv --out activity.csv
+```
+
+## CLI и параметры
+Общий вид:
+
+```bash
+pretty-git <report> <repo_path> [options]
+```
+
+Доступные отчёты: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`.
+
+Ключевые опции:
+* __--format, -f__ `console|json|csv|md|yaml|xml` (по умолчанию `console`)
+* __--out, -o__ Путь для записи в файл
+* __--limit, -l__ Число элементов в топах/выводе; `all` или `0` — без ограничения
+* __--time-bucket__ `day|week|month` (для `activity`)
+* __--since/--until__ Дата/время в ISO8601 или `YYYY-MM-DD` (DR-005)
+* __--branch__ Мульти-опция, можно указывать несколько веток
+* __--author/--exclude-author__ Фильтрация по авторам
+* __--path/--exclude-path__ Фильтрация по путям (через запятую или повтор опции)
+* __--no-color__ Отключить цвета в консоли
+* __--theme__ `basic|bright|mono` — тема оформления консольного вывода (по умолчанию `basic`; `mono` принудительно отключает цвета)
+* __--metric__ `bytes|files|loc` — метрика для отчёта `languages` (по умолчанию `bytes`)
+
+Примеры значений с несколькими параметрами:
+
+```bash
+# Несколько веток
+pretty-git summary . --branch main --branch develop
+
+# Фильтрация по авторам (включая/исключая)
+pretty-git authors . --author alice@example.com --exclude-author bot@company
+
+# Фильтрация по путям
+pretty-git files . --path app,lib --exclude-path vendor,node_modules
+```
+
+### Фильтры
+Фильтры применяются на этапе выборки коммитов и последующей агрегации. Формат дат: ISO8601 или `YYYY-MM-DD`. Если часовой пояс не указан — используется локальная зона пользователя; на выводе время нормализуется к UTC.
+
+### Формат вывода
+Задаётся через `--format`. Для файловых форматов рекомендуется использовать `--out`.
+
+### Вывод в файл
+```bash
+pretty-git authors . --format csv --out authors.csv
+```
+
+### Коды возврата
+* `0` — успех
+* `1` — ошибка пользователя (неизвестный отчёт/формат, неверные аргументы)
+* `2` — системная ошибка (ошибка Git и пр.)
+
+## Отчёты и примеры
+
+### summary — сводка
+```bash
+pretty-git summary . --format json
+```
+Содержит totals (commits, authors, additions, deletions) и топы по авторам/файлам.
+
+### activity — активность (day/week/month)
+```bash
+pretty-git activity . --time-bucket week --format csv
+```
+CSV-колонки: `bucket,timestamp,commits,additions,deletions`.
+Пример JSON:
+```json
+[
+  {"bucket":"week","timestamp":"2025-06-02T00:00:00Z","commits":120,"additions":3456,"deletions":2100},
+  {"bucket":"week","timestamp":"2025-06-09T00:00:00Z","commits":98,"additions":2890,"deletions":1760}
+]
+```
+
+### authors — по авторам
+```bash
+pretty-git authors . --format md --limit 10
+```
+CSV-колонки: `author,author_email,commits,additions,deletions,avg_commit_size`.
+Пример Markdown:
+```markdown
+| author | author_email | commits | additions | deletions | avg_commit_size |
+|---|---|---:|---:|---:|---:|
+| Alice | a@example.com | 2 | 5 | 1 | 3.0 |
+| Bob   | b@example.com | 1 | 2 | 0 | 2.0 |
+```
+
+### files — по файлам
+```bash
+pretty-git files . --paths app,lib --format csv
+```
+CSV-колонки: `path,commits,additions,deletions,changes`.
+Пример XML:
+```xml
+<files>
+  <item path="app/models/user.rb" commits="42" additions="2100" deletions="1400" changes="3500" />
+  <item path="app/services/auth.rb" commits="35" additions="1500" deletions="900" changes="2400" />
+  <generated_at>2025-01-31T00:00:00Z</generated_at>
+  <repo_path>/abs/path/to/repo</repo_path>
+  <report>files</report>
+  <period>
+    <since/>
+    <until/>
+  </period>
+  </files>
+```
+
+### heatmap — тепловая карта
+```bash
+pretty-git heatmap . --format json
+```
+JSON: массив бакетов по (день недели × час) с числом коммитов.
+Пример CSV:
+```csv
+dow,hour,commits
+1,10,5
+1,11,7
+```
+
+### languages — языки
+```bash
+pretty-git languages . --format md --limit 10
+```
+Определяет распределение языков в репозитории. Поддерживаются несколько метрик: `bytes`, `files`, `loc` (по умолчанию: `bytes`). Вывод включает язык, выбранную метрику и долю в процентах; в консоли отображаются цвета языков.
+
+Пример консольного вывода:
+```text
+Languages for .
+
+language     bytes percent
+-------- ---------- -------
+Ruby        123456    60.0
+JavaScript   78901    38.3
+Markdown      1200     1.7
+```
+
+![Console output — languages](docs/images/PrettyGitConsoleLanguages.png)
+
+Замечания:
+- __Определение языка__: по расширениям файлов и некоторым именам файлов (`Makefile`, `Dockerfile`).
+- __Исключения__: бинарные файлы и "vendor"‑директории игнорируются. По умолчанию пропускаются `vendor/`, `node_modules/`, `.git/`, артефакты сборки и кэши. Для Python дополнительно исключаются `.venv/`, `venv/`, `env/`, `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.tox/`, `.eggs/`, `.ruff_cache/`, `.ipynb_checkpoints/`.
+- __JSON__: JSON включён как язык. Если крупные файлы данных искажают картину, сузьте область `--path/--exclude-path`.
+- __Фильтры путей__: используйте `--path/--exclude-path` (поддерживаются glob‑маски), чтобы сосредоточиться на соответствующих директориях.
+- __Лимит__: `--limit N` ограничивает число строк в итоговой таблице; `0`/`all` — без ограничения.
+- __Цвета в консоли__: имена языков подсвечиваются приблизительными цветами GitHub; `--no-color` отключает, `--theme mono` делает монохром.
+
+Экспорт:
+- CSV/MD: колонки динамические — `language,<metric>,percent`. В Markdown дополнительно присутствует колонка `color`.
+- JSON/YAML/XML: полная структура отчёта, включая `color` на язык и метаданные (`report`, `generated_at`, `repo_path`).
+
+## Игнорируемые директории и файлы
+
+Чтобы статистика по языкам оставалась релевантной, некоторые директории и типы файлов пропускаются по умолчанию.
+
+**Игнорируемые директории** (если сегмент пути совпадает):
+
+```
+vendor, node_modules, .git, .bundle, dist, build, out, target, coverage,
+.venv, venv, env, __pycache__, .mypy_cache, .pytest_cache, .tox, .eggs, .ruff_cache,
+.ipynb_checkpoints
+```
+
+**Игнорируемые бинарные/данные расширения**:
+
+```
+.png, .jpg, .jpeg, .gif, .svg, .webp, .ico, .bmp,
+.pdf, .zip, .tar, .gz, .tgz, .bz2, .7z, .rar,
+.mp3, .ogg, .wav, .mp4, .mov, .avi, .mkv,
+.woff, .woff2, .ttf, .otf, .eot,
+.jar, .class, .dll, .so, .dylib,
+.exe, .bin, .dat
+```
+
+Списки соответствуют реализации в `lib/pretty_git/analytics/languages.rb` и могут изменяться.
+
+## Экспорт в форматы
+
+Ниже — точные правила сериализации для каждого формата, чтобы обеспечивалась совместимость с популярными инструментами (Excel, BI, CI и т.п.).
+
+### Console
+![Console output — basic theme](docs/images/PrettyGitConsole.png)
+_Пример вывода в терминале (тема: basic)._ 
+* __Цвета__: заголовки и шапки таблиц подсвечены; суммы: `commits` — жёлтым, `+additions` — зелёным, `-deletions` — красным. `--no-color` полностью отключает раскраску.
+* __Темы__: `--theme basic|bright|mono`. `bright` — более насыщенные заголовки, `mono` — монохром (аналогично `--no-color`).
+* __Выделение максимума__: на числовых колонках максимальные значения подчёркиваются жирным для быстрого сканирования.
+* __Ширина терминала__: при выводе таблиц автоматически учитывается ширина терминала. Если ширины не хватает, первый столбец аккуратно обрезается с многоточием `…`.
+* __Кодировка__: UTF‑8, переводы строк LF.
+* __Назначение__: человекочитаемый вывод в терминал.
+* __Оформление__: таблицы с границами, авто-обрезка длинных значений.
+* __Цвета__: включены, если есть TTY; отключаются `--no-color`.
+* __Пустые наборы__: печатается `No data`.
+* __Кодировка/переводы строк__: UTF‑8, LF (`\n`).
+
+### JSON
+* __Ключи__: `snake_case`.
+* __Числа__: целые/вещественные без локализации (точка как разделитель).
+* __Булевы__: `true/false`; __null__: `null`.
+* __Даты/время__: ISO8601 в UTC, например `2025-01-31T00:00:00Z`.
+* __Порядок__: поля в объектах стабильно упорядочены логически (например, `report`, `generated_at`, `repo_path`, затем данные).
+* __Кодировка/переводы строк__: UTF‑8, LF.
+* __Рекомендуемое расширение__: `.json`.
+* __Пример__:
+  ```json
+  {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
+  ```
+
+### CSV
+* __Структура__: плоская таблица, первая строка — заголовок.
+* __Кодировка__: UTF‑8, без BOM.
+* __Разделитель__: запятая `,`.
+* __Экранирование__: по RFC 4180 — поля с запятыми/кавычками/переводами строк заключаются в двойные кавычки, двойные кавычки внутри поля удваиваются.
+* __Пустые значения__: пустая ячейка (не `null`).
+* __Числа__: без тысячных разделителей, десятичная точка.
+* __Даты/время__: ISO8601 UTC.
+* __Порядок колонок__: фиксирован на отчёт и стабилен.
+* __Переводы строк__: LF.
+* __Рекомендуемое расширение__: `.csv`.
+* __Открытие в Excel__: указывайте кодировку UTF‑8 при импорте.
+* __Пример__:
+  ```csv
+  author,author_email,commits,additions,deletions,avg_commit_size
+  Alice,a@example.com,2,5,1,3.0
+  Bob,b@example.com,1,2,0,2.0
+  ```
+
+### Markdown
+* __Таблицы__: стандартный синтаксис GitHub Flavored Markdown.
+* __Выравнивание__: числовые колонки выравниваются по правому краю (`---:`).
+* __Кодировка/переводы строк__: UTF‑8, LF.
+* __Рекомендуемое расширение__: `.md`.
+* __Пустые наборы__: таблица с заголовком и без строк либо краткое сообщение `No data` (в зависимости от отчёта).
+* __Пример__:
+  ```markdown
+  | path | commits | additions | deletions |
+  |---|---:|---:|---:|
+  | app/models/user.rb | 42 | 2100 | 1400 |
+  ```
+
+### YAML
+* __Структура__: полная иерархия результата.
+* __Ключи__: сериализуются строками.
+* __Числа/булевы/null__: стандарт YAML (`123`, `true/false`, `null`).
+* __Даты/время__: ISO8601 UTC как строки.
+* __Кодировка/переводы строк__: UTF‑8, LF.
+* __Рекомендуемое расширение__: `.yml` или `.yaml`.
+* __Пример__:
+  ```yaml
+  report: authors
+  generated_at: "2025-01-31T00:00:00Z"
+  items:
+    - author: Alice
+      author_email: a@example.com
+      commits: 2
+    - author: Bob
+      author_email: b@example.com
+      commits: 1
+  ```
+
+### XML
+* __Структура__: элементы соответствуют ключам; массивы — повторяющиеся `<item>` или специализированные теги.
+* __Атрибуты__: для компактных записей (например, строк файлового отчёта) основные поля могут быть атрибутами элемента.
+* __Текстовые узлы__: применяются для скалярных значений при необходимости.
+* __Экранирование__: `& < > " ' ` по правилам XML, при необходимости CDATA для произвольного текста.
+* __Даты/время__: ISO8601 UTC.
+* __Кодировка/переводы строк__: UTF‑8, LF; декларация `<?xml version="1.0" encoding="UTF-8"?>` может добавляться генератором.
+* __Рекомендуемое расширение__: `.xml`.
+* __Пример__:
+  ```xml
+  <authors>
+    <item author="Alice" author_email="a@example.com" commits="2" />
+    <item author="Bob" author_email="b@example.com" commits="1" />
+    <generated_at>2025-01-31T00:00:00Z</generated_at>
+    <repo_path>/abs/path</repo_path>
+  </authors>
+  ```
+
+## Детерминизм и сортировка
+Вывод детерминирован при одинаковых входных данных. Сортировка для файлов/авторов: по количеству изменений (desc), затем по числу коммитов (desc), затем по пути/имени (asc). Лимиты применяются поверх отсортированного списка; значение `all` или `0` означает отсутствие ограничения.
+
+## Советы по Windows
+Целевая платформа — macOS/Linux. Windows поддерживается в режиме best‑effort:
+* Запуск через Git Bash/WSL допустим
+* Цвета можно отключить `--no-color`
+* Аккуратное квотирование аргументов при работе с путями
+
+## Диагностика и ошибки
+Типичные ошибки и решения:
+
+* __Неизвестный отчёт/формат__ — проверьте значение первого аргумента и `--format`.
+* __Неверный формат даты__ — используйте ISO8601 или `YYYY-MM-DD` (например, `2025-01-31` или `2025-01-31T12:00:00Z`).
+* __Git недоступен__ — убедитесь, что `git` установлен и доступен в `PATH`.
+* __Пустой результат__ — проверьте фильтры (`--since/--until`, `--branch`, `--path`), возможно, выборка слишком узкая.
+* __Проблемы с кодировкой CSV__ — файлы сохраняются в UTF‑8, при открытии в Excel выбирайте UTF‑8.
+
+## FAQ
+* __Почему Ruby 3.4+?__ Проект использует зависимости, согласованные с версией 3.4+, и ориентируется на актуальную экосистему.
+* __Можно ли добавить новые форматы?__ Да, добавьте рендерер в `lib/pretty_git/render/` и зарегистрируйте его в приложении.
+* __Откуда берутся данные?__ Из системного `git` через вызовы CLI.
+
+## Разработка
+```bash
+# Установка зависимостей
+bin/setup
+
+# Запуск тестов и линтера
+bundle exec rspec
+bundle exec rubocop
+```
+
+Стиль — RuboCop без ошибок. Тесты покрывают агрегаторы, рендереры, CLI и интеграционные сценарии (детерминизм, корректность форматов).
+
+## Лицензия
+MIT © Contributors

data/lib/pretty_git/analytics/languages.rb

@@ -15,7 +15,7 @@ module PrettyGit
       '.sh' => 'Shell', '.bash' => 'Shell', '.zsh' => 'Shell',
       '.ps1' => 'PowerShell', '.psm1' => 'PowerShell',
       '.bat' => 'Batchfile', '.cmd' => 'Batchfile',
-      # Intentionally excluding JSON (usually data, not source code)
+      '.json' => 'JSON',
       '.yml' => 'YAML', '.yaml' => 'YAML', '.toml' => 'TOML', '.ini' => 'INI', '.xml' => 'XML',
       '.html' => 'HTML', '.htm' => 'HTML', '.css' => 'CSS', '.scss' => 'SCSS', '.sass' => 'SCSS',
       '.md' => 'Markdown', '.markdown' => 'Markdown',
@@ -43,6 +43,25 @@ module PrettyGit
       'Dockerfile' => 'Dockerfile'
     }.freeze
 
+    # Language → HEX color (without leading #) for exports (CSV/JSON/YAML/XML)
+    LANG_HEX_COLORS = {
+      'Ruby' => 'cc342d',
+      'JavaScript' => 'f1e05a', 'TypeScript' => '3178c6',
+      'JSX' => 'f1e05a', 'TSX' => '3178c6',
+      'Python' => '3572a5', 'Go' => '00add8', 'Rust' => 'dea584', 'Java' => 'b07219',
+      'C' => '555555', 'C++' => 'f34b7d', 'C#' => '178600', 'Objective-C' => '438eff', 'Swift' => 'ffac45',
+      'Kotlin' => 'a97bff', 'Scala' => 'c22d40', 'Groovy' => 'e69f56', 'Dart' => '00b4ab',
+      'PHP' => '4f5d95', 'Perl' => '0298c3', 'R' => '198ce7', 'Lua' => '000080', 'Haskell' => '5e5086',
+      'Elixir' => '6e4a7e', 'Erlang' => 'b83998',
+      'Shell' => '89e051', 'PowerShell' => '012456', 'Batchfile' => 'c1f12e',
+      'HTML' => 'e34c26', 'CSS' => '563d7c', 'SCSS' => 'c6538c',
+      'JSON' => 'eeeeee',
+      'YAML' => 'cb171e', 'TOML' => '9c4221', 'INI' => '6b7280', 'XML' => '0060ac',
+      'Markdown' => '083fa1', 'Makefile' => '427819', 'Dockerfile' => '384d54',
+      'SQL' => 'e38c00', 'GraphQL' => 'e10098', 'Proto' => '3b5998',
+      'Svelte' => 'ff3e00', 'Vue' => '41b883'
+    }.freeze
+
     VENDOR_DIRS = %w[
       vendor node_modules .git .bundle dist build out target coverage
       .venv venv env __pycache__ .mypy_cache .pytest_cache .tox .eggs .ruff_cache
@@ -56,21 +75,25 @@ module PrettyGit
       .jar .class .dll .so .dylib
       .exe .bin .dat
     ].freeze
-    # Computes language distribution by summing file sizes per language.
-    # Similar to GitHub Linguist approach (bytes per language).
+    # Computes language distribution by bytes, files, and LOC per language.
+    # Default metric: bytes (similar to GitHub Linguist approach).
+    # rubocop:disable Metrics/ClassLength
     class Languages
       def self.call(_enum, filters)
         repo = filters.repo_path
         items = calculate(repo, include_globs: filters.paths, exclude_globs: filters.exclude_paths)
-        total = total_bytes(items)
-        items = add_percents(items, total)
-        items = sort_and_limit(items, filters.limit)
+        metric = (filters.metric || 'bytes').to_s
+        totals = compute_totals(items)
+        items = add_percents(items, totals, metric)
+        items = add_colors(items)
+        items = sort_and_limit(items, filters.limit, metric)
 
-        build_result(repo, items, total)
+        build_result(repo, items, totals, metric)
       end
 
+      # rubocop:disable Metrics/AbcSize
       def self.calculate(repo_path, include_globs:, exclude_globs:)
-        by_lang = Hash.new(0)
+        by_lang = Hash.new { |h, k| h[k] = { bytes: 0, files: 0, loc: 0 } }
         Dir.chdir(repo_path) do
           each_source_file(include_globs, exclude_globs) do |abs_path|
             basename = File.basename(abs_path)
@@ -78,16 +101,17 @@ module PrettyGit
             lang = FILENAME_TO_LANG[basename] || EXT_TO_LANG[ext]
             next unless lang
 
-            size = begin
-              File.size(abs_path)
-            rescue StandardError
-              0
-            end
-            by_lang[lang] += size
+            size = safe_file_size(abs_path)
+            lines = safe_count_lines(abs_path)
+            agg = by_lang[lang]
+            agg[:bytes] += size
+            agg[:files] += 1
+            agg[:loc] += lines
           end
         end
-        by_lang.map { |lang, bytes| { language: lang, bytes: bytes } }
+        by_lang.map { |lang, h| { language: lang, bytes: h[:bytes], files: h[:files], loc: h[:loc] } }
       end
+      # rubocop:enable Metrics/AbcSize
 
       def self.each_source_file(include_globs, exclude_globs)
         # Build list of files under repo respecting includes/excludes
@@ -98,6 +122,20 @@ module PrettyGit
         files.each { |rel| yield File.expand_path(rel) }
       end
 
+      def self.safe_file_size(path)
+        File.size(path)
+      rescue StandardError
+        0
+      end
+
+      def self.safe_count_lines(path)
+        count = 0
+        File.foreach(path) { |_l| count += 1 }
+        count
+      rescue StandardError
+        0
+      end
+
       def self.filter_includes(files, globs)
         globs = Array(globs).compact
         return files if globs.empty?
@@ -123,33 +161,52 @@ module PrettyGit
         BINARY_EXTS.include?(File.extname(path).downcase)
       end
 
-      def self.total_bytes(items)
-        items.sum { |item| item[:bytes] }
+      def self.compute_totals(items)
+        {
+          bytes: items.sum { |i| i[:bytes] },
+          files: items.sum { |i| i[:files] },
+          loc: items.sum { |i| i[:loc] }
+        }
       end
 
-      def self.add_percents(items, total)
+      def self.add_percents(items, totals, metric)
+        total = totals[metric.to_sym].to_f
         return items.map { |item| item.merge(percent: 0.0) } unless total.positive?
 
-        items.map { |item| item.merge(percent: (item[:bytes] * 100.0 / total)) }
+        items.map do |item|
+          val = item[metric.to_sym].to_f
+          pct = (val * 100.0 / total).round(2)
+          item.merge(percent: pct)
+        end
+      end
+
+      def self.add_colors(items)
+        items.map do |item|
+          color = LANG_HEX_COLORS[item[:language]]
+          item.merge(color: color)
+        end
       end
 
-      def self.sort_and_limit(items, limit)
-        sorted = items.sort_by { |item| [-item[:percent], item[:language]] }
+      def self.sort_and_limit(items, limit, metric)
+        key = metric.to_sym
+        sorted = items.sort_by { |item| [-item[key], item[:language]] }
         lim = limit.to_i
         return sorted if lim <= 0
 
         sorted.first(lim)
       end
 
-      def self.build_result(repo, items, total)
+      def self.build_result(repo, items, totals, metric)
         {
           report: 'languages',
           repo_path: repo,
+          metric: metric,
           generated_at: Time.now.utc.iso8601,
-          totals: { bytes: total, languages: items.size },
+          totals: totals.merge(languages: items.size),
           items: items
         }
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/pretty_git/cli.rb

@@ -9,7 +9,7 @@ require_relative 'cli_helpers'
 module PrettyGit
   # Command-line interface entry point.
   class CLI
-    SUPPORTED_REPORTS = %w[summary activity authors files heatmap].freeze
+    SUPPORTED_REPORTS = %w[summary activity authors files heatmap languages].freeze
     SUPPORTED_FORMATS = %w[console json csv md yaml xml].freeze
 
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength

data/lib/pretty_git/cli_helpers.rb

@@ -7,9 +7,11 @@ require_relative 'app'
 module PrettyGit
   # Helpers extracted from `PrettyGit::CLI` to keep the CLI class small
   # and RuboCop-compliant. Provides parser configuration and execution utilities.
+  # rubocop:disable Metrics/ModuleLength
   module CLIHelpers
     REPORTS = %w[summary activity authors files heatmap languages].freeze
     FORMATS = %w[console json csv md yaml xml].freeze
+    METRICS = %w[bytes files loc].freeze
 
     module_function
 
@@ -19,6 +21,7 @@ module PrettyGit
       add_time_author_options(opts, options)
       add_path_limit_options(opts, options)
       add_format_output_options(opts, options)
+      add_metric_options(opts, options)
       add_misc_options(opts, options)
     end
 
@@ -48,6 +51,12 @@ module PrettyGit
       opts.on('--theme NAME', 'console color theme: basic|bright|mono') { |val| options[:theme] = val }
     end
 
+    def add_metric_options(opts, options)
+      opts.on('--metric NAME', 'languages metric: bytes|files|loc (default: bytes)') do |val|
+        options[:metric] = val
+      end
+    end
+
     def add_misc_options(opts, options)
       opts.on('--version', 'Show version') { options[:_version] = true }
       opts.on('--help', 'Show help') { options[:_help] = true }
@@ -66,7 +75,7 @@ module PrettyGit
       code = handle_version_help(options, parser, out)
       return code unless code.nil?
 
-      return nil if valid_report?(options[:report]) && valid_theme?(options[:theme])
+      return nil if valid_report?(options[:report]) && valid_theme?(options[:theme]) && valid_metric?(options[:metric])
 
       print_validation_errors(options, err)
       1
@@ -87,15 +96,20 @@ module PrettyGit
     def valid_report?(report) = REPORTS.include?(report)
     def valid_theme?(theme) = %w[basic bright mono].include?(theme)
 
+    def valid_metric?(metric)
+      metric.nil? || METRICS.include?(metric)
+    end
+
     def print_validation_errors(options, err)
       supported = REPORTS.join(', ')
       unless valid_report?(options[:report])
         err.puts "Unknown report: #{options[:report]}."
         err.puts "Supported: #{supported}"
       end
-      return if valid_theme?(options[:theme])
+      err.puts "Unknown theme: #{options[:theme]}. Supported: basic, bright, mono" unless valid_theme?(options[:theme])
+      return if valid_metric?(options[:metric])
 
-      err.puts "Unknown theme: #{options[:theme]}. Supported: basic, bright, mono"
+      err.puts "Unknown metric: #{options[:metric]}. Supported: #{METRICS.join(', ')}"
     end
 
     def build_filters(options)
@@ -109,6 +123,7 @@ module PrettyGit
         paths: options[:paths],
         exclude_paths: options[:exclude_paths],
         time_bucket: options[:time_bucket],
+        metric: options[:metric],
         limit: options[:limit],
         format: options[:format],
         out: options[:out],
@@ -127,4 +142,5 @@ module PrettyGit
       PrettyGit::App.new.run(report, filters, out: out, err: err)
     end
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/pretty_git/filters.rb

@@ -13,6 +13,7 @@ module PrettyGit
     :paths,
     :exclude_paths,
     :time_bucket,
+    :metric,
     :limit,
     :format,
     :out,

data/lib/pretty_git/git/provider.rb

@@ -16,7 +16,7 @@ module PrettyGit
       end
 
       # Returns Enumerator of PrettyGit::Types::Commit
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def each_commit
         Enumerator.new do |yld|
           cmd = build_git_command
@@ -24,17 +24,15 @@ module PrettyGit
             current = nil
             stdout.each_line do |line|
               line = line.chomp
-              if record_separator?(line)
+              # Try to start a new commit from header on any line
+              header = start_commit_from_header(line)
+              if header
+                # emit previous commit if any
                 emit_current(yld, current)
-                current = nil
+                current = header
                 next
               end
 
-              if current.nil?
-                current = start_commit_from_header(line)
-                next if current
-              end
-
               next if line.empty?
 
               append_numstat_line(current, line)
@@ -50,7 +48,7 @@ module PrettyGit
           end
         end
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       private
 
@@ -84,7 +82,7 @@ module PrettyGit
           author_name: author_name,
           author_email: author_email,
           authored_at: Time.parse(authored_at).utc.iso8601,
-          message: subject,
+          message: subject.delete(SEP_RECORD),
           files: []
         }
       end

data/lib/pretty_git/render/csv_renderer.rb

@@ -21,7 +21,9 @@ module PrettyGit
         when 'heatmap'
           write_csv(%w[dow hour commits], result[:items])
         when 'languages'
-          write_csv(%w[language bytes percent], result[:items])
+          metric = (result[:metric] || 'bytes').to_s
+          headers = ['language', metric, 'percent', 'color']
+          write_csv(headers, result[:items])
         else
           raise ArgumentError, "CSV output for report '#{report}' is not supported yet"
         end

data/lib/pretty_git/render/languages_section.rb

@@ -26,9 +26,11 @@ module PrettyGit
       def render(io, table, data, color: true)
         title(io, data, color)
         io.puts
-        table_rows = rows(data[:items])
+        metric = (data[:metric] || 'bytes').to_s
+        table_rows = rows(data[:items], metric)
         colorizer = ->(row) { LANG_ANSI_COLOR_CODES[row[:language]] }
-        table.print(%w[language bytes percent], table_rows, highlight_max: false, first_col_colorizer: colorizer)
+        headers = ['language', metric, 'percent']
+        table.print(headers, table_rows, highlight_max: false, first_col_colorizer: colorizer)
         io.puts
         io.puts "Generated at: #{data[:generated_at]}"
       end
@@ -37,9 +39,10 @@ module PrettyGit
         io.puts Colors.title("Languages for #{data[:repo_path]}", color)
       end
 
-      def rows(items)
+      def rows(items, metric)
+        key = metric.to_sym
         items.map do |item|
-          { language: item[:language], bytes: item[:bytes], percent: format('%.1f', item[:percent]) }
+          { language: item[:language], key => item[key], percent: format('%.2f', item[:percent]) }
         end
       end
     end

data/lib/pretty_git/render/markdown_renderer.rb

@@ -8,6 +8,7 @@ module PrettyGit
         @io = io
       end
 
+      # rubocop:disable Metrics/CyclomaticComplexity
       def call(report, result, _filters)
         case report
         when 'summary'
@@ -21,11 +22,14 @@ module PrettyGit
         when 'heatmap'
           render_table('Heatmap', %w[dow hour commits], result[:items])
         when 'languages'
-          render_table('Languages', %w[language bytes percent], result[:items])
+          metric = (result[:metric] || 'bytes').to_s
+          headers = ['language', metric, 'percent', 'color']
+          render_table('Languages', headers, result[:items])
         else
           @io.puts result.inspect
         end
       end
+      # rubocop:enable Metrics/CyclomaticComplexity
 
       private
 

data/lib/pretty_git/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrettyGit
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pretty-git
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Pretty Git Authors
@@ -58,8 +58,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
+- README.ru.md
 - bin/pretty-git
 - lib/pretty_git.rb
 - lib/pretty_git/analytics/activity.rb