@raystack/chronicle 0.5.3 → 0.6.0

package/src/lib/config.test.ts

@@ -0,0 +1,493 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { chronicleConfigSchema } from '@/types'
+import {
+  getAllVersions,
+  getApiConfigsForVersion,
+  getLandingEntries,
+  getLatestContentRoots,
+  getVersionContentRoots,
+  loadConfig,
+} from './config'
+
+type GlobalWithRaw = typeof globalThis & {
+  __CHRONICLE_CONFIG_RAW__?: string | null
+}
+
+const g = globalThis as GlobalWithRaw
+
+const minimal = {
+  site: { title: 'My Docs' },
+  content: [{ dir: 'docs', label: 'Docs' }],
+}
+
+describe('chronicleConfigSchema', () => {
+  test('parses minimal single-content config', () => {
+    const parsed = chronicleConfigSchema.parse(minimal)
+    expect(parsed.site.title).toBe('My Docs')
+    expect(parsed.content).toEqual([{ dir: 'docs', label: 'Docs' }])
+  })
+
+  test('parses multi-content config', () => {
+    const parsed = chronicleConfigSchema.parse({
+      ...minimal,
+      content: [
+        { dir: 'docs', label: 'Docs' },
+        { dir: 'dev', label: 'Dev Docs' },
+      ],
+    })
+    expect(parsed.content).toHaveLength(2)
+  })
+
+  test('parses versioned config with badge and defaults variant to accent', () => {
+    const parsed = chronicleConfigSchema.parse({
+      ...minimal,
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          badge: { label: 'deprecated' },
+          content: [{ dir: 'docs', label: 'Docs' }],
+        },
+      ],
+    })
+    expect(parsed.versions?.[0].badge).toEqual({
+      label: 'deprecated',
+      variant: 'accent',
+    })
+  })
+
+  test('accepts explicit badge variant', () => {
+    const parsed = chronicleConfigSchema.parse({
+      ...minimal,
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          badge: { label: 'deprecated', variant: 'warning' },
+          content: [{ dir: 'docs', label: 'Docs' }],
+        },
+      ],
+    })
+    expect(parsed.versions?.[0].badge?.variant).toBe('warning')
+  })
+
+  test('rejects unknown top-level field (legacy title)', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({ ...minimal, title: 'My Docs' }),
+    ).toThrow()
+  })
+
+  test('rejects string form of content', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({ site: { title: 'x' }, content: '.' }),
+    ).toThrow()
+  })
+
+  test('rejects empty content array', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({ site: { title: 'x' }, content: [] }),
+    ).toThrow()
+  })
+
+  test('rejects invalid dir names (hidden, path-shaped, whitespace)', () => {
+    const bad = ['.', '..', 'foo/bar', 'foo\\bar', '.hidden', ' docs', 'docs ', 'do cs', '']
+    for (const dir of bad) {
+      expect(() =>
+        chronicleConfigSchema.parse({
+          site: { title: 'x' },
+          content: [{ dir, label: 'Docs' }],
+        }),
+      ).toThrow()
+    }
+  })
+
+  test('accepts standard dir names (letters, digits, dash, underscore)', () => {
+    for (const dir of ['docs', 'dev-docs', 'v1', 'v1_beta', 'api2']) {
+      expect(() =>
+        chronicleConfigSchema.parse({
+          site: { title: 'x' },
+          content: [{ dir, label: 'x' }],
+        }),
+      ).not.toThrow()
+    }
+  })
+
+  test('rejects version dir overlapping a top-level content dir', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        site: { title: 'x' },
+        content: [{ dir: 'v1', label: 'V1 docs' }],
+        latest: { label: '2.0' },
+        versions: [
+          {
+            dir: 'v1',
+            label: '1.0',
+            content: [{ dir: 'docs', label: 'Docs' }],
+          },
+        ],
+      }),
+    ).toThrow(/must not overlap/)
+  })
+
+  test('rejects reserved route segments as dir names', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        site: { title: 'x' },
+        content: [{ dir: 'apis', label: 'API' }],
+      }),
+    ).toThrow(/reserved route segment/)
+
+    expect(() =>
+      chronicleConfigSchema.parse({
+        site: { title: 'x' },
+        content: [{ dir: 'docs', label: 'Docs' }],
+        latest: { label: '2.0' },
+        versions: [
+          {
+            dir: 'apis',
+            label: '1.0',
+            content: [{ dir: 'docs', label: 'Docs' }],
+          },
+        ],
+      }),
+    ).toThrow(/reserved route segment/)
+  })
+
+  test('rejects "." or ".." version dir', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        site: { title: 'x' },
+        content: [{ dir: 'docs', label: 'Docs' }],
+        latest: { label: '2.0' },
+        versions: [
+          {
+            dir: '.',
+            label: '1.0',
+            content: [{ dir: 'docs', label: 'Docs' }],
+          },
+        ],
+      }),
+    ).toThrow()
+  })
+
+  test('rejects versions without latest', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        ...minimal,
+        versions: [
+          {
+            dir: 'v1',
+            label: '1.0',
+            content: [{ dir: 'docs', label: 'Docs' }],
+          },
+        ],
+      }),
+    ).toThrow(/latest is required/)
+  })
+
+  test('rejects duplicate content[].dir', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        ...minimal,
+        content: [
+          { dir: 'docs', label: 'A' },
+          { dir: 'docs', label: 'B' },
+        ],
+      }),
+    ).toThrow(/content\[\]\.dir must be unique/)
+  })
+
+  test('rejects duplicate versions[].dir', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        ...minimal,
+        latest: { label: '3.0' },
+        versions: [
+          { dir: 'v1', label: '1', content: [{ dir: 'docs', label: 'd' }] },
+          { dir: 'v1', label: '1b', content: [{ dir: 'docs', label: 'd' }] },
+        ],
+      }),
+    ).toThrow(/versions\[\]\.dir must be unique/)
+  })
+
+  test('rejects duplicate content dirs within a version', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        ...minimal,
+        latest: { label: '3.0' },
+        versions: [
+          {
+            dir: 'v1',
+            label: '1',
+            content: [
+              { dir: 'docs', label: 'A' },
+              { dir: 'docs', label: 'B' },
+            ],
+          },
+        ],
+      }),
+    ).toThrow(/unique within each version/)
+  })
+
+  test('rejects invalid badge variant', () => {
+    expect(() =>
+      chronicleConfigSchema.parse({
+        ...minimal,
+        latest: { label: '3.0' },
+        versions: [
+          {
+            dir: 'v1',
+            label: '1',
+            badge: { label: 'x', variant: 'info' },
+            content: [{ dir: 'docs', label: 'd' }],
+          },
+        ],
+      }),
+    ).toThrow()
+  })
+})
+
+describe('getLatestContentRoots', () => {
+  test('maps each content entry to content/<dir>', () => {
+    const cfg = chronicleConfigSchema.parse({
+      ...minimal,
+      content: [
+        { dir: 'docs', label: 'Docs' },
+        { dir: 'dev', label: 'Dev Docs' },
+      ],
+    })
+    const roots = getLatestContentRoots(cfg)
+    expect(roots).toEqual([
+      {
+        versionDir: null,
+        versionLabel: null,
+        contentDir: 'docs',
+        contentLabel: 'Docs',
+        fsPath: 'content/docs',
+        urlPrefix: '/docs',
+      },
+      {
+        versionDir: null,
+        versionLabel: null,
+        contentDir: 'dev',
+        contentLabel: 'Dev Docs',
+        fsPath: 'content/dev',
+        urlPrefix: '/dev',
+      },
+    ])
+  })
+
+  test('includes versionLabel when latest is set', () => {
+    const cfg = chronicleConfigSchema.parse({
+      ...minimal,
+      latest: { label: '3.0' },
+    })
+    expect(getLatestContentRoots(cfg)[0].versionLabel).toBe('3.0')
+  })
+})
+
+describe('getVersionContentRoots', () => {
+  test('resolves versions/<v>/<dir> and preserves config order', () => {
+    const cfg = chronicleConfigSchema.parse({
+      ...minimal,
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          content: [
+            { dir: 'dev', label: 'Developer Guide' },
+            { dir: 'docs', label: 'Docs' },
+          ],
+        },
+      ],
+    })
+    const roots = getVersionContentRoots(cfg, 'v1')
+    expect(roots.map((r) => r.fsPath)).toEqual([
+      'versions/v1/dev',
+      'versions/v1/docs',
+    ])
+    expect(roots.map((r) => r.urlPrefix)).toEqual(['/v1/dev', '/v1/docs'])
+    expect(roots[0].contentLabel).toBe('Developer Guide')
+  })
+
+  test('returns empty array for unknown version', () => {
+    const cfg = chronicleConfigSchema.parse(minimal)
+    expect(getVersionContentRoots(cfg, 'v1')).toEqual([])
+  })
+})
+
+describe('getAllVersions', () => {
+  test('returns latest first then versions in config order', () => {
+    const cfg = chronicleConfigSchema.parse({
+      ...minimal,
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v2',
+          label: '2.0',
+          content: [{ dir: 'docs', label: 'Docs' }],
+        },
+        {
+          dir: 'v1',
+          label: '1.0',
+          badge: { label: 'deprecated', variant: 'warning' },
+          content: [{ dir: 'docs', label: 'Docs' }],
+        },
+      ],
+    })
+    const all = getAllVersions(cfg)
+    expect(all).toEqual([
+      { dir: null, label: '3.0', isLatest: true },
+      { dir: 'v2', label: '2.0', isLatest: false },
+      {
+        dir: 'v1',
+        label: '1.0',
+        badge: { label: 'deprecated', variant: 'warning' },
+        isLatest: false,
+      },
+    ])
+  })
+
+  test('always includes the latest entry, even without latest or versions', () => {
+    const cfg = chronicleConfigSchema.parse(minimal)
+    expect(getAllVersions(cfg)).toEqual([
+      { dir: null, label: '', isLatest: true },
+    ])
+  })
+})
+
+describe('getLandingEntries', () => {
+  test('returns labels + unprefixed hrefs for latest', () => {
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [
+        { dir: 'docs', label: 'Docs' },
+        { dir: 'dev', label: 'Dev' },
+      ],
+    })
+    expect(getLandingEntries(cfg, null)).toEqual([
+      { label: 'Docs', href: '/docs', contentDir: 'docs' },
+      { label: 'Dev', href: '/dev', contentDir: 'dev' },
+    ])
+  })
+
+  test('returns versioned hrefs for a version', () => {
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          content: [
+            { dir: 'dev', label: 'Developer Guide' },
+            { dir: 'docs', label: 'Docs' },
+          ],
+        },
+      ],
+    })
+    expect(getLandingEntries(cfg, 'v1')).toEqual([
+      { label: 'Developer Guide', href: '/v1/dev', contentDir: 'dev' },
+      { label: 'Docs', href: '/v1/docs', contentDir: 'docs' },
+    ])
+  })
+
+  test('returns empty array for unknown version', () => {
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+    })
+    expect(getLandingEntries(cfg, 'v9')).toEqual([])
+  })
+})
+
+describe('getApiConfigsForVersion', () => {
+  const apiFixture = {
+    name: 'Petstore',
+    spec: './petstore.json',
+    basePath: '/apis',
+    server: { url: 'https://petstore.example.com' },
+  }
+
+  test('returns config.api for latest (null)', () => {
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+      api: [apiFixture],
+    })
+    expect(getApiConfigsForVersion(cfg, null)).toEqual([apiFixture])
+  })
+
+  test('returns versions[].api for a matching version', () => {
+    const versionedApi = { ...apiFixture, spec: './v1-petstore.json' }
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          content: [{ dir: 'docs', label: 'Docs' }],
+          api: [versionedApi],
+        },
+      ],
+    })
+    expect(getApiConfigsForVersion(cfg, 'v1')).toEqual([versionedApi])
+  })
+
+  test('returns [] for unknown version or missing api', () => {
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+    })
+    expect(getApiConfigsForVersion(cfg, 'v9')).toEqual([])
+    expect(getApiConfigsForVersion(cfg, null)).toEqual([])
+  })
+})
+
+describe('loadConfig', () => {
+  beforeEach(() => {
+    delete g.__CHRONICLE_CONFIG_RAW__
+  })
+
+  afterEach(() => {
+    delete g.__CHRONICLE_CONFIG_RAW__
+  })
+
+  test('returns default config when raw is undefined', () => {
+    const cfg = loadConfig()
+    expect(cfg.site.title).toBe('Documentation')
+    expect(cfg.content).toEqual([{ dir: 'docs', label: 'Docs' }])
+  })
+
+  test('returns default config when raw is null', () => {
+    g.__CHRONICLE_CONFIG_RAW__ = null
+    const cfg = loadConfig()
+    expect(cfg.site.title).toBe('Documentation')
+  })
+
+  test('parses yaml raw string', () => {
+    g.__CHRONICLE_CONFIG_RAW__ = `
+site:
+  title: Yaml Docs
+content:
+  - dir: docs
+    label: Docs
+  - dir: dev
+    label: Dev
+`
+    const cfg = loadConfig()
+    expect(cfg.site.title).toBe('Yaml Docs')
+    expect(cfg.content).toHaveLength(2)
+  })
+
+  test('throws on invalid yaml config', () => {
+    g.__CHRONICLE_CONFIG_RAW__ = 'title: Legacy'
+    expect(() => loadConfig()).toThrow()
+  })
+})

