Further extraction needed: bump.py and publish.py still exceed 400-line guideline

[coderabbitai]

Summary

Follow-up from PR #136 (issue #108): two source files still exceed the project's 400-line guideline and require further extraction beyond what was completed in that PR.

Affected files

• lading/commands/bump.py — still ~27 lines over the 400-line limit. Docstring trimming alone cannot close the gap; further logic extraction is required (in the spirit of the bump_manifests.py split already landed).
• lading/commands/publish.py — 741 lines, deliberately deferred from PR Bring oversized files under the 400-line guideline (#108) #136.

Rationale for deferral

Extracting publish.py is a substantial, non-minimal task because it requires:

1. Reconciling main's Add syrupy snapshot tests for 'already published' warning in _handle_publish_result #73/De-duplicate _run_preflight_checks / _preflight_argument_sets to a single home #96 refactor with the pipeline extraction done in PR Bring oversized files under the 400-line guideline (#108) #136 (lading/commands/publish_pipeline.py).
2. Rewriting the many monkeypatch.setattr(publish, …) test seams to target publish_pipeline instead, per the project's no-compat convention (no shim/back-compat layers).

This was judged unsuited to the review-fix pass on PR #136 and tracked here as the agreed follow-up.

Acceptance criteria

• lading/commands/bump.py is at or below 400 lines through further logic extraction (not just docstring trimming).
• lading/commands/publish.py is at or below 400 lines, with responsibilities distributed to publish_pipeline.py and/or other new modules as appropriate.
• All monkeypatch.setattr(publish, …) test seams are updated to target the correct module post-extraction, with no compatibility shims left behind.
• docs/developers-guide.md extraction map is updated to reflect the new module boundaries.
• make lint, make typecheck, and make test pass.

References

• PR: Bring oversized files under the 400-line guideline (#108) #136
• Requested by: @leynos

[coderabbitai]

🔗 Related PRs

leynos/stilyagi#20 - Refresh agent documentation standards [closed]
#122 - Collapse bump result-message formatting into canonical bump_output (#95) [merged]
#123 - De-duplicate preflight helpers into publish_preflight (#96) [merged]
#124 - Remove dead lockfile.refresh_lockfile; fix module docstring (#99) [merged]
leynos/shared-actions#287 - Fix remaining checksum mismatch in cargo-nextest [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

Apply the established coordinator/delegate pattern: pull the bump run-sequence into bump_pipeline.py, and split publish.py's two heaviest concerns into publish_pipeline.py (per-crate execution/dispatch) and publish_staging.py (workspace staging).

Honour the no-compat convention throughout — move symbols to their canonical home and repoint every caller and test seam rather than leaving shims.

Relocate _PublishExecutionOptions with the pipeline and update the single TYPE_CHECKING back-reference in publish_index_check.py, preserving the existing one-way runtime dependency shape.

Update the extraction map and correct the stale per-crate-helper attribution, then confirm the guideline and quality gates with make lint, make typecheck, and make test.

Design Choices

Design Choice 1: Where should publish.py's workspace-staging helpers land?

Options Considered:

1. Fold staging helpers into existing publish_manifest.py (206 → ~305 lines).
2. Create a dedicated publish_staging.py for tree-copy/build-directory/preparation helpers.

Chosen Option: 2

Rationale: Pipeline execution and staging together exceed 400 lines, so they cannot share one module. publish_manifest.py already frames itself around staging-time mutations, but its current job is patch-table manipulation. A focused publish_staging.py keeps single-responsibility boundaries consistent with the issue-108 convention and avoids overloading the patch-table module with raw filesystem-mirroring logic.

Design Choice 2: Where should bump.py's per-step orchestration helpers land?

Options Considered:

1. Expand existing bump_manifests.py (197 → ~399 lines).
2. Create a new bump_pipeline.py for the run-sequence steps.

Chosen Option: 2

Rationale: bump.py needs ~27+ lines shed; the cohesive process*/_apply_crate_manifest_update group is the natural unit. A dedicated bump_pipeline.py keeps per-manifest rewrite logic distinct from run-sequencing, mirrors the intended publish_pipeline.py split, and avoids pushing bump_manifests.py back to the ceiling.

💡 User Tips

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

Implementation Steps

Phase 1: Extract the bump run-sequence into bump_pipeline.py

Move the cohesive per-step orchestration out of the bump coordinator so it holds only entry-point, options, and context construction. This closes the bump.py overage using logic extraction rather than docstring trimming.

Task 1: Create lading/commands/bump_pipeline.py

Relocate the run-sequence helpers into a new focused module.

• Create lading/commands/bump_pipeline.py and move _CrateManifestOutcome, _process_workspace_manifest, _process_crate_manifests, _process_documentation_files, _process_readme_transposition, _process_lockfiles, _prepare_sorted_changes, and _apply_crate_manifest_update from bump.py.
• Import the delegate modules these helpers already depend on (bump_manifests, bump_docs, bump_lockfiles, bump_readme, bump_output, bump_toml) directly into the new module.
• Reference BumpOptions under a TYPE_CHECKING guard only, matching the bump_manifests.py precedent, so no runtime import cycle forms.

Task 2: Reduce bump.py to a thin coordinator

Leave the entry point and construction glue behind, importing the pipeline steps.

• Update bump.py so run(), BumpOptions, and _initialize_bump_context remain, calling the extracted steps via the bump_pipeline module namespace.
• Remove the moved definitions and do not leave re-export aliases for them (no-compat convention).
• Confirm bump.py lands comfortably below 400 lines.

Task 3: Repoint bump test seams

Update the two files that call the moved helper directly.

• Update tests/unit/test_bump_result_formatting.py and tests/unit/test_bump_context_properties.py to call bump_pipeline._apply_crate_manifest_update instead of bump._apply_crate_manifest_update.
• Leave tests/unit/test_bump_manifest_updates.py and tests/unit/test_bump_lockfile_rebuild.py untouched — they drive the public bump.run surface and patch bump.bump_lockfiles.*, which is unaffected.

🤖 Prompt for AI agents

Extract the bump run-sequence orchestration out of `bump.py` into a new
`bump_pipeline.py`, leaving the coordinator thin, and repoint the test seams
that reference the moved helper.

- Create `lading/commands/bump_pipeline.py` and move `_CrateManifestOutcome`,
`_process_workspace_manifest`, `_process_crate_manifests`,
`_process_documentation_files`, `_process_readme_transposition`,
`_process_lockfiles`, `_prepare_sorted_changes`, and
`_apply_crate_manifest_update` into it from `bump.py`.
- Bring the delegate module imports (`bump_manifests`, `bump_docs`,
`bump_lockfiles`, `bump_readme`, `bump_output`, `bump_toml`) across into
`bump_pipeline.py` at runtime scope.
- Reference `BumpOptions` only under a `TYPE_CHECKING` guard in
`bump_pipeline.py`, matching the existing `bump_manifests.py` precedent, to
avoid a runtime import cycle.
- Update `bump.py` to retain only `run()`, `BumpOptions`, and
`_initialize_bump_context`, calling the extracted steps via the `bump_pipeline`
module namespace.
- Remove the moved definitions from `bump.py` entirely — leave no re-export
aliases (no-compat convention).
- Verify `bump.py` sits comfortably below the 400-line guideline.
- Update `tests/unit/test_bump_result_formatting.py` and
`tests/unit/test_bump_context_properties.py` to call
`bump_pipeline._apply_crate_manifest_update` instead of
`bump._apply_crate_manifest_update`.
- Leave `tests/unit/test_bump_manifest_updates.py` and
`tests/unit/test_bump_lockfile_rebuild.py` untouched, since they drive the
public `bump.run` surface and patch `bump.bump_lockfiles.*`, which is unaffected
by this extraction.

Phase 2: Extract the publish pipeline and staging modules

Split publish.py's two largest cohesive concerns — the per-crate package/publish pipeline and the workspace-staging helpers — into dedicated modules, leaving the coordinator with entry-point, options, and setup/validation glue.

Task 1: Create lading/commands/publish_pipeline.py

House the per-crate execution and dispatch logic.

• Create lading/commands/publish_pipeline.py and move _PublishExecutionOptions, _PublicationPipelineState, _CrateAction, _for_each_publishable_crate, _package_publishable_crates, _package_crate, the _ALREADY_PUBLISHED_MARKERS/_CARGO_REGISTRY_ERROR_CODE constants, _is_already_published_error, _publish_crates, _publish_crate, _handle_publish_result, _execute_live_publication_pipeline, _handle_index_missing_version, and _dispatch_publication.
• Carry across the runtime imports these functions need (publish_execution._invoke, publish_index_check helpers, cargo_output_adapter, publish_errors), and import _resolve_staged_crate_root from the new staging module (Task 2.2).
• Keep the one-way dependency shape: publish_pipeline imports publish_index_check at runtime; publish_index_check references _PublishExecutionOptions only for typing.

Task 2: Create lading/commands/publish_staging.py

House the workspace-staging primitives.

• Create lading/commands/publish_staging.py and move PublishPreparation, _normalise_build_directory, _copy_workspace_tree, prepare_workspace, _format_preparation_summary, and _resolve_staged_crate_root.
• Bring across the atexit usage and workspace/path dependencies so cleanup registration continues to work from the staging module.

Task 3: Relocate _PublishExecutionOptions consumers

Fix the sole cross-module reference to the moved dataclass.

• Update the TYPE_CHECKING import in lading/commands/publish_index_check.py to import _PublishExecutionOptions from publish_pipeline rather than publish.
• Keep that import inside the TYPE_CHECKING guard so no runtime edge is introduced.

Task 4: Reduce publish.py to a thin coordinator

Retain entry-point, options, and setup glue; delegate everything else.

• Update publish.py so run(), PublishOptions, _ensure_configuration, _run_preflight_checks (the thin preflight wrapper seam), _ensure_workspace, and _validate_publication_options remain.
• Have run() call staging and pipeline entry points via the publish_staging and publish_pipeline module namespaces.
• Remove all moved definitions and do not leave bare re-export aliases behind them (no-compat convention); retain only the pre-existing publish_preflight re-exports that remain genuinely in use.
• Confirm publish.py lands below 400 lines and that neither publish_pipeline.py nor publish_staging.py exceeds the guideline.

🤖 Prompt for AI agents

Split `publish.py`'s two heaviest concerns — per-crate pipeline execution and
workspace staging — into `publish_pipeline.py` and `publish_staging.py`, then
reduce the coordinator to entry-point/options/setup glue.

- Create `lading/commands/publish_pipeline.py` and move
`_PublishExecutionOptions`, `_PublicationPipelineState`, `_CrateAction`,
`_for_each_publishable_crate`, `_package_publishable_crates`, `_package_crate`,
the `_ALREADY_PUBLISHED_MARKERS`/`_CARGO_REGISTRY_ERROR_CODE` constants,
`_is_already_published_error`, `_publish_crates`, `_publish_crate`,
`_handle_publish_result`, `_execute_live_publication_pipeline`,
`_handle_index_missing_version`, and `_dispatch_publication` into it.
- Carry across the runtime imports these moved functions need
(`publish_execution._invoke`, `publish_index_check` helpers,
`cargo_output_adapter`, `publish_errors`), and import
`_resolve_staged_crate_root` from the new `publish_staging` module.
- Preserve the one-way dependency shape: `publish_pipeline` imports
`publish_index_check` at runtime, while `publish_index_check` references
`_PublishExecutionOptions` for typing only.
- Create `lading/commands/publish_staging.py` and move `PublishPreparation`,
`_normalise_build_directory`, `_copy_workspace_tree`, `prepare_workspace`,
`_format_preparation_summary`, and `_resolve_staged_crate_root` into it,
carrying across the `atexit` usage and workspace/path dependencies so cleanup
registration keeps working from the staging module.
- Update the `TYPE_CHECKING` import in `lading/commands/publish_index_check.py`
to import `_PublishExecutionOptions` from `publish_pipeline` rather than
`publish`, keeping it inside the `TYPE_CHECKING` guard.
- Update `publish.py` to retain only `run()`, `PublishOptions`,
`_ensure_configuration`, `_run_preflight_checks` (the thin preflight wrapper
seam), `_ensure_workspace`, and `_validate_publication_options`.
- Have `run()` call staging and pipeline entry points via the `publish_staging`
and `publish_pipeline` module namespaces.
- Remove all moved definitions from `publish.py` and leave no bare re-export
aliases (no-compat convention); retain only the pre-existing `publish_preflight`
re-exports that remain genuinely in use.
- Verify `publish.py` sits below 400 lines and that neither
`publish_pipeline.py` nor `publish_staging.py` exceeds the guideline.

Phase 3: Rewrite publish test seams for the new boundaries

Repoint every publish monkeypatch seam to the module that now owns the target, honouring the no-compat convention, and leave preflight-owned seams where they still live.

Task 1: Repoint pipeline seams

Update the seams targeting moved pipeline helpers.

• Update tests/unit/publish/test_phase_dispatch.py to patch publish_pipeline._for_each_publishable_crate and to invoke publish_pipeline._package_publishable_crates, publish_pipeline._publish_crates, and publish_pipeline._handle_index_missing_version.
• Update the shared invoke_phase dispatcher in tests/unit/publish/conftest.py to reference the phase functions from publish_pipeline.
• Repoint each publish._invoke seam that stubs pipeline cargo invocations to publish_pipeline._invoke in tests/unit/publish/conftest.py, tests/unit/publish/preflight_test_utils.py, and tests/unit/publish/test_run_preflight.py; keep publish._run_preflight_checks seams pointing at publish (the wrapper stays there). Run the affected suites to confirm any residual preflight-path _invoke stubs resolve to publish_preflight/publish_execution as appropriate.

Task 2: Repoint staging seams

Update the seams targeting moved staging helpers.

• Update tests/unit/test_publish_staging.py to call publish_staging._normalise_build_directory, publish_staging._copy_workspace_tree, and publish_staging.prepare_workspace, and to patch publish_staging.atexit.register.
• Update tests/unit/publish/test_run_workspace_config.py to patch publish_staging.prepare_workspace; leave the publish.config_module.* and lading.workspace.load_workspace seams unchanged.

Task 3: Confirm unchanged seams

Guard against over-editing.

• Leave tests/unit/test_cli.py (publish_command.run, bump_command.run), the preflight/lockfile suites (publish._run_preflight_checks, publish_preflight.*), and the bump manifest/lockfile suites untouched, since their targets remain in place.

🤖 Prompt for AI agents

Repoint every publish-related monkeypatch test seam to the module that now owns
its target, following the no-compat convention, while leaving preflight-owned
seams alone.

- Update `tests/unit/publish/test_phase_dispatch.py` to patch
`publish_pipeline._for_each_publishable_crate` and to invoke
`publish_pipeline._package_publishable_crates`,
`publish_pipeline._publish_crates`, and
`publish_pipeline._handle_index_missing_version`.
- Update the shared `invoke_phase` dispatcher in
`tests/unit/publish/conftest.py` to reference the phase functions from
`publish_pipeline`.
- Repoint each `publish._invoke` seam that stubs pipeline cargo invocations to
`publish_pipeline._invoke` in `tests/unit/publish/conftest.py`,
`tests/unit/publish/preflight_test_utils.py`, and
`tests/unit/publish/test_run_preflight.py`.
- Keep `publish._run_preflight_checks` seams pointing at `publish`, since the
wrapper stays there.
- Run the affected suites to confirm any residual preflight-path `_invoke` stubs
resolve correctly to `publish_preflight`/`publish_execution` as appropriate.
- Update `tests/unit/test_publish_staging.py` to call
`publish_staging._normalise_build_directory`,
`publish_staging._copy_workspace_tree`, and `publish_staging.prepare_workspace`,
and to patch `publish_staging.atexit.register`.
- Update `tests/unit/publish/test_run_workspace_config.py` to patch
`publish_staging.prepare_workspace`, leaving the `publish.config_module.*` and
`lading.workspace.load_workspace` seams unchanged.
- Leave `tests/unit/test_cli.py` (`publish_command.run`, `bump_command.run`),
the preflight/lockfile suites (`publish._run_preflight_checks`,
`publish_preflight.*`), and the bump manifest/lockfile suites untouched, since
their targets remain in place — do not edit these.

Phase 4: Update documentation and verify

Bring the extraction map in line with the new boundaries and run the quality gates.

Task 1: Refresh the extraction map

Document the new modules and correct the stale attribution.

• Add bullets to the "Module size extractions (issue 108)" section of docs/developers-guide.md for lading.commands.bump_pipeline, lading.commands.publish_pipeline, and lading.commands.publish_staging, following the existing `module.path` — responsibility (imported by `original_home`) pattern.
• Correct the "Per-crate publication helpers" section so _package_crate, _publish_crate, _CrateAction, _for_each_publishable_crate, _PublicationPipelineState, and _dispatch_publication are attributed to publish_pipeline rather than publish_execution; while editing, fix the adjacent stale claim that publish_execution loads cmd_mox.command_runner (the real indirection lives in lading/cli.py).
• Update any prose in the "Extracted publish modules" section that would otherwise conflict with staging now living in publish_staging.

Task 2: Run the quality gates

Confirm the acceptance criteria hold.

• Run make lint, make typecheck, and make test; resolve any fallout from the moved imports and repointed seams.

🤖 Prompt for AI agents

Bring the developer-guide extraction map in line with the new module boundaries,
then run the project's quality gates to confirm everything holds together.

- Add bullets to the "Module size extractions (issue 108)" section of
`docs/developers-guide.md` for `lading.commands.bump_pipeline`,
`lading.commands.publish_pipeline`, and `lading.commands.publish_staging`,
following the existing `` `module.path` — responsibility (imported by
`original_home`) `` pattern.
- Correct the "Per-crate publication helpers" section so `_package_crate`,
`_publish_crate`, `_CrateAction`, `_for_each_publishable_crate`,
`_PublicationPipelineState`, and `_dispatch_publication` are attributed to
`publish_pipeline` rather than `publish_execution`.
- While editing that section, fix the adjacent stale claim that
`publish_execution` loads `cmd_mox.command_runner` — the real indirection lives
in `lading/cli.py`.
- Update any prose in the "Extracted publish modules" section that would
otherwise conflict with staging now living in `publish_staging`.
- Run `make lint`, `make typecheck`, and `make test`, and resolve any fallout
arising from the moved imports and repointed test seams.

Research

lading/commands/ follows an established "coordinator + delegate" pattern: a thin coordinator module keeps run(), public option dataclasses, and sequencing glue, while focused sibling modules own file-format or per-item logic.

PR #136 (issue #108) applied this to most oversized files — most notably splitting per-manifest rewrite logic out of bump.py into bump_manifests.py — but explicitly deferred publish.py and left bump.py marginally over budget.

The project follows a "no-compat" convention (PR #164): when a symbol moves home, callers and test seams update to reference the new canonical module directly rather than relying on re-export aliases.

Tests pin directly to private helpers via monkeypatch.setattr(publish, "_...") and by calling bump._apply_crate_manifest_update directly, so any extraction that honours the no-compat rule must rewrite those seams.

The extraction map lives in docs/developers-guide.md and currently misattributes the per-crate publication helpers to publish_execution.py.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extract the bump run-sequence orchestration out of `bump.py` into a new
`bump_pipeline.py`, leaving the coordinator thin, and repoint the test seams
that reference the moved helper.

- Create `lading/commands/bump_pipeline.py` and move `_CrateManifestOutcome`,
`_process_workspace_manifest`, `_process_crate_manifests`,
`_process_documentation_files`, `_process_readme_transposition`,
`_process_lockfiles`, `_prepare_sorted_changes`, and
`_apply_crate_manifest_update` into it from `bump.py`.
- Bring the delegate module imports (`bump_manifests`, `bump_docs`,
`bump_lockfiles`, `bump_readme`, `bump_output`, `bump_toml`) across into
`bump_pipeline.py` at runtime scope.
- Reference `BumpOptions` only under a `TYPE_CHECKING` guard in
`bump_pipeline.py`, matching the existing `bump_manifests.py` precedent, to
avoid a runtime import cycle.
- Update `bump.py` to retain only `run()`, `BumpOptions`, and
`_initialize_bump_context`, calling the extracted steps via the `bump_pipeline`
module namespace.
- Remove the moved definitions from `bump.py` entirely — leave no re-export
aliases (no-compat convention).
- Verify `bump.py` sits comfortably below the 400-line guideline.
- Update `tests/unit/test_bump_result_formatting.py` and
`tests/unit/test_bump_context_properties.py` to call
`bump_pipeline._apply_crate_manifest_update` instead of
`bump._apply_crate_manifest_update`.
- Leave `tests/unit/test_bump_manifest_updates.py` and
`tests/unit/test_bump_lockfile_rebuild.py` untouched, since they drive the
public `bump.run` surface and patch `bump.bump_lockfiles.*`, which is unaffected
by this extraction.
===============================================================================

Task: 2

Split `publish.py`'s two heaviest concerns — per-crate pipeline execution and
workspace staging — into `publish_pipeline.py` and `publish_staging.py`, then
reduce the coordinator to entry-point/options/setup glue.

- Create `lading/commands/publish_pipeline.py` and move
`_PublishExecutionOptions`, `_PublicationPipelineState`, `_CrateAction`,
`_for_each_publishable_crate`, `_package_publishable_crates`, `_package_crate`,
the `_ALREADY_PUBLISHED_MARKERS`/`_CARGO_REGISTRY_ERROR_CODE` constants,
`_is_already_published_error`, `_publish_crates`, `_publish_crate`,
`_handle_publish_result`, `_execute_live_publication_pipeline`,
`_handle_index_missing_version`, and `_dispatch_publication` into it.
- Carry across the runtime imports these moved functions need
(`publish_execution._invoke`, `publish_index_check` helpers,
`cargo_output_adapter`, `publish_errors`), and import
`_resolve_staged_crate_root` from the new `publish_staging` module.
- Preserve the one-way dependency shape: `publish_pipeline` imports
`publish_index_check` at runtime, while `publish_index_check` references
`_PublishExecutionOptions` for typing only.
- Create `lading/commands/publish_staging.py` and move `PublishPreparation`,
`_normalise_build_directory`, `_copy_workspace_tree`, `prepare_workspace`,
`_format_preparation_summary`, and `_resolve_staged_crate_root` into it,
carrying across the `atexit` usage and workspace/path dependencies so cleanup
registration keeps working from the staging module.
- Update the `TYPE_CHECKING` import in `lading/commands/publish_index_check.py`
to import `_PublishExecutionOptions` from `publish_pipeline` rather than
`publish`, keeping it inside the `TYPE_CHECKING` guard.
- Update `publish.py` to retain only `run()`, `PublishOptions`,
`_ensure_configuration`, `_run_preflight_checks` (the thin preflight wrapper
seam), `_ensure_workspace`, and `_validate_publication_options`.
- Have `run()` call staging and pipeline entry points via the `publish_staging`
and `publish_pipeline` module namespaces.
- Remove all moved definitions from `publish.py` and leave no bare re-export
aliases (no-compat convention); retain only the pre-existing `publish_preflight`
re-exports that remain genuinely in use.
- Verify `publish.py` sits below 400 lines and that neither
`publish_pipeline.py` nor `publish_staging.py` exceeds the guideline.
===============================================================================

Task: 3

Repoint every publish-related monkeypatch test seam to the module that now owns
its target, following the no-compat convention, while leaving preflight-owned
seams alone.

- Update `tests/unit/publish/test_phase_dispatch.py` to patch
`publish_pipeline._for_each_publishable_crate` and to invoke
`publish_pipeline._package_publishable_crates`,
`publish_pipeline._publish_crates`, and
`publish_pipeline._handle_index_missing_version`.
- Update the shared `invoke_phase` dispatcher in
`tests/unit/publish/conftest.py` to reference the phase functions from
`publish_pipeline`.
- Repoint each `publish._invoke` seam that stubs pipeline cargo invocations to
`publish_pipeline._invoke` in `tests/unit/publish/conftest.py`,
`tests/unit/publish/preflight_test_utils.py`, and
`tests/unit/publish/test_run_preflight.py`.
- Keep `publish._run_preflight_checks` seams pointing at `publish`, since the
wrapper stays there.
- Run the affected suites to confirm any residual preflight-path `_invoke` stubs
resolve correctly to `publish_preflight`/`publish_execution` as appropriate.
- Update `tests/unit/test_publish_staging.py` to call
`publish_staging._normalise_build_directory`,
`publish_staging._copy_workspace_tree`, and `publish_staging.prepare_workspace`,
and to patch `publish_staging.atexit.register`.
- Update `tests/unit/publish/test_run_workspace_config.py` to patch
`publish_staging.prepare_workspace`, leaving the `publish.config_module.*` and
`lading.workspace.load_workspace` seams unchanged.
- Leave `tests/unit/test_cli.py` (`publish_command.run`, `bump_command.run`),
the preflight/lockfile suites (`publish._run_preflight_checks`,
`publish_preflight.*`), and the bump manifest/lockfile suites untouched, since
their targets remain in place — do not edit these.
===============================================================================

Task: 4

Bring the developer-guide extraction map in line with the new module boundaries,
then run the project's quality gates to confirm everything holds together.

- Add bullets to the "Module size extractions (issue 108)" section of
`docs/developers-guide.md` for `lading.commands.bump_pipeline`,
`lading.commands.publish_pipeline`, and `lading.commands.publish_staging`,
following the existing `` `module.path` — responsibility (imported by
`original_home`) `` pattern.
- Correct the "Per-crate publication helpers" section so `_package_crate`,
`_publish_crate`, `_CrateAction`, `_for_each_publishable_crate`,
`_PublicationPipelineState`, and `_dispatch_publication` are attributed to
`publish_pipeline` rather than `publish_execution`.
- While editing that section, fix the adjacent stale claim that
`publish_execution` loads `cmd_mox.command_runner` — the real indirection lives
in `lading/cli.py`.
- Update any prose in the "Extracted publish modules" section that would
otherwise conflict with staging now living in `publish_staging`.
- Run `make lint`, `make typecheck`, and `make test`, and resolve any fallout
arising from the moved imports and repointed test seams.

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