clang-tools-extra/clang-tidy/utils/HeaderGuard.cpp

   1 //===--- HeaderGuard.cpp - clang-tidy -------------------------------------===//
   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 "HeaderGuard.h"
  10 #include "clang/Frontend/CompilerInstance.h"
  11 #include "clang/Lex/PPCallbacks.h"
  12 #include "clang/Lex/Preprocessor.h"
  13 #include "clang/Tooling/Tooling.h"
  14 #include "llvm/Support/Path.h"
  15
  16 namespace clang::tidy::utils {
  17
  18 /// canonicalize a path by removing ./ and ../ components.
  19 static std::string cleanPath(StringRef Path) {
  20   SmallString<256> Result = Path;
  21   llvm::sys::path::remove_dots(Result, true);
  22   return std::string(Result.str());
  23 }
  24
  25 namespace {
  26 class HeaderGuardPPCallbacks : public PPCallbacks {
  27 public:
  28   HeaderGuardPPCallbacks(Preprocessor *PP, HeaderGuardCheck *Check)
  29       : PP(PP), Check(Check) {}
  30
  31   void FileChanged(SourceLocation Loc, FileChangeReason Reason,
  32                    SrcMgr::CharacteristicKind FileType,
  33                    FileID PrevFID) override {
  34     // Record all files we enter. We'll need them to diagnose headers without
  35     // guards.
  36     SourceManager &SM = PP->getSourceManager();
  37     if (Reason == EnterFile && FileType == SrcMgr::C_User) {
  38       if (const FileEntry *FE = SM.getFileEntryForID(SM.getFileID(Loc))) {
  39         std::string FileName = cleanPath(FE->getName());
  40         Files[FileName] = FE;
  41       }
  42     }
  43   }
  44
  45   void Ifndef(SourceLocation Loc, const Token &MacroNameTok,
  46               const MacroDefinition &MD) override {
  47     if (MD)
  48       return;
  49
  50     // Record #ifndefs that succeeded. We also need the Location of the Name.
  51     Ifndefs[MacroNameTok.getIdentifierInfo()] =
  52         std::make_pair(Loc, MacroNameTok.getLocation());
  53   }
  54
  55   void MacroDefined(const Token &MacroNameTok,
  56                     const MacroDirective *MD) override {
  57     // Record all defined macros. We store the whole token to get info on the
  58     // name later.
  59     Macros.emplace_back(MacroNameTok, MD->getMacroInfo());
  60   }
  61
  62   void Endif(SourceLocation Loc, SourceLocation IfLoc) override {
  63     // Record all #endif and the corresponding #ifs (including #ifndefs).
  64     EndIfs[IfLoc] = Loc;
  65   }
  66
  67   void EndOfMainFile() override {
  68     // Now that we have all this information from the preprocessor, use it!
  69     SourceManager &SM = PP->getSourceManager();
  70
  71     for (const auto &MacroEntry : Macros) {
  72       const MacroInfo *MI = MacroEntry.second;
  73
  74       // We use clang's header guard detection. This has the advantage of also
  75       // emitting a warning for cases where a pseudo header guard is found but
  76       // preceded by something blocking the header guard optimization.
  77       if (!MI->isUsedForHeaderGuard())
  78         continue;
  79
  80       const FileEntry *FE =
  81           SM.getFileEntryForID(SM.getFileID(MI->getDefinitionLoc()));
  82       std::string FileName = cleanPath(FE->getName());
  83       Files.erase(FileName);
  84
  85       // See if we should check and fix this header guard.
  86       if (!Check->shouldFixHeaderGuard(FileName))
  87         continue;
  88
  89       // Look up Locations for this guard.
  90       SourceLocation Ifndef =
  91           Ifndefs[MacroEntry.first.getIdentifierInfo()].second;
  92       SourceLocation Define = MacroEntry.first.getLocation();
  93       SourceLocation EndIf =
  94           EndIfs[Ifndefs[MacroEntry.first.getIdentifierInfo()].first];
  95
  96       // If the macro Name is not equal to what we can compute, correct it in
  97       // the #ifndef and #define.
  98       StringRef CurHeaderGuard =
  99           MacroEntry.first.getIdentifierInfo()->getName();
 100       std::vector<FixItHint> FixIts;
 101       std::string NewGuard = checkHeaderGuardDefinition(
 102           Ifndef, Define, EndIf, FileName, CurHeaderGuard, FixIts);
 103
 104       // Now look at the #endif. We want a comment with the header guard. Fix it
 105       // at the slightest deviation.
 106       checkEndifComment(FileName, EndIf, NewGuard, FixIts);
 107
 108       // Bundle all fix-its into one warning. The message depends on whether we
 109       // changed the header guard or not.
 110       if (!FixIts.empty()) {
 111         if (CurHeaderGuard != NewGuard) {
 112           Check->diag(Ifndef, "header guard does not follow preferred style")
 113               << FixIts;
 114         } else {
 115           Check->diag(EndIf, "#endif for a header guard should reference the "
 116                              "guard macro in a comment")
 117               << FixIts;
 118         }
 119       }
 120     }
 121
 122     // Emit warnings for headers that are missing guards.
 123     checkGuardlessHeaders();
 124     clearAllState();
 125   }
 126
 127   bool wouldFixEndifComment(StringRef FileName, SourceLocation EndIf,
 128                             StringRef HeaderGuard,
 129                             size_t *EndIfLenPtr = nullptr) {
 130     if (!EndIf.isValid())
 131       return false;
 132     const char *EndIfData = PP->getSourceManager().getCharacterData(EndIf);
 133     size_t EndIfLen = std::strcspn(EndIfData, "\r\n");
 134     if (EndIfLenPtr)
 135       *EndIfLenPtr = EndIfLen;
 136
 137     StringRef EndIfStr(EndIfData, EndIfLen);
 138     EndIfStr = EndIfStr.substr(EndIfStr.find_first_not_of("#endif \t"));
 139
 140     // Give up if there's an escaped newline.
 141     size_t FindEscapedNewline = EndIfStr.find_last_not_of(' ');
 142     if (FindEscapedNewline != StringRef::npos &&
 143         EndIfStr[FindEscapedNewline] == '\\')
 144       return false;
 145
 146     bool IsLineComment =
 147         EndIfStr.consume_front("//") ||
 148         (EndIfStr.consume_front("/*") && EndIfStr.consume_back("*/"));
 149     if (!IsLineComment)
 150       return Check->shouldSuggestEndifComment(FileName);
 151
 152     return EndIfStr.trim() != HeaderGuard;
 153   }
 154
 155   /// Look for header guards that don't match the preferred style. Emit
 156   /// fix-its and return the suggested header guard (or the original if no
 157   /// change was made.
 158   std::string checkHeaderGuardDefinition(SourceLocation Ifndef,
 159                                          SourceLocation Define,
 160                                          SourceLocation EndIf,
 161                                          StringRef FileName,
 162                                          StringRef CurHeaderGuard,
 163                                          std::vector<FixItHint> &FixIts) {
 164     std::string CPPVar = Check->getHeaderGuard(FileName, CurHeaderGuard);
 165     CPPVar = Check->sanitizeHeaderGuard(CPPVar);
 166     std::string CPPVarUnder = CPPVar + '_';
 167
 168     // Allow a trailing underscore if and only if we don't have to change the
 169     // endif comment too.
 170     if (Ifndef.isValid() && CurHeaderGuard != CPPVar &&
 171         (CurHeaderGuard != CPPVarUnder ||
 172          wouldFixEndifComment(FileName, EndIf, CurHeaderGuard))) {
 173       FixIts.push_back(FixItHint::CreateReplacement(
 174           CharSourceRange::getTokenRange(
 175               Ifndef, Ifndef.getLocWithOffset(CurHeaderGuard.size())),
 176           CPPVar));
 177       FixIts.push_back(FixItHint::CreateReplacement(
 178           CharSourceRange::getTokenRange(
 179               Define, Define.getLocWithOffset(CurHeaderGuard.size())),
 180           CPPVar));
 181       return CPPVar;
 182     }
 183     return std::string(CurHeaderGuard);
 184   }
 185
 186   /// Checks the comment after the #endif of a header guard and fixes it
 187   /// if it doesn't match \c HeaderGuard.
 188   void checkEndifComment(StringRef FileName, SourceLocation EndIf,
 189                          StringRef HeaderGuard,
 190                          std::vector<FixItHint> &FixIts) {
 191     size_t EndIfLen;
 192     if (wouldFixEndifComment(FileName, EndIf, HeaderGuard, &EndIfLen)) {
 193       FixIts.push_back(FixItHint::CreateReplacement(
 194           CharSourceRange::getCharRange(EndIf,
 195                                         EndIf.getLocWithOffset(EndIfLen)),
 196           Check->formatEndIf(HeaderGuard)));
 197     }
 198   }
 199
 200   /// Looks for files that were visited but didn't have a header guard.
 201   /// Emits a warning with fixits suggesting adding one.
 202   void checkGuardlessHeaders() {
 203     // Look for header files that didn't have a header guard. Emit a warning and
 204     // fix-its to add the guard.
 205     // TODO: Insert the guard after top comments.
 206     for (const auto &FE : Files) {
 207       StringRef FileName = FE.getKey();
 208       if (!Check->shouldSuggestToAddHeaderGuard(FileName))
 209         continue;
 210
 211       SourceManager &SM = PP->getSourceManager();
 212       FileID FID = SM.translateFile(FE.getValue());
 213       SourceLocation StartLoc = SM.getLocForStartOfFile(FID);
 214       if (StartLoc.isInvalid())
 215         continue;
 216
 217       std::string CPPVar = Check->getHeaderGuard(FileName);
 218       CPPVar = Check->sanitizeHeaderGuard(CPPVar);
 219       std::string CPPVarUnder = CPPVar + '_'; // Allow a trailing underscore.
 220       // If there's a macro with a name that follows the header guard convention
 221       // but was not recognized by the preprocessor as a header guard there must
 222       // be code outside of the guarded area. Emit a plain warning without
 223       // fix-its.
 224       // FIXME: Can we move it into the right spot?
 225       bool SeenMacro = false;
 226       for (const auto &MacroEntry : Macros) {
 227         StringRef Name = MacroEntry.first.getIdentifierInfo()->getName();
 228         SourceLocation DefineLoc = MacroEntry.first.getLocation();
 229         if ((Name == CPPVar || Name == CPPVarUnder) &&
 230             SM.isWrittenInSameFile(StartLoc, DefineLoc)) {
 231           Check->diag(DefineLoc, "code/includes outside of area guarded by "
 232                                  "header guard; consider moving it");
 233           SeenMacro = true;
 234           break;
 235         }
 236       }
 237
 238       if (SeenMacro)
 239         continue;
 240
 241       Check->diag(StartLoc, "header is missing header guard")
 242           << FixItHint::CreateInsertion(
 243                  StartLoc, "#ifndef " + CPPVar + "\n#define " + CPPVar + "\n\n")
 244           << FixItHint::CreateInsertion(
 245                  SM.getLocForEndOfFile(FID),
 246                  Check->shouldSuggestEndifComment(FileName)
 247                      ? "\n#" + Check->formatEndIf(CPPVar) + "\n"
 248                      : "\n#endif\n");
 249     }
 250   }
 251
 252 private:
 253   void clearAllState() {
 254     Macros.clear();
 255     Files.clear();
 256     Ifndefs.clear();
 257     EndIfs.clear();
 258   }
 259
 260   std::vector<std::pair<Token, const MacroInfo *>> Macros;
 261   llvm::StringMap<const FileEntry *> Files;
 262   std::map<const IdentifierInfo *, std::pair<SourceLocation, SourceLocation>>
 263       Ifndefs;
 264   std::map<SourceLocation, SourceLocation> EndIfs;
 265
 266   Preprocessor *PP;
 267   HeaderGuardCheck *Check;
 268 };
 269 } // namespace
 270
 271 void HeaderGuardCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
 272   Options.store(Opts, "HeaderFileExtensions", RawStringHeaderFileExtensions);
 273 }
 274
 275 void HeaderGuardCheck::registerPPCallbacks(const SourceManager &SM,
 276                                            Preprocessor *PP,
 277                                            Preprocessor *ModuleExpanderPP) {
 278   PP->addPPCallbacks(std::make_unique<HeaderGuardPPCallbacks>(PP, this));
 279 }
 280
 281 std::string HeaderGuardCheck::sanitizeHeaderGuard(StringRef Guard) {
 282   // Only reserved identifiers are allowed to start with an '_'.
 283   return Guard.drop_while([](char C) { return C == '_'; }).str();
 284 }
 285
 286 bool HeaderGuardCheck::shouldSuggestEndifComment(StringRef FileName) {
 287   return utils::isFileExtension(FileName, HeaderFileExtensions);
 288 }
 289
 290 bool HeaderGuardCheck::shouldFixHeaderGuard(StringRef FileName) { return true; }
 291
 292 bool HeaderGuardCheck::shouldSuggestToAddHeaderGuard(StringRef FileName) {
 293   return utils::isFileExtension(FileName, HeaderFileExtensions);
 294 }
 295
 296 std::string HeaderGuardCheck::formatEndIf(StringRef HeaderGuard) {
 297   return "endif // " + HeaderGuard.str();
 298 }
 299 } // namespace clang::tidy::utils