Domain leak: bump README transposition raises publish-named PublishPreparationError

[lodyai]

Summary

The lading bump path raises a publish-named error for README transposition
failures, coupling the bump domain to the publish domain and misnaming the
condition.

Evidence

bump.py:13 and bump_readme.py:27 import PublishPreparationError from
publish_manifest and raise it for README-transposition failures during
lading bump (bump.py:301-303, bump_readme.py:152-174). A bump-time failure
surfacing a PublishPreparation error is a domain leak and misnames the failure.

Fix

• Introduce a bump-domain error (e.g. ReadmeTranspositionError(LadingError)) in a
  bump module and raise that.
• If a shared staging error is genuinely intended, move it to a neutral module
  (e.g. exceptions.py) with a neutral name rather than leaving it in
  publish_manifest.

Domain ownership mandate

• Single canonical error per domain: README transposition failures are owned by
  the bump domain; publish staging failures by the publish domain. No cross-domain
  imports of error types for unrelated conditions.
• Document it: record the error taxonomy (which module owns which LadingError
  subclass) in docs/developers-guide.md.
• Property/behavioural tests: assert that README-transposition failure paths
  raise the new bump-domain error (missing workspace README; crate outside the
  workspace root). Keep the publish staging tests asserting the publish error.
• Snapshot assertions: snapshot the user-facing error messages so the rename is
  a reviewed change.
• Model checking: not applicable.

Acceptance criteria

• Bump README failures raise a bump-domain error, not PublishPreparationError.
• No bump module imports a publish-domain error type.
• Error taxonomy documented in docs/developers-guide.md.
• Tests assert the new error on both transposition failure paths.

[coderabbitai]

🔗 Related PRs

#63 - Document and detect dry-run failures with unindexed sibling crates (#60) [merged]
#70 - Interleave live publish packaging (#59) [merged]
#75 - Refresh stale Cargo lockfiles before publish preflight (#61) [merged]
#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

• Define ReadmeTranspositionError(LadingError) in lading/commands/bump_readme.py, following the codebase pattern of co-locating errors with their raise sites
• Replace all bump-domain usages of PublishPreparationError so no bump module imports publish-domain errors
• Update existing tests and add snapshot assertions to lock error message wording
• Document the new error in the developer guide's exception taxonomy table

Implementation Steps

Phase 1: Introduce Bump-Domain Error and Update Production Code

Define the new error type in the bump domain and replace all cross-domain usages, eliminating the import of publish-domain error types from bump modules.

Task 1: Define ReadmeTranspositionError in bump_readme.py

Add a new exception class to encapsulate README transposition failures within the bump domain.

• Add ReadmeTranspositionError(LadingError) class definition near the top of lading/commands/bump_readme.py, following the import of LadingError from lading.exceptions
• Include a docstring describing when this error is raised: missing workspace README, crate outside workspace root
• Remove the import of PublishPreparationError from publish_manifest

Task 2: Update raise sites in bump_readme.py

Replace PublishPreparationError with the new ReadmeTranspositionError at both raise locations.

• In _load_source_text: raise ReadmeTranspositionError when the workspace README.md does not exist
• In _resolve_crate_relative_path: raise ReadmeTranspositionError (with chained cause) when the crate path cannot be made relative to the workspace root
• Preserve the existing error messages verbatim to maintain user-facing behaviour

Task 3: Update bump.py to catch the new error type

Correct the exception handling in the README transposition orchestration.

• Remove the import of PublishPreparationError from publish_manifest
• Import ReadmeTranspositionError from bump_readme
• Update _process_readme_transposition to catch ReadmeTranspositionError instead of PublishPreparationError

Task 4: Update lading/exceptions.py docstring

Keep the package-level exception documentation accurate.

• Add ReadmeTranspositionError to the docstring's list of example subclasses
• Optionally add PublishPreparationError if missing (for completeness)

🤖 Prompt for AI agents

Introduce a new bump-domain exception `ReadmeTranspositionError` in
`lading/commands/bump_readme.py` and wire it up across all relevant production
files, removing all cross-domain imports of `PublishPreparationError`.

**`lading/commands/bump_readme.py`**
- Near the top of the file, after importing `LadingError` from
`lading.exceptions`, define a new class `ReadmeTranspositionError(LadingError)`
- Add a docstring to `ReadmeTranspositionError` describing when it is raised:
missing workspace README, or crate outside workspace root
- Remove the import of `PublishPreparationError` from `publish_manifest`
- In `_load_source_text`, replace `raise PublishPreparationError(...)` with
`raise ReadmeTranspositionError(...)`; preserve the existing error message
verbatim
- In `_resolve_crate_relative_path`, replace `raise
PublishPreparationError(...)` with `raise ReadmeTranspositionError(...)`
(retaining the chained cause); preserve the existing error message verbatim

**`lading/commands/bump.py`**
- Remove the import of `PublishPreparationError` from `publish_manifest`
- Add an import of `ReadmeTranspositionError` from `bump_readme`
- In `_process_readme_transposition`, update the `except` clause to catch
`ReadmeTranspositionError` instead of `PublishPreparationError`

**`lading/exceptions.py`**
- In the module-level docstring, add `ReadmeTranspositionError` to the list of
example subclasses
- If `PublishPreparationError` is absent from the docstring, add it for
completeness

Phase 2: Update Tests

Ensure all test assertions use the new bump-domain error type and add snapshot coverage for error messages.

Task 1: Update error path tests in test_bump_readme.py

Change assertions to expect the new error type.

• Update test_transpose_readme_to_crate_requires_workspace_readme to assert ReadmeTranspositionError instead of PublishPreparationError
• Update test_transpose_readme_to_crate_rejects_external_crate_root to assert ReadmeTranspositionError
• Update the import statement: import ReadmeTranspositionError from bump_readme, remove the publish_manifest import

Task 2: Add snapshot assertions for error messages

Lock down the user-facing error message wording so future changes are explicit and reviewed.

• Add snapshot assertions (using syrupy) to capture the full error message strings for both failure paths
• Follow the pattern established in tests/unit/publish/test_snapshot_messages.py
• Ensure the snapshot files are committed so CI enforces message stability

🤖 Prompt for AI agents

Update the test suite for `bump_readme.py` to use the new
`ReadmeTranspositionError` and add syrupy snapshot assertions to lock down error
message wording.

**`tests/unit/bump/test_bump_readme.py`**
- Replace the import of `PublishPreparationError` from `publish_manifest` with
an import of `ReadmeTranspositionError` from `bump_readme`
- In `test_transpose_readme_to_crate_requires_workspace_readme`, change the
`pytest.raises` target from `PublishPreparationError` to
`ReadmeTranspositionError`
- In `test_transpose_readme_to_crate_rejects_external_crate_root`, change the
`pytest.raises` target from `PublishPreparationError` to
`ReadmeTranspositionError`
- Add snapshot assertions (using syrupy) for both failure paths, capturing the
full error message strings
- Follow the pattern established in
`tests/unit/publish/test_snapshot_messages.py` for snapshot usage
- Commit the generated snapshot files so that CI enforces message stability

Phase 3: Update Documentation

Record the error taxonomy change in the developer guide.

Update error taxonomy table in developers-guide.md

Document the new error and its domain ownership.

• Add a row to the "Root domain exceptions" table (around line 249–261) for ReadmeTranspositionError with module lading.commands.bump_readme and notes describing README transposition failures
• Verify that PublishPreparationError remains documented as publish-domain only (staged manifest preparation)
• Check that the taxonomy section is not buried exclusively under "Publish command internals" — if so, add a cross-reference or brief mention in the "Bump command internals" section

🤖 Prompt for AI agents

Update `docs/developers-guide.md` to reflect the new error in the exception
taxonomy.

