npm - jamdesk - Versions diffs - 1.1.35 → 1.1.38 - Mend

jamdesk 1.1.35 → 1.1.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (49) hide show

package/dist/__tests__/integration/init.integration.test.js +41 -0
package/dist/__tests__/integration/init.integration.test.js.map +1 -1
package/dist/__tests__/unit/docs-config.test.js +17 -0
package/dist/__tests__/unit/docs-config.test.js.map +1 -1
package/dist/__tests__/unit/init.test.js +2 -1
package/dist/__tests__/unit/init.test.js.map +1 -1
package/dist/lib/docs-config.d.ts +4 -1
package/dist/lib/docs-config.d.ts.map +1 -1
package/dist/lib/docs-config.js +27 -23
package/dist/lib/docs-config.js.map +1 -1
package/package.json +1 -1
package/templates/api-reference/openapi-example.mdx +55 -0
package/templates/api-reference/request-response-examples.mdx +210 -0
package/templates/docs.json +27 -0
package/templates/openapi/example-api.yaml +185 -0
package/vendored/app/[[...slug]]/page.tsx +26 -8
package/vendored/app/api/chat/[project]/route.ts +53 -3
package/vendored/app/api/docs-search/[project]/search/route.ts +83 -3
package/vendored/app/layout.tsx +26 -3
package/vendored/components/HtmlLangSync.tsx +38 -0
package/vendored/components/mdx/OpenApiEndpoint.tsx +2 -1
package/vendored/components/navigation/LanguageSelector.tsx +18 -21
package/vendored/components/navigation/TableOfContents.tsx +18 -3
package/vendored/components/search/SearchModal.tsx +7 -14
package/vendored/hooks/useChat.ts +22 -4
package/vendored/lib/chat-prompt.ts +1 -1
package/vendored/lib/chat-tools.ts +3 -0
package/vendored/lib/embedding-chunker.ts +18 -2
package/vendored/lib/language-codes.json +27 -0
package/vendored/lib/language-utils.ts +98 -6
package/vendored/lib/link-rewriter.ts +67 -0
package/vendored/lib/locale-helpers.ts +62 -0
package/vendored/lib/middleware-helpers.ts +57 -2
package/vendored/lib/openapi/code-examples.ts +5 -6
package/vendored/lib/openapi/derive-auth.ts +46 -0
package/vendored/lib/openapi/index.ts +7 -0
package/vendored/lib/openapi/parser.ts +7 -2
package/vendored/lib/openapi/resolve-server-url.ts +14 -0
package/vendored/lib/openapi/types.ts +2 -0
package/vendored/lib/page-isr-helpers.ts +20 -0
package/vendored/lib/path-safety.ts +96 -0
package/vendored/lib/search-client.ts +67 -10
package/vendored/lib/seo.ts +80 -13
package/vendored/lib/static-artifacts.ts +25 -1
package/vendored/lib/vector-store.ts +70 -17
package/vendored/scripts/build-search-index.cjs +59 -0
package/vendored/scripts/validate-links.cjs +21 -66
package/vendored/themes/base.css +5 -0
package/vendored/workspace-package-lock.json +16 -16

package/vendored/lib/middleware-helpers.ts CHANGED Viewed

@@ -17,6 +17,7 @@ import { redis } from './redis';
 import { getForwardedHosts, isJamdeskDomain } from './domain-helpers';
 import { getRedirects, matchRedirect, mergeQueryStrings, isInvalidDestination } from './redirect-matcher';
 import { ASSET_PREFIX } from './docs-types';
+import { extractLanguageFromPath } from './language-utils';
 import type { NextRequest } from 'next/server';
 /**
@@ -536,25 +537,79 @@ export function getHostAtDocsRedirect(
   return null;
 }
+/**
+ * Headers we own end-to-end: written by middleware, trusted by the layout.
+ * Strip any inbound copy from the cloned request before we set our own,
+ * otherwise a client can send `x-jd-language: ar` (or `x-project-slug: evil`)
+ * and the layout will trust it. Same shape of bug as inbound `x-forwarded-*`.
+ */
+const TRUSTED_PROXY_HEADERS = [
+  'x-project-slug',
+  'x-host-at-docs',
+  'x-jd-language',
+] as const;
 /**
  * Build response headers with project context.
  *
+ * Sets:
+ *   - x-project-slug   — resolved project for downstream handlers
+ *   - x-host-at-docs   — whether docs are mounted at /docs
+ *   - x-jd-language    — locale code if the path starts with one (e.g. /fr/...)
+ *
+ * Strips any client-supplied copies of those headers from the inbound
+ * request to prevent header smuggling.
+ *
  * @param projectSlug - Resolved project slug
- * @param hostAtDocs - Whether docs are hosted at /docs
  * @param existingHeaders - Existing request headers to clone
+ * @param hostAtDocs - Whether docs are hosted at /docs
+ * @param pathname - The request pathname (request.nextUrl.pathname or, for
+ *   the unlock direct-hit branch, the `from` query param). Used to derive
+ *   the active locale so the root layout can emit <html lang>.
  * @returns New headers with project context added
  */
 export function buildProjectHeaders(
   projectSlug: string,
   existingHeaders: Headers,
-  hostAtDocs = true
+  hostAtDocs: boolean,
+  pathname: string,
 ): Headers {
   const newHeaders = new Headers(existingHeaders);
+  for (const h of TRUSTED_PROXY_HEADERS) {
+    newHeaders.delete(h);
+  }
   newHeaders.set('x-project-slug', projectSlug);
   newHeaders.set('x-host-at-docs', hostAtDocs ? 'true' : 'false');
+  const language = extractLanguageFromPath(pathname);
+  if (language) {
+    newHeaders.set('x-jd-language', language);
+  }
   return newHeaders;
 }
+/**
+ * Recover a pathname from the `from` query param on /jd/unlock.
+ *
+ * The unlock URL itself carries no locale ("/jd/unlock"), but the user's
+ * original path is encoded in `?from=` (e.g. `?from=%2Ffr%2Ffoo`). The
+ * proxy uses this to derive the active locale so the unlock page renders
+ * with the user's language, not the project default.
+ *
+ * Returns "" when input is null, empty, or unparseable. The caller treats
+ * this as "no language signal available" and falls back to project default.
+ */
+export function pathnameFromUnlockFrom(from: string | null): string {
+  if (!from) return '';
+  try {
+    return new URL(from, 'http://x').pathname;
+  } catch {
+    return '';
+  }
+}
 /**
  * Asset extensions that need to be routed to the assets API.
  */

package/vendored/lib/openapi/code-examples.ts CHANGED Viewed

@@ -11,11 +11,10 @@ import type {
   CodeExample,
   JsonSchema,
 } from './types';
+import type { ApiAuthMethod } from '../docs-types';
+import { resolveServerUrl } from './resolve-server-url';
-/**
- * Supported auth methods from docs.json
- */
-export type AuthMethod = 'bearer' | 'basic' | 'key' | 'cobo';
+export type AuthMethod = ApiAuthMethod;
 /**
  * Configuration for code example generation
@@ -194,7 +193,7 @@ export function buildGeneratorContext(
   config: CodeExampleConfig
 ): GeneratorContext {
   const { method, path, parameters, requestBody } = endpoint;
-  const baseUrl = endpoint.servers[0]?.url || DEFAULT_BASE_URL;
+  const baseUrl = resolveServerUrl(endpoint.servers[0]) || DEFAULT_BASE_URL;
   const formattedPath = formatPathWithParams(path, parameters);
   const queryString = formatQueryParams(parameters);
   const fullUrl = `${baseUrl}${formattedPath}${queryString}`;
@@ -257,7 +256,7 @@ export function generatePythonExample(
   // Python handles query params separately (params=params in request call),
   // so we build the URL without query string
-  const baseUrl = endpoint.servers[0]?.url || DEFAULT_BASE_URL;
+  const baseUrl = resolveServerUrl(endpoint.servers[0]) || DEFAULT_BASE_URL;
   const formattedPath = formatPathWithParams(endpoint.path, parameters);
   const pythonUrl = `${baseUrl}${formattedPath}`;

package/vendored/lib/openapi/derive-auth.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import type { AuthMethod } from './code-examples';
+import type { SecurityRequirement } from './types';
+export interface DerivedAuth {
+  method?: AuthMethod;
+  headerName?: string;
+}
+/**
+ * Derive playground auth config from a parsed OpenAPI security list.
+ *
+ * Returns `{}` when no scheme is renderable in the playground (empty list,
+ * apiKey-in-query/cookie, etc). docs.json `api.mdx.auth` should still take
+ * precedence over this — callers in page.tsx merge with the docs.json value first.
+ *
+ * Falls through past schemes the playground can't render, so a spec offering
+ * "either apiKey-in-query or bearer" still works.
+ */
+export function deriveAuthFromSecurity(security: SecurityRequirement[]): DerivedAuth {
+  for (const req of security) {
+    const mapped = mapSingle(req);
+    if (mapped.method) return mapped;
+  }
+  return {};
+}
+function mapSingle(req: SecurityRequirement): DerivedAuth {
+  if (req.type === 'http') {
+    if (req.scheme === 'bearer') return { method: 'bearer' };
+    if (req.scheme === 'basic') return { method: 'basic' };
+    return {};
+  }
+  if (req.type === 'apiKey') {
+    if (req.in === 'header' && req.parameterName) {
+      return { method: 'key', headerName: req.parameterName };
+    }
+    return {};
+  }
+  if (req.type === 'oauth2' || req.type === 'openIdConnect') {
+    return { method: 'bearer' };
+  }
+  return {};
+}

