@salesforce/afv-skills 1.16.0 → 1.18.0

package/skills/configuring-code-analyzer/references/config-schema.md

@@ -0,0 +1,257 @@
+# Code Analyzer Configuration Schema
+
+Full reference for the `code-analyzer.yml` configuration file.
+
+## Top-Level Fields
+
+```yaml
+# code-analyzer.yml
+
+# Root directory for resolving relative paths in the config
+config_root: .
+
+# Directory where Code Analyzer writes log files
+log_folder: /tmp
+
+# Log verbosity: 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Fine
+log_level: 3
+
+# File patterns to exclude from analysis
+ignores:
+  files: []
+
+# Rule severity, tag, and disable overrides
+rules: {}
+
+# Engine-specific configuration
+engines: {}
+
+# Bulk suppression rules
+suppressions:
+  disable_suppressions: false
+```
+
+## Ignores Section
+
+```yaml
+ignores:
+  files:
+    - "**/node_modules/**"      # npm dependencies
+    - "**/.sfdx/**"             # Salesforce DX internal
+    - "**/.sf/**"               # Salesforce CLI internal
+    - "**/test/**"              # Test directories
+    - "**/*.test.js"            # Test files
+    - "**/*.min.js"             # Minified files
+    - "**/staticresources/**"   # Static resources (often vendor)
+```
+
+**Pattern syntax:** Glob patterns using `*` (any filename chars), `**` (any path segment), `?` (single char).
+
+## Rules Section
+
+Override severity, tags, or disable rules per engine:
+
+```yaml
+rules:
+  <engine_name>:
+    <rule_name>:
+      severity: <1-5 or "Critical"|"High"|"Moderate"|"Low"|"Info">
+      tags: ["Tag1", "Tag2"]    # Override rule tags
+      disabled: true|false       # Disable/enable rule
+```
+
+### Severity Values
+
+| Number | Name | Meaning |
+|--------|------|---------|
+| 1 | Critical | Security vulnerabilities, must fix before release |
+| 2 | High | Significant issues, should fix |
+| 3 | Moderate | Recommended improvements |
+| 4 | Low | Minor suggestions |
+| 5 | Info | Informational, no action required |
+
+### Example Rule Overrides
+
+```yaml
+rules:
+  pmd:
+    ApexCRUDViolation:
+      severity: 1               # Promote to Critical
+    AvoidGlobalModifier:
+      disabled: true            # Disable entirely
+    ApexDoc:
+      severity: 5              # Demote to Info
+      tags: ["Documentation"]
+  eslint:
+    no-console:
+      severity: 4              # Demote to Low
+    no-unused-vars:
+      severity: 2              # Promote to High
+```
+
+## Engines Section
+
+### PMD Engine
+
+```yaml
+engines:
+  pmd:
+    disable_engine: false
+    java_command: "java"                    # Path to Java executable
+    custom_rulesets:                        # Additional ruleset XML files
+      - "./config/custom-pmd-rules.xml"
+    java_classpath_entries:                 # JARs for custom Java rules
+      - "./lib/my-custom-rules.jar"
+    file_extensions:                        # Override scanned file types
+      apex: [".cls", ".trigger"]
+      visualforce: [".page", ".component"]
+```
+
+### ESLint Engine
+
+```yaml
+engines:
+  eslint:
+    disable_engine: false
+    auto_discover_eslint_config: true       # Use project's eslint config files
+    eslint_config_file: "./eslint.config.mjs"  # Explicit config file path
+    disable_javascript_base_config: false   # Disable built-in JS rules
+    disable_typescript_base_config: false   # Disable built-in TS rules
+    disable_lwc_base_config: false          # Disable built-in LWC rules
+    disable_flow_base_config: false         # Disable built-in Flow rules
+```
+
+**Note:** `auto_discover_eslint_config` requires a `--workspace` flag on the run command.
+
+### CPD Engine (Copy-Paste Detector)
+
+```yaml
+engines:
+  cpd:
+    disable_engine: false
+    minimum_tokens:                         # Min tokens for duplicate detection
+      apex: 100                             # Lower = more sensitive
+      html: 100
+      javascript: 100
+      visualforce: 100
+      xml: 100
+    skip_duplicate_files: false             # Skip files with identical content
+```
+
+### SFGE Engine (Salesforce Graph Engine)
+
+```yaml
+engines:
+  sfge:
+    disable_engine: false
+    java_max_heap_size: "4g"               # JVM heap (increase for large projects)
+    java_thread_count: 4                    # Parallel threads
+    java_thread_timeout: 900000             # Per-thread timeout in ms
+```
+
+**Warning:** SFGE is resource-intensive. For projects with 500+ Apex classes, use 4g+ heap. Analysis can take 10-30 minutes.
+
+### ApexGuru Engine
+
+```yaml
+engines:
+  apexguru:
+    disable_engine: false
+    target_org: "my-org-alias"             # Authenticated org alias or username
+    api_timeout_ms: 300000                  # API timeout in ms (default 5min)
+```
+
+**Requires:** Authenticated Salesforce org (`sf org login web`).
+
+### Flow Engine
+
+```yaml
+engines:
+  flow:
+    disable_engine: false
+    python_command: "python3"              # Path to Python 3 executable
+```
+
+**Requires:** Python 3 installed.
+
+### Regex Engine
+
+```yaml
+engines:
+  regex:
+    disable_engine: false
+    custom_rules:
+      <RuleName>:
+        regex: "/<pattern>/<flags>"         # JavaScript regex syntax
+        regex_ignore: "/<pattern>/<flags>"  # Optional: false positive filter
+        file_extensions: [".cls", ".trigger"]
+        description: "What this rule checks"
+        violation_message: "Message shown to developer"
+        severity: 3
+        tags: ["Recommended", "Security"]
+```
+
+### RetireJS Engine
+
+```yaml
+engines:
+  retire-js:
+    disable_engine: false
+```
+
+**Note:** RetireJS scans JavaScript dependencies for known CVEs. No additional configuration needed beyond enable/disable.
+
+## Suppressions Section
+
+```yaml
+suppressions:
+  disable_suppressions: false              # Set true to ignore ALL suppressions
+
+  # Bulk suppressions by file/folder path
+  "src/legacy/":
+    - rule_selector: "pmd:ApexDoc"
+      max_suppressed_violations: 50        # Quota (null = unlimited)
+      reason: "Legacy code, documentation not required"
+
+  "src/utils/Logger.cls":
+    - rule_selector: "eslint:no-console"
+      max_suppressed_violations: 10
+      reason: "Logger intentionally uses console"
+```
+
+### Inline Suppression Markers
+
+In addition to bulk config suppressions, violations can be suppressed inline:
+
+```java
+// Apex: PMD suppression
+// NOPMD - reason here
+@SuppressWarnings('PMD.ApexCRUDViolation')
+
+// Any engine: universal marker
+// code-analyzer-suppress(pmd:ApexCRUDViolation) - reason
+// code-analyzer-suppress(eslint:no-console) - reason
+```
+
+## Config File Discovery
+
+Code Analyzer automatically looks for configuration in this order:
+1. File specified via `--config-file` flag
+2. `code-analyzer.yml` in current working directory
+3. `code-analyzer.yaml` in current working directory
+4. No config (use defaults)
+
+## Validating Configuration
+
+Always validate after making changes:
+
+```bash
+# Validate config and show effective settings
+sf code-analyzer config --config-file code-analyzer.yml
+
+# Show config for specific rules
+sf code-analyzer config --rule-selector pmd:Security
+
+# Show all rule defaults (verbose)
+sf code-analyzer config --include-unmodified-rules --rule-selector all
+```

