@capagents/forgeqe 1.1.3 → 1.1.5

package/src/code/graph/graph.ts

@@ -0,0 +1,511 @@
+import { createHash } from "node:crypto"
+import { mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { findPage, type MemoryElement, type MemoryPage } from "../../memory.ts"
+import { forgeqeHome } from "../../tools.ts"
+import { walk } from "../profile.ts"
+import { describeLocator, fromMemory, matchLocator, type LocatorRef } from "./locators.ts"
+import { langOf, parseFile, type ClassFacts, type CodeLocator, type FileFacts, type Member } from "./parse.ts"
+
+/**
+ * The code graph of a test repository: every class, member, test, call, and locator, read without a model and kept
+ * between jobs (a file is read again only when it changes). Scribe asks it where things are instead of reading files,
+ * and ForgeQE ties it to page memory, so an element of a run is found in the code however the code locates it.
+ */
+
+export type CodeGraph = { repo: string; files: FileFacts[]; parsed: number; reused: number; ms: number }
+
+type CacheEntry = { size: number; mtime: number; facts: FileFacts | null }
+type Cache = { version: number; files: Record<string, CacheEntry> }
+
+/** Raise when FileFacts changes shape, so older caches are read again. */
+const CACHE_VERSION = 4
+
+export function graphCacheFile(repo: string, dir = process.env.FORGEQE_GRAPH_CACHE_DIR || path.join(forgeqeHome(), "cache", "code-graph")): string {
+  let real = repo
+  try {
+    real = realpathSync(repo)
+  } catch {}
+  return path.join(dir, `${createHash("sha256").update(real).digest("hex").slice(0, 16)}.json`)
+}
+
+function readCache(file: string): Cache {
+  try {
+    const c = JSON.parse(readFileSync(file, "utf8")) as Cache
+    if (c.version === CACHE_VERSION && c.files) return c
+  } catch {}
+  return { version: CACHE_VERSION, files: {} }
+}
+
+/** The repository's graph, from the cache where its files have not changed. */
+export async function buildGraph(repo: string, opts: { cacheDir?: string } = {}): Promise<CodeGraph> {
+  const started = performance.now()
+  const cacheFile = graphCacheFile(repo, opts.cacheDir)
+  const cache = readCache(cacheFile)
+  const next: Cache = { version: CACHE_VERSION, files: {} }
+  const files: FileFacts[] = []
+  let parsed = 0
+  let reused = 0
+  for (const rel of walk(repo).filter((f) => langOf(f))) {
+    let st
+    try {
+      st = statSync(path.join(repo, rel))
+    } catch {
+      continue
+    }
+    const old = cache.files[rel]
+    let entry: CacheEntry
+    if (old && old.size === st.size && old.mtime === st.mtimeMs) {
+      entry = old
+      reused++
+    } else {
+      let facts: FileFacts | null = null
+      try {
+        facts = await parseFile(rel, readFileSync(path.join(repo, rel), "utf8"))
+      } catch {
+        // A file the grammar cannot read stays out of the graph.
+      }
+      entry = { size: st.size, mtime: st.mtimeMs, facts }
+      parsed++
+    }
+    next.files[rel] = entry
+    if (entry.facts) files.push(entry.facts)
+  }
+  if (parsed || Object.keys(cache.files).length !== Object.keys(next.files).length) {
+    try {
+      mkdirSync(path.dirname(cacheFile), { recursive: true })
+      writeFileSync(cacheFile, JSON.stringify(next))
+    } catch {
+      // Without a cache the next job reads every file again.
+    }
+  }
+  return { repo, files, parsed, reused, ms: Math.round(performance.now() - started) }
+}
+
+/** A member (or top-level function or test) with where it is. */
+export type Located = { file: string; cls?: ClassFacts; member: Member }
+
+export function allMembers(g: CodeGraph): Located[] {
+  return g.files.flatMap((f) => [...f.classes.flatMap((cls) => cls.members.map((member) => ({ file: f.file, cls, member }))), ...f.functions.map((member) => ({ file: f.file, member }))])
+}
+
+const qualified = (l: Located) => (l.cls ? `${l.cls.name}.${l.member.name}` : l.member.name)
+const where = (file: string, line: number) => `${file}:${line}`
+
+/** Words of an identifier or phrase: SignInAsync → sign, in, async; "Sign in" → sign, in. */
+function words(s: string): string[] {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Find
+
+export type Found = { score: number; text: string }
+
+/**
+ * Classes and members whose name, file, or locators match the query, best first. Only strong matches: every word of
+ * the query in the name, its class, or its locator text. A query for text in files (a config key, a case id) finds
+ * nothing here, and grep is the tool for it.
+ */
+export function findSymbols(g: CodeGraph, query: string, limit = 15): string[] {
+  const q = query.trim().toLowerCase()
+  const qw = words(query)
+  if (!qw.length) return []
+  const found: Found[] = []
+  const score = (name: string, extra: string): number => {
+    const n = name.toLowerCase()
+    if (n === q || n === q.replace(/\s+/g, "")) return 100
+    const nw = words(name)
+    if (qw.every((w) => nw.includes(w))) return 70
+    if (n.includes(q.replace(/\s+/g, ""))) return 60
+    const all = new Set([...nw, ...words(extra)])
+    const hit = qw.filter((w) => all.has(w) || [...all].some((a) => a.startsWith(w) && w.length >= 3)).length
+    return hit === qw.length ? 40 : hit && qw.length > 1 ? (20 * hit) / qw.length : 0
+  }
+  for (const f of g.files) {
+    for (const cls of f.classes) {
+      const s = score(cls.name, f.file)
+      if (s) found.push({ score: s + 5, text: `${cls.kind} ${cls.name}${cls.bases.length ? ` : ${cls.bases.join(", ")}` : ""}  ${where(f.file, cls.line)}  (${cls.members.length} members)` })
+    }
+  }
+  for (const l of allMembers(g)) {
+    const locText = l.member.locators.map((x) => `${x.role || ""} ${x.value}`).join(" ")
+    let s = score(l.member.name, `${l.cls?.name || ""} ${l.file}`)
+    // A locator's text ("Sign in") finds the member that locates it.
+    if (!s && locText && qw.every((w) => words(locText).includes(w))) s = 50
+    if (s) found.push({ score: s, text: `${l.member.kind} ${qualified(l)}  ${where(l.file, l.member.line)}  ${l.member.signature}` })
+  }
+  return found
+    .filter((x) => x.score >= 40)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((x) => x.text)
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Outline
+
+function locatorNote(l: CodeLocator): string {
+  return `${describeLocator(l)}${l.quality === "brittle" ? " [brittle]" : ""}`
+}
+
+function classOutline(file: string, cls: ClassFacts): string[] {
+  const lines = [`${cls.kind} ${cls.name}${cls.bases.length ? ` : ${cls.bases.join(", ")}` : ""}  ${where(file, cls.line)}-${cls.endLine}`]
+  for (const m of cls.members) {
+    lines.push(`  L${m.line} ${m.kind === "test" ? "test " : ""}${m.signature}`)
+    for (const l of m.locators) lines.push(`      locates: ${locatorNote(l)}`)
+  }
+  return lines
+}
+
+/**
+ * The outline of a file, a class, or the source of one member ("LoginPage.SignInAsync"): signatures and locators,
+ * not bodies, so Scribe reads only the lines it needs.
+ */
+export function outline(g: CodeGraph, target: string): string {
+  const t = target.trim().replace(/^\.\//, "")
+  const file = g.files.find((f) => f.file === t || f.file.endsWith(`/${t}`))
+  if (file) {
+    const out = [`${file.file} (${file.lang})`]
+    for (const cls of file.classes) out.push(...classOutline(file.file, cls))
+    for (const fn of file.functions) {
+      out.push(`L${fn.line} ${fn.kind === "test" ? "test " : ""}${fn.signature}`)
+      for (const l of fn.locators) out.push(`    locates: ${locatorNote(l)}`)
+    }
+    return out.join("\n")
+  }
+  const [clsName, memberName] = t.includes(".") ? [t.slice(0, t.lastIndexOf(".")), t.slice(t.lastIndexOf(".") + 1)] : [t, ""]
+  const owners = g.files.flatMap((f) => f.classes.filter((c) => c.name === clsName).map((cls) => ({ file: f.file, cls })))
+  if (owners.length && !memberName) return owners.flatMap((o) => classOutline(o.file, o.cls)).join("\n")
+  const members = memberName
+    ? owners.flatMap((o) => o.cls.members.filter((m) => m.name === memberName).map((member) => ({ file: o.file, cls: o.cls, member })))
+    : allMembers(g).filter((l) => l.member.name === t)
+  if (!members.length) return `Nothing named ${target} in the code graph. Use code_find to search.`
+  return members
+    .slice(0, 3)
+    .map((l) => {
+      let src = ""
+      try {
+        src = readFileSync(path.join(g.repo, l.file), "utf8").split("\n").slice(l.member.line - 1, l.member.endLine).join("\n")
+      } catch {}
+      return `${qualified(l)}  ${where(l.file, l.member.line)}-${l.member.endLine}\n${src}`
+    })
+    .join("\n\n")
+}
+
+/** The outlines of several classes, in order, up to a size, so a prompt can carry them instead of the files. */
+export function outlines(g: CodeGraph, classes: string[], maxChars = 8000): string {
+  const out: string[] = []
+  let size = 0
+  for (const cls of classes) {
+    const text = outline(g, cls)
+    if (text.startsWith("Nothing named") || size + text.length > maxChars) continue
+    size += text.length
+    out.push(text)
+  }
+  return out.join("\n\n")
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Elements: code ↔ page memory
+
+export type ElementMatch = { at: Located; locator: CodeLocator; how: "exact" | "pattern" | "param"; via: LocatorRef }
+
+const HOW_RANK = { exact: 0, pattern: 1, param: 2 }
+
+/** Members whose locators find an element known by any of `refs`, best first. */
+export function membersLocating(g: CodeGraph, refs: LocatorRef[]): ElementMatch[] {
+  const out: ElementMatch[] = []
+  for (const at of allMembers(g)) {
+    let best: ElementMatch | null = null
+    for (const locator of at.member.locators) {
+      for (const ref of refs) {
+        const how = matchLocator(locator, ref)
+        if (how && (!best || HOW_RANK[how] < HOW_RANK[best.how])) best = { at, locator, how, via: ref }
+      }
+    }
+    if (best) out.push(best)
+  }
+  // A parameterised role (any link) matches too much to be useful once something matches better.
+  const sorted = out.sort((a, b) => HOW_RANK[a.how] - HOW_RANK[b.how] || Number(b.at.member.kind === "property" || b.at.member.kind === "field") - Number(a.at.member.kind === "property" || a.at.member.kind === "field"))
+  return sorted[0] && sorted[0].how !== "param" ? sorted.filter((m) => m.how !== "param") : sorted
+}
+
+/** An element's locators from page memory, as refs, with its role and name. */
+export function elementRefs(e: MemoryElement): LocatorRef[] {
+  const refs = e.locators.map((l) => fromMemory(l.type, l.value)).filter((r): r is LocatorRef => Boolean(r))
+  if (e.role && e.name && !refs.some((r) => r.kind === "role")) refs.push({ kind: "role", role: e.role, value: e.name, quality: "semantic" })
+  if (e.text && !refs.some((r) => r.kind === "text")) refs.push({ kind: "text", value: e.text, quality: "semantic" })
+  return refs
+}
+
+/**
+ * Every locator of the element `refs` describe, from page memory: the same element is known there by its id, its role
+ * and name, its text, and its CSS, so code that uses any one of them is found. `url` narrows it to one page. When the
+ * refs fit several different elements (six "Add to cart" buttons), it says how many and adds nothing: guessing one
+ * would point at the wrong page-object member.
+ */
+export function sameElement(
+  pages: MemoryPage[],
+  refs: LocatorRef[],
+  url?: string,
+): { refs: LocatorRef[]; page?: MemoryPage; element?: MemoryElement; ambiguous?: number } {
+  const scope = url ? [findPage(pages, url)].filter((p): p is MemoryPage => Boolean(p)) : pages
+  const found = new Map<string, { page: MemoryPage; element: MemoryElement; known: LocatorRef[] }>()
+  for (const page of scope) {
+    for (const element of Object.values(page.elements || {})) {
+      const known = elementRefs(element)
+      // Only an exact, unique-looking locator ties a ref to a memory element: role+name, id, test id, label.
+      if (!refs.some((r) => !r.param && !r.pattern && r.value && r.kind !== "text" && r.kind !== "css" && known.some((k) => matchLocator(r, k) === "exact"))) continue
+      // The same element on several pages (a header on every page) is one element: keyed by its strongest locator.
+      const id = known.find((k) => k.kind === "testid") || known.find((k) => k.kind === "id") || known.find((k) => k.kind === "xpath") || known[0]
+      const key = `${id.kind}|${id.role || ""}|${id.value}`
+      if (!found.has(key)) found.set(key, { page, element, known })
+    }
+  }
+  if (found.size > 1) return { refs, ambiguous: found.size }
+  const [only] = found.values()
+  if (!only) return { refs }
+  const all = [...refs]
+  for (const k of only.known) if (!all.some((a) => a.kind === k.kind && a.value === k.value && a.role === k.role)) all.push(k)
+  return { refs: all, page: only.page, element: only.element }
+}
+
+/**
+ * The members that use a member: in its class and subclasses (LoginButton → SignInAsync), or, for a module-level
+ * selector constant, in its file and the files that import it (loginButton → LoginPage.login).
+ */
+const CONSTRUCTOR = /^(constructor|__init__)$/
+
+export function usersOf(g: CodeGraph, at: Located): string[] {
+  const name = at.member.name
+  if (!at.cls) {
+    const base = path.basename(at.file).replace(/\.\w+$/, "")
+    const files = g.files.filter((f) => f.file === at.file || (f.imports || []).some((spec) => spec.split(/[/.]/).filter(Boolean).pop() === base))
+    return allMembers(g)
+      .filter((l) => files.some((f) => f.file === l.file) && l.member !== at.member && !CONSTRUCTOR.test(l.member.name) && (l.member.names || []).includes(name))
+      // Page objects' methods first: they are what a test calls.
+      .sort((a, b) => Number(a.member.kind === "test") - Number(b.member.kind === "test"))
+      .map(qualified)
+  }
+  const subclasses = new Set(g.files.flatMap((f) => f.classes.filter((c) => c.bases.includes(at.cls!.name)).map((c) => c.name)))
+  return allMembers(g)
+    // A constructor only sets the field up; the members that act through it are its users.
+    .filter((l) => l.cls && (l.cls === at.cls || subclasses.has(l.cls.name)) && l.member !== at.member && !CONSTRUCTOR.test(l.member.name) && l.member.idents.includes(name))
+    .map(qualified)
+}
+
+/** One line per match, for the handoff and the tools. */
+export function describeMatches(g: CodeGraph, matches: ElementMatch[], max = 3): string[] {
+  return matches.slice(0, max).map((m) => {
+    const users = usersOf(g, m.at).slice(0, 4)
+    const how = m.how === "exact" ? "" : m.how === "pattern" ? " (its pattern matches)" : " (a parameterised locator for this role)"
+    return `${qualified(m.at)} at ${where(m.at.file, m.at.member.line)}: ${describeLocator(m.locator)}${m.locator.quality === "brittle" ? " [brittle]" : ""}${how}${users.length ? `; used by ${users.join(", ")}` : ""}`
+  })
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// References
+
+/** The class a receiver names: from the file's declarations, then any file's, then by name (articlePage → WikipediaArticlePage). */
+function receiverClass(g: CodeGraph, file: FileFacts, receiver: string, classes: Set<string>): string | null {
+  if (!receiver) return null
+  const last = receiver.split(".").pop() || receiver
+  if (classes.has(last)) return last
+  const bound = file.bindings[receiver] || file.bindings[last]
+  if (bound && classes.has(bound)) return bound
+  for (const f of g.files) {
+    const t = f.bindings[last]
+    if (t && classes.has(t)) return t
+  }
+  const key = last.replace(/^_+/, "").toLowerCase()
+  if (key.length < 3) return null
+  const byName = [...classes].filter((c) => c.toLowerCase() === key || c.toLowerCase().endsWith(key))
+  return byName.length === 1 ? byName[0] : null
+}
+
+/** The class and its base classes, nearest first. */
+function lineage(g: CodeGraph, name: string): string[] {
+  const out: string[] = []
+  let cur: string | undefined = name
+  while (cur && !out.includes(cur)) {
+    out.push(cur)
+    cur = g.files.flatMap((f) => f.classes).find((c) => c.name === cur)?.bases[0]
+  }
+  return out
+}
+
+export type Reference = { at: Located; line: number; certain: boolean }
+
+/** Every place that calls or reads `Class.member` (or `member`), tests first. */
+export function references(g: CodeGraph, target: string): { defined: Located[]; refs: Reference[] } {
+  const t = target.trim()
+  const dot = t.lastIndexOf(".")
+  const clsName = dot > 0 ? t.slice(0, dot) : ""
+  const name = dot > 0 ? t.slice(dot + 1) : t
+  const defined = allMembers(g).filter((l) => l.member.name === name && (!clsName || l.cls?.name === clsName))
+  if (!defined.length) return { defined, refs: [] }
+  const owners = new Set(defined.map((d) => d.cls?.name).filter((c): c is string => Boolean(c)))
+  const classes = new Set(g.files.flatMap((f) => f.classes.map((c) => c.name)))
+  const refs: Reference[] = []
+  for (const file of g.files) {
+    const members: Located[] = [...file.classes.flatMap((cls) => cls.members.map((member) => ({ file: file.file, cls, member }))), ...file.functions.map((member) => ({ file: file.file, member }))]
+    for (const at of members) {
+      if (defined.some((d) => d.member === at.member)) continue
+      const call = at.member.calls.find((c) => c.name === name)
+      if (call) {
+        const own = !call.receiver || /^(this|self|base|super)$/.test(call.receiver)
+        const cls = own ? (at.cls?.name ?? null) : receiverClass(g, file, call.receiver, classes)
+        if (cls && owners.size && lineage(g, cls).some((c) => owners.has(c))) {
+          refs.push({ at, line: call.line, certain: true })
+          continue
+        }
+        if (!cls && (owners.size <= 1 || !clsName)) {
+          refs.push({ at, line: call.line, certain: false })
+          continue
+        }
+      }
+      // A property read inside its own class or a subclass: LoginButton in SignInAsync.
+      if (!call && at.cls && at.member.idents.includes(name) && lineage(g, at.cls.name).some((c) => owners.has(c))) refs.push({ at, line: at.member.line, certain: true })
+    }
+  }
+  refs.sort((a, b) => Number(b.at.member.kind === "test") - Number(a.at.member.kind === "test") || Number(b.certain) - Number(a.certain))
+  return { defined, refs }
+}
+
+export function describeReferences(target: string, r: ReturnType<typeof references>, limit = 40): string {
+  if (!r.defined.length) return `Nothing named ${target} in the code graph. Use code_find to search.`
+  const lines = [`${target} is defined at ${r.defined.map((d) => where(d.file, d.member.line)).join(", ")}`]
+  if (!r.refs.length) return [...lines, "Nothing in the repository calls or reads it."].join("\n")
+  const tests = r.refs.filter((x) => x.at.member.kind === "test").length
+  lines.push(`${r.refs.length} ${r.refs.length === 1 ? "place uses" : "places use"} it${tests ? ` (${tests} ${tests === 1 ? "test" : "tests"})` : ""}:`)
+  for (const x of r.refs.slice(0, limit)) lines.push(`- ${x.at.member.kind === "test" ? "test " : ""}${qualified(x.at)}  ${where(x.at.file, x.line)}${x.certain ? "" : "  (by name only: its receiver's type is unknown)"}`)
+  if (r.refs.length > limit) lines.push(`… and ${r.refs.length - limit} more`)
+  return lines.join("\n")
+}
+
+/**
+ * The tests a change to these files reaches, through the calls between members: a changed page object reaches the
+ * flows that call it, and the tests that call those. Tests are known by their markers ([Test], @Test, test('…'),
+ * def test_), so a suite file of any name counts.
+ */
+export function testsReaching(g: CodeGraph, changed: string[]): { test: Located; why: string }[] {
+  const files = new Set(changed.map((f) => f.replace(/^\.\//, "")))
+  const classes = new Set(g.files.flatMap((f) => f.classes.map((c) => c.name)))
+  const byFile = new Map(g.files.map((f) => [f.file, f]))
+  const all = allMembers(g)
+  // Reached members, as Class.member, with why.
+  const reached = new Map<string, string>()
+  for (const l of all) if (files.has(l.file)) reached.set(qualified(l), `in ${l.file}`)
+  const out = new Map<Located, string>()
+  for (const l of all) if (files.has(l.file) && l.member.kind === "test") out.set(l, `is in ${l.file}`)
+  for (let round = 0; round < 5; round++) {
+    let grew = false
+    for (const l of all) {
+      const key = qualified(l)
+      if (reached.has(key) && !(l.member.kind === "test" && !out.has(l))) continue
+      for (const call of l.member.calls) {
+        const own = !call.receiver || /^(this|self|base|super)$/.test(call.receiver)
+        const cls = own ? (l.cls?.name ?? null) : receiverClass(g, byFile.get(l.file)!, call.receiver, classes)
+        if (!cls) continue
+        const hit = lineage(g, cls).map((c) => `${c}.${call.name}`).find((k) => reached.has(k))
+        if (!hit) continue
+        if (l.member.kind === "test") out.set(l, `calls ${hit}${reached.get(hit)?.startsWith("in ") ? "" : ` (${reached.get(hit)})`}`)
+        if (!reached.has(key)) {
+          reached.set(key, `through ${hit}`)
+          grew = true
+        }
+        break
+      }
+    }
+    if (!grew) break
+  }
+  return [...out].map(([test, why]) => ({ test, why }))
+}
+
+/** The classes a member calls into: its receivers' classes and their bases, and its own class's bases. */
+function classesCalled(g: CodeGraph, file: FileFacts, at: Located, classes: Set<string>): Set<string> {
+  const out = new Set<string>()
+  for (const call of at.member.calls) {
+    const own = !call.receiver || /^(this|self|base|super)$/.test(call.receiver)
+    const cls = own ? (at.cls?.bases[0] ?? null) : receiverClass(g, file, call.receiver, classes)
+    if (!cls) continue
+    // Only the classes in the lineage that define what was called, so BasePage is named for OpenAsync, not always.
+    for (const c of lineage(g, cls)) {
+      if (!classes.has(c)) continue
+      out.add(c)
+      if (g.files.some((f) => f.classes.some((k) => k.name === c && k.members.some((m) => m.name === call.name)))) break
+    }
+  }
+  return out
+}
+
+/** The classes the code in these files uses, most used first; not the classes the files define themselves. */
+export function classesUsedBy(g: CodeGraph, files: string[]): string[] {
+  const wanted = new Set(files.map((f) => f.replace(/^\.\//, "")))
+  const classes = new Set(g.files.flatMap((f) => f.classes.map((c) => c.name)))
+  const own = new Set(g.files.filter((f) => wanted.has(f.file)).flatMap((f) => f.classes.map((c) => c.name)))
+  const count = new Map<string, number>()
+  for (const file of g.files.filter((f) => wanted.has(f.file))) {
+    const members: Located[] = [...file.classes.flatMap((cls) => cls.members.map((member) => ({ file: file.file, cls, member }))), ...file.functions.map((member) => ({ file: file.file, member }))]
+    for (const at of members) for (const c of classesCalled(g, file, at, classes)) if (!own.has(c)) count.set(c, (count.get(c) || 0) + 1)
+  }
+  return [...count].sort((a, b) => b[1] - a[1]).map(([c]) => c)
+}
+
+/**
+ * The test that uses the most of these classes, as an example of how the repository's tests use them: its fixture,
+ * attributes, setup, and assertion style. Null when no test uses any of them.
+ */
+export function exampleTest(g: CodeGraph, classes: string[]): Located | null {
+  const wanted = new Set(classes)
+  const all = new Set(g.files.flatMap((f) => f.classes.map((c) => c.name)))
+  let best: { at: Located; hits: number; size: number } | null = null
+  for (const file of g.files) {
+    const members: Located[] = [...file.classes.flatMap((cls) => cls.members.map((member) => ({ file: file.file, cls, member }))), ...file.functions.map((member) => ({ file: file.file, member }))]
+    for (const at of members) {
+      if (at.member.kind !== "test") continue
+      const hits = [...classesCalled(g, file, at, all)].filter((c) => wanted.has(c)).length
+      const size = at.member.endLine - at.member.line
+      if (hits && (!best || hits > best.hits || (hits === best.hits && size < best.size))) best = { at, hits, size }
+    }
+  }
+  return best?.at ?? null
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// What a job added: duplicates and brittle locators, for the reviewer
+
+/** Members in `after` that are new, keyed Class.member@file. */
+function newMembers(before: CodeGraph, after: CodeGraph, changed: Set<string>): Located[] {
+  const key = (l: Located) => `${l.file}|${qualified(l)}`
+  const old = new Set(allMembers(before).map(key))
+  return allMembers(after).filter((l) => changed.has(l.file) && !old.has(key(l)))
+}
+
+/**
+ * Facts about what a job added, for the reviewer: new members that locate an element an existing member already
+ * locates (a duplicate to reuse), and new XPath or positional locators.
+ */
+export function additionFacts(before: CodeGraph, after: CodeGraph, changed: string[]): string[] {
+  const added = newMembers(before, after, new Set(changed))
+  const existing = allMembers(before)
+  const out: string[] = []
+  for (const l of added) {
+    for (const loc of l.member.locators) {
+      if (loc.param || loc.pattern || !loc.value) continue
+      const same = existing.find((e) => e.member.locators.some((x) => !x.param && matchLocator(x, loc) === "exact"))
+      if (same) out.push(`${qualified(l)} (${where(l.file, l.member.line)}) locates ${describeLocator(loc)}, which ${qualified(same)} (${where(same.file, same.member.line)}) already locates: reuse it instead of a second locator for the same element.`)
+    }
+    for (const loc of l.member.locators.filter((x) => x.quality === "brittle")) {
+      out.push(`${qualified(l)} (${where(l.file, loc.line)}) uses a brittle locator: ${describeLocator(loc)}.`)
+    }
+  }
+  return [...new Set(out)].slice(0, 20)
+}