jamdesk 1.1.89 → 1.1.91

package/vendored/lib/seo.ts

@@ -8,9 +8,14 @@
  */
 
 import type { Metadata } from 'next';
-import type { DocsConfig, Logo, LogoConfig, Favicon, FaviconConfig, LanguageConfig, LanguageCode } from './docs-types';
+import type { DocsConfig, Logo, LogoConfig, Favicon, LanguageConfig, LanguageCode } from './docs-types';
 import { transformConfigImagePath } from './docs-types';
-import { transformLanguagePath, extractLanguageFromPath, isValidLanguageCode } from './language-utils';
+import { findHreflangAliasCollisions, transformLanguagePath, toHreflang } from './language-utils';
+import { logger } from '../shared/logger';
+
+// Dedupe per-process: same docs.json shape produces the same collision
+// signature on every page render, so we'd otherwise spam logs.
+const warnedCollisionSignatures = new Set<string>();
 
 const HAS_DOCS_SUFFIX = /\b(?:Documentation|Docs)\s*$/i;
 
@@ -197,14 +202,12 @@ function buildHreflangAlternates(
   const defaultLang = languages.find((l) => l.default)?.language || languages[0]?.language || 'en';
 
   // Detect current language from path
-  const currentLang = extractLanguageFromPath(pagePath) || defaultLang;
-
   // 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 langPath = transformLanguagePath(pagePath, currentLang, langConfig.language, defaultLang);
+    const langPath = transformLanguagePath(pagePath, langConfig.language, defaultLang);
     const cleanPath = langPath.replace(/^\//, '');
     if (getLanguagePagePaths(langConfig).has(cleanPath)) {
       supported.push({ lang: langConfig.language, cleanPath });
@@ -217,9 +220,21 @@ function buildHreflangAlternates(
     return undefined;
   }
 
+  const collisions = findHreflangAliasCollisions(supported.map((s) => s.lang));
+  for (const { tag, codes } of collisions) {
+    const signature = `${tag}:${codes.join(',')}`;
+    if (warnedCollisionSignatures.has(signature)) continue;
+    warnedCollisionSignatures.add(signature);
+    logger.warn('hreflang alias collision — last entry wins, earlier translations dropped', {
+      bcp47Tag: tag,
+      internalCodes: codes,
+      remedy: 'Remove one of the duplicate entries from navigation.languages in docs.json',
+    });
+  }
+
   const alternates: Record<string, string> = {};
   for (const { lang, cleanPath } of supported) {
-    alternates[lang] = cleanPath ? `${baseUrl}/${cleanPath}` : baseUrl;
+    alternates[toHreflang(lang)] = cleanPath ? `${baseUrl}/${cleanPath}` : baseUrl;
   }
 
   // x-default points to the default language only when it has the page; absence

package/vendored/lib/shiki-highlighter.ts

@@ -8,7 +8,7 @@ import { PRELOADED_LANGUAGES, SUPPORTED_THEMES, type SupportedTheme } from './sh
 
 // Extend globalThis type for highlighter caching
 declare global {
-  // eslint-disable-next-line no-var
+
   var __shikiHighlighterPromise: Promise<Highlighter> | undefined;
 }
 

package/vendored/lib/snippet-loader-isr.ts

@@ -322,7 +322,7 @@ async function compileSnippet(
     try {
       // Create function that returns the component
       // NOTE: new Function() is intentionally used here to compile user-provided snippets
-      // eslint-disable-next-line @typescript-eslint/no-implied-eval
+
       const createComponent = new Function(
         'React',
         '_jsx',

package/vendored/lib/validate-config.ts

@@ -12,6 +12,7 @@
 import AjvModule, { ErrorObject } from 'ajv';
 import addFormatsModule from 'ajv-formats';
 // ESM compatibility - ajv-formats exports differently under NodeNext resolution
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- ajv-formats ESM/CJS interop default-export shape varies by bundler
 const addFormats = (addFormatsModule as any).default || addFormatsModule;
 // ESM compatibility - Ajv exports differently in Node.js ESM
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -60,6 +61,10 @@ export interface ValidationResult {
   error?: string;
   errorType?: 'config_error';
   errorSuggestion?: string;
+  /** Populated only on missing-file failures when `repoRoot` was supplied. */
+  discovery?: DocsJsonDiscovery;
+  /** Prose remediation derived from discovery (e.g., "Did you mean docsPath=apps/docs?"). */
+  discoveryHint?: string;
 }
 
 type Schema = Record<string, unknown>;
@@ -297,12 +302,121 @@ export function formatValidationErrors(errors: ErrorObject[] | null | undefined)
   return messages.join('. ');
 }
 
+/** Limits keep worst-case repos (huge monorepos, generated dirs) cheap on failure. */
+const DISCOVER_MAX_DEPTH = 3;
+const DISCOVER_MAX_ENTRIES = 500;
+const DISCOVER_SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', '.turbo', '.cache',
+  'dist', 'build', 'out', '.vercel', 'coverage',
+]);
+
+export interface DocsJsonDiscovery {
+  /** Repo-relative paths (POSIX separators), sorted, to docs.json files. */
+  foundAt: string[];
+  /** First-level entries at the repo root, sorted. */
+  rootEntries: string[];
+  /** True if the walk hit DISCOVER_MAX_ENTRIES before finishing. */
+  truncated: boolean;
+}
+
+/**
+ * Walk `repoRoot` looking for any `docs.json`. Used only on the failure path —
+ * gives ops a snapshot of what was cloned and lets us suggest the right docsPath.
+ *
+ * Documented behavior (covered by tests):
+ * - Case-sensitive filename match (`docs.json` only, not `Docs.json`). Matches Linux
+ *   prod semantics — macOS dev might see different fs.existsSync behavior but discovery
+ *   is consistent across platforms.
+ * - Skips directories whose name starts with `.` (so `.config/docs.json` is invisible).
+ * - Skips symlinks unconditionally (cycle defense; Windows junctions covered by the
+ *   entry+depth caps as a backstop).
+ * - Output paths use POSIX separators on all platforms.
+ * - `rootEntries` is the raw, sorted listing of the repo's top-level entries — it is
+ *   captured once at depth 0 and is NOT bounded by DISCOVER_MAX_ENTRIES. Persistence
+ *   layers (Firestore writes, structured logs) slice it to a fixed cap on their side.
+ *
+ * Limits: DISCOVER_MAX_DEPTH=3, DISCOVER_MAX_ENTRIES=500.
+ */
+export async function discoverDocsJson(repoRoot: string): Promise<DocsJsonDiscovery> {
+  const foundAt: string[] = [];
+  let rootEntries: string[] = [];
+  let seen = 0;
+  let truncated = false;
+
+  async function walk(absDir: string, relDir: string, depth: number): Promise<void> {
+    if (truncated || depth > DISCOVER_MAX_DEPTH) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    if (depth === 0) {
+      rootEntries = entries.map(e => e.name).sort();
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory() && (DISCOVER_SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))) continue;
+      if (++seen > DISCOVER_MAX_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(path.join(absDir, entry.name), rel, depth + 1);
+      } else if (entry.isFile() && entry.name === 'docs.json') {
+        foundAt.push(rel);
+      }
+    }
+  }
+
+  await walk(repoRoot, '', 0);
+  foundAt.sort();
+  return { foundAt, rootEntries, truncated };
+}
+
+/**
+ * Build the prose remediation hint from a discovery snapshot. Pure function —
+ * separated from validateConfig so it can be unit-tested directly and so the
+ * hint phrasings live in one named place.
+ */
+export function synthesizeDiscoveryHint(
+  foundAt: string[],
+  expectedRel: string,
+  docsPath?: string,
+): string {
+  const elsewhere = foundAt.filter(p => p !== expectedRel);
+  if (elsewhere.length === 1) {
+    // path.posix.dirname returns '.' for files at the root (e.g. 'docs.json' → '.').
+    const dir = path.posix.dirname(elsewhere[0]);
+    if (dir === '.') {
+      return docsPath
+        ? 'We found docs.json at the repository root. You can clear the docs path setting to use it.'
+        : 'We found docs.json at the repository root.';
+    }
+    return `We found docs.json at '${elsewhere[0]}'. Did you mean to set the docs path to '${dir}'?`;
+  }
+  if (elsewhere.length > 1) {
+    const list = elsewhere.slice(0, 3).map(p => `'${p}'`).join(', ');
+    const more = elsewhere.length > 3 ? ` and ${elsewhere.length - 3} more` : '';
+    return `We found docs.json at: ${list}${more}. Update the docs path setting to point at one of these.`;
+  }
+  return 'We could not find a docs.json file anywhere in this commit. '
+    + 'Check that you pushed the right branch and that docs.json is committed.';
+}
+
 /**
- * Validate docs.json configuration
+ * Validate docs.json configuration.
  * @param configPath - Full path to docs.json
- * @param docsPath - Optional monorepo path for better error messages (e.g., "jamdesk")
+ * @param docsPath   - Optional monorepo path for better error messages (e.g., "jamdesk")
+ * @param repoRoot   - Optional repo root; when supplied, missing-file errors include
+ *                    a discovery snapshot and a remediation hint.
  */
-export async function validateConfig(configPath: string, docsPath?: string): Promise<ValidationResult> {
+export async function validateConfig(
+  configPath: string,
+  docsPath?: string,
+  repoRoot?: string,
+): Promise<ValidationResult> {
   // Check file exists
   if (!fs.existsSync(configPath)) {
     // If `mint.json` sits where docs.json should be, the project is mid-migration
@@ -311,13 +425,27 @@ export async function validateConfig(configPath: string, docsPath?: string): Pro
     if (fs.existsSync(mintPath)) {
       return mintlifyMigrationError('Found `mint.json` but no `docs.json`.');
     }
-    const pathHint = docsPath
+
+    const baseError = docsPath
       ? `Missing docs.json at '${docsPath}/docs.json'. Check that your monorepo path is correct.`
       : 'Missing docs.json configuration file. Your repository must have a docs.json file in the root directory.';
-    return {
-      valid: false,
-      error: pathHint,
-    };
+
+    if (!repoRoot) {
+      return { valid: false, error: baseError };
+    }
+
+    const discovery = await discoverDocsJson(repoRoot);
+
+    const normalizedDocsPath = docsPath
+      ? path.posix.normalize(docsPath.replace(/\\/g, '/').replace(/^\.\//, '')).replace(/\/$/, '')
+      : '';
+    const expectedRel = normalizedDocsPath
+      ? path.posix.join(normalizedDocsPath, 'docs.json')
+      : 'docs.json';
+
+    const discoveryHint = synthesizeDiscoveryHint(discovery.foundAt, expectedRel, docsPath);
+
+    return { valid: false, error: baseError, discovery, discoveryHint };
   }
   
   // Read and parse file

package/vendored/shared/status-reporter.ts

@@ -66,8 +66,20 @@ export interface FailureUpdate {
   failedPhase: string;
   timing: TimingSummary | null;
   memory?: MemoryStats;
+  /** docs.json discovery snapshot — populated only on missing-file validate failures. */
+  discovery?: {
+    foundAt: string[];
+    rootEntries: string[];
+    truncated: boolean;
+  };
 }
 
+/**
+ * Cap applied when persisting `FailureUpdate.discovery.rootEntries` to keep
+ * Firestore docs and Cloud Run log payloads bounded on wide repos.
+ */
+export const DISCOVERY_ROOT_ENTRIES_PERSIST_CAP = 30;
+
 export interface ErrorLogData {
   rawOutput: string;
   stderr: string;

package/vendored/workspace-package-lock.json

@@ -1921,12 +1921,12 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "25.7.0",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.7.0.tgz",
-      "integrity": "sha512-z+pdZyxE+RTQE9AcboAZCb4otwcrvgHD+GlBpPgn0emDVt0ohrTMhAwlr2Wd9nZ+nihhYFxO2pThz3C5qSu2Eg==",
+      "version": "25.8.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.8.0.tgz",
+      "integrity": "sha512-TCFSk8IZh+iLX1xtksoBVtdmgL+1IX0fC9BeU4QqFSuNdN/K+HUlhqOzEmSYYpZUVsLYcPqc9KX+60iDuninSQ==",
       "license": "MIT",
       "dependencies": {
-        "undici-types": "~7.21.0"
+        "undici-types": ">=7.24.0 <7.24.7"
       }
     },
     "node_modules/@types/react": {
@@ -2913,9 +2913,9 @@
       }
     },
     "node_modules/dompurify": {
-      "version": "3.4.2",
-      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.2.tgz",
-      "integrity": "sha512-lHeS9SA/IKeIFFyYciHBr2n0v1VMPlSj843HdLOwjb2OxNwdq9Xykxqhk+FE42MzAdHvInbAolSE4mhahPpjXA==",
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.3.tgz",
+      "integrity": "sha512-VVwJidIJcp1hpg2OMXML3ZVRPYSZiq4aX7qBh83BSIpOaRDqI+qxhXjjIWnpzkOXhmp0L81lnoME1mnCc9H48A==",
       "license": "(MPL-2.0 OR Apache-2.0)",
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
@@ -2928,9 +2928,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.353",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.353.tgz",
-      "integrity": "sha512-kOrWphBi8TOZyiJZqsgqIle0lw+tzmnQK83pV9dZUd01Nm2POECSyFQMAuarzZdYqQW7FH9RaYOuaRo3h+bQ3w==",
+      "version": "1.5.355",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.355.tgz",
+      "integrity": "sha512-LUPZhKzZPYSPme1jEYohpkA+ybYCJztr1quAdBd7E7h3+VOBVcKkwwtBJu41nrjawrRzfb8mtMfzWozoaK0ZIQ==",
       "license": "ISC"
     },
     "node_modules/enhanced-resolve": {
@@ -3739,9 +3739,9 @@
       }
     },
     "node_modules/katex": {
-      "version": "0.16.45",
-      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.45.tgz",
-      "integrity": "sha512-pQpZbdBu7wCTmQUh7ufPmLr0pFoObnGUoL/yhtwJDgmmQpbkg/0HSVti25Fu4rmd1oCR6NGWe9vqTWuWv3GcNA==",
+      "version": "0.16.46",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.46.tgz",
+      "integrity": "sha512-WHy4Coo+bGZyH7NwJKHkS04YFsFcarWbAEOAC3EMndzdN6VSZqklLLIgfxzyaW9jDoeGYJX9SWbJPKpecox0Uw==",
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"
@@ -6279,9 +6279,9 @@
       "license": "MIT"
     },
     "node_modules/undici-types": {
-      "version": "7.21.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.21.0.tgz",
-      "integrity": "sha512-w9IMgQrz4O0YN1LtB7K5P63vhlIOvC7opSmouCJ+ZywlPAlO9gIkJ+otk6LvGpAs2wg4econaCz3TvQ9xPoyuQ==",
+      "version": "7.24.6",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+      "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
       "license": "MIT"
     },
     "node_modules/unified": {