package/src/lib/config.ts

@@ -1,32 +1,133 @@
-import { parse } from 'yaml';
-import type { ChronicleConfig } from '@/types';
+import { parse } from 'yaml'
+import {
+  type ApiConfig,
+  type BadgeConfig,
+  type ChronicleConfig,
+  chronicleConfigSchema,
+} from '@/types'
 
-const defaultConfig: ChronicleConfig = {
-  title: 'Documentation',
+const defaultConfig: ChronicleConfig = chronicleConfigSchema.parse({
+  site: { title: 'Documentation' },
+  content: [{ dir: 'docs', label: 'Docs' }],
   theme: { name: 'default' },
-  search: { enabled: true, placeholder: 'Search...' }
-};
+  search: { enabled: true, placeholder: 'Search...' },
+})
 
 export function loadConfig(): ChronicleConfig {
-  const raw = typeof __CHRONICLE_CONFIG_RAW__ !== 'undefined' ? __CHRONICLE_CONFIG_RAW__ : null;
+  const raw =
+    typeof __CHRONICLE_CONFIG_RAW__ !== 'undefined'
+      ? __CHRONICLE_CONFIG_RAW__
+      : null
 
-  if (!raw) {
-    return defaultConfig;
-  }
-
-  const userConfig = parse(raw) as Partial<ChronicleConfig>;
+  if (!raw) return defaultConfig
 
+  const parsed = chronicleConfigSchema.parse(parse(raw))
   return {
     ...defaultConfig,
-    ...userConfig,
-    theme: {
-      name: userConfig.theme?.name ?? defaultConfig.theme!.name,
-      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors }
+    ...parsed,
+    theme: { ...defaultConfig.theme, ...parsed.theme },
+    search: { ...defaultConfig.search, ...parsed.search },
+  }
+}
+
+export interface ContentRoot {
+  versionDir: string | null
+  versionLabel: string | null
+  contentDir: string
+  contentLabel: string
+  contentIcon?: string
+  fsPath: string
+  urlPrefix: string
+}
+
+export function getLatestContentRoots(config: ChronicleConfig): ContentRoot[] {
+  return config.content.map((c) => ({
+    versionDir: null,
+    versionLabel: config.latest?.label ?? null,
+    contentDir: c.dir,
+    contentLabel: c.label,
+    contentIcon: c.icon,
+    fsPath: `content/${c.dir}`,
+    urlPrefix: `/${c.dir}`,
+  }))
+}
+
+export function getVersionContentRoots(
+  config: ChronicleConfig,
+  versionDir: string,
+): ContentRoot[] {
+  const version = config.versions?.find((v) => v.dir === versionDir)
+  if (!version) return []
+
+  return version.content.map((c) => ({
+    versionDir: version.dir,
+    versionLabel: version.label,
+    contentDir: c.dir,
+    contentLabel: c.label,
+    contentIcon: c.icon,
+    fsPath: `versions/${version.dir}/${c.dir}`,
+    urlPrefix: `/${version.dir}/${c.dir}`,
+  }))
+}
+
+export interface VersionDescriptor {
+  dir: string | null
+  label: string
+  badge?: BadgeConfig
+  isLatest: boolean
+}
+
+export interface LandingEntry {
+  label: string
+  href: string
+  contentDir: string
+  icon?: string
+}
+
+export function getLandingEntries(
+  config: ChronicleConfig,
+  versionDir: string | null,
+): LandingEntry[] {
+  const roots =
+    versionDir === null
+      ? getLatestContentRoots(config)
+      : getVersionContentRoots(config, versionDir)
+
+  return roots.map((r) => ({
+    label: r.contentLabel,
+    href: r.urlPrefix,
+    contentDir: r.contentDir,
+    icon: r.contentIcon,
+  }))
+}
+
+export function getApiConfigsForVersion(
+  config: ChronicleConfig,
+  versionDir: string | null,
+): ApiConfig[] {
+  if (versionDir === null) return config.api ?? []
+  return (
+    config.versions?.find((v) => v.dir === versionDir)?.api ?? []
+  )
+}
+
+export function getAllVersions(config: ChronicleConfig): VersionDescriptor[] {
+  const result: VersionDescriptor[] = [
+    {
+      dir: null,
+      label: config.latest?.label ?? '',
+      isLatest: true,
     },
-    search: { ...defaultConfig.search, ...userConfig.search },
-    footer: userConfig.footer,
-    api: userConfig.api,
-    llms: { enabled: false, ...userConfig.llms },
-    analytics: { enabled: false, ...userConfig.analytics }
-  };
+  ]
+
+  for (const v of config.versions ?? []) {
+    result.push({
+      dir: v.dir,
+      label: v.label,
+      badge: v.badge,
+      isLatest: false,
+    })
+  }
+
+  return result
 }

