clang-tools-extra/clangd/IncludeCleaner.h

   1 //===--- IncludeCleaner.h - Unused/Missing Headers Analysis -----*- C++ -*-===//
   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 /// \file
  10 /// Include Cleaner is clangd functionality for providing diagnostics for misuse
  11 /// of transitive headers and unused includes. It is inspired by
  12 /// Include-What-You-Use tool (https://include-what-you-use.org/). Our goal is
  13 /// to provide useful warnings in most popular scenarios but not 1:1 exact
  14 /// feature compatibility.
  15 ///
  16 //===----------------------------------------------------------------------===//
  17
  18 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H
  19 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H
  20
  21 #include "Diagnostics.h"
  22 #include "Headers.h"
  23 #include "ParsedAST.h"
  24 #include "clang-include-cleaner/Types.h"
  25 #include "clang/Basic/SourceManager.h"
  26 #include "clang/Tooling/Syntax/Tokens.h"
  27 #include "llvm/ADT/ArrayRef.h"
  28 #include "llvm/ADT/StringRef.h"
  29 #include <functional>
  30 #include <optional>
  31 #include <string>
  32 #include <tuple>
  33 #include <vector>
  34
  35 namespace clang {
  36 namespace clangd {
  37
  38 // Data needed for missing include diagnostics.
  39 struct MissingIncludeDiagInfo {
  40   include_cleaner::Symbol Symbol;
  41   syntax::FileRange SymRefRange;
  42   std::vector<include_cleaner::Header> Providers;
  43
  44   bool operator==(const MissingIncludeDiagInfo &Other) const {
  45     return std::tie(SymRefRange, Providers, Symbol) ==
  46            std::tie(Other.SymRefRange, Other.Providers, Other.Symbol);
  47   }
  48 };
  49
  50 struct IncludeCleanerFindings {
  51   std::vector<const Inclusion *> UnusedIncludes;
  52   std::vector<MissingIncludeDiagInfo> MissingIncludes;
  53 };
  54
  55 IncludeCleanerFindings computeIncludeCleanerFindings(ParsedAST &AST);
  56
  57 using HeaderFilter = llvm::ArrayRef<std::function<bool(llvm::StringRef)>>;
  58 std::vector<Diag>
  59 issueIncludeCleanerDiagnostics(ParsedAST &AST, llvm::StringRef Code,
  60                                const IncludeCleanerFindings &Findings,
  61                                HeaderFilter IgnoreHeader = {});
  62
  63 /// Affects whether standard library includes should be considered for
  64 /// removal. This is off by default for now due to implementation limitations:
  65 /// - macros are not tracked
  66 /// - symbol names without a unique associated header are not tracked
  67 /// - references to std-namespaced C types are not properly tracked:
  68 ///   instead of std::size_t -> <cstddef> we see ::size_t -> <stddef.h>
  69 /// FIXME: remove this hack once the implementation is good enough.
  70 void setIncludeCleanerAnalyzesStdlib(bool B);
  71
  72 /// Converts the clangd include representation to include-cleaner
  73 /// include representation.
  74 include_cleaner::Includes
  75 convertIncludes(const SourceManager &SM,
  76                 const llvm::ArrayRef<Inclusion> Includes);
  77
  78 std::vector<include_cleaner::SymbolReference>
  79 collectMacroReferences(ParsedAST &AST);
  80
  81 /// Find the first provider in the list that is matched by the includes.
  82 std::optional<include_cleaner::Header>
  83 firstMatchedProvider(const include_cleaner::Includes &Includes,
  84                      llvm::ArrayRef<include_cleaner::Header> Providers);
  85 } // namespace clangd
  86 } // namespace clang
  87
  88 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H