Code Analyzer

The code analyzer linter runs Salesforce Code Analyzer against your project, providing static analysis through PMD, ESLint, and CPD engines. It identifies security issues, best practice violations, performance concerns, and duplicate code.

The PMD and CPD engines run on the JVM and require a Java runtime and the Code Analyzer engine libraries on the machine running sfp analyze. See Code Analyzer prerequisites before the first run.

Overview

The code analyzer integrates Salesforce Code Analyzer into the project:analyze command and:

  1. Detects the configuration file (or uses engine defaults)
  2. Runs the configured engines (PMD, ESLint, CPD) against the target files
  3. Collects results in SARIF format
  4. Reports findings with file locations, line numbers, and rule details
  5. Creates GitHub Checks with annotations when running in CI

When an engine cannot process a single file — a parse error on one class, for example — the run reports it as a scan warning and continues, so the remaining files' findings are still returned rather than the whole analysis failing. The warnings appear in the run's notes and in the scanWarnings field of the JSON output.

Supported Engines

EngineLanguageWhat It Checks
pmdApexSecurity, best practices, performance, design
eslintLWC JavaScript / AuraJavaScript quality, security, best practices
cpdApex, JavaScriptCopy-paste / duplicate code detection

Configuration

The code analyzer is configured through a YAML file that follows the Salesforce Code Analyzer v5 configuration format. The file is checked in priority order until the first match is found:

  1. --code-analyzer-config <path> CLI flag
  2. code-analyzer.yml (repository root)
  3. code-analyzer.yaml (repository root)
  4. config/code-analyzer.yml
  5. config/code-analyzer.yaml
  6. .code-analyzer.yml
  7. .code-analyzer.yaml

The repository-root filenames match where the sf code-analyzer CLI looks by default, so a project already carrying a root code-analyzer.yml is picked up without moving it under config/.

If --code-analyzer-config names a path that does not exist, the command fails rather than falling back to the default rules. If no flag is given and none of the locations above exist, the default engine configuration is used (all engines with their built-in rule sets).

Paths inside the config — such as custom_rulesets — resolve relative to the repository root.

Schema

# config/code-analyzer.yml

engines:
  pmd:
    # Disable specific PMD rules by name
    disable_rules:
      - ApexUnitTestClassShouldHaveAsserts
      - AvoidDebugStatements

    # Custom PMD rule sets (paths relative to repo root or URLs)
    custom_rulesets:
      - config/pmd/custom-rules.xml

    # Java heap size for PMD (MB)
    java_max_heap: 1024

  eslint:
    # Path to ESLint config file
    config_file: config/.eslintrc.json

    # Additional plugins to load
    plugins:
      - '@salesforce/eslint-plugin-lwc'

  cpd:
    # Minimum number of duplicate tokens to report
    minimum_tokens: 100

    # File extensions to scan for duplicates
    language: apex

Examples

PMD-Only with Custom Rules

# config/code-analyzer.yml
engines:
  pmd:
    disable_rules:
      - ApexUnitTestClassShouldHaveRunAs
    custom_rulesets:
      - config/pmd/salesforce-best-practices.xml

Tighter Duplicate Detection

# config/code-analyzer.yml
engines:
  cpd:
    minimum_tokens: 75

Disable PMD Rules That Don't Apply

# config/code-analyzer.yml
engines:
  pmd:
    disable_rules:
      - ApexUnitTestClassShouldHaveRunAs
      - AvoidDebugStatements
      - ApexUnitTestClassShouldHaveAsserts

Failing on severity

When code-analyzer is listed in --fail-on, --code-analyzer-severity-threshold decides which violations fail the check: only those at or above the given severity, mirroring sf code-analyzer run --severity-threshold:

ValueSeverity
1Critical (default)
2High
3Moderate
4Low
5Info

The default of 1 means only Critical violations fail the check. Findings below the threshold are still reported. Raise the value to gate on less severe findings; 5 fails on any violation:

# Critical and High (severity 1 and 2) violations fail the check; the rest are reported
sfp project:analyze --fail-on code-analyzer --code-analyzer-severity-threshold 2

