From d01a3925f4b23132ec89d333cfd9b6f4fcbe75d2 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Mon, 21 Jul 2025 09:20:13 +0000 Subject: [PATCH 1/3] Add TOCHANGE.md research documentation - Analyzed target/toChange parameter flow from LaunchQLProject to LaunchQLMigrate - Confirmed LaunchQLProject now normalizes target format before passing to migration client - Documented clean separation of concerns and potential simplifications - Research shows no unneeded complexity for project name extraction in LaunchQLMigrate Co-Authored-By: Dan Lynch --- TOCHANGE.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 TOCHANGE.md diff --git a/TOCHANGE.md b/TOCHANGE.md new file mode 100644 index 0000000000..dc3f5e54bd --- /dev/null +++ b/TOCHANGE.md @@ -0,0 +1,89 @@ +# toChange Parameter Analysis + +## Summary + +After deep research into the LaunchQL codebase, the user's hypothesis is **CORRECT**. LaunchQLProject now properly normalizes target parameters before passing them to LaunchQLMigrate, eliminating the need for complex project name extraction logic in the migration client. + +## Current Architecture + +### LaunchQLProject (Target Processing) + +**File**: `packages/core/src/core/class/launchql.ts` + +The `parseProjectTarget()` method (lines 682-702) uses the `parseTarget()` utility to cleanly separate: +- `projectName`: The module/project name +- `toChange`: The change name or tag (without project prefix) + +**Target Format Support**: +- `project` → `{ projectName: "project", toChange: undefined }` +- `project:changeName` → `{ projectName: "project", toChange: "changeName" }` +- `project:@tagName` → `{ projectName: "project", toChange: "@tagName" }` + +### parseTarget Utility + +**File**: `packages/core/src/utils/target-utils.ts` + +This utility handles all target parsing complexity: +- Validates target format +- Extracts project name and change specification +- Handles tag syntax (`:@tagName`) vs change syntax (`:changeName`) +- Returns clean, normalized values + +### LaunchQLMigrate (toChange Processing) + +**File**: `packages/core/src/migrate/client.ts` + +All migration methods (`deploy`, `revert`, `verify`) receive clean `toChange` values and handle them consistently: + +```typescript +// Lines 121, 269, 344 - Identical pattern across all methods +const resolvedToChange = toChange && toChange.includes('@') + ? resolveTagToChangeName(planPath, toChange, plan.project) + : toChange; +``` + +**Key Observations**: +1. **No project name extraction** - LaunchQLMigrate never needs to parse project names from `toChange` +2. **Simple tag resolution** - Only checks for `@` prefix to determine if tag resolution is needed +3. **Consistent handling** - All three methods use identical logic + +## Flow Analysis + +``` +User Input: "auth:@v2.0.0" or "auth:some/change" + ↓ +LaunchQLProject.parseProjectTarget() + ↓ +parseTarget() utility + ↓ +{ projectName: "auth", toChange: "@v2.0.0" } or { projectName: "auth", toChange: "some/change" } + ↓ +LaunchQLMigrate.deploy/revert/verify() + ↓ +Simple tag resolution if toChange.includes('@') +``` + +## Historical Context + +Based on the git history and code structure, it appears that: + +1. **Legacy Support**: LaunchQLMigrate may have previously handled complex target parsing +2. **Architecture Evolution**: LaunchQLProject now centralizes target parsing logic +3. **Clean Separation**: Migration client focuses purely on database operations + +## Potential Simplifications + +Since LaunchQLProject now handles all target parsing complexity, LaunchQLMigrate could potentially be simplified by: + +1. **Removing redundant validation** - Target format is already validated upstream +2. **Simplifying parameter documentation** - `toChange` is always clean (no project prefixes) +3. **Consolidating tag resolution** - Could extract the common pattern into a helper method + +## Conclusion + +The user's analysis is **accurate**. LaunchQLProject has evolved to properly normalize target parameters, making complex project name extraction logic in LaunchQLMigrate unnecessary. The current architecture provides clean separation of concerns: + +- **LaunchQLProject**: Handles target parsing and project management +- **LaunchQLMigrate**: Focuses on database migration operations with clean parameters + +This represents good architectural evolution toward cleaner, more maintainable code. From 0201f5fa0acd37f5a921ce86d2eeadf572a80535 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Mon, 21 Jul 2025 09:34:43 +0000 Subject: [PATCH 2/3] Simplify LaunchQLMigrate: improve documentation and consolidate tag resolution - Enhanced toChange parameter documentation in types.ts to clarify project names are resolved upstream - Consolidated duplicate tag resolution logic into private resolveToChange() helper method - Removed code duplication across deploy(), revert(), and verify() methods - Improved code maintainability and readability Co-Authored-By: Dan Lynch --- packages/core/src/migrate/client.ts | 13 ++++++++++--- packages/core/src/migrate/types.ts | 12 ++++++++++++ 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/packages/core/src/migrate/client.ts b/packages/core/src/migrate/client.ts index f59235a1c2..1c7b8cea27 100644 --- a/packages/core/src/migrate/client.ts +++ b/packages/core/src/migrate/client.ts @@ -109,6 +109,13 @@ export class LaunchQLMigrate { } } + /** + * Resolve toChange parameter, handling tag resolution if needed + */ + private resolveToChange(toChange: string | undefined, planPath: string, project: string): string | undefined { + return toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, project) : toChange; + } + /** * Deploy changes according to plan file */ @@ -118,7 +125,7 @@ export class LaunchQLMigrate { const { modulePath, toChange, useTransaction = true, debug = false, logOnly = false } = options; const planPath = join(modulePath, 'launchql.plan'); const plan = parsePlanFileSimple(planPath); - const resolvedToChange = toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, plan.project) : toChange; + const resolvedToChange = this.resolveToChange(toChange, planPath, plan.project); const changes = getChangesInOrder(planPath); const fullPlanResult = parsePlanFile(planPath); @@ -266,7 +273,7 @@ export class LaunchQLMigrate { const { modulePath, toChange, useTransaction = true } = options; const planPath = join(modulePath, 'launchql.plan'); const plan = parsePlanFileSimple(planPath); - const resolvedToChange = toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, plan.project) : toChange; + const resolvedToChange = this.resolveToChange(toChange, planPath, plan.project); const changes = getChangesInOrder(planPath, true); // Reverse order for revert const reverted: string[] = []; @@ -341,7 +348,7 @@ export class LaunchQLMigrate { const { modulePath, toChange } = options; const planPath = join(modulePath, 'launchql.plan'); const plan = parsePlanFileSimple(planPath); - const resolvedToChange = toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, plan.project) : toChange; + const resolvedToChange = this.resolveToChange(toChange, planPath, plan.project); const changes = getChangesInOrder(planPath); const verified: string[] = []; diff --git a/packages/core/src/migrate/types.ts b/packages/core/src/migrate/types.ts index 566efa4c87..0146a22c9e 100644 --- a/packages/core/src/migrate/types.ts +++ b/packages/core/src/migrate/types.ts @@ -16,6 +16,10 @@ export interface MigratePlanFile { export interface DeployOptions { modulePath: string; + /** + * Target change name or tag (e.g., "changeName" or "@tagName"). + * Note: Project name is already resolved upstream by LaunchQLProject. + */ toChange?: string; useTransaction?: boolean; // Add debug mode for enhanced error reporting @@ -25,6 +29,10 @@ export interface DeployOptions { export interface RevertOptions { modulePath: string; + /** + * Target change name or tag (e.g., "changeName" or "@tagName"). + * Note: Project name is already resolved upstream by LaunchQLProject. + */ toChange?: string; useTransaction?: boolean; // Add debug mode for enhanced error reporting @@ -33,6 +41,10 @@ export interface RevertOptions { export interface VerifyOptions { modulePath: string; + /** + * Target change name or tag (e.g., "changeName" or "@tagName"). + * Note: Project name is already resolved upstream by LaunchQLProject. + */ toChange?: string; } From 625ec2e1ca177a0ccfb6278d96cd4e97b2e75252 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Mon, 21 Jul 2025 12:57:19 -0700 Subject: [PATCH 3/3] change --- TOCHANGE.md | 89 ----------------------------------------------------- 1 file changed, 89 deletions(-) delete mode 100644 TOCHANGE.md diff --git a/TOCHANGE.md b/TOCHANGE.md deleted file mode 100644 index dc3f5e54bd..0000000000 --- a/TOCHANGE.md +++ /dev/null @@ -1,89 +0,0 @@ -# toChange Parameter Analysis - -## Summary - -After deep research into the LaunchQL codebase, the user's hypothesis is **CORRECT**. LaunchQLProject now properly normalizes target parameters before passing them to LaunchQLMigrate, eliminating the need for complex project name extraction logic in the migration client. - -## Current Architecture - -### LaunchQLProject (Target Processing) - -**File**: `packages/core/src/core/class/launchql.ts` - -The `parseProjectTarget()` method (lines 682-702) uses the `parseTarget()` utility to cleanly separate: -- `projectName`: The module/project name -- `toChange`: The change name or tag (without project prefix) - -**Target Format Support**: -- `project` → `{ projectName: "project", toChange: undefined }` -- `project:changeName` → `{ projectName: "project", toChange: "changeName" }` -- `project:@tagName` → `{ projectName: "project", toChange: "@tagName" }` - -### parseTarget Utility - -**File**: `packages/core/src/utils/target-utils.ts` - -This utility handles all target parsing complexity: -- Validates target format -- Extracts project name and change specification -- Handles tag syntax (`:@tagName`) vs change syntax (`:changeName`) -- Returns clean, normalized values - -### LaunchQLMigrate (toChange Processing) - -**File**: `packages/core/src/migrate/client.ts` - -All migration methods (`deploy`, `revert`, `verify`) receive clean `toChange` values and handle them consistently: - -```typescript -// Lines 121, 269, 344 - Identical pattern across all methods -const resolvedToChange = toChange && toChange.includes('@') - ? resolveTagToChangeName(planPath, toChange, plan.project) - : toChange; -``` - -**Key Observations**: -1. **No project name extraction** - LaunchQLMigrate never needs to parse project names from `toChange` -2. **Simple tag resolution** - Only checks for `@` prefix to determine if tag resolution is needed -3. **Consistent handling** - All three methods use identical logic - -## Flow Analysis - -``` -User Input: "auth:@v2.0.0" or "auth:some/change" - ↓ -LaunchQLProject.parseProjectTarget() - ↓ -parseTarget() utility - ↓ -{ projectName: "auth", toChange: "@v2.0.0" } or { projectName: "auth", toChange: "some/change" } - ↓ -LaunchQLMigrate.deploy/revert/verify() - ↓ -Simple tag resolution if toChange.includes('@') -``` - -## Historical Context - -Based on the git history and code structure, it appears that: - -1. **Legacy Support**: LaunchQLMigrate may have previously handled complex target parsing -2. **Architecture Evolution**: LaunchQLProject now centralizes target parsing logic -3. **Clean Separation**: Migration client focuses purely on database operations - -## Potential Simplifications - -Since LaunchQLProject now handles all target parsing complexity, LaunchQLMigrate could potentially be simplified by: - -1. **Removing redundant validation** - Target format is already validated upstream -2. **Simplifying parameter documentation** - `toChange` is always clean (no project prefixes) -3. **Consolidating tag resolution** - Could extract the common pattern into a helper method - -## Conclusion - -The user's analysis is **accurate**. LaunchQLProject has evolved to properly normalize target parameters, making complex project name extraction logic in LaunchQLMigrate unnecessary. The current architecture provides clean separation of concerns: - -- **LaunchQLProject**: Handles target parsing and project management -- **LaunchQLMigrate**: Focuses on database migration operations with clean parameters - -This represents good architectural evolution toward cleaner, more maintainable code.