vocs 2.0.17 → 2.1.2

package/src/internal/markdown-negotiation.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared user-agent lists and content negotiation used to decide whether a
+ * request for a documentation route should be served as Markdown instead of
+ * HTML. Consumed by the Waku `.md` router middleware and the standalone
+ * `Handler.openApi` server so both honor the same rules.
+ */
+
+/** AI crawlers/agents that should receive Markdown. */
+export const aiUserAgents = [
+  'GPTBot',
+  'OAI-SearchBot',
+  'ChatGPT-User',
+  'ChatGPT-User/2.0',
+  'anthropic-ai',
+  'ClaudeBot',
+  'claude-web',
+  'PerplexityBot',
+  'Perplexity-User',
+  'Google-Extended',
+  'FacebookBot',
+  'meta-externalagent',
+  'Bytespider',
+  'cohere-ai',
+  'AI2Bot',
+  'CCBot',
+  'Diffbot',
+  'omgili',
+  'Timpibot',
+  'MistralAI-User',
+  'GoogleAgent-Mariner',
+]
+
+/** Search engine crawlers that should always receive HTML. */
+export const searchEngineUserAgents = [
+  'Googlebot',
+  'Bingbot',
+  'Amazonbot',
+  'Applebot',
+  'Applebot-Extended',
+  'DuckAssistBot',
+  'YouBot',
+]
+
+/** Terminal HTTP clients that should receive Markdown. */
+export const terminalUserAgents = ['curl/', 'Wget/', 'HTTPie/', 'httpie-go/', 'xh/']
+
+/** Link-preview/Open Graph bots that must always receive HTML (for meta tags). */
+export const ogBotUserAgents = [
+  'Discordbot',
+  'Embedly',
+  'Facebot',
+  'Iframely',
+  'LinkedInBot',
+  'Pinterestbot',
+  'Slackbot',
+  'Slurp',
+  'TelegramBot',
+  'Twitterbot',
+  'WhatsApp',
+  'facebookexternalhit',
+]
+
+/**
+ * Decides whether a route request should be served as Markdown.
+ *
+ * Resolution order (matches the `.md` router middleware):
+ * 1. Open Graph bots never get Markdown (they need HTML meta tags).
+ * 2. An explicit `.md` suffix always serves Markdown.
+ * 3. Search engines otherwise always get HTML.
+ * 4. AI agents, terminal clients, or `Accept: text/markdown` get Markdown.
+ * 5. Everything else gets HTML.
+ */
+export function prefersMarkdown(options: prefersMarkdown.Options): boolean {
+  const { pathname, userAgent = '', accept = '' } = options
+
+  if (ogBotUserAgents.some((agent) => userAgent.includes(agent))) return false
+  if (pathname.endsWith('.md')) return true
+  if (searchEngineUserAgents.some((agent) => userAgent.includes(agent))) return false
+
+  const isAiAgent = aiUserAgents.some((agent) => userAgent.includes(agent))
+  const isTerminal = terminalUserAgents.some((agent) => userAgent.includes(agent))
+  const acceptsMarkdown = accept.includes('text/markdown')
+  return isAiAgent || isTerminal || acceptsMarkdown
+}
+
+export declare namespace prefersMarkdown {
+  type Options = {
+    /** Request pathname (used to detect an explicit `.md` suffix). */
+    pathname: string
+    /** Request `User-Agent` header. */
+    userAgent?: string | undefined
+    /** Request `Accept` header. */
+    accept?: string | undefined
+  }
+}

package/src/internal/markdown.ts

@@ -1,5 +1,6 @@
 import type * as Hast from 'hast'
 import type * as Mdast from 'mdast'
+import rehypeSlug from 'rehype-slug'
 import rehypeStringify from 'rehype-stringify'
 import remarkGfm from 'remark-gfm'
 import remarkParse from 'remark-parse'
