@capagents/forgeqe 1.1.3 → 1.1.5

package/src/code/graph/parse.ts

@@ -0,0 +1,439 @@
+import { createRequire } from "node:module"
+import path from "node:path"
+
+import { Language, Parser, type Node } from "@vscode/tree-sitter-wasm"
+
+import { fromSelectorString, locatorFromBy, locatorFromCall, selectorLike, type LocatorRef } from "./locators.ts"
+
+/**
+ * What one source file of a test repository holds, read with tree-sitter: its classes and their members, top-level
+ * functions and tests, the calls each makes, and the locators each builds. TypeScript, JavaScript, C#, Java, Python.
+ */
+
+export type Lang = "typescript" | "tsx" | "javascript" | "c_sharp" | "java" | "python"
+
+export type Call = { name: string; receiver: string; line: number }
+
+export type CodeLocator = LocatorRef & { line: number; code: string }
+
+export type Member = {
+  name: string
+  kind: "method" | "property" | "field" | "function" | "test"
+  /** The declaration up to its body, on one line. */
+  signature: string
+  line: number
+  endLine: number
+  calls: Call[]
+  /** Names the member's body mentions (properties it reads, as well as calls). */
+  idents: string[]
+  /** The names it uses on their own, not as a property of something (loginButton, not testData.username). */
+  names?: string[]
+  locators: CodeLocator[]
+}
+
+export type ClassFacts = { name: string; kind: "class" | "interface"; bases: string[]; line: number; endLine: number; members: Member[] }
+
+export type FileFacts = {
+  file: string
+  lang: Lang
+  classes: ClassFacts[]
+  /** Top-level functions and tests (test('…'), def test_…), outside any class. */
+  functions: Member[]
+  /** Variables and parameters the file declares with a type or constructs: loginPage → LoginPage. */
+  bindings: Record<string, string>
+  /** The modules it imports, as written: "../pageobjects/loginPage", "pages.login_page", "pages.LoginPage". */
+  imports: string[]
+}
+
+const EXT: Record<string, Lang> = { ".ts": "typescript", ".mts": "typescript", ".cts": "typescript", ".tsx": "tsx", ".js": "javascript", ".mjs": "javascript", ".cjs": "javascript", ".jsx": "javascript", ".cs": "c_sharp", ".java": "java", ".py": "python" }
+
+export function langOf(file: string): Lang | null {
+  if (file.endsWith(".d.ts")) return null
+  return EXT[path.extname(file).toLowerCase()] || null
+}
+
+const WASM: Record<Lang, string> = { typescript: "typescript", tsx: "tsx", javascript: "javascript", c_sharp: "c-sharp", java: "java", python: "python" }
+
+let ready: Promise<void> | null = null
+const languages = new Map<Lang, Promise<Language>>()
+const wasmDir = () => path.dirname(createRequire(import.meta.url).resolve("@vscode/tree-sitter-wasm"))
+
+async function parserFor(lang: Lang): Promise<Parser> {
+  ready ??= Parser.init({ locateFile: (f: string) => path.join(wasmDir(), f) })
+  await ready
+  if (!languages.has(lang)) languages.set(lang, Language.load(path.join(wasmDir(), `tree-sitter-${WASM[lang]}.wasm`)))
+  const parser = new Parser()
+  parser.setLanguage(await languages.get(lang)!)
+  return parser
+}
+
+const CLASS_TYPES = new Set(["class_declaration", "abstract_class_declaration", "interface_declaration", "record_declaration", "struct_declaration", "class_definition", "class"])
+const CALL_TYPES = new Set(["call_expression", "invocation_expression", "method_invocation", "call"])
+const IDENT_TYPES = new Set(["identifier", "property_identifier", "field_identifier", "type_identifier", "shorthand_property_identifier", "shorthand_property_identifier_pattern"])
+const TEST_ATTRS = /^(Test|TestCase|TestCaseSource|Fact|Theory|TestMethod|DataTestMethod|ParameterizedTest|RepeatedTest|TestTemplate)$/
+const TEST_CALLEE = /^(test|it|specify)(\.(only|skip|fixme|fail|slow))?$/
+
+const line = (n: Node) => n.startPosition.row + 1
+const endLine = (n: Node) => n.endPosition.row + 1
+const one = (s: string, max = 200) => {
+  const t = s.replace(/\s+/g, " ").trim()
+  return t.length <= max ? t : `${t.slice(0, max - 1)}…`
+}
+const kids = (n: Node | null) => (n ? (n.namedChildren.filter(Boolean) as Node[]) : [])
+
+/**
+ * What a call is made on: this.loginPage → loginPage, new CartPage(page) → CartPage, (await x) → x. "?" for an
+ * expression it cannot name (a chained call), so it is never taken for the caller's own class.
+ */
+function receiverName(n: Node | null): string {
+  if (!n) return ""
+  let e = n
+  while (["parenthesized_expression", "await_expression"].includes(e.type) && kids(e).length === 1) e = kids(e)[0]
+  if (["object_creation_expression", "new_expression"].includes(e.type)) {
+    const type = e.childForFieldName("type") || e.childForFieldName("constructor")
+    const name = type?.text.replace(/<.*$/, "").split(".").pop() || ""
+    return /^[A-Za-z_]\w*$/.test(name) ? name : "?"
+  }
+  const t = e.text.replace(/^(this|self)\./, "")
+  return /^[\w$.]+$/.test(t) ? t : "?"
+}
+
+/** A call's callee name and the expression it is called on. */
+function calleeOf(call: Node): { name: string; receiver: string } | null {
+  if (call.type === "method_invocation") return { name: call.childForFieldName("name")?.text || "", receiver: receiverName(call.childForFieldName("object")) }
+  const fn = call.childForFieldName("function")
+  if (!fn) return null
+  switch (fn.type) {
+    case "identifier":
+      return { name: fn.text, receiver: "" }
+    case "member_expression":
+      return { name: fn.childForFieldName("property")?.text || "", receiver: receiverName(fn.childForFieldName("object")) }
+    case "member_access_expression": {
+      const name = fn.childForFieldName("name")
+      return { name: (name?.type === "generic_name" ? kids(name)[0]?.text : name?.text) || "", receiver: receiverName(fn.childForFieldName("expression")) }
+    }
+    case "attribute":
+      return { name: fn.childForFieldName("attribute")?.text || "", receiver: receiverName(fn.childForFieldName("object")) }
+    case "generic_name":
+      return { name: kids(fn)[0]?.text || "", receiver: "" }
+    default:
+      return null
+  }
+}
+
+function argsText(call: Node): string {
+  const args = call.childForFieldName("arguments")
+  return args ? args.text.replace(/^\(|\)$/g, "") : ""
+}
+
+/** Calls, names, and locators in a subtree. */
+const ACCESS_TYPES = new Set(["member_expression", "member_access_expression", "attribute", "field_access"])
+
+/** An identifier that names a property of something: the "username" of testData.username. */
+function isProperty(n: Node): boolean {
+  const p = n.parent
+  if (!p || !ACCESS_TYPES.has(p.type)) return false
+  const object = p.childForFieldName("object") || p.childForFieldName("expression")
+  return !object || object.startIndex !== n.startIndex
+}
+
+function scan(root: Node, skip?: (n: Node) => boolean): { calls: Call[]; idents: string[]; names: string[]; locators: CodeLocator[] } {
+  const calls: Call[] = []
+  const idents = new Set<string>()
+  const names = new Set<string>()
+  const locators: CodeLocator[] = []
+  const seen = new Set<string>()
+  const stack: Node[] = [root]
+  while (stack.length) {
+    const n = stack.pop()!
+    if (n !== root && skip?.(n)) continue
+    if (CALL_TYPES.has(n.type)) {
+      const c = calleeOf(n)
+      if (c?.name) {
+        calls.push({ name: c.name, receiver: c.receiver, line: line(n) })
+        const loc = locatorFromCall(c.name, c.receiver, argsText(n))
+        const key = loc ? `${loc.kind}|${loc.role || ""}|${loc.value}` : ""
+        if (loc && !seen.has(key)) {
+          seen.add(key)
+          locators.push({ ...loc, line: line(n), code: one(n.text, 160) })
+        }
+      }
+    } else if (IDENT_TYPES.has(n.type) && n.text.length > 1) {
+      idents.add(n.text)
+      if (n.type === "identifier" && !isProperty(n)) names.add(n.text)
+    }
+    for (const k of kids(n)) stack.push(k)
+  }
+  locators.sort((a, b) => a.line - b.line)
+  return { calls, idents: [...idents].slice(0, 300), names: [...names].slice(0, 300), locators }
+}
+
+/** The declaration up to its body, without the body. */
+function signatureOf(n: Node): string {
+  const body = n.childForFieldName("body")
+  if (!body) return one(n.text)
+  return one(n.text.slice(0, body.startIndex - n.startIndex).replace(/\s*(=>|:)\s*$/, ""))
+}
+
+function memberName(n: Node): string {
+  const name = n.childForFieldName("name") || n.childForFieldName("property")
+  if (name) return name.text
+  // C# and Java fields: the first declarator's name.
+  const decl = n.descendantsOfType("variable_declarator")[0]
+  const declName = decl?.childForFieldName("name") || (decl ? kids(decl)[0] : null)
+  if (declName) return declName.text
+  // Python class attribute: x = …
+  const assign = n.type === "expression_statement" ? kids(n).find((k) => k.type === "assignment") : null
+  return assign?.childForFieldName("left")?.text || ""
+}
+
+/** C# [Test] attributes, Java @Test annotations. */
+function hasTestMarker(n: Node): boolean {
+  for (const k of kids(n)) {
+    if (k.type === "attribute_list" && k.descendantsOfType("attribute").some((a) => TEST_ATTRS.test(a?.childForFieldName("name")?.text.split(".").pop() || ""))) return true
+    if (k.type === "modifiers" && k.descendantsOfType(["marker_annotation", "annotation"]).some((a) => TEST_ATTRS.test(a?.childForFieldName("name")?.text || ""))) return true
+  }
+  return false
+}
+
+const STRING_TYPES = new Set(["string", "string_literal", "verbatim_string_literal", "raw_string_literal", "template_string"])
+const VALUE_PARENTS = new Set(["variable_declarator", "public_field_definition", "field_definition", "assignment", "assignment_expression", "arrow_expression_clause", "equals_value_clause", "property_declaration"])
+
+/** A plain string literal's value ('…', "…", @"…", r"…", `…` without ${}); null for anything else. */
+function stringValue(n: Node | null): string | null {
+  if (!n || !STRING_TYPES.has(n.type)) return null
+  const m = /^(?:@|[rRbBuU]{1,2})?(["'`])([\s\S]*)\1$/.exec(n.text)
+  if (!m || (m[1] === "`" && m[2].includes("${"))) return null
+  return m[2].replace(/\\(["'`\\])/g, "$1")
+}
+
+/** A selector kept as a declaration's value: const login = "#login", private String LOGIN = "[data-test=x]". */
+function constantLocator(n: Node): CodeLocator | null {
+  const lit = n.descendantsOfType([...STRING_TYPES]).find((x) => x && VALUE_PARENTS.has(x.parent?.type || "") && x.parent !== null)
+  const value = stringValue(lit || null)
+  if (!lit || value === null || !selectorLike(value)) return null
+  return { ...fromSelectorString(value), line: line(lit), code: one(n.text, 160) }
+}
+
+/** Selenium page-factory annotations: Java @FindBy(id = "x"), @FindBy(how = How.ID, using = "x"); C# [FindsBy(How = How.Id, Using = "x")]. */
+function annotationLocators(n: Node): CodeLocator[] {
+  const out: CodeLocator[] = []
+  const notes = kids(n).flatMap((k) =>
+    k.type === "modifiers" ? (k.descendantsOfType("annotation").filter(Boolean) as Node[]) : k.type === "attribute_list" ? (k.descendantsOfType("attribute").filter(Boolean) as Node[]) : [],
+  )
+  for (const a of notes) {
+    if (!/^(FindBy|FindsBy|AndroidFindBy|iOSXCUITFindBy)$/.test(a.childForFieldName("name")?.text.split(".").pop() || "")) continue
+    const pairs = new Map<string, string>()
+    for (const m of a.text.matchAll(/(\w+)\s*=\s*("(?:[^"\\]|\\.)*"|How\.\w+)/g)) pairs.set(m[1].toLowerCase(), m[2].replace(/^"|"$/g, "").replace(/^How\./, ""))
+    const how = pairs.get("how")
+    const using = pairs.get("using")
+    const [kind, value] = how && using ? [how, using] : [...pairs].find(([k]) => /^(id|name|classname|css|xpath|linktext|partiallinktext|tagname|accessibility|androiduiautomator)$/.test(k)) || ["", ""]
+    const ref = kind && value ? locatorFromBy(kind === "accessibility" ? "name" : kind, value) : null
+    if (ref) out.push({ ...ref, line: line(a), code: one(a.text, 160) })
+  }
+  return out
+}
+
+function member(n: Node, kind: Member["kind"], name = memberName(n)): Member | null {
+  if (!name) return null
+  const body = scan(n)
+  const constant = kind === "field" || kind === "property" ? constantLocator(n) : null
+  const locators = [...annotationLocators(n), ...(constant ? [constant] : []), ...body.locators]
+  return { name, kind, signature: signatureOf(n), line: line(n), endLine: endLine(n), ...body, locators }
+}
+
+/** this.x = …, self.x = …, X = … (C#, Java): the field an assignment sets, or "" for a local variable. */
+function assignedField(left: Node | null, fields: Set<string>): string {
+  if (!left) return ""
+  const t = left.text
+  const own = /^(this|self)\.([A-Za-z_$][\w$]*)$/.exec(t)
+  if (own) return own[2]
+  return /^[A-Za-z_]\w*$/.test(t) && fields.has(t) ? t : ""
+}
+
+/**
+ * Locators that methods and constructors assign to fields (this.cart = page.locator('.cart'), self.user =
+ * page.get_by_label("User"), LoginButton = page.Locator("#login") in a C# constructor) belong to those fields:
+ * the field is what the page object's other members use, not the constructor.
+ */
+function assignFieldLocators(body: Node | null, members: Member[]): void {
+  const fields = new Set(members.filter((m) => m.kind === "field" || m.kind === "property").map((m) => m.name))
+  for (const holder of kids(body)) {
+    const def = holder.type === "decorated_definition" ? holder.childForFieldName("definition") : holder
+    if (!def || !["method_definition", "method_declaration", "constructor_declaration", "function_definition"].includes(def.type)) continue
+    const owner = members.find((m) => m.line === line(def) && m.name === memberName(def))
+    for (const a of def.descendantsOfType(["assignment_expression", "assignment"]).filter(Boolean) as Node[]) {
+      const field = assignedField(a.childForFieldName("left"), fields)
+      const right = a.childForFieldName("right")
+      if (!field || !right) continue
+      const found = scan(right).locators.map((l) => ({ ...l, line: line(a) }))
+      const value = stringValue(right)
+      if (value !== null && selectorLike(value)) found.push({ ...fromSelectorString(value), line: line(a), code: one(a.text, 160) })
+      if (!found.length) continue
+      let target = members.find((m) => m.name === field && (m.kind === "field" || m.kind === "property"))
+      if (!target) {
+        target = { name: field, kind: "field", signature: one(a.text), line: line(a), endLine: endLine(a), calls: [], idents: [], locators: [] }
+        members.push(target)
+        fields.add(field)
+      }
+      for (const l of found) if (!target.locators.some((x) => x.kind === l.kind && x.value === l.value && x.role === l.role)) target.locators.push(l)
+      // The constructor or method only assigned them.
+      if (owner) owner.locators = owner.locators.filter((l) => !found.some((f) => f.kind === l.kind && f.value === l.value && f.role === l.role))
+    }
+  }
+}
+
+/** One member of a class body, or null for what is not one (comments, constructors, nested classes). */
+function classMember(n: Node, lang: Lang): Member | null {
+  const def = n.type === "decorated_definition" ? n.childForFieldName("definition") : n
+  if (!def) return null
+  switch (def.type) {
+    case "method_definition":
+    case "method_declaration":
+      return member(def, hasTestMarker(def) ? "test" : def.text.startsWith("get ") ? "property" : "method")
+    case "function_definition":
+      return member(def, lang === "python" && /^test_/.test(memberName(def)) ? "test" : n.type === "decorated_definition" && /@property/.test(n.text) ? "property" : "method")
+    case "property_declaration":
+      return member(def, "property")
+    case "public_field_definition":
+    case "field_definition":
+    case "field_declaration":
+      return member(def, "field")
+    case "expression_statement":
+      return lang === "python" ? member(def, "field") : null
+    default:
+      return null
+  }
+}
+
+function basesOf(n: Node): string[] {
+  const holder = kids(n).find((k) => ["class_heritage", "base_list", "superclass", "super_interfaces", "argument_list"].includes(k.type)) || n.childForFieldName("superclasses")
+  if (!holder) return []
+  const names = holder.descendantsOfType(["identifier", "type_identifier"]).map((x) => x?.text || "")
+  return [...new Set(names.filter((x) => /^[A-Z]/.test(x)))]
+}
+
+function classFacts(n: Node, lang: Lang): ClassFacts | null {
+  const name = n.childForFieldName("name")?.text
+  if (!name) return null
+  const body = n.childForFieldName("body")
+  const members = kids(body)
+    .map((k) => classMember(k, lang))
+    .filter((m): m is Member => Boolean(m))
+  assignFieldLocators(body, members)
+  members.sort((a, b) => a.line - b.line)
+  return { name, kind: n.type === "interface_declaration" ? "interface" : "class", bases: basesOf(n), line: line(n), endLine: endLine(n), members }
+}
+
+/** test('title', …, async () => {…}) in TypeScript and JavaScript, with the title as its name. */
+function jsTest(call: Node): Member | null {
+  const c = calleeOf(call)
+  const callee = c ? (c.receiver ? `${c.receiver}.${c.name}` : c.name) : ""
+  if (!TEST_CALLEE.test(callee)) return null
+  const args = kids(call.childForFieldName("arguments"))
+  const title = args[0]
+  const fn = args[args.length - 1]
+  if (!title || !/string|template_string/.test(title.type) || !fn || !/function|arrow_function/.test(fn.type)) return null
+  return { name: title.text.slice(1, -1), kind: "test", signature: one(`${callee}(${title.text})`), line: line(call), endLine: endLine(call), ...scan(fn) }
+}
+
+/** Top-level functions: function f(), const f = () =>, def f(). */
+function topFunction(n: Node, lang: Lang): Member | null {
+  const def = n.type === "decorated_definition" ? n.childForFieldName("definition") : n
+  if (!def) return null
+  if (def.type === "function_declaration" || def.type === "generator_function_declaration") return member(def, "function")
+  if (def.type === "function_definition") return member(def, lang === "python" && /^test_/.test(memberName(def)) ? "test" : "function")
+  // A selector constant at module level: export const loginButton = "[data-test='login-button']", LOGIN = "#login".
+  if (def.type === "lexical_declaration" || def.type === "variable_declaration" || (lang === "python" && def.type === "expression_statement")) {
+    const decl = kids(def).find((k) => k.type === "variable_declarator" || k.type === "assignment")
+    const value = decl?.childForFieldName("value") || decl?.childForFieldName("right")
+    const text = stringValue(value || null)
+    const name = (decl?.childForFieldName("name") || decl?.childForFieldName("left"))?.text || ""
+    if (text !== null && selectorLike(text) && /^[A-Za-z_$][\w$]*$/.test(name)) {
+      return { name, kind: "field", signature: one(def.text), line: line(def), endLine: endLine(def), calls: [], idents: [], locators: [{ ...fromSelectorString(text), line: line(def), code: one(def.text, 160) }] }
+    }
+  }
+  if (def.type === "lexical_declaration" || def.type === "variable_declaration") {
+    const decl = kids(def).find((k) => k.type === "variable_declarator")
+    const value = decl?.childForFieldName("value")
+    if (decl && value && /function|arrow_function/.test(value.type)) {
+      const name = decl.childForFieldName("name")?.text || ""
+      const body = value.childForFieldName("body")
+      return name ? { name, kind: "function", signature: one(def.text.slice(0, (body?.startIndex ?? value.endIndex) - def.startIndex).replace(/\s*=>\s*$/, "")), line: line(def), endLine: endLine(def), ...scan(value) } : null
+    }
+  }
+  return null
+}
+
+/** loginPage → LoginPage from `x = new T(`, `T x`, `x: T`, `x = T(` (Python). Only names that look like types. */
+export function bindingsOf(text: string, lang: Lang): Record<string, string> {
+  const out: Record<string, string> = {}
+  const add = (v: string, t: string) => {
+    if (v && t && /^[A-Z]/.test(t) && !(v in out)) out[v.replace(/^(this|self)\./, "")] = t
+  }
+  for (const m of text.matchAll(/([\w$.]+)\s*=\s*new\s+([A-Z]\w*)\s*[(<]/g)) add(m[1], m[2])
+  if (lang === "python") for (const m of text.matchAll(/([\w.]+)\s*=\s*([A-Z]\w*)\(/g)) add(m[1], m[2])
+  for (const m of text.matchAll(/([\w$]+)\s*\??:\s*([A-Z]\w*)\b/g)) add(m[1], m[2])
+  if (lang === "c_sharp" || lang === "java") {
+    for (const m of text.matchAll(/\b([A-Z]\w*)(?:<[^<>]*>)?\s+(_?[a-z]\w*)\s*(?=[;=,)])/g)) add(m[2], m[1])
+  }
+  return out
+}
+
+/** The modules a file imports, as written. */
+function importsOf(text: string, lang: Lang): string[] {
+  const out = new Set<string>()
+  const patterns =
+    lang === "python"
+      ? [/^\s*from\s+([\w.]+)\s+import/gm, /^\s*import\s+([\w.]+)/gm]
+      : lang === "java"
+        ? [/^\s*import\s+(?:static\s+)?([\w.]+)\s*;/gm]
+        : lang === "c_sharp"
+          ? [/^\s*using\s+(?:static\s+)?([\w.]+)\s*;/gm]
+          : [/(?:from\s+|require\(\s*|import\s+)['"]([^'"]+)['"]/g]
+  for (const re of patterns) for (const m of text.matchAll(re)) out.add(m[1])
+  return [...out]
+}
+
+/** The file's facts; null when the language is not supported or it does not parse. */
+export async function parseFile(file: string, text: string): Promise<FileFacts | null> {
+  const lang = langOf(file)
+  if (!lang) return null
+  const parser = await parserFor(lang)
+  const tree = parser.parse(text)
+  if (!tree) {
+    parser.delete()
+    return null
+  }
+  try {
+    const classes: ClassFacts[] = []
+    const functions: Member[] = []
+    const visit = (n: Node, inClass: boolean) => {
+      if (CLASS_TYPES.has(n.type)) {
+        const c = classFacts(n, lang)
+        if (c) classes.push(c)
+        // Nested classes are classes of their own.
+        for (const k of kids(n.childForFieldName("body"))) visit(k, true)
+        return
+      }
+      if (!inClass) {
+        const f = topFunction(n, lang)
+        if (f) functions.push(f)
+        if (CALL_TYPES.has(n.type)) {
+          const t = jsTest(n)
+          if (t) {
+            functions.push(t)
+            return
+          }
+        }
+      }
+      if (n.type === "function_declaration" || n.type === "function_definition" || n.type === "method_definition") return
+      for (const k of kids(n)) visit(k, inClass)
+    }
+    visit(tree.rootNode, false)
+    return { file, lang, classes, functions, bindings: bindingsOf(text, lang), imports: importsOf(text, lang) }
+  } finally {
+    tree.delete()
+    parser.delete()
+  }
+}

package/src/code/graph/tools.ts

@@ -0,0 +1,113 @@
+import { readPages, type MemoryPage } from "../../memory.ts"
+import type { McpTool } from "../../mcp/tools.ts"
+import { analyzeImpact } from "../impact.ts"
+import { buildGraph, describeMatches, describeReferences, findSymbols, membersLocating, outline, references, sameElement, testsReaching, type CodeGraph } from "./graph.ts"
+import { describeLocator, fromCss, locatorFromExpression, type LocatorRef } from "./locators.ts"
+
+/**
+ * The code graph as tools for Scribe (the agent runtime names them code_find, code_outline, …). Each call brings the
+ * graph up to date first, re-reading only the files changed since, so Scribe's own edits are in it.
+ */
+
+/** The agent runtime names this server's tools `code_<tool>`. */
+export const CODE_GRAPH_SERVER = "code"
+
+/** The refs an element argument describes: a Playwright expression, or role and name, text, test id, id, label, CSS. */
+export function refsFromArgs(a: Record<string, unknown>): LocatorRef[] {
+  const s = (k: string) => (typeof a[k] === "string" ? (a[k] as string).trim() : "")
+  const refs: LocatorRef[] = []
+  if (s("locator")) {
+    const r = locatorFromExpression(s("locator")) || (/^[#.[\w]/.test(s("locator")) ? fromCss(s("locator")) : null)
+    if (r) refs.push(r)
+  }
+  if (s("role")) refs.push({ kind: "role", role: s("role").toLowerCase(), value: s("name"), quality: "semantic" })
+  else if (s("name")) refs.push({ kind: "role", role: "*", value: s("name"), quality: "semantic" })
+  if (s("text")) refs.push({ kind: "text", value: s("text"), quality: "semantic" })
+  if (s("label")) refs.push({ kind: "label", value: s("label"), quality: "semantic" })
+  if (s("test_id")) refs.push({ kind: "testid", value: s("test_id"), quality: "semantic" })
+  if (s("id")) refs.push({ kind: "id", value: s("id").replace(/^#/, ""), quality: "stable" })
+  return refs
+}
+
+export function codeGraphTools(opts: { repo: string; memoryDir?: string; cacheDir?: string }): McpTool[] {
+  let pages: MemoryPage[] | null = null
+  const memory = () => (pages ??= opts.memoryDir ? readPages(opts.memoryDir) : [])
+  const graph = (): Promise<CodeGraph> => buildGraph(opts.repo, { cacheDir: opts.cacheDir })
+  return [
+    {
+      name: "find",
+      description:
+        "Find classes, page objects, methods, properties, and tests by name or words (\"login\", \"SignIn\", \"search results\"), or by the text a locator uses (\"Sign in\"). Returns each with its file:line and signature. It searches names, not file contents: for config keys, ids, or strings, use grep.",
+      inputSchema: { type: "object", properties: { query: { type: "string", description: "Words or a name" } }, required: ["query"] },
+      async run(args) {
+        const found = findSymbols(await graph(), String(args.query || ""))
+        return found.length ? found.join("\n") : `No class, member, or test is named "${args.query}". For text in files (config keys, ids, strings), use grep.`
+      },
+    },
+    {
+      name: "outline",
+      description:
+        "The outline of a file or a class (\"LoginPage\", \"tests/login.spec.ts\"): each member's signature and line and the locators it builds, without bodies. With \"Class.member\" (\"LoginPage.SignInAsync\"), the source of that member only. Use it instead of reading a whole file.",
+      inputSchema: { type: "object", properties: { target: { type: "string", description: "A file path, a class name, or Class.member" } }, required: ["target"] },
+      async run(args) {
+        return outline(await graph(), String(args.target || ""))
+      },
+    },
+    {
+      name: "element",
+      description:
+        "Which page objects already locate an element, however they locate it: give the handoff's locator (\"page.getByRole('button', { name: 'Sign in' })\"), or role and name, text, label, test_id, id. ForgeQE's page memory knows each element by all its locators (id, role and name, text, CSS), so a page object that uses #login-button is found from getByRole('button', { name: 'Login' }). Reuse what it returns instead of writing a new locator.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          locator: { type: "string", description: "A Playwright locator expression or a CSS selector" },
+          role: { type: "string" },
+          name: { type: "string", description: "Accessible name" },
+          text: { type: "string" },
+          label: { type: "string" },
+          test_id: { type: "string" },
+          id: { type: "string" },
+          url: { type: "string", description: "The page it is on, to look it up in page memory" },
+        },
+      },
+      async run(args) {
+        const given = refsFromArgs(args)
+        if (!given.length) return "Give a locator, or role and name, text, label, test_id, or id."
+        const same = sameElement(memory(), given, typeof args.url === "string" ? args.url : undefined)
+        const g = await graph()
+        const matches = membersLocating(g, same.refs)
+        const known = same.element
+          ? `Page memory knows this element on ${same.page?.host}${same.page?.path} as: ${same.refs.map(describeLocator).join("; ")}`
+          : same.ambiguous
+            ? `Page memory has ${same.ambiguous} different elements like this; matched on the locator as given. Give a test_id, an id, or the url of its page to tell them apart.`
+            : "Page memory has no record of this element; matched on the locator as given."
+        if (!matches.length) return `${known}\nNo page object locates it by these locators. One may still locate it another way (a class or a path page memory has not recorded): check the handoff's "in this repository" lines and the outline of that page's page object before you add one.`
+        return [known, "Already in the repository:", ...describeMatches(g, matches, 6).map((l) => `- ${l}`)].join("\n")
+      },
+    },
+    {
+      name: "references",
+      description:
+        "Every test, page object, and helper that calls or reads a member (\"LoginPage.SignInAsync\", or just \"SignInAsync\"), tests first. Use it before you change a shared member, to see what else depends on it.",
+      inputSchema: { type: "object", properties: { symbol: { type: "string", description: "Class.member or member" } }, required: ["symbol"] },
+      async run(args) {
+        const symbol = String(args.symbol || "")
+        return describeReferences(symbol, references(await graph(), symbol))
+      },
+    },
+    {
+      name: "impact",
+      description: "The tests a change to these files reaches, through imports and the classes they name, each with the reason. Use it to choose which tests to run after changing a shared page object or helper.",
+      inputSchema: { type: "object", properties: { files: { type: "array", items: { type: "string" }, description: "Changed files, relative to the repository" } }, required: ["files"] },
+      async run(args) {
+        const files = Array.isArray(args.files) ? args.files.map(String) : []
+        const g = await graph()
+        const lines = testsReaching(g, files).map((t) => `- test ${t.test.cls ? `${t.test.cls.name}.` : ""}${t.test.member.name}  ${t.test.file}:${t.test.member.line}: ${t.why}`)
+        // Imports reach test files the call graph cannot resolve (dynamic fixtures, re-exports).
+        const named = new Set(lines.map((l) => l.split("  ")[1]?.split(":")[0]))
+        for (const t of analyzeImpact(opts.repo, files).tests) if (!named.has(t.file)) lines.push(`- ${t.file}: ${t.reasons.join("; ")}`)
+        return lines.length ? lines.join("\n") : `No test reaches ${files.join(", ")}.`
+      },
+    },
+  ]
+}