Feat: Validate against a migration archive

[amenocal]

Description

This pull request adds comprehensive support for GitHub migration archives to the migration validator tool, enabling enhanced three-way validation between the source repository, migration archive, and target repository. It introduces new CLI options for downloading or specifying existing migration archives, updates the export and validation workflows to incorporate archive data, and provides extensive documentation for users.

Checklist

• I have added the appropriate label to this PR according to the type of change
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests

Additional Context

Migration Archive Support and Workflow:

• Added new CLI options --download-archive and --archive-path to export command, allowing users to automatically download or specify an existing migration archive for enhanced validation. These options are mutually exclusive and include validation for proper usage and directory structure. [1] [2] [3] [4] [5]
• Integrated migration archive data into the export process, so exports now include both API and archive-derived metrics. The validation process is updated to support three-way comparisons: Source API ↔ Archive ↔ Target API.

Documentation Enhancements:

• Added a detailed docs/migration-archive.md guide covering migration archive features, workflow, CLI usage, data analysis, and troubleshooting.
• Updated README.md to reference the new documentation, explain archive options, provide usage examples, and describe the enhanced export/validation output when migration archives are used. [1] [2] [3] [4] [5] [6]

User Experience Improvements:

• The CLI now interactively helps users select the correct migration archive when multiple are available, and provides clear error messages and validation for archive directory structure. [1] [2]
• Example export and validation output are updated to show how migration archive data is included and compared.

Internal Refactoring:

• Refactored code to pass archive directory information through the export and validation pipeline, and to validate archive paths robustly. [1] [2] [3]

API and Dependency Updates:

• Minor updates to imports and dependencies to support archive file handling and directory operations.

Overall, these changes provide a robust, user-friendly way to leverage GitHub migration archives for more accurate and auditable migration validation.

[Copilot]

Pull Request Overview

This pull request adds comprehensive support for GitHub migration archives to the migration validator tool, enabling enhanced three-way validation between the source repository, migration archive, and target repository. The implementation introduces new CLI options for downloading or specifying existing migration archives and updates the export and validation workflows to incorporate archive data.

• Adds new CLI options --download-archive and --archive-path for migration archive support
• Implements three-way validation comparing Source API ↔ Archive ↔ Target API data
• Includes comprehensive documentation and user experience improvements

Reviewed Changes

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

Show a summary per file

File	Description
cmd/export.go	Adds CLI flags and validation for migration archive options
internal/export/export.go	Updates export function to include migration archive analysis
internal/validator/validator.go	Extends validation logic to support three-way comparisons
internal/migrationarchive/migrationarchive.go	New module for archive download, extraction, and analysis
internal/archive/archive.go	New module for tar.gz archive extraction
internal/api/api.go	Extends API to support migration listing and archive downloads
docs/migration-archive.md	Comprehensive documentation for migration archive features
README.md	Updates main documentation with migration archive references
Test files	Comprehensive test coverage for new functionality

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 5 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}