jamdesk 1.1.35 → 1.1.38

package/vendored/lib/static-artifacts.ts

@@ -8,6 +8,11 @@
 import type { NavigationConfig } from './docs-types.js';
 import { RECURSE_KEYS } from './enhance-navigation.js';
 import { filterVisibility } from './visibility-filter.js';
+import {
+  buildLoweredLocaleSet,
+  resolveLocaleFromPath,
+  resolveLocaleWithLoweredSet,
+} from './language-utils.js';
 
 /**
  * Page metadata for artifact generation.
@@ -585,6 +590,8 @@ export interface SearchDocument {
   slug: string;
   section?: string;
   type: string;
+  /** Language of the document. Empty string for default-language pages. */
+  locale: string;
 }
 
 /**
@@ -602,6 +609,14 @@ export interface SearchPageInfo {
   };
 }
 
+/** Whitelist-gated alias of `resolveLocaleFromPath`, named for the search-index domain. */
+export function detectLocaleFromSlug(
+  slug: string,
+  projectLanguages: readonly string[],
+): string {
+  return resolveLocaleFromPath(slug, projectLanguages);
+}
+
 /**
  * Infer page type from slug path.
  */
@@ -668,15 +683,23 @@ export function extractSections(content: string): Array<{ heading: string; conte
  * Generate search data from page content.
  *
  * @param pages - Array of page info with content
+ * @param projectLanguages - Language codes declared in docs.json.navigation.languages.
+ *   Used as the locale whitelist; slugs whose prefix is not in this list are
+ *   tagged as default-language (locale='').
  * @returns JSON string of search documents
  */
-export function generateSearchData(pages: SearchPageInfo[]): string {
+export function generateSearchData(
+  pages: SearchPageInfo[],
+  projectLanguages: readonly string[],
+): string {
   const documents: SearchDocument[] = [];
+  const loweredLanguages = buildLoweredLocaleSet(projectLanguages);
 
   for (const page of pages) {
     const pathWithoutExt = page.path.replace(/\.mdx?$/, '');
     const slug = pathWithoutExt.replace(/\\/g, '/');
     const pageType = inferPageType(slug);
+    const locale = resolveLocaleWithLoweredSet(slug, loweredLanguages);
     // Filter for="agents" content out of the search index — the site
     // search is a human-facing surface, so agent-only content must not
     // leak into autocomplete.
@@ -694,6 +717,7 @@ export function generateSearchData(pages: SearchPageInfo[]): string {
           slug,
           section: section.heading || undefined,
           type: pageType,
+          locale,
         });
       }
     });

package/vendored/lib/vector-store.ts

@@ -11,6 +11,7 @@
  */
 import { Index, FusionAlgorithm, WeightingStrategy, QueryMode } from '@upstash/vector';
 import type { EmbeddingChunk } from './embedding-chunker.js';
+import { logger } from '../shared/logger';
 
 export interface ChunkMetadata {
   [key: string]: unknown;
@@ -18,6 +19,10 @@ export interface ChunkMetadata {
   sectionHeading: string;
   pageTitle: string;
   content: string;
+  /** Locale code (lowercased, e.g. "en", "es", "pt-br"). Absent for chunks
+   *  written by single-language projects (no `i18n.languages` config) — the
+   *  filter is gated per-project so unfiltered queries return all chunks. */
+  locale?: string;
 }
 
 /** Upstash limit per upsert call */
@@ -78,20 +83,24 @@ export async function upsertChunks(
   for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
     const batch = chunks.slice(i, i + BATCH_SIZE);
     await ns.upsert(
-      batch.map(c => ({
-        id: c.id,
-        // Prefix + body goes to Upstash for embedding/BM25; metadata.content
-        // stays prefix-free so consumers display clean body text.
-        data: c.prefix + c.content,
-        metadata: {
+      batch.map(c => {
+        const metadata: ChunkMetadata = {
           pageSlug: c.pageSlug,
           sectionHeading: c.sectionHeading,
           pageTitle: c.pageTitle,
           content: c.content.length > MAX_METADATA_CONTENT_CHARS
             ? c.content.slice(0, MAX_METADATA_CONTENT_CHARS) + '...'
             : c.content,
-        } satisfies ChunkMetadata,
-      })),
+        };
+        if (c.locale) metadata.locale = c.locale; // omit when null
+        return {
+          id: c.id,
+          // Prefix + body goes to Upstash for embedding/BM25; metadata.content
+          // stays prefix-free so consumers display clean body text.
+          data: c.prefix + c.content,
+          metadata,
+        };
+      }),
     );
   }
 }
@@ -130,13 +139,12 @@ export function extractTopicQuery(queryText: string): string | null {
 /** Query with hybrid mode, falling back to dense-only if hybrid is not supported */
 async function queryWithFallback(
   ns: ReturnType<typeof getNamespace>,
-  params: { data: string; topK: number; includeMetadata: true },
+  params: { data: string; topK: number; includeMetadata: true; filter?: string },
 ): Promise<Array<{ id: string | number; score: number; metadata?: ChunkMetadata }>> {
   try {
     return await ns.query<ChunkMetadata>({ ...params, ...HYBRID_QUERY_OPTS });
   } catch (err) {
-    // Hybrid not supported on this index — fall back to dense-only
-    console.warn('[vector-store] Hybrid query failed, falling back to dense-only:', String(err));
+    logger.warn('vector-store: hybrid query failed, falling back to dense-only', { error: String(err) });
     return await ns.query<ChunkMetadata>({ ...params, queryMode: QueryMode.DENSE });
   }
 }
@@ -184,6 +192,10 @@ function filterAndMerge(
  * request-pattern words (e.g. "give me a javascript example") from diluting
  * the topic signal in the embedding.
  *
+ * When `options.locale` is set, a strict Upstash filter expression is applied
+ * so only chunks for that locale are returned. No retry-without-filter on 0
+ * results — migration safety lives in the per-project gate (Task A5).
+ *
  * Returns up to `topK` results with their similarity scores,
  * filtering out any results with missing metadata.
  */
@@ -191,25 +203,66 @@ export async function querySimilarChunks(
   projectId: string,
   queryText: string,
   topK = 5,
+  options: { locale?: string } = {},
 ): Promise<Array<ChunkMetadata & { score: number }>> {
   const ns = getNamespace(projectId);
-  const queryParams = { topK, includeMetadata: true as const };
+  const locale = options.locale ? normalizeLocaleForFilter(options.locale) : undefined;
+  // Defense-in-depth: A5 rejects malformed locales at the API boundary. If a
+  // truthy locale here normalizes to empty, A5's guard was bypassed (test or
+  // internal caller) — surface it loudly rather than silently dropping the filter.
+  if (options.locale && !locale) {
+    logger.warn('vector-store: locale normalized to empty — filter skipped', { rawLocale: options.locale });
+  }
+  const filter = locale ? buildLocaleFilter(locale) : undefined;
+  // When filtering, raise effective topK by ~33% so we still get ~topK chunks
+  // back from a mixed-language namespace where filtering cuts the candidate set.
+  const effectiveTopK = filter ? Math.ceil(topK * 1.33) : topK;
+  const queryParams = { topK: effectiveTopK, includeMetadata: true as const, filter };
 
   const topicQuery = extractTopicQuery(queryText);
 
   // Dual-query: topic query is the PRIMARY source (better topical relevance);
   // the full query fills remaining slots with unique results only.
+  let merged: Array<ChunkMetadata & { score: number }>;
   if (topicQuery) {
     const [fullResults, topicResults] = await Promise.all([
       queryWithFallback(ns, { data: queryText, ...queryParams }),
       queryWithFallback(ns, { data: topicQuery, ...queryParams }),
     ]);
+    merged = filterAndMerge([topicResults, fullResults], topK);
+  } else {
+    const results = await queryWithFallback(ns, { data: queryText, ...queryParams });
+    merged = filterAndMerge([results], topK);
+  }
 
-    // Topic results first for best topical relevance
-    return filterAndMerge([topicResults, fullResults], topK);
+  // Telemetry: a filtered query that returns materially fewer chunks than
+  // requested signals the locale filter is hurting recall (project skewed away
+  // from the requested locale, or filter syntax matched a near-empty subset).
+  // Surface it so we can decide whether to widen the carve-out, increase the
+  // 1.33× boost, or rebuild the project's index.
+  if (filter && merged.length < Math.ceil(topK / 2)) {
+    logger.warn('vector-store: locale filter under-fills topK', {
+      projectId, locale, returned: merged.length, requested: topK,
+    });
   }
 
-  // Simple single-query path for short/simple queries
-  const results = await queryWithFallback(ns, { data: queryText, ...queryParams });
-  return filterAndMerge([results], topK);
+  return merged;
+}
+
+/**
+ * Validate + normalize a locale code for use inside an Upstash filter
+ * expression. We allow [a-z0-9_-] (covers `en`, `pt-br`, `zh-Hans` after
+ * lowercasing) and lowercase to match how chunks were stored. Any other
+ * character is dropped — defense against filter injection from a malformed
+ * client request. The route layer rejects bad locales at the API boundary
+ * (Task A5), so this strip is belt-and-suspenders.
+ */
+function normalizeLocaleForFilter(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+}
+
+/** Single source of truth for the Upstash filter expression. The smoke-test
+ *  script reuses this so production and verification stay in sync. */
+export function buildLocaleFilter(locale: string): string {
+  return `locale = "${locale}"`;
 }

package/vendored/scripts/build-search-index.cjs

@@ -25,6 +25,56 @@ const { create, insertMultiple } = require('@orama/orama');
 const { persist } = require('@orama/plugin-data-persistence');
 const { filterVisibility } = require('./visibility-filter.cjs');
 
+// Shared canonical list of language codes — keep in sync with
+// lib/language-utils.ts. The sync test in
+// __tests__/lib/language-codes-sync.test.ts catches drift.
+const LANGUAGE_CODES = require('../lib/language-codes.json');
+
+const LANGUAGE_CODE_BY_LOWER = (() => {
+  const m = new Map();
+  for (const k of LANGUAGE_CODES) {
+    const lower = k.toLowerCase();
+    if (!m.has(lower)) m.set(lower, k);
+  }
+  return m;
+})();
+
+/** Mirrors lib/language-utils.ts:extractLanguageFromPath. */
+function extractLanguageFromPath(pathname) {
+  if (!pathname) return undefined;
+  const parts = pathname.replace(/^\/docs\/?/, '').replace(/^\//, '').split('/').filter(Boolean);
+  if (parts.length === 0) return undefined;
+  return LANGUAGE_CODE_BY_LOWER.get(parts[0].toLowerCase());
+}
+
+/** Mirrors lib/language-utils.ts:resolveLocaleFromPath. */
+function resolveLocaleFromPath(pathname, projectLanguages) {
+  const candidate = extractLanguageFromPath(pathname);
+  if (!candidate) return '';
+  const lowered = new Set(projectLanguages.map((l) => l.toLowerCase()));
+  return lowered.has(candidate.toLowerCase()) ? candidate : '';
+}
+
+/**
+ * Read the project's declared languages from its docs.json. Returns [] when
+ * the file is missing or malformed — the script proceeds with no whitelist,
+ * which means every doc gets locale='' (matches single-language behavior).
+ */
+function readProjectLanguages(contentDir) {
+  try {
+    const docsJsonPath = path.join(contentDir, 'docs.json');
+    if (!fs.existsSync(docsJsonPath)) return [];
+    const config = JSON.parse(fs.readFileSync(docsJsonPath, 'utf-8'));
+    const langs = config?.navigation?.languages ?? [];
+    return langs
+      .map((l) => (l && typeof l.language === 'string' ? l.language : null))
+      .filter((c) => typeof c === 'string');
+  } catch (err) {
+    console.warn(`Could not read languages from ${contentDir}/docs.json: ${err.message}`);
+    return [];
+  }
+}
+
 // Concurrency control for parallel file processing
 const CONCURRENCY = parseInt(process.env.SEARCH_INDEX_CONCURRENCY || '') || os.cpus().length * 2;
 
@@ -214,6 +264,11 @@ async function buildSearchIndex() {
     process.exit(1);
   }
 
+  const projectLanguages = readProjectLanguages(contentDir);
+  if (projectLanguages.length > 0) {
+    console.log(`Project languages: ${projectLanguages.join(', ')}`);
+  }
+
   // First, collect all MDX file paths
   const mdxFiles = [];
 
@@ -264,6 +319,7 @@ async function buildSearchIndex() {
       const docs = [];
       const normalizedSlug = slug.replace(/\\/g, '/');
       const pageType = inferPageType(normalizedSlug);
+      const locale = resolveLocaleFromPath(normalizedSlug, projectLanguages);
       sections.forEach((section, idx) => {
         const cleanContent = stripMarkdown(section.content);
         if (cleanContent.trim()) {
@@ -275,6 +331,7 @@ async function buildSearchIndex() {
             slug: normalizedSlug,
             section: section.heading || undefined,
             type: pageType,
+            locale,
           });
         }
       });
@@ -318,6 +375,7 @@ async function buildOramaIndex(searchData, outputDir) {
       slug: 'string',
       section: 'string',
       type: 'string',
+      locale: 'enum',
     },
   });
 
@@ -330,6 +388,7 @@ async function buildOramaIndex(searchData, outputDir) {
     slug: item.slug,
     section: item.section || '',
     type: item.type || 'guide',
+    locale: item.locale || '',
   }));
 
   await insertMultiple(db, normalizedData);