package/vendored/lib/openapi/index.ts CHANGED Viewed

@@ -90,3 +90,10 @@ export {
   generateNavigationGroups,
   getSpecStats,
 } from './generator';
+// Auth derivation
+export type { DerivedAuth } from './derive-auth';
+export { deriveAuthFromSecurity } from './derive-auth';
+// Server URL resolution
+export { resolveServerUrl } from './resolve-server-url';

package/vendored/lib/openapi/parser.ts CHANGED Viewed

@@ -5,7 +5,7 @@
  * Extracts parameters, request bodies, responses, and security info.
  */
-import type { OpenAPI, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import type { OpenAPI, OpenAPIV3 } from 'openapi-types';
 import type {
   HttpMethod,
   ParsedOpenApiFrontmatter,
@@ -219,10 +219,14 @@ function parseSecuritySchemes(api: OpenAPI.Document): Map<string, SecurityRequir
         scheme: 'scheme' in s ? s.scheme : undefined,
         in: 'in' in s ? s.in as SecurityRequirement['in'] : undefined,
         bearerFormat: 'bearerFormat' in s ? s.bearerFormat : undefined,
+        parameterName:
+          s.type === 'apiKey' && 'name' in s
+            ? (s as OpenAPIV3.ApiKeySecurityScheme).name
+            : undefined,
       });
     }
   }
   // Swagger 2.0
   if ('securityDefinitions' in api) {
     const defs = (api as any).securityDefinitions;
@@ -233,6 +237,7 @@ function parseSecuritySchemes(api: OpenAPI.Document): Map<string, SecurityRequir
         type: s.type,
         scheme: s.scheme,
         in: s.in,
+        parameterName: s.type === 'apiKey' ? s.name : undefined,
       });
     }
   }

package/vendored/lib/openapi/resolve-server-url.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import type { ServerInfo } from './types';
+/**
+ * Substitute `{varname}` placeholders in an OpenAPI server URL with the
+ * defaults declared in `server.variables`. Unknown placeholders are left
+ * intact so they remain visible to the user rather than producing a broken
+ * URL fragment.
+ */
+export function resolveServerUrl(server: ServerInfo | undefined): string | undefined {
+  if (!server) return undefined;
+  return server.url.replace(/\{(\w+)\}/g, (_, key: string) => {
+    return server.variables?.[key]?.default ?? `{${key}}`;
+  });
+}

package/vendored/lib/openapi/types.ts CHANGED Viewed

