@salesforce/afv-skills 1.27.0 → 1.29.0

package/skills/dx-code-analyzer-custom-rule-create/examples/metadata-xml-example-flows.md

@@ -0,0 +1,105 @@
+# Metadata XML Examples: Flows
+
+[← Back to Metadata XML Examples Index](metadata-xml-examples.md)
+
+## Example 5: Require Flow Auto-Layout
+
+**Problem:** Flows should use Auto-Layout canvas for consistency and maintainability.
+
+**Target file:** `*.flow-meta.xml`
+
+**Sample violating metadata:**
+```xml
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>58.0</apiVersion>
+    <label>My Flow</label>
+    <processMetadataValues>
+        <name>CanvasMode</name>
+        <value><stringValue>FREE_FORM_CANVAS</stringValue></value>
+    </processMetadataValues>
+</Flow>
+```
+
+**XPath (PMD 7 — flags FREE_FORM_CANVAS):**
+```xpath
+//*[@Text='FREE_FORM_CANVAS']/../..
+  [local-name()='value']
+  [ancestor::*[local-name()='processMetadataValues'][.//*[@Text='CanvasMode']]]
+```
+
+**How it works:** Finds text nodes with "FREE_FORM_CANVAS", navigates up to the `<value>` element, then confirms it's inside a `processMetadataValues` block that also contains "CanvasMode".
+
+**PMD ruleset:**
+```xml
+<rule name="FlowMustUseAutoLayout"
+      language="xml"
+      message="Flows must use AUTO_LAYOUT_CANVAS mode"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <description>Enforces auto-layout canvas mode on all flows for consistency</description>
+    <priority>3</priority>
+    <properties>
+        <property name="xpath">
+            <value><![CDATA[
+//*[@Text='FREE_FORM_CANVAS']/../..
+  [local-name()='value']
+  [ancestor::*[local-name()='processMetadataValues'][.//*[@Text='CanvasMode']]]
+]]></value>
+        </property>
+    </properties>
+</rule>
+```
+
+---
+
+## Example 6: Flow Missing Fault Handler
+
+**Problem:** Flow actions without fault connectors can fail silently.
+
+**Target file:** `*.flow-meta.xml`
+
+**Sample violating metadata:**
+```xml
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <recordCreates>
+        <name>Create_Account</name>
+        <object>Account</object>
+        <connector>
+            <targetReference>Next_Step</targetReference>
+        </connector>
+        <!-- No <faultConnector> element! -->
+    </recordCreates>
+</Flow>
+```
+
+**XPath:**
+```xpath
+//*[local-name()='Flow']/*[
+  local-name()='recordCreates' or local-name()='recordUpdates'
+  or local-name()='recordDeletes' or local-name()='recordLookups'
+][
+  not(*[local-name()='faultConnector'])
+]
+```
+
+**PMD ruleset:**
+```xml
+<rule name="FlowActionRequiresFaultHandler"
+      language="xml"
+      message="Flow DML/query actions must have a fault connector for error handling"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <description>Ensures all data operations in flows have fault paths</description>
+    <priority>2</priority>
+    <properties>
+        <property name="xpath">
+            <value><![CDATA[
+//*[local-name()='Flow']/*[
+  local-name()='recordCreates' or local-name()='recordUpdates'
+  or local-name()='recordDeletes' or local-name()='recordLookups'
+][
+  not(*[local-name()='faultConnector'])
+]
+]]></value>
+        </property>
+    </properties>
+</rule>
+```

package/skills/dx-code-analyzer-custom-rule-create/examples/metadata-xml-example-permissions.md

