Terminal
Terminal/Skill
Sets up Salesforce Code Analyzer, edits its code-analyzer.yml overrides, and adds it to CI pipelines such as GitHub Actions.
By Salesforce
Works with
npx skills add forcedotcom/sf-skills --skill dx-code-analyzer-configureEcosystem: 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.
In scope:
code-analyzer.yml if it doesn't existcode-analyzer.yml for all configuration changesOut of scope:
dx-code-analyzer-run skilldx-code-analyzer-run skilldx-code-analyzer-custom-rule-create skillAllowed: Bash (sf, java, node, python3, npm), Read, Write, Edit
Forbidden: MCP tools, Agent tool, Web tools, other skills, which, find, locate, searching for binaries
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:
code-analyzer.yml proactively — only when user asks to change somethingsfdx-project.json or sf-project.json livessf code-analyzer run from project root automatically picks up code-analyzer.yml in that directory. No --config-file flag needed.Workflow:
code-analyzer.yml exists at project rootsf code-analyzer configThe user can request ANY combination of configuration changes in natural language. Your job is to:
code-analyzer.ymlcode-analyzer.yml Structure (what you can write/edit)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>"
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" |
BEFORE editing anything, check if code-analyzer.yml exists at project root:
ls code-analyzer.yml code-analyzer.yaml 2>/dev/null
The CLI auto-discovers code-analyzer.yml in the current directory. Since scans run from project root, the file must live there.
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:
ApexDoc (engine: pmd)no-console (engine: eslint)ApexCRUDViolation (engine: pmd)@salesforce-ux/slds/no-hardcoded-values-slds2 (engine: eslint)Only skip the lookup when the user provides an unambiguous, exact, well-known name (e.g., "ApexDoc", "no-console", "no-unused-vars").
Users will often combine multiple changes in one request. Handle ALL of them in a single edit:
rules.pmdignores.files + engines.sfge.java_max_heap_sizeengines (disable others) + ignoressf code-analyzer rules --rule-selector Security, then override each| 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.
Run bash "<skill_dir>/scripts/check-prerequisites.sh" or check manually:
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):
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.
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):
which, find, ls /opt/homebrew/bin/)sfdx as a workaround — only sfcode-analyzer.ymlOnly triggered when user requests a customization. Never create proactively.
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.ymlalready 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:
<skill_dir>/examples/apex-project-config.yml<skill_dir>/examples/lwc-project-config.yml<skill_dir>/examples/fullstack-project-config.ymlWrite the file at project root using the Write tool. Include ONLY the user's requested changes:
# Example: user said "ignore test files and increase SFGE memory"
# → Write to project root (where sfdx-project.json lives):
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.
Read the file, then use the Edit tool to add/modify only the relevant section. Preserve everything else.
Run bash "<skill_dir>/scripts/validate-config.sh" to validate YAML syntax and schema correctness, or use the CLI directly:
sf code-analyzer config
(No --config-file needed — the CLI auto-discovers code-analyzer.yml in CWD.)
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."
Edit the engines section in code-analyzer.yml:
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:
sf code-analyzer config --config-file code-analyzer.yml
Edit the ignores section in code-analyzer.yml:
ignores:
files:
- "**/node_modules/**"
- "**/.sfdx/**"
- "**/.sf/**"
- "**/vendor/**"
- "**/*.min.js"
Common patterns:
| Pattern | Excludes |
|---|---|
**/node_modules/** | npm dependencies |
**/.sfdx/**, **/.sf/** | SF CLI internals |
**/test/**, **/__tests__/** | Test directories |
**/*.test.js, **/*.spec.js | Test files |
**/jest-mocks/** | Jest mocks |
**/vendor/**, **/*.min.js | Third-party/minified |
**/staticresources/** | Static resources |
Edit the rules section in code-analyzer.yml. Each rule can have severity, tags, and disabled overrides:
rules:
pmd:
ApexCRUDViolation:
severity: 1 # Promote to Critical
AvoidGlobalModifier:
disabled: true # Turn off 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
Severity values: 1/Critical, 2/High, 3/Moderate, 4/Low, 5/Info
CRITICAL: A misspelled or partial rule name in code-analyzer.yml is SILENTLY IGNORED — no error, the override just won't apply.
When users reference rules by approximate names (e.g., "the doc rule", "CRUD violation", "hardcoded values"), resolve to exact names BEFORE writing YAML:
sf code-analyzer rules --rule-selector all 2>&1 | grep -i "<USER_KEYWORD>"
Skip the lookup only when the name is unambiguous and exact (e.g., "ApexDoc", "no-console", "no-unused-vars").
For detailed matching strategies, common fuzzy→exact mappings, and engine identification: Read <skill_dir>/references/rule-name-resolution.md.
Edit the engines section. Most common overrides:
engines:
sfge:
java_max_heap_size: "4g" # <200 classes→"2g", 200-500→"4g", 500+→"6g"/"8g"
java_thread_count: 4
java_thread_timeout: 900000
eslint:
auto_discover_eslint_config: true # Use project's own ESLint config
eslint_config_file: "./eslint.config.mjs"
pmd:
custom_rulesets: ["./config/custom-pmd-rules.xml"]
java_classpath_entries: ["./lib/custom-rules.jar"]
cpd:
minimum_tokens: { apex: 100, javascript: 100 }
apexguru:
target_org: "my-org-alias"
flow:
python_command: "python3"
# regex.custom_rules — use the dx-code-analyzer-custom-rule-create skill to create these.
# Never hand-write regex patterns into code-analyzer.yml: quotes/backslashes
# inside YAML cause parsing failures. The create-regex-rule.js script handles
# serialization correctly and must always be used for regex rule creation.
For full property list per engine, read <skill_dir>/references/config-schema.md.
Detect CI system from workspace (.github/workflows/ → GitHub Actions, Jenkinsfile → Jenkins, etc.). Read <skill_dir>/references/ci-cd-templates.md for templates. Use <skill_dir>/examples/ci-github-actions.yml as GitHub Actions base. Key flags: --severity-threshold 2 (gate), --output-file results.sarif (GitHub scanning), --config-file code-analyzer.yml.
sf code-analyzer config # Show effective config
sf code-analyzer config --rule-selector pmd:Security # Specific rules
sf code-analyzer config --include-unmodified-rules # All defaults
This skill works together with dx-code-analyzer-run. The AI agent should seamlessly hand off between them:
dx-code-analyzer-run delegates HERE:If a user says "scan my code" / "run code analyzer" but it fails (CLI missing, plugin not installed, or scan errors out), dx-code-analyzer-run delegates to this skill. In that case:
dx-code-analyzer-run behavior (build command, execute, parse results).dx-code-analyzer-run:After any successful configuration action, offer to run a scan (e.g., "Setup complete! Want me to run a scan?", "Config updated — want to scan and verify?"). If user says yes, proceed with dx-code-analyzer-run behavior.
dx-code-analyzer-custom-rule-create:If the user asks to create a custom rule while you are working on configuration (e.g., "also add a rule that bans System.debug", "set up a PMD XPath rule"), delegate to dx-code-analyzer-custom-rule-create. When that skill finishes, the custom_rulesets or eslint_config_file pointer in code-analyzer.yml may need to be set — that edit belongs here, in this skill.
Handle end-to-end: "not working" → Diagnose → Fix → Scan. "Set up and scan" → Install → Scan. "Disable ESLint and scan Apex" → Edit config → Run with --rule-selector pmd. "Configure custom rules and scan" → dx-code-analyzer-custom-rule-create → wire config → dx-code-analyzer-run. Always follow through to the user's final intent.
| Constraint | Rationale |
|---|---|
| Only create YAML when user requests a customization | Defaults work without any file — don't create boilerplate |
| Place YAML at project root only | CLI auto-discovers code-analyzer.yml from CWD |
| Write only overrides, never duplicate defaults | Keep file minimal and intentional |
| Use Write tool to create, Edit tool to modify | Preserves existing settings |
| Validate after every change | sf code-analyzer config catches YAML errors |
| Ask before installing prerequisites | Never auto-install without consent |
| Never delete existing config without asking | User may have custom settings |
| After setup, offer to scan | Close the loop — config without scan is incomplete |
| Issue | Solution |
|---|---|
| Config not picked up | Must be code-analyzer.yml in CWD or use --config-file |
| YAML validation fails | Spaces only (no tabs), check colon spacing |
| SFGE out of memory | Increase java_max_heap_size in engines section |
| ESLint rules missing | Set auto_discover_eslint_config: true |
For full troubleshooting, read <skill_dir>/references/troubleshooting.md.
<skill_dir> is the absolute path to the directory containing this SKILL.md file.
| File | Purpose |
|---|---|
<skill_dir>/scripts/check-prerequisites.sh | Environment check |
<skill_dir>/scripts/generate-config.sh | Auto-detect project type and generate config |
<skill_dir>/scripts/validate-config.sh | Validate YAML after changes |
<skill_dir>/references/config-schema.md | Full YAML schema documentation |
<skill_dir>/references/diagnostic-flow.md | Step 2A: layered diagnostic procedure and fix table |
<skill_dir>/references/rule-name-resolution.md | Step 6.1: fuzzy rule name lookup strategies and mappings |
<skill_dir>/references/engine-prerequisites.md | Install instructions per engine |
<skill_dir>/references/ci-cd-templates.md | CI/CD pipeline templates |
<skill_dir>/references/troubleshooting.md | Common setup issues and fixes |
<skill_dir>/examples/apex-project-config.yml | Config for Apex-only project |
<skill_dir>/examples/lwc-project-config.yml | Config for LWC-only project |
<skill_dir>/examples/fullstack-project-config.yml | Config for Apex + LWC + Flows |
<skill_dir>/examples/ci-github-actions.yml | GitHub Actions workflow |