If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rust-lang-nursery/rust-cookbook shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 48+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• CC0-1.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rust-lang-nursery/rust-cookbook repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rust-lang-nursery/rust-cookbook.

What it runs against: a local clone of rust-lang-nursery/rust-cookbook — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rust-lang-nursery/rust-cookbook | Confirms the artifact applies here, not a fork | | 2 | License is still CC0-1.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rust-lang-nursery/rust-cookbook. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rust-lang-nursery/rust-cookbook.git
#   cd rust-cookbook
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rust-lang-nursery/rust-cookbook and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rust-lang-nursery/rust-cookbook(\\.git)?\\b" \\
  && ok "origin remote is rust-lang-nursery/rust-cookbook" \\
  || miss "origin remote is not rust-lang-nursery/rust-cookbook (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC0-1\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC0-1\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC0-1.0" \\
  || miss "license drift — was CC0-1.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "book.toml" \\
  && ok "book.toml" \\
  || miss "missing critical file: book.toml"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "src/SUMMARY.md" \\
  && ok "src/SUMMARY.md" \\
  || miss "missing critical file: src/SUMMARY.md"
test -f "build.rs" \\
  && ok "build.rs" \\
  || miss "missing critical file: build.rs"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rust-lang-nursery/rust-cookbook"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Rust Cookbook is a curated collection of ~100 runnable, copy-paste-ready code examples demonstrating idiomatic Rust patterns across the ecosystem. It covers algorithms, concurrency, web development, and safety-critical code using real crates (rand, crossbeam, image, serde, etc.), all tested in CI and rendered as an mdbook guide. It solves the problem of new Rustaceans finding trustworthy, working examples for common tasks without wading through incomplete StackOverflow snippets. Workspace monorepo: root Cargo.toml includes 4 member directories under crates/ (algorithms, concurrency, development_tools, safety_critical, web). Each category contains sub-crates like crates/algorithms/randomness with src/bin/ binaries for individual examples (rand.rs, passwd.rs, etc.). The mdbook source lives alongside as book.toml, with CI in .github/workflows/ and deployment via ci/deploy.sh to gh-pages.

Junior-to-intermediate Rust programmers learning ecosystem best practices, and developers migrating to Rust who need battle-tested recipes for file I/O, random numbers, parallel processing, or serialization. Contributors are documentation-focused community members (not necessarily core Rust team) who improve examples and add new recipes.

Actively maintained but not rapidly evolving. The repo shows mature structure (workspace layout, CI/CD pipelines in .github/workflows/, spellcheck + link validation, Makefile for common tasks) and uses a stable mdbook build (pinned to v0.4.43). Commit recency and issue backlog are not visible in provided data, but the edition pinned to 2018 (Cargo.toml) with workspace edition 2024 in config suggests incremental modernization.

Low risk for a documentation/example repo. Dependencies are pinned to stable versions (rand 0.9, clap 4.5, chrono 0.4, etc.) with no major version chaos. The main risk is the dual-edition mismatch (root package is edition 2018, workspace is 2024), which could cause subtle compilation surprises. Single-maintainer risk exists (curator listed as Andrew Gauger) but community contribution model mitigates this.

The visible state shows active maintenance: CI includes mdbook-test.yml (compiles all examples), check-links.yml (validates URLs), spellcheck.yml (enforces dictionary ci/dictionary.txt), and deploy-mdbook.yml (publishes to GitHub Pages). The Makefile provides dev, test, build, serve, and deploy targets, indicating active development workflow. No specific PR or milestone data is visible, but the infrastructure is modern (GitHub Actions, not Travis).

git clone https://github.com/rust-lang-nursery/rust-cookbook
cd rust-cookbook
cargo install mdbook --vers "0.4.43"
make serve

OR for offline reading: mdbook serve --open builds to ./book/index.html.

