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/mre/idiomatic-rust 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 — Missing license — unclear to depend on

• Last commit 3mo ago
• 18 active contributors
• CI configured
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ 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 mre/idiomatic-rust repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mre/idiomatic-rust.

What it runs against: a local clone of mre/idiomatic-rust — 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 mre/idiomatic-rust | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 114 days ago | Catches sudden abandonment since generation |

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

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

# 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 "render/src/main.rs" \\
  && ok "render/src/main.rs" \\
  || miss "missing critical file: render/src/main.rs"
test -f "resources.json" \\
  && ok "resources.json" \\
  || miss "missing critical file: resources.json"
test -f "render/Cargo.toml" \\
  && ok "render/Cargo.toml" \\
  || miss "missing critical file: render/Cargo.toml"
test -f "render/templates/README.md" \\
  && ok "render/templates/README.md" \\
  || miss "missing critical file: render/templates/README.md"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 114 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~84d)"
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/mre/idiomatic-rust"
  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).

A peer-reviewed curated repository that aggregates the best articles, talks, and resources for learning idiomatic Rust patterns and best practices. It maintains a resources.json file containing structured data about Rust learning materials, which is automatically rendered into a searchable HTML website via a Rust-based template engine (Askama) in the /render directory. The README is auto-generated from this JSON source to ensure consistency across the curated list. Monorepo structure: root level contains resources.json (the single source of truth for all curated resources) and README.md (generated output). The render/ subdirectory is a standalone Rust binary (Cargo project at render/Cargo.toml) that reads resources.json, applies Askama templates from render/templates/, and outputs the final README. CI workflows in .github/workflows/ automate link validation and rendering.

Rust developers (intermediate and advanced) seeking authoritative, community-vetted resources on writing clean, idiomatic Rust code; junior Rust engineers onboarding to idiomatic patterns; and contributors who want to suggest high-quality Rust learning materials for peer review and inclusion.

Actively maintained and mature. The repo has GitHub Actions workflows for link-checking (check_links.yml) and rendering (render.yml), indicating regular automation. The codebase uses edition 2021 and modern dependencies (Askama 0.12.1, serde 1.0.228). However, the render binary is small (~500 LOC in main.rs), suggesting this is a focused, stable tool rather than a large platform.

Low risk overall. Dependencies are minimal and well-established (Askama for templating, serde for JSON, indexmap for ordered maps). The single-maintainer risk exists (mre is the primary owner), but the project's read-only nature (no user data, no complex state) limits blast radius. Link-checking CI may occasionally fail if external resources move, but that's a feature, not a bug.

The repo is in steady-state maintenance mode. It continuously collects and curates Rust learning resources via community contributions (see CONTRIBUTING.md). The check_links.yml workflow runs regularly to validate all URLs in the curated list, and render.yml regenerates the README whenever resources.json changes. No large feature work is evident, but the resource catalog is actively updated.

git clone https://github.com/mre/idiomatic-rust.git
cd idiomatic-rust
make render

The Makefile is the entry point. Running make render invokes the Rust binary in render/ to regenerate README.md from resources.json.

Daily commands:

cd render
cargo build --release
./target/release/render  # or run via: make render from root

This reads ../resources.json, applies templates from templates/, and writes the new README.md to the root. The Makefile wraps this for convenience.

• render/src/main.rs — Entry point for the resource compilation pipeline—defines how resources.json is transformed into the rendered README.
• resources.json — Single source of truth containing all curated Rust learning resources; every contributor must understand its schema to add entries.
• render/Cargo.toml — Declares template engine (askama) and serialization stack (serde/serde_json) that enable the rendering pipeline.
• render/templates/README.md — Askama template that generates the final README.md output; contributors must know how data maps to rendered content.
• CONTRIBUTING.md — Documents the contribution workflow and how to properly add resources without breaking the build process.
• .github/workflows/render.yml — Automated rendering CI/CD step that validates and regenerates README from resources.json on each commit.

