# How ai-memory's Clippy Workspace Lints Enforce unsafe_code and missing_docs

> Learn how ai-memory's clippy workspace lints enforce unsafe_code and missing_docs. Discover how Cargo lints and CI ensure a zero-unsafe, fully-documented codebase.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-30

---

**ai-memory enforces a zero-unsafe and fully-documented codebase through workspace-level Cargo lints in [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml), combined with CI that runs Clippy with `-D warnings` to upgrade all warnings to hard errors.**

The `akitaonrails/ai-memory` repository maintains strict code quality standards across its multi-crate Rust workspace. By centralizing lint configuration in the workspace root and enforcing it in CI, the project guarantees that no `unsafe` code can be committed and that all public APIs remain documented.

## Workspace-Level Rust Lints in Cargo.toml

The foundation of ai-memory's lint policy lives in the root [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) file. This configuration applies automatically to every crate in the workspace without requiring per-crate duplication.

### unsafe_code = "forbid"

The `[workspace.lints.rust]` section declares:

```toml
[workspace.lints.rust]
unsafe_code = "forbid"
missing_docs = "warn"

```

The `unsafe_code = "forbid"` setting makes any use of the `unsafe` keyword a **compile-time error**. This is stronger than `deny`—it cannot be overridden with `allow` attributes in source code. When a developer attempts to write:

```rust
fn dangerous() {
    unsafe { /* ... */ }   // ← compile-time error
}

```

The Rust compiler immediately fails with:

```

error: use of unsafe code is forbidden by the `unsafe_code` lint
 --> src/lib.rs:2:5
  |
2 |     unsafe { /* ... */ }
  |     ^^^^^^^

```

This **fail-fast guarantee** prevents unsafe code from ever entering the build pipeline, let alone the repository.

### missing_docs = "warn"

The same `[workspace.lints.rust]` section sets `missing_docs = "warn"`, which triggers warnings for any public item lacking documentation comments:

```rust
pub fn compute(a: i32) -> i32 { a + 1 }  // ← warning: missing documentation

```

While this produces only a warning locally, the CI configuration (detailed below) promotes it to an error.

## Workspace-Level Clippy Lints

Beyond the Rust compiler's built-in lints, ai-memory configures **Clippy** at the workspace level:

```toml
[workspace.lints.clippy]
all = { level = "warn", priority = -1 }

```

The `clippy.all` setting enables **all available Clippy lints** at the warning level for every crate in the workspace. The `priority = -1` ensures this baseline applies unless specifically overridden.

Individual crates can opt into additional lints (such as `pedantic` or `nursery` groups), but the workspace guarantees a comprehensive minimum standard everywhere.

## CI Enforcement with -D warnings

The GitHub Actions workflow in [`.github/workflows/ci.yml`](https://github.com/akitaonrails/ai-memory/blob/main/.github/workflows/ci.yml) transforms warnings into blocking errors:

```yaml
- run: cargo clippy --workspace --all-targets -- -D warnings

```

The `-D warnings` flag tells Clippy to **upgrade every warning to an error**. This has two critical effects in ai-memory:

- **Compiler lint warnings become errors**: The `missing_docs` warnings from `workspace.lints.rust` are treated as failures, blocking any PR with undocumented public APIs.
- **Clippy warnings become errors**: The `clippy.all` warnings (plus any crate-specific additions) also fail the build, preventing style or correctness issues from merging.

Because CI uses the same [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) resolved at the workspace root, the configuration remains **centralized and tamper-proof**. Developers cannot accidentally weaken lints in a single crate's [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) to bypass the policy.

## How the Three Layers Work Together

| Layer | Mechanism | Enforcement Point |
|-------|-----------|-----------------|
| **Rust compiler** | `unsafe_code = "forbid"` in `[workspace.lints.rust]` | Compile-time error, local and CI |
| **Rust compiler** | `missing_docs = "warn"` in `[workspace.lints.rust]` | Warning locally, error in CI |
| **Clippy** | `all = "warn"` in `[workspace.lints.clippy]` | Warning locally, error in CI |
| **CI gate** | `cargo clippy -- -D warnings` | GitHub Actions failure |

This layered approach ensures **consistent developer experience**: identical rules run locally and in CI, with no surprises. The `unsafe_code` prohibition triggers immediately at compile time, while documentation and Clippy quality gates enforce policy at the pull request boundary.

## Summary

- ai-memory's [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) uses `[workspace.lints.rust]` to forbid all `unsafe` code and warn on missing docs across every crate
- `[workspace.lints.clippy]` enables comprehensive Clippy warnings as a baseline for the entire workspace
- The CI workflow in [`.github/workflows/ci.yml`](https://github.com/akitaonrails/ai-memory/blob/main/.github/workflows/ci.yml) runs `cargo clippy --workspace --all-targets -- -D warnings` to treat all warnings as errors
- Together, these mechanisms create a **fail-fast, zero-configuration guarantee** that the codebase remains safe-by-construction and well-documented

## Frequently Asked Questions

### Can individual crates override the unsafe_code = "forbid" setting?

No. The `forbid` level is absolute and cannot be overridden with `#[allow(unsafe_code)]` or crate-level attributes. This is intentional—the workspace root controls the policy, and individual crates cannot weaken it. Only modifying the root [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) could change this rule.

### What happens if I add a public function without documentation?

Locally, `cargo build` or `cargo clippy` emits a warning. When you push to GitHub, the CI job fails because `-D warnings` promotes it to an error. The pull request is blocked until you add a doc comment (`///` or `//!`) to the public item.

### Does ai-memory use any additional Clippy lint groups?

The workspace baseline uses `clippy.all`. Individual crates may enable `pedantic`, `nursery`, or other groups in their own [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) files under `[lints.clippy]`, but these are additive—the workspace `all` setting still applies globally.

### Why use workspace.lints instead of adding attributes to source files?

`[workspace.lints]` centralizes policy in a single, version-controlled location. It eliminates duplication across dozens of crates, prevents accidental misconfiguration, and ensures that `cargo clippy --workspace` uses identical rules everywhere. This scales better than maintaining `#![deny(...)]` attributes in every [`lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/lib.rs) or [`main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/main.rs).