fix(ui): resolve name, version and org in usePackageRoute across all

package-related routes

Author: WilhelmBerggren

app/composables/usePackageRoute.ts

@@ -1,23 +1,63 @@
 /**
- * Parse package name and optional version from the route URL.
+ * Parse package name and optional version from the current route URL.
  *
- * Routes use structured params:
- *   /package/nuxt → org: undefined, name: "nuxt"
- *   /package/@nuxt/kit → org: "@nuxt", name: "kit"
- *   /package/nuxt/v/4.2.0 → org: undefined, name: "nuxt", version: "4.2.0"
- *   /package/@nuxt/kit/v/1.0.0 → org: "@nuxt", name: "kit", version: "1.0.0"
+ * Works across every package-scoped route, which use different param shapes:
+ *   /package/nuxt                        → org: undefined, name: "nuxt"
+ *   /package/@nuxt/kit/v/1.0.0           → org: "@nuxt", name: "kit", version: "1.0.0"
+ *   /package-code/@nuxt/kit/v/1.0.0/...  → org: "@nuxt", packageName: "kit", version: "1.0.0"
+ *   /package-stats/nuxt/v/4.2.0          → packageName: "nuxt", version: "4.2.0"
+ *   /package-timeline/nuxt/v/4.2.0       → packageName: "nuxt", version: "4.2.0"
+ *   /package-docs/@nuxt/kit/v/1.0.0      → path: ["@nuxt", "kit", "v", "1.0.0"]
+ *
+ * Rather than pinning to a single named route, read the live route params and
+ * normalise the differing param names (`name` vs `packageName`) and the docs
+ * catch-all `path` into a common `{ org, name, version }` shape.
  */
 export function usePackageRoute() {
-  const route = useRoute<'package'>('package')
+  const route = useRoute()
+
+  const parsed = computed<{ org?: string; name?: string; version: string | null }>(() => {
+    const params = route.params as Record<string, string | string[] | undefined>
+
+    // Docs uses a single catch-all `path` param: [org?, name, "v", version?].
+    // The package prefix is one segment (unscoped) or two (scoped, "@org/name").
+    // A "v" only marks the version when it directly follows that prefix, so a
+    // package literally named "v" (e.g. /package-docs/v) isn't mistaken for a
+    // version delimiter and a later "v" stays part of the package name.
+    if (Array.isArray(params.path)) {
+      const segments = params.path.filter(Boolean)
+      const scoped = segments[0]?.startsWith('@') ?? false
+      const prefixLength = scoped ? 2 : 1
+      const org = scoped ? segments[0] : undefined
+      const name = segments.slice(scoped ? 1 : 0, prefixLength).join('/')
+      const version =
+        segments[prefixLength] === 'v' && segments.length > prefixLength + 1
+          ? segments.slice(prefixLength + 1).join('/')
+          : null
+      return { org, name, version }
+    }
+
+    const org = typeof params.org === 'string' ? params.org : undefined
+    // `package`/`changelog` name their param `name`; `code`/`stats`/`timeline`/`diff`
+    // name it `packageName`.
+    const name =
+      (typeof params.name === 'string' ? params.name : undefined) ??
+      (typeof params.packageName === 'string' ? params.packageName : undefined)
+    const version = typeof params.version === 'string' ? params.version : null
+
+    return { org, name, version }
+  })
 
   const packageName = computed(() => {
-    const { org, name } = route.params
+    const { org, name } = parsed.value
+    if (!name) return ''
     return org ? `${org}/${name}` : name
   })
 
-  const requestedVersion = computed(() => ('version' in route.params ? route.params.version : null))
+  const requestedVersion = computed(() => parsed.value.version)
+
   const orgName = computed(() => {
-    const org = route.params.org
+    const org = parsed.value.org
     return org ? org.replace(/^@/, '') : null
   })
 

test/nuxt/composables/use-package-route.spec.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest'
+
+// `useRoute()` cannot be mocked via `mockNuxtImport` in this runtime, so instead
+// we drive the app's real router. That has the upside of exercising the actual
+// route definitions: if a route's param names ever change (e.g. `packageName` →
+// `name`), these tests break, which is exactly what should happen since
+// `usePackageRoute` reads those params.
+async function at(url: string) {
+  await useRouter().push(url)
+  return usePackageRoute()
+}
+
+describe('usePackageRoute', () => {
+  describe('package / package-version routes (`name` param)', () => {
+    it('parses an unscoped package with no version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package/nuxt')
+      expect(packageName.value).toBe('nuxt')
+      expect(requestedVersion.value).toBeNull()
+      expect(orgName.value).toBeNull()
+    })
+
+    it('parses a scoped package with a version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package/@nuxt/kit/v/1.0.0')
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBe('1.0.0')
+      expect(orgName.value).toBe('nuxt')
+    })
+  })
+
+  describe('code / stats / timeline routes (`packageName` param)', () => {
+    it('parses the code route (scoped, with file path)', async () => {
+      const { packageName, requestedVersion, orgName } = await at(
+        '/package-code/@nuxt/kit/v/1.0.0/src/index.ts',
+      )
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBe('1.0.0')
+      expect(orgName.value).toBe('nuxt')
+    })
+
+    it('parses the stats route (unscoped)', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package-stats/nuxt/v/4.2.0')
+      expect(packageName.value).toBe('nuxt')
+      expect(requestedVersion.value).toBe('4.2.0')
+      expect(orgName.value).toBeNull()
+    })
+
+    it('parses the timeline route (scoped)', async () => {
+      const { packageName, requestedVersion, orgName } = await at(
+        '/package-timeline/@nuxt/kit/v/1.0.0',
+      )
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBe('1.0.0')
+      expect(orgName.value).toBe('nuxt')
+    })
+  })
+
+  describe('changelog routes (`name` param)', () => {
+    it('parses a scoped package with a version', async () => {
+      const { packageName, requestedVersion, orgName } = await at(
+        '/package-changelog/@nuxt/kit/v/1.0.0',
+      )
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBe('1.0.0')
+      expect(orgName.value).toBe('nuxt')
+    })
+  })
+
+  describe('docs route (catch-all `path` param)', () => {
+    it('parses a scoped package with a version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package-docs/@nuxt/kit/v/1.0.0')
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBe('1.0.0')
+      expect(orgName.value).toBe('nuxt')
+    })
+
+    it('parses an unscoped package with a version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package-docs/nuxt/v/4.2.0')
+      expect(packageName.value).toBe('nuxt')
+      expect(requestedVersion.value).toBe('4.2.0')
+      expect(orgName.value).toBeNull()
+    })
+
+    it('parses an unscoped package with no version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package-docs/nuxt')
+      expect(packageName.value).toBe('nuxt')
+      expect(requestedVersion.value).toBeNull()
+      expect(orgName.value).toBeNull()
+    })
+
+    it('parses a scoped package with no version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/package-docs/@nuxt/kit')
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBeNull()
+      expect(orgName.value).toBe('nuxt')
+    })
+
+    it('treats a package literally named "v" as the package, not a version marker', async () => {
+      const { packageName, requestedVersion } = await at('/package-docs/v')
+      expect(packageName.value).toBe('v')
+      expect(requestedVersion.value).toBeNull()
+    })
+
+    it('recognises the version marker only when it follows the package name', async () => {
+      // package "v" at version "1.0.0": the first "v" is the name, the second is the marker
+      const { packageName, requestedVersion } = await at('/package-docs/v/v/1.0.0')
+      expect(packageName.value).toBe('v')
+      expect(requestedVersion.value).toBe('1.0.0')
+    })
+  })
+
+  describe('diff route (`versionRange` param)', () => {
+    it('resolves the package/org but does not treat the range as a requested version', async () => {
+      const { packageName, requestedVersion, orgName } = await at('/diff/@nuxt/kit/v/1.0.0...2.0.0')
+      expect(packageName.value).toBe('@nuxt/kit')
+      expect(requestedVersion.value).toBeNull()
+      expect(orgName.value).toBe('nuxt')
+    })
+  })
+})