Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/automattic/vip-go-compatibility-scanner

Scan for compatibility problems in repository code using PHPCS with any standard, report as GitHub issues.
https://github.com/automattic/vip-go-compatibility-scanner

phpcs vip vip-go-ci

Last synced: 3 months ago
JSON representation

Scan for compatibility problems in repository code using PHPCS with any standard, report as GitHub issues.

Awesome Lists containing this project

README 

        
# vip-go-compatibility-scanner



Find issues in selected repositories using PHPCS, report to GitHub.



This tool is to be used to search for any (compatibility) issues in VIP Go repositories. It will scan a given repository with PHPCS, using a specified PHPCS standard, and then post GitHub issue for each folder that has any detected issues detailing what was found. It will add labels to each issue created, if specified, and print links to the labels in its output. Note that the tool needs to have the repository cloned and ready to be used when started.



This tool can be used for any GitHub repository and with any PHPCS standard. Issues can be posted on a per-file basis.



The tool will also create Zendesk tickets using the REST API if set up to do so.



The tool uses [vip-go-ci](https://github.com/automattic/vip-go-ci/) as a library, and uses some of its dependencies as well. See below.



Note that the tool has two parts:

 * The `compatibility-scanner.php` script will scan using PHPCS and report to GitHub. It will also save to a local database file the information needed to create Zendesk tickets later, by the other part of this tool.

 * The `zendesk-tickets-create.php` script will create Zendesk tickets with URLs to the GitHub issues. It utilises the local database file for this purpose.



## System requirements



- PHP 8.0 or later. PHP 8.1 is recommended. 

- SQLite support is required if the Zendesk functionality is to be used. Same if PHPCSCacheDB functionality is to be used.

- Linux is a preferred OS for `vip-go-compatibility-scanner`, but it should work on other platforms as well. 

- See instructions for macOS below.



## Installing



Included is a script to install `vip-go-compatibility-scanner`. You can use it like this:



```

wget https://raw.githubusercontent.com/Automattic/vip-go-compatibility-scanner/trunk/install.sh && bash ./install.sh 

```



This will result in `vip-go-compatibility-scanner`, `vip-go-ci` and other dependencies being installed in your home directory under `vip-go-ci-tools`.



If installation fails due to missing system requirements, once they've been installed you'll need to delete the lock file before attempting the installation again.



```

rm -iv $HOME/.vip-go-ci-tools-init.lck

```



### Note on macOS



On macOS the following requirements also need to be installed:



- wget

- md5sha1sum



You can use the following to install using [Homebrew](https://brew.sh/):



```

brew install wget md5sha1sum

```



If not installed, the installation script will attempt to install these utilities.



## Scanning a single repository



The compatibility-scanner.php script is meant to be used on a per-repo bases. Here is an example of how it can be run:



```

pushd /tmp && \

git clone [email protected]:githubuser/testing123.git && \

pushd testing123 && \

git submodule init && \

git submodule update --recursive && \

popd && popd && \

./compatibility-scanner.php --vipgoci-path="$HOME/vip-go-ci-tools/vip-go-ci/"  --repo-owner="mygithubuser" --repo-name="testing123" --token="xyz" --github-labels='PHP Compatibility' --github-issue-title="PHP Upgrade: Compatibility violations found in " --github-issue-body="The following violations were found when scanning branch %branch_name% for compatibility problems:  %error_msg% This is an automated report." --github-issue-assign="direct" --local-git-repo="/tmp/testing123" --phpcs-path="$HOME/vip-go-ci-tools/phpcs/bin/phpcs" --phpcs-php-path=/usr/bin/php --phpcs-standard="PHPCompatibilityWP" --phpcs-runtime-set='testVersion 7.3-' 

```



Use the `--github-issue-group-by` option to switch between posting issues on a per `file` and `folder` basis.



Instead of specifying the whole of GitHub issue body on the command-line, you can place it in a file and use the `--github-issue-body-file` parameter instead. The file contents should meet the same requirements as the `--github-issue-body` parameter. For example:



```

./compatibility-scanner.php [...] --github-issue-body-file=/tmp/my-github-issue-body.txt

```



To skip reporting of certain PHPCS issues, use the `--phpcs-sniffs-exclude` parameter, like this:



```

./compatibility-scanner.php [...] --phpcs-sniffs-exclude=My.Sniff.function

```



Note: If you want to open up Zendesk tickets later, use the `--zendesk-db` parameter, like this:



```

./compatibility-scanner.php [...] --zendesk-db=/tmp/zendeskdb.sqlite

```



You can run many scans in a sequence and then run the Zendesk script.



You can use the `--dry-run` parameter to do a test run and see how many GitHub issues would be opened.



### Creating Zendesk tickets



If you wish to also create Zendesk tickets to notify about the GitHub issues opened, you can use the `zendesk-tickets-create.php` script. This script will determine, from a CSV file specified, with what users to open up tickets. It will attempt to open up only one ticket per user, listing all the GitHub issues opened up earlier by the scanning script.



Usage is as follow:



```

./zendesk-tickets-create.php --vipgoci-path="$HOME/vip-go-ci-tools/vip-go-ci/" --zendesk-subdomain="myzendesksubdomain" --zendesk-access-username="user@email" --zendesk-access-token="xyz"  --zendesk-ticket-subject="PHP Upgrade: Issues that need solving" --zendesk-ticket-body="Hi! %linebreak% Some issues were found. %linebreak% See issues here: %github_issues_link%" --zendesk-ticket-status=PENDING --zendesk-csv-data-path="file.csv" --zendesk-db="/tmp/zendeskdb.sqlite"

```



The `--zendesk-ticket-body` parameter supports `%linebreak%` strings, which will be replaced with actual line-breaks. You can use the `--zendesk-ticket-body-file` parameter to load the ticket body from a file instead. Line breaks will be preserved.



The `--zendesk-ticket-tags` parameter is optional and supports a comma separated list of tags to be added. 



The `--zendesk-ticket-group-id` parameter is optional as well, and expects an integer. 



The `--zendesk-csv-data-path` parameter should point to a CSV file that is used to pair together the repository and the email address used as assignee of the Zendesk ticket. The CSV should look like this:



```

client_email,source_repo

email@email,repoowner/reponame

```



The first line should always specify columns. You can specify as many repositories and emails as needed.



This script also supports the `--dry-run` parameter; this will output tickets created.



### PHPCSCacheDB support



`vip-go-compatibility-scanner` supports caching PHPCS results for individual files. With this feature enabled, any PHPCS results are cached in a database so that the PHPCS scanner does not have to be run in case a file is encountered that has been scanned before and results have been cached for it. To identify files, SHA hashing is used and stored. PHPCS options used to scan a file are stored as SHA hashes as well. Only if both SHA hash for a file and PHPCS options SHA hash match for a file, the results for the file are re-used.



PHPCS results are cached in a SQLite database and it will grow as more files are scanned. The database uses indexing. 



It is recommended to use the cached database only while scanning a set of repositories and then remove the cached database when scanning of all repositories is complete. Old databases should not be re-used, as the cached results are likely to get obsolete. 



While SHA is used for PHPCS options, the SHA will _not_ incorporate version numbers for either PHPCS or versions for PHPCS standards used. If you upgrade or change versions, the database should be removed, otherwise you may encounter obsolete results.



Note that this feature is experimental and is distinct from the built-in support for caching in PHPCS.



Usage:



```

./compatibility-scanner.php ... --phpcs-cachedb="/tmp/vip-go-compatibility-scanner-phpcs-cachedb.sqlite"

```



## Tests



To run the tests for `vip-go-compatibility-scanner`, you will need to install `phpunit` and any dependencies needed (this would include `xdebug`).



### PHPUnit configuration file



To run the tests, a configuration file for PHPUnit needs to be set up.



Run:

> cp phpunit.xml.dist phpunit.xml



Replace the string `PROJECT_DIR` with your local project directory. E.g.:

> PROJECT_DIR/tests/integration

will be:

> ~/Projects/tests/integration



### Unit test suite



Run the unit tests using this command:



> phpunit --testsuite=unit-tests -vv



By running this command, you will run tests that do not make external calls nor call external scanners. 



### Integration test suite



First create and adjust the `unittests.ini` file:



> cp unittests.ini.dist unittests.ini



And configure any values as needed.



Run the integration tests using the following command:



> phpunit --testsuite=integration-tests -vv



These tests may create temporary files, and may depend on external scanners, external APIs and so forth. 



## Contributing



If you want to contribute to this project, please see [this file](https://github.com/Automattic/vip-go-ci/blob/trunk/CONTRIBUTING.md) from the [vip-go-ci project](https://github.com/Automattic/vip-go-ci/) on contributing.