Daily commands: Development: make serve (starts mdbook on http://localhost:3000 with live reload). Testing: make test (compiles and runs all crate examples). Building: make build (outputs to ./book/). Deployment: make deploy (requires maintainer permissions to push gh-pages branch).

• book.toml — mdBook configuration defining the cookbook's structure, styling, and output settings—required to understand how content is organized and rendered.
• Cargo.toml — Workspace root manifest declaring all member crates and shared package metadata; essential for understanding the project's dependency graph and build structure.
• src/SUMMARY.md — mdBook table of contents defining the complete navigation structure and recipe organization across all chapters.
• build.rs — Build script that prepares examples and validates cookbook content at compile time; critical for understanding how examples are tested.
• Makefile — Development workflow orchestration with targets for building, testing, serving, and deploying; go-to reference for local development practices.
• .github/workflows/mdbook-test.yml — CI pipeline that validates all examples compile and run correctly; defines the quality gate every contribution must pass.
• CONTRIBUTING.md — Contributor guidelines specifying example structure, testing requirements, and documentation standards for new recipes.

• Content Layer (src/) (Markdown, mdBook syntax, embedded code blocks) — Markdown recipes organized by topic; links to example code; provides narrative explanation and learning context.
  • Failure mode: Broken links, outdated advice, unclear examples lead to reader confusion and failed implementations.
• Example Crates (crates/*/) (Cargo, Rust 2021 edition, ecosystem crates (rand, tokio, rayon, leptos, etc.)) — Standalone, compilable Rust code organized in member crates; each example is a complete, runnable program.
  • Failure mode: Compilation errors, runtime panics, or outdated dependencies cause CI failures and block releases.
• Build & Test Pipeline (CI/CD) (GitHub Actions, bash) — GitHub Actions workflows that compile examples, run tests, validate links, and deploy the built book.

Add a new category of recipes

1. Create a new markdown file in src/algorithms/ or appropriate directory, e.g., src/algorithms/sorting.md (src/algorithms/sorting.md)
2. Add an entry in src/SUMMARY.md under the appropriate chapter heading (src/SUMMARY.md)
3. Link to embedded example code snippets in the markdown file (src/algorithms/sorting.md)

Add a new runnable example

1. Create a new binary file in crates/{category}/{subcategory}/src/bin/{example}.rs (crates/algorithms/randomness/src/bin/rand.rs)
2. Write a complete, self-contained example with all imports and a fn main() (crates/algorithms/randomness/src/bin/rand.rs)
3. Create or update the corresponding markdown recipe in src/{category}/{subcategory}/{recipe}.md (src/algorithms/randomness/rand.md)
4. Embed the example in the recipe markdown using include macros or code fences (src/algorithms/randomness/rand.md)
5. Run make test to verify the example compiles and runs (Makefile)

Add a new member crate for a topic area

1. Create directory structure: crates/{category}/{topic}/ (crates/algorithms/randomness)
2. Add Cargo.toml with dependencies and bin targets matching example files (crates/algorithms/randomness/Cargo.toml)
3. Add the crate to [workspace].members in root Cargo.toml (Cargo.toml)
4. Populate src/bin/ with example binaries and update documentation (crates/algorithms/randomness/src/bin)

• mdBook — Lightweight static site generator purpose-built for Rust documentation; renders Markdown to responsive HTML with built-in search and offline support.
• Cargo workspace — Organizes examples as independent, compilable member crates; enables each example to be copied directly into new projects without modification.
• GitHub Actions — Runs example code as part of CI to guarantee correctness; free for public repos and integrates seamlessly with PR workflow.
• Rust ecosystem crates — Cookbook showcases real-world crates (rand, rayon, tokio, leptos, etc.); examples demonstrate idiomatic Rust practices.

• Each example is a standalone binary, not embedded in markdown

  • Why: Allows 100% verification via CI compilation; users can copy-paste and run immediately.
  • Consequence: Slight duplication between markdown snippets and actual code; requires two-place updates when fixing examples.

• Member crates grouped by topic, not flattened into single crate

  • Why: Mirrors the book's structure; users see the exact directory layout they should replicate.
  • Consequence: More Cargo.toml files to maintain; slower initial builds when many examples are compiled.

• Static site generation (mdBook) instead of dynamic backend

  • Why: Low operational overhead, infinite scale on GitHub Pages, instant page loads, offline-readable.
  • Consequence: No server-side functionality; cannot dynamically generate or validate examples at read-time.

• Does not teach Rust language fundamentals—assumes reader has basic Rust knowledge.
• Does not provide production-grade libraries—examples prioritize clarity over performance.
• Does not offer interactive REPL or playground—examples are meant to be copied and run locally.
• Does not maintain version compatibility guarantees—focuses on stable, recent crate versions.

1. Edition mismatch: root package is 2018, workspace is 2024—this can cause subtle feature/syntax differences in sub-crates. Verify the correct edition in Cargo.toml when adding examples. 2. mdbook version pinning: examples must compile against mdbook 0.4.43 specifically (ci/install_deps.sh enforces this), not latest; test locally with this exact version. 3. Spellcheck dictionary: CI runs ci/spellcheck.sh against ci/dictionary.txt; domain-specific terms or project names must be added to avoid CI failure. 4. No indicated private keys or secrets, but ci/deploy.sh requires GitHub write permissions on gh-pages branch—maintainer-only operation.

• Workspace monorepo — Rust Cookbook uses Cargo workspaces to organize category-specific crates (algorithms, concurrency, web, safety_critical) under one root, enabling shared dependencies and unified CI; understanding this pattern is essential for scaling multi-crate projects.
• Example-per-binary pattern — Each recipe is a standalone src/bin/*.rs binary (e.g., crates/algorithms/randomness/src/bin/rand.rs), making examples copy-paste-ready and independently testable; this design choice is central to the Cookbook's usability.
• mdbook static site generation — Rust Cookbook is rendered from Markdown into HTML via mdbook (not a dynamic app), enabling offline reading and GitHub Pages hosting; contributors must understand this flow to add new chapters.
• CI/CD with GitHub Actions — The Cookbook uses .github/workflows/ for automated testing (mdbook-test.yml compiles all examples), link checking, spellchecking, and deployment; this ensures examples never break between releases.
• Edition management in Rust — The Cookbook has a hidden edition mismatch (root 2018, workspace 2024) that requires careful handling; understanding Rust editions (2015, 2018, 2021, 2024) is critical for maintaining backward compatibility across examples.
• Idiomatic Rust patterns — The Cookbook's entire purpose is to demonstrate idiomatic patterns (error handling with Result/anyhow, iterator adapters, ownership semantics) rather than 'correct but non-idiomatic' code; contributors must align examples with the Rust API guidelines.
• Ecosystem crate selection (rand, crossbeam, serde) — The Cookbook relies on a curated set of well-maintained ecosystem crates (rand for RNG, crossbeam for concurrency, serde for serialization); understanding why these are chosen over alternatives (e.g., rand vs. oorandom, crossbeam vs. rayon) helps contributors evaluate new recipes.

• rust-lang/rust-by-example — Official Rust language documentation with examples; complementary to Cookbook but focuses on language syntax, not ecosystem crates.
• tokio-rs/tokio — Async runtime used in many Cookbook examples; primary dependency for web and concurrency recipes.
• serde-rs/serde — Serialization framework appearing implicitly in many Cookbook examples; de facto standard for data encoding/decoding.
• rust-lang/crates.io — Upstream crate registry; Cookbook examples pull from crates.io and serve as trusted examples of published crates.
• rust-lang-nursery/api-guidelines — Sibling Rust community project providing design philosophy; Cookbook examples should follow these guidelines for consistency.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add mdbook-test validation for all example binaries in CI

The repo uses mdbook to generate documentation from Rust examples, but the current CI workflows (check-links.yml, mdbook-test.yml, spellcheck.yml) don't have explicit validation that all binaries in crates//src/bin/.rs are actually tested. Many example binaries like choose.rs, custom.rs, dist.rs, actor_pattern.rs, etc. exist but there's no guarantee they compile or their output is validated. Adding a CI job to enumerate and test all binaries would catch bitrot early.

• [ ] Create a new GitHub Action workflow file .github/workflows/test-all-binaries.yml
• [ ] Add a step that runs 'cargo test --bins' for each workspace member in crates/*/
• [ ] Integrate output validation by checking that 'cargo build --bins' succeeds for all members
• [ ] Document the new workflow in CONTRIBUTING.md with a note about maintaining example binaries

Add missing workspace member testing for crates/web and crates/development_tools subdirectories

The workspace configuration includes crates/web and crates/development_tools/debugging/tracing, but the Makefile and CI scripts appear to only test individual crate directories. The test_script.sh in ci/ doesn't show explicit coverage of all nested workspace members. This creates a risk that changes to web examples or tracing examples aren't properly validated in CI.

• [ ] Review ci/test_script.sh and update it to explicitly test 'cargo test -p <crate>' for web and tracing members
• [ ] Add a test matrix in .github/workflows/mdbook-test.yml that covers all workspace members from Cargo.toml
• [ ] Update Makefile with a 'make test-all' target that runs tests for each workspace member separately
• [ ] Document the workspace structure in CONTRIBUTING.md

Create edition consistency checker and upgrade path from 2018 to 2021

The root Cargo.toml uses edition '2024' in workspace.package but the main [package] uses edition '2018', and workspace members likely vary. This inconsistency can cause subtle compatibility issues. A lint or CI check ensuring all members use a consistent edition (ideally 2021 as a minimum) would improve maintainability and modernize the examples.

• [ ] Add a xtask command in xtask/src/main.rs to check all Cargo.toml edition fields for consistency
• [ ] Create .github/workflows/check-edition.yml that runs 'cargo xtask check-edition' to fail if inconsistent
• [ ] Create a migration guide in CONTRIBUTING.md with steps to upgrade all members from 2018 to 2021
• [ ] Run the migration and update all Cargo.toml files in the workspace

• Add missing examples to crates/concurrency/: The structure shows actor, custom_future, and parallel directories, but no visible src/bin binaries. Identify what async/concurrency patterns are missing (e.g., tokio spawn, async channels, select!) and create runnable example binaries following the crates/algorithms/randomness/src/bin/ pattern.
• Expand safety_critical/ category with real examples: The crates/safety_critical/ directory exists in workspace members but no binaries are visible in the file list. Research Rust safety-critical patterns (unwrap avoidance, panic safety, no_std) and add 3–5 documented examples with tests.
• Update deprecated dependencies and test against Rust 2024 edition: Several dependencies (e.g., lazy_static 1.0 is deprecated in favor of once_cell/std::sync::OnceLock) are still in use. Create a tracking issue, update Cargo.lock, verify all examples still compile, and migrate the workspace to a consistent edition.

The rust-cookbook repository has moderate security concerns. The most critical issues are the invalid Rust edition configuration (2024) and incomplete dependency definitions that will prevent compilation and testing. These prevent examples from being properly verified. Additionally, the lack of automated security auditing in CI/CD is concerning given that this cookbook serves as a reference for many developers' production code. The dependency versions are not critically outdated but should be regularly audited. The codebase itself appears well-structured with proper use of GitHub workflows for automated checks, but security-specific scanning is absent. Immediate fixes required: correct the edition field, complete the num dependency, and add cargo-audit to CI/CD.

• High · Invalid Rust Edition in Workspace Configuration — Cargo.toml - workspace.package.edition. The workspace.package section specifies edition = "2024", which is not a valid Rust edition. Valid editions are 2015, 2018, and 2021. This will cause build failures and prevent the cookbook examples from being compiled and tested properly, potentially masking other security issues. Fix: Update to a valid edition: edition = "2021". This is the latest stable edition and provides better security features and language improvements.
• High · Incomplete Dependency Definition — Cargo.toml - dependencies section (incomplete 'num' entry). The Cargo.toml has an incomplete dependency entry 'num' at the end of the dependencies list with no version specified. This will cause build failures and prevents proper dependency resolution. Fix: Complete the dependency entry by specifying a version: num = "0.4" (matching the other num-related dependencies already defined).
• Medium · Outdated and Potentially Vulnerable Dependencies — Cargo.toml - dependencies section. Several dependencies use older versions that may contain known vulnerabilities: base64 0.22.1, image 0.24, crossbeam 0.8, and others. While this is a cookbook of examples, it still demonstrates practices to users who may copy these versions into production code. Fix: Regularly audit and update dependencies to their latest stable versions using 'cargo audit' and 'cargo update'. Consider using tools like dependabot for automated updates.
• Medium · Missing Security Audit Configuration — .github/workflows/ - missing security audit workflow. No evidence of cargo-audit or security scanning in CI/CD workflows. The repository contains example code used as reference by many developers, making security critical. Fix: Add a GitHub Actions workflow to run 'cargo audit' on all dependencies regularly. Example: Create .github/workflows/cargo-audit.yml to check for known vulnerabilities.
• Low · Multiple CI/CD Systems Configured — .travis.yml and appveyor.yml files. The repository uses both .travis.yml and appveyor.yml in addition to GitHub Actions. This creates maintenance overhead and potential inconsistencies in what gets tested. Fix: Consolidate to GitHub Actions only (.github/workflows/) and remove legacy CI configurations. This reduces configuration debt and ensures consistent testing.
• Low · No Security Policy Documentation — Repository root - missing SECURITY.md. No SECURITY.md file found to document security reporting procedures and vulnerability disclosure policy. Fix: Add a SECURITY.md file documenting: how to report security vulnerabilities privately, expected response times, and the security update process for dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.