Refresh or diagnose stale nested Cargo.lock files before publish preflight

[leynos]

Summary

lading publish can fail during preflight when a workspace contains tracked nested Cargo.lock files that become stale after lading bump updates package versions.

The observed failure came from rstest-bdd after bumping workspace packages from 0.5.0 to 0.6.0-beta1.

Error

Updating crates.io index                                                                                                
error: cannot update the lock file /data/leynos/Projects/rstest-bdd/crates/rstest-bdd/tests/ui_lints/Cargo.lock because 
--locked was passed to prevent this                                                                                     
help: to generate the lock file without accessing the network, remove the --locked flag and use --offline instead.      

Cause

lading publish runs cargo test --workspace --all-targets as source-workspace preflight before staging.

In rstest-bdd, one integration test shells out to:

cargo clippy --locked --manifest-path tests/ui_lints/Cargo.toml                                                         

tests/ui_lints is a nested Cargo workspace with its own tracked Cargo.lock. After lading bump updates path dependency versions, that nested lockfile still contains the old path package versions, so Cargo needs to rewrite it. The nested test passes --locked, so Cargo aborts.

A scratch refresh showed the nested lockfile needed to update the internal path crates from 0.5.0 to 0.6.0-beta1 and add the new tracing dependency set.

Expected Behaviour

Lading should either:

• refresh tracked lockfiles after manifest version/dependency rewrites, including nested lockfiles; or
• fail before the full publish preflight with a targeted diagnostic naming the stale lockfile and the exact repair command.

Proposed Fix

Add lockfile handling to lading:

1. After lading bump, discover tracked Cargo.lock files under the workspace excluding target.

2. For each lockfile whose parent has a Cargo.toml, run:

   cargo generate-lockfile --manifest-path <parent>/Cargo.toml                                                          
   

3. In lading publish, add a lockfile freshness validation phase before cargo test:

   cargo metadata --locked --manifest-path <parent>/Cargo.toml --format-version=1                                       
   

4. If Cargo reports that a lockfile cannot be updated because --locked was passed, raise a PublishPreflightError with the lockfile path and the corresponding cargo generate-lockfile --manifest-path ... command.

Further Investigation

lading publish currently runs preflight before staging and patch stripping. That means preflight does not validate the exact tree later used for cargo package and cargo publish.

Investigate whether publish should be split into:

1. verify source git cleanliness;
2. plan and stage the workspace;
3. apply publish-time manifest changes;
4. refresh or validate staged lockfiles;
5. run cargo preflight in the staged workspace;
6. package and publish from the same staged workspace.

This would let dry-run publish repair staged lockfiles without mutating the source checkout.

No code changes were made in either repository during this investigation. The only commands with side effects were in / tmp scratch copies/logs, plus Cargo may have downloaded dependencies while checking the root metadata because the root
lockfile was already locally modified before this investigation.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Introduce a lockfile.py module providing discovery, refresh, and validation functions reusable by both bump and publish commands
• Extend the bump command to invoke subprocess commands via the existing _invoke infrastructure from publish_execution.py, refreshing all tracked lockfiles after manifest updates
• Insert lockfile validation into the publish preflight sequence before cargo check, failing early with actionable repair commands
• Maintain full cmd-mox stub compatibility for testing without real subprocess execution

Design Choices

Design Choice 1: Lockfile refresh is unconditional

Options Considered:

1. Always refresh tracked lockfiles after bump
2. Add a config option to disable lockfile refresh

Chosen Option: 1

Rationale: The ticket frames this as expected behaviour, and making it optional adds complexity without clear benefit.

Design Choice 2: Lockfile discovery uses git

Options Considered:

1. Use git ls-files to find tracked lockfiles
2. Use Path.glob("**/Cargo.lock") with manual target exclusion

Chosen Option: 1

Rationale: git ls-files automatically respects .gitignore, handles nested workspaces correctly, and matches the "tracked" semantics in the ticket.

Design Choice 3: Subprocess capability in bump via existing module

Options Considered:

1. Import _invoke from publish_execution.py directly
2. Create a new shared execution module

Chosen Option: 1

Rationale: publish_execution.py already provides cmd-mox stub support for testing; reusing it avoids duplication and ensures consistent test infrastructure.

