refactor: source-level audit — fix doc inaccuracies, modernize build, unify style

LessUp · LessUp · commit bb612b561fa4 · 2026-07-24T17:25:39.000+08:00
Documentation accuracy:
- README: CMake 3.22+ → 3.20+ (matches CMakeLists.txt)
- CLAUDE.md, docs index: "C++17 minimum" → C++20 required
- benchmarks/README: fix script path to tools/performance/
- SECURITY.md: 1.0.x → 1.3.x

Build system:
- Remove redundant BENCHMARK_MAIN() from all 10 bench files
  (CMake template already links benchmark::benchmark_main)
- Replace directory-level include_directories() with hpc_headers
  INTERFACE library and target-based linkage throughout
- Fix pre-push hook: --cached (always empty) → @{push}..HEAD

Style:
- Unify #include "hpc/..." → &lt;hpc/...&gt; (3 files)
- Translate all Chinese source comments to English

Content trimming:
- README doc entry points: 9 links → 4
- CLAUDE.md "avoid reintroducing": 11 items → 4
diff --git a/.githooks/pre-push b/.githooks/pre-push
@@ -6,8 +6,11 @@ set -euo pipefail
 repo_root="$(git rev-parse --show-toplevel)"
 cd "$repo_root"
 
+# Compare against the upstream tracking branch (or origin/master as fallback)
+upstream=$(git rev-parse --abbrev-ref @{push} 2>/dev/null || echo "origin/master")
+
 # Only run format check if there are C++ files changed
