vocs 2.1.12 → 2.2.3

package/src/internal/markdown-imports.ts

@@ -0,0 +1,154 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type * as Estree from 'estree'
+import type * as MdAst from 'mdast'
+import remarkMdx from 'remark-mdx'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
+
+type MdxEsm = MdAst.RootContent & {
+  type: 'mdxjsEsm'
+  data?: {
+    estree?: Estree.Program
+  }
+}
+
+type MdxJsxElement = MdAst.RootContent & {
+  type: 'mdxJsxFlowElement' | 'mdxJsxTextElement'
+  attributes?: unknown[]
+  children?: MdAst.RootContent[]
+  name?: string | null
+}
+
+type MarkdownImport = {
+  source: string
+}
+
+type Replacement = {
+  end: number
+  start: number
+  value: string
+}
+
+export function inlineMarkdownImports(source: string, filePath: string): string {
+  return inline(source, path.resolve(filePath), new Set())
+}
+
+function inline(source: string, filePath: string, seen: Set<string>): string {
+  if (seen.has(filePath)) return ''
+  seen.add(filePath)
+
+  let tree: MdAst.Root
+  try {
+    tree = unified().use(remarkParse).use(remarkMdx).parse(source)
+  } catch {
+    return source
+  }
+
+  const imports = new Map<string, MarkdownImport>()
+  const replacements: Replacement[] = []
+
+  collectImports(tree.children, imports, replacements)
+  collectComponentReplacements(tree, imports, filePath, seen, replacements)
+
+  if (replacements.length === 0) return source
+  return applyReplacements(source, replacements)
+}
+
+function collectImports(
+  children: MdAst.RootContent[],
+  imports: Map<string, MarkdownImport>,
+  replacements: Replacement[],
+) {
+  for (const node of children) {
+    if (node.type !== 'mdxjsEsm') continue
+
+    const mdxEsm = node as MdxEsm
+    const declarations = mdxEsm.data?.estree?.body.filter(
+      (statement): statement is Estree.ImportDeclaration => statement.type === 'ImportDeclaration',
+    )
+    if (!declarations || declarations.length === 0) continue
+
+    let markdownDeclarations = 0
+    for (const declaration of declarations) {
+      const source = declaration.source.value
+      if (typeof source !== 'string' || !isMarkdownImport(source)) continue
+      markdownDeclarations++
+
+      const specifier = declaration.specifiers.find(
+        (specifier): specifier is Estree.ImportDefaultSpecifier =>
+          specifier.type === 'ImportDefaultSpecifier',
+      )
+      if (!specifier) continue
+      imports.set(specifier.local.name, { source })
+    }
+
+    if (markdownDeclarations === declarations.length) {
+      const replacement = toReplacement(node, '')
+      if (replacement) replacements.push(replacement)
+    }
+  }
+}
+
+function collectComponentReplacements(
+  node: MdAst.Root | MdAst.RootContent,
+  imports: Map<string, MarkdownImport>,
+  filePath: string,
+  seen: Set<string>,
+  replacements: Replacement[],
+) {
+  if (isMdxJsxElement(node)) {
+    const name = node.name ?? undefined
+    const markdownImport = name ? imports.get(name) : undefined
+    if (markdownImport && isStaticMdxComponent(node)) {
+      const importedPath = resolveMarkdownImport(markdownImport.source, filePath)
+      if (importedPath) {
+        const importedSource = fs.readFileSync(importedPath, 'utf-8')
+        const value = inline(importedSource, importedPath, new Set(seen))
+        const replacement = toReplacement(node, value)
+        if (replacement) replacements.push(replacement)
+      }
+    }
+  }
+
+  if ('children' in node && Array.isArray(node.children))
+    for (const child of node.children)
+      collectComponentReplacements(child, imports, filePath, seen, replacements)
+}
+
+function isMdxJsxElement(node: MdAst.Root | MdAst.RootContent): node is MdxJsxElement {
+  return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement'
+}
+
+function isStaticMdxComponent(node: MdxJsxElement): boolean {
+  return (node.attributes?.length ?? 0) === 0 && (node.children?.length ?? 0) === 0
+}
+
+function resolveMarkdownImport(source: string, filePath: string): string | undefined {
+  if (!source.startsWith('.') && !path.isAbsolute(source)) return undefined
+
+  const resolved = path.isAbsolute(source) ? source : path.resolve(path.dirname(filePath), source)
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved
+  return undefined
+}
+
+function isMarkdownImport(source: string): boolean {
+  return /\.(md|mdx)$/.test(source)
+}
+
+function toReplacement(
+  node: MdAst.Root | MdAst.RootContent,
+  value: string,
+): Replacement | undefined {
+  const start = node.position?.start.offset
+  const end = node.position?.end.offset
+  if (start === undefined || end === undefined) return undefined
+  return { end, start, value }
+}
+
+function applyReplacements(source: string, replacements: Replacement[]): string {
+  let result = source
+  for (const replacement of replacements.sort((a, b) => b.start - a.start))
+    result = result.slice(0, replacement.start) + replacement.value + result.slice(replacement.end)
+  return result
+}

package/src/internal/openapi/parser.test.ts

@@ -226,6 +226,45 @@ describe('parse', () => {
       globalThis.fetch = fetch_
     }
   })
+
+  test('parses OpenAPI 3.1 top-level `webhooks` as non-callable operations', async () => {
+    const webhookSpec = {
+      openapi: '3.1.0',
+      info: { title: 'Petstore', version: '1.0.0' },
+      tags: [{ name: 'Webhooks', description: 'Outbound deliveries.' }],
+      paths: {
+        '/pets': { get: { operationId: 'listPets', tags: ['pets'], responses: { '200': {} } } },
+      },
+      webhooks: {
+        event: {
+          post: {
+            summary: 'Webhook event delivery',
+            tags: ['Webhooks'],
+            parameters: [
+              { name: 'x-signature', in: 'header', required: true, schema: { type: 'string' } },
+            ],
+            requestBody: {
+              required: true,
+              content: { 'application/json': { schema: { type: 'object' } } },
+            },
+            responses: { '2xx': { description: 'Delivery acknowledged.' } },
+          },
+        },
+      },
+    }
+    const ir = await parse(OpenApi.from({ spec: webhookSpec, path: '/api' }))
+
+    const webhooks = ir.groups.find((group) => group.name === 'Webhooks')
+    expect(webhooks?.operations).toHaveLength(1)
+    const event = webhooks?.operations[0]
+    expect(event?.method).toBe('POST')
+    expect(event?.path).toBe('event')
+    expect(event?.isWebhook).toBe(true)
+    expect(event?.summary).toBe('Webhook event delivery')
+    expect(event?.requestBody?.content[0]?.schema).toEqual({ type: 'object' })
+    // Webhook ids are prefixed so they can't collide with real path operations.
+    expect(event?.id).toBe('webhook-post-event')
+  })
 })
 
 describe('from', () => {

package/src/internal/openapi/parser.ts

@@ -95,8 +95,14 @@ export type IrOperation = {
   id: string
   /** HTTP method (uppercased for display, e.g. `GET`). */
   method: string
-  /** Templated path (e.g. `/pets/{petId}`). */
+  /** Templated path (e.g. `/pets/{petId}`), or the event name for webhooks. */
   path: string
+  /**
+   * `true` for an OpenAPI 3.1 outbound webhook delivery (from the document's
+   * top-level `webhooks`). The renderer omits the interactive client and code
+   * samples for these, since there's no endpoint to call.
+   */
+  isWebhook?: boolean | undefined
   /**
    * Name of the host operation's request example to preselect in the
    * interactive client. Set for JSON-RPC operations expanded from an OpenRPC
@@ -192,6 +198,12 @@ type Document = {
     'x-parent'?: string
   }[]
   paths?: Record<string, PathItem>
+  /**
+   * OpenAPI 3.1 outbound webhook deliveries. Keyed by event name (an arbitrary
+   * label, not a URL); each value is a Path Item with the same operation shape
+   * as `paths`. Rendered as non-callable operations (no server endpoint).
+   */
+  webhooks?: Record<string, PathItem>
   components?: { securitySchemes?: Record<string, IrSecurityScheme> }
   security?: Record<string, string[]>[]
 }
@@ -551,6 +563,35 @@ async function buildGroups(
     }
   }
 
+  // OpenAPI 3.1 outbound webhooks: same Path Item shape as `paths`, but keyed by
+  // event name and rendered as non-callable operations.
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    if (!item || typeof item !== 'object') continue
+    const pathParameters = item.parameters ?? []
+
+    for (const method of methods) {
+      const operation = item[method]
+      if (!operation) continue
+
+      const groupName = operation.tags?.[0] ?? 'Webhooks'
+      if (!byName.has(groupName)) {
+        byName.set(groupName, [])
+        order.push(groupName)
+      }
+
+      byName.get(groupName)?.push(
+        buildOperation({
+          method,
+          pathname: name,
+          operation,
+          pathParameters,
+          slugger,
+          isWebhook: true,
+        }),
+      )
+    }
+  }
+
   const groups = order
     .map((name) => ({
       id: slugger.slug(name),
@@ -569,10 +610,13 @@ function buildOperation(options: {
   operation: Operation
   pathParameters: RawParameter[]
   slugger: GithubSlugger
+  isWebhook?: boolean
 }): IrOperation {
-  const { method, pathname, operation, pathParameters, slugger } = options
+  const { method, pathname, operation, pathParameters, slugger, isWebhook = false } = options
 
-  const idSource = operation.operationId || `${method}-${pathname}`
+  // Webhook keys are arbitrary labels (not URLs) and can collide with real
+  // paths, so prefix the id source to keep anchors unique.
+  const idSource = operation.operationId || `${isWebhook ? 'webhook-' : ''}${method}-${pathname}`
 
   // Merge path-level parameters with operation-level (operation wins on conflict).
   const merged = new Map<string, RawParameter>()
@@ -585,6 +629,7 @@ function buildOperation(options: {
     id: slugger.slug(idSource),
     method: method.toUpperCase(),
     path: pathname,
+    ...(isWebhook ? { isWebhook: true } : {}),
     summary: operation.summary,
     description: operation.description,
     deprecated: operation.deprecated,

package/src/internal/openapi/sidebar.test.ts

@@ -119,6 +119,37 @@ describe('toSidebar', () => {
   })
 })
 
+describe('webhook badges', () => {
+  const webhookIr: Ir = {
+    ...ir,
+    groups: [
+      {
+        id: 'webhooks',
+        name: 'Webhooks',
+        operations: [
+          {
+            id: 'payment-succeeded',
+            method: 'POST',
+            path: 'payment.succeeded',
+            summary: 'Payment succeeded',
+            parameters: [],
+            responses: [],
+            isWebhook: true,
+          },
+        ],
+      },
+    ],
+  }
+
+  test('webhook operations get an icon badge instead of the POST method text', () => {
+    const sidebar = toSidebar(webhookIr)
+    const group = sidebar[1] as { items: { badge?: { icon?: string; text?: string } }[] }
+    const badge = group.items[1]?.badge
+    expect(badge?.text).toBeUndefined()
+    expect(badge?.icon).toContain('<svg')
+  })
+})
+
 describe('methodVariant', () => {
   test('maps methods to badge variants', () => {
     expect(methodVariant('GET')).toBe('info')

package/src/internal/openapi/sidebar.ts

@@ -1,6 +1,10 @@
+import { resolveIconSync } from '../icons.js'
 import type { SidebarItem } from '../sidebar.js'
 import type { Ir, IrOperation } from './parser.js'
 
+/** Inline SVG for the webhook badge, resolved once at module load (server-side). */
+const webhookIcon = resolveIconSync('lucide:webhook')
+
 export type Badge = NonNullable<SidebarItem['badge']>
 export type BadgeVariant = NonNullable<Exclude<Badge, string>['variant']>
 
@@ -72,7 +76,12 @@ export function toSidebar(ir: Ir, options: toSidebar.Options = {}): SidebarItem<
         ...group.operations.map((operation) => ({
           text: operation.summary || `${operation.method} ${operation.path}`,
           link: operationLink(operation, group.id),
-          badge: { text: operation.method, variant: methodVariant(operation.method) },
+          // Webhooks are inbound deliveries, not callable endpoints — show a
+          // webhook glyph instead of the HTTP method (which is always POST).
+          badge:
+            operation.isWebhook && webhookIcon
+              ? { icon: webhookIcon, variant: methodVariant(operation.method) }
+              : { text: operation.method, variant: methodVariant(operation.method) },
         })),
       ],
     })),

package/src/internal/search.client.ts

@@ -1,3 +1,9 @@
+import type {
+  Options as MiniSearchOptions,
+  SearchOptions as MiniSearchSearchOptions,
+} from 'minisearch'
+import type * as Config from './config.js'
+
 export const searchFields = ['category', 'subtitle', 'text', 'title', 'titles'] as const
 export const storeFields = [
   'category',
@@ -40,3 +46,26 @@ export function tokenize(text: string): string[] {
 
   return tokens.filter((w) => w.length > 0)
 }
+
+export namespace SearchConfig {
+  export function getIndexOptions(config?: Config.Config): MiniSearchOptions {
+    const index = config?.search.index ?? {}
+    return {
+      ...index,
+      fields: index.fields ? [...index.fields] : [...searchFields],
+      storeFields: mergeStoreFields(index.storeFields),
+      tokenize: index.tokenize ?? tokenize,
+    }
+  }
+
+  export function getQueryOptions(config: Config.Config): MiniSearchSearchOptions {
+    return {
+      ...config.search.query,
+      tokenize: config.search.query?.tokenize ?? config.search.index?.tokenize ?? tokenize,
+    }
+  }
+
+  function mergeStoreFields(fields: readonly string[] | undefined): string[] {
+    return [...new Set([...storeFields, ...(fields ?? [])])]
+  }
+}

package/src/internal/search.test.ts

@@ -1,3 +1,6 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
 import type * as MdAst from 'mdast'
 import { describe, expect, it } from 'vitest'
 import * as Config from './config.js'
@@ -859,6 +862,40 @@ Some content here.
   })
 })
 
+describe('SearchDocuments.fromConfig', () => {
+  it('indexes imported markdown content from file-backed pages', async () => {
+    const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vocs-search-'))
+    const pagesDir = path.join(rootDir, 'src/pages')
+    fs.mkdirSync(pagesDir, { recursive: true })
+
+    fs.writeFileSync(
+      path.join(rootDir, 'notes.md'),
+      '# Notes\n\nSome indexable prose about widgets and links.',
+    )
+    fs.writeFileSync(
+      path.join(pagesDir, 'notes.mdx'),
+      `---
+title: Notes
+---
+
+import Notes from '../../notes.md'
+
+<Notes />`,
+    )
+
+    const documents = await Search.SearchDocuments.fromConfig(Config.define({ rootDir }))
+
+    expect(documents).toContainEqual(
+      expect.objectContaining({
+        href: '/notes#notes',
+        text: ' Some indexable prose about widgets and links.',
+        title: 'Notes',
+        type: 'page',
+      }),
+    )
+  })
+})
+
 describe('Search fields and storeFields', () => {
   it('exports search fields', () => {
     expect(Search.searchFields).toMatchInlineSnapshot(`
@@ -902,6 +939,65 @@ describe('Config.search defaults', () => {
     expect(config.search.fuzzy).toBe(0.2)
     expect(config.search.prefix).toBe(true)
     expect(typeof config.search.boostDocument).toBe('function')
+    expect(config.search.query?.boost).toEqual(config.search.boost)
+    expect(config.search.query?.fuzzy).toBe(0.2)
+    expect(config.search.query?.prefix).toBe(true)
+  })
+
+  it('normalizes legacy search options into query options', () => {
+    const config = Config.define({
+      search: {
+        boost: { text: 10 },
+        combineWith: 'OR',
+        fuzzy: false,
+        prefix: false,
+      },
+    })
+
+    expect(config.search.query?.boost).toMatchObject({ title: 4, text: 10 })
+    expect(config.search.query?.combineWith).toBe('OR')
+    expect(config.search.query?.fuzzy).toBe(false)
+    expect(config.search.query?.prefix).toBe(false)
+  })
+})
+
+describe('SearchConfig', () => {
+  it('returns default index options', () => {
+    expect(Search.SearchConfig.getIndexOptions(config)).toMatchObject({
+      fields: ['category', 'subtitle', 'text', 'title', 'titles'],
+      storeFields: [
+        'category',
+        'href',
+        'searchPriority',
+        'subtitle',
+        'text',
+        'title',
+        'titles',
+        'type',
+      ],
+    })
+  })
+
+  it('keeps required store fields when custom store fields are configured', () => {
+    const config = Config.define({
+      search: {
+        index: {
+          storeFields: ['href', 'custom'],
+        },
+      },
+    })
+
+    expect(Search.SearchConfig.getIndexOptions(config).storeFields).toEqual([
+      'category',
+      'href',
+      'searchPriority',
+      'subtitle',
+      'text',
+      'title',
+      'titles',
+      'type',
+      'custom',
+    ])
   })
 })
 
@@ -1006,6 +1102,105 @@ describe('SearchIndex.fromSearchDocuments', () => {
     expect(results[0]?.score).toBeGreaterThan(results[1]?.score ?? 0)
   })
 
+  it('indexes custom virtual fields', () => {
+    const docs: SearchDocuments.Document[] = [
+      {
+        category: '',
+        href: '/docs/runtime-api',
+        id: '/docs/runtime-api.mdx#runtime-api',
+        searchPriority: undefined,
+        subtitle: '',
+        text: 'Reference content.',
+        title: 'Runtime API',
+        titles: [],
+        type: 'page',
+      },
+    ]
+    const config = Config.define({
+      search: {
+        index: {
+          fields: ['path'],
+          extractField(document, fieldName) {
+            if (fieldName === 'path') return document.href
+            return document[fieldName as keyof typeof document]
+          },
+        },
+      },
+    })
+
+    const index = SearchIndex.fromSearchDocuments(docs, config)
+
+    expect(index.search('runtime', Search.SearchConfig.getQueryOptions(config))[0]?.id).toBe(
+      '/docs/runtime-api.mdx#runtime-api',
+    )
+  })
+
+  it('stores custom fields', () => {
+    const docs: SearchDocuments.Document[] = [
+      {
+        category: 'Docs',
+        href: '/guide',
+        id: '/docs/guide.mdx#guide',
+        searchPriority: undefined,
+        subtitle: '',
+        text: 'Install instructions.',
+        title: 'Guide',
+        titles: [],
+        type: 'page',
+      },
+    ]
+    const config = Config.define({
+      search: {
+        index: {
+          storeFields: ['path'],
+          extractField(document, fieldName) {
+            if (fieldName === 'path') return document.href
+            return document[fieldName as keyof typeof document]
+          },
+        },
+      },
+    })
+
+    const index = SearchIndex.fromSearchDocuments(docs, config)
+    const result = index.search('guide', Search.SearchConfig.getQueryOptions(config))[0]
+
+    expect(result).toMatchObject({ href: '/guide', path: '/guide', title: 'Guide' })
+  })
+
+  it('applies query fields, weights, and filter at runtime', () => {
+    const docs = [
+      ...buildDoc(
+        '/docs/title.mdx',
+        '/title',
+        `# Alpha
+
+No keyword.
+`,
+      ),
+      ...buildDoc(
+        '/docs/text.mdx',
+        '/text',
+        `# Other
+
+Alpha keyword.
+`,
+      ),
+    ]
+    const config = Config.define({
+      search: {
+        query: {
+          fields: ['text'],
+          filter: (result) => result.id !== '/docs/text.mdx#other',
+          weights: { fuzzy: 0.5, prefix: 0.5 },
+        },
+      },
+    })
+
+    const index = SearchIndex.fromSearchDocuments(docs, config)
+
+    expect(index.search('alpha', Search.SearchConfig.getQueryOptions(config))).toEqual([])
+  })
+
   it('boosts shallow paths over deep paths', () => {
     const shallowDoc: SearchDocuments.Document = {
       category: '',

package/src/internal/search.ts

@@ -14,11 +14,12 @@ import { unified } from 'unified'
 import * as UnistUtil from 'unist-util-visit'
 import * as yaml from 'yaml'
 import type * as Config from './config.js'
+import * as MarkdownImports from './markdown-imports.js'
 import { extractSubheading, getPhrasingContentText } from './mdx.js'
 import * as OpenApiRegistry from './openapi/registry.js'
 import * as OpenApiSearch from './openapi/search.js'
 import * as Path from './path.js'
-import { searchFields, storeFields, tokenize } from './search.client.js'
+import { SearchConfig } from './search.client.js'
 import * as Sidebar from './sidebar.js'
 import * as TaskRunner from './task-runner.js'
 import * as TopNav from './topNav.js'
@@ -61,7 +62,8 @@ export namespace SearchDocuments {
     for (const page of mdxPages)
       taskRunner.run(async () => {
         const filePath = path.join(pagesDirPath, page)
-        const content = await fs.promises.readFile(filePath, 'utf-8')
+        const rawContent = await fs.promises.readFile(filePath, 'utf-8')
+        const content = MarkdownImports.inlineMarkdownImports(rawContent, filePath)
 
         const { searchPriority, sections } = extract(content, config)
         if (sections.length === 0) return
@@ -206,12 +208,11 @@ export namespace SearchIndex {
   /**
    * Create a search index from documents.
    */
-  export function fromSearchDocuments(documents: SearchDocuments.Document[]): SearchIndex {
-    const index = new MiniSearch<SearchDocuments.Document>({
-      fields: [...searchFields],
-      storeFields: [...storeFields],
-      tokenize,
-    })
+  export function fromSearchDocuments(
+    documents: SearchDocuments.Document[],
+    config?: Config.Config,
+  ): SearchIndex {
+    const index = new MiniSearch<SearchDocuments.Document>(SearchConfig.getIndexOptions(config))
     index.addAll(documents)
     return index
   }
@@ -220,17 +221,15 @@ export namespace SearchIndex {
    * Load a search index from a JSON file.
    */
   export function loadFromFile(options: loadFromFile.Options): SearchIndex {
-    const { filePath } = options
+    const { config, filePath } = options
 
     const json = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
-    return MiniSearch.loadJSON(json, {
-      fields: [...searchFields],
-      storeFields: [...storeFields],
-    })
+    return MiniSearch.loadJSON(json, SearchConfig.getIndexOptions(config))
   }
 
   export declare namespace loadFromFile {
     type Options = {
+      config?: Config.Config
       filePath: string
     }
   }
@@ -260,7 +259,8 @@ export namespace SearchIndex {
   ): string[] {
     const { pagesDir, previousIds = [], config } = options
 
-    const content = fs.readFileSync(filePath, 'utf-8')
+    const rawContent = fs.readFileSync(filePath, 'utf-8')
+    const content = MarkdownImports.inlineMarkdownImports(rawContent, filePath)
     const { searchPriority, sections } = extract(content, config)
 
     // Remove old entries for this file

package/src/internal/sidebar.ts

@@ -3,8 +3,14 @@ import type { Config } from './config.js'
 export type SidebarItemBadge =
   | string
   | {
-      /** Text displayed inside the badge. */
-      text: string
+      /**
+       * Inline SVG markup rendered before the badge text. Used for icon badges
+       * (e.g. the generated OpenAPI webhook badge). Resolve an icon name to SVG
+       * server-side (via the icon helpers) before assigning.
+       */
+      icon?: string | undefined
+      /** Text displayed inside the badge. Optional when an `icon` is provided. */
+      text?: string | undefined
       /** Visual variant. Defaults to `'info'`. */
       variant?: 'note' | 'info' | 'warning' | 'danger' | 'tip' | 'success' | undefined
     }