@raystack/chronicle 0.1.0-canary.5a2be79

package/src/lib/api-routes.ts

@@ -0,0 +1,120 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import slugify from 'slugify'
+import type { PageTree, PageTreeItem } from '@/types/content'
+import type { ApiSpec } from './openapi'
+
+export function getSpecSlug(spec: ApiSpec): string {
+  return slugify(spec.name, { lower: true, strict: true })
+}
+
+
+export function buildApiRoutes(specs: ApiSpec[]): { slug: string[] }[] {
+  const routes: { slug: string[] }[] = []
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op?.operationId) continue
+        routes.push({ slug: [specSlug, encodeURIComponent(op.operationId)] })
+      }
+    }
+  }
+
+  return routes
+}
+
+export interface ApiRouteMatch {
+  spec: ApiSpec
+  operation: OpenAPIV3.OperationObject
+  method: string
+  path: string
+}
+
+export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatch | null {
+  if (slug.length !== 2) return null
+  const [specSlug, operationId] = slug
+
+  const spec = specs.find((s) => getSpecSlug(s) === specSlug)
+  if (!spec) return null
+
+  const paths = spec.document.paths ?? {}
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem) continue
+    for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+      const op = pathItem[method]
+      if (op?.operationId && encodeURIComponent(op.operationId) === operationId) {
+        return { spec, operation: op, method: method.toUpperCase(), path: pathStr }
+      }
+    }
+  }
+
+  return null
+}
+
+export function buildApiPageTree(specs: ApiSpec[]): PageTree {
+  const children: PageTreeItem[] = []
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+    const tags = spec.document.tags ?? []
+
+    // Group operations by tag (case-insensitive to avoid duplicates)
+    const opsByTag = new Map<string, PageTreeItem[]>()
+    const tagDisplayName = new Map<string, string>()
+
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op?.operationId) continue
+
+        const rawTag = op.tags?.[0] ?? 'default'
+        const tagKey = rawTag.toLowerCase()
+        if (!opsByTag.has(tagKey)) {
+          opsByTag.set(tagKey, [])
+          tagDisplayName.set(tagKey, rawTag.charAt(0).toUpperCase() + rawTag.slice(1))
+        }
+
+        opsByTag.get(tagKey)!.push({
+          type: 'page',
+          name: op.summary ?? op.operationId,
+          url: `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`,
+          icon: `method-${method}`,
+        })
+      }
+    }
+
+    // Use doc.tags display names where available
+    for (const t of tags) {
+      const key = t.name.toLowerCase()
+      if (opsByTag.has(key)) {
+        tagDisplayName.set(key, t.name.charAt(0).toUpperCase() + t.name.slice(1))
+      }
+    }
+
+    const tagFolders: PageTreeItem[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
+      type: 'folder' as const,
+      name: tagDisplayName.get(key) ?? key,
+      icon: 'rectangle-stack',
+      children: ops,
+    }))
+
+    if (specs.length > 1) {
+      children.push({
+        type: 'folder',
+        name: spec.name,
+        children: tagFolders,
+      })
+    } else {
+      children.push(...tagFolders)
+    }
+  }
+
+  return { name: 'API Reference', children }
+}

package/src/lib/config.ts

@@ -0,0 +1,55 @@
+import fs from 'fs'
+import path from 'path'
+import { parse } from 'yaml'
+import type { ChronicleConfig } from '@/types'
+
+const CONFIG_FILE = 'chronicle.yaml'
+
+const defaultConfig: ChronicleConfig = {
+  title: 'Documentation',
+  theme: { name: 'default' },
+  search: { enabled: true, placeholder: 'Search...' },
+}
+
+function resolveConfigPath(): string | null {
+  // Check project root via env var
+  const projectRoot = process.env.CHRONICLE_PROJECT_ROOT
+  if (projectRoot) {
+    const rootPath = path.join(projectRoot, CONFIG_FILE)
+    if (fs.existsSync(rootPath)) return rootPath
+  }
+  // Check cwd
+  const cwdPath = path.join(process.cwd(), CONFIG_FILE)
+  if (fs.existsSync(cwdPath)) return cwdPath
+  // Check content dir
+  const contentDir = process.env.CHRONICLE_CONTENT_DIR
+  if (contentDir) {
+    const contentPath = path.join(contentDir, CONFIG_FILE)
+    if (fs.existsSync(contentPath)) return contentPath
+  }
+  return null
+}
+
+export function loadConfig(): ChronicleConfig {
+  const configPath = resolveConfigPath()
+
+  if (!configPath) {
+    return defaultConfig
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf-8')
+  const userConfig = parse(raw) as Partial<ChronicleConfig>
+
+  return {
+    ...defaultConfig,
+    ...userConfig,
+    theme: {
+      name: userConfig.theme?.name ?? defaultConfig.theme!.name,
+      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors },
+    },
+    search: { ...defaultConfig.search, ...userConfig.search },
+    footer: userConfig.footer,
+    api: userConfig.api,
+    llms: { enabled: false, ...userConfig.llms },
+  }
+}

