Align core crates with workspace lint policy (#200) - #228

 _______________________________________
< `NaN` is not a valid user experience. >
 ---------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

Summary

• Align workspace crates with the root lint policy.
• Enable clippy::missing_docs_in_private_items = "deny" and workspace unexpected_cfgs checks.
• Narrow Dylint filesystem exclusions and document deferred work in the workspace lint ExecPlan.
• Harden HNSW, MST, hierarchy, distance-cache, dense-provider, and SIMD paths against invalid indexing and malformed input.
• Add structured hierarchy errors and propagate failures instead of panicking.
• Refactor test fixtures, assertions, property tests, and subprocess helpers.
• Improve floating-point comparisons with total ordering and explicit conversion boundaries.
• Document private APIs and update the distance-primitives design documentation.
• Add distance-cache metrics for hits, misses, evictions, and lookup latency.

Validation

• Pass formatting, linting, type checking, tests, Markdown linting, and Nixie.
• Run 1,082 tests successfully.
• Skip 1 test.

Walkthrough

The pull request aligns workspace lint settings, adds num-traits, improves checked error handling, makes selected APIs const, refactors HNSW hierarchy and cache safety, updates provider and CLI helpers, and expands documentation and test coverage.

Changes

Workspace alignment

Poem

Lints align in ordered flight,
Checked paths replace the bite,
Errors travel, clear and true,
Const APIs gather too,
Tests find safer ground.

❌ Failed checks (2 errors, 5 warnings)

• Fix all pre-merge checks with AI

_{Comment @coderabbitai help to get the list of available commands.}

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

chutoro-core/src/mst/property/strategies.rs

Comment on file

    let mut perm: Vec<usize> = (0..node_count).collect();
    shuffle(&mut perm, rng);
    for i in 1..node_count {
    for pair in perm.windows(2) {

❌ New issue: Bumpy Road Ahead
generate_sparse has 2 blocks with nested conditional logic. Any nesting of 2 or deeper is considered. Threshold is 2 blocks per function

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

chutoro-core/src/hnsw/tests/search.rs

Comment on lines +132 to +134

    let neighbour = neighbours
        .first()
        .expect("a successful ef=1 search returns one neighbour");

❌ New issue: Large Method
layer_search_halts_on_equal_distance_candidates has 70 lines, threshold = 70

@coderabbitai review

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

Large Method

chutoro-core/src/hnsw/insert/executor/tests/mod.rs: ensure_reverse_edge_evicts_and_scrubs_forward_link

What lead to degradation?

ensure_reverse_edge_evicts_and_scrubs_forward_link has 72 lines, threshold = 70

Why does this problem occur?

Overly long functions make the code harder to read. The recommended maximum function length for the Rust language is 70 lines of code. Severity: Brain Method - Complex Method - Long Method.

How to fix it?

We recommend to be careful here -- just splitting long functions don't necessarily make the code easier to read. Instead, look for natural chunks inside the functions that expresses a specific task or concern. Often, such concerns are indicated by a Code Comment followed by an if-statement. Use the EXTRACT FUNCTION refactoring to encapsulate that concern.

@coderabbitai Have the following failed checks now been resolved?

If further work is required, please provide an AI agent prompt for the remaining work to be done to address these failures.

Do not treat warnings as optional or aspirational. Where a change is out of scope for this PR, propose a GitHub issue unless one exists already. (Treat o11y, code safety, documentation and validation coverage as in scope).

❌ Failed checks (2 errors, 5 warnings)

#!/bin/bash
set -euo pipefail

printf '%s\n' '== Current revision and changed files =='
git rev-parse HEAD
git diff --name-only "$(git merge-base HEAD origin/main)" HEAD 2>/dev/null || true

printf '%s\n' '== Hierarchy error definitions and tests =='
ast-grep outline chutoro-core/src/hierarchy --items all --view expanded
rg -n -C5 'InvalidEdgeEndpoint|extract_labels_from_mst|HierarchyErrorCode|InvalidForestReference' \
  chutoro-core/src/hierarchy chutoro-core/tests -g '*.rs'

printf '%s\n' '== Write graph marker bindings =='
rg -n -C4 'write_graph_marker_guard|let _ = &' chutoro-core -g '*.rs'

printf '%s\n' '== Documentation paths and relevant content =='
fd -t f 'users-guide\.md|developers-guide\.md|.*guide.*\.md' docs . 2>/dev/null || true
rg -n -i -C3 \
  'extract_labels_from_mst|InvalidEdgeEndpoint|distance.cache|cache.*(hit|miss|eviction|latency)|workspace lint|check-cfg|dylint|find_test_binary|bench' \
  docs -g '*.md' 2>/dev/null || true

printf '%s\n' '== Process helper and test coverage =='
ast-grep outline chutoro-test-support/src/process.rs --items all --view expanded
rg -n -C4 'find_test_binary|TestBinaryError|CARGO_BIN_EXE|NotFound|suffix' \
  chutoro-test-support -g '*.rs'

printf '%s\n' '== Const-context and trybuild coverage =='
fd -t f . | rg '(trybuild|ui|compile|const).*\.rs$|\.stderr$' || true
rg -n -i -C3 'trybuild|const .*ChutoroBuilder|estimate_peak_bytes|with_min_cluster_size' \
  chutoro-core -g '*.rs' -g 'Cargo.toml'

printf '%s\n' '== Issue 200 =='
gh issue view 200 --repo leynos/chutoro --json number,title,state,body,url

#!/bin/bash
set -euo pipefail

printf '%s\n' '== Revision and PR metadata =='
git rev-parse HEAD
gh pr view 228 --repo leynos/chutoro --json headRefOid,baseRefOid,updatedAt,url

printf '%s\n' '== Relevant changed files only =='
git diff --name-only "$(git merge-base HEAD origin/main)" HEAD | \
  rg '^(chutoro-core/src/hierarchy|chutoro-core/src/hnsw/tests/write_lock\.rs|chutoro-core/tests/trybuild|chutoro-core/tests/session_api_surface\.rs|chutoro-test-support/src/process\.rs|docs/(users|developers)-guide\.md|dylint\.toml|Cargo\.toml|[^/]+/Cargo\.toml|docs/execplans/feat-align-workspace-lint-policy\.md)$' || true

printf '%s\n' '== Endpoint validation and code coverage =='
rg -n -C8 'InvalidEdgeEndpoint|invalid.*endpoint|endpoint.*invalid|HierarchyErrorCode::' \
  chutoro-core/src/hierarchy chutoro-core/tests -g '*.rs'

printf '%s\n' '== Write graph marker bindings and fake reads =='
rg -n -C3 'write_graph_marker_guard|let _ = &' chutoro-core/src/hnsw/tests/write_lock.rs

printf '%s\n' '== User documentation relevant sections =='
rg -n -i -C5 'extract_labels_from_mst|hierarchy error|InvalidEdgeEndpoint|distance cache|hnsw.*cache|chutoro_hnsw' \
  docs/users-guide.md 2>/dev/null || true

printf '%s\n' '== Developer documentation relevant sections =='
rg -n -i -C5 'workspace lint|check-cfg|dylint|no_std_fs_operations|find_test_binary|process helper|chutoro-benches|benchmark.*inherit' \
  docs/developers-guide.md 2>/dev/null || true

printf '%s\n' '== Lint-policy plan status =='
rg -n -C3 'Remaining|defer|Deferred|complete workspace|private-item|filesystem|developer' \
  docs/execplans/feat-align-workspace-lint-policy.md

printf '%s\n' '== Workspace lint inheritance and filesystem exclusions =='
rg -n -C2 '^\[lints\]|workspace = true|missing_docs_in_private_items|unexpected_cfgs|dylint_lib' \
  Cargo.toml */Cargo.toml chutoro-providers/*/Cargo.toml 2>/dev/null
cat dylint.toml

@leynos

All seven reported checks are resolved in the current PR head: 7c0b1e2de288581eac2a87c410024c1a8eb4824e.

No AI-agent prompt is required. No new GitHub issue is required for these checks.

This result is based on static inspection of the current codegraph. Runtime validation was not executed in this environment.

_{You are interacting with an AI system.}

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

chutoro-core/src/hnsw/insert/executor/tests/mod.rs

Comment on lines +201 to +203

    let mut helpers = TestHelpers::new(&mut graph);
    helpers.enforce_bidirectional_all(2);
    let violation = helpers.find_reciprocity_violation(2);

❌ New issue: Code Duplication
The module contains 2 functions with similar structure: enforce_bidirectional_all_adds_upper_layer_backlink,enforce_bidirectional_all_removes_invalid_upper_edge

@coderabbitai review