Skip to content

Commit 733a355

Browse files
Karnaukhov-khKarnaukhov-kh
authored
Merge pull request #7 from push-based/feature/non-viable-migration-handling
feat(): add non-viable handling
2 parents a58f293 + fd14ae6 commit 733a355

File tree

7 files changed

+338
-12
lines changed

7 files changed

+338
-12
lines changed

‎.cursor/flows/README.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,21 @@ Flows are collections of rule files (.mdc) that guide the AI through multi-step
2727
**Location:** `ds-refactoring-flow/`
2828
**Purpose:** Migrate components from deprecated design system patterns to modern alternatives
2929

30-
**Note:** This flow appears to be empty in the current directory but rule files exist in `.cursor/rules/` for:
31-
- Finding violations
32-
- Planning refactoring
33-
- Fixing violations
34-
- Validating changes
35-
- Preparing reports
30+
**Files:**
31+
- `01-find-violations.mdc` - Identify deprecated component usage
32+
- `02-plan-refactoring.mdc` - Create detailed migration strategy
33+
- `03-non-viable-cases.mdc` - Handle non-migratable components by marking them for exclusion
34+
- `03-fix-violations.mdc` - Execute code changes
35+
- `04-validate-changes.mdc` - Verify improvements through contract comparison
36+
- `05-prepare-report.mdc` - Generate testing checklists and documentation
37+
- `clean-global-styles.mdc` - Independent analysis of deprecated CSS usage
38+
39+
**Special Handling:**
40+
- **Non-Viable Cases**: When components are identified as non-viable during the planning step, use `03-non-viable-cases.mdc` instead of proceeding with the normal fix violations step. This marks components with special prefixes (`after-migration-[ORIGINAL_CLASS]`) to exclude them from future violation reports.
41+
42+
**Use Cases:**
43+
- **Primary Flow**: Migrating components to modern design system patterns
44+
- **Non-Viable Handling**: Alternative handling within the main flow for legacy components that cannot be migrated
3645

3746
## How to Use Flows
3847

‎.cursor/flows/ds-refactoring-flow/03-non-viable-cases.mdc‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
You are a design system migration specialist executing a non-migratable component workflow. Follow this systematic process:
7+
8+
## PHASE 1: IDENTIFICATION & DISCOVERY
9+
**Step 1:** Identify and output the target component class name from previous conversation context
10+
- Output: <target_component>[CLASS_NAME]</target_component>
11+
12+
**Step 2:** Run CSS discovery in parallel using report-deprecated-css tool:
13+
- **Global Styles Directory:** [USER_PROVIDED_INPUT] (if not provided, request from user)
14+
- **Styles Overrides Directory:** [USER_PROVIDED_INPUT] (if not provided, request from user)
15+
- **Fallback behavior:** If only one directory provided, run tool for that directory only
16+
- **Error handling:** If neither directory provided, ask user for at least one input
17+
- Component: [IDENTIFIED_CLASS_NAME]
18+
19+
**Step 3:** Create implementation checklist
20+
- Count total violations found across both directories
21+
- Generate checklist item for each violation location
22+
- **Validation Check:** Verify checklist item count = total violation count
23+
- **Save checklist to:** `.cursor/tmp/css-cleanup/[class-name]-[scope]-non-viable-migration-checklist.md`
24+
- **DO NOT output checklist content in chat** - only reference checklist file location
25+
- Output format:
26+
<checklist_summary>
27+
<total_violations>[NUMBER]</total_violations>
28+
<total_checklist_items>[NUMBER]</total_checklist_items>
29+
<validation_check>Items match violations: [TRUE/FALSE]</validation_check>
30+
<checklist_file>`.cursor/tmp/css-cleanup/[class-name]-[scope]-non-viable-migration-checklist.md`</checklist_file>
31+
</checklist_summary>
32+
33+
## PHASE 2: IMPLEMENTATION
34+
**Work from checklist file** - reference saved checklist and update it as you progress through each item.
35+
36+
Execute each checklist item systematically in this exact order:
37+
38+
**Step 1: HTML Template Updates (FIRST PRIORITY)**
39+
- Replace original component classes with "after-migration-[ORIGINAL_CLASS]" in HTML files/templates
40+
- This must be done BEFORE any CSS changes
41+
- Update all instances found in the violation reports
42+
- **Update checklist:** Mark HTML items as complete
43+
44+
**Step 2: CSS Selector Duplication (NOT REPLACEMENT)**
45+
- DUPLICATE CSS selectors, do NOT replace them
46+
- Transform: `.custom-radio {}` → `.custom-radio, .after-migration-custom-radio {}`
47+
- Keep original selector intact alongside new prefixed selector
48+
- This ensures both old and new classes work with identical styling
49+
- Maintain visual parity between original and prefixed versions
50+
- **Update checklist:** Mark CSS items as complete
51+
52+
## PHASE 3: VALIDATION (Success Criteria) - MANDATORY EXECUTION
53+
**CRITICAL:** Execute validation steps from checklist using actual tools, not just manual verification.
54+
55+
**Validation 1 - CSS Count Consistency:**
56+
- **TOOL REQUIRED:** Re-run report-deprecated-css tool on both original directories
57+
- Compare counts with original baseline
58+
- **Update checklist:** Mark validation item as complete
59+
- Output: <validation_1>
60+
<original_count>[NUMBER]</original_count>
61+
<new_count>[NUMBER]</new_count>
62+
<status>PASS/FAIL</status>
63+
<criteria>Deprecated class count remains identical to original</criteria>
64+
</validation_1>
65+
66+
**Validation 2 - Violation Reduction:**
67+
- **TOOL REQUIRED:** Run report-violations tool against modified component scope
68+
- Compare with original violation count
69+
- **Update checklist:** Mark validation item as complete
70+
- Output: <validation_2>
71+
<original_violations>[NUMBER]</original_violations>
72+
<new_violations>[NUMBER]</new_violations>
73+
<replacements_made>[NUMBER]</replacements_made>
74+
<expected_reduction>[NUMBER]</expected_reduction>
75+
<status>PASS/FAIL</status>
76+
<criteria>0 violations OR exactly X fewer violations (where X = number of replacements made)</criteria>
77+
</validation_2>
78+
79+
**Final Step:** Update saved checklist file with validation results and mark all items complete.
80+
81+
## OUTPUT REQUIREMENTS
82+
- Start with identified class name in <target_component> tags
83+
- Show violation counts and checklist summary in <checklist_summary> tags (NO detailed checklist content)
84+
- Reference checklist file location only
85+
- Provide step-by-step implementation status with checklist updates
86+
- Report validation results in <validation_1> and <validation_2> tags with clear pass/fail status
87+
- **Throughout process:** Update checklist file, don't repeat content in chat
88+
89+
Execute each phase completely before proceeding to the next. Request confirmation if validation criteria are not met.
90+
91+
## USAGE
92+
To invoke this workflow, user can say:
93+
- "Execute non-viable handling for [component]"
94+
- "Run the non-migratable component workflow"
95+
- "Handle non-viable component migration"
96+
- Or simply reference this rule: @non-viable-handling
97+
description:
98+
globs:
99+
alwaysApply: false
100+
---

