jamdesk 1.1.205 → 1.1.207

package/vendored/lib/language-cookie.ts

@@ -0,0 +1,20 @@
+/**
+ * The language-preference cookie, in a module with NO imports.
+ *
+ * It lives alone because both sides need it and neither may reach the other:
+ * `middleware-helpers.ts` pulls in `next/server`, `@upstash/redis` (via
+ * ./redis and ./cached-redis) and the project resolver, while
+ * `language-utils.ts` is client code — the `'use client'` LanguageSelector
+ * imports it. Having language-utils import the constant from
+ * middleware-helpers would both close an import cycle (middleware-helpers
+ * already imports extractLanguageFromPath from language-utils, line 22) and
+ * drag the edge/Redis modules into the browser bundle. Neither `tsc --noEmit`
+ * nor vitest would catch that — only `next build` would, and this repo has
+ * already taken a production outage from exactly that class of bug.
+ */
+
+/** Cookie carrying the visitor's chosen documentation language. */
+export const LANGUAGE_COOKIE = 'jd-lang';
+
+/** One year — this is a stated preference, not a session detail. */
+export const LANGUAGE_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;

package/vendored/lib/language-matcher.ts

@@ -0,0 +1,124 @@
+/**
+ * Language routing module.
+ *
+ * Fetches a project's language-routing descriptor from `_languages.json` in R2,
+ * cached in Upstash Redis with a 5-minute TTL. Mirrors redirect-matcher.ts —
+ * same cache shape, same negative caching, same fail-open contract.
+ *
+ * Fail-open is not optional here: this runs inside proxy.ts, which has no error
+ * boundary. Any throw becomes a 500 on a page that would otherwise have served
+ * fine, so every path in this file returns null instead of raising.
+ */
+
+import { redis } from './redis';
+import type { LanguagesFile } from './languages-artifact';
+import { getFileBufferFromR2 } from './r2';
+
+// Cache TTL in seconds (5 minutes) — same as redirects.
+const CACHE_TTL = 300;
+
+// Redis cache key prefix.
+const CACHE_PREFIX = 'languages:';
+
+/** Sentinel written on a miss so a project without the file stops hitting R2. */
+const EMPTY: LanguagesFile = {
+  version: 1,
+  autoRedirect: false,
+  defaultLanguage: '',
+  languages: [],
+};
+
+/** Structural gate — a half-written or hand-edited file must not reach callers. */
+function isValid(value: unknown): value is LanguagesFile {
+  if (!value || typeof value !== 'object') return false;
+  const file = value as Partial<LanguagesFile>;
+  return (
+    typeof file.autoRedirect === 'boolean' &&
+    typeof file.defaultLanguage === 'string' &&
+    Array.isArray(file.languages) &&
+    file.languages.every((code) => typeof code === 'string')
+  );
+}
+
+/**
+ * Clear cached language routing for a project (or all projects).
+ * Called during revalidation to pick up an updated `_languages.json` from R2.
+ */
+export async function clearLanguageCache(projectName?: string): Promise<void> {
+  if (!redis) return;
+  try {
+    if (projectName) {
+      await redis.del(`${CACHE_PREFIX}${projectName}`);
+      return;
+    }
+    const keys: string[] = [];
+    let cursor = '0';
+    do {
+      const result: [string, string[]] = await redis.scan(cursor, {
+        match: `${CACHE_PREFIX}*`,
+        count: 100,
+      });
+      cursor = result[0];
+      keys.push(...result[1]);
+    } while (cursor !== '0');
+    if (keys.length > 0) {
+      const pipeline = redis.pipeline();
+      for (const key of keys) pipeline.del(key);
+      await pipeline.exec();
+    }
+  } catch {
+    // Ignore cache clear errors — a stale entry expires in CACHE_TTL anyway.
+  }
+}
+
+/**
+ * Fetch language routing for a project from R2 with Redis caching.
+ * Returns null when the project has no descriptor, or on any failure.
+ */
+export async function getLanguageRouting(projectName: string): Promise<LanguagesFile | null> {
+  const cacheKey = `${CACHE_PREFIX}${projectName}`;
+
+  if (redis) {
+    try {
+      const cached = await redis.get<LanguagesFile>(cacheKey);
+      if (isValid(cached)) {
+        return cached.languages.length > 0 ? cached : null;
+      }
+    } catch (error) {
+      console.error('[Languages] Redis cache read failed:', error);
+      // Continue to R2.
+    }
+  }
+
+  try {
+    const buffer = await getFileBufferFromR2(projectName, '_languages.json');
+    if (!buffer) {
+      // Negative-cache the miss so a single-language project does not pay an R2
+      // round trip on every request for the next five minutes.
+      if (redis) {
+        try {
+          await redis.set(cacheKey, EMPTY, { ex: CACHE_TTL });
+        } catch {
+          // Ignore cache write errors.
+        }
+      }
+      return null;
+    }
+
+    const parsed: unknown = JSON.parse(buffer.toString('utf-8'));
+    if (!isValid(parsed)) return null;
+
+    if (redis) {
+      try {
+        await redis.set(cacheKey, parsed, { ex: CACHE_TTL });
+      } catch {
+        // Ignore cache write errors.
+      }
+    }
+
+    return parsed.languages.length > 0 ? parsed : null;
+  } catch (error) {
+    console.error('[Languages] Failed to load _languages.json:', error);
+    return null;
+  }
+}

