Appendix F: Rules¶

This appendix holds every rule that enforces these standards: the stock PMD rules that the reference adopts, the custom rules of the reference, in three kinds, and the severity levels that all of them share.

• Appendix F.1: Stock PMD Rules: every stock PMD rule that the reference adopts, by language, with its priority and the standard it enforces.
• Appendix F.2: Custom PMD XPath Rules: the custom rules written in XPath, for Apex, Visualforce, Lightning markup, and metadata XML, and a sample rule that enforces a trigger framework.
• Appendix F.3: Custom PMD Java Rules: the rules that XPath cannot express, as a Maven project with tests.
• Appendix F.4: Custom Code Analyzer Regex Rules: the rules that match text rather than syntax, defined in code-analyzer.yml, and the rules that the regex engine ships.
• Appendix F.5: Every Rule of Salesforce Code Analyzer: the complete inventory of the rules that Code Analyzer ships, engine by engine, current for a named version.
• Appendix F.6: Standards and Rules Cross-Reference: which rules enforce each standard, which standards each rule serves, and the rules that have no written standard yet.

The reference writes no rule of its own for ESLint, the Flow engine, or the other engines of Salesforce Code Analyzer, but it relies on rules that ship with them, and each is listed beside the rules of the reference in Appendix F.6. The ESLint rules that these standards set are on the Version Control page (ESLint), and How an ESLint Rule Reaches a Pull Request says how they reach the quality gate.

The reference ships as {N} ruleset files, and each name below is a link to the file in full, on a page of its own: pmd-custom-rules-apex.xml, pmd-custom-rules-markup.xml, pmd-custom-rules-metadata.xml, and pmd-custom-rules-flow.xml, the custom XPath rules of the F.2 page for Apex, for Visualforce and Lightning markup, for XML metadata, and for Flows, Process Builder, and Workflow Rules; pmd-custom-rules-javascript.xml, the custom XPath rules for JavaScript, also on the F.2 page; pmd-stock-rules.xml, the stock PMD rules that the reference adopts; and pmd-stock-rules-javascript.xml, the stock PMD rules for JavaScript, which have a file of their own (Appendix F.1 says why).

A single file, pmd-all-rules.xml, imports the others with one line each, for a run of PMD by itself: PMD loads every rule of an imported file with the priorities and the properties set there, so one --rulesets argument runs them all. Its last line is the ruleset of the Java rules, which travels inside the JAR, so the JAR must be on PMD's classpath for that run; with the JAR absent, PMD loads no rule at all from the file and says nothing, and the file's comment says so.

With our required rules, Code Analyzer does not read that file (which would seem easier). It lists the four files one by one, because the Apex and the JavaScript rules that share a name would be interpreted as one name again in one ruleset, and Code Analyzer would run only the first. It is unfortunate that PMD has multiple stock rules with the same name, and that is why this workaround is needed.

Regex rules are not in any of the files: they are defined inside code-analyzer.yml (Appendix F.4).

The PMD Folder¶

In a project repository the ruleset files and the JAR of the Java rules sit together in config/pmd/, and code-analyzer.yml, at the root, names the four that it reads (Repository Structure).

config/pmd/
├── pmd-stock-rules.xml                   # The stock PMD rules this reference adopts, with their priorities
├── pmd-stock-rules-javascript.xml        # The stock PMD rules for JavaScript, in a file of their own
├── pmd-custom-rules-apex.xml             # The custom rules for Apex, written in XPath
├── pmd-custom-rules-markup.xml           # The custom rules for Visualforce and Lightning markup
├── pmd-custom-rules-metadata.xml         # The custom rules for XML metadata
├── pmd-custom-rules-flow.xml             # The custom rules for Flows, Process Builder, and Workflow Rules
├── pmd-custom-rules-javascript.xml       # The custom rules for JavaScript, written in XPath
├── pmd-all-rules.xml                     # The seven files above, imported into one, for a run of
│                                         # PMD by itself. Code Analyzer does not read it
└── pmd-java-rules-1.0.0.jar              # The custom rules written in Java. The ruleset that names
                                          # them, rulesets/devsecops-java.xml, is inside the JAR

The Java source is not in a project repository. It is the Maven project of Appendix F.3, which lives in the configuration repository (Appendix D) and builds the JAR that each project receives.

Three Kinds of Custom Rules¶

PMD offers two ways to write a rule, and Salesforce Code Analyzer adds a third. An XPath rule is a query written inside the ruleset XML. A Java rule is a compiled class that a ruleset names. A regex rule is a pattern, defined in code-analyzer.yml, that is matched against the text of a file. This appendix uses all three. Each has advantages the others lack.

Rules Written in XPath¶

An XPath rule is one query: every node the query selects is a violation. The query, the message, the description, and the priority sit together in the ruleset file, so the file is the whole of the rule.

