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

ai-memory enforces a zero-unsafe and fully-documented codebase through workspace-level Cargo lints in 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 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:

[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:

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:

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:

[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 transforms warnings into blocking errors:

- 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 resolved at the workspace root, the configuration remains centralized and tamper-proof. Developers cannot accidentally weaken lints in a single crate's 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 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 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 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 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 or main.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}