@@ -160,6 +161,10 @@ const processor = unified()
   .use(remarkGfm)
   .use(remarkGitHubCallouts)
   .use(remarkRehype, { allowDangerousHtml: true })
+  // Add `id`s to headings so the outline (which scans `[data-v-content]
+  // :is(h2..h6)[id]`) and heading anchors work on guide/trait pages and on
+  // rendered spec descriptions, matching the MDX pipeline.
+  .use(rehypeSlug)
   .use(rehypeVocsAttrs)
   .use(rehypeTableWrapper)
   .use(rehypeCalloutIcons)

package/src/internal/openapi/anchors.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared id/path helpers that keep the left-hand schema documentation rows and
+ * the right-hand response example lines pointing at the same anchor ids. Both
+ * sides derive an element id from a schema "path" (the chain of property names
+ * leading to a value, e.g. `['data', 'items', 'id']`) plus an `idBase` that
+ * scopes the path to a specific operation section (a request body or a single
+ * response status).
+ */
+
+/** A chain of property names identifying a value within a schema. */
+export type SchemaPath = readonly string[]
+
+/** Slugifies a path segment / title into a URL-safe id fragment. */
+export function slug(value: string): string {
+  const result = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return result || 'value'
+}
+
+/** Id base for an operation's request body schema rows. */
+export function requestBodyIdBase(operationId: string): string {
+  return `${operationId}-request-body`
+}
+
+/** Id base for a single response status's schema rows. */
+export function responseIdBase(operationId: string, status: string): string {
+  return `${operationId}-response-${slug(status)}`
+}
+
+/**
+ * Qualifies an id base by media type when a section exposes more than one media
+ * type, so colliding paths across media types resolve to distinct ids. With a
+ * single media type the base is returned unchanged (shorter, stable ids).
+ */
+export function mediaIdBase(base: string, mediaType: string, mediaCount: number): string {
+  return mediaCount > 1 ? `${base}-${slug(mediaType)}` : base
+}
+
+/** The element id for a schema property at `path` within `idBase`. */
+export function schemaPropertyId(idBase: string, path: SchemaPath): string {
+  return `${idBase}-${slug(path.join('.'))}`
+}

