@salesforce/afv-skills 1.28.0 → 1.29.0

package/skills/dx-code-analyzer-custom-rule-create/references/xpath-patterns-governor-limits.md

@@ -0,0 +1,83 @@
+# XPath Patterns for Governor Limits
+
+[← Back to XPath Patterns Index](xpath-patterns.md)
+
+## Governor Limit Patterns
+
+### SOQL inside loops
+
+⚠️ **Must scope to `/BlockStatement//`** — ForEachStatement has the iterable SOQL as a direct child alongside BlockStatement. Without this, `for (Contact c : [SELECT...])` is a false positive.
+
+**ForEachStatement child structure (from ast-dump):**
+```text
+ForEachStatement
+├── VariableDeclarationStatements   ← loop variable declaration
+├── VariableExpression              ← loop variable reference
+├── BlockStatement                  ← LOOP BODY — only match here
+└── SoqlExpression (or VariableExpression)  ← ITERABLE — do NOT flag
+```
+
+```xpath
+//ForEachStatement/BlockStatement//SoqlExpression
+|
+//ForLoopStatement/BlockStatement//SoqlExpression
+|
+//WhileLoopStatement/BlockStatement//SoqlExpression
+```
+
+**Catches:** `for (Id accId : ids) { Account acc = [SELECT ...]; }` (SOQL in body)
+**Does NOT catch (correct):** `for (Contact c : [SELECT Id FROM Contact]) { ... }` (SOQL as iterable)
+
+### DML inside loops
+
+Same principle — scope to BlockStatement:
+
+```xpath
+//ForEachStatement/BlockStatement//DmlInsertStatement
+|
+//ForEachStatement/BlockStatement//DmlUpdateStatement
+|
+//ForEachStatement/BlockStatement//DmlDeleteStatement
+|
+//ForEachStatement/BlockStatement//DmlUpsertStatement
+|
+//ForLoopStatement/BlockStatement//DmlInsertStatement
+|
+//ForLoopStatement/BlockStatement//DmlUpdateStatement
+|
+//ForLoopStatement/BlockStatement//DmlDeleteStatement
+|
+//ForLoopStatement/BlockStatement//DmlUpsertStatement
+|
+//WhileLoopStatement/BlockStatement//DmlInsertStatement
+|
+//WhileLoopStatement/BlockStatement//DmlUpdateStatement
+|
+//WhileLoopStatement/BlockStatement//DmlDeleteStatement
+|
+//WhileLoopStatement/BlockStatement//DmlUpsertStatement
+```
+
+**Shorter variant** (ForEach only, most common):
+```xpath
+//ForEachStatement/BlockStatement//DmlInsertStatement
+| //ForEachStatement/BlockStatement//DmlUpdateStatement
+| //ForEachStatement/BlockStatement//DmlDeleteStatement
+| //ForEachStatement/BlockStatement//DmlUpsertStatement
+```
+
+### Database methods inside loops
+
+```xpath
+//ForEachStatement/BlockStatement//MethodCallExpression[@FullMethodName='Database.query']
+|
+//ForEachStatement/BlockStatement//MethodCallExpression[@FullMethodName='Database.insert']
+|
+//ForEachStatement/BlockStatement//MethodCallExpression[@FullMethodName='Database.update']
+|
+//ForEachStatement/BlockStatement//MethodCallExpression[@FullMethodName='Database.delete']
+|
+//ForLoopStatement/BlockStatement//MethodCallExpression[@FullMethodName='Database.query']
+|
+//WhileLoopStatement/BlockStatement//MethodCallExpression[@FullMethodName='Database.query']
+```

package/skills/dx-code-analyzer-custom-rule-create/references/xpath-patterns-method-calls.md