package/skills/configuring-code-analyzer/references/diagnostic-flow.md

@@ -0,0 +1,70 @@
+# Diagnostic Flow: Fix a Broken Setup
+
+**TRIGGER:** User says "not working", "broken", "getting errors", "scan fails", "help me fix", etc.
+
+## NEVER DO THESE (anti-patterns that waste time)
+
+- ❌ NEVER run `which sfdx`, `which sf`, `find`, `ls /opt/homebrew/bin/` or search for binaries
+- ❌ NEVER use an old `sfdx` binary as a workaround — it is NOT a substitute for `sf`
+- ❌ NEVER create symlinks (`ln -s`) to work around missing commands
+- ❌ NEVER check PATH, inspect Cellar directories, or search for alternative installations
+- ❌ NEVER proceed to Layer 2 if Layer 1 failed — fix Layer 1 first
+- ❌ NEVER give the user a list of manual steps — fix it yourself or give ONE command
+
+## Diagnostic Flow (follow this EXACTLY, no deviation)
+
+Run **ONLY** this one command first:
+```bash
+sf --version 2>&1
+```
+
+**If output contains "command not found":**
+→ STOP. Do not run any other commands. Tell user: "sf CLI is not installed. I'll install it now."
+→ Ask user for permission, then run: `npm install -g @salesforce/cli`
+→ After install, re-run `sf --version 2>&1` to verify. If it works, continue to next layer.
+
+**If sf works**, run ONLY:
+```bash
+sf plugins --core 2>&1 | grep -i "code-analyzer"
+```
+
+**If output is empty or shows "JIT" but not a real version:**
+→ STOP. Run: `sf plugins install @salesforce/plugin-code-analyzer`
+→ After install, re-check. If it works, continue to next layer.
+
+**If plugin is installed**, check engine deps:
+```bash
+java -version 2>&1
+node --version 2>&1
+```
+
+**If all pass**, verify with a scan:
+```bash
+sf code-analyzer run --rule-selector Recommended 2>&1 | tail -20
+```
+
+## Fix Table
+
+| Error Pattern | The ONE Fix |
+|--------------|-------------|
+| `sf: command not found` | `npm install -g @salesforce/cli` |
+| Plugin missing / JIT error | `sf plugins install @salesforce/plugin-code-analyzer` |
+| `Cannot find module` | `sf plugins uninstall @salesforce/plugin-code-analyzer && sf plugins install @salesforce/plugin-code-analyzer` |
+| `java: command not found` | Install Java 11+ (see `<skill_dir>/references/engine-prerequisites.md`) |
+| `OutOfMemoryError` (SFGE) | Add `engines.sfge.java_max_heap_size: "4g"` to `code-analyzer.yml` |
+| `YAMLException` | Read the config file, fix YAML syntax |
+| `EPERM` / npm permission error | Tell user to run: `sudo chown -R $(whoami) ~/.npm` — then wait for them to confirm, then retry the SAME install command that failed. Do NOT dump next steps. |
+
+## After Fix: Verify and Hand Off
+
+Re-run the check for the fixed layer. Once a scan succeeds, tell the user what was fixed and **proceed to run the full scan**.
+
+## When a fix requires user action (sudo, manual step)
+
+Tell the user ONLY the ONE command they need to run and WHY. Then STOP and WAIT for them to confirm it's done. Do NOT:
+- ❌ List the remaining steps ("after that, do X, then Y, then Z")
+- ❌ Tell them what to run next after the manual step
+- ❌ Provide a multi-step recovery plan
+- ❌ Ask "would you like me to attempt with sudo or do it yourself"
+
+Just say: "Run this command: `<command>`. It fixes [reason]. Let me know when it's done and I'll continue."

