Collapse duplicated bump result-message formatting into canonical bump_output

[lodyai]

Summary

lading/commands/bump_output.py is a dead, divergent duplicate of formatting
logic that lading/commands/bump.py re-implements inline. The two copies have
drifted apart, which has already produced a latent output bug.

Evidence

bump_output.py defines BumpChanges, _build_changes_description,
_format_no_changes_message, _format_header, _format_manifest_path, and
_format_result_message. bump.py defines its own inline copies of every one of
them (bump.py:84-154, 396-425) and uses those. bump_output is imported only
by tests (tests/unit/test_bump_command_internals.py) and is described by
docs/developers-guide.md:93-96 as if it were the real home of the formatting.

The copies have diverged:

• bump_output.BumpChanges has 3 fields (manifests, documents, lockfiles);
  bump.BumpChanges has 4 (adds transposed_readmes). README transposition was
  only ever added to the inline copy.
• bump_output._build_changes_description (bump_output.py:73-77) renders 3+
  categories with an Oxford comma ("A, B, and C"); bump._build_changes_description
  (bump.py:118) uses " and ".join(...), producing "A and B and C and D" for the
  now-four categories — grammatically wrong output that the bump_output version was
  evidently written to fix but was never wired in.

Fix

Complete the extraction the docs already describe:

1. Add transposed_readmes to bump_output.BumpChanges and _format_result_message,
   and port _has_changes.
2. Delete the inline copies from bump.py and import from bump_output.
3. Update tests to target the single home.

This removes ~120 lines of duplication and fixes the description grammar.

Canonical implementation mandate

• One canonical home: lading.commands.bump_output is the sole owner of
  BumpChanges and all bump result-message formatting. No other module may
  re-declare them.
• Document it: record the canonical home and its responsibility in
  docs/developers-guide.md (correct the existing §describing bump_output).
• Property tests (Hypothesis): generate arbitrary combinations of changed
  categories (0–4 present, varying counts) and assert the description is
  grammatically well-formed (correct Oxford-comma joining for 1, 2, and 3+
  categories) and that every changed path appears exactly once with the correct
  suffix tag.
• Snapshot assertions (syrupy .ambr): snapshot the full rendered result
  message for representative cases (no changes, single category, all four
  categories, dry-run vs apply). Reuse/extend
  tests/unit/__snapshots__/test_bump_command_internals.ambr.
• Model checking (CrossHair): applicable to the pure helpers
  (_build_changes_description, _format_header, _format_manifest_path);
  add contracts and run CrossHair over them.

Acceptance criteria

• bump.py contains no formatting/BumpChanges definitions; it imports from bump_output.
• bump_output.BumpChanges includes transposed_readmes; _format_result_message renders it.
• Oxford-comma grammar holds for 1/2/3/4 categories (property test).
• Snapshot coverage for the rendered messages.
• docs/developers-guide.md names bump_output as the canonical home.

[coderabbitai]

🔗 Related PRs

leynos/netsuke#302 - Overhaul Netsuke CLI documentation contract [merged]
leynos/ortho-config#328 - Record migration rules for existing consumers (5.2.2) [merged]
leynos/dear-diary#42 - Adopt shared-actions stage-release-artefacts for cargo-binstall [closed]
#85 - Regenerate bump lockfiles (#65) [closed]
#87 - Move workspace README adoption to bump (#66) [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Extend bump_output.py to include the transposed_readmes field and correct Oxford-comma joining, making it the complete canonical implementation.
• Delete all inline formatting code from bump.py and replace with imports from bump_output.
• Add Hypothesis property tests asserting grammatical correctness and path coverage; add CrossHair contracts to pure helpers for model checking.
• Update snapshots and documentation to reflect the consolidated architecture.

Design Choices

Design Choice 1: CrossHair integration approach

Options Considered:

1. Add crosshair-tool as a dev dependency and use @ensure/@require decorators on pure functions, running crosshair check as a test command.
2. Use crosshair-hypothesis integration to run CrossHair analysis via existing Hypothesis infrastructure.
3. Implement contracts inline using assertions and run crosshair watch during development only.

Chosen Option: 1

Rationale: Add crosshair-tool with explicit contracts as decorators, invoked via crosshair check; this aligns with the ticket's phrasing "add contracts and run CrossHair over them" and keeps contract-based checking separate from property-based testing.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Extend bump_output Module to Full Capability

