feat: add dry-run and fix symbol repetition

Author: tsurumi-yizhou

.github/workflows/generate-docs.yml

@@ -1,64 +1,59 @@
 name: generate-docs
 
 on:
-    push:
-      branches: ["main"]
-    pull_request:
-    workflow_dispatch:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
 
 jobs:
-    generate:
-        runs-on: windows-2025
-        permissions:
-            contents: write
-            models: read
-
-        steps:
-            - name: Checkout clore
-              uses: actions/checkout@v6
-
-            - name: Setup pixi
-              uses: prefix-dev/setup-pixi@v0.9.4
-              with:
-                  pixi-version: v0.67.0
-                  activate-environment: true
-                  cache: true
-                  locked: true
-
-            - name: Restore compiler cache
-              uses: actions/cache@v5
-              with:
-                  path: .cache/sccache
-                  key: Windows-sccache-${{ github.sha }}
-                  restore-keys: |
-                      Windows-sccache-
-
-            - name: Build
-              run: pixi run build
-
-            - name: Generate documentation
-              env:
-                  OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
-                  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-              run: |
-                  ./build/RelWithDebInfo/bin/clore `
-                    --compile-commands build/RelWithDebInfo/compile_commands.json `
-                    --project-root . `
-                    --output generated `
-                    --llm-model moonshotai/kimi-k2.5 `
-                    --config example.toml `
-                    --log-level info
-
-            - name: Package documentation
-              run: Compress-Archive -Path generated/* -DestinationPath clore-docs.zip
-
-            - name: Upload documentation artifact
-              uses: actions/upload-artifact@v7
-              with:
-                  name: clore-docs
-                  path: clore-docs.zip
-                  retention-days: 30
-
-            - name: Stop sccache
-              if: always()
-              run: pixi run -- sccache --stop-server 2>$null
+  generate:
+    runs-on: windows-2025
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout clore
+        uses: actions/checkout@v6
+
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          pixi-version: v0.67.0
+          activate-environment: true
+          cache: true
+          locked: true
+
+      - name: Restore compiler cache
+        uses: actions/cache@v5
+        with:
+          path: .cache/sccache
+          key: Windows-sccache-${{ github.sha }}
+          restore-keys: |
+            Windows-sccache-
+
+      - name: Build
+        run: pixi run build
+
+      - name: Generate documentation
+        run: |
+          ./build/RelWithDebInfo/bin/clore `
+            --compile-commands build/RelWithDebInfo/compile_commands.json `
+            --project-root src `
+            --output generated `
+            --log-level info `
+            --dry-run
+
+      - name: Package documentation
+        run: Compress-Archive -Path generated/* -DestinationPath clore-docs.zip
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: clore-docs
+          path: clore-docs.zip
+          retention-days: 30
+
+      - name: Stop sccache
+        if: always()
+        run: pixi run -- sccache --stop-server 2>$null

CMakeLists.txt

@@ -8,13 +8,14 @@ set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 include(GNUInstallDirs)
+include(CheckIPOSupported)
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/lib")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/lib")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/bin")
 
-option(CLORE_ENABLE_LTO "Enable ThinLTO for all targets" OFF)
+option(CLORE_ENABLE_LTO "Enable ThinLTO for all targets" ON)
 option(CLORE_OFFLINE_BUILD "Disable network downloads during configuration" OFF)
-option(CLORE_ENABLE_TEST "Build unit tests" OFF)
+option(CLORE_ENABLE_TEST "Build unit tests" ON)
 
 # Global flags that apply to all targets (including FetchContent dependencies).
 if(NOT MSVC)
@@ -39,47 +40,31 @@ else()
     string(APPEND CMAKE_SHARED_LINKER_FLAGS " -Wl,--gc-sections")
 endif()
 
+set(CLORE_ENABLE_IPO OFF)
+set(CLORE_USE_LTO_ARTIFACT OFF)
 if(CLORE_ENABLE_LTO)
-    string(APPEND CMAKE_C_FLAGS " -flto=thin")
-    string(APPEND CMAKE_CXX_FLAGS " -flto=thin")
-    string(APPEND CMAKE_EXE_LINKER_FLAGS " -flto=thin")
-    string(APPEND CMAKE_SHARED_LINKER_FLAGS " -flto=thin")
-    string(APPEND CMAKE_MODULE_LINKER_FLAGS " -flto=thin")
+    if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+        message(STATUS "Interprocedural optimization disabled for Debug builds.")
+    else()
+        check_ipo_supported(RESULT CLORE_IPO_SUPPORTED OUTPUT CLORE_IPO_ERROR LANGUAGES C CXX)
+        if(CLORE_IPO_SUPPORTED)
+            set(CLORE_ENABLE_IPO ON)
+            set(CLORE_USE_LTO_ARTIFACT ON)
+            message(STATUS "Interprocedural optimization enabled for ${CMAKE_BUILD_TYPE} builds.")
+        else()
+            message(WARNING "LTO requested but IPO is not supported by the active toolchain: ${CLORE_IPO_ERROR}")
+        endif()
+    endif()
 endif()
 
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
-    add_compile_options(-fsanitize=address)
-
-    if(CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC")
-        # clang-cl (MSVC frontend): manually link ASan runtime since clang-cl
-        # doesn't handle -fsanitize=address linking automatically.
-        execute_process(
-            COMMAND ${CMAKE_CXX_COMPILER} --print-resource-dir
-            OUTPUT_VARIABLE CLANG_RESOURCE_DIR
-            OUTPUT_STRIP_TRAILING_WHITESPACE
-        )
-        set(ASAN_LIB_PATH "${CLANG_RESOURCE_DIR}/lib/windows")
-        link_directories(${ASAN_LIB_PATH})
-
-        set(ASAN_LINK_FLAGS "")
-        list(APPEND ASAN_LINK_FLAGS "clang_rt.asan_dynamic-x86_64.lib")
-        list(APPEND ASAN_LINK_FLAGS "/wholearchive:clang_rt.asan_dynamic_runtime_thunk-x86_64.lib")
-
-        foreach(flag ${ASAN_LINK_FLAGS})
-            string(APPEND CMAKE_EXE_LINKER_FLAGS " ${flag}")
-            string(APPEND CMAKE_SHARED_LINKER_FLAGS " ${flag}")
-            string(APPEND CMAKE_MODULE_LINKER_FLAGS " ${flag}")
-        endforeach()
+    if(WIN32)
+        message(STATUS "AddressSanitizer disabled on Windows Debug builds: the current MSVC-targeting clang toolchain and prebuilt LLVM static libraries are not ASan-safe in this repo.")
     else()
+        add_compile_options(-fsanitize=address)
         string(APPEND CMAKE_EXE_LINKER_FLAGS " -fsanitize=address")
         string(APPEND CMAKE_SHARED_LINKER_FLAGS " -fsanitize=address")
     endif()
-
-    if(WIN32)
-        # Disable Identical COMDAT Folding in Debug to avoid ASan ODR false positives.
-        string(APPEND CMAKE_EXE_LINKER_FLAGS " -Wl,/OPT:NOICF")
-        string(APPEND CMAKE_SHARED_LINKER_FLAGS " -Wl,/OPT:NOICF")
-    endif()
 endif()
 
 include("${PROJECT_SOURCE_DIR}/cmake/package.cmake")

clore.toml

@@ -0,0 +1,10 @@
+[clore]
+language = "简体中文"
+
+[filter]
+include = ["src/"]
+exclude = []
+
+[[frontmatter.fields]]
+key = "sidebar_label"
+value = "Clore API"

cmake/llvm.cmake

@@ -5,15 +5,21 @@ function(setup_llvm LLVM_VERSION)
 
     set(LLVM_SETUP_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/.llvm/setup-llvm.json")
     set(LLVM_SETUP_SCRIPT "${PROJECT_SOURCE_DIR}/scripts/setup-llvm.py")
+    set(LLVM_ARTIFACT_BUILD_TYPE "${CMAKE_BUILD_TYPE}")
+    if(WIN32 AND CMAKE_BUILD_TYPE STREQUAL "Debug")
+        set(LLVM_ARTIFACT_BUILD_TYPE "RelWithDebInfo")
+        message(STATUS "Windows Debug builds use the non-ASan RelWithDebInfo LLVM artifact because ASan is disabled for this toolchain.")
+    endif()
     set(LLVM_SETUP_ARGS
         "--version" "${LLVM_VERSION}"
         "--build-type" "${CMAKE_BUILD_TYPE}"
+        "--artifact-build-type" "${LLVM_ARTIFACT_BUILD_TYPE}"
         "--binary-dir" "${CMAKE_CURRENT_BINARY_DIR}"
         "--manifest" "${PROJECT_SOURCE_DIR}/config/llvm-manifest.json"
         "--output" "${LLVM_SETUP_OUTPUT}"
     )
 
-    if(CLORE_ENABLE_LTO)
+    if(CLORE_USE_LTO_ARTIFACT)
         list(APPEND LLVM_SETUP_ARGS "--enable-lto")
     endif()
 

scripts/setup-llvm.py

@@ -259,6 +259,7 @@ def main() -> None:
     parser = argparse.ArgumentParser(description="Setup LLVM dependencies for CMake")
     parser.add_argument("--version", required=True)
     parser.add_argument("--build-type", required=True)
+    parser.add_argument("--artifact-build-type")
     parser.add_argument("--binary-dir", required=True)
     parser.add_argument("--manifest", required=True)
     parser.add_argument("--install-path")
@@ -270,13 +271,18 @@ def main() -> None:
     log(
         "Args: "
         f"version={args.version}, build_type={args.build_type}, "
+        f"artifact_build_type={args.artifact_build_type or args.build_type}, "
         f"binary_dir={args.binary_dir}, install_path={args.install_path or '(auto)'}, "
         f"enable_lto={args.enable_lto}, offline={args.offline}"
     )
     token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
     build_type = args.build_type
+    artifact_build_type = args.artifact_build_type or build_type
     platform_name = detect_platform()
-    log(f"Platform detected: {platform_name}, normalized build type: {build_type}")
+    log(
+        f"Platform detected: {platform_name}, normalized build type: {build_type}, "
+        f"artifact build type: {artifact_build_type}"
+    )
     manifest = read_manifest(Path(args.manifest))
 
     binary_dir = Path(args.binary_dir).resolve()
@@ -304,7 +310,7 @@ def main() -> None:
     if install_path is None:
         needs_install = True
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest, args.version, artifact_build_type, args.enable_lto, platform_name
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]
@@ -317,7 +323,7 @@ def main() -> None:
         install_path = install_root
     elif needs_install:
         artifact = pick_artifact(
-            manifest, args.version, build_type, args.enable_lto, platform_name
+            manifest, args.version, artifact_build_type, args.enable_lto, platform_name
         )
         log(f"Selected artifact: {artifact.get('filename')} for download")
         filename = artifact["filename"]

src/CMakeLists.txt

@@ -38,7 +38,7 @@ install(
 
 if(CLORE_ENABLE_TEST)
     file(GLOB_RECURSE CLORE_TEST_SOURCES CONFIGURE_DEPENDS
-        "${PROJECT_SOURCE_DIR}/tests/unit/*/*_tests.cpp"
+        "${PROJECT_SOURCE_DIR}/tests/unit/*/*.cpp"
     )
 
     add_executable(unit_tests
@@ -51,3 +51,11 @@ if(CLORE_ENABLE_TEST)
     )
     target_link_libraries(unit_tests PRIVATE clore::core eventide::zest eventide::deco)
 endif()
