@salesforce/afv-skills 1.27.0 → 1.29.0

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

@@ -0,0 +1,288 @@
+# Advanced PMD Patterns
+
+Multi-rule rulesets, overriding built-in rules, exclusion patterns, Java-based rules, and sharing rules across projects.
+
+## Multiple Rules in One Ruleset File
+
+A single ruleset XML can contain any number of rules. This is the recommended approach for teams maintaining a shared rule set:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="TeamStandards"
+    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>Team coding standards</description>
+
+    <!-- Rule 1: Custom XPath rule -->
+    <rule name="NoSystemDebug" language="apex"
+          message="Remove System.debug before merging"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>3</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//MethodCallExpression[@FullMethodName='System.debug']
+  [not(ancestor::UserClass[ModifierNode[@Test = true()]])]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+
+    <!-- Rule 2: Another custom XPath rule -->
+    <rule name="SoqlInLoop" language="apex"
+          message="SOQL query inside a loop — move query before the loop"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>2</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//ForEachStatement//SoqlExpression | //ForLoopStatement//SoqlExpression | //WhileLoopStatement//SoqlExpression
+]]></value>
+            </property>
+        </properties>
+    </rule>
+
+    <!-- Rule 3: XML metadata rule in the same file -->
+    <rule name="MinApiVersion" language="xml"
+          message="Update API version to 60.0+"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+        <priority>3</priority>
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+//*[local-name()='apiVersion'][number(substring-before(text(), '.')) < 60]
+]]></value>
+            </property>
+        </properties>
+    </rule>
+</ruleset>
+```
+
+Rules with different `language` values (apex, xml, visualforce, etc.) can coexist in one ruleset. PMD applies each rule only to files matching its language.
+
+## Overriding Built-in PMD Rules
+
+Override severity, priority, or configurable properties on PMD's built-in rules without writing new ones:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="CustomizedBuiltins"
+    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>Customized built-in rule thresholds</description>
+
+    <!-- Lower the complexity threshold from default 25 to 10 -->
+    <rule ref="category/apex/design.xml/CyclomaticComplexity">
+        <priority>2</priority>
+        <properties>
+            <property name="classReportLevel" value="40" />
+            <property name="methodReportLevel" value="10" />
+        </properties>
+    </rule>
+
+    <!-- Change excessive parameter count from default 4 to 3 -->
+    <rule ref="category/apex/design.xml/ExcessiveParameterList">
+        <properties>
+            <property name="minimum" value="3" />
+        </properties>
+    </rule>
+
+    <!-- Make debug statement rule high-severity instead of moderate -->
+    <rule ref="category/apex/bestpractices.xml/DebugsShouldUseLoggingLevel">
+        <priority>2</priority>
+        <properties>
+            <property name="strictMode" value="true" />
+        </properties>
+    </rule>
+
+    <!-- Include an entire category with one exclusion -->
+    <rule ref="category/apex/security.xml">
+        <exclude name="ApexSuggestUsingNamedCred" />
+    </rule>
+</ruleset>
+```
+
+**Configuration:**
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    custom_rulesets:
+      - "custom-rules/customized-builtins.xml"
+```
+
+### How rule ref works
+
+| Pattern | Effect |
+|---------|--------|
+| `<rule ref="category/apex/design.xml/CyclomaticComplexity">` | Override one specific rule |
+| `<rule ref="category/apex/security.xml">` | Include entire category |
+| `<rule ref="..."><exclude name="RuleName"/></rule>` | Include category minus specific rules |
+| Nested `<priority>` | Override severity (1=Critical, 2=High, 3=Moderate, 4=Low, 5=Info) |
+| Nested `<properties>` | Override configurable thresholds/options |
+
+### Common built-in rules to customize
+
+| Rule | Useful Properties |
+|------|-------------------|
+| `CyclomaticComplexity` | `classReportLevel` (default: 40), `methodReportLevel` (default: 25) |
+| `ExcessiveParameterList` | `minimum` (default: 4) |
+| `ExcessiveClassLength` | `minimum` (default: 1000) |
+| `TooManyFields` | `maxfields` (default: 15) |
+| `NcssMethodCount` | `minimum` (default: 60) |
+| `DebugsShouldUseLoggingLevel` | `strictMode` (default: false) |
+| `ApexUnitTestClassShouldHaveAsserts` | (no properties — exclude if unwanted) |
+
+## Exclusion Patterns
+
+Three mechanisms for excluding files and rules:
+
+### 1. File exclusions in `code-analyzer.yml`
+
+Exclude entire directories or file patterns from all engines:
+
+```yaml
+# code-analyzer.yml
+ignores:
+  files:
+    - "**/node_modules/**"
+    - "**/fflib_*"
+    - "**/*Test*.cls"
+    - "**/generated/**"
+```
+
+Supports glob patterns: `*`, `**`, `?`, `[...]`, `{...}`
+
+### 2. Rule exclusions in PMD rulesets
+
+Exclude specific rules when including an entire category:
+
+```xml
+<rule ref="category/apex/bestpractices.xml">
+    <exclude name="ApexUnitTestClassShouldHaveAsserts" />
+    <exclude name="ApexAssertionsShouldIncludeMessage" />
+</rule>
+```
+
+### 3. Exclude patterns in PMD rulesets
+
+Exclude files at the PMD level (applies only to rules in that ruleset):
+
+```xml
+<ruleset name="MyRules" ...>
+    <exclude-pattern>.*/fflib_.*</exclude-pattern>
+    <exclude-pattern>.*/test/.*</exclude-pattern>
+
+    <rule name="..." ...>
+        ...
+    </rule>
+</ruleset>
+```
+
+### 4. Disabling individual rules via config
+
+Disable any rule without editing rulesets:
+
+```yaml
+# code-analyzer.yml
+rules:
+  pmd:
+    ApexUnitTestClassShouldHaveAsserts:
+      disabled: true
+    CyclomaticComplexity:
+      severity: "Low"    # Downgrade instead of disable
+```
+
+## Java-Based Custom Rules (Advanced)
+
+For rules that need logic beyond XPath (complex data flow, cross-file analysis), write Java PMD rules:
+
+1. **Create a Java class** extending `net.sourceforge.pmd.lang.apex.rule.AbstractApexRule`
+2. **Compile into a JAR** file
+3. **Reference in config:**
+
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    java_classpath_entries:
+      - "custom-rules/my-rules.jar"      # JAR with compiled rule classes
+      - "custom-rules/lib/"              # Folder of JARs (all JARs inside loaded)
+    custom_rulesets:
+      - "category/myteam/rules.xml"      # Ruleset inside the JAR (classpath resource)
+```
+
+The JAR's ruleset XML references the Java class:
+```xml
+<rule name="AvoidFutureAnnotation" language="apex"
+      message="Use Queueable instead of @Future"
+      class="com.myteam.pmd.rules.AvoidFutureRule">
+    <priority>3</priority>
+</rule>
+```
+
+**Requirements:**
+- Java 11+ for compilation
+- PMD 7.x API (use `net.sourceforge.pmd.lang.rule.xpath.XPathRule` for XPath, or extend `AbstractApexRule` for visitor-pattern Java rules)
+
+## Sharing Rules Across Projects
+
+### Approach 1: Relative paths with shared config
+
+If projects share a parent directory or monorepo:
+```yaml
+# code-analyzer.yml
+engines:
+  pmd:
+    custom_rulesets:
+      - "../shared-rules/team-standards.xml"    # Relative to config_root
+```
+
+`config_root` is the directory containing `code-analyzer.yml`. All relative paths resolve from there.
+
+### Approach 2: JAR-based distribution
+
+Package rules into a JAR and distribute via artifact repository:
+
+1. Build a JAR containing your ruleset XML at a classpath resource path (e.g., `category/myteam/standards.xml`)
+2. Place the JAR in each project's `custom-rules/` directory (or download in CI)
+3. Reference in config:
+
+```yaml
+engines:
+  pmd:
+    java_classpath_entries:
+      - "custom-rules/myteam-rules-1.0.jar"
+    custom_rulesets:
+      - "category/myteam/standards.xml"    # Resource inside the JAR
+```
+
+### Approach 3: Git submodule or symlink
+
+For simpler setups, share the ruleset XML via git submodule:
+```bash
+git submodule add https://github.com/myteam/pmd-rules.git custom-rules/shared
+```
+
+```yaml
+engines:
+  pmd:
+    custom_rulesets:
+      - "custom-rules/shared/team-standards.xml"
+```
+
+### CI/CD Integration
+
+All approaches work in CI because paths are relative to `config_root`. Example GitHub Actions step:
+
+```yaml
+- name: Run Code Analyzer
+  run: |
+    sf code-analyzer run --rule-selector "pmd:2,regex:2" --target force-app/
+```
+
+No absolute paths needed — the config file handles resolution.