💡 User Tips

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

Implementation Steps

Phase 1: Lockfile Discovery and Refresh Infrastructure

Add foundational functions for discovering tracked Cargo.lock files and refreshing them via cargo generate-lockfile. These functions serve both the bump command (refresh) and publish command (validation).

Task 1: Add lockfile discovery function

Create a function to discover tracked Cargo.lock files in the workspace by invoking git ls-files.

• Create lading/commands/lockfile.py as a new module for lockfile operations
• Implement discover_tracked_lockfiles(workspace_root, runner) that runs git ls-files "*/Cargo.lock" "Cargo.lock" and returns a tuple of Path objects
• Filter results to include only lockfiles whose parent directory contains a Cargo.toml
• Follow the _verify_clean_working_tree pattern in publish.py for runner invocation
• Handle the case where the workspace is not a git repository (return empty tuple with a logged warning)

Task 2: Add lockfile refresh function

Implement the cargo generate-lockfile invocation for refreshing a single lockfile.

• Add refresh_lockfile(manifest_path, runner) to lading/commands/lockfile.py
• Invoke cargo generate-lockfile --manifest-path <manifest_path> via the runner
• Raise LockfileRefreshError (new exception) on non-zero exit, including stderr in the message
• Return the lockfile path on success for inclusion in output summaries

Task 3: Add lockfile validation function

Implement lockfile freshness validation using cargo metadata --locked.

• Add validate_lockfile_freshness(manifest_path, runner) to lading/commands/lockfile.py
• Invoke cargo metadata --locked --manifest-path <manifest_path> --format-version=1
• Return True if exit code is 0, False otherwise
• Capture stderr for diagnostic purposes when validation fails

🤖 Prompt for AI agents

Create `lading/commands/lockfile.py` as a new module providing three core
functions for lockfile discovery, refresh, and validation.

**`discover_tracked_lockfiles(workspace_root, runner)`**
- Run `git ls-files "*/Cargo.lock" "Cargo.lock"` via the runner, rooted at
`workspace_root`
- Parse stdout into a tuple of `Path` objects
- Filter results to include only lockfiles whose parent directory also contains
a `Cargo.toml`
- Follow the `_verify_clean_working_tree` pattern from `publish.py` for runner
invocation
- If the workspace is not a git repository, return an empty tuple and log a
warning

**`refresh_lockfile(manifest_path, runner)`**
- Invoke `cargo generate-lockfile --manifest-path <manifest_path>` via the
runner
- On non-zero exit, raise `LockfileRefreshError` (define this new exception in
the same module), including stderr in the message
- Return the lockfile path on success

**`validate_lockfile_freshness(manifest_path, runner)`**
- Invoke `cargo metadata --locked --manifest-path <manifest_path>
--format-version=1` via the runner
- Return `True` if exit code is 0, `False` otherwise
- Capture stderr for diagnostic use when validation fails

Phase 2: Integrate Lockfile Refresh into Bump Command

Extend the bump command to refresh tracked lockfiles after updating manifests, ensuring lockfiles remain consistent with the new versions.

Task 1: Add runner injection to bump command

Enable subprocess execution in the bump command by accepting an optional runner.

• Add runner: _CommandRunner | None = None parameter to BumpOptions in lading/commands/bump.py
• Import _invoke from lading/commands/publish_execution.py as the default runner
• Pass the runner to the new _refresh_lockfiles internal function

Task 2: Implement lockfile refresh step in bump

Add lockfile refresh as the final step of the bump workflow, after manifest updates.

• Add _refresh_lockfiles(context, runner) function in lading/commands/bump.py
• Call discover_tracked_lockfiles to find all tracked lockfiles
• For each lockfile, call refresh_lockfile with the parent's Cargo.toml path
• Collect refreshed lockfile paths for the output summary
• Skip refresh in dry-run mode (log what would be refreshed instead)

Task 3: Update bump output to include lockfile changes

Extend the BumpChanges dataclass and output formatting to report refreshed lockfiles.

• Add lockfiles: Sequence[Path] = () field to BumpChanges dataclass
• Update _format_result_message to include lockfile count and paths in the output
• Format lockfiles with a "(lockfile)" suffix similar to "(documentation)" for docs

