Add clippy lints configuration to enforce codebase consistency

[aram356]

Summary

Configure clippy lints to automatically enforce coding standards and catch inconsistencies during development and CI. This will prevent new inconsistencies from being introduced.

Current State

• No .clippy.toml configuration file exists
• CI runs cargo clippy --all-targets --all-features but with default settings
• Inconsistencies in import ordering, unwrap usage, and documentation are not caught automatically

Target State

Add clippy configuration to enforce:

1. Import ordering - Group and sort imports consistently
2. Unwrap usage - Warn on unwrap() in non-test code
3. Documentation - Require docs on public items
4. Error handling - Prefer expect() over unwrap() where unavoidable

Changes Required

1. Create clippy.toml in project root

# Clippy configuration for trusted-server
# See: https://doc.rust-lang.org/clippy/configuration.html

# Cognitive complexity threshold for functions
cognitive-complexity-threshold = 30

# Maximum number of lines in a function
too-many-lines-threshold = 200

2. Add workspace-level clippy lints in Cargo.toml

[workspace.lints.clippy]
# Correctness
unwrap_used = "warn"
expect_used = "allow"  # Allow expect with context message
panic = "warn"

# Style  
module_name_repetitions = "allow"
must_use_candidate = "warn"

# Pedantic (selective)
doc_markdown = "warn"
missing_errors_doc = "warn"
missing_panics_doc = "warn"

# Restriction (selective)
print_stdout = "warn"
print_stderr = "warn"
dbg_macro = "warn"

3. Enable lints in each crate's Cargo.toml

[lints]
workspace = true

4. Add lint allows for test modules

In test code, add:

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
    // ...
}

5. Update CI workflow (.github/workflows/format.yml)

Ensure clippy runs with deny on warnings for enforced lints:

- name: Clippy
  run: cargo clippy --all-targets --all-features -- -D warnings

Lints Explanation

Lint	Purpose
unwrap_used	Catch potential panics, encourage proper error handling
panic	Explicit panics should be documented or avoided
doc_markdown	Enforce proper markdown in documentation
missing_errors_doc	Document what errors functions can return
missing_panics_doc	Document when functions can panic
print_stdout/stderr	Use logging instead of print statements
dbg_macro	Remove debug macros before committing

Testing

1. cargo clippy --all-targets --all-features - Run clippy with new config
2. Address any new warnings or add targeted #[allow(...)] with justification
3. Ensure CI passes

Complexity

Low - Configuration only, with some targeted allow annotations

Notes

• Start with warn level to identify issues without breaking builds
• Gradually promote to deny as codebase is cleaned up
• Individual exceptions can use #[allow(clippy::...)] with a comment explaining why

Labels

• good first issue
• tech-debt
• developer-experience
• ci