package/src/lib/get-llm-text.ts

@@ -0,0 +1,10 @@
+import { source } from '@/lib/source'
+import type { InferPageType } from 'fumadocs-core/source'
+
+export async function getLLMText(page: InferPageType<typeof source>) {
+  const processed = await page.data.getText('processed')
+
+  return `# ${page.data.title} (${page.url})
+
+${processed}`
+}

package/src/lib/index.ts

@@ -0,0 +1,2 @@
+export * from './config'
+export * from './source'

package/src/lib/openapi.ts

@@ -0,0 +1,188 @@
+import fs from 'fs'
+import path from 'path'
+import { parse as parseYaml } from 'yaml'
+import type { OpenAPIV2, OpenAPIV3 } from 'openapi-types'
+import type { ApiConfig, ApiServerConfig, ApiAuthConfig } from '@/types/config'
+
+type JsonObject = Record<string, unknown>
+
+export interface ApiSpec {
+  name: string
+  basePath: string
+  server: ApiServerConfig
+  auth?: ApiAuthConfig
+  document: OpenAPIV3.Document
+}
+
+export type { SchemaField } from './schema'
+export { flattenSchema } from './schema'
+
+export function loadApiSpecs(apiConfigs: ApiConfig[]): ApiSpec[] {
+  const contentDir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd()
+  return apiConfigs.map((config) => loadApiSpec(config, contentDir))
+}
+
+export function loadApiSpec(config: ApiConfig, contentDir: string): ApiSpec {
+  const specPath = path.resolve(contentDir, config.spec)
+  const raw = fs.readFileSync(specPath, 'utf-8')
+  const isYaml = specPath.endsWith('.yaml') || specPath.endsWith('.yml')
+  const doc = (isYaml ? parseYaml(raw) : JSON.parse(raw)) as OpenAPIV2.Document | OpenAPIV3.Document
+
+  let v3Doc: OpenAPIV3.Document
+
+  if ('swagger' in doc && doc.swagger === '2.0') {
+    v3Doc = convertV2toV3(doc as OpenAPIV2.Document)
+  } else if ('openapi' in doc && doc.openapi.startsWith('3.')) {
+    v3Doc = resolveDocument(doc as OpenAPIV3.Document)
+  } else {
+    throw new Error(`Unsupported spec version in ${config.spec}`)
+  }
+
+  return {
+    name: config.name,
+    basePath: config.basePath,
+    server: config.server,
+    auth: config.auth,
+    document: v3Doc,
+  }
+}
+
+// --- $ref resolution ---
+
+function resolveRef(ref: string, root: JsonObject): JsonObject {
+  const parts = ref.replace(/^#\//, '').split('/')
+  let current: unknown = root
+  for (const part of parts) {
+    if (current && typeof current === 'object' && !Array.isArray(current)) {
+      current = (current as JsonObject)[part]
+    } else {
+      throw new Error(`Cannot resolve $ref: ${ref}`)
+    }
+  }
+  return current as JsonObject
+}
+
+function deepResolveRefs(
+  obj: unknown,
+  root: JsonObject,
+  stack = new Set<string>(),
+  cache = new Map<string, JsonObject>(),
+): unknown {
+  if (obj === null || obj === undefined || typeof obj !== 'object') return obj
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => deepResolveRefs(item, root, stack, cache))
+  }
+
+  const record = obj as JsonObject
+
+  if (typeof record.$ref === 'string') {
+    const ref = record.$ref
+    if (cache.has(ref)) return cache.get(ref) as JsonObject
+    if (stack.has(ref)) return { type: 'object', description: '[circular]' }
+    stack.add(ref)
+    const resolved = deepResolveRefs(resolveRef(ref, root), root, stack, cache) as JsonObject
+    stack.delete(ref)
+    cache.set(ref, resolved)
+    return resolved
+  }
+
+  const result: JsonObject = {}
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = deepResolveRefs(value, root, stack, cache)
+  }
+  return result
+}
+
+function resolveDocument(doc: OpenAPIV3.Document): OpenAPIV3.Document {
+  const root = doc as unknown as JsonObject
+  return deepResolveRefs(doc, root) as unknown as OpenAPIV3.Document
+}
+
+// --- V2 → V3 conversion ---
+
+function convertV2toV3(doc: OpenAPIV2.Document): OpenAPIV3.Document {
+  const root = doc as unknown as JsonObject
+  const resolved = deepResolveRefs(doc, root) as unknown as OpenAPIV2.Document
+
+  const v3Paths: OpenAPIV3.PathsObject = {}
+
+  for (const [pathStr, pathItem] of Object.entries(resolved.paths ?? {})) {
+    if (!pathItem) continue
+    const v3PathItem: OpenAPIV3.PathItemObject = {}
+
+    for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+      const op = (pathItem as Record<string, unknown>)[method] as OpenAPIV2.OperationObject | undefined
+      if (!op) continue
+      v3PathItem[method] = convertV2Operation(op)
+    }
+
+    v3Paths[pathStr] = v3PathItem
+  }
+
+  return {
+    openapi: '3.0.0',
+    info: resolved.info as unknown as OpenAPIV3.InfoObject,
+    paths: v3Paths,
+    tags: (resolved.tags ?? []) as unknown as OpenAPIV3.TagObject[],
+  }
+}
+
+function convertV2Operation(op: OpenAPIV2.OperationObject): OpenAPIV3.OperationObject {
+  const params = (op.parameters ?? []) as OpenAPIV2.Parameter[]
+
+  const v3Params: OpenAPIV3.ParameterObject[] = params
+    .filter((p) => p.in !== 'body')
+    .map((p) => ({
+      name: p.name,
+      in: p.in as 'path' | 'query' | 'header' | 'cookie',
+      required: p.required ?? false,
+      description: p.description,
+      schema: { type: ((p as JsonObject).type as string) ?? 'string', format: (p as JsonObject).format as string | undefined } as OpenAPIV3.SchemaObject,
+    }))
+
+  const bodyParam = params.find((p) => p.in === 'body') as JsonObject | undefined
+  let requestBody: OpenAPIV3.RequestBodyObject | undefined
+  if (bodyParam?.schema) {
+    requestBody = {
+      required: (bodyParam.required as boolean) ?? false,
+      content: {
+        'application/json': {
+          schema: bodyParam.schema as OpenAPIV3.SchemaObject,
+        },
+      },
+    }
+  }
+
+  const v3Responses: OpenAPIV3.ResponsesObject = {}
+  for (const [status, resp] of Object.entries(op.responses ?? {})) {
+    const v2Resp = resp as OpenAPIV2.ResponseObject
+    const v3Resp: OpenAPIV3.ResponseObject = {
+      description: v2Resp.description ?? '',
+    }
+    if ((v2Resp as unknown as JsonObject).schema) {
+      v3Resp.content = {
+        'application/json': {
+          schema: (v2Resp as unknown as JsonObject).schema as OpenAPIV3.SchemaObject,
+        },
+      }
+    }
+    v3Responses[status] = v3Resp
+  }
+
+  const result: OpenAPIV3.OperationObject = {
+    operationId: op.operationId,
+    summary: op.summary,
+    description: op.description,
+    tags: op.tags,
+    parameters: v3Params,
+    responses: v3Responses,
+  }
+
+  if (requestBody) {
+    result.requestBody = requestBody
+  }
+
+  return result
+}
+