@@ -0,0 +1,95 @@
+# Metadata XML Examples: Permissions
+
+[← Back to Metadata XML Examples Index](metadata-xml-examples.md)
+
+## Example 1: Flag ModifyAllData / ViewAllData Permissions
+
+**Problem:** Permission sets granting ModifyAllData or ViewAllData are a security risk.
+
+**Target file:** `*.permissionset-meta.xml`
+
+**Sample violating metadata:**
+```xml
+<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Power User</label>
+    <userPermissions>
+        <enabled>true</enabled>
+        <name>ModifyAllData</name>
+    </userPermissions>
+</PermissionSet>
+```
+
+**XPath (PMD 7):**
+```xpath
+//*[@Text='ModifyAllData' or @Text='ViewAllData']/../..
+  [local-name()='userPermissions']
+  [.//*[@Text='true']]
+```
+
+**How it works:**
+1. `//*[@Text='ModifyAllData' or @Text='ViewAllData']` — find text node with dangerous permission name
+2. `/../..` — navigate up: text node → `<name>` element → `<userPermissions>` parent
+3. `[local-name()='userPermissions']` — confirm we're at the right element
+4. `[.//*[@Text='true']]` — check that a descendant text node contains "true" (the `<enabled>` value)
+
+**PMD ruleset:**
+```xml
+<rule name="NoDangerousPermissions"
+      language="xml"
+      message="Permission set grants ModifyAllData or ViewAllData — use specific object permissions instead"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <description>Flags permission sets that grant ModifyAllData or ViewAllData</description>
+    <priority>1</priority>
+    <properties>
+        <property name="xpath">
+            <value><![CDATA[
+//*[@Text='ModifyAllData' or @Text='ViewAllData']/../..
+  [local-name()='userPermissions']
+  [.//*[@Text='true']]
+]]></value>
+        </property>
+    </properties>
+</rule>
+```
+
+---
+
+## Example 4: No Field Permissions in Profiles
+
+**Problem:** Field permissions should be managed via Permission Sets, not Profiles.
+
+**Target file:** `*.profile-meta.xml`
+
+**Sample violating metadata:**
+```xml
+<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fieldPermissions>
+        <editable>true</editable>
+        <field>Account.Revenue__c</field>
+        <readable>true</readable>
+    </fieldPermissions>
+</Profile>
+```
+
+**XPath:**
+```xpath
+//*[local-name()='Profile']/*[local-name()='fieldPermissions']
+```
+
+**PMD ruleset:**
+```xml
+<rule name="NoFieldPermissionsInProfile"
+      language="xml"
+      message="Field permissions should be in Permission Sets, not Profiles"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <description>Profiles should not contain field-level security — use Permission Sets</description>
+    <priority>2</priority>
+    <properties>
+        <property name="xpath">
+            <value><![CDATA[
+//*[local-name()='Profile']/*[local-name()='fieldPermissions']
+]]></value>
+        </property>
+    </properties>
+</rule>
+```

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

