fix: slug formatting and mermaid support

Author: tsurumi-yizhou

.github/workflows/generate-docs.yml

@@ -10,7 +10,7 @@ jobs:
   generate:
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      contents: read
 
     steps:
       - name: Checkout clore
@@ -24,14 +24,16 @@ jobs:
           cache: false
           locked: true
 
-      - name: Cache .clice
-        uses: actions/cache@v5
+      - name: Restore .clice cache
+        id: restore-clice-cache
+        uses: actions/cache/restore@v5
         with:
           path: .clice/
           key: ${{ runner.os }}-clice
 
-      - name: Cache build directory
-        uses: actions/cache@v5
+      - name: Restore build directory cache
+        id: restore-build-cache
+        uses: actions/cache/restore@v5
         with:
           path: build/Debug/
           key: ${{ runner.os }}-${{ hashFiles('pixi.lock', 'pixi.toml', '**/CMakeLists.txt', 'cmake/**/*.cmake') }}
@@ -42,7 +44,22 @@ jobs:
       - name: Build
         run: pixi run cmake-build Debug
 
+      - name: Save .clice cache
+        if: steps.restore-clice-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        with:
+          path: .clice/
+          key: ${{ steps.restore-clice-cache.outputs.cache-primary-key }}
+
+      - name: Save build directory cache
+        if: steps.restore-build-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        with:
+          path: build/Debug/
+          key: ${{ steps.restore-build-cache.outputs.cache-primary-key }}
+
       - name: Generate documentation
+        if: github.event_name == 'push'
         env:
           OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

src/config/validate.cppm

@@ -167,9 +167,6 @@ auto validate(const TaskConfig& config) -> std::expected<void, ValidationError>
     if(auto r = validate_nonzero(config.evidence_rules.max_related_summaries, "evidence_rules.max_related_summaries"); !r) return r;
 
     // Validate workflow rules
