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/ron-rs/ron 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 all four use cases

• Last commit 5d ago
• 18 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 82% of recent commits

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

What it runs against: a local clone of ron-rs/ron — 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 ron-rs/ron | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.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 ≤ 35 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.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 "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/de/mod.rs" \\
  && ok "src/de/mod.rs" \\
  || miss "missing critical file: src/de/mod.rs"
test -f "src/ser/mod.rs" \\
  && ok "src/ser/mod.rs" \\
  || miss "missing critical file: src/ser/mod.rs"
test -f "src/parse.rs" \\
  && ok "src/parse.rs" \\
  || miss "missing critical file: src/parse.rs"
test -f "src/value/mod.rs" \\
  && ok "src/value/mod.rs" \\
  || miss "missing critical file: src/value/mod.rs"

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

RON (Rusty Object Notation) is a human-readable data serialization format designed to look like Rust syntax while supporting all of Serde's data model. It handles structs, enums, tuples, arrays, maps, and primitives with features like comments, trailing commas, and multiple number formats (hex, binary, float), offering a more readable alternative to JSON for Rust applications. Single-crate structure: src/de/ handles deserialization, src/ser/ handles serialization, src/value/ provides a value type abstraction, src/parse.rs implements the parser, and src/options.rs configures behavior. src/extensions.rs and docs/extensions.md document optional RON extensions. Fuzzing targets in fuzz/fuzz_targets/ and examples/ provide runnable demonstrations.

Rust developers who need config files, game data, or serialized data structures that are both human-readable and type-safe. Primary users are game developers, systems engineers, and anyone using Serde who wants config syntax that mirrors Rust rather than JSON or TOML.

Production-ready and actively maintained. The codebase shows v0.12.1 with MSRV 1.64.0, comprehensive CI/CD in .github/workflows/ci.yaml, fuzzing via cifuzz.yml through oss-fuzz integration, and high code coverage tracking. Regular dependency updates via Dependabot indicate ongoing maintenance.

Low risk for core usage. Dependencies are well-vetted (serde 1.0.181, bitflags 2.1, indexmap 2.0). The codebase is focused and stable with formal grammar documentation (docs/grammar.md). Main risk is feature additions like the indexmap feature flag dependency, but no single-maintainer bottleneck is evident from the author list.

Active development with recent CI/CD improvements (cifuzz.yml integration for OSS-Fuzz), feature flags being refined (integer128, indexmap support), and extension documentation being maintained. The CHANGELOG.md suggests regular release cycles; version 0.12.1 is recent relative to the codebase age.

git clone https://github.com/ron-rs/ron.git
cd ron
cargo build
cargo test
cargo run --example decode examples/example.ron

Daily commands: This is a library, not a runnable application. Test it via cargo test or run included examples: cargo run --example encode (serializes Rust struct to RON), cargo run --example decode_file examples/example.ron (reads RON file), or cargo run --example transcode (RON→other formats). No dev server.

• src/lib.rs — Main library entry point exposing public API (from_str, to_string, Serializer, Deserializer) that every user depends on
• src/de/mod.rs — Core deserialization logic implementing the Deserializer trait; handles parsing RON into Rust types
• src/ser/mod.rs — Core serialization logic implementing the Serializer trait; converts Rust types to RON format
• src/parse.rs — Low-level RON syntax parser; tokenizes and parses raw input into AST structures
• src/value/mod.rs — Dynamic value representation (enum Value); enables type-agnostic RON manipulation and is the foundation for value-based serialization
• src/extensions.rs — Extension configuration system (implicit_some, unwrap_newtypes, etc.) that controls serialization/deserialization behavior
• src/error.rs — Error types and span tracking; critical for user-facing error messages with position information

Add a new extension/option to control serialization/deserialization

1. Define the option flag in src/extensions.rs (e.g., struct Extensions) (src/extensions.rs)
2. Thread the option through ReaderOptions or WriterOptions in src/options.rs (src/options.rs)
3. Implement the logic in src/de/mod.rs or src/ser/mod.rs to respect the flag (src/de/mod.rs)
4. Add integration tests in tests/ to verify the new behavior (tests/extensions.rs)

Handle a new primitive type or variant

1. Add parsing logic in src/parse.rs to tokenize the new syntax (src/parse.rs)
2. Add serialization support in src/ser/mod.rs (src/ser/mod.rs)
3. Add deserialization support in src/de/mod.rs (src/de/mod.rs)
4. Update Value enum in src/value/mod.rs if a new variant is needed (src/value/mod.rs)
5. Add test cases in tests/ or in src/de/tests.rs and src/ser/tests.rs (tests/)

Improve error messages or add span tracking