Bring bump_output.py to feature parity with bump.py's inline implementation, adding the missing transposed_readmes field and ensuring correct Oxford-comma grammar for up to four change categories.

Task 1: Add transposed_readmes Field to BumpChanges

Extend the BumpChanges dataclass to include the fourth category that bump.py already tracks.

• Add transposed_readmes: cabc.Sequence[Path] = () as the fourth field in lading/commands/bump_output.py's BumpChanges dataclass
• Position the field after lockfiles to maintain consistent ordering with the inline version

Task 2: Port the _has_changes Helper

Introduce the predicate function that checks whether any change category is non-empty.

• Create _has_changes(changes: BumpChanges) -> bool in lading/commands/bump_output.py
• Evaluate truthiness across all four fields: manifests, documents, lockfiles, transposed_readmes
• Return True if any sequence is non-empty

Task 3: Update _build_changes_description for Four Categories

Ensure the description builder handles up to four categories with proper Oxford-comma joining.

• Add a conditional block in _build_changes_description to append f"{len(changes.transposed_readmes)} readme file(s)" when transposed_readmes is non-empty
• Verify the existing three-branch Oxford-comma logic (1, 2, 3+) works correctly when four parts are present
• Retain the named constants _SINGLE_CHANGE_CATEGORY_COUNT and _PAIRED_CHANGE_CATEGORY_COUNT for clarity

Task 4: Update _format_result_message for Readme Paths

Extend the result formatter to render transposed readme paths with the (readme) suffix.

• Replace the inline any(...) guard with a call to _has_changes(changes)
• After the documents loop, add a loop over changes.transposed_readmes that appends f"- {_format_manifest_path(readme_path, workspace_root)} (readme)"
• Maintain ordering: manifests → documents → readmes → lockfiles

🤖 Prompt for AI agents

Extend `lading/commands/bump_output.py` to full feature parity with `bump.py`'s
inline implementation, making it the canonical home for all bump result-message
formatting logic.

- In the `BumpChanges` dataclass, add `transposed_readmes: cabc.Sequence[Path] =
()` as the fourth field, positioned after `lockfiles`
- Create a `_has_changes(changes: BumpChanges) -> bool` function that evaluates
truthiness across all four fields (`manifests`, `documents`, `lockfiles`,
`transposed_readmes`) and returns `True` if any sequence is non-empty
- In `_build_changes_description`, add a conditional block that appends
`f"{len(changes.transposed_readmes)} readme file(s)"` when `transposed_readmes`
is non-empty; verify the existing three-branch Oxford-comma logic (`1`, `2`,
`3+` categories) works correctly with up to four parts present; retain the named
constants `_SINGLE_CHANGE_CATEGORY_COUNT` and `_PAIRED_CHANGE_CATEGORY_COUNT`
- In `_format_result_message`, replace the inline `any(...)` guard with a call
to `_has_changes(changes)`; after the `documents` loop, add a loop over
`changes.transposed_readmes` appending `f"- {_format_manifest_path(readme_path,
workspace_root)} (readme)"`; maintain path ordering: manifests → documents →
readmes → lockfiles

Phase 2: Consolidate bump.py Imports

Remove all duplicated formatting definitions from bump.py and wire it to import from the canonical bump_output module.

Task 1: Delete Inline Formatting Definitions from bump.py

Excise the ~120 lines of duplicated code.

• Delete the inline BumpChanges dataclass (lines ~84–91)
• Delete _build_changes_description (lines ~107–118)
• Delete _format_no_changes_message (lines ~121–127)
• Delete _format_header (lines ~130–134)
• Delete _format_manifest_path (lines ~137–142)
• Delete _has_changes (lines ~147–154)
• Delete _format_result_message (lines ~396–425)

Task 2: Add Imports from bump_output

Wire the coordinator to use the canonical module.

• Add from lading.commands.bump_output import BumpChanges, _format_result_message to the imports in lading/commands/bump.py
• Verify all existing call sites in bump.py compile and behave identically (the function signatures are unchanged)

🤖 Prompt for AI agents

Remove ~120 lines of duplicated formatting code from `lading/commands/bump.py`
and replace with imports from the canonical `bump_output` module.

