@tiramisu-docs/kit 0.1.0

package/src/vite.ts

@@ -0,0 +1,478 @@
+import { compileTiramisu } from "@tiramisu-docs/core"
+import type { DocMeta, Heading } from "@tiramisu-docs/core"
+import { execSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import type { Plugin, ResolvedConfig as ViteConfig, HmrContext } from "vite"
+import { highlightCodeBlocks } from "./highlight.js"
+import type { SectionConfig, TiramisuDocsConfig } from "./config.js"
+import { findTiramisuFiles, extractPlainText, titleCase } from "./scan.js"
+import type { SidebarItem, SidebarSubgroup, SidebarEntry, SidebarGroup, ResolvedSection } from "./types.js"
+
+export type { SidebarItem, SidebarSubgroup, SidebarEntry, SidebarGroup, ResolvedSection } from "./types.js"
+
+/** Wrap compileTiramisu to produce Vite-friendly errors with file location */
+function compileWithLocation(source: string, filePath: string) {
+  const dir = path.dirname(filePath)
+  try {
+    return compileTiramisu(source, {
+      resolveFile(src) {
+        const resolved = path.resolve(dir, src)
+        return fs.readFileSync(resolved, "utf-8")
+      },
+    })
+  } catch (err: unknown) {
+    const isParseError = err instanceof Error && "line" in err
+    if (isParseError) {
+      const parseErr = err as Error & { line: number; column?: number; hint?: string }
+      const enhanced = new Error(parseErr.hint ?? parseErr.message)
+      Object.assign(enhanced, {
+        id: filePath,
+        loc: { file: filePath, line: parseErr.line, column: parseErr.column ?? 0 },
+        plugin: "tiramisu-docs",
+      })
+      if (parseErr.stack) enhanced.stack = parseErr.stack
+      throw enhanced
+    }
+    throw err
+  }
+}
+
+export interface TiramisuPluginOptions {
+  docsDir?: string
+  config?: TiramisuDocsConfig
+}
+
+
+function resolveLastEdited(filePath: string, meta: DocMeta): string {
+  if (meta.lastEdited) return new Date(meta.lastEdited).toISOString()
+  try {
+    const stdout = execSync(`git log -1 --format=%cI "${filePath}"`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim()
+    if (stdout) return new Date(stdout).toISOString()
+  } catch {}
+  return fs.statSync(filePath).mtime.toISOString()
+}
+
+const VIRTUAL_MODULE_ID = "virtual:tiramisu-docs"
+const RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID
+const TIRAMISU_SVELTE_SUFFIX = ".tiramisu.svelte"
+
+export function buildSidebarTree(
+  docs: { slug: string; meta: DocMeta }[],
+  groupOrder: string[] = []
+): SidebarGroup[] {
+  const groupMap = new Map<string, { label: string; items: SidebarEntry[]; icon?: string }>()
+
+  function getOrCreateGroup(label: string): { label: string; items: SidebarEntry[]; icon?: string } {
+    // Normalize lookup: case-insensitive match against existing groups
+    for (const [key, group] of groupMap) {
+      if (key.toLowerCase() === label.toLowerCase()) {
+        return group
+      }
+    }
+    const group = { label, items: [] as SidebarEntry[] }
+    groupMap.set(label, group)
+    return group
+  }
+
+  function getOrCreateSubgroup(
+    parent: SidebarEntry[],
+    segment: string
+  ): SidebarSubgroup {
+    const key = segment.toLowerCase()
+    const existing = parent.find(
+      (e): e is SidebarSubgroup =>
+        e.type === "subgroup" && e.key === key
+    )
+    if (existing) return existing
+    const sub: SidebarSubgroup = {
+      type: "subgroup",
+      key,
+      label: titleCase(segment),
+      items: [],
+      order: 999,
+    }
+    parent.push(sub)
+    return sub
+  }
+
+  for (const doc of docs) {
+    const segments = doc.slug.split("/")
+    const item: SidebarItem = {
+      type: "item",
+      title: doc.meta.title ?? doc.slug,
+      slug: doc.slug,
+      order: doc.meta.order ?? 999,
+      icon: doc.meta.icon,
+    }
+
+    if (segments.length === 1) {
+      // Root-level file: use meta.group
+      const groupLabel = doc.meta.group ?? "Docs"
+      const group = getOrCreateGroup(groupLabel)
+      group.items.push(item)
+    } else {
+      // Nested file: first segment = group (static heading), deeper segments = subgroups
+      const groupLabel = titleCase(segments[0])
+      const group = getOrCreateGroup(groupLabel)
+      const fileName = segments[segments.length - 1]
+
+      // Walk/create subgroups for middle segments (starting at segments[1])
+      let parent = group.items
+      let lastSub: SidebarSubgroup | null = null
+      for (let i = 1; i < segments.length - 1; i++) {
+        const sub = getOrCreateSubgroup(parent, segments[i])
+        lastSub = sub
+        parent = sub.items
+      }
+
+      if (fileName === "index" && lastSub) {
+        // Deeper folder index → sets subgroup slug/label
+        lastSub.slug = item.slug
+        if (item.order < lastSub.order) lastSub.order = item.order
+        if (item.title !== item.slug) lastSub.label = item.title
+        if (doc.meta.icon) lastSub.icon = doc.meta.icon
+      } else if (fileName === "index" && !lastSub) {
+        // Top-level folder index (e.g. "integrations/index") → sets group label only
+        if (item.title !== item.slug) {
+          group.label = item.title
+        }
+        if (doc.meta.icon) group.icon = doc.meta.icon
+      } else {
+        parent.push(item)
+      }
+    }
+  }
+
+  // Sort entries recursively
+  function sortEntries(entries: SidebarEntry[]): void {
+    for (const entry of entries) {
+      if (entry.type === "subgroup") {
+        sortEntries(entry.items)
+        // Derive subgroup order from its index page, or min child order
+        if (!entry.slug) {
+          const minOrder = entry.items.reduce((min, e) => {
+            const o = e.order
+            return o < min ? o : min
+          }, entry.order)
+          entry.order = minOrder
+        }
+      }
+    }
+    entries.sort((a, b) => {
+      const ao = a.type === "item" ? a.order : a.order
+      const bo = b.type === "item" ? b.order : b.order
+      return ao - bo
+    })
+  }
+
+  const sidebar: SidebarGroup[] = []
+  for (const [, group] of groupMap) {
+    sortEntries(group.items)
+    sidebar.push({ label: group.label, items: group.items, icon: group.icon })
+  }
+
+  // Sort groups by groupOrder config
+  if (groupOrder.length > 0) {
+    sidebar.sort((a, b) => {
+      const ai = groupOrder.indexOf(a.label)
+      const bi = groupOrder.indexOf(b.label)
+      const ao = ai === -1 ? Infinity : ai
+      const bo = bi === -1 ? Infinity : bi
+      return ao - bo
+    })
+  }
+
+  return sidebar
+}
+
+
+export function buildSectionSidebars(
+  docs: { slug: string; meta: DocMeta }[],
+  sections: SectionConfig[],
+  implicitLabel?: string
+): ResolvedSection[] {
+  const allSectionPaths = flattenSectionPaths(sections)
+  const rootDocs = docs.filter(
+    (d) => !allSectionPaths.some((p) => d.slug === p || d.slug.startsWith(p + "/"))
+  )
+
+  const result: ResolvedSection[] = []
+
+  if (rootDocs.length > 0) {
+    result.push({
+      label: implicitLabel ?? "Docs",
+      sidebar: buildSidebarTree(rootDocs),
+    })
+  }
+
+  for (const section of sections) {
+    result.push(resolveSection(docs, section))
+  }
+
+  return result
+}
+
+function flattenSectionPaths(sections: SectionConfig[]): string[] {
+  const paths: string[] = []
+  for (const s of sections) {
+    if (s.path) paths.push(s.path)
+    if (s.children) paths.push(...flattenSectionPaths(s.children))
+  }
+  return paths
+}
+
+function resolveSection(
+  docs: { slug: string; meta: DocMeta }[],
+  section: SectionConfig
+): ResolvedSection {
+  if (section.href) {
+    return { label: section.label, href: section.href, icon: section.icon }
+  }
+  if (section.children) {
+    return {
+      label: section.label,
+      icon: section.icon,
+      children: section.children.map((c) => resolveSection(docs, c)),
+    }
+  }
+  const sectionDocs = docs
+    .filter((d) => d.slug === section.path || d.slug.startsWith(section.path + "/"))
+
+  const sidebar = buildSidebarTree(sectionDocs)
+
+  return {
+    label: section.label,
+    path: section.path,
+    icon: section.icon,
+    sidebar,
+  }
+}
+
+export function buildLocaleData(
+  allDocs: { slug: string; meta: DocMeta; headings: Heading[]; lastEdited: string }[],
+  locales: { code: string }[]
+): Record<string, { docs: { slug: string; meta: DocMeta; headings: Heading[]; lastEdited: string }[] }> {
+  const result: Record<string, { docs: { slug: string; meta: DocMeta; headings: Heading[]; lastEdited: string }[] }> = {}
+  for (const locale of locales) {
+    const prefix = locale.code + "/"
+    const docs = allDocs
+      .filter((d) => d.slug.startsWith(prefix))
+      .map((d) => ({ slug: d.slug.slice(prefix.length), meta: d.meta, headings: d.headings, lastEdited: d.lastEdited }))
+    result[locale.code] = { docs }
+  }
+  return result
+}
+
+export function tiramisuPlugin(options: TiramisuPluginOptions = {}): Plugin {
+  const docsDir = options.docsDir ?? "src/docs"
+  const config = options.config
+  const groupOrder = config?.sidebar?.groupOrder ?? []
+  let viteRoot = process.cwd()
+
+  function resolveDocsDir(): string {
+    return path.resolve(viteRoot, docsDir)
+  }
+
+  function buildVirtualModule(): string {
+    const absDocsDir = resolveDocsDir()
+    const files = findTiramisuFiles(absDocsDir)
+
+    const docs: { slug: string; meta: DocMeta; headings: Heading[]; lastEdited: string }[] = []
+
+    for (const file of files) {
+      const source = fs.readFileSync(file, "utf-8")
+      const { meta, headings } = compileWithLocation(source, file)
+      const relativePath = path.relative(absDocsDir, file)
+      const slug = relativePath.replace(/\.tiramisu$/, "").replace(/\\/g, "/")
+      const lastEdited = resolveLastEdited(file, meta)
+      docs.push({ slug, meta, headings, lastEdited })
+    }
+
+    // Build search index with hierarchical group paths
+    function resolveSearchGroup(slug: string, meta: DocMeta): string {
+      const segments = slug.split("/")
+      if (segments.length === 1) return meta.group ?? "Docs"
+      return segments
+        .slice(0, -1)
+        .map(titleCase)
+        .join(" > ")
+    }
+
+    const searchIndex = docs.map((doc) => {
+      const file = path.resolve(absDocsDir, doc.slug + ".tiramisu")
+      const source = fs.readFileSync(file, "utf-8")
+      const { svelte } = compileWithLocation(source, file)
+      const text = extractPlainText(svelte)
+      return {
+        id: doc.slug,
+        title: doc.meta.title ?? doc.slug,
+        group: resolveSearchGroup(doc.slug, doc.meta),
+        slug: doc.slug,
+        headings: doc.headings.map((h) => h.text).join(" "),
+        text,
+      }
+    })
+
+    // Build dynamic imports — use .tiramisu.svelte suffix so resolveId maps them
+    const importsEntries = docs
+      .map((doc) => {
+        const absPath = path
+          .resolve(absDocsDir, doc.slug + ".tiramisu")
+          .replace(/\\/g, "/")
+        return `  "${doc.slug}": () => import("${absPath}")`
+      })
+      .join(",\n")
+
+    if (config?.i18n) {
+      const localeData = buildLocaleData(docs, config.i18n.locales)
+
+      const localeBlocks = config.i18n.locales.map((locale) => {
+        const localeDocs = localeData[locale.code].docs
+        const localeSections = config.sections
+          ? buildSectionSidebars(localeDocs, config.sections, config.title)
+          : undefined
+        const localeSidebar = buildSidebarTree(localeDocs, groupOrder)
+
+        // Build locale-specific search index
+        const localeSearchIndex = localeDocs.map((doc) => {
+          const fullSlug = `${locale.code}/${doc.slug}`
+          const file = path.resolve(absDocsDir, fullSlug + ".tiramisu")
+          const source = fs.readFileSync(file, "utf-8")
+          const { svelte } = compileWithLocation(source, file)
+          const text = extractPlainText(svelte)
+          return {
+            id: doc.slug,
+            title: doc.meta.title ?? doc.slug,
+            group: resolveSearchGroup(doc.slug, doc.meta),
+            slug: doc.slug,
+            headings: docs.find(d => d.slug === fullSlug)?.headings?.map(h => h.text).join(" ") ?? "",
+            text,
+          }
+        })
+
+        const localeImports = localeDocs
+          .map((doc) => {
+            const fullSlug = `${locale.code}/${doc.slug}`
+            const absPath = path.resolve(absDocsDir, fullSlug + ".tiramisu").replace(/\\/g, "/")
+            return `    "${doc.slug}": () => import("${absPath}")`
+          })
+          .join(",\n")
+
+        return `  "${locale.code}": {
+    sections: ${JSON.stringify(localeSections, null, 2)},
+    sidebar: ${JSON.stringify(localeSidebar, null, 2)},
+    docs: ${JSON.stringify(localeDocs, null, 2)},
+    searchIndex: ${JSON.stringify(localeSearchIndex)},
+    docImports: {\n${localeImports}\n    },
+  }`
+      }).join(",\n")
+
+      return [
+
+        `export const locales = {\n${localeBlocks}\n};`,
+        `export const defaultLocale = "${config.i18n.defaultLocale}";`,
+        `export const sidebar = locales["${config.i18n.defaultLocale}"].sidebar;`,
+        `export const sections = locales["${config.i18n.defaultLocale}"].sections;`,
+        `export const docs = locales["${config.i18n.defaultLocale}"].docs;`,
+        `export const searchIndex = locales["${config.i18n.defaultLocale}"].searchIndex;`,
+        `export const docImports = locales["${config.i18n.defaultLocale}"].docImports;`,
+      ].join("\n\n")
+    }
+
+    if (config?.sections) {
+      const resolvedSections = buildSectionSidebars(docs, config.sections, config.title)
+      return [
+
+        `export const locales = undefined;`,
+        `export const defaultLocale = undefined;`,
+        `export const sections = ${JSON.stringify(resolvedSections, null, 2)};`,
+        `export const sidebar = [];`,
+        `export const docs = ${JSON.stringify(docs, null, 2)};`,
+        `export const searchIndex = ${JSON.stringify(searchIndex)};`,
+        `export const docImports = {\n${importsEntries}\n};`,
+      ].join("\n\n")
+    } else {
+      const sidebar = buildSidebarTree(docs, groupOrder)
+      return [
+
+        `export const locales = undefined;`,
+        `export const defaultLocale = undefined;`,
+        `export const sections = undefined;`,
+        `export const sidebar = ${JSON.stringify(sidebar, null, 2)};`,
+        `export const docs = ${JSON.stringify(docs, null, 2)};`,
+        `export const searchIndex = ${JSON.stringify(searchIndex)};`,
+        `export const docImports = {\n${importsEntries}\n};`,
+      ].join("\n\n")
+    }
+  }
+
+  return {
+    name: "tiramisu-docs",
+    enforce: "pre",
+
+    configResolved(config: ViteConfig) {
+      viteRoot = config.root
+    },
+
+    resolveId(id: string) {
+      if (id === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_MODULE_ID
+      }
+      // Resolve .tiramisu imports to a virtual .svelte ID
+      // so the Svelte plugin processes the output
+      if (id.endsWith(".tiramisu")) {
+        const resolved = path.isAbsolute(id) ? id : path.resolve(viteRoot, id)
+        if (fs.existsSync(resolved)) {
+          return resolved + ".svelte"
+        }
+      }
+      return undefined
+    },
+
+    async load(id: string) {
+      if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+        return buildVirtualModule()
+      }
+
+      // Compile .tiramisu files to Svelte component source
+      // These come in as .tiramisu.svelte due to resolveId above
+      if (id.endsWith(TIRAMISU_SVELTE_SUFFIX)) {
+        const tiramisuPath = id.slice(0, -".svelte".length)
+        if (!fs.existsSync(tiramisuPath)) return undefined
+
+        const source = fs.readFileSync(tiramisuPath, "utf-8")
+        const { svelte } = compileWithLocation(source, tiramisuPath)
+        return await highlightCodeBlocks(svelte)
+      }
+
+      return undefined
+    },
+
+    handleHotUpdate(ctx: HmrContext) {
+      if (ctx.file.endsWith(".tiramisu")) {
+        // Invalidate the virtual module so sidebar/docs get rebuilt
+        const virtualMod = ctx.server.moduleGraph.getModuleById(
+          RESOLVED_VIRTUAL_MODULE_ID
+        )
+        if (virtualMod) {
+          ctx.server.moduleGraph.invalidateModule(virtualMod)
+        }
+
+        // Invalidate the compiled .svelte version too
+        const svelteMod = ctx.server.moduleGraph.getModuleById(
+          ctx.file + ".svelte"
+        )
+        if (svelteMod) {
+          ctx.server.moduleGraph.invalidateModule(svelteMod)
+        }
+
+        ctx.server.ws.send({ type: "full-reload" })
+        return []
+      }
+    },
+  }
+}

package/tests/config.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "bun:test"
+import { defineConfig, resolveConfig } from "../src/config"
+
+describe("defineConfig", () => {
+  it("returns the config as-is (type helper)", () => {
+    const config = defineConfig({ title: "Test" })
+    expect(config.title).toBe("Test")
+  })
+})
+
+describe("resolveConfig", () => {
+  it("fills in defaults", () => {
+    const config = resolveConfig({})
+    expect(config.title).toBe("Documentation")
+    expect(config.sidebar.groupOrder).toEqual([])
+  })
+
+  it("resolves sections config", () => {
+    const config = resolveConfig({
+      sections: [
+        { label: "Guides", path: "guides" },
+        { label: "Reference", children: [
+          { label: "API", path: "api" },
+          { label: "CLI", path: "cli" },
+        ]},
+        { label: "Blog", href: "https://blog.example.com" },
+      ],
+    })
+    expect(config.sections).toHaveLength(3)
+    expect(config.sections![0].label).toBe("Guides")
+    expect(config.sections![1].children).toHaveLength(2)
+    expect(config.sections![2].href).toBe("https://blog.example.com")
+  })
+
+  it("resolves undefined sections as undefined", () => {
+    const config = resolveConfig({})
+    expect(config.sections).toBeUndefined()
+  })
+
+  it("resolves i18n config", () => {
+    const config = resolveConfig({
+      i18n: {
+        defaultLocale: "en",
+        locales: [
+          { code: "en", label: "English", flag: "🇺🇸" },
+          { code: "fr", label: "Français", flag: "🇫🇷" },
+        ],
+      },
+    })
+    expect(config.i18n).toBeDefined()
+    expect(config.i18n!.defaultLocale).toBe("en")
+    expect(config.i18n!.locales).toHaveLength(2)
+    expect(config.i18n!.fallback).toBe("default-language")
+  })
+
+  it("resolves undefined i18n as undefined", () => {
+    const config = resolveConfig({})
+    expect(config.i18n).toBeUndefined()
+  })
+})

package/tests/mcp.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "bun:test"
+import { handleMcpRequest } from "../src/mcp"
+import type { McpData } from "../src/mcp"
+
+const mockData: McpData = {
+  docs: [
+    {
+      slug: "getting-started",
+      meta: { title: "Getting Started", description: "How to begin" },
+      headings: [
+        { level: 2, text: "Installation", id: "installation" },
+        { level: 2, text: "Usage", id: "usage" },
+      ],
+    },
+    {
+      slug: "api/auth",
+      meta: { title: "Authentication", description: "Auth docs" },
+      headings: [{ level: 2, text: "Tokens", id: "tokens" }],
+    },
+  ],
+  searchIndex: [
+    { id: "1", title: "Getting Started", group: "Guide", slug: "getting-started", headings: "Installation Usage", text: "Welcome to the docs. Install the package and get started." },
+    { id: "2", title: "Authentication", group: "API", slug: "api/auth", headings: "Tokens", text: "Authentication uses bearer tokens." },
+  ],
+  sidebar: [],
+}
+
+describe("handleMcpRequest", () => {
+  it("handles initialize", () => {
+    const res = handleMcpRequest({ jsonrpc: "2.0", id: 1, method: "initialize" }, mockData)
+    expect(res.result).toBeDefined()
+    expect((res.result as any).serverInfo.name).toBe("tiramisu-docs")
+    expect((res.result as any).capabilities.tools).toBeDefined()
+  })
+
+  it("handles tools/list", () => {
+    const res = handleMcpRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" }, mockData)
+    const tools = (res.result as any).tools
+    expect(tools).toHaveLength(5)
+    expect(tools.map((t: any) => t.name)).toContain("search_docs")
+    expect(tools.map((t: any) => t.name)).toContain("read_doc")
+  })
+
+  it("search_docs finds matching pages", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 3, method: "tools/call",
+      params: { name: "search_docs", arguments: { query: "install" } },
+    }, mockData)
+    const content = JSON.parse((res.result as any).content[0].text)
+    expect(content).toHaveLength(1)
+    expect(content[0].slug).toBe("getting-started")
+  })
+
+  it("read_doc returns page content", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 4, method: "tools/call",
+      params: { name: "read_doc", arguments: { slug: "getting-started" } },
+    }, mockData)
+    const content = JSON.parse((res.result as any).content[0].text)
+    expect(content.title).toBe("Getting Started")
+    expect(content.content).toContain("Install the package")
+  })
+
+  it("read_doc returns error for missing page", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 5, method: "tools/call",
+      params: { name: "read_doc", arguments: { slug: "nonexistent" } },
+    }, mockData)
+    expect((res.result as any).isError).toBe(true)
+  })
+
+  it("list_pages returns all pages", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 6, method: "tools/call",
+      params: { name: "list_pages", arguments: {} },
+    }, mockData)
+    const content = JSON.parse((res.result as any).content[0].text)
+    expect(content).toHaveLength(2)
+  })
+
+  it("list_pages filters by section", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 7, method: "tools/call",
+      params: { name: "list_pages", arguments: { section: "API" } },
+    }, mockData)
+    const content = JSON.parse((res.result as any).content[0].text)
+    expect(content).toHaveLength(1)
+    expect(content[0].slug).toBe("api/auth")
+  })
+
+  it("list_sections groups pages", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 8, method: "tools/call",
+      params: { name: "list_sections", arguments: {} },
+    }, mockData)
+    const content = JSON.parse((res.result as any).content[0].text)
+    expect(content).toHaveLength(2)
+    expect(content.find((s: any) => s.label === "Guide").pageCount).toBe(1)
+  })
+
+  it("get_table_of_contents returns headings", () => {
+    const res = handleMcpRequest({
+      jsonrpc: "2.0", id: 9, method: "tools/call",
+      params: { name: "get_table_of_contents", arguments: { slug: "getting-started" } },
+    }, mockData)
+    const content = JSON.parse((res.result as any).content[0].text)
+    expect(content).toHaveLength(2)
+    expect(content[0].text).toBe("Installation")
+  })
+
+  it("returns error for unknown method", () => {
+    const res = handleMcpRequest({ jsonrpc: "2.0", id: 10, method: "unknown/method" }, mockData)
+    expect(res.error).toBeDefined()
+    expect(res.error!.code).toBe(-32601)
+  })
+})

