feat(phpstan): add CanonicalCapitalizationRule for enforcing term spelling

phpstan.neon

@@ -36,8 +36,12 @@ parameters:
     paths:
     - tests/PHPStan/data/
 
+  # Test fixtures intentionally contain Lab ID capitalization violations
+  - message: '#should use "Lab ID" instead of#'
+    paths:
+    - tests/PHPStan/data/
+
   # PHPStan internal API usage is acceptable in tests
   - message: '#is not covered by backward compatibility promise#'
     paths:
     - tests/PHPStan/
-

src/PHPStan/Rules/CanonicalCapitalizationRule.php

@@ -0,0 +1,94 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\PHPStan\Rules;
+
+use Illuminate\Support\Str;
+use PhpParser\Node;
+use PhpParser\Node\Scalar\String_;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+
+/**
+ * Only checks string literals because canonical forms like "Lab ID" contain spaces,
+ * which are invalid in PHP identifiers (variables, methods, classes).
+ *
+ * @implements Rule<String_>
+ */
+abstract class CanonicalCapitalizationRule implements Rule
+{
+    abstract protected function getCanonicalForm(): string;
+
+    /** @return array<int, string> */
+    abstract protected function getWrongVariants(): array;
+
+    abstract protected function getErrorIdentifier(): string;
+
+    public function getNodeType(): string
+    {
+        return String_::class;
+    }
+
+    /** @param String_ $node */
+    public function processNode(Node $node, Scope $scope): array
+    {
+        if ($this->hasLanguageAnnotation($node)) {
+            return [];
+        }
+
+        $value = $node->value;
+
+        if ($this->cannotContainSpaces($value)) {
+            return [];
+        }
+
+        $wrongVariant = $this->findWrongVariant($value);
+
+        if ($wrongVariant === null) {
+            return [];
+        }
+
+        $expectedValue = $this->fixCapitalization($value, $wrongVariant);
+
+        return [
+            RuleErrorBuilder::message(<<<TXT
+                String "{$value}" should use "{$this->getCanonicalForm()}" instead of "{$wrongVariant}", change it to "{$expectedValue}".
+                TXT)
+                ->identifier($this->getErrorIdentifier())
+                ->build(),
+        ];
+    }
+
+    protected function cannotContainSpaces(string $value): bool
+    {
+        return ! str_contains($value, ' ');
+    }
+
+    /** @see https://www.jetbrains.com/help/phpstorm/using-language-injections.html */
+    protected function hasLanguageAnnotation(String_ $node): bool
+    {
+        foreach ($node->getComments() as $comment) {
+            if (Str::contains($comment->getText(), '@lang')) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    public function findWrongVariant(string $value): ?string
+    {
+        foreach ($this->getWrongVariants() as $wrongVariant) {
+            if (Str::contains($value, $wrongVariant)) {
+                return $wrongVariant;
+            }
+        }
+
+        return null;
+    }
+
+    public function fixCapitalization(string $value, string $wrongVariant): string
+    {
+        return str_replace($wrongVariant, $this->getCanonicalForm(), $value);
+    }
+}

src/PHPStan/Rules/IdToIDRule.php

@@ -23,7 +23,6 @@ abstract protected function getErrorIdentifier(): string;
 
     abstract protected function extractName(Node $node): ?string;
 
-    /** Override for custom formatting (e.g., adding $ prefix for variables). */
     protected function formatNameForMessage(string $name): string
     {
         return $name;

src/PHPStan/Rules/LabIDCapitalizationRule.php

@@ -0,0 +1,32 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\PHPStan\Rules;
+
+final class LabIDCapitalizationRule extends CanonicalCapitalizationRule
+{
+    protected function getCanonicalForm(): string
+    {
+        return 'Lab ID';
+    }
+
+    /** @return array<int, string> */
+    protected function getWrongVariants(): array
+    {
+        return [
+            'LabID',
+            'labID',
+            'LABID',
+            'Labid',
+            'labid',
+            'Lab-ID',
+            'lab-Id',
+            'Lab Id',
+            'lab id',
+        ];
+    }
+
+    protected function getErrorIdentifier(): string
+    {
+        return 'mll.labIDCapitalization';
+    }
+}

tests/PHPStan/IdToIDRuleIntegrationTest.php

@@ -0,0 +1,54 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Tests\PHPStan;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+
+final class IdToIDRuleIntegrationTest extends PHPStanIntegrationTestCase
+{
+    private const ERROR_PATTERN = 'should use "ID" instead of "Id"';
+
+    /** @return iterable<array{0: string, 1: array<int, array<int, string>>}> */
+    public static function dataIntegrationTests(): iterable
+    {
+        self::getContainer();
+
+        yield 'wrong capitalization' => [__DIR__ . '/data/wrong-capitalization.php', [
+            5 => [
+                'Name of Stmt_Class "LabIdProcessor" should use "ID" instead of "Id", rename it to "LabIDProcessor".',
+            ],
+            7 => [
+                'Name of Stmt_ClassMethod "getLabId" should use "ID" instead of "Id", rename it to "getLabID".',
+            ],
+            12 => [
+                'Name of Stmt_ClassMethod "processLabId" should use "ID" instead of "Id", rename it to "processLabID".',
+                'Name of Param "$labId" should use "ID" instead of "Id", rename it to "$labID".',
+            ],
+            14 => [
+                'Name of Expr_Variable "$sampleId" should use "ID" instead of "Id", rename it to "$sampleID".',
+                'Name of Expr_Variable "$labId" should use "ID" instead of "Id", rename it to "$labID".',
+            ],
+        ]];
+
+        yield 'correct capitalization' => [__DIR__ . '/data/correct-capitalization.php', []];
+    }
+
+    /**
+     * @param array<int, array<int, string>> $expectedErrors
+     *
+     * @dataProvider dataIntegrationTests
+     */
+    #[DataProvider('dataIntegrationTests')]
+    public function testIntegration(string $file, array $expectedErrors): void
+    {
+        $errors = $this->analyseFile($file);
+        $filteredErrors = $this->filterErrors($errors, self::ERROR_PATTERN);
+
+        if ($expectedErrors === []) {
+            self::assertEmpty($filteredErrors, 'Should not report errors for correct capitalization');
+        } else {
+            self::assertNotEmpty($filteredErrors, 'Should detect wrong capitalization');
+            $this->assertExpectedErrors($expectedErrors, $filteredErrors);
+        }
+    }
+}

tests/PHPStan/LabIDCapitalizationRuleIntegrationTest.php

@@ -0,0 +1,65 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Tests\PHPStan;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+
+/**
+ * @requires PHP >= 8.3
+ */
+final class LabIDCapitalizationRuleIntegrationTest extends PHPStanIntegrationTestCase
+{
+    private const ERROR_PATTERN = 'should use "Lab ID"';
+
+    /** @return iterable<string, array{0: string, 1: array<int, array<int, string>>}> */
+    public static function dataIntegrationTests(): iterable
+    {
+        self::getContainer();
+
+        yield 'detects wrong capitalization' => [
+            __DIR__ . '/data/lab-id-capitalization.php',
+            [
+                9 => ['String "The LabID is wrong" should use "Lab ID" instead of "LabID", change it to "The Lab ID is wrong".'],
+                30 => ['String "
+            {
+                patient {
+                    labID
+                }
+            }
+        " should use "Lab ID" instead of "labID", change it to "
+            {
+                patient {
+                    Lab ID
+                }
+            }
+        ".'],
+                66 => ['String "
+            SELECT exam_no AS labID
+            FROM examinations
+        " should use "Lab ID" instead of "labID", change it to "
+            SELECT exam_no AS Lab ID
+            FROM examinations
+        ".'],
+            ],
+        ];
+    }
+
+    /**
+     * @param array<int, array<int, string>> $expectedErrors
+     *
+     * @dataProvider dataIntegrationTests
+     */
+    #[DataProvider('dataIntegrationTests')]
+    public function testIntegration(string $file, array $expectedErrors): void
+    {
+        $errors = $this->analyseFile($file);
+        $filteredErrors = $this->filterErrors($errors, self::ERROR_PATTERN);
+
+        if ($expectedErrors === []) {
+            self::assertEmpty($filteredErrors, 'Should not report errors for correct capitalization');
+        } else {
+            self::assertNotEmpty($filteredErrors, 'Should detect wrong Lab ID capitalization');
+            $this->assertExpectedErrors($expectedErrors, $filteredErrors);
+        }
+    }
+}