@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/cases/ado.ts

@@ -0,0 +1,325 @@
+import { spawnSync } from "node:child_process"
+import { XMLParser } from "fast-xml-parser"
+
+import { readIndex } from "../auth/store.ts"
+import type { SourcesConfig } from "../config.ts"
+import { basic, envSecret, htmlToText, http } from "./http.ts"
+import { FAILURE_ACTION, FAILURE_LABEL } from "./failure.ts"
+import { stepVerdictLines, type CaseResult, type CaseStep, type TestCase, type WriteBack } from "./types.ts"
+
+const API = "api-version=7.1"
+const FIELDS = [
+  "System.Title",
+  "System.Description",
+  "System.Tags",
+  "System.WorkItemType",
+  "System.AreaPath",
+  "System.TeamProject",
+  "Microsoft.VSTS.TCM.Steps",
+  "Microsoft.VSTS.TCM.LocalDataSource",
+]
+
+type Ado = NonNullable<SourcesConfig["ado"]>
+type WorkItem = { id: number; fields: Record<string, unknown> }
+type Point = { id: number; testCaseReference: { id: number; name?: string }; configuration?: { name?: string } }
+
+const scoped = (org: string, project: string) => `${org}/${encodeURIComponent(project)}`
+
+export function adoSettings(cfg: SourcesConfig): { ado: Ado; auth: string; org: string; project?: string; base: string } {
+  if (!cfg.ado) {
+    throw new Error("Azure DevOps is not set up. Add sources.azure_devops.org_url to forgeqe.yaml, or set ADO_ORG_URL.")
+  }
+  // Without a token, the Azure CLI's sign-in, when the user chose it with forgeqe auth login azure_devops.
+  const auth = process.env[cfg.ado.tokenEnv] ? basic("", envSecret(cfg.ado.tokenEnv, "Azure DevOps")) : readIndex().systems.azure_devops?.via === "azcli" ? azCliAuth() : null
+  if (!auth) throw new Error(`Azure DevOps needs ${cfg.ado.tokenEnv} in the environment, or a sign-in: run forgeqe auth login azure_devops (or /auth azure_devops in the shell).`)
+  const org = cfg.ado.orgUrl.replace(/\/+$/, "")
+  const project = cfg.ado.project
+  return { ado: cfg.ado, auth, org, project, base: project ? scoped(org, project) : org }
+}
+
+/** Azure DevOps' resource id in Microsoft Entra ID: tokens for it are accepted by every Azure DevOps Services API. */
+export const ADO_RESOURCE = "499b84ac-1321-427f-aa17-267ca6975798"
+
+let azToken: { value: string; until: number } | null = null
+
+/**
+ * A bearer token for Azure DevOps from the Azure CLI's sign-in (az login), cached until five minutes before it
+ * expires; null when az is missing or not signed in.
+ */
+export function azCliAuth(run = spawnSync): string | null {
+  if (azToken && Date.now() < azToken.until) return `Bearer ${azToken.value}`
+  if (run === spawnSync && !Bun.which("az")) return null
+  const r = run("az", ["account", "get-access-token", "--resource", ADO_RESOURCE, "--output", "json", "--only-show-errors"], { encoding: "utf8", timeout: 30_000, shell: process.platform === "win32" })
+  if (r.status !== 0) return null
+  try {
+    const t = JSON.parse(String(r.stdout)) as { accessToken?: string; expires_on?: number; expiresOn?: string }
+    if (!t.accessToken) return null
+    const expires = t.expires_on ? t.expires_on * 1000 : t.expiresOn ? Date.parse(t.expiresOn) : Date.now() + 30 * 60_000
+    azToken = { value: t.accessToken, until: expires - 5 * 60_000 }
+    return `Bearer ${t.accessToken}`
+  } catch {
+    return null
+  }
+}
+
+/** Forget the cached Azure CLI token (after az login or logout). */
+export function resetAzCliAuth() {
+  azToken = null
+}
+
+/** Every well-formed project in the organization, or the one project when sources.azure_devops.project is set. */
+export async function adoProjectNames(cfg: SourcesConfig): Promise<string[]> {
+  const { auth, org, project } = adoSettings(cfg)
+  if (project) return [project]
+  const rows = await paged<{ name?: string }>(`${org}/_apis/projects?${API}&stateFilter=wellFormed`, auth)
+  const names = rows.map((p) => p.name).filter((n): n is string => Boolean(n))
+  if (!names.length) throw new Error("No projects in this Azure DevOps organization.")
+  return names
+}
+
+/**
+ * `ado:123,456` test case work items by id; `ado:plan=12` every suite in a plan; `ado:plan=12/suite=34` one suite.
+ * `ado:project=Shop/plan=12` names the project. With no project in the reference or in forgeqe.yaml, a plan is
+ * looked up across every project, and work item ids are read from the organization (ids are unique there).
+ * Cases from a plan carry their test point, so results can be recorded as a test run.
+ */
+export async function adoCases(ref: string, cfg: SourcesConfig): Promise<TestCase[]> {
+  const { auth, org, project: configured } = adoSettings(cfg)
+  const named = ref.match(/(?:^|[/,\s])project=([^/\s,]+)/)?.[1]
+  const plan = ref.match(/plan=(\d+)/)?.[1]
+  const suite = ref.match(/suite=(\d+)/)?.[1]
+  if (plan) {
+    const project = named || configured || (await projectForPlan(org, plan, auth))
+    const base = scoped(org, project)
+    const suites = suite ? [Number(suite)] : (await paged<{ id: number }>(`${base}/_apis/testplan/Plans/${plan}/suites?${API}`, auth)).map((s) => s.id)
+    const points: Point[] = []
+    for (const s of suites) points.push(...(await paged<Point>(`${base}/_apis/testplan/Plans/${plan}/Suites/${s}/TestPoint?${API}`, auth)))
+    if (!points.length) throw new Error(`No test cases in Azure DevOps plan ${plan}${suite ? ` suite ${suite}` : ""}.`)
+    const items = await workItems([...new Set(points.map((p) => p.testCaseReference.id))], base, auth)
+    const perCase = new Map<number, number>()
+    for (const p of points) perCase.set(p.testCaseReference.id, (perCase.get(p.testCaseReference.id) || 0) + 1)
+    const cases: TestCase[] = []
+    for (const p of points) {
+      const item = items.get(p.testCaseReference.id)
+      if (!item) continue
+      const suffix = (perCase.get(p.testCaseReference.id) || 0) > 1 && p.configuration?.name ? ` [${p.configuration.name}]` : ""
+      for (const tc of await toCases(item, org, base, auth, project)) {
+        cases.push({ ...tc, title: tc.title + suffix, id: suffix ? `${tc.id}-${p.id}` : tc.id, ref: { ...tc.ref, project, plan: Number(plan), point: p.id } })
+      }
+    }
+    return cases
+  }
+  const ids = ref.split(/[,\s]+/).map((s) => Number(s.replace(/^ADO-/i, ""))).filter((n) => Number.isInteger(n) && n > 0)
+  if (!ids.length) throw new Error(`Azure DevOps reference "${ref}": use ado:123,456, ado:plan=12, ado:plan=12/suite=34, or ado:project=Shop/plan=12.`)
+  const project = named || configured
+  const base = project ? scoped(org, project) : org
+  const items = await workItems(ids, base, auth)
+  const missing = ids.filter((id) => !items.has(id))
+  if (missing.length) throw new Error(`Azure DevOps work items not found: ${missing.join(", ")}.`)
+  const cases: TestCase[] = []
+  for (const id of ids) cases.push(...(await toCases(items.get(id)!, org, base, auth, project)))
+  return cases
+}
+
+/** The project that owns a test plan, when forgeqe.yaml does not name one. */
+async function projectForPlan(org: string, plan: string, auth: string): Promise<string> {
+  const rows = await paged<{ name?: string }>(`${org}/_apis/projects?${API}&stateFilter=wellFormed`, auth)
+  const names = rows.map((p) => p.name).filter((n): n is string => Boolean(n))
+  if (!names.length) throw new Error("No projects in this Azure DevOps organization.")
+  for (const name of names) {
+    try {
+      await http(`${scoped(org, name)}/_apis/testplan/Plans/${plan}?${API}`, { auth })
+      return name
+    } catch (err) {
+      if (!/failed: 404\b/.test((err as Error).message)) throw err
+    }
+  }
+  throw new Error(`Azure DevOps plan ${plan} was not found in any project.`)
+}
+
+async function paged<T>(url: string, auth: string): Promise<T[]> {
+  const out: T[] = []
+  let token: string | null = null
+  do {
+    const u: string = token ? `${url}&continuationToken=${encodeURIComponent(token)}` : url
+    const { data, headers } = await http<{ value?: T[] }>(u, { auth })
+    out.push(...(data?.value || []))
+    token = headers.get("x-ms-continuationtoken")
+  } while (token)
+  return out
+}
+
+async function workItems(ids: number[], base: string, auth: string): Promise<Map<number, WorkItem>> {
+  const map = new Map<number, WorkItem>()
+  for (let i = 0; i < ids.length; i += 200) {
+    const { data } = await http<{ value: WorkItem[] }>(`${base}/_apis/wit/workitemsbatch?${API}`, {
+      auth,
+      body: { ids: ids.slice(i, i + 200), fields: FIELDS, errorPolicy: "omit" },
+    })
+    for (const w of data?.value || []) if (w?.id) map.set(w.id, w)
+  }
+  return map
+}
+
+async function toCases(item: WorkItem, org: string, base: string, auth: string, project?: string): Promise<TestCase[]> {
+  const f = item.fields
+  const steps = await parseSteps(String(f["Microsoft.VSTS.TCM.Steps"] || ""), base, auth)
+  const rows = dataRows(String(f["Microsoft.VSTS.TCM.LocalDataSource"] || ""))
+  const tags = String(f["System.Tags"] || "").split(";").map((t) => t.trim()).filter(Boolean)
+  const team = project || (f["System.TeamProject"] ? String(f["System.TeamProject"]) : "")
+  const tc: TestCase = {
+    id: `ADO-${item.id}`,
+    title: String(f["System.Title"] || `Work item ${item.id}`),
+    source: "ado",
+    url: `${team ? scoped(org, team) : base}/_workitems/edit/${item.id}`,
+    description: htmlToText(String(f["System.Description"] || "")) || undefined,
+    steps,
+    tags: tags.length ? tags : undefined,
+    group: f["System.AreaPath"] ? String(f["System.AreaPath"]) : undefined,
+    ref: { workItem: item.id, ...(team ? { project: team } : {}) },
+  }
+  if (!rows.length) return [tc]
+  return rows.map((row, i) => ({
+    ...tc,
+    id: `${tc.id}.${i + 1}`,
+    title: `${tc.title} (data row ${i + 1})`,
+    steps: steps.map((s) => ({ action: fill(s.action, row), data: s.data && fill(s.data, row), expected: s.expected && fill(s.expected, row) })),
+  }))
+}
+
+const xml = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "", preserveOrder: true, parseTagValue: false, trimValues: false })
+
+type Node = Record<string, unknown> & { ":@"?: Record<string, string> }
+
+/** Microsoft.VSTS.TCM.Steps: `<step>` action/expected pairs in order, with shared steps (`<compref ref>`) inlined. */
+async function parseSteps(source: string, base: string, auth: string, depth = 0): Promise<CaseStep[]> {
+  if (!source.trim()) return []
+  const steps: CaseStep[] = []
+  const walk = async (nodes: Node[]) => {
+    for (const node of nodes) {
+      const tag = Object.keys(node).find((k) => k !== ":@")
+      if (!tag) continue
+      const children = (node[tag] as Node[]) || []
+      if (tag === "steps") await walk(children)
+      else if (tag === "step") {
+        const strings = children.filter((c) => "parameterizedString" in c).map((c) => htmlToText(textOf(c.parameterizedString as Node[])))
+        if (strings[0]) steps.push({ action: strings[0], expected: strings[1] || undefined })
+      } else if (tag === "compref") {
+        const ref = Number(node[":@"]?.ref)
+        if (ref && depth < 3) {
+          const shared = (await workItems([ref], base, auth)).get(ref)
+          if (shared) steps.push(...(await parseSteps(String(shared.fields["Microsoft.VSTS.TCM.Steps"] || ""), base, auth, depth + 1)))
+        }
+        await walk(children)
+      }
+    }
+  }
+  await walk(xml.parse(source) as Node[])
+  return steps
+}
+
+function textOf(nodes: Node[] | undefined): string {
+  return (nodes || []).map((n) => (typeof n["#text"] === "string" ? (n["#text"] as string) : "")).join("")
+}
+
+/** Rows of a test case's local parameter table (`<NewDataSet><Table1><user>alice</user>…`). */
+function dataRows(source: string): Record<string, string>[] {
+  if (!source.trim().startsWith("<")) return []
+  const parsed = new XMLParser({ ignoreAttributes: true, parseTagValue: false }).parse(source) as Record<string, any>
+  const set = parsed?.NewDataSet
+  if (!set) return []
+  const tables = Object.entries(set).filter(([k]) => !k.includes(":")).flatMap(([, v]) => (Array.isArray(v) ? v : [v]))
+  return tables
+    .filter((row) => row && typeof row === "object")
+    .map((row) => Object.fromEntries(Object.entries(row as Record<string, unknown>).map(([k, v]) => [k, String(v ?? "")])))
+}
+
+function fill(text: string, row: Record<string, string>): string {
+  return Object.entries(row).reduce((acc, [k, v]) => acc.replace(new RegExp(`@${k}\\b`, "g"), v), text)
+}
+
+const OUTCOME = { passed: "Passed", failed: "Failed", stopped: "Aborted", error: "Blocked" } as const
+const RANK = { passed: 0, stopped: 1, error: 2, failed: 3 } as const
+
+/**
+ * Cases from a plan: one test run per plan with every point's outcome. Cases by id: a comment on the work item.
+ * Data rows of one test case share its point; the point gets the worst row's outcome.
+ */
+export async function adoWriteBack(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+  const { auth, org, project, base: configuredBase } = adoSettings(cfg)
+  const resultBase = (r: CaseResult) => {
+    if (project) return configuredBase
+    const name = typeof r.case.ref?.project === "string" ? r.case.ref.project : ""
+    if (!name) throw new Error(`Azure DevOps result ${r.case.id} has no project, so it cannot be written back.`)
+    return scoped(org, name)
+  }
+  const out: WriteBack[] = []
+  const byPlan = new Map<string, CaseResult[]>()
+  for (const r of results) {
+    const plan = Number(r.case.ref?.plan)
+    if (plan && r.case.ref?.point) {
+      const key = `${project || r.case.ref.project || ""}:${plan}`
+      byPlan.set(key, [...(byPlan.get(key) || []), r])
+    } else if (r.case.ref?.workItem) {
+      try {
+        const base = resultBase(r)
+        await http(`${base}/_apis/wit/workItems/${r.case.ref.workItem}/comments?api-version=7.1-preview.4`, {
+          auth,
+          body: { text: commentHtml(r) },
+        })
+        out.push({ source: "ado", caseId: r.case.id, text: `${r.case.id}: result added as a comment`, url: r.case.url })
+      } catch (err) {
+        out.push({ source: "ado", caseId: r.case.id, text: `${r.case.id}: comment not added`, error: (err as Error).message })
+      }
+    }
+  }
+  for (const list of byPlan.values()) {
+    const plan = Number(list[0].case.ref?.plan)
+    try {
+      const base = resultBase(list[0])
+      const byPoint = new Map<number, CaseResult[]>()
+      for (const r of list) byPoint.set(Number(r.case.ref!.point), [...(byPoint.get(Number(r.case.ref!.point)) || []), r])
+      const { data: run } = await http<{ id: number; webAccessUrl?: string }>(`${base}/_apis/test/runs?${API}`, {
+        auth,
+        body: { name: runName, plan: { id: String(plan) }, pointIds: [...byPoint.keys()], automated: false },
+      })
+      const { data: created } = await http<{ value: { id: number; testPoint?: { id: string | number } }[] }>(
+        `${base}/_apis/test/Runs/${run.id}/results?${API}`,
+        { auth },
+      )
+      const updates = (created?.value || []).flatMap((res) => {
+        const rs = byPoint.get(Number(res.testPoint?.id))
+        if (!rs) return []
+        const worst = rs.reduce((a, b) => (RANK[b.status] > RANK[a.status] ? b : a))
+        return [{
+          id: res.id,
+          // A failure that is not the application's (the test case, the environment, the automation) blocks the point
+          // rather than failing it, so the plan's failures are product defects.
+          outcome: worst.failure && worst.failure.type !== "functional_defect" ? "Blocked" : OUTCOME[worst.status],
+          state: "Completed",
+          durationInMs: rs.reduce((n, r) => n + r.ms, 0),
+          completedDate: rs.map((r) => r.finishedAt).sort().at(-1),
+          comment: rs.map((r) => commentText(r)).join("\n\n").slice(0, 1000),
+        }]
+      })
+      if (updates.length) await http(`${base}/_apis/test/Runs/${run.id}/results?${API}`, { auth, method: "PATCH", body: updates })
+      await http(`${base}/_apis/test/runs/${run.id}?${API}`, { auth, method: "PATCH", body: { state: "Completed" } })
+      out.push({ source: "ado", text: `Azure DevOps test run ${run.id} (plan ${plan}, ${updates.length} results)`, url: run.webAccessUrl })
+    } catch (err) {
+      out.push({ source: "ado", text: `Azure DevOps plan ${plan}: results not recorded`, error: (err as Error).message })
+    }
+  }
+  return out
+}
+
+function commentText(r: CaseResult): string {
+  const kind = r.failure ? ` (${FAILURE_LABEL[r.failure.type]}: ${FAILURE_ACTION[r.failure.type]})` : ""
+  const lines = [`ForgeQE: ${r.case.id} ${r.status} in ${Math.round(r.ms / 1000)}s${kind}.`, r.summary.trim(), ...stepVerdictLines(r)]
+  if (r.code?.testFile) lines.push(`Test: ${r.code.testFile} (${r.code.status})${r.code.command ? `, run with: ${r.code.command}` : ""}`)
+  return lines.filter(Boolean).join("\n")
+}
+
+function commentHtml(r: CaseResult): string {
+  const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+  return commentText(r).split("\n").map((l) => `<p>${esc(l)}</p>`).join("")
+}

