@raystack/chronicle 0.5.4 → 0.6.1

package/src/lib/llms.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+import { chronicleConfigSchema } from '@/types'
+import { buildLlmsTxt } from './llms'
+import { LATEST_CONTEXT } from './version-source'
+
+describe('buildLlmsTxt', () => {
+  test('uses site.title and appends latest label when set', () => {
+    const config = chronicleConfigSchema.parse({
+      site: { title: 'My Docs' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          content: [{ dir: 'docs', label: 'Docs' }],
+        },
+      ],
+    })
+
+    const out = buildLlmsTxt(
+      config,
+      [
+        { url: '/docs/a', title: 'A' },
+        { url: '/', title: 'Home' },
+      ],
+      LATEST_CONTEXT,
+    )
+
+    expect(out).toContain('# My Docs — 3.0')
+    expect(out).toContain('- [A](/docs/a.md)')
+    expect(out).toContain('- [Home](/index.md)')
+  })
+
+  test('heading has no version label when latest is absent and ctx is latest', () => {
+    const config = chronicleConfigSchema.parse({
+      site: { title: 'My Docs' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+    })
+
+    const out = buildLlmsTxt(config, [], LATEST_CONTEXT)
+    expect(out.startsWith('# My Docs\n')).toBe(true)
+  })
+
+  test('falls back to page url when title is missing or empty', () => {
+    const config = chronicleConfigSchema.parse({
+      site: { title: 'Docs' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+    })
+    const out = buildLlmsTxt(
+      config,
+      [
+        { url: '/docs/untitled' },
+        { url: '/docs/blank', title: '   ' },
+      ],
+      LATEST_CONTEXT,
+    )
+    expect(out).toContain('- [/docs/untitled](/docs/untitled.md)')
+    expect(out).toContain('- [/docs/blank](/docs/blank.md)')
+  })
+
+  test('omits the description line when description is empty', () => {
+    const config = chronicleConfigSchema.parse({
+      site: { title: 'Docs' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+    })
+    const out = buildLlmsTxt(config, [{ url: '/a', title: 'A' }], LATEST_CONTEXT)
+    // heading immediately followed by a single blank line then the index
+    expect(out).toBe('# Docs\n\n- [A](/a.md)')
+  })
+
+  test('uses the version label for a versioned ctx', () => {
+    const config = chronicleConfigSchema.parse({
+      site: { title: 'My Docs' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+      latest: { label: '3.0' },
+      versions: [
+        {
+          dir: 'v1',
+          label: '1.0',
+          content: [{ dir: 'docs', label: 'Docs' }],
+        },
+      ],
+    })
+
+    const out = buildLlmsTxt(
+      config,
+      [{ url: '/v1/docs/a', title: 'A' }],
+      { dir: 'v1', urlPrefix: '/v1' },
+    )
+    expect(out).toContain('# My Docs — 1.0')
+    expect(out).toContain('- [A](/v1/docs/a.md)')
+  })
+})

package/src/lib/llms.ts

@@ -0,0 +1,41 @@
+import type { ChronicleConfig } from '@/types'
+import type { VersionContext } from './version-source'
+
+export interface LlmsPage {
+  url: string
+  title?: string
+}
+
+export function buildLlmsTxt(
+  config: ChronicleConfig,
+  pages: LlmsPage[],
+  version: VersionContext,
+): string {
+  const versionLabel = getVersionLabel(config, version)
+  const heading = versionLabel
+    ? `# ${config.site.title} — ${versionLabel}`
+    : `# ${config.site.title}`
+
+  const description = config.site.description ?? ''
+
+  const index = pages
+    .map((p) => {
+      const mdUrl = p.url === '/' ? '/index.md' : `${p.url}.md`
+      const title = p.title?.trim() || p.url
+      return `- [${title}](${mdUrl})`
+    })
+    .join('\n')
+
+  const parts = [heading]
+  if (description) parts.push(description)
+  parts.push(index)
+  return parts.join('\n\n')
+}
+
+function getVersionLabel(
+  config: ChronicleConfig,
+  version: VersionContext,
+): string | null {
+  if (version.dir === null) return config.latest?.label ?? null
+  return config.versions?.find((v) => v.dir === version.dir)?.label ?? null
+}

package/src/lib/navigation.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+import { type ChronicleConfig, chronicleConfigSchema } from '@/types'
+import {
+  getActiveContentDir,
+  getVersionHomeHref,
+  splitContentButtons,
+} from './navigation'
+
+function versioned(): ChronicleConfig {
+  return chronicleConfigSchema.parse({
+    site: { title: 'x' },
+    content: [
+      { dir: 'docs', label: 'Docs' },
+      { dir: 'dev', label: 'Dev' },
+    ],
+    latest: { label: '3.0' },
+    versions: [
+      {
+        dir: 'v1',
+        label: '1.0',
+        content: [
+          { dir: 'docs', label: 'Docs' },
+          { dir: 'dev', label: 'Dev' },
+        ],
+      },
+    ],
+  })
+}
+
+describe('getActiveContentDir', () => {
+  test('returns latest content dir from URL', () => {
+    expect(getActiveContentDir('/docs/intro', versioned())).toBe('docs')
+    expect(getActiveContentDir('/dev/setup', versioned())).toBe('dev')
+  })
+
+  test('returns versioned content dir from URL', () => {
+    expect(getActiveContentDir('/v1/docs/intro', versioned())).toBe('docs')
+    expect(getActiveContentDir('/v1/dev/setup', versioned())).toBe('dev')
+  })
+
+  test('returns null for root and api routes', () => {
+    expect(getActiveContentDir('/', versioned())).toBeNull()
+    expect(getActiveContentDir('/v1', versioned())).toBeNull()
+    expect(getActiveContentDir('/apis/x', versioned())).toBeNull()
+    expect(getActiveContentDir('/v1/apis/x', versioned())).toBeNull()
+  })
+
+  test('returns null for unknown content dir', () => {
+    expect(getActiveContentDir('/random', versioned())).toBeNull()
+    expect(getActiveContentDir('/v1/random', versioned())).toBeNull()
+  })
+})
+
+describe('getVersionHomeHref', () => {
+  test('single content dir returns /<dir>', () => {
+    const cfg = chronicleConfigSchema.parse({
+      site: { title: 'x' },
+      content: [{ dir: 'docs', label: 'Docs' }],
+    })
+    expect(getVersionHomeHref(cfg, null)).toBe('/docs')
+  })
+
+  test('multi content dir returns / (version root for landing)', () => {
+    expect(getVersionHomeHref(versioned(), null)).toBe('/')
+  })
+
+  test('versioned multi content returns /<v>', () => {
+    expect(getVersionHomeHref(versioned(), 'v1')).toBe('/v1')
+  })
+
+  test('unknown version returns /<v> fallback', () => {
+    expect(getVersionHomeHref(versioned(), 'v9')).toBe('/v9')
+  })
+})
+
+describe('splitContentButtons', () => {
+  test('all visible when length <= max', () => {
+    expect(splitContentButtons([1, 2, 3], 3)).toEqual({
+      visible: [1, 2, 3],
+      overflow: [],
+    })
+  })
+
+  test('first max visible, rest overflow', () => {
+    expect(splitContentButtons([1, 2, 3, 4, 5], 3)).toEqual({
+      visible: [1, 2, 3],
+      overflow: [4, 5],
+    })
+  })
+
+  test('empty input returns empty arrays', () => {
+    expect(splitContentButtons([], 3)).toEqual({ visible: [], overflow: [] })
+  })
+})

package/src/lib/navigation.ts

@@ -0,0 +1,51 @@
+import type { ChronicleConfig } from '@/types'
+import {
+  getLandingEntries,
+  getLatestContentRoots,
+  getVersionContentRoots,
+} from './config'
+import { resolveVersionFromUrl } from './version-source'
+
+export function getActiveContentDir(
+  url: string,
+  config: ChronicleConfig,
+): string | null {
+  const version = resolveVersionFromUrl(url, config)
+  const parts = url.split('/').filter(Boolean)
+  const remainder =
+    version.dir !== null && parts[0] === version.dir ? parts.slice(1) : parts
+
+  if (remainder.length === 0) return null
+  if (remainder[0] === 'apis') return null
+
+  const dirs =
+    version.dir === null
+      ? getLatestContentRoots(config).map((root) => root.contentDir)
+      : getVersionContentRoots(config, version.dir).map(
+          (root) => root.contentDir,
+        )
+
+  return dirs.includes(remainder[0]) ? remainder[0] : null
+}
+
+export function getVersionHomeHref(
+  config: ChronicleConfig,
+  versionDir: string | null,
+): string {
+  const entries = getLandingEntries(config, versionDir)
+  if (entries.length === 1) return entries[0].href
+  return versionDir ? `/${versionDir}` : '/'
+}
+
+export interface ContentButtonSplit<T> {
+  visible: T[]
+  overflow: T[]
+}
+
+export function splitContentButtons<T>(
+  items: T[],
+  max: number,
+): ContentButtonSplit<T> {
+  if (items.length <= max) return { visible: items, overflow: [] }
+  return { visible: items.slice(0, max), overflow: items.slice(max) }
+}

package/src/lib/page-context.tsx

@@ -7,23 +7,20 @@ import {
 } from 'react';
 import { useLocation } from 'react-router';
 import type { ApiSpec } from '@/lib/openapi';
-import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+import { resolveRoute, RouteType } from '@/lib/route-resolver';
+import type { VersionContext } from '@/lib/version-source';
+import { LATEST_CONTEXT } from '@/lib/version-source';
+import type { ChronicleConfig, Frontmatter, Page, Root, TableOfContents } from '@/types';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
-interface PageData {
-  slug: string[];
-  frontmatter: Frontmatter;
-  content: ReactNode;
-  toc: TableOfContents;
-}
-
 interface PageContextValue {
   config: ChronicleConfig;
   tree: Root;
-  page: PageData | null;
+  page: Page | null;
   errorStatus: number | null;
   apiSpecs: ApiSpec[];
+  version: VersionContext;
 }
 
 const PageContext = createContext<PageContextValue | null>(null);
@@ -33,11 +30,15 @@ export function usePageContext(): PageContextValue {
   if (!ctx) {
     console.error('usePageContext: no context found!');
     return {
-      config: { title: 'Documentation' },
+      config: {
+        site: { title: 'Documentation' },
+        content: [{ dir: 'docs', label: 'Docs' }],
+      },
       tree: { name: 'root', children: [] } as Root,
       page: null,
       errorStatus: null,
-      apiSpecs: []
+      apiSpecs: [],
+      version: LATEST_CONTEXT,
     };
   }
   return ctx;
@@ -46,8 +47,9 @@ export function usePageContext(): PageContextValue {
 interface PageProviderProps {
   initialConfig: ChronicleConfig;
   initialTree: Root;
-  initialPage: PageData | null;
+  initialPage: Page | null;
   initialApiSpecs: ApiSpec[];
+  initialVersion: VersionContext;
   loadMdx: MdxLoader;
   children: ReactNode;
 }
@@ -56,9 +58,12 @@ function isApisRoute(pathname: string): boolean {
   return pathname === '/apis' || pathname.startsWith('/apis/');
 }
 
-function getInitialErrorStatus(page: PageData | null, pathname: string): number | null {
+function getInitialErrorStatus(page: Page | null, config: ChronicleConfig, pathname: string): number | null {
   if (page) return null;
-  if (pathname === '/' || isApisRoute(pathname)) return null;
+  const route = resolveRoute(pathname, config);
+  if (route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage) return null;
+  if (route.type === RouteType.Redirect) return null;
+  if (route.type === RouteType.DocsIndex) return null;
   return 404;
 }
 
@@ -67,39 +72,53 @@ export function PageProvider({
   initialTree,
   initialPage,
   initialApiSpecs,
+  initialVersion,
   loadMdx,
   children
 }: PageProviderProps) {
   const { pathname } = useLocation();
   const [tree] = useState<Root>(initialTree);
-  const [page, setPage] = useState<PageData | null>(initialPage);
-  const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, pathname));
+  const [page, setPage] = useState<Page | null>(initialPage);
+  const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, initialConfig, pathname));
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
+  const [version, setVersion] = useState<VersionContext>(initialVersion);
   const [currentPath, setCurrentPath] = useState(pathname);
 
   useEffect(() => {
     if (pathname === currentPath) return;
     setCurrentPath(pathname);
 
+    const route = resolveRoute(pathname, initialConfig);
+    if (route.type !== RouteType.Redirect) setVersion(route.version);
+
     const cancelled = { current: false };
 
-    if (isApisRoute(pathname)) {
-      if (apiSpecs.length === 0) {
-        fetch('/api/specs')
-          .then(res => res.json())
-          .then(specs => {
-            if (!cancelled.current) setApiSpecs(specs);
-          })
-          .catch(() => {});
-      }
+    if (route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage) {
+      setPage(null);
+      setErrorStatus(null);
+      const specsUrl = route.version.dir
+        ? `/api/specs?version=${encodeURIComponent(route.version.dir)}`
+        : '/api/specs';
+      fetch(specsUrl)
+        .then(res => res.json())
+        .then(specs => {
+          if (!cancelled.current) setApiSpecs(specs);
+        })
+        .catch(() => {
+          // swallow — api specs are best-effort on client nav
+        });
       return () => { cancelled.current = true; };
     }
 
-    const slug = pathname === '/'
-      ? []
-      : pathname.slice(1).split('/').filter(Boolean);
+    if (route.type !== RouteType.DocsPage) {
+      setPage(null);
+      setErrorStatus(null);
+      return () => { cancelled.current = true; };
+    }
 
-    const apiPath = slug.length === 0 ? '/api/page' : `/api/page?slug=${slug.join(',')}`;
+    const apiPath = route.slug.length === 0
+      ? '/api/page'
+      : `/api/page?slug=${route.slug.join(',')}`;
 
     fetch(apiPath)
       .then(res => {
@@ -112,12 +131,12 @@ export function PageProvider({
         }
         return res.json();
       })
-      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string } | undefined) => {
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string; prev?: Page['prev']; next?: Page['next'] } | undefined) => {
         if (cancelled.current || !data) return;
         const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
         if (cancelled.current) return;
         setErrorStatus(null);
-        setPage({ slug, frontmatter: data.frontmatter, content, toc });
+        setPage({ slug: route.slug, frontmatter: data.frontmatter, content, toc, prev: data.prev, next: data.next });
       })
       .catch(() => {
         if (!cancelled.current) {
@@ -131,7 +150,7 @@ export function PageProvider({
 
   return (
     <PageContext.Provider
-      value={{ config: initialConfig, tree, page, errorStatus, apiSpecs }}
+      value={{ config: initialConfig, tree, page, errorStatus, apiSpecs, version }}
     >
       {children}
     </PageContext.Provider>

package/src/lib/route-resolver.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from 'bun:test'
+import { type ChronicleConfig, chronicleConfigSchema } from '@/types'
+import { resolveRoute, RouteType } from './route-resolver'
+import { LATEST_CONTEXT } from './version-source'
+
+function singleContent(): ChronicleConfig {
+  return chronicleConfigSchema.parse({
+    site: { title: 'x' },
+    content: [{ dir: 'docs', label: 'Docs' }],
+  })
+}
+
+function multiContent(): ChronicleConfig {
+  return chronicleConfigSchema.parse({
+    site: { title: 'x' },
+    content: [
+      { dir: 'docs', label: 'Docs' },
+      { dir: 'dev', label: 'Dev' },
+    ],
+    latest: { label: '3.0', landing: true },
+  })
+}
+
+function multiContentNoLanding(): ChronicleConfig {
+  return chronicleConfigSchema.parse({
+    site: { title: 'x' },
+    content: [
+      { dir: 'docs', label: 'Docs' },
+      { dir: 'dev', label: 'Dev' },
+    ],
+  })
+}
+
+function versioned(): ChronicleConfig {
+  return chronicleConfigSchema.parse({
+    site: { title: 'x' },
+    content: [{ dir: 'docs', label: 'Docs' }],
+    latest: { label: '3.0' },
+    versions: [
+      {
+        dir: 'v2',
+        label: '2.0',
+        content: [{ dir: 'docs', label: 'Docs' }],
+      },
+      {
+        dir: 'v1',
+        label: '1.0',
+        landing: true,
+        content: [
+          { dir: 'docs', label: 'Docs' },
+          { dir: 'dev', label: 'Dev' },
+        ],
+      },
+    ],
+  })
+}
+
+describe('resolveRoute — root', () => {
+  test('redirects single-content latest root to /<dir>', () => {
+    expect(resolveRoute('/', singleContent())).toEqual({
+      type: RouteType.Redirect,
+      to: '/docs',
+      status: 302,
+    })
+  })
+
+  test('docs-index for latest root when latest.landing = true', () => {
+    expect(resolveRoute('/', multiContent())).toEqual({
+      type: RouteType.DocsIndex,
+      version: LATEST_CONTEXT,
+    })
+  })
+
+  test('redirect for multi-content latest root when landing is not set', () => {
+    expect(resolveRoute('/', multiContentNoLanding())).toEqual({
+      type: RouteType.Redirect,
+      to: '/docs',
+      status: 302,
+    })
+  })
+
+  test('redirects single-content version root to /<v>/<dir>', () => {
+    expect(resolveRoute('/v2', versioned())).toEqual({
+      type: RouteType.Redirect,
+      to: '/v2/docs',
+      status: 302,
+    })
+  })
+
+  test('docs-index for version root when versions[].landing = true', () => {
+    expect(resolveRoute('/v1', versioned())).toEqual({
+      type: RouteType.DocsIndex,
+      version: { dir: 'v1', urlPrefix: '/v1' },
+    })
+  })
+})
+
+describe('resolveRoute — docs pages', () => {
+  test('latest docs page returns full slug and latest context', () => {
+    expect(resolveRoute('/docs/getting-started', singleContent())).toEqual({
+      type: RouteType.DocsPage,
+      version: LATEST_CONTEXT,
+      slug: ['docs', 'getting-started'],
+    })
+  })
+
+  test('versioned docs page returns full slug and version context', () => {
+    expect(resolveRoute('/v1/dev/intro', versioned())).toEqual({
+      type: RouteType.DocsPage,
+      version: { dir: 'v1', urlPrefix: '/v1' },
+      slug: ['v1', 'dev', 'intro'],
+    })
+  })
+
+  test('unrecognized first segment stays latest (page lookup handles 404)', () => {
+    expect(resolveRoute('/foo/bar', singleContent())).toEqual({
+      type: RouteType.DocsPage,
+      version: LATEST_CONTEXT,
+      slug: ['foo', 'bar'],
+    })
+  })
+})
+
+describe('resolveRoute — APIs', () => {
+  test('latest api index', () => {
+    expect(resolveRoute('/apis', singleContent())).toEqual({
+      type: RouteType.ApiIndex,
+      version: LATEST_CONTEXT,
+    })
+  })
+
+  test('latest api page', () => {
+    expect(resolveRoute('/apis/petstore/getPetById', singleContent())).toEqual({
+      type: RouteType.ApiPage,
+      version: LATEST_CONTEXT,
+      slug: ['petstore', 'getPetById'],
+    })
+  })
+
+  test('versioned api index', () => {
+    expect(resolveRoute('/v1/apis', versioned())).toEqual({
+      type: RouteType.ApiIndex,
+      version: { dir: 'v1', urlPrefix: '/v1' },
+    })
+  })
+
+  test('versioned api page', () => {
+    expect(
+      resolveRoute('/v1/apis/petstore/getPetById', versioned()),
+    ).toEqual({
+      type: RouteType.ApiPage,
+      version: { dir: 'v1', urlPrefix: '/v1' },
+      slug: ['petstore', 'getPetById'],
+    })
+  })
+})
+
+describe('resolveRoute — edge cases', () => {
+  test('trailing slash is normalized', () => {
+    expect(resolveRoute('/v1/', versioned())).toEqual({
+      type: RouteType.DocsIndex,
+      version: { dir: 'v1', urlPrefix: '/v1' },
+    })
+  })
+
+  test('version-shaped path without a matching version stays latest', () => {
+    expect(resolveRoute('/v9/docs', versioned())).toEqual({
+      type: RouteType.DocsPage,
+      version: LATEST_CONTEXT,
+      slug: ['v9', 'docs'],
+    })
+  })
+})

package/src/lib/route-resolver.ts

@@ -0,0 +1,73 @@
+import type { ChronicleConfig } from '@/types'
+import { getLatestContentRoots, getVersionContentRoots } from './config'
+import { type VersionContext, resolveVersionFromUrl } from './version-source'
+
+export const RouteType = {
+  Redirect: 'redirect',
+  DocsIndex: 'docs-index',
+  DocsPage: 'docs-page',
+  ApiIndex: 'api-index',
+  ApiPage: 'api-page',
+} as const
+
+export type RouteType = (typeof RouteType)[keyof typeof RouteType]
+
+export type Route =
+  | { type: typeof RouteType.Redirect; to: string; status: 302 }
+  | { type: typeof RouteType.DocsIndex; version: VersionContext }
+  | { type: typeof RouteType.DocsPage; version: VersionContext; slug: string[] }
+  | { type: typeof RouteType.ApiIndex; version: VersionContext }
+  | { type: typeof RouteType.ApiPage; version: VersionContext; slug: string[] }
+
+function contentDirsFor(
+  config: ChronicleConfig,
+  version: VersionContext,
+): string[] {
+  if (version.dir === null) {
+    return getLatestContentRoots(config).map((root) => root.contentDir)
+  }
+  return getVersionContentRoots(config, version.dir).map(
+    (root) => root.contentDir,
+  )
+}
+
+function isLandingEnabled(
+  config: ChronicleConfig,
+  version: VersionContext,
+): boolean {
+  if (version.dir === null) return config.latest?.landing === true
+  return (
+    config.versions?.find((v) => v.dir === version.dir)?.landing === true
+  )
+}
+
+export function resolveRoute(
+  pathname: string,
+  config: ChronicleConfig,
+): Route {
+  const parts = pathname.split('/').filter(Boolean)
+  const version = resolveVersionFromUrl(pathname, config)
+  const remainder =
+    version.dir !== null && parts[0] === version.dir ? parts.slice(1) : parts
+
+  if (remainder[0] === 'apis') {
+    const slug = remainder.slice(1)
+    if (slug.length === 0) return { type: RouteType.ApiIndex, version }
+    return { type: RouteType.ApiPage, version, slug }
+  }
+
+  if (remainder.length === 0) {
+    if (isLandingEnabled(config, version)) {
+      return { type: RouteType.DocsIndex, version }
+    }
+    const dirs = contentDirsFor(config, version)
+    if (dirs.length === 0) return { type: RouteType.DocsIndex, version }
+    return {
+      type: RouteType.Redirect,
+      to: `${version.urlPrefix}/${dirs[0]}`,
+      status: 302,
+    }
+  }
+
+  return { type: RouteType.DocsPage, version, slug: parts }
+}