package/src/lib/remark-unused-directives.ts

@@ -0,0 +1,30 @@
+import { visit } from 'unist-util-visit'
+import type { Plugin } from 'unified'
+import type { Node } from 'unist'
+
+const remarkUnusedDirectives: Plugin = () => {
+  return (tree) => {
+    visit(tree, ['textDirective'], (node) => {
+      const directive = node as Node & {
+        name?: string
+        attributes?: Record<string, string>
+        children?: Node[]
+        value?: string
+        [key: string]: unknown
+      }
+      if (!directive.data) {
+        const hasAttributes = directive.attributes && Object.keys(directive.attributes).length > 0
+        const hasChildren = directive.children && directive.children.length > 0
+        if (!hasAttributes && !hasChildren) {
+          const name = directive.name
+          if (!name) return
+          Object.keys(directive).forEach((key) => delete directive[key])
+          directive.type = 'text'
+          directive.value = `:${name}`
+        }
+      }
+    })
+  }
+}
+
+export default remarkUnusedDirectives

package/src/lib/schema.ts

@@ -0,0 +1,99 @@
+import type { OpenAPIV3 } from 'openapi-types'
+
+export interface SchemaField {
+  name: string
+  type: string
+  required: boolean
+  description?: string
+  default?: unknown
+  enum?: unknown[]
+  children?: SchemaField[]
+}
+
+export function flattenSchema(
+  schema: OpenAPIV3.SchemaObject,
+  requiredFields: string[] = [],
+): SchemaField[] {
+  if (schema.type === 'array' && schema.items) {
+    const items = schema.items as OpenAPIV3.SchemaObject
+    const itemType = inferType(items)
+    const children =
+      itemType === 'object' || items.properties
+        ? flattenSchema(items, items.required ?? [])
+        : itemType.endsWith('[]') && (items as OpenAPIV3.ArraySchemaObject).items
+          ? flattenSchema((items as OpenAPIV3.ArraySchemaObject).items as OpenAPIV3.SchemaObject)
+          : undefined
+    return [{
+      name: 'items',
+      type: `${itemType}[]`,
+      required: true,
+      description: items.description,
+      children: children?.length ? children : undefined,
+    }]
+  }
+
+  if (schema.type === 'object' || schema.properties) {
+    const properties = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>
+    const required = schema.required ?? requiredFields
+
+    return Object.entries(properties).map(([name, prop]) => {
+      const fieldType = inferType(prop)
+      const children =
+        fieldType === 'object' || prop.properties
+          ? flattenSchema(prop, prop.required)
+          : fieldType.endsWith('[]') && (prop as OpenAPIV3.ArraySchemaObject).items
+            ? flattenSchema((prop as OpenAPIV3.ArraySchemaObject).items as OpenAPIV3.SchemaObject)
+            : undefined
+
+      return {
+        name,
+        type: fieldType,
+        required: required.includes(name),
+        description: prop.description,
+        default: prop.default,
+        enum: prop.enum,
+        children: children?.length ? children : undefined,
+      }
+    })
+  }
+
+  return []
+}
+
+export function generateExampleJson(schema: OpenAPIV3.SchemaObject): unknown {
+  if (schema.example !== undefined) return schema.example
+  if (schema.default !== undefined) return schema.default
+
+  if (schema.type === 'array') {
+    const items = schema.items as OpenAPIV3.SchemaObject | undefined
+    return items ? [generateExampleJson(items)] : []
+  }
+
+  if (schema.type === 'object' || schema.properties) {
+    const properties = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>
+    const result: Record<string, unknown> = {}
+    for (const [name, prop] of Object.entries(properties)) {
+      result[name] = generateExampleJson(prop)
+    }
+    return result
+  }
+
+  const defaults: Record<string, unknown> = {
+    string: 'string',
+    integer: 0,
+    number: 0,
+    boolean: true,
+  }
+  return defaults[schema.type as string] ?? null
+}
+
+function inferType(schema: OpenAPIV3.SchemaObject): string {
+  if (schema.type === 'array') {
+    const items = schema.items as OpenAPIV3.SchemaObject | undefined
+    const itemType = items ? inferType(items) : 'unknown'
+    return `${itemType}[]`
+  }
+
+  if (schema.format) return `${schema.type}(${schema.format})`
+  return (schema.type as string) ?? 'object'
+}