package/src/cases/api.ts

@@ -0,0 +1,117 @@
+import type { SourcesConfig } from "../config.ts"
+import { adoSettings } from "./ado.ts"
+import { confluenceApi } from "./confluence.ts"
+import { http } from "./http.ts"
+import { jiraApi } from "./jira.ts"
+import { xrayCloudToken, xrayGraphql } from "./xray.ts"
+
+export type ApiQuery = {
+  system: "azure_devops" | "jira" | "xray" | "confluence"
+  path?: string
+  query?: string
+  variables?: Record<string, unknown>
+  /** azure_devops: a WIQL query (read-only by design); the project it runs in when it uses @project. */
+  wiql?: string
+  project?: string
+}
+
+const WIQL_TOP = 50
+const WIQL_FIELDS = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.AssignedTo", "System.ChangedDate", "System.IterationPath"]
+
+/**
+ * A WIQL search: Azure DevOps answers it with ids only (a POST, but WIQL has no statement that changes anything), so
+ * the first WIQL_TOP are read back with their main fields in one batch read.
+ */
+async function adoWiql(cfg: SourcesConfig, wiql: string, project?: string): Promise<unknown> {
+  const { ado, auth } = adoSettings(cfg)
+  const org = ado.orgUrl.replace(/\/+$/, "")
+  const scope = project || ado.project
+  const base = scope ? `${org}/${encodeURIComponent(scope)}` : org
+  const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { source?: { id: number } | null; target?: { id: number } }[] }>(
+    `${base}/_apis/wit/wiql?api-version=7.1&$top=${WIQL_TOP}`,
+    { auth, body: { query: wiql } },
+  )
+  const ids = [...new Set([...(data.workItems || []).map((w) => w.id), ...(data.workItemRelations || []).flatMap((r) => [r.source?.id, r.target?.id])])].filter((id): id is number => typeof id === "number").slice(0, WIQL_TOP)
+  if (!ids.length) return { count: 0, items: [] }
+  const batch = await http<{ value: { id: number; fields: Record<string, unknown> }[] }>(`${org}/_apis/wit/workitemsbatch?api-version=7.1`, { auth, body: { ids, fields: WIQL_FIELDS } })
+  const name = (v: unknown) => (v && typeof v === "object" ? String((v as { displayName?: string }).displayName || "") : String(v || ""))
+  return {
+    count: ids.length,
+    items: batch.data.value.map((w) => ({
+      id: w.id,
+      type: w.fields["System.WorkItemType"],
+      title: w.fields["System.Title"],
+      state: w.fields["System.State"],
+      assignedTo: name(w.fields["System.AssignedTo"]) || undefined,
+      changed: w.fields["System.ChangedDate"],
+      iteration: w.fields["System.IterationPath"],
+    })),
+    note: `Read each one in full with path <project>/_apis/wit/workitems/<id>?$expand=all.${ids.length === WIQL_TOP ? ` Only the first ${WIQL_TOP} are listed; narrow the query for the rest.` : ""}`,
+  }
+}
+
+const MAX_CHARS = 40_000
+
+/** An absolute URL must stay on one of `bases`; a path is joined to the first. Keeps credentials on their own host. */
+function resolve(path: string, bases: string[], system: string): string {
+  const p = path.trim()
+  if (/^https?:\/\//i.test(p)) {
+    if (bases.some((b) => p === b || p.startsWith(`${b}/`) || p.startsWith(`${b}?`))) return p
+    throw new Error(`${system} requests must stay on ${bases[0]}.`)
+  }
+  return `${bases[0]}/${p.replace(/^\/+/, "")}`
+}
+
+function adoBases(orgUrl: string): string[] {
+  const u = new URL(orgUrl)
+  if (u.hostname !== "dev.azure.com") return [orgUrl]
+  const org = u.pathname.split("/").filter(Boolean)[0]
+  return [orgUrl, ...["vsrm", "vssps", "almsearch", "feeds", "vsaex"].map((sub) => `https://${sub}.dev.azure.com/${org}`)]
+}
+
+/** True when a GraphQL document contains a mutation, ignoring string literals and comments. */
+export function isMutation(query: string): boolean {
+  const code = query.replace(/"""[\s\S]*?"""|"(?:[^"\\]|\\.)*"/g, '""').replace(/#.*$/gm, "")
+  return /(^|[\s{}])mutation\b/.test(code)
+}
+
+function clipJson(data: unknown): unknown {
+  const text = typeof data === "string" ? data : JSON.stringify(data)
+  if (text.length <= MAX_CHARS) return data
+  return `${text.slice(0, MAX_CHARS)}… (cut at ${MAX_CHARS} characters; ask for fewer fields or a smaller page)`
+}
+
+/**
+ * Read-only requests with the credentials from forgeqe.yaml and the environment: GET and WIQL searches for Azure
+ * DevOps, GET for Jira (Xray Server/Data Center is under Jira's /rest/raven), GraphQL queries for Xray Cloud.
+ */
+export async function queryApi(cfg: SourcesConfig, q: ApiQuery): Promise<unknown> {
+  switch (q.system) {
+    case "azure_devops": {
+      if (q.wiql?.trim()) return clipJson(await adoWiql(cfg, q.wiql, q.project))
+      if (!q.path) throw new Error("path or wiql is required for azure_devops")
+      const { ado, auth } = adoSettings(cfg)
+      let url = resolve(q.path, adoBases(ado.orgUrl), "Azure DevOps")
+      if (!/[?&]api-version=/.test(url)) url += `${url.includes("?") ? "&" : "?"}api-version=7.1`
+      return clipJson((await http(url, { auth })).data)
+    }
+    case "jira": {
+      if (!q.path) throw new Error("path is required for jira")
+      const j = jiraApi(cfg)
+      return clipJson((await http(resolve(q.path, [j.url], "Jira"), { auth: j.auth })).data)
+    }
+    case "confluence": {
+      if (!q.path) throw new Error("path is required for confluence")
+      const c = confluenceApi(cfg)
+      return clipJson((await http(resolve(q.path, [c.url], "Confluence"), { auth: c.auth })).data)
+    }
+    case "xray": {
+      if (cfg.jira && !cfg.jira.cloud) throw new Error("Xray Server/Data Center is part of Jira: use system jira with a /rest/raven/1.0/... path.")
+      if (!q.query) throw new Error("query (GraphQL) is required for xray")
+      if (isMutation(q.query)) throw new Error("query_api only reads; GraphQL mutations are not allowed.")
+      return clipJson(await xrayGraphql(cfg, await xrayCloudToken(cfg), q.query, q.variables || {}))
+    }
+    default:
+      throw new Error(`Unknown system "${String(q.system)}". Use azure_devops, jira, xray, or confluence.`)
+  }
+}

