[lldb][NFCI] Implement language-agnostic diagnostic for non-captured vars in "frame var"

This commit adds the language-agnostic logic to support diagnosing when
a `frame var` command failed because a variable is not visible in the
current frame, but the current frame is a "closure-like"(*) function and
it could have access to the variable, had it been captured by the
closure.

(*) A lambda in C++, a block in C or Objective C, a closure in Swift.

The logic relies on language plugins being able to produce the name of
the function where the current closure is defined, given the mangled
name of the closure. Since this commit does not implement support for
this in any languages, it is NFCI. It contains all the necessary pieces
to upstream the code, once we implement Language support for at least
one upstream language.

Author: felipepiovezan

lldb/include/lldb/Target/Language.h

@@ -403,6 +403,28 @@ class Language : public PluginInterface {
     return nullptr;
   }
 
+  // BEGIN SWIFT
+  // Implement LanguageCPlusPlus::GetParentNameIfClosure and upstream this.
+  // rdar://152321823
+
+  /// If `mangled_name` refers to a function that is a "closure-like" function,
+  /// returns the name of the parent function where the input closure was
+  /// defined. Returns an empty string if there is no such parent, or if the
+  /// query does not make sense for this language.
+  virtual std::string
+  GetParentNameIfClosure(llvm::StringRef mangled_name) const {
+    return "";
+  }
+
+  /// If `sc` corresponds to a "closure-like" function (as defined in
+  /// `GetParentNameIfClosure`), returns the parent Function*
+  /// where a variable named `variable_name` exists.
+  /// Returns nullptr if `sc` is not a closure, or if the query does
+  /// not make sense for this language.
+  Function *FindParentOfClosureWithVariable(llvm::StringRef variable_name,
+                                            const SymbolContext &sc) const;
+  // END SWIFT
+
 protected:
   // Classes that inherit from Language can see and modify these
 

lldb/source/Target/Language.cpp

@@ -14,8 +14,10 @@
 
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Interpreter/OptionValueProperties.h"
+#include "lldb/Symbol/CompileUnit.h"
 #include "lldb/Symbol/SymbolFile.h"
 #include "lldb/Symbol/TypeList.h"
+#include "lldb/Symbol/VariableList.h"
 #include "lldb/Target/Target.h"
 #include "lldb/Utility/Stream.h"
 