+
+if(CLORE_ENABLE_IPO)
+    set_property(TARGET clore-core PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+    set_property(TARGET clore PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+    if(CLORE_ENABLE_TEST)
+        set_property(TARGET unit_tests PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+    endif()
+endif()

src/config/load.cpp

@@ -110,6 +110,11 @@ auto load_config(std::string_view path) -> std::expected<TaskConfig, ConfigError
     namespace fs = std::filesystem;
 
     auto config_path = fs::path(path);
+    if(config_path.is_relative()) {
+        config_path = fs::absolute(config_path);
+    }
+    config_path = config_path.lexically_normal();
+
     if(!fs::exists(config_path)) {
         return std::unexpected(ConfigError{
             .message = std::format("configuration file not found: {}", path)});
@@ -123,7 +128,14 @@ auto load_config(std::string_view path) -> std::expected<TaskConfig, ConfigError
 
     std::ostringstream ss;
     ss << file.rdbuf();
-    return load_config_from_string(ss.str());
+
+    auto config = load_config_from_string(ss.str());
+    if(!config.has_value()) {
+        return config;
+    }
+
+    config->workspace_root = config_path.parent_path().string();
+    return config;
 }
 
 auto load_config_from_string(std::string_view toml_content) -> std::expected<TaskConfig, ConfigError> {

src/config/normalize.cpp

@@ -11,19 +11,29 @@ auto normalize(TaskConfig& config) -> std::expected<void, NormalizeError> {
     // Reject empty required path fields before any filesystem operations.
     // fs::absolute("") silently resolves to cwd, which would bypass validation.
     auto make_absolute = [](std::string& path,
-                            std::string_view field) -> std::expected<void, NormalizeError> {
+                            std::string_view field,
+                            const std::optional<fs::path>& base = std::nullopt)
+        -> std::expected<void, NormalizeError> {
         if(path.empty()) {
             return std::unexpected(
                 NormalizeError{.message = std::format("{} must not be empty", field)});
         }
         auto p = fs::path(path);
         if(p.is_relative()) {
-            path = fs::absolute(p).string();
+            p = base.has_value() ? (*base / p) : fs::absolute(p);
         }
-        path = fs::path(path).lexically_normal().string();
+        path = p.lexically_normal().string();
         return {};
     };
 
+    if(config.workspace_root.empty()) {
+        config.workspace_root = fs::current_path().string();
+    }
+    if(auto r = make_absolute(config.workspace_root, "workspace_root"); !r.has_value()) {
+        return r;
+    }
+    auto workspace_root = fs::path(config.workspace_root);
+
     if(auto r = make_absolute(config.compile_commands_path, "compile_commands_path");
        !r.has_value()) {
         return r;
@@ -36,14 +46,18 @@ auto normalize(TaskConfig& config) -> std::expected<void, NormalizeError> {
     }
 
     auto make_absolute_opt = [&](std::optional<std::string>& opt,
-                                 std::string_view field) -> std::expected<void, NormalizeError> {
+                                 std::string_view field,
+                                 const std::optional<fs::path>& base = std::nullopt)
+        -> std::expected<void, NormalizeError> {
         if(opt.has_value()) {
-            return make_absolute(*opt, field);
+            return make_absolute(*opt, field, base);
         }
         return {};
     };
 
-    if(auto r = make_absolute_opt(config.frontmatter.template_path, "frontmatter.template_path");
+    if(auto r = make_absolute_opt(config.frontmatter.template_path,
+                                  "frontmatter.template_path",
+                                  workspace_root);
        !r.has_value()) {
         return r;
     }
@@ -60,8 +74,12 @@ auto normalize(TaskConfig& config) -> std::expected<void, NormalizeError> {
     normalize_separators(config.compile_commands_path);
     normalize_separators(config.project_root);
     normalize_separators(config.output_root);
+    normalize_separators(config.workspace_root);
     for(auto& p : config.filter.include) normalize_separators(p);
     for(auto& p : config.filter.exclude) normalize_separators(p);
+    if(config.frontmatter.template_path.has_value()) {
+        normalize_separators(*config.frontmatter.template_path);
+    }
 
     return {};
 }