PMD Customization

By default, Salesforce Code Analyzer's catalog of PMD rules includes the PMD built-in rules and any custom rules that you added with scanner rule add. Filter which rules are run using flags such as --category.

To replace the catalog with your own custom catalog, use --pmdconfig. With this flag, you can:

  • Indicate a specific set of rules to run without using filtering flags such as --category
  • Modify the properties of existing rules to meet your needs
  • Define and run new XPath-based rules without permanently adding them to the catalog

Create your custom rules file just like another other PMD category or ruleset file. Keep these limitations in mind.

  • The PMD built-in rules can be referenced freely with the ref property.
  • Custom rules defined in other files can be referenced through the ref property only if they’re bundled into a JAR as described in Authoring Custom PMD Rules and registered via scanner rule add as described in Managing Custom PMD Rules. This constraint applies to XPath-based and Java-based rules.
  • Custom XPath-based rules can be declared inline.

Because --pmdconfig replaces our catalog with yours, rule-filter flags such as --category and --ruleset aren’t applied to PMD rules, though they’re still applied to other engines. Only the PMD rules that you specify in your config file are evaluated.

To invoke your rules in Code Analyzer, run scanner run --pmdconfig filename, and pass the path to your rule reference file:

$ sf scanner run —target /path/to/your/target —pmdconfig /path/to/rule_reference.xml

  • /path/to/your/target: The source code location.
  • /path/to/rule_reference.xml: The location of the PMD rule reference file.

You can specify the rules that you invoke on PMD using --pmdconfig. Using –pmdconfig causes other filter parameters to be ignored, such as –category and –ruleset.

$ sf scanner run --engine eslint-typescript,pmd --pmdconfig /path/to/ruleref.xml --target /path/to/target

  • eslint-typescript,pmd: The location of ESlintrc config.
  • /path/to/ruleref.xml: The location of the PMD rule reference file.
  • /path/to/target: The source code location.

To be compatible with Code Analyzer, build your PMD custom rules following these guidelines:

  • Declare your new XPath or Java-based rules in custom category XML files using this format: <some base dir>/category/<language>/<filename>.xml. For more info, read the PMD XML rule definition documentation.
  • Combine your custom rules and the PMD built-in rules into custom rulesets in XML files using this format: <some base dir>/rulesets/<language>/<filename>.xml. For more info, read Making rulesets in the PMD documentation.
  • Register custom rulesets or XPath-only custom categories with Code Analyzer as standalone XML files.
  • Compile your Java-based rules, and bundle them into a JAR along with your rule declaration files, then register that JAR with Code Analyzer. We recommend using a build tool such as Maven or Gradle to manage the dependency on PMD and automate the process of building the JAR. Use our example repo as a scaffold to build your own project.

Use the scanner rule add command to add a custom rule to the Code Analyzer catalog. Rules added in this way can then be invoked with scanner run the same way that PMD default rules are invoked. Use the -p|--path parameter to specify the XML file containing your XPath-based rules or the JAR containing your Java-based rules. You can specify multiple files to add multiple custom rules for a single language. You can also use the -p|--path parameter to specify a directory that contains multiple JAR or XML files.

To add one or more custom rules to multiple languages, use a separate scanner rule add command for each language.

For example, to add a single JAR file for the Apex language:

  • apex: The language to evaluate the rules against.
  • path/to/your/File.jar: One or more paths to custom rule definitions.

To add a directory path that contains multiple JAR/XML files for the same language:

  • apex: The language to evaluate the rules against.
  • path/to/your/files: One or more paths to custom rule definitions.

To add multiple paths to files that are in different locations for the same language:

  • apex: The language to evaluate the rules against.
  • path/to/your/files,/another/path/Custom.jar,/yet/another/jar/lib: One or more paths to custom rule definitions.

The command output indicates which JAR files were found and added to Code Analyzer.

After you add your rules to Code Analyzer with scanner rule add, run [scanner rule list] (../command-reference/list.md) to review the complete catalog of existing PMD rules and your latest additions. Your custom rules are displayed under the category names that you defined in your XML rule-definition files, and they’re ready to use.

Run your custom rules using scanner run the same way you run PMD's built-in rules: scanner run --category MyCustomCategory. You don't need the --pmdconfig flag to run your custom rules.

Remove custom rules from the catalog with the [scanner rule remove] (../command-reference/remove.md). The rules defined in the JAR/XML file that you specify with the -p|--path parameter are removed from the catalog.

To bypass confirmation of the removal, use the --force parameter.