ci: deny rustdoc breakage — workspace lints + a cargo doc job

[jensholdgaard]

Closes #124 (items 1 + 3).

• [workspace.lints.rustdoc]: broken_intra_doc_links / private_intra_doc_links / invalid_rust_codeblocks = deny, bare_urls = warn. Propagates to all member crates via [lints] workspace = true.
• Fixed the 17 existing offenders (links to private items or unresolved targets downgraded to plain code spans per the issue recipe).
• New docs CI job: cargo doc --workspace --no-deps --all-features (no RUSTDOCFLAGS override — the workspace lint table is the single source of truth, so bare_urls stays advisory in CI too); read-only token + no persisted credentials; gates merges via ci-success.needs.
• Removed a git add -A-swept local .claude/settings.json from the branch and gitignored it.

NOT included: item 2 (the one CLAUDE.md §6.6 bullet, cargo doc --workspace --no-deps --all-features) — CLAUDE.md changes go through the maintainer meta-process; flagged.

Verified: cargo doc clean, full suite green, clippy/fmt/actionlint clean.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

Summary by CodeRabbit

• Chores

  • CI now builds workspace documentation as part of the gated checks.
  • Workspace Rustdoc linting tightened to enforce stricter documentation rules.
  • .gitignore updated to exclude a machine-specific settings file.

• Documentation

  • Clarified and standardized rustdoc comment formatting across the codebase.

[jensholdgaard]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5362edea-b979-49a7-8146-6307892cbace

📥 Commits

Reviewing files that changed from the base of the PR and between 380ed47 and fcfea80.

📒 Files selected for processing (1)

• crates/ourios-bench/src/store.rs

✅ Files skipped from review due to trivial changes (1)

• crates/ourios-bench/src/store.rs

---

📝 Walkthrough

Walkthrough

Enables workspace rustdoc lints, adds a CI docs job that runs cargo doc --workspace --no-deps --all-features, and updates doc comments across crates to comply with the new lint rules; ci-success now requires the docs job.

Changes

Rustdoc Linting Enforcement and Fixes

Layer / File(s)	Summary
Rustdoc linting infrastructure Cargo.toml, .github/workflows/ci.yml, .gitignore	Workspace-level rustdoc lint configuration denies broken and private intra-doc links and invalid Rust codeblocks while warning on bare URLs. New CI docs job runs cargo doc --workspace --no-deps --all-features with a stable Rust toolchain and build cache. CI success gate extended to require the docs job. Local development allowlist file added to .gitignore.
Parquet crate intra-doc link corrections crates/ourios-parquet/src/audit_record_batch.rs, crates/ourios-parquet/src/audit_writer.rs, crates/ourios-parquet/src/writer.rs	Five broken or private intra-doc links fixed by converting link-style bracket formatting to inline code formatting in encode_rejection_reason, append_events, and append_records doc comments.
Doc comment formatting alignment across workspace crates/ourios-bench/src/store.rs, crates/ourios-core/src/audit.rs, crates/ourios-miner/src/cluster.rs, crates/ourios-miner/src/overflow.rs	Rustdoc comments in bench, core, and miner crates aligned by converting link-style bracket references to inline code formatting for consistency with the new lint standards.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hops with joy at lints so bright,
Doc links now shine in rustdoc light,
Five broken paths made straight and clean,
The finest code the world has seen!
CI checks what Claude knows best,
Rustdoc rules have passed the test. 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes one minor out-of-scope change: adding .claude/settings.json to .gitignore (accidentally committed via git add -A), which is unrelated to the core rustdoc linting objectives.	The .gitignore modification for .claude/settings.json is out-of-scope. Remove this change or clarify why it is necessary for the rustdoc linting PR objectives.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main changes: adding workspace rustdoc lints and a cargo doc CI job to prevent rustdoc breakage.
Description check	✅ Passed	The description covers the required template sections: what the PR does (Summary), closure of issue #124 (Related), and verification of checks, though the checklist items are verified in prose rather than checked boxes.
Linked Issues check	✅ Passed	The PR successfully implements items 1 and 3 from issue #124: workspace rustdoc lints [broken_intra_doc_links/private_intra_doc_links/invalid_rust_codeblocks = deny, bare_urls = warn], fixes 17 existing offenders, and adds a cargo doc CI job gating merges.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/rustdoc-lints

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR aims to prevent mechanical rustdoc breakage (broken/private intra-doc links, invalid code blocks) from reaching review by enabling workspace-level rustdoc lints and adding a cargo doc CI job, plus mechanically fixing existing doc link offenders by downgrading them to code spans.

