feat(core/github): support custom pullsURL and commitHistoryURL (#5100)

Author: daniel-montalvo

src/core/github.js

@@ -93,18 +93,81 @@ export async function run(conf) {
   }
   const branch = conf.github.branch || "gh-pages";
   const issueBase = new URL("./issues/", ghURL).href;
-  const commitHistoryURL = new URL(
-    `./commits/${conf.github.branch ?? ""}`,
-    ghURL.href
-  );
+
+  // Allow custom pullsURL and commitHistoryURL for monorepo scenarios
+  let pullsURL;
+  if (
+    typeof conf.github === "object" &&
+    conf.github.hasOwnProperty("pullsURL")
+  ) {
+    pullsURL = conf.github.pullsURL;
+  } else {
+    pullsURL = new URL("./pulls/", ghURL).href;
+  }
+
+  // Validate pullsURL if it's provided
+  if (pullsURL) {
+    try {
+      const pullsURLObj = new URL(pullsURL);
+      if (pullsURLObj.origin !== "https://github.com") {
+        const msg = docLink`${"[github.pullsURL]"} must be HTTPS and pointing to GitHub. (${pullsURL}).`;
+        rejectGithubPromise(msg);
+        return;
+      }
+      if (!pullsURLObj.pathname.includes("/pulls")) {
+        const msg = docLink`${"[github.pullsURL]"} must point to pull requests. (${pullsURL}).`;
+        rejectGithubPromise(msg);
+        return;
+      }
+    } catch {
+      const msg = docLink`${"[github.pullsURL]"} is not a valid URL. (${pullsURL}).`;
+      rejectGithubPromise(msg);
+      return;
+    }
+  }
+
+  let commitHistoryURL;
+  if (
+    typeof conf.github === "object" &&
+    conf.github.hasOwnProperty("commitHistoryURL")
+  ) {
+    commitHistoryURL = conf.github.commitHistoryURL;
+  } else {
+    commitHistoryURL = new URL(
+      `./commits/${conf.github.branch ?? ""}`,
+      ghURL.href
+    ).href;
+  }
+
+  // Validate commitHistoryURL if it's provided
+  if (commitHistoryURL) {
+    try {
+      const commitURLObj = new URL(commitHistoryURL);
+      if (commitURLObj.origin !== "https://github.com") {
+        const msg = docLink`${"[github.commitHistoryURL]"} must be HTTPS and pointing to GitHub. (${commitHistoryURL}).`;
+        rejectGithubPromise(msg);
+        return;
+      }
+      if (!commitURLObj.pathname.includes("/commits")) {
+        const msg = docLink`${"[github.commitHistoryURL]"} must point to commits. (${commitHistoryURL}).`;
+        rejectGithubPromise(msg);
+        return;
+      }
+    } catch {
+      const msg = docLink`${"[github.commitHistoryURL]"} is not a valid URL. (${commitHistoryURL}).`;
+      rejectGithubPromise(msg);
+      return;
+    }
+  }
+
   const newProps = {
     edDraftURI: `https://${org.toLowerCase()}.github.io/${repo}/`,
     githubToken: undefined,
     githubUser: undefined,
     issueBase,
     atRiskBase: issueBase,
     otherLinks: [],
-    pullBase: new URL("./pulls/", ghURL).href,
+    pullBase: pullsURL,
     shortName: repo,
   };
   // Assign new properties, but retain existing ones
@@ -133,11 +196,11 @@ export async function run(conf) {
         },
         {
           value: l10n.commit_history,
-          href: commitHistoryURL.href,
+          href: commitHistoryURL,
         },
         {
           value: "Pull requests",
-          href: newProps.pullBase,
+          href: pullsURL,
         },
       ],
     };
@@ -152,9 +215,9 @@ export async function run(conf) {
     apiBase: githubAPI,
     fullName: `${org}/${repo}`,
     issuesURL: issueBase,
-    pullsURL: newProps.pullBase,
+    pullsURL,
     newIssuesURL: new URL("./new/choose", issueBase).href,
-    commitHistoryURL: commitHistoryURL.href,
+    commitHistoryURL,
   };
   resolveGithubPromise(normalizedGHObj);
 

tests/spec/core/github-spec.js

@@ -81,6 +81,33 @@ describe("Core - Github", () => {
       const doc = await makeRSDoc(opts);
       doesntOverrideTest(doc);
     });
+    it("normalizes github object with custom pullsURL and commitHistoryURL", async () => {
+      const opts = {
+        config: Object.assign(makeBasicConfig(), {
+          github: {
+            repoURL: "https://github.com/w3c/core-aam/",
+            pullsURL: "https://github.com/w3c/aria/pulls/",
+            commitHistoryURL: "https://github.com/w3c/aria/commits/",
+          },
+        }),
+        body: makeDefaultBody(),
+      };
+      delete opts.config.edDraftURI;
+      delete opts.config.shortName;
+
+      const doc = await makeRSDoc(opts);
+      const { respecConfig: conf } = doc.defaultView;
+
+      // Check that the github object is normalized correctly
+      expect(conf.github.pullsURL).toBe("https://github.com/w3c/aria/pulls/");
+      expect(conf.github.commitHistoryURL).toBe(
+        "https://github.com/w3c/aria/commits/"
+      );
+      expect(conf.github.issuesURL).toBe(
+        "https://github.com/w3c/core-aam/issues/"
+      );
+      expect(conf.github.repoURL).toBe("https://github.com/w3c/core-aam/");
+    });
   });
   describe("the definition list items (localized)", () => {
     const l10n = {
@@ -135,5 +162,54 @@ describe("Core - Github", () => {
         "https://github.com/speced/respec/commits/develop"
       );
     });
+    it("supports custom pullsURL and commitHistoryURL for monorepo scenarios", async () => {
+      const customOpt = {
+        config: Object.assign(makeBasicConfig(), {
+          github: {
+            repoURL: "https://github.com/w3c/core-aam/",
+            pullsURL:
+              "https://github.com/w3c/aria/pulls?q=+label%3A%22spec%3Acore-aam%22is%3Apr+is%3Aopen+",
+            commitHistoryURL:
+              "https://github.com/w3c/aria/commits/main/core-aam",
+          },
+          excludeGithubLinks: false,
+        }),
+        body: makeDefaultBody(),
+        htmlAttrs: {
+          lang: "nl",
+        },
+      };
+      delete customOpt.config.edDraftURI;
+      delete customOpt.config.shortName;
+
+      const doc = await makeRSDoc(customOpt);
+
+      // Check that the custom pull request URL with parameters is used
+      const pullRequests = Array.from(doc.querySelectorAll("dd")).find(
+        elem => elem.textContent.trim() === "Pull requests"
+      );
+      expect(pullRequests).toBeTruthy();
+      expect(pullRequests.querySelector("a").href).toBe(
+        "https://github.com/w3c/aria/pulls?q=+label%3A%22spec%3Acore-aam%22is%3Apr+is%3Aopen+"
+      );
+
+      // Check that the custom commit history URL is used
+      const commitHistory = Array.from(doc.querySelectorAll("dd")).find(
+        elem => elem.textContent.trim() === "Revisiehistorie"
+      );
+      expect(commitHistory).toBeTruthy();
+      expect(commitHistory.querySelector("a").href).toBe(
+        "https://github.com/w3c/aria/commits/main/core-aam"
+      );
+
+      // Issue base should still use repoURL
+      const fileABug = Array.from(doc.querySelectorAll("dd")).find(
+        elem => elem.textContent.trim() === "Dien een melding in"
+      );
+      expect(fileABug).toBeTruthy();
+      expect(fileABug.querySelector("a").href).toBe(
+        "https://github.com/w3c/core-aam/issues/"
+      );
+    });
   });
 });