package/src/lib/snippet-generators.ts

@@ -0,0 +1,87 @@
+interface SnippetOptions {
+  method: string
+  url: string
+  headers: Record<string, string>
+  body?: string
+}
+
+export function generateCurl({ method, url, headers, body }: SnippetOptions): string {
+  const parts = [`curl -X ${method} '${url}'`]
+  for (const [key, value] of Object.entries(headers)) {
+    parts.push(`  -H '${key}: ${value}'`)
+  }
+  if (body) {
+    parts.push(`  -d '${body}'`)
+  }
+  return parts.join(' \\\n')
+}
+
+export function generatePython({ method, url, headers, body }: SnippetOptions): string {
+  const lines: string[] = ['import requests', '']
+  const methodLower = method.toLowerCase()
+  const headerEntries = Object.entries(headers)
+
+  lines.push(`response = requests.${methodLower}(`)
+  lines.push(`    "${url}",`)
+
+  if (headerEntries.length > 0) {
+    lines.push('    headers={')
+    for (const [key, value] of headerEntries) {
+      lines.push(`        "${key}": "${value}",`)
+    }
+    lines.push('    },')
+  }
+
+  if (body) {
+    lines.push(`    json=${body},`)
+  }
+
+  lines.push(')')
+  lines.push('print(response.json())')
+  return lines.join('\n')
+}
+
+export function generateGo({ method, url, headers, body }: SnippetOptions): string {
+  const lines: string[] = []
+
+  if (body) {
+    lines.push('payload := strings.NewReader(`' + body + '`)')
+    lines.push('')
+    lines.push(`req, _ := http.NewRequest("${method}", "${url}", payload)`)
+  } else {
+    lines.push(`req, _ := http.NewRequest("${method}", "${url}", nil)`)
+  }
+
+  for (const [key, value] of Object.entries(headers)) {
+    lines.push(`req.Header.Set("${key}", "${value}")`)
+  }
+
+  lines.push('')
+  lines.push('resp, _ := http.DefaultClient.Do(req)')
+  lines.push('defer resp.Body.Close()')
+  return lines.join('\n')
+}
+
+export function generateTypeScript({ method, url, headers, body }: SnippetOptions): string {
+  const lines: string[] = []
+  const headerEntries = Object.entries(headers)
+
+  lines.push(`const response = await fetch("${url}", {`)
+  lines.push(`  method: "${method}",`)
+
+  if (headerEntries.length > 0) {
+    lines.push('  headers: {')
+    for (const [key, value] of headerEntries) {
+      lines.push(`    "${key}": "${value}",`)
+    }
+    lines.push('  },')
+  }
+
+  if (body) {
+    lines.push(`  body: JSON.stringify(${body}),`)
+  }
+
+  lines.push('});')
+  lines.push('const data = await response.json();')
+  return lines.join('\n')
+}

