build(docs-infra): fix CLI command github links (#30889)

The "view" links were broken because the version used to
compute the git tag for the GitHub URL included a build SHA.
Now we clean that off before using it in the URL.

The links are to the JSON schema that defines the documentation for
the command. This is accurate but confusing because the content for the
long description is stored in a separate markdown file referenced from this
schema file.
This commit adds a second set of links for the long description, if it exists,
which links directly to the markdown file.

Closes #30700

PR Close #30889

aio/tools/transforms/cli-docs-package/readers/cli-command.js

@@ -26,22 +26,59 @@ module.exports = function cliCommandFileReader(log) {
           docType: 'cli-command',
           id: `cli-${doc.name}`,
           commandAliases: doc.aliases || [],
-          aliases: computeAliases(doc),
-          path,
+          aliases: computeAliases(doc), path,
           outputPath: `${path}.json`,
           breadCrumbs: [
-            { text: 'CLI', path: 'cli' },
-            { text: name, path },
+            {text: 'CLI', path: 'cli'},
+            {text: name, path},
           ]
         });
+        if (doc.longDescription) {
+          doc.longDescriptionDoc = createLongDescriptionDoc(fileInfo);
+        }
         return [result];
       } catch (e) {
         log.warn(`Failed to read cli command file: "${fileInfo.relativePath}" - ${e.message}`);
       }
     }
   };
-};
+  function computeAliases(doc) {
+    return [doc.name].concat(doc.aliases || []).map(alias => `cli-${alias}`);
+  }
 
-function computeAliases(doc) {
-  return [doc.name].concat(doc.aliases || []).map(alias => `cli-${alias}`);
-}
+  /**
+   * Synthesize a doc for the CLI command long description, which is used to generate links
+   * for viewing and editing the long description in GitHub.
+   *
+   * The long description is stored in a markdown file that is referenced from the original
+   * schema file for the command, via the `$longDescription` field. The field is a relative path
+   * to the markdown file from the schema file.
+   *
+   * This function tries to retrieve that original schema based on the file path of the help JSON
+   * file, which was passed to the `cliCommandFileReader.getDocs()` method.
+   */
+  function createLongDescriptionDoc(fileInfo) {
+    try {
+      const path = require('canonical-path');
+      const fs = require('fs');
+      const json5 = require('json5');
+
+      const schemaJsonPath = path.resolve(fileInfo.basePath, '../commands', fileInfo.relativePath);
+      const schemaJson = fs.readFileSync(schemaJsonPath);
+      const schema = json5.parse(schemaJson);
+      if (schema.$longDescription) {
+        return {
+          docType: 'content',
+          startingLine: 0,
+          fileInfo: {
+            realProjectRelativePath:
+                path.join(path.dirname(fileInfo.realProjectRelativePath), schema.$longDescription)
+          }
+        };
+      }
+    } catch (e) {
+      log.warn('Unable to read CLI long description file info', e, fileInfo);
+      return undefined;
+    }
+  }
+};