package/vendored/lib/language-utils.ts

@@ -6,6 +6,7 @@
 
 import type { LanguageCode, LanguageConfig } from './docs-types';
 import LANGUAGE_CODES_JSON from './language-codes.json';
+import { LANGUAGE_COOKIE, LANGUAGE_COOKIE_MAX_AGE } from './language-cookie';
 
 /**
  * Canonical language code list, shared with the CJS build script via
@@ -472,6 +473,13 @@ function storageKey(projectSlug: string): string {
   return `${LANGUAGE_STORAGE_KEY_PREFIX}${projectSlug}`;
 }
 
+// Mirrors proxy.ts's `secure: process.env.NODE_ENV === 'production'` exactly
+// — gated rather than hardcoded so a write from this client code doesn't
+// silently downgrade the attribute the server's redirect already set.
+// `NODE_ENV` is inlined at build time by Next.js, so this is a build-time
+// constant even though it reads like a runtime check.
+const COOKIE_SECURE_ATTR = process.env.NODE_ENV === 'production' ? '; secure' : '';
+
 /**
  * Save language preference to localStorage, scoped to project slug.
  * Handles private browsing mode gracefully.
@@ -484,6 +492,16 @@ export function saveLanguagePreference(code: LanguageCode, projectSlug: string):
     // localStorage not available (private browsing, etc.)
     // Fail silently
   }
+  // Mirror the choice into the cookie the edge reads. Without this, a visitor
+  // who overrides the server's Accept-Language guess is redirected back to the
+  // language they just rejected on their next visit to a locale root.
+  try {
+    document.cookie =
+      `${LANGUAGE_COOKIE}=${encodeURIComponent(code)}; path=/; max-age=${LANGUAGE_COOKIE_MAX_AGE}; samesite=lax${COOKIE_SECURE_ATTR}`;
+  } catch {
+    // Cookies blocked (private mode, strict settings) — localStorage still
+    // carries the preference for this browser, so degrade quietly.
+  }
 }
 
 /**
@@ -521,6 +539,11 @@ export function clearLanguagePreference(projectSlug: string): void {
   } catch {
     // localStorage not available
   }
+  try {
+    document.cookie = `${LANGUAGE_COOKIE}=; path=/; max-age=0; samesite=lax${COOKIE_SECURE_ATTR}`;
+  } catch {
+    // Ignore — see saveLanguagePreference.
+  }
 }
 
 /**
@@ -545,3 +568,83 @@ export function resolveLanguageWithFallback(
   }
   return 'en';
 }
+
+/**
+ * Cap on Accept-Language segments we will parse. A header is attacker-
+ * controlled; parsing is O(segments x available) and middleware runs on every
+ * request, so we stop reading after a sane number of entries rather than let a
+ * crafted header burn edge CPU. Real browsers send fewer than 10.
+ */
+const MAX_ACCEPT_LANGUAGE_SEGMENTS = 20;
+
+/**
+ * Pick the best available language for an Accept-Language header.
+ *
+ * Returns `null` — meaning "do nothing" — when the header is absent, unusable,
+ * matches nothing available, or resolves to the site's default language. A null
+ * return is always safe: the caller simply serves the page it was going to
+ * serve. This function never throws; middleware has no error boundary, so a
+ * throw here would 500 the page.
+ *
+ * Matching is case-insensitive and two-pass: an exact tag match (`zh-Hans`)
+ * beats a base-language match (`zh`), so a site offering both gets the precise
+ * one.
+ */
+export function negotiateLanguage(
+  header: string | null,
+  available: string[],
+  defaultLang: string,
+): string | null {
+  if (!header || available.length === 0) return null;
+
+  // Map lowercased code -> original casing, so we return the code exactly as
+  // the tenant configured it (callers build URLs from this).
+  const availableByLower = new Map<string, string>();
+  for (const code of available) {
+    availableByLower.set(code.toLowerCase(), code);
+  }
+
+  const parsed: Array<{ tag: string; q: number }> = [];
+  const segments = header.split(',', MAX_ACCEPT_LANGUAGE_SEGMENTS);
+
+  for (const segment of segments) {
+    const [rawTag, ...params] = segment.trim().split(';');
+    const tag = rawTag.trim().toLowerCase();
+    // '*' means "anything" — it expresses no preference, so we decline to guess.
+    if (!tag || tag === '*') continue;
+    if (!BCP47_LANGUAGE_RE.test(tag)) continue;
+
+    let q = 1;
+    for (const param of params) {
+      const match = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(param);
+      if (!match) continue;
+      const value = Number.parseFloat(match[1]);
+      // A malformed q (NaN) is ignored, leaving the default q=1 — RFC 9110
+      // treats an unparseable parameter as absent rather than fatal.
+      if (Number.isFinite(value)) q = value;
+    }
+    if (q <= 0) continue;
+    parsed.push({ tag, q });
+  }
+
+  if (parsed.length === 0) return null;
+
+  // Stable sort by descending q: equal-q tags keep header order, which is the
+  // client's own stated preference order.
+  parsed.sort((a, b) => b.q - a.q);
+
+  const defaultLower = defaultLang.toLowerCase();
+
+  for (const { tag } of parsed) {
+    // Pass 1: exact tag ('zh-hans' -> 'zh-Hans').
+    const exact = availableByLower.get(tag);
+    if (exact) return exact.toLowerCase() === defaultLower ? null : exact;
+
+    // Pass 2: base language ('fr-ca' -> 'fr').
+    const base = tag.split('-')[0];
+    const baseMatch = availableByLower.get(base);
+    if (baseMatch) return baseMatch.toLowerCase() === defaultLower ? null : baseMatch;
+  }
+
+  return null;
+}

