fix(dev): update dev tooling for changes in new surface (#6699)

googleapis · Oct 16, 2023 · 2c13327 · 2c13327
1 parent 82a5c69
commit 2c13327
Show file tree

Hide file tree

Showing 39 changed files with 9,326 additions and 3,034 deletions.
diff --git a/dev/src/ComponentPackage.php b/dev/src/ComponentPackage.php
@@ -50,7 +50,7 @@ public function getName(): string
 
     public function getProtoPackage(): string
     {
-        $gapicClientFiles = $this->getV1GapicClientFiles() + $this->getV2BaseClientFiles();
+        $gapicClientFiles = $this->getV1GapicClientFiles() + $this->getV2ClientFiles();
 
         foreach ($gapicClientFiles as $file) {
             $gapicClientContent = file_get_contents($file);
@@ -65,7 +65,7 @@ public function getProtoPackage(): string
     public function getMigrationStatus()
     {
         $hasV1Clients = count($this->getV1GapicClientFiles()) > 0;
-        $hasV2Clients = count($this->getV2BaseClientFiles()) > 0;
+        $hasV2Clients = count($this->getV2ClientFiles()) > 0;
         if ($hasV1Clients) {
             return $hasV2Clients ? self::MIGRATION_V1_AND_V2 : self::MIGRATION_V1;
         }
@@ -74,7 +74,7 @@ public function getMigrationStatus()
 
     public function getServiceAddress(): string
     {
-        $gapicClientFiles = $this->getV1GapicClientFiles() + $this->getV2BaseClientFiles();
+        $gapicClientFiles = $this->getV1GapicClientFiles() + $this->getV2ClientFiles();
         $gapicClientClasses = array_map(fn ($fp) => $this->getClassFromFile($fp), $gapicClientFiles);
 
         foreach ($gapicClientClasses as $className) {
@@ -101,17 +101,20 @@ public function getApiShortname(): string
 
     private function getV1GapicClientFiles(): array
     {
-        return $this->getFilesInDir('*GapicClient.php');
+        return $this->getFilesInDir('*GapicClient.php', $this->path . '/Gapic');
     }
 
-    private function getV2BaseClientFiles(): array
+    private function getV2ClientFiles(): array
     {
-        return $this->getFilesInDir('*BaseClient.php');
+        return $this->getFilesInDir('*Client.php', $this->path . '/Client');
     }
 
-    private function getFilesInDir(string $pattern): array
+    private function getFilesInDir(string $pattern, string $dir): array
     {
-        $result = (new Finder())->files()->name($pattern)->in($this->path);
+        if (!is_dir($dir)) {
+            return [];
+        }
+        $result = (new Finder())->files()->name($pattern)->in($dir);
         return array_map(fn ($file) => $file->getRealPath(), iterator_to_array($result));
     }
 

diff --git a/dev/src/DocFx/Node/ClassNode.php b/dev/src/DocFx/Node/ClassNode.php
@@ -84,15 +84,18 @@ public function isV1ServiceClass(): bool
     public function isServiceBaseClass(): bool
     {
         // returns true if the class extends a generated GAPIC client
-        return 'GapicClient' === substr($this->getName(), -11)
-            || 'BaseClient' === substr($this->getName(), -10);
+        return 'GapicClient' === substr($this->getName(), -11);
     }
 
     public function isV2ServiceClass(): bool
     {
-        // returns true if the class extends a generated V2 GAPIC client
-        if ($extends = $this->getExtends()) {
-            return 'BaseClient' === substr($extends, -10);
+        // returns true if the class does not extend another class and isn't a
+        // base class
+        if (!$this->getExtends()
+            && !$this->isServiceBaseClass()
+            && 'Client' === substr($this->getName(), -6)
+        ) {
+            return true;
         }
         return false;
     }

diff --git a/dev/src/DocFx/Page/PageTree.php b/dev/src/DocFx/Page/PageTree.php
@@ -79,31 +79,26 @@ private function loadPages(): array
             }
 
             // Manually skip GAPIC base clients
-            $fullName = $classNode->getFullname();
-            if ('GapicClient' === substr($fullName, -11)
-                || 'BaseClient' === substr($fullName, -10)) {
+            if ($classNode->isServiceBaseClass()) {
                 $gapicClients[] = $classNode;
                 continue;
             }
 
             // Skip internal classes
-            // Do this after the GAPIC check because new base clients are internal
             if ($classNode->isInternal()) {
                 continue;
             }
 
-            if ($classNode->isV1ServiceClass()) {
-                $this->hasV1Client = true;
-            } elseif ($classNode->isV2ServiceClass()) {
-                $this->hasV2Client = true;
-            }
+            $this->hasV1Client |= $classNode->isV1ServiceClass();
+            $this->hasV2Client |= $classNode->isV2ServiceClass();
 
             // Manually skip protobuf enums in favor of Gapic enums (see below).
             // @TODO: Do not generate them in V2, eventually mark them as deprecated
             $isDiregapic = $isDiregapic || $classNode->isGapicEnumClass();
 
             // Manually skip Grpc classes
             // @TODO: Do not generate Grpc classes in V2, eventually mark these as deprecated
+            $fullName = $classNode->getFullname();
             if (
                 'GrpcClient' === substr($fullName, -10)
                 && '\Grpc\BaseStub' === $classNode->getExtends()
@@ -142,6 +137,18 @@ private function loadPages(): array
         // We no longer need the array keys
         $pages = array_values($pageMap);
 
+        // Mark V2 services as "beta" if they have a V1 client
+        if ($this->hasV1Client && $this->hasV2Client) {
+            foreach ($pages as $page) {
+                if ($page->getClassNode()->isV2ServiceClass()) {
+                    $page->getClassNode()->setTocName(sprintf(
+                        '%s (beta)',
+                        $page->getClassNode()->getName()
+                    ));
+                }
+            }
+        }
+
         /**
          * Set a map of protobuf package names to PHP namespaces for Xrefs.
          * This MUST be done after combining GAPIC clients.
@@ -175,25 +182,13 @@ private function combineGapicClients(array $gapicClients, array $pageMap): array
         foreach ($gapicClients as $gapicClient) {
             // Find  Classname
             $parts = explode('\\', $gapicClient->getFullName());
-            $clientClassName = str_replace(
-                ['BaseClient', 'GapicClient'],
-                'Client',
-                array_pop($parts)
-            );
-            array_pop($parts); // remove "Gapic" or "Client" namespace
+            $clientClassName = str_replace('GapicClient', 'Client', array_pop($parts));
+            array_pop($parts); // remove "Gapic" namespace
             $parts[] = $clientClassName;
             $clientFullName = implode('\\', $parts);
             if (isset($pageMap[$clientFullName])) {
                 $parentClassNode = $pageMap[$clientFullName]->getClassNode();
                 $parentClassNode->setChildNode($gapicClient);
-                if ($this->hasV1Client && $this->hasV2Client) {
-                    if ($parentClassNode->isV2ServiceClass()) {
-                        $parentClassNode->setTocName(sprintf(
-                            '%s (beta)',
-                            $parentClassNode->getName()
-                        ));
-                    }
-                }
             }
         }
 

diff --git a/dev/tests/Unit/Command/DocFxCommandTest.php b/dev/tests/Unit/Command/DocFxCommandTest.php
@@ -76,6 +76,21 @@ public function testGenerateNewClientStructureXml()
         $this->assertFileEqualsWithDiff($left, $right, '1' === getenv('UPDATE_FIXTURES'));
     }
 
+    public function testGenerateSnippetsStructureXml()
+    {
+        $structureXml = __DIR__ . '/../../fixtures/phpdoc/clientsnippets.xml';
+        $componentPath = __DIR__ . '/../../fixtures/component/ClientSnippets';
+
+        $process = DocFxCommand::getPhpDocCommand($componentPath, self::$tmpDir);
+        $process->mustRun();
+
+        $this->assertFileEqualsWithDiff(
+            $structureXml,
+            self::$tmpDir . '/structure.xml',
+            '1' === getenv('UPDATE_FIXTURES')
+        );
+    }
+
     public function testGenerateDocFxFiles()
     {
         $fixturesFiles = array_diff(scandir(self::$fixturesDir . '/docfx/Vision'), ['..', '.']);
@@ -92,7 +107,7 @@ public function testDocFxFiles(string $file)
     {
         $this->assertTrue(
             file_exists(self::$fixturesDir . '/docfx/Vision/' . $file),
-            sprintf('%s does not exist in fixtures (%s)', $file, self::$tmpDir . '/' . $file)
+            sprintf('tests/fixtures/docfx/%s does not exist (%s)', $file, self::$tmpDir . '/' . $file)
         );
 
         $left  = self::$fixturesDir . '/docfx/Vision/' . $file;

diff --git a/dev/tests/Unit/DocFx/PageTest.php b/dev/tests/Unit/DocFx/PageTest.php
@@ -119,6 +119,5 @@ public function testHandleSample()
         $this->assertNotEmpty($rpcMethod['example']);
         $this->assertCount(1, $rpcMethod['example']);
         $this->assertStringContainsString('function an_rpc_method_sample', $rpcMethod['example'][0]);
-
     }
 }
diff --git a/...s/fixtures/component/ClientSnippets/src/V1/Client/BaseClient/ClientSnippetsBaseClient.php b/...s/fixtures/component/ClientSnippets/src/V1/Client/BaseClient/ClientSnippetsBaseClient.php
diff --git a/dev/tests/fixtures/component/ClientSnippets/src/V1/Client/ClientSnippetsClient.php b/dev/tests/fixtures/component/ClientSnippets/src/V1/Client/ClientSnippetsClient.php
@@ -2,8 +2,13 @@
 
 namespace Google\Cloud\ClientSnippets\Client;
 
-use Google\Cloud\ClientSnippets\Client\BaseClient\ClientSnippetsBaseClient;
-
-class ClientSnippetsClient extends ClientSnippetsBaseClient
+final class ClientSnippetsClient
 {
+    /**
+     * @example samples/V1/ClientSnippetsClient/an_rpc_method.php
+     */
+    public function anRpcMethod()
+    {
+
+    }
 }