@panomc/client-gen 0.0.0-stage → 1.0.0-dev.61

package/src/golden/mini/types.js

@@ -0,0 +1,59 @@
+// Generated by pano-client from openapi.json. Do not edit; run pano-client again.
+
+/**
+ * Who wrote a post.
+ * @typedef {Object} Author
+ * @property {string | null} [avatar] Head image url.
+ * @property {number} id
+ * @property {string} username
+ */
+
+/** @typedef {Author & { extra?: number }} Combined */
+
+/**
+ * @typedef {Object} ErrorEnvelope
+ * @property {{ code: string, fields?: Record<string, string>, message?: string }} error
+ */
+
+/**
+ * @typedef {Object} PageInfo
+ * @property {number} number
+ * @property {number} size
+ * @property {number} totalItems
+ * @property {number} totalPages
+ */
+
+/** @typedef {{ author: Author, body?: string | Author, id: number, image?: string | null, meta?: Record<string, string>, status: 'DRAFT' | 'PUBLISHED', tags?: string[], title: string, 'x-extra'?: boolean }} Post */
+
+/**
+ * @typedef {Object} PostInput
+ * @property {number} [categoryId]
+ * @property {string} [text]
+ * @property {string} title
+ */
+
+/**
+ * @typedef {Object} PostPage
+ * @property {Post[]} items
+ * @property {PageInfo} page
+ */
+
+/** @typedef {'UP' | 'DOWN'} Status */
+
+/** @typedef {Post} CreatePostResponse */
+
+/** @typedef {PostInput} CreatePostRequest */
+
+/** @typedef {void} DeletePostResponse */
+
+/** @typedef {Blob} GetApiV1ExportByKindResponse */
+
+/** @typedef {any} GetLegacyThingResponse */
+
+/** @typedef {Post} GetPostResponse */
+
+/** @typedef {PostPage} GetPostsResponse */
+
+/** @typedef {{ url: string }} UploadAvatarResponse */
+
+export {};

package/src/http.js

@@ -0,0 +1,58 @@
+import { ClientGenError } from './errors.js'
+
+/**
+ * @typedef {Object} Fetched
+ * @property {number} status
+ * @property {boolean} ok
+ * @property {string} text
+ */
+
+/** @param {string} url */
+export function trimBase(url) {
+  return String(url).trim().replace(/\/+$/, '')
+}
+
+/**
+ * GET a URL as text. A network failure throws `onUnreachable()`'s message; any HTTP status is returned.
+ * @param {string} url
+ * @param {{ fetch?: typeof fetch, onUnreachable: () => string }} opts
+ * @returns {Promise<Fetched>}
+ */
+export async function getText(url, opts) {
+  const doFetch = opts.fetch ?? globalThis.fetch
+  let res
+  try {
+    res = await doFetch(url, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(20_000), redirect: 'follow' })
+  } catch {
+    throw new ClientGenError(opts.onUnreachable())
+  }
+  let text = ''
+  try {
+    text = await res.text()
+  } catch {
+    throw new ClientGenError(opts.onUnreachable())
+  }
+  return { status: res.status, ok: res.ok, text }
+}
+
+/** @param {string} base */
+export const unreachableMessage = (base) =>
+  `Pano did not answer at ${base}/api/v1/openapi.json. Is it running? Try --url http://localhost:8088`
+
+/**
+ * @param {string} text
+ * @param {string} what
+ */
+export function parseJson(text, what) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new ClientGenError(`${what} is not valid JSON.`)
+  }
+}
+
+/** Plugin ids and namespaces end up in URLs and file names. @param {string} s */
+export const isSafeName = (s) => typeof s === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(s) && !s.includes('..')
+
+/** Namespace rule of doc 01: the id minus a leading `pano-plugin-`. @param {string} pluginId */
+export const namespaceOf = (pluginId) => (pluginId.startsWith('pano-plugin-') ? pluginId.slice('pano-plugin-'.length) : pluginId)

package/src/index.js

