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/mustache/mustache 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 3mo ago
• 22+ active contributors
• Distributed ownership (top contributor 44% of recent commits)
• MIT 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 mustache/mustache repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mustache/mustache.

What it runs against: a local clone of mustache/mustache — 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 mustache/mustache | 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 | Last commit ≤ 105 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mustache/mustache(\\.git)?\\b" \\
  && ok "origin remote is mustache/mustache" \\
  || miss "origin remote is not mustache/mustache (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"

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

Mustache is a Ruby implementation of logic-less templating that cleanly separates view markup from business logic. It parses Mustache template syntax ({{variable}}, {{#section}}, {{>partial}}, etc.) and renders them by binding to Ruby view objects, with automatic HTML escaping for security and support for lambdas, partials, and collections. Monolithic gem structure: lib/mustache.rb is the entry point wrapping lib/mustache/*.rb modules (context.rb for variable lookup, parser.rb for template syntax, generator.rb for code generation, template.rb for the rendering engine). Examples in examples/ and benchmarks/ in benchmarks/ provide runnable demonstrations and performance validation.

Ruby developers building web applications (especially with Rails) who want to enforce strict separation between template markup and view logic, making templates easier to test, maintain, and reason about without embedded Ruby code.

Production-ready and stable. The project has a clean test suite, active GitHub Actions CI/CD pipeline (.github/workflows/test.yml), comprehensive man pages, and benchmarking infrastructure. Version 1.0+ indicates API stability, though the last commit date is not provided in the metadata—check GitHub directly for recency.

Very low risk for a templating engine. Zero external dependencies (pure Ruby implementation), well-defined scope (logic-less templates), comprehensive test coverage visible in test/ directory, and established specification via mustache.github.io ensures compatibility. Single-maintainer risk is typical for mature open-source projects of this type, but the codebase is not actively evolving—that's by design.

No active development visible from the file list—this is a mature, feature-complete project. The test.yml workflow indicates CI is maintained to ensure compatibility with new Ruby versions. The presence of benchmarks suggests historical performance tuning; new work would likely be Ruby version compatibility or minor bug fixes.

Check README for instructions.

Daily commands:

bundle exec rake test           # Run all tests
bundle exec ruby examples/simple.rb  # Run example
bundle exec ruby -Ilib bin/mustache  # CLI interface

• lib/mustache.rb: Entry point; exports the public API (render, compile, templates_dir)
• lib/mustache/parser.rb: Tokenizes and parses Mustache template syntax ({{var}}, {{#section}}, etc.) into AST
• lib/mustache/generator.rb: Converts parsed AST into executable Ruby code for efficient rendering
• lib/mustache/context.rb: Implements variable resolution and method lookup against view objects
• lib/mustache/template.rb: Core rendering engine; compiles templates and manages caching
• test/autoloading_test.rb: Smoke tests for the public API; start here to understand expected behavior
• [examples/simple.rb and examples/simple.mustache](https://github.com/mustache/mustache/blob/master/examples/simple.rb and examples/simple.mustache): Canonical example of view class + template pattern
• benchmarks/render_template_benchmark.rb: Performance baseline; useful for validating optimizations

For template syntax changes: edit lib/mustache/parser.rb (tokenization/AST), then lib/mustache/generator.rb (code generation). For rendering logic: modify lib/mustache/template.rb and lib/mustache/context.rb. For new examples: add .mustache and .rb files to examples/. For performance: use benchmarks/ scripts (render_template_benchmark.rb, etc.) to measure impact.

Template auto-discovery: calling Mustache.render without arguments relies on class name convention (e.g., class MyView expects my_view.mustache in templates_dir). Parser is whitespace-sensitive in some contexts (e.g., standalone tag handling). Lambda support requires the view method to return a Proc that receives the unrendered section as a string. HTML escaping is on by default (use triple-staches to disable); test edge cases like single quotes in Ruby >= 2.0.

• Logic-less templating — Core philosophy of Mustache; understanding why templates should have zero conditionals, loops, or arithmetic is essential to using this library correctly and appreciating its design constraints
• Visitor pattern (AST traversal) — The parser generates an AST that the generator walks via visitors to emit Ruby code; this pattern is central to how Mustache compiles templates
• Code generation — Mustache compiles templates to executable Ruby code (not interpreted at render time) for performance; understanding this trade-off is key to knowing when Mustache is fast
• Context and method resolution — Mustache resolves {{variable}} against a view object using dynamic method lookup (context.rb) with fallbacks; this enables the clean separation between template and logic
• HTML entity escaping — By default Mustache escapes &, <, >, ", and ' to prevent XSS; understanding when escaping applies ({{var}} vs {{{var}}}) is critical for security
• Lazy evaluation with lambdas — Mustache sections can be backed by Proc objects (lambdas) that receive the raw template string, enabling computed sections and advanced patterns despite being 'logic-less'
• Partial template inclusion — The {{>partial}} syntax allows composing templates from reusable fragments; understanding partial resolution (file lookup, context passing) is necessary for organizing complex templates

• ruby-template/html — Alternative Ruby templating engine (if it exists); for comparison of template syntax approaches
• thoughtbot/capybara — Common pairing: Mustache templates often tested with Capybara in Rails apps
• rails/rails — Primary integration target; Mustache templates work as Rails view format via mustache-rails gem
• mustache/mustache.github.io — Language-agnostic Mustache spec and spec tests; defines the standard all implementations follow
• janlelis/mustache-fast — Performance-focused fork or alternative Mustache implementation in Ruby (verify this exists)

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 test coverage for lib/mustache/parser.rb edge cases

The parser is a critical component that tokenizes mustache templates, but the test suite appears to rely heavily on fixture-based integration tests rather than unit tests for parser-specific edge cases. Adding targeted unit tests for the Parser class would improve maintainability and catch regressions in template syntax handling (delimiters, section nesting, escaped vs unescaped tags, etc.).

• [ ] Create test/parser_test.rb with unit tests for lib/mustache/parser.rb
• [ ] Add tests for delimiter customization ({{=<% %>=}})
• [ ] Add tests for malformed templates and error handling
• [ ] Add tests for deeply nested sections and inverted sections
• [ ] Add tests for whitespace handling around tags

Add GitHub Actions workflow for testing against multiple Ruby versions and gemsets

The repo has a test.yml workflow but it appears minimal. Given this is a widely-used templating library with Ruby version compatibility concerns, adding a matrix strategy to test against Ruby 2.7, 3.0, 3.1, 3.2, 3.3 and JRuby would catch version-specific issues early and provide confidence for users on different Ruby versions.

• [ ] Expand .github/workflows/test.yml with strategy.matrix for ruby-version
• [ ] Include Ruby 2.7, 3.0, 3.1, 3.2, 3.3 as matrix targets
• [ ] Add optional JRuby testing
• [ ] Ensure bundler caching is enabled for performance
• [ ] Verify Gemfile supports all tested Ruby versions

Add integration tests for partial rendering with nested directory structures

The fixtures directory shows partials are tested (inner_partial.mustache), but there's no explicit test coverage for the partial resolution logic in lib/mustache/template.rb when dealing with complex directory hierarchies, path resolution, and edge cases like missing partials or circular references.

• [ ] Create test/partials_test.rb with focused unit tests for partial resolution
• [ ] Add tests in test/fixtures with nested subdirectory partials structure
• [ ] Test partial path resolution with various Mustache.template_path configurations
• [ ] Add tests for missing partial error handling
• [ ] Add tests for partial context inheritance and variable scoping

• Add test coverage for edge cases in lib/mustache/context.rb around nested property access (e.g., deeply nested arrays/hashes in sections) by examining the test/ directory for gaps
• Document the code generation output in lib/mustache/generator.rb with examples showing what compiled Ruby code looks like for each tag type (helpful for maintainability)
• Create a new benchmark in benchmarks/ comparing performance of Mustache against ERB for equivalent templates to quantify the logic-less separation benefit

The Mustache Ruby template library is a well-structured logic-less templating engine with a relatively good security posture. The main security concerns are potential XSS/template injection vulnerabilities if user-controlled templates are rendered without validation, and possible path traversal risks in partial loading. The library design itself encourages separation of logic from templates, which reduces certain risks. However, documentation lacks explicit security guidance for library users. No critical vulnerabilities were identified based on the file structure analysis, but application developers using this library should implement strict input validation and follow secure integration patterns. The codebase would benefit from security-focused documentation and comprehensive security testing.

• Medium · Potential XSS Vulnerability in Template Rendering — lib/mustache/parser.rb, lib/mustache/generator.rb, lib/mustache/template.rb. Mustache is a logic-less templating engine that renders user-provided templates. While the library itself is designed to be logic-free, the parser and generator components handle template compilation and rendering. If user-controlled data is used to construct template paths or content without proper validation, it could lead to template injection attacks. The presence of files like parser.rb and generator.rb suggests dynamic template processing that may be vulnerable if inputs are not sanitized. Fix: 1. Validate and sanitize all user-provided template content before rendering. 2. Use allowlists for template paths and variable names. 3. Document security best practices for library users in CONTRIBUTING.md. 4. Implement Content Security Policy (CSP) headers in applications using this library. 5. Consider adding security warnings to README.md about proper usage.
• Medium · Potential Path Traversal in Partial Loading — lib/mustache/template.rb, lib/mustache/context.rb. The file structure indicates support for partials (template_partial.mustache, partial_with_module.mustache). Partial file paths may be constructed from user input. Without proper path validation, attackers could potentially use directory traversal sequences (../) to load unintended template files from the filesystem, potentially exposing sensitive information or executing unintended templates. Fix: 1. Implement strict path validation for all partial file loading. 2. Use realpath() to resolve canonical paths and verify they are within the intended directory. 3. Maintain a whitelist of allowed partial directories. 4. Sanitize partial names to reject sequences like '../' and absolute paths. 5. Add security tests for path traversal attempts.
• Low · Missing Security Headers Documentation — README.md, CONTRIBUTING.md. The README and documentation do not include security best practices or warnings for developers using this library. There is no mention of input validation, output encoding, or XSS prevention strategies when integrating Mustache with web applications. Fix: 1. Add a 'Security Considerations' section to README.md. 2. Document proper escaping and output encoding practices. 3. Warn against rendering untrusted templates. 4. Provide examples of secure integration patterns. 5. Link to OWASP guidelines for template injection prevention.
• Low · No Visible Input Validation in Utils Module — lib/mustache/utils.rb. The utils.rb module likely contains utility functions for string handling and HTML escaping. Without reviewing the actual code, there's a risk that HTML escaping may be incomplete or context-inappropriate (e.g., escaping for HTML vs. JavaScript contexts). Fix: 1. Verify that HTML escaping uses a well-established library rather than custom implementation. 2. Ensure escaping is context-aware (HTML, JavaScript, URL, CSS). 3. Add comprehensive unit tests for edge cases in escaping. 4. Consider using a dedicated security library for output encoding.
• Low · Test Fixtures May Contain Sensitive Data — test/fixtures/. The test/fixtures directory contains various test data files. While these appear to be test examples, fixtures should be reviewed to ensure no actual credentials, API keys, or sensitive information are stored even in test data. Fix: 1. Review all fixture files for any hardcoded credentials or sensitive data. 2. Use placeholder values (e.g., 'test_value', 'example_key') instead of real data. 3. Add a pre-commit hook to prevent accidental commit of secrets. 4. Document fixture guidelines in CONTRIBUTING.md.

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.