🤖 Prompt for AI agents

Extend `lading/commands/bump.py` to refresh tracked lockfiles as the final step
of the bump workflow.

**Runner injection**
- Add `runner: _CommandRunner | None = None` to `BumpOptions`
- Import `_invoke` from `lading/commands/publish_execution.py` and use it as the
default when `runner` is `None`
- Pass the resolved runner to `_refresh_lockfiles`

**`_refresh_lockfiles(context, runner)` function**
- Call `discover_tracked_lockfiles` from `lading/commands/lockfile.py` to find
all tracked lockfiles
- For each discovered lockfile, call `refresh_lockfile` with the parent
directory's `Cargo.toml` path
- Collect successfully refreshed lockfile paths for the output summary
- In dry-run mode, skip invocation and log what would be refreshed instead

**`BumpChanges` and output formatting**
- Add `lockfiles: Sequence[Path] = ()` to the `BumpChanges` dataclass
- Update `_format_result_message` to report lockfile count and individual paths
- Apply a `(lockfile)` suffix to each lockfile entry, consistent with the
`(documentation)` pattern used for docs

Phase 3: Integrate Lockfile Validation into Publish Preflight

Add lockfile freshness validation to the publish preflight sequence, failing early with actionable diagnostics if any lockfile is stale.

Task 1: Add lockfile validation to preflight sequence

Insert lockfile validation between auxiliary commands and cargo check.

• Add _validate_lockfile_freshness(workspace_root, runner, env) function in lading/commands/publish.py
• Call discover_tracked_lockfiles to enumerate lockfiles
• For each lockfile, call validate_lockfile_freshness
• Collect all stale lockfiles before reporting (do not fail on first)

Task 2: Implement actionable error diagnostics

Raise PublishPreflightError with clear diagnostic messages when lockfile validation fails.

• Format error message to name each stale lockfile path
• Include the exact repair command: cargo generate-lockfile --manifest-path <path>/Cargo.toml
• If multiple lockfiles are stale, list all paths and commands
• Mention lading bump as the typical cause and suggest re-running it

Task 3: Wire validation into _run_preflight_checks

Integrate the new validation step into the existing preflight flow.

• Call _validate_lockfile_freshness after _run_aux_build_commands and before the cargo check phase in _run_preflight_checks
• Use the same runner and base_env as other preflight commands
• Ensure the step respects cmd-mox stubs for testing

🤖 Prompt for AI agents

Extend `lading/commands/publish.py` to validate lockfile freshness during
preflight.

**`_validate_lockfile_freshness(workspace_root, runner, env)` function**
- Call `discover_tracked_lockfiles` from `lading/commands/lockfile.py` to
enumerate all tracked lockfiles
- For each lockfile, call `validate_lockfile_freshness` from the same module
- Collect *all* stale lockfiles before reporting — do not fail on the first one

**Actionable error diagnostics**
- Raise `PublishPreflightError` listing each stale lockfile path
- Include the exact repair command for each: `cargo generate-lockfile
--manifest-path <path>/Cargo.toml`
- When multiple lockfiles are stale, list every path and its corresponding
repair command
- Reference `lading bump` as the typical cause and advise re-running it

**Wiring into `_run_preflight_checks`**
- Call `_validate_lockfile_freshness` after `_run_aux_build_commands` and before
the `cargo check` phase
- Pass the same `runner` and `base_env` used by other preflight commands
- Ensure cmd-mox stubs are respected (no special-casing required if runner is
passed consistently)

Phase 4: Testing

Add comprehensive tests for the new lockfile handling in both bump and publish commands.

Task 1: Add unit tests for lockfile module

Test the discovery, refresh, and validation functions in isolation.

• Create tests/unit/test_lockfile.py
• Test discover_tracked_lockfiles with mocked git output (empty, single, multiple lockfiles)
• Test discover_tracked_lockfiles handles non-git directories gracefully
• Test refresh_lockfile success and failure paths
• Test validate_lockfile_freshness returns correct boolean for exit codes

Task 2: Add bump command lockfile refresh tests

Test that bump refreshes lockfiles after manifest updates.

