@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/cases/readiness.ts

@@ -0,0 +1,284 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { DEFAULT_THRESHOLDS, type AppConfig, type ReleaseThresholds } from "../config.ts"
+export { DEFAULT_THRESHOLDS, type ReleaseThresholds }
+import { flakiness, readHistory } from "../code/history.ts"
+import { readMappings } from "../code/traceability.ts"
+import { runDirectory } from "../run.ts"
+import { adoSettings } from "./ado.ts"
+import { http } from "./http.ts"
+import { adoSprints, findSprint } from "./sprints.ts"
+
+/**
+ * Requirement coverage and release readiness for an Azure DevOps scope (a sprint, an area, an epic or feature and
+ * everything under it, or given work items): each story with its test cases, whether each is automated, and its
+ * last result; the stories nobody tests, the cases nobody automated, the open bugs by severity, and the flaky and
+ * quarantined tests; then a verdict, GO, GO WITH RISKS, or NO-GO, with its reasons, from thresholds in forgeqe.yaml.
+ *
+ * A test case's last result is its newest test point outcome in Azure DevOps; where a plan has none, ForgeQE's own
+ * runs: the newest suite report for the case, then the automated test's history.
+ */
+
+export type Scope = { sprint?: string; area?: string; parent?: number; ids?: number[]; project?: string }
+
+export type Outcome = "passed" | "failed" | "blocked" | "not run"
+export type CaseRow = { id: number; title: string; url: string; automated: boolean; test?: string; outcome: Outcome; when?: string; from?: "Azure DevOps" | "ForgeQE"; flaky?: boolean; quarantined?: boolean }
+export type StoryRow = { id: number; type: string; title: string; state: string; url: string; area?: string; cases: CaseRow[] }
+export type BugRow = { id: number; title: string; state: string; severity: number; severityText: string; url: string }
+export type Verdict = "GO" | "GO WITH RISKS" | "NO-GO"
+
+export type Readiness = {
+  scope: string
+  stories: StoryRow[]
+  bugs: BugRow[]
+  counts: { stories: number; untested: number; cases: number; automated: number; executed: number; passed: number; failed: number; blocked: number; notRun: number; flaky: number; quarantined: number }
+  passRate: number | null
+  verdict: Verdict
+  blockers: string[]
+  risks: string[]
+  notes: string[]
+}
+
+type Item = { id: number; fields: Record<string, unknown>; relations?: { rel: string; url: string }[] }
+
+const REQUIREMENT = "[System.WorkItemType] IN GROUP 'Microsoft.RequirementCategory'"
+const OPEN_BUG = "[System.WorkItemType] IN GROUP 'Microsoft.BugCategory' AND [System.State] NOT IN ('Closed', 'Done', 'Removed', 'Resolved')"
+const q = (s: string) => `'${s.replace(/'/g, "''")}'`
+const idOf = (url: string) => Number(url.split("/").pop())
+
+/** The verdict from the counts: blockers make it NO-GO, risks GO WITH RISKS. */
+export function verdictOf(r: Pick<Readiness, "stories" | "bugs" | "counts" | "passRate">, t: ReleaseThresholds): { verdict: Verdict; blockers: string[]; risks: string[] } {
+  const blockers: string[] = []
+  const risks: string[] = []
+  const critical = r.bugs.filter((b) => b.severity === 1).length
+  const high = r.bugs.filter((b) => b.severity === 2).length
+  if (critical > t.maxCritical) blockers.push(`${critical} open critical bug${critical === 1 ? "" : "s"} (allowed: ${t.maxCritical})`)
+  if (high > t.maxHigh) blockers.push(`${high} open high-severity bug${high === 1 ? "" : "s"} (allowed: ${t.maxHigh})`)
+  const failing = r.stories.filter((s) => s.cases.some((c) => c.outcome === "failed" && !c.quarantined))
+  if (failing.length) blockers.push(`${failing.length} stor${failing.length === 1 ? "y has" : "ies have"} a failing test case: ${failing.slice(0, 5).map((s) => `${s.id} ${s.title}`).join("; ")}`)
+  if (r.passRate !== null && r.passRate < t.minPassRate) blockers.push(`pass rate ${r.passRate}% is below ${t.minPassRate}%`)
+  if (t.requireTests && r.counts.untested) risks.push(`${r.counts.untested} stor${r.counts.untested === 1 ? "y has" : "ies have"} no test case`)
+  if (r.counts.notRun) risks.push(`${r.counts.notRun} test case${r.counts.notRun === 1 ? " has" : "s have"} not run`)
+  if (r.counts.blocked) risks.push(`${r.counts.blocked} test case${r.counts.blocked === 1 ? " is" : "s are"} blocked`)
+  if (r.counts.flaky) risks.push(`${r.counts.flaky} automated test${r.counts.flaky === 1 ? " is" : "s are"} flaky`)
+  if (r.counts.quarantined) risks.push(`${r.counts.quarantined} automated test${r.counts.quarantined === 1 ? " is" : "s are"} in quarantine`)
+  const other = r.bugs.filter((b) => b.severity > 2).length
+  if (other) risks.push(`${other} other open bug${other === 1 ? "" : "s"}`)
+  return { verdict: blockers.length ? "NO-GO" : risks.length ? "GO WITH RISKS" : "GO", blockers, risks }
+}
+
+/** The newest result per test case in ForgeQE's suite reports. */
+function forgeqeResults(suitesDir: string): Map<number, { outcome: Outcome; when: string }> {
+  const out = new Map<number, { outcome: Outcome; when: string }>()
+  if (!existsSync(suitesDir)) return out
+  for (const dir of readdirSync(suitesDir).sort()) {
+    try {
+      const suite = JSON.parse(readFileSync(path.join(suitesDir, dir, "suite.json"), "utf8")) as { results?: { case: { id: string; ref?: { workItem?: number } }; status: string; finishedAt?: string; failure?: { type: string } }[] }
+      for (const r of suite.results || []) {
+        const id = Number(r.case.ref?.workItem || /^ADO-(\d+)/.exec(r.case.id)?.[1])
+        if (!id || r.status === "stopped") continue
+        const outcome: Outcome = r.status === "passed" ? "passed" : r.failure && r.failure.type !== "functional_defect" ? "blocked" : "failed"
+        out.set(id, { outcome, when: r.finishedAt || dir })
+      }
+    } catch {}
+  }
+  return out
+}
+
+export async function releaseReadiness(cfg: AppConfig, repo: string, scope: Scope, thresholds: ReleaseThresholds = DEFAULT_THRESHOLDS): Promise<Readiness> {
+  const { org, auth, project: configured } = adoSettings(cfg.sources)
+  const project = scope.project || configured
+  if (!project && !scope.ids?.length) throw new Error("Name the Azure DevOps project (project, or sources.azure_devops.project) for a sprint, area, or epic.")
+  const notes: string[] = []
+  const wiql = async (query: string) => {
+    const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { target?: { id: number } }[] }>(`${org}/${encodeURIComponent(project!)}/_apis/wit/wiql?api-version=7.1`, { auth, body: { query } })
+    return [...new Set([...(data?.workItems || []).map((w) => w.id), ...(data?.workItemRelations || []).map((r) => r.target?.id).filter((n): n is number => Boolean(n))])]
+  }
+  const items = async (ids: number[]) => {
+    const out: Item[] = []
+    for (let i = 0; i < ids.length; i += 200) {
+      const { data } = await http<{ value?: Item[] }>(`${org}/_apis/wit/workitems?ids=${ids.slice(i, i + 200).join(",")}&$expand=relations&api-version=7.1`, { auth })
+      out.push(...(data?.value || []))
+    }
+    return out
+  }
+  const urlOf = (it: Item) => `${org}/${encodeURIComponent(String(it.fields["System.TeamProject"] || project || ""))}/_workitems/edit/${it.id}`
+
+  // The scope: its stories, and the filter its open bugs share.
+  let label: string
+  let filter = ""
+  let storyIds: number[]
+  if (scope.ids?.length) {
+    label = `work items ${scope.ids.join(", ")}`
+    storyIds = scope.ids
+  } else if (scope.parent) {
+    label = `everything under ${scope.parent}`
+    storyIds = (await wiql(`SELECT [System.Id] FROM WorkItemLinks WHERE ([Source].[System.Id] = ${scope.parent}) AND ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward') AND ([Target].${REQUIREMENT}) MODE (Recursive)`)).filter((id) => id !== scope.parent)
+  } else {
+    const parts: string[] = []
+    if (scope.sprint) {
+      const sprints = await adoSprints(cfg.sources)
+      const s = scope.sprint.toLowerCase() === "current" ? sprints.find((x) => x.state === "current") : findSprint(sprints, scope.sprint)
+      if (!s?.path) throw new Error(`No sprint "${scope.sprint}" with an iteration path in ${project}.`)
+      parts.push(`[System.IterationPath] UNDER ${q(s.path)}`)
+      label = `sprint ${s.name}${s.start ? ` (${s.start} to ${s.end})` : ""}`
+    } else label = ""
+    if (scope.area) {
+      parts.push(`[System.AreaPath] UNDER ${q(scope.area)}`)
+      label = [label, `area ${scope.area}`].filter(Boolean).join(", ")
+    }
+    if (!parts.length) throw new Error("Give a sprint, an area, a parent epic or feature, or work item ids.")
+    filter = parts.join(" AND ")
+    storyIds = await wiql(`SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND ${REQUIREMENT} AND [System.State] <> 'Removed' AND ${filter}`)
+  }
+  const storyItems = await items(storyIds)
+
+  // Test cases each story is tested by, and their newest outcome.
+  const caseIds = [...new Set(storyItems.flatMap((s) => (s.relations || []).filter((r) => r.rel === "Microsoft.VSTS.Common.TestedBy-Forward").map((r) => idOf(r.url))))]
+  const caseItems = new Map((await items(caseIds)).map((c) => [c.id, c]))
+  const points = new Map<number, { outcome: Outcome; when: string }>()
+  if (caseIds.length && project) {
+    try {
+      for (let i = 0; i < caseIds.length; i += 200) {
+        const { data } = await http<{ points?: { testCase?: { id: string | number }; outcome?: string; lastUpdatedDate?: string }[]; value?: { testCase?: { id: string | number }; outcome?: string; lastUpdatedDate?: string }[] }>(
+          `${org}/${encodeURIComponent(project)}/_apis/test/points?api-version=7.1-preview.2`,
+          { auth, body: { pointsFilter: { testcaseIds: caseIds.slice(i, i + 200) } } },
+        )
+        for (const p of data?.points || data?.value || []) {
+          const id = Number(p.testCase?.id)
+          const o = String(p.outcome || "").toLowerCase()
+          if (!id || !o || o === "unspecified" || o === "none") continue
+          const outcome: Outcome = o === "passed" ? "passed" : o === "failed" ? "failed" : o === "blocked" ? "blocked" : "not run"
+          const when = p.lastUpdatedDate || ""
+          if (!points.has(id) || (points.get(id)!.when || "") < when) points.set(id, { outcome, when })
+        }
+      }
+    } catch (err) {
+      notes.push(`Test point outcomes could not be read (${(err as Error).message.slice(0, 120)}); ForgeQE's own runs are used.`)
+    }
+  }
+  const local = forgeqeResults(cfg.suite.outDir)
+  const mapping = readMappings(repo).cases
+  const history = readHistory(repo).tests
+  const flakyAfter = cfg.flaky?.flakyAfter ?? 2
+
+  const stories: StoryRow[] = storyItems.map((s) => {
+    const cases = (s.relations || [])
+      .filter((r) => r.rel === "Microsoft.VSTS.Common.TestedBy-Forward")
+      .map((r) => caseItems.get(idOf(r.url)))
+      .filter((c): c is Item => Boolean(c))
+      .map((c): CaseRow => {
+        const map = mapping[`ADO-${c.id}`]
+        const testName = String(c.fields["Microsoft.VSTS.TCM.AutomatedTestName"] || map?.testName || "")
+        const automated = String(c.fields["Microsoft.VSTS.TCM.AutomationStatus"] || "") === "Automated" || Boolean(map && map.status !== "needs_attention")
+        const key = Object.keys(history).find((n) => (testName && (n === testName || n.endsWith(testName))) || n.includes(`ADO-${c.id}`))
+        const f = key ? flakiness(key, history[key], flakyAfter) : undefined
+        const ado = points.get(c.id)
+        const mine = local.get(c.id)
+        const last = key ? history[key].runs.at(-1) : undefined
+        const fromTest = last ? { outcome: (last.status === "passed" ? "passed" : last.status === "failed" ? "failed" : "not run") as Outcome, when: last.at } : undefined
+        const best = [ado && { ...ado, from: "Azure DevOps" as const }, mine && { ...mine, from: "ForgeQE" as const }, fromTest && { ...fromTest, from: "ForgeQE" as const }]
+          .filter((x): x is { outcome: Outcome; when: string; from: "Azure DevOps" | "ForgeQE" } => Boolean(x))
+          .sort((a, b) => (b.when || "").localeCompare(a.when || ""))[0]
+        return {
+          id: c.id,
+          title: String(c.fields["System.Title"] || ""),
+          url: urlOf(c),
+          automated,
+          ...(testName ? { test: testName } : map?.testFile ? { test: map.testFile } : {}),
+          outcome: best?.outcome || "not run",
+          ...(best?.when ? { when: best.when.slice(0, 10) } : {}),
+          ...(best ? { from: best.from } : {}),
+          ...(f?.flaky ? { flaky: true } : {}),
+          ...(f?.quarantined ? { quarantined: true } : {}),
+        }
+      })
+    return { id: s.id, type: String(s.fields["System.WorkItemType"] || ""), title: String(s.fields["System.Title"] || ""), state: String(s.fields["System.State"] || ""), url: urlOf(s), ...(s.fields["System.AreaPath"] ? { area: String(s.fields["System.AreaPath"]) } : {}), cases }
+  })
+
+  // Open bugs: in the scope, and those linked to its stories.
+  const linked = storyItems.flatMap((s) => (s.relations || []).filter((r) => r.rel === "System.LinkTypes.Hierarchy-Forward" || r.rel === "System.LinkTypes.Related").map((r) => idOf(r.url)))
+  const scoped = filter ? await wiql(`SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND ${OPEN_BUG} AND ${filter}`) : []
+  const bugItems = (await items([...new Set([...scoped, ...linked])].filter((id) => !storyIds.includes(id)))).filter(
+    (b) => /bug/i.test(String(b.fields["System.WorkItemType"] || "")) && !/^(closed|done|removed|resolved)$/i.test(String(b.fields["System.State"] || "")),
+  )
+  const bugs: BugRow[] = bugItems
+    .map((b) => {
+      const sev = String(b.fields["Microsoft.VSTS.Common.Severity"] || "")
+      return { id: b.id, title: String(b.fields["System.Title"] || ""), state: String(b.fields["System.State"] || ""), severity: Number(/^(\d)/.exec(sev)?.[1] || 3), severityText: sev || "unset", url: urlOf(b) }
+    })
+    .sort((a, b) => a.severity - b.severity)
+
+  const all = stories.flatMap((s) => s.cases)
+  const executed = all.filter((c) => c.outcome === "passed" || c.outcome === "failed")
+  const passed = all.filter((c) => c.outcome === "passed").length
+  const counts = {
+    stories: stories.length,
+    untested: stories.filter((s) => !s.cases.length).length,
+    cases: all.length,
+    automated: all.filter((c) => c.automated).length,
+    executed: executed.length,
+    passed,
+    failed: all.filter((c) => c.outcome === "failed").length,
+    blocked: all.filter((c) => c.outcome === "blocked").length,
+    notRun: all.filter((c) => c.outcome === "not run").length,
+    flaky: all.filter((c) => c.flaky).length,
+    quarantined: all.filter((c) => c.quarantined).length,
+  }
+  const passRate = executed.length ? Math.round((passed / executed.length) * 1000) / 10 : null
+  const v = verdictOf({ stories, bugs, counts, passRate }, thresholds)
+  return { scope: label, stories, bugs, counts, passRate, ...v, notes }
+}
+
+const MARK: Record<Outcome, string> = { passed: "✅ passed", failed: "❌ failed", blocked: "⛔ blocked", "not run": "⚪ not run" }
+
+/** The report as Markdown, for the wiki and the reports folder. */
+export function readinessMarkdown(r: Readiness, generated = new Date().toISOString().slice(0, 16).replace("T", " ")): string {
+  const icon = r.verdict === "GO" ? "🟢" : r.verdict === "NO-GO" ? "🔴" : "🟡"
+  const c = r.counts
+  const esc = (s: string) => s.replace(/\|/g, "\\|")
+  const lines = [
+    `# Release readiness: ${r.scope}`,
+    "",
+    `**${icon} ${r.verdict}** · generated by ForgeQE ${generated} UTC`,
+    "",
+    ...(r.blockers.length ? ["**Blocking:**", ...r.blockers.map((b) => `- ${b}`), ""] : []),
+    ...(r.risks.length ? ["**Risks:**", ...r.risks.map((b) => `- ${b}`), ""] : []),
+    "| Stories | Without test cases | Test cases | Automated | Executed | Pass rate | Open bugs |",
+    "|---|---|---|---|---|---|---|",
+    `| ${c.stories} | ${c.untested} | ${c.cases} | ${c.automated} (${c.cases ? Math.round((c.automated / c.cases) * 100) : 0}%) | ${c.executed} | ${r.passRate === null ? "–" : `${r.passRate}%`} | ${r.bugs.length} |`,
+    "",
+    "## Coverage",
+    "",
+    "| Story | State | Test case | Automated | Last result |",
+    "|---|---|---|---|---|",
+  ]
+  for (const s of r.stories) {
+    const story = `[${s.id}](${s.url}) ${esc(s.title)}`
+    if (!s.cases.length) {
+      lines.push(`| ${story} | ${s.state} | ⚠️ no test case | | |`)
+      continue
+    }
+    s.cases.forEach((tc, i) => {
+      const extra = tc.quarantined ? " (quarantined)" : tc.flaky ? " (flaky)" : ""
+      lines.push(`| ${i ? "" : story} | ${i ? "" : s.state} | [${tc.id}](${tc.url}) ${esc(tc.title)} | ${tc.automated ? "yes" : "no"}${extra} | ${MARK[tc.outcome]}${tc.when ? ` ${tc.when}` : ""} |`)
+    })
+  }
+  if (r.bugs.length) {
+    lines.push("", "## Open bugs", "", "| Bug | Severity | State |", "|---|---|---|", ...r.bugs.map((b) => `| [${b.id}](${b.url}) ${esc(b.title)} | ${b.severityText} | ${b.state} |`))
+  }
+  const manual = r.stories.flatMap((s) => s.cases.filter((tc) => !tc.automated))
+  if (manual.length) lines.push("", `## Not automated (${manual.length})`, "", ...manual.slice(0, 50).map((tc) => `- [${tc.id}](${tc.url}) ${tc.title}`))
+  if (r.notes.length) lines.push("", ...r.notes.map((n) => `_${n}_`))
+  return `${lines.join("\n")}\n`
+}
+
+/** Save the report beside ForgeQE's other reports. */
+export function saveReadiness(cfg: AppConfig, r: Readiness): { dir: string; markdown: string } {
+  const dir = runDirectory(path.join(cfg.export.outDir, "readiness"))
+  const markdown = readinessMarkdown(r)
+  writeFileSync(path.join(dir, "readiness.md"), markdown)
+  writeFileSync(path.join(dir, "readiness.json"), JSON.stringify(r, null, 2))
+  return { dir, markdown }
+}