- Delete the following inline definitions from `bump.py`:
  - `BumpChanges` dataclass (lines ~84–91)
  - `_build_changes_description` (lines ~107–118)
  - `_format_no_changes_message` (lines ~121–127)
  - `_format_header` (lines ~130–134)
  - `_format_manifest_path` (lines ~137–142)
  - `_has_changes` (lines ~147–154)
  - `_format_result_message` (lines ~396–425)
- Add `from lading.commands.bump_output import BumpChanges,
_format_result_message` to the imports section of `lading/commands/bump.py`
- Verify all existing call sites in `bump.py` compile and behave identically —
the function signatures are unchanged

Phase 3: Update and Extend Test Coverage

Redirect existing tests to the canonical module, add Hypothesis property tests for grammar correctness, integrate CrossHair contracts, and update snapshot assertions.

Task 1: Update Existing Tests to Target bump_output

Ensure all formatting tests import from the canonical home.

• In tests/unit/test_bump_command_internals.py, change imports of BumpChanges, _build_changes_description, and _format_result_message to come from lading.commands.bump_output rather than lading.commands.bump
• Keep imports of _format_no_changes_message, _format_header, _format_manifest_path from bump_output (already there)
• Run existing tests to confirm they pass with the consolidated module

Task 2: Add Hypothesis Property Tests for Grammar Correctness

Create property-based tests that verify Oxford-comma joining across arbitrary category combinations.

• Add new test functions in tests/unit/test_bump_command_internals.py using @given with strategies generating:
  • manifests: st.lists(st.builds(Path, st.text(min_size=1, max_size=20)), min_size=0, max_size=5)
  • documents, lockfiles, transposed_readmes: same pattern
• Construct BumpChanges from the generated sequences
• Assert invariants on _build_changes_description(changes):
  • When 1 category present: no " and " in result
  • When 2 categories present: exactly one " and ", no commas
  • When 3+ categories present: result matches pattern "A, B, ..., and Z" (Oxford comma)
• Assert invariant: every non-empty category count appears in the description string

Task 3: Add Hypothesis Property Tests for Path Coverage

Verify that _format_result_message emits every changed path exactly once with the correct suffix.

• Generate arbitrary BumpChanges instances with non-overlapping path sets
• Assert the formatted message contains each manifest path without suffix, each document path with (documentation), each readme path with (readme), each lockfile path with (lockfile)
• Assert no path appears more than once

Task 4: Add CrossHair Dependency and Contracts

Introduce CrossHair for model checking the pure formatting helpers.

• Add crosshair-tool>=0.0.75 to [dependency-groups] → dev in pyproject.toml
• In lading/commands/bump_output.py, add imports: from crosshair import post_condition (or ensure depending on API)
• Add contracts to _build_changes_description:
  • Post-condition: result is non-empty string when any category is non-empty
  • Post-condition: result contains no consecutive " and " substrings
• Add contracts to _format_header:
  • Post-condition: result starts with "Dry run;" when dry_run=True, otherwise starts with "Updated"
• Add contracts to _format_manifest_path:
  • Post-condition: result does not start with / when path is relative to workspace_root
• Document in a code comment or docstring how to run: crosshair check lading/commands/bump_output.py

Task 5: Update Snapshot Assertions

Extend snapshot coverage to include all representative cases.

• Ensure snapshots exist for:
  • No changes (dry-run and live)
  • Single category only (manifests, documents, readmes, lockfiles)
  • All four categories together (dry-run and live)
• Update tests/unit/__snapshots__/test_bump_command_internals.ambr via test execution
• Verify snapshot names follow existing convention: test_format_result_message_handles_changes[case_name]

🤖 Prompt for AI agents

Update and extend the test suite in `tests/unit/test_bump_command_internals.py`
to target the canonical `bump_output` module, add Hypothesis property tests,
integrate CrossHair contracts into `bump_output.py`, and regenerate snapshots.

**Update existing imports:**
- Change imports of `BumpChanges`, `_build_changes_description`, and
`_format_result_message` to come from `lading.commands.bump_output` rather than
`lading.commands.bump`
- Keep imports of `_format_no_changes_message`, `_format_header`,
`_format_manifest_path` from `bump_output`

**Add Hypothesis property tests for grammar correctness:**
- Add new test functions using `@given` with strategies generating
`st.lists(st.builds(Path, st.text(min_size=1, max_size=20)), min_size=0,
max_size=5)` for each of `manifests`, `documents`, `lockfiles`, and
`transposed_readmes`
- Construct `BumpChanges` from the generated sequences and assert invariants on
`_build_changes_description(changes)`:
  - When 1 category present: no `" and "` in result
  - When 2 categories present: exactly one `" and "`, no commas
