[cxx-interop] Allow Swift to access non-public C++ members (#79093)

This patch introduces an a C++ class annotation, SWIFT_PRIVATE_FILEID,
which will specify where Swift extensions of that class will be allowed
to access its non-public members, e.g.:

    class SWIFT_PRIVATE_FILEID("MyModule/MyFile.swift") Foo { ... };

The goal of this feature is to help C++ developers incrementally migrate
the implementation of their C++ classes to Swift, without breaking
encapsulation and indiscriminately exposing those classes' private and
protected fields.

As an implementation detail of this feature, this patch introduces an
abstraction for file ID strings, FileIDStr, which represent a parsed pair
of module name/file name.

rdar://137764620

Author: j-hui

include/swift/AST/DiagnosticsClangImporter.def

@@ -212,6 +212,24 @@ NOTE(iterator_method_unavailable, none, "C++ method '%0' that returns an "
 NOTE(iterator_potentially_unsafe, none, "C++ methods that return iterators "
                                         "are potentially unsafe; try using Swift collection APIs instead", ())
 
+ERROR(private_fileid_attr_repeated, none,
+     "multiple SWIFT_PRIVATE_FILEID annotations were found on '%0'",
+     (StringRef))
+
+ ERROR(private_fileid_attr_on_incomplete_type, none,
+     "SWIFT_PRIVATE_FILEID cannot be applied to incomplete type, '%0'",
+     (StringRef))
+ NOTE(private_fileid_attr_here, none,
+     "SWIFT_PRIVATE_FILEID annotation found here", ())
+
+ WARNING(private_fileid_attr_format_invalid, none,
+     "SWIFT_PRIVATE_FILEID annotation on '%0' does not have a valid file ID",
+     (StringRef))
+ REMARK(private_fileid_attr_format_specification, none,
+     "file IDs have the following format: 'ModuleName/FileName.swift'", ())
+ NOTE(private_fileid_attr_format_suggestion, none,
+     "did you mean '%0'?", (StringRef))
+
 ERROR(reference_type_must_have_retain_release_attr, none,
       "reference type '%1' must have %select{'retain:'|'release:'}0 Swift "
       "attribute",

include/swift/AST/SourceFile.h

@@ -825,6 +825,22 @@ class SourceFile final : public FileUnit {
 
   ArrayRef<TypeDecl *> getLocalTypeDecls() const;
 
+  /// Uniquely identifies a source file without exposing its full file path.
+  ///
+  /// A valid file ID should always be of the format "modulename/filename.swift"
+  struct FileIDStr {
+    StringRef moduleName;
+    StringRef fileName;
+
+    /// Parse a string as a SourceFile::FileIDStr.
+    ///
+    /// Returns \c nullopt if \param fileID could not be parsed.
+    static std::optional<FileIDStr> parse(StringRef fileID);
+
+    /// Whether this SourceFile::FileID matches that of the given \param file.
+    bool matches(const SourceFile *file) const;
+  };
+
 private:
 
   /// If not \c None, the underlying vector contains the parsed tokens of this

include/swift/ClangImporter/ClangImporter.h

@@ -738,11 +738,23 @@ llvm::StringRef getCFTypeName(const clang::TypedefNameDecl *decl);
 ValueDecl *getImportedMemberOperator(const DeclBaseName &name,
                                      NominalTypeDecl *selfType,
                                      std::optional<Type> parameterType);
+
 /// Map the access specifier of a Clang record member to a Swift access level.
 ///
 /// This mapping is conservative: the resulting Swift access should be at _most_
 /// as permissive as the input C++ access.
 AccessLevel convertClangAccess(clang::AccessSpecifier access);
+
+/// Read file IDs from 'private_fileid' Swift attributes on a Clang decl.
+///
+/// May return >1 fileID when a decl is annotated more than once, which should
+/// be treated as an error and appropriately diagnosed (using the included
+/// SourceLocation).
+///
+/// The returned fileIDs may not be of a valid format (e.g., missing a '/'),
+/// and should be parsed using swift::SourceFile::FileIDStr::parse().
+SmallVector<std::pair<StringRef, clang::SourceLocation>, 1>
+getPrivateFileIDAttrs(const clang::Decl *decl);
 } // namespace importer
 
 struct ClangInvocationFileMapping {

lib/AST/DeclContext.cpp

@@ -31,6 +31,7 @@
 #include "swift/Basic/Assertions.h"
 #include "swift/Basic/SourceManager.h"
 #include "swift/Basic/Statistic.h"
+#include "swift/ClangImporter/ClangImporter.h"
 #include "clang/AST/ASTContext.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/Statistic.h"
@@ -1480,16 +1481,37 @@ bool AccessScope::allowsPrivateAccess(const DeclContext *useDC, const DeclContex
       return usePkg->isSamePackageAs(srcPkg);
     }
   }
-  // Do not allow access if the sourceDC is in a different file
-  auto useSF = useDC->getOutermostParentSourceFile();
-  if (useSF != sourceDC->getOutermostParentSourceFile())
-    return false;
 
   // Do not allow access if the sourceDC does not represent a type.
   auto sourceNTD = sourceDC->getSelfNominalTypeDecl();
   if (!sourceNTD)
     return false;
 
+  // Do not allow access if the sourceDC is in a different file
+  auto *useSF = useDC->getOutermostParentSourceFile();
+  if (useSF != sourceDC->getOutermostParentSourceFile()) {
+    // This might be a C++ declaration with a SWIFT_PRIVATE_FILEID
+    // attribute, which asks us to treat it as if it were defined in the file
+    // with the specified FileID.
+
+    auto clangDecl = sourceNTD->getDecl()->getClangDecl();
+    if (!clangDecl)
+      return false;
+
+    // Diagnostics should enforce that there is at most SWIFT_PRIVATE_FILEID,
+    // but this handles the case where there is more than anyway (whether that
+    // is a feature or a bug). Allow access check to proceed if useSF is blessed
+    // by any of the SWIFT_PRIVATE_FILEID annotations (i.e., disallow private
+    // access if none of them bless useSF).
+    if (!llvm::any_of(
+            importer::getPrivateFileIDAttrs(clangDecl), [&](auto &blessed) {
+              auto blessedFileID = SourceFile::FileIDStr::parse(blessed.first);
+              return blessedFileID && blessedFileID->matches(useSF);
+            })) {
+      return false;
+    }
+  }
+
   // Compare the private scopes and iterate over the parent types.
   sourceDC = getPrivateDeclContext(sourceDC, useSF);
   while (!useDC->isModuleContext()) {

lib/AST/Module.cpp

@@ -3783,6 +3783,29 @@ ArrayRef<TypeDecl *> SourceFile::getLocalTypeDecls() const {
                            LocalTypeDeclsRequest{mutableThis}, {});
 }
 
+std::optional<SourceFile::FileIDStr>
+SourceFile::FileIDStr::parse(StringRef fileID) {
+  auto names = fileID.split('/');
+  auto moduleName = names.first;
+  auto fileName = names.second;
+
+  if (moduleName.empty() || fileName.empty() || !fileName.ends_with(".swift") ||
+      fileName.contains('/'))
+    return {};
+
+  return {SourceFile::FileIDStr{/*.moduleName=*/moduleName,
+                                /*.fileName=*/fileName}};
+}
+
+bool SourceFile::FileIDStr::matches(const SourceFile *file) const {
+  // Never match with SourceFiles that do not correpond to a file on disk
+  if (file->getFilename().empty())
+    return false;
+
+  return moduleName == file->getParentModule()->getNameStr() &&
+         fileName == llvm::sys::path::filename(file->getFilename());
+}
+
 namespace {
 class LocalTypeDeclCollector : public ASTWalker {
   SmallVectorImpl<TypeDecl *> &results;

lib/ClangImporter/ClangImporter.cpp

@@ -8450,3 +8450,21 @@ AccessLevel importer::convertClangAccess(clang::AccessSpecifier access) {
     return AccessLevel::Public;
   }
 }
+
+SmallVector<std::pair<StringRef, clang::SourceLocation>, 1>
+importer::getPrivateFileIDAttrs(const clang::Decl *decl) {
+  llvm::SmallVector<std::pair<StringRef, clang::SourceLocation>, 1> files;
+
+  constexpr auto prefix = StringRef("private_fileid:");
+
+  if (decl->hasAttrs()) {
+    for (const auto *attr : decl->getAttrs()) {
+      const auto *swiftAttr = dyn_cast<clang::SwiftAttrAttr>(attr);
+      if (swiftAttr && swiftAttr->getAttribute().starts_with(prefix))
+        files.push_back({swiftAttr->getAttribute().drop_front(prefix.size()),
+                         attr->getLocation()});
+    }
+  }
+
+  return files;
+}

lib/ClangImporter/ImportDecl.cpp

@@ -2602,6 +2602,44 @@ namespace {
       return result;
     }
 
+    void validatePrivateFileIDAttributes(const clang::CXXRecordDecl *decl) {
+      auto anns = importer::getPrivateFileIDAttrs(decl);
+
+      if (anns.size() > 1) {
+        Impl.diagnose(HeaderLoc(decl->getLocation()),
+                      diag::private_fileid_attr_repeated, decl->getName());
+        for (auto ann : anns)
+          Impl.diagnose(HeaderLoc(ann.second), diag::private_fileid_attr_here);
+      } else if (anns.size() == 1) {
+        auto ann = anns[0];
+        if (!SourceFile::FileIDStr::parse(ann.first)) {
+          Impl.diagnose(HeaderLoc(ann.second),
+                        diag::private_fileid_attr_format_invalid,
+                        decl->getName());
+          Impl.diagnose({}, diag::private_fileid_attr_format_specification);
+
+          if (ann.first.count('/') > 1) {
+            // Try to construct a suggestion from predictable mistakes.
+            SmallString<32> suggestion;
+
+            // Mistake #1: confusing fileID for filePath => writing too many
+            // '/'s
+            suggestion.append(ann.first.split('/').first);
+            suggestion.push_back('/');
+            suggestion.append(ann.first.rsplit('/').second);
+
+            // Mistake #2: forgetting to use filename with .swift extension
+            if (!suggestion.ends_with(".swift"))
+              suggestion.append(".swift");
+
+            if (SourceFile::FileIDStr::parse(suggestion))
+              Impl.diagnose({}, diag::private_fileid_attr_format_suggestion,
+                            suggestion);
+          }
+        }
+      }
+    }
+
     void validateForeignReferenceType(const clang::CXXRecordDecl *decl,
                                       ClassDecl *classDecl) {
 
@@ -2804,6 +2842,16 @@ namespace {
             Diagnostic(diag::incomplete_record, Impl.SwiftContext.AllocateCopy(
                                                     decl->getNameAsString())),
             decl->getLocation());
+
+        auto attrs = importer::getPrivateFileIDAttrs(decl);
+        if (!attrs.empty()) {
+          Impl.diagnose(HeaderLoc(decl->getLocation()),
+                        diag::private_fileid_attr_on_incomplete_type,
+                        decl->getName());
+          for (auto attr : attrs)
+            Impl.diagnose(HeaderLoc(attr.second),
+                          diag::private_fileid_attr_here);
+        }
       }
 
       decl = decl->getDefinition();
@@ -2958,6 +3006,8 @@ namespace {
                              "are not yet available in Swift");
       }
 
+      validatePrivateFileIDAttributes(decl);
+
       if (auto classDecl = dyn_cast<ClassDecl>(result)) {
         validateForeignReferenceType(decl, classDecl);
 

lib/ClangImporter/SwiftBridging/swift/bridging

@@ -191,6 +191,42 @@
 #define SWIFT_RETURNS_UNRETAINED                                               \
   __attribute__((swift_attr("returns_unretained")))
 
+/// Specifies that the non-public members of a C++ class, struct, or union can
+/// be accessed from extensions of that type, in the given file ID.
+///
+/// In other words, Swift's access controls will behave as if the non-public
+/// members of the annotated C++ class were privated declared in the specified
+/// Swift source file, rather than in a C++ header file/Clang module.
+///
+/// For example, we can annotate a C++ class definition like this:
+///
+/// ```c++
+/// class SWIFT_PRIVATE_FILEID("MySwiftModule/MySwiftFile.swift")
+/// MyCxxClass {
+/// private:
+///   void privateMethod();
+///   int  privateStorage;
+/// };
+/// ```
+///
+/// Then, Swift extensions of `MyCxxClass` in `MySwiftModule/MySwiftFile.swift`
+/// are allowed to access `privateMethod()` and `privateStorage`:
+///
+/// ```swift
+/// //-- MySwiftModule/SwiftFile.swift
+/// extension MyCxxClass {
+///     func ext() {
+///         privateMethod()
+///         print("\(privateStorage)")
+///     }
+/// }
+/// ```
+///
+/// Non-public access is still forbidden outside of extensions and outside of
+/// the designated file ID.
+#define SWIFT_PRIVATE_FILEID(_fileID) \
+  __attribute__((swift_attr("private_fileid:" _fileID)))
+
 #else  // #if _CXX_INTEROP_HAS_ATTRIBUTE(swift_attr)
 
 // Empty defines for compilers that don't support `attribute(swift_attr)`.
@@ -210,6 +246,7 @@
 #define SWIFT_ESCAPABLE_IF(...)
 #define SWIFT_RETURNS_RETAINED
 #define SWIFT_RETURNS_UNRETAINED
+#define SWIFT_PRIVATE_FILEID(_fileID)
 
 #endif // #if _CXX_INTEROP_HAS_ATTRIBUTE(swift_attr)
 

test/Interop/Cxx/class/access/Inputs/module.modulemap

@@ -0,0 +1,4 @@
+module NonPublic {
+    requires cplusplus
+    header "non-public.h"
+}

test/Interop/Cxx/class/access/Inputs/non-public.h

@@ -0,0 +1,89 @@
+#ifndef NON_PUBLIC_H
+#define NON_PUBLIC_H
+
+// Override this to test structs
+#ifndef TEST_CLASS
+#define TEST_CLASS class
+#endif
+
+// Override this to test protected
+#ifndef TEST_PRIVATE
+#define TEST_PRIVATE private
+#endif
+
+/// A C++ class with various kinds of public and non-public fields, all of which
+/// should be imported. Non-public fields should only be accessible inside
+/// MyClass extensions in blessed.swift.
+TEST_CLASS
+__attribute__((__swift_attr__("private_fileid:main/blessed.swift"))) MyClass {
+
+public:
+  void publMethod(void) const {}
+  void publMutatingMethod(void) {}
+  int publVar;
+  static void publStaticFunc(void);
+  static int publStaticVar;
+
+  typedef int publTypedef;
+  struct publStruct {};
+
+  enum publEnum { publEnumValue1 };
+  enum class publEnumClass { publEnumClassValue1 };
+  enum { publEnumAnonValue1 };
+  enum publEnumClosed {
+    publEnumClosedValue1
+  } __attribute__((enum_extensibility(closed)));
+  enum publEnumOpen {
+    publEnumOpenValue1
+  } __attribute__((enum_extensibility(open)));
+  enum publEnumFlag {} __attribute__((flag_enum));
+
+TEST_PRIVATE:
+  void privMethod(void) const {}
+  void privMutatingMethod(void) {}
+  int privVar;
+  static void privStaticFunc(void);
+  static int privStaticVar;
+
+  typedef int privTypedef;
+  struct privStruct {};
+
+  enum privEnum { privEnumValue1 };
+  enum class privEnumClass { privEnumClassValue1 };
+  enum { privEnumAnonValue1 };
+  enum privEnumClosed {
+    privEnumClosedValue1
+  } __attribute__((enum_extensibility(closed)));
+  enum privEnumOpen {
+    privEnumOpenValue1
+  } __attribute__((enum_extensibility(open)));
+  enum privEnumFlag {} __attribute__((flag_enum));
+};
+
+/// A C++ templated class, whose non-public fields should be accessible in
+/// extensions of the (instantiated) class in blessed.swift.
+template <typename T>
+TEST_CLASS __attribute__((
+    __swift_attr__("private_fileid:main/blessed.swift"))) MyClassTemplate {
+public:
+  T publMethodT(T t) const { return t; }
+  T publVarT;
+  typedef T publTypedefT;
+
+  void publMethod(void) const {}
+  int publVar;
+  typedef int publTypedef;
+TEST_PRIVATE:
+  T privMethodT(T t) const { return t; }
+  T privVarT;
+  typedef T privTypedefT;
+
+  void privMethod(void) const {}
+  int privVar;
+  typedef int privTypedef;
+};
+
+typedef MyClassTemplate<float> MyFloatyClass;
+typedef MyClassTemplate<MyClass> MyClassyClass;
+
+#endif /* NON_PUBLIC_H */