Migrate IPR non-mutating headers to C++20 modules (includes and supersedes #322) (#323)

* Migrate IPR interface to C++20 module cxx.ipr

Replace <ipr/interface> and its transitive header dependencies with a
named C++20 module expressed as three partitions:

  cxx.ipr:vocabulary  - structural templates, enums, locations
  cxx.ipr:syntax      - tokens, attributes, declarators, constraints
  cxx.ipr             - semantic node hierarchy, Visitor, Lexicon

New files:
  src/cxx-ipr-vocabulary.ixx  - :vocabulary partition
  src/cxx-ipr-syntax.ixx      - :syntax partition
  src/cxx-ipr.ixx             - primary module interface
  src/cxx-ipr.cxx             - module implementation unit
  include/ipr/std-preamble    - TEMPORARY standard header preamble
  include/ipr/utility-impl    - impl-only utility types (rb_tree, etc.)

Removed headers: interface, synopsis, ancillary, location, attribute,
cxx-form, utility, and src/interface.cxx.

Tested on MSVC 19.50, GCC 15.2, Clang 21.1 (libstdc++ and libc++).

* Restore comments removed during module migration

Preserve the original form and content of comments that were
inadvertently dropped or reformatted when migrating headers to
C++20 module partitions:

- cxx-ipr-syntax.ixx: restore '// -- ' prefix on the design
  rationale comment block (matching the original <ipr/cxx-form>)
- cxx-ipr-vocabulary.ixx: restore box-style section dividers,
  add missing directive forward declarations section, add
  'distinguished node' section, restore multi-line inline
  comments on Phantom, Demotion, and Label
- cxx-ipr.cxx: add Visitor sub-hierarchy forwarding rationale
  and section headers (Types, Expressions, Directives,
  Statements, Declarations) from the original traversal.cxx
- utility-impl: restore rb_tree algorithm comments (rotation
  operations, chain/container insert documentation, string
  pool description)

* Migrate <ipr/traversal> and <ipr/io> to C++20 modules

Introduce two new named modules:
  - cxx.ipr.traversal: structural comparison, visitor utilities
  - cxx.ipr.io: the XPR pretty-printer

Move physically_same and as<> from the traversal module to
cxx.ipr's :vocabulary partition, where they belong: both are
vocabulary-level predicates depending only on Node&.

New files:
  - src/cxx-ipr-traversal.ixx (module interface)
  - src/cxx-ipr-traversal.cxx (module implementation unit)
  - src/cxx-ipr-io.ixx (module interface)
  - src/cxx-ipr-io.cxx (module implementation unit)

Deleted files:
  - include/ipr/traversal (replaced by cxx.ipr.traversal)
  - include/ipr/io (replaced by cxx.ipr.io)
  - src/traversal.cxx (renamed to cxx-ipr-traversal.cxx)
  - src/io.cxx (renamed to cxx-ipr-io.cxx)

Key changes:
  - Export physically_same and as<> from cxx.ipr:vocabulary.
    This eliminates the as<> duplicate that was in cxx-ipr.cxx,
    and removes the need for <ipr/impl> to import cxx.ipr.traversal.
  - Define util::std_insertable solely in cxx.ipr.io (removed
    from <ipr/utility-impl> where it was the only consumer).
  - Both module interfaces import only cxx.ipr; implementation-
    only dependencies (cxx.ipr.traversal in cxx-ipr-io.cxx,
    <typeinfo> in cxx-ipr-traversal.cxx) are in the .cxx files.
  - Update CMakeLists.txt: new module file sets, renamed sources,
    removed deleted headers from PRIVATE list.
  - Update consumer TUs: only files that use traversal-specific
    symbols (Constant_visitor, util::view, etc.) import
    cxx.ipr.traversal; others get physically_same from cxx.ipr.

Tested on:
  - MSVC 19.50 (VS 18 Preview): pass
  - GCC 15.2: pass
  - Clang 21.1 (libstdc++): pass
  - Clang 21.1 (libc++): pass

Author: gdr-at-ms

CMakeLists.txt

@@ -26,12 +26,22 @@ else()
 endif()
 
 add_library(${PROJECT_NAME}
-   src/interface.cxx
    src/impl.cxx
-   src/io.cxx
-   src/traversal.cxx
+   src/cxx-ipr-io.cxx
+   src/cxx-ipr-traversal.cxx
    src/input.cxx
    src/utility.cxx
+   src/cxx-ipr.cxx
+)
+
+target_sources(${PROJECT_NAME}
+   PUBLIC
+      FILE_SET CXX_MODULES FILES
+         src/cxx-ipr-vocabulary.ixx
+         src/cxx-ipr-syntax.ixx
+         src/cxx-ipr.ixx
+         src/cxx-ipr-traversal.ixx
+         src/cxx-ipr-io.ixx
 )
 
 target_include_directories(${PROJECT_NAME}
@@ -41,18 +51,10 @@ target_include_directories(${PROJECT_NAME}
 
 target_sources(${PROJECT_NAME}
     PRIVATE
-        ${PROJECT_SOURCE_DIR}/include/ipr/ancillary
-        ${PROJECT_SOURCE_DIR}/include/ipr/attribute
-        ${PROJECT_SOURCE_DIR}/include/ipr/cxx-form
         ${PROJECT_SOURCE_DIR}/include/ipr/impl
-        ${PROJECT_SOURCE_DIR}/include/ipr/interface
-        ${PROJECT_SOURCE_DIR}/include/ipr/io
         ${PROJECT_SOURCE_DIR}/include/ipr/lexer
-        ${PROJECT_SOURCE_DIR}/include/ipr/location
         ${PROJECT_SOURCE_DIR}/include/ipr/node-category
-        ${PROJECT_SOURCE_DIR}/include/ipr/synopsis
-        ${PROJECT_SOURCE_DIR}/include/ipr/traversal
-        ${PROJECT_SOURCE_DIR}/include/ipr/utility
+        ${PROJECT_SOURCE_DIR}/include/ipr/utility-impl
         ${PROJECT_SOURCE_DIR}/include/ipr/input
         ${PROJECT_SOURCE_DIR}/3rdparty/doctest/doctest.h
 )
@@ -99,6 +101,7 @@ install(
    TARGETS ipr
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
+   FILE_SET CXX_MODULES DESTINATION lib/cmake/ipr
 )
 install(
    DIRECTORY include/ipr