@@ -120,6 +120,8 @@ export interface SecurityRequirement {
   scheme?: string;  // For http type: 'bearer', 'basic'
   in?: 'query' | 'header' | 'cookie';  // For apiKey type
   bearerFormat?: string;
+  /** For apiKey schemes: the header / query / cookie parameter name (e.g. 'X-Api-Key'). */
+  parameterName?: string;
 }
 /**

package/vendored/lib/page-isr-helpers.ts CHANGED Viewed

@@ -5,6 +5,9 @@
  * These are extracted to be testable without importing Next.js components.
  */
+import { isValidLanguageCode } from './language-utils';
+import type { LanguageCode } from './docs-types';
 /**
  * Check if ISR mode is enabled.
  */
@@ -155,3 +158,20 @@ export function getBaseUrl(headers: Headers, projectSlug: string, hostAtDocs = f
   // Fallback to subdomain URL (subdomains always serve at root, never /docs)
   return `https://${projectSlug}.jamdesk.app`;
 }
+/**
+ * Read the active locale from request headers.
+ *
+ * The middleware (proxy.ts → buildProjectHeaders) sets `x-jd-language` based
+ * on the URL path (e.g. `/fr/intro` → "fr"). Returns null when the header is
+ * absent (path had no language prefix, or middleware did not run — e.g. local
+ * CLI dev) or when the value is not a recognised LanguageCode.
+ *
+ * Callers should fall back to the project's default language and then "en".
+ */
+export function getLanguageFromRequest(headers: Headers): LanguageCode | null {
+  const value = headers.get('x-jd-language');
+  if (!value) return null;
+  if (!isValidLanguageCode(value)) return null;
+  return value;
+}

package/vendored/lib/path-safety.ts CHANGED Viewed

@@ -97,6 +97,102 @@ export function validateDocsPath(
   return { valid: true, resolvedPath: resolved };
 }
