@salesforce/afv-skills 1.28.0 → 1.29.0

package/skills/dx-code-analyzer-custom-rule-create/examples/xpath-examples.md

@@ -0,0 +1,227 @@
+# XPath Rule Examples
+
+Real-world custom PMD/XPath rules for Apex, derived from community requests and common enforcement needs.
+
+## Example 1: Ban System.debug in Production Code
+
+**Problem:** Debug statements clutter logs and expose sensitive data.
+
+**Sample violating code:**
+```apex
+public class MyService {
+    public void doWork() {
+        System.debug('Sensitive: ' + record.SSN__c);
+    }
+}
+```
+
+**AST nodes (from ast-dump):**
+```xml
+<MethodCallExpression FullMethodName='System.debug' InputParametersSize='1' ...>
+```
+
+**XPath:**
+```xpath
+//MethodCallExpression[@FullMethodName='System.debug']
+  [not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+```
+
+**PMD ruleset:**
+```xml
+<rule name="NoSystemDebugInProduction" language="apex"
+      message="System.debug statements are not allowed in production code"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <priority>3</priority>
+    <properties>
+        <property name="xpath">
+            <value>//MethodCallExpression[@FullMethodName='System.debug'][not(ancestor::UserClass[ModifierNode[@Test = true()]])]</value>
+        </property>
+    </properties>
+</rule>
+```
+
+---
+
+## Example 2: SOQL Query Inside a Loop
+
+**Problem:** Governor limit risk — N+1 queries.
+
+**Sample violating code:**
+```apex
+public class AccountProcessor {
+    public void process(List<Account> accounts) {
+        for (Account acc : accounts) {
+            List<Contact> contacts = [SELECT Id FROM Contact WHERE AccountId = :acc.Id];
+        }
+    }
+}
+```
+
+**AST nodes:**
+```xml
+<ForEachStatement>
+    ...
+    <BlockStatement>
+        <VariableDeclarationStatements>
+            <VariableDeclaration>
+                <SoqlExpression Query='SELECT Id FROM Contact...' />
+```
+
+**XPath:**
+```xpath
+//ForEachStatement/BlockStatement//SoqlExpression
+|
+//ForLoopStatement/BlockStatement//SoqlExpression
+|
+//WhileLoopStatement/BlockStatement//SoqlExpression
+```
+
+> ⚠️ **Why `/BlockStatement//`?** ForEachStatement has the iterable SOQL as a direct child alongside BlockStatement. Without scoping to `/BlockStatement//`, the XPath also matches `for (Contact c : [SELECT...])` — a valid Apex idiom that is NOT a governor limit risk.
+
+---
+
+## Example 3: Enforce @IsTest(testFor) Annotation
+
+**Problem:** Test classes should specify which class they test for traceability.
+(GitHub issue #2008 — real community request)
+
+**Sample violating code:**
+```apex
+@IsTest
+public class MyServiceTest {
+    // Missing testFor parameter
+}
+```
+
+**AST nodes:**
+```xml
+<UserClass Image='MyServiceTest'>
+    <ModifierNode Test='true'>
+        <Annotation Image='IsTest'>
+            <!-- No AnnotationParameter with Name='testFor' -->
+        </Annotation>
+    </ModifierNode>
+```
+
+**XPath:**
+```xpath
+/ApexFile/UserClass/ModifierNode/Annotation[
+  @Image='IsTest'
+  and count(AnnotationParameter[@Name='testFor']) = 0
+]
+```
+
+---
+
+## Example 4: DML Operations Without Try-Catch
+
+**Problem:** Unhandled DML exceptions cause runtime failures.
+(GitHub issue #738 — user requested "detect missing try-catch")
+
+**Sample violating code:**
+```apex
+public class AccountService {
+    public void createAccount(String name) {
+        Account acc = new Account(Name = name);
+        insert acc;  // No try-catch!
+    }
+}
+```
+
+**AST nodes:**
+```xml
+<DmlInsertStatement>
+    <VariableExpression Image='acc' />
+</DmlInsertStatement>
+<!-- No TryCatchFinallyBlockStatement ancestor -->
+```
+
+**XPath:**
+```xpath
+//DmlInsertStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+|
+//DmlUpdateStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+|
+//DmlDeleteStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+```
+
+---
+
+## Example 5: Nested If Statements (Max Depth 3)
+
+**Problem:** Deep nesting reduces readability and maintainability.
+
+**Sample violating code:**
+```apex
+public class ComplexLogic {
+    public void process(Integer a, Integer b, Integer c, Integer d) {
+        if (a > 0) {
+            if (b > 0) {
+                if (c > 0) {
+                    if (d > 0) {  // 4th level — violation!
+                        doWork();
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+**XPath (flags depth 4+):**
+```xpath
+//IfBlockStatement[
+  ancestor::IfBlockStatement[
+    ancestor::IfBlockStatement[
+      ancestor::IfBlockStatement
+    ]
+  ]
+]
+```
+
+---
+
+## Example 6: Class Without Explicit Sharing Declaration
+
+**Problem:** Classes without sharing default to "without sharing" — security risk.
+
+**Sample violating code:**
+```apex
+public class UnsafeService {  // No "with sharing" or "without sharing"
+    public List<Account> getAccounts() {
+        return [SELECT Id FROM Account];
+    }
+}
+```
+
+**AST nodes:**
+```xml
+<UserClass Image='UnsafeService'>
+    <ModifierNode WithSharing='false' WithoutSharing='false' InheritedSharing='false' ...>
+```
+
+**XPath:**
+```xpath
+//UserClass[
+  ModifierNode[
+    @WithSharing = false()
+    and @WithoutSharing = false()
+    and @InheritedSharing = false()
+  ]
+  and not(ModifierNode[@Test = true()])
+]
+```
+
+---
+
+## How to Create These
+
+For each example above, the creation process was:
+
+1. Write the sample violating code (5-10 lines)
+2. Run: `sf code-analyzer ast-dump --file sample.cls`
+3. Find the relevant node in the XML output
+4. Write XPath using the exact node names and attributes
+5. Create the ruleset XML using the template
+6. Validate: `sf code-analyzer rules --rule-selector pmd:RuleName`
+7. Test: `sf code-analyzer run --rule-selector pmd:RuleName --target sample.cls`

package/skills/dx-code-analyzer-custom-rule-create/references/advanced-pmd-patterns.md

@@ -0,0 +1,288 @@
+# Advanced PMD Patterns
+
+Multi-rule rulesets, overriding built-in rules, exclusion patterns, Java-based rules, and sharing rules across projects.
+
+## Multiple Rules in One Ruleset File
+
+A single ruleset XML can contain any number of rules. This is the recommended approach for teams maintaining a shared rule set:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="TeamStandards"
+    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
+
+    <description>Team coding standards</description>
+
+    <!-- Rule 1: Custom XPath rule -->
+    <rule name="NoSystemDebug" language="apex"
+          message="Remove System.debug before merging"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>3</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//MethodCallExpression[@FullMethodName='System.debug']
+  [not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+
+    <!-- Rule 2: Another custom XPath rule -->
+    <rule name="SoqlInLoop" language="apex"
+          message="SOQL query inside a loop — move query before the loop"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>2</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//ForEachStatement//SoqlExpression | //ForLoopStatement//SoqlExpression | //WhileLoopStatement//SoqlExpression
+]]></value>
+            </property>
+        </properties>
+    </rule>
+
+    <!-- Rule 3: XML metadata rule in the same file -->
+    <rule name="MinApiVersion" language="xml"
+          message="Update API version to 60.0+"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>3</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//*[local-name()='apiVersion'][number(substring-before(text(), '.')) < 60]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+</ruleset>
+```
+
+Rules with different `language` values (apex, xml, visualforce, etc.) can coexist in one ruleset. PMD applies each rule only to files matching its language.
+
+## Overriding Built-in PMD Rules
+
+Override severity, priority, or configurable properties on PMD's built-in rules without writing new ones:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="CustomizedBuiltins"
+    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
+
+    <description>Customized built-in rule thresholds</description>
+
+    <!-- Lower the complexity threshold from default 25 to 10 -->
+    <rule ref="category/apex/design.xml/CyclomaticComplexity">
+        <priority>2</priority>
+        <properties>
+            <property name="classReportLevel" value="40" />
+            <property name="methodReportLevel" value="10" />
+        </properties>
+    </rule>
+
+    <!-- Change excessive parameter count from default 4 to 3 -->
+    <rule ref="category/apex/design.xml/ExcessiveParameterList">
+        <properties>
+            <property name="minimum" value="3" />
+        </properties>
+    </rule>
+
+    <!-- Make debug statement rule high-severity instead of moderate -->
+    <rule ref="category/apex/bestpractices.xml/DebugsShouldUseLoggingLevel">
+        <priority>2</priority>
+        <properties>
+            <property name="strictMode" value="true" />
+        </properties>
+    </rule>
+
+    <!-- Include an entire category with one exclusion -->
+    <rule ref="category/apex/security.xml">
+        <exclude name="ApexSuggestUsingNamedCred" />
+    </rule>
+</ruleset>
+```
+
+**Configuration:**
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    custom_rulesets:
+      - "custom-rules/customized-builtins.xml"
+```
+
+### How rule ref works
+
+| Pattern | Effect |
+|---------|--------|
+| `<rule ref="category/apex/design.xml/CyclomaticComplexity">` | Override one specific rule |
+| `<rule ref="category/apex/security.xml">` | Include entire category |
+| `<rule ref="..."><exclude name="RuleName"/></rule>` | Include category minus specific rules |
+| Nested `<priority>` | Override severity (1=Critical, 2=High, 3=Moderate, 4=Low, 5=Info) |
+| Nested `<properties>` | Override configurable thresholds/options |
+
+### Common built-in rules to customize
+
+| Rule | Useful Properties |
+|------|-------------------|
+| `CyclomaticComplexity` | `classReportLevel` (default: 40), `methodReportLevel` (default: 25) |
+| `ExcessiveParameterList` | `minimum` (default: 4) |
+| `ExcessiveClassLength` | `minimum` (default: 1000) |
+| `TooManyFields` | `maxfields` (default: 15) |
+| `NcssMethodCount` | `minimum` (default: 60) |
+| `DebugsShouldUseLoggingLevel` | `strictMode` (default: false) |
+| `ApexUnitTestClassShouldHaveAsserts` | (no properties — exclude if unwanted) |
+
+## Exclusion Patterns
+
+Three mechanisms for excluding files and rules:
+
+### 1. File exclusions in `code-analyzer.yml`
+
+Exclude entire directories or file patterns from all engines:
+
+```yaml
+# code-analyzer.yml
+ignores:
+  files:
+    - "**/node_modules/**"
+    - "**/fflib_*"
+    - "**/*Test*.cls"
+    - "**/generated/**"
+```
+
+Supports glob patterns: `*`, `**`, `?`, `[...]`, `{...}`
+
+### 2. Rule exclusions in PMD rulesets
+
+Exclude specific rules when including an entire category:
+
+```xml
+<rule ref="category/apex/bestpractices.xml">
+    <exclude name="ApexUnitTestClassShouldHaveAsserts" />
+    <exclude name="ApexAssertionsShouldIncludeMessage" />
+</rule>
+```
+
+### 3. Exclude patterns in PMD rulesets
+
+Exclude files at the PMD level (applies only to rules in that ruleset):
+
+```xml
+<ruleset name="MyRules" ...>
+    <exclude-pattern>.*/fflib_.*</exclude-pattern>
+    <exclude-pattern>.*/test/.*</exclude-pattern>
+
+    <rule name="..." ...>
+        ...
+    </rule>
+</ruleset>
+```
+
+### 4. Disabling individual rules via config
+
+Disable any rule without editing rulesets:
+
+```yaml
+# code-analyzer.yml
+rules:
+  pmd:
+    ApexUnitTestClassShouldHaveAsserts:
+      disabled: true
+    CyclomaticComplexity:
+      severity: "Low"    # Downgrade instead of disable
+```
+
+## Java-Based Custom Rules (Advanced)
+
+For rules that need logic beyond XPath (complex data flow, cross-file analysis), write Java PMD rules:
+
+1. **Create a Java class** extending `net.sourceforge.pmd.lang.apex.rule.AbstractApexRule`
+2. **Compile into a JAR** file
+3. **Reference in config:**
+
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    java_classpath_entries:
+      - "custom-rules/my-rules.jar"      # JAR with compiled rule classes
+      - "custom-rules/lib/"              # Folder of JARs (all JARs inside loaded)
+    custom_rulesets:
+      - "category/myteam/rules.xml"      # Ruleset inside the JAR (classpath resource)
+```
+
+The JAR's ruleset XML references the Java class:
+```xml
+<rule name="AvoidFutureAnnotation" language="apex"
+      message="Use Queueable instead of @Future"
+      class="com.myteam.pmd.rules.AvoidFutureRule">
+    <priority>3</priority>
+</rule>
+```
+
+**Requirements:**
+- Java 11+ for compilation
+- PMD 7.x API (use `net.sourceforge.pmd.lang.rule.xpath.XPathRule` for XPath, or extend `AbstractApexRule` for visitor-pattern Java rules)
+
+## Sharing Rules Across Projects
+
+### Approach 1: Relative paths with shared config
+
+If projects share a parent directory or monorepo:
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    custom_rulesets:
+      - "../shared-rules/team-standards.xml"    # Relative to config_root
+```
+
+`config_root` is the directory containing `code-analyzer.yml`. All relative paths resolve from there.
+
+### Approach 2: JAR-based distribution
+
+Package rules into a JAR and distribute via artifact repository:
+
+1. Build a JAR containing your ruleset XML at a classpath resource path (e.g., `category/myteam/standards.xml`)
+2. Place the JAR in each project's `custom-rules/` directory (or download in CI)
+3. Reference in config:
+
+```yaml
+engines:
+  pmd:
+    java_classpath_entries:
+      - "custom-rules/myteam-rules-1.0.jar"
+    custom_rulesets:
+      - "category/myteam/standards.xml"    # Resource inside the JAR
+```
+
+### Approach 3: Git submodule or symlink
+
+For simpler setups, share the ruleset XML via git submodule:
+```bash
+git submodule add https://github.com/myteam/pmd-rules.git custom-rules/shared
+```
+
+```yaml
+engines:
+  pmd:
+    custom_rulesets:
+      - "custom-rules/shared/team-standards.xml"
+```
+
+### CI/CD Integration
+
+All approaches work in CI because paths are relative to `config_root`. Example GitHub Actions step:
+
+```yaml
+- name: Run Code Analyzer
+  run: |
+    sf code-analyzer run --rule-selector "pmd:2,regex:2" --target force-app/
+```
+
+No absolute paths needed — the config file handles resolution.

