Skip to content

Add combined, per-root, and comparison summary scopes - #832

Merged
helly25 merged 5 commits into
mainfrom
feature/summary-scopes
Sep 15, 2026
Merged

helly25 merged 5 commits into
mainfrom
feature/summary-scopes

Conversation

@helly25

@helly25 helly25 commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Add --summary-scope to combine statistics across roots, report each root separately, or summarize comparison categories. Existing summary groupings can now accompany comparison counts without losing left/right size information.

AG;DR

  • Add all (default), root, left-only, right-only, different, and identical scopes. left/right alias the one-sided categories; diff and compare expand to ordered category lists. Expansion removes duplicates, and repeating the flag replaces the list.
  • Scope selection is independent of per-path --compare-select. Paired categories emit separate tables for the two roots. Combined comparison statistics count both copies, including identical content.
  • Preserve ordinary summary grouping, templates, archive accounting, collection/shard feeds, and hash-verification feeds. Category scopes retain per-entry contributions until comparison classifies them; they do not replay expressions or actions. Combined and root scopes aggregate during the walk.
  • Keep --summary=compare as comparison counts and percentages. Bare --summary in comparison mode additionally requests ordinary counts/sizes when a scope is explicit. Scope without an active file-summary driver is a usage error, including --compare=summary --summary-scope=all and scopes following --summary=none. The shortcut expands to --summary=compare; users add --summary or a grouping for file statistics. Validation precedes traversal and actions.
  • Share summary rendering, label explicit scope/root output, preserve default ordinary output, and emit zero totals for empty populations. JSONL exposes scope and root.
  • Update registry help, comparison topic/examples, generated reference, changelog, and design documentation.

Validation: all seven affected Bazel targets passed (summary_test, globals_test, help_render_test, help_topic_test, run_test, xff_markdown_test, xff_notice_test). Tests include three roots, unequal pair sizes, category aliases/deduplication, combined counts, empty roots, replacement semantics, templates/collections, and invalid contexts. Normal pre-commit checks include changed-file clang-tidy, clang-format, shfmt, and shellcheck. macOS validation used the existing local Apple linker workaround; CI validates the supported platform matrix.

Category statistics require retained per-entry reduction data in addition to the comparison entries. Entries excluded from comparison classification do not enter category tables, even where special feeds include them in whole-root statistics. --summary-scope does not change histogram populations.

Follow-up validation: summary CLI and engine tests pass with regressions for both reported shortcut/scope combinations, explicit comparison-only summaries, clearing/restoring summaries, and rejection before execution. Regenerated Markdown passes its diff test; changed-file clang-tidy and formatting checks pass. Main now includes #831; its changelog-only conflict is resolved while retaining the feature notes.

Coverage follow-up: add direct engine and end-to-end cases for plain scope labels, count/name tie-breaking under --top, and empty comparison scope rejection. These exercise the 14 changed lines reported uncovered by CI. Both test targets pass locally; local coverage collection produced no usable line counters, so the measured patch percentage is verified by the Linux CI coverage job. No production behavior or thresholds changed in this follow-up.

CI coverage verification on 8aa6addaf: patch lines 275/275 (100.00%), branches 174/180 (96.67%), rating GOOD. The coverage gate passed.

@helly25
helly25 merged commit 9dc8a1f into main Sep 15, 2026
15 checks passed
@helly25
helly25 deleted the feature/summary-scopes branch September 15, 2026 21:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant