plotter/cmake/plot_umbrella_check.cmake

# Keeps include/plot/plot.hpp honest against the plan's Global Constraints:
# every public header under include/plot/ must be included by the umbrella, and
# every <plot/...> the umbrella names must be a file that actually exists.
#
# "Public" is everything the recursive glob finds except the macro-gated
# */detail/ instrumentation, which is documented as not part of the surface and
# deliberately stays out of the umbrella.
#
# One more class is exempt: a header owned by an *optional* target. Such a target
# can be switched off (PLOT_BUILD_TTF_FONT), so its header cannot be named by an
# umbrella every consumer compiles -- that would make plot.hpp unbuildable in a
# configuration where the target does not exist. The list below holds those
# headers by exact path, one per target, because an exemption is a hole in this
# check and a hole should be a list of files rather than a wildcard or a
# directory prefix: a header that is merely inconvenient cannot slip in behind
# one. The run names what it exempted, so the hole is visible in the configure
# log, and the header is still held to standalone compilation like any other
# (tests/CMakeLists.txt generates a self-containment TU for every globbed header
# regardless of which targets are on).
#
# Runs twice: tests/CMakeLists.txt includes it at configure time (so a header
# added without its umbrella line stops the configure rather than the run), and
# ctest runs it again as `plot_umbrella_covers_public_headers` via `cmake -P`.
# Both read the same file so a header the build sees is a header this checks --
# there is no hand-maintained list to fall out of date.
#
# Inputs (set by the including scope, or passed with -D in script mode):
#   PLOT_INCLUDE_DIR  the installed-header root, e.g. <source>/include
#   PLOT_UMBRELLA     the umbrella header, e.g. <PLOT_INCLUDE_DIR>/plot/plot.hpp
#   PLOT_OPTIONAL_HEADERS  optional-target headers, relative to PLOT_INCLUDE_DIR,
#                          that the umbrella deliberately does not name. Defaults
#                          to the list below; a caller may override it, and
#                          emptying it is how a test proves the exemption is what
#                          keeps a header out of the "missing" report.
#   PLOT_EXTRA_PUBLIC_HEADERS  generated public headers, relative to
#                          PLOT_INCLUDE_DIR, that the glob below cannot see
#                          because configure_file() writes them into the build
#                          tree (plot/version.hpp). They are checked like any
#                          other public header: the umbrella has to name them,
#                          and the dangling-include check cannot demand them
#                          under PLOT_INCLUDE_DIR, because their existence is
#                          pinned by the configure that generated them. Defaults
#                          to the project's own list, on the same terms as the
#                          optional list: exact paths, because a hole should be
#                          a list of files.
#   PLOT_GENERATED_INCLUDE_DIR  the build-tree directory those headers live in,
#                          consulted when one of them is not under
#                          PLOT_INCLUDE_DIR. Unset in a tree with no generated
#                          headers.

if(NOT DEFINED PLOT_OPTIONAL_HEADERS)
  set(PLOT_OPTIONAL_HEADERS
    # plot::text::TrueTypeFont, built only by the PLOT_BUILD_TTF_FONT target
    # because it is the one thing in the project that reaches the vendored
    # third_party/stb_truetype.h. That target is off wherever the vendored
    # header is absent, so the umbrella must not require this one.
    "plot/text/true_type_font.hpp")
endif()

if(NOT DEFINED PLOT_EXTRA_PUBLIC_HEADERS)
  set(PLOT_EXTRA_PUBLIC_HEADERS
    # <plot/version.hpp>, generated by configure_file() from
    # include/plot/version.hpp.in into the build tree and installed with the
    # public headers. The glob cannot see it -- it is not under the source
    # include root -- and neither can the dangling-include check, so the
    # default list declares it: the umbrella must still carry its include, and
    # a script run without the caller's -D inputs (the exemption test, a bare
    # -P invocation) judges the umbrella exactly as the build does.
    "plot/version.hpp")
endif()

if(NOT DEFINED PLOT_INCLUDE_DIR)
  message(FATAL_ERROR "plot: PLOT_INCLUDE_DIR is not set")
endif()
if(NOT DEFINED PLOT_UMBRELLA)
  set(PLOT_UMBRELLA "${PLOT_INCLUDE_DIR}/plot/plot.hpp")
endif()

file(GLOB_RECURSE plot_umbrella_headers
  RELATIVE "${PLOT_INCLUDE_DIR}"
  "${PLOT_INCLUDE_DIR}/plot/*.hpp")
if(PLOT_EXTRA_PUBLIC_HEADERS)
  list(APPEND plot_umbrella_headers ${PLOT_EXTRA_PUBLIC_HEADERS})
endif()
list(SORT plot_umbrella_headers)
file(READ "${PLOT_UMBRELLA}" plot_umbrella_text)

# The umbrella is a public header too, but it cannot include itself.
file(RELATIVE_PATH plot_umbrella_relative "${PLOT_INCLUDE_DIR}" "${PLOT_UMBRELLA}")

# Every other public header is named by the umbrella.
set(plot_umbrella_missing "")
set(plot_umbrella_exempt "")
foreach(header IN LISTS plot_umbrella_headers)
  if(header MATCHES "/detail/" OR header STREQUAL plot_umbrella_relative)
    continue()
  endif()
  if(header IN_LIST PLOT_OPTIONAL_HEADERS)
    list(APPEND plot_umbrella_exempt "${header}")
    continue()
  endif()
  string(FIND "${plot_umbrella_text}" "#include <${header}>" plot_umbrella_pos)
  if(plot_umbrella_pos EQUAL -1)
    list(APPEND plot_umbrella_missing "${header}")
  endif()
endforeach()

if(plot_umbrella_missing)
  string(REPLACE ";" "\n  " plot_umbrella_missing_text "${plot_umbrella_missing}")
  message(FATAL_ERROR
    "plot: ${PLOT_UMBRELLA} does not include every public header under "
    "include/plot/ -- missing:\n  ${plot_umbrella_missing_text}\n"
    "Add each as `#include <plot/...>`, or move it under a */detail/ directory "
    "if it is implementation-only and not part of the public surface.")
endif()

# Said out loud rather than kept quiet: this is the one place the coverage rule
# is not applied, so a configure log that does not list it would hide the fact
# that a header is unchecked against the umbrella.
if(plot_umbrella_exempt)
  string(REPLACE ";" "\n  " plot_umbrella_exempt_text "${plot_umbrella_exempt}")
  message(STATUS
    "plot: umbrella check exempts optional-target header(s) the umbrella does "
    "not name by design:\n  ${plot_umbrella_exempt_text}")
endif()

# And every header the umbrella names is a file that exists (a rename or a
# deleted header cannot leave a dangling include behind).
string(REGEX MATCHALL "#include <plot/[^>]+>" plot_umbrella_includes "${plot_umbrella_text}")
set(plot_umbrella_dangling "")
foreach(plot_umbrella_include IN LISTS plot_umbrella_includes)
  string(REGEX REPLACE "#include <([^>]+)>" "\\1" plot_umbrella_header "${plot_umbrella_include}")
  # A declared generated header is exempt from the existence demand: it lives
  # in the build tree by construction -- the configure that produced this
  # umbrella also produced the header -- so a run without
  # PLOT_GENERATED_INCLUDE_DIR set (a bare -P invocation) judges it on the
  # umbrella naming it, which the required-set loop above already checked.
  if(plot_umbrella_header IN_LIST PLOT_EXTRA_PUBLIC_HEADERS)
    continue()
  endif()
  if(NOT EXISTS "${PLOT_INCLUDE_DIR}/${plot_umbrella_header}")
    if(NOT DEFINED PLOT_GENERATED_INCLUDE_DIR OR
       NOT EXISTS "${PLOT_GENERATED_INCLUDE_DIR}/${plot_umbrella_header}")
      list(APPEND plot_umbrella_dangling "${plot_umbrella_header}")
    endif()
  endif()
endforeach()

if(plot_umbrella_dangling)
  string(REPLACE ";" "\n  " plot_umbrella_dangling_text "${plot_umbrella_dangling}")
  message(FATAL_ERROR
    "plot: ${PLOT_UMBRELLA} includes headers that do not exist under "
    "include/plot/:\n  ${plot_umbrella_dangling_text}")
endif()

list(LENGTH plot_umbrella_headers plot_umbrella_header_count)
message(STATUS
  "plot: umbrella covers every public header (${plot_umbrella_header_count} headers globbed)")