package/skills/dx-code-analyzer-custom-rule-create/references/apex-ast-reference.md

@@ -0,0 +1,127 @@
+# Apex AST Node Reference
+
+PMD 7.x Apex AST node types and their attributes. Use `sf code-analyzer ast-dump --file <file.cls>` to see the actual tree for your code.
+
+## Node Hierarchy (Common Structure)
+
+```text
+ApexFile
+├── UserClass / UserInterface / UserTrigger / UserEnum
+│   ├── FormalComment (Javadoc)
+│   ├── ModifierNode (public, private, static, etc.)
+│   ├── Field (class-level variables)
+│   │   └── VariableDeclaration
+│   └── Method
+│       ├── ModifierNode
+│       ├── Parameter
+│       └── BlockStatement
+│           ├── VariableDeclarationStatements
+│           ├── ExpressionStatement
+│           │   └── MethodCallExpression
+│           ├── IfElseBlockStatement
+│           │   └── IfBlockStatement
+│           ├── ForEachStatement / ForLoopStatement / WhileLoopStatement
+│           ├── TryCatchFinallyBlockStatement
+│           │   ├── BlockStatement (try body)
+│           │   ├── CatchBlockStatement
+│           │   └── BlockStatement (finally body)
+│           ├── DmlInsertStatement / DmlUpdateStatement / DmlDeleteStatement
+│           ├── ReturnStatement
+│           └── ThrowStatement
+```
+
+## ModifierNode Attributes
+
+Every class, method, field, and parameter has a `ModifierNode` with these boolean attributes:
+
+| Attribute | Meaning |
+|-----------|---------|
+| `Public` | public access |
+| `Private` | private access |
+| `Protected` | protected access |
+| `Global` | global access |
+| `Static` | static member |
+| `Final` | final/const |
+| `Abstract` | abstract method/class |
+| `Virtual` | virtual method/class |
+| `Override` | overrides parent method |
+| `Test` | @IsTest annotated |
+| `TestOrTestSetup` | @IsTest or @TestSetup |
+| `WebService` | webservice method |
+| `WithSharing` | with sharing class |
+| `WithoutSharing` | without sharing class |
+| `InheritedSharing` | inherited sharing class |
+| `Transient` | transient field |
+| `Modifiers` | Bitmask integer of all modifiers |
+
+⚠️ **PMD 7 Boolean Attribute Comparison:**
+
+In PMD 7, these boolean attributes are **always present** on the node — they are never absent. This means:
+- ✅ `@WithSharing = false()` — correct (XPath boolean function)
+- ✅ `@WithSharing = true()` — correct
+- ❌ `@WithSharing = 'false'` — WRONG (string comparison, won't match)
+- ❌ `not(@WithSharing)` — WRONG (attribute always exists, so this is always false)
+- ❌ `@WithSharing` (as existence check) — WRONG (always true, attribute always present)
+
+Use the XPath `true()`/`false()` functions for boolean comparisons:
+```xpath
+<!-- Classes without sharing declaration -->
+//UserClass[ModifierNode[@WithSharing = false() and @WithoutSharing = false() and @InheritedSharing = false()]]
+
+<!-- Abstract classes -->
+//UserClass[ModifierNode[@Abstract = true()]]
+```
+
+## MethodCallExpression Attributes
+
+| Attribute | Example | Notes |
+|-----------|---------|-------|
+| `FullMethodName` | `'System.debug'`, `'Database.query'` | Most reliable for matching |
+| `MethodName` | `'debug'`, `'query'` | Just the method part |
+| `InputParametersSize` | `'1'`, `'0'` | Number of arguments |
+
+## LiteralExpression Attributes
+
+| Attribute | Values | Notes |
+|-----------|--------|-------|
+| `LiteralType` | `STRING`, `INTEGER`, `DECIMAL`, `DOUBLE`, `LONG`, `BOOLEAN` | Type of literal |
+| `Image` | The literal value | For strings, excludes quotes |
+| `String` | `'true'` / `'false'` | Boolean shorthand |
+| `Null` | `'true'` / `'false'` | Is it a null literal |
+
+## SoqlExpression Attributes
+
+| Attribute | Example | Notes |
+|-----------|---------|-------|
+| `Query` | `'SELECT Id FROM Account WHERE Name = :name'` | Original SOQL as written |
+| `CanonicalQuery` | `'SELECT Id FROM Account WHERE Name = :tmpVar1'` | Normalized (bind vars replaced) |
+
+## Annotation Node
+
+```xml
+<Annotation Image="IsTest">
+  <AnnotationParameter Name="testFor" Value="'ApexClass:MyService'" />
+</Annotation>
+```
+
+Use: `//Annotation[@Image='IsTest']` to find test annotations.
+
+## DML Nodes
+
+| Statement | Node | Notes |
+|-----------|------|-------|
+| `insert x;` | `DmlInsertStatement` | |
+| `update x;` | `DmlUpdateStatement` | |
+| `delete x;` | `DmlDeleteStatement` | |
+| `upsert x;` | `DmlUpsertStatement` | |
+| `undelete x;` | `DmlUndeleteStatement` | |
+| `Database.insert(x)` | `MethodCallExpression[@FullMethodName='Database.insert']` | Method-form DML |
+
+## Tips for Reading AST Dumps
+
+1. **`Image` attribute** = the actual source name (variable name, class name, method name)
+2. **`DefiningType` attribute** = which class this node belongs to (present on every node)
+3. **`RealLoc='true'`** = this node has a real source position (not compiler-generated)
+4. **`RealLoc='false'`** = compiler-generated node (e.g., implicit modifiers, empty references)
+5. **`EmptyReferenceExpression`** = placeholder for unqualified variable access (ignore these)
+6. **`Type` attribute on VariableDeclaration** = the declared type (e.g., `'Account'`, `'List<Contact>'`)