@salesforce/afv-skills 1.27.0 → 1.29.0

package/skills/dx-code-analyzer-custom-rule-create/references/eslint-rules-discovery.md

@@ -0,0 +1,188 @@
+# ESLint Rules Discovery & Configuration
+
+**READ THIS FIRST** for ANY ESLint request. 90% of ESLint rules already exist — this guide shows you how to find and configure them instead of creating custom plugins.
+
+---
+
+## Three Tiers of ESLint Rules
+
+| Tier | What It Is | When to Use | Effort | Coverage |
+|---|---|---|---|---|
+| **Tier 1: Built-In Rules** | 200+ core ESLint rules | First choice — check here FIRST | LOW (enable in config) | 70% of requests |
+| **Tier 2: Configurable Rules** | no-restricted-syntax, no-restricted-globals, no-restricted-properties | When no built-in rule exists but pattern is generic | MEDIUM (AST selector) | 20% of requests |
+| **Tier 3: Custom Plugins** | Write your own ESLint plugin | LAST RESORT — domain-specific multi-node patterns only | HIGH (Node code, testing) | 10% of requests |
+
+**Always start at Tier 1 and work down.**
+
+---
+
+## Tier 1: Discover Built-In Rules
+
+### Discovery Workflow (MANDATORY)
+
+Before creating ANY custom ESLint rule:
+
+1. **Run:** `sf code-analyzer rules --rule-selector eslint`
+2. **Search output** for keywords from the user's request:
+   - User says "ban console.log" → search for "console"
+   - User says "enforce ===" → search for "equal" or "strict"
+   - User says "no unused variables" → search for "unused"
+3. **Check naming patterns:**
+   - `no-*` — Disallow something (no-console, no-debugger, no-eval)
+   - `prefer-*` — Prefer one style (prefer-const, prefer-arrow-callback)
+   - `require-*` — Require something (require-await, require-yield)
+   - `@lwc/lwc/*` — LWC-specific rules (no-inner-html, no-document-query)
+4. **If found:** Configure it (see "Configuration Workflow" below). **STOP — do NOT create a custom plugin.**
+5. **If NOT found:** Proceed to Tier 2.
+
+### Common Built-In Rules by Category
+
+#### Code Quality
+| User Request | Rule Name | Config Example |
+|---|---|---|
+| "No unused variables" | `no-unused-vars` | `"no-unused-vars": "error"` |
+| "No unused imports" | `no-unused-vars` | Same rule covers imports |
+| "Require await in async functions" | `require-await` | `"require-await": "error"` |
+| "No empty blocks" | `no-empty` | `"no-empty": "error"` |
+| "No unreachable code" | `no-unreachable` | `"no-unreachable": "error"` |
+
+#### Security
+| User Request | Rule Name | Config Example |
+|---|---|---|
+| "Ban eval()" | `no-eval` | `"no-eval": "error"` |
+| "Ban debugger" | `no-debugger` | `"no-debugger": "error"` |
+| "No implied eval" | `no-implied-eval` | `"no-implied-eval": "error"` |
+| "Ban alert()" | `no-alert` | `"no-alert": "error"` |
+
+#### Best Practices
+| User Request | Rule Name | Config Example |
+|---|---|---|
+| "Enforce ===" | `eqeqeq` | `"eqeqeq": ["error", "always"]` |
+| "Prefer const" | `prefer-const` | `"prefer-const": "error"` |
+| "No var" | `no-var` | `"no-var": "error"` |
+| "Prefer arrow functions" | `prefer-arrow-callback` | `"prefer-arrow-callback": "error"` |
+| "Require default in switch" | `default-case` | `"default-case": "error"` |
+
+#### Logging/Debugging
+| User Request | Rule Name | Config Example |
+|---|---|---|
+| "Ban console.log" | `no-console` | `"no-console": "error"` |
+| "Ban console.* except error" | `no-console` | `"no-console": ["error", { "allow": ["error", "warn"] }]` |
+
+### LWC Plugin Rules (Check if Available)
+
+If Code Analyzer has `@lwc/eslint-plugin-lwc` enabled:
+
+| User Request | Rule Name | Notes |
+|---|---|---|
+| "Ban innerHTML" | `@lwc/lwc/no-inner-html` | XSS prevention |
+| "No document.querySelector" | `@lwc/lwc/no-document-query` | Use template queries |
+| "Validate @api usage" | `@lwc/lwc/no-api-reassignments` | Prevents reassigning @api properties |
+| "Validate @wire syntax" | `@lwc/lwc/valid-wire` | Built-in |
+| "No async in getters" | `@lwc/lwc/no-async-operation` | Lifecycle hook validation |
+
+**Check availability:**
+```bash
+sf code-analyzer rules --rule-selector eslint | grep -i "@lwc"
+```
+
+### External Documentation
+
+- **All ESLint built-in rules:** https://eslint.org/docs/latest/rules/
+- **LWC ESLint plugin:** https://github.com/salesforce/eslint-plugin-lwc
+- **Salesforce Lightning plugin:** https://github.com/forcedotcom/eslint-plugin-lightning
+
+---
+
+## Configuration Workflow (Tier 1)
+
+When a built-in rule exists:
+
+1. **Create `eslint.config.js`** if it doesn't exist:
+   ```javascript
+   module.exports = [
+     {
+       files: ["**/lwc/**/*.js"],  // or ["**/*.js"] for all JS files
+       rules: {
+         // Rules go here
+       }
+     }
+   ];
+   ```
+
+2. **Add the rule** with desired severity:
+   ```javascript
+   rules: {
+     "no-console": "error",              // Ban completely
+     "eqeqeq": ["error", "always"],      // With options
+     "no-unused-vars": ["warn"]          // Warning instead of error
+   }
+   ```
+
+3. **Update `code-analyzer.yml`** (AFTER file exists):
+   ```yaml
+   engines:
+     eslint:
+       eslint_config_file: "eslint.config.js"
+   ```
+
+4. **Validate:**
+   ```bash
+   sf code-analyzer rules --rule-selector eslint:no-console
+   ```
+   If the rule does NOT appear in the output, the config is wrong. Do NOT proceed to testing.
+
+5. **Test positive:**
+   ```bash
+   sf code-analyzer run --rule-selector eslint:no-console --target lwc/
+   ```
+
+6. **Test negative:** Run against clean code, confirm 0 violations.
+
+---
+
+## Tier 2 and Tier 3: Configurable Rules and Custom Plugins
+
+For detailed information on these tiers:
+
+| Tier | File | When to Use |
+|------|------|-------------|
+| **Tier 2: Configurable Rules** | [eslint-tier2-configurable.md](eslint-tier2-configurable.md) | no-restricted-globals, no-restricted-syntax, no-restricted-properties — ban specific patterns without writing plugins |
+| **Tier 3: Custom Plugins** | [eslint-tier3-custom-plugins.md](eslint-tier3-custom-plugins.md) | Complete examples for all tiers + when to create custom plugins (LAST RESORT) |
+
+---
+
+## Decision Tree
+
+```text
+User asks for ESLint rule
+    ↓
+Run: sf code-analyzer rules --rule-selector eslint
+    ↓
+Search output for keywords
+    ↓
+    ├─ Built-in rule found? → Configure it (Tier 1) → DONE ✅
+    │
+    ├─ Pattern is "ban function X"? → Use no-restricted-globals (Tier 2) → DONE ✅
+    │
+    ├─ Pattern is "ban syntax Y"? → Use no-restricted-syntax (Tier 2) → DONE ✅
+    │
+    └─ Complex multi-node pattern? → Create custom plugin (Tier 3) → See eslint-custom-plugins.md
+```
+
+---
+
+## Key Rules
+
+1. **ALWAYS run discovery FIRST** — 90% of requests are Tier 1 or Tier 2
+2. **NEVER create a custom plugin without checking built-in rules** — this is a skill failure
+3. **VALIDATE after configuration** — `sf code-analyzer rules --rule-selector eslint:<name>` must show the rule
+4. **TEST both positive and negative samples** — confirm violations are caught AND clean code passes
+
+---
+
+## When to Read Other References
+
+- **All ESLint requests start here** (discovery)
+- **If Tier 3 custom plugin needed:** Read `references/eslint-custom-plugins.md`
+- **If troubleshooting config issues:** Read `references/troubleshooting.md` (ESLint section)

package/skills/dx-code-analyzer-custom-rule-create/references/eslint-tier2-configurable.md

@@ -0,0 +1,114 @@
+# ESLint Tier 2: Configurable Rules
+
+[← Back to ESLint Rules Discovery](eslint-rules-discovery.md)
+
+## Tier 2: Configurable Rules
+
+When no built-in rule exists but the pattern is generic (ban a function, ban a property, ban a syntax construct):
+
+### Option A: `no-restricted-globals`
+
+Ban specific global functions or variables.
+
+**Example: Ban setTimeout/setInterval**
+```javascript
+// eslint.config.js
+module.exports = [
+  {
+    files: ["**/lwc/**/*.js"],
+    rules: {
+      "no-restricted-globals": ["error",
+        {
+          name: "setTimeout",
+          message: "Use LWC lifecycle hooks instead of setTimeout"
+        },
+        {
+          name: "setInterval",
+          message: "Use LWC lifecycle hooks instead of setInterval"
+        }
+      ]
+    }
+  }
+];
+```
+
+**Example: Ban window.localStorage**
+```javascript
+rules: {
+  "no-restricted-globals": ["error",
+    {
+      name: "localStorage",
+      message: "Use Salesforce state management instead of localStorage"
+    }
+  ]
+}
+```
+
+### Option B: `no-restricted-syntax`
+
+Ban specific AST patterns using ESLint selectors.
+
+**Example: Ban eval() calls**
+```javascript
+rules: {
+  "no-restricted-syntax": ["error",
+    {
+      selector: "CallExpression[callee.name='eval']",
+      message: "eval() is forbidden for security reasons"
+    }
+  ]
+}
+```
+
+**Example: Ban innerHTML property access**
+```javascript
+rules: {
+  "no-restricted-syntax": ["error",
+    {
+      selector: "MemberExpression[property.name='innerHTML']",
+      message: "innerHTML is forbidden - use textContent or render() for XSS prevention"
+    }
+  ]
+}
+```
+
+**Example: Ban for-in loops**
+```javascript
+rules: {
+  "no-restricted-syntax": ["error",
+    {
+      selector: "ForInStatement",
+      message: "for-in loops are forbidden - use for-of or Object.keys()"
+    }
+  ]
+}
+```
+
+#### ESLint Selector Syntax Cheat Sheet
+
+| Pattern | Selector | Example |
+|---|---|---|
+| Function call | `CallExpression[callee.name='functionName']` | `eval()`, `alert()` |
+| Property access | `MemberExpression[property.name='propName']` | `obj.innerHTML` |
+| Statement type | `ForInStatement`, `WithStatement` | for-in, with statements |
+| Operator | `BinaryExpression[operator='==']` | `==` instead of `===` |
+| Literal value | `Literal[value='string']` | Specific string literals |
+
+**Full selector docs:** https://eslint.org/docs/latest/extend/selectors
+
+### Option C: `no-restricted-properties`
+
+Ban specific object properties.
+
+**Example: Ban Object.prototype methods**
+```javascript
+rules: {
+  "no-restricted-properties": ["error",
+    {
+      object: "Object",
+      property: "setPrototypeOf",
+      message: "setPrototypeOf is forbidden for performance reasons"
+    }
+  ]
+}
+```