‎.cursor/rules/03-non-viable-cases.mdc‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
You are a design system migration specialist executing a non-migratable component workflow. Follow this systematic process:
7+
8+
## PHASE 1: IDENTIFICATION & DISCOVERY
9+
**Step 1:** Identify and output the target component class name from previous conversation context
10+
- Output: <target_component>[CLASS_NAME]</target_component>
11+
12+
**Step 2:** Run CSS discovery in parallel using report-deprecated-css tool:
13+
- **Global Styles Directory:** [USER_PROVIDED_INPUT] (if not provided, request from user)
14+
- **Styles Overrides Directory:** [USER_PROVIDED_INPUT] (if not provided, request from user)
15+
- **Fallback behavior:** If only one directory provided, run tool for that directory only
16+
- **Error handling:** If neither directory provided, ask user for at least one input
17+
- Component: [IDENTIFIED_CLASS_NAME]
18+
19+
**Step 3:** Create implementation checklist
20+
- Count total violations found across both directories
21+
- Generate checklist item for each violation location
22+
- **Validation Check:** Verify checklist item count = total violation count
23+
- **Save checklist to:** `.cursor/tmp/css-cleanup/[class-name]-[scope]-non-viable-migration-checklist.md`
24+
- **DO NOT output checklist content in chat** - only reference checklist file location
25+
- Output format:
26+
<checklist_summary>
27+
<total_violations>[NUMBER]</total_violations>
28+
<total_checklist_items>[NUMBER]</total_checklist_items>
29+
<validation_check>Items match violations: [TRUE/FALSE]</validation_check>
30+
<checklist_file>`.cursor/tmp/css-cleanup/[class-name]-[scope]-non-viable-migration-checklist.md`</checklist_file>
31+
</checklist_summary>
32+
33+
## PHASE 2: IMPLEMENTATION
34+
**Work from checklist file** - reference saved checklist and update it as you progress through each item.
35+
36+
Execute each checklist item systematically in this exact order:
37+
38+
**Step 1: HTML Template Updates (FIRST PRIORITY)**
39+
- Replace original component classes with "after-migration-[ORIGINAL_CLASS]" in HTML files/templates
40+
- This must be done BEFORE any CSS changes
41+
- Update all instances found in the violation reports
42+
- **Update checklist:** Mark HTML items as complete
43+
44+
**Step 2: CSS Selector Duplication (NOT REPLACEMENT)**
45+
- DUPLICATE CSS selectors, do NOT replace them
46+
- Transform: `.custom-radio {}` → `.custom-radio, .after-migration-custom-radio {}`
47+
- Keep original selector intact alongside new prefixed selector
48+
- This ensures both old and new classes work with identical styling
49+
- Maintain visual parity between original and prefixed versions
50+
- **Update checklist:** Mark CSS items as complete
51+
52+
## PHASE 3: VALIDATION (Success Criteria) - MANDATORY EXECUTION
53+
**CRITICAL:** Execute validation steps from checklist using actual tools, not just manual verification.
54+
55+
**Validation 1 - CSS Count Consistency:**
56+
- **TOOL REQUIRED:** Re-run report-deprecated-css tool on both original directories
57+
- Compare counts with original baseline
58+
- **Update checklist:** Mark validation item as complete
59+
- Output: <validation_1>
60+
<original_count>[NUMBER]</original_count>
61+
<new_count>[NUMBER]</new_count>
62+
<status>PASS/FAIL</status>
63+
<criteria>Deprecated class count remains identical to original</criteria>
64+
</validation_1>
65+
66+
**Validation 2 - Violation Reduction:**
67+
- **TOOL REQUIRED:** Run report-violations tool against modified component scope
68+
- Compare with original violation count
69+
- **Update checklist:** Mark validation item as complete
70+
- Output: <validation_2>
71+
<original_violations>[NUMBER]</original_violations>
72+
<new_violations>[NUMBER]</new_violations>
73+
<replacements_made>[NUMBER]</replacements_made>
74+
<expected_reduction>[NUMBER]</expected_reduction>
75+
<status>PASS/FAIL</status>
76+
<criteria>0 violations OR exactly X fewer violations (where X = number of replacements made)</criteria>
77+
</validation_2>
78+
79+
**Final Step:** Update saved checklist file with validation results and mark all items complete.
80+
81+
## OUTPUT REQUIREMENTS
82+
- Start with identified class name in <target_component> tags
83+
- Show violation counts and checklist summary in <checklist_summary> tags (NO detailed checklist content)
84+
- Reference checklist file location only
85+
- Provide step-by-step implementation status with checklist updates
86+
- Report validation results in <validation_1> and <validation_2> tags with clear pass/fail status
87+
- **Throughout process:** Update checklist file, don't repeat content in chat
88+
89+
Execute each phase completely before proceeding to the next. Request confirmation if validation criteria are not met.
90+
91+
## USAGE
92+
To invoke this workflow, user can say:
93+
- "Execute non-viable handling for [component]"
94+
- "Run the non-migratable component workflow"
95+
- "Handle non-viable component migration"
96+
- Or simply reference this rule: @non-viable-handling
97+
description:
98+
globs:
99+
alwaysApply: false
100+
---