@@ -0,0 +1,108 @@
+# XPath Patterns for Method Calls and Annotations
+
+[← Back to XPath Patterns Index](xpath-patterns.md)
+
+## Method Call Patterns
+
+### Ban System.debug (non-test classes)
+
+```xpath
+//MethodCallExpression[@FullMethodName='System.debug']
+  [not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+```
+
+**AST evidence:** `MethodCallExpression` has `@FullMethodName='System.debug'`. Test classes have `ModifierNode[@Test = true()]`.
+
+**Catches:** `System.debug('anything');` in production classes
+**Does NOT catch (correct):** Same call inside `@IsTest` classes
+
+### Ban Database.query (dynamic SOQL — SOQL injection risk)
+
+```xpath
+//MethodCallExpression[@FullMethodName='Database.query']
+```
+
+**AST evidence:** `MethodCallExpression[@FullMethodName='Database.query']` (line 118 of verified AST)
+
+To exclude test classes:
+```xpath
+//MethodCallExpression[@FullMethodName='Database.query']
+  [not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+```
+
+### Ban Test.isRunningTest() in production code
+
+```xpath
+//MethodCallExpression[@FullMethodName='Test.isRunningTest']
+  [not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+```
+
+### Ban specific method calls (generic pattern)
+
+```xpath
+//MethodCallExpression[@FullMethodName='ClassName.methodName']
+```
+
+Common examples:
+- `@FullMethodName='System.debug'`
+- `@FullMethodName='Database.query'`
+- `@FullMethodName='Test.isRunningTest'`
+- `@FullMethodName='UserInfo.getUserId'`
+- `@FullMethodName='Limits.getQueries'`
+
+---
+
+## Annotation Patterns
+
+### @AuraEnabled without cacheable=true
+
+```xpath
+//Method/ModifierNode/Annotation[@Name='AuraEnabled'
+  and not(AnnotationParameter[@Name='cacheable' and @Value='true'])]
+```
+
+**AST evidence:** `Annotation[@Name='AuraEnabled']` with child `AnnotationParameter[@Name='cacheable'][@Value='true']`
+
+**Catches:** `@AuraEnabled public static ...` (no cacheable)
+**Does NOT catch (correct):** `@AuraEnabled(cacheable=true) public static ...`
+
+### @future methods (recommend Queueable instead)
+
+```xpath
+//Method/ModifierNode/Annotation[@Name='Future']
+```
+
+**AST evidence:** Annotation `@Name='Future'` (note: PMD normalizes `@future` → `Future` in the Name attribute, but `@RawName='future'`)
+
+### @SuppressWarnings usage (audit/ban)
+
+```xpath
+//Annotation[@Name='SuppressWarnings']
+```
+
+**AST evidence:** `Annotation[@Name='SuppressWarnings']` with `AnnotationParameter[@Name='value'][@Value='PMD.RuleName']`
+
+To flag specific suppressions:
+```xpath
+//Annotation[@Name='SuppressWarnings']/AnnotationParameter[contains(@Value, 'ApexCRUDViolation')]
+```
+
+### @IsTest without testFor parameter
+
+From GitHub issue #2008:
+```xpath
+//UserClass/ModifierNode/Annotation[
+  @Name='IsTest'
+  and not(AnnotationParameter[@Name='testFor'])
+]
+```
+
+### @IsTest class without System.runAs
+
+```xpath
+//UserClass[ModifierNode[@Test = true()]]
+  /Method[ModifierNode[@Test = true()]]
+  /BlockStatement[not(.//RunAsBlockStatement)]
+```
+
+**AST evidence:** `RunAsBlockStatement` is the node for `System.runAs(...) { }` blocks.

package/skills/dx-code-analyzer-custom-rule-create/references/xpath-patterns-security.md

@@ -0,0 +1,45 @@
+# XPath Patterns for Security
+
+[← Back to XPath Patterns Index](xpath-patterns.md)
+
+## Security Patterns
+
+### Class without sharing declaration
+
+```xpath
+//UserClass[
+  @Nested = false()
+  and ModifierNode[@WithSharing = false() and @WithoutSharing = false() and @InheritedSharing = false()]
+]
+```
+
+**AST evidence:** `ModifierNode` has `@WithSharing`, `@WithoutSharing`, `@InheritedSharing` — all `false()` means no sharing keyword declared (implicit without sharing).
+
+Added `@Nested = false()` to exclude inner classes (which inherit from parent).
+
+> ⚠️ **PMD 7 boolean attributes:** `@WithSharing`, `@WithoutSharing`, `@InheritedSharing`, and `@Nested` are boolean-typed in PMD 7 — string comparison (`='false'`) errors with "Cannot compare xs:boolean to xs:string". Always use `= false()` / `= true()`. See [xpath-patterns.md](xpath-patterns.md) for the full list.
+
+### SOQL without WITH USER_MODE or SECURITY_ENFORCED
+
+```xpath
+//SoqlExpression[
+  not(contains(@CanonicalQuery, 'WITH USER_MODE'))
+  and not(contains(@CanonicalQuery, 'WITH SECURITY_ENFORCED'))
+]
+[not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+```
+
+**AST evidence:** `SoqlExpression[@CanonicalQuery]` contains the full normalized query text.
+
+### Hardcoded Salesforce IDs (structural — string literals 15-18 chars)
+
+```xpath
+//LiteralExpression[
+  @LiteralType='STRING'
+  and string-length(@Image) >= 15
+  and string-length(@Image) <= 18
+]
+[not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+```
+
+**Note:** `matches()` function may not be available in all PMD XPath versions. The string-length check catches most cases. For precision, use Regex engine instead.