package/src/internal/openapi/app.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared types for the prebuilt OpenAPI app (the `Handler.openApi` server
+ * handler and the static browser bundle it serves).
+ *
+ * This module is intentionally free of Node and DOM dependencies so it can be
+ * imported by both the server handler and the client entry.
+ */
+
+import type { Config } from '../config.js'
+import type { SidebarItem } from '../sidebar.js'
+import { normalizePath } from './openapi.js'
+import type { Ir } from './parser.js'
+
+/**
+ * A block of rendered page content. Guide/override pages are compiled on the
+ * server into an ordered list of blocks so embedded `<OpenApi.Endpoints />`
+ * components can be re-hydrated as real React on the client (rather than
+ * inlined as static HTML).
+ */
+export type PageBlock =
+  | { type: 'html'; html: string }
+  | { type: 'endpoints'; path?: string | undefined }
+
+/**
+ * A compiled consumer-authored page, keyed by its section-relative route.
+ *
+ * - `path === '/'` overrides the landing/intro content.
+ * - `path === '/<group>'` overrides a category header.
+ * - any other `path` is a standalone guide page.
+ */
+export type CompiledPage = {
+  /** Section-relative route (normalized, leading slash, no trailing slash). */
+  path: string
+  /** Document title (frontmatter `title` or first `# heading`). */
+  title?: string | undefined
+  /** Subtitle Markdown rendered below the title on guide pages. */
+  description?: string | undefined
+  /**
+   * Render `title`/`description` as an on-page header above the content. Set for
+   * trait pages (`x-traitTag`), whose title comes from the tag name and subtitle
+   * from `x-subtitle` (their Markdown body has no heading). Authored guide pages
+   * leave this unset because their MDX owns its own headings.
+   */
+  header?: boolean | undefined
+  /** Ordered content blocks. */
+  blocks: PageBlock[]
+  /**
+   * Raw authored Markdown (frontmatter + ESM import/export lines stripped), used
+   * to serve the page's `.md` / agent-facing version. Absent for trait pages
+   * compiled from a description that is already the body.
+   */
+  markdown?: string | undefined
+}
+
+/**
+ * The JSON payload embedded in the standalone HTML shell and consumed by the
+ * browser bundle to render the reference entirely client-side.
+ */
+export type Payload = {
+  /** Parsed OpenAPI IR. */
+  ir: Ir
+  /** Document title (spec `info.title`). */
+  title: string
+  /** Computed sidebar (extras + generated items). */
+  sidebar: SidebarItem<true>[]
+  /** Compiled override/guide pages. */
+  pages: CompiledPage[]
+  /**
+   * Serialized Vocs config that backs `virtual:vocs/config` in the browser
+   * bundle, so the prebuilt app renders the real Vocs layout/chrome. Functions
+   * are serialized via {@link file://../config-serializer.ts config-serializer};
+   * the client deserializes them on load.
+   */
+  config: Config
+}
+
+/** Joins a section base path with a section-relative sub-path. */
+export function join(base: string, sub: string): string {
+  const b = base === '/' ? '' : base
+  if (!sub || sub === '/') return b || '/'
+  return `${b}${sub.startsWith('/') ? sub : `/${sub}`}`
+}
+
+/**
+ * The set of known section routes for a payload: the intro (the spec `path`),
+ * one per category, and one per compiled page.
+ */
+export function knownRoutes(payload: Payload): string[] {
+  const base = payload.ir.path || '/'
+  const routes = new Set<string>()
+  routes.add(base === '/' ? '/' : normalizePath(base))
+  for (const group of payload.ir.groups) routes.add(join(base, `/${group.id}`))
+  for (const page of payload.pages) routes.add(join(base, page.path))
+  return [...routes]
+}
+
+/**
+ * Infers the host mount prefix from a request pathname: the longest known
+ * section route that is a path-suffix of `pathname` is stripped; whatever
+ * precedes it is the mount (e.g. `/docs/pets` with route `/pets` → `/docs`).
+ * Falls back to treating the whole pathname as the mount (the intro page).
+ */
+export function inferMount(pathname: string, routes: string[]): string {
+  const path = stripTrailingSlash(pathname)
+  let mount = ''
+  let best = -1
+  for (const route of routes) {
+    if (route === '/') continue
+    if (path === route || path.endsWith(route)) {
+      const prefix = path.slice(0, path.length - route.length)
+      if (route.length > best && (prefix === '' || prefix.startsWith('/'))) {
+        best = route.length
+        mount = prefix
+      }
+    }
+  }
+  // No group/page route matched: we're on the intro/landing page, so the whole
+  // pathname is the mount. A root mount (`/`) has no prefix, though — return ''
+  // so callers build `/group` rather than `//group` (a protocol-relative URL the
+  // browser reads as `http://group/`).
+  if (best === -1) return path === '/' ? '' : path
+  return mount
+}
+
+function stripTrailingSlash(value: string): string {
+  return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value
+}

package/src/internal/openapi/index.ts

