refactor(ingestion): extract docket-gap path validation

[johnjhughes]

Summary

• move opinion docket-gap writable-path validation into the importable planner domain module
• preserve the CLI boundary with a thin CommandError adapter and unchanged messages
• add direct domain coverage for snapshot containment, distinct outputs, hard-link aliases, and the new-output fast path

Validation

• uv run ruff format --check .
• uv run ruff check .
• uv run pyright
• uv run pytest -q tests/test_opinion_docket_gap_planner.py tests/test_opinion_docket_gap_cli.py tests/test_multiharness_command_adapter.py::test_systemd_scope_preserves_duplex_protocol_and_defers_provider_values (45 passed)
• uv run pytest -q (6099 passed, 13 skipped)

Bead: LegalForecastBench-cwdv.3

---

Note

Low Risk
Pure refactor with behavior preserved; changes are localized path-validation and test relocation with no auth, data, or execution-path changes.

Overview
Writable-path checks for plan-opinion-docket-gaps now live in validate_opinion_docket_gap_paths on the opinion docket-gap planner module, so the same rules can be imported outside the CLI.

The CLI keeps a thin _validate_opinion_docket_gap_paths that delegates to that function and maps OpinionDocketGapPlanningError to CommandError with unchanged user-facing messages. Behavior is unchanged: outputs must stay outside the immutable snapshot, plan/summary paths must be distinct, hard-linked duplicates are rejected, and existing outputs are checked against snapshot files via samefile.

Planner tests now cover the domain helper directly (including the fast path that skips snapshot rglob when outputs do not exist yet); the CLI test asserts the CommandError adapter contract.

^{Reviewed by Cursor Bugbot for commit 335c8e2. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes
  • Improved validation of opinion docket gap output paths before files are written.
  • Prevented outputs from overwriting or residing within immutable snapshots.
  • Detected duplicate paths, hard-linked files, and outputs aliased to snapshot evidence.
  • Preserved clear command-line error reporting for invalid paths.

[coderabbitai]

Walkthrough

The planner now provides shared validation for snapshot and writable output paths. The CLI uses this validator and converts planning failures to CommandError. Tests cover snapshot protection, aliases, hard links, duplicates, traversal avoidance, and CLI error preservation.

Changes

Opinion docket gap path validation

Layer / File(s)	Summary
Planner path validation legalforecast/ingestion/opinion_docket_gap_planner.py, tests/test_opinion_docket_gap_planner.py	The planner validates snapshot boundaries, duplicate paths, hard-linked outputs, and existing outputs that alias snapshot evidence. Tests cover these checks and avoid unnecessary snapshot traversal.
CLI validation integration legalforecast/cli.py, tests/test_opinion_docket_gap_cli.py	The CLI delegates path checks to the shared validator and converts OpinionDocketGapPlanningError to CommandError. The CLI test verifies the error message contract.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: copilot

Poem

I’m a rabbit guarding paths in line,
No snapshot file shall cross the sign.
Duplicates, links, aliases too,
Meet one validator, strict and true.
The CLI keeps its error tune.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes extracting docket-gap path validation into the ingestion module.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/opinion-gap-path-validation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR refactors opinion docket-gap writable-path validation out of the CLI and into the provider-free planner domain module so the same validation rules can be imported and reused outside the command layer, while preserving the CLI error contract.

Changes:

• Added validate_opinion_docket_gap_paths to legalforecast.ingestion.opinion_docket_gap_planner and raised domain-specific OpinionDocketGapPlanningError with the same user-facing messages as before.
• Simplified the CLI _validate_opinion_docket_gap_paths to delegate to the planner helper and adapt errors to CommandError.
• Relocated/expanded tests so domain behavior is covered directly (including the “new outputs” fast path that avoids a snapshot walk) and the CLI test now asserts the adapter contract.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
legalforecast/ingestion/opinion_docket_gap_planner.py	Introduces reusable domain-level path validation for snapshot containment, distinct outputs, and alias detection.
legalforecast/cli.py	Replaces duplicated CLI validation logic with a thin adapter around the planner helper.
tests/test_opinion_docket_gap_planner.py	Adds direct domain tests for the extracted validation helper, including the “no snapshot walk for new outputs” fast path.
tests/test_opinion_docket_gap_cli.py	Updates CLI test to assert the CommandError mapping contract is preserved.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@legalforecast/ingestion/opinion_docket_gap_planner.py`:
- Around line 41-44: Update validate_opinion_docket_gap_paths() to catch
exceptions from both snapshot_path.resolve() and each writable_paths
path.resolve(), translating symlink-loop RuntimeError and other filesystem
resolution failures into OpinionDocketGapPlanningError. Add regression tests
covering failures while resolving the snapshot path and output paths, while
preserving successful path validation behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 30b6ee17-2aa1-4374-a0d6-98db4fb64c1d

📥 Commits

Reviewing files that changed from the base of the PR and between 302bb98 and 335c8e2.

📒 Files selected for processing (4)

• legalforecast/cli.py
• legalforecast/ingestion/opinion_docket_gap_planner.py
• tests/test_opinion_docket_gap_cli.py
• tests/test_opinion_docket_gap_planner.py