From bb6ae9ce7dfab6a1bb937bc5ec692c011cdb34c9 Mon Sep 17 00:00:00 2001
From: Adrien Crivelli <adrien.crivelli@gmail.com>
Date: Tue, 12 Sep 2023 23:56:25 +0800
Subject: [PATCH] Prevent adding PHPDoc types instead of native types

PHPDoc types can sometimes be entirely expressed as PHP native types. It
is better because it avoids code duplication and enables type runtime
check.

This will help us slowly migrate away from PHPDoc typing to PHP native typing.
---
 .github/workflows/main.yml | 17 +++++++++++++++++
 bin/check-phpdoc-types     | 29 +++++++++++++++++++++++++++++
 bin/pre-commit             |  6 ++++++
 composer.json              |  1 +
 4 files changed, 53 insertions(+)
 create mode 100755 bin/check-phpdoc-types

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 3a37448c4..3690aef19 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -61,6 +61,23 @@ jobs:
           FAILURE_ACTION: "${{ matrix.experimental == true }}"
         run: vendor/bin/phpunit --verbose || $FAILURE_ACTION
 
+  phpdoc-types:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup PHP, with composer and extensions
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.1
+          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          coverage: none
+          tools: cs2pr
+
+      - name: Check PHPDoc types
+        run: ./bin/check-phpdoc-types
+
   php-cs-fixer:
     runs-on: ubuntu-latest
     steps:
diff --git a/bin/check-phpdoc-types b/bin/check-phpdoc-types
new file mode 100755
index 000000000..43809f6b9
--- /dev/null
+++ b/bin/check-phpdoc-types
@@ -0,0 +1,29 @@
+#!/usr/bin/env php
+<?php
+
+/**
+ * This will check that the "current patch" does not add or modify lines that contain types as PHPDoc when we can express
+ * them with PHP native types. The "current patch" is either the file about to be committed, the non-committed file, or
+ * the latest commit.
+ *
+ * This will help us slowly migrate away from PHPDoc typing to PHP native typing.
+ */
+function checkPhpDocTypes(): void
+{
+    $content = `git diff --cached` ?? `git diff` ?? `git show HEAD`;
+    preg_match_all('~^\+ +\* @(param|var) (mixed|string|int|float|bool|null|array|\?|\|)+ \$\w+$~m', $content, $parameters);
+    preg_match_all('~^\+ +\* @return (mixed|string|int|float|bool|null|array|void|\?|\|)+$~m', $content, $returns);
+
+    $errors = [
+        ...$parameters[0],
+        ...$returns[0],
+    ];
+
+    if ($errors) {
+        echo 'PHP native types must be used instead of PHPDoc types (without comments), for the following lines:' . PHP_EOL . PHP_EOL;
+        echo join(PHP_EOL, $errors) . PHP_EOL;
+        exit(1);
+    }
+}
+
+checkPhpDocTypes();
diff --git a/bin/pre-commit b/bin/pre-commit
index 3a237b530..87a2cb4b9 100755
--- a/bin/pre-commit
+++ b/bin/pre-commit
@@ -23,6 +23,12 @@ if [ "$files" != "" ]; then
     echo "$files" | xargs git add
 fi
 
+# Check PHPDoc types
+./bin/check-phpdoc-types
+if [ $? -ne 0 ]; then
+    pass=false
+fi
+
 if $pass; then
     exit 0
 else
diff --git a/composer.json b/composer.json
index f71ec94ed..64dd85577 100644
--- a/composer.json
+++ b/composer.json
@@ -42,6 +42,7 @@
     ],
     "scripts": {
         "check": [
+            "./bin/check-phpdoc-types",
             "phpcs src/ tests/ --report=checkstyle",
             "phpcs --report-width=200 samples/ src/ tests/ --ignore=samples/Header.php --standard=PHPCompatibility --runtime-set testVersion 8.0- -n",
             "php-cs-fixer fix --ansi --dry-run --diff",