dx-code-analyzer-configure

# Configuring Code Analyzer Skill ## Overview > **Ecosystem:** This skill is part of a 3-skill Code Analyzer suite — `dx-code-analyzer-run` (scans & results) · `dx-code-analyzer-configure` (setup, config, CI/CD) · `dx-code-analyzer-custom-rule-create` (custom rule authoring). This skill manages the `code-analyzer.yml` configuration file — the single source of truth for how Code Analyzer behaves in a project. All customization (engines, rules, ignores, suppressions) is done by creating or editing this file. If the file doesn't exist, this skill creates it in the current working directory. --- ## Scope **In scope:** - Checking prerequisites (sf CLI, Java, Node.js, Python, org auth) - Installing/updating the Code Analyzer plugin - Creating `code-analyzer.yml` if it doesn't exist - Editing `code-analyzer.yml` for all configuration changes - Engine settings, rule overrides, ignore patterns, suppressions - CI/CD pipeline setup (GitHub Actions, Jenkins, etc.) - Environment validation and troubleshooting **Out of scope:** - Running scans → use `dx-code-analyzer-run` skill - Fixing violations, explaining rules, suppression management → use `dx-code-analyzer-run` skill - Creating custom rules → use `dx-code-analyzer-custom-rule-create` skill --- ## Tool Usage Rules **Allowed:** Bash (sf, java, node, python3, npm), Read, Write, Edit **Forbidden:** MCP tools, Agent tool, Web tools, other skills, `which`, `find`, `locate`, searching for binaries --- ## Core Principle: YAML Only When Customizing Code Analyzer works out of the box with NO config file — all defaults are built into the tool. The `code-analyzer.yml` file is ONLY created when the user explicitly requests a customization. **Rules:** - **Do NOT create `code-analyzer.yml` proactively** — only when user asks to change something - **Do NOT duplicate built-in defaults** — only write entries that intentionally override behavior - **Always place at project root** — where `sfdx-project.json` or `sf-project.json` lives - **The CLI auto-discovers it** — `sf code-analyzer run` from project root automatically picks up `code-analyzer.yml` in that directory. No `--config-file` flag needed. - User says "configure code analyzer" with no specifics? → **Ask what they want to customize**. Don't create an empty or boilerplate file. **Workflow:** 1. User requests a customization (e.g., "disable PMD", "ignore test files", "increase SFGE memory") 2. Check if `code-analyzer.yml` exists at project root 3. If NO → create it at project root with ONLY the requested override 4. If YES → read it, then edit in the requested change 5. Validate with `sf code-analyzer config` --- ## Step 1: Understand Intent and Map to Config Sections The user can request ANY combination of configuration changes in natural language. Your job is to: 1. **Parse what they want** — may be one thing or many things combined 2. **Map each request to the correct section(s) of `code-analyzer.yml`** 3. **Create the file if it doesn't exist, then apply all changes** ### The `code-analyzer.yml` Structure (what you can write/edit) ```yaml config_root: . # Root for relative path resolution log_folder: <path> # Where logs are written log_level: <1-5> # 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Fine ignores: # Files/folders excluded from scanning files: [<glob patterns>] engines: # Per-engine settings <engine_name>: disable_engine: <bool> <engine_specific_keys>: ... rules: # Per-rule overrides <engine_name>: <rule_name>: severity: <1-5> tags: [<strings>] disabled: <bool> suppressions: # Bulk suppression configuration disable_suppressions: <bool> "<file_or_folder_path>": - rule_selector: "<selector>" max_suppressed_violations: <number|null> reason: "<why>" ``` ### Mapping Principle Any user request maps to one or more sections above. Parse the intent and edit the right section(s): | Intent Category | Maps To | Examples of What User Might Say | |----------------|---------|-------------------------------| | Setup / Install | Step 2 (prerequisites + install) | "set up", "install", "get started", "new laptop", "from scratch" | | **Diagnose / Fix** | **Step 2A (systematic debug)** | **"not working", "broken", "fix my setup", "scan fails", "getting errors"** | | Engine control | `engines.<name>.disable_engine` | "disable X", "turn off Y", "only use Z", "enable all" | | Engine tuning | `engines.<name>.<property>` | "increase memory", "change heap", "use my eslint config", "set tokens to 50" | | File exclusions | `ignores.files` | "exclude", "ignore", "skip", "don't scan X" | | Rule severity | `rules.<engine>.<rule>.severity` | "make X critical", "promote", "demote", "change severity" | | Rule disable | `rules.<engine>.<rule>.disabled` | "disable rule X", "turn off Y rule", "remove Z" | | Rule tags | `rules.<engine>.<rule>.tags` | "tag X as security", "add recommended tag" | | Suppressions | `suppressions` section | "suppress X in folder Y", "allow N violations" | | CI/CD | Generate pipeline file (separate from config) | "github actions", "CI", "quality gate" | | View/inspect | Read file + `sf code-analyzer config` | "show config", "what's configured", "current settings" | ### File Existence Decision **BEFORE editing anything**, check if `code-analyzer.yml` exists at project root: ```bash ls code-analyzer.yml code-analyzer.yaml 2>/dev/null ``` - **File does NOT exist** → Create it at project root with ONLY the user's requested override(s) - **File exists** → Read it, then Edit to add/modify the requested section(s) The CLI auto-discovers `code-analyzer.yml` in the current directory. Since scans run from project root, the file must live there. ### Rule Name Resolution — ALWAYS Before Writing YAML When a user references rules by partial, descriptive, or approximate names (e.g., "the doc rule", "CRUD violation", "console rule", "hardcoded values"), you MUST resolve to exact rule names using the lookup in **Step 6.1** BEFORE writing any YAML. The `code-analyzer.yml` file silently ignores rule names that don't exactly match — there is no error, the override just won't apply. **Examples of fuzzy → exact resolution needed:** - "Disable the ApexDoc rule" → lookup confirms `ApexDoc` (engine: `pmd`) - "Demote no-console to low" → lookup confirms `no-console` (engine: `eslint`) - "Make CRUD violations critical" → lookup confirms `ApexCRUDViolation` (engine: `pmd`) - "Turn off the hardcoded values check" → lookup finds `@salesforce-ux/slds/no-hardcoded-values-slds2` (engine: `eslint`) - "Disable the injection rule" → multiple matches possible → ask user which one **Only skip the lookup** when the user provides an unambiguous, exact, well-known name (e.g., "ApexDoc", "no-console", "no-unused-vars"). ### Handling Combined/Complex Requests Users will often combine multiple changes in one request. Handle ALL of them in a single edit: - "Disable PMD's ApexDoc rule and make CRUD violations critical" → edit two entries under `rules.pmd` - "Exclude test files and vendor code, and increase SFGE memory" → edit `ignores.files` + `engines.sfge.java_max_heap_size` - "Set up code analyzer with only ESLint and PMD, ignore node_modules" → create file with `engines` (disable others) + `ignores` - "Make all security rules severity 1" → look up rules via `sf code-analyzer rules --rule-selector Security`, then override each - "Configure code analyzer" (no specifics) → ask user what they want to customize before creating any file ### Quick Reference: Common Requests → Config Output | User Says | Resulting YAML | |-----------|---------------| | "configure code analyzer" | Ask user what to customize — don't create file until there's an actual override | | "disable the ApexDoc rule" | `rules: pmd: ApexDoc: disabled: true` | | "only scan Apex, no JavaScript" | `engines: eslint: disable_engine: true` + `engines: retire-js: disable_engine: true` | | "ignore all test files" | `ignores: files: ["**/test/**", "**/__tests__/**", "**/*.test.js"]` | | "make security rules critical" | Look up rules, then `rules: <engine>: <rule>: severity: 1` for each | | "increase SFGE memory to 8g" | `engines: sfge: java_max_heap_size: "8g"` | | "use my project's ESLint config" | `engines: eslint: auto_discover_eslint_config: true` | | "suppress CRUD violations in legacy folder" | `suppressions: "force-app/legacy/": [{rule_selector: "pmd:ApexCRUDViolation", reason: "..."}]` | **The AI must understand the YAML schema and write valid config for ANY request, not just the examples above.** --- ## Step 2: Check Prerequisites and Install Run `bash "<skill_dir>/scripts/check-prerequisites.sh"` or check manually: ```bash sf --version 2>&1 # sf CLI sf plugins --core 2>&1 | grep -i "code-analyzer" # Plugin java -version 2>&1 # Java 11+ (PMD, CPD, SFGE) node --version 2>&1 # Node 18+ (ESLint, RetireJS) python3 --version 2>&1 # Python 3 (Flow engine) ``` If anything is missing, install it (**always ask user first**): ```bash npm install -g @salesforce/cli # sf CLI sf plugins install @salesforce/plugin-code-analyzer # Code Analyzer plugin ``` For Java/Node/Python installs, read `<skill_dir>/references/engine-prerequisites.md`. If install fails, read `<skill_dir>/references/troubleshooting.md`. --- ## Step 2A: Diagnose and Fix a Broken Setup **TRIGGER:** User says "not working", "broken", "getting errors", "scan fails", "help me fix", etc. **Read `<skill_dir>/references/diagnostic-flow.md`** for the complete layered diagnostic procedure, fix table, and anti-patterns. **Key principles (always apply):** - Never search for binaries (`which`, `find`, `ls /opt/homebrew/bin/`) - Never use `sfdx` as a workaround — only `sf` - Fix layer by layer: CLI → Plugin → Engine deps → verify scan - Give user ONE command at a time, wait for confirmation before continuing - After fix succeeds, proceed to run the full scan automatically --- ## Step 3: Create or Edit `code-analyzer.yml` **Only triggered when user requests a customization.** Never create proactively. ### Creating (file doesn't exist) Choose **one** of the two approaches below — do not run both: **Option A — Auto-generate from project type (recommended for first-time setup):** Run `bash "<skill_dir>/scripts/generate-config.sh"`. This detects Apex, LWC, and Flow markers and produces a minimal `code-analyzer.yml` suited to the project. Skip to the "After any create/edit, validate" section. > Note: The script exits with an error if `code-analyzer.yml` already exists. Delete the existing file first if you need to regenerate. **Option B — Write manually (when the user has specific customizations in mind):** Read the appropriate example config as a reference for structure: - For Apex-only projects, read `<skill_dir>/examples/apex-project-config.yml` - For LWC-only projects, read `<skill_dir>/examples/lwc-project-config.yml` - For full-stack (Apex + LWC + Flows), read `<skill_dir>/examples/fullstack-project-config.yml` Write the file at project root using the Write tool. Include ONLY the user's requested changes: ```bash # Example: user said "ignore test files and increase SFGE memory" # → Write to project root (where sfdx-project.json lives): ``` ```yaml ignores: files: - "**/test/**" - "**/__tests__/**" engines: sfge: java_max_heap_size: "4g" ``` Do NOT add `config_root`, `log_folder`, or any other field the user didn't ask for. ### Editing (file already exists) Read the file, then use the Edit tool to add/modify only the relevant section. Preserve everything else. ### After any create/edit, validate: Run `bash "<skill_dir>/scripts/validate-config.sh"` to validate YAML syntax and schema correctness, or use the CLI directly: ```bash sf code-analyzer config ``` (No `--config-file` needed — the CLI auto-discovers `code-analyzer.yml` in CWD.) ### If user says "configure code analyzer" with no specifics Ask: "What would you like to customize? For example: ignore certain files, change rule severities, tune engine settings, or disable engines you don't need." --- ## Step 4: Enable/Disable Engines Edit the `engines` section in `code-analyzer.yml`: ```yaml engines: pmd: disable_engine: true # Disable PMD eslint: disable_engine: false # Enable ESLint (default) ``` Valid engine names: `pmd`, `cpd`, `eslint`, `regex`, `retire-js`, `flow`, `sfge`, `apexguru` **Always validate after editing:** ```bash sf code-analyzer config --config-file code-analyzer.yml ``` --- ## Step 5: Ignore Patterns Edit the `ignores` section in `code-analyzer.yml`: ```yaml ignores: files: - "**/node_modules/**" - "**/.sfdx/**" - "**/.sf/**" - "**/vendor/**"