Research: toChange parameter flow analysis

[pyramation]

Research: toChange parameter flow analysis + LaunchQLMigrate simplifications

Summary

This PR contains research documentation and code simplifications for the LaunchQLMigrate class based on analysis of the target/toChange parameter flow from LaunchQLProject.

Research findings (documented in TOCHANGE.md):

• Confirmed that LaunchQLProject's parseProjectTarget() method now properly normalizes target parameters before passing to LaunchQLMigrate
• Verified that toChange parameters received by LaunchQLMigrate are always clean (no project prefixes like auth:)
• Identified that project name extraction complexity in LaunchQLMigrate is indeed unnecessary

Code simplifications implemented:

1. Enhanced parameter documentation - Added clear documentation to toChange parameters in DeployOptions, RevertOptions, and VerifyOptions interfaces to clarify that project names are resolved upstream
2. Consolidated tag resolution logic - Extracted duplicate tag resolution pattern from deploy(), revert(), and verify() methods into a private resolveToChange() helper method

Note: Minimal redundant validation was found to remove, as most error handling in LaunchQLMigrate deals with legitimate runtime database errors rather than target format validation.

Review & Testing Checklist for Human

• Verify tag resolution works correctly - Test deploy, revert, and verify operations with both tag format (@tagName) and direct change names to ensure the consolidated resolveToChange() helper method works correctly across all three operations
• Validate documentation accuracy - Confirm that the added documentation claiming "project names are resolved upstream by LaunchQLProject" is accurate by tracing the actual parameter flow in a real scenario
• Check for missed validation opportunities - Review if there are additional redundant validations in LaunchQLMigrate that should have been removed but were missed in this analysis

---

Diagram

%%{ init : { "theme" : "default" }}%%
graph TD
    LP["LaunchQLProject<br/>parseProjectTarget()"]:::major-edit
    TU["target-utils.ts<br/>parseTarget()"]:::context
    MT["migrate/types.ts<br/>Options interfaces"]:::minor-edit
    MC["migrate/client.ts<br/>LaunchQLMigrate class"]:::major-edit
    
    LP -->|"calls"| TU
    LP -->|"passes clean toChange"| MC
    MT -->|"documents parameters"| MC
    
    subgraph "LaunchQLMigrate Methods"
        D["deploy()"]:::major-edit
        R["revert()"]:::major-edit  
        V["verify()"]:::major-edit
        H["resolveToChange()<br/>(new helper)"]:::major-edit
    end
    
    MC --> D
    MC --> R
    MC --> V
    D -->|"uses"| H
    R -->|"uses"| H
    V -->|"uses"| H
    
    subgraph Legend
        L1["Major Edit"]:::major-edit
        L2["Minor Edit"]:::minor-edit
        L3["Context/No Edit"]:::context
    end

    classDef major-edit fill:#90EE90
    classDef minor-edit fill:#87CEEB
    classDef context fill:#FFFFFF

Loading

Notes

• This work was requested by Dan Lynch (pyramation@gmail.com)
• Session URL: https://app.devin.ai/sessions/dcaeffa397f74adcbbf28f699473d901
• The research confirms architectural evolution toward cleaner separation of concerns between LaunchQLProject (target parsing) and LaunchQLMigrate (database operations)
• Build passes with no TypeScript errors, indicating the refactoring maintains type safety

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring