@salesforce/afv-skills 1.28.0 → 1.29.0

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 |

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

@@ -0,0 +1,174 @@
+# Regex Rule Schema Reference
+
+Custom regex rules are defined inline in `code-analyzer.yml` under `engines.regex.custom_rules`.
+
+## Complete Schema
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      RuleName:                          # Must match: /^[A-Za-z@][A-Za-z_0-9@\-/]*$/
+        regex: "/pattern/flags"          # REQUIRED — JavaScript regex literal format
+        description: "What this checks"  # REQUIRED — Purpose of the rule
+        violation_message: "Fix this"    # Optional — Message shown on violation
+        severity: 3                      # Optional — 1=Critical, 2=High, 3=Moderate, 4=Low, 5=Info
+        tags:                            # Optional — Default: ['Recommended', 'Custom']
+          - "Custom"
+          - "Security"
+        file_extensions:                 # Optional — Default: all text files
+          - ".cls"
+          - ".trigger"
+        regex_ignore: "/exception/i"     # Optional — Matches excluded from violations
+```
+
+## Field Details
+
+### `regex` (Required)
+
+JavaScript regex literal format: `/pattern/flags`
+
+| Format | Example | Meaning |
+|--------|---------|---------|
+| `/pattern/g` | `/TODO/g` | Case-sensitive, global (find all matches) — **minimum required** |
+| `/pattern/gi` | `/todo/gi` | Global + case-insensitive |
+| `/pattern/gm` | `/^import/gm` | Global + multiline (^ matches each line start) |
+
+**Common pitfalls:**
+- **The `/g` (global) flag is REQUIRED.** Code Analyzer rejects regex patterns without at least one flag after the closing `/`. Always include `/g` (or `/gi`, `/gm`, etc.).
+- Backslashes must be escaped: `\d` → write as `/\\d/`
+- Dots match any character: use `/\\.cls/` not `/.cls/`
+- Regex is tested against file content line by line
+
+**Named capture groups** narrow the violation highlight to a specific portion of the match:
+```yaml
+# Without named group — entire match is highlighted:
+regex: "/System\\.debug\\([^)]*\\)/g"
+# Highlights: "System.debug('hello')" (entire expression)
+
+# With named group — only captured portion highlighted:
+regex: "/(?<target>System\\.debug)\\([^)]*\\)/g"
+# Highlights: "System.debug" (just the method name)
+```
+
+Use `(?<target>...)` when the regex needs surrounding context to match correctly, but the violation should point to a narrower location. Common patterns:
+
+```yaml
+# Highlight just the hardcoded ID, not the surrounding quotes
+regex: "/['\"](?<target>[0-9a-zA-Z]{15,18})['\"]/g"
+
+# Highlight the annotation, not the whole line
+regex: "/(?<target>@SuppressWarnings\\([^)]*\\))/g"
+
+# Highlight the method call within a larger expression
+regex: "/(?<target>Database\\.query)\\(/g"
+```
+
+### `description` (Required)
+
+Brief explanation of what the rule enforces. Used in rule listings and generated messages.
+
+### `violation_message` (Optional)
+
+Message shown when a violation is found. If omitted, auto-generated as:
+> "A match of the regular expression `<regex>` was found for rule '<RuleName>': <description>"
+
+Good violation messages tell the user HOW to fix, not just WHAT's wrong:
+- ❌ "Hardcoded ID found"
+- ✅ "Replace hardcoded Salesforce ID with a Custom Label or Custom Metadata reference"
+
+### `severity` (Optional, default: 3)
+
+| Value | Name | Meaning |
+|-------|------|---------|
+| 1 | Critical | Security vulnerability, must fix before deploy |
+| 2 | High | Significant quality issue, should fix |
+| 3 | Moderate | Recommended improvement |
+| 4 | Low | Minor style issue |
+| 5 | Info | Informational, no action required |
+
+Also accepts string names: `"Critical"`, `"High"`, `"Moderate"`, `"Low"`, `"Info"`
+
+### `tags` (Optional, default: ['Recommended', 'Custom'])
+
+Array of tag strings. Used for `--rule-selector` filtering. Common tags:
+- `Custom` — auto-applied to user-created rules
+- `Security` — security-related rules
+- `BestPractices` — coding standards
+- `Performance` — performance anti-patterns
+- `CodeStyle` — formatting/naming rules
+
+### `file_extensions` (Optional, default: all text files)
+
+Array of file extensions to scan. Each must start with `.` and match: `/^([.][a-zA-Z0-9-_]+)+$/`
+
+Common values for Salesforce:
+- `.cls` — Apex classes
+- `.trigger` — Apex triggers
+- `.js` — JavaScript/LWC
+- `.html` — LWC HTML templates
+- `.xml` — Metadata files
+- `.page` — Visualforce pages
+- `.component` — Visualforce components
+
+### `regex_ignore` (Optional)
+
+A second regex pattern — matches that ALSO match this pattern are excluded. Useful for reducing false positives.
+
+⚠️ **`regex_ignore` operates per-LINE, not per-FILE.** It only skips a match if the same line also matches the ignore pattern. It does NOT exclude entire files or classes. For example, adding `/@isTest/` only suppresses violations on lines that literally contain `@isTest` — a hardcoded ID on line 50 of a test class still flags because line 50 doesn't contain `@isTest`.
+
+To exclude entire files, use `ignores.files` in `code-analyzer.yml`:
+```yaml
+ignores:
+  files:
+    - "**/*Test.cls"
+    - "**/test/**"
+```
+
+```yaml
+# Flag System.debug everywhere EXCEPT in lines with "// OK" comment
+regex: "/System\\.debug/g"
+regex_ignore: "/\\/\\/ OK/"
+```
+
+## Validation Rules
+
+| Rule | Error if violated |
+|------|-------------------|
+| Name matches `/^[A-Za-z@][A-Za-z_0-9@\-/]*$/` | "Invalid rule name" |
+| Regex starts and ends with `/` | "Invalid regex format" |
+| File extensions start with `.` | "Invalid file extension" |
+| Severity is 1-5 or valid name | "Invalid severity" |
+| No duplicate rule names | "Rule already exists" |
+
+## Multiple Rules Example
+
+```yaml
+engines:
+  regex:
+    custom_rules:
+      NoHardcodedIds:
+        regex: "/['\"][0-9a-zA-Z]{15,18}['\"]/g"
+        description: "Detects hardcoded Salesforce record IDs"
+        violation_message: "Use Custom Labels or Custom Metadata instead of hardcoded IDs"
+        severity: 2
+        tags: ["Custom", "Security"]
+        file_extensions: [".cls", ".trigger"]
+
+      NoTodos:
+        regex: "/TODO|FIXME|HACK/gi"
+        description: "Flags TODO/FIXME/HACK comments that should be resolved"
+        violation_message: "Resolve or remove this TODO/FIXME/HACK before merging"
+        severity: 4
+        tags: ["Custom", "BestPractices"]
+
+      NoSuppressWarnings:
+        regex: "/(?<target>@SuppressWarnings\\([^)]*\\))/g"
+        description: "Bans @SuppressWarnings annotations — violations must be fixed, not suppressed"
+        violation_message: "Remove @SuppressWarnings and fix the underlying violation instead"
+        severity: 2
+        tags: ["Recommended", "Custom", "BestPractices"]
+        file_extensions: [".cls", ".trigger"]
+```
+
+⚠️ **Note on test-class exclusion:** The `regex_ignore` field is per-LINE only. Adding `regex_ignore: "/@isTest/i"` does NOT exclude entire test classes — it only skips lines that literally contain `@isTest`. For SOQL rules that should skip test classes, use PMD/XPath instead (which can structurally check `[not(ancestor::UserClass[ModifierNode[@Test = true()]])]`). See the "Excluding Test Classes" section in SKILL.md.

package/skills/dx-code-analyzer-custom-rule-create/references/troubleshooting.md

@@ -0,0 +1,141 @@
+# Troubleshooting Custom Rules
+
+## Regex Rule Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| "Invalid rule name" | Name starts with number or contains spaces | Use PascalCase: `NoHardcodedIds`, `BanTodoComments` |
+| "Invalid regex" | Missing `/` delimiters | Must be `/pattern/flags` format |
+| YAML parse error when adding regex | Quotes/backslashes in regex conflict with YAML syntax | **Use `create-regex-rule.js` script** — do not manually write regex into YAML. The script handles serialization correctly. |
+| Rule not listed | YAML indentation wrong | Must be under `engines.regex.custom_rules` with correct nesting |
+| No violations found | Regex doesn't match content | Test regex at regex101.com with your file content |
+| Matches in wrong files | `file_extensions` not set | Add `file_extensions: [".cls"]` to limit scope |
+| Matches in comments | Regex is text-based | Consider using PMD/XPath instead for code-aware matching |
+| Too many matches | Regex too broad | Tighten pattern first (e.g., require leading `0` for IDs), then add `regex_ignore` for remaining edge cases |
+| `regex_ignore` doesn't exclude test classes | `regex_ignore` is per-LINE, not per-FILE | It only skips lines where the ignore pattern matches. To exclude entire test files, use `ignores.files: ["**/*Test.cls"]` in `code-analyzer.yml` |
+| Hardcoded ID regex flags normal words | Pattern `{15,18}` matches 16/17 char words | Salesforce IDs are exactly 15 OR 18 chars, start with `0`. Use: `0[a-zA-Z0-9]{14}(?:[a-zA-Z0-9]{3})?` |
+| Special chars not working | YAML escaping issue | Use `create-regex-rule.js` script to avoid escaping issues. If manual: double-escape (`\\d` → `\d`) |
+
+### Common Regex Escaping in YAML
+
+| Character | In YAML | In regex |
+|-----------|---------|----------|
+| Backslash | `\\\\` | `\\` |
+| Dot | `\\.` | `.` as literal |
+| Quote | `\\"` or use single quotes | `"` |
+| Newline | `\\n` | Line break |
+
+## PMD/XPath Rule Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| "Could not locate Java" | Java not installed or not on PATH | Install Java 11+ or set `engines.pmd.java_command` in config |
+| "Language not supported" | Invalid language identifier | Use: apex, visualforce, html, xml, javascript |
+| "File not found" for ruleset | Wrong path in `custom_rulesets` | Path is relative to `code-analyzer.yml` location |
+| Rule not listed after creation | XML format wrong | Verify against template in `assets/pmd-ruleset-template.xml` |
+| XPath returns 0 matches | Node name or attribute wrong | Re-run `sf code-analyzer ast-dump` and compare |
+| XPath too broad | Missing attribute filter | Add `[@attribute='value']` conditions |
+| XPath `@WithSharing='false'` returns 0 matches | PMD 7 boolean attributes are always present, not string-typed | Use XPath boolean function: `@WithSharing = false()`. NOT string `'false'`, NOT `not(@WithSharing)`. Same for `@Abstract`, `@Final`, etc. |
+| Loop rule flags `for (x : [SELECT...])` | Used `//ForEachStatement//SoqlExpression` (matches iterable) | Scope to body: `//ForEachStatement/BlockStatement//SoqlExpression` |
+| PMD parse error on sample code | Invalid Apex syntax in sample | Ensure sample compiles (doesn't need to deploy) |
+
+### Debugging XPath Step by Step
+
+1. **Dump the AST:** `sf code-analyzer ast-dump --file sample.cls`
+2. **Find the target node:** Search the XML for the pattern (e.g., grep for "System.debug")
+3. **Note the exact node name:** e.g., `MethodCallExpression` (not `MethodCall`)
+4. **Note the exact attribute:** e.g., `FullMethodName='System.debug'` (not `Name` or `Image`)
+5. **Check ancestry:** What's the parent chain? Does your XPath's `ancestor::` match?
+6. **Simplify first:** Start with `//MethodCallExpression` → verify it matches → then add filters
+
+### Verifying Rule Registration
+
+```bash
+# Check if rule appears in the rule list
+sf code-analyzer rules --rule-selector regex:MyRuleName
+sf code-analyzer rules --rule-selector pmd:MyRuleName
+
+# Check all custom rules
+sf code-analyzer rules --rule-selector Custom
+```
+
+### Verifying Rule Execution
+
+```bash
+# Test against a file that SHOULD violate
+sf code-analyzer run --rule-selector regex:MyRuleName --target ./sample-violation.cls
+
+# Test against a file that should NOT violate (expect 0 results)
+sf code-analyzer run --rule-selector regex:MyRuleName --target ./clean-file.cls
+```
+
+## Metadata XML Rule Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| XPath matches nothing on metadata | Missing `local-name()` | MUST use `*[local-name()='element']` — namespace blocks bare names |
+| XPath matches nothing (text values) | Used `text()` — broken in PMD 7 | Use `@Text` attribute: `//*[@Text='value']` |
+| Rule fires on wrong file type | XPath not scoped to root element | Add root check or `ancestor::*[local-name()='PermissionSet']` |
+| `text()` comparison always returns 0 | PMD 7 XML language change | Replace ALL `text()='value'` with `@Text='value'`. This is a PMD 7 breaking change. |
+| `@Text` matches but can't navigate up | `@Text` matches TEXT NODES, not elements | Navigate up: `//*[@Text='value']/..` (element), `/../..` (grandparent) |
+| `[@Text]` predicate on element returns 0 matches | `@Text` lives on CHILD text nodes, not on elements | Use `/*[@Text...]` to navigate to child text node. E.g., `//*[local-name()='apiVersion']/*[number(@Text) < 60]` — NOT `//*[local-name()='apiVersion'][number(@Text) < 60]` |
+| Child predicate `[*[local-name()='x'][@Text='y']]` returns 0 | PMD 7 doesn't support `@Text` in child predicates | Use bottom-up navigation: start from `@Text` match, go up with `../..` |
+| Number comparison doesn't work | Need to use `@Text` not `text()` | `number(substring-before(@Text, '.'))` |
+| Rule doesn't fire on metadata files | PMD only scans `.xml` extension by default | Add `file_extensions: { xml: [".xml"] }` under `engines.pmd`. This covers all compound extensions (`.permissionset-meta.xml`, etc.). Do NOT add compound extensions — the validator rejects them. |
+| "Too many violations" on metadata | Rule too broad, scanning all XML | Scope to specific file types via root element check |
+| ast-dump for XML fails with "XmlEncoding" error | Known bug in some versions | Read the raw XML file — the file content IS the DOM structure |
+| ast-dump for XML shows flat DOM | Expected — XML AST is the literal DOM tree | Elements, text nodes, and attributes — not like Apex AST |
+
+### Debugging Metadata XML XPath (PMD 7)
+
+1. **Dump the AST** (or read raw file if ast-dump fails): `sf code-analyzer ast-dump --file MyField.field-meta.xml --language xml`
+2. **Check namespace:** If file has `xmlns="..."`, ALL XPath must use `local-name()`
+3. **Use `@Text` for text values:** Never use `text()` — it does not work in PMD 7 XML
+4. **Start from the text node, navigate up:** `//*[@Text='TargetValue']/../..` to reach parent elements
+5. **Test with `//*` first:** Confirm PMD is scanning the file at all (should return many violations)
+6. **Test `@Text` matching:** `//*[@Text='YourValue']` — confirm the text node is found
+7. **Add navigation one step at a time:** `../..`, then `[local-name()='parent']`, then sibling checks
+8. **Check file extensions:** Ensure `file_extensions: { xml: [".xml"] }` is in your `engines.pmd` config. Just `.xml` is enough — it covers all Salesforce compound extensions.
+
+## ESLint Rule Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Custom rules not appearing | Plugin missing `meta.docs.description` + `meta.docs.url` | Ensure plugin exports rule metadata |
+| "Cannot find module" for plugin | Plugin not installed | Run `npm install --save-dev eslint-plugin-<name>` |
+| Base rules conflict with custom | Both Code Analyzer base + custom config active | Set `disable_<type>_base_config: true` to suppress built-in rules |
+| ESLint config not found | Wrong path or auto-discover off | Set `eslint_config_file` explicitly or enable `auto_discover_eslint_config` |
+| Deprecated rules excluded | ESLint engine filters deprecated rules | Use replacement rule name (check ESLint docs) |
+| `eslint_config_file` path in `code-analyzer.yml` fails at startup | Code Analyzer validates the path at load time | **Create `eslint.config.js` BEFORE adding it to `code-analyzer.yml`.** File must exist first. |
+| Core rule (e.g., `no-restricted-globals`) not appearing in `sf code-analyzer rules` | Rule not enabled in `eslint.config.js` | Core ESLint rules only appear after you enable them in config AND Code Analyzer loads it. Always validate after configuration. |
+| Created same rule in both Regex AND PMD — double-flagging | Rule defined in two engines | A rule should live in ONE engine only. Use PMD when structural exclusions (e.g., test classes) are needed; Regex for simple text patterns with no exclusions. |
+
+## PMD Apex Rule Issues
+
+> XPath authoring gotchas (loop-type coverage, PMD 7 boolean attributes like `@WithSharing`, etc.) live in the SKILL.md **Gotchas** table — that is the single source. This section covers PMD issues outside XPath authoring.
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Rule works but wrong severity shows | Severity set in wrong place | Regex: edit `severity` under `engines.regex.custom_rules.<RuleName>` in `code-analyzer.yml`. PMD: set `<priority>` in the ruleset XML. |
+| Too many false positives | Pattern too broad | Regex: tighten pattern, then add `regex_ignore` for edge cases. PMD: tighten XPath with `[not(...)]` predicates. |
+| Want to customize threshold on a built-in rule | Can't modify built-in ruleset files | Use `<rule ref="category/...">` with nested `<properties>` override — see `references/advanced-pmd-patterns.md`. |
+
+## Config File Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Config not picked up | File named wrong or in wrong directory | Must be `code-analyzer.yml` or `code-analyzer.yaml` at project root |
+| YAML parse error | Invalid YAML syntax | Check indentation (2 spaces), colon spacing, quote balance |
+| "engines.regex.custom_rules" not recognized | Wrong nesting level | Ensure correct hierarchy: `engines` → `regex` → `custom_rules` → `RuleName` |
+| Multiple config files conflict | Both `.yml` and `.yaml` exist | Delete one — `.yaml` takes precedence over `.yml` |
+| Custom ruleset path not found | Path not relative to config_root | `custom_rulesets` paths resolve relative to `code-analyzer.yml` directory |
+| Rule severity override not working | Wrong config location | Use `rules.pmd.RuleName.severity` in config, not inside ruleset XML |
+| Can't disable a specific rule | Wrong field name | Use `rules.pmd.RuleName.disabled: true` in `code-analyzer.yml` |
+
+## Exclusion Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Rule still fires on excluded files | Glob pattern wrong | Use `**` for recursive: `"**/fflib_*"` not `"fflib_*"` |
+| PMD exclude-pattern ignored | Pattern syntax differs from glob | PMD uses Java regex in `<exclude-pattern>`, not glob |
+| Want to exclude one rule from a category | Missing `<exclude>` in ref | Use `<rule ref="category/..."><exclude name="RuleName"/></rule>` |