@capagents/forgeqe 1.1.4 → 1.1.5

package/src/cases/defectHistory.ts

@@ -0,0 +1,193 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { DefectCluster } from "./defects.ts"
+import type { CaseResult, CaseStatus } from "./types.ts"
+
+/**
+ * Defect intelligence, part two: what earlier runs know about each defect. Kept in defect-history.json next to the
+ * suite folders (the folder the report reads earlier runs from; keep it between CI runs as a cache to track a
+ * pipeline's defects). Only defects found by browser evidence are kept: a defect matched by the agent's words gets
+ * new words, and so a new id, every run.
+ *
+ * - new: never seen before
+ * - known: seen in earlier runs, and still there
+ * - regression: it went away (a case it broke passed, and it was not seen) and came back; or its bug was closed
+ */
+
+export const DEFECT_HISTORY = "defect-history.json"
+const KEEP_SIGHTINGS = 30
+const KEEP_CASES = 50
+/** Earlier suites read to tell an intermittent failure from a steady one. */
+const WINDOW = 20
+
+export type Sighting = { at: string; suite: string; cases: string[] }
+
+export type PastDefect = {
+  title: string
+  kind: string
+  /** The page it was seen on last, for the area it belongs to. */
+  page?: string
+  firstSeen: string
+  lastSeen: string
+  /** Runs it was seen in. */
+  seen: number
+  sightings: Sighting[]
+  /** The cases it has broken, newest last. */
+  cases: string[]
+  bug?: { label: string; url?: string }
+  /** It went away: not seen in a run where a case it broke passed. */
+  goneSince?: string
+  /** When it came back after going away. */
+  returns?: string[]
+}
+
+export type DefectHistoryFile = { version: 1; defects: Record<string, PastDefect> }
+
+export type DefectHistoryNote = {
+  status: "new" | "known" | "regression"
+  /** Earlier runs it was seen in. */
+  seen: number
+  firstSeen?: string
+  /** For a regression: since when it was gone, or the closed bug it matches. */
+  goneSince?: string
+  previousBug?: { label: string; url?: string; closedAt?: string }
+  /** Its cases kept changing between passing and failing: failed in `failed` of the last `runs` runs. */
+  intermittent?: { failed: number; runs: number }
+}
+
+export const defectHistoryFile = (suiteDir: string) => path.join(path.dirname(suiteDir), DEFECT_HISTORY)
+
+export function readDefectHistory(file: string): DefectHistoryFile {
+  try {
+    const d = JSON.parse(readFileSync(file, "utf8")) as DefectHistoryFile
+    return { version: 1, defects: d?.defects && typeof d.defects === "object" ? d.defects : {} }
+  } catch {
+    return { version: 1, defects: {} }
+  }
+}
+
+export function writeDefectHistory(file: string, h: DefectHistoryFile): void {
+  writeFileSync(file, `${JSON.stringify(h, null, 2)}\n`)
+}
+
+type SavedSuite = { at: string; results: { case: { id: string }; status: CaseStatus }[] }
+
+/** The suites saved next to this one (this one left out), oldest first. */
+function savedSuites(suiteDir: string): SavedSuite[] {
+  const parent = path.dirname(suiteDir)
+  const self = path.basename(suiteDir)
+  const suites: SavedSuite[] = []
+  let names: string[] = []
+  try {
+    names = readdirSync(parent).filter((n) => n !== self && existsSync(path.join(parent, n, "suite.json")))
+  } catch {}
+  for (const n of names) {
+    try {
+      const s = JSON.parse(readFileSync(path.join(parent, n, "suite.json"), "utf8"))
+      if (s?.startedAt && Array.isArray(s.results)) suites.push({ at: s.startedAt, results: s.results })
+    } catch {}
+  }
+  return suites.sort((a, b) => a.at.localeCompare(b.at))
+}
+
+/** Each case's results in the suites saved next to this one, oldest first (this suite left out). */
+export function caseOutcomes(suiteDir: string, window = WINDOW): Map<string, CaseStatus[]> {
+  const out = new Map<string, CaseStatus[]>()
+  for (const s of savedSuites(suiteDir).slice(-window)) {
+    for (const r of s.results) {
+      if (r.status === "stopped") continue
+      const list = out.get(r.case.id) || []
+      list.push(r.status)
+      out.set(r.case.id, list)
+    }
+  }
+  return out
+}
+
+/** When the newest saved suite in which one of these cases passed started; undefined when none did. */
+export function lastPassed(suiteDir: string, caseIds: string[]): string | undefined {
+  const ids = new Set(caseIds)
+  return [...savedSuites(suiteDir)].reverse().find((s) => s.results.some((r) => ids.has(r.case.id) && r.status === "passed"))?.at
+}
+
+/** How many of the latest runs in a row failed: 0 when the latest passed or there is none. */
+export function failedInARow(statuses: CaseStatus[] = []): number {
+  let n = 0
+  for (let i = statuses.length - 1; i >= 0 && statuses[i] !== "passed"; i--) n++
+  return n
+}
+
+/** Failed in some runs and passed in others, changing more than once: pass, fail, pass. */
+function intermittent(statuses: CaseStatus[]): { failed: number; runs: number } | undefined {
+  const bad = statuses.map((s) => s !== "passed")
+  const flips = bad.slice(1).filter((b, i) => b !== bad[i]).length
+  return flips >= 2 ? { failed: bad.filter(Boolean).length, runs: bad.length } : undefined
+}
+
+/**
+ * What is known about each of this run's defects: from the history, the closed bug a regression matched in the tracker,
+ * and the earlier results of its cases (with this run's result counted).
+ */
+export function noteHistory(clusters: DefectCluster[], h: DefectHistoryFile, outcomes: Map<string, CaseStatus[]>, closed: Map<string, { label: string; url?: string; closedAt?: string }> = new Map()): void {
+  for (const c of clusters) {
+    const past = c.kind === "page" ? undefined : h.defects[c.id]
+    const previousBug = closed.get(c.id)
+    // A defect matched by the agent's words has no history of its own: its cases failing in the runs just before
+    // make it known, so it is not run again and analysed again every suite.
+    const streak = c.kind === "page" ? Math.min(...c.cases.map((x) => failedInARow(outcomes.get(x.id)))) : 0
+    const status = past?.goneSince || previousBug ? "regression" : past || streak > 0 ? "known" : "new"
+    // A regression's pass in between was the fix, not chance.
+    const flaky = status === "regression" ? undefined : c.cases.map((x) => intermittent([...(outcomes.get(x.id) || []), x.status])).find(Boolean)
+    c.history = {
+      status,
+      seen: past?.seen || streak,
+      ...(past ? { firstSeen: past.firstSeen } : {}),
+      ...(past?.goneSince ? { goneSince: past.goneSince } : {}),
+      ...(previousBug || (past?.goneSince && past.bug) ? { previousBug: previousBug || past!.bug } : {}),
+      ...(flaky ? { intermittent: flaky } : {}),
+    }
+  }
+}
+
+/** Add this run: its defects are seen now; an earlier defect not seen while a case it broke passed has gone away. */
+export function recordRun(h: DefectHistoryFile, clusters: DefectCluster[], results: CaseResult[], suite: string, at: string): void {
+  const seen = new Set<string>()
+  for (const c of clusters) {
+    if (c.kind === "page") continue
+    seen.add(c.id)
+    const cases = c.cases.map((x) => x.id)
+    const p: PastDefect = h.defects[c.id] || { title: c.title, kind: c.kind, firstSeen: at, lastSeen: at, seen: 0, sightings: [], cases: [] }
+    if (p.goneSince) {
+      p.returns = [...(p.returns || []), at].slice(-KEEP_SIGHTINGS)
+      delete p.goneSince
+    }
+    p.title = c.title
+    if (c.page || c.pages[0]) p.page = c.page || c.pages[0]
+    p.lastSeen = at
+    p.seen += 1
+    p.sightings = [...p.sightings, { at, suite, cases }].slice(-KEEP_SIGHTINGS)
+    p.cases = [...p.cases.filter((id) => !cases.includes(id)), ...cases].slice(-KEEP_CASES)
+    if (c.bug) p.bug = c.bug
+    h.defects[c.id] = p
+  }
+  const passed = new Set(results.filter((r) => r.status === "passed").map((r) => r.case.id))
+  for (const [id, p] of Object.entries(h.defects)) {
+    if (!seen.has(id) && !p.goneSince && p.cases.some((c) => passed.has(c))) p.goneSince = at
+  }
+}
+
+/** "new", "seen in 3 earlier runs since 2026-10-02", "regression of SHOP-12 (closed 2026-10-01)", "intermittent: …". */
+export function historyText(n?: DefectHistoryNote): string {
+  if (!n) return ""
+  const day = (at?: string) => (at ? at.slice(0, 10) : "")
+  const base =
+    n.status === "regression"
+      ? n.previousBug
+        ? `regression of ${n.previousBug.label}${n.previousBug.closedAt ? ` (closed ${day(n.previousBug.closedAt)})` : n.goneSince ? ` (gone since ${day(n.goneSince)})` : ""}`
+        : `regression (gone since ${day(n.goneSince)})`
+      : n.status === "known"
+        ? `seen in ${n.seen} earlier run${n.seen === 1 ? "" : "s"}${n.firstSeen ? ` since ${day(n.firstSeen)}` : ""}`
+        : "new"
+  return n.intermittent ? `${base}; intermittent: failed ${n.intermittent.failed} of the last ${n.intermittent.runs} runs` : base
+}

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