‎docs/README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,9 @@ This documentation is organized into several sections to help you get started qu
3030

3131
### For Design System Migration
3232
1. Use **[Design System Refactoring Flow](ds-refactoring-flow.md)** for systematic legacy component migration
33-
2. Learn about **[Component Contracts](contracts.md)** for validation and safety
34-
3. Reference **[Tools Reference](tools.md)** for specific tool details
33+
2. When components are identified as non-viable during planning, use the **Non-Viable Cases handling** instead of normal fix violations step (requires developer review and approval)
34+
3. Learn about **[Component Contracts](contracts.md)** for validation and safety
35+
4. Reference **[Tools Reference](tools.md)** for specific tool details
3536

3637
### For Developers & Contributors
3738
1. Read **[Architecture & Internal Design](architecture-internal-design.md)** to understand the system
@@ -54,8 +55,10 @@ graph LR
5455
### Design System Migration
5556
```mermaid
5657
graph LR
57-
A[Find Violations] --> B[Plan Refactoring] --> C[Fix Violations] --> D[Validate Changes] --> E[Prepare Report]
58+
A[Find Violations] --> B[Plan Refactoring] --> B1{Viable?}
5859
B --> F[Human Review]
60+
B1 -->|Yes| C[Fix Violations] --> D[Validate Changes] --> E[Prepare Report]
61+
B1 -->|No + Dev Approval| B2[Non-Viable Cases<br/>Handling]
5962
C --> G[Quality Gate]
6063
D --> H[Final Validation]
6164
```

‎docs/contracts.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,8 @@ The contracts system is fully integrated into the 5-step refactoring workflow:
124124
- **Contract role**: Analysis of component structure informs refactoring strategy
125125
- **Output**: Comprehensive migration plan with complexity scoring
126126

127+
**Note on Non-Viable Cases**: When components are identified as non-viable during step 2 and developer approval is obtained, the non-viable cases handling (`03-non-viable-cases.mdc`) is used instead of proceeding to steps 3-5. This handling does not use contracts as it maintains existing component structure while marking components for exclusion from future reports.
128+
127129
### Step 3: Fix Violations (`03-fix-violations.mdc`)
128130
- **Purpose**: Execute the refactoring plan systematically
129131
- **Contract role**: **Pre-refactoring contracts are automatically generated** for each component before changes begin

0 commit comments

Comments
 (0)