Add Hypothesis property-based tests for lockfile filtering invariants in discover_tracked_lockfiles

[coderabbitai]

Background

Raised during review of PR #75 (refresh stale Cargo lockfiles before publish preflight).

Problem

discover_tracked_lockfiles enforces several filtering invariants (exclude target/ paths, require adjacent Cargo.toml, restrict to git-tracked files) that are only verified by fixed-scenario unit tests. Property-based coverage would catch edge cases across generated input ranges that fixed tests miss.

Resolution

Add @hypothesis.given tests in tests/unit/test_lockfile.py that generate workspace trees with:

• Random Cargo.lock / Cargo.toml placements at varying nesting depths
• target/ directory subtrees at varying depths
• Synthesised git ls-files stdout with varying combinations of tracked / untracked / target paths

Assert that all four invariants hold for every returned path:

1. Path ends with Cargo.lock
2. No target component in the relative path
3. An adjacent Cargo.toml exists
4. The path was present in the git ls-files output

References

• PR: Refresh stale Cargo lockfiles before publish preflight (#61) #75
• Requested by: @leynos

[coderabbitai]

🔗 Related PRs

leynos/repovec-appliance#23 - Add proptest property tests for Qdrant Quadlet parser and validator (#17) [merged]
leynos/actix-v2a#27 - Add SSE property tests (#18) [merged]
leynos/rstest-bdd#488 - Extend first-party policy hint resolution (9.7.1) [merged]
leynos/falcon-correlate#45 - Add property tests for parsing invariants (#39) [merged]
leynos/dear-diary#27 - Adopt Cranelift codegen and mold linking [merged]

---

📝 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

• Introduce Hypothesis as a test dependency in pyproject.toml
• Create tests/unit/test_lockfile.py with composite Hypothesis strategies generating workspace trees, target/ placements, and synthetic git ls-files output
• Write property-based tests that materialise generated trees on disk, inject a fake subprocess runner, and assert all four filtering invariants hold for every path returned by discover_tracked_lockfiles
• Follow existing test patterns: frozen dataclasses for scenario data, _CommandRunner injection for subprocess mocking, @settings for controlling example counts

Design Choices

Design Choice 1: Location of `discover_tracked_lockfiles`

Options Considered:

1. Place tests assuming the function lives in lading.commands.publish_preflight (consistent with existing git interaction code)
2. Create a new module lading.commands.publish_lockfiles and import from there

Chosen Option: 1

Rationale: Import from lading.commands.publish_preflight, as this module already handles pre-publication git checks and is the natural home for lockfile discovery. Adjust the import if PR #75 places the function elsewhere.

Design Choice 2: Function signature for `discover_tracked_lockfiles`

Options Considered:

1. discover_tracked_lockfiles(workspace_root: Path, *, runner: _CommandRunner) -> Sequence[Path] — follows existing subprocess injection pattern
2. discover_tracked_lockfiles(workspace_root: Path) -> Sequence[Path] — invokes git internally without injection

Chosen Option: 1

Rationale: Use the _CommandRunner injection pattern to allow test doubles for git ls-files, matching the established pattern in _verify_clean_working_tree.

💡 User Tips

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

Implementation Steps

Phase 1: Add Hypothesis Dependency

Introduce Hypothesis into the project's test dependencies so property-based tests can be written.

Declare Hypothesis in pyproject.toml

Add the Hypothesis package to the dev dependency group.

• Append "hypothesis>=6.100.0" to the [dependency-groups] dev list in pyproject.toml
• Run uv lock (or equivalent) to regenerate uv.lock with the new dependency

🤖 Prompt for AI agents

Add Hypothesis as a test dependency in `pyproject.toml` and regenerate the lock
file.

- In `pyproject.toml`, append `"hypothesis>=6.100.0"` to the
`[dependency-groups] dev` list
- Run `uv lock` (or equivalent) to regenerate `uv.lock` with the new dependency

Phase 2: Create Property-Based Tests for Lockfile Filtering

Write Hypothesis-driven tests that generate randomised workspace structures and git output, then assert the four filtering invariants.

Task 1: Create test module structure

Establish tests/unit/test_lockfile.py following existing unit test conventions.

• Create tests/unit/test_lockfile.py with a module docstring describing lockfile discovery invariant tests
• Use standard imports: from __future__ import annotations, import typing as typ, from hypothesis import given, settings, from hypothesis import strategies as st
• Import the function under test (assumed: from lading.commands.publish_preflight import discover_tracked_lockfiles)
• Import _CommandRunner protocol or define a minimal compatible stub for injection

Task 2: Implement Hypothesis strategies for workspace trees

Define composite strategies that generate plausible directory structures containing Cargo.lock and Cargo.toml files at varying nesting depths.

• Create a strategy path_segments() generating valid directory name components (alphanumeric, underscores, hyphens; exclude reserved names like target)
• Create a strategy workspace_tree() that produces a frozenset[PurePath] of relative paths representing Cargo.lock and Cargo.toml placements, with nesting depths from 0 (workspace root) to a configurable maximum (e.g., 5)
• Ensure the strategy can produce:
  • Lockfiles with adjacent manifests
  • Lockfiles without adjacent manifests
  • Manifests without adjacent lockfiles
  • Empty trees

Task 3: Implement Hypothesis strategies for target directory injection

Extend the workspace tree strategy to optionally place Cargo.lock files inside target/ subtrees at various depths.

• Create a strategy target_lockfile_paths() producing paths of the form <prefix>/target/<suffix>/Cargo.lock where prefix and suffix have variable depth
• The composite strategy should combine legitimate workspace lockfiles with target-embedded lockfiles to test exclusion logic

Task 4: Implement Hypothesis strategy for git ls-files output

Generate synthetic stdout for git ls-files based on the workspace tree, with controlled inclusion/exclusion of paths.

• Create a strategy git_ls_files_output(tree: frozenset[PurePath]) that:
  • Selects a random subset of paths from the tree to mark as "tracked"
  • Formats them as newline-separated relative path strings (simulating git ls-files stdout)
• Include edge cases: empty output, all paths tracked, no lockfiles tracked

Task 5: Write property-based test asserting all four invariants

Create the main @given-decorated test function that exercises discover_tracked_lockfiles and checks invariants.

• Define test_discover_tracked_lockfiles_invariants decorated with @given using the composite strategies
• Within the test:
  • Materialise the generated tree on disk inside tmp_path
  • Construct a fake _CommandRunner that returns the synthesised git ls-files stdout
  • Call discover_tracked_lockfiles(workspace_root=tmp_path, runner=fake_runner)
  • For each returned path, assert:
    1. path.name == "Cargo.lock"
    2. "target" not in path.relative_to(tmp_path).parts
    3. (path.parent / "Cargo.toml").exists()
    4. The path (relative) appears in the generated git output set
• Use @settings(max_examples=200) or similar to balance coverage with runtime

Task 6: Add supplementary edge-case tests

Include explicit property tests for known tricky scenarios that Hypothesis might not generate frequently.

• Add a test verifying behaviour when git ls-files returns an empty string (no tracked files)
• Add a test for deeply nested target/ directories (e.g., foo/bar/target/baz/Cargo.lock)
• Add a test for workspace root Cargo.lock (depth 0) with and without adjacent manifest
• Use @example(...) decorators to pin specific regression cases if valuable

🤖 Prompt for AI agents

Create `tests/unit/test_lockfile.py` with all Hypothesis-driven property-based
tests for `discover_tracked_lockfiles`. The goal is to verify all four filtering
invariants hold across randomised inputs.

**Module setup**
- Create `tests/unit/test_lockfile.py` with a module docstring describing
lockfile discovery invariant tests
- Add imports: `from __future__ import annotations`, `import typing as typ`,
`from hypothesis import given, settings`, `from hypothesis import strategies as
st`
- Import the function under test: `from lading.commands.publish_preflight import
discover_tracked_lockfiles`
- Import or define a minimal stub compatible with the `_CommandRunner` protocol
for injection

**Hypothesis strategies**
- Implement `path_segments()`: generates valid directory name components
(alphanumeric, underscores, hyphens; exclude reserved names like `target`)
- Implement `workspace_tree()`: produces a `frozenset[PurePath]` of relative
paths for `Cargo.lock` and `Cargo.toml` placements, with nesting depths from 0
to a configurable maximum (e.g., 5); must be capable of generating lockfiles
with adjacent manifests, lockfiles without adjacent manifests, manifests without
adjacent lockfiles, and empty trees
- Implement `target_lockfile_paths()`: produces paths of the form
`<prefix>/target/<suffix>/Cargo.lock` with variable prefix and suffix depth;
combine with `workspace_tree()` to test exclusion logic
- Implement `git_ls_files_output(tree: frozenset[PurePath])`: selects a random
subset of paths from the tree as "tracked" and formats them as newline-separated
relative path strings; cover edge cases of empty output, all paths tracked, and
no lockfiles tracked

**Main property-based test**
- Define `test_discover_tracked_lockfiles_invariants` decorated with `@given`
using the composite strategies above
- Decorate with `@settings(max_examples=200)` or similar
- Inside the test body:
  - Materialise the generated tree on disk inside `tmp_path`
- Construct a fake `_CommandRunner` returning the synthesised `git ls-files`
stdout
- Call `discover_tracked_lockfiles(workspace_root=tmp_path, runner=fake_runner)`
  - Assert all four invariants for every returned path:
    1. `path.name == "Cargo.lock"`
    2. `"target" not in path.relative_to(tmp_path).parts`
    3. `(path.parent / "Cargo.toml").exists()`
    4. The relative path appears in the generated git output set

**Supplementary edge-case tests**
- Add a test for `git ls-files` returning an empty string
- Add a test for deeply nested `target/` directories (e.g.,
`foo/bar/target/baz/Cargo.lock`)
- Add a test for workspace root `Cargo.lock` (depth 0) with and without adjacent
manifest
- Use `@example(...)` decorators to pin specific regression cases if valuable

Research

The project is a Python CLI tool for Cargo workspace management. Unit tests reside in tests/unit/ using pytest with fixture factories (make_crate, make_workspace) defined in tests/unit/conftest.py. Subprocess calls (e.g., git status) follow an injected _CommandRunner protocol from lading/commands/publish_execution.py, enabling test doubles. Hypothesis is not yet a declared dependency. The discover_tracked_lockfiles function does not exist in the current codebase—it will be introduced by PR #75.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Add Hypothesis as a test dependency in `pyproject.toml` and regenerate the lock
file.

- In `pyproject.toml`, append `"hypothesis>=6.100.0"` to the
`[dependency-groups] dev` list
- Run `uv lock` (or equivalent) to regenerate `uv.lock` with the new dependency
===============================================================================

Task: 2

Create `tests/unit/test_lockfile.py` with all Hypothesis-driven property-based
tests for `discover_tracked_lockfiles`. The goal is to verify all four filtering
invariants hold across randomised inputs.

**Module setup**
- Create `tests/unit/test_lockfile.py` with a module docstring describing
lockfile discovery invariant tests
- Add imports: `from __future__ import annotations`, `import typing as typ`,
`from hypothesis import given, settings`, `from hypothesis import strategies as
st`
- Import the function under test: `from lading.commands.publish_preflight import
discover_tracked_lockfiles`
- Import or define a minimal stub compatible with the `_CommandRunner` protocol
for injection

**Hypothesis strategies**
- Implement `path_segments()`: generates valid directory name components
(alphanumeric, underscores, hyphens; exclude reserved names like `target`)
- Implement `workspace_tree()`: produces a `frozenset[PurePath]` of relative
paths for `Cargo.lock` and `Cargo.toml` placements, with nesting depths from 0
to a configurable maximum (e.g., 5); must be capable of generating lockfiles
with adjacent manifests, lockfiles without adjacent manifests, manifests without
adjacent lockfiles, and empty trees
- Implement `target_lockfile_paths()`: produces paths of the form
`<prefix>/target/<suffix>/Cargo.lock` with variable prefix and suffix depth;
combine with `workspace_tree()` to test exclusion logic
- Implement `git_ls_files_output(tree: frozenset[PurePath])`: selects a random
subset of paths from the tree as "tracked" and formats them as newline-separated
relative path strings; cover edge cases of empty output, all paths tracked, and
no lockfiles tracked

**Main property-based test**
- Define `test_discover_tracked_lockfiles_invariants` decorated with `@given`
using the composite strategies above
- Decorate with `@settings(max_examples=200)` or similar
- Inside the test body:
  - Materialise the generated tree on disk inside `tmp_path`
- Construct a fake `_CommandRunner` returning the synthesised `git ls-files`
stdout
- Call `discover_tracked_lockfiles(workspace_root=tmp_path, runner=fake_runner)`
  - Assert all four invariants for every returned path:
    1. `path.name == "Cargo.lock"`
    2. `"target" not in path.relative_to(tmp_path).parts`
    3. `(path.parent / "Cargo.toml").exists()`
    4. The relative path appears in the generated git output set

**Supplementary edge-case tests**
- Add a test for `git ls-files` returning an empty string
- Add a test for deeply nested `target/` directories (e.g.,
`foo/bar/target/baz/Cargo.lock`)
- Add a test for workspace root `Cargo.lock` (depth 0) with and without adjacent
manifest
- Use `@example(...)` decorators to pin specific regression cases if valuable

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