Add redirects debugging tools (#2634)

Author: NWylynko

package-lock.json

@@ -8,6 +8,9 @@
     "lint:formatting": "prettier . --check",
     "lint:check-quickstarts": "node ./scripts/check-quickstarts.mjs",
     "lint:check-frontmatter": "node ./scripts/check-frontmatter.mjs",
+    "lint:check-redirects": "bun ./scripts/check-redirects.ts",
+    "lint:check-duplicate-redirects": "bun ./scripts/check-duplicate-redirects.ts",
+    "trace-redirect": "bun ./scripts/trace-redirect.ts",
     "build": "bun ./scripts/build-docs.ts",
     "build:tsx": "tsx ./scripts/build-docs.ts",
     "dev": "bun --watch ./scripts/build-docs.ts --watch",
@@ -33,6 +36,7 @@
     "dotenv": "^17.2.0",
     "glob": "^11.0.1",
     "jsonc-parser": "^3.3.1",
+    "path-to-regexp": "^6.3.0",
     "prettier": "^3.2.5",
     "prettier-plugin-astro": "^0.14.0",
     "prettier-plugin-nginx": "^1.0.3",

package.json

@@ -524,6 +524,11 @@
     "destination": "/docs/reference/nextjs/app-router/auth",
     "permanent": true
   },
+  {
+    "source": "/docs/reference/nextjs/auth",
+    "destination": "/docs/reference/nextjs/app-router/auth",
+    "permanent": true
+  },
   {
     "source": "/docs/nextjs/authentication-props",
     "destination": "/docs/reference/backend/types/auth-object",
@@ -1559,11 +1564,6 @@
     "destination": "/docs/guides/development/custom-flows/authentication/multi-session-applications",
     "permanent": true
   },
-  {
-    "source": "/docs/how-to/organizations",
-    "destination": "/docs/guides/organizations/overview",
-    "permanent": true
-  },
   {
     "source": "/docs/authentication/progressive-sign-up-beta",
     "destination": "/docs/guides/development/upgrading/upgrade-guides/progressive-sign-up",
@@ -1614,11 +1614,6 @@
     "destination": "/docs/reference/backend/organization/get-organization-invitation-list",
     "permanent": true
   },
-  {
-    "source": "/docs/reference/javascript/types/paginated-response",
-    "destination": "/docs/reference/javascript/types/clerk-paginated-response",
-    "permanent": true
-  },
   {
     "source": "/docs/reference/nextjs/with-clerk-middleware",
     "destination": "/docs/reference/nextjs/clerk-middleware",
@@ -2274,11 +2269,6 @@
     "destination": "/docs/guides/development/errors/overview",
     "permanent": true
   },
-  {
-    "source": "/docs/errors/",
-    "destination": "/docs/guides/development/errors/overview",
-    "permanent": true
-  },
   {
     "source": "/docs/errors/blocklist-identifiers",
     "destination": "/docs/guides/development/errors/overview",
@@ -2461,17 +2451,17 @@
   },
   {
     "source": "/docs/ai-prompts/nextjs",
-    "destination": "/docs/guides/ai-prompts",
+    "destination": "/docs/guides/development/ai-prompts",
     "permanent": true
   },
   {
     "source": "/docs/ai-prompts/overview",
-    "destination": "/docs/guides/ai-prompts",
+    "destination": "/docs/guides/development/ai-prompts",
     "permanent": true
   },
   {
     "source": "/docs/ai-prompts/react",
-    "destination": "/docs/guides/ai-prompts",
+    "destination": "/docs/guides/development/ai-prompts",
     "permanent": true
   },
   {
@@ -3160,12 +3150,12 @@
     "permanent": true
   },
   {
-    "source": "/docs/integrations/vercel-marketplace",
+    "source": "/docs/guides/development/integrations/vercel-marketplace",
     "destination": "/docs/guides/development/integrations/platforms/vercel-marketplace",
     "permanent": true
   },
   {
-    "source": "/docs/integrations/shopify",
+    "source": "/docs/guides/development/integrations/shopify",
     "destination": "/docs/guides/development/integrations/platforms/shopify",
     "permanent": true
   },
@@ -3529,6 +3519,11 @@
     "destination": "/docs/guides/development/machine-auth/m2m-tokens",
     "permanent": true
   },