• Add tests to tests/unit/test_bump_command_integration.py
• Verify refresh_lockfile is called for each discovered lockfile
• Verify dry-run mode does not invoke cargo generate-lockfile
• Verify refreshed lockfiles appear in the output summary
• Use monkeypatched runner to avoid real subprocess calls

Task 3: Add publish preflight lockfile validation tests

Test that publish preflight detects and reports stale lockfiles.

• Add tests to tests/unit/publish/test_preflight_checks.py
• Test validation passes when all lockfiles are fresh
• Test validation raises PublishPreflightError with correct message when lockfiles are stale
• Test error message includes repair command for each stale lockfile

Task 4: Add BDD scenarios for lockfile handling

Add feature scenarios covering the end-to-end lockfile workflows.

• Add scenario to tests/bdd/features/cli.feature: "Bump refreshes tracked Cargo.lock files"
• Add scenario: "Bump dry-run does not modify lockfiles"
• Add scenario: "Publish pre-flight aborts when lockfile is stale"
• Add scenario: "Publish pre-flight error includes repair command"
• Register cmd-mox stubs for git ls-files, cargo generate-lockfile, and cargo metadata --locked in tests/bdd/steps/

🤖 Prompt for AI agents

Add comprehensive tests for lockfile handling across all affected modules.

**`tests/unit/test_lockfile.py` (new file)**
- Test `discover_tracked_lockfiles` with mocked git output covering: empty
result, single lockfile, multiple lockfiles
- Test graceful handling of non-git directories
- Test `refresh_lockfile` success path (returns lockfile path) and failure path
(raises `LockfileRefreshError`)
- Test `validate_lockfile_freshness` returns `True` on exit code 0 and `False`
otherwise

**`tests/unit/test_bump_command_integration.py` (extend)**
- Verify `refresh_lockfile` is called for each lockfile returned by
`discover_tracked_lockfiles`
- Verify dry-run mode does not invoke `cargo generate-lockfile`
- Verify refreshed lockfile paths appear in the output summary
- Use a monkeypatched runner throughout — no real subprocess calls

**`tests/unit/publish/test_preflight_checks.py` (extend)**
- Test validation passes when all lockfiles are fresh
- Test validation raises `PublishPreflightError` with the correct message when
lockfiles are stale
- Test that the error message includes the repair command for each stale
lockfile

**`tests/bdd/features/cli.feature` and `tests/bdd/steps/` (extend)**
- Add scenario: "Bump refreshes tracked Cargo.lock files"
- Add scenario: "Bump dry-run does not modify lockfiles"
- Add scenario: "Publish pre-flight aborts when lockfile is stale"
- Add scenario: "Publish pre-flight error includes repair command"
- Register cmd-mox stubs for `git ls-files`, `cargo generate-lockfile`, and
`cargo metadata --locked` in the BDD steps

Research

Codebase Summary

lading is a Python toolkit for managing Rust Cargo workspaces, built with Cyclopts for CLI and msgspec/tomlkit for data handling. The bump command (lading/commands/bump.py) performs pure file I/O to update version strings across Cargo.toml manifests. The publish command (lading/commands/publish.py) orchestrates preflight checks, workspace staging, and crate publication, using _invoke from publish_execution.py for subprocess execution with cmd-mox stub support for testing. Configuration lives in lading/config.py with PreflightConfig controlling preflight behaviour.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create `lading/commands/lockfile.py` as a new module providing three core
functions for lockfile discovery, refresh, and validation.

**`discover_tracked_lockfiles(workspace_root, runner)`**
- Run `git ls-files "*/Cargo.lock" "Cargo.lock"` via the runner, rooted at
`workspace_root`
- Parse stdout into a tuple of `Path` objects
- Filter results to include only lockfiles whose parent directory also contains
a `Cargo.toml`
- Follow the `_verify_clean_working_tree` pattern from `publish.py` for runner
invocation
- If the workspace is not a git repository, return an empty tuple and log a
warning

**`refresh_lockfile(manifest_path, runner)`**
- Invoke `cargo generate-lockfile --manifest-path <manifest_path>` via the
runner
- On non-zero exit, raise `LockfileRefreshError` (define this new exception in
the same module), including stderr in the message
- Return the lockfile path on success