• resources.json (JSON schema (untyped, but enforced by serde in Rust)) — Canonical data source storing all curated learning resources with metadata (title, URL, author, description, category)
  • Failure mode: Malformed JSON causes deserialization panic; missing required fields causes struct mismatch; broken links detected by lychee in CI
• render/src/main.rs (Rust, serde, askama, indexmap) — Main CLI binary: deserializes resources.json, passes to Askama template, writes rendered README.md to disk
  • Failure mode: Panics on invalid JSON or template errors; returns non-zero exit code for CI to catch
• Askama template (render/templates/README.md) (Askama template syntax) — Jinja2-like template that defines the structure, sections, and formatting of the final README.md output
  • Failure mode: Template syntax errors caught at cargo build time; logic errors (e.g., wrong variable names) cause undefined variable panics
• GitHub Actions (CI/CD) (GitHub Actions, lychee, git) — Automated workflows: render.yml regenerates README on each push; check_links.yml validates all URLs are live
  • Failure mode: Render failure blocks merge; broken links cause check_links.yml to fail PR checks

• Developer → resources.json — Add or edit a resource entry (title, URL, author, description, category)
• resources.json → render/src/main.rs — Developer runs 'make render'; main.rs reads and deserializes JSON
• render/src/main.rs → render/templates/README.md — Deserialized resources passed to Askama template as context
• render/templates/README.md → README.md (generated) — Template iterates resources, generates markdown sections, writes to output file
• Developer → GitHub (git push) — Commits resources.json and regenerated README.md
• GitHub Actions (render.yml) → resources.json → README.md — CI re-runs render pipeline to ensure README is up-to-date; fails if not
• GitHub Actions (check_links.yml) → README.md (all URLs) — Lychee crawler validates every resource URL is reachable; fails PR if links are broken

Add a new learning resource (article, talk, or repo)

1. Open resources.json and locate the appropriate category (e.g., 'idioms', 'embedded', 'algorithms') (resources.json)
2. Add a new JSON object with fields: title, url, author, description, and category tags (resources.json)
3. Run 'make render' locally to regenerate README.md from the updated resources.json (Makefile)
4. Commit both resources.json and the regenerated README.md; CI will validate all URLs automatically (.github/workflows/check_links.yml)

Modify the README layout or styling

1. Edit the Askama template to change how resources are grouped, formatted, or presented (render/templates/README.md)
2. Run 'make render' to regenerate README.md with the new template logic (Makefile)
3. Review the updated README.md in git diff to ensure formatting is correct (README.md)

Update rendering pipeline dependencies or logic

1. Modify Cargo.toml to add or upgrade dependencies (askama, serde, itertools, etc.) (render/Cargo.toml)
2. Update render/src/main.rs to use new dependencies or add deserialization/filtering logic (render/src/main.rs)
3. Run 'make render' and verify the output README.md is correct (Makefile)

• Askama (templating engine) — Compile-time Jinja2-like templates with zero runtime overhead; generates type-safe README.md from structured resource data
• serde + serde_json — Zero-copy, strongly-typed deserialization of resources.json into Rust structs; enables validation at compile time
• itertools — Functional combinators for grouping, filtering, and transforming resource collections without allocating intermediate collections
• GitHub Actions (render.yml + check_links.yml) — Automated validation: regenerates README on each commit and verifies all 100+ URLs are still live using lychee

• Single resources.json file vs. directory of per-category files

  • Why: Simpler to maintain a single source of truth; easier for contributors to search and understand the full schema
  • Consequence: resources.json may grow large (currently manageable at ~100 entries); no fine-grained per-category locking

• Generated README.md (committed to repo) vs. dynamic rendering at build/deploy time

  • Why: Generated README is viewable directly on GitHub without custom server; stable snapshots enable git blame and history
  • Consequence: README is out-of-sync if render step is skipped; CI enforces regeneration, but developer must run 'make render' locally first