package/skills/configuring-code-analyzer/references/engine-prerequisites.md

@@ -0,0 +1,276 @@
+# Engine Prerequisites
+
+Detailed installation instructions for each Code Analyzer engine's dependencies.
+
+## Summary Table
+
+| Engine | Required Dependencies | Optional |
+|--------|----------------------|----------|
+| PMD | Java 11+ | Custom ruleset JARs |
+| CPD | Java 11+ | — |
+| ESLint | Node.js 18+ | Project ESLint config |
+| RetireJS | Node.js 18+ | — |
+| Regex | None (built-in) | — |
+| Flow | Python 3 | — |
+| SFGE | Java 11+ (4g+ heap recommended) | — |
+| ApexGuru | Authenticated Salesforce org | — |
+
+## Core: Salesforce CLI
+
+**Required for ALL engines.**
+
+### macOS
+
+```bash
+# Via Homebrew (recommended)
+brew install sf
+
+# Or via npm
+npm install -g @salesforce/cli
+```
+
+### Windows
+
+```bash
+# Via npm
+npm install -g @salesforce/cli
+
+# Or download installer from:
+# https://developer.salesforce.com/tools/salesforcecli
+```
+
+### Linux
+
+```bash
+# Via npm
+npm install -g @salesforce/cli
+
+# Or via tarball:
+# https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm
+```
+
+### Verify
+
+```bash
+sf --version
+# Expected: @salesforce/cli/2.x.x ...
+```
+
+## Code Analyzer Plugin
+
+**Required: sf CLI must be installed first.**
+
+```bash
+# Install
+sf plugins install @salesforce/plugin-code-analyzer
+
+# Verify
+sf code-analyzer --help
+
+# Update to latest
+sf plugins install @salesforce/plugin-code-analyzer@latest
+
+# Check version
+sf plugins --core | grep code-analyzer
+```
+
+## Java 11+ (for PMD, CPD, SFGE)
+
+### macOS
+
+```bash
+# Via Homebrew
+brew install openjdk@11
+
+# Add to PATH (add to ~/.zshrc or ~/.bash_profile)
+export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"
+export JAVA_HOME="/opt/homebrew/opt/openjdk@11"
+
+# Or via SDKMAN (manages multiple Java versions)
+curl -s "https://get.sdkman.io" | bash
+sdk install java 11.0.21-tem
+```
+
+### Windows
+
+```bash
+# Via winget
+winget install EclipseAdoptium.Temurin.11.JDK
+
+# Or via Chocolatey
+choco install temurin11
+```
+
+### Linux
+
+```bash
+# Ubuntu/Debian
+sudo apt install openjdk-11-jdk
+
+# RHEL/CentOS/Fedora
+sudo dnf install java-11-openjdk-devel
+
+# Via SDKMAN (any Linux)
+curl -s "https://get.sdkman.io" | bash
+sdk install java 11.0.21-tem
+```
+
+### Verify
+
+```bash
+java -version
+# Expected: openjdk version "11.x.x" or higher
+
+echo $JAVA_HOME
+# Should point to JDK installation
+```
+
+### Troubleshooting Java
+
+| Issue | Solution |
+|-------|----------|
+| `java: command not found` | Add Java bin dir to PATH |
+| Wrong Java version | Set JAVA_HOME explicitly |
+| Multiple Java versions | Use `sdk use java 11.x.x` or update PATH order |
+| SFGE heap errors | Increase `java_max_heap_size` in config |
+
+## Node.js 18+ (for ESLint, RetireJS)
+
+### macOS
+
+```bash
+# Via Homebrew
+brew install node@20
+
+# Or via nvm (recommended for version management)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+nvm install 20
+nvm use 20
+```
+
+### Windows
+
+```bash
+# Via winget
+winget install OpenJS.NodeJS.LTS
+
+# Or via nvm-windows
+# Download from: https://github.com/coreybutler/nvm-windows/releases
+nvm install 20
+nvm use 20
+```
+
+### Linux
+
+```bash
+# Via nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+nvm install 20
+nvm use 20
+
+# Or via package manager (may be outdated)
+# Ubuntu/Debian (use NodeSource for latest):
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+### Verify
+
+```bash
+node --version
+# Expected: v20.x.x or v18.x.x (minimum v18)
+
+npm --version
+# Expected: 9.x.x or 10.x.x
+```
+
+## Python 3 (for Flow Engine)
+
+**Only needed if you scan Flow files (*.flow-meta.xml).**
+
+### macOS
+
+```bash
+# Via Homebrew
+brew install python3
+
+# macOS may already have python3 via Xcode Command Line Tools
+xcode-select --install
+```
+
+### Windows
+
+```bash
+# Via winget
+winget install Python.Python.3.12
+
+# Or from python.org
+# https://www.python.org/downloads/windows/
+```
+
+### Linux
+
+```bash
+# Usually pre-installed. If not:
+# Ubuntu/Debian
+sudo apt install python3
+
+# RHEL/CentOS/Fedora
+sudo dnf install python3
+```
+
+### Verify
+
+```bash
+python3 --version
+# Expected: Python 3.x.x
+```
+
+## Authenticated Org (for ApexGuru)
+
+**Only needed for ApexGuru performance analysis.**
+
+```bash
+# Login to a Salesforce org
+sf org login web --alias my-org
+
+# Or login with JWT (CI/CD)
+sf org login jwt --client-id <id> --jwt-key-file <key> --username <user> --alias my-org
+
+# Verify
+sf org display --target-org my-org
+```
+
+### Troubleshooting ApexGuru Auth
+
+| Issue | Solution |
+|-------|----------|
+| `No default org` | Set default: `sf config set target-org my-org` |
+| `Session expired` | Re-login: `sf org login web --alias my-org` |
+| `Insufficient permissions` | Org needs API access enabled |
+
+## Quick Setup Script
+
+For a complete setup on macOS with Homebrew:
+
+```bash
+# Install all prerequisites
+brew install node@20 openjdk@11 python3
+
+# Set Java environment
+export JAVA_HOME="/opt/homebrew/opt/openjdk@11"
+export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"
+
+# Install Salesforce CLI
+npm install -g @salesforce/cli
+
+# Install Code Analyzer
+sf plugins install @salesforce/plugin-code-analyzer
+
+# Verify everything
+sf --version
+sf plugins --core | grep code-analyzer
+java -version
+node --version
+python3 --version
+```

package/skills/configuring-code-analyzer/references/rule-name-resolution.md

@@ -0,0 +1,67 @@
+# Rule Name Resolution (Fuzzy Matching)
+
+**⚠️ CRITICAL:** The `rules` section in `code-analyzer.yml` requires the EXACT full rule name as it appears in Code Analyzer's rule registry. A misspelled or partial name will be silently ignored — the override won't apply, and no error is shown.
+
+## Why This Matters
+
+Unlike `--rule-selector` (which returns 0 results on mismatch), a wrong name in `code-analyzer.yml` is SILENTLY ignored. The config validates fine, but the override simply doesn't apply. This makes typos and partial names dangerous.
+
+## Common Fuzzy → Exact Mappings
+
+Users will often refer to rules by approximate, partial, or descriptive names:
+
+| User Says | Exact Rule Name | Engine |
+|-----------|----------------|--------|
+| "the ApexDoc rule" | `ApexDoc` | `pmd` |
+| "no-console" | `no-console` | `eslint` |
+| "CRUD violation" | `ApexCRUDViolation` | `pmd` |
+| "hardcoded values" | `@salesforce-ux/slds/no-hardcoded-values-slds2` | `eslint` |
+| "unused variables" | `no-unused-vars` | `eslint` |
+| "soql injection" | `ApexSOQLInjection` | `pmd` |
+| "global modifier" | `AvoidGlobalModifier` | `pmd` |
+| "empty catch" | `EmptyCatchBlock` | `pmd` |
+
+## Lookup Procedure
+
+When you are NOT 100% certain of the exact full rule name:
+
+1. **Do NOT guess** — a wrong name silently fails (the override is ignored with no error)
+2. **Look up the rule first** using the `sf code-analyzer rules` command with grep:
+   ```bash
+   sf code-analyzer rules --rule-selector all 2>&1 | grep -i "<USER_KEYWORD>"
+   ```
+3. **If grep returns exactly one match** → use that exact rule name in the YAML
+4. **If grep returns multiple matches** → present them to the user and ask which one they meant
+5. **If grep returns 0 matches** → try broader keywords or tell the user no rule matched
+
+## When You CAN Skip the Lookup
+
+Skip only when confident in the exact name:
+- User provides the full exact name (e.g., "ApexCRUDViolation", "no-unused-vars")
+- The rule is extremely common AND unambiguous (e.g., "ApexDoc", "no-console")
+
+## Matching Strategies for Ambiguous Input
+
+| User Says | Grep Command | Notes |
+|-----------|-------------|-------|
+| "the doc rule" | `grep -i "doc"` | May match ApexDoc, JSDoc, etc. — ask user if multiple |
+| "CRUD" | `grep -i "crud"` | Likely matches ApexCRUDViolation |
+| "hardcoded" | `grep -i "hardcoded"` | May match multiple SLDS/custom rules |
+| "console" | `grep -i "console"` | Likely matches no-console |
+| "security rules" | Use `--rule-selector all:Security` | Category-based, not name-based |
+| "the injection rule" | `grep -i "injection"` | May match ApexSOQLInjection, ApexXSSFromURLParam, etc. |
+| "unused" | `grep -i "unused"` | May match no-unused-vars, UnusedLocalVariable, etc. |
+
+## Identifying the Engine
+
+The YAML structure requires nesting under the correct engine. Always extract BOTH the engine and rule name from the `sf code-analyzer rules` output:
+
+```yaml
+rules:
+  <engine>:      # ← must match the engine that owns the rule
+    <rule_name>:
+      severity: ...
+      disabled: ...
+```
+
+The output of `sf code-analyzer rules` shows engine name alongside each rule. Use that to determine the correct YAML path.