Migrate from Code Analyzer v4 to v5

Code Analyzer v5 is more intuitive and powerful than v4, but the configuration and CLI commands work a bit differently. This document helps you migrate.

The most obvious high-level change between the Code Analyzer v4 and v5 CLI commands is that v4 commands are in the scanner topic and v5 commands in the code-analyzer topic. For example:

v4:

v5:

We also reduced the six v4 commands to just three in v5: code-analyzer run|rules|config. This table summarizes the changes.

Another high-level change is that in v5, the three commands share many of the same flags for:

• Selecting the rules (--rule-selector).
• Selecting the set of files you want to include in your analysis (--workspace).
• Specifying the path to the configuration file (--config-file).

As a result, executing the three v5 commands is essentially the same whether you want to list rules, run rules, or view your configuration.

The v5 CLI commands now have a single flag (--rule-selector) for selecting the rules you want to list or run on your source code. With this single flag you can select rules based on their name, engine, severity level, and tags. And more importantly, you can combine these properties in many different ways so as to select exactly what you want. It's a powerful flag. But it's also different from how v4 CLI commands worked, which had multiple flags such as --engine or --category.

Finally, another big change: v5 introduces a configuration YAML file (code-analyzer.yml) which you can use to configure global properties and customize rules and engines, including adding custom rules. See Customize the v5 Configuration for details.

In v4, if you specify a PMD ruleset file with the --pmdconfig flag of scanner run, only the rules in the ruleset actually run. You can't also run other PMD rules that aren't specified in the ruleset.

But with v5, when you specify your ruleset file in your code-analyzer.yml file, the rules in the ruleset are added to the full list of PMD rules that you can select and run. To make selection of your ruleset rules easy, we add a tag to each rule that matches the name attribute of your ruleset, minus any spaces.

For example, let's say your PMD ruleset file looks like this:

Then each rule in the ruleset file is tagged with MyRules.

Follow these steps to mimic the v4 behavior of sf scanner rule --pmdconfig path/to/my/ruleset.xml in v5:

1. As described in Add Custom PMD Rules, update your code-analyzer.yml file like this:

2. Run this command to ensure that your custom rules are available.

   Your PMD rules have up to two new tags added. The first tag is the name of your ruleset, with spaces removed. This tag is added to all rules, including the standard PMD rules that are referenced in your ruleset. The second tag is Custom, which is added to only the custom non-standard PMD rules in your ruleset.

3. Run all the rules in your ruleset by specifying the --rule-selector pmd:<RuleSetNameWithoutSpaces> flag.

   Be sure the code-analyzer.yml file is either in your local directory or you use the --config-file flag to specify it.

In v5, you can do more than just run the rules in your ruleset. This example shows how to run all the Recommended rules in addition to the rules from your ruleset file:

In v4, you specify custom ESLint rules by pointing to your .eslintrc.json file with the --eslintconfig flag of scanner run. But then you couldn't also run the recommended standard ESLint rules that run when you don't supply the --eslintconfig flag.

With v5, we allow you to supply your ESLint configuration either on its own or added alongside our recommended base configuration, assuming there are no configuration conflicts.

To mimic the v4 behavior in v5, provide your ESLint configuration file and turn off our recommended base configuration, as described by these steps:

1. If you haven't already, create a code-analyzer.yml configuration file and set these options in the engine:eslint section:

   See Add Custom ESLint Configuration and Rules for details.

2. Run this command to ensure that your custom ESLint rules are available.

   Any new custom ESLint rules that are not already provided by the base configurations have the Custom tag added.

3. Run only your custom ESLint rules this way:

   Be sure the code-analyzer.yml file is either in your local directory or you use the --config-file flag to specify it.

If you want ESLint to merge your configuration with our recommended base configurations, then set the disable_*_base_config fields back to false while still supplying your eslint_config_file. This merging of configurations wasn't possible in v4. Then run this command:

Let's look at a few examples to get you started using the new v5 commands.

This v4 CLI command runs all the rules with the Security or Performance category:

This is the v5 equivalent CLI command:

It's a Salesforce CLI best practice to use multiple flags to specify multiple values, but this syntax also still works:

This v4 CLI command runs all the PMD rules in the Security category:

This is the v5 equivalent:

Due to the improved design of the v5 CLI commands, there are many useful scans that you can easily run in v5 that are impossible with v4 commands.

Run all the ESLint rules and any PMD rules with the Security category:

Run only PMD's rules for the Apex language:

Run only the rules that have severity 1 (critical), for all enabled engines: