Validate redirects instead of rewriting them (#219)

In order to migrate the legacy custom site to Docusaurus, we added logic
to the Docusaurus config to convert redirects to use the Docusaurus
format. The logic included some steps to rewrite redirect sources and
desinations.

This change adjusts the logic to validate redirects instead and throw
errors on malformed redirects. This way, it is easier to troubleshoot
issues with redirects, since the redirects that a documentation author
would see are the same ones that Docusaurus processes.

As part of this, this change adds a rule to require a leading slash in
redirect paths. When validating redirects, Docusaurus ignores
destinations that do not begin with a slash, causing unexpected issues
for custom logic in the docs engine that expects redirect paths to begin
with slashes.

For context, see the following file in facebook/docusaurus#9171:

packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts

Author: ptgott

server/redirects.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "@jest/globals";
+import { CustomRedirect, validateRedirect } from "./redirects";
+
+describe("validateRedirects", () => {
+  interface testCase {
+    description: string;
+    input: CustomRedirect;
+    shouldThrow: boolean;
+    errorSubstring: string;
+  }
+  const testCases: Array<testCase> = [
+    {
+      description: "incorrect index page source",
+      input: {
+        source: "/enroll-resources/applications/applications/",
+        destination: "/enroll-resources/apps/",
+        permanent: true,
+      },
+      shouldThrow: true,
+      errorSubstring:
+        "redirect source includes an incorrect category index page path - remove the final path segment: /enroll-resources/applications/applications/",
+    },
+    {
+      description: "incorrect index page destination",
+      input: {
+        source: "/enroll-resources/apps/",
+        destination: "/enroll-resources/applications/applications/",
+        permanent: true,
+      },
+      shouldThrow: true,
+      errorSubstring:
+        "redirect destination includes an incorrect category index page path - remove the final path segment: /enroll-resources/applications/applications/",
+    },
+    {
+      description: "no leading slash in a source",
+      input: {
+        source: "enroll-resources/apps/",
+        destination: "/enroll-resources/applications/applications/",
+        permanent: true,
+      },
+      shouldThrow: true,
+      errorSubstring:
+        "redirect source must start with a trailing slash: enroll-resources/apps/",
+    },
+    {
+      description: "no leading slash in a destination",
+      input: {
+        source: "/enroll-resources/apps/",
+        destination: "enroll-resources/applications/applications/",
+        permanent: true,
+      },
+      shouldThrow: true,
+      errorSubstring:
+        "redirect destination includes an incorrect category index page path - remove the final path segment: enroll-resources/applications/applications/",
+    },
+    {
+      description: "valid case",
+      input: {
+        source: "/enroll-resources/apps/",
+        destination: "/enroll-resources/applications/",
+        permanent: true,
+      },
+      shouldThrow: false,
+      errorSubstring: "",
+    },
+  ];
+
+  test.each(testCases)("$description", (c) => {
+    if (c.shouldThrow) {
+      expect(() => {
+        validateRedirect(c.input);
+      }).toThrow(c.errorSubstring);
+    } else {
+      expect(() => {
+        validateRedirect(c.input);
+      }).not.toThrow();
+    }
+  });
+});

server/redirects.ts

@@ -5,56 +5,48 @@ const versions = getVersionNames();
 
 // Gather all redirects from all versions and convert them in the Docusaurus format.
 
+export interface CustomRedirect {
+  source: string;
+  destination: string;
+  permanent: boolean;
+}
+
+const isIndexPage = (urlpath: string): boolean => {
+  const parts = urlpath.split("/").filter((p) => p !== "");
+  return (
+    parts.length >= 2 && parts[parts.length - 1] == parts[parts.length - 2]
+  );
+};
+
+export const validateRedirect = (redirect: CustomRedirect) => {
+  ["source", "destination"].forEach((p) => {
+    if (isIndexPage(redirect[p])) {
+      throw new Error(
+        `redirect ${p} includes an incorrect category index page path - remove the final path segment: ${redirect[p]}`,
+      );
+    }
+    if (!redirect[p].startsWith("/")) {
+      throw new Error(
+        `redirect ${p} must start with a trailing slash: ${redirect[p]}`,
+      );
+    }
+  });
+
+  return;
+};
+
 export const getRedirects = () => {
   const result = versions.flatMap((version) => {
     const config = loadDocsConfig(version, ".");
 
     return config.redirects || [];
   });
 
-  return result.map((redirect) => {
-    // If a page is an index page for a section, it has the same name as the
-    // containing subdirectory. Handle this logic to accommodate redirects
-    // from the previous docs site.
-    const sourceSegs = redirect.source
-      .replaceAll(new RegExp("/$", "g"), "")
-      .split("/");
-
-    const destSegs = redirect.destination
-      .replaceAll(new RegExp("/$", "g"), "")
-      .split("/");
-
-    // The destination is an index page, since the slug matches the containing
-    // path segment.
-    const destIndex =
-      destSegs.length >= 2 &&
-      destSegs[destSegs.length - 1] == destSegs[destSegs.length - 2];
-
-    if (!destIndex) {
-      return {
-        from: redirect.source,
-        to: redirect.destination,
-      };
-    }
-
-    const docusaurusDest =
-      destSegs.slice(0, -1).join("/") + "/";
-
-    // This redirect maps a Docusaurus-style index page to a previous-site index
-    // page, so reverse the mapping.
-    if (redirect.source == docusaurusDest) {
-      const oldSource = redirect.source;
-      redirect.source = redirect.destination;
-      redirect.destination = oldSource;
-      // This redirect has an old-style index page path as a destination, so
-      // change it to a Docusaurus-style one.
-    } else {
-      redirect.destination = docusaurusDest;
-    }
-
+  result.forEach(validateRedirect);
+  return result.map((r) => {
     return {
-      from: redirect.source,
-      to: redirect.destination,
+      from: r.source,
+      to: r.destination,
     };
   });
 };