package/src/lib/source.ts

@@ -0,0 +1,67 @@
+import { docs } from '@/.source/server'
+import { loader } from 'fumadocs-core/source'
+import type { PageTree, PageTreeItem, Frontmatter } from '@/types'
+
+export const source = loader({
+  baseUrl: '/',
+  source: docs.toFumadocsSource(),
+})
+
+export function sortByOrder<T extends { frontmatter?: Frontmatter }>(
+  items: T[]
+): T[] {
+  return [...items].sort((a, b) => {
+    const orderA = a.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
+    const orderB = b.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
+    return orderA - orderB
+  })
+}
+
+export function buildPageTree(): PageTree {
+  const pages = source.getPages()
+  const folders = new Map<string, PageTreeItem[]>()
+  const rootPages: PageTreeItem[] = []
+
+  pages.forEach((page) => {
+    const data = page.data as { title?: string; order?: number }
+    const isIndex = page.url === '/'
+    const item: PageTreeItem = {
+      type: 'page',
+      name: data.title ?? page.slugs.join('/') ?? 'Untitled',
+      url: page.url,
+      order: data.order ?? (isIndex ? 0 : undefined),
+    }
+
+    if (page.slugs.length > 1) {
+      const folder = page.slugs[0]
+      if (!folders.has(folder)) {
+        folders.set(folder, [])
+      }
+      folders.get(folder)?.push(item)
+    } else {
+      rootPages.push(item)
+    }
+  })
+
+  const sortByOrder = (items: PageTreeItem[]) =>
+    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+
+  const children: PageTreeItem[] = sortByOrder(rootPages)
+
+  const folderItems: PageTreeItem[] = []
+  folders.forEach((items, folder) => {
+    const sorted = sortByOrder(items)
+    const indexPage = items.find(item => item.url === `/${folder}`)
+    const folderOrder = indexPage?.order ?? sorted[0]?.order
+    folderItems.push({
+      type: 'folder',
+      name: folder.charAt(0).toUpperCase() + folder.slice(1),
+      order: folderOrder,
+      children: sorted,
+    })
+  })
+
+  children.push(...sortByOrder(folderItems))
+
+  return { name: 'root', children }
+}