1. Define or extend error types in src/error.rs (src/error.rs)
2. Update src/parse.rs to track spans during tokenization (src/parse.rs)
3. Use span utilities from src/util/span_substring.rs to extract context (src/util/span_substring.rs)
4. Test with tests/203_error_positions.rs or similar test files (tests/203_error_positions.rs)

Add support for custom data types via serde traits

1. Implement serde::Serialize and serde::Deserialize on your type (src/lib.rs)
2. Verify serialization behavior in src/ser/mod.rs handles your type (src/ser/mod.rs)
3. Verify deserialization behavior in src/de/mod.rs handles your type (src/de/mod.rs)
4. Add integration test in tests/ to ensure round-trip works (tests/big_struct.rs)

• Serde — De facto standard for Rust serialization; enables integration with vast ecosystem (databases, RPC, config systems)
• Custom parser (parse.rs) — RON has unique Rust-like syntax (tuples, enums, comments) that standard JSON/TOML parsers cannot handle; hand-rolled parser gives fine-grained control over spans and extensions
• Span-tracked errors — User-friendly error messages with source locations are critical for configuration files; spans enable precise error reporting
• Dynamic Value enum — Allows flexible, schema-free RON manipulation without deserializing to typed structs; necessary for generic tools (transcoding, validation)

• Hand-rolled parser instead of parser combinator library

  • Why: Full control over error spans, performance, and Rust-specific syntax (e.g., raw identifiers, byte strings)
  • Consequence: More code to maintain; risk of subtle parsing bugs; harder to extend for significant grammar changes

• Value enum instead of fully generic AST

  • Why: Simpler mental model; matches common use case (dynamic access); aligns with JSON Value paradigm
  • Consequence: Less precise type information during serialization; enum size overhead; cannot easily extend to custom AST nodes

• Extensions opt-in via ReaderOptions/WriterOptions

  • Why: Prevents breaking changes to stable RON spec; allows experimental features without forking
  • Consequence: Configuration complexity; users must know which options enable desired behavior; potential confusion over default behavior

• No built-in pretty-printing control in serializer

  • Why: Keeps core serializer simple; pretty printing is secondary use case
  • Consequence: Users relying on formatted output must use explicit pretty printer; small code duplication

• Not a schema validator—RON does not enforce type constraints or structural validation
• Not a streaming parser—the entire RON document must fit in memory
• Not cross-language compatible—RON is Rust-first; other languages must implement their own parsers
• Not a configuration language with environment variable expansion or macro support
• Not designed for security-critical contexts (no cryptographic signing or tamper detection)
• Not suitable for real-time or latency-critical applications requiring microsecond parsing

MSRV is 1.64.0: tested in CI, don't use newer Rust features. Span tracking for errors: internal-span-substring-test feature enables detailed error position reporting but is not for users (see clippy.toml lints). Fuzzing corpus: fuzz/ is separate workspace; requires separate cargo install cargo-fuzz setup. Unicode handling: unicode-segmentation is optional (only with internal-span-substring-test); some string operations may differ with/without it. Trailing commas: enabled by default in deserialization but requires checking PrettyConfig in serialization context.

• Serde Data Model — RON's entire design goal is to serialize/deserialize all types supported by Serde; understanding this model (primitives, newtype, unit, seq, tuple, tuple_struct, map, struct, enum, identifier) is necessary to know what RON can represent
• Visitor Pattern (Deserialization) — src/de/mod.rs implements Serde's Visitor trait; this is how RON tells Serde what data it found, and the pattern allows zero-copy and type-driven parsing
• Serializer Trait — src/ser/mod.rs implements Serde's Serializer trait to convert Rust types to RON text; understanding serialize_struct, serialize_enum, etc. is key to adding new serialization features
• EBNF Grammar — docs/grammar.md formally specifies valid RON syntax; this is the canonical reference for parser correctness and for identifying ambiguities or missing features
• Lookahead Parsing / Recursive Descent — src/parse.rs implements a recursive descent parser with single-token lookahead; understanding peek() patterns and how the parser handles backtracking is essential for fixing parse bugs
• Span/Position Tracking — src/error.rs and src/util/span_substring.rs track byte positions in the input for error reporting; this allows RON to point to exactly where syntax errors occur, improving user experience
• Feature Flags / Conditional Compilation — src/extensions.rs gates non-standard syntax (implicit generics, unwrap_newtypes) behind feature flags in Cargo.toml; this allows RON to support both strict and permissive parsing modes

• serde-rs/serde — RON is built on top of Serde; understanding Serde's Serializer/Deserializer traits is essential to modifying RON's core
• toml-rs/toml — Alternative Rust serialization format; TOML is stricter and more config-focused, RON is more flexible for data structures
• dtolnay/serde_json — JSON parser/serializer using Serde; RON's architecture mirrors serde_json's approach but with Rust-like syntax
• amethyst/specs — Game engine that popularized RON adoption for config/scene serialization; primary early use case
• rustsec/advisory-db — Security advisory tracking; relevant for auditing RON's dependencies and understanding CVE exposure

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 tests for src/value/number.rs number parsing edge cases