• Compile-time Askama templates vs. runtime Handlebars/Tera

  • Why: Type safety and zero-cost abstractions; template errors caught at compile time, not runtime
  • Consequence: Requires Rust knowledge to modify templates; less flexible for dynamic template loading (not needed here)

• Does not provide a database or persistence layer for managing contributions; resources.json is the only state
• Does not implement user authentication or role-based access control; entirely pull-request driven curation
• Does not support dynamic filtering/search on the static README; sorting/searching is deferred to the external site (corrode.dev)
• Does not handle multiple versions or branching of resources; only a single canonical list per master branch

• Manual README.md edits bypassing render step — README.md: undefined

Render flow assumption: The README.md in the root is generated and should never be edited manually—all changes must flow through resources.json and make render (a git hook or CI will reject direct edits). Template assumption: The Askama template at render/templates/README.md must exist and be valid, or rendering silently fails. No hot-reload: Changes to resources.json require explicit make render invocation—updates don't auto-apply. URL validation: The check_links.yml workflow uses Lychee; be aware of .lycheeignore entries that are exempt from checking (may hide dead links).

• Static Site Generation (SSG) — This repo uses SSG via Rust templates to generate a static README from JSON data; understanding this pattern explains why the build step exists and why edits must flow through the JSON source, not the rendered output
• Idiomatic Code (Language-specific idioms) — The entire repository exists to curate and teach Rust-specific idioms—understanding what makes code 'idiomatic' (following language conventions over forcing patterns from other languages) is the core mission
• Template Engines (Askama) — Askama powers the README generation; understanding how the template at render/templates/README.md is processed is essential for modifying the output format without changing logic
• Serialization/Deserialization (serde) — The entire data flow depends on serde to deserialize resources.json into Rust structs; understanding serde traits is necessary to extend the resource schema
• CI/CD Automation (GitHub Actions) — Link validation and rendering are automated via .github/workflows/; understanding these workflows is critical for maintaining data integrity and catching broken resources automatically
• Peer Review Process (Open Source Contribution Model) — This repo emphasizes peer-reviewed resources (see CONTRIBUTING.md); the curation model is as important as the content—understanding why quality gates exist shapes how to evaluate and submit resources

• rust-unofficial/awesome-rust — Comprehensive curated list of Rust crates and resources; complements idiomatic-rust by casting a wider net on ecosystem tools, while idiomatic-rust focuses specifically on code style and best practices
• rust-lang/rust-clippy — Official Rust linter that enforces idiomatic patterns and catches anti-patterns; directly implements many of the idioms promoted by this curated list
• rust-lang/api-guidelines — Official Rust API design guidelines from the language team; featured prominently in resources.json and foundational to what 'idiomatic Rust' means
• ferrous-systems/elements-of-rust — In-depth exploration of Rust software engineering patterns; one of the flagship resources curated in this repository
• google/comprehensive-rust — Google's four-day Rust course covering all language aspects; featured as a primary learning workshop in the curated list

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 integration test for render/src/main.rs to validate resources.json parsing and template rendering

The render crate transforms resources.json into the README.md using Askama templates, but there are no visible tests to ensure the parsing and rendering pipeline works correctly. This is critical since the README is auto-generated and breaking changes could corrupt the main documentation. A test would verify that valid resources.json files are correctly parsed and that the rendered output matches expected formats.

• [ ] Create render/tests/integration_test.rs with test fixture resources
• [ ] Add tests that load resources.json and verify Askama template rendering produces valid markdown
• [ ] Add test cases for edge cases: empty resources, missing fields, special characters in URLs
• [ ] Update render/Cargo.toml if needed to ensure test dependencies (assert_matches, etc.) are available
• [ ] Document test execution in CONTRIBUTING.md

Create GitHub Actions workflow to validate resources.json schema consistency on each PR

