@capagents/forgeqe 1.2.0 → 1.3.0

package/src/pack/collect.ts

@@ -0,0 +1,251 @@
+import { spawnSync } from "node:child_process"
+import { realpathSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import { adoSettings } from "../cases/ado.ts"
+import { htmlToText, http } from "../cases/http.ts"
+import { resolveScope, type Scope, type WorkItem } from "../cases/readiness.ts"
+import { changedBetween } from "../code/impact.ts"
+import { adoBase, fetchPr, fetchPrBranches, gh, gitRemotes, parseRemote, resolvePr, type PrRef } from "../code/prreview.ts"
+
+/**
+ * What goes into a release, from wherever it is recorded, as one list of change items: an Azure DevOps scope (a
+ * sprint, area, epic, or work items, with their pull requests and the files those changed), the commits between two
+ * refs of a repository, pull requests (named, or merged in the last days), and items ForgeQE's agent read from any
+ * other tool it is connected to (Jira, GitHub issues, a release note) and passes in as they are.
+ */
+
+export type ChangeItem = {
+  kind: "work_item" | "pr" | "commit" | "note"
+  /** azure_devops, github, git, or the tool the agent read it from. */
+  source: string
+  id: string
+  title: string
+  /** Description, acceptance criteria, repro steps, commit body: what changes, in words. */
+  text?: string
+  url?: string
+  /** Story, Bug, Feature… */
+  type?: string
+  /** Files the change touches, relative to the repository it is in. */
+  files?: string[]
+  /** The change is in the test repository itself: its files reach tests through the code. */
+  inTestRepo?: boolean
+  /** Work items or issues it refers to: "ado:123", "github:45", "jira:PAY-12". */
+  links?: string[]
+  /** Test cases that test it: "ADO-123". */
+  testCases?: string[]
+}
+
+export type Collected = { label: string; items: ChangeItem[]; notes: string[] }
+
+const MAX_TEXT = 2000
+const MAX_PRS = 25
+const MAX_COMMITS = 300
+
+const clip = (s: string, n = MAX_TEXT) => (s.length > n ? `${s.slice(0, n)}…` : s)
+const git = (repo: string, args: string[]) => spawnSync("git", ["-c", "core.quotepath=false", ...args], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+
+function real(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return path.resolve(p)
+  }
+}
+
+/** Work items, issues, and keys a commit message or PR text mentions. */
+export function linksIn(text: string, platform?: "github" | "azure_devops"): string[] {
+  const out = new Set<string>()
+  for (const m of text.matchAll(/\bAB#(\d+)\b/g)) out.add(`ado:${m[1]}`)
+  for (const m of text.matchAll(/(?<![\w#/-])#(\d+)\b/g)) out.add(platform === "azure_devops" ? `ado:${m[1]}` : `github:${m[1]}`)
+  for (const m of text.matchAll(/\b([A-Z][A-Z0-9]{1,9}-\d+)\b/g)) if (!/^(ADO|AB|SHOP|WEB)-/.test(m[1]!)) out.add(`jira:${m[1]}`)
+  return [...out]
+}
+
+const PR_LINK = /PullRequestId\/([^/]+)%2F([^/]+)%2F(\d+)$/i
+
+/** A work item as a change item: its words, its test cases, and the pull requests linked to it. */
+function itemOf(w: WorkItem, url: string): ChangeItem & { prLinks: { project: string; repo: string; id: number }[] } {
+  const f = w.fields
+  const text = [htmlToText(String(f["System.Description"] || "")), htmlToText(String(f["Microsoft.VSTS.Common.AcceptanceCriteria"] || "")), htmlToText(String(f["Microsoft.VSTS.TCM.ReproSteps"] || ""))]
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .join("\n")
+  const rels = w.relations || []
+  return {
+    kind: "work_item",
+    source: "azure_devops",
+    id: String(w.id),
+    title: String(f["System.Title"] || `Work item ${w.id}`),
+    ...(text ? { text: clip(text) } : {}),
+    url,
+    type: String(f["System.WorkItemType"] || ""),
+    testCases: rels.filter((r) => r.rel === "Microsoft.VSTS.Common.TestedBy-Forward").map((r) => `ADO-${r.url.split("/").pop()}`),
+    prLinks: rels.flatMap((r) => {
+      const m = r.rel === "ArtifactLink" ? PR_LINK.exec(decodeURIComponent(r.url).replace(/\//g, "/")) || PR_LINK.exec(r.url) : null
+      return m ? [{ project: m[1]!, repo: m[2]!, id: Number(m[3]) }] : []
+    }),
+  }
+}
+
+/** The files an Azure DevOps pull request changed, from its last iteration. */
+async function adoPrFiles(org: string, auth: string, project: string, repo: string, id: number): Promise<string[]> {
+  const base = `${org}/${encodeURIComponent(project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${id}`
+  const { data: its } = await http<{ value?: { id: number }[] }>(`${base}/iterations?api-version=7.1`, { auth })
+  const last = its?.value?.at(-1)?.id
+  if (!last) return []
+  const { data } = await http<{ changeEntries?: { item?: { path?: string; isFolder?: boolean } }[] }>(`${base}/iterations/${last}/changes?$top=1000&api-version=7.1`, { auth })
+  return (data?.changeEntries || []).filter((c) => c.item?.path && !c.item.isFolder).map((c) => c.item!.path!.replace(/^\//, ""))
+}
+
+/**
+ * An Azure DevOps scope: its stories, and with a sprint or area its bugs too (fixed bugs are changes); each with its
+ * test cases, and the files its linked pull requests changed.
+ */
+export async function fromAdoScope(cfg: AppConfig, scope: Scope): Promise<Collected> {
+  const notes: string[] = []
+  const r = await resolveScope(cfg, scope)
+  const bugIds = r.filter
+    ? await r.wiql(`SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] IN GROUP 'Microsoft.BugCategory' AND [System.State] <> 'Removed' AND ${r.filter}`)
+    : []
+  const all = await r.items([...new Set([...r.storyIds, ...bugIds])])
+  const { org, auth } = adoSettings(cfg.sources)
+  const items: ChangeItem[] = []
+  let prs = 0
+  for (const w of all) {
+    const { prLinks, ...item } = itemOf(w, r.urlOf(w))
+    const files: string[] = []
+    for (const p of prLinks) {
+      if (prs >= MAX_PRS) break
+      prs++
+      try {
+        files.push(...(await adoPrFiles(org, auth, p.project, p.repo, p.id)))
+      } catch (err) {
+        notes.push(`Pull request ${p.id} of work item ${w.id} could not be read: ${(err as Error).message.slice(0, 120)}`)
+      }
+    }
+    items.push({ ...item, ...(files.length ? { files: [...new Set(files)] } : {}) })
+  }
+  if (prs >= MAX_PRS) notes.push(`Only the first ${MAX_PRS} linked pull requests were read for their files.`)
+  return { label: r.label, items, notes }
+}
+
+/** The commits between two refs of a repository, each with its files and the work items it mentions. */
+export function fromGitRange(repo: string, from: string, to = "HEAD", testRepo?: string): Collected {
+  const range = `${from}..${to}`
+  const log = git(repo, ["log", "--no-merges", `--max-count=${MAX_COMMITS}`, "--format=%H%x1f%s%x1f%b%x1e", range])
+  if (log.status !== 0) throw new Error(`git log ${range} failed in ${repo}: ${log.stderr.trim().split("\n")[0]}`)
+  const inTestRepo = Boolean(testRepo) && real(repo) === real(testRepo!)
+  const platform = remotePlatform(repo)
+  const items: ChangeItem[] = log.stdout
+    .split("\x1e")
+    .map((c) => c.trim())
+    .filter(Boolean)
+    .map((c) => {
+      const [sha = "", subject = "", body = ""] = c.split("\x1f")
+      const files = git(repo, ["show", "--name-only", "--format=", sha]).stdout.split("\n").map((l) => l.trim()).filter(Boolean)
+      const links = linksIn(`${subject}\n${body}`, platform)
+      return { kind: "commit" as const, source: "git", id: sha.slice(0, 10), title: subject, ...(body.trim() ? { text: clip(body.trim()) } : {}), files, ...(inTestRepo ? { inTestRepo } : {}), ...(links.length ? { links } : {}) }
+    })
+  const notes = items.length >= MAX_COMMITS ? [`Only the newest ${MAX_COMMITS} commits of ${range} were read.`] : []
+  return { label: `commits ${range} in ${path.basename(real(repo))}`, items, notes }
+}
+
+function remotePlatform(repo: string): "github" | "azure_devops" | undefined {
+  const url = git(repo, ["remote", "get-url", "origin"]).stdout.trim()
+  return /github\.com/i.test(url) ? "github" : /dev\.azure\.com|visualstudio\.com/i.test(url) ? "azure_devops" : undefined
+}
+
+/** Pull requests by number or URL: their words, linked work items, and changed files. */
+export async function fromPrs(cfg: AppConfig, repo: string, refs: string[], testRepo?: string): Promise<Collected> {
+  const items: ChangeItem[] = []
+  const notes: string[] = []
+  for (const input of refs.slice(0, MAX_PRS)) {
+    try {
+      const r = await resolvePr(repo, input)
+      const pr = await fetchPr(r.ref, cfg, r.root)
+      let files: string[] = []
+      try {
+        const { base, dropRefs } = await fetchPrBranches(r.root, r.remote, pr)
+        try {
+          files = changedBetween(r.root, base, pr.headSha)
+        } finally {
+          await dropRefs()
+        }
+      } catch (err) {
+        notes.push(`The files of pull request ${r.ref.number} could not be read: ${(err as Error).message.slice(0, 120)}`)
+      }
+      const links = [...(pr.workItemIds || []).map((id) => `ado:${id}`), ...linksIn(`${pr.title}\n${pr.description}`, r.ref.platform)]
+      items.push({
+        kind: "pr",
+        source: r.ref.platform,
+        id: String(r.ref.number),
+        title: pr.title,
+        text: clip([pr.description, ...pr.linked.map((l) => `${l.title}${l.text ? `: ${l.text}` : ""}`)].filter(Boolean).join("\n")),
+        url: pr.url,
+        files,
+        ...(testRepo && real(r.root) === real(testRepo) ? { inTestRepo: true } : {}),
+        ...(links.length ? { links: [...new Set(links)] } : {}),
+      })
+    } catch (err) {
+      notes.push(`Pull request ${input} could not be read: ${(err as Error).message.slice(0, 160)}`)
+    }
+  }
+  if (refs.length > MAX_PRS) notes.push(`Only the first ${MAX_PRS} of ${refs.length} pull requests were read.`)
+  return { label: `pull requests ${refs.slice(0, 8).join(", ")}${refs.length > 8 ? "…" : ""}`, items, notes }
+}
+
+/** The pull requests merged into a repository in the last `days` days, newest first, as refs fromPrs reads. */
+export async function recentPrs(cfg: AppConfig, repo: string, days: number): Promise<string[]> {
+  const since = new Date(Date.now() - days * 86_400_000).toISOString()
+  const remote = (await gitRemotes(repo)).find((r) => r.name === "origin") || (await gitRemotes(repo))[0]
+  const where = remote ? parseRemote(remote.url) : null
+  if (!where) throw new Error(`${repo} has no GitHub or Azure DevOps remote to list pull requests from.`)
+  if (where.platform === "github") {
+    const out = await gh(["pr", "list", "--state", "merged", "--search", `merged:>=${since.slice(0, 10)}`, "--json", "number", "--limit", "100"], repo)
+    return (JSON.parse(out || "[]") as { number: number }[]).map((p) => String(p.number))
+  }
+  const { auth } = adoSettings(cfg.sources)
+  const ref = { ...where, number: 0 } as PrRef
+  const { data } = await http<{ value?: { pullRequestId: number; closedDate?: string }[] }>(
+    `${adoBase(ref)}/pullrequests?searchCriteria.status=completed&searchCriteria.minTime=${encodeURIComponent(since)}&searchCriteria.queryTimeRangeType=closed&$top=100&api-version=7.1`,
+    { auth },
+  )
+  return (data?.value || []).map((p) => String(p.pullRequestId))
+}
+
+/** Items ForgeQE's agent read from another tool (Jira, GitHub issues, a release note), checked and trimmed. */
+export function fromGiven(raw: unknown[]): Collected {
+  const items: ChangeItem[] = []
+  for (const r of raw) {
+    if (!r || typeof r !== "object") continue
+    const o = r as Record<string, unknown>
+    const title = String(o.title || "").trim()
+    if (!title) continue
+    const list = (v: unknown) => (Array.isArray(v) ? v.map(String).map((s) => s.trim()).filter(Boolean) : [])
+    items.push({
+      kind: ["work_item", "pr", "commit", "note"].includes(String(o.kind)) ? (o.kind as ChangeItem["kind"]) : "work_item",
+      source: String(o.source || "agent"),
+      id: String(o.id || title.slice(0, 40)),
+      title,
+      ...(o.text ? { text: clip(String(o.text)) } : {}),
+      ...(o.url ? { url: String(o.url) } : {}),
+      ...(o.type ? { type: String(o.type) } : {}),
+      ...(list(o.files).length ? { files: list(o.files) } : {}),
+      ...(list(o.links).length ? { links: list(o.links) } : {}),
+      ...(list(o.test_cases).length ? { testCases: list(o.test_cases).map((c) => (/^\d+$/.test(c) ? `ADO-${c}` : c)) } : {}),
+    })
+  }
+  return { label: `${items.length} item${items.length === 1 ? "" : "s"} from ForgeQE's agent`, items, notes: [] }
+}
+
+/** Work items commits or pull requests mention by id ("ado:123"), read from Azure DevOps, that are not in the list yet. */
+export async function linkedWorkItems(cfg: AppConfig, items: ChangeItem[]): Promise<Collected | null> {
+  if (!cfg.sources.ado) return null
+  const have = new Set(items.filter((i) => i.source === "azure_devops" && i.kind === "work_item").map((i) => i.id))
+  const ids = [...new Set(items.flatMap((i) => i.links || []).filter((l) => l.startsWith("ado:")).map((l) => Number(l.slice(4))))].filter((id) => id && !have.has(String(id)))
+  if (!ids.length) return null
+  const got = await fromAdoScope(cfg, { ids: ids.slice(0, 200) })
+  return { ...got, label: `${got.items.length} linked work item${got.items.length === 1 ? "" : "s"}` }
+}

package/src/pack/index.ts

@@ -0,0 +1,134 @@
+import type { Card } from "../card.ts"
+import type { AppConfig } from "../config.ts"
+import type { Scope } from "../cases/readiness.ts"
+import type { TestsRun } from "../code/find.ts"
+import { fromAdoScope, fromGitRange, fromGiven, fromPrs, linkedWorkItems, recentPrs, type ChangeItem, type Collected } from "./collect.ts"
+import { buildPack, type Pack, type PackRun, type ReasonKind } from "./pack.ts"
+
+export { buildPack, listPacks, loadPack, type Pack } from "./pack.ts"
+export { runPack } from "./run.ts"
+
+/** Where a release's changes are: any mix of these. */
+export type PackSources = {
+  ado?: Scope
+  /** Commits between two refs of a repository (the product's, or the tests' own). */
+  range?: { repo: string; from: string; to?: string }
+  /** Pull requests by number or URL, in `prRepo` (default: the test repository). */
+  prs?: string[]
+  /** Pull requests merged in the last N days, in `prRepo`. */
+  mergedDays?: number
+  prRepo?: string
+  /** Items ForgeQE's agent read from any other tool. */
+  items?: unknown[]
+}
+
+/** Every source's changes as one list, without repeats; work items the commits and PRs mention are read too. */
+export async function collectChanges(cfg: AppConfig, testRepo: string, src: PackSources): Promise<Collected & { scope: string[] }> {
+  const parts: Collected[] = []
+  const notes: string[] = []
+  const tryPart = async (what: string, f: () => Promise<Collected> | Collected) => {
+    try {
+      parts.push(await f())
+    } catch (err) {
+      notes.push(`${what}: ${(err as Error).message.slice(0, 200)}`)
+    }
+  }
+  if (src.ado && Object.values(src.ado).some((v) => (Array.isArray(v) ? v.length : Boolean(v)))) await tryPart("Azure DevOps", () => fromAdoScope(cfg, src.ado!))
+  if (src.range) await tryPart(`Commits ${src.range.from}..${src.range.to || "HEAD"}`, () => fromGitRange(src.range!.repo, src.range!.from, src.range!.to || "HEAD", testRepo))
+  const prRepo = src.prRepo || testRepo
+  const prs = [...(src.prs || [])]
+  if (src.mergedDays) {
+    try {
+      prs.push(...(await recentPrs(cfg, prRepo, src.mergedDays)))
+    } catch (err) {
+      notes.push(`Pull requests merged in the last ${src.mergedDays} days: ${(err as Error).message.slice(0, 200)}`)
+    }
+  }
+  if (prs.length) await tryPart("Pull requests", () => fromPrs(cfg, prRepo, [...new Set(prs)], testRepo))
+  if (src.items?.length) parts.push(fromGiven(src.items))
+  const seen = new Set<string>()
+  const items: ChangeItem[] = []
+  for (const p of parts) {
+    for (const i of p.items) {
+      const key = `${i.source}:${i.kind}:${i.id}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      items.push(i)
+    }
+    notes.push(...p.notes)
+  }
+  // Work items the commits and pull requests name, read for their words and their test cases.
+  try {
+    const linked = await linkedWorkItems(cfg, items)
+    if (linked?.items.length) {
+      for (const i of linked.items) if (!seen.has(`${i.source}:${i.kind}:${i.id}`)) items.push(i)
+      parts.push(linked)
+      notes.push(...linked.notes)
+    }
+  } catch (err) {
+    notes.push(`Work items the changes mention: ${(err as Error).message.slice(0, 200)}`)
+  }
+  const scope = parts.map((p) => p.label).filter(Boolean)
+  return { label: scope.join("; "), items, notes, scope }
+}
+
+/** Collect and build in one go. */
+export async function makePack(opts: { config: AppConfig; repo: string; name?: string; sources: PackSources; risk?: boolean; smoke?: boolean }): Promise<Pack> {
+  const c = await collectChanges(opts.config, opts.repo, opts.sources)
+  if (!c.items.length) throw new Error(`No changes found${c.notes.length ? `: ${c.notes.join(" ")}` : ". Give a sprint or work items, a commit range, pull requests, or items."}`)
+  return buildPack({ config: opts.config, repo: opts.repo, name: opts.name, scope: c.scope, items: c.items, notes: c.notes, risk: opts.risk, smoke: opts.smoke })
+}
+
+const KIND_TEXT: Record<ReasonKind, string> = { linked: "linked test case", changed: "test code changed", covers: "matches a change", risk: "risk area", smoke: "smoke" }
+
+export function packCard(p: Pack): Card {
+  const by = (k: ReasonKind) => p.tests.filter((t) => t.reasons.some((r) => r.kind === k)).length
+  const kinds = (Object.keys(KIND_TEXT) as ReasonKind[]).filter((k) => by(k)).map((k) => `${by(k)} ${KIND_TEXT[k]}`)
+  return {
+    status: p.tests.length ? "ok" : "info",
+    title: `Regression pack ${p.name}: ${p.tests.length} test${p.tests.length === 1 ? "" : "s"} for ${p.items.length} change${p.items.length === 1 ? "" : "s"}`,
+    stats: [kinds.join(", "), p.uncovered.length ? `${p.uncovered.length} not covered` : ""].filter(Boolean).join(" · "),
+    body: [
+      `From      ${p.scope.join("; ") || "—"}`,
+      ...p.tests.slice(0, 12).map((t) => `${t.test}${t.flaky ? " (flaky)" : ""}: ${[...new Set(t.reasons.map((r) => r.text))].slice(0, 2).join("; ").slice(0, 160)}`),
+      ...(p.tests.length > 12 ? [`… and ${p.tests.length - 12} more`] : []),
+      ...(p.risk.length ? ["", `Risk areas: ${p.risk.map((r) => `${r.area} (${r.level})`).join(", ")}`] : []),
+      ...(p.uncovered.length ? ["", "Not covered by any test:", ...p.uncovered.slice(0, 8).map((u) => `${u.item} "${u.title}"${u.nearest ? `: closest ${u.nearest.test}${u.nearest.lacks.length ? `, which lacks ${u.nearest.lacks.slice(0, 3).join(", ")}` : ""}` : ""}`)] : []),
+      ...p.notes.slice(0, 4).map((n) => `Note: ${n}`),
+    ],
+  }
+}
+
+export function packRunCard(p: Pack, run: TestsRun, record: PackRun, notes: string[] = []): Card {
+  const before = p.runs.at(-2)
+  const fixed = before ? before.failed.filter((f) => !record.failed.includes(f)) : []
+  const broke = before ? record.failed.filter((f) => !before.failed.includes(f)) : []
+  return {
+    status: run.status === "passed" ? "ok" : run.status === "stopped" ? "stopped" : "fail",
+    title: `Pack ${p.name} on ${record.target || record.on}: ${run.status}`,
+    stats: `${run.counts.passed} passed, ${run.counts.failed} failed${run.counts.skipped ? `, ${run.counts.skipped} skipped` : ""} · ${run.seconds}s`,
+    body: [
+      ...run.tests.filter((t) => t.status === "failed").slice(0, 12).map((t) => `✗ ${t.name}${t.message ? `: ${t.message.slice(0, 140)}` : ""}`),
+      ...(run.flaky?.length ? [`Flaky (passed on retry): ${run.flaky.join(", ")}`] : []),
+      ...(before ? [`Since the last run (${before.at.slice(0, 16).replace("T", " ")} on ${before.target || before.on}): ${broke.length} newly failing, ${fixed.length} fixed`] : []),
+      `Command   ${run.command.slice(0, 300)}`,
+      ...notes.map((n) => `Note: ${n}`),
+    ],
+  }
+}
+
+/** The pack as markdown, for a pull request, a wiki page, or a release note. */
+export function packMarkdown(p: Pack): string {
+  return [
+    `# Regression pack ${p.name}`,
+    "",
+    `${p.tests.length} tests for ${p.items.length} changes (${p.scope.join("; ")}), built ${p.createdAt.slice(0, 16).replace("T", " ")}.`,
+    "",
+    "| Test | File | Why |",
+    "|---|---|---|",
+    ...p.tests.map((t) => `| ${t.test}${t.flaky ? " ⚠ flaky" : ""} | ${t.file} | ${[...new Set(t.reasons.map((r) => r.text.replace(/\|/g, "\\|")))].join("<br>")} |`),
+    ...(p.uncovered.length ? ["", "## Not covered by any test", "", ...p.uncovered.map((u) => `- **${u.item}** ${u.title}: ${u.why}${u.nearest ? `. Closest test: ${u.nearest.test}${u.nearest.lacks.length ? ` (lacks ${u.nearest.lacks.join(", ")})` : ""}` : ""}`)] : []),
+    ...(p.risk.length ? ["", "## Risk areas", "", ...p.risk.map((r) => `- **${r.area}** (${r.level}): ${r.reasons.join("; ")}`)] : []),
+    ...(p.runs.length ? ["", "## Runs", "", "| When | Where | Result | Passed | Failed |", "|---|---|---|---|---|", ...p.runs.map((r) => `| ${r.at.slice(0, 16).replace("T", " ")} | ${r.target || r.on} | ${r.status} | ${r.counts.passed} | ${r.counts.failed} |`)] : []),
+  ].join("\n")
+}

package/src/pack/init.ts

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import { walk } from "../code/profile.ts"
+import { listPacks } from "./pack.ts"
+import { ADO_PIPELINE_FILE, adoPipeline, dotnetProject, githubWorkflow, packSelector, WORKFLOW_FILE, type Framework } from "./pipeline.ts"
+
+/** The repository's test framework, from its newest pack, else its files. */
+function frameworkOf(repo: string, files: string[]): { framework: Framework; dotnet?: { project: string; settings?: string } } {
+  const pack = listPacks(repo).find((p) => p.tests.length)
+  if (pack) {
+    const { framework } = packSelector(pack)
+    return { framework, ...(framework === "dotnet" ? { dotnet: dotnetProject(repo, pack, files) } : {}) }
+  }
+  const test = files.filter((f) => f.endsWith(".csproj") && /test/i.test(f)).sort((a, b) => Number(/web|ui|e2e/i.test(b)) - Number(/web|ui|e2e/i.test(a)))[0]
+  if (test) return { framework: "dotnet", dotnet: { project: test, ...(files.find((f) => /(^|\/)ci\.runsettings$/i.test(f)) ? { settings: files.find((f) => /(^|\/)ci\.runsettings$/i.test(f))! } : {}) } }
+  if (files.some((f) => /(^|\/)playwright\.config\.(ts|js|mjs|cjs)$/.test(f))) return { framework: "playwright" }
+  if (files.some((f) => f.endsWith(".py"))) return { framework: "pytest" }
+  throw new Error("ForgeQE cannot tell this repository's test framework: build a pack first.")
+}
+
+/** Writes the pipeline files into the test repository; never over an existing one unless asked. Returns what it did, as lines. */
+export function writePipelineFiles(cfg: AppConfig, repo: string, which: { github: boolean; azureDevops: boolean; force?: boolean }): string[] {
+  const files = walk(repo)
+  const { framework, dotnet } = frameworkOf(repo, files)
+  const remote = cfg.browser.remotes?.testmu
+  const out: string[] = []
+  const write = (rel: string, text: string) => {
+    const file = path.join(repo, rel)
+    if (existsSync(file) && !which.force) return out.push(`Kept ${rel}: it exists (--force writes over it).`)
+    mkdirSync(path.dirname(file), { recursive: true })
+    writeFileSync(file, text)
+    out.push(`Wrote ${rel} (${framework}${dotnet ? `, ${dotnet.project}` : ""}).`)
+  }
+  if (which.github) write(path.join(".github", "workflows", WORKFLOW_FILE), githubWorkflow(framework, remote, dotnet))
+  if (which.azureDevops) write(ADO_PIPELINE_FILE, adoPipeline(framework, remote, dotnet))
+  out.push(
+    "",
+    "Next:",
+    ...(which.github ? [`- GitHub: commit and push ${path.join(".github", "workflows", WORKFLOW_FILE)} to the default branch; for TestMu AI add the repository secrets LT_USERNAME and LT_ACCESS_KEY; then set packs.pipeline.github (repo: owner/name, workflow: ${WORKFLOW_FILE}) in forgeqe.yaml.`] : []),
+    ...(which.azureDevops ? [`- Azure DevOps: commit ${ADO_PIPELINE_FILE}, create a pipeline from it (Pipelines > New > your repository > Existing YAML); for TestMu AI add the secret variables LT_USERNAME and LT_ACCESS_KEY; then set packs.pipeline.azure_devops (project, pipeline_id) in forgeqe.yaml. The PAT needs Build (read & execute) and Test Management (read).`] : []),
+  )
+  return out
+}