The repo has extensive test coverage but src/value/number.rs handling (floats, integers, 128-bit integers) lacks dedicated test cases. Given that RON supports integer128 as an optional feature and number parsing is critical for data deserialization, adding edge case tests (NaN, Infinity, denormalized floats, integer overflow boundaries, etc.) would catch regressions and improve reliability.

• [ ] Create tests/number_parsing.rs with test cases for float edge cases (NaN, Infinity, subnormals)
• [ ] Add tests for i128/u128 parsing with feature gate checks
• [ ] Add tests for number boundaries and overflow handling
• [ ] Test interop between different number types in Value
• [ ] Reference src/value/number.rs implementation details in test comments

Add missing documentation in docs/extensions.md for all extension features

The docs/extensions.md file exists but the repository supports several optional features (indexmap, integer128, bitflags integration via serde) that may not be fully documented. Contributors need clear guidance on when/how to enable each extension. This would improve discoverability for users and reduce support burden.

• [ ] Review src/extensions.rs to identify all enabled extensions
• [ ] Document indexmap feature with usage examples (docs/extensions.md)
• [ ] Document integer128 feature with type handling examples
• [ ] Document bitflags integration patterns
• [ ] Add a feature matrix table showing feature interactions
• [ ] Reference relevant examples/ files where applicable

Add integration tests for src/options.rs configuration options with end-to-end serialization/deserialization

While src/options.rs contains serialization/deserialization options, the existing test suite (tests/*.rs) doesn't show comprehensive coverage of all option combinations. Adding dedicated integration tests would ensure option behavior is correct, prevent regressions, and provide usage examples for users.

• [ ] Create tests/400_options_integration.rs for end-to-end option testing
• [ ] Test all ReflectMode variants with complex nested structures
• [ ] Test PrettyConfig combinations (depth, indentor, separator, etc.)
• [ ] Test error handling with different option configurations
• [ ] Test edge cases like deeply nested structures with specific options
• [ ] Reference src/options.rs to ensure all public APIs are tested

• Add serialization tests for the raw string and raw byte string syntax (r#"..."# and br#"..."#) in src/ser/tests.rs, as they are parsed (src/parse.rs) but test coverage is sparse.
• Improve error messages in src/error.rs: currently reports line/column for parse errors, but the span_substring module is only tested internally; write doc examples showing realistic error output for common mistakes (unmatched parens, invalid enum syntax).
• Document the difference between List vs Tuple serialization in the grammar (docs/grammar.md and README.md), as Serde's data model treats fixed-size arrays as tuples, which confuses new users coming from JSON.

The ron-rs codebase demonstrates strong security posture with no critical vulnerabilities detected. The project follows security best practices including: (1) Active fuzzing integration with OSS-Fuzz, (2) Comprehensive test coverage with security-focused test cases, (3) No hardcoded secrets or credentials visible, (4) No SQL injection, XSS, or command injection patterns present, (5) Proper dependency management with recent versions of serde and other security-aware libraries, (6) MSRV clearly defined (1.64.0). Minor improvements include completing the Cargo.toml syntax error and adding a SECURITY.md file. As a parsing/serialization library, the focus on fuzzing and parser security is appropriate.

• Low · Incomplete Dependency Declaration in Cargo.toml — Cargo.toml (dev-dependencies section). The dev-dependencies section in Cargo.toml appears to be truncated. The serde dependency declaration is incomplete with an unclosed bracket, which could indicate a build configuration error or incomplete review. Fix: Complete the serde dev-dependency declaration by closing the features array properly: features = ["std"] }
• Low · Fuzzing Infrastructure Present — fuzz/ directory. While fuzzing is a positive security practice, the presence of fuzzing targets (fuzz/fuzz_targets/from_str.rs) indicates the codebase is being tested for parser vulnerabilities. Ensure fuzzing is regularly executed and findings are tracked. Fix: Maintain active fuzzing campaigns and integrate results into CI/CD. Monitor OSS-Fuzz for reported issues (already in use per README badge).
• Low · No SECURITY.md File — Repository root. The repository lacks a SECURITY.md file to document vulnerability reporting procedures, which is a best practice for open-source projects. Fix: Create a SECURITY.md file with clear instructions for reporting security vulnerabilities privately, following responsible disclosure practices.
• Low · Dependency Version Constraints — Cargo.toml (dependencies section). Some dependencies use flexible version constraints (e.g., 'once_cell = 1.20', 'typeid = 1.0.1'). While not critical, strict pinning could reduce supply chain risk. Fix: Consider using more specific version constraints (=X.Y.Z) for critical dependencies, or document rationale for allowing patch updates.

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.