Code Analyzer and Quality Gates

When to use

• Setting up or changing static analysis for a Salesforce project.
• Triaging a vf-check analyzer failure, deciding fix versus suppress, or writing a suppression with a reason and a cap.
• Authoring a custom PMD rule or a regex rule for a project convention.
• Wiring Prettier/ESLint so vf-check format and vf-check lint are deterministic.
• Introducing the gate to a legacy codebase without stopping delivery (baseline and ratchet).
• Wave 2 of the vibe-force workflow: sf-quality-gate runs vf-check local and reports.
• Org-wide debt rather than a diff: skill sf-technical-debt-audit (it turns recurring findings into regex rules authored here).

Toolchain and prerequisites

If Java or Python are unavailable in an environment (a lean CI image, for example), disable those engines in code-analyzer.yml rather than tolerating engine errors:

engines:
  flow:
    disable_engine: true
  cpd:
    disable_engine: true

Config files live in the plugin and are referenced by the check runner; do not duplicate them per project: config/code-analyzer.yml, config/pmd/apex-ruleset.xml, config/eslint/eslint.config.mjs, config/prettier/.prettierrc.

Engines

Severity taxonomy and the gate

--severity-threshold makes the command exit non-zero when a violation meets or exceeds the given level; it accepts a number or its name (2 or "High"). vf-check analyzer passes gates.analyzerFailSeverity from .vibeforce/config.json.

Core patterns

1. List the rules before running them

# recommended rules for every available engine (the default selector is Recommended)
sf code-analyzer rules

# everything the pmd engine offers, with full detail
sf code-analyzer rules --rule-selector pmd --view detail

# scope to what actually applies to this codebase
sf code-analyzer rules --rule-selector all --workspace . --target force-app/**/*.cls

--rule-selector eslint is equivalent to eslint:all; append :Recommended to stay inside the recommended set. Criteria combine with : as AND and , as OR, and parentheses group; a selector containing parentheses must be double-quoted.

2. Run the same selectors

sf code-analyzer run --workspace . --rule-selector Recommended --severity-threshold 3 --view detail

# Apex-only path analysis, whole project as context, targeted files as entry points
sf code-analyzer run --workspace . --rule-selector sfge --target force-app/main/default/classes

# machine-readable plus human-readable in one pass
sf code-analyzer run --workspace . \
  --output-file .vibeforce/reports/analyzer.json \
  --output-file .vibeforce/reports/analyzer.html

--workspace is the analysis context (default .); --target narrows which files produce violations while keeping the workspace available to engines that need the whole project - Graph Engine compiles the workspace to build its call graph.

3. Generate and evolve the configuration

# write the current effective configuration, comments included, to a file
sf code-analyzer config --config-file ./code-analyzer.yml --output-file ./code-analyzer.yml

# just the recommended rules, including their unmodified default values
sf code-analyzer config --rule-selector Recommended --include-unmodified-rules

# what is configured for one rule
sf code-analyzer config --rule-selector pmd:ApexCRUDViolation

Every code-analyzer command auto-discovers code-analyzer.yml or code-analyzer.yaml in the current folder; --config-file overrides the location. Schema details: references/code-analyzer-cli.md and references/config-templates.md.

4. Override severity and tags instead of deleting rules

rules:
  pmd:
    ApexCRUDViolation:
      severity: "Critical"
      tags: ["Recommended", "Security", "VibeForceBlocking"]
    ApexDoc:
      disabled: true
  eslint:
    "@lwc/lwc/no-inner-html":
      severity: 1
  regex:
    NoTrailingWhiteSpace:
      tags: ["Suggestion"]

rules.<engine>.<rule>.severity accepts 1-5 or Critical|High|Moderate|Low|Info; tags replaces the rule's tags; disabled: true switches the rule off for every file.

5. Add a project convention as a regex rule

engines:
  regex:
    custom_rules:
      NoSeeAllData:
        regex: /@IsTest\s*\(\s*seeAllData\s*=\s*true\s*\)/gi
        file_extensions: [".cls"]
        description: "Tests must not use seeAllData=true."
        violation_message: "Replace seeAllData=true with @TestSetup-created data."
        severity: 2
        tags: ["Recommended", "VibeForce"]

The regex must carry a global modifier (/.../g or /.../gi); without it the engine errors. [unverified] The exact property names under custom_rules beyond regex and file_extensions were not enumerated on the fetched configuration pages; generate a skeleton with sf code-analyzer config --rule-selector regex --include-unmodified-rules and copy the shape it prints.

6. Add a custom PMD rule

1. Write an XPath rule (or a Java rule packaged in a JAR) in a PMD ruleset XML file; use sf code-analyzer ast-dump to see the AST you are matching against.
2. Register the ruleset:

engines:
  pmd:
    custom_rulesets:
      - "config/pmd/apex-ruleset.xml"
    java_classpath_entries: []

3. Confirm registration, then run it:

sf code-analyzer rules --rule-selector pmd:Custom --view detail
sf code-analyzer run --rule-selector pmd:CheckForBadVariableNames --view detail

Code Analyzer tags every custom rule Custom and also adds a tag matching the <ruleset> name attribute with spaces removed. Custom PMD severities derive from PMD priority: 1 -> 2 (High), 2 -> 3 (Moderate), 3 -> 3 (Moderate), 4 -> 4 (Low), 5 -> 4 (Low).

7. Suppress narrowly, with a reason

In-source markers (processed by Code Analyzer v5 for any text file):

// code-analyzer-suppress-next-line eslint:no-console -- deliberate build-time diagnostic
console.log('bundle built');

Configuration-level bulk suppression:

suppressions:
  disable_suppressions: false
  "force-app/legacy/classes/":
    - rule_selector: "pmd:ApexCRUDViolation,pmd:ApexSharingViolations"
      max_suppressed_violations: 40
      reason: "Legacy module; tracked by VF-214, migrating to user mode per quarter."

Marker forms: code-analyzer-suppress, code-analyzer-suppress-line, code-analyzer-suppress-next-line, and code-analyzer-unsuppress to restore checking. A bare code-analyzer-suppress applies from that line to end of file or until an unsuppress marker, so prefer the line-scoped forms. Folder paths in suppressions must end with /. --no-suppressions ignores both marker and config suppressions, except that a suppressions.disable_suppressions setting in the config file takes precedence over the flag. PMD's own @SuppressWarnings('PMD.RuleName') annotation and // NOPMD comment still work for the PMD engine; vibe-force prefers the Code Analyzer markers because they work across every engine and are greppable.

8. Formatting and linting around the analyzer

# format check (what vf-check format runs)
npx prettier --check --config config/prettier/.prettierrc --ignore-path config/prettier/.prettierignore "force-app/**/*.{cls,trigger,js,html,css,xml,json}"

# lint LWC/Aura JS (what vf-check lint runs)
npx eslint --config config/eslint/eslint.config.mjs "force-app/**/lwc/**/*.js" "force-app/**/aura/**/*.js"

Prettier owns whitespace, ESLint owns JavaScript semantics, Code Analyzer owns Apex, metadata, and cross-language rules. Never encode formatting preferences as analyzer rules.

9. Composition of the vibe-force checks

Reports land in <project>/.vibeforce/reports/<check>-<ISO>.json with {check, startedAt, durationMs, status, gates, findings[], raw}. Exit codes: 0 pass, 1 gate failed, 2 misconfiguration or missing tool, 3 org/network error.

Anti-patterns

Verification

# does the configuration resolve and are the intended rules selected?
sf code-analyzer config --config-file config/code-analyzer.yml --rule-selector Recommended
sf code-analyzer rules --config-file config/code-analyzer.yml --workspace . --view table

# the gate itself, on changed files only
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" analyzer --changed

# the full local gate before any deploy
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" local

# CI: SARIF for code scanning upload
sf code-analyzer run --workspace . --rule-selector Recommended \
  --severity-threshold 3 --output-file analyzer.sarif

A configuration change is proven by a before/after sf code-analyzer rules --rule-selector <rule> pair showing the new severity or tags, plus a run that exits 0 on clean code and 1 on a deliberately seeded violation.

References

• references/code-analyzer-cli.md - command, flag, and engine tables; output file formats; v4 to v5 migration.
• references/rule-catalogue.md - highest-value PMD Apex, ESLint LWC, Graph Engine, regex, and retire-js rules with fixes.
• references/config-templates.md - the content expected in config/code-analyzer.yml, config/pmd/apex-ruleset.xml, config/eslint/eslint.config.mjs, config/prettier/.prettierrc, .prettierignore.
• references/quality-gates-and-baselines.md - gate policy, legacy baselines, ratchets, CI integration, suppression review.
• Code Analyzer: Use CLI Commands, Customize the Configuration, Top-Level Customization Reference, PMD engine, ESLint engine, Graph Engine, Graph Engine rules, Suppress Violations, Output Schemas
• CLI reference: code-analyzer commands
• PMD Apex rules, PMD rulesets
• @lwc/eslint-plugin-lwc, @salesforce/eslint-config-lwc, prettier-plugin-apex
• Sibling skills: sf-apex-development, sf-apex-testing, sf-lwc-development, sf-lwc-jest-testing, sf-security-model, sf-debugging-logs, sf-deployment-strategies, sf-post-deploy-verification.