tests: docs coverage now checks ai-reference.md too, exempt list derived by reflection

- ai-reference.md ships in the Composer bundle but had no coverage test;
  all 45 public methods were already in it, now a test keeps it that way
- the deprecated-method exemptions come from reflecting the Deprecations
  trait instead of a hand-copied list that had to be kept in sync

Author: daveedis

tests/Integration/DocsCoverageTest.php

@@ -3,26 +3,28 @@
 
 namespace Itools\SmartString\Tests\Integration;
 
+use Itools\SmartString\Deprecations;
 use Itools\SmartString\SmartString;
 use PHPUnit\Framework\Attributes\DataProvider;
 use ReflectionClass;
 use ReflectionMethod;
 use Itools\SmartString\Tests\Support\SmartStringTestCase;
 
 /**
- * Every public method must appear in the docs method reference, so new
- * methods can't ship undocumented.
+ * Every public method must appear in the docs method reference and in
+ * ai-reference.md (the one docs file that ships in the Composer bundle),
+ * so new methods can't ship undocumented.
  *
  * Exemptions:
  * - magic methods, jsonSerialize(), getIterator(): interface plumbing, never
  *   called directly (getIterator only throws a foreach-misuse error)
- * - everything in the Deprecations trait: renamed and retired methods
- *   keep working but stay out of the docs by design - docs show only the
- *   current names
+ * - everything in the Deprecations trait (derived by reflection): renamed and
+ *   retired methods keep working but stay out of the docs by design - docs
+ *   show only the current names
  */
 class DocsCoverageTest extends SmartStringTestCase
 {
-    private const EXEMPT = ['and', 'andPrefix', 'apply', 'dateTimeFormat', 'help', 'if', 'ifBlank', 'phoneFormat', 'textToHtml', 'jsonSerialize', 'getIterator'];
+    private const INTERFACE_PLUMBING = ['jsonSerialize', 'getIterator'];
 
     #[DataProvider('publicMethodsProvider')]
     public function testMethodIsInMethodReference(string $method): void
@@ -34,14 +36,31 @@ public function testMethodIsInMethodReference(string $method): void
         );
     }
 
+    #[DataProvider('publicMethodsProvider')]
+    public function testMethodIsInAiReference(string $method): void
+    {
+        // ai-reference writes methods bare (`textOnly(): SmartString`), so no arrow prefix
+        $reference = file_get_contents(dirname(__DIR__, 2) . '/docs/ai-reference.md');
+        $this->assertTrue(
+            str_contains($reference, "$method("),
+            "Public method $method() is not mentioned in docs/ai-reference.md"
+        );
+    }
+
     public static function publicMethodsProvider(): array
     {
+        $deprecated = array_map(
+            static fn(ReflectionMethod $m) => $m->getName(),
+            (new ReflectionClass(Deprecations::class))->getMethods(ReflectionMethod::IS_PUBLIC)
+        );
+        $exempt = [...$deprecated, ...self::INTERFACE_PLUMBING];
+
         $methods = (new ReflectionClass(SmartString::class))->getMethods(ReflectionMethod::IS_PUBLIC);
 
         $rows = [];
         foreach ($methods as $method) {
             $name = $method->getName();
-            if (str_starts_with($name, '__') || in_array($name, self::EXEMPT, true)) {
+            if (str_starts_with($name, '__') || in_array($name, $exempt, true)) {
                 continue;
             }
             $rows[$name] = [$name];
@@ -51,10 +70,12 @@ public static function publicMethodsProvider(): array
 
     /**
      * The exemption list stays honest: exempt methods must still exist.
+     * (The Deprecations trait names exist by definition, so only the
+     * hand-listed plumbing needs checking.)
      */
     public function testExemptMethodsStillExist(): void
     {
-        foreach (self::EXEMPT as $method) {
+        foreach (self::INTERFACE_PLUMBING as $method) {
             $this->assertTrue(method_exists(SmartString::class, $method), "Exempt method $method() no longer exists - remove it from the list");
         }
     }