@@ -0,0 +1,24 @@
+export type { SchemaPath } from './anchors.js'
+export {
+  mediaIdBase,
+  requestBodyIdBase,
+  responseIdBase,
+  schemaPropertyId,
+  slug,
+} from './anchors.js'
+export * from './openapi.js'
+export type {
+  Ir,
+  IrBody,
+  IrGroup,
+  IrMediaType,
+  IrOperation,
+  IrParameter,
+  IrResponse,
+  IrSecurityScheme,
+  IrServer,
+  Method,
+} from './parser.js'
+export { methods, parse } from './parser.js'
+export type { CodeSample, ResponseSample } from './sample.js'
+export { codeSamples, harRequest, responseSamples } from './sample.js'

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

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'vitest'
+import { fromIr } from './markdown.js'
+import type { Ir } from './parser.js'
+
+const ir: Ir = {
+  path: '/api',
+  client: { url: 'https://example.com/openapi.json' },
+  info: { title: 'Petstore', version: '1.0.0', description: 'The **best** pet API.' },
+  servers: [{ url: 'https://example.com', description: 'Production' }],
+  securitySchemes: {},
+  traits: [],
+  groups: [
+    {
+      id: 'pets',
+      name: 'Pets',
+      description: 'Manage pets.',
+      operations: [
+        {
+          id: 'listpets',
+          method: 'GET',
+          path: '/pets',
+          summary: 'List pets',
+          description: 'Returns all pets.',
+          parameters: [
+            { name: 'limit', in: 'query', description: 'Max items', schema: { type: 'integer' } },
+            { name: 'cursor', in: 'query', deprecated: true },
+          ],
+          responses: [
+            {
+              status: '200',
+              description: 'A list of pets',
+              headers: [
+                { name: 'X-Total', schema: { type: 'integer' }, description: 'Total count' },
+              ],
+              content: [
+                {
+                  mediaType: 'application/json',
+                  schema: {
+                    type: 'object',
+                    required: ['data'],
+                    properties: {
+                      data: { type: 'array', items: { type: 'object' }, description: 'Pets.' },
+                    },
+                  },
+                },
+              ],
+            },
+          ],
+        },
+        {
+          id: 'createpet',
+          method: 'POST',
+          path: '/pets',
+          summary: 'Create pet',
+          parameters: [],
+          requestBody: {
+            required: true,
+            content: [
+              {
+                mediaType: 'application/json',
+                schema: {
+                  type: 'object',
+                  required: ['name'],
+                  properties: { name: { type: 'string', description: 'Pet name.' } },
+                },
+              },
+            ],
+          },
+          responses: [{ status: '201', description: 'Created', content: [], headers: [] }],
+        },
+      ],
+    },
+  ],
+}
+
+describe('fromIr', () => {
+  const pages = fromIr(ir)
+
+  test('emits an overview page and one page per category', () => {
+    expect(pages.map((page) => ({ path: page.path, title: page.title }))).toEqual([
+      { path: '/api', title: 'Petstore' },
+      { path: '/api/pets', title: 'Pets' },
+    ])
+  })
+
+  test('overview lists every category with links to its operations', () => {
+    const overview = pages.find((page) => page.path === '/api')
+    expect(overview?.content).toContain('# Petstore')
+    expect(overview?.content).toContain('Version: `1.0.0`')
+    expect(overview?.content).toContain('## Servers')
+    expect(overview?.content).toContain('## Endpoints')
+    expect(overview?.content).toContain('### Pets')
+    expect(overview?.content).toContain('- [`GET /pets`](/api/pets#listpets): List pets')
+  })
+
+  test('category page renders params, request body, responses and samples', () => {
+    const group = pages.find((page) => page.path === '/api/pets')
+    const content = group?.content ?? ''
+    expect(content).toContain('## List pets')
+    expect(content).toContain('`GET /pets`')
+    expect(content).toContain('### Query parameters')
+    expect(content).toContain('- `limit` `integer`: Max items')
+    // Deprecated parameters are excluded.
+    expect(content).not.toContain('cursor')
+    expect(content).toContain('### Responses')
+    expect(content).toContain('#### `200`: A list of pets')
+    expect(content).toContain('- `X-Total` `integer`: Total count')
+    expect(content).toContain('- `data` `object[]` _(required)_: Pets.')
+    expect(content).toContain('### Request body (required) (`application/json`)')
+    expect(content).toContain('- `name` `string` _(required)_: Pet name.')
+    expect(content).toContain('### Example request')
+    expect(content).toContain('```bash')
+    expect(content).toContain('curl')
+  })
+})