package/vendored/lib/languages-artifact.ts

@@ -0,0 +1,160 @@
+/**
+ * The `_languages.json` descriptor shape, plus the pure builder for it — kept
+ * free of `./redis` and `./r2`.
+ *
+ * Two very different callers need it. `lib/language-matcher.ts` reads the file
+ * at the edge and therefore imports `./redis` (Upstash) and `./r2`. `build.ts`
+ * runs on Cloud Run and only ever *builds* the descriptor — a pure transform
+ * that must not pull an edge Redis client into the build image. Keeping the
+ * type and the builder here is what keeps those two apart: this module imports
+ * the `DocsConfig` type (erased at compile time) plus two import-light pure
+ * helpers — `./locale-helpers` and `./root-page-slug`, whose own chain
+ * (find-first-nav-page, language-utils, page-isr-helpers, shared/docs-subpath)
+ * is plain data and string work with no React, Next or network in it. The edge
+ * side imports THIS module `import type`-only, so none of that reaches the
+ * middleware bundle.
+ *
+ * `languages` and `defaultLanguage` are lowercased at build time by
+ * normalizeLanguageList(), so comparisons at the edge need no normalization.
+ */
+import { normalizeLanguageList } from './locale-helpers';
+import { findFirstPage } from './root-page-slug';
+import type { DocsConfig } from './docs-types';
+
+export interface LanguagesFile {
+  version: number;
+  generatedAt?: string;
+  /** Mirrors docs.json `localization.autoRedirect`. */
+  autoRedirect: boolean;
+  defaultLanguage: string;
+  languages: string[];
+}
+
+/**
+ * The descriptor that means "this project does not language-route", written
+ * whenever fewer than two languages are routable.
+ *
+ * Byte-identical in shape to language-matcher's EMPTY sentinel, deliberately:
+ * both `getLanguageRouting` return sites gate on `languages.length > 0` and
+ * hand the caller `null`, so this file reads at the edge exactly like no file
+ * at all.
+ *
+ * `autoRedirect` is hardcoded false rather than mirrored from docs.json. It is
+ * not a report of the tenant's setting here — it is this descriptor's own
+ * meaning, and `{autoRedirect: true, languages: []}` would be a file that
+ * contradicts itself for anyone reading it out of R2 during an incident.
+ */
+function noRoutingDescriptor(): LanguagesFile {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    autoRedirect: false,
+    defaultLanguage: '',
+    languages: [],
+  };
+}
+
+/** docs.json nav paths and on-disk page paths, reduced to one comparable form. */
+function normalizePagePath(value: string): string {
+  return value
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .replace(/\.mdx?$/i, '')
+    .toLowerCase();
+}
+
+/**
+ * Build the `_languages.json` descriptor for a project. ALWAYS returns one.
+ *
+ * Never null, and that is the whole contract. R2ContentUploader exposes no
+ * delete (lib/r2.ts:279-294), so "the file is absent" is not a state a build
+ * can reach for a project that has ever written one — every state has to be
+ * expressed by WRITING the truth over the top. An earlier version returned
+ * null both for the opted-out switch (correctly reasoned about in a comment)
+ * and for "fewer than two languages" (not), which meant a tenant who pulled a
+ * bad translation the documented way — `hidden: true` on the second language —
+ * skipped the write entirely and left `{autoRedirect: true, languages:
+ * ['en','fr']}` in R2 forever, 307-ing French visitors into the language just
+ * hidden, or into an `/fr` the build no longer produces. Silently: the success
+ * log sat inside the same `if`, so a skipped write looked exactly like a
+ * project that never had the feature. Single-language projects now write a
+ * no-routing descriptor too — ~93 small objects, one per build, which is the
+ * price of the absent state not existing.
+ *
+ * Two filters decide what may be a redirect DESTINATION:
+ *
+ * 1. Eligibility, from docs.json. `hidden: true` is the documented way to
+ *    stage a translation that is not ready, and auto-redirecting a first-time
+ *    visitor into it is the maximum possible surfacing of a language its
+ *    author deliberately hid. `href` points at an external site with no local
+ *    `/<code>` tree here, so redirecting there is a 307 into a 404.
+ *
+ * 2. Routability, from what this build actually PRODUCED. Config alone never
+ *    proves a destination exists: `{"language": "de"}` added before anything
+ *    is translated used to cost a broken entry in the language switcher — one
+ *    click — and would now 307 every German-preferring visitor off the
+ *    homepage into a 404. A non-default language is routable only when the
+ *    page `/<code>` really renders is (a) inside that language's own tree and
+ *    (b) among this build's pages.
+ *
+ *    Both clauses are load-bearing. `findFirstPage` falls through to the WHOLE
+ *    nav for a language block with no pages of its own, so (b) alone would
+ *    happily route `/de` at an English page — English served under a German
+ *    URL with `jd-lang=de` pinned, which is worse than not redirecting. And
+ *    (a) alone would route a language whose tree exists but whose front door
+ *    was never translated. The boundary this draws is deliberate: the test is
+ *    the visitor's ENTRY POINT, not page count. One translated page is enough
+ *    if it is the one `/<code>` lands on; two hundred are not enough if it is
+ *    missing. Resolution goes through findFirstPage — the same module the HTML
+ *    renderer and the markdown export both use — so this check cannot drift
+ *    from what the URL actually serves; it is called with the lowercased code
+ *    because that is the segment decideLanguageRedirect emits.
+ *
+ * The default language is exempt from (2). It is never a redirect destination
+ * — decideLanguageRedirect returns null as soon as the negotiated language is
+ * the default — but it has to stay in `languages` for negotiation to see it
+ * and for `defaultLanguage` to remain a member of its own list.
+ *
+ * @param builtPagePaths page paths this build produced, e.g. pageInfos[].path.
+ *   Required, not defaulted: an empty list disables routing for every
+ *   non-default language, and that must be a caller's decision rather than
+ *   something a forgotten argument does quietly.
+ */
+export function buildLanguagesArtifact(
+  docsConfig: DocsConfig,
+  builtPagePaths: readonly string[],
+): LanguagesFile {
+  const nav = docsConfig.navigation as
+    | { languages?: Array<{ language: string; default?: boolean; hidden?: boolean; href?: string }> }
+    | undefined;
+
+  // Applied HERE and not inside normalizeLanguageList(). That helper has
+  // another caller — deriveChunkLocale, via embedding-chunker.ts and
+  // json-ld.ts — which answers "what locale does this file belong to" for
+  // translation chunking and localized JSON-LD. A hidden or href-only entry is
+  // still a real locale for that question; it is only ineligible as an
+  // autoRedirect destination. Filtering inside normalizeLanguageList would
+  // have silently changed which pages get translated or how chunks are
+  // locale-tagged — a much bigger blast radius than this feature.
+  const eligible = (nav?.languages ?? []).filter((l) => l.hidden !== true && !l.href);
+  const entries = normalizeLanguageList(eligible);
+
+  const built = new Set(builtPagePaths.map(normalizePagePath));
+  const routable = entries.filter((entry) => {
+    if (entry.isDefault) return true;
+    const landing = normalizePagePath(findFirstPage(docsConfig, entry.code));
+    return landing.startsWith(`${entry.code}/`) && built.has(landing);
+  });
+
+  if (routable.length < 2) return noRoutingDescriptor();
+
+  const defaultEntry = routable.find((e) => e.isDefault) ?? routable[0];
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    autoRedirect: docsConfig.localization?.autoRedirect === true,
+    defaultLanguage: defaultEntry.code,
+    languages: routable.map((e) => e.code),
+  };
+}

