@salesforce/afv-skills 1.17.0 → 1.18.0

package/skills/configuring-code-analyzer/references/troubleshooting.md

@@ -0,0 +1,298 @@
+# Troubleshooting Code Analyzer Setup
+
+Common issues and solutions during installation and configuration.
+
+## Installation Issues
+
+### sf CLI Not Found
+
+**Symptom:** `sf: command not found` or `'sf' is not recognized`
+
+**Solutions:**
+1. Check if installed: `which sf` or `where sf`
+2. If not installed: `npm install -g @salesforce/cli`
+3. If installed but not in PATH:
+   - macOS/Linux: Add `export PATH="$(npm prefix -g)/bin:$PATH"` to `~/.zshrc` or `~/.bashrc`
+   - Windows: Add npm global bin to System PATH
+4. Restart terminal after PATH changes
+
+### Plugin Install Fails
+
+**Symptom:** `Error: EACCES permission denied` or timeout errors
+
+**Solutions:**
+| Error | Fix |
+|-------|-----|
+| Permission denied | `sudo sf plugins install @salesforce/plugin-code-analyzer` or fix npm permissions |
+| Network timeout | Check proxy: `npm config set proxy http://proxy:port` |
+| Node version error | Upgrade Node.js to 18+: `nvm install 20 && nvm use 20` |
+| Corrupt install | `sf plugins uninstall @salesforce/plugin-code-analyzer && sf plugins install @salesforce/plugin-code-analyzer` |
+
+### Plugin Version Mismatch
+
+**Symptom:** Command flags don't work, unexpected behavior
+
+**Check version:**
+```bash
+sf plugins --core | grep code-analyzer
+```
+
+**Expected:** `@salesforce/plugin-code-analyzer` v5.x+
+
+**If on v3/v4 (legacy):**
+```bash
+sf plugins uninstall @salesforce/sfdx-scanner  # Remove legacy v3
+sf plugins install @salesforce/plugin-code-analyzer  # Install v5+
+```
+
+## Java Issues
+
+### Java Not Found
+
+**Symptom:** PMD/CPD/SFGE fails with `java: command not found` or `JAVA_HOME not set`
+
+**Fix:**
+```bash
+# macOS
+brew install openjdk@11
+export JAVA_HOME="/opt/homebrew/opt/openjdk@11"
+export PATH="$JAVA_HOME/bin:$PATH"
+
+# Add to ~/.zshrc for persistence
+echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@11"' >> ~/.zshrc
+echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
+```
+
+### Wrong Java Version
+
+**Symptom:** `UnsupportedClassVersionError` or `class file version X.Y`
+
+**Fix:** Code Analyzer needs Java 11+. Check and switch:
+```bash
+java -version  # Check current
+
+# If using SDKMAN:
+sdk install java 11.0.21-tem
+sdk use java 11.0.21-tem
+
+# If using Homebrew:
+brew install openjdk@11
+export JAVA_HOME="/opt/homebrew/opt/openjdk@11"
+```
+
+### SFGE Out of Memory
+
+**Symptom:** `java.lang.OutOfMemoryError: Java heap space`
+
+**Fix:** Increase heap in `code-analyzer.yml`:
+```yaml
+engines:
+  sfge:
+    java_max_heap_size: "4g"  # Default is 1g, increase for large projects
+```
+
+**Guidelines:**
+| Project Size | Heap Recommendation |
+|-------------|-------------------|
+| < 200 Apex classes | 2g |
+| 200-500 Apex classes | 4g |
+| 500-1000 Apex classes | 6g |
+| 1000+ Apex classes | 8g |
+
+## Node.js Issues
+
+### Node.js Version Too Old
+
+**Symptom:** `Error: Node.js v16 is not supported` or ESLint failures
+
+**Fix:**
+```bash
+# Check version
+node --version
+
+# Upgrade via nvm
+nvm install 20
+nvm use 20
+nvm alias default 20
+
+# Or via Homebrew
+brew upgrade node
+```
+
+### ESLint Config Conflicts
+
+**Symptom:** ESLint rules not loading, or unexpected rules appearing
+
+**Possible causes:**
+1. Project has its own `.eslintrc.*` conflicting with Code Analyzer's built-in config
+2. `auto_discover_eslint_config` is enabled but project config is incompatible
+
+**Fix options:**
+```yaml
+# Option A: Disable auto-discovery (use only Code Analyzer's built-in rules)
+engines:
+  eslint:
+    auto_discover_eslint_config: false
+
+# Option B: Use project's config exclusively
+engines:
+  eslint:
+    auto_discover_eslint_config: true
+    disable_javascript_base_config: true
+    disable_typescript_base_config: true
+    disable_lwc_base_config: true
+```
+
+## Configuration Issues
+
+### Config File Not Picked Up
+
+**Symptom:** Custom settings not applied, default behavior persists
+
+**Checklist:**
+1. File must be named exactly `code-analyzer.yml` or `code-analyzer.yaml`
+2. File must be in the current working directory when running commands
+3. Or specify explicitly: `--config-file ./path/to/code-analyzer.yml`
+4. Check for YAML syntax errors: `sf code-analyzer config --config-file code-analyzer.yml`
+
+### YAML Syntax Errors
+
+**Symptom:** `YAMLException: bad indentation` or `unexpected token`
+
+**Common YAML mistakes:**
+```yaml
+# WRONG - tabs instead of spaces
+engines:
+	pmd:           # TAB character - YAML requires spaces!
+
+# CORRECT - spaces only
+engines:
+  pmd:             # 2 spaces
+
+# WRONG - missing quotes around special values
+rules:
+  pmd:
+    MyRule:
+      severity: High    # String values need quotes or use numbers
+
+# CORRECT
+rules:
+  pmd:
+    MyRule:
+      severity: 2       # Use numbers 1-5
+      # OR
+      severity: "High"  # Or quoted strings
+```
+
+### Unknown Engine or Rule Name
+
+**Symptom:** Rule selector returns 0 results
+
+**Fix:** Verify the engine/rule name:
+```bash
+# List all available engines
+sf code-analyzer rules --rule-selector all 2>&1 | head -50
+
+# Search for a specific rule
+sf code-analyzer rules --rule-selector all 2>&1 | grep -i "CRUD"
+
+# List rules for specific engine
+sf code-analyzer rules --rule-selector pmd 2>&1 | head -50
+```
+
+## Engine-Specific Issues
+
+### PMD: Custom Rules Not Loading
+
+**Symptom:** Custom PMD rules don't appear in `sf code-analyzer rules`
+
+**Checklist:**
+1. Ruleset XML must be valid PMD format
+2. Path in `custom_rulesets` must be relative to `config_root`
+3. For Java rules: JAR must be in `java_classpath_entries`
+4. Validate: `sf code-analyzer rules --rule-selector pmd:<YourRuleName>`
+
+### RetireJS: False Positives on Test Files
+
+**Symptom:** RetireJS flags test fixtures or mock data
+
+**Fix:** Add test paths to ignores:
+```yaml
+ignores:
+  files:
+    - "**/test/**"
+    - "**/__tests__/**"
+    - "**/jest-mocks/**"
+    - "**/*.test.js"
+    - "**/*.spec.js"
+```
+
+### Flow Engine: Python Not Found
+
+**Symptom:** `python3: command not found` when scanning Flows
+
+**Fix:**
+```bash
+# Install Python 3
+brew install python3  # macOS
+# OR
+sudo apt install python3  # Linux
+
+# If python3 is at non-standard path:
+# code-analyzer.yml
+engines:
+  flow:
+    python_command: "/usr/local/bin/python3"
+```
+
+### ApexGuru: Authentication Error
+
+**Symptom:** `No authenticated org found` or `Session expired`
+
+**Fix:**
+```bash
+# Login to org
+sf org login web --alias my-org
+
+# Set as default
+sf config set target-org my-org
+
+# Configure in code-analyzer.yml
+engines:
+  apexguru:
+    target_org: "my-org"
+```
+
+## Performance Issues
+
+### Scan Takes Too Long
+
+**Possible causes and solutions:**
+
+| Cause | Solution |
+|-------|----------|
+| SFGE on large project | Increase heap, reduce thread timeout, or disable SFGE for routine scans |
+| Scanning node_modules | Add `**/node_modules/**` to ignores |
+| Too many engines enabled | Use `--rule-selector Recommended` instead of `all` for routine scans |
+| Large static resources | Add `**/staticresources/**` to ignores |
+| Many Flow files | Flow engine can be slow; scan Flows separately |
+
+### Reduce Scan Time in CI
+
+```yaml
+# Fast CI scan: recommended rules only, severity gate at High
+sf code-analyzer run \
+  --rule-selector Recommended \
+  --severity-threshold 2 \
+  --target force-app/main/default \
+  --output-file results.json
+```
+
+## Getting Help
+
+If none of the above solves your issue:
+
+1. **Check logs:** Look in the log folder (default: `/tmp` or configured `log_folder`)
+2. **Increase log level:** Set `log_level: 5` in config for maximum detail
+3. **Run with debug:** `SF_LOG_LEVEL=debug sf code-analyzer run ...`
+4. **File an issue:** https://github.com/forcedotcom/code-analyzer-core/issues