package/skills/dx-code-analyzer-custom-rule-create/references/eslint-tier3-custom-plugins.md

@@ -0,0 +1,113 @@
+# ESLint Tier 3: Custom Plugins
+
+[← Back to ESLint Rules Discovery](eslint-rules-discovery.md)
+
+## Tier 3: Custom Plugins (LAST RESORT)
+
+Only create a custom ESLint plugin when:
+- ❌ No built-in rule exists (checked Tier 1)
+- ❌ No configurable rule can express the pattern (checked Tier 2 — see [eslint-tier2-configurable.md](eslint-tier2-configurable.md))
+- ✅ The pattern requires checking multiple AST nodes with complex logic
+- ✅ The pattern is domain-specific to your codebase
+
+**Examples that justify custom plugins:**
+- "Flag LWC components with @api properties but no input validation in connectedCallback"
+- "Detect imperative Apex calls without error handling (import + .then() without .catch())"
+- "Enforce naming conventions on specific decorator patterns"
+
+**See:** [eslint-custom-plugins.md](eslint-custom-plugins.md) for the plugin creation guide.
+
+---
+
+## Tier-by-Tier Worked Examples
+
+Tier 2 worked examples (banning globals, restricting syntax, restricting properties) live in [eslint-tier2-configurable.md](eslint-tier2-configurable.md). The examples below cover Tier 1 (built-in rules and the LWC plugin) so the discovery → configure → validate flow is documented end-to-end.
+
+### Example 1: "Ban console.log" (Tier 1 — built-in)
+
+**User Request:** "Create a rule to ban console.log in LWC"
+
+**Discovery:**
+```bash
+$ sf code-analyzer rules --rule-selector eslint | grep -i console
+eslint:no-console  disallow the use of console
+```
+
+**Result:** Built-in rule exists. ✅
+
+**Configuration:**
+```javascript
+// eslint.config.js
+module.exports = [
+  {
+    files: ["**/lwc/**/*.js"],
+    rules: {
+      "no-console": "error"
+    }
+  }
+];
+```
+
+**Validation:**
+```bash
+sf code-analyzer rules --rule-selector eslint:no-console
+# Should show: eslint:no-console | error | ...
+```
+
+**Test:**
+```bash
+sf code-analyzer run --rule-selector eslint:no-console --target lwc/
+```
+
+---
+
+### Example 2: "Ban innerHTML" (Tier 1 — LWC plugin)
+
+**User Request:** "Ban innerHTML in LWC for XSS prevention"
+
+**Discovery:**
+```bash
+$ sf code-analyzer rules --rule-selector eslint | grep -i inner
+@lwc/lwc/no-inner-html  disallow use of innerHTML
+```
+
+**Result:** LWC plugin rule exists. ✅
+
+**Configuration:**
+```javascript
+// eslint.config.js
+module.exports = [
+  {
+    files: ["**/lwc/**/*.js"],
+    rules: {
+      "@lwc/lwc/no-inner-html": "error"
+    }
+  }
+];
+```
+
+**Validation:**
+```bash
+sf code-analyzer rules --rule-selector eslint:@lwc/lwc/no-inner-html
+```
+
+---
+
+### Example 3: "Enforce === over ==" (Tier 1 — built-in)
+
+**User Request:** "Enforce strict equality checks"
+
+**Discovery:**
+```bash
+$ sf code-analyzer rules --rule-selector eslint | grep -i equal
+eslint:eqeqeq  require the use of === and !==
+```
+
+**Result:** Built-in rule `eqeqeq` exists. ✅
+
+**Configuration:**
+```javascript
+rules: {
+  "eqeqeq": ["error", "always"]
+}
+```

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

