@aravindc26/velu 0.11.0 → 0.11.3

package/src/engine/lib/velu.ts

@@ -1,6 +1,14 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { normalizeConfigNavigation } from './navigation-normalize';
+const PRIMARY_CONFIG_NAME = 'docs.json';
+const LEGACY_CONFIG_NAME = 'velu.json';
+
+function resolveConfigPath(cwd: string): string {
+  const primary = resolve(cwd, PRIMARY_CONFIG_NAME);
+  if (existsSync(primary)) return primary;
+  return resolve(cwd, LEGACY_CONFIG_NAME);
+}
 
 interface VeluTab {
   tab: string;
@@ -10,6 +18,11 @@ interface VeluTab {
   groups?: VeluGroup[];
 }
 
+interface VeluTabMenuItem {
+  item: string;
+  pages?: Array<string | VeluSeparator | VeluLink>;
+}
+
 interface VeluSeparator {
   separator: string;
 }
@@ -29,6 +42,7 @@ interface VeluAnchor {
   anchor: string;
   href?: string;
   icon?: string;
+  iconType?: string;
   color?: {
     light: string;
     dark: string;
@@ -52,6 +66,7 @@ interface VeluProductNav {
   product: string;
   description?: string;
   icon?: string;
+  iconType?: string;
   hidden?: boolean;
   href?: string;
 }
@@ -63,11 +78,47 @@ interface VeluVersionNav {
   href?: string;
 }
 
+type VeluApiAuthMethod = 'bearer' | 'basic' | 'key' | 'none';
+
+interface VeluApiConfig {
+  baseUrl?: string;
+  playground?: {
+    mode?: string;
+    display?: string;
+    proxy?: boolean;
+  };
+  examples?: {
+    languages?: string[];
+    defaults?: 'required' | 'all';
+    prefill?: boolean;
+    autogenerate?: boolean;
+  };
+  mdx?: {
+    server?: string | string[];
+    auth?: {
+      method?: VeluApiAuthMethod | string;
+      name?: string;
+    };
+  };
+}
+
+interface VeluSeoConfig {
+  metatags?: Record<string, unknown>;
+  indexing?: 'navigable' | 'all' | string;
+}
+
+interface VeluThemeAsset {
+  light?: string;
+  dark?: string;
+  href?: string;
+}
+
 export interface VeluProductOption {
   product: string;
   slug: string;
   description?: string;
   icon?: string;
+  iconType?: string;
   tabSlugs: string[];
   defaultPath: string;
 }
@@ -81,8 +132,24 @@ export interface VeluVersionOption {
 }
 
 interface VeluConfig {
+  name?: string;
+  title?: string;
+  favicon?: string | VeluThemeAsset;
+  logo?: string | VeluThemeAsset;
+  colors?: {
+    primary?: string;
+    light?: string;
+    dark?: string;
+  };
+  icons?: {
+    library?: string;
+  };
   appearance?: 'system' | 'light' | 'dark';
   languages?: string[];
+  openapi?: string | string[] | Record<string, unknown>;
+  asyncapi?: string | string[] | Record<string, unknown>;
+  api?: VeluApiConfig;
+  seo?: VeluSeoConfig;
   navigation: {
     tabs?: VeluTab[];
     languages?: VeluLanguageNav[];
@@ -97,19 +164,39 @@ interface VeluConfig {
 }
 
 let cachedConfig: VeluConfig | null = null;
+let cachedRawConfig: Record<string, unknown> | null = null;
 
 function loadVeluConfig(): VeluConfig {
   if (cachedConfig) return cachedConfig;
-  const configPath = resolve(process.cwd(), 'velu.json');
+  const configPath = resolveConfigPath(process.cwd());
   const raw = readFileSync(configPath, 'utf-8');
   cachedConfig = normalizeConfigNavigation(JSON.parse(raw)) as VeluConfig;
   return cachedConfig;
 }
 
+function loadRawConfig(): Record<string, unknown> {
+  if (cachedRawConfig) return cachedRawConfig;
+  const configPath = resolveConfigPath(process.cwd());
+  const raw = readFileSync(configPath, 'utf-8');
+  const parsed = JSON.parse(raw);
+  cachedRawConfig = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+    ? parsed as Record<string, unknown>
+    : {};
+  return cachedRawConfig;
+}
+
 function isGroup(item: unknown): item is VeluGroup {
   return typeof item === 'object' && item !== null && 'group' in item;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isTabMenuItem(value: unknown): value is VeluTabMenuItem {
+  return isRecord(value) && typeof value.item === 'string';
+}
+
 function slugify(input: string, fallback: string): string {
   const slug = input
     .toLowerCase()
@@ -201,6 +288,60 @@ export function getGlobalAnchors(): VeluAnchor[] {
   );
 }
 
+export interface VeluTabMenuDefinition {
+  tab: string;
+  items: Array<{
+    item: string;
+    pages: string[];
+  }>;
+}
+
+function extractMenuItems(menuValue: unknown): VeluTabMenuDefinition['items'] {
+  if (!Array.isArray(menuValue)) return [];
+  const out: VeluTabMenuDefinition['items'] = [];
+  for (const entry of menuValue) {
+    if (!isTabMenuItem(entry)) continue;
+    const pages = Array.isArray(entry.pages)
+      ? entry.pages.filter((page): page is string => typeof page === 'string' && page.trim().length > 0)
+      : [];
+    out.push({ item: entry.item, pages });
+  }
+  return out;
+}
+
+function collectTabMenus(section: unknown, out: VeluTabMenuDefinition[]): void {
+  if (!isRecord(section)) return;
+
+  const tabs = Array.isArray(section.tabs) ? section.tabs : [];
+  for (const tabCandidate of tabs) {
+    if (!isRecord(tabCandidate)) continue;
+    if (typeof tabCandidate.tab === 'string') {
+      const items = extractMenuItems(tabCandidate.menu);
+      if (items.length > 0) out.push({ tab: tabCandidate.tab, items });
+    }
+    collectTabMenus(tabCandidate, out);
+  }
+
+  const nestedKeys: Array<'dropdowns' | 'products' | 'versions' | 'anchors'> = [
+    'dropdowns',
+    'products',
+    'versions',
+    'anchors',
+  ];
+  for (const key of nestedKeys) {
+    const list = Array.isArray(section[key]) ? section[key] : [];
+    for (const entry of list) collectTabMenus(entry, out);
+  }
+}
+
+export function getTabMenuDefinitions(): VeluTabMenuDefinition[] {
+  const raw = loadRawConfig();
+  const navigation = isRecord(raw.navigation) ? raw.navigation : {};
+  const out: VeluTabMenuDefinition[] = [];
+  collectTabMenus(navigation, out);
+  return out;
+}
+
 export function getLanguages(): string[] {
   const config = loadVeluConfig();
   // Prefer navigation.languages codes, fall back to top-level languages
@@ -239,6 +380,7 @@ export function getProductOptions(): VeluProductOption[] {
       slug: prefix,
       description: product.description,
       icon: product.icon,
+      iconType: product.iconType,
       tabSlugs,
       defaultPath,
     };
@@ -304,3 +446,227 @@ export function getAppearance(): 'system' | 'light' | 'dark' {
   if (appearance === 'light' || appearance === 'dark') return appearance;
   return 'system';
 }
+
+export type VeluIconLibrary = 'fontawesome' | 'lucide' | 'tabler';
+
+export function getIconLibrary(): VeluIconLibrary {
+  const raw = loadVeluConfig().icons?.library;
+  if (raw === 'lucide' || raw === 'tabler' || raw === 'fontawesome') return raw;
+  return 'fontawesome';
+}
+
+type PlaygroundDisplayMode = 'interactive' | 'simple' | 'none' | 'auth';
+
+export interface VeluResolvedApiConfig {
+  baseUrl?: string;
+  mdxServer?: string;
+  mdxServers?: string[];
+  authMethod: VeluApiAuthMethod;
+  authName?: string;
+  playgroundDisplay: PlaygroundDisplayMode;
+  playgroundProxyEnabled: boolean;
+  exampleLanguages?: string[];
+  exampleDefaults: 'required' | 'all';
+  examplePrefill: boolean;
+  exampleAutogenerate: boolean;
+  defaultOpenApiSpec?: string;
+  defaultAsyncApiSpec?: string;
+}
+
+export interface VeluResolvedSeoConfig {
+  metatags: Record<string, string>;
+  indexing: 'navigable' | 'all';
+}
+
+function normalizePlaygroundDisplay(api: VeluApiConfig | undefined): PlaygroundDisplayMode {
+  const display = api?.playground?.display;
+  if (display === 'interactive' || display === 'simple' || display === 'none') return display;
+  if (display === 'auth') return 'none';
+
+  const mode = api?.playground?.mode;
+  if (mode === 'hide' || mode === 'none') return 'none';
+  return 'interactive';
+}
+
+function normalizeAuthMethod(method: unknown): VeluApiAuthMethod {
+  if (method === 'bearer' || method === 'basic' || method === 'key' || method === 'none') return method;
+  return 'none';
+}
+
+function extractOpenApiSource(openapi: VeluConfig['openapi']): string | string[] | undefined {
+  if (typeof openapi === 'string' || Array.isArray(openapi)) return openapi;
+  if (openapi && typeof openapi === 'object') {
+    const source = (openapi as Record<string, unknown>).source;
+    if (typeof source === 'string' || Array.isArray(source)) return source as string | string[];
+  }
+  return undefined;
+}
+
+function resolveDefaultOpenApiSpec(openapi: VeluConfig['openapi']): string | undefined {
+  const source = extractOpenApiSource(openapi);
+  if (typeof source === 'string' && source.trim()) return source.trim();
+  if (Array.isArray(source)) {
+    const first = source.find((entry) => typeof entry === 'string' && entry.trim().length > 0);
+    return typeof first === 'string' ? first.trim() : undefined;
+  }
+  return undefined;
+}
+
+function normalizeExampleLanguages(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const normalized = value
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function normalizeMdxServers(value: unknown): string[] | undefined {
+  const rawValues = Array.isArray(value) ? value : (typeof value === 'string' ? [value] : []);
+  const normalized = rawValues
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function normalizeSeoMetatags(value: unknown): Record<string, string> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const output: Record<string, string> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    const tag = key.trim();
+    if (!tag) continue;
+    if (typeof raw === 'string') {
+      const normalized = raw.trim();
+      if (normalized) output[tag] = normalized;
+      continue;
+    }
+    if (typeof raw === 'number' || typeof raw === 'boolean') {
+      output[tag] = String(raw);
+    }
+  }
+  return output;
+}
+
+function normalizeAssetPath(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeThemeAsset(value: unknown): VeluThemeAsset {
+  if (typeof value === 'string') {
+    const asset = normalizeAssetPath(value);
+    return asset ? { light: asset, dark: asset } : {};
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const record = value as Record<string, unknown>;
+  const light = normalizeAssetPath(record.light);
+  const dark = normalizeAssetPath(record.dark);
+  const any = normalizeAssetPath(record.default);
+  const href = normalizeAssetPath(record.href);
+  return {
+    ...(light ? { light } : {}),
+    ...(dark ? { dark } : {}),
+    ...(!light && any ? { light: any } : {}),
+    ...(!dark && any ? { dark: any } : {}),
+    ...(href ? { href } : {}),
+  };
+}
+
+function extractOrigin(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  try {
+    return new URL(trimmed).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+export function getApiConfig(): VeluResolvedApiConfig {
+  const config = loadVeluConfig();
+  const api = config.api;
+  const auth = api?.mdx?.auth;
+  const examples = api?.examples;
+  const playgroundDisplay = normalizePlaygroundDisplay(api);
+  const staticExportBuild = process.env.VELU_STATIC_EXPORT === '1';
+  const mdxServers = normalizeMdxServers(api?.mdx?.server);
+
+  return {
+    baseUrl: typeof api?.baseUrl === 'string' && api.baseUrl.trim() ? api.baseUrl.trim() : undefined,
+    mdxServer: mdxServers?.[0],
+    mdxServers,
+    authMethod: normalizeAuthMethod(auth?.method),
+    authName: typeof auth?.name === 'string' && auth.name.trim() ? auth.name.trim() : undefined,
+    playgroundDisplay,
+    // Next static export cannot include runtime route handlers such as /api/proxy.
+    // Disable proxy automatically for static export builds.
+    playgroundProxyEnabled: !staticExportBuild && api?.playground?.proxy !== false,
+    exampleLanguages: normalizeExampleLanguages(examples?.languages),
+    exampleDefaults: examples?.defaults === 'required' ? 'required' : 'all',
+    examplePrefill: examples?.prefill === true,
+    exampleAutogenerate: examples?.autogenerate !== false,
+    defaultOpenApiSpec: resolveDefaultOpenApiSpec(config.openapi),
+    defaultAsyncApiSpec: resolveDefaultOpenApiSpec(config.asyncapi),
+  };
+}
+
+export function getSeoConfig(): VeluResolvedSeoConfig {
+  const config = loadVeluConfig();
+  const seo = config.seo;
+  const indexing: 'navigable' | 'all' = seo?.indexing === 'all' ? 'all' : 'navigable';
+  return {
+    metatags: normalizeSeoMetatags(seo?.metatags),
+    indexing,
+  };
+}
+
+export function getSiteName(): string {
+  const config = loadVeluConfig();
+  const fromName = normalizeAssetPath(config.name);
+  if (fromName) return fromName;
+  const fromTitle = normalizeAssetPath(config.title);
+  if (fromTitle) return fromTitle;
+  return 'Velu Docs';
+}
+
+export function getSiteFavicon(): string | undefined {
+  const config = loadVeluConfig();
+  const asset = normalizeThemeAsset(config.favicon);
+  return asset.light ?? asset.dark;
+}
+
+export function getSiteLogoAsset(): VeluThemeAsset {
+  const config = loadVeluConfig();
+  return normalizeThemeAsset(config.logo);
+}
+
+export function getSitePrimaryColor(): string | undefined {
+  const config = loadVeluConfig();
+  const colors = config.colors;
+  if (!colors) return undefined;
+  return normalizeAssetPath(colors.primary) ?? normalizeAssetPath(colors.light) ?? normalizeAssetPath(colors.dark);
+}
+
+export function getSiteOrigin(): string {
+  const seo = getSeoConfig();
+  const envCandidates = [
+    process.env.VELU_SITE_URL,
+    process.env.NEXT_PUBLIC_SITE_URL,
+    process.env.SITE_URL,
+  ];
+  for (const candidate of envCandidates) {
+    const origin = extractOrigin(candidate);
+    if (origin) return origin;
+  }
+
+  const canonicalOrigin = extractOrigin(seo.metatags.canonical);
+  if (canonicalOrigin) return canonicalOrigin;
+
+  const ogOrigin = extractOrigin(seo.metatags['og:url']);
+  if (ogOrigin) return ogOrigin;
+
+  return 'http://localhost:4321';
+}