+/**
+ * Validates a git ref (branch name) for use in `git clone --branch <ref>`.
+ *
+ * Combines two rule sets:
+ * 1. git's `check-ref-format` constraints (forbids `..`, `@{`, trailing `.lock`,
+ *    leading/trailing `/`, control chars, and a handful of ASCII punctuation).
+ * 2. A strict shell-safety allowlist — even though `cloneRepo` now uses
+ *    `execFileSync` with an argv array, this validator is defense-in-depth so
+ *    a future refactor that reintroduces a shell cannot be silently exploited.
+ *
+ * Allowed characters: A–Z, a–z, 0–9, and `._-/`.
+ *
+ * @param ref - Git ref received from a client (webhook payload / API request)
+ * @returns `{ valid: true }` or `{ valid: false, error }`
+ */
+export function validateGitRef(ref: unknown): SlugValidationResult {
+  if (typeof ref !== 'string') {
+    return { valid: false, error: 'Invalid git ref: must be a string' };
+  }
+  // Deliberately do NOT trim. The caller passes `ref` verbatim into argv, so
+  // the validator must judge the exact string the caller will use. If a
+  // consumer wants to allow trimming, they must trim before calling.
+  if (ref.length === 0) {
+    return { valid: false, error: 'Invalid git ref: cannot be empty' };
+  }
+  if (ref.length > 255) {
+    return { valid: false, error: 'Invalid git ref: exceeds 255 characters' };
+  }
+  // Allowlist: alphanumerics plus `._-/` only.
+  // Everything outside this set — including every shell metacharacter
+  // (`;`, backtick, `$`, `|`, `&`, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`,
+  // single/double quotes, `\`, `#`, `!`, `*`, `?`, `~`, `^`, `:`, spaces,
+  // tabs, newlines, null bytes, and all other control chars) — is rejected.
+  if (!/^[A-Za-z0-9._\-\/]+$/.test(ref)) {
+    return { valid: false, error: 'Invalid git ref: contains disallowed characters' };
+  }
+  // The following enforce git check-ref-format rules that the allowlist
+  // cannot express positionally — characters like `.`, `/`, and `-` are
+  // permitted in general but disallowed in specific positions or sequences.
+  if (ref.includes('..')) {
+    return { valid: false, error: 'Invalid git ref: cannot contain ".." sequences' };
+  }
+  if (ref.startsWith('/') || ref.endsWith('/')) {
+    return { valid: false, error: 'Invalid git ref: cannot start or end with "/"' };
+  }
+  if (ref.startsWith('.') || ref.endsWith('.')) {
+    return { valid: false, error: 'Invalid git ref: cannot start or end with "."' };
+  }
+  if (ref.endsWith('.lock')) {
+    return { valid: false, error: 'Invalid git ref: cannot end with ".lock"' };
+  }
+  // Block leading `-` so git does not parse the ref as a CLI flag
+  // (e.g. `-oProxyCommand=...`, `--upload-pack=...`).
+  if (ref.startsWith('-')) {
+    return { valid: false, error: 'Invalid git ref: cannot start with "-"' };
+  }
+  return { valid: true };
+}
+/**
+ * Validates a GitHub `owner/repo` full-name string.
+ *
+ * Allowlist per segment: `[A-Za-z0-9][A-Za-z0-9_.-]*` with 1–100 chars each.
+ * Exactly one `/` separating owner and repo. Leading `-` is rejected so the
+ * value cannot be mistaken for a CLI flag even if it ever escapes argv to a
+ * shell (defense-in-depth).
+ *
+ * @param repoFullName - Full repo name from a webhook/API payload
+ * @returns `{ valid: true }` or `{ valid: false, error }`
+ */
+export function validateRepoFullName(repoFullName: unknown): SlugValidationResult {
+  if (typeof repoFullName !== 'string') {
+    return { valid: false, error: 'Invalid repoFullName: must be a string' };
+  }
+  // No trim: validate the exact string the caller will pass into argv.
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(repoFullName)) {
+    return {
+      valid: false,
+      error: 'Invalid repoFullName: must match owner/repo with alphanumerics, "_", ".", or "-"',
+    };
+  }
+  // Defense in depth against path traversal: `..` segments could resolve
+  // outside the intended repos dir if this value ever flows into a path-join.
+  if (repoFullName.includes('..')) {
+    return { valid: false, error: 'Invalid repoFullName: cannot contain ".." sequences' };
+  }
+  return { valid: true };
+}
 /**
  * Validates a project slug for use in file paths.
  * Defense-in-depth: slugs come from Firestore but should still be validated

package/vendored/lib/search-client.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 // Client-side search with Orama (BM25 ranking)
 import { create, insertMultiple, search as oramaSearch, type Orama } from '@orama/orama';
+import { resolveLocaleWithLoweredSet } from './language-utils';
 export interface SearchResult {
   id: string;
@@ -9,6 +10,8 @@ export interface SearchResult {
   slug: string;
   section?: string;
   type?: 'api' | 'component' | 'guide' | 'help' | 'quickstart';
+  /** Language of the document. Empty string for default-language pages. */
+  locale: string;
 }
 type OramaDb = Orama<{
@@ -19,6 +22,7 @@ type OramaDb = Orama<{
   slug: 'string';
   section: 'string';
   type: 'string';
+  locale: 'enum';
 }>;
 // Orama database instance
@@ -33,6 +37,18 @@ let initPromise: Promise<void> | null = null;
 let lastEtag = '';
 let lastParsedData: SearchResult[] | null = null;
+/**
+ * Non-empty locale values present in the currently-committed index.
+ * Empty Set means either (a) the index has zero translated docs (single-
+ * language project) or (b) the index is a legacy build that predates the
+ * locale field. In either case the language filter is a no-op.
+ *
+ * `projectLocalesLowered` mirrors the same set lowercased — kept around so
+ * `resolveActiveLocale` doesn't re-lowercase per keystroke.
+ */
+let projectLocales: Set<string> = new Set();
+let projectLocalesLowered: ReadonlySet<string> = new Set();
 /**
  * Cheap fingerprint: count + first/last IDs + a sample of content lengths.
  * Detects new/removed pages AND content edits (which change content length).
@@ -60,20 +76,34 @@ async function buildIndex(data: SearchResult[], etag: string): Promise<void> {
       slug: 'string',
       section: 'string',
       type: 'string',
+      locale: 'enum',
     },
   });
-  const normalizedData = data.map(item => ({
-    id: item.id,
-    title: item.title,
-    description: item.description || '',
-    content: item.content,
-    slug: item.slug,
-    section: item.section || '',
-    type: item.type || 'guide',
-  }));
+  // Detect a legacy (pre-feature) index by inspecting the RAW input — once the
+  // ?? '' fallback runs in the map below, we can't tell "doc had locale=''" from
+  // "doc was missing the locale field entirely".
+  const seenLocales = new Set<string>();
+  const normalizedData = data.map(item => {
+    const raw = item.locale;
+    if (typeof raw === 'string' && raw.length > 0) seenLocales.add(raw);
+    return {
+      id: item.id,
+      title: item.title,
+      description: item.description || '',
+      content: item.content,
+      slug: item.slug,
+      section: item.section || '',
+      type: item.type || 'guide',
+      locale: raw ?? '',
+    };
+  });
   await insertMultiple(db, normalizedData);
+  projectLocales = seenLocales;
+  projectLocalesLowered = new Set(Array.from(seenLocales, (l) => l.toLowerCase()));
   committedFingerprint = buildingFingerprint;
   lastParsedData = data;
   lastEtag = etag;
@@ -104,7 +134,11 @@ export function getLastData(etag: string | null): SearchResult[] | null {
   return lastParsedData;
 }
-export async function search(query: string, limit = 10): Promise<SearchResult[]> {
+export async function search(
+  query: string,
+  limit = 10,
+  language?: string,
+): Promise<SearchResult[]> {
   if (!db) {
     console.warn('Search database not initialized');
     return [];
@@ -114,6 +148,12 @@ export async function search(query: string, limit = 10): Promise<SearchResult[]>
     return [];
   }
+  // Legacy-index safety: if the committed index has zero translated docs
+  // (single-language project OR pre-feature search-data.json), skip the where
+  // clause so un-rebuilt R2 files behave identically to before this feature.
+  const useFilter = projectLocales.size > 0;
+  const targetLocale = language ?? '';
   const results = await oramaSearch(db, {
     term: query,
     limit,
@@ -124,6 +164,7 @@ export async function search(query: string, limit = 10): Promise<SearchResult[]>
       description: 1,
       content: 0.5,
     },
+    ...(useFilter ? { where: { locale: { eq: targetLocale } } } : {}),
   });
   return results.hits.map(hit => hit.document as unknown as SearchResult);
@@ -134,3 +175,19 @@ export function isInitialized(): boolean {
   return db !== null;
 }
+/**
+ * Resolve the locale that the search filter should target for a given pathname,
+ * gated by the locales actually present in the currently-committed index.
+ *
+ * Returns:
+ *   - `''` when there is no committed index yet, OR no translations exist, OR
+ *     the pathname's prefix is not a translated locale.
+ *   - The canonical language code when the prefix matches an indexed locale.
+ *
+ * Caller (SearchModal) should pass the result to `search()`. Empty string and
+ * undefined are equivalent — both target the default-language doc set.
+ */
+export function resolveActiveLocale(pathname: string): string {
+  if (projectLocalesLowered.size === 0) return '';
+  return resolveLocaleWithLoweredSet(pathname, projectLocalesLowered);
+}

package/vendored/lib/seo.ts CHANGED Viewed

@@ -99,9 +99,63 @@ export interface PageFrontmatter {
   };
 }
