Useful tools

There are some CLI tools that can help you find what needs to be changed in the project files before the project is used for a security advisory application. They are the same tools used by the reviewers; using them would allow you to fix most of what reported by reviewers.

• PAReview.sh
  It is a Bash script appositely created to automatically review projects used in the applications to be able to opt projects into security advisory policy. It runs the following commands on the project files to report what should be changed.
   
  • PHP_CodeSniffer is a tool that checks the content of files basing on a set of rules that usually are created from existing coding standards. It is not specific for Drupal, but there are two rulesets that are specific for Drupal: Drupal and DrupalPractice.
  • ESLint is a tool that statically analyzes JavaScript code to quickly find problems.

  • codespell is a tool to check misspelled words in source code.

  PAReview.sh can use a Git repository URL instead of a directory name. In this case, PAReview.sh also verifies the repository does not contain branches or tags with the wrong name, or tag names that conflict with branch names. For this reason, PAReview.sh is the preferred tool for reviewing what needs to be changed in a project.

• PHP_CodeSniffer can also be executed independently from PAReview.sh. In this case:

  • Both the Drupal and DrupalPractice rulesets should be used.
  • It is preferable to not use PHPCode_Sniffer for JavaScript files. It would try to apply PHP rules to JavaScript files, even when those are not correct; for example, it would report that NULL must be used, while null, true, and false are used in JavaScript code.

• ESLint can be executed independently from PAReview.sh. In this case, the eslintrc.json file used by PAReview.sh, which is tailored for Drupal, should be used to set up ESLint when used for projects used in security advisory applications.

• PHPStan scans the whole codebase and looks for obvious and tricky bugs.
  Given its purpose (finding bugs) and the false positives that PHPStan can show when not correctly configured, it is preferable not to use it for security advisory applications.
  The other tools listed in this page are preferable; PAReview.sh is still preferable to the other ones.

Caveats

The tools described in this page could give false positives: They could report lines to change when those lines do not need to be changed. For example, this can happen with PHP_CodeSniffer and JavaScript files, where PHP_CodeSniffer would show as error/warning using null  instead of NULL. null is used in JavaScript files and NULL is used in PHP files; PHP_CodeSniffer is applying rules that are for PHP files to JavaScript files and gives a wrong error/warning.

In other cases, they could give an error/warning that should be shown in a different context. For example, PHP_CodeSniffer could report
that the text in the following comment should end with a period.

// $config['system.performance']['css']['preprocess'] = FALSE;
// $config['system.performance']['js']['preprocess'] = FALSE;

That is commented out PHP code and it does not need to be changed. The rule PHP_CodeSniffer applies is for comments containing a sentence, which ends with a period. The rule is thought for comments like the following ones.

// If we are updating an existing node without adding a new revision, we
// need to make sure $entity->revision_log is reset whenever it is empty.
// Therefore, this code allows us to avoid clobbering an existing log
// entry with an empty one.

The rule is for adding more helpful comments in code, but it does not verify if the comment contains code, nor can it understand when there are exceptions to the Drupal coding standards.