libcxx/test/tools/clang_tidy_checks/header_exportable_declarations.cpp

   1 //===----------------------------------------------------------------------===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #include "clang-tidy/ClangTidyCheck.h"
  10 #include "clang-tidy/ClangTidyModuleRegistry.h"
  11
  12 #include "llvm/ADT/ArrayRef.h"
  13
  14 #include "header_exportable_declarations.hpp"
  15
  16 #include <iostream>
  17 #include <iterator>
  18 #include <ranges>
  19 #include <algorithm>
  20
  21 template <>
  22 struct clang::tidy::OptionEnumMapping<libcpp::header_exportable_declarations::FileType> {
  23   static llvm::ArrayRef<std::pair<libcpp::header_exportable_declarations::FileType, llvm::StringRef>> getEnumMapping() {
  24     static constexpr std::pair<libcpp::header_exportable_declarations::FileType, llvm::StringRef> Mapping[] = {
  25         {libcpp::header_exportable_declarations::FileType::Header, "Header"},
  26         {libcpp::header_exportable_declarations::FileType::ModulePartition, "ModulePartition"},
  27         {libcpp::header_exportable_declarations::FileType::Module, "Module"},
  28         {libcpp::header_exportable_declarations::FileType::CHeader, "CHeader"},
  29         {libcpp::header_exportable_declarations::FileType::CompatModulePartition, "CompatModulePartition"},
  30         {libcpp::header_exportable_declarations::FileType::CompatModule, "CompatModule"}};
  31     return ArrayRef(Mapping);
  32   }
  33 };
  34
  35 namespace libcpp {
  36 header_exportable_declarations::header_exportable_declarations(
  37     llvm::StringRef name, clang::tidy::ClangTidyContext* context)
  38     : clang::tidy::ClangTidyCheck(name, context),
  39       filename_(Options.get("Filename", "")),
  40       file_type_(Options.get("FileType", header_exportable_declarations::FileType::Unknown)),
  41       extra_header_(Options.get("ExtraHeader", "")) {
  42   switch (file_type_) {
  43   case header_exportable_declarations::FileType::CHeader:
  44   case header_exportable_declarations::FileType::Header:
  45     if (filename_.empty())
  46       llvm::errs() << "No filename is provided.\n";
  47     if (extra_header_.empty())
  48       extra_header_ = "$^"; // Use a never matching regex to silence an error message.
  49     break;
  50   case header_exportable_declarations::FileType::ModulePartition:
  51   case header_exportable_declarations::FileType::CompatModulePartition:
  52     if (filename_.empty())
  53       llvm::errs() << "No filename is provided.\n";
  54     [[fallthrough]];
  55   case header_exportable_declarations::FileType::Module:
  56   case header_exportable_declarations::FileType::CompatModule:
  57     if (!extra_header_.empty())
  58       llvm::errs() << "Extra headers are not allowed for modules.\n";
  59     if (Options.get("SkipDeclarations"))
  60       llvm::errs() << "Modules may not skip declarations.\n";
  61     if (Options.get("ExtraDeclarations"))
  62       llvm::errs() << "Modules may not have extra declarations.\n";
  63     break;
  64   case header_exportable_declarations::FileType::Unknown:
  65     llvm::errs() << "No file type is provided.\n";
  66     break;
  67   }
  68
  69   std::optional<llvm::StringRef> list = Options.get("SkipDeclarations");
  70   if (list)
  71     for (auto decl : std::views::split(*list, ' ')) {
  72       std::string s;
  73       std::ranges::copy(decl, std::back_inserter(s)); // use range based constructor
  74       skip_decls_.emplace(std::move(s));
  75     }
  76   decls_ = skip_decls_;
  77
  78   list = Options.get("ExtraDeclarations");
  79   if (list)
  80     for (auto decl : std::views::split(*list, ' ')) {
  81       auto common = decl | std::views::common;
  82       std::cout << "using ::" << std::string{common.begin(), common.end()} << ";\n";
  83     }
  84 }
  85
  86 header_exportable_declarations::~header_exportable_declarations() {
  87   for (const auto& name : global_decls_)
  88     if (!skip_decls_.contains("std::" + name) && decls_.contains("std::" + name))
  89       std::cout << "using ::" << name << ";\n";
  90 }
  91
  92 void header_exportable_declarations::registerMatchers(clang::ast_matchers::MatchFinder* finder) {
  93   // there are no public names in the Standard starting with an underscore, so
  94   // no need to check the strict rules.
  95   using namespace clang::ast_matchers;
  96
  97   switch (file_type_) {
  98   case FileType::Header:
  99     finder->addMatcher(
 100         namedDecl(
 101             // Looks at the common locations where headers store their data
 102             // * header
 103             // * __header/*.h
 104             // * __fwd/header.h
 105             anyOf(isExpansionInFileMatching(("v1/__" + filename_ + "/").str()),
 106                   isExpansionInFileMatching(extra_header_),
 107                   isExpansionInFileMatching(("v1/__fwd/" + filename_ + "\\.h$").str()),
 108                   isExpansionInFileMatching(("v1/" + filename_ + "$").str())),
 109             unless(hasAncestor(friendDecl())))
 110             .bind("header_exportable_declarations"),
 111         this);
 112     break;
 113   case FileType::CHeader:
 114     // For C headers of the std.compat two matchers are used
 115     // - The cheader matcher; in libc++ these are never split in multiple
 116     //   headers so limiting the declarations to that header works.
 117     // - The header.h; where the declarations of this header are provided
 118     //   is not specified and depends on the libc used. Therefore it is not
 119     //   possible to restrict the location in a portable way.
 120     finder->addMatcher(namedDecl().bind("cheader_exportable_declarations"), this);
 121
 122     [[fallthrough]];
 123   case FileType::ModulePartition:
 124   case FileType::CompatModulePartition:
 125     finder->addMatcher(namedDecl(anyOf(isExpansionInFileMatching(filename_), isExpansionInFileMatching(extra_header_)))
 126                            .bind("header_exportable_declarations"),
 127                        this);
 128     break;
 129   case FileType::Module:
 130   case FileType::CompatModule:
 131     finder->addMatcher(namedDecl().bind("header_exportable_declarations"), this);
 132     break;
 133   case header_exportable_declarations::FileType::Unknown:
 134     llvm::errs() << "This should be unreachable.\n";
 135     break;
 136   }
 137 }
 138
 139 /// Returns the qualified name of a public declaration.
 140 ///
 141 /// There is a small issue with qualified names. Typically the name returned is
 142 /// in the namespace \c std instead of the namespace \c std::__1. Except when a
 143 /// name is declared both in the namespace \c std and in the namespace
 144 /// \c std::__1. In that case the returned value will adjust the name to use
 145 /// the namespace \c std.
 146 ///
 147 /// The reason this happens is due to some parts of libc++ using
 148 /// \code namespace std \endcode instead of
 149 /// \code _LIBCPP_BEGIN_NAMESPACE_STD \endcode
 150 /// Some examples
 151 /// * cstddef has bitwise operators for the type \c byte
 152 /// * exception has equality operators for the type \c exception_ptr
 153 /// * initializer_list has the functions \c begin and \c end
 154 ///
 155 /// When the named declaration uses a reserved name the result is an
 156 /// empty string.
 157 static std::string get_qualified_name(const clang::NamedDecl& decl) {
 158   std::string result = decl.getNameAsString();
 159   // Reject reserved names (ignoring _ in global namespace).
 160   if (result.size() >= 2 && result[0] == '_')
 161     if (result[1] == '_' || std::isupper(result[1]))
 162       if (result != "_Exit")
 163         return "";
 164
 165   for (auto* context = llvm::dyn_cast_or_null<clang::NamespaceDecl>(decl.getDeclContext()); //
 166        context;
 167        context = llvm::dyn_cast_or_null<clang::NamespaceDecl>(context->getDeclContext())) {
 168     std::string ns = std::string(context->getName());
 169
 170     if (ns.starts_with("__")) {
 171       // When the reserved name is an inline namespace the namespace is
 172       // not added to the qualified name instead of removed. Libc++ uses
 173       // several inline namespace with reserved names. For example,
 174       // __1 for every declaration, __cpo in range-based algorithms.
 175       //
 176       // Note other inline namespaces are expanded. This resolves
 177       // ambiguity when two named declarations have the same name but in
 178       // different inline namespaces. These typically are the literal
 179       // conversion operators like operator""s which can be a
 180       // std::string or std::chrono::seconds.
 181       if (!context->isInline())
 182         return "";
 183     } else
 184       result = ns + "::" + result;
 185   }
 186   return result;
 187 }
 188
 189 static bool is_viable_declaration(const clang::NamedDecl* decl) {
 190   // Declarations that are a subobject of a friend Declaration are automatically exported with the record itself.
 191   if (decl->getFriendObjectKind() != clang::Decl::FOK_None)
 192     return false;
 193
 194   // *** Function declarations ***
 195
 196   if (clang::CXXMethodDecl::classof(decl))
 197     return false;
 198
 199   if (clang::CXXDeductionGuideDecl::classof(decl))
 200     return false;
 201
 202   if (clang::FunctionDecl::classof(decl))
 203     return true;
 204
 205   if (clang::CXXConstructorDecl::classof(decl))
 206     return false;
 207
 208   // implicit constructors disallowed
 209   if (const auto* r = llvm::dyn_cast_or_null<clang::RecordDecl>(decl))
 210     return !r->isLambda() && !r->isImplicit();
 211
 212   // *** Unconditionally accepted declarations ***
 213   return llvm::isa<clang::EnumDecl, clang::VarDecl, clang::ConceptDecl, clang::TypedefNameDecl, clang::UsingDecl>(decl);
 214 }
 215
 216 /// Some declarations in the global namespace are exported from the std module.
 217 static bool is_global_name_exported_by_std_module(std::string_view name) {
 218   static const std::set<std::string_view> valid{
 219       "operator delete", "operator delete[]", "operator new", "operator new[]"};
 220   return valid.contains(name);
 221 }
 222
 223 static bool is_valid_declaration_context(
 224     const clang::NamedDecl& decl, std::string_view name, header_exportable_declarations::FileType file_type) {
 225   const clang::DeclContext& context = *decl.getDeclContext();
 226   if (context.isNamespace())
 227     return true;
 228
 229   if (context.isFunctionOrMethod() || context.isRecord())
 230     return false;
 231
 232   if (is_global_name_exported_by_std_module(name))
 233     return true;
 234
 235   return file_type != header_exportable_declarations::FileType::Header;
 236 }
 237
 238 static bool is_module(header_exportable_declarations::FileType file_type) {
 239   switch (file_type) {
 240   case header_exportable_declarations::FileType::Module:
 241   case header_exportable_declarations::FileType::ModulePartition:
 242   case header_exportable_declarations::FileType::CompatModule:
 243   case header_exportable_declarations::FileType::CompatModulePartition:
 244     return true;
 245
 246   case header_exportable_declarations::FileType::Header:
 247   case header_exportable_declarations::FileType::CHeader:
 248     return false;
 249
 250   case header_exportable_declarations::FileType::Unknown:
 251     llvm::errs() << "This should be unreachable.\n";
 252     return false;
 253   }
 254 }
 255
 256 void header_exportable_declarations::check(const clang::ast_matchers::MatchFinder::MatchResult& result) {
 257   if (const auto* decl = result.Nodes.getNodeAs<clang::NamedDecl>("header_exportable_declarations"); decl != nullptr) {
 258     if (!is_viable_declaration(decl))
 259       return;
 260
 261     std::string name = get_qualified_name(*decl);
 262     if (name.empty())
 263       return;
 264
 265     // For modules only take the declarations exported.
 266     if (is_module(file_type_))
 267       if (decl->getModuleOwnershipKind() != clang::Decl::ModuleOwnershipKind::VisibleWhenImported)
 268         return;
 269
 270     if (!is_valid_declaration_context(*decl, name, file_type_))
 271       return;
 272
 273     if (decls_.contains(name)) {
 274       // For modules avoid exporting the same named declaration twice. For
 275       // header files this is common and valid.
 276       if (file_type_ == FileType::ModulePartition || file_type_ == FileType::CompatModulePartition)
 277         // After the warning the script continues.
 278         // The test will fail since modules have duplicated entries and headers not.
 279         llvm::errs() << "Duplicated export of '" << name << "'.\n";
 280       else
 281         return;
 282     }
 283
 284     // For named declarations in std this is valid
 285     //   using std::foo;
 286     // for named declarations it is invalid to use
 287     //   using bar;
 288     // Since fully qualifying named declarations in the std namespace is valid
 289     // using fully qualified names unconditionally.
 290     std::cout << "using ::" << std::string{name} << ";\n";
 291     decls_.insert(name);
 292   } else if (const auto* decl = result.Nodes.getNodeAs<clang::NamedDecl>("cheader_exportable_declarations");
 293              decl != nullptr) {
 294     if (decl->getDeclContext()->isNamespace())
 295       return;
 296
 297     if (!is_viable_declaration(decl))
 298       return;
 299
 300     std::string name = get_qualified_name(*decl);
 301     if (name.empty())
 302       return;
 303
 304     if (global_decls_.contains(name))
 305       return;
 306
 307     global_decls_.insert(name);
 308   }
 309 }
 310
 311 } // namespace libcpp