@@ -0,0 +1,6 @@
+export { generateClient } from './generate.js'
+export { pull } from './pull.js'
+export { check } from './check.js'
+export { scaffold, STARTER_TARBALL } from './new.js'
+export { canonicalJson, shortHash } from './canonical.js'
+export { ClientGenError } from './errors.js'

package/src/new.js

@@ -0,0 +1,115 @@
+// new: copy the starter template, write .env, bun install (doc 06 §2.4, §5.1).
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
+import { ClientGenError } from './errors.js'
+import { trimBase } from './http.js'
+
+/** Where the starter comes from when --from is not given. */
+export const STARTER_TARBALL = 'https://codeload.github.com/PanoMC/pano-starter-sveltekit/tar.gz/refs/heads/main'
+
+const SKIP = new Set(['node_modules', '.git', 'build', '.svelte-kit', '.DS_Store'])
+
+/**
+ * @typedef {Object} NewOptions
+ * @property {string} dir
+ * @property {string} [url]        Pano address; written to .env as API_URL=<url>/api
+ * @property {string} [from]       local template directory (default: download the starter)
+ * @property {boolean} [install]   run `bun install` (default true)
+ * @property {string} [cwd]
+ * @property {typeof fetch} [fetch]
+ * @property {(dir: string) => { ok: boolean, message?: string }} [installer]  replaces the `bun install` call (tests)
+ * @property {(line: string) => void} [log]
+ */
+
+/** @param {string} dir */
+function isEmptyDir(dir) {
+  return !existsSync(dir) || (statSync(dir).isDirectory() && readdirSync(dir).length === 0)
+}
+
+/** @param {string} url @param {typeof fetch | undefined} doFetch @returns {Promise<string>} directory with the extracted template */
+async function downloadStarter(url, doFetch) {
+  const tmp = mkdtempSync(join(tmpdir(), 'pano-starter-'))
+  let res
+  try {
+    res = await (doFetch ?? globalThis.fetch)(url, { redirect: 'follow', signal: AbortSignal.timeout(60_000) })
+  } catch {
+    throw new ClientGenError(`Could not download the starter from ${url}. Check your connection or pass --from <dir>.`)
+  }
+  if (!res.ok) throw new ClientGenError(`Could not download the starter from ${url} (HTTP ${res.status}). Pass --from <dir> instead.`)
+  const archive = join(tmp, 'starter.tar.gz')
+  writeFileSync(archive, new Uint8Array(await res.arrayBuffer()))
+  const extracted = join(tmp, 'tree')
+  mkdirSync(extracted)
+  const r = spawnSync('tar', ['-xzf', archive, '-C', extracted, '--strip-components=1'], { encoding: 'utf8' })
+  if (r.status !== 0) throw new ClientGenError(`Could not unpack the starter archive: ${(r.stderr || r.error?.message || '').trim()}`)
+  return extracted
+}
+
+/** @param {string} dir */
+function defaultInstaller(dir) {
+  const r = spawnSync('bun', ['install'], { cwd: dir, stdio: 'inherit' })
+  if (r.error) return { ok: false, message: r.error.message }
+  return { ok: r.status === 0, message: `exit code ${r.status}` }
+}
+
+/**
+ * @param {NewOptions} options
+ * @returns {Promise<{ dir: string, installed: boolean }>}
+ */
+export async function scaffold(options) {
+  if (!options.dir) throw new ClientGenError('new needs a directory, e.g. pano-client new my-site')
+  const cwd = resolve(options.cwd ?? process.cwd())
+  const target = resolve(cwd, options.dir)
+  const log = options.log ?? (() => {})
+  if (!isEmptyDir(target)) throw new ClientGenError(`${target} already exists and is not empty.`)
+
+  let source
+  let cleanup = null
+  if (options.from) {
+    source = resolve(cwd, options.from)
+    if (!existsSync(source) || !statSync(source).isDirectory()) throw new ClientGenError(`--from ${source} is not a directory.`)
+  } else {
+    source = await downloadStarter(process.env.PANO_STARTER_URL || STARTER_TARBALL, options.fetch)
+    cleanup = join(source, '..')
+  }
+
+  try {
+    mkdirSync(target, { recursive: true })
+    cpSync(source, target, { recursive: true, filter: (src) => !SKIP.has(basename(src)) })
+  } finally {
+    if (cleanup) rmSync(cleanup, { recursive: true, force: true })
+  }
+
+  // package name from the folder
+  const pkgPath = join(target, 'package.json')
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      const name = basename(target).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+/, '')
+      if (name) {
+        pkg.name = name
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+      }
+    } catch {}
+  }
+
+  // .env from .env.example, API_URL from --url
+  const examplePath = join(target, '.env.example')
+  let env = existsSync(examplePath) ? readFileSync(examplePath, 'utf8') : 'API_URL=http://localhost:8088/api\n'
+  if (options.url) {
+    const apiUrl = `${trimBase(options.url).replace(/\/api$/, '')}/api`
+    env = /^API_URL=.*$/m.test(env) ? env.replace(/^API_URL=.*$/m, `API_URL=${apiUrl}`) : `API_URL=${apiUrl}\n${env}`
+  }
+  if (!existsSync(join(target, '.env'))) writeFileSync(join(target, '.env'), env)
+  log(`created ${target}`)
+
+  let installed = false
+  if (options.install !== false) {
+    const r = (options.installer ?? defaultInstaller)(target)
+    if (!r.ok) throw new ClientGenError(`bun install failed in ${target} (${r.message ?? 'unknown error'}). The project is created; run bun install there yourself.`)
+    installed = true
+  }
+  return { dir: target, installed }
+}

