pretty-git 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84571ab2bdd16f92dc31c1883a70433a140253ee0d0c66f1079453fc30f34419
-  data.tar.gz: 532ee3a2e436163f12821073297dc013e874746c5ac269f89c455826566c9f27
+  metadata.gz: 7bd982eee724a56adcb2aa941fdecc2c95309c1bf681a5c3b9a1be0b8bf0306f
+  data.tar.gz: 1ef12cd144493563bbe99a869e81fe6aa9436136dc7aac52b713d5436975a48a
 SHA512:
-  metadata.gz: a0ba7918e1179ebfe3c4771c995b8b0eda978263be1fc6484f0f913e7b2129472272660e3c6dfb24a11f9d64300c26748d0b01fc14f0594e04e9b88cf244b96c
-  data.tar.gz: afaa201615eff920f1af0b86384964437fe7a119fc0d43d2a5ae10ee36211215b84c9607b92354646a20d691f0382f0b5d214385a214e8107596cdcf06eefcb2
+  metadata.gz: fba3dc59a53571d80cf38e13a555b2ad62b44964f29039a1fe68000349f642d024bb854542d62d58608dd8f9a8169548b0444a0fc8488cccc9a8e3497ba68ade
+  data.tar.gz: 1f8037f3e7ef97e13b60be37c6d447c684586ffb78017d1905fc6b75d4d055ce533d4a87f04baf6e15fa734fa20fcbfe8854f5f4ef429c402106cbbf4a9a70b5

data/CHANGELOG.md

@@ -5,7 +5,46 @@ 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]
- 
+### Added
+- Docs: `docs/testing.md` covering the golden workflow, snapshot update/validation; linked from `README.md`, `README.ru.md`, and `CONTRIBUTING.md`.
+- Tests: determinism invariants for YAML/XML renderers (stable output regardless of input order).
+
+### Changed
+- Completions: refreshed bash/zsh completions — added short flags `-f`/`-o`/`-l`, values for `--time-bucket` (`day|week|month`), and repo path completion as the 2nd positional argument.
+
+## [0.1.5] - 2025-08-17
+### Added
+- CLI: warn to stderr when `--theme`/`--no-color` are used with non-console `--format` values.
+- Docs: expanded Filters documentation (branches, authors, paths, time semantics, verbose diagnostics), schemas/examples pointers, performance and CI usage.
+- Tests: unit tests for `PrettyGit::Utils::TimeUtils`.
+
+### Changed
+- Internals: extracted time parsing/normalization to `PrettyGit::Utils::TimeUtils` and centralized verbose logging via `PrettyGit::Logger`. `Git::Provider` routes verbose messages through the centralized logger (stderr).
+- Verbose mode: documentation clarified to note that diagnostics are printed to stderr for easier CI parsing.
+
+### Deprecated
+- Filters: legacy `:until` keyword in `PrettyGit::Filters` initialization is accepted for backward compatibility and emits a deprecation warning; use `:until_at` instead.
+
+### Fixed
+- Filters: allow initialization via a single Hash argument (legacy call sites) while preserving `Struct` keyword semantics.
+
+## [0.1.4] - 2025-08-17
+### Added
+- Integration tests for new reports exports: CSV/Markdown/YAML/XML for `hotspots`, `churn`, `ownership`.
+- Schema validations: `rake validate:json`, `rake validate:xml` to ensure format compatibility.
+- CI: expanded matrix to include macOS; smoke test for installed binary (`--help`, `--version`).
+
+### Changed
+- Renderers (`MarkdownRenderer`, `YamlRenderer`, `XmlRenderer`): deterministic sorting for all new reports according to `docs/determinism.md`.
+- XML: per-report root elements in XML exports to match XSDs (`hotspotsReport`, `churnReport`, `ownershipReport`, `languagesReport`, etc.).
+- Documentation: `README.md` and `README.ru.md` updated with sections and examples for new reports and all export formats.
+- CLI: keep `--time-bucket` permissive; default `time_bucket=nil`.
+
+### Fixed
+- Time parsing: interpret date-only inputs (`YYYY-MM-DD`) as UTC midnight and normalize to UTC ISO8601.
+- CLI UX: error when `--metric` is used outside `languages` report.
+- Tests/specs: updated XML specs to per-report roots; added timezone edge cases; fixed Open3 `popen3` stubs (`chdir:`) and integration requires.
+
 
 ## [0.1.3] - 2025-08-14
 ### Added
