@raystack/chronicle 0.1.0-canary.111b55a

package/src/lib/config.ts

@@ -0,0 +1,56 @@
+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 },
+    analytics: { enabled: false, ...userConfig.analytics },
+  }
+}

package/src/lib/head.tsx

@@ -0,0 +1,45 @@
+import type { ChronicleConfig } from '@/types'
+
+export interface HeadProps {
+  title: string
+  description?: string
+  config: ChronicleConfig
+  jsonLd?: Record<string, unknown>
+}
+
+export function Head({ title, description, config, jsonLd }: HeadProps) {
+  const fullTitle = `${title} | ${config.title}`
+  const ogParams = new URLSearchParams({ title })
+  if (description) ogParams.set('description', description)
+
+  return (
+    <>
+      <title>{fullTitle}</title>
+      {description && <meta name="description" content={description} />}
+
+      {config.url && (
+        <>
+          <meta property="og:title" content={title} />
+          {description && <meta property="og:description" content={description} />}
+          <meta property="og:site_name" content={config.title} />
+          <meta property="og:type" content="website" />
+          <meta property="og:image" content={`/og?${ogParams.toString()}`} />
+          <meta property="og:image:width" content="1200" />
+          <meta property="og:image:height" content="630" />
+
+          <meta name="twitter:card" content="summary_large_image" />
+          <meta name="twitter:title" content={title} />
+          {description && <meta name="twitter:description" content={description} />}
+          <meta name="twitter:image" content={`/og?${ogParams.toString()}`} />
+        </>
+      )}
+
+      {jsonLd && (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd, null, 2) }}
+        />
+      )}
+    </>
+  )
+}

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/page-context.tsx

@@ -0,0 +1,95 @@
+import { createContext, useContext, useState, useEffect, type ReactNode } from 'react'
+import { useLocation } from 'react-router-dom'
+import type { ChronicleConfig, Frontmatter, PageTree } from '@/types'
+import type { ApiSpec } from '@/lib/openapi'
+import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
+import { mdxComponents } from '@/components/mdx'
+import React from 'react'
+
+interface PageData {
+  slug: string[]
+  frontmatter: Frontmatter
+  content: ReactNode
+}
+
+interface PageContextValue {
+  config: ChronicleConfig
+  tree: PageTree
+  page: PageData | null
+  apiSpecs: ApiSpec[]
+}
+
+const PageContext = createContext<PageContextValue | null>(null)
+
+export function usePageContext(): PageContextValue {
+  const ctx = useContext(PageContext)
+  if (!ctx) {
+    console.error('usePageContext: no context found!')
+    return {
+      config: { title: 'Documentation' },
+      tree: { name: 'root', children: [] },
+      page: null,
+      apiSpecs: [],
+    }
+  }
+  return ctx
+}
+
+interface PageProviderProps {
+  initialConfig: ChronicleConfig
+  initialTree: PageTree
+  initialPage: PageData | null
+  initialApiSpecs: ApiSpec[]
+  children: ReactNode
+}
+
+export function PageProvider({ initialConfig, initialTree, initialPage, initialApiSpecs, children }: PageProviderProps) {
+  const { pathname } = useLocation()
+  const [tree, setTree] = useState<PageTree>(initialTree)
+  const [page, setPage] = useState<PageData | null>(initialPage)
+  const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs)
+  const [currentPath, setCurrentPath] = useState(pathname)
+
+  useEffect(() => {
+    if (pathname === currentPath) return
+    setCurrentPath(pathname)
+
+    let cancelled = false
+
+    if (pathname.startsWith('/apis')) {
+      // Fetch API specs if not already loaded
+      if (apiSpecs.length === 0) {
+        fetch('/api/specs')
+          .then((res) => res.json())
+          .then((specs) => { if (!cancelled) setApiSpecs(specs) })
+          .catch(() => {})
+      }
+      return () => { cancelled = true }
+    }
+
+    async function load() {
+      const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
+
+      const [sourcePage, newTree] = await Promise.all([getPage(slug), buildPageTree()])
+      if (cancelled || !sourcePage) return
+
+      const component = await loadPageComponent(sourcePage)
+      if (cancelled) return
+
+      setTree(newTree)
+      setPage({
+        slug,
+        frontmatter: sourcePage.frontmatter,
+        content: component ? React.createElement(component, { components: mdxComponents }) : null,
+      })
+    }
+    load()
+    return () => { cancelled = true }
+  }, [pathname])
+
+  return (
+    <PageContext.Provider value={{ config: initialConfig, tree, page, apiSpecs }}>
+      {children}
+    </PageContext.Provider>
+  )
+}

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')
+}