@salesforce/afv-skills 1.28.0 → 1.29.0

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

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

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

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

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

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

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