@@ -30,7 +69,7 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 ### 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`.
+- Internal specs updated: `docs/output_formats.md`, `docs/cli_spec.md`, `docs/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`).

data/README.md

@@ -58,6 +58,13 @@ Generator of rich reports for a local Git repository: summary, activity, authors
 * **Exports**: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
 * **Output**: to stdout or file via `--out`.
 
+## ❓ Why Pretty Git
+* **One tool, many views**: activity, authorship, hotspots, languages, ownership — consistent UX and outputs.
+* **Deterministic results**: stable sorting and formatting make it reliable for CI and diffs.
+* **Format-first**: JSON/CSV/Markdown/YAML/XML out of the box with strict and documented rules.
+* **Fast enough for daily use**: streams `git log` and aggregates in-memory; tips below for large repos.
+* **Safe defaults**: sensible path and binary ignores for the `languages` report; colorized console output with themes.
+
 ## ⚙️ Requirements
 * **Ruby**: >= 3.4 (recommended 3.4.x)
 * **Git**: installed and available in `PATH`
@@ -124,6 +131,10 @@ General form:
 pretty-git <report> <repo_path> [options]
 ```
 
+Notes:
+* `<repo_path>` defaults to `.` if omitted.
+* You can also pass the repository via `--repo PATH` as an alternative to the positional argument.
+
 Available reports: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`, `hotspots`, `churn`, `ownership`.
 
 Key options:
@@ -138,12 +149,15 @@ Key options:
 * **--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`)
+* **--verbose** Print debug information (effective git command, filters)
 
 Examples with multiple values:
 
 ```bash
-# Multiple branches
+# Multiple branches (treated as explicit revisions)
 pretty-git summary . --branch main --branch develop
+## This is equivalent to:
+## git log main develop -- ...
 
 # Filter authors (include/exclude)
 pretty-git authors . --author alice@example.com --exclude-author bot@company
@@ -153,7 +167,30 @@ pretty-git files . --path app,lib --exclude-path vendor,node_modules
 ```
 
 ### Filters
-Filters apply at commit fetch and later aggregation. Date format: ISO8601 or `YYYY-MM-DD`. If timezone is omitted — your local zone is assumed; output timestamps are normalized to UTC.
+Filters apply at commit fetch and later aggregation. Below — exact semantics and tips.
+
+#### Branches / revisions
+* `--branch BRANCH` may be provided multiple times.
+* Multiple branches are treated as explicit revisions to `git log` (no implicit merge-base range). Example: `--branch main --branch develop` → `git log main develop -- ...`.
+* If no branches are specified, the repository’s current `HEAD` is used.
+
+#### Authors
+* `--author` and `--exclude-author` accept name or email substrings (case-insensitive match by `git log`).
+* Multiple values may be provided by repeating the option.
+
+#### Paths
+* `--path` and `--exclude-path` accept comma-separated values or repeated options.
+* Globs are supported by git pathspec. Excludes are translated to `:(exclude)pattern` and applied consistently.
+* When only excludes are present, `.` is included to ensure the pathspec is valid (mirrors tests in `spec/pretty_git/git/provider_spec.rb`).
+
+#### Time period
+* `--since` / `--until`: ISO8601 (e.g. `2025-01-31T12:00:00Z`) or `YYYY-MM-DD`.
+* Date-only values are interpreted as UTC midnight to avoid timezone drift in different environments.
+* Time values are normalized to UTC in outputs.
+
+#### Verbose diagnostics
+* `--verbose` prints the effective `git log` command and active filters to stderr.
+* Useful for debugging filters, CI logs, or when reproducing results locally.
 
 ### Output format
 Set via `--format`. For file formats it’s recommended to use `--out`.
@@ -207,19 +244,31 @@ Markdown example:
 pretty-git files . --paths app,lib --format csv
 ```
 CSV columns: `path,commits,additions,deletions,changes`.
+
 XML example:
 ```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" />
+<?xml version="1.0" encoding="UTF-8"?>
+<report>
+  <report>files</report>
   <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>
+  <items>
+    <item>
+      <path>app/models/user.rb</path>
+      <commits>42</commits>
+      <additions>2100</additions>
+      <deletions>1400</deletions>
+      <changes>3500</changes>
+    </item>
+    <item>
+      <path>app/services/auth.rb</path>
+      <commits>35</commits>
+      <additions>1500</additions>
+      <deletions>900</deletions>
+      <changes>2400</changes>
+    </item>
+  </items>
+</report>
 ```
 
 ### 🔥 heatmap — commit heatmap