package/tests/scan.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "bun:test"
+import { scanDocs, extractPlainText, titleCase, findTiramisuFiles } from "../src/scan"
+import path from "node:path"
+
+const playgroundDocs = path.resolve(__dirname, "../../../playground/src/docs")
+
+describe("extractPlainText", () => {
+  it("strips HTML tags", () => {
+    expect(extractPlainText("<p>Hello <strong>world</strong></p>")).toBe("Hello world")
+  })
+
+  it("decodes entities", () => {
+    expect(extractPlainText("&amp; &lt; &gt; &quot;")).toBe('& < > "')
+  })
+
+  it("removes script tags entirely", () => {
+    expect(extractPlainText('<script>var x = 1;</script><p>text</p>')).toBe("text")
+  })
+})
+
+describe("titleCase", () => {
+  it("converts slug to title case", () => {
+    expect(titleCase("getting-started")).toBe("Getting Started")
+  })
+})
+
+describe("findTiramisuFiles", () => {
+  it("returns empty for nonexistent dir", () => {
+    expect(findTiramisuFiles("/nonexistent/path")).toEqual([])
+  })
+})
+
+describe("scanDocs", () => {
+  it("scans playground docs and returns docs + searchIndex", () => {
+    const { docs, searchIndex } = scanDocs(playgroundDocs)
+    expect(docs.length).toBeGreaterThan(0)
+    expect(searchIndex.length).toBe(docs.length)
+    for (const doc of docs) {
+      expect(doc.slug).toBeDefined()
+      expect(doc.meta).toBeDefined()
+      expect(doc.headings).toBeDefined()
+    }
+    for (const entry of searchIndex) {
+      expect(entry.title).toBeDefined()
+      expect(entry.text.length).toBeGreaterThan(0)
+    }
+  })
+})