- In the "Root domain exceptions" table (around line 249–261), add a row for
`ReadmeTranspositionError` with module `lading.commands.bump_readme` and a note
describing README transposition failures (missing workspace README, crate
outside workspace root)
- Verify that `PublishPreparationError` remains documented as publish-domain
only, scoped to staged manifest preparation
- Check whether the taxonomy section sits exclusively under "Publish command
internals"; if it does, add a cross-reference or brief mention of
`ReadmeTranspositionError` in the "Bump command internals" section as well

Research

The lading project is a Python CLI toolkit for Rust/Cargo workspace management. It has two main command domains: bump (version bumping) and publish (crate publication). Exceptions follow a hierarchy rooted at LadingError in lading/exceptions.py, with domain-specific errors defined in their owning modules (e.g., LockfileRegenerationError in bump_lockfiles.py, PublishPreflightError in publish_errors.py). The offending cross-domain import is in bump_readme.py and bump.py, which import PublishPreparationError from publish_manifest.py. Tests use pytest.raises with match= patterns, and the publish domain has snapshot tests via syrupy. Documentation of the error taxonomy exists in docs/developers-guide.md under "Publish command internals".

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Introduce a new bump-domain exception `ReadmeTranspositionError` in
`lading/commands/bump_readme.py` and wire it up across all relevant production
files, removing all cross-domain imports of `PublishPreparationError`.

**`lading/commands/bump_readme.py`**
- Near the top of the file, after importing `LadingError` from
`lading.exceptions`, define a new class `ReadmeTranspositionError(LadingError)`
- Add a docstring to `ReadmeTranspositionError` describing when it is raised:
missing workspace README, or crate outside workspace root
- Remove the import of `PublishPreparationError` from `publish_manifest`
- In `_load_source_text`, replace `raise PublishPreparationError(...)` with
`raise ReadmeTranspositionError(...)`; preserve the existing error message
verbatim
- In `_resolve_crate_relative_path`, replace `raise
PublishPreparationError(...)` with `raise ReadmeTranspositionError(...)`
(retaining the chained cause); preserve the existing error message verbatim

**`lading/commands/bump.py`**
- Remove the import of `PublishPreparationError` from `publish_manifest`
- Add an import of `ReadmeTranspositionError` from `bump_readme`
- In `_process_readme_transposition`, update the `except` clause to catch
`ReadmeTranspositionError` instead of `PublishPreparationError`

**`lading/exceptions.py`**
- In the module-level docstring, add `ReadmeTranspositionError` to the list of
example subclasses
- If `PublishPreparationError` is absent from the docstring, add it for
completeness
===============================================================================

Task: 2

Update the test suite for `bump_readme.py` to use the new
`ReadmeTranspositionError` and add syrupy snapshot assertions to lock down error
message wording.

**`tests/unit/bump/test_bump_readme.py`**
- Replace the import of `PublishPreparationError` from `publish_manifest` with
an import of `ReadmeTranspositionError` from `bump_readme`
- In `test_transpose_readme_to_crate_requires_workspace_readme`, change the
`pytest.raises` target from `PublishPreparationError` to
`ReadmeTranspositionError`
- In `test_transpose_readme_to_crate_rejects_external_crate_root`, change the
`pytest.raises` target from `PublishPreparationError` to
`ReadmeTranspositionError`
- Add snapshot assertions (using syrupy) for both failure paths, capturing the
full error message strings
- Follow the pattern established in
`tests/unit/publish/test_snapshot_messages.py` for snapshot usage
- Commit the generated snapshot files so that CI enforces message stability
===============================================================================

Task: 3

Update `docs/developers-guide.md` to reflect the new error in the exception
taxonomy.

- In the "Root domain exceptions" table (around line 249–261), add a row for
`ReadmeTranspositionError` with module `lading.commands.bump_readme` and a note
describing README transposition failures (missing workspace README, crate
outside workspace root)
- Verify that `PublishPreparationError` remains documented as publish-domain
only, scoped to staged manifest preparation
- Check whether the taxonomy section sits exclusively under "Publish command
internals"; if it does, add a cross-reference or brief mention of
`ReadmeTranspositionError` in the "Bump command internals" section as well

💡 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!