+/**
+ * Walk a navigation node (LanguageConfig, GroupConfig, etc.) and collect every
+ * page path declared anywhere underneath it. Pages can appear under `pages`,
+ * `groups`, `tabs`, `anchors`, `dropdowns`, `products`, `versions`, or `menu`,
+ * and groups nest. Permissive `unknown` typing handles every container shape
+ * with one walker — keep the key list in sync with new container types in
+ * docs-types.ts (a future container would silently miss pages otherwise).
+ */
+function collectPagePathsUnder(node: unknown, out: Set<string>): void {
+  if (!node || typeof node !== 'object') return;
+  const obj = node as Record<string, unknown>;
+  const pages = obj.pages;
+  if (Array.isArray(pages)) {
+    for (const entry of pages) {
+      if (typeof entry === 'string') {
+        out.add(entry);
+      } else if (entry && typeof entry === 'object') {
+        const page = (entry as { page?: unknown }).page;
+        if (typeof page === 'string') out.add(page);
+        else collectPagePathsUnder(entry, out); // nested group inside `pages`
+      }
+    }
+  }
+  for (const key of ['groups', 'tabs', 'anchors', 'dropdowns', 'products', 'versions', 'menu']) {
+    const children = obj[key];
+    if (Array.isArray(children)) {
+      for (const child of children) collectPagePathsUnder(child, out);
+    }
+  }
+}
+// Same `LanguageConfig` reference is reused across every page render in a
+// config's cache window (see r2-content.ts configCache + IsrContentLoader).
+// Memoising avoids re-walking the nav tree on every generateMetadata call —
+// a real cost for sites with many languages × many pages.
+const langPagePathsCache = new WeakMap<LanguageConfig, Set<string>>();
+function getLanguagePagePaths(langConfig: LanguageConfig): Set<string> {
+  let paths = langPagePathsCache.get(langConfig);
+  if (!paths) {
+    paths = new Set<string>();
+    collectPagePathsUnder(langConfig, paths);
+    langPagePathsCache.set(langConfig, paths);
+  }
+  return paths;
+}
 /**
  * Build hreflang alternate links for multi-language pages.
- * Generates links for each language version of the page, plus x-default.
+ *
+ * Only emits hreflang for languages whose navigation actually declares the
+ * current page — Ahrefs flagged 25+ pages where we advertised translations
+ * (`/docs/es/ai/overview`, `/docs/fr/ai/overview`) that returned 404 because
+ * partially-translated sections (e.g. AI section in jamdesk-docs is en-only)
+ * still got hreflang for every declared language.
  *
  * @param baseUrl - The base URL (e.g., "https://docs.example.com")
  * @param pagePath - The current page path (e.g., "es/getting-started")
@@ -124,22 +178,35 @@ function buildHreflangAlternates(
   // Detect current language from path
   const currentLang = extractLanguageFromPath(pagePath) || defaultLang;
-  // Build alternates for each language
-  const alternates: Record<string, string> = {};
+  // Keep only languages whose navigation declares this page — capturing the
+  // language-relative path so the build loop and x-default branch don't have
+  // to recompute it via transformLanguagePath.
+  const supported: Array<{ lang: LanguageCode; cleanPath: string }> = [];
   for (const langConfig of languages) {
-    const lang = langConfig.language;
-    // Transform current path to this language's version
-    // transformLanguagePath returns paths relative to app root (e.g., '/es/intro' or '/intro')
-    const langPath = transformLanguagePath(pagePath, currentLang, lang, defaultLang);
-    const cleanPath = langPath.replace(/^\//, ''); // Remove leading slash for URL building
+    const langPath = transformLanguagePath(pagePath, currentLang, langConfig.language, defaultLang);
+    const cleanPath = langPath.replace(/^\//, '');
+    if (getLanguagePagePaths(langConfig).has(cleanPath)) {
+      supported.push({ lang: langConfig.language, cleanPath });
+    }
+  }
+  // One or zero language versions → no useful hreflang. `<html lang>` and page
+  // content are sufficient signals.
+  if (supported.length <= 1) {
+    return undefined;
+  }
+  const alternates: Record<string, string> = {};
+  for (const { lang, cleanPath } of supported) {
     alternates[lang] = cleanPath ? `${baseUrl}/${cleanPath}` : baseUrl;
   }
-  // Add x-default pointing to the default language version
-  const defaultPath = transformLanguagePath(pagePath, currentLang, defaultLang, defaultLang);
-  const cleanDefaultPath = defaultPath.replace(/^\//, '');
-  alternates['x-default'] = cleanDefaultPath ? `${baseUrl}/${cleanDefaultPath}` : baseUrl;
+  // x-default points to the default language only when it has the page; absence
+  // is fine per Google, whereas pointing at a 404 is what Ahrefs flagged.
+  const defaultEntry = supported.find((s) => s.lang === defaultLang);
+  if (defaultEntry) {
+    alternates['x-default'] = defaultEntry.cleanPath ? `${baseUrl}/${defaultEntry.cleanPath}` : baseUrl;
+  }
   return alternates;
 }