perf(cache): inline normalization functions to reduce allocations

[KingingWang]

Summary

• Inlined normalize_crate_name and normalize_version directly into cache key generation methods to avoid intermediate String allocations in hot paths
• Added #[inline] hints to validation helper functions (is_valid_crate_name_char, is_valid_item_path_char, is_valid_crate_name, is_valid_item_path)
• Removed obsolete comment line in html.rs

Performance Impact

The cache key generation functions are called frequently (hot path: src/tools/docs/cache/key.rs was accessed 12x in recent sessions). By inlining normalization logic:

• Eliminates intermediate String allocations from separate normalization functions
• Reduces function call overhead in the hot path
• #[inline] hints allow compiler to further optimize validation checks

Test Plan

• Run cargo test --test unit to verify all unit tests pass
• Run cargo clippy --all-targets -- -D warnings to verify no clippy warnings
• Verify cache key generation still produces correct, normalized keys

[KingingWang]

PR Review: perf(cache): inline normalization functions to reduce allocations

Overall: The changes are sound and the performance optimization is valid. All tests pass and clippy is clean. Below are specific observations:

Code Quality

Positive:

• Inlining normalization logic eliminates unnecessary function calls and intermediate String allocations in hot paths
• #[inline] hints on validation helpers are appropriate given their small size and frequent use
• Documentation updated to reflect the change (removed "via normalize_crate_name" references)
• All 291 unit tests pass; clippy clean

Minor issues:

1. Code duplication (src/tools/docs/cache/key.rs:63,69,105,113): The expression version.map(|v| v.trim().to_lowercase()) is repeated 4 times. While the goal is to avoid allocations, this repetition could be reduced with a local variable:

   let normalized_ver = version.map(|v| v.trim().to_lowercase());

   This is already done for normalized_name — applying the same pattern to version would improve consistency without any performance cost.

2. Removed doc comment (key.rs:6-11): The normalize_crate_name function had useful documentation explaining why normalization is needed (case-insensitivity on crates.io). This context is now lost. Consider adding a brief comment at the call sites or module level explaining the normalization rationale.

Potential Bugs

None found. The behavior is identical to the original implementation — all existing tests pass, including edge cases for whitespace, case insensitivity, injection prevention, and unicode handling.

Security

No concerns. The validation and hashing logic for injection prevention remains intact. Invalid crate names still produce hashed keys.

Suggestions

1. Add a local normalized_ver variable in crate_cache_key and item_cache_key to avoid repeating the closure 4 times (consistency + readability, zero perf impact).

2. Preserve the "crate names are case-insensitive on crates.io" rationale as a module-level comment or in the doc comments for crate_cache_key/item_cache_key.

opencode session  |  github run

[KingingWang]

/oc 感谢 review！针对提出的建议：

Suggestion #1 (代码重复)：已修复。将 version normalization 提取为本地变量 normalized_ver，与 normalized_name 保持一致，消除4处重复。

Suggestion #2 (文档注释)：已添加。在 crate_cache_key 和 item_cache_key 的文档注释中加入 "crate names are case-insensitive on crates.io" 的说明。

更改已提交并推送：c1d70ae

[KingingWang]

UnknownError: "Upstream error from Alibaba: Request rate increased too quickly. To ensure system stability, please adjust your client logic to scale requests more smoothly over time."

opencode session  |  github run

[KingingWang]

PR Review: perf(cache): inline normalization functions to reduce allocations

Summary

The changes are sound. Inlining normalization logic into cache key generation methods is a valid optimization that eliminates intermediate String allocations in hot paths. All tests pass and formatting is clean.

Code Quality

Positive:

• #[inline] hints on validation helpers are appropriate for small, frequently-called functions
• Documentation updated to reflect the change (removed "via normalize_crate_name" references)
• Normalization rationale preserved in doc comments for crate_cache_key and item_cache_key

Minor issue:

The expression version.map(|v| v.trim().to_lowercase()) is repeated 4 times across crate_cache_key and item_cache_key. While already extracted as normalized_ver in both functions (lines 59, 102), the inline closure pattern is still visible. This is already well-handled — no action needed.

Potential Bugs

None found. Behavior is identical to the original implementation. All existing tests pass including edge cases for whitespace, case insensitivity, injection prevention, and unicode handling.

Security

No concerns. The validation and hashing logic for injection prevention remains intact. Invalid crate names still produce hashed keys.

Suggestions

1. Consider benchmarking — If not already done, a simple criterion benchmark comparing before/after would quantify the allocation savings and validate the performance claim.

2. Empty version edge case — crate_cache_key("serde", Some("")) produces "crate:serde:" (trailing colon). This is existing behavior, not introduced by this PR, but worth noting as a potential inconsistency.

Verdict: Approve — Clean, safe optimization with no behavioral changes.

opencode session  |  github run