[all-commits] [llvm/llvm-project] 41ac24: [include-cleaner] Include-cleaner library structur...

[Sam McCall via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: 41ac245c10fc256c96c45cb874918a3bd5665369
      https://github.com/llvm/llvm-project/commit/41ac245c10fc256c96c45cb874918a3bd5665369
  Author: Sam McCall <sam.mccall at gmail.com>
  Date:   2022-04-29 (Fri, 29 Apr 2022)

  Changed paths:
    M clang-tools-extra/CMakeLists.txt
    A clang-tools-extra/include-cleaner/CMakeLists.txt
    A clang-tools-extra/include-cleaner/README.md
    A clang-tools-extra/include-cleaner/lib/AnalysisInternal.h
    A clang-tools-extra/include-cleaner/lib/CMakeLists.txt
    A clang-tools-extra/include-cleaner/lib/WalkAST.cpp
    A clang-tools-extra/include-cleaner/test/CMakeLists.txt
    A clang-tools-extra/include-cleaner/test/Unit/lit.cfg.py
    A clang-tools-extra/include-cleaner/test/Unit/lit.site.cfg.py.in
    A clang-tools-extra/include-cleaner/test/lit.cfg.py
    A clang-tools-extra/include-cleaner/test/lit.site.cfg.py.in
    A clang-tools-extra/include-cleaner/unittests/CMakeLists.txt
    A clang-tools-extra/include-cleaner/unittests/WalkASTTest.cpp
    M clang/include/clang/Testing/TestAST.h
    M clang/lib/Testing/TestAST.cpp

  Log Message:
  -----------
  [include-cleaner] Include-cleaner library structure, and simplistic AST walking.

Include-cleaner is a library that uses the clang AST and preprocessor to
determine which headers are used. It will be used in clang-tidy, in
clangd, in a standalone tool at least for testing, and in out-of-tree tools.

Roughly, it walks the AST, finds referenced decls, maps these to
used sourcelocations, then to FileEntrys, then matching these against #includes.
However there are many wrinkles: dealing with macros, standard library
symbols, umbrella headers, IWYU directives etc.

It is not built on the C++20 modules concept of usage, to allow:
 - use with existing non-modules codebases
 - a flexible API embeddable in clang-tidy, clangd, and other tools
 - avoiding a chicken-and-egg problem where include cleanups are needed
   before modules can be adopted

This library is based on existing functionality in clangd that provides
an unused-include warning. However it has design changes:
 - it accommodates diagnosing missing includes too (this means tracking
   where references come from, not just the set of targets)
 - it more clearly separates the different mappings
   (symbol => location => header => include) for better testing
 - it handles special cases like standard library symbols and IWYU directives
   more elegantly by adding unified Location and Header types instead of
   side-tables
 - it will support some customization of policy where necessary (e.g.
   for style questions of what constitutes a use, or to allow
   both missing-include and unused-include modes to be conservative)

This patch adds the basic directory structure under clang-tools-extra
and a skeleton version of the AST traversal, which will be the central
piece.
A more end-to-end prototype is in https://reviews.llvm.org/D122677

RFC: https://discourse.llvm.org/t/rfc-lifting-include-cleaner-missing-unused-include-detection-out-of-clangd/61228

Differential Revision: https://reviews.llvm.org/D124164