package/skills/configuring-code-analyzer/scripts/check-prerequisites.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# check-prerequisites.sh
+# Checks all Code Analyzer prerequisites and reports status.
+# Usage: bash <skill_dir>/scripts/check-prerequisites.sh
+#
+# Exit codes:
+#   0 = All prerequisites met
+#   1 = Some prerequisites missing (details in output)
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m' # No Color
+
+PASS="${GREEN}PASS${NC}"
+FAIL="${RED}FAIL${NC}"
+WARN="${YELLOW}WARN${NC}"
+
+MISSING_COUNT=0
+WARNINGS_COUNT=0
+
+echo "========================================="
+echo "  Code Analyzer Prerequisites Check"
+echo "========================================="
+echo ""
+
+# --- Check sf CLI ---
+echo -n "Salesforce CLI (sf): "
+if command -v sf &> /dev/null; then
+    SF_VERSION=$(sf --version 2>&1 | head -1)
+    echo -e "${PASS} - ${SF_VERSION}"
+else
+    echo -e "${FAIL} - Not installed"
+    echo "  Install: npm install -g @salesforce/cli"
+    MISSING_COUNT=$((MISSING_COUNT + 1))
+fi
+
+# --- Check Code Analyzer Plugin ---
+echo -n "Code Analyzer plugin: "
+if command -v sf &> /dev/null; then
+    CA_VERSION=$(sf plugins --core 2>&1 | grep -i "code-analyzer" | head -1)
+    if [ -n "$CA_VERSION" ]; then
+        echo -e "${PASS} - ${CA_VERSION}"
+    else
+        echo -e "${FAIL} - Not installed"
+        echo "  Install: sf plugins install @salesforce/plugin-code-analyzer"
+        MISSING_COUNT=$((MISSING_COUNT + 1))
+    fi
+else
+    echo -e "${FAIL} - Cannot check (sf CLI missing)"
+    MISSING_COUNT=$((MISSING_COUNT + 1))
+fi
+
+# --- Check Java ---
+echo -n "Java 11+ (PMD, CPD, SFGE): "
+if command -v java &> /dev/null; then
+    JAVA_VERSION=$(java -version 2>&1 | head -1)
+    # Extract major version number
+    JAVA_MAJOR=$(java -version 2>&1 | head -1 | sed -E 's/.*"([0-9]+)\..*/\1/')
+    if [ "$JAVA_MAJOR" -ge 11 ] 2>/dev/null; then
+        echo -e "${PASS} - ${JAVA_VERSION}"
+    else
+        echo -e "${WARN} - ${JAVA_VERSION} (need 11+)"
+        echo "  Upgrade: brew install openjdk@11"
+        WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
+    fi
+else
+    echo -e "${FAIL} - Not installed"
+    echo "  Install: brew install openjdk@11 (macOS) / sdk install java 11.0.x-tem"
+    echo "  Needed for: PMD, CPD, SFGE engines"
+    MISSING_COUNT=$((MISSING_COUNT + 1))
+fi
+
+# --- Check JAVA_HOME ---
+echo -n "JAVA_HOME: "
+if [ -n "${JAVA_HOME:-}" ]; then
+    echo -e "${PASS} - ${JAVA_HOME}"
+else
+    echo -e "${WARN} - Not set (may cause issues with some Java installations)"
+    WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
+fi
+
+# --- Check Node.js ---
+echo -n "Node.js 18+ (ESLint, RetireJS): "
+if command -v node &> /dev/null; then
+    NODE_VERSION=$(node --version 2>&1)
+    NODE_MAJOR=$(echo "$NODE_VERSION" | sed -E 's/v([0-9]+)\..*/\1/')
+    if [ "$NODE_MAJOR" -ge 18 ] 2>/dev/null; then
+        echo -e "${PASS} - ${NODE_VERSION}"
+    else
+        echo -e "${WARN} - ${NODE_VERSION} (need 18+)"
+        echo "  Upgrade: nvm install 20 && nvm use 20"
+        WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
+    fi
+else
+    echo -e "${FAIL} - Not installed"
+    echo "  Install: brew install node@20 (macOS) / nvm install 20"
+    echo "  Needed for: ESLint, RetireJS engines"
+    MISSING_COUNT=$((MISSING_COUNT + 1))
+fi
+
+# --- Check Python 3 ---
+echo -n "Python 3 (Flow engine): "
+if command -v python3 &> /dev/null; then
+    PY_VERSION=$(python3 --version 2>&1)
+    echo -e "${PASS} - ${PY_VERSION}"
+else
+    echo -e "${WARN} - Not installed (only needed for Flow scanning)"
+    echo "  Install: brew install python3 (macOS) / apt install python3 (Linux)"
+    echo "  Needed for: Flow engine only"
+    WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
+fi
+
+# --- Check authenticated org ---
+echo -n "Authenticated Org (ApexGuru): "
+if command -v sf &> /dev/null; then
+    ORG_INFO=$(sf org display 2>&1)
+    if echo "$ORG_INFO" | grep -qi "username\|access token"; then
+        ORG_USER=$(echo "$ORG_INFO" | grep -i "username" | head -1 | awk '{print $NF}')
+        echo -e "${PASS} - ${ORG_USER}"
+    else
+        echo -e "${WARN} - No default org (only needed for ApexGuru)"
+        echo "  Login: sf org login web --alias my-org"
+        WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
+    fi
+else
+    echo -e "${WARN} - Cannot check (sf CLI missing)"
+    WARNINGS_COUNT=$((WARNINGS_COUNT + 1))
+fi
+
+# --- Check for existing config ---
+echo ""
+echo "-----------------------------------------"
+echo -n "Config file (code-analyzer.yml): "
+if [ -f "code-analyzer.yml" ] || [ -f "code-analyzer.yaml" ]; then
+    CONFIG_FILE=$(ls code-analyzer.yml code-analyzer.yaml 2>/dev/null | head -1)
+    echo -e "${PASS} - Found: ${CONFIG_FILE}"
+else
+    echo -e "${WARN} - Not found (will use defaults)"
+    echo "  Generate: sf code-analyzer config --output-file code-analyzer.yml"
+fi
+
+# --- Check project type ---
+echo -n "Project type: "
+HAS_APEX=false
+HAS_LWC=false
+HAS_FLOWS=false
+HAS_SFDX=false
+
+[ -d "force-app" ] && HAS_APEX=true
+find . -maxdepth 4 -path "*/lwc/*" -name "*.js" 2>/dev/null | head -1 | grep -q . && HAS_LWC=true
+find . -maxdepth 4 -name "*.flow-meta.xml" 2>/dev/null | head -1 | grep -q . && HAS_FLOWS=true
+[ -f "sfdx-project.json" ] || [ -f "sf-project.json" ] && HAS_SFDX=true
+
+PROJECT_TYPES=""
+[ "$HAS_APEX" = true ] && PROJECT_TYPES="${PROJECT_TYPES}Apex, "
+[ "$HAS_LWC" = true ] && PROJECT_TYPES="${PROJECT_TYPES}LWC, "
+[ "$HAS_FLOWS" = true ] && PROJECT_TYPES="${PROJECT_TYPES}Flows, "
+[ "$HAS_SFDX" = true ] && PROJECT_TYPES="${PROJECT_TYPES}SFDX Project, "
+
+if [ -n "$PROJECT_TYPES" ]; then
+    echo "${PROJECT_TYPES%, }"
+else
+    echo "Unknown (no Salesforce project markers found)"
+fi
+
+# --- Summary ---
+echo ""
+echo "========================================="
+echo "  Summary"
+echo "========================================="
+
+if [ $MISSING_COUNT -eq 0 ] && [ $WARNINGS_COUNT -eq 0 ]; then
+    echo -e "${GREEN}All prerequisites met! Ready to scan.${NC}"
+    exit 0
+elif [ $MISSING_COUNT -eq 0 ]; then
+    echo -e "${YELLOW}${WARNINGS_COUNT} warning(s) - some engines may not work.${NC}"
+    echo "Core functionality (PMD, ESLint) should work if Java and Node.js are available."
+    exit 0
+else
+    echo -e "${RED}${MISSING_COUNT} required prerequisite(s) missing.${NC}"
+    [ $WARNINGS_COUNT -gt 0 ] && echo -e "${YELLOW}${WARNINGS_COUNT} additional warning(s).${NC}"
+    echo ""
+    echo "Install missing prerequisites before running Code Analyzer."
+    exit 1
+fi

