From 995c591c2a845b7f923fe9a44537a4d572e75c54 Mon Sep 17 00:00:00 2001
From: Brent Shaffer <betterbrent@google.com>
Date: Mon, 7 Oct 2024 14:54:06 -0700
Subject: [PATCH] add command to list broken xrefs

---
 dev/google-cloud                           |  2 +
 dev/src/Command/ListBrokenXrefsCommand.php | 67 ++++++++++++++++++++++
 dev/src/DocFx/Node/ClassNode.php           |  4 +-
 dev/src/DocFx/XrefValidationTrait.php      |  1 +
 4 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 dev/src/Command/ListBrokenXrefsCommand.php

diff --git a/dev/google-cloud b/dev/google-cloud
index 4683cd760b98..806aeb71a794 100755
--- a/dev/google-cloud
+++ b/dev/google-cloud
@@ -25,6 +25,7 @@ require __DIR__ . '/vendor/autoload.php';
 use Google\Cloud\Dev\Command\AddComponentCommand;
 use Google\Cloud\Dev\Command\ComponentInfoCommand;
 use Google\Cloud\Dev\Command\DocFxCommand;
+use Google\Cloud\Dev\Command\ListBrokenXrefsCommand;
 use Google\Cloud\Dev\Command\RepoInfoCommand;
 use Google\Cloud\Dev\Command\ReleaseInfoCommand;
 use Google\Cloud\Dev\Command\SplitCommand;
@@ -45,6 +46,7 @@ $app = new Application;
 $app->add(new AddComponentCommand($rootDirectory));
 $app->add(new ComponentInfoCommand());
 $app->add(new DocFxCommand());
+$app->add(new ListBrokenXrefsCommand());
 $app->add(new RepoInfoCommand());
 $app->add(new ReleaseInfoCommand());
 $app->add(new SplitCommand($rootDirectory));
diff --git a/dev/src/Command/ListBrokenXrefsCommand.php b/dev/src/Command/ListBrokenXrefsCommand.php
new file mode 100644
index 000000000000..703a1f4d1c29
--- /dev/null
+++ b/dev/src/Command/ListBrokenXrefsCommand.php
@@ -0,0 +1,67 @@
+<?php
+/**
+ * Copyright 2024 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Dev\Command;
+
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\ArrayInput;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\BufferedOutput;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Process\Process;
+use Google\Cloud\Dev\Component;
+
+/**
+ * @internal
+ */
+class ListBrokenXrefsCommand extends Command
+{
+    const BROKEN_REFS_REGEX = '/\[(\w+)\] Broken xref in (.*) \((.*)\): (.*)/';
+
+    protected function configure()
+    {
+        $this->setName('list-broken-xrefs')
+            ->setDescription('List all the broken xrefs in the documentation using ".kokoro/docs/publish.sh"')
+        ;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        foreach (Component::getComponents() as $component) {
+            $input = new ArrayInput($f = [
+                'command' => 'docfx',
+                '--component' => $component->getName(),
+            ]);
+
+            $buffer = new BufferedOutput(OutputInterface::VERBOSITY_DEBUG);
+            $returnCode = $this->getApplication()->doRun($input, $buffer);
+            foreach (explode("\n", $buffer->fetch()) as $line) {
+                if (preg_match(self::BROKEN_REFS_REGEX, $line, $matches)) {
+                    list(, $component, $file, $ref, $brokenText) = $matches;
+                    $link = sprintf(
+                        '=HYPERLINK("https://github.com/googleapis/googleapis/blob/master/%s", "%s")',
+                        $file,
+                        $file
+                    );
+                    $output->writeln(implode(',', [$component, $link, $ref, $brokenText]));
+                }
+            }
+        }
+
+        return 0;
+    }
+}
diff --git a/dev/src/DocFx/Node/ClassNode.php b/dev/src/DocFx/Node/ClassNode.php
index 4d1a6a287ed5..82644fb30325 100644
--- a/dev/src/DocFx/Node/ClassNode.php
+++ b/dev/src/DocFx/Node/ClassNode.php
@@ -101,10 +101,10 @@ public function getProtoFileName(string $ref = null): string|null
             if ($ref1 && $ref2) {
                 if (false !== stripos($line, $ref1)
                     && false !== stripos($lines[$i+1], $ref2)) {
-                    return $proto . '#' . ($i + 1);
+                    return $proto . '#L' . ($i + 1);
                 }
             } elseif (false !== stripos($line, $ref)) {
-                return $proto . '#' . ($i + 1);
+                return $proto . '#L' . ($i + 1);
             }
         }
 
diff --git a/dev/src/DocFx/XrefValidationTrait.php b/dev/src/DocFx/XrefValidationTrait.php
index 7ec63deba4a2..570deaea734c 100644
--- a/dev/src/DocFx/XrefValidationTrait.php
+++ b/dev/src/DocFx/XrefValidationTrait.php
@@ -19,6 +19,7 @@
 
 use Google\Cloud\Core\Logger\AppEngineFlexFormatter;
 use Google\Cloud\Core\Logger\AppEngineFlexFormatterV2;
+use Google\Cloud\Dev\Component;
 
 /**
  * @internal