package/src/lib/head.tsx

@@ -1,3 +1,4 @@
+import { useLocation } from 'react-router';
 import type { ChronicleConfig } from '@/types';
 
 export interface HeadProps {
@@ -5,17 +6,33 @@ export interface HeadProps {
   description?: string;
   config: ChronicleConfig;
   jsonLd?: Record<string, unknown>;
+  markdownHref?: string;
 }
 
-export function Head({ title, description, config, jsonLd }: HeadProps) {
-  const fullTitle = `${title} | ${config.title}`;
+export function Head({ title, description, config, jsonLd, markdownHref }: HeadProps) {
+  const { pathname } = useLocation();
+  const fullTitle = `${title} | ${config.site.title}`;
   const ogParams = new URLSearchParams({ title });
   if (description) ogParams.set('description', description);
+  const siteUrl = config.url ? config.url.replace(/\/$/, '') : null;
+  const canonical = siteUrl ? `${siteUrl}${pathname}` : null;
+  const ogImage = siteUrl
+    ? `${siteUrl}/og?${ogParams.toString()}`
+    : `/og?${ogParams.toString()}`;
 
   return (
     <>
       <title>{fullTitle}</title>
       {description && <meta name='description' content={description} />}
+      {canonical && <link rel='canonical' href={canonical} />}
+      {markdownHref && (
+        <link
+          rel='alternate'
+          type='text/markdown'
+          href={markdownHref}
+          title={`${title} (Markdown)`}
+        />
+      )}
 
       {config.url && (
         <>
@@ -23,9 +40,10 @@ export function Head({ title, description, config, jsonLd }: HeadProps) {
           {description && (
             <meta property='og:description' content={description} />
           )}
-          <meta property='og:site_name' content={config.title} />
+          <meta property='og:site_name' content={config.site.title} />
           <meta property='og:type' content='website' />
-          <meta property='og:image' content={`/og?${ogParams.toString()}`} />
+          {canonical && <meta property='og:url' content={canonical} />}
+          <meta property='og:image' content={ogImage} />
           <meta property='og:image:width' content='1200' />
           <meta property='og:image:height' content='630' />
 
@@ -34,7 +52,7 @@ export function Head({ title, description, config, jsonLd }: HeadProps) {
           {description && (
             <meta name='twitter:description' content={description} />
           )}
-          <meta name='twitter:image' content={`/og?${ogParams.toString()}`} />
+          <meta name='twitter:image' content={ogImage} />
         </>
       )}