**`validate_lockfile_freshness(manifest_path, runner)`**
- Invoke `cargo metadata --locked --manifest-path <manifest_path>
--format-version=1` via the runner
- Return `True` if exit code is 0, `False` otherwise
- Capture stderr for diagnostic use when validation fails
===============================================================================

Task: 2

Extend `lading/commands/bump.py` to refresh tracked lockfiles as the final step
of the bump workflow.

**Runner injection**
- Add `runner: _CommandRunner | None = None` to `BumpOptions`
- Import `_invoke` from `lading/commands/publish_execution.py` and use it as the
default when `runner` is `None`
- Pass the resolved runner to `_refresh_lockfiles`

**`_refresh_lockfiles(context, runner)` function**
- Call `discover_tracked_lockfiles` from `lading/commands/lockfile.py` to find
all tracked lockfiles
- For each discovered lockfile, call `refresh_lockfile` with the parent
directory's `Cargo.toml` path
- Collect successfully refreshed lockfile paths for the output summary
- In dry-run mode, skip invocation and log what would be refreshed instead

**`BumpChanges` and output formatting**
- Add `lockfiles: Sequence[Path] = ()` to the `BumpChanges` dataclass
- Update `_format_result_message` to report lockfile count and individual paths
- Apply a `(lockfile)` suffix to each lockfile entry, consistent with the
`(documentation)` pattern used for docs
===============================================================================

Task: 3

Extend `lading/commands/publish.py` to validate lockfile freshness during
preflight.

**`_validate_lockfile_freshness(workspace_root, runner, env)` function**
- Call `discover_tracked_lockfiles` from `lading/commands/lockfile.py` to
enumerate all tracked lockfiles
- For each lockfile, call `validate_lockfile_freshness` from the same module
- Collect *all* stale lockfiles before reporting — do not fail on the first one

**Actionable error diagnostics**
- Raise `PublishPreflightError` listing each stale lockfile path
- Include the exact repair command for each: `cargo generate-lockfile
--manifest-path <path>/Cargo.toml`
- When multiple lockfiles are stale, list every path and its corresponding
repair command
- Reference `lading bump` as the typical cause and advise re-running it

**Wiring into `_run_preflight_checks`**
- Call `_validate_lockfile_freshness` after `_run_aux_build_commands` and before
the `cargo check` phase
- Pass the same `runner` and `base_env` used by other preflight commands
- Ensure cmd-mox stubs are respected (no special-casing required if runner is
passed consistently)
===============================================================================

Task: 4

Add comprehensive tests for lockfile handling across all affected modules.

**`tests/unit/test_lockfile.py` (new file)**
- Test `discover_tracked_lockfiles` with mocked git output covering: empty
result, single lockfile, multiple lockfiles
- Test graceful handling of non-git directories
- Test `refresh_lockfile` success path (returns lockfile path) and failure path
(raises `LockfileRefreshError`)
- Test `validate_lockfile_freshness` returns `True` on exit code 0 and `False`
otherwise

**`tests/unit/test_bump_command_integration.py` (extend)**
- Verify `refresh_lockfile` is called for each lockfile returned by
`discover_tracked_lockfiles`
- Verify dry-run mode does not invoke `cargo generate-lockfile`
- Verify refreshed lockfile paths appear in the output summary
- Use a monkeypatched runner throughout — no real subprocess calls

**`tests/unit/publish/test_preflight_checks.py` (extend)**
- Test validation passes when all lockfiles are fresh
- Test validation raises `PublishPreflightError` with the correct message when
lockfiles are stale
- Test that the error message includes the repair command for each stale
lockfile

**`tests/bdd/features/cli.feature` and `tests/bdd/steps/` (extend)**
- Add scenario: "Bump refreshes tracked Cargo.lock files"
- Add scenario: "Bump dry-run does not modify lockfiles"
- Add scenario: "Publish pre-flight aborts when lockfile is stale"
- Add scenario: "Publish pre-flight error includes repair command"
- Register cmd-mox stubs for `git ls-files`, `cargo generate-lockfile`, and
`cargo metadata --locked` in the BDD steps

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