fix: allow overriding source directory per class in GitHub links (#285)

Currently, the doclet assumes the source directory name matches the
artifact ID when generating GitHub links. This leads to broken links
for libraries where they differ, such as Firestore (artifact:
`google-cloud-firestore`, directory: `google-cloud-firestore-admin`
for `FirestoreAdminClient`).

This change adds an optional `library_path_overrides` map to
`RepoMetadata` and updates `ClassBuilder` to check this map using the
simple class name before falling back to the artifact ID.

Fixes: b/442875200

Author: jinseopkim0

third_party/docfx-doclet-143274/src/main/java/com/google/docfx/doclet/RepoMetadata.java

@@ -8,6 +8,8 @@
 import java.io.IOException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.util.Collections;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -49,6 +51,9 @@ public class RepoMetadata {
   @SerializedName("recommended_package")
   private String recommendedPackage;
 
+  @SerializedName("library_path_overrides")
+  private Map<String, String> libraryPathOverrides;
+
   private String artifactId;
 
   public String getNamePretty() {
@@ -135,6 +140,14 @@ public void setApiId(String apiId) {
     this.apiId = apiId;
   }
 
+  public Map<String, String> getLibraryPathOverrides() {
+    return this.libraryPathOverrides != null ? this.libraryPathOverrides : Collections.emptyMap();
+  }
+
+  public void setLibraryPathOverrides(Map<String, String> libraryPathOverrides) {
+    this.libraryPathOverrides = libraryPathOverrides;
+  }
+
   // artifactId is parsed from distributionName
   public String getArtifactId() {
     String substrings[] = this.distributionName.split(":");

third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/ClassBuilder.java

@@ -248,13 +248,16 @@ private void addClientClassInfo(
 
   private String createClientOverviewTable(TypeElement classElement, RepoMetadata repoMetadata) {
     String clientURI = classLookup.extractUid(classElement).replaceAll("\\.", "/");
+    String className = classElement.getSimpleName().toString();
+
+    // Check overrides map first, otherwise default to artifactId
+    String directory =
+        repoMetadata
+            .getLibraryPathOverrides()
+            .getOrDefault(className, repoMetadata.getArtifactId());
+
     String githubSourceLink =
-        repoMetadata.getGithubLink()
-            + "/"
-            + repoMetadata.getArtifactId()
-            + "/src/main/java/"
-            + clientURI
-            + ".java";
+        repoMetadata.getGithubLink() + "/" + directory + "/src/main/java/" + clientURI + ".java";
     StringBuilder tableBuilder = new StringBuilder();
     tableBuilder
         .append("<table>")

third_party/docfx-doclet-143274/src/test/java/com/google/docfx/doclet/RepoMetadataTest.java

@@ -0,0 +1,29 @@
+package com.google.docfx.doclet;
+
+import static org.junit.Assert.assertEquals;
+
+import com.google.gson.Gson;
+import org.junit.Test;
+
+public class RepoMetadataTest {
+
+  @Test
+  public void testParseWithLibraryPathOverrides() {
+    String json =
+        "{ "
+            + "\"distribution_name\": \"com.google.cloud:google-cloud-firestore\", "
+            + "\"library_path_overrides\": { "
+            + "  \"FirestoreAdminClient\": \"google-cloud-firestore-admin\" "
+            + "}, "
+            + "\"repo\": \"googleapis/java-firestore\" "
+            + "}";
+
+    RepoMetadata metadata = new Gson().fromJson(json, RepoMetadata.class);
+
+    assertEquals("google-cloud-firestore", metadata.getArtifactId());
+    // Verify the map is populated correctly
+    assertEquals(
+        "google-cloud-firestore-admin",
+        metadata.getLibraryPathOverrides().get("FirestoreAdminClient"));
+  }
+}

third_party/docfx-doclet-143274/src/test/java/com/microsoft/build/ClassBuilderTest.java

@@ -16,8 +16,10 @@
 package com.microsoft.build;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
 import static org.mockito.Mockito.when;
 
+import com.google.docfx.doclet.RepoMetadata;
 import com.google.testing.compile.CompilationRule;
 import com.microsoft.lookup.ClassItemsLookup;
 import com.microsoft.lookup.ClassLookup;
@@ -28,6 +30,9 @@
 import com.sun.source.util.DocTrees;
 import java.io.File;
 import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+import javax.lang.model.element.Name; // Required for mocking getSimpleName()
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
 import jdk.javadoc.doclet.DocletEnvironment;
@@ -89,4 +94,47 @@ public void addConstructorsInfo() {
     Collection<MetadataFileItem> constructorItems = container.getItems();
     assertEquals("Container should contain 2 constructor items", constructorItems.size(), 2);
   }
+
+  @Test
+  public void createClientOverviewTable_usesLibraryPathOverride() {
+    // 1. Setup Mock RepoMetadata
+    RepoMetadata repoMetadata = new RepoMetadata();
+    repoMetadata.setRepo("googleapis/java-firestore");
+    repoMetadata.setDistributionName("com.google.cloud:google-cloud-firestore:1.0.0");
+
+    Map<String, String> overrides = new HashMap<>();
+    overrides.put("FirestoreAdminClient", "google-cloud-firestore-admin");
+    repoMetadata.setLibraryPathOverrides(overrides);
+
+    // 2. Mock ClassLookup and Element
+    ClassLookup classLookup = Mockito.mock(ClassLookup.class);
+    TypeElement classElement = Mockito.mock(TypeElement.class);
+
+    Name simpleName = Mockito.mock(Name.class);
+    when(simpleName.toString()).thenReturn("FirestoreAdminClient");
+    when(classElement.getSimpleName()).thenReturn(simpleName);
+
+    when(classLookup.extractUid(classElement))
+        .thenReturn("com.google.cloud.firestore.v1.FirestoreAdminClient");
+
+    // 3. Test
+    ClassBuilder builder = new ClassBuilder(null, classLookup, null, null, null, null);
+
+    try {
+      java.lang.reflect.Method method =
+          ClassBuilder.class.getDeclaredMethod(
+              "createClientOverviewTable", TypeElement.class, RepoMetadata.class);
+      method.setAccessible(true);
+      String html = (String) method.invoke(builder, classElement, repoMetadata);
+
+      // 4. Verify link contains "google-cloud-firestore-admin" and the double slash "//"
+      assertTrue(
+          "Link should use the override directory",
+          html.contains(
+              "googleapis/java-firestore/tree/main//google-cloud-firestore-admin/src/main/java"));
+
+    } catch (Exception e) {
+      throw new RuntimeException(e);
+    }
+  }
 }