From 790977a69c63a2d394f0ed28f747e1af8e289afe Mon Sep 17 00:00:00 2001
From: brunota20 <brunot.anjos@gmail.com>
Date: Wed, 17 Jun 2026 09:24:12 -0300
Subject: [PATCH] ci: gate cargo doc warnings (-D warnings) + fix 3 broken
 intra-doc links (COW-1069)

Locks the rustdoc discipline BLEU-844 (COW-1045) introduced.

CI changes (.github/workflows/ci.yml):

- New `docs:` job runs `cargo doc --workspace --no-deps` with
  `RUSTDOCFLAGS="-D warnings"`. Any rustdoc warning (missing docs,
  broken intra-doc link, unresolved code reference) fails CI.

Source fixes surfaced by the new gate:

- `crates/nexum-engine/src/bindings.rs:8`: drop `[crate::host::impls]`
  intra-doc link; `impls` is `mod` (private) so rustdoc cannot
  resolve it. Keep the prose reference unquoted.
- `crates/nexum-engine/src/manifest/mod.rs:24`: `[load]` is
  ambiguous (sibling `fn load` + `mod load`). Disambiguate with
  `[mod@load]`.
- `crates/nexum-engine/src/manifest/types.rs:4`: same fix for
  `[super::load]` -> `[mod@super::load]`.

`#![warn(missing_docs)]` is already on `crates/shepherd-sdk/src/lib.rs`
(line 80) and `crates/shepherd-sdk-test/src/lib.rs` (line 59), so the
new CI step locks the existing baseline rather than introducing fresh
churn.

Verified locally:
  RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps  -> clean

Linear: COW-1069. Stacks on COW-1066 (CI matrix).
---
 .github/workflows/ci.yml                  | 14 ++++++++++++++
 crates/nexum-engine/src/bindings.rs       |  2 +-
 crates/nexum-engine/src/manifest/mod.rs   |  2 +-
 crates/nexum-engine/src/manifest/types.rs |  2 +-
 4 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3bbd544..d0e66fd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -55,6 +55,20 @@ jobs:
       - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
       - run: cargo test --workspace --all-features --no-fail-fast
 
+  docs:
+    name: rustdoc
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: "-D warnings"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 # master 2026-03-27
+        with:
+          toolchain: nightly
+          targets: wasm32-wasip2
+      - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+      - run: cargo doc --workspace --no-deps
+
   build-module:
     name: build ${{ matrix.module }} (wasm32-wasip2)
     runs-on: ubuntu-latest
diff --git a/crates/nexum-engine/src/bindings.rs b/crates/nexum-engine/src/bindings.rs
index d0f57dd..9ddd00c 100644
--- a/crates/nexum-engine/src/bindings.rs
+++ b/crates/nexum-engine/src/bindings.rs
@@ -5,7 +5,7 @@
 //! natively - no vendored `deps/` tree needed. The world name is fully
 //! qualified.
 //!
-//! Every `Host` trait impl in [`crate::host::impls`] consumes types
+//! Every `Host` trait impl in `crate::host::impls` consumes types
 //! generated here.
 
 wasmtime::component::bindgen!({
diff --git a/crates/nexum-engine/src/manifest/mod.rs b/crates/nexum-engine/src/manifest/mod.rs
index 9cd00b6..f58d25b 100644
--- a/crates/nexum-engine/src/manifest/mod.rs
+++ b/crates/nexum-engine/src/manifest/mod.rs
@@ -21,7 +21,7 @@
 //!
 //! - [`types`]: the serde `Manifest` shape + `LoadedManifest` the engine
 //!   actually consumes, plus the `KNOWN_CAPABILITIES` registry.
-//! - [`load`]: `module.toml` -> `LoadedManifest`, plus the host/URL
+//! - [`mod@load`]: `module.toml` -> `LoadedManifest`, plus the host/URL
 //!   helpers the `http` backend uses at request time.
 //! - [`capabilities`]: WIT-import vs declared-capabilities cross-check.
 //! - [`error`]: `ParseError`, `CapabilityViolation`.
diff --git a/crates/nexum-engine/src/manifest/types.rs b/crates/nexum-engine/src/manifest/types.rs
index 403a201..e91bff1 100644
--- a/crates/nexum-engine/src/manifest/types.rs
+++ b/crates/nexum-engine/src/manifest/types.rs
@@ -1,7 +1,7 @@
 //! Data structures: `Manifest`, sections, and `LoadedManifest`.
 //!
 //! Plain serde shapes plus the `KNOWN_CAPABILITIES` registry. The parsing
-//! and validation logic lives in [`super::load`]; capability enforcement
+//! and validation logic lives in [`mod@super::load`]; capability enforcement
 //! in [`super::capabilities`].
 
 use serde::Deserialize;