@salesforce/afv-skills 1.1.0

package/skills/trigger-refactor-pipeline/references/handler_patterns.md

@@ -0,0 +1,442 @@
+# Trigger Handler Patterns Reference
+
+This guide covers common patterns for refactoring Salesforce triggers into handler classes with bulk-safe operations.
+
+## Pattern 1: Simple Handler Class
+
+**Best for**: Triggers with 1-3 contexts and straightforward logic.
+
+### Structure
+
+```apex
+public class OpportunityTriggerHandler {
+    
+    public void beforeInsert(List<Opportunity> newRecords) {
+        validateClosedWonAmount(newRecords);
+    }
+    
+    public void beforeUpdate(List<Opportunity> newRecords, Map<Id, Opportunity> oldMap) {
+        updateDescriptionOnStageChange(newRecords, oldMap);
+    }
+    
+    public void afterUpdate(List<Opportunity> newRecords, Map<Id, Opportunity> oldMap) {
+        createTasksForClosedWon(newRecords, oldMap);
+    }
+    
+    // Private helper methods below
+    private void validateClosedWonAmount(List<Opportunity> opportunities) {
+        for (Opportunity opp : opportunities) {
+            if (opp.StageName == 'Closed Won' && 
+                (opp.Amount == null || opp.Amount < 1000)) {
+                opp.addError('Closed Won opportunities must have Amount ≥ 1000.');
+            }
+        }
+    }
+    
+    private void updateDescriptionOnStageChange(
+        List<Opportunity> newRecords, 
+        Map<Id, Opportunity> oldMap
+    ) {
+        for (Opportunity opp : newRecords) {
+            Opportunity oldOpp = oldMap.get(opp.Id);
+            if (opp.StageName != oldOpp.StageName) {
+                opp.Description = 'Stage changed from ' + 
+                    oldOpp.StageName + ' to ' + opp.StageName;
+            }
+        }
+    }
+    
+    private void createTasksForClosedWon(
+        List<Opportunity> newRecords, 
+        Map<Id, Opportunity> oldMap
+    ) {
+        List<Task> tasksToInsert = new List<Task>();
+        
+        for (Opportunity opp : newRecords) {
+            Opportunity oldOpp = oldMap.get(opp.Id);
+            
+            // Check if stage changed to Closed Won
+            if (opp.StageName == 'Closed Won' && 
+                oldOpp.StageName != 'Closed Won') {
+                
+                tasksToInsert.add(new Task(
+                    WhatId = opp.Id,
+                    OwnerId = opp.OwnerId,
+                    Subject = 'Send thank-you',
+                    Status = 'Not Started',
+                    Priority = 'Normal',
+                    ActivityDate = Date.today()
+                ));
+            }
+        }
+        
+        // Bulk DML outside loop
+        if (!tasksToInsert.isEmpty()) {
+            insert tasksToInsert;
+        }
+    }
+}
+```
+
+### Trigger Delegation
+
+```apex
+trigger OpportunityTrigger on Opportunity (
+    before insert, before update, after update
+) {
+    OpportunityTriggerHandler handler = new OpportunityTriggerHandler();
+    
+    if (Trigger.isBefore) {
+        if (Trigger.isInsert) {
+            handler.beforeInsert(Trigger.new);
+        } else if (Trigger.isUpdate) {
+            handler.beforeUpdate(Trigger.new, Trigger.oldMap);
+        }
+    }
+    
+    if (Trigger.isAfter && Trigger.isUpdate) {
+        handler.afterUpdate(Trigger.new, Trigger.oldMap);
+    }
+}
+```
+
+## Pattern 2: Handler with Database Methods
+
+**Best for**: When you need granular error handling and partial success.
+
+### Key Features
+
+- Uses `Database.insert()` instead of `insert` for partial saves
+- Returns `Database.SaveResult` for error handling
+- Logs errors without stopping execution
+
+### Example
+
+```apex
+private void createTasksForClosedWon(
+    List<Opportunity> newRecords, 
+    Map<Id, Opportunity> oldMap
+) {
+    List<Task> tasksToInsert = new List<Task>();
+    
+    for (Opportunity opp : newRecords) {
+        Opportunity oldOpp = oldMap.get(opp.Id);
+        
+        if (opp.StageName == 'Closed Won' && 
+            oldOpp.StageName != 'Closed Won') {
+            
+            tasksToInsert.add(new Task(
+                WhatId = opp.Id,
+                OwnerId = opp.OwnerId,
+                Subject = 'Send thank-you',
+                Status = 'Not Started',
+                Priority = 'Normal',
+                ActivityDate = Date.today()
+            ));
+        }
+    }
+    
+    if (!tasksToInsert.isEmpty()) {
+        Database.SaveResult[] results = Database.insert(tasksToInsert, false);
+        
+        // Log errors without stopping execution
+        for (Integer i = 0; i < results.size(); i++) {
+            if (!results[i].isSuccess()) {
+                System.debug('Failed to create task: ' + results[i].getErrors());
+            }
+        }
+    }
+}
+```
+
+## Pattern 3: Handler with Maps for Lookups
+
+**Best for**: When you need to query related records for processing.
+
+### Key Features
+
+- Pre-queries related records using Sets
+- Uses Maps for O(1) lookups instead of nested loops
+- Avoids SOQL in loops
+
+### Example
+
+```apex
+private void enrichOpportunitiesWithAccountData(List<Opportunity> opportunities) {
+    // Collect Account IDs
+    Set<Id> accountIds = new Set<Id>();
+    for (Opportunity opp : opportunities) {
+        if (opp.AccountId != null) {
+            accountIds.add(opp.AccountId);
+        }
+    }
+    
+    // Single SOQL query outside loop
+    Map<Id, Account> accountMap = new Map<Id, Account>([
+        SELECT Id, Name, Industry, AnnualRevenue
+        FROM Account
+        WHERE Id IN :accountIds
+    ]);
+    
+    // Use Map for O(1) lookup
+    for (Opportunity opp : opportunities) {
+        if (opp.AccountId != null && accountMap.containsKey(opp.AccountId)) {
+            Account acc = accountMap.get(opp.AccountId);
+            // Process with account data
+            opp.Description = 'Account Industry: ' + acc.Industry;
+        }
+    }
+}
+```
+
+## Pattern 4: Unified Handler Framework
+
+**Best for**: Complex triggers with many contexts and cross-cutting concerns.
+
+### Structure
+
+```apex
+public abstract class TriggerHandler {
+    
+    protected Boolean isBefore;
+    protected Boolean isAfter;
+    protected Boolean isInsert;
+    protected Boolean isUpdate;
+    protected Boolean isDelete;
+    protected Boolean isUndelete;
+    
+    public void run() {
+        isBefore = Trigger.isBefore;
+        isAfter = Trigger.isAfter;
+        isInsert = Trigger.isInsert;
+        isUpdate = Trigger.isUpdate;
+        isDelete = Trigger.isDelete;
+        isUndelete = Trigger.isUndelete;
+        
+        if (isBefore) {
+            if (isInsert) beforeInsert();
+            if (isUpdate) beforeUpdate();
+            if (isDelete) beforeDelete();
+        }
+        
+        if (isAfter) {
+            if (isInsert) afterInsert();
+            if (isUpdate) afterUpdate();
+            if (isDelete) afterDelete();
+            if (isUndelete) afterUndelete();
+        }
+    }
+    
+    protected virtual void beforeInsert() {}
+    protected virtual void beforeUpdate() {}
+    protected virtual void beforeDelete() {}
+    protected virtual void afterInsert() {}
+    protected virtual void afterUpdate() {}
+    protected virtual void afterDelete() {}
+    protected virtual void afterUndelete() {}
+}
+```
+
+### Concrete Handler
+
+```apex
+public class OpportunityTriggerHandler extends TriggerHandler {
+    
+    private List<Opportunity> newRecords;
+    private List<Opportunity> oldRecords;
+    private Map<Id, Opportunity> newMap;
+    private Map<Id, Opportunity> oldMap;
+    
+    public OpportunityTriggerHandler() {
+        this.newRecords = (List<Opportunity>) Trigger.new;
+        this.oldRecords = (List<Opportunity>) Trigger.old;
+        this.newMap = (Map<Id, Opportunity>) Trigger.newMap;
+        this.oldMap = (Map<Id, Opportunity>) Trigger.oldMap;
+    }
+    
+    protected override void beforeInsert() {
+        validateClosedWonAmount();
+    }
+    
+    protected override void beforeUpdate() {
+        updateDescriptionOnStageChange();
+    }
+    
+    protected override void afterUpdate() {
+        createTasksForClosedWon();
+    }
+    
+    // Private helper methods omitted for brevity
+}
+```
+
+### Trigger Delegation
+
+```apex
+trigger OpportunityTrigger on Opportunity (
+    before insert, before update, after update
+) {
+    new OpportunityTriggerHandler().run();
+}
+```
+
+## Best Practices
+
+### 1. Bulkification
+
+Always process records in collections:
+
+```apex
+// ✓ Good: Collect DML outside loop
+List<Task> tasksToInsert = new List<Task>();
+for (Opportunity opp : opportunities) {
+    tasksToInsert.add(new Task(...));
+}
+if (!tasksToInsert.isEmpty()) {
+    insert tasksToInsert;
+}
+
+// ✗ Bad: DML inside loop
+for (Opportunity opp : opportunities) {
+    insert new Task(...);  // SOQL/DML in loop!
+}
+```
+
+### 2. Defensive Null Checks
+
+```apex
+// ✓ Good: Check for null before accessing
+if (opp.AccountId != null && accountMap.containsKey(opp.AccountId)) {
+    Account acc = accountMap.get(opp.AccountId);
+    // Safe to use acc
+}
+
+// ✗ Bad: Assumes data exists
+Account acc = accountMap.get(opp.AccountId);
+String industry = acc.Industry;  // NullPointerException risk
+```
+
+### 3. Clear Method Names
+
+```apex
+// ✓ Good: Descriptive, verb-noun pattern
+private void validateClosedWonAmount(List<Opportunity> opportunities)
+private void createTasksForClosedWon(List<Opportunity> opportunities)
+
+// ✗ Bad: Vague or unclear
+private void validate(List<Opportunity> opportunities)
+private void doStuff(List<Opportunity> opportunities)
+```
+
+### 4. Single Responsibility
+
+Each handler method should do one thing:
+
+```apex
+// ✓ Good: Separate concerns
+private void validateClosedWonAmount(List<Opportunity> opportunities)
+private void validateRequiredFields(List<Opportunity> opportunities)
+private void calculateDiscounts(List<Opportunity> opportunities)
+
+// ✗ Bad: One method does everything
+private void processOpportunities(List<Opportunity> opportunities)
+```
+
+### 5. Test Boundaries
+
+Structure code to make testing easier:
+
+```apex
+// ✓ Good: Public method for testing, private for implementation
+@TestVisible
+private void createTasksForClosedWon(
+    List<Opportunity> newRecords,
+    Map<Id, Opportunity> oldMap
+) {
+    // Implementation
+}
+```
+
+## Deployment Order
+
+When deploying refactored triggers:
+
+1. Deploy handler class(es) first
+2. Update trigger to use handler
+3. Deploy test class
+4. Run all tests before production deployment
+5. Monitor debug logs for 24-48 hours after production deployment
+
+## Rollback Strategy
+
+Keep the old trigger code commented out or in version control:
+
+```apex
+trigger OpportunityTrigger on Opportunity (...) {
+    // New handler approach
+    new OpportunityTriggerHandler().run();
+    
+    /* OLD CODE - REMOVE AFTER 1 WEEK IF NO ISSUES
+    if (Trigger.isBefore && Trigger.isInsert) {
+        for (Opportunity o : Trigger.new) {
+            // old logic
+        }
+    }
+    */
+}
+```
+
+## Common Pitfalls
+
+### Pitfall 1: Recursive Triggers
+
+**Problem**: Handler calls DML which triggers the same trigger again.
+
+**Solution**: Use static flag to prevent recursion:
+
+```apex
+public class OpportunityTriggerHandler {
+    private static Boolean isExecuting = false;
+    
+    public void beforeUpdate(List<Opportunity> newRecords, Map<Id, Opportunity> oldMap) {
+        if (isExecuting) return;
+        
+        isExecuting = true;
+        try {
+            // Your logic here
+        } finally {
+            isExecuting = false;
+        }
+    }
+}
+```
+
+### Pitfall 2: Mixed Context Logic
+
+**Problem**: Before-context logic mixed with after-context logic.
+
+**Solution**: Keep context methods separate and focused:
+
+```apex
+// ✓ Good: Separate methods per context
+public void beforeUpdate(List<Opportunity> newRecords, Map<Id, Opportunity> oldMap)
+public void afterUpdate(List<Opportunity> newRecords, Map<Id, Opportunity> oldMap)
+
+// ✗ Bad: Mixed logic in one method
+public void handleUpdate(List<Opportunity> newRecords, Map<Id, Opportunity> oldMap)
+```
+
+### Pitfall 3: Over-Engineering
+
+**Problem**: Using complex framework for simple triggers.
+
+**Solution**: Choose the right pattern for your complexity:
+- 1-3 contexts with simple logic → Simple Handler (Pattern 1)
+- 3-5 contexts with moderate complexity → Handler with Database Methods (Pattern 2)
+- 5+ contexts with cross-cutting concerns → Unified Framework (Pattern 4)
+
+## Additional Resources
+
+- [Apex Developer Guide: Trigger and Bulk Request Best Practices](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_triggers_bulk_requests.htm)
+- [Apex Enterprise Patterns](https://github.com/apex-enterprise-patterns)
+- [Trigger Framework Comparison](https://github.com/kevinohara80/sfdc-trigger-framework)

package/skills/trigger-refactor-pipeline/scripts/analyze_trigger.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""
+Analyze Salesforce Apex triggers for common anti-patterns.
+
+Usage:
+    python analyze_trigger.py <TriggerName>
+
+Requirements:
+    - Salesforce CLI authenticated to target org
+    - Python 3.9+
+"""
+
+import sys
+import subprocess
+import json
+import re
+from typing import List, Dict, Tuple
+
+class TriggerAnalyzer:
+    def __init__(self, trigger_name: str):
+        self.trigger_name = trigger_name
+        self.trigger_body = ""
+        self.issues = {
+            'dml_in_loops': [],
+            'soql_in_loops': [],
+            'missing_bulk': [],
+        }
+        self.complexity_score = 0
+        
+    def retrieve_trigger(self) -> bool:
+        """Retrieve trigger source code from Salesforce org."""
+        try:
+            cmd = [
+                'sf', 'apex', 'get', 'trigger',
+                '--trigger-name', self.trigger_name,
+                '--json'
+            ]
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            
+            if result.returncode != 0:
+                print(f"Error retrieving trigger: {result.stderr}")
+                return False
+                
+            data = json.loads(result.stdout)
+            self.trigger_body = data.get('result', {}).get('body', '')
+            return True
+            
+        except Exception as e:
+            print(f"Failed to retrieve trigger: {e}")
+            return False
+    
+    def analyze_dml_in_loops(self) -> None:
+        """Detect DML operations inside for loops."""
+        lines = self.trigger_body.split('\n')
+        in_loop = False
+        loop_start = 0
+        
+        dml_patterns = [
+            r'\binsert\s+', r'\bupdate\s+', r'\bdelete\s+',
+            r'\bundelete\s+', r'\bupsert\s+'
+        ]
+        
+        for i, line in enumerate(lines, 1):
+            # Track loop entry
+            if re.search(r'\bfor\s*\(', line):
+                in_loop = True
+                loop_start = i
+                
+            # Track loop exit
+            if in_loop and line.strip() == '}':
+                # Check if this closes the loop (simplified heuristic)
+                in_loop = False
+                
+            # Check for DML in loop
+            if in_loop:
+                for pattern in dml_patterns:
+                    if re.search(pattern, line):
+                        self.issues['dml_in_loops'].append({
+                            'line': i,
+                            'code': line.strip(),
+                            'loop_start': loop_start
+                        })
+    
+    def analyze_soql_in_loops(self) -> None:
+        """Detect SOQL queries inside for loops."""
+        lines = self.trigger_body.split('\n')
+        in_loop = False
+        loop_start = 0
+        
+        soql_pattern = r'\[SELECT\s+'
+        
+        for i, line in enumerate(lines, 1):
+            if re.search(r'\bfor\s*\(', line):
+                in_loop = True
+                loop_start = i
+                
+            if in_loop and line.strip() == '}':
+                in_loop = False
+                
+            if in_loop and re.search(soql_pattern, line, re.IGNORECASE):
+                self.issues['soql_in_loops'].append({
+                    'line': i,
+                    'code': line.strip(),
+                    'loop_start': loop_start
+                })
+    
+    def analyze_bulkification(self) -> None:
+        """Check for proper bulkification patterns."""
+        # Simple heuristic: if we have DML in loops, bulkification is missing
+        if self.issues['dml_in_loops']:
+            self.issues['missing_bulk'].append({
+                'message': 'DML operations should be collected and executed outside loops',
+                'affected_lines': [issue['line'] for issue in self.issues['dml_in_loops']]
+            })
+            
+        if self.issues['soql_in_loops']:
+            self.issues['missing_bulk'].append({
+                'message': 'SOQL queries should be moved outside loops or use Maps for lookups',
+                'affected_lines': [issue['line'] for issue in self.issues['soql_in_loops']]
+            })
+    
+    def calculate_complexity(self) -> None:
+        """Calculate overall complexity score (1-10)."""
+        score = 1
+        
+        # Add points for each issue type
+        score += len(self.issues['dml_in_loops']) * 2
+        score += len(self.issues['soql_in_loops']) * 2
+        score += len(self.issues['missing_bulk']) * 1
+        
+        # Count trigger contexts
+        contexts = len(re.findall(r'Trigger\.(isBefore|isAfter)', self.trigger_body))
+        score += contexts
+        
+        # Count lines of code (normalized)
+        loc = len([l for l in self.trigger_body.split('\n') if l.strip()])
+        score += min(loc // 10, 3)
+        
+        self.complexity_score = min(score, 10)
+    
+    def recommend_approach(self) -> str:
+        """Recommend refactoring approach based on analysis."""
+        if self.complexity_score <= 3:
+            return "Simple handler class with separate methods for each trigger context"
+        elif self.complexity_score <= 6:
+            return "Handler class with bulkified collections and helper methods"
+        else:
+            return "Unified handler framework with separate concern classes (validation, DML, etc.)"
+    
+    def generate_report(self) -> None:
+        """Print analysis report."""
+        print("\n" + "="*70)
+        print(f"TRIGGER ANALYSIS REPORT: {self.trigger_name}")
+        print("="*70 + "\n")
+        
+        print(f"Complexity Score: {self.complexity_score}/10")
+        print(f"Recommended Approach: {self.recommend_approach()}\n")
+        
+        # DML in loops
+        if self.issues['dml_in_loops']:
+            print("⚠️  DML OPERATIONS IN LOOPS:")
+            for issue in self.issues['dml_in_loops']:
+                print(f"   Line {issue['line']}: {issue['code']}")
+                print(f"   └─ Loop started at line {issue['loop_start']}")
+            print()
+        else:
+            print("✓ No DML operations found in loops\n")
+        
+        # SOQL in loops
+        if self.issues['soql_in_loops']:
+            print("⚠️  SOQL QUERIES IN LOOPS:")
+            for issue in self.issues['soql_in_loops']:
+                print(f"   Line {issue['line']}: {issue['code']}")
+                print(f"   └─ Loop started at line {issue['loop_start']}")
+            print()
+        else:
+            print("✓ No SOQL queries found in loops\n")
+        
+        # Bulkification
+        if self.issues['missing_bulk']:
+            print("⚠️  BULKIFICATION RECOMMENDATIONS:")
+            for issue in self.issues['missing_bulk']:
+                print(f"   • {issue['message']}")
+                print(f"     Affected lines: {', '.join(map(str, issue['affected_lines']))}")
+            print()
+        else:
+            print("✓ Bulkification patterns look good\n")
+        
+        print("="*70)
+        print("NEXT STEPS:")
+        print("1. Review the handler patterns reference guide")
+        print("2. Create handler class with bulk-safe collections")
+        print("3. Extract trigger logic into handler methods")
+        print("4. Generate comprehensive tests using the template")
+        print("="*70 + "\n")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python analyze_trigger.py <TriggerName>")
+        sys.exit(1)
+    
+    trigger_name = sys.argv[1]
+    
+    print(f"Analyzing trigger: {trigger_name}...")
+    
+    analyzer = TriggerAnalyzer(trigger_name)
+    
+    # For demo purposes, use inline example if retrieval fails
+    if not analyzer.retrieve_trigger():
+        print("⚠️  Could not retrieve from org. Using example trigger for demonstration.\n")
+        # Use the example from the SKILL.md
+        analyzer.trigger_body = """trigger OpportunityTrigger on Opportunity (before insert, before update, after update) {
+    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.');
+            }
+        }
+    }
+    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;
+            }
+        }
+    }
+    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;
+            }
+        }
+    }
+}"""
+    
+    # Run analysis
+    analyzer.analyze_dml_in_loops()
+    analyzer.analyze_soql_in_loops()
+    analyzer.analyze_bulkification()
+    analyzer.calculate_complexity()
+    
+    # Generate report
+    analyzer.generate_report()
+
+
+if __name__ == '__main__':
+    main()