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-unofficial/too-many-lists 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.

WAIT — Stale — last commit 2y ago

• 43+ active contributors
• Distributed ownership (top contributor 34% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ No test directory detected

_{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-unofficial/too-many-lists repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rust-unofficial/too-many-lists.

What it runs against: a local clone of rust-unofficial/too-many-lists — 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-unofficial/too-many-lists | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 677 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rust-unofficial/too-many-lists. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rust-unofficial/too-many-lists.git
#   cd too-many-lists
#
# 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-unofficial/too-many-lists and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "lists/src/lib.rs" \\
  && ok "lists/src/lib.rs" \\
  || miss "missing critical file: lists/src/lib.rs"
test -f "lists/src/first.rs" \\
  && ok "lists/src/first.rs" \\
  || miss "missing critical file: lists/src/first.rs"
test -f "lists/src/second.rs" \\
  && ok "lists/src/second.rs" \\
  || miss "missing critical file: lists/src/second.rs"
test -f "src/SUMMARY.md" \\
  && ok "src/SUMMARY.md" \\
  || miss "missing critical file: src/SUMMARY.md"
test -f "book.toml" \\
  && ok "book.toml" \\
  || miss "missing critical file: book.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 677 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~647d)"
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-unofficial/too-many-lists"
  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-unofficial/too-many-lists is an interactive Rust learning resource that teaches memory management, ownership, and data structure implementation by progressively building five different linked list implementations (singly-linked, mutable, with iterators, persistent, and unsafe). It combines mdbook-rendered tutorials in src/ with compilable Rust code in lists/src/, making it a hands-on curriculum rather than a passive reference. Dual-structure project: lists/src/ contains the actual Rust implementations (first.rs, second.rs, third.rs, fourth.rs, fifth.rs, plus silly1.rs and silly2.rs for anti-patterns), while src/ holds the mdbook curriculum chapters (first.md through fifth.md and supporting files like fifth-unsafe.md, fourth-iteration.md, etc.). Each list implementation maps 1:1 to a chapter, allowing readers to follow tutorials then study the corresponding .rs source.

Intermediate Rust learners who understand basic syntax but struggle with ownership, borrowing, and lifetimes; people transitioning from languages with garbage collection who need concrete examples of how Rust's memory model works in practice.

Actively maintained and stable. The project has comprehensive CI via .github/workflows/main.yml, structured chapters covering progressively complex patterns (first through fifth list implementations), and a polished mdbook website. No clear indicators of abandonment, though commit recency data is not visible in the provided file list.

Standard open source risks apply.

No PR or milestone data is visible in the provided file structure. The presence of fifth-*.md files (fifth-unsafe.md, fifth-stacked-borrows.md, fifth-miri.md) suggests recent focus on unsafe Rust and advanced memory model topics, likely following stabilization of the core five implementations.

git clone https://github.com/rust-unofficial/too-many-lists.git
cd too-many-lists
cargo install mdbook
mdbook build
mdbook serve  # Visit http://localhost:3000 in your browser

To run the Rust code directly: cd lists && cargo test or cargo build.

Daily commands:

cd lists
cargo test                # Run tests for all list implementations
cargo build --release   # Build optimized binaries
cargo doc --open        # View generated docs

For the book: mdbook serve from repo root.

• lists/src/lib.rs — Entry point that exports all list implementations (first through sixth) — every contributor must understand which list type to study or modify.
• lists/src/first.rs — The foundational singly-linked list implementation teaching Rust ownership and Drop semantics — the pedagogical starting point for the entire codebase.
• lists/src/second.rs — Extends first.rs with Option, generics, and iterators — demonstrates core Rust patterns that appear in all subsequent implementations.
• src/SUMMARY.md — Book table of contents that structures the learning progression — guides contributors to understand the intended teaching order and dependencies.
• book.toml — mdbook configuration defining how documentation is built and deployed — critical for maintaining the published learning resource.
• lists/Cargo.toml — Rust package manifest defining dependencies and workspace settings — controls which Rust features and external crates are available.

Add a new linked list implementation variant

1. Create a new module file in lists/src/ (e.g., lists/src/seventh.rs) with a struct and impl blocks for core operations (lists/src/seventh.rs)
2. Export the new module in lists/src/lib.rs with a public mod declaration (lists/src/lib.rs)
3. Write accompanying documentation chapter in src/seventh.md explaining design choices and implementation details (src/seventh.md)
4. Add chapter reference to src/SUMMARY.md in the appropriate position in the learning progression (src/SUMMARY.md)
5. Add unit tests in the impl block (following pattern in first.rs, second.rs, etc.) to validate correctness (lists/src/seventh.rs)

Expand documentation for an existing implementation

1. Identify the implementation's main chapter (e.g., src/second.md) and break-out topics (e.g., src/second-generic.md) (src/second.md)
2. Create new markdown file for the new topic (e.g., src/second-advanced-patterns.md) with code examples (src/second-advanced-patterns.md)
3. Update src/SUMMARY.md to register the new sub-chapter under the parent implementation heading (src/SUMMARY.md)
4. Link the new documentation to relevant code sections in lists/src/second.rs using comments and cross-references (lists/src/second.rs)

Add unsafe code analysis and documentation

1. Add // SAFETY: comments above unsafe blocks in lists/src/fifth.rs explaining invariant guarantees (lists/src/fifth.rs)
2. Create detailed documentation chapter in src/fifth-safety-analysis.md covering preconditions and invariants (src/fifth-safety-analysis.md)
3. Add miri tests in lists/src/fifth.rs to validate memory safety under stacked-borrows model (lists/src/fifth.rs)
4. Update src/SUMMARY.md to link the safety analysis chapter under the fifth list section (src/SUMMARY.md)

• Rust (systems language) — Core subject matter: the book teaches Rust ownership, borrowing, and memory safety through linked list implementation; no other language could serve the pedagogical goal
• mdbook (documentation generator) — Provides clean, indexed, searchable HTML output for the learning material; integrates seamlessly with Rust ecosystem and GitHub Pages hosting
• Box<T> (heap allocation) — First.rs uses Box to introduce owned smart pointers; essential for teaching manual memory management vs garbage collection
• Arc<T> (atomic reference counting) — Third.rs uses Arc to teach shared immutable ownership and thread-safe reference counting as alternative to exclusive ownership
• Rc<RefCell<T>> (single-threaded mutable sharing) — Fourth.rs uses this pattern to enable interior mutability in non-Send contexts; demonstrates RefCell's runtime borrow checking
• Unsafe Rust (raw pointers) — Fifth.rs deliberately uses unsafe code to teach low-level pointer manipulation and contract-based safety reasoning

• Teach Box first (first.rs) before generic types (second.rs)

  • Why: Concrete types reduce cognitive load for ownership concepts before introducing type parameters
  • Consequence: Learners must refactor first.rs to second.rs themselves; higher initial complexity but deeper understanding

• Use Arc<T> (third.rs) instead of Mutex-based concurrency

  • Why: Arc teaches shared immutability pattern; simpler than Mutex without introducing thread communication yet
  • Consequence: Third.rs is read-only; concurrent mutations deferred to sixth.rs cursor-based list

• Provide both Rc<RefCell<T>> (fourth) and unsafe pointers (fifth) for doubly-linked lists

  • Why: Different safety models teach both idiomatic Rust and unsafe pragmatism; gives learners real alternatives
  • Consequence: Two parallel implementations increase code volume but demonstrate the spectrum of control vs safety

• Emphas

  • Why: undefined
  • Consequence: undefined

No special env vars or service requirements. The main trap is that readers often try to run code snippets from mdbook chapters directly without understanding they must study the corresponding .rs file in lists/src/ to see the full implementation—the book breaks concepts into chapters, not complete runnable examples. Additionally, the fifth.rs implementation uses unsafe Rust, which requires understanding Rust's memory model deeply (stacked borrows, aliasing rules); the fifth-stacked-borrows.md chapter is essential reading before attempting modifications.

• Smart Pointers (Box<T>, Rc<T>, Arc<T>) — Core to every list implementation in this repo; understanding when to use Box (unique ownership), Rc (shared read-only), vs Arc (thread-safe shared) is essential for Rust data structures
• Lifetime Annotations and Borrow Checker — Lists with iterators (third.rs, fourth.rs) require explicit lifetime bounds; this repo teaches why the compiler needs them through concrete examples
• Interior Mutability (RefCell<T>, Cell<T>) — Second.rs uses RefCell<T> to enable mutations through immutable references; this pattern is non-obvious and critical for real-world Rust
• Iterator Trait and IntoIterator — Third and fourth implementations teach why for loops work and how to implement iterators; fifth.rs shows unsafe iterator tricks for performance
• Unsafe Rust and Stacked Borrows — Fifth.rs deliberately uses unsafe blocks to violate borrow rules; chapters fifth-unsafe.md and fifth-stacked-borrows.md teach what rules you're breaking and why
• Drop Trait and Resource Management — First.rs chapter first-drop.md explores how linked lists must implement Drop to avoid memory leaks; foundational for understanding Rust's RAII model
• Recursive Data Structures and Indirection — Linked lists fundamentally require Box<T> or pointers because Rust cannot create recursive types without a level of indirection; first.rs explains this blocker and solution

• nrc/r4cppp — Rust for C++ programmers; covers memory model basics complementary to this list-focused curriculum
• rust-lang/rustlings — Official interactive Rust exercises for syntax fundamentals; pairs well as prerequisite before tackling too-many-lists
• tokio-rs/tokio — Real-world async Rust library that heavily uses unsafe and advanced pointer patterns taught here (Rc, Pin, unsafe blocks)
• mcarton/rust-mitochondria — Another educational deep-dive into Rust's ownership semantics and unsafe code practices similar in pedagogy
• serde-rs/serde — Uses advanced trait-based patterns (visitor pattern, generics) that become clearer after mastering iterator traits in lists chapters

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 comprehensive integration tests for all list implementations in lists/src/

The repo teaches Rust through implementing 6 different linked list types (first.rs, second.rs, third.rs, fourth.rs, fifth.rs, sixth.rs) but lacks dedicated test files. Currently tests are likely embedded in the source files or missing entirely. Adding a tests/ directory with integration tests for each list type would validate implementations match their documented behavior in src/*.md chapters and provide learners with concrete test examples.

• [ ] Create lists/tests/ directory structure
• [ ] Add lists/tests/first_tests.rs validating push/pop/drop behavior from src/first*.md chapters
• [ ] Add lists/tests/second_tests.rs covering Option handling and iterators (src/second*.md)
• [ ] Add lists/tests/third_tests.rs for Arc/Rc shared ownership (src/third*.md)
• [ ] Add lists/tests/fourth_tests.rs for recursive iteration patterns (src/fourth*.md)
• [ ] Add lists/tests/fifth_tests.rs for unsafe code sections (src/fifth*.md)
• [ ] Add lists/tests/sixth_tests.rs for cursor/double-ended implementations (src/sixth*.md)

Create GitHub Action workflow to validate book builds and test code snippets

The repo has .github/workflows/main.yml but it likely doesn't validate that mdbook builds successfully or that Rust code examples in documentation compile. Adding a workflow that runs mdbook build, builds the lists crate, and optionally extracts/validates code snippets from .md files would catch documentation drift.

• [ ] Update .github/workflows/main.yml to add mdbook build step (cargo install mdbook && mdbook build)
• [ ] Add Rust toolchain setup (actions/checkout, dtolnay/rust-toolchain)
• [ ] Add step to run cargo test --manifest-path lists/Cargo.toml
• [ ] Add step to verify no Rust edition/MSRV issues (consider testing against stable, beta, nightly)
• [ ] Document the workflow changes in README.md

Add missing documentation chapters for silly1.rs and silly2.rs implementations

The file structure shows lists/src/silly1.rs and lists/src/silly2.rs exist but there are no corresponding src/silly*.md chapters in the documentation. These appear to be educational variants (perhaps alternative approaches or anti-patterns). Adding explanatory chapters would complete the learning material.

• [ ] Create src/silly1.md documenting the silly1.rs implementation with its design rationale
• [ ] Create src/silly2.md documenting the silly2.rs implementation with its design rationale
• [ ] Add entries for silly1 and silly2 to src/SUMMARY.md in the appropriate section
• [ ] Include diagrams in src/img/ if needed (similar to indy.gif, profbee.gif pattern)
• [ ] Add code examples and explain what makes these approaches 'silly' (performance, unsafety, etc.)

• Add comprehensive doc comments to lists/src/third.rs iterator implementation. Currently sparse documentation on why lifetime annotations are structured the way they are; a contributor could add examples showing lifetime bounds for each method.: Low
• Expand lists/src/silly1.rs and lists/src/silly2.rs with additional anti-pattern examples (e.g., returning references to stack-allocated data, improper Arc usage) and link from src/ chapters to explain why these fail.: Medium
• Create missing intermediate chapter: a src/transition-second-to-third.md explaining the jump from RefCell<T> (second.rs) to full iterator impl (third.rs), with diagrams of memory layout differences.: Medium

This is an educational Rust project focused on teaching linked list implementation. The security posture is generally strong with no critical or high-severity vulnerabilities identified. The project has minimal dependencies, reducing attack surface. Main recommendations include: (1) ensuring all dependencies are explicitly managed and audited, (2) completing Cargo.toml metadata, and (3) establishing a security reporting policy. As an educational resource rather than production code, the risk profile is inherently low. The codebase appears to focus on safe Rust patterns with unsafe code isolated to the fifth implementation, which aligns with the educational goals.

• Low · Minimal Dependency Information — lists/Cargo.toml. The Cargo.toml file shows no explicit dependencies listed. While this reduces attack surface, it's unclear if dependencies are intentionally absent or if the file snippet is incomplete. Educational projects may have minimal dependencies by design. Fix: Ensure all necessary dependencies are explicitly declared and regularly audited using 'cargo audit'. Consider adding dev-dependencies for testing frameworks if not present.
• Low · Missing Security Metadata — lists/Cargo.toml. The Cargo.toml lacks security-related metadata such as repository URL, homepage, license details, and edition specification. This could make it harder to track security updates and verify package authenticity. Fix: Add complete metadata to Cargo.toml including: edition (e.g., '2021'), repository, homepage, and ensure license field references the license-MIT file correctly.
• Low · No SECURITY.md Policy — Repository root. No SECURITY.md or security policy file is present in the repository. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with instructions for reporting security vulnerabilities and responsible disclosure practices.

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.