- When 3+ categories present: result matches the Oxford-comma pattern `"A, B,
..., and Z"`
  - Every non-empty category count appears in the description string

**Add Hypothesis property tests for path coverage:**
- Generate arbitrary `BumpChanges` instances with non-overlapping path sets
- Assert `_format_result_message` contains each manifest path without suffix,
each document path with `(documentation)`, each readme path with `(readme)`,
each lockfile path with `(lockfile)`, and that no path appears more than once

**Add CrossHair dependency and contracts:**
- Add `crosshair-tool>=0.0.75` to `[dependency-groups]` → `dev` in
`pyproject.toml`
- In `lading/commands/bump_output.py`, import `post_condition` (or `ensure`)
from `crosshair`
- Add post-condition contracts to `_build_changes_description` (non-empty result
when any category non-empty; no consecutive `" and "` substrings),
`_format_header` (starts with `"Dry run;"` when `dry_run=True`, otherwise
`"Updated"`), and `_format_manifest_path` (result does not start with `/` when
path is relative)
- Add a comment or docstring noting how to run: `crosshair check
lading/commands/bump_output.py`

**Update snapshots:**
- Ensure snapshots cover: no changes (dry-run and live), single category only
(manifests, documents, readmes, lockfiles), and all four categories together
(dry-run and live)
- Regenerate `tests/unit/__snapshots__/test_bump_command_internals.ambr` via
test execution
- Verify snapshot names follow the convention:
`test_format_result_message_handles_changes[case_name]`

Phase 4: Update Documentation

Record the canonical home and its responsibilities in the developers guide.

Update developers-guide.md

Clarify that bump_output is the single source of truth for bump formatting.

• In docs/developers-guide.md lines 93–98, revise the description to explicitly state:
  • lading.commands.bump_output is the canonical and sole owner of BumpChanges and all result-message formatting
  • BumpChanges now includes four fields: manifests, documents, lockfiles, transposed_readmes
  • No other module may re-declare these types or functions
• Add a sentence noting the Oxford-comma joining behaviour for 3+ categories
• Mention that CrossHair contracts are present and can be checked via crosshair check

🤖 Prompt for AI agents

Update `docs/developers-guide.md` to reflect the consolidated architecture of
bump formatting.

- At lines 93–98, revise the description of `bump_output` to explicitly state:
- `lading.commands.bump_output` is the **canonical and sole** owner of
`BumpChanges` and all result-message formatting
- `BumpChanges` now includes four fields: `manifests`, `documents`, `lockfiles`,
`transposed_readmes`
  - No other module may re-declare these types or functions
- Add a sentence noting the Oxford-comma joining behaviour for 3+ categories
- Add a sentence mentioning that CrossHair contracts are present and can be
checked via `crosshair check lading/commands/bump_output.py`

Research

The project is a Python CLI tool (lading) for managing Rust workspace versioning. The lading/commands/ directory contains the bump command implementation split across several modules: bump.py (main coordinator), bump_output.py (intended canonical formatting home), bump_docs.py, bump_lockfiles.py, bump_readme.py, and bump_toml.py. Testing infrastructure uses pytest with BDD steps (tests/bdd/), unit tests (tests/unit/), syrupy snapshots, and Hypothesis property tests. CrossHair is not currently installed. Documentation lives in docs/developers-guide.md.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend `lading/commands/bump_output.py` to full feature parity with `bump.py`'s
inline implementation, making it the canonical home for all bump result-message
formatting logic.

- In the `BumpChanges` dataclass, add `transposed_readmes: cabc.Sequence[Path] =
()` as the fourth field, positioned after `lockfiles`
- Create a `_has_changes(changes: BumpChanges) -> bool` function that evaluates
truthiness across all four fields (`manifests`, `documents`, `lockfiles`,
`transposed_readmes`) and returns `True` if any sequence is non-empty
- In `_build_changes_description`, add a conditional block that appends
`f"{len(changes.transposed_readmes)} readme file(s)"` when `transposed_readmes`
is non-empty; verify the existing three-branch Oxford-comma logic (`1`, `2`,
`3+` categories) works correctly with up to four parts present; retain the named
constants `_SINGLE_CHANGE_CATEGORY_COUNT` and `_PAIRED_CHANGE_CATEGORY_COUNT`
- In `_format_result_message`, replace the inline `any(...)` guard with a call
to `_has_changes(changes)`; after the `documents` loop, add a loop over
`changes.transposed_readmes` appending `f"- {_format_manifest_path(readme_path,
workspace_root)} (readme)"`; maintain path ordering: manifests → documents →
readmes → lockfiles
===============================================================================

