@capagents/forgeqe 1.1.4 → 1.1.6

package/src/cases/defects.ts

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto"
+
+import { pageKey } from "../quality/history.ts"
+import { problemLine, readTimeline, type BrowserProblem } from "../report/data.ts"
+import { FAILURE_LABEL, type FailureType } from "./failure.ts"
+import type { DefectHistoryNote, PastDefect } from "./defectHistory.ts"
+import type { ReportEnv } from "../report/html.ts"
+import type { RootCause } from "./rca.ts"
+import type { ReproPack } from "./repro.ts"
+import type { CaseResult, WriteBack } from "./types.ts"
+
+/**
+ * Defect intelligence, part one: failures with the same cause are one defect. Each failing case gets a signature from
+ * the strongest evidence its run recorded, ids and numbers taken out so the same fault matches across cases, devices
+ * and runs:
+ *
+ * - request: a request that failed (a 5xx before a 4xx), by its route and status
+ * - exception: an uncaught error in the page, by its message
+ * - console: a console error, by its text
+ * - page: no browser evidence; the page and what the agent saw. Two such cases are one defect only on the same page
+ *   with mostly the same words, and only within a run, since the agent's words change from run to run.
+ *
+ * Errors that also appear in the suite's passing runs are noise (an analytics call, a missing favicon), not evidence.
+ * Evidence is the cause whatever the case's failure was classified as: a 500 that fails one case and stops another
+ * from running is one defect.
+ */
+
+export type SignatureKind = "request" | "exception" | "console" | "page"
+
+/** The defect a failing case belongs to; kept on the case result, so suite.json carries it. */
+export type CaseDefect = {
+  /** forgeqe-d-<hash> for evidence that holds across runs (also the bug's label or tag); forgeqe-p-<hash> for page. */
+  id: string
+  kind: SignatureKind
+  title: string
+  evidence: string[]
+  page?: string
+  /** Words a person filing this bug by hand would likely use (a route, an error message), to find their bugs. */
+  term?: string
+}
+
+/** A second run of a defect's first case: whether it failed the same way. */
+export type Reproduced = { runs: number; failed: number; runDir?: string }
+
+/** One defect and every case it breaks, for the report and the suite summary. */
+export type DefectCluster = CaseDefect & {
+  failure: FailureType | "unclassified"
+  failureLabel: string
+  cases: { id: string; title: string; status: CaseResult["status"]; device?: string }[]
+  pages: string[]
+  bug?: { label: string; url?: string }
+  /** What earlier runs and the bug tracker know about it (src/cases/defectHistory.ts). */
+  history?: DefectHistoryNote
+  /** Open bugs not filed for this defect that mention its route or error: possibly the same. */
+  related?: { label: string; url?: string; title?: string }[]
+  /** How to make it happen again (src/cases/repro.ts). */
+  repro?: ReproPack
+  /** Why it may happen (src/cases/rca.ts): a hypothesis, never a verdict. */
+  rca?: RootCause
+}
+
+const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi
+const ID_SEGMENT = /^(\d+|[0-9a-f-]{8,}|(?=.*\d)[A-Za-z0-9_-]{16,})$/i
+
+/** A URL as its route: host and path, ids in the path as :id, no query or hash. */
+export function routeOf(url: string): string {
+  try {
+    const u = new URL(url)
+    const segs = u.pathname.split("/").map((s) => (s && /\d/.test(s) && ID_SEGMENT.test(s) ? ":id" : s))
+    return `${u.host}${segs.join("/").replace(/\/+$/, "") || "/"}`
+  } catch {
+    return url.split(/[?#]/)[0]
+  }
+}
+
+/** Text with what changes between runs taken out: URLs as routes, then ids, times and numbers. */
+export function normalize(text: string): string {
+  return text
+    .replace(/https?:\/\/[^\s"')]+/g, (u) => routeOf(u))
+    .replace(UUID, "<id>")
+    .replace(/\b[0-9a-f]{12,}\b/gi, "<id>")
+    .replace(/\b\d{4}-\d\d-\d\d[T ][\d:.]+Z?/g, "<time>")
+    .replace(/\d+(\.\d+)?/g, "#")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200)
+}
+
+/** Requests the browser cancels itself (a navigation, a blocker) say nothing about the application. */
+const IGNORED = /ERR_ABORTED|ERR_BLOCKED_BY_CLIENT|favicon\.ico/i
+
+function problemKey(p: BrowserProblem): string {
+  if (p.kind === "network") return `request:${p.status || "failed"} ${routeOf(p.url || p.text)}`
+  if (p.kind === "exception") return `exception:${normalize(p.text.split("\n")[0])}`
+  return `console:${normalize(p.text)}`
+}
+
+/** Stronger evidence first: a server error, an uncaught exception, any other failed request, a console error. */
+function rank(p: BrowserProblem): number {
+  if (p.kind === "network" && (p.status || 0) >= 500) return 0
+  if (p.kind === "exception") return 1
+  if (p.kind === "network") return 2
+  return 3
+}
+
+function errorsOf(r: CaseResult): { p: BrowserProblem; step: number }[] {
+  return readTimeline(r.runDir).flatMap((t, i) => (t.problems || []).filter((p) => p.level === "error" && p.kind !== "slow" && !IGNORED.test(`${p.url || ""} ${p.text}`)).map((p) => ({ p, step: i })))
+}
+
+const clip = (s: string, n: number) => {
+  const t = s.replace(/\s+/g, " ").trim()
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t
+}
+
+/** The route's path without its ids (/api/cart), or the error's message without its type (price is undefined). */
+function problemTerm(p: BrowserProblem): string | undefined {
+  if (p.kind === "network") {
+    const route = routeOf(p.url || p.text)
+    const segs = route.slice(route.indexOf("/")).split("/").filter((s) => s && s !== ":id")
+    return segs.length ? `/${segs.join("/")}` : undefined
+  }
+  if (p.kind === "exception") {
+    const msg = p.text.split("\n")[0].replace(/^[\w.$]*(Error|Exception):\s*/, "").trim()
+    return msg.length >= 8 ? clip(msg, 60) : undefined
+  }
+  return undefined
+}
+
+function problemTitle(p: BrowserProblem): string {
+  if (p.kind === "network") return `${routeOf(p.url || p.text)} ${p.status ? `returns ${p.status}` : "fails"}`
+  if (p.kind === "exception") return `Uncaught error: ${clip(p.text.split("\n")[0], 120)}`
+  return `Console error: ${clip(p.text, 120)}`
+}
+
+/** What the agent saw go wrong, without the step number the failure reason starts with. */
+function reasonOf(r: CaseResult): string {
+  return (r.failure?.reason || r.summary.split("\n")[0] || "").replace(/^Step \d+:\s*/, "").trim()
+}
+
+const STOP = new Set(["the", "and", "but", "not", "was", "were", "with", "that", "this", "from", "for", "page", "shows", "instead", "expected", "step"])
+const words = (s: string) => new Set(normalize(s).toLowerCase().split(/[^a-z#<>]+/).filter((w) => w.length > 2 && !STOP.has(w)))
+
+function overlap(a: Set<string>, b: Set<string>): number {
+  if (!a.size || !b.size) return 0
+  let both = 0
+  for (const w of a) if (b.has(w)) both++
+  return both / (a.size + b.size - both)
+}
+
+const hash = (s: string) => createHash("sha1").update(s).digest("hex").slice(0, 10)
+
+const failureOf = (r: CaseResult): DefectCluster["failure"] => r.failure?.type || "unclassified"
+
+/**
+ * The defects of one suite: the noise its passing runs show, the defects found so far, and the bug each has in this
+ * run. Bug filing runs through `serial`, so two cases of one defect finishing at once file one bug, not two.
+ */
+export class DefectBook {
+  private noise = new Set<string>()
+  private pages: { id: string; failure: string; page: string; words: Set<string> }[] = []
+  private queue: Promise<unknown> = Promise.resolve()
+  /** The bug a defect has in this run, and the case that filed or found it. */
+  readonly bugs = new Map<string, { id: string; label: string; url: string; caseId: string }>()
+  /** The closed bug a defect matched in the tracker: it came back. */
+  readonly closed = new Map<string, { label: string; url?: string; closedAt?: string }>()
+  /** Open bugs not filed by ForgeQE that mention a defect's route or error. */
+  readonly related = new Map<string, { label: string; url?: string; title?: string }[]>()
+  /** What earlier runs know about each defect (defect-history.json); empty outside a suite. */
+  past: Record<string, PastDefect> = {}
+  /** Defects whose first case was run a second time in this suite, to see whether it repeats. */
+  readonly reproduced = new Set<string>()
+  /** Where the suite runs: the browser, the build, the commit; for the repro steps in a bug. */
+  env?: ReportEnv
+  /** How many suites in a row before this one a case failed in: its earlier failures count as repeats. */
+  earlier?: (caseId: string) => number
+
+  /** A passing run's errors are noise for every failure after it. */
+  notePassed(r: CaseResult): void {
+    for (const { p } of errorsOf(r)) this.noise.add(problemKey(p))
+  }
+
+  /** The defect a failing case belongs to; undefined for a case that passed or did not run. */
+  assign(r: CaseResult): CaseDefect | undefined {
+    return this.signature(r, true)
+  }
+
+  /** The defect a failing run would belong to, without recording it: to compare a second run with the first. */
+  peek(r: CaseResult): CaseDefect | undefined {
+    return this.signature(r, false)
+  }
+
+  private signature(r: CaseResult, record: boolean): CaseDefect | undefined {
+    if (r.status !== "failed" && r.status !== "error") return undefined
+    const failure = failureOf(r)
+    const evidence = errorsOf(r)
+      .filter(({ p }) => !this.noise.has(problemKey(p)))
+      // The strongest kind; of those, the one nearest the failure (the latest step).
+      .sort((a, b) => rank(a.p) - rank(b.p) || b.step - a.step)[0]?.p
+    const page = r.finalUrl ? pageKey(r.finalUrl) : undefined
+    if (evidence) {
+      const key = problemKey(evidence)
+      const term = problemTerm(evidence)
+      return { id: `forgeqe-d-${hash(key)}`, kind: key.split(":")[0] as SignatureKind, title: problemTitle(evidence), evidence: [problemLine(evidence)], ...(page ? { page } : {}), ...(term ? { term } : {}) }
+    }
+    const reason = reasonOf(r)
+    const own = words(reason)
+    const same = this.pages.find((c) => c.failure === failure && c.page === (page || "") && overlap(c.words, own) >= 0.5)
+    const id = same?.id || `forgeqe-p-${hash(`${failure}|${page || ""}|${normalize(reason).toLowerCase()}`)}`
+    if (!same && record) this.pages.push({ id, failure, page: page || "", words: own })
+    const where = page ? routeOf(page) : ""
+    return { id, kind: "page", title: clip(`${where ? `${where}: ` : ""}${reason || FAILURE_LABEL[failure as FailureType] || "failed"}`, 160), evidence: reason ? [clip(reason, 300)] : [], ...(page ? { page } : {}) }
+  }
+
+  /** Run `fn` after every earlier call has finished. */
+  serial<T>(fn: () => Promise<T>): Promise<T> {
+    const next = this.queue.then(fn, fn)
+    this.queue = next.catch(() => {})
+    return next
+  }
+}
+
+/**
+ * The suite's defects, the ones breaking most cases first. Results without a defect (passed, not run) are left out.
+ * A defect's bug is the one set on a case, else one posted for it (bugs filed at the end of the suite, or for a case
+ * run on several devices, whose results carry the device in their id).
+ */
+export function defectClusters(results: CaseResult[], posted: WriteBack[] = []): DefectCluster[] {
+  const postedBug = (id: string) => {
+    const w = posted.find((p) => p.source === "bugs" && p.url && !p.error && p.caseId && (p.caseId === id || id.startsWith(`${p.caseId}@`)))
+    return w ? { label: w.text.split(":")[0], url: w.url } : undefined
+  }
+  const byId = new Map<string, DefectCluster>()
+  for (const r of results) {
+    const d = r.defect
+    if (!d || (r.status !== "failed" && r.status !== "error")) continue
+    let c = byId.get(d.id)
+    if (!c) {
+      const failure = failureOf(r)
+      c = { ...d, evidence: [...d.evidence], failure, failureLabel: failure === "unclassified" ? "not classified" : FAILURE_LABEL[failure], cases: [], pages: [] }
+      byId.set(d.id, c)
+    }
+    c.cases.push({ id: r.case.id, title: r.case.title, status: r.status, ...(r.device ? { device: r.device } : {}) })
+    if (d.page && !c.pages.includes(d.page)) c.pages.push(d.page)
+    for (const e of d.evidence) if (c.evidence.length < 5 && !c.evidence.includes(e)) c.evidence.push(e)
+    if (!c.bug) c.bug = r.bug || postedBug(r.case.id)
+  }
+  return [...byId.values()].sort((a, b) => b.cases.length - a.cases.length)
+}
+
+/** "7 failures from 3 defects", or "" when nothing failed. */
+export function defectLine(clusters: DefectCluster[]): string {
+  const failures = clusters.reduce((n, c) => n + c.cases.length, 0)
+  if (!failures) return ""
+  return `${failures} failure${failures === 1 ? "" : "s"} from ${clusters.length} defect${clusters.length === 1 ? "" : "s"}`
+}

package/src/cases/github.ts

@@ -0,0 +1,162 @@
+import { spawnSync } from "node:child_process"
+
+import type { BugsConfig, SourcesConfig } from "../config.ts"
+import type { BugRef, Tracker } from "./bugs.ts"
+import { http } from "./http.ts"
+import { resultText } from "./jira.ts"
+import type { CaseResult, TestCase, WriteBack } from "./types.ts"
+
+/**
+ * GitHub issues as test cases (github:owner/repo#12, github:#12,#13, github:label=login, github:q=<search>), results
+ * posted back as issue comments, and GitHub as a bug tracker. Signs in with GITHUB_TOKEN (sources.github.token_env),
+ * else the GitHub CLI's sign-in (gh auth token), so `forgeqe auth login github` is all it needs.
+ */
+
+export type GithubApi = { api: string; web: string; auth: string; repo?: string }
+
+let ghCached: string | null | undefined
+
+/** The GitHub CLI's token, once per process; never on test machines' saved sign-ins (FORGEQE_SAVED_AUTH=off). */
+export function ghAuthToken(): string | null {
+  if (process.env.FORGEQE_SAVED_AUTH === "off") return null
+  if (ghCached !== undefined) return ghCached
+  if (!Bun.which("gh")) return (ghCached = null)
+  const res = spawnSync("gh", ["auth", "token"], { encoding: "utf8", timeout: 10_000 })
+  ghCached = res.status === 0 ? res.stdout.trim() || null : null
+  return ghCached
+}
+
+/** The token GitHub calls use, or null when there is none (no GITHUB_TOKEN and no gh sign-in). */
+export function githubToken(cfg: SourcesConfig): string | null {
+  const env = cfg.github?.tokenEnv || "GITHUB_TOKEN"
+  return process.env[env]?.trim() || ghAuthToken()
+}
+
+export function githubApi(cfg: SourcesConfig, what = "GitHub"): GithubApi {
+  const token = githubToken(cfg)
+  const env = cfg.github?.tokenEnv || "GITHUB_TOKEN"
+  if (!token) throw new Error(`${what} needs ${env} in the environment, or a GitHub CLI sign-in: run forgeqe auth login github.`)
+  const api = (cfg.github?.apiUrl || "https://api.github.com").replace(/\/+$/, "")
+  const web = api === "https://api.github.com" ? "https://github.com" : api.replace(/\/api\/v3$/, "")
+  return { api, web, auth: `Bearer ${token}`, ...(cfg.github?.repo ? { repo: cfg.github.repo } : {}) }
+}
+
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/
+
+type Issue = { number: number; title: string; body?: string | null; html_url: string; labels?: ({ name?: string } | string)[]; milestone?: { title?: string } | null; pull_request?: unknown }
+
+/** owner/repo#12,#13 · #12 · 12,13 · label=login,smoke · q=<GitHub search> (each optionally after owner/repo). */
+export function parseGithubRef(ref: string, defaultRepo?: string): { repo: string; numbers: number[]; labels: string[]; query?: string } {
+  let rest = ref.trim()
+  let repo = defaultRepo || ""
+  const lead = rest.match(/^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)(?=#|\s|\?|$|:)/)
+  if (lead) {
+    repo = lead[1]
+    rest = rest.slice(lead[0].length).replace(/^[?:\s]+/, "")
+  }
+  if (!REPO.test(repo)) throw new Error(`GitHub reference "${ref}": name the repository as owner/repo (or set sources.github.repo).`)
+  const q = rest.match(/^q=(.+)$/s)?.[1]
+  if (q) return { repo, numbers: [], labels: [], query: q.trim() }
+  const labels = rest.match(/^labels?=(.+)$/s)?.[1]
+  if (labels) return { repo, numbers: [], labels: labels.split(",").map((l) => l.trim()).filter(Boolean) }
+  const numbers = rest.split(/[,\s]+/).map((n) => n.replace(/^#/, "").trim()).filter(Boolean)
+  if (!numbers.length || numbers.some((n) => !/^\d+$/.test(n))) throw new Error(`GitHub reference "${ref}": use owner/repo#12,#13, label=<labels>, or q=<search>.`)
+  return { repo, numbers: numbers.map(Number), labels: [] }
+}
+
+function issueCase(repo: string, i: Issue): TestCase {
+  const labels = (i.labels || []).map((l) => (typeof l === "string" ? l : l.name || "")).filter(Boolean)
+  return {
+    id: `${repo}#${i.number}`,
+    title: i.title || `${repo}#${i.number}`,
+    source: "github",
+    url: i.html_url,
+    description: i.body?.trim() || undefined,
+    steps: [],
+    ...(labels.length ? { tags: labels } : {}),
+    ...(i.milestone?.title ? { group: i.milestone.title } : {}),
+    ref: { repo, issue: i.number },
+  }
+}
+
+export async function githubCases(ref: string, cfg: SourcesConfig): Promise<TestCase[]> {
+  const g = githubApi(cfg)
+  const { repo, numbers, labels, query } = parseGithubRef(ref, g.repo)
+  if (numbers.length) {
+    const out: TestCase[] = []
+    for (const n of numbers) {
+      const { data } = await http<Issue>(`${g.api}/repos/${repo}/issues/${n}`, { auth: g.auth })
+      if (data.pull_request) throw new Error(`${repo}#${n} is a pull request, not an issue: review_pull_request or select_pr_tests cover pull requests.`)
+      out.push(issueCase(repo, data))
+    }
+    return out
+  }
+  // Pull requests are issues to this API: only issues are test cases.
+  const issues: Issue[] = []
+  if (query) {
+    const q = new URLSearchParams({ q: `repo:${repo} is:issue ${query}`, per_page: "100" })
+    issues.push(...((await http<{ items: Issue[] }>(`${g.api}/search/issues?${q}`, { auth: g.auth })).data.items || []))
+  } else {
+    const q = new URLSearchParams({ labels: labels.join(","), state: "open", per_page: "100" })
+    issues.push(...(await http<Issue[]>(`${g.api}/repos/${repo}/issues?${q}`, { auth: g.auth })).data)
+  }
+  return issues.filter((i) => !i.pull_request).map((i) => issueCase(repo, i))
+}
+
+/** Each result as a comment on its issue. */
+export async function githubWriteBack(results: CaseResult[], cfg: SourcesConfig): Promise<WriteBack[]> {
+  const g = githubApi(cfg)
+  const out: WriteBack[] = []
+  for (const r of results) {
+    const repo = String(r.case.ref?.repo || "")
+    const n = Number(r.case.ref?.issue)
+    const label = `${repo}#${n}`
+    try {
+      await http(`${g.api}/repos/${repo}/issues/${n}/comments`, { auth: g.auth, body: { body: resultText(r) } })
+      out.push({ source: "github", caseId: r.case.id, text: `${label}: result added as a comment`, url: r.case.url })
+    } catch (err) {
+      out.push({ source: "github", caseId: r.case.id, text: `${label}: comment not added`, error: (err as Error).message })
+    }
+  }
+  return out
+}
+
+/** GitHub as sources.bugs: an issue per defect or failing case, found again by its fingerprint labels. */
+export function githubBugTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
+  const g = githubApi(cfg, "Filing bugs in GitHub")
+  const repo = b.project || g.repo
+  if (!repo || !REPO.test(repo)) throw new Error("Filing bugs in GitHub needs the repository: sources.bugs.project (owner/repo) or sources.github.repo.")
+  const ref = (n: number, url?: string): BugRef => ({ id: String(n), label: `${repo}#${n}`, url: url || `${g.web}/${repo}/issues/${n}` })
+  return {
+    async findOpen(fp: string): Promise<BugRef | null> {
+      const q = new URLSearchParams({ labels: fp, state: "open", per_page: "1" })
+      const { data } = await http<Issue[]>(`${g.api}/repos/${repo}/issues?${q}`, { auth: g.auth })
+      const hit = data.find((i) => !i.pull_request)
+      return hit ? ref(hit.number, hit.html_url) : null
+    },
+    async findClosed(fp) {
+      const q = new URLSearchParams({ labels: fp, state: "closed", sort: "updated", per_page: "5" })
+      const { data } = await http<(Issue & { closed_at?: string | null; state_reason?: string | null })[]>(`${g.api}/repos/${repo}/issues?${q}`, { auth: g.auth })
+      // Closed as not planned is not a fix: it cannot come back.
+      const hit = data.find((i) => !i.pull_request && i.state_reason !== "not_planned")
+      return hit ? { ...ref(hit.number, hit.html_url), ...(hit.closed_at ? { closedAt: hit.closed_at } : {}) } : null
+    },
+    async related(term, limit) {
+      const q = new URLSearchParams({ q: `repo:${repo} is:issue is:open "${term.replace(/"/g, " ")}"`, per_page: String(limit), sort: "updated" })
+      const { data } = await http<{ items?: Issue[] }>(`${g.api}/search/issues?${q}`, { auth: g.auth })
+      return (data?.items || []).filter((i) => !i.pull_request).map((i) => ({ ...ref(i.number, i.html_url), title: i.title }))
+    },
+    async create(_r, bug) {
+      const regression = bug.regressionOf ? `\n\nRegression of #${bug.regressionOf.id}.` : ""
+      const body = `${bug.body}${regression}\n\n_GitHub has no API to upload a screenshot to an issue: it is in the run folder above._`
+      const { data } = await http<Issue>(`${g.api}/repos/${repo}/issues`, { auth: g.auth, body: { title: bug.title, body, labels: bug.labels } })
+      return ref(data.number, data.html_url)
+    },
+    async comment(id, body) {
+      await http(`${g.api}/repos/${repo}/issues/${id}/comments`, { auth: g.auth, body: { body } })
+    },
+    async tag(id, label) {
+      await http(`${g.api}/repos/${repo}/issues/${id}/labels`, { auth: g.auth, body: { labels: [label] } })
+    },
+  }
+}

package/src/cases/goal.ts

@@ -1,6 +1,6 @@
 import type { TestCase } from "./types.ts"
 
-const SOURCE_NAME = { text: "text", file: "file", ado: "Azure DevOps", jira: "Jira", xray: "Xray", testrail: "TestRail", zephyr: "Zephyr Scale", qtest: "qTest" } as const
+const SOURCE_NAME = { text: "text", file: "file", ado: "Azure DevOps", jira: "Jira", xray: "Xray", testrail: "TestRail", zephyr: "Zephyr Scale", qtest: "qTest", github: "GitHub" } as const
 
 /**
  * The browser goal for a test case: every step with its data and expected result, and an instruction to check each

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)