fix(build): preserve CDB links during atomic publication

Author: wellwei

.agents/docs/2026-08-08-configure-only-cdb-design.md

@@ -132,6 +132,7 @@ CDB 发布前，并保留旧 CDB。项目自身模块或未缓存依赖模块保
 
 - POSIX 使用同文件系统 `rename`；
 - Windows 使用 `MoveFileExW(..., MOVEFILE_REPLACE_EXISTING)`；
+- Windows 遇到短暂 sharing violation 时有限退避重试；
 - 不先删除 destination；
 - 函数为 `noexcept` 风格，通过 `error_code` 报错。
 
@@ -140,9 +141,10 @@ CDB 写入流程：
 1. 生成并解析 JSON，要求顶层为数组。
 2. 与现有有效条目合并并删除已不存在源文件的旧条目。
 3. 内容未变化时不写文件，避免无意义触发 clangd 重索引。
-4. 在同目录完成唯一临时文件写入和 flush。
-5. 通过 `replace_file` 原子替换目标。
-6. 替换失败时清理临时文件，返回错误，旧文件保持不变。
+4. 若根 CDB 是文件符号链接，解析并原子更新其目标，保留链接本身。
+5. 在同目录完成带跨进程随机量的临时文件写入和 flush。
+6. 通过 `replace_file` 原子替换目标。
+7. 替换失败时清理临时文件，返回错误，旧文件保持不变。
 
 `write_compile_commands()` 改为返回结构化成功或错误。为保持普通构建兼容性：
 

src/build/compile_commands.cppm

@@ -253,15 +253,46 @@ publish_compile_commands(
             "fresh compile database for '{}' is not a JSON array", path.string())));
     }
 
+    std::filesystem::path publishPath = path;
+    std::error_code statusEc;
+    const bool isLink = std::filesystem::is_symlink(path, statusEc);
+    if (statusEc) {
+        return std::unexpected(write_error(std::format(
+            "cannot inspect compile database '{}': {}", path.string(),
+            statusEc.message())));
+    }
+    if (isLink) {
+        auto target = std::filesystem::read_symlink(path, statusEc);
+        if (statusEc) {
+            return std::unexpected(write_error(std::format(
+                "cannot resolve compile database link '{}': {}", path.string(),
+                statusEc.message())));
+        }
+        publishPath = target.is_absolute() ? target : path.parent_path() / target;
+    }
+
     std::optional<std::string> existing;
-    if (std::ifstream is(path, std::ios::binary); is) {
+    std::ifstream input(publishPath, std::ios::binary);
+    if (input) {
         std::stringstream ss;
-        ss << is.rdbuf();
-        if (is.bad()) {
+        ss << input.rdbuf();
+        if (input.bad()) {
             return std::unexpected(write_error(std::format(
-                "cannot read existing compile database '{}'", path.string())));
+                "cannot read existing compile database '{}'", publishPath.string())));
         }
         existing = ss.str();
+    } else {
+        std::error_code existsEc;
+        auto exists = std::filesystem::exists(publishPath, existsEc);
+        if (existsEc) {
+            return std::unexpected(write_error(std::format(
+                "cannot inspect existing compile database '{}': {}",
+                publishPath.string(), existsEc.message())));
+        }
+        if (exists) {
+            return std::unexpected(write_error(std::format(
+                "cannot read existing compile database '{}'", publishPath.string())));
+        }
     }
 
     // 完全相同的有效输入不重写文件，避免 clangd 因 mtime 变化重复索引。
@@ -288,9 +319,12 @@ publish_compile_commands(
     }
 
     static std::atomic<std::uint64_t> sequence{0};
-    auto temp = path.parent_path()
-        / std::format(".{}.tmp.{}.{}", path.filename().string(),
+    const auto nonce = std::random_device{}();
+    // 临时文件和链接目标同目录，避免 rename 跨文件系统；随机量降低跨进程碰撞概率。
+    auto temp = publishPath.parent_path()
+        / std::format(".{}.tmp.{}.{}.{}", publishPath.filename().string(),
                       std::chrono::steady_clock::now().time_since_epoch().count(),
+                      static_cast<unsigned long long>(nonce),
                       sequence.fetch_add(1, std::memory_order_relaxed));
     auto cleanup_temp = [&] {
         std::error_code cleanupEc;
@@ -318,10 +352,10 @@ publish_compile_commands(
     }
 
     std::error_code ec;
-    if (!replaceFile(temp, path, ec)) {
+    if (!replaceFile(temp, publishPath, ec)) {
         cleanup_temp();
         return std::unexpected(write_error(std::format(
-            "cannot replace '{}': {}", path.string(), ec.message())));
+            "cannot replace '{}': {}", publishPath.string(), ec.message())));
     }
 
     return CompileCommandsWriteResult{true, finalJson.size()};

