@salesforce/afv-skills 1.22.0 → 1.24.0

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

@@ -1,257 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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

@@ -1,276 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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.