package/skills/dx-code-analyzer-custom-rule-create/references/xpath-patterns-structure.md

@@ -0,0 +1,127 @@
+# XPath Patterns for Code Structure, Tests, and Naming
+
+[← Back to XPath Patterns Index](xpath-patterns.md)
+
+## Code Structure Patterns
+
+### DML without try-catch
+
+```xpath
+//DmlInsertStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+|
+//DmlUpdateStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+|
+//DmlDeleteStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+|
+//DmlUpsertStatement[not(ancestor::TryCatchFinallyBlockStatement)]
+```
+
+**AST evidence:** DML nodes sit inside `TryCatchFinallyBlockStatement` when wrapped in try-catch.
+
+To exclude test classes:
+```xpath
+//DmlInsertStatement[
+  not(ancestor::TryCatchFinallyBlockStatement)
+  and not(ancestor::UserClass[ModifierNode[@Test = true()]])
+]
+```
+
+### Empty catch blocks (swallowed exceptions)
+
+```xpath
+//CatchBlockStatement[BlockStatement[not(*)]]
+```
+
+**AST evidence:** `CatchBlockStatement` contains a `BlockStatement`. Empty body = `BlockStatement` with no children.
+
+### Nested if statements (max depth 3)
+
+```xpath
+//IfBlockStatement[
+  ancestor::IfBlockStatement[
+    ancestor::IfBlockStatement[
+      ancestor::IfBlockStatement
+    ]
+  ]
+]
+```
+
+### Methods with too many parameters
+
+```xpath
+//Method[@Arity >= 5 and @Constructor = false()]
+```
+
+**AST evidence:** `Method[@Arity]` gives parameter count directly.
+
+### Logic in trigger (should delegate to handler)
+
+For trigger files (UserTrigger node):
+```xpath
+//UserTrigger/BlockStatement//DmlInsertStatement
+|
+//UserTrigger/BlockStatement//DmlUpdateStatement
+|
+//UserTrigger/BlockStatement//SoqlExpression
+|
+//UserTrigger/BlockStatement//MethodCallExpression[@FullMethodName='Database.query']
+```
+
+---
+
+## Test Quality Patterns
+
+### Test method without assertions
+
+```xpath
+//Method[ModifierNode[@Test = true()]]
+  /BlockStatement[
+    not(.//MethodCallExpression[
+      contains(@FullMethodName, 'System.assert')
+      or contains(@FullMethodName, 'Assert.')
+    ])
+  ]
+```
+
+**Catches:** Test methods with no `System.assert*` or `Assert.*` calls anywhere in their body.
+
+### Test method without System.runAs
+
+```xpath
+//Method[ModifierNode[@Test = true()]]
+  /BlockStatement[not(.//RunAsBlockStatement)]
+```
+
+**AST evidence:** `System.runAs(user) { ... }` becomes `RunAsBlockStatement` in the AST.
+
+### Test using seeAllData=true
+
+```xpath
+//Annotation[@Name='IsTest']/AnnotationParameter[@Name='seeAllData' and @Value='true']
+```
+
+---
+
+## Naming Convention Patterns
+
+### Class name doesn't match file (non-test)
+
+This is better enforced by the built-in rule, but the XPath pattern for a specific convention:
+```xpath
+//UserClass[@Nested = false() and not(starts-with(@Image, 'Test')) and not(ends-with(@Image, 'Test'))]
+```
+
+### Method naming (non-standard)
+
+```xpath
+//Method[
+  @Constructor = false()
+  and not(ModifierNode[@Test = true()])
+  and not(starts-with(@Image, 'get'))
+  and not(starts-with(@Image, 'set'))
+  and not(starts-with(@Image, 'is'))
+  and matches(@Image, '^[A-Z]')
+]
+```
+
+**Catches:** Methods starting with uppercase in non-test code (Apex convention is camelCase).

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

@@ -0,0 +1,131 @@
+# XPath Patterns for Apex Custom Rules
+
+Pre-validated PMD XPath patterns for Salesforce Apex code. Every pattern below has been verified against actual `sf code-analyzer ast-dump` output. Use these directly — but still run `ast-dump` on YOUR code to confirm node names haven't changed in newer PMD versions.
+
+## XPath Syntax Quick Reference
+
+| Syntax | Meaning |
+|--------|---------|
+| `//Node` | Find Node anywhere in tree |
+| `//Node[@attr='value']` | Node with specific string attribute value |
+| `//Node[@attr = true()]` | Node with boolean attribute = true (**PMD 7 requirement**) |
+| `//Parent//Child` | Child anywhere inside Parent (any descendant) |
+| `//Parent/Child` | **Direct child only** — use this to avoid false positives |
+| `//Node[not(...)]` | Node where condition is NOT true |
+| `//Node[ancestor::Other]` | Node that has Other as an ancestor |
+| `//Node[.//Other]` | Node that contains Other somewhere inside |
+| `@Image` | The name/text of the node |
+| `@FullMethodName` | Full qualified method name (e.g., 'System.debug') |
+| `@LiteralType` | Type of literal: STRING, INTEGER, BOOLEAN, TRUE, FALSE, NULL |
+
+### PMD 7 Boolean Attributes — MUST use `true()` / `false()`
+
+In PMD 7, many node attributes are **boolean typed**, not strings — even though `ast-dump` renders them as `Nested='false'` or `Test='true'` in the XML output. String attributes (`@FullMethodName`, `@Name`, `@Image`, `@LiteralType`, etc.) are safe to copy from the AST dump as-is. But **attributes whose values are `true` or `false` in the dump are boolean-typed** — comparing them with string literals (`@Nested='false'`) causes the error: "Cannot compare xs:boolean to xs:string".
+
+Known boolean attributes by node:
+
+| Node | Boolean Attributes |
+|------|--------------------|
+| `ModifierNode` | `@Test`, `@Public`, `@Private`, `@Protected`, `@Static`, `@Abstract`, `@Final`, `@Global`, `@WithSharing`, `@WithoutSharing`, `@InheritedSharing` |
+| `UserClass` | `@Nested` |
+| `Method` | `@Constructor` |
+
+| WRONG | CORRECT |
+|-------|---------|
+| `UserClass[@Nested='false']` | `UserClass[@Nested = false()]` |
+| `UserClass[@Nested='true']` | `UserClass[@Nested = true()]` |
+| `ModifierNode[@Test='true']` | `ModifierNode[@Test = true()]` |
+| `ModifierNode[@Static='false']` | `ModifierNode[@Static = false()]` |
+| `Method[@Constructor = false()]` | `Method[@Constructor = false()]` |
+
+`true()` and `false()` are XPath boolean functions. If you see an attribute that looks boolean in the AST dump, assume it is typed as boolean and use `true()`/`false()`.
+
+---
+
+### `/` vs `//` — The Most Common Source of False Positives
+
+| XPath | Meaning | Risk |
+|-------|---------|------|
+| `//ForEachStatement//SoqlExpression` | SOQL anywhere inside ForEachStatement | ❌ Matches iterable position too |
+| `//ForEachStatement/BlockStatement//SoqlExpression` | SOQL inside loop **body** only | ✅ Correct |
+
+**Rule of thumb:** When matching inside a structural node (loop, if, try), always scope to `/BlockStatement//` to target the body, not sibling children like iterables or conditions.
+
+---
+
+## Pattern Categories (By Topic)
+
+For detailed patterns in each category, see the dedicated files below:
+
+| Category | File | Contents |
+|----------|------|----------|
+| Governor Limits | [xpath-patterns-governor-limits.md](xpath-patterns-governor-limits.md) | SOQL/DML in loops, Database methods in loops |
+| Method Calls & Annotations | [xpath-patterns-method-calls.md](xpath-patterns-method-calls.md) | Ban specific methods, @AuraEnabled, @future, @IsTest, @SuppressWarnings patterns |
+| Security | [xpath-patterns-security.md](xpath-patterns-security.md) | Sharing declarations, SOQL security modes, hardcoded IDs |
+| Code Structure, Tests & Naming | [xpath-patterns-structure.md](xpath-patterns-structure.md) | DML error handling, empty catches, test assertions, naming conventions |
+
+---
+
+## Key Apex AST Node Names
+
+| Apex Construct | AST Node | Key Attributes |
+|---|---|---|
+| Class | `UserClass` | `Image`, `SuperClassName`, `InterfaceNames`, `Nested` |
+| Interface | `UserInterface` | `Image`, `SuperInterfaceName` |
+| Method | `Method` | `Image`, `Arity`, `ReturnType`, `Constructor` |
+| Trigger | `UserTrigger` | `Image`, `TargetName` |
+| SOQL query | `SoqlExpression` | `Query`, `CanonicalQuery` |
+| DML insert | `DmlInsertStatement` | |
+| DML update | `DmlUpdateStatement` | |
+| DML delete | `DmlDeleteStatement` | |
+| DML upsert | `DmlUpsertStatement` | |
+| Method call | `MethodCallExpression` | `FullMethodName`, `MethodName`, `InputParametersSize` |
+| For-each loop | `ForEachStatement` | children: VariableDeclarationStatements, VariableExpression, **BlockStatement** (body), iterable |
+| For loop | `ForLoopStatement` | children: init, condition, update, **BlockStatement** (body) |
+| While loop | `WhileLoopStatement` | children: condition, **BlockStatement** (body) |
+| If/else | `IfElseBlockStatement` > `IfBlockStatement` | `ElseStatement` |
+| Try-catch | `TryCatchFinallyBlockStatement` | |
+| Catch block | `CatchBlockStatement` | `ExceptionType`, `VariableName` |
+| RunAs | `RunAsBlockStatement` | |
+| String literal | `LiteralExpression` | `@LiteralType='STRING'`, `@Image` (value without quotes) |
+| Integer literal | `LiteralExpression` | `@LiteralType='INTEGER'`, `@Image` |
+| Boolean true | `LiteralExpression` | `@LiteralType='TRUE'` |
+| Boolean false | `LiteralExpression` | `@LiteralType='FALSE'` |
+| Null | `LiteralExpression` | `@LiteralType='NULL'` |
+| Variable | `VariableExpression` | `@Image` (name) |
+| Assignment | `AssignmentExpression` | `@Op` (=, +=, etc.) |
+| Binary expression | `BinaryExpression` | `@Op` (+, -, *, /) |
+| Boolean expression | `BooleanExpression` | `@Op` (>, <, ==, !=, >=, <=) |
+| New object | `NewKeyValueObjectExpression` | `@Type` |
+| New object (no-arg) | `NewObjectExpression` | `@Type` |
+| Return | `ReturnStatement` | |
+| Annotation | `Annotation` | `@Name` (IsTest, AuraEnabled, Future, SuppressWarnings) |
+| Annotation param | `AnnotationParameter` | `@Name`, `@Value` |
+| Modifier | `ModifierNode` | `Public`, `Private`, `Static`, `Test`, `WithSharing`, `Global`, etc. |
+| Parameter | `Parameter` | `@Image` (name), `@Type` |
+| New list | `NewListInitExpression` | |
+| New map | `NewMapInitExpression` | |
+
+---
+
+## XPath Best Practices
+
+1. **ALWAYS run `ast-dump` first** — never guess node names, even for patterns listed here
+2. **Use `/BlockStatement//` for loop/if body** — avoids matching iterables, conditions, etc.
+3. **Use `@FullMethodName`** for method calls — not `@Image` or `@MethodName` alone
+4. **Exclude test classes** with `[not(ancestor::UserClass[ModifierNode[@Test = true()]])]`
+5. **Test with BOTH positive AND negative cases** — ensure no false positives
+6. **Prefer `//Node` over absolute paths** — code structure varies
+7. **Use `ancestor::` / `not(ancestor::)`** for structural exclusions (try-catch, test class)
+8. **Keep XPath simple** — complex expressions are fragile and hard to maintain
+
+## Common False Positive Traps
+
+| Pattern | Trap | Fix |
+|---------|------|-----|
+| SOQL in loop | `//ForEachStatement//SoqlExpression` matches iterable | Use `/BlockStatement//` |
+| DML in loop | Same as above | Use `/BlockStatement//` |
+| Ban method in all code | Flags test code too | Add `[not(ancestor::UserClass[ModifierNode[@Test = true()]])]` |
+| Empty block detection | Matches intentional empty constructors | Add `[@Constructor = false()]` or exclude specific patterns |
+| No sharing declaration | Flags inner classes (which inherit) | Add `[@Nested = false()]` |
+| String literal length check | Matches test data strings | Exclude test classes |