resources.json is the single source of truth for all curated resources, but there's no automated schema validation. Contributors could accidentally introduce malformed entries (missing fields, invalid URLs, wrong structure). A dedicated validation workflow would catch these issues before merge and maintain data quality.

• [ ] Create .github/workflows/validate_schema.yml workflow file
• [ ] Implement schema validation in render/src/main.rs (or new render/src/validate.rs module) using serde to enforce required fields and types
• [ ] Run validation against resources.json in the workflow before rendering
• [ ] Add clear error messages for common schema violations
• [ ] Document schema requirements in CONTRIBUTING.md with example valid entry

Add render/tests/fixtures/ directory with test resources.json samples and expected template outputs

The render crate processes resources.json through Askama templates to generate README.md, but there are no snapshot tests to prevent regressions. Without fixture-based tests, changes to render/templates/README.md or parsing logic could silently break the generated output format.

• [ ] Create render/tests/fixtures/ directory with sample_resources.json (small, valid test data)
• [ ] Create render/tests/fixtures/expected_readme.md with reference markdown output
• [ ] Add snapshot test in render/tests/integration_test.rs comparing actual rendered output to expected fixture
• [ ] Include edge case fixtures: resources with unicode characters, very long URLs, missing optional fields
• [ ] Update Makefile render target to include test execution and document in CONTRIBUTING.md

• Add missing Rust ecosystem crate recommendations to resources.json from the Awesome Rust list or lib.rs and test the render output locally before submitting a PR.
• Expand the render/templates/README.md template to include a 'Difficulty Level' badge (beginner/intermediate/advanced) for each resource—requires modifying the JSON schema in resources.json to add a difficulty field, updating render/src/main.rs to handle it, and regenerating the template.
• Write a Rust test in render/src/main.rs that validates the structure of resources.json at compile time (e.g., using serde_json to ensure no duplicate entries, all URLs are valid format, required fields are present). This catches corruption before CI runs.

The codebase demonstrates generally good security practices as a static documentation generator. No critical vulnerabilities detected. The main risks involve template rendering safety when consuming resources.json and URL validation. The application appears to be a build-time tool rather than a runtime service, which limits exposure. Recommended actions: implement input validation for resources.json, ensure template content escaping, and maintain regular dependency audits with 'cargo audit'.

• Medium · Template Injection Risk in Askama — render/src/main.rs, render/templates/. The codebase uses Askama templating engine (v0.12.1) to render README.md from resources.json. While Askama is generally safe due to compile-time template checking, improper handling of user-controlled data in templates could lead to XSS vulnerabilities if resources.json contains untrusted content. Fix: Ensure all dynamic content from resources.json is properly escaped in templates. Validate and sanitize resources.json input. Consider implementing content security policy for rendered output.
• Low · Dependency Version Pinning — render/Cargo.toml. Dependencies in Cargo.toml use flexible version constraints (e.g., '0.12.1', '1.0.228') rather than exact pinning. This could allow automatic updates to patch versions that may introduce unexpected behavior or vulnerabilities. Fix: Consider using Cargo.lock for reproducible builds in CI/CD pipelines. For production releases, use exact version pinning with '=' operator or maintain regular dependency audits via 'cargo audit'.
• Low · Potential URL Parsing Security — render/Cargo.toml, render/src/main.rs. The url crate (v2.5.8) is used with serde feature for JSON serialization. Improper validation of URLs from resources.json before usage could lead to SSRF or malicious redirect vulnerabilities. Fix: Validate all parsed URLs against a whitelist of allowed domains before including them in rendered output. Implement URL scheme validation (only http/https).
• Low · JSON Deserialization Without Validation — render/src/main.rs. The application deserializes resources.json using serde_json without apparent input validation. Malformed or malicious JSON could cause panics or unexpected behavior. Fix: Implement proper error handling for JSON deserialization. Add schema validation for resources.json structure. Log and gracefully handle malformed input.

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.