@salesforce/afv-skills 1.28.0 → 1.29.0

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

@@ -0,0 +1,87 @@
+# Metadata XML Examples: Fields and API Version
+
+[← Back to Metadata XML Examples Index](metadata-xml-examples.md)
+
+## Example 2: Require Description on Custom Fields
+
+**Problem:** Custom fields without descriptions make orgs hard to maintain.
+
+**Target file:** `*.field-meta.xml`
+
+**Sample violating metadata:**
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Revenue__c</fullName>
+    <label>Revenue</label>
+    <type>Currency</type>
+    <!-- No <description> element! -->
+</CustomField>
+```
+
+**XPath (PMD 7):**
+```xpath
+//*[local-name()='CustomField'][not(*[local-name()='description']) or *[local-name()='description'][not(@Text)]]
+```
+
+**How it works:** Matches `CustomField` elements that either lack a `<description>` child entirely, or have one with no text content (`@Text` absent means empty).
+
+**PMD ruleset:**
+```xml
+<rule name="FieldRequiresDescription"
+      language="xml"
+      message="Custom field must have a non-empty description"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <description>Enforces that all custom fields have a description for documentation</description>
+    <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>
+```
+
+---
+
+## Example 3: Enforce Minimum API Version
+
+**Problem:** Metadata using API versions older than 60.0 should be updated.
+
+**Target file:** Any `*-meta.xml` with `<apiVersion>`
+
+**Sample violating metadata:**
+```xml
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>52.0</apiVersion>
+    <status>Active</status>
+</ApexClass>
+```
+
+**XPath (PMD 7):**
+```xpath
+//*[local-name()='apiVersion']/*[number(@Text) < 60]
+```
+
+**How it works:** Finds `<apiVersion>` elements, then navigates to their child text node with `/*`. The `@Text` attribute on the text node holds the value (e.g., "52.0"). `number(@Text)` converts it to a float, and flags if < 60.
+
+⚠️ **Key insight:** `@Text` lives on CHILD text nodes, not on elements. You must use `/*` to reach the text node — putting `[@Text]` directly on the element (after `local-name()='apiVersion'`) returns 0 matches.
+
+**PMD ruleset:**
+```xml
+<rule name="MinimumApiVersion"
+      language="xml"
+      message="API version must be 60.0 or higher — update this metadata"
+      class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+    <description>Enforces minimum API version of 60.0 across all metadata</description>
+    <priority>3</priority>
+    <properties>
+        <property name="xpath">
+            <value><![CDATA[
+//*[local-name()='apiVersion']/*[number(@Text) < 60]
+]]></value>
+        </property>
+    </properties>
+</rule>
+```

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"]
+```