@@ -574,3 +576,165 @@ bool SourceLanguage::IsObjC() const {
 bool SourceLanguage::IsCPlusPlus() const {
   return name == llvm::dwarf::DW_LNAME_C_plus_plus;
 }
+
+// BEGIN SWIFT
+// Implement LanguageCPlusPlus::GetParentNameIfClosure and upstream this.
+// rdar://152321823
+
+/// If `sc` represents a "closure"-like function (according to
+/// Language::GetParentNameIfClosure), returns sc.function and all parent
+/// functions up to and including the first non-closure-like function. If `sc`
+/// is not a closure, or if the query does not make sense for `language`,
+/// returns a list containing only sc.function.
+static llvm::SmallVector<Function *>
+GetParentFunctionsWhileClosure(const SymbolContext &sc,
+                               const Language &language) {
+  // The algorithm below terminates on the assumption that
+  // `GetParentNameIfClosure` produces an empty string when composing that
+  // function with itself enough times. For safety, define an upper limit.
+  constexpr auto upper_limit = 8;
+
+  llvm::SmallVector<Function *> parents;
+  Function *root = sc.function;
+  if (root == nullptr)
+    return parents;
+
+  parents.push_back(root);
+  for (int idx = 0; idx < upper_limit; idx++) {
+    ConstString mangled = root->GetMangled().GetMangledName();
+    std::string parent = language.GetParentNameIfClosure(mangled);
+    if (parent.empty())
+      break;
+
+    // Find the enclosing function, if it exists.
+    SymbolContextList sc_list;
+    Module::LookupInfo lookup_info(
+        ConstString(parent), lldb::FunctionNameType::eFunctionNameTypeFull,
+        lldb::eLanguageTypeSwift);
+    sc.module_sp->FindFunctions(lookup_info, CompilerDeclContext(),
+                                ModuleFunctionSearchOptions(), sc_list);
+    if (sc_list.GetSize() != 1 || sc_list[0].function == nullptr)
+      break;
+    parents.push_back(sc_list[0].function);
+    root = sc_list[0].function;
+  }
+  return parents;
+}
+
+/// Scans the line table of `function` looking for the first entry whose line
+/// number is `line_number`. If no such entry is found, returns the entry
+/// closest to but after `line_number`.
+static std::optional<Address> FindAddressForLineNumber(Function &function,
+                                                       uint32_t line_number) {
+  CompileUnit *cu = function.GetCompileUnit();
+  LineTable *line_table = cu ? cu->GetLineTable() : nullptr;
+  if (line_table == nullptr)
+    return std::nullopt;
+
+  // Get the first line entry for this function.
+  AddressRange func_range = function.GetAddressRange();
+  uint32_t first_entry_idx;
+  {
+    LineEntry first_line_entry;
+    line_table->FindLineEntryByAddress(func_range.GetBaseAddress(),
+                                       first_line_entry, &first_entry_idx);
+  }
+
+  LineEntry best_match;
+  for (uint32_t entry_idx = first_entry_idx; entry_idx < line_table->GetSize();
+       entry_idx++) {
+    LineEntry next_line;
+    line_table->GetLineEntryAtIndex(entry_idx, next_line);
+
+    // Stop if this entry is outside the range of `function`.
+    Address base_addr = next_line.range.GetBaseAddress();
+    if (!func_range.ContainsFileAddress(base_addr))
+      break;
+
+    // Stop on an exact match.
+    if (next_line.line == line_number) {
+      best_match = next_line;
+      break;
+    }
+
+    // Otherwise, keep track of the best match so far.
+    if (next_line.line > line_number && next_line.line < best_match.line)
+      best_match = next_line;
+  }
+
+  return best_match.range.GetBaseAddress();
+}
+
+/// Given a list of functions, returns a map: Function -> VariableList
+/// containing local variables of each function.
+static std::map<Function *, VariableList>
+GetFuncToLocalVariablesMap(llvm::ArrayRef<Function *> funcs) {
+  std::map<Function *, VariableList> map;
+  for (Function *function : funcs) {
+    VariableList &variable_list = map[function];
+    Block &block = function->GetBlock(true /*can_create=*/);
+    block.AppendBlockVariables(
+        true /*can_create=*/, true /*get_child_block_variables=*/,
+        true /*stop_if_child_block_is_inlined_function=*/,
+        [](Variable *v) { return true; }, &variable_list);
+  }
+  return map;
+}
+
+/// Returns the first line associated with `function`.
+static uint32_t GetLineNumberForFunction(Function &function) {
+  FileSpec filespec;
+  uint32_t line_num = 0;
+  function.GetStartLineSourceInfo(filespec, line_num);
+  return line_num;
+}
+
+/// Checks if `var` is in scope inside `function` at line `line_number`.
+/// If this check can't be done, a best-effort comparison of:
+///    line_number >= var.line_number
+/// is performed.
+static bool IsVariableInScopeAtLine(uint32_t line_number,
+                                    std::optional<Address> line_addr,
+                                    Variable &var) {
+  auto fallback_line_comp = [&] {
+    return line_number >= var.GetDeclaration().GetLine();
+  };
+
+  if (!line_addr)
+    return fallback_line_comp();
+
+  Block *defining_block = line_addr->CalculateSymbolContextBlock();
+  if (defining_block)
+    return var.IsInScope(*defining_block, *line_addr);
+  return fallback_line_comp();
+}
+
+Function *Language::FindParentOfClosureWithVariable(
+    llvm::StringRef variable_name, const SymbolContext &closure_sc) const {
+  llvm::SmallVector<Function *> function_chain =
+      GetParentFunctionsWhileClosure(closure_sc, *this);
+  if (function_chain.empty())
+    return nullptr;
+
+  std::map<Function *, VariableList> func_to_locals =
+      GetFuncToLocalVariablesMap(function_chain);
+
+  llvm::ArrayRef<Function *> children =
+      llvm::ArrayRef(function_chain).drop_back();
+  llvm::ArrayRef<Function *> parents =
+      llvm::ArrayRef(function_chain).drop_front();
+
+  for (auto [parent, child] : llvm::zip_equal(parents, children)) {
+    VariableList &parent_variables = func_to_locals[parent];
+    uint32_t child_line_number = GetLineNumberForFunction(*child);
+    std::optional<Address> parent_line_addr =
+        FindAddressForLineNumber(*parent, child_line_number);
+
+    for (const VariableSP &var : parent_variables)
+      if (var->GetName() == variable_name &&
+          IsVariableInScopeAtLine(child_line_number, parent_line_addr, *var))
+        return parent;
+  }
+  return nullptr;
+}
+// END SWIFT

lldb/source/Target/StackFrame.cpp

@@ -22,6 +22,7 @@
 #include "lldb/Symbol/VariableList.h"
 #include "lldb/Target/ABI.h"
 #include "lldb/Target/ExecutionContext.h"
+#include "lldb/Target/Language.h"
 #include "lldb/Target/LanguageRuntime.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/RegisterContext.h"
@@ -475,6 +476,31 @@ VariableList *StackFrame::GetVariableList(bool get_file_globals,
   return m_variable_list_sp.get();
 }
 
+// BEGIN SWIFT
+// Implement LanguageCPlusPlus::GetParentNameIfClosure and upstream this.
+// rdar://152321823
+
+/// If `sc` represents a "closure-like" function according to `lang`, and
+/// `missing_var_name` can be found in a parent context, create a diagnostic
+/// explaining that this variable is available but not captured by the closure.
+static std::string
+GetVariableNotCapturedDiagnostic(SymbolContext &sc, SourceLanguage lang,
+                                 ConstString missing_var_name) {
+  Language *lang_plugin = Language::FindPlugin(lang.AsLanguageType());
+  if (lang_plugin == nullptr)
+    return "";
+  Function *parent_func =
+      lang_plugin->FindParentOfClosureWithVariable(missing_var_name, sc);
+  if (!parent_func)
+    return "";
+  return llvm::formatv("A variable named '{0}' existed in function '{1}', but "
+                       "it was not captured in the closure.\nHint: the "
+                       "variable may be available in a parent frame.",
+                       missing_var_name,
+                       parent_func->GetDisplayName().GetStringRef());
+}
+// END SWIFT
+
 VariableListSP
 StackFrame::GetInScopeVariableList(bool get_file_globals,
                                    bool must_have_valid_location) {
@@ -620,6 +646,15 @@ ValueObjectSP StackFrame::GetValueForVariableExpressionPath(
       return valobj_sp;
   }
   if (!valobj_sp) {
+    // BEGIN SWIFT
+    // Implement LanguageCPlusPlus::GetParentNameIfClosure and upstream this.
+    // rdar://152321823
+    if (std::string message = GetVariableNotCapturedDiagnostic(
+            m_sc, GetLanguage(), name_const_string);
+        !message.empty())
+      error = Status::FromErrorString(message.c_str());
+    else
+    // END SWIFT
     error = Status::FromErrorStringWithFormatv(
         "no variable named '{0}' found in this frame", name_const_string);
     return ValueObjectSP();