@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/api/spec.ts

@@ -0,0 +1,624 @@
+import { XMLParser } from "fast-xml-parser"
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+import YAML from "yaml"
+
+import { exampleFor } from "./schema.ts"
+import type { Contract, ContractSet, JsonSchema, KeyField, SourceKind } from "./types.ts"
+
+/**
+ * Contracts from an API description, given as a link or a file: OpenAPI 3 or Swagger 2 (JSON or YAML, or the Swagger UI
+ * page that shows one), WSDL for SOAP, a GraphQL endpoint (read by introspection), an introspection result or SDL file,
+ * and .proto files or a gRPC server with reflection (through grpcurl). One contract per operation, with an example call
+ * from the description's examples, and the status, schema, and fields its answer must have.
+ */
+
+export type Fetcher = (url: string, init?: RequestInit) => Promise<Response>
+export type LoadOptions = { headers?: Record<string, string>; fetch?: Fetcher; include?: string[]; grpcurl?: (args: string[], input?: string) => Promise<{ ok: boolean; out: string }> }
+
+type Loaded = { kind: SourceKind; name: string; baseUrl: string; contracts: Contract[]; skipped: string[] }
+
+const READ_NAME = /^(get|list|find|search|query|read|fetch|lookup|check|validate|describe|count|is|has)/i
+const KEY_NAME = /(^|_|\b)(id|uuid|key|code|status|state|type|kind|name|title|total|count|amount|price|currency|email|success|result)$/i
+const METHODS = ["get", "post", "put", "patch", "delete", "head", "options"]
+
+export const isUrl = (s: string) => /^https?:\/\//i.test(s)
+
+async function getText(ref: string, opts: LoadOptions): Promise<{ text: string; url?: string; type: string }> {
+  if (!isUrl(ref)) {
+    const file = path.resolve(ref)
+    if (!existsSync(file)) throw new Error(`No such file or link: ${ref}`)
+    return { text: readFileSync(file, "utf8"), type: "" }
+  }
+  const res = await (opts.fetch || fetch)(ref, { headers: { Accept: "application/json, application/yaml, text/yaml, application/xml, text/xml, */*", ...(opts.headers || {}) } })
+  if (!res.ok) throw new Error(`${ref} answered HTTP ${res.status}`)
+  return { text: await res.text(), url: res.url || ref, type: res.headers.get("content-type") || "" }
+}
+
+/** Load an API description from a link or file and write a contract for each of its operations. */
+export async function loadSpec(ref: string, opts: LoadOptions = {}): Promise<Loaded> {
+  const src = ref.trim()
+  if (/^grpcs?:\/\//i.test(src)) return grpcReflection(src, opts)
+  if (/\.proto$/i.test(src)) return fromProto([src], opts)
+  if (isUrl(src) && /\/graphql\/?(\?.*)?$/i.test(src)) return graphqlEndpoint(src, opts)
+  const { text, url, type } = await getText(src, opts)
+  const base = url || src
+  const t = text.trim()
+  if (/html/i.test(type) || /^<!doctype html|^<html/i.test(t)) return fromSwaggerUi(base, t, opts)
+  if (t.startsWith("<")) {
+    if (/definitions|description/.test(t.slice(0, 2000)) && /wsdl|schemas\.xmlsoap\.org/i.test(t.slice(0, 4000))) return fromWsdl(t, base, opts)
+    throw new Error(`${src} is XML but not a WSDL document.`)
+  }
+  if (/^\s*(syntax\s*=|package\s+[\w.]+;|service\s+\w+\s*{)/m.test(t) && /\brpc\s+\w+/.test(t)) return fromProto([src], opts, t)
+  let doc: unknown
+  try {
+    doc = t.startsWith("{") || t.startsWith("[") ? JSON.parse(t) : YAML.parse(t)
+  } catch {
+    doc = undefined
+  }
+  const d = doc as Record<string, any> | undefined
+  if (d && (d.openapi || d.swagger)) return fromOpenApi(d, base, opts)
+  if (d && (d.__schema || d.data?.__schema)) return fromIntrospection(d.data?.__schema || d.__schema, "", base, opts)
+  if (/\btype\s+(Query|Mutation)\b|\bschema\s*{/.test(t)) return fromSdl(t, base, opts)
+  throw new Error(`Could not tell what kind of API description ${src} is. ForgeQE reads OpenAPI or Swagger (JSON or YAML), WSDL, GraphQL (an endpoint, an introspection result, or SDL), and .proto files.`)
+}
+
+/** A contract set from a description. */
+export async function setFromSpec(ref: string, id: string, opts: LoadOptions & { name?: string; baseUrl?: string } = {}): Promise<ContractSet> {
+  const loaded = await loadSpec(ref, opts)
+  const include = (opts.include || []).map((s) => s.toLowerCase()).filter(Boolean)
+  const contracts = include.length ? loaded.contracts.filter((c) => include.some((i) => `${c.id} ${c.name}`.toLowerCase().includes(i))) : loaded.contracts
+  return {
+    version: 1,
+    id,
+    name: opts.name || loaded.name,
+    baseUrl: opts.baseUrl || loaded.baseUrl,
+    createdAt: new Date().toISOString(),
+    source: { kind: loaded.kind, ref },
+    contracts,
+    ...(loaded.skipped.length ? { skipped: loaded.skipped } : {}),
+  }
+}
+
+// -- OpenAPI and Swagger ------------------------------------------------------------------------
+
+/** Swagger UI's page: find the description it shows (its config, the initializer script, or the usual paths). */
+async function fromSwaggerUi(pageUrl: string, html: string, opts: LoadOptions): Promise<Loaded> {
+  const found = (text: string) => [...text.matchAll(/\burls?\s*[:=]\s*\[?\s*{?\s*(?:url\s*:\s*)?["'`]([^"'`]+\.(?:json|ya?ml)[^"'`]*|[^"'`]*api-docs[^"'`]*)["'`]/g)].map((m) => m[1])
+  const candidates = found(html)
+  for (const s of html.matchAll(/<script[^>]+src=["']([^"']*(?:initializer|swagger-config)[^"']*)["']/g)) {
+    try {
+      candidates.push(...found((await getText(new URL(s[1], pageUrl).href, opts)).text))
+    } catch {}
+  }
+  candidates.push("swagger.json", "openapi.json", "v1/swagger.json", "../swagger/v1/swagger.json", "/v3/api-docs", "/v2/api-docs", "/openapi.json", "/swagger.json")
+  for (const c of candidates) {
+    const url = new URL(c, pageUrl.endsWith("/") || /\.html?$/.test(pageUrl) ? pageUrl : `${pageUrl}/`).href
+    try {
+      const { text } = await getText(url, opts)
+      const d = text.trim().startsWith("{") ? JSON.parse(text) : YAML.parse(text)
+      if (d && (d.openapi || d.swagger)) return fromOpenApi(d, url, opts)
+    } catch {}
+  }
+  throw new Error(`${pageUrl} is a web page, and no OpenAPI or Swagger document was found behind it. Give the link to the JSON or YAML document itself.`)
+}
+
+function deref(node: any, root: any, seen: string[] = []): any {
+  if (!node || typeof node !== "object") return node
+  if (Array.isArray(node)) return node.map((n) => deref(n, root, seen))
+  if (typeof node.$ref === "string") {
+    const ref = node.$ref as string
+    if (!ref.startsWith("#/") || seen.includes(ref) || seen.length > 12) return {}
+    const target = ref
+      .slice(2)
+      .split("/")
+      .map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"))
+      .reduce((o: any, k) => (o ? o[k] : undefined), root)
+    return deref(target, root, [...seen, ref])
+  }
+  const out: any = {}
+  for (const [k, v] of Object.entries(node)) out[k] = k === "example" || k === "examples" ? v : deref(v, root, seen)
+  return out
+}
+
+/** OpenAPI's schema object as ForgeQE's schema: nullable, x-nullable, and type lists. */
+function toSchema(s: any): JsonSchema | undefined {
+  if (!s || typeof s !== "object") return undefined
+  const out: JsonSchema = {}
+  if (s.type) out.type = s.type
+  if (s.nullable || s["x-nullable"]) out.nullable = true
+  if (Array.isArray(s.type) && s.type.includes("null")) out.nullable = true
+  if (s.enum) out.enum = s.enum
+  if (s.format) out.format = s.format
+  if (s.example !== undefined) out.example = s.example
+  if (s.required && Array.isArray(s.required)) out.required = s.required
+  if (s.properties) out.properties = Object.fromEntries(Object.entries(s.properties).map(([k, v]) => [k, toSchema(v) || {}]))
+  if (s.items) out.items = toSchema(s.items)
+  for (const k of ["anyOf", "oneOf", "allOf"] as const) if (Array.isArray(s[k])) out[k] = s[k].map((x: any) => toSchema(x) || {})
+  if (!out.type && out.properties) out.type = "object"
+  return out
+}
+
+/** Fields to check from a response schema: required scalars named like ids, statuses, names, totals; their type only. */
+export function schemaFields(schema: JsonSchema | undefined, max = 8): KeyField[] {
+  if (!schema) return []
+  const out: KeyField[] = []
+  const walk = (s: JsonSchema, at: string, depth: number) => {
+    if (depth > 3 || out.length >= max) return
+    if (s.allOf) for (const x of s.allOf) walk(x, at, depth)
+    const t = Array.isArray(s.type) ? s.type[0] : s.type
+    if ((t === "array" || s.items) && s.items) return walk(s.items, `${at}[0]`, depth + 1)
+    const req = new Set(s.required || [])
+    for (const [k, p] of Object.entries(s.properties || {})) {
+      if (out.length >= max) break
+      const pt = Array.isArray(p.type) ? p.type.find((x) => x !== "null") : p.type
+      if (req.has(k) && pt && !["object", "array"].includes(pt) && KEY_NAME.test(k)) out.push({ path: at ? `${at}.${k}` : k, type: pt === "integer" ? "number" : pt })
+    }
+    for (const [k, p] of Object.entries(s.properties || {})) if (req.has(k) && (p.properties || p.items)) walk(p, at ? `${at}.${k}` : k, depth + 1)
+  }
+  walk(schema, "", 0)
+  return out
+}
+
+function firstExample(media: any): unknown {
+  if (!media) return undefined
+  if (media.example !== undefined) return media.example
+  const ex = media.examples && typeof media.examples === "object" ? Object.values(media.examples)[0] : undefined
+  if (ex && typeof ex === "object" && "value" in (ex as object)) return (ex as { value: unknown }).value
+  return undefined
+}
+
+function jsonMedia(content: any): [string, any] | undefined {
+  if (!content || typeof content !== "object") return undefined
+  const entries = Object.entries(content)
+  return (entries.find(([t]) => /json/i.test(t)) || entries.find(([t]) => /xml|text/i.test(t)) || entries[0]) as [string, any] | undefined
+}
+
+function fromOpenApi(raw: any, docUrl: string, opts: LoadOptions): Loaded {
+  const doc = raw
+  const v2 = Boolean(doc.swagger)
+  const skipped: string[] = []
+  let baseUrl = ""
+  if (v2) {
+    const scheme = (doc.schemes || []).includes("https") ? "https" : doc.schemes?.[0] || (isUrl(docUrl) ? new URL(docUrl).protocol.replace(":", "") : "https")
+    const host = doc.host || (isUrl(docUrl) ? new URL(docUrl).host : "")
+    baseUrl = host ? `${scheme}://${host}${(doc.basePath || "").replace(/\/$/, "")}` : ""
+  } else {
+    const server = doc.servers?.[0]
+    if (server?.url) {
+      let u = String(server.url)
+      for (const [k, v] of Object.entries(server.variables || {})) u = u.replace(`{${k}}`, String((v as { default?: string }).default ?? ""))
+      baseUrl = isUrl(u) ? u : isUrl(docUrl) ? new URL(u, docUrl).href : u
+    } else if (isUrl(docUrl)) baseUrl = new URL(docUrl).origin
+  }
+  baseUrl = baseUrl.replace(/\/+$/, "")
+  const schemes = (v2 ? doc.securityDefinitions : doc.components?.securitySchemes) || {}
+  const authOf = (security: any[] | undefined): Contract["auth"] | undefined => {
+    const first = (security || doc.security || [])[0]
+    const name = first ? Object.keys(first)[0] : undefined
+    const s = name ? schemes[name] : undefined
+    if (!s) return undefined
+    if (s.type === "apiKey") return { type: s.in === "header" ? "header" : s.in === "cookie" ? "cookie" : "query", name: s.name }
+    if (s.type === "http") return { type: String(s.scheme || "bearer").toLowerCase() }
+    if (s.type === "basic") return { type: "basic" }
+    return { type: s.type === "oauth2" || s.type === "openIdConnect" ? "bearer" : String(s.type) }
+  }
+
+  const contracts: Contract[] = []
+  for (const [p, item] of Object.entries<any>(doc.paths || {})) {
+    for (const m of METHODS) {
+      const opRaw = item?.[m]
+      if (!opRaw) continue
+      const op = deref(opRaw, doc)
+      const params = [...(deref(item.parameters, doc) || []), ...(op.parameters || [])].filter((x: any) => x && x.name)
+      const needs: string[] = []
+      let concrete = p
+      const query: Record<string, string> = {}
+      const headers: Record<string, string> = {}
+      let body: unknown
+      for (const prm of params) {
+        const sch = prm.schema || prm
+        const ex = prm.example ?? firstExample(prm) ?? sch.example ?? sch.default ?? sch.enum?.[0]
+        if (prm.in === "path") {
+          if (ex === undefined) needs.push(`path parameter ${prm.name}`)
+          concrete = concrete.replace(`{${prm.name}}`, encodeURIComponent(String(ex ?? exampleFor(toSchema(sch), 0, prm.name))))
+        } else if (prm.in === "query" && (prm.required || ex !== undefined)) {
+          if (ex === undefined) needs.push(`query parameter ${prm.name}`)
+          query[prm.name] = String(ex ?? exampleFor(toSchema(sch), 0, prm.name))
+        } else if (prm.in === "header" && prm.required && !/^(authorization|accept|content-type)$/i.test(prm.name)) {
+          if (ex === undefined) needs.push(`header ${prm.name}`)
+          headers[prm.name] = String(ex ?? "sample")
+        } else if (prm.in === "body" && prm.schema) {
+          body = prm.schema.example ?? exampleFor(toSchema(prm.schema))
+          headers["Content-Type"] = (op.consumes || doc.consumes || ["application/json"])[0]
+          if (prm.schema.example === undefined) needs.push("request body (made from the schema)")
+        }
+      }
+      const reqMedia = jsonMedia(op.requestBody?.content)
+      if (reqMedia) {
+        const ex = firstExample(reqMedia[1])
+        body = ex ?? exampleFor(toSchema(reqMedia[1].schema))
+        headers["Content-Type"] = reqMedia[0]
+        if (ex === undefined && reqMedia[1].schema?.example === undefined) needs.push("request body (made from the schema)")
+      }
+      const codes = Object.keys(op.responses || {})
+      const ok = codes.filter((c) => /^2\d\d$/.test(c)).sort()[0] || (codes.includes("2XX") ? "200" : codes.includes("default") ? "default" : "")
+      const res = ok ? op.responses[ok] : undefined
+      const status = ok && /^\d+$/.test(ok) ? Number(ok) : 200
+      let schema: JsonSchema | undefined
+      let contentType: string | undefined
+      if (v2) {
+        schema = toSchema(res?.schema)
+        if (res?.schema) contentType = (op.produces || doc.produces || ["application/json"])[0]
+      } else {
+        const media = jsonMedia(res?.content)
+        if (media) {
+          contentType = media[0]
+          schema = toSchema(media[1].schema)
+        }
+      }
+      const fields = schemaFields(schema)
+      const method = m.toUpperCase()
+      const bodySchema = reqMedia?.[1]?.schema || params.find((x: any) => x.in === "body")?.schema
+      const requestRequired: string[] = Array.isArray(bodySchema?.required) ? bodySchema.required : []
+      const links = Object.values<any>(res?.links || {})
+        .filter((l) => l && typeof l.operationId === "string")
+        .map((l) => ({ operationId: String(l.operationId), parameters: Object.fromEntries(Object.entries<any>(l.parameters || {}).map(([k, v]) => [k.replace(/^(path|query|header)\./, ""), String(v)])) }))
+      contracts.push({
+        id: `${method} ${p}`,
+        protocol: "rest",
+        name: String(op.summary || op.operationId || `${method} ${p}`).slice(0, 120),
+        method,
+        path: p,
+        example: { path: concrete, ...(Object.keys(query).length ? { query } : {}), ...(Object.keys(headers).length ? { headers } : {}), ...(body !== undefined ? { body } : {}) },
+        expect: { status, ...(contentType ? { contentType } : {}), ...(schema && Object.keys(schema).length ? { schema } : {}), ...(fields.length ? { fields } : {}) },
+        ...(authOf(op.security) ? { auth: authOf(op.security) } : {}),
+        writes: !["GET", "HEAD", "OPTIONS"].includes(method),
+        ...(needs.length ? { needsData: needs } : {}),
+        source: { kind: v2 ? "swagger" : "openapi", ref: docUrl },
+        ...(op.description || op.summary ? { description: String(op.description || op.summary).slice(0, 300) } : {}),
+        ...(op.operationId ? { operationId: String(op.operationId) } : {}),
+        ...(links.length ? { links } : {}),
+        ...(requestRequired.length ? { requestRequired } : {}),
+      })
+    }
+  }
+  if (!contracts.length) skipped.push("The description has no operations under paths.")
+  return { kind: v2 ? "swagger" : "openapi", name: String(doc.info?.title || "API"), baseUrl, contracts, skipped }
+}
+
+// -- WSDL (SOAP) --------------------------------------------------------------------------------
+
+const asList = <T>(v: T | T[] | undefined): T[] => (v === undefined ? [] : Array.isArray(v) ? v : [v])
+const local = (qname: unknown) => String(qname || "").split(":").pop() || ""
+
+function fromWsdl(text: string, docUrl: string, _opts: LoadOptions): Loaded {
+  const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@", removeNSPrefix: true })
+  const root = parser.parse(text)
+  const defs = root.definitions || root.description
+  if (!defs) throw new Error("Not a WSDL document: no definitions element.")
+  const tns = String(defs["@targetNamespace"] || "")
+  const soap12 = /soap12|w3\.org\/2003\/05\/soap/.test(text)
+  const schemas = asList<any>(defs.types?.schema)
+  const elements = new Map<string, any>()
+  const complex = new Map<string, any>()
+  for (const s of schemas) {
+    for (const e of asList<any>(s.element)) elements.set(e["@name"], e)
+    for (const c of asList<any>(s.complexType)) complex.set(c["@name"], c)
+  }
+  const children = (el: any): string[] => {
+    const ct = el?.complexType || (el?.["@type"] ? complex.get(local(el["@type"])) : undefined)
+    const seq = ct?.sequence || ct?.all || ct?.complexContent?.extension?.sequence
+    return asList<any>(seq?.element).map((c) => c["@name"] || local(c["@ref"])).filter(Boolean)
+  }
+  const messages = new Map<string, any>(asList<any>(defs.message).map((m) => [m["@name"], m]))
+  const location = asList<any>(defs.service).flatMap((s) => asList<any>(s.port || s.endpoint)).map((p) => p.address?.["@location"] || p["@address"]).find(Boolean) || ""
+  const binding = asList<any>(defs.binding)[0]
+  const actions = new Map<string, string>(asList<any>(binding?.operation).map((o) => [o["@name"], String(o.operation?.["@soapAction"] || o["@soapAction"] || "")]))
+  const portType = asList<any>(defs.portType || defs.interface)[0]
+  const contracts: Contract[] = []
+  const base = location ? new URL(location).origin : isUrl(docUrl) ? new URL(docUrl).origin : ""
+  const endpointPath = location ? new URL(location).pathname : "/"
+  for (const op of asList<any>(portType?.operation)) {
+    const name = String(op["@name"])
+    const inMsg = messages.get(local(op.input?.["@message"]))
+    const outMsg = messages.get(local(op.output?.["@message"]))
+    const inEl = local(asList<any>(inMsg?.part)[0]?.["@element"]) || local(op.input?.["@element"]) || name
+    const outEl = local(asList<any>(outMsg?.part)[0]?.["@element"]) || local(op.output?.["@element"]) || `${name}Response`
+    const kids = children(elements.get(inEl))
+    const envNs = soap12 ? "http://www.w3.org/2003/05/soap-envelope" : "http://schemas.xmlsoap.org/soap/envelope/"
+    const body = `<soap:Envelope xmlns:soap="${envNs}" xmlns:tns="${tns}"><soap:Header/><soap:Body><tns:${inEl}>${kids.map((k) => `<tns:${k}>?</tns:${k}>`).join("")}</tns:${inEl}></soap:Body></soap:Envelope>`
+    const action = actions.get(name) || ""
+    const headers: Record<string, string> = soap12 ? { "Content-Type": `application/soap+xml; charset=utf-8${action ? `; action="${action}"` : ""}` } : { "Content-Type": "text/xml; charset=utf-8", SOAPAction: `"${action}"` }
+    contracts.push({
+      id: `soap ${name}`,
+      protocol: "soap",
+      name,
+      method: "POST",
+      path: endpointPath,
+      example: { path: endpointPath, headers, body },
+      expect: { status: 200, contentType: soap12 ? "application/soap+xml" : "text/xml", elements: [outEl] },
+      writes: !READ_NAME.test(name),
+      ...(kids.length ? { needsData: kids.map((k) => `element ${k}`) } : {}),
+      source: { kind: "wsdl", ref: docUrl },
+      ...(op.documentation ? { description: String(op.documentation).slice(0, 300) } : {}),
+    })
+  }
+  return { kind: "wsdl", name: String(defs["@name"] || asList<any>(defs.service)[0]?.["@name"] || "SOAP service"), baseUrl: base, contracts, skipped: contracts.length ? [] : ["The WSDL has no operations."] }
+}
+
+// -- GraphQL ------------------------------------------------------------------------------------
+
+type GqlTypeRef = { kind: string; name?: string | null; ofType?: GqlTypeRef | null }
+type GqlField = { name: string; args?: { name: string; type: GqlTypeRef; defaultValue?: string | null }[]; type: GqlTypeRef }
+type GqlType = { kind: string; name: string; fields?: GqlField[] | null; enumValues?: { name: string }[] | null; inputFields?: { name: string; type: GqlTypeRef }[] | null }
+type GqlSchema = { queryType?: { name: string } | null; mutationType?: { name: string } | null; types: GqlType[] }
+
+export const INTROSPECTION = `query IntrospectionQuery { __schema { queryType { name } mutationType { name } types { kind name fields(includeDeprecated: false) { name args { name defaultValue type { ...T } } type { ...T } } inputFields { name type { ...T } } enumValues { name } } } }
+fragment T on __Type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } }`
+
+async function graphqlEndpoint(url: string, opts: LoadOptions): Promise<Loaded> {
+  const res = await (opts.fetch || fetch)(url, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", ...(opts.headers || {}) }, body: JSON.stringify({ query: INTROSPECTION }) })
+  const json = (await res.json().catch(() => null)) as { data?: { __schema?: GqlSchema }; errors?: { message: string }[] } | null
+  if (!json?.data?.__schema) throw new Error(`${url} did not answer the GraphQL introspection query${json?.errors?.length ? `: ${json.errors[0].message}` : ` (HTTP ${res.status})`}. Introspection may be off on this server; give the schema as a file instead.`)
+  return fromIntrospection(json.data.__schema, url, url, opts)
+}
+
+const unwrap = (t: GqlTypeRef): { name: string; list: boolean; required: boolean } => {
+  let required = false
+  let list = false
+  let cur: GqlTypeRef | null | undefined = t
+  if (cur.kind === "NON_NULL") {
+    required = true
+    cur = cur.ofType
+  }
+  while (cur && (cur.kind === "NON_NULL" || cur.kind === "LIST")) {
+    if (cur.kind === "LIST") list = true
+    cur = cur.ofType
+  }
+  return { name: cur?.name || "", list, required }
+}
+
+const typeText = (t: GqlTypeRef): string => (t.kind === "NON_NULL" ? `${typeText(t.ofType!)}!` : t.kind === "LIST" ? `[${typeText(t.ofType!)}]` : t.name || "")
+
+const SCALAR_SCHEMA: Record<string, string> = { Int: "integer", Float: "number", String: "string", Boolean: "boolean", ID: "string" }
+
+function fromIntrospection(schema: GqlSchema, endpoint: string, ref: string, _opts: LoadOptions): Loaded {
+  const types = new Map(schema.types.map((t) => [t.name, t]))
+  const isLeaf = (name: string) => ["SCALAR", "ENUM"].includes(types.get(name)?.kind || "SCALAR")
+  const selection = (typeName: string, depth: number): string => {
+    const t = types.get(typeName)
+    if (!t?.fields) return ""
+    const leaves = t.fields.filter((f) => !f.args?.some((a) => a.type.kind === "NON_NULL") && isLeaf(unwrap(f.type).name)).slice(0, 12)
+    const nested = depth < 1 ? t.fields.filter((f) => !f.args?.some((a) => a.type.kind === "NON_NULL") && !isLeaf(unwrap(f.type).name)).slice(0, 3) : []
+    const parts = [...leaves.map((f) => f.name), ...nested.map((f) => `${f.name} ${selection(unwrap(f.type).name, depth + 1)}`.trim()).filter((s) => s.includes("{"))]
+    return parts.length ? `{ ${parts.join(" ")} }` : "{ __typename }"
+  }
+  const schemaOf = (typeName: string, list: boolean, depth: number): JsonSchema => {
+    const t = types.get(typeName)
+    let s: JsonSchema
+    if (!t || t.kind === "SCALAR") s = SCALAR_SCHEMA[typeName] ? { type: SCALAR_SCHEMA[typeName] } : {}
+    else if (t.kind === "ENUM") s = { type: "string", ...(t.enumValues?.length ? { enum: t.enumValues.map((e) => e.name) } : {}) }
+    else s = { type: "object" }
+    if (s.type === "object" && t?.fields && depth < 1) {
+      const leaves = t.fields.filter((f) => !f.args?.some((a) => a.type.kind === "NON_NULL") && isLeaf(unwrap(f.type).name)).slice(0, 12)
+      s.properties = Object.fromEntries(leaves.map((f) => [f.name, { ...schemaOf(unwrap(f.type).name, unwrap(f.type).list, depth + 1), ...(unwrap(f.type).required ? {} : { nullable: true }) }]))
+    }
+    return list ? { type: "array", items: s } : s
+  }
+  const exampleArg = (t: GqlTypeRef, name: string): unknown => {
+    const u = unwrap(t)
+    const it = types.get(u.name)
+    let v: unknown
+    if (it?.kind === "ENUM") v = it.enumValues?.[0]?.name
+    else if (it?.kind === "INPUT_OBJECT") v = Object.fromEntries((it.inputFields || []).filter((f) => f.type.kind === "NON_NULL").map((f) => [f.name, exampleArg(f.type, f.name)]))
+    else v = u.name === "Int" || u.name === "Float" ? 1 : u.name === "Boolean" ? true : u.name === "ID" ? "1" : /email/i.test(name) ? "user@example.com" : `sample-${name}`
+    return u.list ? [v] : v
+  }
+  const contracts: Contract[] = []
+  const endpointPath = isUrl(endpoint) ? new URL(endpoint).pathname : "/graphql"
+  for (const [rootName, kind] of [[schema.queryType?.name, "query"], [schema.mutationType?.name, "mutation"]] as const) {
+    const root = rootName ? types.get(rootName) : undefined
+    for (const f of root?.fields || []) {
+      if (f.name.startsWith("__")) continue
+      const required = (f.args || []).filter((a) => a.type.kind === "NON_NULL" && a.defaultValue == null)
+      const ret = unwrap(f.type)
+      const sel = isLeaf(ret.name) ? "" : ` ${selection(ret.name, 0)}`
+      const opName = f.name.charAt(0).toUpperCase() + f.name.slice(1)
+      const vars = required.map((a) => `$${a.name}: ${typeText(a.type)}`).join(", ")
+      const call = required.length ? `(${required.map((a) => `${a.name}: $${a.name}`).join(", ")})` : ""
+      const query = `${kind} ${opName}${vars ? `(${vars})` : ""} { ${f.name}${call}${sel} }`
+      const variables = Object.fromEntries(required.map((a) => [a.name, exampleArg(a.type, a.name)]))
+      const data: JsonSchema = { type: "object", required: ret.required ? [f.name] : [], properties: { [f.name]: { ...schemaOf(ret.name, ret.list, 0), ...(ret.required ? {} : { nullable: true }) } } }
+      contracts.push({
+        id: `graphql ${kind} ${opName}`,
+        protocol: "graphql",
+        name: f.name,
+        method: "POST",
+        path: endpointPath,
+        example: { path: endpointPath, headers: { "Content-Type": "application/json" }, body: { query, ...(required.length ? { variables } : {}), operationName: opName } },
+        expect: { status: 200, contentType: "application/json", schema: { type: "object", required: ["data"], properties: { data } }, fields: [{ path: `data.${f.name}` }] },
+        writes: kind === "mutation",
+        ...(required.length ? { needsData: required.map((a) => `argument ${a.name}`) } : {}),
+        source: { kind: "graphql", ref },
+      })
+    }
+  }
+  return { kind: "graphql", name: "GraphQL API", baseUrl: isUrl(endpoint) ? new URL(endpoint).origin : "", contracts, skipped: [] }
+}
+
+/** GraphQL SDL as an introspection-like schema (types, fields, arguments), for the same contracts. */
+export function sdlSchema(sdl: string): GqlSchema {
+  const text = sdl.replace(/#[^\n]*/g, "").replace(/"""[\s\S]*?"""/g, "").replace(/"[^"\n]*"/g, "")
+  const ref = (s: string): GqlTypeRef => {
+    const t = s.trim()
+    if (t.endsWith("!")) return { kind: "NON_NULL", ofType: ref(t.slice(0, -1)) }
+    if (t.startsWith("[")) return { kind: "LIST", ofType: ref(t.slice(1, t.lastIndexOf("]"))) }
+    return { kind: "NAMED", name: t }
+  }
+  const types: GqlType[] = []
+  const kinds = new Map<string, string>()
+  for (const m of text.matchAll(/\b(type|input|enum|interface|scalar)\s+(\w+)[^{\n]*({([^}]*)})?/g)) {
+    const [, kw, name, , body = ""] = m
+    const kind = kw === "type" || kw === "interface" ? "OBJECT" : kw === "input" ? "INPUT_OBJECT" : kw === "enum" ? "ENUM" : "SCALAR"
+    kinds.set(name, kind)
+    if (kind === "ENUM") {
+      types.push({ kind, name, enumValues: body.split(/\s+/).filter((v) => /^\w+$/.test(v)).map((n) => ({ name: n })) })
+      continue
+    }
+    const fields: GqlField[] = []
+    for (const f of body.matchAll(/(\w+)\s*(\(([^)]*)\))?\s*:\s*([\w[\]!]+)/g)) {
+      const args = (f[3] || "")
+        .split(/,|\n/)
+        .map((a) => a.match(/(\w+)\s*:\s*([\w[\]!]+)(\s*=\s*(\S+))?/))
+        .filter(Boolean)
+        .map((a) => ({ name: a![1], type: ref(a![2]), defaultValue: a![4] ?? null }))
+      fields.push({ name: f[1], args, type: ref(f[4]) })
+    }
+    types.push(kind === "INPUT_OBJECT" ? { kind, name, inputFields: fields.map((f) => ({ name: f.name, type: f.type })) } : { kind, name, fields })
+  }
+  for (const s of ["String", "Int", "Float", "Boolean", "ID"]) if (!kinds.has(s)) types.push({ kind: "SCALAR", name: s })
+  const fix = (r: GqlTypeRef): GqlTypeRef => (r.kind === "NAMED" ? { kind: kinds.get(r.name!) || "SCALAR", name: r.name } : { ...r, ofType: r.ofType ? fix(r.ofType) : null })
+  for (const t of types) {
+    for (const f of t.fields || []) {
+      f.type = fix(f.type)
+      for (const a of f.args || []) a.type = fix(a.type)
+    }
+    for (const f of t.inputFields || []) f.type = fix(f.type)
+  }
+  const root = (name: string) => text.match(new RegExp(`\\b${name}\\s*:\\s*(\\w+)`))?.[1]
+  return { queryType: { name: root("query") || "Query" }, mutationType: { name: root("mutation") || "Mutation" }, types }
+}
+
+function fromSdl(sdl: string, ref: string, opts: LoadOptions): Loaded {
+  const loaded = fromIntrospection(sdlSchema(sdl), "", ref, opts)
+  return { ...loaded, skipped: ["The schema file gives no endpoint: set the base URL (and the endpoint path if it is not /graphql) to run these."] }
+}
+
+// -- gRPC ---------------------------------------------------------------------------------------
+
+type ProtoMessage = { name: string; fields: { name: string; type: string; repeated: boolean }[] }
+type ProtoService = { pkg: string; name: string; rpcs: { name: string; input: string; output: string; streaming: boolean }[] }
+
+/** Each `keyword Name { ... }` block in the text, with braces matched (rpc option blocks and nested messages inside). */
+function blocks(text: string, keyword: string): { name: string; body: string }[] {
+  const out: { name: string; body: string }[] = []
+  const re = new RegExp(`\\b${keyword}\\s+([\\w.]+)\\s*{`, "g")
+  for (const m of text.matchAll(re)) {
+    let depth = 1
+    let i = m.index! + m[0].length
+    const start = i
+    for (; i < text.length && depth; i++) depth += text[i] === "{" ? 1 : text[i] === "}" ? -1 : 0
+    out.push({ name: m[1], body: text.slice(start, i - 1) })
+  }
+  return out
+}
+
+/** Services, rpcs, and messages from .proto text (or grpcurl describe output, which is written the same way). */
+export function parseProto(text: string): { services: ProtoService[]; messages: Map<string, ProtoMessage> } {
+  const clean = text
+    .replace(/\/\/[^\n]*/g, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    // grpcurl describe: "shop.Orders is a service:" then "service Orders {": keep the full name.
+    .replace(/^([\w.]+) is a service:\s*\n\s*service\s+\w+/gm, "service $1")
+    .replace(/^([\w.]+) is a message:\s*$/gm, "")
+  const pkg = clean.match(/\bpackage\s+([\w.]+)\s*;/)?.[1] || ""
+  const services: ProtoService[] = []
+  const messages = new Map<string, ProtoMessage>()
+  for (const s of blocks(clean, "service")) {
+    const name = s.name.split(".").pop()!
+    const sp = s.name.includes(".") ? s.name.split(".").slice(0, -1).join(".") : pkg
+    const rpcs = [...s.body.matchAll(/\brpc\s+(\w+)\s*\(\s*(stream\s+)?\.?([\w.]+)\s*\)\s*returns\s*\(\s*(stream\s+)?\.?([\w.]+)\s*\)/g)].map((r) => ({ name: r[1], input: r[3], output: r[5], streaming: Boolean(r[2] || r[4]) }))
+    services.push({ pkg: sp, name, rpcs })
+  }
+  for (const m of blocks(clean, "message")) {
+    const own = m.body.replace(/\b(message|enum|oneof)\s+\w+\s*{[^{}]*}/g, (b) => (b.startsWith("oneof") ? b.replace(/^oneof\s+\w+\s*{|}$/g, "") : ""))
+    const fields = [...own.matchAll(/(repeated\s+|optional\s+)?\.?([\w.]+)\s+(\w+)\s*=\s*\d+/g)].map((f) => ({ name: f[3], type: f[2], repeated: f[1]?.trim() === "repeated" }))
+    const name = m.name.replace(/^\./, "")
+    messages.set(name.split(".").pop()!, { name, fields })
+  }
+  return { services, messages }
+}
+
+const PROTO_EXAMPLE: Record<string, unknown> = { string: "sample", bool: true, bytes: "", double: 1, float: 1, int32: 1, int64: "1", uint32: 1, uint64: "1", sint32: 1, sint64: "1", fixed32: 1, fixed64: "1" }
+
+function protoExample(msg: ProtoMessage | undefined, messages: Map<string, ProtoMessage>, depth = 0): Record<string, unknown> {
+  if (!msg || depth > 3) return {}
+  return Object.fromEntries(
+    msg.fields.map((f) => {
+      const nested = messages.get(f.type.split(".").pop()!)
+      const v = f.type in PROTO_EXAMPLE ? PROTO_EXAMPLE[f.type] : nested ? protoExample(nested, messages, depth + 1) : f.name.endsWith("id") ? "1" : 0
+      return [f.name, f.repeated ? [v] : v]
+    }),
+  )
+}
+
+function grpcContracts(services: ProtoService[], messages: Map<string, ProtoMessage>, ref: string, kind: SourceKind): { contracts: Contract[]; skipped: string[] } {
+  const contracts: Contract[] = []
+  const skipped: string[] = []
+  for (const s of services) {
+    if (/^grpc\.(reflection|health)/.test(s.pkg) || s.name === "ServerReflection") continue
+    for (const r of s.rpcs) {
+      const full = `${s.pkg ? `${s.pkg}.` : ""}${s.name}/${r.name}`
+      if (r.streaming) {
+        skipped.push(`${full}: streaming rpc (contracts cover unary calls)`)
+        continue
+      }
+      const input = messages.get(r.input.split(".").pop()!)
+      const output = messages.get(r.output.split(".").pop()!)
+      const schema: JsonSchema | undefined = output ? { type: "object", properties: Object.fromEntries(output.fields.map((f) => [f.name, f.repeated ? { type: "array" } : {}])) } : undefined
+      contracts.push({
+        id: `grpc ${full}`,
+        protocol: "grpc",
+        name: full,
+        method: "POST",
+        path: `/${full}`,
+        example: { path: `/${full}`, body: protoExample(input, messages) },
+        expect: { status: 0, ...(schema ? { schema } : {}) },
+        writes: !READ_NAME.test(r.name),
+        ...(input?.fields.length ? { needsData: input.fields.map((f) => `field ${f.name}`) } : {}),
+        source: { kind, ref },
+      })
+    }
+  }
+  return { contracts, skipped }
+}
+
+async function fromProto(files: string[], _opts: LoadOptions, given?: string): Promise<Loaded> {
+  const text = given ?? files.map((f) => readFileSync(path.resolve(f), "utf8")).join("\n")
+  const { services, messages } = parseProto(text)
+  const { contracts, skipped } = grpcContracts(services, messages, files.join(", "), "proto")
+  if (!services.length) skipped.push("The .proto file has no service.")
+  return { kind: "proto", name: services.map((s) => s.name).join(", ") || "gRPC service", baseUrl: "", contracts, skipped: [...skipped, "A .proto file gives no server address: set the base URL to grpc://host:port (plaintext) or grpcs://host:port."] }
+}
+
+export async function runGrpcurl(args: string[], input?: string): Promise<{ ok: boolean; out: string }> {
+  const bin = Bun.which("grpcurl")
+  if (!bin) throw new Error("gRPC needs grpcurl (https://github.com/fullstorydev/grpcurl) on PATH: brew install grpcurl, or go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest.")
+  const proc = Bun.spawn([bin, ...args], { stdin: input === undefined ? "ignore" : new Blob([input]), stdout: "pipe", stderr: "pipe" })
+  const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited])
+  return { ok: code === 0, out: `${out}${err}` }
+}
+
+export function grpcTarget(url: string): { address: string; plaintext: boolean } {
+  const m = url.match(/^grpc(s?):\/\/([^/]+)/i)
+  if (!m) throw new Error(`Not a gRPC address: ${url} (use grpc://host:port or grpcs://host:port)`)
+  return { address: m[2], plaintext: !m[1] }
+}
+
+async function grpcReflection(url: string, opts: LoadOptions): Promise<Loaded> {
+  const { address, plaintext } = grpcTarget(url)
+  const run = opts.grpcurl || runGrpcurl
+  const flags = [...(plaintext ? ["-plaintext"] : []), ...Object.entries(opts.headers || {}).flatMap(([k, v]) => ["-H", `${k}: ${v}`])]
+  const list = await run([...flags, address, "list"])
+  if (!list.ok) throw new Error(`grpcurl could not list the services at ${address}: ${list.out.trim().split("\n")[0]}. The server may not have reflection on; give its .proto files instead.`)
+  const names = list.out.split("\n").map((s) => s.trim()).filter((s) => s && !/^grpc\.reflection|^grpc\.health/.test(s))
+  let text = ""
+  for (const n of names) text += `\n${(await run([...flags, address, "describe", n])).out}`
+  const types = new Set([...text.matchAll(/\(\s*(?:stream\s+)?\.?([\w.]+)\s*\)/g)].map((m) => m[1]))
+  for (const t of types) text += `\n${(await run([...flags, address, "describe", t])).out}`
+  const { services, messages } = parseProto(text)
+  const { contracts, skipped } = grpcContracts(services, messages, url, "proto")
+  return { kind: "proto", name: names.join(", ") || "gRPC service", baseUrl: `${plaintext ? "grpc" : "grpcs"}://${address}`, contracts, skipped }
+}
+