package/skills/dx-code-analyzer-custom-rule-create/references/apex-ast-reference.md

@@ -0,0 +1,127 @@
+# Apex AST Node Reference
+
+PMD 7.x Apex AST node types and their attributes. Use `sf code-analyzer ast-dump --file <file.cls>` to see the actual tree for your code.
+
+## Node Hierarchy (Common Structure)
+
+```text
+ApexFile
+├── UserClass / UserInterface / UserTrigger / UserEnum
+│   ├── FormalComment (Javadoc)
+│   ├── ModifierNode (public, private, static, etc.)
+│   ├── Field (class-level variables)
+│   │   └── VariableDeclaration
+│   └── Method
+│       ├── ModifierNode
+│       ├── Parameter
+│       └── BlockStatement
+│           ├── VariableDeclarationStatements
+│           ├── ExpressionStatement
+│           │   └── MethodCallExpression
+│           ├── IfElseBlockStatement
+│           │   └── IfBlockStatement
+│           ├── ForEachStatement / ForLoopStatement / WhileLoopStatement
+│           ├── TryCatchFinallyBlockStatement
+│           │   ├── BlockStatement (try body)
+│           │   ├── CatchBlockStatement
+│           │   └── BlockStatement (finally body)
+│           ├── DmlInsertStatement / DmlUpdateStatement / DmlDeleteStatement
+│           ├── ReturnStatement
+│           └── ThrowStatement
+```
+
+## ModifierNode Attributes
+
+Every class, method, field, and parameter has a `ModifierNode` with these boolean attributes:
+
+| Attribute | Meaning |
+|-----------|---------|
+| `Public` | public access |
+| `Private` | private access |
+| `Protected` | protected access |
+| `Global` | global access |
+| `Static` | static member |
+| `Final` | final/const |
+| `Abstract` | abstract method/class |
+| `Virtual` | virtual method/class |
+| `Override` | overrides parent method |
+| `Test` | @IsTest annotated |
+| `TestOrTestSetup` | @IsTest or @TestSetup |
+| `WebService` | webservice method |
+| `WithSharing` | with sharing class |
+| `WithoutSharing` | without sharing class |
+| `InheritedSharing` | inherited sharing class |
+| `Transient` | transient field |
+| `Modifiers` | Bitmask integer of all modifiers |
+
+⚠️ **PMD 7 Boolean Attribute Comparison:**
+
+In PMD 7, these boolean attributes are **always present** on the node — they are never absent. This means:
+- ✅ `@WithSharing = false()` — correct (XPath boolean function)
+- ✅ `@WithSharing = true()` — correct
+- ❌ `@WithSharing = 'false'` — WRONG (string comparison, won't match)
+- ❌ `not(@WithSharing)` — WRONG (attribute always exists, so this is always false)
+- ❌ `@WithSharing` (as existence check) — WRONG (always true, attribute always present)
+
+Use the XPath `true()`/`false()` functions for boolean comparisons:
+```xpath
+<!-- Classes without sharing declaration -->
+//UserClass[ModifierNode[@WithSharing = false() and @WithoutSharing = false() and @InheritedSharing = false()]]
+
+<!-- Abstract classes -->
+//UserClass[ModifierNode[@Abstract = true()]]
+```
+
+## MethodCallExpression Attributes
+
+| Attribute | Example | Notes |
+|-----------|---------|-------|
+| `FullMethodName` | `'System.debug'`, `'Database.query'` | Most reliable for matching |
+| `MethodName` | `'debug'`, `'query'` | Just the method part |
+| `InputParametersSize` | `'1'`, `'0'` | Number of arguments |
+
+## LiteralExpression Attributes
+
+| Attribute | Values | Notes |
+|-----------|--------|-------|
+| `LiteralType` | `STRING`, `INTEGER`, `DECIMAL`, `DOUBLE`, `LONG`, `BOOLEAN` | Type of literal |
+| `Image` | The literal value | For strings, excludes quotes |
+| `String` | `'true'` / `'false'` | Boolean shorthand |
+| `Null` | `'true'` / `'false'` | Is it a null literal |
+
+## SoqlExpression Attributes
+
+| Attribute | Example | Notes |
+|-----------|---------|-------|
+| `Query` | `'SELECT Id FROM Account WHERE Name = :name'` | Original SOQL as written |
+| `CanonicalQuery` | `'SELECT Id FROM Account WHERE Name = :tmpVar1'` | Normalized (bind vars replaced) |
+
+## Annotation Node
+
+```xml
+<Annotation Image="IsTest">
+  <AnnotationParameter Name="testFor" Value="'ApexClass:MyService'" />
+</Annotation>
+```
+
+Use: `//Annotation[@Image='IsTest']` to find test annotations.
+
+## DML Nodes
+
+| Statement | Node | Notes |
+|-----------|------|-------|
+| `insert x;` | `DmlInsertStatement` | |
+| `update x;` | `DmlUpdateStatement` | |
+| `delete x;` | `DmlDeleteStatement` | |
+| `upsert x;` | `DmlUpsertStatement` | |
+| `undelete x;` | `DmlUndeleteStatement` | |
+| `Database.insert(x)` | `MethodCallExpression[@FullMethodName='Database.insert']` | Method-form DML |
+
+## Tips for Reading AST Dumps
+
+1. **`Image` attribute** = the actual source name (variable name, class name, method name)
+2. **`DefiningType` attribute** = which class this node belongs to (present on every node)
+3. **`RealLoc='true'`** = this node has a real source position (not compiler-generated)
+4. **`RealLoc='false'`** = compiler-generated node (e.g., implicit modifiers, empty references)
+5. **`EmptyReferenceExpression`** = placeholder for unqualified variable access (ignore these)
+6. **`Type` attribute on VariableDeclaration** = the declared type (e.g., `'Account'`, `'List<Contact>'`)

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

@@ -0,0 +1,247 @@
+# ESLint Custom Rules for LWC/JavaScript
+
+Create and integrate custom ESLint rules for Lightning Web Components, JavaScript, and TypeScript through Code Analyzer.
+
+## How It Works
+
+Code Analyzer's ESLint engine loads your project's ESLint configuration alongside its built-in rules. You can:
+- Use your own `eslint.config.js` with custom plugins
+- Extend or override built-in base configs (LWC, TypeScript, SLDS, React)
+- Install any npm ESLint plugin and have Code Analyzer pick it up
+
+## Configuration
+
+```yaml
+# code-analyzer.yml
+engines:
+  eslint:
+    # Point to your project's ESLint config
+    eslint_config_file: "eslint.config.js"
+
+    # Or auto-discover from workspace (searches for eslint.config.js/mjs/cjs)
+    auto_discover_eslint_config: true
+
+    # Disable base configs you don't need
+    disable_javascript_base_config: false
+    disable_lwc_base_config: false
+    disable_typescript_base_config: false
+    disable_slds_base_config: false
+    disable_react_base_config: false
+
+    # Custom file extension mapping
+    file_extensions:
+      javascript: [".js", ".cjs", ".mjs", ".jsx"]
+      typescript: [".ts", ".tsx"]
+      html: [".html", ".htm", ".cmp"]
+      css: [".css", ".scss"]
+```
+
+## Adding Custom ESLint Plugins
+
+### Step 1: Install the plugin
+
+```bash
+npm install --save-dev eslint-plugin-my-custom
+```
+
+### Step 2: Create or update `eslint.config.js` (flat config)
+
+```javascript
+const myPlugin = require('eslint-plugin-my-custom');
+
+module.exports = [
+    {
+        plugins: {
+            'my-custom': myPlugin
+        },
+        rules: {
+            'my-custom/no-dangerous-pattern': 'error',
+            'my-custom/enforce-naming': ['warn', { pattern: '^[a-z]' }]
+        }
+    }
+];
+```
+
+### Step 3: Reference in `code-analyzer.yml`
+
+```yaml
+engines:
+  eslint:
+    eslint_config_file: "eslint.config.js"
+```
+
+### Step 4: Validate and run
+
+```bash
+# Check that custom rules appear
+sf code-analyzer rules --rule-selector eslint
+
+# Run against targets
+sf code-analyzer run --rule-selector eslint --target force-app/main/default/lwc/
+```
+
+## Common LWC Custom Rule Patterns
+
+### Enforce component naming convention
+
+```javascript
+// eslint.config.js
+module.exports = [
+    {
+        rules: {
+            '@lwc/lwc/no-unknown-wire-adapters': 'error',
+            '@lwc/lwc/no-api-reassignments': 'error',
+            '@lwc/lwc/no-leaky-event-listeners': 'error'
+        }
+    }
+];
+```
+
+### Add SSR compatibility checks
+
+```javascript
+module.exports = [
+    {
+        rules: {
+            '@lwc/lwc/no-restricted-browser-globals-during-ssr': 'error',
+            '@lwc/lwc/no-unsupported-ssr-properties': 'error'
+        }
+    }
+];
+```
+
+### TypeScript strict rules
+
+```javascript
+module.exports = [
+    {
+        rules: {
+            '@typescript-eslint/no-explicit-any': 'error',
+            '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+            '@typescript-eslint/strict-boolean-expressions': 'warn'
+        }
+    }
+];
+```
+
+## Disabling Base Configs
+
+When you want full control over which rules run, disable the built-in base configs:
+
+```yaml
+engines:
+  eslint:
+    eslint_config_file: "eslint.config.js"
+    disable_javascript_base_config: true
+    disable_lwc_base_config: true
+    disable_typescript_base_config: true
+```
+
+This prevents Code Analyzer's bundled rules from running — only your custom config's rules apply. Parsers are still configured (so files parse correctly), but no built-in rules fire.
+
+## Overriding Rule Severity via Config
+
+After ESLint rules are loaded, override severity in `code-analyzer.yml`:
+
+```yaml
+rules:
+  eslint:
+    no-unused-vars:
+      severity: "Low"
+    my-custom/dangerous-pattern:
+      severity: "Critical"
+    no-console:
+      disabled: true
+```
+
+## Legacy Config Support
+
+If your project uses `.eslintrc.js` (ESLint v8 format), it still works:
+
+```yaml
+engines:
+  eslint:
+    eslint_config_file: ".eslintrc.js"
+    eslint_ignore_file: ".eslintignore"    # Only needed with legacy config
+```
+
+Flat config (`eslint.config.js`) is recommended for new projects.
+
+## Plugin Requirements
+
+For Code Analyzer to pick up custom plugin rules, each rule must have:
+- `meta.docs.description` — rule description
+- `meta.docs.url` — documentation URL
+
+Rules without these metadata fields are silently excluded. Deprecated rules are also excluded.
+
+## Banning APIs Without a Custom Plugin
+
+Core ESLint includes powerful "restrictor" rules that can ban specific globals, syntax patterns, or properties — no plugin installation needed. These rules are NOT active by default — you must enable them in `eslint.config.js`:
+
+### `no-restricted-globals` — ban global functions/variables
+
+```javascript
+module.exports = [
+    {
+        files: ["**/lwc/**/*.js"],
+        rules: {
+            "no-restricted-globals": ["error",
+                { "name": "setTimeout", "message": "Use lifecycle hooks instead of setTimeout." },
+                { "name": "setInterval", "message": "Use lifecycle hooks instead of setInterval." },
+                { "name": "eval", "message": "eval is forbidden for security." }
+            ]
+        }
+    }
+];
+```
+
+### `no-restricted-syntax` — ban arbitrary AST patterns
+
+```javascript
+module.exports = [
+    {
+        files: ["**/lwc/**/*.js"],
+        rules: {
+            "no-restricted-syntax": ["error",
+                { "selector": "CallExpression[callee.name='fetch']", "message": "Use Lightning Data Service instead of fetch." },
+                { "selector": "NewExpression[callee.name='XMLHttpRequest']", "message": "Use fetch or LDS." }
+            ]
+        }
+    }
+];
+```
+
+### `no-restricted-properties` — ban specific object methods
+
+```javascript
+module.exports = [
+    {
+        files: ["**/lwc/**/*.js"],
+        rules: {
+            "no-restricted-properties": ["error",
+                { "object": "window", "property": "location", "message": "Use NavigationMixin." },
+                { "object": "document", "property": "cookie", "message": "Cookies are not available in LWC." }
+            ]
+        }
+    }
+];
+```
+
+⚠️ **These rules will NOT appear in `sf code-analyzer rules` output until you:**
+1. Create the `eslint.config.js` file with the rule enabled
+2. Set `engines.eslint.eslint_config_file: "eslint.config.js"` in `code-analyzer.yml`
+3. Run `sf code-analyzer rules --rule-selector eslint:no-restricted-globals` to verify
+
+They are core ESLint rules, not Code Analyzer built-ins — they require your config to activate.
+
+## When to Use ESLint vs Regex vs PMD
+
+| Need | Engine |
+|------|--------|
+| JavaScript/TypeScript code patterns | **ESLint** |
+| LWC component best practices | **ESLint** (with @lwc plugin) |
+| HTML template issues | **ESLint** (with SLDS or custom HTML plugin) |
+| Simple string patterns in JS/TS | **ESLint** (Regex cannot distinguish code from comments/strings in JS) |
+| Apex code structure | **PMD** (ESLint doesn't parse Apex) |
+| Metadata XML governance | **PMD** with `language="xml"` |