package/src/cases/bugs.ts

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto"
+import { existsSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { BugsConfig, SourcesConfig } from "../config.ts"
+import { browserErrors, problemLine } from "../report/data.ts"
+import { ciInfo } from "../report/html.ts"
+import { adoSettings } from "./ado.ts"
+import { http, textToAdf } from "./http.ts"
+import { jiraApi, type JiraApi } from "./jira.ts"
+import { stepVerdictLines, type CaseResult, type WriteBack } from "./types.ts"
+
+const MAX_ATTACHMENT = 8 * 1024 * 1024
+
+/**
+ * The label (Jira) or tag (Azure DevOps) that ties a bug to one test case across runs. Cases from a test system keep
+ * their id; text and file cases are identified by their title, since their ids are only positions.
+ */
+export function bugFingerprint(r: CaseResult): string {
+  const c = r.case
+  const identity = c.source === "text" || c.source === "file" ? `${c.source}:${c.title.trim().toLowerCase()}` : `${c.source}:${c.id}`
+  return `forgeqe-${createHash("sha1").update(identity).digest("hex").slice(0, 10)}`
+}
+
+export function bugTitle(r: CaseResult): string {
+  return `[ForgeQE] ${r.case.id}: ${r.case.title}`.slice(0, 250)
+}
+
+/** The bug's description: what failed, each step with the agent's verdict, where it ended, and where the evidence is. */
+export function bugText(r: CaseResult, runName: string): string {
+  const c = r.case
+  const ci = ciInfo().ci
+  const lines = [
+    `ForgeQE found this failing in "${runName}".`,
+    "",
+    `Test case: ${c.id} ${c.title}${c.url ? ` (${c.url})` : ""}`,
+    `Result: ${r.status}. ${r.summary.trim()}`,
+  ]
+  const steps = stepVerdictLines(r)
+  if (steps.length) lines.push("", "Steps:", ...steps)
+  else if (c.steps.length) lines.push("", "Steps:", ...c.steps.map((s, i) => `${i + 1}. ${s.action}${s.expected ? ` (expected: ${s.expected})` : ""}`))
+  else if (c.description?.trim()) lines.push("", c.description.trim())
+  if (c.preconditions?.length) lines.push("", "Preconditions:", ...c.preconditions.map((p) => `- ${p}`))
+  const errors = browserErrors(r.runDir)
+  if (errors.length) lines.push("", "Browser errors:", ...errors.slice(0, 10).map((p) => `- ${problemLine(p)}`), ...(errors.length > 10 ? [`- and ${errors.length - 10} more`] : []))
+  lines.push("")
+  if (r.finalUrl) lines.push(`Ended on: ${r.finalUrl}`)
+  if (ci?.url) lines.push(`Build: ${ci.url}`)
+  if (r.runDir) lines.push(`Run folder: ${r.runDir}`)
+  return lines.join("\n").trim()
+}
+
+/**
+ * A bug is for a functional defect: a case whose failure was classified as something else (the test case needs
+ * updating, the environment was down, the automation could not finish) is not a product bug.
+ */
+const failing = (r: CaseResult, b: BugsConfig) =>
+  r.failure ? r.failure.type === "functional_defect" : r.status === "failed" || (b.onError && r.status === "error")
+
+/** File a bug for each failing case, or comment on the open one filed before; note on the open bug when a case passes again. */
+export async function fileBugs(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+  const b = cfg.bugs
+  if (!b) return []
+  const relevant = results.filter((r) => failing(r, b) || r.status === "passed")
+  if (!relevant.length) return []
+  let tracker: Tracker
+  try {
+    tracker = b.system === "jira" ? jiraTracker(cfg, b) : adoTracker(cfg, b)
+  } catch (err) {
+    return [{ source: "bugs", text: "Bugs not filed", error: (err as Error).message }]
+  }
+  const out: WriteBack[] = []
+  for (const r of relevant) {
+    const fp = bugFingerprint(r)
+    try {
+      // A bug filed before ForgeQE was renamed from WebPilot carries the same hash under the old prefix.
+      const open = (await tracker.findOpen(fp)) ?? (await tracker.findOpen(fp.replace(/^forgeqe-/, "webpilot-")))
+      if (r.status === "passed") {
+        if (!open) continue
+        await tracker.comment(open.id, `ForgeQE: ${r.case.id} passed again in "${runName}".`)
+        out.push({ source: "bugs", caseId: r.case.id, text: `${open.label}: noted that ${r.case.id} passes again`, url: open.url })
+      } else if (open) {
+        await tracker.comment(open.id, `Still failing.\n\n${bugText(r, runName)}`)
+        out.push({ source: "bugs", caseId: r.case.id, text: `${open.label}: still failing, comment added`, url: open.url })
+      } else {
+        const bug = await tracker.create(r, fp, runName)
+        out.push({ source: "bugs", caseId: r.case.id, text: `${bug.label}: bug filed for ${r.case.id}${bug.note ? ` (${bug.note})` : ""}`, url: bug.url })
+      }
+    } catch (err) {
+      out.push({ source: "bugs", caseId: r.case.id, text: `${r.case.id}: bug not filed`, error: (err as Error).message })
+    }
+  }
+  return out
+}
+
+type BugRef = { id: string; label: string; url: string; note?: string }
+
+type Tracker = {
+  findOpen(fingerprint: string): Promise<BugRef | null>
+  create(r: CaseResult, fingerprint: string, runName: string): Promise<BugRef>
+  comment(id: string, text: string): Promise<void>
+}
+
+function screenshot(r: CaseResult): { name: string; data: Buffer } | null {
+  if (!r.runDir) return null
+  const file = path.join(r.runDir, "failure.png")
+  if (!existsSync(file) || statSync(file).size > MAX_ATTACHMENT) return null
+  return { name: `${r.case.id.replace(/[^A-Za-z0-9._-]+/g, "-")}-failure.png`, data: readFileSync(file) }
+}
+
+function jiraTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
+  const j: JiraApi = jiraApi(cfg, "Filing bugs in Jira")
+  const body = (text: string) => (j.cloud ? textToAdf(text) : text)
+  const ref = (key: string): BugRef => ({ id: key, label: key, url: `${j.url}/browse/${key}` })
+  return {
+    async findOpen(fp) {
+      const jql = `project = "${b.project}" AND labels = "${fp}" AND statusCategory != Done ORDER BY created DESC`
+      const q = new URLSearchParams({ jql, fields: "summary", maxResults: "1" })
+      const { data } = await http<{ issues?: { key: string; id: string }[] }>(`${j.api}/${j.cloud ? "search/jql" : "search"}?${q}`, { auth: j.auth })
+      const hit = data?.issues?.[0]
+      return hit ? ref(hit.key) : null
+    },
+    async create(r, fp, runName) {
+      const { data } = await http<{ key: string; id: string }>(`${j.api}/issue`, {
+        auth: j.auth,
+        body: {
+          fields: {
+            project: { key: b.project },
+            issuetype: { name: b.type },
+            summary: bugTitle(r),
+            description: body(bugText(r, runName)),
+            labels: [...new Set([...b.labels, fp])],
+          },
+        },
+      })
+      const notes: string[] = []
+      const shot = screenshot(r)
+      if (shot) {
+        const form = new FormData()
+        form.append("file", new Blob([new Uint8Array(shot.data)], { type: "image/png" }), shot.name)
+        const res = await fetch(`${j.api}/issue/${encodeURIComponent(data.key)}/attachments`, {
+          method: "POST",
+          headers: { Authorization: j.auth, "X-Atlassian-Token": "no-check", Accept: "application/json" },
+          body: form,
+        })
+        notes.push(res.ok ? "screenshot attached" : `screenshot not attached: ${res.status}`)
+      }
+      const linked = r.case.source === "jira" || r.case.source === "xray" ? String(r.case.ref?.issue || r.case.ref?.test || r.case.id) : ""
+      if (linked) {
+        try {
+          await http(`${j.api}/issueLink`, { auth: j.auth, body: { type: { name: "Relates" }, inwardIssue: { key: data.key }, outwardIssue: { key: linked } } })
+          notes.push(`linked to ${linked}`)
+        } catch {
+          notes.push(`not linked to ${linked}`)
+        }
+      }
+      return { ...ref(data.key), note: notes.join(", ") || undefined }
+    },
+    async comment(id, text) {
+      await http(`${j.api}/issue/${encodeURIComponent(id)}/comment`, { auth: j.auth, body: { body: body(text) } })
+    },
+  }
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+const html = (text: string) => text.split("\n").map((l) => (l ? `<div>${esc(l)}</div>` : "<br>")).join("")
+
+function adoTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
+  const { ado, auth } = adoSettings(cfg)
+  const project = ado.project || b.project
+  if (!project) throw new Error("Azure DevOps bugs need a project. Set sources.bugs.project or sources.azure_devops.project.")
+  const base = `${ado.orgUrl.replace(/\/+$/, "")}/${encodeURIComponent(project)}`
+  const api = "api-version=7.1"
+  const ref = (id: number | string): BugRef => ({ id: String(id), label: `${b.type} ${id}`, url: `${base}/_workitems/edit/${id}` })
+  return {
+    async findOpen(fp) {
+      const query =
+        `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] = '${b.type.replace(/'/g, "''")}' ` +
+        `AND [System.Tags] CONTAINS '${fp}' AND [System.State] NOT IN ('Closed', 'Done', 'Removed', 'Resolved') ORDER BY [System.CreatedDate] DESC`
+      const { data } = await http<{ workItems?: { id: number }[] }>(`${base}/_apis/wit/wiql?${api}&$top=1`, { auth, body: { query } })
+      const hit = data?.workItems?.[0]
+      return hit ? ref(hit.id) : null
+    },
+    async create(r, fp, runName) {
+      const notes: string[] = []
+      const ops: Record<string, unknown>[] = [
+        { op: "add", path: "/fields/System.Title", value: bugTitle(r) },
+        { op: "add", path: "/fields/Microsoft.VSTS.TCM.ReproSteps", value: html(bugText(r, runName)) },
+        { op: "add", path: "/fields/System.Tags", value: [...new Set([...b.labels, fp])].join("; ") },
+      ]
+      if (b.areaPath) ops.push({ op: "add", path: "/fields/System.AreaPath", value: b.areaPath })
+      const testCase = r.case.source === "ado" ? Number(r.case.ref?.workItem) : 0
+      if (testCase) {
+        ops.push({ op: "add", path: "/relations/-", value: { rel: "Microsoft.VSTS.Common.TestedBy-Forward", url: `${ado.orgUrl}/_apis/wit/workItems/${testCase}` } })
+        notes.push(`linked to test case ${testCase}`)
+      }
+      const shot = screenshot(r)
+      if (shot) {
+        const res = await fetch(`${base}/_apis/wit/attachments?fileName=${encodeURIComponent(shot.name)}&${api}`, {
+          method: "POST",
+          headers: { Authorization: auth, "Content-Type": "application/octet-stream", Accept: "application/json" },
+          body: new Uint8Array(shot.data),
+        })
+        if (res.ok) {
+          const att = (await res.json()) as { url?: string }
+          if (att.url) {
+            ops.push({ op: "add", path: "/relations/-", value: { rel: "AttachedFile", url: att.url, attributes: { comment: "Last screenshot" } } })
+            notes.push("screenshot attached")
+          }
+        } else notes.push(`screenshot not attached: ${res.status}`)
+      }
+      const { data } = await http<{ id: number }>(`${base}/_apis/wit/workitems/$${encodeURIComponent(b.type)}?${api}`, {
+        auth,
+        body: ops,
+        contentType: "application/json-patch+json",
+      })
+      return { ...ref(data.id), note: notes.join(", ") || undefined }
+    },
+    async comment(id, text) {
+      await http(`${base}/_apis/wit/workItems/${id}/comments?api-version=7.1-preview.4`, { auth, body: { text: html(text) } })
+    },
+  }
+}