package/src/new.test.js

@@ -0,0 +1,106 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { run } from './cli.js'
+import { ClientGenError } from './errors.js'
+import { scaffold } from './new.js'
+import { tmp } from './test-helpers.js'
+
+const dirs = []
+afterAll(() => dirs.forEach((d) => rmSync(d, { recursive: true, force: true })))
+
+/** a tiny template with the shape of the starter: .env.example, a build script, ignored folders */
+function template() {
+  const t = tmp('tpl')
+  dirs.push(t)
+  writeFileSync(
+    join(t, 'package.json'),
+    JSON.stringify({ name: 'pano-starter-sveltekit', private: true, scripts: { build: "bun -e \"require('fs').writeFileSync('built.txt','ok')\"" } }, null, 2)
+  )
+  writeFileSync(join(t, '.env.example'), '# Where Pano answers.\nAPI_URL=http://localhost:8088/api\nPANO_FRONTEND_KEY=\n')
+  mkdirSync(join(t, 'src/lib/pano'), { recursive: true })
+  writeFileSync(join(t, 'src/lib/pano/index.json'), '{}')
+  for (const skipped of ['node_modules', '.git', 'build', '.svelte-kit']) {
+    mkdirSync(join(t, skipped), { recursive: true })
+    writeFileSync(join(t, skipped, 'x'), 'x')
+  }
+  return t
+}
+
+describe('new', () => {
+  test('--from copies the template, names the package, writes .env, runs bun install, and the tree builds', async () => {
+    const t = template()
+    const cwd = tmp('new')
+    dirs.push(cwd)
+    const outs = []
+    const code = await run(['new', 'my-site', '--from', t], { cwd, stdout: (s) => outs.push(s), stderr: () => {} })
+    expect(code).toBe(0)
+    const site = join(cwd, 'my-site')
+    expect(JSON.parse(readFileSync(join(site, 'package.json'), 'utf8')).name).toBe('my-site')
+    expect(readFileSync(join(site, '.env'), 'utf8')).toBe(readFileSync(join(t, '.env.example'), 'utf8'))
+    expect(existsSync(join(site, 'src/lib/pano/index.json'))).toBe(true)
+    for (const skipped of ['.git', 'build', '.svelte-kit']) expect(existsSync(join(site, skipped))).toBe(false)
+    expect(existsSync(join(site, 'bun.lock')) || existsSync(join(site, 'bun.lockb')) || existsSync(join(site, 'node_modules'))).toBe(true)
+    expect(outs.at(-1)).toBe('\nNext: cd my-site && bun dev')
+
+    const build = Bun.spawnSync(['bun', 'run', 'build'], { cwd: site })
+    expect(build.exitCode).toBe(0)
+    expect(readFileSync(join(site, 'built.txt'), 'utf8')).toBe('ok')
+  })
+
+  test('--url rewrites API_URL (the /api suffix is added once)', async () => {
+    const t = template()
+    const cwd = tmp('new-url')
+    dirs.push(cwd)
+    await scaffold({ dir: 'a', from: t, cwd, install: false, url: 'https://pano.example.com/' })
+    await scaffold({ dir: 'b', from: t, cwd, install: false, url: 'http://localhost:9000/api' })
+    expect(readFileSync(join(cwd, 'a/.env'), 'utf8')).toContain('API_URL=https://pano.example.com/api\n')
+    expect(readFileSync(join(cwd, 'a/.env'), 'utf8')).toContain('PANO_FRONTEND_KEY=\n')
+    expect(readFileSync(join(cwd, 'b/.env'), 'utf8')).toContain('API_URL=http://localhost:9000/api\n')
+  })
+
+  test('refuses a directory that is not empty, and a missing template', async () => {
+    const t = template()
+    const cwd = tmp('new-refuse')
+    dirs.push(cwd)
+    mkdirSync(join(cwd, 'taken'))
+    writeFileSync(join(cwd, 'taken/file'), 'x')
+    await expect(scaffold({ dir: 'taken', from: t, cwd, install: false })).rejects.toThrow(`${join(cwd, 'taken')} already exists and is not empty.`)
+    await expect(scaffold({ dir: 'z', from: join(cwd, 'nope'), cwd, install: false })).rejects.toThrow('is not a directory')
+    await expect(scaffold({ dir: '', from: t, cwd })).rejects.toBeInstanceOf(ClientGenError)
+  })
+
+  test('a failing install keeps the project and says what to do', async () => {
+    const t = template()
+    const cwd = tmp('new-install')
+    dirs.push(cwd)
+    await expect(scaffold({ dir: 's', from: t, cwd, installer: () => ({ ok: false, message: 'exit code 1' }) })).rejects.toThrow(
+      `bun install failed in ${join(cwd, 's')} (exit code 1). The project is created; run bun install there yourself.`
+    )
+    expect(existsSync(join(cwd, 's/.env'))).toBe(true)
+  })
+
+  test('without --from the starter is downloaded (stubbed fetch + tarball)', async () => {
+    const t = template()
+    const cwd = tmp('new-dl')
+    dirs.push(cwd)
+    const tarDir = tmp('tar')
+    dirs.push(tarDir)
+    // GitHub tarballs have one top folder
+    const tar = join(tarDir, 's.tar.gz')
+    Bun.spawnSync(['tar', '-czf', tar, '-C', join(t, '..'), '--transform', 's,^[^/]*,pano-starter-main,', t.split('/').pop()])
+    const bytes = readFileSync(tar)
+    let asked = ''
+    const fakeFetch = async (/** @type {string} */ url) => {
+      asked = url
+      return new Response(bytes)
+    }
+    await scaffold({ dir: 'dl', cwd, install: false, fetch: /** @type {any} */ (fakeFetch) })
+    expect(asked).toContain('pano-starter-sveltekit')
+    expect(JSON.parse(readFileSync(join(cwd, 'dl/package.json'), 'utf8')).name).toBe('dl')
+    expect(existsSync(join(cwd, 'dl/.env'))).toBe(true)
+
+    const failing = async () => new Response('no', { status: 404 })
+    await expect(scaffold({ dir: 'dl2', cwd, install: false, fetch: /** @type {any} */ (failing) })).rejects.toThrow('Pass --from <dir> instead.')
+  })
+})