Changes:

• Add [workspace.lints.rustdoc] configuration to deny key rustdoc breakage classes.
• Add a new CI job that runs cargo doc --workspace --no-deps --all-features with warnings denied.
• Fix existing rustdoc offenders across several crates by replacing intra-doc links to private/unresolvable targets with code spans.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Cargo.toml	Introduces workspace rustdoc lints to turn rustdoc breakage into build failures.
.github/workflows/ci.yml	Adds a dedicated cargo doc job to catch rustdoc breakage in CI.
crates/ourios-parquet/src/writer.rs	Replaces rustdoc links to private/unresolvable targets with code spans.
crates/ourios-parquet/src/audit_writer.rs	Same rustdoc-link downgrade for SUB_BATCH_ROWS.
crates/ourios-parquet/src/audit_record_batch.rs	Downgrades an unresolvable ReasonPayload rustdoc link to a code span.
crates/ourios-miner/src/overflow.rs	Downgrades a rustdoc link to docs/hazards.md to a code span to avoid rustdoc link failures.
crates/ourios-miner/src/cluster.rs	Downgrades rustdoc links to private TenantState / private fields to code spans.
crates/ourios-core/src/audit.rs	Downgrades rustdoc links to private methods/fields to code spans.
crates/ourios-bench/src/store.rs	Downgrades rustdoc links to private/cross-crate targets to code spans.
.claude/settings.json	Adds Claude tool permissions and enables a rust-analyzer plugin (not mentioned in the PR description).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/settings.json:
- Around line 5-6: The checked-in AI tool config grants broad kubectl shell
permissions via the entries "Bash(kubectl get *)" and "Bash(kubectl logs *)";
remove or replace these wildcard permissions in .claude/settings.json with
scoped commands (e.g., explicit namespaces, resource types, or parameterized
safe patterns) or remove them entirely to avoid exposing cluster data/logs.
Update the strings so they target only necessary resources (for example
"Bash(kubectl get pods -n my-namespace)" or "Bash(kubectl logs my-pod -n
my-namespace)") or delete the lines if the capability is not required.

In @.github/workflows/ci.yml:
- Around line 39-52: The docs job ("docs" / name: cargo doc) is not included in
the required aggregate CI gate (ci-success.needs), so doc failures can be
ignored; update the workflow so the "ci-success" aggregate (the job named
ci-success) lists "docs" in its needs array (or otherwise include the docs job
in the required aggregate) so the cargo doc job becomes required for ci-success
to pass; locate the job with name "docs" and the aggregate job "ci-success" and
add "docs" to ci-success's needs list.
- Around line 43-45: In the docs job, restrict GITHUB_TOKEN to read-only and
disable persisted git credentials: add a job-level permissions entry like
"permissions: contents: read" (or equivalent) and update the actions/checkout@v4
step to include "with: persist-credentials: false" so the checkout does not
leave long-lived credentials; locate the docs job and the actions/checkout@v4
step to apply these changes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e751aab-662d-472b-916e-b11fe44adc52

📥 Commits

Reviewing files that changed from the base of the PR and between dc9d809 and 8fb3939.

📒 Files selected for processing (10)

• .claude/settings.json
• .github/workflows/ci.yml
• Cargo.toml
• crates/ourios-bench/src/store.rs
• crates/ourios-core/src/audit.rs
• crates/ourios-miner/src/cluster.rs
• crates/ourios-miner/src/overflow.rs
• crates/ourios-parquet/src/audit_record_batch.rs
• crates/ourios-parquet/src/audit_writer.rs
• crates/ourios-parquet/src/writer.rs

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.