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/yoav-lavi/melody 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 1y ago

• 4 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% 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 yoav-lavi/melody repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/yoav-lavi/melody.

What it runs against: a local clone of yoav-lavi/melody — 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 yoav-lavi/melody | 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 main exists | Catches branch renames | | 4 | Last commit ≤ 559 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "yoav-lavi/melody(\\.git)?\\b" \\
  && ok "origin remote is yoav-lavi/melody" \\
  || miss "origin remote is not yoav-lavi/melody (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main 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 559 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~529d)"
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/yoav-lavi/melody"
  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).

Melody is a Domain-Specific Language (DSL) written in Rust that compiles to ECMAScript regular expressions, prioritizing readability and maintainability over raw regex syntax. It transforms human-readable Melody code (like 16 of "na"; 2 of match { <space>; "batman"; }) into optimized regex output ((?:na){16}(?: batman){2}), solving the problem of regex incomprehensibility and maintenance burden. Rust monorepo with workspace structure: crates/melody_compiler is the core compilation engine (AST parser, code generation), crates/melody_cli wraps it with CLI commands for compile/REPL/test modes, crates/melody_wasm enables browser playgrounds, and xtask holds build utilities. The compiler crate references crates/melody_compiler/src/ast.rs and ast/ subdir for syntax tree definitions.

Developers and technical writers who need to write, maintain, or explain regular expressions in their codebases. This includes regex-heavy backend developers, security researchers building pattern matchers, and frontend engineers validating input. Users access Melody via the CLI (melody_cli), WASM bindings, or programmatically through the melody_compiler crate.

Actively developed with solid engineering practices: dual Apache/MIT licensing, GitHub Actions CI (Clippy, Rust test suite), fuzzing infrastructure (crates/melody_compiler/fuzz), benchmarking support, and a CHANGELOG tracking changes. The workspace structure and Vercel-hosted playground suggest production-oriented maturity, though as a language project it remains under active enhancement rather than stable/frozen.

Single-maintainer project (yoav-lavi owns the repo) with moderate bus factor risk. No visible breaking change policy documented in file list, and the language syntax is explicitly noted as 'may change' in README examples. Dependency surface is relatively contained (Rust ecosystem deps via Cargo.toml), but language stability for downstream users isn't guaranteed. Last maintainer commit recency would indicate health, not visible here.

Based on file structure: active language feature development (AST module organization suggests iterative syntax enhancement), fuzzing integration (fuzz/fuzz_targets/ast_fuzz.rs), benchmarking setup for performance tracking, and CLI tool expansion (REPL, test runner, shell completions). The CHANGELOG.md and PR template indicate structured release cadence.

git clone https://github.com/yoav-lavi/melody.git
cd melody
cargo build --release
cargo run --bin melody -- --help

For development: cargo build compiles both crates; cargo test runs test suite; cargo run -p melody_cli -- compile <file.melody> compiles a Melody file.

Daily commands:

# Compile a Melody file to regex
cargo run -p melody_cli -- compile <input.melody>

# Start interactive REPL
cargo run -p melody_cli -- repl

# Run tests
cargo run -p melody_cli -- test <test.melody>

# Generate shell completions
cargo run -p melody_cli -- completions <shell>

• crates/melody_compiler/src/ast.rs: Core AST definitions and parser—all Melody syntax representation and compilation logic flows through this file
• crates/melody_cli/src/main.rs: CLI entry point and command router; understand how compile, REPL, test, and completions commands dispatch to submodules
• crates/melody_cli/src/compile.rs: Wrapper around melody_compiler API for the compile command; shows how to invoke the compiler crate from CLI
• crates/melody_compiler/Cargo.toml: Defines the compiler crate as a library; understand public API surface and dependencies
• crates/melody_compiler/fuzz/fuzz_targets/ast_fuzz.rs: Fuzzing harness for parser robustness; critical for catching panics and edge cases in AST parsing
• Cargo.toml: Workspace configuration; defines all member crates and release profile optimizations (LTO, strip, codegen-units)

Adding syntax features: Edit crates/melody_compiler/src/ast.rs to extend the AST, then update parser logic in the same module. CLI changes: Modify crates/melody_cli/src/main.rs (command dispatch) and relevant submodule (e.g., compile.rs, repl.rs). Testing: Add tests to crates/melody_cli/tests/mod.rs or fuzz targets in crates/melody_compiler/fuzz/fuzz_targets/. Documentation: Update markdown in crates/melody_compiler/README.md or main README.md.