-if git diff --name-only --cached | grep -qE '\.(cpp|hpp|h|cxx|cc)$'; then
+if git diff --name-only "$upstream"..HEAD | grep -qE '\.(cpp|hpp|h|cxx|cc)$'; then
     echo "Checking C++ formatting..."
     ./scripts/format.sh --check || {
         echo "❌ Format check failed. Run ./scripts/format.sh to fix."
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -4,7 +4,7 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.0.x   | :white_check_mark: |
+| 1.3.x   | :white_check_mark: |
 
 ## Reporting a Vulnerability
 
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,7 +6,7 @@ This repository is in **closure and hardening mode** (archive-ready for low-freq
 
 ## C++ Standards and Style
 
-- **Target**: C++17 minimum, C++20 where beneficial
+- **Target**: C++20 (required, `CMAKE_CXX_STANDARD_REQUIRED ON`)
 - **Style**: enforced via `.clang-format` (Google style, 100 chars)
 - **Memory safety**: prefer RAII, smart pointers, avoid raw `new/delete`
 - **Performance**: always measure with benchmarks before claiming improvement
@@ -73,14 +73,7 @@ The `.vscode/` directory is **gitignored**. Use `.clangd`, `.editorconfig`, and
 
 ## Things to avoid reintroducing
 
-- HonKit / GitBook-era configuration
-- `.kiro/`-style legacy spec structures
-- duplicate changelog surfaces with no maintenance value
 - non-blocking CI steps that hide real failures
-- generic AI instructions that do not reflect this repository
 - per-example shim headers that only re-export a canonical `include/hpc/` header
-- CMake anti-pattern directories with no runnable target
 - wrapper scripts that duplicate `cmake --preset` commands
-- split root-level design md files (consolidated into `docs/META.md`)
-- English-only documentation surfaces (all bilingual surfaces now have zh parity)
-- unused custom Vue components in the docs theme
+- English-only documentation surfaces (all bilingual surfaces must have zh parity)
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -14,8 +14,9 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 # Export compile commands for IDE support
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
-# Add core include directory for all targets
-include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)
+# Canonical header-only library (include/hpc/)
+add_library(hpc_headers INTERFACE)
+target_include_directories(hpc_headers INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/include)
 
 # Include custom CMake modules
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
diff --git a/README.md b/README.md
@@ -78,20 +78,14 @@ cmake --preset=ubsan && cmake --build build/ubsan && ctest --preset=ubsan
 ## Documentation entry points
 
 - **Docs site:** <https://lessup.github.io/cpp-high-performance-guide/>
-- **Academy:** [`docs/en/academy/index.md`](docs/en/academy/index.md)
-- **Architecture:** [`docs/en/architecture/index.md`](docs/en/architecture/index.md)
 - **Playbook:** [`docs/en/playbook/index.md`](docs/en/playbook/index.md)
 - **Reference:** [`docs/en/reference/index.md`](docs/en/reference/index.md)
-- **Research:** [`docs/en/research/index.md`](docs/en/research/index.md)
-- **Quick start inside the playbook:** [`docs/en/getting-started/quickstart.md`](docs/en/getting-started/quickstart.md)
-- **Profiling guide:** [`docs/en/guides/profiling-guide.md`](docs/en/guides/profiling-guide.md)
-- **Validation & sanitizers:** [`docs/en/guides/validation.md`](docs/en/guides/validation.md)
 - **Chinese entry:** `README.zh-CN.md` and `docs/zh/`
 
 ## Tech stack
 
 - **Language:** C++20
-- **Build:** CMake 3.22+, Ninja
+- **Build:** CMake 3.20+, Ninja
 - **Testing:** Google Test, RapidCheck
 - **Benchmarking:** Google Benchmark
 - **Docs:** VitePress + GitHub Pages
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -78,21 +78,14 @@ cmake --preset=ubsan && cmake --build build/ubsan && ctest --preset=ubsan
 ## 文档入口
 
 - **文档站：** <https://lessup.github.io/cpp-high-performance-guide/>
-- **学院：** [`docs/zh/academy/index.md`](docs/zh/academy/index.md)
-- **架构：** [`docs/zh/architecture/index.md`](docs/zh/architecture/index.md)
 - **实践手册：** [`docs/zh/playbook/index.md`](docs/zh/playbook/index.md)
 - **参考：** [`docs/zh/reference/index.md`](docs/zh/reference/index.md)
-- **研究：** [`docs/zh/research/index.md`](docs/zh/research/index.md)
-- **实践手册内的快速开始：** [`docs/zh/getting-started/quickstart.md`](docs/zh/getting-started/quickstart.md)
-- **学习路径：** [`docs/zh/guides/learning-path.md`](docs/zh/guides/learning-path.md)
-- **性能分析指南：** [`docs/zh/guides/profiling-guide.md`](docs/zh/guides/profiling-guide.md)
-- **验证与 Sanitizer：** [`docs/zh/guides/validation.md`](docs/zh/guides/validation.md)
 - **英文入口：** `README.md` 与 `docs/en/`
 
 ## 技术栈
 
 - **语言：** C++20
-- **构建：** CMake 3.22+、Ninja
+- **构建：** CMake 3.20+、Ninja
 - **测试：** Google Test、RapidCheck
 - **基准测试：** Google Benchmark
 - **文档：** VitePress + GitHub Pages
diff --git a/benchmarks/README.md b/benchmarks/README.md
@@ -33,7 +33,7 @@ cmake --build build/release
 4. Compare the two runs:
 
 ```bash
-python3 scripts/compare_benchmarks.py simd-baseline.json simd-candidate.json --threshold 10
+python3 tools/performance/benchmark_compare.py simd-baseline.json simd-candidate.json --threshold 10
 ```
 
 The script prints a per-benchmark table with baseline time, candidate time, and
diff --git a/cmake/ExampleTemplate.cmake b/cmake/ExampleTemplate.cmake
@@ -40,6 +40,9 @@ function(hpc_add_example)
     
     # Enable sanitizers if configured
     hpc_enable_sanitizers(${ARG_NAME})
+
+    # Canonical headers (include/hpc/)
+    target_link_libraries(${ARG_NAME} PRIVATE hpc_headers)
     
     # Add include directories (target-based, not directory-based!)
     if(ARG_INCLUDE_DIRS)
@@ -74,6 +77,7 @@ function(hpc_add_example)
         target_link_libraries(${bench_name} PRIVATE
             benchmark::benchmark
             benchmark::benchmark_main
+            hpc_headers
         )
         
         if(ARG_INCLUDE_DIRS)
@@ -173,6 +177,7 @@ function(hpc_add_benchmark)
     target_link_libraries(${ARG_NAME} PRIVATE
         benchmark::benchmark
         benchmark::benchmark_main
+        hpc_headers
     )
     
     if(ARG_INCLUDE_DIRS)
diff --git a/docs/en/index.md b/docs/en/index.md
@@ -211,7 +211,7 @@ Use the preset-driven path first. It is the shortest route that still preserves
 
 | Surface | Detail |
 | --- | --- |
-| C++ standard | C++17 minimum, C++20 where beneficial |
+| C++ standard | C++20 (required) |
 | Build system | CMake 3.20+ with presets |
 | Platforms | Linux primary; macOS and Windows via cross-platform headers |
 | Compilers | GCC 11+, Clang 14+, MSVC 2022+ |
diff --git a/docs/zh/index.md b/docs/zh/index.md
@@ -211,7 +211,7 @@ layout: home
 
 | 层面 | 详情 |
 | --- | --- |
-| C++ 标准 | C++17 最低，C++20 在有益处时使用 |
+| C++ 标准 | C++20（必需） |
 | 构建系统 | CMake 3.20+，基于 preset |
 | 平台 | 以 Linux 为主；macOS 和 Windows 通过跨平台头文件支持 |
 | 编译器 | GCC 11+、Clang 14+、MSVC 2022+ |
diff --git a/examples/02-memory-cache/bench/alignment_bench.cpp b/examples/02-memory-cache/bench/alignment_bench.cpp
@@ -142,5 +142,3 @@ BENCHMARK(BM_AVX_Unaligned)
 #endif
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/02-memory-cache/bench/aos_soa_bench.cpp b/examples/02-memory-cache/bench/aos_soa_bench.cpp
@@ -138,5 +138,3 @@ BENCHMARK(BM_SOA_Update)
     ->Unit(benchmark::kMicrosecond);
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/02-memory-cache/bench/false_sharing_bench.cpp b/examples/02-memory-cache/bench/false_sharing_bench.cpp
@@ -99,5 +99,3 @@ BENCHMARK(BM_FalseSharing_Padded)
     ->UseRealTime();
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/02-memory-cache/bench/prefetch_bench.cpp b/examples/02-memory-cache/bench/prefetch_bench.cpp
@@ -156,5 +156,3 @@ BENCHMARK(BM_Random_WithPrefetch)
     ->Unit(benchmark::kMillisecond);
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/02-memory-cache/include/memory_utils.hpp b/examples/02-memory-cache/include/memory_utils.hpp
@@ -15,19 +15,18 @@
 
 #include <cstddef>
 #include <cstdlib>
+#include <hpc/core.hpp>  // platform constants
 #include <memory>
 #include <new>
 #include <vector>
 
-#include "hpc/core.hpp"  // 平台常量
-
 namespace hpc::memory {
 
 //------------------------------------------------------------------------------
-// 使用核心头文件中的常量
+// Constants from the canonical core header
 //------------------------------------------------------------------------------
 
-// CACHE_LINE_SIZE 和 PAGE_SIZE 来自 hpc::core 命名空间
+// CACHE_LINE_SIZE and PAGE_SIZE come from the hpc::core namespace
 
 //------------------------------------------------------------------------------
 // Aligned Memory Allocation
diff --git a/examples/02-memory-cache/include/particle_types.hpp b/examples/02-memory-cache/include/particle_types.hpp
@@ -150,7 +150,7 @@ inline float compute_energy_soa(const ParticleSOA& particles) {
  * @brief Initialize AOS particles with deterministic random values
  */
 inline void initialize_particles(std::vector<ParticleAOS>& particles, size_t n) {
-    // 使用确定性初始化而非随机，避免 <random> 依赖
+    // Deterministic init instead of random to avoid <random> dependency
     particles.resize(n);
     for (size_t i = 0; i < n; ++i) {
         float fi = static_cast<float>(i);
diff --git a/examples/03-modern-cpp/bench/move_semantics_bench.cpp b/examples/03-modern-cpp/bench/move_semantics_bench.cpp
@@ -111,5 +111,3 @@ BENCHMARK(BM_Vector_EmplaceBack)
     ->Unit(benchmark::kMillisecond);
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/03-modern-cpp/bench/ranges_bench.cpp b/examples/03-modern-cpp/bench/ranges_bench.cpp
@@ -166,5 +166,3 @@ BENCHMARK(BM_Chain_RangesView)
     ->Unit(benchmark::kMicrosecond);
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/03-modern-cpp/bench/vector_reserve_bench.cpp b/examples/03-modern-cpp/bench/vector_reserve_bench.cpp
@@ -72,5 +72,3 @@ BENCHMARK(BM_Vector_Resize)
     ->Unit(benchmark::kMicrosecond);
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/04-simd-vectorization/bench/simd_bench.cpp b/examples/04-simd-vectorization/bench/simd_bench.cpp
@@ -298,5 +298,3 @@ static void BM_FloatVec_HorizontalSum(benchmark::State& state) {
 }
 
 BENCHMARK(BM_FloatVec_HorizontalSum);
-
-BENCHMARK_MAIN();
diff --git a/examples/05-concurrency/bench/atomic_bench.cpp b/examples/05-concurrency/bench/atomic_bench.cpp
@@ -85,5 +85,3 @@ BENCHMARK(BM_Atomic_Relaxed)
     ->UseRealTime();
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/05-concurrency/bench/openmp_bench.cpp b/examples/05-concurrency/bench/openmp_bench.cpp
@@ -85,5 +85,3 @@ BENCHMARK(BM_OpenMP_Reduction)
     ->UseRealTime();
 
 }  // namespace
-
-BENCHMARK_MAIN();
diff --git a/examples/05-concurrency/include/concurrency_utils.hpp b/examples/05-concurrency/include/concurrency_utils.hpp
@@ -18,22 +18,21 @@
 #include <chrono>
 #include <concepts>  // C++20 concepts
 #include <functional>
-#include <mutex>  // for std::lock_guard, std::unique_lock
+#include <hpc/core.hpp>  // platform constants
+#include <mutex>         // for std::lock_guard, std::unique_lock
 #include <thread>
 #include <vector>
 
-#include "hpc/core.hpp"  // 平台常量
-
 namespace hpc::concurrency {
 
 //------------------------------------------------------------------------------
-// 使用核心头文件中的常量和函数
+// Constants and utilities from the canonical core header
 //------------------------------------------------------------------------------
 
-// CACHE_LINE_SIZE 来自 hpc::core 命名空间
-// hardware_concurrency() 在 hpc::core 中定义
+// CACHE_LINE_SIZE comes from the hpc::core namespace
+// hardware_concurrency() is defined in hpc::core
 
-// 为了向后兼容，在当前命名空间中提供别名
+// Backward-compatibility alias in the current namespace
 using hpc::core::hardware_concurrency;
 
 //------------------------------------------------------------------------------
@@ -70,7 +69,7 @@ struct alignas(hpc::core::CACHE_LINE_SIZE) AlignedCounter {
 };
 
 //------------------------------------------------------------------------------
-// Spin Lock - 符合 C++ BasicLockable 和 Lockable 概念
+// Spin Lock - satisfies C++ BasicLockable and Lockable concepts
 //------------------------------------------------------------------------------
 
 /**
diff --git a/tests/property/CMakeLists.txt b/tests/property/CMakeLists.txt
@@ -9,7 +9,6 @@ add_executable(memory_properties_test
 target_include_directories(memory_properties_test PRIVATE
     ${CMAKE_SOURCE_DIR}/examples/02-memory-cache/include
     ${CMAKE_SOURCE_DIR}/examples/05-concurrency/include
-    ${CMAKE_SOURCE_DIR}/include
     ${CMAKE_SOURCE_DIR}/benchmarks/common
 )
 
@@ -19,6 +18,7 @@ target_link_libraries(memory_properties_test PRIVATE
     rapidcheck
     rapidcheck_gtest
     benchmark::benchmark
+    hpc_headers
 )
 
 hpc_set_compiler_options(memory_properties_test)
@@ -35,6 +35,7 @@ target_link_libraries(simd_properties_test PRIVATE
     rapidcheck
     rapidcheck_gtest
     benchmark::benchmark
+    hpc_headers
 )
 
 hpc_set_compiler_options(simd_properties_test)
@@ -64,6 +65,7 @@ target_link_libraries(concurrency_properties_test PRIVATE
     rapidcheck
     rapidcheck_gtest
     Threads::Threads
+    hpc_headers
 )
 
 # Link OpenMP if available
diff --git a/tests/property/memory_properties.cpp b/tests/property/memory_properties.cpp
@@ -19,17 +19,13 @@
 #include <atomic>
 #include <cmath>
 #include <cstdlib>
+#include <hpc/core.hpp>
 #include <thread>
 #include <vector>
 
-// 使用共享的粒子类型定义，确保测试与示例代码一致
-#include "particle_types.hpp"
-// 使用核心平台常量
-#include "hpc/core.hpp"
-// 使用并发工具（AlignedCounter）
-#include "concurrency_utils.hpp"
-// 使用基准测试计时工具
 #include "benchmark_utils.hpp"
+#include "concurrency_utils.hpp"
+#include "particle_types.hpp"
 
 namespace {
 
@@ -81,7 +77,7 @@ RC_GTEST_PROP(MemoryProperties, SOAPerformanceAdvantage, ()) {
         update_particles_aos(aos, dt);
     }
     aos_timer.stop();
-    const auto aos_time = aos_timer.elapsed_us();  // 微秒
+    const auto aos_time = aos_timer.elapsed_us();
 
     // Measure SOA time using hpc::bench::Timer
     Timer soa_timer;
@@ -90,7 +86,7 @@ RC_GTEST_PROP(MemoryProperties, SOAPerformanceAdvantage, ()) {
         update_particles_soa(soa, dt);
     }
     soa_timer.stop();
-    const auto soa_time = soa_timer.elapsed_us();  // 微秒
+    const auto soa_time = soa_timer.elapsed_us();
 
     // SOA should be faster (or at least not significantly slower)
     // Allow 20% tolerance for system noise
@@ -111,9 +107,8 @@ RC_GTEST_PROP(MemoryProperties, SOAPerformanceAdvantage, ()) {
 // Validates: Requirements 2.2, 5.3
 //------------------------------------------------------------------------------
 
-// 使用 hpc::concurrency::AlignedCounter 和 std::atomic<int> 进行对比测试
-// 注意：UnalignedCounter 已被删除，因为它没有任何价值
-// 对于未对齐的情况，直接使用 std::atomic<int>
+// Compare hpc::concurrency::AlignedCounter vs plain std::atomic<int>.
+// For the unaligned case, use std::atomic<int> directly.
 
 RC_GTEST_PROP(MemoryProperties, AlignedCountersEliminateFalseSharing, ()) {
     // Feature: hpc-optimization-guide, Property 4: Cache-Line Aligned Counters
@@ -123,7 +118,7 @@ RC_GTEST_PROP(MemoryProperties, AlignedCountersEliminateFalseSharing, ()) {
     const int increments = *rc::gen::inRange(10000, 100001);
 
     // Test with unaligned counters (false sharing)
-    // 直接使用 std::atomic<int64_t> 来演示未对齐的情况
+    // Use plain std::atomic<int64_t> to demonstrate the unaligned case
     std::vector<std::atomic<int64_t>> unaligned(static_cast<size_t>(num_threads));
 
     Timer unaligned_timer;
@@ -142,7 +137,7 @@ RC_GTEST_PROP(MemoryProperties, AlignedCountersEliminateFalseSharing, ()) {
         }
     }
     unaligned_timer.stop();
-    const auto unaligned_time = unaligned_timer.elapsed_us();  // 微秒
+    const auto unaligned_time = unaligned_timer.elapsed_us();
 
     // Test with aligned counters (no false sharing)
     std::vector<AlignedCounter> aligned(static_cast<size_t>(num_threads));
@@ -163,7 +158,7 @@ RC_GTEST_PROP(MemoryProperties, AlignedCountersEliminateFalseSharing, ()) {
         }
     }
     aligned_timer.stop();
-    const auto aligned_time = aligned_timer.elapsed_us();  // 微秒
+    const auto aligned_time = aligned_timer.elapsed_us();
 
     // Verify correctness
     for (int t = 0; t < num_threads; ++t) {
diff --git a/tests/unit/concurrency/CMakeLists.txt b/tests/unit/concurrency/CMakeLists.txt
diff --git a/tests/unit/core/CMakeLists.txt b/tests/unit/core/CMakeLists.txt
diff --git a/tests/unit/memory/CMakeLists.txt b/tests/unit/memory/CMakeLists.txt
diff --git a/tests/unit/simd/CMakeLists.txt b/tests/unit/simd/CMakeLists.txt
