vocs 2.0.17 → 2.1.2

package/src/internal/openapi/registry.ts

@@ -0,0 +1,89 @@
+import type { Config } from '../config.js'
+import type { SidebarItem } from '../sidebar.js'
+import { type Ir, parse } from './parser.js'
+import * as Sidebar from './sidebar.js'
+
+type Specs = Record<string, Ir>
+
+let cache: Specs | null = null
+let building: Promise<Specs> | null = null
+
+/**
+ * Parses all configured OpenAPI specs into IRs, memoized across plugins and
+ * Vite environments. Call {@link invalidate} to force a re-parse (e.g. when a
+ * local spec file changes).
+ */
+export async function build(config: Config): Promise<Specs> {
+  if (cache) return cache
+  if (building) return building
+
+  building = (async () => {
+    const next: Specs = {}
+    for (const entry of config.openapi ?? [])
+      next[entry.path] = await parse(entry, { rootDir: config.rootDir })
+    cache = next
+    building = null
+    return next
+  })()
+
+  return building
+}
+
+/** Returns the cached specs, or `null` if not yet built. */
+export function peek(): Specs | null {
+  return cache
+}
+
+/** Clears the cache so the next {@link build} re-parses. */
+export function invalidate(): void {
+  cache = null
+  building = null
+}
+
+/**
+ * Returns the OpenAPI-generated sidebars keyed by mount path, derived from the
+ * cached IRs. Empty if specs haven't been built yet or none are configured.
+ */
+export function sidebars(
+  config?: Config,
+): Record<string, { backLink: boolean; items: SidebarItem<true>[] }> {
+  const result: Record<string, { backLink: boolean; items: SidebarItem<true>[] }> = {}
+  if (!cache) return result
+  for (const [path, ir] of Object.entries(cache)) {
+    const collapsed = config?.openapi?.find((entry) => entry.path === path)?.sidebar?.collapsed
+    result[path] = { backLink: true, items: Sidebar.toSidebar(ir, { collapsed }) }
+  }
+  return result
+}
+
+/**
+ * Merges OpenAPI-generated sidebars into a user's `sidebar` config.
+ *
+ * Returns the original config unchanged when no OpenAPI sidebars exist.
+ * Array-form sidebars are converted to path-keyed form (under `/`) so the
+ * OpenAPI section can be scoped to its own mount path.
+ *
+ * Per-entry `sidebar.top` / `sidebar.bottom` items (links to consumer guide
+ * pages mounted under the same path) are prepended/appended around the
+ * generated items. Never mutates inputs.
+ */
+export function mergeSidebar(config: Config): Config {
+  const generated = sidebars(config)
+  if (Object.keys(generated).length === 0) return config
+
+  const userSidebar = config.sidebar
+
+  let merged: Record<string, unknown>
+  if (!userSidebar) merged = {}
+  else if (Array.isArray(userSidebar)) merged = { '/': userSidebar }
+  else merged = { ...userSidebar }
+
+  for (const [path, sidebar] of Object.entries(generated)) {
+    const entry = config.openapi?.find((candidate) => candidate.path === path)
+    const top = entry?.sidebar?.top ?? []
+    const bottom = entry?.sidebar?.bottom ?? []
+    merged[path] = { ...sidebar, items: [...top, ...sidebar.items, ...bottom] }
+  }
+
+  return { ...config, sidebar: merged as Config['sidebar'] }
+}

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

@@ -0,0 +1,283 @@
+import { describe, expect, test } from 'vitest'
+import type { IrOperation } from './parser.js'
+import { codeSamples, harRequest, responseSamples } from './sample.js'
+
+const operation: IrOperation = {
+  id: 'createpet',
+  method: 'POST',
+  path: '/pets/{petId}',
+  parameters: [
+    { name: 'petId', in: 'path', required: true, schema: { type: 'string' } },
+    { name: 'limit', in: 'query', required: true, schema: { type: 'integer' } },
+    { name: 'dryRun', in: 'query', schema: { type: 'boolean' } },
+  ],
+  requestBody: {
+    content: [
+      {
+        mediaType: 'application/json',
+        schema: {
+          type: 'object',
+          properties: { name: { type: 'string' }, age: { type: 'integer' } },
+        },
+      },
+    ],
+  },
+  responses: [
+    {
+      status: '200',
+      description: 'A pet',
+      content: [
+        {
+          mediaType: 'application/json',
+          schema: { type: 'object', properties: { id: { type: 'string' } } },
+        },
+      ],
+      headers: [],
+    },
+    { status: '404', description: 'Not found', content: [], headers: [] },
+  ],
+}
+
+describe('harRequest', () => {
+  test('fills path params, required query/body, and resolves the server', () => {
+    const request = harRequest(operation, 'https://api.example.com/')
+    expect(request.method).toBe('POST')
+    expect(request.url).toBe('https://api.example.com/pets/string')
+    // All non-deprecated query params are included (required and optional).
+    expect(request.queryString).toEqual([
+      { name: 'limit', value: '0' },
+      { name: 'dryRun', value: 'true' },
+    ])
+    expect(request.postData?.mimeType).toBe('application/json')
+    expect(JSON.parse(request.postData?.text ?? '{}')).toEqual({ name: 'string', age: 0 })
+    expect(request.headers).toContainEqual({ name: 'Content-Type', value: 'application/json' })
+  })
+})
+
+describe('codeSamples', () => {
+  test('generates cURL and TypeScript fetch snippets', () => {
+    const samples = codeSamples(operation, 'https://api.example.com')
+    expect(samples.map((sample) => sample.id)).toEqual(['shell/curl', 'js/fetch'])
+    const curl = samples.find((sample) => sample.id === 'shell/curl')
+    expect(curl?.lang).toBe('bash')
+    expect(curl?.code).toContain('curl')
+    expect(curl?.code).toContain('https://api.example.com/pets/string')
+    const ts = samples.find((sample) => sample.id === 'js/fetch')
+    expect(ts?.label).toBe('TypeScript')
+    expect(ts?.lang).toBe('ts')
+  })
+
+  test('anchors query parameters to their schema rows per line', () => {
+    const samples = codeSamples(operation, 'https://api.example.com')
+    const curl = samples.find((sample) => sample.id === 'shell/curl')
+    // Each query parameter is on its own line, so the whole line is anchored.
+    const lineIds = (curl?.lineAnchors ?? []).filter(Boolean)
+    expect(lineIds).toContain('createpet-limit')
+    expect(lineIds).toContain('createpet-dryrun')
+    // The anchored line indices correspond to the `?limit`/`&dryRun` lines.
+    const lines = curl?.display.split('\n') ?? []
+    curl?.lineAnchors.forEach((id, index) => {
+      if (id) expect(lines[index]?.trim()).toMatch(/^'?[?&]/)
+    })
+  })
+
+  test('color-codes query parameter names and values', () => {
+    const samples = codeSamples(operation, 'https://api.example.com')
+    const curl = samples.find((sample) => sample.id === 'shell/curl')
+    const ranges = curl?.colorRanges ?? []
+    // Each query param contributes a `key` (name) and a `value` range.
+    const display = curl?.display ?? ''
+    const keys = ranges.filter((r) => r.kind === 'key').map((r) => display.slice(...r.range))
+    const values = ranges.filter((r) => r.kind === 'value').map((r) => display.slice(...r.range))
+    // The key range includes the leading `?`/`&` separator so it's colored too.
+    expect(keys).toContain('?limit')
+    expect(keys).toContain('&dryRun')
+    expect(values).toContain('0')
+    expect(values).toContain('true')
+  })
+
+  test('places each query parameter on its own line', () => {
+    const samples = codeSamples(operation, 'https://api.example.com')
+    const curl = samples.find((sample) => sample.id === 'shell/curl')
+    // Copy text stays single-line/valid; the display variant is broken up.
+    expect(curl?.code).toContain('?limit=0&dryRun=true')
+    expect(curl?.display).toContain('\n  ?limit=0')
+    expect(curl?.display).toContain('\n  &dryRun=true')
+    const ts = samples.find((sample) => sample.id === 'js/fetch')
+    expect(ts?.display).toContain("'?limit=0'")
+    expect(ts?.display).toContain("'&dryRun=true'")
+  })
+
+  test('collapses query parameters beyond the first 2', () => {
+    const many: IrOperation = {
+      ...operation,
+      parameters: [
+        { name: 'a', in: 'query', schema: { type: 'string' } },
+        { name: 'b', in: 'query', schema: { type: 'string' } },
+        { name: 'c', in: 'query', schema: { type: 'string' } },
+        { name: 'd', in: 'query', schema: { type: 'string' } },
+        { name: 'e', in: 'query', schema: { type: 'string' } },
+      ],
+    }
+    const curl = codeSamples(many).find((sample) => sample.id === 'shell/curl')
+    expect(curl?.hiddenQueryCount).toBe(3)
+    // Collapsed variant has the first 2 query params, full has all 5.
+    expect(curl?.collapsed?.display).toContain('?a=')
+    expect(curl?.collapsed?.display).toContain('&b=')
+    expect(curl?.collapsed?.display).not.toContain('&c=')
+    expect(curl?.display).toContain('&e=')
+  })
+
+  test('does not collapse 2 or fewer query parameters', () => {
+    const curl = codeSamples(operation).find((sample) => sample.id === 'shell/curl')
+    expect(curl?.collapsed).toBeUndefined()
+    expect(curl?.hiddenQueryCount).toBeUndefined()
+  })
+})
+
+describe('responseSamples', () => {
+  test('builds JSON samples only for responses with a JSON schema/example', () => {
+    const samples = responseSamples(operation)
+    expect(samples.map((sample) => sample.status)).toEqual(['200'])
+    expect(samples[0]?.lang).toBe('json')
+    expect(JSON.parse(samples[0]?.code ?? '{}')).toEqual({ id: 'string' })
+  })
+
+  test('marks synthesized placeholder values via offset ranges', () => {
+    const samples = responseSamples(operation)
+    const sample = samples[0]
+    expect(sample?.placeholders).toHaveLength(1)
+    const [start, end] = sample?.placeholders[0] ?? [0, 0]
+    expect(sample?.code.slice(start, end)).toBe('"string"')
+  })
+
+  test('authored examples have no placeholders', () => {
+    const samples = responseSamples({
+      ...operation,
+      responses: [
+        {
+          status: '200',
+          description: 'A pet',
+          content: [{ mediaType: 'application/json', example: { id: 'abc' } }],
+          headers: [],
+        },
+      ],
+    })
+    expect(samples[0]?.placeholders).toEqual([])
+    expect(JSON.parse(samples[0]?.code ?? '{}')).toEqual({ id: 'abc' })
+  })
+
+  test('exposes a status-scoped id base for anchor resolution', () => {
+    const samples = responseSamples(operation)
+    expect(samples[0]?.idBase).toBe('createpet-response-200')
+  })
+
+  test('records per-line schema paths for nested objects and arrays', () => {
+    const samples = responseSamples({
+      ...operation,
+      responses: [
+        {
+          status: '200',
+          description: 'ok',
+          content: [
+            {
+              mediaType: 'application/json',
+              schema: {
+                type: 'object',
+                properties: {
+                  data: {
+                    type: 'object',
+                    properties: {
+                      items: {
+                        type: 'array',
+                        items: { type: 'object', properties: { id: { type: 'string' } } },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          ],
+          headers: [],
+        },
+      ],
+    })
+    const sample = samples[0]
+    const lines = sample?.code.split('\n') ?? []
+    const paths = sample?.linePaths ?? []
+    // Find the line for the nested `id` and assert its recorded path.
+    const idLine = lines.findIndex((line) => line.includes('"id"'))
+    expect(paths[idLine]).toEqual(['data', 'items', 'id'])
+    // The `data` opening line maps to `['data']`.
+    const dataLine = lines.findIndex((line) => line.includes('"data"'))
+    expect(paths[dataLine]).toEqual(['data'])
+    // Closing braces carry no path.
+    const closingLine = lines.length - 1
+    expect(paths[closingLine]).toBeUndefined()
+  })
+
+  test('qualifies union variant paths so they match the variant picker rows', () => {
+    const samples = responseSamples({
+      ...operation,
+      responses: [
+        {
+          status: '200',
+          description: 'ok',
+          content: [
+            {
+              mediaType: 'application/json',
+              schema: {
+                type: 'object',
+                properties: {
+                  data: {
+                    type: 'array',
+                    items: {
+                      anyOf: [
+                        {
+                          title: 'Transfer',
+                          type: 'object',
+                          properties: { amount: { type: 'string' } },
+                        },
+                        {
+                          title: 'Mint',
+                          type: 'object',
+                          properties: { supply: { type: 'string' } },
+                        },
+                      ],
+                    },
+                  },
+                },
+              },
+            },
+          ],
+          headers: [],
+        },
+      ],
+    })
+    const sample = samples[0]
+    const lines = sample?.code.split('\n') ?? []
+    const paths = sample?.linePaths ?? []
+    // The sampled variant (index 0) qualifies its children with `variant-0`.
+    const amountLine = lines.findIndex((line) => line.includes('"amount"'))
+    expect(paths[amountLine]).toEqual(['data', 'variant-0', 'amount'])
+  })
+
+  test('authored examples still record per-line schema paths', () => {
+    const samples = responseSamples({
+      ...operation,
+      responses: [
+        {
+          status: '200',
+          description: 'ok',
+          content: [{ mediaType: 'application/json', example: { id: 'abc', nested: { x: 1 } } }],
+          headers: [],
+        },
+      ],
+    })
+    const sample = samples[0]
+    const lines = sample?.code.split('\n') ?? []
+    const paths = sample?.linePaths ?? []
+    const xLine = lines.findIndex((line) => line.includes('"x"'))
+    expect(paths[xLine]).toEqual(['nested', 'x'])
+  })
+})