src/platform/fs.cppm

@@ -145,13 +145,23 @@ bool replace_file(const std::filesystem::path& source,
                   const std::filesystem::path& destination,
                   std::error_code& ec) {
 #if defined(_WIN32)
-    // 直接替换已有文件，不能先删除 last-known-good CDB。
-    if (MoveFileExW(source.wstring().c_str(), destination.wstring().c_str(),
-                    MOVEFILE_REPLACE_EXISTING)) {
-        ec.clear();
-        return true;
+    // 直接替换已有文件，不能先删除 last-known-good CDB。编辑器或杀毒软件
+    // 可能短暂占用目标文件，sharing violation 仅做有限退避后再报告失败。
+    auto delay = std::chrono::milliseconds{50};
+    for (int attempt = 0; attempt < 4; ++attempt) {
+        if (MoveFileExW(source.wstring().c_str(), destination.wstring().c_str(),
+                        MOVEFILE_REPLACE_EXISTING)) {
+            ec.clear();
+            return true;
+        }
+        const auto error = GetLastError();
+        if (error != ERROR_SHARING_VIOLATION || attempt == 3) {
+            ec = std::error_code(static_cast<int>(error), std::system_category());
+            return false;
+        }
+        std::this_thread::sleep_for(delay);
+        delay *= 3;
     }
-    ec = std::error_code(static_cast<int>(GetLastError()), std::system_category());
     return false;
 #else
     // 临时文件与目标文件位于同一文件系统时，rename 提供原子替换。

tests/unit/test_compile_commands.cpp

@@ -166,3 +166,51 @@ TEST(CompileCommandsWriter, ReplacementFailurePreservesOldDatabase) {
     EXPECT_EQ(std::distance(std::filesystem::directory_iterator(temp.path),
                             std::filesystem::directory_iterator{}), 1);
 }
+
+TEST(CompileCommandsWriter, ReplacesSymlinkTargetWithoutRemovingLink) {
+    TempDir temp;
+    auto target = temp.path / "build" / "compile_commands.json";
+    auto link = temp.path / "compile_commands.json";
+    std::filesystem::create_directories(target.parent_path());
+    auto oldContent = cdb({entry((temp.path / "old.cpp").string(), "-DOLD")});
+    auto newContent = cdb({entry((temp.path / "new.cpp").string(), "-DNEW")});
+    std::ofstream(target) << oldContent;
+    std::error_code symlinkEc;
+    std::filesystem::create_symlink(target, link, symlinkEc);
+    if (symlinkEc) GTEST_SKIP() << "symlink unavailable: " << symlinkEc.message();
+
+    auto result = publish_compile_commands(
+        link, newContent, [](const std::filesystem::path&) { return false; });
+
+    ASSERT_TRUE(result.has_value()) << result.error().message;
+    EXPECT_TRUE(std::filesystem::is_symlink(link));
+    auto published = read_file(target);
+    EXPECT_NE(published.find("-DNEW"), std::string::npos);
+    EXPECT_EQ(published.find("-DOLD"), std::string::npos);
+}
+
+TEST(CompileCommandsWriter, ExistingUnreadableDatabaseIsNotOverwritten) {
+    TempDir temp;
+    auto path = temp.path / "compile_commands.json";
+    std::ofstream(path) << "last-known-good";
+    std::error_code permissionEc;
+    std::filesystem::permissions(
+        path, std::filesystem::perms::owner_read,
+        std::filesystem::perm_options::remove, permissionEc);
+    if (permissionEc) GTEST_SKIP() << "cannot change permissions: " << permissionEc.message();
+    std::ifstream probe(path);
+    if (probe) {
+        std::filesystem::permissions(path, std::filesystem::perms::owner_all,
+                                     std::filesystem::perm_options::replace, permissionEc);
+        GTEST_SKIP() << "test user can still read restricted file";
+    }
+
+    auto result = publish_compile_commands(
+        path, cdb({entry((temp.path / "new.cpp").string(), "-DNEW")}),
+        [](const std::filesystem::path&) { return true; });
+
+    ASSERT_FALSE(result.has_value());
+    EXPECT_NE(result.error().message.find("read existing"), std::string::npos);
+    std::filesystem::permissions(path, std::filesystem::perms::owner_all,
+                                 std::filesystem::perm_options::replace, permissionEc);
+}