package/src/operations.js

@@ -0,0 +1,244 @@
+// Reads the operations of an OpenAPI document: names, parameters, bodies, responses, fingerprints.
+import { canonicalJson } from './canonical.js'
+
+export const METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch']
+
+const RESERVED = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum',
+  'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return',
+  'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield', 'let', 'static',
+  'implements', 'interface', 'package', 'private', 'protected', 'public', 'arguments', 'eval', 'operations'
+])
+
+/** @param {string} s */
+const upperFirst = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s)
+/** @param {string} s */
+const lowerFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s)
+
+/** `get-posts`, `get_posts`, `GetPosts` -> `GetPosts` / `GetPosts` @param {string} s */
+export function pascal(s) {
+  const parts = s.split(/[^A-Za-z0-9]+/).filter(Boolean)
+  return parts.map(upperFirst).join('')
+}
+
+/** Name for an operation without operationId: `<method><PascalPath>`. @param {string} method @param {string} path */
+export function fallbackId(method, path) {
+  const segments = path
+    .split('/')
+    .filter(Boolean)
+    .map((seg) => {
+      const m = /^\{(.+)\}$/.exec(seg)
+      return m ? 'By' + pascal(m[1]) : pascal(seg)
+    })
+  return method.toLowerCase() + segments.join('')
+}
+
+/**
+ * @param {any} doc
+ * @param {string} ref
+ */
+function resolveRef(doc, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) return undefined
+  let node = doc
+  for (const part of ref.slice(2).split('/')) {
+    if (node === null || typeof node !== 'object') return undefined
+    node = node[part.replace(/~1/g, '/').replace(/~0/g, '~')]
+  }
+  return node
+}
+
+/** Follows a single level of `$ref` for parameters, request bodies and responses. @param {any} doc @param {any} node */
+function deref(doc, node) {
+  let n = node
+  for (let i = 0; i < 8 && n && typeof n === 'object' && typeof n.$ref === 'string'; i++) n = resolveRef(doc, n.$ref)
+  return n
+}
+
+/**
+ * @typedef {Object} Operation
+ * @property {string} id            operationId (or the generated fallback)
+ * @property {string} name          function name in index.js
+ * @property {string} method        upper case
+ * @property {string} path         the request path: server prefix plus `docPath`
+ * @property {string} docPath       the key in `paths`
+ * @property {'none'|'user'} auth
+ * @property {boolean} mutation
+ * @property {boolean} deprecated
+ * @property {boolean} undocumented
+ * @property {string} summary
+ * @property {string} description
+ * @property {{ name: string, in: string, required: boolean, schema: any, description: string }[]} parameters
+ * @property {{ required: boolean, kind: 'json'|'form'|'other', schema: any } | null} body
+ * @property {{ kind: 'void'|'json'|'text'|'blob', schema: any }} response
+ * @property {any} raw
+ */
+
+/** @param {any} security */
+function authOf(security) {
+  if (!Array.isArray(security) || security.length === 0) return 'none'
+  return security.some((s) => s && typeof s === 'object' && Object.keys(s).length === 0) ? 'none' : 'user'
+}
+
+/**
+ * The path part of the first usable server (`/api/plugins/pano-plugin-market`, `/api/v1`), without a trailing slash;
+ * `''` for none, `/` or an absolute URL without a path. An operation's `servers` wins over its path item's, and
+ * that over the document's (OpenAPI 3.1).
+ * @param {any} servers
+ */
+export function serverPrefix(servers) {
+  const first = Array.isArray(servers) ? servers.find((s) => s && typeof s.url === 'string') : undefined
+  if (!first) return ''
+  let url = first.url
+  const absolute = /^[a-z][a-z0-9+.-]*:\/\/[^/]*/i.exec(url)
+  if (absolute) url = url.slice(absolute[0].length)
+  return url.startsWith('/') ? url.replace(/\/+$/, '') : ''
+}
+
+/** The request path of an operation: the server prefix plus the document path (not doubled when already there). */
+function joinServerPath(prefix, path) {
+  if (!prefix || path === prefix || path.startsWith(`${prefix}/`)) return path
+  return `${prefix}${path}`
+}
+
+/**
+ * Collects every operation of the document, sorted by function name.
+ * @param {any} doc
+ * @param {(message: string) => void} [warn]
+ * @returns {Operation[]}
+ */
+export function collectOperations(doc, warn = () => {}) {
+  /** @type {Operation[]} */
+  const list = []
+  const paths = doc && typeof doc.paths === 'object' && doc.paths ? doc.paths : {}
+
+  for (const path of Object.keys(paths).sort()) {
+    const item = paths[path]
+    if (!item || typeof item !== 'object') continue
+    for (const method of METHODS) {
+      const raw = item[method]
+      if (!raw || typeof raw !== 'object') continue
+
+      let id = typeof raw.operationId === 'string' && raw.operationId ? raw.operationId : ''
+      if (!id) {
+        id = fallbackId(method, path)
+        warn(`${method.toUpperCase()} ${path} has no operationId, using "${id}"`)
+      }
+
+      let name = lowerFirst(id.includes('-') || id.includes('_') || id.includes(' ') || id.includes('.') ? pascal(id) : id.replace(/[^A-Za-z0-9_$]/g, ''))
+      if (!name || /^[0-9]/.test(name)) name = 'op' + upperFirst(name)
+      if (RESERVED.has(name)) name += 'Operation'
+
+      /** @type {Map<string, any>} */
+      const params = new Map()
+      for (const p of [...(Array.isArray(item.parameters) ? item.parameters : []), ...(Array.isArray(raw.parameters) ? raw.parameters : [])]) {
+        const r = deref(doc, p)
+        if (r && typeof r === 'object' && typeof r.name === 'string') params.set(`${r.in}:${r.name}`, r)
+      }
+      const parameters = [...params.values()]
+        .filter((p) => p.in === 'path' || p.in === 'query')
+        .map((p) => ({
+          name: p.name,
+          in: p.in,
+          required: p.in === 'path' ? true : p.required === true,
+          schema: p.schema ?? (p.content?.['application/json']?.schema ?? {}),
+          description: typeof p.description === 'string' ? p.description : ''
+        }))
+      // placeholders in the path that the document forgot to declare
+      for (const m of path.matchAll(/\{([^}]+)\}/g)) {
+        if (!parameters.some((p) => p.in === 'path' && p.name === m[1])) {
+          parameters.push({ name: m[1], in: 'path', required: true, schema: { type: 'string' }, description: '' })
+        }
+      }
+      parameters.sort((a, b) => (a.in === b.in ? a.name.localeCompare(b.name) : a.in === 'path' ? -1 : 1))
+
+      const undocumented = raw['x-pano-undocumented'] === true || raw['x-pano-undocumented'] === 'true'
+
+      /** @type {Operation['body']} */
+      let body = null
+      const rb = deref(doc, raw.requestBody)
+      if (rb && typeof rb === 'object') {
+        const content = rb.content && typeof rb.content === 'object' ? rb.content : {}
+        const jsonKey = Object.keys(content).find((k) => /^application\/(.+\+)?json/.test(k))
+        const formKey = Object.keys(content).find((k) => k.startsWith('multipart/form-data'))
+        if (jsonKey) body = { required: rb.required === true, kind: 'json', schema: content[jsonKey].schema ?? {} }
+        else if (formKey) body = { required: rb.required === true, kind: 'form', schema: null }
+        else body = { required: rb.required === true, kind: 'other', schema: null }
+      }
+
+      /** @type {Operation['response']} */
+      let response = { kind: 'void', schema: null }
+      const responses = raw.responses && typeof raw.responses === 'object' ? raw.responses : {}
+      const okKey = Object.keys(responses).filter((k) => /^2/.test(k)).sort()[0]
+      if (okKey !== undefined) {
+        const r = deref(doc, responses[okKey])
+        const content = r && typeof r.content === 'object' && r.content ? r.content : {}
+        const keys = Object.keys(content)
+        const jsonKey = keys.find((k) => /^application\/(.+\+)?json/.test(k))
+        if (jsonKey) response = { kind: 'json', schema: content[jsonKey].schema ?? {} }
+        else if (keys.some((k) => k.startsWith('text/'))) response = { kind: 'text', schema: null }
+        else if (keys.length) response = { kind: 'blob', schema: null }
+      } else if (Object.keys(responses).length) {
+        response = { kind: 'json', schema: {} }
+      }
+
+      list.push({
+        id,
+        name,
+        method: method.toUpperCase(),
+        path: joinServerPath(serverPrefix(raw.servers ?? item.servers ?? doc.servers), path),
+        docPath: path,
+        auth: authOf(raw.security !== undefined ? raw.security : doc.security),
+        mutation: !['get', 'head', 'options'].includes(method),
+        deprecated: raw.deprecated === true,
+        undocumented,
+        summary: typeof raw.summary === 'string' ? raw.summary : '',
+        description: typeof raw.description === 'string' ? raw.description : '',
+        parameters,
+        body,
+        response,
+        raw
+      })
+    }
+  }
+
+  // unique function names, deterministic: the later one in (path, method) order gets a number
+  const used = new Set()
+  for (const op of list) {
+    let name = op.name
+    for (let n = 2; used.has(name); n++) name = `${op.name}${n}`
+    if (name !== op.name) warn(`${op.method} ${op.path}: operation name "${op.name}" is taken, using "${name}"`)
+    op.name = name
+    used.add(name)
+  }
+  return list.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+}
+
+/**
+ * Operation object with every `$ref` replaced by its target (cycles stay as `$ref`), canonical text.
+ * Two documents with the same fingerprint for an operation describe the same request and response types.
+ * @param {any} doc
+ * @param {Operation} op
+ */
+export function fingerprint(doc, op) {
+  /** @param {any} node @param {string[]} stack @returns {any} */
+  const inline = (node, stack) => {
+    if (Array.isArray(node)) return node.map((n) => inline(n, stack))
+    if (!node || typeof node !== 'object') return node
+    if (typeof node.$ref === 'string') {
+      if (stack.includes(node.$ref)) return { $ref: node.$ref }
+      const target = resolveRef(doc, node.$ref)
+      return target === undefined ? { $ref: node.$ref } : inline(target, [...stack, node.$ref])
+    }
+    /** @type {Record<string, any>} */
+    const out = {}
+    for (const k of Object.keys(node)) out[k] = inline(node[k], stack)
+    return out
+  }
+  const pathItem = doc.paths?.[op.docPath ?? op.path] ?? {}
+  return canonicalJson({
+    method: op.method,
+    path: op.path,
+    pathParameters: inline(pathItem.parameters ?? [], []),
+    operation: inline(op.raw, [])
+  })
+}