• Nothing to build. The ruleset is a text file. Adding or changing a rule is an edit to that file, and PMD reads it as it is.
• Easy to review. A change to a rule appears in a pull request as a few lines of XML beside the rule's own description, and a reviewer can read it without building anything.
• Quick to write and to try. A query on PMD's syntax tree can be tried in PMD's Rule Designer against a sample class, and any query can be tried by running PMD on a sample file.
• The same technique covers code and metadata. One kind of rule checks Apex, Visualforce, and Lightning markup on PMD's syntax tree and, through DomXPathRule, any XML metadata file. Most of the rules in this appendix are XPath rules.
• One file to deploy. The ruleset is listed under engines.pmd.custom_rulesets in code-analyzer.yml, and nothing else is needed.

Its limit is its reach. An XPath rule sees one file, as PMD's parser presents it. It cannot read a second file, and it cannot see detail that the parser records but does not expose to XPath.

Rules Written in Java¶

A Java rule is a class that walks the same syntax tree through PMD's own API, with everything else Java can do.

• It can see what XPath cannot. PMD's parser records the access mode of a DML statement but does not expose it to XPath (pmd/pmd#7108). A Java rule asks the parser directly, and the access mode standard is enforced that way.
• It can read another file. A rule about an Apex class can open the -meta.xml file beside it, where the class's API version is stored. None of the rules here does: the sharing and access mode standards are the same at every API version (Apex: Be Explicit Everywhere).
• It can reason, not only select. Conditions, helper classes shared between rules, and a message chosen for each violation are ordinary code. RequireAccessMode gives a different message for a query, a method call, and a DML statement, and FlagSystemMode has a property that decides whether test classes are reported.
• It has automated tests. PMD's rule-test harness runs each rule against snippets of Apex with the expected violations and line numbers, so a change to a rule can be tested on every pull request.

Its cost is the build. A Java rule needs a Java project (Maven here), a JAR built and delivered to wherever PMD runs, a PMD version kept in step with the one Salesforce Code Analyzer bundles, and a reviewer who reads Java.

Rules Written as Regex Patterns¶

A regex rule is one pattern: every match is a violation. The pattern, the file extensions it scans, the description, the message, and the severity sit together in code-analyzer.yml, so the entry is the whole of the rule.

• Nothing to build, and no ruleset file. The rule is a few lines of YAML in the configuration file that the project already has.
• It reads any file. PMD parses the languages it knows. A pattern reads whatever text it is pointed at, so one rule can cover Visualforce, Lightning markup, and metadata XML together.
• It sees what no parser exposes. An ordinary comment in Apex, or the JavaScript inside a Visualforce script block, is invisible to an XPath rule and plain text to a pattern.

Its limit is that it sees only text. A pattern has no context: it cannot tell code from a string or a comment that holds the same characters. And it does nothing under PMD on its own, because the regex engine is Code Analyzer's. So the reference keeps regex for what no PMD rule can see at all.

Choosing Between Them¶

Write a rule in XPath when XPath can express the whole check, and in Java when it cannot. A check that XPath can only half express belongs in Java whole. The access mode rules are the example: XPath could check queries and method calls but not DML statements, so the standard is enforced by {N} Java rules that cover every case, with no XPath rule beside them.

A Code Analyzer regex rule is not a way around XPath's limits where a Java rule can do the job. The access mode of a DML statement is out of XPath's reach, and a pattern could find it in the text of a class, but it would have no context. A Java rule reads the mode from the parser, so it cannot mistake a comment for code. Regex is kept for what no PMD rule can see at all, such as an ordinary comment (Appendix F.4).

For worked examples of both kinds beyond this reference, Salesforce publishes the source of the AppExchange rules that ship with Code Analyzer. In Code Analyzer 5.16.0 they are {N} rules written in XPath and {N} written in Java, with a test for each: the ruleset files, the Java classes, and the tests. Its XML rules are written with PMD's XPathRule, on the tree PMD wraps around an XML file, where the metadata rules in this reference use DomXPathRule on the document itself, as PMD recommends for XML (How the Rules Are Written). An expression from one does not work unchanged in the other.

What an Organisation Can Change¶

Every rule in this appendix is a recommendation and a tool. An organisation that sees a standard differently changes the rule to suit, and does not have to rewrite it.

• Its severity. code-analyzer.yml sets the severity of any rule, so a rule that blocks here can be advisory there, or the reverse.
• Its properties. A property holds a value that a rule works with, such as the lowest API version allowed or the list of metadata types that need approval, and a ruleset can set it without touching the rule (Using and Changing the Ruleset). The properties of every PMD rule, custom or stock, give this flexibility. A regex rule has no property: its pattern and the file extensions it scans are in its definition, and are changed there (Using and Changing the Rules).
• Whether it runs. A rule that an organisation does not want is disabled in code-analyzer.yml.

The Stock PMD Rules¶

PMD ships its own rules, and Appendix F.1 lists the ones this reference adopts. The {N} stock rules files adopt them by reference: every Apex, JavaScript, HTML, and Visualforce rule that PMD ships, except those listed under Stock PMD Rules Not Adopted, each with an explicit priority and, where its behaviour is changed, a property override. There is nothing to write: the work is setting the priorities, and deciding which rules not to enforce (Stock PMD Rules Not Adopted).

