@salesforce/afv-skills 1.27.0 → 1.29.0

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>` |

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).