@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/api/store.ts

@@ -0,0 +1,232 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import type { Card } from "../card.ts"
+import type { Contract, ContractRun, ContractSet, Scenario, ScenarioRun, ScenarioStep } from "./types.ts"
+
+/** Contract sets live in <export dir>/api/<id>/: contracts.json (edit its examples freely), api.md, and each run's results. */
+
+export const apiRoot = (config: AppConfig) => path.join(config.export.outDir, "api")
+
+export function newSetId(config: AppConfig, hint: string): string {
+  const slug = hint.toLowerCase().replace(/^https?:\/\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "api"
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..*/, "").replace("T", "-")
+  let id = `${stamp}-${slug}`
+  for (let n = 2; existsSync(path.join(apiRoot(config), id)); n++) id = `${stamp}-${slug}-${n}`
+  return id
+}
+
+export function saveSet(config: AppConfig, set: ContractSet): { dir: string; file: string; brief: string } {
+  const dir = path.join(apiRoot(config), set.id)
+  mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, "contracts.json")
+  writeFileSync(file, `${JSON.stringify(set, null, 2)}\n`)
+  const brief = path.join(dir, "api.md")
+  writeFileSync(brief, briefMarkdown(set))
+  return { dir, file, brief }
+}
+
+/** A saved set by id (or the newest when id is "latest" or empty), or a contracts.json path. */
+export function loadSet(config: AppConfig, ref?: string): { set: ContractSet; dir: string } {
+  const r = (ref || "").trim()
+  let file: string
+  if (r.endsWith(".json") && existsSync(path.resolve(r))) file = path.resolve(r)
+  else {
+    const id = !r || r === "latest" ? listSets(config)[0]?.id : path.basename(r)
+    if (!id) throw new Error("No API contracts yet: make some with api_contracts (from a browser run or an API description).")
+    file = path.join(apiRoot(config), id, "contracts.json")
+    if (!existsSync(file)) throw new Error(`No API contracts "${r}". Saved sets: ${listSets(config).slice(0, 8).map((s) => s.id).join(", ") || "none"}.`)
+  }
+  const set = JSON.parse(readFileSync(file, "utf8")) as ContractSet
+  if (!Array.isArray(set?.contracts)) throw new Error(`${file} is not a contracts file.`)
+  return { set, dir: path.dirname(file) }
+}
+
+export function listSets(config: AppConfig): { id: string; name: string; contracts: number; scenarios: number; at: number }[] {
+  const root = apiRoot(config)
+  if (!existsSync(root)) return []
+  return readdirSync(root)
+    .map((id) => {
+      const file = path.join(root, id, "contracts.json")
+      if (!existsSync(file)) return null
+      try {
+        const s = JSON.parse(readFileSync(file, "utf8")) as ContractSet
+        return { id, name: s.name, contracts: s.contracts.length, scenarios: s.scenarios?.length || 0, at: statSync(file).mtimeMs }
+      } catch {
+        return null
+      }
+    })
+    .filter((x): x is NonNullable<typeof x> => Boolean(x))
+    .sort((a, b) => b.at - a.at)
+}
+
+const json = (v: unknown, max = 1200) => {
+  const t = typeof v === "string" ? v : JSON.stringify(v, null, 1)
+  return t.length > max ? `${t.slice(0, max)}\n… (${t.length - max} more characters in contracts.json)` : t
+}
+
+/** The schema as short lines: field: type (required marked), nested two levels. Cheaper than the schema itself for the agent. */
+function schemaLines(s: Contract["expect"]["schema"], at = "", depth = 0, out: string[] = []): string[] {
+  if (!s || depth > 2 || out.length > 30) return out
+  const t = Array.isArray(s.type) ? s.type.join("|") : s.type || (s.anyOf ? "anyOf" : "any")
+  if (s.items) return schemaLines(s.items, `${at}[]`, depth, out)
+  const req = new Set(s.required || [])
+  for (const [k, p] of Object.entries(s.properties || {})) {
+    const pt = Array.isArray(p.type) ? p.type.join("|") : p.type || (p.anyOf ? "anyOf" : "any")
+    out.push(`${"  ".repeat(depth)}- ${at}${at ? "." : ""}${k}: ${pt}${p.items ? `[${(Array.isArray(p.items.type) ? p.items.type.join("|") : p.items.type) || "any"}]` : ""}${req.has(k) ? " (required)" : ""}${p.nullable ? " (nullable)" : ""}${p.enum ? ` one of ${p.enum.slice(0, 6).join(", ")}` : ""}`)
+    if (p.properties || p.items?.properties) schemaLines(p.items?.properties ? p.items : p, `${at}${at ? "." : ""}${k}${p.items ? "[]" : ""}`, depth + 1, out)
+  }
+  if (!out.length && t) out.push(`- (${t})`)
+  return out
+}
+
+/** The set as markdown: for people to read, and for the coding agent to write tests from. */
+export function briefMarkdown(set: ContractSet): string {
+  const lines = [
+    `# ${set.name}`,
+    "",
+    `Source: ${set.source.kind === "run" ? `browser run ${path.basename(set.source.ref)}` : `${set.source.kind} ${set.source.ref}`}`,
+    `Base URL: ${set.baseUrl || "(not known: set api.base_url)"}`,
+    `${set.contracts.length} operation${set.contracts.length === 1 ? "" : "s"}`,
+    "",
+  ]
+  if (set.skipped?.length) lines.push("Left out:", ...set.skipped.map((s) => `- ${s}`), "")
+  for (const c of set.contracts) {
+    lines.push(`## ${c.id}`, "")
+    if (c.name !== c.id) lines.push(c.name, "")
+    if (c.description && c.description !== c.name) lines.push(c.description, "")
+    const facts = [
+      `Protocol: ${c.protocol}`,
+      c.writes ? "Changes data: yes" : "Changes data: no",
+      c.auth ? `Auth: ${c.auth.type}${c.auth.name ? ` (${c.auth.name})` : ""}` : "",
+      c.source.samples ? `Seen ${c.source.samples} time${c.source.samples === 1 ? "" : "s"}${c.source.steps?.length ? ` in step${c.source.steps.length === 1 ? "" : "s"} ${c.source.steps.join(", ")}` : ""}` : "",
+    ].filter(Boolean)
+    lines.push(facts.join(" · "), "")
+    const q = c.example.query ? `?${new URLSearchParams(c.example.query)}` : ""
+    lines.push("Example call:", "", "```", `${c.method} ${c.example.path}${q}`)
+    for (const [k, v] of Object.entries(c.example.headers || {})) lines.push(`${k}: ${v}`)
+    if (c.example.body !== undefined) lines.push("", json(c.example.body))
+    lines.push("```", "")
+    if (c.needsData?.length) lines.push(`Needs real values for: ${c.needsData.join(", ")}`, "")
+    lines.push(`Expect: status ${c.protocol === "grpc" ? `${c.expect.status} (OK)` : c.expect.status}${c.expect.contentType ? `, ${c.expect.contentType}` : ""}`)
+    if (c.expect.elements?.length) lines.push(`Elements: ${c.expect.elements.join(", ")}`)
+    if (c.expect.fields?.length) lines.push("Key fields:", ...c.expect.fields.map((f) => `- ${f.path}${f.type ? `: ${f.type}` : ""}${f.equals !== undefined ? ` = ${JSON.stringify(f.equals)}` : ""}`))
+    if (c.expect.schema) {
+      const s = schemaLines(c.expect.schema)
+      if (s.length) lines.push("Body schema:", ...s)
+    }
+    lines.push("")
+  }
+  if (set.scenarios?.length) {
+    lines.push("# Scenarios", "", "Calls in order; {{name}} is a value saved from an earlier answer. {{$unique}} is new on every run.", "")
+    for (const sc of set.scenarios) lines.push(...scenarioMarkdown(sc), "")
+  }
+  return `${lines.join("\n").trimEnd()}\n`
+}
+
+function stepLine(st: ScenarioStep, i: number): string[] {
+  const q = st.query ? `?${Object.entries(st.query).map(([k, v]) => `${k}=${v}`).join("&")}` : ""
+  const status = st.expect.statusIn?.length ? st.expect.statusIn.join(" or ") : String(st.expect.status)
+  const out = [`${i + 1}. ${st.name}: ${st.method} ${st.path}${q} → ${status}${st.noAuth ? " (without credentials)" : ""}`]
+  if (st.body !== undefined) out.push(`   body: ${json(st.body, 300).replace(/\n\s*/g, " ")}`)
+  if (st.save) out.push(`   saves: ${Object.entries(st.save).map(([k, p]) => `${k} ← ${p}`).join(", ")}`)
+  if (st.expect.fields?.length) out.push(`   checks: ${st.expect.fields.map((f) => `${f.path}${f.equals !== undefined ? ` = ${JSON.stringify(f.equals)}` : f.type ? `: ${f.type}` : ""}`).join(", ")}`)
+  return out
+}
+
+export function scenarioMarkdown(sc: Scenario): string[] {
+  const lines = [`## Scenario ${sc.id}: ${sc.name}`, "", [`Kind: ${sc.kind}`, sc.caseId ? `Test case: ${sc.caseId}${sc.caseTitle ? ` ${sc.caseTitle}` : ""}` : "", sc.writes ? "Changes data: yes" : "Changes data: no"].filter(Boolean).join(" · "), ""]
+  sc.steps.forEach((st, i) => lines.push(...stepLine(st, i)))
+  if (sc.cleanup?.length) {
+    lines.push("", "Cleanup when it fails part-way:")
+    sc.cleanup.forEach((st, i) => lines.push(...stepLine(st, i)))
+  }
+  if (sc.notes?.length) lines.push("", ...sc.notes.map((n) => `Note: ${n}`))
+  return lines
+}
+
+export function scenariosCard(set: ContractSet, made: Scenario[], dir: string, cwd: string, extra: string[] = []): Card {
+  const body: string[] = []
+  for (const sc of made.slice(0, 12)) {
+    body.push(`▸ ${sc.name}${sc.caseId ? `  [${sc.caseId}]` : ""}${sc.writes ? "  · changes data" : ""}`)
+    sc.steps.slice(0, 10).forEach((st, i) => body.push(`    ${stepLine(st, i)[0]}`))
+    if (sc.steps.length > 10) body.push(`    and ${sc.steps.length - 10} more steps`)
+    for (const n of (sc.notes || []).slice(0, 4)) body.push(`    note: ${n}`)
+  }
+  if (made.length > 12) body.push(`and ${made.length - 12} more scenarios`)
+  if (extra.length) body.push("", ...extra)
+  const r = path.relative(cwd, path.join(dir, "contracts.json"))
+  body.push("", `Saved     ${r && !r.startsWith("..") ? r : path.join(dir, "contracts.json")} (scenarios) and api.md`)
+  const kinds = new Map<string, number>()
+  for (const sc of made) kinds.set(sc.kind, (kinds.get(sc.kind) || 0) + 1)
+  return { status: made.length ? "info" : "stopped", title: `${plural(made.length, "API scenario")}: ${set.name}`, stats: [...kinds].map(([k, n]) => `${n} ${k}`).join(" · "), body }
+}
+
+export function scenarioRunCard(run: ScenarioRun, set: ContractSet, cwd: string): Card {
+  const c = run.counts
+  const body: string[] = []
+  for (const r of run.results) {
+    body.push(`${r.status === "passed" ? "✓" : r.status === "skipped" ? "–" : "✗"} ${r.name}${r.ms ? `  ${(r.ms / 1000).toFixed(1)}s` : ""}`)
+    if (r.reason) body.push(`    ${r.reason}`)
+    for (const st of r.steps) {
+      if (st.status === "passed" && r.status === "passed") continue
+      body.push(`    ${st.status === "passed" ? "✓" : st.status === "skipped" ? "–" : "✗"} ${st.name}${st.httpStatus ? ` (${st.httpStatus})` : ""}`)
+      if (st.reason && st.status !== "skipped") body.push(`        ${st.reason}`)
+      for (const k of st.checks.filter((x) => !x.ok)) body.push(`        ${k.name}: ${k.detail || "failed"}`)
+    }
+    if (r.cleanup?.length) body.push(`    cleanup: ${r.cleanup.map((x) => `${x.name} ${x.status}`).join(", ")}`)
+  }
+  const rel = path.relative(cwd, run.dir)
+  body.push("", `Results   ${rel && !rel.startsWith("..") ? rel : run.dir}/scenario-results.json, scenarios-junit.xml`)
+  return {
+    status: c.failed || c.error ? "fail" : c.passed ? "ok" : "stopped",
+    title: `API scenarios ${c.failed || c.error ? "failed" : c.passed ? "passed" : "not run"}: ${set.name}`,
+    stats: [c.passed && `${c.passed} passed`, c.failed && `${c.failed} failed`, c.error && `${c.error} errors`, c.skipped && `${c.skipped} skipped`, run.baseUrl].filter(Boolean).join(" · "),
+    body,
+  }
+}
+
+const plural = (n: number, w: string) => `${n} ${w}${n === 1 ? "" : "s"}`
+
+export function setCard(set: ContractSet, dir: string, cwd: string): Card {
+  const rel = (p: string) => {
+    const r = path.relative(cwd, p)
+    return r && !r.startsWith("..") ? r : p
+  }
+  const by = new Map<string, number>()
+  for (const c of set.contracts) by.set(c.protocol, (by.get(c.protocol) || 0) + 1)
+  const body: string[] = []
+  for (const c of set.contracts.slice(0, 25)) {
+    const notes = [c.writes ? "changes data" : "", c.needsData?.length ? "needs real values" : "", c.source.samples ? `seen ${c.source.samples}×` : "", c.expect.fields?.length ? `${plural(c.expect.fields.length, "key field")}` : ""].filter(Boolean)
+    body.push(`• ${c.id} → ${c.protocol === "grpc" ? "OK" : c.expect.status}${notes.length ? `  · ${notes.join(", ")}` : ""}`)
+  }
+  if (set.contracts.length > 25) body.push(`and ${set.contracts.length - 25} more`)
+  if (set.skipped?.length) body.push("", ...set.skipped.map((s) => `Left out: ${s}`))
+  body.push("", `Base URL  ${set.baseUrl || "not known (set api.base_url)"}`, `Saved     ${rel(path.join(dir, "contracts.json"))} and api.md`)
+  return {
+    status: set.contracts.length ? "info" : "stopped",
+    title: `${plural(set.contracts.length, "API contract")}: ${set.name}`,
+    stats: [...by].map(([p, n]) => `${n} ${p === "rest" ? "REST" : p === "graphql" ? "GraphQL" : p === "soap" ? "SOAP" : "gRPC"}`).join(" · "),
+    body,
+  }
+}
+
+export function runCard(run: ContractRun, set: ContractSet, cwd: string): Card {
+  const c = run.counts
+  const body: string[] = []
+  for (const r of run.results) {
+    const mark = r.status === "passed" ? "✓" : r.status === "skipped" ? "–" : "✗"
+    body.push(`${mark} ${r.id}${r.ms !== undefined ? `  ${r.ms} ms` : ""}`)
+    if (r.status === "skipped" || r.status === "error") body.push(`    ${r.reason}`)
+    for (const k of r.checks.filter((x) => !x.ok)) body.push(`    ${k.name}: ${k.detail || "failed"}`)
+  }
+  const rel = path.relative(cwd, run.dir)
+  body.push("", `Results   ${rel && !rel.startsWith("..") ? rel : run.dir}/results.json, junit.xml`)
+  return {
+    status: c.failed || c.error ? "fail" : c.passed ? "ok" : "stopped",
+    title: `API contracts ${c.failed || c.error ? "failed" : c.passed ? "passed" : "not run"}: ${set.name}`,
+    stats: [c.passed && `${c.passed} passed`, c.failed && `${c.failed} failed`, c.error && `${c.error} errors`, c.skipped && `${c.skipped} skipped`, run.baseUrl].filter(Boolean).join(" · "),
+    body,
+  }
+}