package/src/cases/save.ts

@@ -0,0 +1,149 @@
+import type { SourcesConfig } from "../config.ts"
+import { adoSettings } from "./ado.ts"
+import { http, textToAdf } from "./http.ts"
+import { jiraApi } from "./jira.ts"
+
+/** A test case the agent wrote from requirements, to save in Azure DevOps or Jira. */
+export type NewCase = {
+  title: string
+  steps: { action: string; expected?: string }[]
+  preconditions?: string[]
+  description?: string
+}
+
+/** One saved case: created now, or found already linked to the story under the same title (never duplicated). */
+export type SavedCase = { title: string; id: string; url: string; created: boolean; error?: string }
+
+export type SaveResult = { system: "azure_devops" | "jira"; story: { id: string; title: string; url: string }; cases: SavedCase[] }
+
+const API = "api-version=7.1"
+const sameTitle = (a: string, b: string) => a.trim().toLowerCase() === b.trim().toLowerCase()
+
+const escXml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+/** One step string as Azure DevOps stores it: HTML, escaped again inside the steps XML. */
+const stepHtml = (text: string) => escXml(`<DIV><P>${escXml(text).replace(/\n/g, "<BR/>")}</P></DIV>`)
+
+/** Microsoft.VSTS.TCM.Steps for the steps, in the format the test case editor writes (and adoCases reads back). */
+export function adoStepsXml(steps: NewCase["steps"]): string {
+  const body = steps
+    .map((s, i) => {
+      const type = s.expected ? "ValidateStep" : "ActionStep"
+      return `<step id="${i + 2}" type="${type}"><parameterizedString isformatted="true">${stepHtml(s.action)}</parameterizedString><parameterizedString isformatted="true">${stepHtml(s.expected || "")}</parameterizedString><description/></step>`
+    })
+    .join("")
+  return `<steps id="0" last="${steps.length + 1}">${body}</steps>`
+}
+
+const html = (lines: string[]) => lines.map((l) => (l ? `<div>${escXml(l)}</div>` : "<br>")).join("")
+
+function describe(c: NewCase): string[] {
+  const out: string[] = []
+  if (c.description?.trim()) out.push(c.description.trim(), "")
+  if (c.preconditions?.length) out.push("Preconditions:", ...c.preconditions.map((p) => `- ${p}`), "")
+  return out
+}
+
+/**
+ * Create each case as an Azure DevOps Test Case linked to the story (Tests / Tested By), in the story's project, area,
+ * and iteration. A case whose title matches a test case already linked to the story is returned instead of created.
+ */
+export async function saveAdoCases(cfg: SourcesConfig, storyId: number, cases: NewCase[]): Promise<SaveResult> {
+  const { org, auth } = adoSettings(cfg)
+  const { data: story } = await http<{ id: number; fields: Record<string, string>; relations?: { rel: string; url: string }[] }>(
+    `${org}/_apis/wit/workitems/${storyId}?$expand=relations&${API}`,
+    { auth },
+  )
+  const project = story.fields["System.TeamProject"]
+  const base = `${org}/${encodeURIComponent(project)}`
+  const link = (id: number | string) => `${base}/_workitems/edit/${id}`
+  const linked = (story.relations || [])
+    .filter((r) => r.rel === "Microsoft.VSTS.Common.TestedBy-Forward")
+    .map((r) => Number(r.url.split("/").pop()))
+    .filter(Boolean)
+  const existing = linked.length
+    ? ((await http<{ value: { id: number; fields: Record<string, string> }[] }>(`${org}/_apis/wit/workitemsbatch?${API}`, { auth, body: { ids: linked, fields: ["System.Title"], errorPolicy: "omit" } })).data?.value || []).filter(Boolean)
+    : []
+
+  const out: SavedCase[] = []
+  for (const c of cases) {
+    const found = existing.find((w) => sameTitle(w.fields["System.Title"] || "", c.title))
+    if (found) {
+      out.push({ title: c.title, id: String(found.id), url: link(found.id), created: false })
+      continue
+    }
+    const ops: Record<string, unknown>[] = [
+      { op: "add", path: "/fields/System.Title", value: c.title.slice(0, 255) },
+      { op: "add", path: "/fields/Microsoft.VSTS.TCM.Steps", value: adoStepsXml(c.steps) },
+      { op: "add", path: "/fields/System.AreaPath", value: story.fields["System.AreaPath"] },
+      { op: "add", path: "/fields/System.IterationPath", value: story.fields["System.IterationPath"] },
+      { op: "add", path: "/relations/-", value: { rel: "Microsoft.VSTS.Common.TestedBy-Reverse", url: `${org}/_apis/wit/workItems/${storyId}` } },
+    ]
+    const text = describe(c)
+    if (text.length) ops.push({ op: "add", path: "/fields/System.Description", value: html(text) })
+    try {
+      const { data } = await http<{ id: number }>(`${base}/_apis/wit/workitems/$Test%20Case?${API}`, { auth, body: ops, contentType: "application/json-patch+json" })
+      out.push({ title: c.title, id: String(data.id), url: link(data.id), created: true })
+    } catch (err) {
+      out.push({ title: c.title, id: "", url: "", created: false, error: (err as Error).message })
+    }
+  }
+  return { system: "azure_devops", story: { id: String(storyId), title: story.fields["System.Title"] || "", url: link(storyId) }, cases: out }
+}
+
+/**
+ * Create each case as a Jira issue (type `issueType`, default Test) in the story's project with its steps in the
+ * description, linked to the story. A case whose summary matches an issue already linked to the story is reused.
+ */
+export async function saveJiraCases(cfg: SourcesConfig, storyKey: string, cases: NewCase[], opts: { issueType?: string; linkType?: string } = {}): Promise<SaveResult> {
+  const j = jiraApi(cfg, "Saving test cases in Jira")
+  const { data: story } = await http<{ key: string; fields: { summary?: string; project?: { key: string }; issuelinks?: { inwardIssue?: { key: string; fields?: { summary?: string } }; outwardIssue?: { key: string; fields?: { summary?: string } } }[] } }>(
+    `${j.api}/issue/${encodeURIComponent(storyKey)}?fields=summary,project,issuelinks`,
+    { auth: j.auth },
+  )
+  const link = (key: string) => `${j.url}/browse/${key}`
+  const existing = (story.fields.issuelinks || []).flatMap((l) => [l.inwardIssue, l.outwardIssue]).filter((i): i is { key: string; fields?: { summary?: string } } => Boolean(i))
+  const out: SavedCase[] = []
+  for (const c of cases) {
+    const found = existing.find((i) => sameTitle(i.fields?.summary || "", c.title))
+    if (found) {
+      out.push({ title: c.title, id: found.key, url: link(found.key), created: false })
+      continue
+    }
+    const lines = [...describe(c), "Steps:", ...c.steps.map((s, i) => `${i + 1}. ${s.action}${s.expected ? `\n   Expected: ${s.expected}` : ""}`)]
+    const text = lines.join("\n")
+    try {
+      const { data } = await http<{ key: string }>(`${j.api}/issue`, {
+        auth: j.auth,
+        body: { fields: { project: { key: story.fields.project?.key || storyKey.split("-")[0] }, issuetype: { name: opts.issueType || "Test" }, summary: c.title.slice(0, 255), description: j.cloud ? textToAdf(text) : text } },
+      })
+      let error: string | undefined
+      try {
+        await http(`${j.api}/issueLink`, { auth: j.auth, body: { type: { name: opts.linkType || "Relates" }, inwardIssue: { key: data.key }, outwardIssue: { key: story.key } } })
+      } catch (err) {
+        error = `created but not linked to ${story.key}: ${(err as Error).message}`
+      }
+      out.push({ title: c.title, id: data.key, url: link(data.key), created: true, ...(error ? { error } : {}) })
+    } catch (err) {
+      out.push({ title: c.title, id: "", url: "", created: false, error: (err as Error).message })
+    }
+  }
+  return { system: "jira", story: { id: story.key, title: story.fields.summary || "", url: link(story.key) }, cases: out }
+}
+
+/**
+ * Replace an Azure DevOps Test Case's steps (and title, when given), and say why in its history. Returns its link.
+ * The previous steps stay in the work item's history, so the change can be undone there.
+ */
+export async function updateAdoCase(cfg: SourcesConfig, id: number, change: { title?: string; steps: NewCase["steps"]; reason: string }): Promise<string> {
+  const { org, auth } = adoSettings(cfg)
+  const { data: item } = await http<{ fields: Record<string, string> }>(`${org}/_apis/wit/workitems/${id}?fields=System.TeamProject,System.WorkItemType&${API}`, { auth })
+  if (item.fields["System.WorkItemType"] && item.fields["System.WorkItemType"] !== "Test Case") throw new Error(`Work item ${id} is a ${item.fields["System.WorkItemType"]}, not a Test Case.`)
+  const base = `${org}/${encodeURIComponent(item.fields["System.TeamProject"])}`
+  const ops: Record<string, unknown>[] = [
+    { op: "add", path: "/fields/Microsoft.VSTS.TCM.Steps", value: adoStepsXml(change.steps) },
+    { op: "add", path: "/fields/System.History", value: html([`Updated by ForgeQE: ${change.reason}`]) },
+  ]
+  if (change.title?.trim()) ops.push({ op: "add", path: "/fields/System.Title", value: change.title.trim() })
+  await http(`${base}/_apis/wit/workitems/${id}?${API}`, { auth, method: "PATCH", body: ops, contentType: "application/json-patch+json" })
+  return `${base}/_workitems/edit/${id}`
+}

