| 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 "Headers.h" |
| 22 |
#include "ParsedAST.h" |
| 23 |
#include "index/CanonicalIncludes.h" |
| 24 |
#include "clang/Basic/SourceLocation.h" |
| 25 |
#include "clang/Tooling/Inclusions/StandardLibrary.h" |
| 26 |
#include "llvm/ADT/DenseSet.h" |
| 27 |
#include "llvm/ADT/STLFunctionalExtras.h" |
| 28 |
#include "llvm/ADT/StringSet.h" |
| 29 |
#include <optional> |
| 30 |
#include <vector> |
| 31 |
|
| 32 |
namespace clang { |
| 33 |
namespace clangd { |
| 34 |
|
| 35 |
struct ReferencedLocations { |
| 36 |
llvm::DenseSet<SourceLocation> User; |
| 37 |
llvm::DenseSet<tooling::stdlib::Symbol> Stdlib; |
| 38 |
}; |
| 39 |
|
| 40 |
/// Finds locations of all symbols used in the main file. |
| 41 |
/// |
| 42 |
/// - RecursiveASTVisitor finds references to symbols and records their |
| 43 |
/// associated locations. These may be macro expansions, and are not resolved |
| 44 |
/// to their spelling or expansion location. These locations are later used to |
| 45 |
/// determine which headers should be marked as "used" and "directly used". |
| 46 |
/// - If \p Tokens is not nullptr, we also examine all identifier tokens in the |
| 47 |
/// file in case they reference macros macros. |
| 48 |
/// We use this to compute unused headers, so we: |
| 49 |
/// |
| 50 |
/// - cover the whole file in a single traversal for efficiency |
| 51 |
/// - don't attempt to describe where symbols were referenced from in |
| 52 |
/// ambiguous cases (e.g. implicitly used symbols, multiple declarations) |
| 53 |
/// - err on the side of reporting all possible locations |
| 54 |
ReferencedLocations findReferencedLocations(ASTContext &Ctx, Preprocessor &PP, |
| 55 |
const syntax::TokenBuffer *Tokens); |
| 56 |
ReferencedLocations findReferencedLocations(ParsedAST &AST); |
| 57 |
|
| 58 |
struct ReferencedFiles { |
| 59 |
llvm::DenseSet<FileID> User; |
| 60 |
llvm::DenseSet<tooling::stdlib::Header> Stdlib; |
| 61 |
/// Files responsible for the symbols referenced in the main file and defined |
| 62 |
/// in private headers (private headers have IWYU pragma: private, include |
| 63 |
/// "public.h"). We store spelling of the public header (with quotes or angle |
| 64 |
/// brackets) files here to avoid dealing with full filenames and visibility. |
| 65 |
llvm::StringSet<> SpelledUmbrellas; |
| 66 |
}; |
| 67 |
|
| 68 |
/// Retrieves IDs of all files containing SourceLocations from \p Locs. |
| 69 |
/// The output only includes things SourceManager sees as files (not macro IDs). |
| 70 |
/// This can include <built-in>, <scratch space> etc that are not true files. |
| 71 |
/// \p HeaderResponsible returns the public header that should be included given |
| 72 |
/// symbols from a file with the given FileID (example: public headers should be |
| 73 |
/// preferred to non self-contained and private headers). |
| 74 |
/// \p UmbrellaHeader returns the public public header is responsible for |
| 75 |
/// providing symbols from a file with the given FileID (example: MyType.h |
| 76 |
/// should be included instead of MyType_impl.h). |
| 77 |
ReferencedFiles findReferencedFiles( |
| 78 |
const ReferencedLocations &Locs, const SourceManager &SM, |
| 79 |
llvm::function_ref<FileID(FileID)> HeaderResponsible, |
| 80 |
llvm::function_ref<std::optional<StringRef>(FileID)> UmbrellaHeader); |
| 81 |
ReferencedFiles findReferencedFiles(const ReferencedLocations &Locs, |
| 82 |
const IncludeStructure &Includes, |
| 83 |
const CanonicalIncludes &CanonIncludes, |
| 84 |
const SourceManager &SM); |
| 85 |
|
| 86 |
/// Maps FileIDs to the internal IncludeStructure representation (HeaderIDs). |
| 87 |
/// FileIDs that are not true files (<built-in> etc) are dropped. |
| 88 |
llvm::DenseSet<IncludeStructure::HeaderID> |
| 89 |
translateToHeaderIDs(const ReferencedFiles &Files, |
| 90 |
const IncludeStructure &Includes, const SourceManager &SM); |
| 91 |
|
| 92 |
/// Retrieves headers that are referenced from the main file but not used. |
| 93 |
/// In unclear cases, headers are not marked as unused. |
| 94 |
std::vector<const Inclusion *> |
| 95 |
getUnused(ParsedAST &AST, |
| 96 |
const llvm::DenseSet<IncludeStructure::HeaderID> &ReferencedFiles, |
| 97 |
const llvm::StringSet<> &ReferencedPublicHeaders); |
| 98 |
|
| 99 |
std::vector<const Inclusion *> computeUnusedIncludes(ParsedAST &AST); |
| 100 |
// The same as computeUnusedIncludes, but it is an experimental and |
| 101 |
// include-cleaner-lib-based implementation. |
| 102 |
std::vector<const Inclusion *> |
| 103 |
computeUnusedIncludesExperimental(ParsedAST &AST); |
| 104 |
|
| 105 |
std::vector<Diag> issueUnusedIncludesDiagnostics(ParsedAST &AST, |
| 106 |
llvm::StringRef Code); |
| 107 |
|
| 108 |
/// Affects whether standard library includes should be considered for |
| 109 |
/// removal. This is off by default for now due to implementation limitations: |
| 110 |
/// - macros are not tracked |
| 111 |
/// - symbol names without a unique associated header are not tracked |
| 112 |
/// - references to std-namespaced C types are not properly tracked: |
| 113 |
/// instead of std::size_t -> <cstddef> we see ::size_t -> <stddef.h> |
| 114 |
/// FIXME: remove this hack once the implementation is good enough. |
| 115 |
void setIncludeCleanerAnalyzesStdlib(bool B); |
| 116 |
|
| 117 |
} // namespace clangd |
| 118 |
} // namespace clang |
| 119 |
|
| 120 |
#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H |