package/vendored/lib/layout-helpers.tsx

@@ -24,6 +24,7 @@ import {
 import type { BackgroundConfig, DocsConfig, FontConfig, LanguageCode } from '@/lib/docs-types';
 import { LinkPrefixProvider } from '@/lib/link-prefix-context';
 import { ProjectSlugProvider } from '@/lib/project-slug-context';
+import { ThemePreviewProvider, type ThemePreviewValue } from '@/lib/theme-preview-context';
 import { getAnalyticsScript } from '@/lib/analytics-script';
 import { isConsentGatingEnabled, buildGatedScripts, getCmpScriptSrcs } from '@/lib/consent-gating';
 import { ConsentGate } from '@/components/ConsentGate';
@@ -410,6 +411,7 @@ interface DocsChromeProps {
   children: React.ReactNode;
   embed?: boolean;
   embedTheme?: 'light' | 'dark' | 'auto';
+  themePreview?: ThemePreviewValue;
 }
 
 /**
@@ -430,6 +432,7 @@ export async function DocsChrome({
   children,
   embed,
   embedTheme,
+  themePreview,
 }: DocsChromeProps): Promise<React.ReactElement> {
   // Lowercase to match docs-config canonical case — `data-theme="nebula"` CSS
   // selectors are case-sensitive, so `theme: "NEBULA"` from disk would silently
@@ -781,9 +784,19 @@ export async function DocsChrome({
         >
           <LinkPrefixProvider prefix={linkPrefix}>
             <ProjectSlugProvider slug={resolvedProjectSlug || ''}>
-              <LayoutWrapper config={config} embed={embed}>
-                {children}
-              </LayoutWrapper>
+              <ThemePreviewProvider
+                value={
+                  themePreview ?? {
+                    enabled: false,
+                    activeTheme: themeName ?? 'jam',
+                    defaultTheme: themeName ?? 'jam',
+                  }
+                }
+              >
+                <LayoutWrapper config={config} embed={embed}>
+                  {children}
+                </LayoutWrapper>
+              </ThemePreviewProvider>
             </ProjectSlugProvider>
           </LinkPrefixProvider>
           <CodeBlockCopyButton />

package/vendored/lib/mdx-import-scan.ts

@@ -0,0 +1,110 @@
+// Extracted from app/[[...slug]]/page.tsx: Next.js's route/page typegen
+// requires that a page.tsx export ONLY the known page-convention symbols
+// (default, generateStaticParams, generateMetadata, dynamic, ...) — any
+// other export fails `tsc`'s check of .next/types/app/**/page.ts with
+// TS2344 ("does not satisfy the constraint '{ [x: string]: never }'").
+// These helpers are used internally by generateStaticParams but also need
+// to be unit-testable, so they live here instead and are imported (not
+// re-exported) by page.tsx.
+import fs from 'fs';
+import path from 'path';
+import { getContentDir } from '@/lib/docs';
+import { readFileSync as readMdxFile } from '@/lib/fs-readfile';
+
+// Mirror of the CLI's detector regex in cli/src/lib/relative-mdx-imports.ts.
+// Duplicated intentionally — build-service uses bundler module resolution
+// and shouldn't reach into cli/src/. Keep the regex itself in sync with
+// that file. Two intentional simplifications vs the CLI version:
+//   - no `g` flag (boolean test, not iteration)
+//   - fence stripping replaces matches with empty string instead of
+//     blank lines of equal count — line numbers don't matter here, only
+//     a yes/no skip decision (the CLI preserves them for warning text).
+const PARENT_RELATIVE_MDX_IMPORT_RE =
+  /^[ \t]*import\s+(?:type\s+)?[\w$*{}, \n\r]+\s+from\s+["']\.{1,2}\/[^"']+\.mdx["']\s*;?/m;
+
+const FENCED_CODE_BLOCK_RE =
+  /^( *)(```+|~~~+)[^\n]*\n([\s\S]*?)\n\1\2\s*$/gm;
+
+// Cache for pageHasRelativeMdxImport, keyed by absolute file path,
+// invalidated when the file's mtime changes. `generateStaticParams` runs
+// on every nav in `jamdesk dev`, and the regex-test reads the FULL file
+// (per fix 7205c17c). For dodo (~200 MDX × 70-94 KB) that's 14-19 MB of
+// disk I/O per nav. Cache hit reduces it to a directory walk + statSync.
+//
+// In production ISR mode generateStaticParams returns [] before any of
+// this runs (see isIsrMode early-return), so the cache is dev-only in
+// practice. The cache is unbounded — entries for deleted files persist
+// until process exit. For a dev-only ~200-file working set this is
+// trivial (a few KB). If this pattern is reused in a long-running ISR
+// context in the future, add LRU eviction or rebuild-on-walk.
+const mdxImportCache = new Map<string, { mtimeMs: number; hasImport: boolean }>();
+
+export function pageHasRelativeMdxImport(filePath: string, mtimeMs?: number): boolean {
+  const cached = mdxImportCache.get(filePath);
+  if (cached && mtimeMs !== undefined && cached.mtimeMs === mtimeMs) {
+    return cached.hasImport;
+  }
+
+  let hasImport: boolean;
+  try {
+    // Read the full file — MDX imports can appear at any top-level position
+    // (after a long prose intro or table of contents), and a slice was
+    // missing real imports past byte ~8192 in 70-94 KB customer pages.
+    const content = readMdxFile(filePath);
+    // Strip fenced code blocks so documentation examples (e.g.
+    // ```mdx\nimport X from "../snippets/foo.mdx";\n```) don't false-trigger.
+    hasImport = PARENT_RELATIVE_MDX_IMPORT_RE.test(content.replace(FENCED_CODE_BLOCK_RE, ''));
+  } catch {
+    hasImport = false;
+  }
+
+  if (mtimeMs !== undefined) {
+    mdxImportCache.set(filePath, { mtimeMs, hasImport });
+  }
+  return hasImport;
+}
+
+/** Test-only: clear the per-file MDX-import cache between test cases. */
+export function _resetMdxImportCacheForTest(): void {
+  if (process.env.NODE_ENV === 'production') return;
+  mdxImportCache.clear();
+}
+
+interface CollectedPaths {
+  supported: string[];
+  skipped: string[];
+}
+
+export function getAllDocPaths(): CollectedPaths {
+  const contentDir = getContentDir();
+  const supported: string[] = [];
+  const skipped: string[] = [];
+
+  function traverseDir(dir: string, basePath: string = '') {
+    if (!fs.existsSync(dir)) return;
+    const files = fs.readdirSync(dir);
+    for (const file of files) {
+      if (file.startsWith('.')) continue;
+      const filePath = path.join(dir, file);
+      let stat;
+      try {
+        stat = fs.statSync(filePath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        traverseDir(filePath, path.join(basePath, file));
+      } else if (file.endsWith('.mdx')) {
+        const slug = path.join(basePath, file.replace(/\.mdx$/, ''));
+        if (pageHasRelativeMdxImport(filePath, stat.mtimeMs)) {
+          skipped.push(slug);
+        } else {
+          supported.push(slug);
+        }
+      }
+    }
+  }
+
+  traverseDir(contentDir);
+  return { supported, skipped };
+}