package/src/cases/sprints.ts

@@ -0,0 +1,148 @@
+import type { SourcesConfig } from "../config.ts"
+import { adoProjectNames, adoSettings } from "./ado.ts"
+import { http } from "./http.ts"
+import { jiraApi } from "./jira.ts"
+
+export type Sprint = {
+  system: "azure_devops" | "jira"
+  name: string
+  /** YYYY-MM-DD; empty when the sprint has no dates yet. */
+  start: string
+  end: string
+  state: "current" | "past" | "future"
+  /** Azure DevOps team or Jira board the sprint belongs to. */
+  where: string
+  /** Azure DevOps iteration path ("Shop\\Sprint 12"), for queries. */
+  path?: string
+}
+
+const day = (d: unknown) => (typeof d === "string" ? d.slice(0, 10) : "")
+
+type AdoIteration = { name: string; path?: string; attributes?: { startDate?: string; finishDate?: string; timeFrame?: string } }
+
+/** A team's iterations. Without a team, the default team of the configured project, or of every project. */
+export async function adoSprints(cfg: SourcesConfig, team?: string): Promise<Sprint[]> {
+  const { ado, auth, org } = adoSettings(cfg)
+  if (team && !ado.project) throw new Error("Name sources.azure_devops.project when asking for one team's sprints, or omit the team to read every project's default team.")
+  const projects = ado.project ? [ado.project] : await adoProjectNames(cfg)
+  const out: Sprint[] = []
+  const failed: string[] = []
+  for (const project of projects) {
+    try {
+      out.push(...(await projectSprints(org, project, ado.project ? team : undefined, auth)))
+    } catch (err) {
+      failed.push(`${project}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  if (!out.length && failed.length) throw new Error(failed[0])
+  return out
+}
+
+async function projectSprints(org: string, project: string, team: string | undefined, auth: string): Promise<Sprint[]> {
+  const url = `${org}/${encodeURIComponent(project)}${team ? `/${encodeURIComponent(team)}` : ""}/_apis/work/teamsettings/iterations?api-version=7.1`
+  const { data } = await http<{ value?: AdoIteration[] }>(url, { auth })
+  const where = team || `${project} default team`
+  return (data.value || []).map((it) => {
+    const frame = it.attributes?.timeFrame
+    return {
+      system: "azure_devops" as const,
+      name: it.name,
+      start: day(it.attributes?.startDate),
+      end: day(it.attributes?.finishDate),
+      state: frame === "current" ? "current" : frame === "future" ? "future" : "past",
+      where,
+      ...(it.path ? { path: it.path } : {}),
+    }
+  })
+}
+
+type JiraBoard = { id: number; name: string; location?: { projectKey?: string } }
+type JiraSprint = { name: string; state?: string; startDate?: string; endDate?: string; completeDate?: string }
+
+const MAX_BOARDS = 5
+const MAX_PAGES = 10
+
+/** Sprints of the scrum boards (of a project, or one board by id), up to five boards. */
+export async function jiraSprints(cfg: SourcesConfig, opts: { project?: string; board?: string } = {}): Promise<Sprint[]> {
+  const j = jiraApi(cfg, "Jira sprints")
+  const agile = `${j.url}/rest/agile/1.0`
+  let boards: JiraBoard[]
+  if (opts.board && /^\d+$/.test(opts.board)) {
+    boards = [(await http<JiraBoard>(`${agile}/board/${opts.board}`, { auth: j.auth })).data]
+  } else {
+    const q = new URLSearchParams({ type: "scrum", maxResults: "50" })
+    if (opts.project) q.set("projectKeyOrId", opts.project)
+    if (opts.board) q.set("name", opts.board)
+    boards = (await http<{ values?: JiraBoard[] }>(`${agile}/board?${q}`, { auth: j.auth })).data.values || []
+  }
+  const out: Sprint[] = []
+  for (const b of boards.slice(0, MAX_BOARDS)) {
+    for (let page = 0, startAt = 0; page < MAX_PAGES; page++) {
+      const q = new URLSearchParams({ state: "active,closed,future", maxResults: "50", startAt: String(startAt) })
+      const { data } = await http<{ values?: JiraSprint[]; isLast?: boolean }>(`${agile}/board/${b.id}/sprint?${q}`, { auth: j.auth })
+      const values = data.values || []
+      for (const s of values) {
+        out.push({
+          system: "jira",
+          name: s.name,
+          start: day(s.startDate),
+          end: day(s.endDate || s.completeDate),
+          state: s.state === "active" ? "current" : s.state === "future" ? "future" : "past",
+          where: b.location?.projectKey ? `${b.name} (${b.location.projectKey})` : b.name,
+        })
+      }
+      if (data.isLast !== false || !values.length) break
+      startAt += values.length
+    }
+  }
+  return out
+}
+
+/** Sprints from every configured system; a system that fails is reported in `errors` instead of failing the rest. */
+export async function listSprints(cfg: SourcesConfig, opts: { team?: string; project?: string; board?: string } = {}): Promise<{ sprints: Sprint[]; errors: string[] }> {
+  if (!cfg.ado && !cfg.jira) throw new Error("No sprint source: set up Azure DevOps (sources.azure_devops) or Jira (sources.jira) in forgeqe.yaml, or give a date range instead.")
+  const sprints: Sprint[] = []
+  const errors: string[] = []
+  const tries: [string, () => Promise<Sprint[]>][] = []
+  if (cfg.ado) tries.push(["Azure DevOps", () => adoSprints(cfg, opts.team)])
+  if (cfg.jira) tries.push(["Jira", () => jiraSprints(cfg, { project: opts.project, board: opts.board })])
+  for (const [name, get] of tries) {
+    try {
+      sprints.push(...(await get()))
+    } catch (err) {
+      errors.push(`${name}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  return { sprints, errors }
+}
+
+/** The sprints worth offering: current ones, then the most recent past ones, then the next one, per team or board. */
+export function recentSprints(sprints: Sprint[], past = 3): Sprint[] {
+  const groups = new Map<string, Sprint[]>()
+  for (const s of sprints) {
+    const key = `${s.system}|${s.where}`
+    groups.set(key, [...(groups.get(key) || []), s])
+  }
+  const out: Sprint[] = []
+  for (const list of groups.values()) {
+    const byStart = (a: Sprint, b: Sprint) => a.start.localeCompare(b.start)
+    out.push(...list.filter((s) => s.state === "current"))
+    out.push(...list.filter((s) => s.state === "past").sort(byStart).slice(-past).reverse())
+    out.push(...list.filter((s) => s.state === "future").sort(byStart).slice(0, 1))
+  }
+  return out
+}
+
+export function sprintLabel(s: Sprint): string {
+  const dates = s.start || s.end ? `${s.start || "?"} to ${s.end || "?"}` : "no dates"
+  return `${s.name} (${s.state}, ${dates}, ${s.system === "jira" ? "Jira" : "Azure DevOps"} ${s.where})`
+}
+
+/** The sprint a name refers to: an exact match first, then the only one containing it. */
+export function findSprint(sprints: Sprint[], name: string): Sprint | undefined {
+  const n = name.trim().toLowerCase()
+  const exact = sprints.filter((s) => s.name.toLowerCase() === n)
+  if (exact.length) return exact.find((s) => s.state === "current") || exact[0]
+  const partial = sprints.filter((s) => s.name.toLowerCase().includes(n))
+  return partial.length === 1 ? partial[0] : undefined
+}