-    if(auto r = validate_nonzero(config.workflow_rules.min_chain_symbols,
-                                 "workflow_rules.min_chain_symbols");
-       !r) return r;
     if(config.workflow_rules.min_chain_symbols < 2) {
         return std::unexpected(ValidationError{
             .message =

src/extract/cache.cppm

@@ -48,10 +48,10 @@ struct CacheRecord {
 
 auto build_compile_signature(const CompileEntry& entry) -> std::uint64_t;
 
-auto hash_file(std::string_view path) -> std::uint64_t;
+auto hash_file(std::string_view path) -> std::expected<std::uint64_t, CacheError>;
 
 auto capture_dependency_snapshot(const std::vector<std::string>& files)
-    -> DependencySnapshot;
+    -> std::expected<DependencySnapshot, CacheError>;
 
 auto dependencies_changed(const DependencySnapshot& snapshot) -> bool;
 
@@ -187,16 +187,19 @@ auto build_compile_signature(const CompileEntry& entry) -> std::uint64_t {
     return llvm::xxh3_64bits(payload);
 }
 
-auto hash_file(std::string_view path) -> std::uint64_t {
+auto hash_file(std::string_view path) -> std::expected<std::uint64_t, CacheError> {
     auto buffer = llvm::MemoryBuffer::getFile(path);
     if(!buffer) {
-        return 0;
+        return std::unexpected(CacheError{
+            .message = std::format("failed to read '{}' for hashing: {}",
+                                   path, buffer.getError().message()),
+        });
     }
     return llvm::xxh3_64bits((*buffer)->getBuffer());
 }
 
 auto capture_dependency_snapshot(const std::vector<std::string>& files)
-    -> DependencySnapshot {
+    -> std::expected<DependencySnapshot, CacheError> {
     DependencySnapshot snapshot;
     snapshot.build_at = std::chrono::system_clock::to_time_t(std::chrono::system_clock::now());
 
@@ -208,14 +211,25 @@ auto capture_dependency_snapshot(const std::vector<std::string>& files)
     snapshot.hashes.reserve(normalized.size());
     for(const auto& file : normalized) {
         auto normalized_path = normalize_path_string(file);
+        auto hash = hash_file(normalized_path);
+        if(!hash.has_value()) {
+            return std::unexpected(CacheError{
+                .message = std::format("failed to hash dependency '{}': {}",
+                                       normalized_path, hash.error().message),
+            });
+        }
         snapshot.files.push_back(normalized_path);
-        snapshot.hashes.push_back(hash_file(normalized_path));
+        snapshot.hashes.push_back(*hash);
     }
 
     return snapshot;
 }
 
 auto dependencies_changed(const DependencySnapshot& snapshot) -> bool {
+    if(snapshot.build_at <= 0 || snapshot.files.empty()) {
+        return true;
+    }
+
     if(snapshot.files.size() != snapshot.hashes.size()) {
         return true;
     }
@@ -235,7 +249,8 @@ auto dependencies_changed(const DependencySnapshot& snapshot) -> bool {
             continue;
         }
 
-        if(hash_file(file) != snapshot.hashes[index]) {
+        auto hash = hash_file(file);
+        if(!hash.has_value() || *hash != snapshot.hashes[index]) {
             return true;
         }
     }

src/extract/extract.cppm

@@ -21,6 +21,7 @@ export import :scan;
 export import :tooling;
 export import :ast;
 export import :cache;
+export import :qualified_name;
 
 import config;
 import support;
@@ -136,7 +137,7 @@ using Ms    = std::chrono::milliseconds;
 
 struct CacheEvaluation {
     std::uint64_t compile_signature = 0;
-    std::uint64_t source_hash = 0;
+    std::optional<std::uint64_t> source_hash;
     bool scan_valid = false;
     bool ast_valid = false;
 };
@@ -161,65 +162,6 @@ void deduplicate(std::vector<T>& values) {
     values.erase(std::unique(values.begin(), values.end()), values.end());
 }
 
-auto split_top_level_qualified_name(std::string_view qualified_name)
-    -> std::vector<std::string> {
-    std::vector<std::string> parts;
-    std::string current;
-    current.reserve(qualified_name.size());
-
-    std::size_t template_depth = 0;
-    for(std::size_t index = 0; index < qualified_name.size(); ++index) {
-        auto ch = qualified_name[index];
-        if(ch == '<') {
-            template_depth++;
-            current.push_back(ch);
-            continue;
-        }
-        if(ch == '>') {
-            if(template_depth > 0) {
-                template_depth--;
-            }
-            current.push_back(ch);
-            continue;
-        }
-        if(ch == ':' && template_depth == 0 && index + 1 < qualified_name.size() &&
-           qualified_name[index + 1] == ':') {
-            parts.push_back(current);
-            current.clear();
-            ++index;
-            continue;
-        }
-        current.push_back(ch);
-    }
-
-    if(!current.empty()) {
-        parts.push_back(std::move(current));
-    }
-
-    return parts;
-}
-
-auto join_qualified_name_parts(const std::vector<std::string>& parts,
-                               std::size_t count) -> std::string {
-    std::string joined;
-    for(std::size_t index = 0; index < count; ++index) {
-        if(index > 0) {
-            joined += "::";
-        }
-        joined += parts[index];
-    }
-    return joined;
-}
-
-auto namespace_prefix_from_qualified_name(std::string_view qualified_name)
-    -> std::string {
-    auto parts = split_top_level_qualified_name(qualified_name);
-    if(parts.size() <= 1) {
-        return {};
-    }
-    return join_qualified_name_parts(parts, parts.size() - 1);
-}
-
 auto ensure_namespace_hierarchy(ProjectModel& model, std::string_view namespace_name)
     -> std::string {
     if(namespace_name.empty() ||
@@ -506,21 +448,23 @@ auto extract_project(const config::TaskConfig& config)
         auto normalized = std::filesystem::path(entry.file).lexically_normal().generic_string();
         auto compile_signature = cache::build_compile_signature(entry);
         auto source_hash = cache::hash_file(normalized);
-        if(source_hash == 0) {
-            return std::unexpected(ExtractError{
-                .message = std::format("failed to hash source file for extract cache: {}",
-                                       normalized)});
+        if(!source_hash.has_value()) {
+            logging::warn("extract cache disabled for {}: {}",
+                          normalized, source_hash.error().message);
         }
 
         CacheEvaluation evaluation{
             .compile_signature = compile_signature,
-            .source_hash = source_hash,
         };
+        if(source_hash.has_value()) {
+            evaluation.source_hash = *source_hash;
+        }
 
         if(auto cache_it = cache_records.find(normalized); cache_it != cache_records.end()) {
             const auto& record = cache_it->second;
-            if(record.compile_signature == compile_signature &&
-               record.source_hash == source_hash) {
+            if(evaluation.source_hash.has_value() &&
+               record.compile_signature == compile_signature &&
+               record.source_hash == *evaluation.source_hash) {
                 seeded_scan_cache.insert_or_assign(normalized, record.scan);
                 evaluation.scan_valid = true;
 
@@ -596,7 +540,13 @@ auto extract_project(const config::TaskConfig& config)
                                            entry.file, ast_result.error().message)});
             }
             ast_data = std::move(*ast_result);
-            ast_deps_snapshot = cache::capture_dependency_snapshot(ast_data.dependencies);
+            auto ast_deps_result = cache::capture_dependency_snapshot(ast_data.dependencies);
+            if(!ast_deps_result.has_value()) {
+                logging::warn("failed to capture AST dependency snapshot for {}: {}",
+                              normalized, ast_deps_result.error().message);
+            } else {
+                ast_deps_snapshot = std::move(*ast_deps_result);
+            }
 
             auto dt_ast = std::chrono::duration_cast<Ms>(Clock::now() - t_ast);
             logging::info("  ast: {} symbols, {} relations ({}ms)",
@@ -685,13 +635,17 @@ auto extract_project(const config::TaskConfig& config)
             }
         }
 
-        cache_records.insert_or_assign(normalized, cache::CacheRecord{
-            .compile_signature = cache_state_it->second.compile_signature,
-            .source_hash = cache_state_it->second.source_hash,
-            .ast_deps = std::move(ast_deps_snapshot),
-            .scan = cache_it->second,
-            .ast = std::move(cached_ast_copy),
-        });
+        if(cache_state_it->second.source_hash.has_value()) {
+            cache_records.insert_or_assign(normalized, cache::CacheRecord{
+                .compile_signature = cache_state_it->second.compile_signature,
+                .source_hash = *cache_state_it->second.source_hash,
+                .ast_deps = std::move(ast_deps_snapshot),
+                .scan = cache_it->second,
+                .ast = std::move(cached_ast_copy),
+            });
+        } else {
+            cache_records.erase(normalized);
+        }
 
         auto dt_file = std::chrono::duration_cast<Ms>(Clock::now() - t_file);
         logging::info("  kept: {} symbols, {} includes ({}ms)",

src/extract/qualified_name.cppm

@@ -0,0 +1,84 @@
+module;
+
+#include <cstddef>
+#include <string>
+#include <string_view>
+#include <vector>
+
+export module extract:qualified_name;
+
+export namespace clore::extract {
+
+auto split_top_level_qualified_name(std::string_view qualified_name)
+    -> std::vector<std::string>;
+
+auto join_qualified_name_parts(const std::vector<std::string>& parts,
+                               std::size_t count) -> std::string;
+
+auto namespace_prefix_from_qualified_name(std::string_view qualified_name)
+    -> std::string;
+
+}  // namespace clore::extract
+
+namespace clore::extract {
+
+auto split_top_level_qualified_name(std::string_view qualified_name)
+    -> std::vector<std::string> {
+    std::vector<std::string> parts;
+    std::string current;
+    current.reserve(qualified_name.size());
+
+    std::size_t template_depth = 0;
+    for(std::size_t index = 0; index < qualified_name.size(); ++index) {
+        auto ch = qualified_name[index];
+        if(ch == '<') {
+            template_depth++;
+            current.push_back(ch);
+            continue;
+        }
+        if(ch == '>') {
+            if(template_depth > 0) {
+                template_depth--;
+            }
+            current.push_back(ch);
+            continue;
+        }
+        if(ch == ':' && template_depth == 0 && index + 1 < qualified_name.size() &&
+           qualified_name[index + 1] == ':') {
+            parts.push_back(current);
+            current.clear();
+            ++index;
+            continue;
+        }
+        current.push_back(ch);
+    }
+
+    if(!current.empty()) {
+        parts.push_back(std::move(current));
+    }
+
+    return parts;
+}
+
+auto join_qualified_name_parts(const std::vector<std::string>& parts,
+                               std::size_t count) -> std::string {
+    std::string joined;
+    for(std::size_t index = 0; index < count; ++index) {
+        if(index > 0) {
+            joined += "::";
+        }
+        joined += parts[index];
+    }
+    return joined;
+}
+
+auto namespace_prefix_from_qualified_name(std::string_view qualified_name)
+    -> std::string {
+    auto parts = split_top_level_qualified_name(qualified_name);
+    if(parts.size() <= 1) {
+        return {};
+    }
+    return join_qualified_name_parts(parts, parts.size() - 1);
+}
+
+}  // namespace clore::extract