chore: Modernize CMake build, CI workflows, and code quality tooling (#16)

This pull request introduces significant improvements to the C++
project's build system, code quality tooling, and codebase consistency.
The main focus is on modernizing the CMake configuration, enhancing CI
workflows, enforcing code quality standards, and making minor code
improvements for readability and correctness.

**Build System Modernization and CI Improvements:**

* Migrated to CMake 3.25+ with modern target-based configuration,
introduced `CMakePresets.json` for standardized build and test presets,
and improved compiler warning handling using `target_compile_options`.
[[1]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aL1-R12)
[[2]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aR36-R43)
[[3]](diffhunk://#diff-1712b235e02bd4a3ad866fe26447a6dc5c1b449faeea513f449d244d46d03cf5R1-R107)
* Updated the GitHub Actions workflow to split formatting and build/test
jobs, enforce `clang-format` checks, and use CMake presets for CI
builds.

**Code Quality and Tooling Enhancements:**

* Refined `.clang-tidy` configuration to enable/disable specific checks,
treat critical warnings as errors, and set header filtering for source
files.
* Improved CMake targets for `clang-format` and `clang-tidy`, ensuring
only source files are linted and all code is properly formatted.
[[1]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aL60-R97)
[[2]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aR118-R133)
* Added VSCode settings for YAML associations and updated documentation
with requirements, build instructions, and code quality commands.
[[1]](diffhunk://#diff-a5de3e5871ffcc383a2294845bd3df25d3eeff6c29ad46e3a396577c413bf357L7-R11)
[[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R6-R55)
* Removed obsolete `scripts/run_tests.sh` in favor of CMake presets and
CI workflows.

**Codebase Consistency and Minor Fixes:**

* Added `[[nodiscard]]` and other modern C++ attributes to key methods,
improved initialization, and standardized output formatting across
several data structures and algorithms.
[[1]](diffhunk://#diff-035b7389279440bf3472b6a9ab837486652786563c0bcb30e6c466af3d972ed0L29-R29)
[[2]](diffhunk://#diff-035b7389279440bf3472b6a9ab837486652786563c0bcb30e6c466af3d972ed0L44-R44)
[[3]](diffhunk://#diff-0b5eede64af7e5fa987b28c15c62d66036eef93142f747dd42406b49e2ee301dL47-R50)
[[4]](diffhunk://#diff-ca43b5fe493a373d174223fe3547b0c58250493f79b5c95b1981b8c286d82c75L16-R16)
[[5]](diffhunk://#diff-ca43b5fe493a373d174223fe3547b0c58250493f79b5c95b1981b8c286d82c75L49)
[[6]](diffhunk://#diff-5524ccff0723a609f11dc709f077a3813e2a34d4533a7fca4b6b891a8408bd94L52-R52)
[[7]](diffhunk://#diff-8e68f308a036639d8ef3c8d27b1d42015f92db971daba5e31fc26fd9acff1e40L190-R190)
[[8]](diffhunk://#diff-e9c600dcc202ad9d737c0c1084beb09567317bf0b01fe089c212d36c602704afL32-R33)
[[9]](diffhunk://#diff-e9c600dcc202ad9d737c0c1084beb09567317bf0b01fe089c212d36c602704afL47-R47)
[[10]](diffhunk://#diff-2cf88c17b45aaab80a3a46e62ee7e698ad0a621a513f96e8c5283467eada8e43L88-R89)
[[11]](diffhunk://#diff-c824d5e43b627b233c542eac5d32e3d436d356cd1b00fa93c89724de403f6cd4L35-R42)
[[12]](diffhunk://#diff-c824d5e43b627b233c542eac5d32e3d436d356cd1b00fa93c89724de403f6cd4L74-R74)
[[13]](diffhunk://#diff-f64e54e408e0f27c25e219f69f3f632f7efc4f70023e48716cb71aca45662392L39-R43)
[[14]](diffhunk://#diff-96b15a28ce488fdb6264a757c5e03585c8032ca9f92b2a852bf1e3b0e40bb6f0R5)
[[15]](diffhunk://#diff-96b15a28ce488fdb6264a757c5e03585c8032ca9f92b2a852bf1e3b0e40bb6f0L54-R55)
[[16]](diffhunk://#diff-a3fbb7e77fc266ed86ac6d96d669c727b8d1c328c30d1db10b48c44c66a8094aL8-R8)
[[17]](diffhunk://#diff-a3fbb7e77fc266ed86ac6d96d669c727b8d1c328c30d1db10b48c44c66a8094aL121-R120)
[[18]](diffhunk://#diff-ffabb94a8f5f7a9e75419de83bfa5ef14f7a632dd612b0f19e245cf418bf022aL13-R13)

**Summary of Most Important Changes:**

**Build System & CI Modernization**
- Migrated to CMake 3.25+ with modern target-based configuration,
introduced `CMakePresets.json` for easier builds and tests, and improved
compiler warning management.
[[1]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aL1-R12)
[[2]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aR36-R43)
[[3]](diffhunk://#diff-1712b235e02bd4a3ad866fe26447a6dc5c1b449faeea513f449d244d46d03cf5R1-R107)
- Updated GitHub Actions workflow to separate formatting and build/test
jobs, enforce code formatting with `clang-format`, and use CMake presets
for CI.
- Removed legacy shell script `scripts/run_tests.sh` in favor of
CMake-based workflows.

**Code Quality Tooling**
- Enhanced `.clang-tidy` configuration: fine-tuned enabled/disabled
checks, set key warnings as errors, and added header filtering for
focused analysis.
- Improved CMake integration for `clang-format` and `clang-tidy`
targets, ensuring correct file selection and command usage.
[[1]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aL60-R97)
[[2]](diffhunk://#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aR118-R133)
- Updated VSCode settings for better YAML support and improved
documentation with requirements and code quality instructions.
[[1]](diffhunk://#diff-a5de3e5871ffcc383a2294845bd3df25d3eeff6c29ad46e3a396577c413bf357L7-R11)
[[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R6-R55)

**Codebase Improvements**
- Applied modern C++ best practices: added `[[nodiscard]]`, improved
initialization, standardized output, and fixed minor code issues for
clarity and correctness across multiple files.
[[1]](diffhunk://#diff-035b7389279440bf3472b6a9ab837486652786563c0bcb30e6c466af3d972ed0L29-R29)
[[2]](diffhunk://#diff-035b7389279440bf3472b6a9ab837486652786563c0bcb30e6c466af3d972ed0L44-R44)
[[3]](diffhunk://#diff-0b5eede64af7e5fa987b28c15c62d66036eef93142f747dd42406b49e2ee301dL47-R50)
[[4]](diffhunk://#diff-ca43b5fe493a373d174223fe3547b0c58250493f79b5c95b1981b8c286d82c75L16-R16)
[[5]](diffhunk://#diff-ca43b5fe493a373d174223fe3547b0c58250493f79b5c95b1981b8c286d82c75L49)
[[6]](diffhunk://#diff-5524ccff0723a609f11dc709f077a3813e2a34d4533a7fca4b6b891a8408bd94L52-R52)
[[7]](diffhunk://#diff-8e68f308a036639d8ef3c8d27b1d42015f92db971daba5e31fc26fd9acff1e40L190-R190)
[[8]](diffhunk://#diff-e9c600dcc202ad9d737c0c1084beb09567317bf0b01fe089c212d36c602704afL32-R33)
[[9]](diffhunk://#diff-e9c600dcc202ad9d737c0c1084beb09567317bf0b01fe089c212d36c602704afL47-R47)
[[10]](diffhunk://#diff-2cf88c17b45aaab80a3a46e62ee7e698ad0a621a513f96e8c5283467eada8e43L88-R89)
[[11]](diffhunk://#diff-c824d5e43b627b233c542eac5d32e3d436d356cd1b00fa93c89724de403f6cd4L35-R42)
[[12]](diffhunk://#diff-c824d5e43b627b233c542eac5d32e3d436d356cd1b00fa93c89724de403f6cd4L74-R74)
[[13]](diffhunk://#diff-f64e54e408e0f27c25e219f69f3f632f7efc4f70023e48716cb71aca45662392L39-R43)
[[14]](diffhunk://#diff-96b15a28ce488fdb6264a757c5e03585c8032ca9f92b2a852bf1e3b0e40bb6f0R5)
[[15]](diffhunk://#diff-96b15a28ce488fdb6264a757c5e03585c8032ca9f92b2a852bf1e3b0e40bb6f0L54-R55)
[[16]](diffhunk://#diff-a3fbb7e77fc266ed86ac6d96d669c727b8d1c328c30d1db10b48c44c66a8094aL8-R8)
[[17]](diffhunk://#diff-a3fbb7e77fc266ed86ac6d96d669c727b8d1c328c30d1db10b48c44c66a8094aL121-R120)
[[18]](diffhunk://#diff-ffabb94a8f5f7a9e75419de83bfa5ef14f7a632dd612b0f19e245cf418bf022aL13-R13)

Author: monkey0722

.clang-format

@@ -1,4 +1,7 @@
 BasedOnStyle: Google
 IndentWidth: 2
-TabWidth: 3
+TabWidth: 2
 ColumnLimit: 100
+RequiresClausePosition: OwnLine
+RequiresExpressionIndentation: OuterScope
+SpacesInContainerLiterals: true

.clang-tidy

@@ -1,19 +1,45 @@
 Checks: >
   -*,
   bugprone-*,
-  modernize-*,
-  readability-*,
-  cppcoreguidelines-*,
-  performance-*,
   clang-analyzer-*,
-  cert-*,
   misc-*,
-  google-*,
-  llvm-*,
-  hicpp-*
+  modernize-*,
+  performance-*,
+  readability-const-return-type,
+  readability-container-size-empty,
+  readability-make-member-function-const,
+  readability-redundant-member-init,
+  readability-redundant-smartptr-get,
+  readability-redundant-string-cstr,
+  readability-simplify-boolean-expr,
+  readability-static-accessed-through-instance,
+  readability-string-compare,
+  cppcoreguidelines-init-variables,
+  cppcoreguidelines-prefer-member-initializer,
+  cppcoreguidelines-slicing,
+  -bugprone-easily-swappable-parameters,
+  -misc-const-correctness,
+  -misc-include-cleaner,
+  -misc-no-recursion,
+  -misc-non-private-member-variables-in-classes,
+  -misc-unused-parameters,
+  -misc-use-anonymous-namespace,
+  -misc-definitions-in-headers,
+  -misc-use-internal-linkage,
+  -modernize-use-trailing-return-type
+
+WarningsAsErrors: >
+  bugprone-use-after-move,
+  bugprone-dangling-handle
+
+HeaderFilterRegex: 'src/.*\.(hpp|h)$'
+
+FormatStyle: file
 
 CheckOptions:
   - key: modernize-use-nullptr.NullMacros
-    value: 'Google'
-  - key: modernize-use-override.IgnoreDestructors
-    value: true
+    value: 'NULL'
+  - key: performance-move-const-arg.CheckTriviallyCopyableMove
+    value: 'false'
+  - key: misc-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic
+    value: 'true'

.github/workflows/cpp-ci.yml

@@ -2,21 +2,47 @@ name: C++ CI
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 jobs:
-  build_and_test:
-    runs-on: ubuntu-latest
+  format-check:
+    name: Format Check
+    runs-on: ubuntu-24.04
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
-      - name: Install Dependencies
+        uses: actions/checkout@v6
+
+      - name: Check format
+        run: |
+          clang-format --version
+          find src tests \( -name "*.hpp" -o -name "*.cpp" -o -name "*.h" \) | \
+            xargs clang-format --dry-run --Werror
+
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-24.04
+    needs: format-check
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y cmake build-essential libgtest-dev
-      - name: Build and run tests
+          sudo apt-get install -y libgtest-dev
+
+      - name: Show tool versions
         run: |
-          chmod +x ./scripts/run_tests.sh
-          ./scripts/run_tests.sh
+          cmake --version
+          g++ --version
+
+      - name: Configure
+        run: cmake --preset ci
+
+      - name: Build
+        run: cmake --build --preset ci
+
+      - name: Test
+        run: ctest --preset ci

.vscode/settings.json

@@ -4,5 +4,9 @@
   "C_Cpp.default.includePath": [
     "${workspaceFolder}/src"
   ],
-  "C_Cpp.default.intelliSenseMode": "clang-x64"
+  "C_Cpp.default.intelliSenseMode": "clang-x64",
+  "files.associations": {
+    ".clang-tidy": "yaml",
+    ".clang-format": "yaml"
+  }
 }

CMakeLists.txt

@@ -1,20 +1,15 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.25)
 
 project(CLAVIS LANGUAGES CXX)
-set(CMAKE_CXX_STANDARD 20)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # Set build type (default is Debug)
 if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE Debug)
 endif()
 
-# Basic compiler flags
-if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
-  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra")
-endif()
-
-# Collect source files
+# NOTE: file(GLOB) is not recommended by CMake official docs.
+# Consider listing source files explicitly for reliable rebuilds.
+# See: https://cmake.org/cmake/help/latest/command/file.html#glob
 file(GLOB CORE_SOURCES
   src/*.cpp
   src/graph/*.hpp
@@ -38,6 +33,14 @@ set(SOURCES ${CORE_SOURCES})
 # Create library
 add_library(clavis_algorithm ${SOURCES})
 
+# Set C++ standard (modern target-based approach)
+target_compile_features(clavis_algorithm PUBLIC cxx_std_20)
+
+# Set compiler warnings (target-based, not global CMAKE_CXX_FLAGS)
+target_compile_options(clavis_algorithm PRIVATE
+  $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wall -Wextra>
+)
+
 # Set include directories
 target_include_directories(clavis_algorithm PUBLIC
   ${CMAKE_SOURCE_DIR}/src
@@ -57,26 +60,41 @@ target_include_directories(clavis_algorithm_test PRIVATE
 
 target_link_libraries(clavis_algorithm_test clavis_algorithm GTest::GTest GTest::Main)
 
-# Register test
-add_test(NAME AlgorithmTest COMMAND clavis_algorithm_test)
+# Set compiler warnings for tests
+target_compile_options(clavis_algorithm_test PRIVATE
+  $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wall -Wextra>
+)
+
+# Discover and register tests
+include(GoogleTest)
+gtest_discover_tests(clavis_algorithm_test)
 
 # =============================================================================
 # Code Quality Tools
 # =============================================================================
 
-# Collect all C++ files for formatting/linting
+# Collect all C++ files for formatting
 file(GLOB_RECURSE ALL_CXX_FILES
   ${CMAKE_SOURCE_DIR}/src/*.hpp
   ${CMAKE_SOURCE_DIR}/src/*.cpp
   ${CMAKE_SOURCE_DIR}/src/*.h
   ${CMAKE_SOURCE_DIR}/tests/*.cpp
 )
 
+# Collect source files only for linting (exclude tests)
+file(GLOB_RECURSE SRC_CXX_FILES
+  ${CMAKE_SOURCE_DIR}/src/*.hpp
+  ${CMAKE_SOURCE_DIR}/src/*.cpp
+  ${CMAKE_SOURCE_DIR}/src/*.h
+)
+
 # clang-format targets
 find_program(CLANG_FORMAT clang-format
   HINTS
+    $ENV{LLVM_DIR}/bin
     /opt/homebrew/opt/llvm/bin
     /usr/local/opt/llvm/bin
+    /usr/bin
 )
 if(CLANG_FORMAT)
   add_custom_target(format
@@ -97,13 +115,22 @@ endif()
 # clang-tidy target
 find_program(CLANG_TIDY clang-tidy
   HINTS
+    $ENV{LLVM_DIR}/bin
     /opt/homebrew/opt/llvm/bin
     /usr/local/opt/llvm/bin
+    /usr/bin
 )
 if(CLANG_TIDY)
   add_custom_target(lint
-    COMMAND ${CLANG_TIDY} -p ${CMAKE_BINARY_DIR} ${ALL_CXX_FILES}
-    COMMENT "Running clang-tidy"
+    COMMAND ${CLANG_TIDY}
+      -p ${CMAKE_BINARY_DIR}
+      -header-filter=${CMAKE_SOURCE_DIR}/src/.*
+      ${SRC_CXX_FILES}
+      --
+      -x c++
+      -std=c++20
+      -I${CMAKE_SOURCE_DIR}/src
+    COMMENT "Running clang-tidy on source files"
     VERBATIM
   )
 else()

CMakePresets.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://cmake.org/cmake/help/latest/_downloads/3e2d73bff478d88a7de0de736ba5e361/schema.json",
+  "version": 8,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 25,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "base",
+      "hidden": true,
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/${presetName}",
+      "cacheVariables": {
+        "CMAKE_CXX_STANDARD": "20",
+        "CMAKE_CXX_STANDARD_REQUIRED": "ON",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    },
+    {
+      "name": "debug",
+      "displayName": "Debug",
+      "inherits": "base",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    },
+    {
+      "name": "release",
+      "displayName": "Release",
+      "inherits": "base",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "ci",
+      "displayName": "CI",
+      "inherits": "base",
+      "generator": "Unix Makefiles",
+      "binaryDir": "${sourceDir}/build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "debug",
+      "configurePreset": "debug"
+    },
+    {
+      "name": "release",
+      "configurePreset": "release"
+    },
+    {
+      "name": "ci",
+      "configurePreset": "ci",
+      "jobs": 4
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "base",
+      "hidden": true,
+      "output": {
+        "outputOnFailure": true,
+        "verbosity": "default"
+      },
+      "execution": {
+        "noTestsAction": "error",
+        "stopOnFailure": false
+      }
+    },
+    {
+      "name": "debug",
+      "configurePreset": "debug",
+      "inherits": "base"
+    },
+    {
+      "name": "release",
+      "configurePreset": "release",
+      "inherits": "base"
+    },
+    {
+      "name": "ci",
+      "configurePreset": "ci",
+      "inherits": "base",
+      "output": {
+        "outputOnFailure": true,
+        "verbosity": "verbose"
+      }
+    }
+  ],
+  "workflowPresets": [
+    {
+      "name": "ci",
+      "displayName": "CI Workflow",
+      "steps": [
+        { "type": "configure", "name": "ci" },
+        { "type": "build", "name": "ci" },
+        { "type": "test", "name": "ci" }
+      ]
+    }
+  ]
+}