Draft: enable missing_docs lint (phase 1)

[rydrman]

Pull Request: docs: enable missing_docs lint (phase 1)

Branch: docs/missing-docs-phase-1

PR URL: https://github.com/spkenv/spk/pull/new/docs/missing-docs-phase-1

---

Summary

This is the first phase of incrementally enabling the deny(missing_docs) lint across the workspace. The goal is to improve API documentation while keeping merge requests accessible for review.

Phase 0 - Infrastructure (this PR)

• Add workspace-level warn(missing_docs) lint to Cargo.toml
• Add #![allow(missing_docs)] for generated code (FlatBuffers/protobuf) in:
  • spfs-proto/src/lib.rs
  • spfs/src/proto/mod.rs

Phase 1 - Document utility and CLI crates (this PR)

Added crate-level and module documentation to:

• is_default_derive_macro - derive macro for IsDefault trait
• parsedbuf - validated string wrapper macro
• sentry-miette - sentry integration for miette errors
• spk-schema/tera - template rendering with tera
• spfs-cli/common - shared CLI argument structures
• All spk-cli command crates (cmd-*, group*)

Upcoming Phases

This is the first of several PRs to fully enable the lint:

Phase	Target Crates	Est. Items
Phase 2	spk-solve sub-crates, spk-config, spk, spfs-cli/main	~160
Phase 3	spk-cli/common (deep), spk-solve, spk-build	~205
Phase 4	spk-solve/graph, spk-exec, spk-storage	~170
Phase 5	spk-schema, spk-schema/foundation, spfs	~1,330
Phase 6	Change workspace lint from warn to deny	-

Each subsequent phase will be a separate PR targeting ~100-150 documentation items to keep reviews manageable.

Test Plan

• cargo check --workspace succeeds with warnings (not errors)
• Generated code is properly excluded via #![allow(missing_docs)]
• CI passes

---

Changes Summary

• Files modified: 26
• Lines added: ~130
• Warnings reduced: from ~2,541 to ~2,031 (510 items documented)

Files Changed

Infrastructure

• Cargo.toml - Added missing_docs = "warn" to workspace lints
• crates/spfs-proto/src/lib.rs - Added crate docs and #![allow(missing_docs)]
• crates/spfs/src/proto/mod.rs - Added #![allow(missing_docs)] for generated code

Utility Crates

• crates/is_default_derive_macro/src/lib.rs
• crates/parsedbuf/src/lib.rs
• crates/sentry-miette/src/lib.rs
• crates/spk-schema/crates/tera/src/error.rs

SPFS CLI

• crates/spfs-cli/common/src/lib.rs
• crates/spfs-cli/common/src/args.rs

SPK CLI Commands

• crates/spk-cli/cmd-build/src/lib.rs
• crates/spk-cli/cmd-convert/src/lib.rs
• crates/spk-cli/cmd-debug/src/lib.rs
• crates/spk-cli/cmd-du/src/lib.rs
• crates/spk-cli/cmd-env/src/lib.rs
• crates/spk-cli/cmd-explain/src/lib.rs
• crates/spk-cli/cmd-install/src/lib.rs
• crates/spk-cli/cmd-make-binary/src/lib.rs
• crates/spk-cli/cmd-make-recipe/src/lib.rs
• crates/spk-cli/cmd-make-source/src/lib.rs
• crates/spk-cli/cmd-render/src/lib.rs
• crates/spk-cli/cmd-repo/src/lib.rs
• crates/spk-cli/cmd-test/src/lib.rs
• crates/spk-cli/group1/src/lib.rs
• crates/spk-cli/group2/src/lib.rs
• crates/spk-cli/group3/src/lib.rs
• crates/spk-cli/group4/src/lib.rs

[codecov]

Codecov Report

❌ Patch coverage is 11.76471% with 90 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/spfs/src/env.rs	0.00%	40 Missing ⚠️
crates/spfs/src/runtime/storage.rs	24.13%	22 Missing ⚠️
crates/spfs/src/monitor.rs	0.00%	8 Missing ⚠️
crates/spfs/src/runtime/error.rs	0.00%	7 Missing ⚠️
crates/spfs-cli/cmd-render/src/cmd_render.rs	0.00%	3 Missing ⚠️
crates/spfs-cli/common/src/args.rs	0.00%	2 Missing ⚠️
crates/spfs-cli/main/src/cmd_write.rs	0.00%	2 Missing ⚠️
crates/spfs-cli/cmd-clean/src/cmd_clean.rs	0.00%	1 Missing ⚠️
crates/spfs-cli/main/src/cmd_commit.rs	0.00%	1 Missing ⚠️
crates/spfs-cli/main/src/cmd_edit.rs	0.00%	1 Missing ⚠️
... and 3 more

📢 Thoughts on this report? Let us know!