@salesforce/afv-skills 1.1.0

package/skills/trigger-refactor-pipeline/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: trigger-refactor-pipeline
+description: Refactor Salesforce triggers into handler patterns with automated test generation and deployment. Use when modernizing legacy triggers with DML/SOQL in loops or inconsistent patterns.
+license: Apache-2.0
+compatibility: Requires Salesforce CLI, Python 3.9+
+metadata:
+  author: afv-library
+  version: "1.0"
+allowed-tools: Bash Read Write
+---
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Modernize legacy triggers with DML/SOQL operations inside loops
+- Refactor triggers that lack clear separation of concerns
+- Implement bulk-safe patterns in existing trigger code
+- Generate comprehensive test coverage for refactored triggers
+
+## Prerequisites
+
+Before starting, ensure you have:
+1. Salesforce CLI installed and authenticated to your target org
+2. Python 3.9 or higher installed
+3. The baseline trigger deployed (see Setup section)
+
+## Setup
+
+Deploy the baseline anti-pattern trigger to analyze and refactor:
+
+```apex
+// ❌ Anti-pattern: all logic stuffed into the trigger, with DML/SOQL in loops.
+trigger OpportunityTrigger on Opportunity (before insert, before update, after update) {
+    // BEFORE INSERT: validate Closed Won w/ low Amount
+    if (Trigger.isBefore && Trigger.isInsert) {
+        for (Opportunity o : Trigger.new) {
+            if (o.StageName == 'Closed Won' && (o.Amount == null || o.Amount < 1000)) {
+                o.addError('Closed Won opportunities must have Amount ≥ 1000.');
+            }
+        }
+    }
+
+    // BEFORE UPDATE: if Stage changed, overwrite Description
+    if (Trigger.isBefore && Trigger.isUpdate) {
+        for (Opportunity o : Trigger.new) {
+            Opportunity oldO = Trigger.oldMap.get(o.Id);
+            if (o.StageName != oldO.StageName) {
+                o.Description = 'Stage changed from ' + oldO.StageName + ' to ' + o.StageName;
+            }
+        }
+    }
+
+    // AFTER UPDATE: when Stage becomes Closed Won, create a follow-up Task
+    if (Trigger.isAfter && Trigger.isUpdate) {
+        for (Opportunity o : Trigger.new) {
+            Opportunity oldO = Trigger.oldMap.get(o.Id);
+            if (o.StageName == 'Closed Won' && oldO.StageName != 'Closed Won') {
+                Task t = new Task(
+                    WhatId     = o.Id,
+                    OwnerId    = o.OwnerId,
+                    Subject    = 'Send thank-you',
+                    Status     = 'Not Started',
+                    Priority   = 'Normal',
+                    ActivityDate = Date.today()
+                );
+                insert t; // ❌ DML in a loop
+            }
+        }
+    }
+}
+```
+
+Deploy this to your org:
+```bash
+sf project deploy start --source-dir force-app/main/default/triggers
+```
+
+## Step 1: Analyze the Trigger
+
+Run the analysis script to identify anti-patterns and generate a report:
+
+```bash
+python scripts/analyze_trigger.py OpportunityTrigger
+```
+
+The script will output:
+- **DML in loops** - Line numbers where DML operations occur inside iteration
+- **SOQL in loops** - Line numbers where SOQL queries occur inside iteration  
+- **Missing bulkification** - Areas where collection-based processing is needed
+- **Complexity score** - Overall trigger complexity rating (1-10)
+- **Recommended approach** - Suggested handler pattern based on trigger contexts
+
+Review the analysis report before proceeding to refactoring.
+
+## Step 2: Review Handler Patterns
+
+Consult the [handler patterns reference](references/handler_patterns.md) to understand:
+- **Single-responsibility handlers** - One handler class per trigger context
+- **Unified handler approach** - Single handler with context methods
+- **Bulk collection strategies** - How to aggregate DML/SOQL outside loops
+- **Best practices** - Error handling, test boundaries, deployment order
+
+Choose the pattern that best fits your trigger's complexity and team conventions.
+
+## Step 3: Refactor the Trigger
+
+Create the handler class using the appropriate pattern from the reference guide:
+
+1. **Extract logic** into handler methods with descriptive names
+2. **Implement bulk-safe collections** for DML operations
+3. **Add proper error handling** using try-catch or Database methods
+4. **Update the trigger** to delegate only, passing Trigger context variables
+5. **Preserve behavior** - ensure the refactored code produces identical results
+
+The trigger should be reduced to simple delegation:
+
+```apex
+trigger OpportunityTrigger on Opportunity (before insert, before update, after update) {
+    OpportunityTriggerHandler handler = new OpportunityTriggerHandler();
+    
+    if (Trigger.isBefore && Trigger.isInsert) {
+        handler.beforeInsert(Trigger.new);
+    }
+    
+    if (Trigger.isBefore && Trigger.isUpdate) {
+        handler.beforeUpdate(Trigger.new, Trigger.oldMap);
+    }
+    
+    if (Trigger.isAfter && Trigger.isUpdate) {
+        handler.afterUpdate(Trigger.new, Trigger.oldMap);
+    }
+}
+```
+
+## Step 4: Generate Tests
+
+Use the test template from `assets/test_template.apex` to scaffold your test class:
+
+1. **Copy the template** and rename for your handler
+2. **Implement setup methods** to create test data
+3. **Write unit tests** covering each handler method:
+   - Positive cases with valid data
+   - Negative cases with invalid data
+   - Boundary conditions
+4. **Add bulk tests** with 200+ records to verify bulkification
+5. **Test mixed scenarios** where only some records qualify for logic
+
+Required test coverage:
+- Each handler method must have at least 2 test methods (positive + negative)
+- At least one bulk test with 200+ records
+- Overall code coverage must be 100%
+
+## Step 5: Deploy and Validate
+
+Deploy the refactored trigger, handler, and tests:
+
+```bash
+# Deploy all components
+sf project deploy start --source-dir force-app/main/default
+
+# Run tests
+sf apex test run --class-names OpportunityTriggerHandlerTest --result-format human --code-coverage
+
+# Verify no regressions
+sf apex test run --test-level RunLocalTests --result-format human
+```
+
+Validation checklist:
+- [ ] All new tests pass with 100% coverage
+- [ ] No new governor limit warnings in debug logs
+- [ ] Existing functionality remains unchanged
+- [ ] Deployment to production planned with rollback strategy
+
+## Troubleshooting
+
+**Issue**: Tests fail with "System.LimitException: Too many DML statements"
+- **Solution**: Ensure handler methods collect DML operations and execute outside loops
+
+**Issue**: Code coverage below 100%
+- **Solution**: Add negative test cases and verify all conditional branches are tested
+
+**Issue**: Behavior differs from original trigger
+- **Solution**: Review Trigger context variables (new, old, oldMap) are passed correctly to handler
+
+## Next Steps
+
+After successful refactoring:
+1. Document the new handler pattern in your team's wiki
+2. Update code review checklist to enforce handler patterns for new triggers
+3. Identify other legacy triggers for refactoring using this skill
+4. Consider implementing a trigger framework if managing many triggers

package/skills/trigger-refactor-pipeline/assets/test_template.apex

@@ -0,0 +1,321 @@
+/**
+ * Test class template for trigger handlers
+ * 
+ * INSTRUCTIONS:
+ * 1. Replace [ObjectName] with your SObject (e.g., Opportunity)
+ * 2. Replace [HandlerClass] with your handler class name
+ * 3. Implement the setupTestData() method with your test records
+ * 4. Add specific test methods for each handler method
+ * 5. Ensure 100% code coverage
+ */
+@IsTest
+private class [ObjectName]TriggerHandlerTest {
+    
+    /**
+     * Setup test data that all test methods can use
+     */
+    @TestSetup
+    static void setupTestData() {
+        // TODO: Create test records here
+        // Example:
+        // List<Opportunity> testOpps = new List<Opportunity>();
+        // for (Integer i = 0; i < 10; i++) {
+        //     testOpps.add(new Opportunity(
+        //         Name = 'Test Opp ' + i,
+        //         StageName = 'Prospecting',
+        //         CloseDate = Date.today().addDays(30),
+        //         Amount = 5000
+        //     ));
+        // }
+        // insert testOpps;
+    }
+    
+    /**
+     * Test beforeInsert handler - Positive case
+     */
+    @IsTest
+    static void testBeforeInsert_Positive() {
+        Test.startTest();
+        
+        // TODO: Create valid test records
+        // List<Opportunity> testRecords = new List<Opportunity>{
+        //     new Opportunity(
+        //         Name = 'Valid Opp',
+        //         StageName = 'Prospecting',
+        //         CloseDate = Date.today().addDays(30),
+        //         Amount = 10000
+        //     )
+        // };
+        
+        // Insert should succeed
+        // insert testRecords;
+        
+        Test.stopTest();
+        
+        // TODO: Add assertions
+        // List<Opportunity> inserted = [SELECT Id, Name FROM Opportunity WHERE Name = 'Valid Opp'];
+        // System.Assert.areEqual(1, inserted.size(), 'Should insert 1 record');
+    }
+    
+    /**
+     * Test beforeInsert handler - Negative case
+     */
+    @IsTest
+    static void testBeforeInsert_Negative() {
+        Test.startTest();
+        
+        Boolean exceptionThrown = false;
+        
+        try {
+            // TODO: Create invalid test records that should fail validation
+            // List<Opportunity> testRecords = new List<Opportunity>{
+            //     new Opportunity(
+            //         Name = 'Invalid Opp',
+            //         StageName = 'Closed Won',
+            //         CloseDate = Date.today(),
+            //         Amount = 500  // Below minimum
+            //     )
+            // };
+            
+            // insert testRecords;
+            
+        } catch (DmlException e) {
+            exceptionThrown = true;
+            // TODO: Assert error message
+            // System.Assert.isTrue(e.getMessage().contains('must have Amount'),
+            //     'Should throw validation error');
+        }
+        
+        Test.stopTest();
+        
+        // System.Assert.isTrue(exceptionThrown, 'Should have thrown an exception');
+    }
+    
+    /**
+     * Test beforeUpdate handler - Positive case
+     */
+    @IsTest
+    static void testBeforeUpdate_Positive() {
+        // TODO: Query existing test data from @TestSetup
+        // List<Opportunity> testOpps = [SELECT Id, StageName, Description FROM Opportunity LIMIT 1];
+        
+        Test.startTest();
+        
+        // TODO: Update records to trigger handler logic
+        // testOpps[0].StageName = 'Qualification';
+        // update testOpps;
+        
+        Test.stopTest();
+        
+        // TODO: Add assertions
+        // Opportunity updated = [SELECT Description FROM Opportunity WHERE Id = :testOpps[0].Id];
+        // System.Assert.isTrue(updated.Description.contains('Stage changed'),
+        //     'Description should be updated');
+    }
+    
+    /**
+     * Test beforeUpdate handler - Negative case
+     */
+    @IsTest
+    static void testBeforeUpdate_Negative() {
+        // TODO: Implement negative test for beforeUpdate
+        Test.startTest();
+        
+        // TODO: Attempt update that should fail
+        
+        Test.stopTest();
+        
+        // TODO: Assert failure occurred
+    }
+    
+    /**
+     * Test afterInsert handler - Positive case
+     */
+    @IsTest
+    static void testAfterInsert_Positive() {
+        Test.startTest();
+        
+        // TODO: Create and insert records
+        
+        Test.stopTest();
+        
+        // TODO: Query for related records created by handler
+        // List<Task> createdTasks = [SELECT Id FROM Task];
+        // System.Assert.areEqual(1, createdTasks.size(), 'Should create 1 task');
+    }
+    
+    /**
+     * Test afterUpdate handler - Positive case
+     */
+    @IsTest
+    static void testAfterUpdate_Positive() {
+        // TODO: Query existing test data
+        // List<Opportunity> testOpps = [SELECT Id, StageName FROM Opportunity LIMIT 1];
+        
+        Test.startTest();
+        
+        // TODO: Update to trigger after-update logic
+        // testOpps[0].StageName = 'Closed Won';
+        // update testOpps;
+        
+        Test.stopTest();
+        
+        // TODO: Query for side effects (e.g., Tasks created)
+        // List<Task> tasks = [SELECT Id, Subject FROM Task WHERE WhatId = :testOpps[0].Id];
+        // System.Assert.areEqual(1, tasks.size(), 'Should create 1 task');
+        // System.Assert.areEqual('Send thank-you', tasks[0].Subject);
+    }
+    
+    /**
+     * Test bulk operations - 200+ records
+     * Critical for validating bulkification
+     */
+    @IsTest
+    static void testBulkInsert() {
+        Test.startTest();
+        
+        // TODO: Create 200+ records
+        // List<Opportunity> bulkOpps = new List<Opportunity>();
+        // for (Integer i = 0; i < 200; i++) {
+        //     bulkOpps.add(new Opportunity(
+        //         Name = 'Bulk Opp ' + i,
+        //         StageName = 'Prospecting',
+        //         CloseDate = Date.today().addDays(30),
+        //         Amount = 10000
+        //     ));
+        // }
+        
+        // insert bulkOpps;
+        
+        Test.stopTest();
+        
+        // TODO: Assert all records inserted successfully
+        // List<Opportunity> inserted = [SELECT Id FROM Opportunity WHERE Name LIKE 'Bulk Opp%'];
+        // System.Assert.areEqual(200, inserted.size(), 'Should insert all 200 records');
+    }
+    
+    /**
+     * Test bulk update with mixed scenarios
+     * Some records qualify for logic, others don't
+     */
+    @IsTest
+    static void testBulkUpdate_Mixed() {
+        // Create test data
+        List<Opportunity> testOpps = new List<Opportunity>();
+        for (Integer i = 0; i < 50; i++) {
+            testOpps.add(new Opportunity(
+                Name = 'Bulk Update Opp ' + i,
+                StageName = 'Prospecting',
+                CloseDate = Date.today().addDays(30),
+                Amount = 10000
+            ));
+        }
+        insert testOpps;
+        
+        Test.startTest();
+        
+        // Update half to trigger logic, half to not trigger
+        for (Integer i = 0; i < testOpps.size(); i++) {
+            if (Math.mod(i, 2) == 0) {
+                // TODO: Set condition that triggers handler logic
+                // testOpps[i].StageName = 'Closed Won';
+            } else {
+                // TODO: Set condition that doesn't trigger handler logic
+                // testOpps[i].Amount = 15000;
+            }
+        }
+        
+        // update testOpps;
+        
+        Test.stopTest();
+        
+        // TODO: Assert only qualifying records triggered side effects
+        // List<Task> tasks = [SELECT Id FROM Task WHERE WhatId IN :testOpps];
+        // System.Assert.areEqual(25, tasks.size(), 'Should create tasks for 25 qualifying records');
+    }
+    
+    /**
+     * Test governor limits are not exceeded
+     */
+    @IsTest
+    static void testGovernorLimits() {
+        Test.startTest();
+        
+        // TODO: Create maximum allowed records
+        // List<Opportunity> maxOpps = new List<Opportunity>();
+        // for (Integer i = 0; i < 200; i++) {
+        //     maxOpps.add(new Opportunity(
+        //         Name = 'Limit Test ' + i,
+        //         StageName = 'Closed Won',
+        //         CloseDate = Date.today(),
+        //         Amount = 10000
+        //     ));
+        // }
+        
+        // insert maxOpps;
+        
+        Test.stopTest();
+        
+        // Assert we're under governor limits
+        System.Assert.isTrue(Limits.getDmlStatements() < Limits.getLimitDmlStatements(),
+            'Should not exceed DML statement limit');
+        System.Assert.isTrue(Limits.getQueries() < Limits.getLimitQueries(),
+            'Should not exceed SOQL query limit');
+    }
+    
+    /**
+     * Test with null or empty collections
+     * Ensures handler doesn't break with edge cases
+     */
+    @IsTest
+    static void testWithEmptyCollection() {
+        Test.startTest();
+        
+        // TODO: Call handler methods with empty lists
+        // OpportunityTriggerHandler handler = new OpportunityTriggerHandler();
+        // handler.beforeInsert(new List<Opportunity>());
+        
+        Test.stopTest();
+        
+        // If we get here without exception, test passes
+        System.Assert.isTrue(true, 'Handler should handle empty collections gracefully');
+    }
+    
+    /**
+     * Helper method to create test data inline
+     * Use when @TestSetup is not sufficient
+     */
+    private static List<Opportunity> createTestOpportunities(Integer count) {
+        List<Opportunity> testOpps = new List<Opportunity>();
+        
+        for (Integer i = 0; i < count; i++) {
+            testOpps.add(new Opportunity(
+                Name = 'Test Opp ' + i,
+                StageName = 'Prospecting',
+                CloseDate = Date.today().addDays(30),
+                Amount = 10000
+            ));
+        }
+        
+        return testOpps;
+    }
+    
+    /**
+     * Helper method to assert task creation
+     */
+    private static void assertTasksCreated(List<Id> oppIds, Integer expectedCount, String subject) {
+        List<Task> tasks = [
+            SELECT Id, Subject, WhatId
+            FROM Task
+            WHERE WhatId IN :oppIds
+        ];
+        
+        System.Assert.areEqual(expectedCount, tasks.size(),
+            'Should create ' + expectedCount + ' task(s)');
+        
+        if (expectedCount > 0) {
+            System.Assert.areEqual(subject, tasks[0].Subject,
+                'Task subject should match');
+        }
+    }
+}