fix: require unambiguous compatible backup selection

[Timpan4]

Backup discovery previously selected the newest filesystem timestamp without checking whether that backup was supported or complete. It now displays candidate identity, recorded timestamps, compatibility, and completeness, and auto-selects only a single supported, recorded-complete candidate. Ambiguous or incomplete discovery requires an explicit manifest file; selecting an unsupported file never falls back to another backup.

Supports explicit files and folders, including moved and nested backups. Discovery validates recorded verification metadata and path presence without hashing content; restore retains its full content checks. The agreed selection policy is documented in docs/BACKUP-FORMAT.md.

Validation: 76 distinct relevant Pester tests passed across discovery, backup hashes, restore outcomes/conflicts, canonical repository behavior, and repository checks. The 31 discovery/hash tests also passed under Windows PowerShell 5.1. Independent review is clean after correcting malformed verification-record selection.

Closes #39.

Summary by CodeRabbit

• New Features

  • Backup discovery now evaluates nested backup locations and displays metadata such as machine, profile, timestamps, compatibility, and completeness.
  • Users can explicitly select a backup manifest by file or folder path, including legacy or partial backups.
  • Restore operations now require a valid, explicitly selected backup when automatic selection is unavailable.

• Bug Fixes

  • Unsupported, incomplete, malformed, or ambiguous backups are no longer selected automatically.
  • Backup verification metadata is validated without unnecessarily hashing file contents.

• Documentation

  • Added guidance covering backup discovery, selection rules, compatibility, and supported formats.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: dc6a7be9-7e54-4570-b8f9-45fceda8d77a

📥 Commits

Reviewing files that changed from the base of the PR and between c8de578 and a58d8dc.

📒 Files selected for processing (6)

• bootstrap.ps1
• docs/BACKUP-FORMAT.md
• modules/BackupManifest.ps1
• restore-backup.ps1
• tests/BackupDiscovery.Tests.ps1
• tests/BackupRestore.Tests.ps1

---

📝 Walkthrough

Walkthrough

Changes

The backup module now validates candidate compatibility and completeness before selection. Discovery searches recursively, supports explicit manifest paths, rejects unsupported selections, and avoids modification-time selection. Restore integration, documentation, and Pester coverage were updated.

Backup discovery and selection

Layer / File(s)	Summary
Candidate validation and metadata checks modules/BackupManifest.ps1	Get-BackupCandidate reports manifest identity, timestamps, compatibility, completeness, and metadata-only verification results.
Manifest selection and restore integration modules/BackupManifest.ps1, restore-backup.ps1, bootstrap.ps1, docs/BACKUP-FORMAT.md	Find-BackupManifest supports explicit paths and recursive discovery. Automatic selection requires one supported, recorded-complete candidate. Restore passes the requested path and reports resolution failures. Documentation describes the selection rules and unsupported snapshot format.
Discovery behavior coverage tests/BackupDiscovery.Tests.ps1, tests/BackupRestore.Tests.ps1	Tests cover nested, incomplete, ambiguous, unsupported, malformed, missing, and explicitly selected manifests, plus search errors and metadata-only verification. The obsolete modification-time sorting assertion was removed.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant RestoreBackup
  participant FindBackupManifest
  participant GetBackupCandidate
  participant FileSystem
  RestoreBackup->>FindBackupManifest: Pass explicit ManifestPath
  FindBackupManifest->>FileSystem: Search selected path or backup containers
  FileSystem-->>FindBackupManifest: Return manifest paths
  FindBackupManifest->>GetBackupCandidate: Validate candidates
  GetBackupCandidate-->>FindBackupManifest: Return compatibility and completeness
  FindBackupManifest-->>RestoreBackup: Return selected path or error

Loading

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/backup-discovery-selection

---

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.}