No environment variables documented in file list (check .envrc.example for dev setup if present). Fuzzing infrastructure requires cargo +nightly fuzz tooling. The .rustfmt.toml and .editorconfig enforce specific formatting—use cargo fmt before commits. WASM crate (melody_wasm) not detailed in file list but exists in workspace, so building for web targets requires additional setup. Language syntax explicitly unstable per README ('may change'), so breaking API/syntax changes are possible between versions.

• Domain-Specific Language (DSL) design — Melody is a textbook DSL—understanding syntax design, semantic analysis, and code generation patterns is central to contributing to or extending the language
• Abstract Syntax Tree (AST) construction and traversal — The ast.rs module is the heart of Melody; contributors must understand how Melody source text is parsed into an AST and then codegen'd to regex
• ECMAScript regular expression dialect — Melody's transpilation target is ECMAScript regex (JavaScript), not Perl or PCRE; understanding dialect differences (backreferences, lookahead support, named groups) is critical to implementing features correctly
• Compiler frontend vs. backend separation — Melody's architecture cleanly separates melody_compiler (parsing + AST) from melody_cli (user interaction); this pattern enables WASM and programmatic usage alongside CLI
• Fuzzing for parser robustness — The dedicated fuzz/ crate with cargo-fuzz shows investment in crash-resistance; contributors should understand how fuzzing catches parser edge cases and invalid input handling

• rust-lang/regex — Canonical Rust regex engine; Melody compiles to regex syntax compatible with JavaScript engines, but understanding Rust's regex semantics helps with cross-platform dialect concerns
• google/re2 — Industry-standard regex engine; understanding RE2's design and limitations informs Melody's transpilation target choices
• tree-sitter/tree-sitter — Alternative parser generator Rust ecosystem; if Melody were to switch from hand-rolled AST parsing, tree-sitter would be a natural candidate
• yoav-lavi/melody-playground — Official Vercel-hosted web playground for Melody, referenced in README; ships with WASM bindings and interactive editor

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 melody_cli compile and test commands

The crates/melody_cli/tests/mod.rs exists but appears minimal. The CLI has multiple important commands (compile.rs, test.rs, repl.rs) that lack dedicated integration tests. This would catch regressions in command-line behavior, output formatting, and error handling across the compiler pipeline.

• [ ] Expand crates/melody_cli/tests/mod.rs with test fixtures (sample .melody files)
• [ ] Add tests for compile command with various input files and flags
• [ ] Add tests for test command execution and output validation
• [ ] Add tests for error handling and user-facing error messages from errors.rs
• [ ] Verify output.rs formatting is tested with golden file comparisons

Add fuzzing coverage for the Pest grammar parser beyond ast_fuzz

The crates/melody_compiler/fuzz/fuzz_targets/ only contains ast_fuzz.rs. The grammar.pest file is critical infrastructure but has no dedicated fuzzing target. Adding a grammar-focused fuzzer would catch parser edge cases and malformed input handling that impacts all users.

• [ ] Create crates/melody_compiler/fuzz/fuzz_targets/grammar_fuzz.rs targeting the Pest parser directly
• [ ] Fuzz the grammar.pest parsing rules with invalid/malformed Melody syntax
• [ ] Add a separate fuzz target for the source_to_ast.rs transformation logic
• [ ] Document fuzzing instructions in crates/melody_compiler/README.md
• [ ] Consider adding corpus seeds for common Melody patterns in fuzz/corpus/

Add property-based tests for regex output correctness in melody_compiler

The crates/melody_compiler/tests/mod.rs likely tests basic compilation, but regex generation (ast_to_regex.rs) is complex and error-prone. Property-based testing with proptest would validate that generated regexes match expected behavior across input variations.

• [ ] Add proptest dependency to crates/melody_compiler/Cargo.toml
• [ ] Create property-based tests in crates/melody_compiler/tests/mod.rs for ast_to_regex.rs
• [ ] Test that valid Melody ASTs always generate valid regex syntax
• [ ] Verify generated regexes compile without errors across major regex engines
• [ ] Add round-trip tests: Melody → AST → Regex → validate matching behavior
• [ ] Document test strategy in crates/melody_compiler/README.md