package/vendored/scripts/validate-links.cjs

@@ -443,79 +443,34 @@ function getNavigationPages(contentDir) {
 
   const pages = new Set();
 
-  /**
-   * Extract page path from a navigation entry
-   */
-  function getPagePath(entry) {
-    if (typeof entry === 'string') return entry;
-    if (entry && typeof entry === 'object' && entry.page) return entry.page;
-    return null;
+  function addPage(value) {
+    if (typeof value === 'string') pages.add(value);
   }
 
-  /**
-   * Recursively collect all pages from a navigation structure
-   */
-  function collectPages(pagesArray) {
-    if (!Array.isArray(pagesArray)) return;
-
-    for (const entry of pagesArray) {
-      const pagePath = getPagePath(entry);
-
-      if (pagePath) {
-        pages.add(pagePath);
-      } else if (entry && typeof entry === 'object') {
-        // It's a group or nested structure - recurse into it
-        if (entry.pages) collectPages(entry.pages);
-        if (entry.groups) {
-          for (const group of entry.groups) {
-            if (group.pages) collectPages(group.pages);
-          }
-        }
-      }
-    }
-  }
-
-  /**
-   * Collect pages from tabs
-   */
-  function collectFromTabs(tabs) {
-    if (!Array.isArray(tabs)) return;
-
-    for (const tab of tabs) {
-      if (tab.pages) collectPages(tab.pages);
-      if (tab.groups) {
-        for (const group of tab.groups) {
-          if (group.pages) collectPages(group.pages);
-        }
-      }
-    }
+  // Mutual recursion: walkContainer dispatches on the known container fields,
+  // walkItems handles arrays of strings (page ids) or nested containers.
+  // Covers pages/groups/tabs/anchors/dropdowns/languages/global at any depth.
+  function walkContainer(c) {
+    if (!c || typeof c !== 'object') return;
+    if ('page' in c) addPage(c.page);
+    walkItems(c.pages);
+    walkItems(c.groups);
+    walkItems(c.tabs);
+    walkItems(c.anchors);
+    walkItems(c.dropdowns);
+    walkItems(c.languages);
+    if (c.global) walkContainer(c.global);
   }
 
-  // Collect from root-level pages
-  if (navigation.pages) collectPages(navigation.pages);
-
-  // Collect from groups
-  if (navigation.groups) {
-    for (const group of navigation.groups) {
-      if (group.pages) collectPages(group.pages);
-    }
-  }
-
-  // Collect from tabs
-  if (navigation.tabs) collectFromTabs(navigation.tabs);
-
-  // Collect from anchors
-  if (navigation.anchors) {
-    for (const anchor of navigation.anchors) {
-      if (anchor.pages) collectPages(anchor.pages);
-      if (anchor.groups) {
-        for (const group of anchor.groups) {
-          if (group.pages) collectPages(group.pages);
-        }
-      }
+  function walkItems(items) {
+    if (!Array.isArray(items)) return;
+    for (const item of items) {
+      if (typeof item === 'string') addPage(item);
+      else if (item && typeof item === 'object') walkContainer(item);
     }
   }
 
+  walkContainer(navigation);
   return pages;
 }
 

package/vendored/themes/base.css

@@ -378,6 +378,11 @@
   text-decoration: none;
 }
 
+/* Restore spacing between stacked .not-prose blocks — prose sibling rules skip them. */
+.prose > .not-prose + .not-prose {
+  margin-top: 1.5rem;
+}
+
 html {
   /* Prevent horizontal overflow on mobile */
   overflow-x: hidden;

package/vendored/workspace-package-lock.json

@@ -294,14 +294,14 @@
       "license": "MIT"
     },
     "node_modules/@iconify/utils": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/@iconify/utils/-/utils-3.1.0.tgz",
-      "integrity": "sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw==",
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/@iconify/utils/-/utils-3.1.1.tgz",
+      "integrity": "sha512-MwzoDtw9rO1x+qfgLTV/IVXsHDBqeYZoMIQC8SfxfYSlaSUG+oWiAcoiB1yajAda6mqblm4/1/w2E8tRu7a7Tw==",
       "license": "MIT",
       "dependencies": {
         "@antfu/install-pkg": "^1.1.0",
         "@iconify/types": "^2.0.0",
-        "mlly": "^1.8.0"
+        "mlly": "^1.8.2"
       }
     },
     "node_modules/@img/colour": {
@@ -2025,9 +2025,9 @@
       }
     },
     "node_modules/ajv": {
-      "version": "8.18.0",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
-      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
       "license": "MIT",
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
@@ -2152,9 +2152,9 @@
       }
     },
     "node_modules/baseline-browser-mapping": {
-      "version": "2.10.21",
-      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.21.tgz",
-      "integrity": "sha512-Q+rUQ7Uz8AHM7DEaNdwvfFCTq7a43lNTzuS94eiWqwyxfV/wJv+oUivef51T91mmRY4d4A1u9rcSvkeufCVXlA==",
+      "version": "2.10.23",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.23.tgz",
+      "integrity": "sha512-xwVXGqevyKPsiuQdLj+dZMVjidjJV508TBqexND5HrF89cGdCYCJFB3qhcxRHSeMctdCfbR1jrxBajhDy7o29g==",
       "license": "Apache-2.0",
       "bin": {
         "baseline-browser-mapping": "dist/cli.cjs"
@@ -2215,9 +2215,9 @@
       "license": "MIT"
     },
     "node_modules/caniuse-lite": {
-      "version": "1.0.30001790",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001790.tgz",
-      "integrity": "sha512-bOoxfJPyYo+ds6W0YfptaCWbFnJYjh2Y1Eow5lRv+vI2u8ganPZqNm1JwNh0t2ELQCqIWg4B3dWEusgAmsoyOw==",
+      "version": "1.0.30001791",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001791.tgz",
+      "integrity": "sha512-yk0l/YSrOnFZk3UROpDLQD9+kC1l4meK/wed583AXrzoarMGJcbRi2Q4RaUYbKxYAsZ8sWmaSa/DsLmdBeI1vQ==",
       "funding": [
         {
           "type": "opencollective",
@@ -5586,9 +5586,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.10",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
-      "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
+      "version": "8.5.12",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.12.tgz",
+      "integrity": "sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA==",
       "funding": [
         {
           "type": "opencollective",