Task: 2

Remove ~120 lines of duplicated formatting code from `lading/commands/bump.py`
and replace with imports from the canonical `bump_output` module.

- Delete the following inline definitions from `bump.py`:
  - `BumpChanges` dataclass (lines ~84–91)
  - `_build_changes_description` (lines ~107–118)
  - `_format_no_changes_message` (lines ~121–127)
  - `_format_header` (lines ~130–134)
  - `_format_manifest_path` (lines ~137–142)
  - `_has_changes` (lines ~147–154)
  - `_format_result_message` (lines ~396–425)
- Add `from lading.commands.bump_output import BumpChanges,
_format_result_message` to the imports section of `lading/commands/bump.py`
- Verify all existing call sites in `bump.py` compile and behave identically —
the function signatures are unchanged
===============================================================================

Task: 3

Update and extend the test suite in `tests/unit/test_bump_command_internals.py`
to target the canonical `bump_output` module, add Hypothesis property tests,
integrate CrossHair contracts into `bump_output.py`, and regenerate snapshots.

**Update existing imports:**
- Change imports of `BumpChanges`, `_build_changes_description`, and
`_format_result_message` to come from `lading.commands.bump_output` rather than
`lading.commands.bump`
- Keep imports of `_format_no_changes_message`, `_format_header`,
`_format_manifest_path` from `bump_output`

**Add Hypothesis property tests for grammar correctness:**
- Add new test functions using `@given` with strategies generating
`st.lists(st.builds(Path, st.text(min_size=1, max_size=20)), min_size=0,
max_size=5)` for each of `manifests`, `documents`, `lockfiles`, and
`transposed_readmes`
- Construct `BumpChanges` from the generated sequences and assert invariants on
`_build_changes_description(changes)`:
  - When 1 category present: no `" and "` in result
  - When 2 categories present: exactly one `" and "`, no commas
- When 3+ categories present: result matches the Oxford-comma pattern `"A, B,
..., and Z"`
  - Every non-empty category count appears in the description string

**Add Hypothesis property tests for path coverage:**
- Generate arbitrary `BumpChanges` instances with non-overlapping path sets
- Assert `_format_result_message` contains each manifest path without suffix,
each document path with `(documentation)`, each readme path with `(readme)`,
each lockfile path with `(lockfile)`, and that no path appears more than once

**Add CrossHair dependency and contracts:**
- Add `crosshair-tool>=0.0.75` to `[dependency-groups]` → `dev` in
`pyproject.toml`
- In `lading/commands/bump_output.py`, import `post_condition` (or `ensure`)
from `crosshair`
- Add post-condition contracts to `_build_changes_description` (non-empty result
when any category non-empty; no consecutive `" and "` substrings),
`_format_header` (starts with `"Dry run;"` when `dry_run=True`, otherwise
`"Updated"`), and `_format_manifest_path` (result does not start with `/` when
path is relative)
- Add a comment or docstring noting how to run: `crosshair check
lading/commands/bump_output.py`

**Update snapshots:**
- Ensure snapshots cover: no changes (dry-run and live), single category only
(manifests, documents, readmes, lockfiles), and all four categories together
(dry-run and live)
- Regenerate `tests/unit/__snapshots__/test_bump_command_internals.ambr` via
test execution
- Verify snapshot names follow the convention:
`test_format_result_message_handles_changes[case_name]`
===============================================================================

Task: 4

Update `docs/developers-guide.md` to reflect the consolidated architecture of
bump formatting.

- At lines 93–98, revise the description of `bump_output` to explicitly state:
- `lading.commands.bump_output` is the **canonical and sole** owner of
`BumpChanges` and all result-message formatting
- `BumpChanges` now includes four fields: `manifests`, `documents`, `lockfiles`,
`transposed_readmes`
  - No other module may re-declare these types or functions
- Add a sentence noting the Oxford-comma joining behaviour for 3+ categories
- Add a sentence mentioning that CrossHair contracts are present and can be
checked via `crosshair check lading/commands/bump_output.py`

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!