The threshold can also be set as codeAnalyzerSeverityThreshold in config/analyze.yaml, or per branch rule in the server-side analyze configuration, where it applies to PR analysis.

Gating on changed lines

In PR analysis, --code-analyzer-scope decides which violations in a changed file can fail the check:

ValueViolations that can fail the checkDefault for
changed-linesViolations whose start line the PR added or modifiedPR analysis (--pr-number is set)
fileEvery violation in a changed fileEvery other run

Code Analyzer still scans the whole of each changed file, because many rules need the full file. With changed-lines, a violation that starts on a line the PR did not change is listed under Pre-existing in touched files. It is reported, but it never fails the check and gets no annotation on the pull request. The summary then shows the scope and the number of new and pre-existing violations.

A rule that reports at a class or method declaration, such as ExcessiveClassLength or MethodNamingConventions, fails the check only when the PR changed that declaration line or added the file. Making an existing method longer therefore does not fail the check on that method.

The changed lines come from git diff <base-ref>...<head-ref> in the analysed checkout. Without --base-ref, or when the diff fails, the check gates on whole files and says so in its notes: Changed-line diff unavailable — gating on whole files. A violation in a file that the diff does not list counts as new.

# gate on every violation in the changed files, as before changed-lines existed
sfp project:analyze --pr-number 42 --base-ref origin/main --fail-on code-analyzer --code-analyzer-scope file

The scope can also be set as codeAnalyzerScope in config/analyze.yaml, or per branch rule in the server-side analyze configuration. Full-workspace runs, which have no changed files, are always file-scoped.

Choosing which rules run

--code-analyzer-rule-selector chooses which rules run, mirroring sf code-analyzer run --rule-selector. The default is the engine name, which runs every rule of that engine. Scope a selector to an engine (pmd:Security, not bare Security):

# run one category
sfp project:analyze --code-analyzer-rule-selector pmd:Security

# a severity-bounded expression
sfp project:analyze --code-analyzer-rule-selector "pmd:(Security,Performance):2"

# Salesforce's Recommended set
sfp project:analyze --code-analyzer-rule-selector pmd:Recommended

Repeat the flag for several selectors. Commas and parentheses are part of the selector expression, so a selector is never split apart, and each selector must match at least one rule — a selector matching nothing is an error rather than a silent pass.

Running only your custom ruleset

custom_rulesets is additive: listing a ruleset makes its rules available, but it does not restrict the run, so the built-in rules still apply and a project configured only with custom_rulesets still reports rules outside its ruleset. To run only your ruleset, select it by name. Code Analyzer tags every rule loaded from a custom ruleset with the ruleset's name attribute, with spaces removed, so for:

<ruleset name="Customer PMD Rules"> ... </ruleset>

the selector is the tag CustomerPMDRules:

# only the rules in your ruleset
sfp project:analyze --code-analyzer-rule-selector pmd:CustomerPMDRules

# your ruleset plus Salesforce's Recommended set
sfp project:analyze \
  --code-analyzer-rule-selector pmd:CustomerPMDRules \
  --code-analyzer-rule-selector pmd:Recommended

Use the ruleset-name tag, not pmd:Custom — the Custom tag is added only to genuinely custom rules, so it would drop the standard PMD rules your ruleset references.

Integration with CI/CD

Integration is limited only to GitHub at the moment. The command needs GITHUB_APP_PRIVATE_KEY and GITHUB_APP_ID to be set in environment variables for results to be reported as GitHub checks.

# Run code analyzer and fail on issues
sfp project:analyze --fail-on code-analyzer --output-format github
# GitHub Actions
- name: Run Code Analysis
  run: |
    sfp project:analyze --fail-on code-analyzer --output-format github
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Scoping Analysis

Use the same scoping options as other analysis commands:

# By package
sfp project:analyze --fail-on code-analyzer -p core,utils

# By domain
sfp project:analyze --fail-on code-analyzer -d sales

# By source path
sfp project:analyze --fail-on code-analyzer -s ./force-app/main/default

For full engine configuration options, see the Salesforce Code Analyzer documentation.

On this page