package/src/api/traffic.ts

@@ -0,0 +1,281 @@
+import { XMLParser } from "fast-xml-parser"
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import { inferSchema, keyFields } from "./schema.ts"
+import type { Contract, ContractSet, Protocol } from "./types.ts"
+
+/**
+ * Contracts from the API calls a browser run saw (network.json, written by the engine): the calls are grouped into
+ * operations (one per method and path template, GraphQL operation, SOAP action, or gRPC method), and each operation's
+ * answers give its status, schema, and key fields. Several calls to one operation make a better contract: a field seen
+ * in every answer is required, a value that differs between calls is not pinned.
+ */
+
+export type NetworkCall = {
+  t: number
+  method: string
+  url: string
+  type: string
+  page?: string
+  third_party?: boolean
+  auth?: { type: string; name?: string }
+  ms?: number
+  failed?: string
+  request: { headers?: Record<string, string>; body?: string; truncated?: boolean }
+  response: { status: number; mime?: string; headers?: Record<string, string>; body?: string; truncated?: boolean; size?: number }
+}
+
+export type NetworkFile = { version: 1; calls: NetworkCall[]; dropped?: number }
+
+export function readNetwork(runDir: string): NetworkCall[] {
+  const file = path.join(runDir, "network.json")
+  if (!existsSync(file)) return []
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8")) as NetworkFile
+    return Array.isArray(data?.calls) ? data.calls : []
+  } catch {
+    return []
+  }
+}
+
+/** The browser run's step each call happened in, from the steps' start times in steps.json. */
+export function stepsOf(runDir: string, calls: NetworkCall[]): Map<NetworkCall, number> {
+  const out = new Map<NetworkCall, number>()
+  let starts: { n: number; t0: number }[] = []
+  try {
+    starts = (JSON.parse(readFileSync(path.join(runDir, "steps.json"), "utf8")) as { n?: number; t0?: number }[])
+      .filter((s) => typeof s.t0 === "number" && typeof s.n === "number")
+      .map((s) => ({ n: s.n!, t0: s.t0! }))
+  } catch {}
+  if (!starts.length) return out
+  for (const c of calls) {
+    let step = starts[0].n
+    for (const s of starts) if (s.t0 <= c.t) step = s.n
+    out.set(c, step)
+  }
+  return out
+}
+
+const header = (h: Record<string, string> | undefined, name: string) => Object.entries(h || {}).find(([k]) => k.toLowerCase() === name)?.[1] || ""
+
+export function parseJson(text: string | undefined): unknown {
+  if (!text) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+const xml = new XMLParser({ ignoreAttributes: true, removeNSPrefix: true })
+
+/** The SOAP body's first element (the operation, or its Response), when the text is a SOAP envelope. */
+export function soapOperation(text: string | undefined): string | null {
+  if (!text || !/Envelope/.test(text)) return null
+  try {
+    const env = xml.parse(text)?.Envelope
+    const body = env?.Body
+    return body && typeof body === "object" ? Object.keys(body)[0] || null : null
+  } catch {
+    return null
+  }
+}
+
+/** Every element name in an XML text, for SOAP answer checks. */
+export function xmlElements(text: string, max = 12): string[] {
+  const names: string[] = []
+  for (const m of text.matchAll(/<(?:[\w.-]+:)?([\w.-]+)[\s>/]/g)) {
+    if (!["Envelope", "Header", "Body", "xml"].includes(m[1]) && !names.includes(m[1])) names.push(m[1])
+    if (names.length >= max) break
+  }
+  return names
+}
+
+export function protocolOf(c: NetworkCall): Protocol {
+  const ct = `${header(c.request.headers, "content-type")} ${c.response.mime || ""}`.toLowerCase()
+  if (/grpc/.test(ct)) return "grpc"
+  if (header(c.request.headers, "soapaction") || /soap\+xml/.test(ct) || soapOperation(c.request.body)) return "soap"
+  const body = parseJson(c.request.body) as { query?: unknown } | undefined
+  if ((body && typeof body.query === "string") || /\/graphql\b/i.test(new URL(c.url).pathname) || /graphql/.test(ct)) return "graphql"
+  return "rest"
+}
+
+const ID_SEGMENT = /^(\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{16,}|[A-Za-z0-9_-]{20,}|[A-Z]{2,5}-\d+)$/i
+
+/** A path with the segments that are ids turned into {id} (two in a row: {id}, {id2}). */
+export function pathTemplate(pathname: string): string {
+  let n = 0
+  return pathname
+    .split("/")
+    .map((seg) => {
+      if (!seg || !ID_SEGMENT.test(decodeURIComponent(seg)) || !/\d/.test(seg)) return seg
+      n++
+      return n === 1 ? "{id}" : `{id${n}}`
+    })
+    .join("/")
+}
+
+/** GraphQL operation: its operationName, else the type and first field of the document. */
+export function graphqlOperation(body: unknown): { kind: "query" | "mutation" | "subscription"; name: string } | null {
+  const b = body as { query?: string; operationName?: string } | undefined
+  if (!b || typeof b.query !== "string") return null
+  const doc = b.query.replace(/#[^\n]*/g, "")
+  const m = doc.match(/^\s*(query|mutation|subscription)\b\s*(\w+)?/)
+  const kind = (m?.[1] as "query" | "mutation" | "subscription") || "query"
+  const field = doc.match(/{\s*(\w+)/)?.[1] || "operation"
+  return { kind, name: b.operationName || m?.[2] || field }
+}
+
+const READ_NAME = /^(get|list|find|search|query|read|fetch|lookup|check|validate|describe|count|is|has)/i
+
+export type Group = { key: string; protocol: Protocol; name: string; method: string; path: string; calls: NetworkCall[]; writes: boolean }
+
+export function groupCall(c: NetworkCall): Group | null {
+  let u: URL
+  try {
+    u = new URL(c.url)
+  } catch {
+    return null
+  }
+  const protocol = protocolOf(c)
+  if (protocol === "graphql") {
+    const op = graphqlOperation(parseJson(c.request.body)) || (c.method === "GET" && u.searchParams.get("query") ? graphqlOperation({ query: u.searchParams.get("query"), operationName: u.searchParams.get("operationName") || undefined }) : null)
+    if (!op) return null
+    return { key: `graphql ${op.kind} ${op.name}`, protocol, name: op.name, method: c.method, path: u.pathname, calls: [c], writes: op.kind === "mutation" }
+  }
+  if (protocol === "soap") {
+    const action = header(c.request.headers, "soapaction").replace(/"/g, "")
+    const op = soapOperation(c.request.body) || action.split(/[/#]/).pop() || "operation"
+    return { key: `soap ${op}`, protocol, name: op, method: c.method, path: u.pathname, calls: [c], writes: !READ_NAME.test(op) }
+  }
+  if (protocol === "grpc") {
+    const method = u.pathname.replace(/^\//, "")
+    return { key: `grpc ${method}`, protocol, name: method, method: "POST", path: u.pathname, calls: [c], writes: !READ_NAME.test(method.split("/").pop() || "") }
+  }
+  const tpl = pathTemplate(u.pathname)
+  return { key: `${c.method} ${tpl}`, protocol, name: `${c.method} ${tpl}`, method: c.method, path: tpl, calls: [c], writes: !["GET", "HEAD", "OPTIONS"].includes(c.method) }
+}
+
+export type FromTrafficOptions = {
+  /** Calls to other sites than the page's are left out unless this is on. */
+  thirdParty?: boolean
+  /** Only operations whose id contains one of these (case-insensitive). */
+  include?: string[]
+  steps?: Map<NetworkCall, number>
+}
+
+/** Group a run's calls into operations and write one contract for each. */
+export function contractsFromTraffic(calls: NetworkCall[], opts: FromTrafficOptions = {}): { contracts: Contract[]; skipped: string[]; baseUrl: string } {
+  const skipped: string[] = []
+  const groups = new Map<string, Group>()
+  const origins = new Map<string, number>()
+  let third = 0
+  let failed = 0
+  for (const c of calls) {
+    if (c.third_party && !opts.thirdParty) {
+      third++
+      continue
+    }
+    if (c.failed || !c.response?.status) {
+      failed++
+      continue
+    }
+    const g = groupCall(c)
+    if (!g) continue
+    const origin = new URL(c.url).origin
+    origins.set(origin, (origins.get(origin) || 0) + 1)
+    const have = groups.get(`${origin} ${g.key}`)
+    if (have) have.calls.push(c)
+    else groups.set(`${origin} ${g.key}`, g)
+  }
+  if (third) skipped.push(`${third} call${third === 1 ? "" : "s"} to other sites (analytics, CDNs, sign-in providers); set api.third_party: true to keep them`)
+  if (failed) skipped.push(`${failed} call${failed === 1 ? "" : "s"} that failed or got no answer`)
+  const baseUrl = [...origins].sort((a, b) => b[1] - a[1])[0]?.[0] || ""
+  const include = (opts.include || []).map((s) => s.toLowerCase()).filter(Boolean)
+  const contracts: Contract[] = []
+  for (const g of groups.values()) {
+    if (include.length && !include.some((i) => g.key.toLowerCase().includes(i))) continue
+    const origin = new URL(g.calls[0].url).origin
+    contracts.push(contractOf(g, origin === baseUrl ? "" : origin, opts.steps))
+  }
+  contracts.sort((a, b) => Number(a.writes) - Number(b.writes) || a.id.localeCompare(b.id))
+  return { contracts, skipped, baseUrl }
+}
+
+function contractOf(g: Group, otherOrigin: string, steps?: Map<NetworkCall, number>): Contract {
+  // The example is the first call that succeeded, else the first; the expected status is the one most calls got.
+  const statuses = new Map<number, number>()
+  for (const c of g.calls) statuses.set(c.response.status, (statuses.get(c.response.status) || 0) + 1)
+  const status = [...statuses].sort((a, b) => b[1] - a[1] || a[0] - b[0])[0][0]
+  const same = g.calls.filter((c) => c.response.status === status)
+  const ex = same[0]
+  const u = new URL(ex.url)
+  const contentType = (ex.response.mime || header(ex.response.headers, "content-type")).split(";")[0].trim()
+  const bodies = same.filter((c) => !c.response.truncated).map((c) => c.response.body)
+  const json = bodies.map(parseJson).filter((v) => v !== undefined)
+  const reqType = header(ex.request.headers, "content-type")
+  const reqBody = ex.request.body === undefined ? undefined : (parseJson(ex.request.body) ?? ex.request.body)
+  const headers: Record<string, string> = {}
+  for (const name of ["content-type", "soapaction", "accept"]) {
+    const v = header(ex.request.headers, name)
+    if (v) headers[name === "soapaction" ? "SOAPAction" : name === "content-type" ? "Content-Type" : "Accept"] = v
+  }
+  const expect: Contract["expect"] = { status, ...(contentType ? { contentType } : {}) }
+  if (g.protocol === "soap") {
+    const text = bodies.find(Boolean)
+    if (text) expect.elements = xmlElements(text, 6)
+  } else if (g.protocol === "grpc") {
+    const grpcStatus = header(ex.response.headers, "grpc-status")
+    if (grpcStatus) expect.fields = [{ path: "grpc-status", equals: Number(grpcStatus) }]
+  } else if (json.length) {
+    expect.schema = inferSchema(json)
+    const fields = keyFields(g.protocol === "graphql" ? json.map((j) => (j as { data?: unknown })?.data) : json)
+    if (fields.length) expect.fields = g.protocol === "graphql" ? fields.map((f) => ({ ...f, path: `data.${f.path}` })) : fields
+  }
+  const stepNumbers = [...new Set(g.calls.map((c) => steps?.get(c)).filter((n): n is number => typeof n === "number"))]
+  const query = Object.fromEntries(u.searchParams)
+  return {
+    id: g.key,
+    protocol: g.protocol,
+    name: g.name,
+    method: g.method,
+    path: `${otherOrigin}${g.path}`,
+    example: {
+      path: `${otherOrigin}${u.pathname}`,
+      ...(Object.keys(query).length ? { query } : {}),
+      ...(Object.keys(headers).length ? { headers } : {}),
+      ...(reqBody !== undefined ? { body: reqBody } : {}),
+    },
+    expect,
+    ...(ex.auth ? { auth: ex.auth } : {}),
+    writes: g.writes,
+    ...(ex.request.truncated || (reqType && reqBody === undefined && g.writes) ? { needsData: ["request body (not recorded in full)"] } : {}),
+    source: { kind: "run", ref: "", samples: g.calls.length, ...(stepNumbers.length ? { steps: stepNumbers } : {}) },
+  }
+}
+
+/** A contract set from a browser run's folder. */
+export function setFromRun(runDir: string, opts: Omit<FromTrafficOptions, "steps"> & { id: string; name?: string }): ContractSet {
+  const calls = readNetwork(runDir)
+  if (!calls.length)
+    throw new Error(
+      `The run ${path.basename(runDir)} recorded no API calls (no network.json). Runs record the application's calls since this version; run the flow again, or check api.capture is not off.`,
+    )
+  const { contracts, skipped, baseUrl } = contractsFromTraffic(calls, { ...opts, steps: stepsOf(runDir, calls) })
+  let goal = ""
+  try {
+    goal = (JSON.parse(readFileSync(path.join(runDir, "run.json"), "utf8")) as { goal?: string }).goal || ""
+  } catch {}
+  for (const c of contracts) c.source.ref = path.basename(runDir)
+  return {
+    version: 1,
+    id: opts.id,
+    name: opts.name || (goal ? `API calls of: ${goal.slice(0, 80)}` : `API calls of run ${path.basename(runDir)}`),
+    baseUrl,
+    createdAt: new Date().toISOString(),
+    source: { kind: "run", ref: runDir },
+    contracts,
+    ...(skipped.length ? { skipped } : {}),
+  }
+}

package/src/api/types.ts

@@ -0,0 +1,163 @@
+/**
+ * API and contract tests. A contract is one API operation with one example call and what its answer must look like:
+ * the status, the shape of the body (a JSON schema), and the fields that matter. Contracts come from an API description
+ * (OpenAPI or Swagger, WSDL, a GraphQL schema, .proto files) or from the calls a browser run saw the application make;
+ * ForgeQE runs them directly, and the coding agent turns them into tests in the repository's own framework.
+ */
+
+export type Protocol = "rest" | "graphql" | "soap" | "grpc"
+
+/** The JSON Schema subset ForgeQE writes and checks: types, properties, required, items, enum, nullable, anyOf. */
+export type JsonSchema = {
+  type?: string | string[]
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  items?: JsonSchema
+  enum?: unknown[]
+  format?: string
+  nullable?: boolean
+  anyOf?: JsonSchema[]
+  oneOf?: JsonSchema[]
+  allOf?: JsonSchema[]
+  additionalProperties?: boolean | JsonSchema
+  description?: string
+  example?: unknown
+}
+
+/** A field the answer must have. `equals` only for values that do not change between calls (a status, a currency). */
+export type KeyField = { path: string; type?: string; equals?: unknown }
+
+export type SourceKind = "run" | "openapi" | "swagger" | "wsdl" | "graphql" | "proto"
+
+export type Contract = {
+  /** "GET /api/orders/{id}", "graphql query GetOrders", "soap GetQuote", "grpc shop.Orders/Get". */
+  id: string
+  protocol: Protocol
+  /** The operation's name or summary. */
+  name: string
+  method: string
+  /** The path template ({id} for values that change). For gRPC, /package.Service/Method. */
+  path: string
+  /** One call to make: a concrete path, query, headers, and body. */
+  example: { path: string; query?: Record<string, string>; headers?: Record<string, string>; body?: unknown }
+  expect: {
+    status: number
+    /** Any of these statuses passes (negative cases: 401 or 403, 400 or 422). */
+    statusIn?: number[]
+    contentType?: string
+    schema?: JsonSchema
+    fields?: KeyField[]
+    /** SOAP: elements the answer must contain. */
+    elements?: string[]
+  }
+  /** How the application authenticated the call (the credential itself is never kept). */
+  auth?: { type: string; name?: string }
+  /** Changes data (POST, PUT, PATCH, DELETE, GraphQL mutations, SOAP and gRPC calls not named like reads): not run without allow_writes. */
+  writes: boolean
+  /** Path parameters or body values the description gives no example for: the call needs real data before it runs. */
+  needsData?: string[]
+  source: { kind: SourceKind; ref: string; samples?: number; steps?: number[] }
+  description?: string
+  /** OpenAPI operationId, and the description's links from this operation's answer to other operations. */
+  operationId?: string
+  links?: { operationId: string; parameters: Record<string, string> }[]
+  /** Required fields of the request body, for invalid-body negative cases. */
+  requestRequired?: string[]
+}
+
+/**
+ * A scenario: API calls in order, where later calls use values earlier answers gave ({{orderId}} in a path, query,
+ * header, or body). Built-in values: {{$unique}} (one per scenario run, for data that must be new each time),
+ * {{$uuid}}, {{$now}}, {{$randomInt}}.
+ */
+export type ScenarioStep = {
+  name: string
+  /** The contract this step calls, when there is one. */
+  operation?: string
+  protocol: Protocol
+  method: string
+  path: string
+  query?: Record<string, string>
+  headers?: Record<string, string>
+  body?: unknown
+  /** Values to keep from the answer: variable name → path in the body (id, data.items[0].id). */
+  save?: Record<string, string>
+  expect: Contract["expect"]
+  /** Sent without the configured credentials: a negative case. */
+  noAuth?: boolean
+}
+
+export type ScenarioKind = "flow" | "lifecycle" | "browse" | "linked" | "negative" | "planned"
+
+export type Scenario = {
+  id: string
+  name: string
+  kind: ScenarioKind
+  source: { kind: SourceKind | "case" | "text"; ref: string }
+  /** The test case it automates, for traceability. */
+  caseId?: string
+  caseTitle?: string
+  caseSource?: string
+  caseUrl?: string
+  /** What the test case's system needs to link the automated test to it (Azure DevOps work item id). */
+  caseRef?: Record<string, string | number>
+  steps: ScenarioStep[]
+  /** Run when the scenario fails part-way, to remove what it created. */
+  cleanup?: ScenarioStep[]
+  writes: boolean
+  notes?: string[]
+}
+
+export type StepResult = ContractResult & { name: string }
+
+export type ScenarioResult = {
+  id: string
+  name: string
+  status: "passed" | "failed" | "skipped" | "error"
+  steps: StepResult[]
+  cleanup?: StepResult[]
+  reason?: string
+  ms: number
+}
+
+export type ScenarioRun = {
+  set: string
+  baseUrl: string
+  at: string
+  results: ScenarioResult[]
+  counts: { passed: number; failed: number; skipped: number; error: number }
+  dir: string
+}
+
+export type ContractSet = {
+  version: 1
+  id: string
+  name: string
+  baseUrl: string
+  createdAt: string
+  source: { kind: SourceKind; ref: string }
+  contracts: Contract[]
+  /** What was left out and why (third-party calls, failed calls, unsupported bits of a description). */
+  skipped?: string[]
+  scenarios?: Scenario[]
+}
+
+export type CheckResult = { name: string; ok: boolean; detail?: string }
+
+export type ContractResult = {
+  id: string
+  status: "passed" | "failed" | "skipped" | "error"
+  ms?: number
+  httpStatus?: number
+  checks: CheckResult[]
+  reason?: string
+}
+
+export type ContractRun = {
+  set: string
+  baseUrl: string
+  at: string
+  results: ContractResult[]
+  counts: { passed: number; failed: number; skipped: number; error: number }
+  dir: string
+}