@@ -337,15 +386,20 @@ Notes:
 
 XML example:
 ```xml
-<ownership>
+<?xml version="1.0" encoding="UTF-8"?>
+<report>
   <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"/>
+    <item>
+      <path>lib/a.rb</path>
+      <owner>Alice &lt;a@example.com&gt;</owner>
+      <owner_share>82.5</owner_share>
+      <authors>2</authors>
+    </item>
   </items>
-  
-</ownership>
+</report>
 ```
 
 ## 📤 Exports
@@ -376,6 +430,13 @@ _Example terminal output (theme: basic)._
   {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
   ```
 
+## 🧾 Schemas and Examples
+Machine-readable examples and schemas live under `docs/export_schemas/` and `docs/examples/`.
+
+* **Schemas**: see `docs/export_schemas/README.md` for JSON and XML schema notes.
+* **Examples**: example payloads for JSON/XML for each report under `docs/examples/`.
+* Intended use: validation in CI, contract documentation, and integration tests.
+
 ### CSV
 * **Structure**: flat table, first line is header.
 * **Encoding**: UTF‑8 without BOM.
@@ -474,16 +535,46 @@ These lists mirror the implementation in `lib/pretty_git/analytics/languages.rb`
 ## 🔁 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.
 
+## ⚡ Performance Tips
+* Prefer narrowing by `--path`/`--exclude-path` and `--since/--until` on large repositories.
+* Use multiple `--branch` only when you explicitly want to include several heads; otherwise rely on current `HEAD`.
+* For CI, cache the repository and fetch shallow history if full history is unnecessary for your report.
+
+## 🤖 CI Usage
+Examples for common pipelines:
+
+```yaml
+# GitHub Actions (excerpt)
+jobs:
+  reports:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - run: gem install pretty-git
+      - run: pretty-git authors . --format json --out authors.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: authors-report
+          path: authors.json
+```
+
 ## 🪟 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
+Primary targets — macOS/Linux. Windows is supported best‑effort. See detailed notes in [docs/windows.md](docs/windows.md).
+
+Highlights:
+* Running via Git Bash/WSL is recommended.
+* CRLF output from git is handled by the parser; exports use UTF‑8 with LF.
+* Path filters are normalized to Unicode NFC when available; otherwise pass‑through.
+* Colors can be disabled by `--no-color` or `--theme mono`.
 
 ## 🩺 Diagnostics and Errors
 Typical issues and solutions:
 
 * **Unknown report/format** — check the first argument and `--format`.
+* **Debugging** — add `--verbose` to see the effective `git log` command and applied filters.
 * **Invalid date format** — use ISO8601 or `YYYY-MM-DD` (e.g., `2025-01-31` or `2025-01-31T12:00:00Z`).
 * **Git not available** — ensure `git` is installed and in the `PATH`.
 * **Empty result** — check your filters (`--since/--until`, `--branch`, `--path`); your selection might be too narrow.
@@ -506,5 +597,7 @@ bundle exec rubocop
 
 Style — RuboCop clean. Tests cover aggregators, renderers, CLI, and integration scenarios (determinism, format correctness).
 
+For detailed testing strategy, determinism rules, and golden tests workflow (how to run/update snapshots), see `docs/testing.md`.
+
 ## 📄 License
 MIT © Contributors

data/README.ru.md

@@ -20,6 +20,7 @@
 
 ## Содержание
 - [Возможности](#возможности)
+- [Почему Pretty Git](#почему-pretty-git)
 - [Требования](#требования)
 - [Установка](#установка)
 - [Быстрый старт](#быстрый-старт)
@@ -41,11 +42,14 @@
 - [Экспорт в форматы](#экспорт-в-форматы)
   - [Console](#console)
   - [JSON](#json)
+  - [Схемы и примеры](#схемы-и-примеры)
   - [CSV](#csv)
   - [Markdown](#markdown)
   - [YAML](#yaml)
   - [XML](#xml)
 - [Детерминизм и сортировка](#детерминизм-и-сортировка)
+- [Советы по производительности](#советы-по-производительности)
+- [Использование в CI](#использование-в-ci)
 - [Советы по Windows](#советы-по-windows)
 - [Диагностика и ошибки](#диагностика-и-ошибки)
 - [FAQ](#faq)
@@ -58,6 +62,13 @@
 * __Экспорт__: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
 * __Вывод__: в stdout или файл через `--out`.
 
+## ❓ Почему Pretty Git
+* __Один инструмент — много представлений__: активность, авторство, риск, языки, владение — единый UX и форматы.
+* __Детерминированные результаты__: стабильные сортировки и форматирование — удобно для CI и диффов.
+* __Сразу форматы__: JSON/CSV/Markdown/YAML/XML из коробки с чёткими правилами.
+* __Достаточно быстро__: потоковый `git log` и ин‑мемори агрегации; советы для больших репозиториев ниже.
+* __Безопасные дефолты__: разумные игноры путей и бинарников для отчёта `languages`; цветной консольный вывод с темами.
+
 ## ⚙️ Требования
 * __Ruby__: >= 3.4 (рекомендуется 3.4.x)
 * __Git__: установлен и доступен в `PATH`
@@ -124,6 +135,10 @@ bundle exec bin/pretty-git activity . --time-bucket week --since 2025-01-01 \
 pretty-git <report> <repo_path> [options]
 ```
 
+Примечания:
+* `<repo_path>` по умолчанию — `.` (если опущен).
+* Репозиторий можно указать и через флаг `--repo PATH` как альтернативу позиционному аргументу.
+
 Доступные отчёты: `summary`, `activity`, `authors`, `files`, `heatmap`, `languages`, `hotspots`, `churn`, `ownership`.
 
 Ключевые опции:
@@ -138,12 +153,15 @@ pretty-git <report> <repo_path> [options]
 * __--no-color__ Отключить цвета в консоли
 * __--theme__ `basic|bright|mono` — тема оформления консольного вывода (по умолчанию `basic`; `mono` принудительно отключает цвета)
 * __--metric__ `bytes|files|loc` — метрика для отчёта `languages` (по умолчанию `bytes`)
+* **--verbose** Печатать отладочную информацию (эффективная команда git, применённые фильтры)
 
 Примеры значений с несколькими параметрами:
 
 ```bash
-# Несколько веток
+# Несколько веток (трактуются как явные ревизии)
 pretty-git summary . --branch main --branch develop
+## Эквивалентно:
+## git log main develop -- ...
 
 # Фильтрация по авторам (включая/исключая)
 pretty-git authors . --author alice@example.com --exclude-author bot@company
@@ -153,7 +171,30 @@ pretty-git files . --path app,lib --exclude-path vendor,node_modules
 ```
 
 ### Фильтры
-Фильтры применяются на этапе выборки коммитов и последующей агрегации. Формат дат: ISO8601 или `YYYY-MM-DD`. Если часовой пояс не указан — используется локальная зона пользователя; на выводе время нормализуется к UTC.
+Фильтры применяются на этапе выборки коммитов и последующей агрегации. Ниже — точные правила и советы.
+
+#### Ветки / ревизии
+* `--branch BRANCH` можно указывать несколько раз.
+* Несколько веток трактуются как явные ревизии для `git log` (без неявного диапазона от merge-base). Пример: `--branch main --branch develop` → `git log main develop -- ...`.
+* Если ветки не указаны — используется текущий `HEAD` репозитория.
+
+#### Авторы
+* `--author` и `--exclude-author` принимают подстроки имени или email (регистронезависимо по логике `git log`).
+* Можно передавать несколько значений повтором опции.
+
+#### Пути
+* `--path` и `--exclude-path` принимают значения через запятую или повтором опции.
+* Поддерживаются glob‑маски git pathspec. Исключения переводятся в `:(exclude)pattern` и применяются последовательно.
+* Если заданы только исключения — автоматически добавляется `.` для корректного pathspec (как в тестах `spec/pretty_git/git/provider_spec.rb`).
+
+#### Период времени
+* `--since` / `--until`: ISO8601 (например, `2025-01-31T12:00:00Z`) или `YYYY-MM-DD`.
+* Даты без времени интерпретируются как полночь UTC, чтобы исключить сдвиги между средами.
+* На выводе время нормализуется к UTC.
+
+#### Подробная диагностика (verbose)
+* `--verbose` печатает эффективную команду `git log` и активные фильтры в stderr.
+* Полезно для отладки фильтров, логов CI и воспроизведения результатов локально.
 
 ### Формат вывода
 Задаётся через `--format`. Для файловых форматов рекомендуется использовать `--out`.
@@ -207,19 +248,31 @@ CSV-колонки: `author,author_email,commits,additions,deletions,avg_commit_
 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" />
+<?xml version="1.0" encoding="UTF-8"?>
+<report>
+  <report>files</report>
   <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>
+  <items>
+    <item>
+      <path>app/models/user.rb</path>
+      <commits>42</commits>
+      <additions>2100</additions>
+      <deletions>1400</deletions>
+      <changes>3500</changes>
+    </item>
+    <item>
+      <path>app/services/auth.rb</path>
+      <commits>35</commits>
+      <additions>1500</additions>
+      <deletions>900</deletions>
+      <changes>2400</changes>
+    </item>
+  </items>
+</report>
 ```
 
 ### 🔥 heatmap — тепловая карта
@@ -335,15 +388,20 @@ CSV‑колонки: `path,owner,owner_share,authors`.
 
 Пример XML:
 ```xml
-<ownership>
+<?xml version="1.0" encoding="UTF-8"?>
+<report>
   <report>ownership</report>
   <generated_at>2025-01-31T00:00:00Z</generated_at>
   <repo_path>.</repo_path>
   <items>
-    <item path="lib/a.rb" owner="Alice &lt;a@example.com&gt;" owner_share="82.5" authors="2"/>
+    <item>
+      <path>lib/a.rb</path>
+      <owner>Alice &lt;a@example.com&gt;</owner>
+      <owner_share>82.5</owner_share>
+      <authors>2</authors>
+    </item>
   </items>
-  
-</ownership>
+</report>
 ```
 
 ## 🚫 Игнорируемые директории и файлы
@@ -402,6 +460,13 @@ _Пример вывода в терминале (тема: basic)._
   {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
   ```
 
+## 🧾 Схемы и примеры
+Машиночитаемые примеры и схемы лежат в `docs/export_schemas/` и `docs/examples/`.
+
+* __Схемы__: смотрите `docs/export_schemas/README.md` с заметками по JSON и XML схемам.
+* __Примеры__: примеры нагрузок для JSON/XML по каждому отчёту — в `docs/examples/`.
+* Назначение: валидация в CI, документация контрактов и интеграционные тесты.
+
 ### CSV
 * __Структура__: плоская таблица, первая строка — заголовок.
 * __Кодировка__: UTF‑8, без BOM.
@@ -475,6 +540,32 @@ _Пример вывода в терминале (тема: basic)._
 ## 🔁 Детерминизм и сортировка
 Вывод детерминирован при одинаковых входных данных. Сортировка для файлов/авторов: по количеству изменений (desc), затем по числу коммитов (desc), затем по пути/имени (asc). Лимиты применяются поверх отсортированного списка; значение `all` или `0` означает отсутствие ограничения.
 
+## ⚡ Советы по производительности
+* На больших репозиториях сужайте выборку `--path/--exclude-path` и `--since/--until`.
+* Несколько `--branch` используйте, только если нужно включить несколько голов; иначе полагайтесь на текущий `HEAD`.
+* В CI кешируйте репозиторий и используйте shallow‑fetch, если полная история не нужна для выбранного отчёта.
+
+## 🤖 Использование в CI
+Пример для GitHub Actions:
+
+```yaml
+# GitHub Actions (фрагмент)
+jobs:
+  reports:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - run: gem install pretty-git
+      - run: pretty-git authors . --format json --out authors.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: authors-report
+          path: authors.json
+```
+
 ## 🪟 Советы по Windows
 Целевая платформа — macOS/Linux. Windows поддерживается в режиме best‑effort:
 * Запуск через Git Bash/WSL допустим
@@ -484,7 +575,8 @@ _Пример вывода в терминале (тема: basic)._
 ## 🩺 Диагностика и ошибки
 Типичные ошибки и решения:
 
-* __Неизвестный отчёт/формат__ — проверьте значение первого аргумента и `--format`.
+* **Неизвестный отчёт/формат** — проверьте первый аргумент и `--format`.
+* **Отладка** — добавьте `--verbose`, чтобы увидеть фактическую команду `git log` и применённые фильтры.
 * __Неверный формат даты__ — используйте ISO8601 или `YYYY-MM-DD` (например, `2025-01-31` или `2025-01-31T12:00:00Z`).
 * __Git недоступен__ — убедитесь, что `git` установлен и доступен в `PATH`.
 * __Пустой результат__ — проверьте фильтры (`--since/--until`, `--branch`, `--path`), возможно, выборка слишком узкая.
@@ -507,5 +599,7 @@ bundle exec rubocop
 
 Стиль — RuboCop без ошибок. Тесты покрывают агрегаторы, рендереры, CLI и интеграционные сценарии (детерминизм, корректность форматов).
 
+Подробнее о стратегии тестирования, правилах детерминизма и процессе работы с golden‑тестами (как запускать/обновлять снапшоты) см. `docs/testing.md`.
+
 ## 📄 Лицензия
 MIT © Contributors

data/lib/pretty_git/analytics/languages.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'json'
+require 'find'
 
 module PrettyGit
   module Analytics
@@ -79,30 +81,46 @@ module PrettyGit
     # Default metric: bytes (similar to GitHub Linguist approach).
     # rubocop:disable Metrics/ClassLength
     class Languages
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def self.call(_enum, filters)
         repo = filters.repo_path
-        items = calculate(repo, include_globs: filters.paths, exclude_globs: filters.exclude_paths)
+        prof = ENV['PG_PROF'] == '1'
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC) if prof
         metric = (filters.metric || 'bytes').to_s
+        items = calculate(repo, include_globs: filters.paths, exclude_globs: filters.exclude_paths, metric: metric)
         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, totals, metric)
+        res = build_result(repo, items, totals, metric)
+        if prof
+          t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          elapsed = (t1 - t0)
+          files = totals[:files]
+          warn format(
+            '[pg_prof] languages: time=%<sec>.3fs files=%<files>d metric=%<metric>s',
+            { sec: elapsed, files: files, metric: metric }
+          )
+          summary = { component: 'languages', time_sec: elapsed, files: files, metric: metric }
+          warn("[pg_prof_json] #{summary.to_json}")
+        end
+        res
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # rubocop:disable Metrics/AbcSize
-      def self.calculate(repo_path, include_globs:, exclude_globs:)
+      def self.calculate(repo_path, include_globs:, exclude_globs:, metric: 'bytes')
         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)
-            ext = File.extname(abs_path).downcase
+          each_source_file(include_globs, exclude_globs) do |path|
+            basename = File.basename(path)
+            ext = File.extname(path).downcase
             lang = FILENAME_TO_LANG[basename] || EXT_TO_LANG[ext]
             next unless lang
 
-            size = safe_file_size(abs_path)
-            lines = safe_count_lines(abs_path)
+            size = safe_file_size(path)
+            lines = metric == 'loc' ? safe_count_lines(path) : 0
             agg = by_lang[lang]
             agg[:bytes] += size
             agg[:files] += 1
@@ -113,14 +131,33 @@ module PrettyGit
       end
       # rubocop:enable Metrics/AbcSize
 
-      def self.each_source_file(include_globs, exclude_globs)
-        # Build list of files under repo respecting includes/excludes
-        all = Dir.glob('**/*', File::FNM_DOTMATCH).select { |p| File.file?(p) }
-        files = all.reject { |p| vendor_path?(p) || binary_ext?(p) }
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def self.each_source_file(include_globs, exclude_globs, &block)
+        # Traverse tree with early prune for vendor/binary paths, then apply include/exclude
+        files = []
+        Find.find('.') do |path|
+          rel = path.sub(%r{^\./}, '')
+          # Prune vendor dirs early
+          if File.directory?(path)
+            dir = File.basename(path)
+            if VENDOR_DIRS.include?(dir)
+              Find.prune
+              next
+            end
+            next
+          end
+          next unless File.file?(path)
+          next if rel.empty?
+          next if vendor_path?(rel) || binary_ext?(rel)
+
+          files << rel
+        end
+
         files = filter_includes(files, include_globs)
         files = filter_excludes(files, exclude_globs)
-        files.each { |rel| yield File.expand_path(rel) }
+        files.each { |rel| block.call(rel) }
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def self.safe_file_size(path)
         File.size(path)
@@ -141,7 +178,8 @@ module PrettyGit
         return files if globs.empty?
 
         allowed = globs.flat_map { |g| Dir.glob(g) }
-        files.select { |f| allowed.include?(f) }
+        allowed_map = allowed.each_with_object({}) { |f, h| h[f] = true }
+        files.select { |f| allowed_map[f] }
       end
 
       def self.filter_excludes(files, globs)
@@ -149,7 +187,8 @@ module PrettyGit
         return files if globs.empty?
 
         blocked = globs.flat_map { |g| Dir.glob(g) }
-        files.reject { |f| blocked.include?(f) }
+        blocked_map = blocked.each_with_object({}) { |f, h| h[f] = true }
+        files.reject { |f| blocked_map[f] }
       end
 
       def self.vendor_path?(path)