@capagents/forgeqe 1.1.4 → 1.1.5

package/src/cases/index.ts

@@ -4,6 +4,7 @@ import path from "node:path"
 import type { SourcesConfig } from "../config.ts"
 import { adoCases, adoWriteBack } from "./ado.ts"
 import { fileCases, textCase } from "./files.ts"
+import { githubCases, githubWriteBack } from "./github.ts"
 import { jiraCases, jiraWriteBack } from "./jira.ts"
 import { qtestCases, qtestWriteBack } from "./qtest.ts"
 import { testrailCases, testrailWriteBack } from "./testrail.ts"
@@ -18,10 +19,11 @@ export type { CaseResult, CaseStatus, CaseStep, TestCase, WriteBack } from "./ty
  * Where a reference points: `ado:…`, `jira:…`, `xray:…`, `testrail:…`, `zephyr:…`, `qtest:…`, an existing file, or
  * otherwise plain text that is itself the test case.
  */
-export function refKind(ref: string): "ado" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "file" | "text" {
-  const scheme = ref.match(/^(ado|azure|jira|xray|testrail|zephyr|qtest):/i)?.[1]?.toLowerCase()
+export function refKind(ref: string): "ado" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "github" | "file" | "text" {
+  const scheme = ref.match(/^(ado|azure|jira|xray|testrail|zephyr|qtest|github|gh):/i)?.[1]?.toLowerCase()
   if (scheme === "ado" || scheme === "azure") return "ado"
-  if (scheme) return scheme as "jira" | "xray" | "testrail" | "zephyr" | "qtest"
+  if (scheme === "gh") return "github"
+  if (scheme) return scheme as "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "github"
   const file = path.resolve(ref)
   if (ref.length < 1024 && existsSync(file) && statSync(file).isFile()) return "file"
   return "text"
@@ -39,6 +41,7 @@ export async function loadCases(refs: string[], cfg: SourcesConfig): Promise<Tes
     else if (kind === "testrail") cases.push(...(await testrailCases(rest, cfg)))
     else if (kind === "zephyr") cases.push(...(await zephyrCases(rest, cfg)))
     else if (kind === "qtest") cases.push(...(await qtestCases(rest, cfg)))
+    else if (kind === "github") cases.push(...(await githubCases(rest, cfg)))
     else if (kind === "file") cases.push(...fileCases(path.resolve(ref)))
     else cases.push(textCase(ref, ++texts))
   }
@@ -47,8 +50,14 @@ export async function loadCases(refs: string[], cfg: SourcesConfig): Promise<Tes
 
 /** Where the agent wants test cases from, as it decided from the user's request. */
 export type CaseSelector = {
-  source: "azure_devops" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "file" | "text"
+  source: "azure_devops" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "github" | "file" | "text"
   ids?: string[]
+  /** github: owner/repo (default sources.github.repo). */
+  repo?: string
+  /** github: issue labels, all of which a case has. */
+  labels?: string[]
+  /** github: GitHub issue search, e.g. "login in:title is:open". */
+  query?: string
   plan?: string
   suite?: string
   run?: string
@@ -82,6 +91,15 @@ export async function casesFrom(selectors: CaseSelector[], cfg: SourcesConfig, c
       cases.push(...(await zephyrCases(s.cycle ? `cycle=${s.cycle}` : s.folder ? `folder=${s.folder}` : ids(s, "Zephyr Scale"), cfg)))
     } else if (s.source === "qtest") {
       cases.push(...(await qtestCases(s.cycle ? `cycle=${s.cycle}` : s.suite ? `suite=${s.suite}` : ids(s, "qTest"), cfg)))
+    } else if (s.source === "github") {
+      const repo = s.repo ? `${s.repo} ` : ""
+      const nums = (s.ids || []).map((i) => String(i).trim()).filter(Boolean)
+      const sel = s.query ? `q=${s.query}` : s.labels?.length ? `label=${s.labels.join(",")}` : nums.length ? nums.map((n) => (n.includes("#") ? n : `#${n}`)).join(",") : ""
+      if (!sel) throw new Error("GitHub: give issue numbers, labels, or a query.")
+      // owner/repo#12 ids name their own repository; the others take repo.
+      if (nums.some((n) => /^[^#\s]+\/[^#\s]+#\d+$/.test(n)) && !s.query && !s.labels?.length) {
+        for (const n of nums) cases.push(...(await githubCases(n, cfg)))
+      } else cases.push(...(await githubCases(`${repo}${sel}`.trim(), cfg)))
     } else if (s.source === "file") {
       if (!s.paths?.length) throw new Error("File source: give the file paths.")
       for (const p of s.paths) {
@@ -117,6 +135,7 @@ export async function writeBack(results: CaseResult[], cfg: SourcesConfig, runNa
     ["testrail", (rs) => testrailWriteBack(rs, cfg, runName)],
     ["zephyr", (rs) => zephyrWriteBack(rs, cfg, runName)],
     ["qtest", (rs) => qtestWriteBack(rs, cfg, runName)],
+    ["github", (rs) => githubWriteBack(rs, cfg)],
   ]
   for (const [source, post] of tasks) {
     const rs = of(source)

package/src/cases/predict.ts

@@ -0,0 +1,372 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { importsOf } from "../code/impact.ts"
+import { DEFECT_HISTORY, readDefectHistory, type DefectHistoryFile, type PastDefect } from "./defectHistory.ts"
+import type { DefectCluster } from "./defects.ts"
+import type { CaseStatus } from "./types.ts"
+
+/**
+ * Defect intelligence, part four: where the next defects are likely, and how the defects went over time.
+ *
+ * An area is a page or an API route, by its path without ids (/checkout, /api/cart/:id). What ForgeQE knows about each
+ * comes from the suites saved in one folder: the pages their cases ended on, the defects in defect-history.json, and
+ * how often the cases failed. A prediction scores the areas a change touches (a file named after the area, a diff that
+ * mentions its route) by that history, with every reason given. It is a heuristic, not a model: each prediction is
+ * saved and scored against the next suite, so the trend report says how often it was right.
+ */
+
+export const PREDICTIONS = "defect-predictions.json"
+const KEEP = 30
+const WINDOW = 10
+const GENERIC = new Set(["api", "v1", "v2", "v3", "rest", "graphql", "www", "app", "index", "home", "static", "assets", "src", "public"])
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte|py|cs|java|kt|go|rb|php|rs|scala|swift)$/i
+const NOT_PRODUCT = /(^|\/)(tests?|__tests__|spec|e2e|docs?|\.github|\.forgeqe)\/|\.(test|spec)\.[a-z]+$/i
+
+export type Level = "high" | "medium" | "low"
+
+export type RiskArea = {
+  area: string
+  level: Level
+  score: number
+  reasons: string[]
+  /** Changed files that touch the area. */
+  changed: string[]
+  /** Cases that ended on the area in earlier suites: the ones to run first. */
+  cases: string[]
+  defects: { id: string; title: string; seen: number; open: boolean; returns: number }[]
+}
+
+export type Prediction = {
+  id: string
+  at: string
+  repo: string
+  base: string
+  head: string
+  changed: string[]
+  areas: RiskArea[]
+  /** Changed product code that touches no area ForgeQE has seen: nothing tests it yet. */
+  untested: string[]
+  /** The cases to run first, the riskiest areas' first. */
+  runFirst: string[]
+  /** Filled in by the first suite after it: whether its defects fell in the areas predicted. */
+  scored?: { suite: string; at: string; defects: number; inPredicted: number; high: number; highWithDefect: number }
+}
+
+type PredictionsFile = { version: 1; predictions: Prediction[] }
+
+/** An area's path, from a URL or a route ("localhost:4517/api/cart/:id" → /api/cart/:id). */
+export function areaPath(urlOrRoute: string): string {
+  // "localhost:4517/api" parses as a URL whose scheme is "localhost:": only a "://" makes one.
+  let p: string
+  try {
+    p = urlOrRoute.includes("://") ? new URL(urlOrRoute).pathname : urlOrRoute.slice(Math.max(0, urlOrRoute.indexOf("/"))) || "/"
+  } catch {
+    p = "/"
+  }
+  if (!p.startsWith("/")) p = "/"
+  const segs = p.split(/[?#]/)[0].split("/").map((s) => (s && /\d/.test(s) && /^(\d+|[0-9a-f-]{8,}|(?=.*\d)[A-Za-z0-9_-]{16,})$/i.test(s) ? ":id" : s))
+  return segs.join("/").replace(/\/+$/, "") || "/"
+}
+
+/** The area a defect is in: its route for a failed request, else the page it was seen on. */
+export function areaOf(d: Pick<DefectCluster, "kind" | "title" | "page"> | (Pick<PastDefect, "kind" | "title"> & { page?: string })): string | undefined {
+  if (d.kind === "request") return areaPath(d.title.replace(/ (returns \d{3}|fails)$/, ""))
+  return d.page ? areaPath(d.page) : undefined
+}
+
+/** The words of an area a file or a change would carry: /api/cart/:id → cart. */
+export function areaWords(area: string): string[] {
+  return area.split("/").filter((w) => w.length >= 3 && !w.startsWith(":") && !GENERIC.has(w.toLowerCase()))
+}
+
+type SavedSuite = { name: string; at: string; results: { case: { id: string }; status: CaseStatus; finalUrl?: string }[] }
+
+function savedSuites(folder: string): SavedSuite[] {
+  let names: string[] = []
+  try {
+    names = readdirSync(folder).filter((n) => existsSync(path.join(folder, n, "suite.json")))
+  } catch {}
+  const out: SavedSuite[] = []
+  for (const name of names) {
+    try {
+      const s = JSON.parse(readFileSync(path.join(folder, name, "suite.json"), "utf8"))
+      if (s?.startedAt && Array.isArray(s.results)) out.push({ name, at: s.startedAt, results: s.results })
+    } catch {}
+  }
+  return out.sort((a, b) => a.at.localeCompare(b.at))
+}
+
+export type AreaFacts = { area: string; cases: Set<string>; runs: number; failed: number; failedLast: boolean; defects: RiskArea["defects"] }
+
+/** What the suites in `folder` and its defect history know about each area. */
+export function areaFacts(folder: string, history: DefectHistoryFile = readDefectHistory(path.join(folder, DEFECT_HISTORY))): Map<string, AreaFacts> {
+  const facts = new Map<string, AreaFacts>()
+  const get = (area: string) => {
+    let f = facts.get(area)
+    if (!f) facts.set(area, (f = { area, cases: new Set(), runs: 0, failed: 0, failedLast: false, defects: [] }))
+    return f
+  }
+  const suites = savedSuites(folder).slice(-WINDOW)
+  suites.forEach((s, i) => {
+    for (const r of s.results) {
+      if (!r.finalUrl || r.status === "stopped") continue
+      const f = get(areaPath(r.finalUrl))
+      f.cases.add(r.case.id)
+      f.runs++
+      if (r.status !== "passed") {
+        f.failed++
+        if (i === suites.length - 1) f.failedLast = true
+      }
+    }
+  })
+  for (const [id, d] of Object.entries(history.defects)) {
+    const area = areaOf(d)
+    if (!area) continue
+    const f = get(area)
+    for (const c of d.cases) f.cases.add(c)
+    f.defects.push({ id, title: d.title, seen: d.seen, open: !d.goneSince, returns: d.returns?.length || 0 })
+  }
+  return facts
+}
+
+const git = (repo: string, args: string[]) => spawnSync("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 50 * 1024 * 1024 })
+
+export type Change = {
+  files: string[]
+  diff: Map<string, string>
+  /** For each changed file, the repository's files that import it: a change to a helper reaches what uses it. */
+  usedBy?: Map<string, string[]>
+}
+
+const MAX_SCAN = 4000
+const MAX_READ = 300_000
+
+/** The files a change touches, its diff, and who imports each changed file, between the merge base of `base` and `head`. */
+export function changeOf(repo: string, base: string, head = "HEAD"): Change {
+  const range = `${base}...${head}`
+  const names = git(repo, ["diff", "--name-only", range])
+  if (names.status !== 0) throw new Error(`git diff ${range} failed in ${repo}: ${names.stderr.trim().split("\n")[0]}`)
+  const files = names.stdout.split("\n").map((l) => l.trim()).filter(Boolean)
+  const diff = new Map<string, string>()
+  const patch = git(repo, ["diff", "-U0", range])
+  let current = ""
+  for (const line of patch.stdout.split("\n")) {
+    const m = /^\+\+\+ b\/(.+)$/.exec(line)
+    if (m) current = m[1]
+    else if (current && (line.startsWith("+") || line.startsWith("-")) && !line.startsWith("---")) diff.set(current, `${diff.get(current) || ""}${line.slice(1)}\n`)
+  }
+  const usedBy = new Map<string, string[]>()
+  const changed = new Set(files)
+  const all = git(repo, ["ls-files"]).stdout.split("\n").map((l) => l.trim()).filter((f) => f && CODE.test(f) && !NOT_PRODUCT.test(f))
+  const known = new Set(all)
+  for (const rel of all.slice(0, MAX_SCAN)) {
+    let text = ""
+    try {
+      const file = path.join(repo, rel)
+      if (statSync(file).size <= MAX_READ) text = readFileSync(file, "utf8")
+    } catch {}
+    for (const dep of importsOf(rel, text, known)) if (changed.has(dep) && dep !== rel) usedBy.set(dep, [...(usedBy.get(dep) || []), rel])
+  }
+  return { files, diff, usedBy }
+}
+
+const LEVEL = (score: number): Level => (score >= 6 ? "high" : score >= 3 ? "medium" : "low")
+
+/** Score each area the change touches, with the reasons, riskiest first. */
+export function predict(facts: Map<string, AreaFacts>, change: Change): Pick<Prediction, "areas" | "untested" | "runFirst"> {
+  const product = change.files.filter((f) => CODE.test(f) && !NOT_PRODUCT.test(f))
+  const touched = new Set<string>()
+  const areas: RiskArea[] = []
+  for (const f of facts.values()) {
+    const words = areaWords(f.area)
+    const route = f.area.split("/:")[0]
+    const namedAfter = (file: string) => words.some((w) => file.toLowerCase().includes(w.toLowerCase()))
+    const named = product.filter(namedAfter)
+    // The route on its own: "/cart" in "/api/cart" is another route.
+    const own = new RegExp(`(^|[^\\w/-])${route.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w-])`)
+    const mentioned = route.length > 1 ? product.filter((file) => own.test(change.diff.get(file) || "")) : []
+    const used = product.filter((file) => !named.includes(file) && (change.usedBy?.get(file) || []).some(namedAfter))
+    const changed = [...new Set([...mentioned, ...named, ...used])]
+    if (!changed.length) continue
+    for (const c of changed) touched.add(c)
+    const reasons: string[] = []
+    let score = 0
+    if (mentioned.length) {
+      score += 3
+      reasons.push(`the change mentions ${route} (${mentioned.slice(0, 3).join(", ")})`)
+    }
+    if (named.length) {
+      score += 2
+      reasons.push(`it changes ${named.slice(0, 3).join(", ")}${named.length > 3 ? ` and ${named.length - 3} more` : ""}`)
+    } else if (used.length) {
+      score += 1
+      const by = (change.usedBy?.get(used[0]) || []).filter(namedAfter)
+      reasons.push(`it changes ${used[0]}, which ${by.slice(0, 2).join(" and ")} import${by.length === 1 ? "s" : ""}${used.length > 1 ? ` (and ${used.length - 1} more such file${used.length === 2 ? "" : "s"})` : ""}`)
+    }
+    const defects = [...f.defects].sort((a, b) => b.seen - a.seen)
+    if (defects.length) {
+      score += 2 * Math.min(defects.length, 3)
+      reasons.push(`${defects.length} defect${defects.length === 1 ? "" : "s"} here before, the latest: ${defects[0].title}`)
+    }
+    const returned = defects.reduce((n, d) => n + d.returns, 0)
+    if (returned) {
+      score += 2
+      reasons.push(`defects came back here ${returned} time${returned === 1 ? "" : "s"} after they were fixed`)
+    }
+    if (defects.some((d) => d.open)) {
+      score += 1
+      reasons.push("a defect here is still open")
+    }
+    if (f.runs) {
+      const rate = f.failed / f.runs
+      if (rate >= 0.2) {
+        score += rate >= 0.5 ? 2 : 1
+        reasons.push(`its cases failed in ${f.failed} of ${f.runs} recent runs`)
+      }
+    }
+    if (!f.cases.size) reasons.push("no case ends on it: nothing tests it directly")
+    areas.push({ area: f.area, level: LEVEL(score), score, reasons, changed, cases: [...f.cases], defects })
+  }
+  areas.sort((a, b) => b.score - a.score || a.area.localeCompare(b.area))
+  const runFirst = [...new Set(areas.filter((a) => a.level !== "low").flatMap((a) => a.cases))]
+  return { areas, untested: product.filter((f) => !touched.has(f)), runFirst }
+}
+
+const predictionsFile = (folder: string) => path.join(folder, PREDICTIONS)
+
+export function readPredictions(folder: string): PredictionsFile {
+  try {
+    const d = JSON.parse(readFileSync(predictionsFile(folder), "utf8")) as PredictionsFile
+    return { version: 1, predictions: Array.isArray(d?.predictions) ? d.predictions : [] }
+  } catch {
+    return { version: 1, predictions: [] }
+  }
+}
+
+export function savePrediction(folder: string, p: Prediction): void {
+  const file = readPredictions(folder)
+  file.predictions = [...file.predictions, p].slice(-KEEP)
+  writeFileSync(predictionsFile(folder), `${JSON.stringify(file, null, 2)}\n`)
+}
+
+/**
+ * Score the newest prediction made before this suite, once: how many of the suite's defects fell in the areas it
+ * named (medium or high), and how many of its high areas had one. Returns it, scored, or undefined.
+ */
+export function scorePrediction(folder: string, suite: string, startedAt: string, clusters: DefectCluster[]): Prediction | undefined {
+  const file = readPredictions(folder)
+  const p = [...file.predictions].reverse().find((x) => x.at <= startedAt)
+  if (!p || p.scored) return undefined
+  const named = new Set(p.areas.filter((a) => a.level !== "low").map((a) => a.area))
+  const high = p.areas.filter((a) => a.level === "high").map((a) => a.area)
+  const hit = clusters.map((c) => areaOf(c)).filter((a): a is string => Boolean(a))
+  p.scored = { suite, at: startedAt, defects: hit.length, inPredicted: hit.filter((a) => named.has(a)).length, high: high.length, highWithDefect: high.filter((a) => hit.includes(a)).length }
+  writeFileSync(predictionsFile(folder), `${JSON.stringify(file, null, 2)}\n`)
+  return p
+}
+
+export type DefectTrends = {
+  suites: number
+  defects: number
+  open: number
+  gone: number
+  /** Defects that came back after going away, and how many times in all. */
+  regressions: number
+  returns: number
+  /** Days from first seen to gone, for the defects that went away. */
+  daysToFix?: { median: number; mean: number; count: number }
+  recurring: { id: string; title: string; seen: number; firstSeen: string; lastSeen: string; open: boolean; returns: number; bug?: { label: string; url?: string } }[]
+  areas: { area: string; defects: number; open: number; failed: number; runs: number; cases: number }[]
+  /** Defects found in each suite, oldest first. */
+  perSuite: { suite: string; at: string; defects: number; failed: number }[]
+  predictions?: { scored: number; defects: number; inPredicted: number; high: number; highWithDefect: number }
+}
+
+const DAY = 86_400_000
+
+/** How the defects of the suites in `folder` went over time. */
+export function defectTrends(folder: string): DefectTrends {
+  const h = readDefectHistory(path.join(folder, DEFECT_HISTORY))
+  const all = Object.entries(h.defects)
+  const suites = savedSuites(folder)
+  const days = all.filter(([, d]) => d.goneSince).map(([, d]) => (Date.parse(d.goneSince!) - Date.parse(d.firstSeen)) / DAY).filter((n) => n >= 0).sort((a, b) => a - b)
+  const round = (n: number) => Math.round(n * 10) / 10
+  const facts = areaFacts(folder, h)
+  const scored = readPredictions(folder).predictions.filter((p) => p.scored)
+  const sum = (k: keyof NonNullable<Prediction["scored"]>) => scored.reduce((n, p) => n + Number(p.scored![k] || 0), 0)
+  const perSuite = suites.map((s) => {
+    const json = (() => {
+      try {
+        return JSON.parse(readFileSync(path.join(folder, s.name, "suite.json"), "utf8")) as { defects?: unknown[] }
+      } catch {
+        return {}
+      }
+    })()
+    return { suite: s.name, at: s.at, defects: Array.isArray(json.defects) ? json.defects.length : 0, failed: s.results.filter((r) => r.status === "failed" || r.status === "error").length }
+  })
+  return {
+    suites: suites.length,
+    defects: all.length,
+    open: all.filter(([, d]) => !d.goneSince).length,
+    gone: all.filter(([, d]) => d.goneSince).length,
+    regressions: all.filter(([, d]) => d.returns?.length).length,
+    returns: all.reduce((n, [, d]) => n + (d.returns?.length || 0), 0),
+    ...(days.length ? { daysToFix: { median: round(days[Math.floor((days.length - 1) / 2)]), mean: round(days.reduce((a, b) => a + b, 0) / days.length), count: days.length } } : {}),
+    recurring: all
+      .map(([id, d]) => ({ id, title: d.title, seen: d.seen, firstSeen: d.firstSeen, lastSeen: d.lastSeen, open: !d.goneSince, returns: d.returns?.length || 0, ...(d.bug ? { bug: d.bug } : {}) }))
+      .sort((a, b) => b.seen - a.seen || b.lastSeen.localeCompare(a.lastSeen))
+      .slice(0, 10),
+    areas: [...facts.values()]
+      .filter((f) => f.defects.length || f.failed)
+      .map((f) => ({ area: f.area, defects: f.defects.length, open: f.defects.filter((d) => d.open).length, failed: f.failed, runs: f.runs, cases: f.cases.size }))
+      .sort((a, b) => b.defects - a.defects || b.failed - a.failed)
+      .slice(0, 10),
+    perSuite: perSuite.slice(-20),
+    ...(scored.length ? { predictions: { scored: scored.length, defects: sum("defects"), inPredicted: sum("inPredicted"), high: sum("high"), highWithDefect: sum("highWithDefect") } } : {}),
+  }
+}
+
+const pct = (a: number, b: number) => (b ? `${Math.round((a / b) * 100)}%` : "—")
+
+/** The trends as Markdown, for defect-trends.md and the terminal. */
+export function trendsMarkdown(t: DefectTrends, generated = new Date().toISOString().slice(0, 16).replace("T", " ")): string {
+  const cell = (s: string) => s.replace(/\|/g, "\\|")
+  const lines = [
+    `# Defect trends`,
+    "",
+    `${t.suites} suite run${t.suites === 1 ? "" : "s"} · ${t.defects} defect${t.defects === 1 ? "" : "s"} found by browser evidence: ${t.open} still there, ${t.gone} gone, ${t.regressions} came back (${t.returns} time${t.returns === 1 ? "" : "s"}) · generated ${generated} UTC`,
+    "",
+    t.daysToFix ? `Time to go away: median ${t.daysToFix.median} days, mean ${t.daysToFix.mean} days, over ${t.daysToFix.count} defect${t.daysToFix.count === 1 ? "" : "s"}.` : "Time to go away: no defect has gone away yet.",
+  ]
+  if (t.predictions) {
+    const p = t.predictions
+    lines.push("", `Predictions: ${p.scored} scored. ${p.inPredicted} of ${p.defects} defects (${pct(p.inPredicted, p.defects)}) fell in an area rated medium or high; ${p.highWithDefect} of ${p.high} high-risk areas (${pct(p.highWithDefect, p.high)}) had a defect.`)
+  }
+  if (t.recurring.length) {
+    lines.push("", "## Most seen", "", "| Defect | Runs | First seen | Last seen | Now | Came back | Bug |", "|---|---|---|---|---|---|---|")
+    for (const d of t.recurring) lines.push(`| ${cell(d.title)} | ${d.seen} | ${d.firstSeen.slice(0, 10)} | ${d.lastSeen.slice(0, 10)} | ${d.open ? "there" : "gone"} | ${d.returns || ""} | ${d.bug ? (d.bug.url ? `[${cell(d.bug.label)}](${d.bug.url})` : cell(d.bug.label)) : ""} |`)
+  }
+  if (t.areas.length) {
+    lines.push("", "## By area", "", "| Area | Defects | Still there | Case failures | Cases |", "|---|---|---|---|---|")
+    for (const a of t.areas) lines.push(`| ${cell(a.area)} | ${a.defects} | ${a.open} | ${a.runs ? `${a.failed} of ${a.runs}` : "—"} | ${a.cases} |`)
+  }
+  if (t.perSuite.length) {
+    lines.push("", "## Per suite", "", "| Suite | Started | Defects | Failed cases |", "|---|---|---|---|")
+    for (const s of t.perSuite) lines.push(`| ${s.suite} | ${s.at.slice(0, 16).replace("T", " ")} | ${s.defects} | ${s.failed} |`)
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** The prediction as Markdown lines, for the terminal and the agent. */
+export function predictionLines(p: Pick<Prediction, "areas" | "untested" | "runFirst" | "changed">): string[] {
+  const lines = [`${p.changed.length} changed file${p.changed.length === 1 ? "" : "s"}; ${p.areas.length} area${p.areas.length === 1 ? "" : "s"} touched.`]
+  for (const a of p.areas) {
+    lines.push("", `${a.level.toUpperCase()} ${a.area} (score ${a.score})`, ...a.reasons.map((r) => `  - ${r}`))
+    if (a.cases.length) lines.push(`  cases: ${a.cases.slice(0, 8).join(", ")}${a.cases.length > 8 ? ` and ${a.cases.length - 8} more` : ""}`)
+  }
+  if (p.runFirst.length) lines.push("", `Run first: ${p.runFirst.join(", ")}`)
+  if (p.untested.length) lines.push("", `Changed with no area ForgeQE has seen (nothing tests them yet): ${p.untested.slice(0, 10).join(", ")}${p.untested.length > 10 ? ` and ${p.untested.length - 10} more` : ""}`)
+  return lines
+}