Debian Codegraph @

llvm-project/clang-tools-extra/clangd/IncludeCleaner.h

raw
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