@@ -0,0 +1,285 @@
+# Metadata XML Rules (PMD with language="xml")
+
+Write PMD XPath rules that target Salesforce metadata XML files (`.field-meta.xml`, `.permissionset-meta.xml`, `.profile-meta.xml`, `.flow-meta.xml`, etc.) to enforce org governance.
+
+## How It Works
+
+PMD's `language="xml"` mode parses any XML file into a DOM-like AST. You write XPath expressions against element/attribute names in the XML structure — same mechanism as Apex rules, but the AST is the XML DOM.
+
+## Critical: PMD 7 XML XPath Rules
+
+### Rule 1: Namespace — use `local-name()`
+
+Salesforce metadata files declare a namespace:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>My_Field__c</fullName>
+    ...
+</CustomField>
+```
+
+This namespace **breaks standard XPath** because `//fullName` won't match — PMD sees it as `//metadata:fullName` internally.
+
+**Solution:** Use `local-name()` to match element names regardless of namespace:
+
+```xpath
+//*[local-name()='CustomField']/*[local-name()='fullName']
+```
+
+**This applies to ALL Salesforce metadata XPath rules.** Never use bare element names without `local-name()`.
+
+### Rule 2: Text content — use `@Text` (NOT `text()`)
+
+⚠️ **PMD 7's XML language does NOT support `text()` for value comparison.** The `text()` function returns 0 matches regardless of content. This is a PMD 7 change from PMD 6.
+
+**Use the `@Text` attribute instead:**
+
+```xpath
+// ❌ WRONG — does not work in PMD 7:
+//*[local-name()='name'][text()='ModifyAllData']
+
+// ✅ CORRECT — use @Text attribute:
+//*[@Text='ModifyAllData']
+```
+
+### Rule 3: Navigation — text nodes require `../..`
+
+In PMD 7 XML, `@Text` matches TEXT NODES (child nodes of elements), not the elements themselves. To navigate from a matched text node to its parent element hierarchy:
+
+```xpath
+// @Text='ModifyAllData' matches the TEXT NODE inside <name>ModifyAllData</name>
+// To get the <name> element: go up one level
+//*[@Text='ModifyAllData']/..
+
+// To get the <userPermissions> parent: go up two levels
+//*[@Text='ModifyAllData']/../..
+
+// To check a sibling's text value from the parent:
+//*[@Text='ModifyAllData']/../..[.//*[@Text='true']]
+```
+
+### Complete Pattern for Checking Parent + Sibling Text Values
+
+The canonical PMD 7 pattern for "find element X that contains child with text A AND child with text B":
+
+```xpath
+//*[@Text='TargetValue']/../..
+  [local-name()='ParentElement']
+  [.//*[@Text='ConditionValue']]
+```
+
+Example — find `userPermissions` where name=ModifyAllData AND enabled=true:
+```xpath
+//*[@Text='ModifyAllData']/../..
+  [local-name()='userPermissions']
+  [.//*[@Text='true']]
+```
+
+## AST Dump for Metadata Files
+
+Dump the AST to see the exact XML structure:
+```bash
+sf code-analyzer ast-dump --file force-app/main/default/objects/Account/fields/MyField__c.field-meta.xml --language xml
+```
+
+The output shows the DOM tree — element nodes, text nodes, and attributes. Use this to confirm element names before writing XPath.
+
+## Ruleset XML Template for Metadata Rules
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MetadataGovernanceRules"
+    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>Custom rules for Salesforce metadata governance</description>
+
+    <rule name="MyMetadataRule"
+          language="xml"
+          message="Violation message here"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+
+        <description>What this rule enforces</description>
+        <priority>3</priority>
+
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//*[local-name()='YourElement'][your-condition]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+</ruleset>
+```
+
+## Configuration
+
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    custom_rulesets:
+      - "custom-rules/metadata-governance.xml"
+    file_extensions:
+      xml: [".xml"]
+```
+
+⚠️ **IMPORTANT:** PMD's XML language only scans `.xml` files by default. You MUST add `file_extensions: { xml: [".xml"] }` under `engines.pmd` in your config. This single entry covers ALL Salesforce metadata compound extensions (`.permissionset-meta.xml`, `.field-meta.xml`, `.flow-meta.xml`, etc.) because the system reads the final `.xml` portion of the filename.
+
+⚠️ **Do NOT add compound extensions** like `.permissionset-meta.xml` to the list — Code Analyzer's validator only accepts single-segment extensions matching `/^[.][a-zA-Z0-9]+$/` and will reject them with a config error.
+
+## Common Metadata File Structures
+
+### Custom Field (`.field-meta.xml`)
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Revenue__c</fullName>
+    <label>Revenue</label>
+    <type>Currency</type>
+    <required>false</required>
+    <description>Annual revenue</description>
+</CustomField>
+```
+
+### Permission Set (`.permissionset-meta.xml`)
+```xml
+<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Admin Access</label>
+    <userPermissions>
+        <enabled>true</enabled>
+        <name>ModifyAllData</name>
+    </userPermissions>
+    <fieldPermissions>
+        <editable>true</editable>
+        <field>Account.Revenue__c</field>
+        <readable>true</readable>
+    </fieldPermissions>
+</PermissionSet>
+```
+
+### Profile (`.profile-meta.xml`)
+```xml
+<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
+    <userPermissions>
+        <enabled>true</enabled>
+        <name>ViewSetup</name>
+    </userPermissions>
+    <fieldPermissions>
+        <editable>true</editable>
+        <field>Account.SSN__c</field>
+    </fieldPermissions>
+</Profile>
+```
+
+### Flow (`.flow-meta.xml`)
+```xml
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>58.0</apiVersion>
+    <label>My Flow</label>
+    <processType>AutoLaunchedFlow</processType>
+    <status>Active</status>
+    <processMetadataValues>
+        <name>CanvasMode</name>
+        <value><stringValue>AUTO_LAYOUT_CANVAS</stringValue></value>
+    </processMetadataValues>
+    <recordCreates>
+        <name>Create_Account</name>
+        <object>Account</object>
+    </recordCreates>
+    <loops>
+        <name>Loop_Records</name>
+        <collectionReference>Get_Records</collectionReference>
+    </loops>
+</Flow>
+```
+
+## XPath Patterns for Metadata (PMD 7)
+
+All patterns below use `@Text` for text content matching (NOT `text()` which is broken in PMD 7).
+
+### Require description on Custom Fields
+
+**Missing description entirely:**
+```xpath
+//*[local-name()='CustomField'][not(*[local-name()='description'])]
+```
+
+**Missing OR empty description (catches `<description></description>` too):**
+```xpath
+//*[local-name()='CustomField'][not(*[local-name()='description']) or *[local-name()='description'][not(.//*[@Text])]]
+```
+Note: `.//*[@Text]` checks for any descendant text node with content. Do NOT put `[not(@Text)]` directly on the `<description>` element — `@Text` only exists on child text nodes, not on elements themselves. Putting it on the element always evaluates to true (false positive).
+
+### Flag ModifyAllData / ViewAllData in Permission Sets
+```xpath
+//*[@Text='ModifyAllData' or @Text='ViewAllData']/../..
+  [local-name()='userPermissions']
+  [.//*[@Text='true']]
+```
+
+### Enforce minimum API version (60.0+)
+```xpath
+//*[local-name()='apiVersion']/*[number(@Text) < 60]
+```
+Note: `/*` navigates to the **child text node** where `@Text` lives. Do NOT put `@Text` directly on the element — it won't match because `@Text` only exists on text nodes (children), not on elements themselves.
+
+### Flag field permissions in Profiles (should be in Perm Sets)
+```xpath
+//*[local-name()='Profile']/*[local-name()='fieldPermissions']
+```
+(No text matching needed — structural only.)
+
+### Flag dangerous permissions (ModifyAllData only, enabled)
+```xpath
+//*[@Text='ModifyAllData']/../..
+  [local-name()='userPermissions']
+  [.//*[@Text='true']]
+```
+
+### Flag DML (recordCreates/recordUpdates/recordDeletes) inside Flow loops
+```xpath
+//*[local-name()='loops'][
+  following-sibling::*[local-name()='recordCreates' or local-name()='recordUpdates' or local-name()='recordDeletes']
+]
+```
+(No text matching needed — structural only.)
+
+## Targeting Specific File Types
+
+PMD only scans `.xml` files by default. You must add `.xml` to the config. This single extension covers ALL Salesforce compound metadata extensions (`.permissionset-meta.xml`, `.field-meta.xml`, etc.) because `path.extname()` returns `.xml` from these filenames.
+
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    file_extensions:
+      xml: [".xml"]
+```
+
+⚠️ Do NOT add compound extensions — the validator rejects anything that doesn't match `/^[.][a-zA-Z0-9]+$/`.
+
+Additionally, scope your XPath to the correct root element to avoid false positives across file types:
+
+```xpath
+//*[@Text='ModifyAllData']/../..[local-name()='userPermissions']
+  [ancestor::*[local-name()='PermissionSet']]
+```
+
+This ensures the rule only fires on permission set files, not on profile or other metadata files.
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| XPath matches nothing | Three causes: (1) Forgot `local-name()`. (2) Used `text()` — broken in PMD 7, use `@Text`. (3) File extension not in `file_extensions.xml` config. |
+| Rule fires on wrong metadata type | Add root element scope: `[ancestor::*[local-name()='PermissionSet']]` |
+| Can't match text content | **Use `@Text` attribute** (NOT `text()`). Example: `//*[@Text='ModifyAllData']` |
+| `@Text` matches but parent navigation fails | `@Text` matches TEXT NODES. Go up with `../..`: text→element→parent. |
+| Number comparison fails | `@Text` lives on the **child text node**, NOT on the element. Use: `//*[local-name()='element']/*[number(@Text) < N]` — the `/*` navigates to the text node. Do NOT put `[@Text]` predicate directly on the element (returns 0 matches). |
+| Too many violations on large orgs | Scope with `file_extensions` in PMD config or add `ignores.files` patterns |
+| Rule doesn't fire on metadata files | Add `file_extensions: { xml: [".xml"] }` under `engines.pmd` — this covers all compound extensions. Do NOT add `.permissionset-meta.xml` etc. (validator rejects them). |
+| ast-dump fails with "XmlEncoding" error | Known issue. Read the raw XML file — the file content IS the DOM structure |
+| ast-dump shows different structure | XML AST is the literal DOM — what you see in the file is what you get |