@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/cli/terminal.ts

@@ -0,0 +1,187 @@
+import { appendFileSync } from "node:fs"
+import path from "node:path"
+import { createInterface } from "node:readline"
+
+import { cardText } from "../card.ts"
+import type { TestCase } from "../cases/index.ts"
+import type { Detail } from "../detail.ts"
+import { formatEvent } from "../print.ts"
+import { FAILURE_ACTION, FAILURE_LABEL } from "../cases/failure.ts"
+import { buildSummary, formatSummary } from "../summary.ts"
+import type { ToolContext, ToolEvent } from "../mcp/tools.ts"
+import { formatSuite, markdownSummary } from "../suite/report.ts"
+import type { SuiteEvent, SuiteResult } from "../suite/run.ts"
+
+/** Plain-terminal output and prompts: tool and suite events as lines, Enter to continue, numbered choices. */
+
+export function suiteEventLine(e: SuiteEvent, parallel: number, color: boolean, detail: Detail = "brief"): string | null {
+  const prefix = (tc: TestCase) => (parallel > 1 ? `[${tc.id}] ` : "")
+  if (e.type === "case-start") return `\n━━ ${e.index + 1}/${e.total}  ${e.case.id}  ${e.case.title}`
+  if (e.type === "code-start") return `\n${prefix(e.case)}▸ Writing a test for ${e.case.id}`
+  if (e.type === "code-done") {
+    const c = e.result.code
+    if (!c) return null
+    const extra = c.existing === "reused" ? " (the existing test passes: no coding job)" : c.knownDefect ? " (marked as an expected failure until the defect is fixed)" : c.attention ? ` (moved to ${c.attention}/)` : c.existing === "updated" ? " (the existing test, updated)" : ""
+    return `${prefix(e.case)}${c.status === "passed" ? "✓" : "✗"} Test for ${e.case.id} ${c.status}${c.testFile ? `: ${c.testFile}` : c.error ? `: ${c.error}` : ""}${extra}`
+  }
+  if (e.type === "case-event" && e.event.type !== "done") {
+    const line = formatEvent(e.event, color, detail)
+    return line ? prefix(e.case) + line : null
+  }
+  if (e.type === "case-done") {
+    const mark = { passed: "✓", failed: "✗", error: "!", stopped: "■" }[e.result.status]
+    const f = e.result.failure
+    const why = f ? ` · ${FAILURE_LABEL[f.type]}: ${FAILURE_ACTION[f.type]}` : ""
+    return `${prefix(e.result.case)}${mark} ${e.result.case.id} ${e.result.status} in ${Math.round(e.result.ms / 1000)}s${why}`
+  }
+  return null
+}
+
+export function writeJobSummary(suite: SuiteResult) {
+  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdownSummary(suite))
+}
+
+/** Prints what ForgeQE's tools do (browser runs, suites, test commands) as plain lines. */
+export function toolPrinter(color: boolean, write: (line: string) => void, detail: Detail = "brief"): (e: ToolEvent) => void {
+  let steps = 0
+  let parallel = 1
+  const out = (line: string | null) => {
+    if (line) write(line)
+  }
+  return (e) => {
+    switch (e.type) {
+      case "run-start":
+        steps = 0
+        return out(`\n▸ Browser: ${e.goal}${e.url ? `  (${e.url})` : ""}`)
+      case "run-event":
+        if (e.event.type === "step") steps = Math.max(steps, e.event.step)
+        return e.event.type === "done" ? undefined : out(formatEvent(e.event, color, detail))
+      case "run-done":
+        if (!e.result) return out(`✗ Browser run failed: ${e.error}`)
+        return out(
+          `\n${formatSummary(
+            buildSummary({
+              status: e.result.status,
+              text: e.result.summary,
+              finalUrl: e.result.finalUrl,
+              ms: e.ms,
+              tokens: e.result.usage.input + e.result.usage.output,
+              steps,
+              files: e.files,
+              memory: e.result.memory,
+              usage: e.result.usage,
+              cost: e.result.cost,
+              outcome: e.result.outcome,
+              failedChecks: e.result.failedChecks,
+              quality: e.result.quality,
+              budgetExceeded: e.result.budgetExceeded,
+            }),
+          )}\n`,
+        )
+      case "suite-start":
+        parallel = e.parallel
+        return out(`\n▸ ${e.cases.length} test case${e.cases.length === 1 ? "" : "s"}${e.parallel > 1 ? `, ${e.parallel} at a time` : ""}`)
+      case "suite-event":
+        // A suite started by a tool reports its coding through code-start, agent, and code-done events instead.
+        if (e.event.type === "code-start" || e.event.type === "code-done") return
+        return out(suiteEventLine(e.event, parallel, color, detail))
+      case "suite-done":
+        writeJobSummary(e.suite)
+        return out(`\n${formatSuite(e.suite)}\n`)
+      case "info":
+        return out(`${e.ok === undefined ? "▸" : e.ok ? "✓" : "✗"} ${e.text}`)
+      case "agent":
+        return e.event.kind === "usage" ? undefined : out(formatEvent(e.event, color, detail))
+      case "code-start":
+        return out(`\n⇢ Handing over to the coding agent: ${path.relative(process.cwd(), e.runDir) || e.runDir} → a test in ${e.repo}`)
+      case "code-done":
+        return e.error ? out(`✗ Coding agent: ${e.error}`) : undefined
+      case "card":
+        return out(`\n${cardText(e.card)}\n`)
+    }
+  }
+}
+
+/** Enter on the terminal continues, Ctrl+C (the signal) cancels; none when stdin is not a terminal. */
+export function terminalWait(signal: AbortSignal): ToolContext["waitForUser"] {
+  if (!process.stdin.isTTY) return undefined
+  return (prompt) =>
+    new Promise((resolve) => {
+      const keys = createInterface({ input: process.stdin })
+      const done = (ok: boolean) => {
+        keys.close()
+        resolve(ok)
+      }
+      console.log(`\n${prompt} Press Enter to continue (Ctrl+C cancels).`)
+      keys.once("line", () => done(true))
+      signal.addEventListener("abort", () => done(false), { once: true })
+    })
+}
+
+/** Numbered options on the terminal; Enter picks the first, Ctrl+C (the signal) cancels. None when stdin is not a terminal. */
+export function terminalAsk(signal: AbortSignal): ToolContext["ask"] {
+  if (!process.stdin.isTTY) return undefined
+  return (q) =>
+    new Promise((resolve) => {
+      const keys = createInterface({ input: process.stdin, output: process.stdout })
+      const done = (id: string | null) => {
+        keys.close()
+        resolve(id)
+      }
+      console.log(["", q.title, ...(q.detail ? [q.detail] : []), ...(q.lines || []), ...q.options.map((o, i) => `  ${i + 1}. ${o.label}`)].join("\n"))
+      const askOnce = () =>
+        keys.question(`Choose 1-${q.options.length} (Enter: 1): `, (line) => {
+          const t = line.trim()
+          const n = t ? Number(t) : 1
+          if (Number.isInteger(n) && n >= 1 && n <= q.options.length) return done(q.options[n - 1].id)
+          askOnce()
+        })
+      askOnce()
+      signal.addEventListener("abort", () => done(null), { once: true })
+    })
+}
+
+/**
+ * One line from the terminal; a secret is read with echo off, so a pasted token never shows. Enter on an empty line
+ * takes `initial`; Ctrl+C or the signal cancels (null). Null straight away when stdin is not a terminal.
+ */
+export function terminalInput(signal?: AbortSignal): (q: { label: string; secret?: boolean; initial?: string }) => Promise<string | null> {
+  return (q) =>
+    new Promise((resolve) => {
+      if (!process.stdin.isTTY) return resolve(null)
+      const label = `${q.label}${q.initial ? ` [${q.initial}]` : ""}: `
+      if (!q.secret) {
+        const keys = createInterface({ input: process.stdin, output: process.stdout })
+        const done = (v: string | null) => {
+          keys.close()
+          resolve(v)
+        }
+        keys.question(label, (line) => done(line.trim() || q.initial || ""))
+        keys.on("SIGINT", () => done(null))
+        signal?.addEventListener("abort", () => done(null), { once: true })
+        return
+      }
+      const stdin = process.stdin
+      let value = ""
+      const done = (v: string | null) => {
+        stdin.off("data", onData)
+        stdin.setRawMode(false)
+        stdin.pause()
+        process.stdout.write("\n")
+        resolve(v)
+      }
+      const onData = (chunk: Buffer | string) => {
+        for (const ch of chunk.toString()) {
+          if (ch === "\r" || ch === "\n") return done(value.trim() || q.initial || "")
+          if (ch === "\u0003") return done(null)
+          if (ch === "\u007f" || ch === "\b") value = value.slice(0, -1)
+          else if (ch >= " ") value += ch
+        }
+      }
+      process.stdout.write(`${label}(hidden) `)
+      stdin.setRawMode(true)
+      stdin.resume()
+      stdin.on("data", onData)
+      signal?.addEventListener("abort", () => done(null), { once: true })
+    })
+}