Stock PMD Rules Not Adopted¶

These standards do not adopt every rule that PMD ships. The stock PMD rules below stay in the stock rules file, each commented out with no priority, on one line or, for a rule with properties, with its properties at PMD's defaults inside the same comment, so that the file accounts for every rule PMD ships and shows which are left out on purpose. Where Code Analyzer would run one of them by default, the sample code-analyzer.yml disables it with disabled: true. {N} of them are rules that PMD has deprecated: a deprecated rule still runs today, with a warning from PMD, and PMD removes it in its next major version, so the reference does not adopt one, and names the rule that replaces it.

Severity Levels¶

Every rule carries a severity from 1 to 5. The severity states how a violation of the rule is treated at the quality gate, whichever tool reports it.

Severities 1 and 2 block the pull request. Severities 3 to 5 are listed in the non-blocking violations table and do not prevent merging.

A severity 1 violation is also cleaned up on sight. A pull request that edits a file fixes the severity 1 violations in that file, including the ones that were there before the pull request.

How a blocking violation is accepted, and the remediation timelines that an organisation may set for severities 3 and 4, are in the Priority Reference, with how a rule's PMD priority becomes its severity. The policy behind these levels is in Ruleset Files as a Governance Artifact, and the scan that applies them is A.2.9, Static Code Analysis.

Priority Reference¶

From PMD Priority to Severity¶

In this reference, a rule's Code Analyzer severity is its PMD priority: the two tools use different names for the same number. A PMD ruleset states each rule's priority, and Salesforce Code Analyzer turns that into a severity of its own, though not to the same number. It derives each severity as shown in the second column, which would leave every priority 2 rule advisory. The organisation's code-analyzer.yml overrides each rule's severity with the same number as its priority, shown in the third column, and that override survives regeneration of the file from each engine's rules and configurations (see Appendix E).

With --severity-threshold 2 configured in the GitHub Actions workflow, priorities 1 and 2, overridden to severities 1 and 2, produce a non-zero exit code and block the PR. What each overridden severity means at the quality gate is under Severity Levels above.

Accepting a Blocking Violation¶

A severity 2 violation is fixed, or the author makes a case for leaving it. A large body of older code written to an earlier naming convention is an example: renaming all of it is rarely the work of the pull request that happens to touch it, so the violation may stay. The case is made to a member of the owning team (the code owners for the changed files, not any approver). Their approving review accepts it, and lets the merge proceed with the violation still listed in the pull request's results.

A severity 1 violation is accepted only in rare cases. The case for leaving one must be stronger than at severity 2, and it can mean more work inside the organisation. A standard that expects such a case says who accepts it. An organisation may also require a second approver for a severity 1 violation, for example from a senior team or the CoE. The workflows in this reference do not include a second approver.

Code Analyzer has no per-violation approval of the kind CodeScan offers, and no built-in way to approve a pull request past blocking violations as Copado and CodeScan do, so the approving review stands in for both, and the review is the record of who accepted what.

Leaving a blocking violation to be fixed in a separate pull request is not recommended (Version Control: Fixing a Blocking Violation).

Remediation Timelines¶

A severity 3 or 4 violation does not block the pull request, but an organisation may give it a deadline. It may set a remediation timeline for severity 3 violations, and perhaps for severity 4: a time within which a reported violation is fixed. No workflow in this reference tracks such a timeline; the organisation's own process does.

The Custom Rules¶

Every custom PMD rule in this reference, by group, with XPath and Java rules together.

The custom regex rules are not PMD rules, and they have a table of their own, in Appendix F.4; so do the stock PMD rules that the reference adopts, in Appendix F.1. The groups are in alphabetical order, and the rules in each are listed most severe first, then by name. Nearly every rule is written in XPath, in the ruleset on Appendix F.2, and two are written in Java as shown on Appendix F.3.

Each rule name is an anchor that a standard can link to. Which standard each rule enforces is in Appendix F.6.

Code Rules¶

Accessibility¶

Apex Access, Sharing, and Access Mode¶

Apex Cookies and Cryptography¶

Apex Documentation¶

Apex Error Prone¶

Apex Hard-Coded Values¶

Apex Naming¶

Apex Performance¶

Apex Readability¶

Apex Testing¶

Apex Triggers¶

Apex Untrusted Input¶

JavaScript Security¶

Lightning Out¶

Visualforce, LWC, and Aura Markup¶

Metadata Rules¶

Field Classification and Design¶

Flow Naming¶

Flow, Process Builder, and Workflow Rules¶

Integration Endpoints¶

Metadata Documentation¶

Metadata Naming¶

Metadata Quality¶

Org Settings¶

Permissions¶

Secrets in Fields¶

Secrets in Metadata¶

Sharing Model¶

Custom Rules Not Adopted¶

When this reference stops recommending a custom rule, the rule stays in its ruleset file, commented out, with a note that says why. It does not run, and an organisation can restore it.