package/src/operations.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test'
+import { collectOperations, serverPrefix } from './operations.js'
+
+const get = { operationId: 'Thing', responses: { 200: { description: 'ok' } } }
+
+describe('server prefix of an operation path', () => {
+  test('serverPrefix reads the path of a relative or absolute server url', () => {
+    expect(serverPrefix([{ url: '/api/plugins/pano-plugin-market/' }])).toBe('/api/plugins/pano-plugin-market')
+    expect(serverPrefix([{ url: 'https://pano.test/api/v1' }])).toBe('/api/v1')
+    expect(serverPrefix([{ url: '/' }])).toBe('')
+    expect(serverPrefix(undefined)).toBe('')
+  })
+
+  test('the document server prefixes every path', () => {
+    const [op] = collectOperations({ servers: [{ url: '/api/plugins/pano-plugin-market' }], paths: { '/store/products': { get } } })
+    expect(op.path).toBe('/api/plugins/pano-plugin-market/store/products')
+    expect(op.docPath).toBe('/store/products')
+  })
+
+  test('an operation-level servers entry overrides the document server (internal document panel routes)', () => {
+    const doc = {
+      servers: [{ url: '/api/v1' }],
+      paths: {
+        '/posts': { get },
+        '/plugins/pano-plugin-market/panel/products': { get: { ...get, operationId: 'Panel', servers: [{ url: '/api' }] } }
+      }
+    }
+    const byId = Object.fromEntries(collectOperations(doc).map((o) => [o.id, o.path]))
+    expect(byId.Thing).toBe('/api/v1/posts')
+    expect(byId.Panel).toBe('/api/plugins/pano-plugin-market/panel/products')
+  })
+
+  test('a path that already carries the prefix is not doubled', () => {
+    const [op] = collectOperations({ servers: [{ url: '/api/v1' }], paths: { '/api/v1/posts': { get } } })
+    expect(op.path).toBe('/api/v1/posts')
+  })
+})