vocs 2.0.17 → 2.1.2

package/src/internal/openapi/search.ts

@@ -0,0 +1,108 @@
+import type { SearchDocuments } from '../search.js'
+import type { Ir, IrOperation } from './parser.js'
+
+/**
+ * Builds search index documents for an OpenAPI section so the auto-generated
+ * reference is discoverable by Vocs's search (which otherwise only crawls
+ * `.md`/`.mdx` files).
+ *
+ * Mirrors the page/anchor structure of the rendered reference:
+ * - the `/api` landing page (one `page` document),
+ * - each category page `/api/<group>` (one `page` document), and
+ * - each operation as a `section` document anchored on its category page
+ *   (`/api/<group>#<operation>`).
+ *
+ * Operation documents fold the method, path, parameter names/descriptions and
+ * response descriptions into their searchable `text` so endpoints surface for a
+ * wide range of queries (summary, path, parameter, status code, …).
+ */
+export function toSearchDocuments(ir: Ir): SearchDocuments.Document[] {
+  const category = ir.info.title
+  const documents: SearchDocuments.Document[] = []
+  // Strip a trailing slash so a root mount (`/`) doesn't yield `//group` hrefs.
+  const base = ir.path === '/' ? '' : ir.path.replace(/\/$/, '')
+
+  // Section landing page (`/api`).
+  documents.push({
+    category,
+    href: ir.path,
+    id: `openapi:${ir.path}`,
+    searchPriority: undefined,
+    subtitle: '',
+    text: plainText(ir.info.description),
+    title: ir.info.title,
+    titles: [],
+    type: 'page',
+  })
+
+  for (const group of ir.groups) {
+    const groupHref = `${base}/${group.id}`
+
+    // Category page (`/api/<group>`).
+    documents.push({
+      category,
+      href: groupHref,
+      id: `openapi:${groupHref}`,
+      searchPriority: undefined,
+      subtitle: '',
+      text: plainText(group.description),
+      title: group.name,
+      titles: [ir.info.title],
+      type: 'page',
+    })
+
+    // Each operation, anchored on its category page.
+    for (const operation of group.operations) {
+      const methodPath = `${operation.method} ${operation.path}`
+      documents.push({
+        category,
+        href: `${groupHref}#${operation.id}`,
+        id: `openapi:${groupHref}#${operation.id}`,
+        searchPriority: undefined,
+        subtitle: methodPath,
+        text: operationText(operation),
+        title: operation.summary || methodPath,
+        titles: [ir.info.title, group.name],
+        type: 'section',
+      })
+    }
+  }
+
+  return documents
+}
+
+/** Folds an operation's searchable content into a single plain-text string. */
+function operationText(operation: IrOperation): string {
+  const parts = [
+    `${operation.method} ${operation.path}`,
+    plainText(operation.description),
+    plainText(operation.summary),
+    ...operation.parameters
+      .filter((parameter) => !parameter.deprecated)
+      .map((parameter) => `${parameter.name} ${plainText(parameter.description)}`.trim()),
+    ...operation.responses.map((response) =>
+      `${response.status} ${plainText(response.description)}`.trim(),
+    ),
+  ]
+  return parts.filter(Boolean).join(' ').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Reduces a Markdown string to plain text suitable for the search index. Strips
+ * the common inline/block syntax (links, emphasis, code, headings, lists,
+ * blockquotes, images) so only human-readable words remain for tokenization.
+ */
+function plainText(markdown: string | undefined): string {
+  if (!markdown) return ''
+  return markdown
+    .replace(/```[\s\S]*?```/g, ' ') // fenced code blocks
+    .replace(/`([^`]+)`/g, '$1') // inline code
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1') // images → alt text
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // links → label
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '') // headings
+    .replace(/^\s{0,3}>\s?/gm, '') // blockquotes
+    .replace(/^\s*[-*+]\s+/gm, '') // unordered list markers
+    .replace(/[*_~]/g, '') // emphasis / strikethrough
+    .replace(/\s+/g, ' ')
+    .trim()
+}

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

@@ -0,0 +1,131 @@
+import { describe, expect, test } from 'vitest'
+import type { Ir } from './parser.js'
+import { methodVariant, toSidebar } from './sidebar.js'
+
+const ir: Ir = {
+  path: '/api',
+  client: { url: 'https://example.com/openapi.json' },
+  info: { title: 'Petstore' },
+  servers: [],
+  securitySchemes: {},
+  traits: [],
+  groups: [
+    {
+      id: 'pets',
+      name: 'pets',
+      operations: [
+        {
+          id: 'listpets',
+          method: 'GET',
+          path: '/pets',
+          summary: 'List pets',
+          parameters: [],
+          responses: [],
+        },
+        {
+          id: 'createpet',
+          method: 'POST',
+          path: '/pets',
+          parameters: [],
+          responses: [],
+        },
+      ],
+    },
+  ],
+}
+
+describe('toSidebar', () => {
+  test('groups are non-link headers; operations anchor onto per-category pages', () => {
+    expect(toSidebar(ir)).toEqual([
+      // Root "Introduction" links to the section landing page.
+      { text: 'Introduction', link: '/api' },
+      {
+        text: 'pets',
+        collapsed: false,
+        items: [
+          {
+            // The category itself is reached via an "Overview" entry; the
+            // top-level item is a non-link header.
+            text: 'Overview',
+            link: '/api/pets',
+          },
+          {
+            text: 'List pets',
+            link: '/api/pets#listpets',
+            badge: { text: 'GET', variant: 'info' },
+          },
+          {
+            // Falls back to "METHOD path" when there's no summary.
+            text: 'POST /pets',
+            link: '/api/pets#createpet',
+            badge: { text: 'POST', variant: 'success' },
+          },
+        ],
+      },
+    ])
+  })
+
+  test('nests intro items under the Introduction group', () => {
+    const sidebar = toSidebar(ir, {
+      intro: [
+        { text: 'Authentication', link: '/api/authentication' },
+        { text: 'Versioning', link: '/api/versioning' },
+      ],
+    })
+    expect(sidebar[0]).toEqual({
+      text: 'Introduction',
+      collapsed: false,
+      items: [
+        { text: 'Overview', link: '/api' },
+        { text: 'Authentication', link: '/api/authentication' },
+        { text: 'Versioning', link: '/api/versioning' },
+      ],
+    })
+  })
+
+  test('collapses generated category groups but not Introduction', () => {
+    const sidebar = toSidebar(ir, {
+      intro: [{ text: 'Authentication', link: '/api/authentication' }],
+      collapsed: true,
+    })
+    // Introduction stays expanded.
+    expect((sidebar[0] as { collapsed: boolean }).collapsed).toBe(false)
+    // Category groups start collapsed.
+    expect((sidebar[1] as { collapsed: boolean }).collapsed).toBe(true)
+  })
+
+  test('injects groupExtras after a group Overview link', () => {
+    const sidebar = toSidebar(ir, {
+      groupExtras: new Map([['pets', [{ text: 'Rate limits', link: '/api/rate-limits' }]]]),
+    })
+    expect(sidebar[1]).toEqual({
+      text: 'pets',
+      collapsed: false,
+      items: [
+        { text: 'Overview', link: '/api/pets' },
+        { text: 'Rate limits', link: '/api/rate-limits' },
+        {
+          text: 'List pets',
+          link: '/api/pets#listpets',
+          badge: { text: 'GET', variant: 'info' },
+        },
+        {
+          text: 'POST /pets',
+          link: '/api/pets#createpet',
+          badge: { text: 'POST', variant: 'success' },
+        },
+      ],
+    })
+  })
+})
+
+describe('methodVariant', () => {
+  test('maps methods to badge variants', () => {
+    expect(methodVariant('GET')).toBe('info')
+    expect(methodVariant('POST')).toBe('success')
+    expect(methodVariant('PUT')).toBe('warning')
+    expect(methodVariant('PATCH')).toBe('warning')
+    expect(methodVariant('DELETE')).toBe('danger')
+    expect(methodVariant('OPTIONS')).toBe('note')
+  })
+})

package/src/internal/openapi/sidebar.ts

@@ -0,0 +1,94 @@
+import type { SidebarItem } from '../sidebar.js'
+import type { Ir, IrOperation } from './parser.js'
+
+export type Badge = NonNullable<SidebarItem['badge']>
+export type BadgeVariant = NonNullable<Exclude<Badge, string>['variant']>
+
+/**
+ * Maps an HTTP method to a sidebar badge variant.
+ */
+export function methodVariant(method: string): BadgeVariant {
+  switch (method.toUpperCase()) {
+    case 'GET':
+      return 'info'
+    case 'POST':
+      return 'success'
+    case 'PUT':
+    case 'PATCH':
+      return 'warning'
+    case 'DELETE':
+      return 'danger'
+    default:
+      return 'note'
+  }
+}
+
+/**
+ * Builds an isolated sidebar (categories → operation anchors) from a parsed
+ * OpenAPI IR.
+ *
+ * Each category is its own page; operation links are in-page anchors on that
+ * page (`/api/{group}#{operation}`).
+ */
+export function toSidebar(ir: Ir, options: toSidebar.Options = {}): SidebarItem<true>[] {
+  // Strip a trailing slash so a root mount (`/`) doesn't yield `//group`.
+  const base = ir.path === '/' ? '' : ir.path.replace(/\/$/, '')
+  const operationLink = (operation: IrOperation, groupId: string) =>
+    `${base}/${groupId}#${operation.id}`
+
+  const groupLink = (groupId: string) => `${base}/${groupId}`
+
+  // When `intro` items are supplied, the "Introduction" leaf becomes a
+  // collapsible group: an "Overview" link to the landing page followed by the
+  // extra items (e.g. authentication/versioning guide pages).
+  const intro = options.intro ?? []
+  const introduction: SidebarItem<true> =
+    intro.length > 0
+      ? {
+          text: 'Introduction',
+          collapsed: false,
+          items: [{ text: 'Overview', link: ir.path }, ...intro] as SidebarItem<true>[],
+        }
+      : { text: 'Introduction', link: ir.path }
+
+  // Extra items (e.g. `x-parent` guide pages) injected into a group, keyed by
+  // group id, rendered after the group's "Overview" link.
+  const groupExtras = options.groupExtras ?? new Map<string, SidebarItem[]>()
+
+  // Generated category groups start collapsed when `collapsed` is set (the
+  // active group still auto-expands at render). `Introduction` is unaffected.
+  const groupCollapsed = options.collapsed ?? false
+
+  return [
+    introduction,
+    ...ir.groups.map((group) => ({
+      text: group.name,
+      collapsed: groupCollapsed,
+      items: [
+        // An "Overview" entry links to the category itself; the top-level item
+        // is a non-link header so its label doesn't compete with the operations.
+        { text: 'Overview', link: groupLink(group.id) },
+        ...((groupExtras.get(group.id) ?? []) as SidebarItem<true>[]),
+        ...group.operations.map((operation) => ({
+          text: operation.summary || `${operation.method} ${operation.path}`,
+          link: operationLink(operation, group.id),
+          badge: { text: operation.method, variant: methodVariant(operation.method) },
+        })),
+      ],
+    })),
+  ]
+}
+
+export declare namespace toSidebar {
+  type Options = {
+    /** Items nested under the generated `Introduction` entry. */
+    intro?: SidebarItem[] | undefined
+    /** Extra items injected into a generated group, keyed by group id. */
+    groupExtras?: Map<string, SidebarItem[]> | undefined
+    /**
+     * Collapse the generated category groups by default (the active group still
+     * auto-expands). `Introduction` is unaffected. @default false
+     */
+    collapsed?: boolean | undefined
+  }
+}

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

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'vitest'
+import { unionVariantSchemas, unwrapSingleVariant } from './union.js'
+
+describe('unwrapSingleVariant', () => {
+  test('unwraps a nullable object union to its sole member', () => {
+    const schema = {
+      description: 'Access-key provisioning authorization.',
+      oneOf: [
+        { title: 'Null', type: 'null' },
+        { type: 'object', properties: { keyId: { type: 'string' } } },
+      ],
+    }
+    expect(unwrapSingleVariant(schema)).toEqual({
+      type: 'object',
+      properties: { keyId: { type: 'string' } },
+      // the wrapper's description is preferred so field-level docs survive
+      description: 'Access-key provisioning authorization.',
+    })
+  })
+
+  test('prefers the member description when the wrapper has none', () => {
+    const schema = {
+      anyOf: [{ type: 'null' }, { type: 'object', description: 'inner' }],
+    }
+    expect(unwrapSingleVariant(schema)).toEqual({ type: 'object', description: 'inner' })
+  })
+
+  test('unwraps a single-member union without an explicit null', () => {
+    const schema = { oneOf: [{ type: 'object', properties: {} }] }
+    expect(unwrapSingleVariant(schema)).toEqual({ type: 'object', properties: {} })
+  })
+
+  test('returns undefined for two or more non-null members', () => {
+    const schema = {
+      oneOf: [{ type: 'null' }, { type: 'string' }, { type: 'number' }],
+    }
+    expect(unwrapSingleVariant(schema)).toBeUndefined()
+  })
+
+  test('returns undefined for non-unions', () => {
+    expect(unwrapSingleVariant({ type: 'object', properties: {} })).toBeUndefined()
+    expect(unwrapSingleVariant(undefined)).toBeUndefined()
+  })
+
+  test('does not collide with the variant picker (which needs >= 2 members)', () => {
+    const nullable = { oneOf: [{ type: 'null' }, { type: 'object', properties: {} }] }
+    // single non-null member: unwrapped, not shown as a picker
+    expect(unwrapSingleVariant(nullable)).toBeDefined()
+    expect(unionVariantSchemas(nullable)).toBeUndefined()
+  })
+})

package/src/internal/openapi/union.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared `oneOf`/`anyOf` union detection so the schema documentation rows (which
+ * render a variant picker) and the response example sampler (which samples one
+ * variant) agree on which variants exist and in what order. Keeping this
+ * framework-agnostic lets both the React renderer and the sample serializer
+ * derive identical variant-qualified anchor ids.
+ */
+
+type SchemaObject = Record<string, unknown>
+
+/**
+ * The displayable variant schemas of a union rendered as a variant picker, or
+ * `undefined` when the schema is not shown as a picker (no `oneOf`/`anyOf`,
+ * fewer than two non-null members, or a plain scalar union like `string |
+ * number` with nothing extra to show). Array schemas are unwrapped to their item
+ * schema first. The returned order is the index space used by
+ * {@link unionVariantSegment}.
+ */
+export function unionVariantSchemas(schema: SchemaObject | undefined): SchemaObject[] | undefined {
+  if (!schema) return undefined
+  const target =
+    schema['type'] === 'array' && schema['items'] ? (schema['items'] as SchemaObject) : schema
+  const oneOf = target['oneOf'] as SchemaObject[] | undefined
+  const members = (oneOf ?? target['anyOf']) as SchemaObject[] | undefined
+  if (!Array.isArray(members)) return undefined
+  const variants = members.filter(
+    (member) => member && typeof member === 'object' && member['type'] !== 'null',
+  )
+  if (variants.length < 2) return undefined
+  const rich = variants.some(
+    (member) =>
+      member['properties'] ||
+      member['allOf'] ||
+      typeof member['title'] === 'string' ||
+      Array.isArray(member['enum']) ||
+      'const' in member ||
+      typeof member['format'] === 'string',
+  )
+  if (!rich) return undefined
+  return variants
+}
+
+/** The path segment qualifying a union variant by its index (see {@link unionVariantSchemas}). */
+export function unionVariantSegment(index: number): string {
+  return `variant-${index}`
+}
+
+/**
+ * Returns the sole non-`null` member of a `oneOf`/`anyOf` union when the union
+ * has exactly one non-`null` member — the ubiquitous "nullable"/optional
+ * pattern, e.g. `oneOf: [{ type: 'null' }, { ...object }]`.
+ *
+ * Such a union is never shown as a variant picker (see
+ * {@link unionVariantSchemas}, which needs ≥2 non-null members), so without
+ * unwrapping it renders as a bare `null | object` type label with no expandable
+ * children. Callers resolve a schema through this first so the single member's
+ * type and nested properties surface instead. The wrapper's `description` wins
+ * over the member's so field-level docs are preserved.
+ *
+ * Returns `undefined` for non-unions or unions with 0 or ≥2 non-null members.
+ */
+export function unwrapSingleVariant(schema: SchemaObject | undefined): SchemaObject | undefined {
+  if (!schema) return undefined
+  const members = (schema['oneOf'] ?? schema['anyOf']) as SchemaObject[] | undefined
+  if (!Array.isArray(members)) return undefined
+  const nonNull = members.filter(
+    (member) => member && typeof member === 'object' && member['type'] !== 'null',
+  )
+  if (nonNull.length !== 1) return undefined
+  // biome-ignore lint/style/noNonNullAssertion: length checked above
+  const member = nonNull[0]!
+  const description = schema['description'] ?? member['description']
+  return description === undefined ? member : { ...member, description }
+}

package/src/internal/search.ts

@@ -15,6 +15,8 @@ import * as UnistUtil from 'unist-util-visit'
 import * as yaml from 'yaml'
 import type * as Config from './config.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 * as Sidebar from './sidebar.js'
@@ -92,9 +94,27 @@ export namespace SearchDocuments {
     const externalLinks = extractExternalLinks(config)
     allDocuments.push(...externalLinks)
 
+    const openapiDocuments = await fromOpenApi(config)
+    allDocuments.push(...openapiDocuments)
+
     return allDocuments
   }
 
+  /**
+   * Builds search documents for every configured OpenAPI section from its parsed
+   * IR, so the auto-generated reference is indexed alongside MDX pages. Failures
+   * are swallowed so a broken/unreachable spec can't break the whole index.
+   */
+  async function fromOpenApi(config: Config.Config): Promise<Document[]> {
+    if (!config.openapi || config.openapi.length === 0) return []
+    try {
+      const specs = await OpenApiRegistry.build(config)
+      return Object.values(specs).flatMap((ir) => OpenApiSearch.toSearchDocuments(ir))
+    } catch {
+      return []
+    }
+  }
+
   export function extractExternalLinks(config: Config.Config): Document[] {
     const documents: Document[] = []
     const seenHrefs = new Set<string>()

package/src/internal/test/virtual-config.stub.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime stub for the `virtual:vocs/config` module used in unit tests.
+ *
+ * The real module is provided by a Vite plugin at dev/build time, so it does not
+ * exist under vitest. Components that import it (e.g. `CodeToHtml`) only read
+ * `config` inside lazy, effect-driven code paths that never run during static
+ * rendering, so this minimal shape is enough to let those modules import.
+ */
+export const config = {
+  codeHighlight: {
+    langAlias: {},
+    themes: { light: 'github-light', dark: 'github-dark-dimmed' },
+  },
+}

package/src/internal/vite-plugins.ts

@@ -12,6 +12,8 @@ import * as Icons from './icons.js'
 import * as Langs from './langs.js'
 import * as Llms from './llms.js'
 import * as Mdx from './mdx.js'
+import type * as OpenApi from './openapi/index.js'
+import * as OpenApiRegistry from './openapi/registry.js'
 import { SearchDocuments, SearchIndex } from './search.js'
 import * as ShikiTransformers from './shiki-transformers.js'
 import * as TaskRunner from './task-runner.js'
@@ -174,8 +176,12 @@ export function llms(config: Config.Config): PluginOption {
   async function buildLlmsContent() {
     const pagesDir = path.resolve(viteConfig.root, config.srcDir, config.pagesDir)
     const pages = await Llms.getPagesFromDir(pagesDir)
+    const openapiPages = await Llms.getOpenApiPages(config)
+    // Generated OpenAPI pages first so they win over any consumer override at the
+    // same generated route (`.md` serves the full reference); authored-only guide
+    // pages under the section keep their own content.
     return Llms.buildLlmsContent({
-      pages,
+      pages: [...openapiPages, ...pages],
       title,
       description,
       rehypePlugins,
@@ -777,7 +783,7 @@ export function virtualConfig(config: Config.Config): PluginOption {
     },
     load(id) {
       if (id === resolvedVirtualModuleId) {
-        const currentConfig = Config.getGlobal() ?? config
+        const currentConfig = OpenApiRegistry.mergeSidebar(Config.getGlobal() ?? config)
         const serializedConfig =
           mode === 'development' ? { ...currentConfig, baseUrl: undefined } : currentConfig
         return `export const config = ${ConfigSerializer.serialize(serializedConfig)}`
@@ -816,26 +822,30 @@ export function virtualLangs(config: Config.Config): PluginOption {
           return 'export const langs = []'
         }
 
-        const imports: string[] = []
-        const langExports: string[] = []
+        const langIds = new Set<string>()
 
         for (let i = 0; i < transformers.length; i++) {
           const t = transformers[i]
           if (t && 'langs' in t && Array.isArray(t.langs) && t.langs.length > 0) {
-            const langIds = t.langs
-              .map((l: { name?: string }) => l.name)
-              .filter(Boolean) as string[]
-            for (const langId of langIds) {
-              imports.push(`import ${langId}Lang from 'shiki/langs/${langId}.mjs'`)
-              langExports.push(`...${langId}Lang`)
+            for (const lang of t.langs) {
+              if (lang.name) langIds.add(lang.name)
             }
           }
         }
 
-        if (!imports.length) {
+        if (!langIds.size) {
           return 'export const langs = []'
         }
 
+        const imports: string[] = []
+        const langExports: string[] = []
+        let index = 0
+        for (const langId of langIds) {
+          const importName = `lang${index++}`
+          imports.push(`import ${importName} from 'shiki/langs/${langId}.mjs'`)
+          langExports.push(`...${importName}`)
+        }
+
         return `${imports.join('\n')}\nexport const langs = [${langExports.join(', ')}]`
       }
       return
@@ -1082,3 +1092,88 @@ export { matchIcon, resolveIcon, resolveIconSync } from './icons.js'
     },
   }
 }
+
+/**
+ * Vite plugin that parses configured OpenAPI specs and exposes them as a
+ * virtual module (`virtual:vocs/openapi`).
+ *
+ * The module exports `specs`, a map of mount path to parsed
+ * {@link OpenApi.Ir | intermediate representation}, consumed by the OpenAPI
+ * route component and sidebar generator.
+ *
+ * Local spec files are watched in dev: changes invalidate the module and
+ * trigger a full reload so the section regenerates.
+ */
+export function openapi(config: Config.Config): PluginOption {
+  const virtualModuleId = 'virtual:vocs/openapi'
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`
+
+  /** Resolve absolute paths of local file specs for dev watching. */
+  function specFilePaths(currentConfig: Config.Config): string[] {
+    const paths: string[] = []
+    for (const entry of currentConfig.openapi ?? []) {
+      const { spec } = entry
+      if (typeof spec !== 'string') continue
+      if (spec.startsWith('http://') || spec.startsWith('https://')) continue
+      paths.push(path.isAbsolute(spec) ? spec : path.resolve(currentConfig.rootDir, spec))
+    }
+    return paths
+  }
+
+  return {
+    name: 'vocs:openapi',
+    enforce: 'pre',
+    async buildStart() {
+      // Parse specs up front so generated sidebars are available when the
+      // `virtual:vocs/config` module is serialized.
+      try {
+        await OpenApiRegistry.build(Config.getGlobal() ?? config)
+      } catch (error) {
+        this.error(
+          `Failed to parse OpenAPI spec: ${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+    },
+    resolveId(id) {
+      if (id === virtualModuleId) return resolvedVirtualModuleId
+      return
+    },
+    configureServer(server) {
+      server.watcher.on('change', async (changedPath) => {
+        const currentConfig = Config.getGlobal() ?? config
+        if (!specFilePaths(currentConfig).includes(changedPath)) return
+
+        // Re-parse before reloading so the new sidebar + page are ready.
+        OpenApiRegistry.invalidate()
+        try {
+          await OpenApiRegistry.build(currentConfig)
+        } catch {}
+
+        for (const moduleId of [resolvedVirtualModuleId, '\0virtual:vocs/config']) {
+          const mod = server.moduleGraph.getModuleById(moduleId)
+          if (mod) server.moduleGraph.invalidateModule(mod)
+        }
+        server.ws.send({ type: 'full-reload' })
+      })
+    },
+    async load(id) {
+      if (id !== resolvedVirtualModuleId) return
+
+      const currentConfig = Config.getGlobal() ?? config
+
+      // Watch local spec files so the build re-runs when they change.
+      for (const filePath of specFilePaths(currentConfig)) this.addWatchFile(filePath)
+
+      let specs: Record<string, OpenApi.Ir> = {}
+      try {
+        specs = await OpenApiRegistry.build(currentConfig)
+      } catch (error) {
+        this.error(
+          `Failed to parse OpenAPI spec: ${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+
+      return `export const specs = ${JSON.stringify(specs)}`
+    },
+  }
+}