Instructions

Implementation Reference

• src/xray/mcp_server.py:222-278 (handler)

  MCP tool handler and registration for 'what_breaks'. Extracts repository root, gets indexer, calls core what_breaks method.
  @mcp.tool def what_breaks(exact_symbol: Dict[str, Any]) -> Dict[str, Any]: """ 💥 STEP 3: See what code might break if you change this symbol. USE THIS AFTER find_symbol() to understand the impact of changing a function/class. IMPROVEMENTS: - Uses structural search (ast-grep) to find ACTUAL code references (ignoring comments/strings). - Returns 2 lines of context around each match. INPUT: - exact_symbol: Pass THE ENTIRE SYMBOL OBJECT from find_symbol(), not just the name! Must be a dictionary with AT LEAST 'name' and 'path' keys. EXAMPLE INPUT: # First, get a symbol from find_symbol(): symbols = find_symbol("/Users/john/project", "authenticate") symbol = symbols[0] # Pick the first result # Then pass THE WHOLE SYMBOL OBJECT: what_breaks(symbol) EXAMPLE OUTPUT: { "references": [ { "file": "/Users/john/project/src/api.py", "line": 23, "text": " # Authenticate the user\n user = authenticate_user(username, password)\n if not user:", "type": "code" } ], "total_count": 1, "strategy": "structural", "note": "Found 1 references using structural search." } """ try: # Extract root path from the symbol's path symbol_path = Path(exact_symbol['path']) root_path = str(symbol_path.parent) # Find a suitable root (go up until we find a git repo or reach root) while root_path != '/': if (Path(root_path) / '.git').exists(): break parent = Path(root_path).parent if parent == Path(root_path): break root_path = str(parent) indexer = get_indexer(root_path) return indexer.what_breaks(exact_symbol) except Exception as e: return {"error": f"Error finding references: {str(e)}"}
• src/xray/core/indexer.py:580-628 (helper)

  Core logic of what_breaks: structural search with ast-grep (prioritized), fallback to text search (ripgrep/python), filters definition file/line, returns references with context.
  def what_breaks(self, exact_symbol: Dict[str, Any], context_lines: int = 2) -> Dict[str, Any]: """ Find what uses a symbol (reverse dependencies) using structural search. Prioritizes ast-grep for code references, falls back to text search. """ symbol_name = exact_symbol['name'] definition_path = str(Path(exact_symbol['path']).resolve()) definition_start = exact_symbol.get('start_line', -1) references = [] strategy = "structural" # Try structural search first (ast-grep) struct_refs = self._ast_grep_search(symbol_name, context_lines) if struct_refs: # Filter out the definition itself for ref in struct_refs: ref_path = str(Path(ref['file']).resolve()) ref_line = ref['line'] # Simple collision check: same file and line is close to definition # (ast-grep definition match might be on definition line) if ref_path == definition_path and abs(ref_line - definition_start) <= 1: continue references.append(ref) else: # Fallback to text search if ast-grep found nothing (or failed) # Note: This might happen if the symbol is not in a supported language file # or if it's only used in comments/strings (which we might want to know about as fallback?) # For now, if structural search returns empty list, we trust it for code. # But we might want to run text search as a backup for non-code files? # Let's stick to the previous behavior's fallback logic: if ast-grep *fails to run*, we use grep. # If ast-grep runs and finds nothing, we return nothing (for code). # BUT, to be safe and "improve" without breaking, let's run text search # if structural search is empty, but mark them as "text matches". # Actually, let's just use the text search if structural returned nothing. strategy = "text" references = self._text_search(symbol_name, context_lines) return { "references": references, "total_count": len(references), "strategy": strategy, "note": f"Found {len(references)} references using {strategy} search." }