package/src/code/areas.ts

@@ -0,0 +1,337 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import { adoRequirements, type Requirement } from "../cases/context.ts"
+import { adoSettings } from "../cases/ado.ts"
+import { http } from "../cases/http.ts"
+import { readPages, type MemoryPage } from "../memory.ts"
+import { importsOf, isTestFile } from "./impact.ts"
+import { adoBase, fetchPr, fetchPrBranches, gh, gitRemotes, parsePrRef, type PrInfo, type PrRef } from "./prreview.ts"
+import { readMappings } from "./traceability.ts"
+
+/**
+ * Which parts of the product a pull request touches, when the product's code and the automated tests may live in
+ * different repositories. The pull request is read from a local clone of the product repository when there is one
+ * (its diff, and its imports to follow a shared component to the pages that use it), otherwise through the GitHub or
+ * Azure DevOps API (the changed files and their contents). Its changes are then tied to the product by:
+ *
+ * - the work items it is linked to, up through feature and epic, with their Area Paths;
+ * - the test ids, ids, labels, and texts its changed UI code carries, matched against page memory (every element
+ *   ForgeQE met on each page of the application), and the routes it changes, matched against the pages' paths;
+ * - in the automation repository (the working directory): the tests that reach those pages, the test cases they
+ *   automate, and the requirements those test cases test.
+ *
+ * ForgeQE's agent turns the evidence into the impact report: the areas, the risk, what to test, and the gaps.
+ */
+
+export type ChangedSource = { path: string; added: string }
+
+export type ImpactedPage = { page: string; title?: string; evidence: string[]; files: string[] }
+export type ImpactedTest = { file: string; reasons: string[]; caseId?: string }
+export type ManualCase = { id: string; title?: string; url?: string; requirement: string }
+
+export type AreaImpact = {
+  pr: PrInfo
+  /** Where the changes were read: a clone's diff, or the API. */
+  via: "clone" | "api"
+  files: string[]
+  requirements: Requirement[]
+  pages: ImpactedPage[]
+  routes: string[]
+  tests: ImpactedTest[]
+  manual: ManualCase[]
+  /** Changed UI files nothing above ties to a page. */
+  unmapped: string[]
+  notes: string[]
+}
+
+const UI = /\.(tsx|jsx|vue|svelte|html?|cshtml|razor|component\.ts|aspx|erb|hbs|ejs|jinja2?|twig|xaml)$/i
+const CODE = /\.([cm]?[jt]sx?|vue|svelte|py|cs|cshtml|razor|java|kt|go|rb|php|html?)$/i
+const MAX_FILES = 60
+const MAX_BYTES = 200_000
+
+const git = (repo: string, args: string[]) => spawnSync("git", ["-c", "core.quotepath=false", ...args], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+
+/** Added lines per file from a unified diff. */
+export function addedByFile(diff: string): ChangedSource[] {
+  const out = new Map<string, string[]>()
+  let file = ""
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++ ")) {
+      file = line === "+++ /dev/null" ? "" : line.slice(4).replace(/^b\//, "")
+      if (file && !out.has(file)) out.set(file, [])
+    } else if (file && line.startsWith("+") && !line.startsWith("+++")) out.get(file)!.push(line.slice(1))
+  }
+  return [...out].map(([p, lines]) => ({ path: p, added: lines.join("\n") }))
+}
+
+// ---- What the changed code names ----
+
+const ATTR = /\b(data-testid|data-test-id|data-test|data-qa|data-cy|id|name|aria-label|placeholder|title|alt|formControlName|testID)\s*=\s*\{?\s*["'`]([^"'`{}$\n]{2,60})["'`]/g
+const TEST_ID_CALL = /\bgetBy(?:TestId|Label|Placeholder|Text|Title|AltText)\(\s*["'`]([^"'`\n]{2,60})["'`]/g
+const JSX_TEXT = />\s*([A-Z][^<>{}\n]{2,40}?)\s*</g
+const ROUTE_PATTERNS = [
+  /\b(?:path|route|to|href|url)\s*[:=]\s*["'`](\/[\w\-/:.{}[\]*]*)["'`]/g,
+  /<Route[^>]*\bpath=\{?["'`](\/?[\w\-/:.{}[\]*]*)["'`]/g,
+  /@(?:app|router|bp|blueprint)\.(?:route|get|post|put|delete)\(\s*["'`](\/[^"'`]*)["'`]/g,
+  /\b(?:router|app)\.(?:get|post|put|patch|delete|use)\(\s*["'`](\/[^"'`]*)["'`]/g,
+  /\[(?:Http(?:Get|Post|Put|Delete))?Route\(\s*"([^"]+)"\s*\)\]/g,
+  /@(?:Get|Post|Put|Delete|Request)Mapping\(\s*(?:value\s*=\s*)?"([^"]+)"/g,
+]
+
+export function namesInCode(text: string): { selectors: string[]; texts: string[]; routes: string[] } {
+  const selectors = new Set<string>()
+  const texts = new Set<string>()
+  const routes = new Set<string>()
+  for (const m of text.matchAll(ATTR)) selectors.add(m[2].trim())
+  for (const m of text.matchAll(TEST_ID_CALL)) selectors.add(m[1].trim())
+  for (const m of text.matchAll(JSX_TEXT)) {
+    const t = m[1].trim()
+    if (t.split(/\s+/).length <= 6 && !/[=;()]/.test(t)) texts.add(t)
+  }
+  for (const r of ROUTE_PATTERNS) for (const m of text.matchAll(r)) if (m[1] && m[1] !== "/") routes.add(m[1].startsWith("/") ? m[1] : `/${m[1]}`)
+  return { selectors: [...selectors], texts: [...texts], routes: [...routes] }
+}
+
+/** The route a file stands for under file-based routing (Next.js pages/ and app/, SvelteKit, Nuxt). */
+export function fileRoute(file: string): string | null {
+  const m = /(?:^|\/)(?:src\/)?(pages|app|routes)\/(.+?)\.(tsx|jsx|ts|js|vue|svelte)$/.exec(file)
+  if (!m) return null
+  let route = m[2].replace(/\/(page|index|\+page|_index)$/, "").replace(/^(page|index|\+page)$/, "")
+  if (m[1] === "app" && !/(^|\/)page$/.test(m[2])) return null
+  route = route.replace(/\([^)]*\)\/?/g, "").replace(/\[\.\.\.(\w+)\]/g, "*").replace(/\[(\w+)\]/g, ":$1")
+  if (/^_|\/_/.test(route) || /^api(\/|$)/.test(route)) return null
+  return `/${route}`.replace(/\/+$/, "") || "/"
+}
+
+// ---- Matching against page memory ----
+
+const lower = (s: string | null | undefined) => (s || "").trim().toLowerCase()
+
+/** The pages whose elements carry a changed selector or text, or whose path is a changed route. */
+export function pagesFor(pages: MemoryPage[], found: { file: string; selectors: string[]; texts: string[]; routes: string[] }[]): ImpactedPage[] {
+  const out = new Map<string, ImpactedPage>()
+  const hit = (p: MemoryPage, why: string, file: string) => {
+    const key = `${p.host}${p.path}`
+    const e = out.get(key) || { page: key, ...(p.title ? { title: p.title } : {}), evidence: [], files: [] }
+    if (!e.evidence.includes(why)) e.evidence.push(why)
+    if (!e.files.includes(file)) e.files.push(file)
+    out.set(key, e)
+  }
+  const routeRe = (r: string) => new RegExp(`^${r.replace(/[.+?^${}()|\\]/g, "\\$&").replace(/:\w+|\\\{\w+\\\}|\[\w+\]/g, "[^/]+").replace(/\*/g, ".*")}/?$`, "i")
+  for (const f of found) {
+    for (const p of pages) {
+      const elements = Object.values(p.elements || {})
+      for (const sel of f.selectors) {
+        const s = lower(sel)
+        const el = elements.find((e) => Object.values(e.attributes || {}).some((v) => lower(v) === s))
+        if (el) hit(p, `element ${JSON.stringify(sel)} (${el.tag}${el.name ? ` "${el.name}"` : ""})`, f.file)
+      }
+      for (const t of f.texts) {
+        const s = lower(t)
+        if (s.length >= 3 && elements.some((e) => lower(e.name) === s || lower(e.text) === s)) hit(p, `text ${JSON.stringify(t)}`, f.file)
+      }
+      for (const r of f.routes) if (routeRe(r).test(p.path) || p.path.toLowerCase().endsWith(r.toLowerCase())) hit(p, `route ${r}`, f.file)
+    }
+  }
+  return [...out.values()].sort((a, b) => b.evidence.length - a.evidence.length)
+}
+
+// ---- Reading the pull request ----
+
+async function adoChanges(cfg: AppConfig, ref: PrRef, pr: PrInfo): Promise<ChangedSource[]> {
+  const { auth } = adoSettings(cfg.sources)
+  const base = adoBase(ref)
+  const { data: its } = await http<{ value?: { id: number }[] }>(`${base}/pullRequests/${ref.number}/iterations?api-version=7.1`, { auth })
+  const last = its?.value?.at(-1)?.id
+  if (!last) return []
+  const { data: ch } = await http<{ changeEntries?: { item?: { path?: string; isFolder?: boolean }; changeType?: string }[] }>(`${base}/pullRequests/${ref.number}/iterations/${last}/changes?api-version=7.1&$top=500`, { auth })
+  const paths = (ch?.changeEntries || []).filter((c) => c.item?.path && !c.item.isFolder && !/delete/i.test(c.changeType || "")).map((c) => c.item!.path!.replace(/^\//, ""))
+  const out: ChangedSource[] = []
+  for (const p of paths) {
+    if (!CODE.test(p) || out.length >= MAX_FILES) {
+      out.push({ path: p, added: "" })
+      continue
+    }
+    try {
+      const q = new URLSearchParams({ path: `/${p}`, "versionDescriptor.version": pr.headSha, "versionDescriptor.versionType": "commit", includeContent: "true", "api-version": "7.1" })
+      const { data } = await http<{ content?: string } | string>(`${base}/items?${q}`, { auth, headers: { Accept: "application/json" } })
+      const content = typeof data === "string" ? data : data?.content || ""
+      out.push({ path: p, added: content.slice(0, MAX_BYTES) })
+    } catch {
+      out.push({ path: p, added: "" })
+    }
+  }
+  return out
+}
+
+/** The pull request and its changed files with their added code: from a matching clone, else the API. */
+export async function prSources(cfg: AppConfig, input: string, opts: { productRepo?: string; cwd: string }): Promise<{ pr: PrInfo; files: ChangedSource[]; via: "clone" | "api"; clone?: string; notes: string[] }> {
+  const notes: string[] = []
+  const candidates = [opts.productRepo, opts.cwd].filter((d): d is string => Boolean(d)).map((d) => path.resolve(opts.cwd, d))
+  let ref: PrRef | null = null
+  for (const dir of candidates) {
+    const top = git(dir, ["rev-parse", "--show-toplevel"])
+    if (top.status !== 0) continue
+    const root = top.stdout.trim()
+    const remotes = await gitRemotes(root)
+    try {
+      ref = parsePrRef(input, remotes)
+    } catch {
+      continue
+    }
+    const remote = remotes.find((r) => r.ref.platform === ref!.platform && (r.ref.repo || "").toLowerCase() === (ref!.repo || "").toLowerCase())
+    if (!remote) continue
+    const pr = await fetchPr(ref, cfg, root)
+    const { base, dropRefs } = await fetchPrBranches(root, remote.name, pr)
+    try {
+      const diff = git(root, ["diff", "--no-color", "--no-ext-diff", "-U0", "-M", "--src-prefix=a/", "--dst-prefix=b/", base, pr.headSha]).stdout
+      return { pr, files: addedByFile(diff), via: "clone", clone: root, notes }
+    } finally {
+      await dropRefs()
+    }
+  }
+  if (!ref) ref = parsePrRef(input, [])
+  const pr = await fetchPr(ref, cfg, opts.cwd)
+  notes.push("No local clone of the product repository: its changes were read through the API, without its imports, so a shared component is tied to pages only by what it names.")
+  if (ref.platform === "github") return { pr, files: addedByFile(await gh(["pr", "diff", String(ref.number), "--repo", ref.repo!], opts.cwd)), via: "api", notes }
+  return { pr, files: await adoChanges(cfg, ref, pr), via: "api", notes }
+}
+
+// ---- Following a shared component to its pages (with a clone) ----
+
+const PAGE_FILE = /(^|\/)(pages|app|routes|views|screens|containers|features)\//i
+
+function pagesThatImport(clone: string, changed: string[]): Map<string, string> {
+  const files = git(clone, ["ls-files"]).stdout.split("\n").filter((f) => f && /\.[cm]?[jt]sx?$|\.vue$|\.svelte$/.test(f) && !/node_modules\//.test(f)).slice(0, 8000)
+  const set = new Set(files)
+  const importers = new Map<string, string[]>()
+  for (const f of files) {
+    let text = ""
+    try {
+      const full = path.join(clone, f)
+      if (statSync(full).size <= MAX_BYTES) text = readFileSync(full, "utf8")
+    } catch {}
+    for (const dep of importsOf(f, text, set)) importers.set(dep, [...(importers.get(dep) || []), f])
+  }
+  // A page or view file that (through other modules) imports a changed file: page file → the changed file it reaches.
+  const reached = new Map<string, string>()
+  for (const start of changed) {
+    const queue = [start]
+    const seen = new Set([start])
+    while (queue.length && seen.size < 400) {
+      const f = queue.shift()!
+      for (const imp of importers.get(f) || []) {
+        if (seen.has(imp)) continue
+        seen.add(imp)
+        if (PAGE_FILE.test(imp) && !isTestFile(imp)) reached.set(imp, start)
+        queue.push(imp)
+      }
+    }
+  }
+  return reached
+}
+
+// ---- The whole analysis ----
+
+/** Tests in the automation repository that visit a page: by its path, its title, or a changed selector they use. */
+function testsForPages(repo: string, pages: ImpactedPage[], selectors: string[]): ImpactedTest[] {
+  const out = new Map<string, ImpactedTest>()
+  const files = git(repo, ["ls-files", "--cached", "--others", "--exclude-standard"]).stdout.split("\n").filter((f) => f && /\.([cm]?[jt]sx?|py|cs|java|kt)$/.test(f) && !/(^|\/)(node_modules|needs-attention)\//.test(f)).slice(0, 6000)
+  const texts = new Map<string, string>()
+  for (const f of files) {
+    try {
+      const full = path.join(repo, f)
+      if (statSync(full).size <= MAX_BYTES) texts.set(f, readFileSync(full, "utf8"))
+    } catch {}
+  }
+  const add = (file: string, why: string) => {
+    const t = out.get(file) || { file, reasons: [] }
+    if (!t.reasons.includes(why)) t.reasons.push(why)
+    out.set(file, t)
+  }
+  // Page objects and helpers that mention the page, then the tests that use them (by name).
+  const mentions = new Map<string, string>()
+  for (const p of pages) {
+    const pathPart = p.page.slice(p.page.indexOf("/"))
+    for (const [f, text] of texts) {
+      if ((pathPart.length > 1 && text.includes(pathPart)) || (p.title && p.title.length > 4 && text.includes(p.title))) mentions.set(f, p.page)
+    }
+  }
+  for (const s of selectors) for (const [f, text] of texts) if (s.length > 3 && (text.includes(`'${s}'`) || text.includes(`"${s}"`))) mentions.set(f, mentions.get(f) || `the element ${s}`)
+  for (const [f, what] of mentions) {
+    if (isTestFile(f)) add(f, `visits ${what}`)
+    else {
+      const stem = path.basename(f).replace(/\.[^.]+$/, "")
+      for (const [t, text] of texts) if (isTestFile(t) && stem.length >= 4 && text.includes(stem)) add(t, `uses ${stem}, which covers ${what}`)
+    }
+  }
+  const map = readMappings(repo).cases
+  for (const [id, m] of Object.entries(map)) if (m.testFile && out.has(m.testFile)) out.get(m.testFile)!.caseId = id
+  return [...out.values()].sort((a, b) => a.file.localeCompare(b.file))
+}
+
+export async function analyzeAreas(cfg: AppConfig, input: string, opts: { productRepo?: string; cwd: string }): Promise<AreaImpact> {
+  const src = await prSources(cfg, input, opts)
+  const notes = [...src.notes]
+  const found = src.files.map((f) => {
+    const names = namesInCode(f.added)
+    const route = fileRoute(f.path)
+    return { file: f.path, ...names, routes: [...names.routes, ...(route ? [route] : [])] }
+  })
+  // With a clone: a changed shared component counts for each page that imports it.
+  if (src.clone) {
+    const changedCode = src.files.map((f) => f.path).filter((p) => /\.[cm]?[jt]sx?$|\.vue$|\.svelte$/.test(p))
+    for (const [pageFile, via] of pagesThatImport(src.clone, changedCode)) {
+      let text = ""
+      try {
+        text = readFileSync(path.join(src.clone, pageFile), "utf8").slice(0, MAX_BYTES)
+      } catch {}
+      const names = namesInCode(text)
+      const route = fileRoute(pageFile)
+      found.push({ file: `${via} (through ${pageFile})`, selectors: names.selectors, texts: [], routes: [...names.routes, ...(route ? [route] : [])] })
+    }
+  }
+  const memory = cfg.memory?.dir && existsSync(cfg.memory.dir) ? readPages(cfg.memory.dir) : []
+  if (!memory.length) notes.push("Page memory is empty: run the application's flows with ForgeQE first, so changes can be tied to its pages.")
+  const pages = pagesFor(memory, found)
+  const routes = [...new Set(found.flatMap((f) => f.routes))]
+  const selectors = [...new Set(found.flatMap((f) => f.selectors))]
+  const tests = testsForPages(opts.cwd, pages, selectors)
+
+  // Requirements: the work items the pull request is linked to, and those the impacted tests' test cases test.
+  const ctx = { requirements: new Map<string, Requirement>() }
+  if (cfg.sources.ado) {
+    try {
+      if (src.pr.workItemIds?.length) await adoRequirements(cfg, src.pr.workItemIds, ctx)
+      const caseIds = tests.map((t) => t.caseId).filter((c): c is string => Boolean(c?.startsWith("ADO-"))).map((c) => Number(c.slice(4)))
+      for (const id of caseIds.slice(0, 15)) {
+        const { data } = await http<{ relations?: { rel: string; url: string }[] }>(`${adoSettings(cfg.sources).org}/_apis/wit/workitems/${id}?$expand=relations&api-version=7.1`, { auth: adoSettings(cfg.sources).auth })
+        const tested = (data?.relations || []).filter((r) => r.rel === "Microsoft.VSTS.Common.TestedBy-Reverse").map((r) => Number(r.url.split("/").pop()))
+        if (tested.length) await adoRequirements(cfg, tested, ctx)
+      }
+    } catch (err) {
+      notes.push(`Some work items could not be read: ${(err as Error).message.slice(0, 200)}`)
+    }
+  }
+  const requirements = [...ctx.requirements.values()]
+  // Manual test cases: test cases of the impacted requirements that no automated test covers yet.
+  const automated = new Set(Object.entries(readMappings(opts.cwd).cases).filter(([, m]) => m.status !== "needs_attention").map(([id]) => id))
+  const manual: ManualCase[] = []
+  for (const r of requirements) for (const tc of r.testedBy || []) if (!automated.has(tc) && !manual.some((m) => m.id === tc)) manual.push({ id: tc, requirement: r.id })
+  if (manual.length && cfg.sources.ado) {
+    try {
+      const { org, auth } = adoSettings(cfg.sources)
+      const { data } = await http<{ value?: { id: number; fields: Record<string, string> }[] }>(`${org}/_apis/wit/workitemsbatch?api-version=7.1`, { auth, body: { ids: manual.slice(0, 200).map((m) => Number(m.id.slice(4))), fields: ["System.Title", "System.TeamProject"], errorPolicy: "omit" } })
+      for (const w of data?.value || []) {
+        const m = manual.find((x) => x.id === `ADO-${w.id}`)
+        if (m) Object.assign(m, { title: w.fields["System.Title"], url: `${org}/${encodeURIComponent(w.fields["System.TeamProject"] || "")}/_workitems/edit/${w.id}` })
+      }
+    } catch {}
+  }
+  const tied = new Set(pages.flatMap((p) => p.files.map((f) => f.split(" (through")[0])))
+  const unmapped = src.files.map((f) => f.path).filter((p) => UI.test(p) && !tied.has(p))
+  return { pr: src.pr, via: src.via, files: src.files.map((f) => f.path), requirements, pages, routes, tests, manual, unmapped, notes }
+}