• Add integration tests for the repl module (crates/melody_cli/src/repl.rs) in crates/melody_cli/tests/mod.rs—currently no visible test coverage for interactive mode beyond CLI tests
• Document the AST node types and their corresponding Melody syntax in code comments within crates/melody_compiler/src/ast.rs—help future contributors map between language features and their representation
• Expand shell completions support in crates/melody_cli/src/completions.rs to include all subcommands and flags, then add bash/zsh/fish completion tests to the CLI test suite

The Melody codebase demonstrates a strong security posture overall. As a Rust-based compiler project, it benefits from Rust's memory safety guarantees. Key findings: (1) No hardcoded secrets or credentials detected in the file structure. (2) No evidence of SQL injection, XSS, or common injection vulnerabilities in the file organization. (3) Docker/infrastructure exposure is minimal and not visible in the provided structure. (4) The project includes fuzzing infrastructure, showing security-conscious development. Minor concerns include: disabled security workflows (Miri analysis), aggressive compiler optimizations that reduce debuggability, lack of explicit dependency audit configuration, and potential WASM-specific security considerations that should be documented. The codebase would benefit from re-enabling security analysis workflows and establishing continuous fuzzing practices.

• Low · Missing SPDX License Expression in Workspace Cargo.toml — Cargo.toml. The root Cargo.toml workspace file does not specify a license field. While individual crates may have licenses, the workspace should explicitly declare its licensing terms for clarity and compliance. Fix: Add a 'license' field to the workspace Cargo.toml (e.g., 'license = "MIT OR Apache-2.0"') to explicitly declare licensing terms.
• Low · Aggressive Compiler Optimization Settings in Release Profile — Cargo.toml - [profile.release]. The release profile uses 'lto = true', 'strip = true', and 'codegen-units = 1', which significantly increase compilation time and may make debugging difficult if issues arise in production. While this improves performance, it reduces debuggability. Fix: Consider keeping debug symbols for production builds (remove 'strip = true') or use a separate 'debug-info' profile. For security-critical applications, maintainable debugging is important: 'strip = false' and '[profile.release.package.'*'] debug = true'.
• Low · Disabled Security Analysis Workflows — .github/disabled-workflows/miri.yml, .github/disabled-workflows/coverage.yml. The '.github/disabled-workflows' directory contains disabled Miri and coverage workflows. Miri is useful for detecting undefined behavior and memory safety issues. Disabled security analysis workflows reduce vulnerability detection. Fix: Re-enable Miri and coverage workflows in the CI/CD pipeline to catch memory safety issues and ensure code coverage. Move these back to '.github/workflows/' and ensure they run on relevant pull requests.
• Low · No Explicit Dependency Audit Configuration — Cargo.toml, root directory. The Cargo.toml does not show explicit security audit configurations or deny.toml for managing dependency vulnerabilities. While Rust's ecosystem has good default security, explicit configuration is best practice. Fix: Add a 'deny.toml' file in the root directory to explicitly configure dependency security policies and run 'cargo deny check' in CI/CD pipeline. Include: wildcards for advisory, unmaintained, and unsound checks.
• Low · WebAssembly WASM Crate Without Explicit Security Considerations — crates/melody_wasm/src/lib.rs. The 'melody_wasm' crate compiles Rust to WebAssembly. WASM has unique attack surface considerations (DOM access, network calls, side-channel attacks) that should be documented or enforced. Fix: Add security documentation for the WASM crate. Ensure: 1) No sensitive data in WASM memory, 2) Input validation for all external calls, 3) Clear documentation on WASM sandbox limitations, 4) Regular security audits of WASM-specific code.
• Low · Fuzzing Infrastructure Without Continuous Fuzzing — crates/melody_compiler/fuzz/. The codebase includes fuzzing targets in 'crates/melody_compiler/fuzz/' but no evidence of continuous fuzzing in CI/CD (e.g., OSS-Fuzz integration or scheduled fuzzing jobs). Fix: Integrate continuous fuzzing: 1) Add scheduled GitHub Actions to run fuzzing, 2) Consider submitting to OSS-Fuzz for continuous coverage, 3) Set up crash reproduction and reporting mechanisms.

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.