+  {
+    "source": "/docs/quickstarts/overview",
+    "destination": "/docs/getting-started/quickstart/overview",
+    "permanent": true
+  },
   {
     "source": "/docs/quickstarts/nextjs",
     "destination": "/docs/nextjs/getting-started/quickstart",
@@ -3913,5 +3908,10 @@
     "source": "/docs/reference/nextjs/current-user",
     "destination": "/docs/reference/nextjs/app-router/current-user",
     "permanent": true
+  },
+  {
+    "source": "/docs/guides/configure/auth-strategies/overview",
+    "destination": "/docs/guides/configure/auth-strategies/sign-up-sign-in-options",
+    "permanent": true
   }
 ]

redirects/static/docs.json

@@ -0,0 +1,109 @@
+#!/usr/bin/env tsx
+
+/**
+ * Check Duplicate Redirects Script
+ *
+ * This script checks for duplicate redirect sources in the static redirects file.
+ * It provides friendly feedback about any duplicates found and suggests how to fix them.
+ *
+ * Usage:
+ *   npx tsx scripts/check-duplicate-redirects.ts
+ *   npm run lint:check-duplicate-redirects
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+interface Redirect {
+  source: string
+  destination: string
+  permanent: boolean
+}
+
+function validateNoDuplicateSources(redirects: Redirect[]): boolean {
+  const sourceMap = new Map<string, Redirect[]>()
+
+  // Group redirects by source
+  for (const redirect of redirects) {
+    if (!sourceMap.has(redirect.source)) {
+      sourceMap.set(redirect.source, [])
+    }
+    sourceMap.get(redirect.source)!.push(redirect)
+  }
+
+  // Find duplicates
+  const duplicates: Array<{ source: string; redirects: Redirect[] }> = []
+  for (const [source, redirectsForSource] of sourceMap.entries()) {
+    if (redirectsForSource.length > 1) {
+      duplicates.push({ source, redirects: redirectsForSource })
+    }
+  }
+
+  if (duplicates.length > 0) {
+    duplicates.forEach(({ source, redirects }) => {
+      const destinations = redirects.map((r) => r.destination)
+      const uniqueDestinations = [...new Set(destinations)]
+
+      if (uniqueDestinations.length === 1) {
+        console.log(`📝 "${source}" appears ${redirects.length} times`)
+        console.log(`   All pointing to: ${uniqueDestinations[0]}`)
+        console.log('   💡 This is just redundant - you can safely remove the duplicates')
+      } else {
+        console.log(`⚠️  "${source}" has ${redirects.length} conflicting destinations:`)
+        destinations.forEach((dest, i) => {
+          console.log(`   ${i + 1}. ${dest}`)
+        })
+        console.log('   💡 Please decide which destination is correct and remove the others')
+      }
+      console.log('')
+    })
+
+    console.log('🔧 To fix this, please:')
+    console.log('   1. Edit redirects/static/docs.json')
+    console.log('   2. Remove the duplicate entries listed above')
+    console.log('   3. Run this check again to verify')
+    console.log('')
+    console.log('✨ Once cleaned up, your redirects will be ready to go!')
+
+    return false
+  }
+
+  return true
+}
+
+async function checkDuplicateRedirects(): Promise<void> {
+  console.log('🔎 Checking for duplicate redirect sources...')
+
+  try {
+    const redirectsPath = path.join(process.cwd(), 'redirects', 'static', 'docs.json')
+    const content = await fs.readFile(redirectsPath, 'utf-8')
+    const redirects: Redirect[] = JSON.parse(content)
+
+    console.log(`📊 Found ${redirects.length} total redirects`)
+
+    const isValid = validateNoDuplicateSources(redirects)
+
+    if (isValid) {
+      console.log('✅ No duplicate redirect sources found! Your redirects look great.')
+    } else {
+      process.exitCode = 1
+    }
+  } catch (error) {
+    console.error('💥 Error reading redirects file:', error)
+    process.exitCode = 1
+  }
+}
+
+async function main() {
+  try {
+    await checkDuplicateRedirects()
+  } catch (error) {
+    console.error('💥 Error checking duplicate redirects:', error)
+    process.exitCode = 1
+  }
+}
+
+// Run the script if called directly
+if (require.main === module) {
+  main()
+}