@@ -0,0 +1,84 @@
+# Metadata XML Rule Examples
+
+Real-world custom PMD rules targeting Salesforce metadata XML files for org governance.
+
+⚠️ **PMD 7 Note:** All examples use `@Text` for text content matching. The `text()` function does NOT work in PMD 7's XML language. See `references/metadata-xml-rules.md` for full details.
+
+## Example Index
+
+| # | Example | File |
+|---|---------|------|
+| 1 | Flag ModifyAllData / ViewAllData Permissions | [metadata-xml-example-permissions.md](metadata-xml-example-permissions.md) |
+| 2 | Require Description on Custom Fields | [metadata-xml-example-fields-api.md](metadata-xml-example-fields-api.md) |
+| 3 | Enforce Minimum API Version | [metadata-xml-example-fields-api.md](metadata-xml-example-fields-api.md) |
+| 4 | No Field Permissions in Profiles | [metadata-xml-example-permissions.md](metadata-xml-example-permissions.md) |
+| 5 | Require Flow Auto-Layout | [metadata-xml-example-flows.md](metadata-xml-example-flows.md) |
+| 6 | Flow Missing Fault Handler | [metadata-xml-example-flows.md](metadata-xml-example-flows.md) |
+
+---
+
+## How to Create These
+
+1. Run `sf code-analyzer ast-dump --file your-file.xml --language xml` to see the DOM structure. If ast-dump fails, read the raw XML file directly — the file content IS the AST.
+2. Write XPath using `local-name()` for element matching and `@Text` for text content (NOT `text()`)
+3. Navigate from text nodes to parent elements using `../..`
+4. Scope to the correct metadata type by checking the root element or using `ancestor::`
+5. Configure `file_extensions: { xml: [".xml"] }` in `code-analyzer.yml` (just `.xml` covers all compound metadata extensions)
+6. Add the rule to a ruleset XML file with `language="xml"`
+7. Reference the ruleset in `code-analyzer.yml` under `engines.pmd.custom_rulesets`
+8. Validate: `sf code-analyzer rules --rule-selector pmd:RuleName`
+9. Test positive + negative: run against both a violating and clean metadata file
+
+## Complete Multi-Rule Ruleset Example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MetadataGovernance"
+    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>Org governance rules for Salesforce metadata</description>
+
+    <rule name="NoDangerousPermissions" language="xml"
+          message="Permission set grants ModifyAllData or ViewAllData"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>1</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//*[@Text='ModifyAllData' or @Text='ViewAllData']/../..
+  [local-name()='userPermissions']
+  [.//*[@Text='true']]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+
+    <rule name="FieldRequiresDescription" language="xml"
+          message="Custom field must have a non-empty description"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>3</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//*[local-name()='CustomField'][not(*[local-name()='description']) or *[local-name()='description'][not(@Text)]]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+
+    <rule name="MinimumApiVersion" language="xml"
+          message="API version must be 60.0 or higher"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>3</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//*[local-name()='apiVersion']/*[number(@Text) < 60]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+</ruleset>
+```

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

@@ -0,0 +1,127 @@
+# Regex Rule Examples
+
+Real-world custom regex rules solving problems from the Code Analyzer community.
+
+## Example 1: Ban Hardcoded Salesforce IDs
+
+**Problem:** Developers hardcode record IDs that differ between orgs.
+(GitHub issue #738 — community request for detecting bad patterns)
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      NoHardcodedSalesforceIds:
+        regex: "/['\"](?<target>0[a-zA-Z0-9]{14}(?:[a-zA-Z0-9]{3})?)['\"]/g"
+        description: "Detects hardcoded 15 or 18 character Salesforce record IDs"
+        violation_message: "Replace hardcoded ID with Custom Label, Custom Metadata, or Custom Setting"
+        severity: 2
+        tags: ["Custom", "Security"]
+        file_extensions: [".cls", ".trigger"]
+```
+
+**Why this pattern:**
+- Salesforce IDs are exactly **15 or 18 characters** (never 16 or 17)
+- They always **start with `0`** (the key prefix)
+- `0[a-zA-Z0-9]{14}` matches 15-char IDs (0 + 14 more)
+- `(?:[a-zA-Z0-9]{3})?` optionally matches the 3-char case-safe suffix (making 18-char)
+- `(?<target>...)` narrows the violation highlight to just the ID, not the surrounding quotes
+- ⚠️ Do NOT use `{15,18}` — this also matches 16/17 char strings and false-positives on normal words like `'BusinessAccount'` or `'RecordTypeInfos'`
+
+**Note on `regex_ignore`:** This field works **per-line**, not per-file. Adding `/@isTest/` only skips lines that literally contain `@isTest` — it does NOT exclude entire test classes. To exclude test files entirely, use `ignores.files` in `code-analyzer.yml` with a glob like `**/*Test.cls`.
+
+---
+
+## Example 2: Flag TODO/FIXME Before Merge
+
+**Problem:** Developers leave TODOs that never get resolved.
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      NoUnresolvedTodos:
+        regex: "/(?:TODO|FIXME|HACK|XXX)\\b/gi"
+        description: "Flags unresolved TODO/FIXME comments"
+        violation_message: "Resolve this TODO/FIXME before merging to main"
+        severity: 4
+        tags: ["Custom", "BestPractices"]
+```
+
+---
+
+## Example 3: Enforce WITH USER_MODE on SOQL
+
+**Problem:** SOQL queries without FLS enforcement are a security risk.
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      RequireUserModeOnSoql:
+        regex: "/\\[\\s*SELECT(?![^\\]]*WITH\\s+(?:USER_MODE|SECURITY_ENFORCED))[^\\]]*\\]/gi"
+        description: "SOQL queries must use WITH USER_MODE or WITH SECURITY_ENFORCED"
+        violation_message: "Add WITH USER_MODE to this SOQL query for FLS enforcement"
+        severity: 2
+        tags: ["Custom", "Security"]
+        file_extensions: [".cls", ".trigger"]
+        regex_ignore: "/@isTest|@IsTest|@testSetup|@TestSetup/"
+```
+
+---
+
+## Example 4: Ban @SuppressWarnings and NOPMD
+
+**Problem:** Teams want to prevent suppression of violations.
+(GitHub issue #1972 — real user request)
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      ProhibitSuppressWarnings:
+        regex: "/@SuppressWarnings\\([^)]*\\)|\\/\\/\\s*NOPMD/gi"
+        description: "Prohibits suppression of code analysis warnings"
+        violation_message: "Fix the underlying issue instead of suppressing warnings"
+        severity: 2
+        tags: ["Custom", "BestPractices"]
+        file_extensions: [".cls", ".trigger"]
+```
+
+---
+
+## Example 5: Detect Old API Versions in Metadata
+
+**Problem:** Metadata files using API versions more than 2 years old.
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      NoOldApiVersions:
+        regex: "/<apiVersion>(4[0-9]|5[0-5])\\.0<\\/apiVersion>/g"
+        description: "Detects metadata files using API version 55.0 or below"
+        violation_message: "Update API version to 60.0 or higher"
+        severity: 3
+        tags: ["Custom", "BestPractices"]
+        file_extensions: [".xml"]
+```
+
+---
+
+## Example 6: Enforce Test Class Naming Convention
+
+**Problem:** Test classes should end with `_TEST` or `Test`.
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      TestClassNaming:
+        regex: "/@(?:isTest|IsTest)(?:\\([^)]*\\))?\\s*(?:public|private)\\s+class\\s+(?!.*(?:_TEST|Test)\\b)\\w+/g"
+        description: "Test classes must end with _TEST or Test suffix"
+        violation_message: "Rename this test class to end with _TEST or Test (e.g., MyServiceTest)"
+        severity: 3
+        tags: ["Custom", "CodeStyle"]
+        file_extensions: [".cls"]
+```

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`