Merge pull request #17 from script-development/armorer/rule-author-contract-tests

test: add rule-author contract tests (F-6 + F-7)

Author: Goosterhof

tests/Rules/RuleDocblockContractTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace ScriptDevelopment\PhpstanWarroomRules\Tests\Rules;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+
+/**
+ * Locks the package's own rule-author convention: every class under `src/Rules/`
+ * must declare a `Doctrine source:` line in its class-level docblock so the rule's
+ * authority (ADR or war-room principle) is visible at the source.
+ *
+ * Doctrine source: ADR-0021 §Doctrine source in docblock.
+ *
+ * This test enforces *how rules are written*, not *what rules check*. It does not
+ * contradict the package's "static-analysis library only" stance (CLAUDE.md
+ * §"What this territory does NOT do") because PHPUnit reflection on rule classes
+ * is rule-authoring discipline, not rule enforcement.
+ */
+final class RuleDocblockContractTest extends TestCase
+{
+    #[Test]
+    public function every_rule_class_declares_doctrine_source_in_class_docblock(): void
+    {
+        $ruleFiles = glob(__DIR__ . '/../../src/Rules/*.php');
+
+        self::assertNotEmpty($ruleFiles, 'No rule files found under src/Rules');
+
+        foreach ($ruleFiles as $file) {
+            $namespace = 'ScriptDevelopment\PhpstanWarroomRules\Rules';
+            $class = $namespace . '\\' . basename($file, '.php');
+
+            self::assertTrue(class_exists($class), "Rule class not autoloadable: {$class}");
+
+            $docblock = (new ReflectionClass($class))->getDocComment();
+
+            self::assertNotFalse(
+                $docblock,
+                "{$class} has no class-level docblock (ADR-0021 §Doctrine source in docblock).",
+            );
+
+            self::assertStringContainsString(
+                'Doctrine source:',
+                $docblock,
+                "{$class} class-level docblock does not name its doctrine source. ADR-0021 §Doctrine source in docblock requires every rule to cite its ADR or war-room principle.",
+            );
+        }
+    }
+}

tests/Rules/RuleIdentifierConventionTest.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace ScriptDevelopment\PhpstanWarroomRules\Tests\Rules;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+use function sprintf;
+
+/**
+ * Locks the package's own rule-author convention: every
+ * `RuleErrorBuilder::message()->identifier(...)` call in `src/Rules/*.php` must
+ * use a `cameLCase.cameLCase` identifier so consumers see a uniform shape across
+ * every rule the package ships.
+ *
+ * Doctrine source: ADR-0021 §Identifier convention.
+ *
+ * Like RuleDocblockContractTest, this enforces rule-authoring discipline (a
+ * lexical contract on identifier strings), not rule enforcement.
+ */
+final class RuleIdentifierConventionTest extends TestCase
+{
+    private const string IDENTIFIER_PATTERN = '/->identifier\(\s*[\'"]([^\'"]+)[\'"]\s*\)/';
+
+    private const string CONVENTION_PATTERN = '/^[a-z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*$/';
+
+    #[Test]
+    public function every_rule_identifier_follows_camel_dot_camel_convention(): void
+    {
+        $ruleFiles = glob(__DIR__ . '/../../src/Rules/*.php');
+
+        self::assertNotEmpty($ruleFiles, 'No rule files found under src/Rules');
+
+        $allIdentifiers = [];
+        foreach ($ruleFiles as $file) {
+            $source = file_get_contents($file);
+            self::assertNotFalse($source, "Could not read {$file}");
+
+            preg_match_all(self::IDENTIFIER_PATTERN, $source, $matches);
+
+            foreach ($matches[1] as $identifier) {
+                $allIdentifiers[] = [$file, $identifier];
+                self::assertMatchesRegularExpression(
+                    self::CONVENTION_PATTERN,
+                    $identifier,
+                    sprintf(
+                        'Identifier "%s" in %s does not follow ADR-0021 §Identifier convention (cameLCase.cameLCase).',
+                        $identifier,
+                        basename($file),
+                    ),
+                );
+            }
+        }
+
+        self::assertNotEmpty(
+            $allIdentifiers,
+            'No identifiers found across rule files — regex broken or rules lack ->identifier() calls.',
+        );
+    }
+}