package/skills/configuring-code-analyzer/scripts/generate-config.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# generate-config.sh
+# Generates a code-analyzer.yml with ONLY project-specific overrides.
+# Does NOT duplicate built-in defaults — only writes what intentionally differs.
+#
+# Usage: bash <skill_dir>/scripts/generate-config.sh [--type apex|lwc|fullstack]
+#
+# If --type is not specified, auto-detects from workspace contents.
+
+set -euo pipefail
+
+CONFIG_FILE="code-analyzer.yml"
+PROJECT_TYPE="${1:-auto}"
+
+# Remove --type prefix if present
+PROJECT_TYPE="${PROJECT_TYPE#--type=}"
+PROJECT_TYPE="${PROJECT_TYPE#--type }"
+
+# Auto-detect project type
+if [ "$PROJECT_TYPE" = "auto" ] || [ "$PROJECT_TYPE" = "" ]; then
+    HAS_APEX=false
+    HAS_LWC=false
+    HAS_NODE_MODULES=false
+
+    [ -d "force-app" ] && HAS_APEX=true
+    find . -maxdepth 4 -path "*/lwc/*" -name "*.js" 2>/dev/null | head -1 | grep -q . && HAS_LWC=true
+    [ -d "node_modules" ] && HAS_NODE_MODULES=true
+
+    if [ "$HAS_APEX" = true ] && [ "$HAS_LWC" = true ]; then
+        PROJECT_TYPE="fullstack"
+    elif [ "$HAS_LWC" = true ]; then
+        PROJECT_TYPE="lwc"
+    elif [ "$HAS_APEX" = true ]; then
+        PROJECT_TYPE="apex"
+    else
+        PROJECT_TYPE="minimal"
+    fi
+
+    echo "Auto-detected project type: ${PROJECT_TYPE}"
+
+    # Warn if no Salesforce project markers found
+    if [ "$PROJECT_TYPE" = "minimal" ] && [ ! -f "sfdx-project.json" ] && [ ! -f "sf-project.json" ]; then
+        echo "WARNING: No Salesforce project markers found (no sfdx-project.json, sf-project.json, or force-app/)."
+        echo "         Are you running this from your project root?"
+        echo "         Generating minimal config — re-run from project root for better detection."
+    fi
+fi
+
+# Check if config already exists
+if [ -f "$CONFIG_FILE" ] || [ -f "code-analyzer.yaml" ]; then
+    echo "WARNING: Config file already exists."
+    echo "Edit the existing file instead of regenerating."
+    exit 1
+fi
+
+echo "Generating ${CONFIG_FILE} (overrides only)..."
+
+case "$PROJECT_TYPE" in
+    apex)
+        cat > "$CONFIG_FILE" << 'YAML'
+# Code Analyzer overrides for Apex project
+# Only entries that differ from built-in defaults
+
+ignores:
+  files:
+    - "**/node_modules/**"
+    - "**/.sfdx/**"
+    - "**/.sf/**"
+
+engines:
+  sfge:
+    java_max_heap_size: "4g"
+YAML
+        ;;
+
+    lwc)
+        cat > "$CONFIG_FILE" << 'YAML'
+# Code Analyzer overrides for LWC project
+# Only entries that differ from built-in defaults
+
+ignores:
+  files:
+    - "**/node_modules/**"
+    - "**/.sfdx/**"
+    - "**/.sf/**"
+    - "**/jest-mocks/**"
+    - "**/__tests__/**"
+
+engines:
+  eslint:
+    auto_discover_eslint_config: true
+YAML
+        ;;
+
+    fullstack)
+        cat > "$CONFIG_FILE" << 'YAML'
+# Code Analyzer overrides for full-stack Salesforce project
+# Only entries that differ from built-in defaults
+
+ignores:
+  files:
+    - "**/node_modules/**"
+    - "**/.sfdx/**"
+    - "**/.sf/**"
+    - "**/jest-mocks/**"
+    - "**/__tests__/**"
+
+engines:
+  sfge:
+    java_max_heap_size: "4g"
+  eslint:
+    auto_discover_eslint_config: true
+YAML
+        ;;
+
+    minimal)
+        cat > "$CONFIG_FILE" << 'YAML'
+# Code Analyzer overrides
+# Only entries that differ from built-in defaults
+
+ignores:
+  files:
+    - "**/node_modules/**"
+YAML
+        ;;
+
+    *)
+        echo "ERROR: Unknown project type: ${PROJECT_TYPE}"
+        echo "Valid types: apex, lwc, fullstack, minimal"
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "Created: ${CONFIG_FILE}"
+echo ""
+echo "This file contains ONLY overrides — built-in defaults still apply for"
+echo "everything not listed here. Add more overrides as needed."
+echo ""
+echo "Next steps:"
+echo "  1. Review: cat ${CONFIG_FILE}"
+echo "  2. Validate: sf code-analyzer config --config-file ${CONFIG_FILE}"
+echo "  3. Run scan: sf code-analyzer run --output-file results.json --include-fixes"