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/github/gemoji 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 6mo ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Concentrated ownership — top contributor handles 70% 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 github/gemoji repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/github/gemoji.

What it runs against: a local clone of github/gemoji — 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 github/gemoji | 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 ≤ 197 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "github/gemoji(\\.git)?\\b" \\
  && ok "origin remote is github/gemoji" \\
  || miss "origin remote is not github/gemoji (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 197 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~167d)"
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/github/gemoji"
  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).

gemoji is a Ruby library that provides a canonical database of emoji characters with their Unicode representations, aliases, and metadata. It parses the Unicode emoji test file (vendor/unicode-emoji-test.txt) into lib/emoji/character.rb objects and exposes a queryable API via lib/emoji.rb to find emoji by alias, Unicode, or name—enabling Rails apps and other Ruby projects to render emoji consistently across platforms. Monolithic gem: lib/gemoji.rb is the entry point that loads lib/emoji/character.rb class definitions and db/emoji.json (pre-parsed emoji data). db/dump.rb and db/emoji-test-parser.rb are build-time tools that generate emoji.json from vendor/unicode-emoji-test.txt. Tests validate emoji existence and documentation completeness. Scripts in script/ handle bootstrap, console REPL, release, and test execution.

Ruby/Rails developers building content management systems, chat applications, or social platforms who need to reliably translate between emoji shortcodes (:cat:), Unicode characters, and image filenames without managing emoji data themselves.

Production-ready and actively maintained. The repo has comprehensive test coverage (test/emoji_test.rb, test/documentation_test.rb), CI via .github/workflows/test.yml, and follows semantic versioning in gemoji.gemspec. The codebase is small (~23KB Ruby), stable, and well-documented in README.md with clear examples.

Low risk overall. The primary dependency is the Unicode emoji-test.txt file (vendor/unicode-emoji-test.txt), which updates annually with Unicode releases but is consumed via a dedicated parser (db/emoji-test-parser.rb) that isolates change impact. Single-maintainer risk exists but is mitigated by the static nature of the data—emoji don't break compatibility once released. No external runtime dependencies listed in Gemfile beyond development tools.

No specific recent changes visible in the file list, but the project appears stable with ongoing CI/CD setup (.github/workflows/test.yml) and Dependabot integration (.github/dependabot.yaml) for dependency updates. The codebase is in maintenance mode—focused on keeping emoji data synchronized with Unicode releases rather than new features.

git clone https://github.com/github/gemoji.git
cd gemoji
script/bootstrap
script/test

Then explore with script/console for interactive REPL access to the Emoji API.

Daily commands: No web server—this is a library gem. Run tests with script/test or use the interactive console via script/console to query emoji. To use in a Rails app, add to Gemfile and require 'emoji'.

• lib/emoji.rb: Main public API—defines Emoji.find_by_alias, find_by_unicode, find_by_name, all, create, and edit_emoji methods that users interact with.
• lib/emoji/character.rb: Core data model—Character class holds emoji name, aliases, Unicode codepoints, tags, and image_filename; add_alias and add_unicode_alias are essential for extensibility.
• db/emoji.json: Pre-parsed emoji database—loaded at gem initialization; contains all emoji metadata in JSON format for fast lookups without parsing Unicode files at runtime.
• db/emoji-test-parser.rb: Build-time Unicode parser—converts vendor/unicode-emoji-test.txt into db/emoji.json; run when updating to new Unicode emoji releases.
• vendor/unicode-emoji-test.txt: Unicode Consortium's official emoji test file—canonical source of truth for all Unicode emoji; updated annually with new releases.
• test/emoji_test.rb: Primary test suite—validates emoji lookup by alias, Unicode, name; tests custom emoji creation and alias resolution.
• gemoji.gemspec: Gem metadata and version definition—defines dependencies, gem name, and release version; required for publishing to RubyGems.

Adding emoji: Edit db/emoji.json directly or regenerate from vendor/unicode-emoji-test.txt using db/emoji-test-parser.rb, then run script/test to validate. Changing query methods: Edit lib/emoji.rb (core API) and lib/emoji/character.rb (data model). Adding tests: Extend test/emoji_test.rb for functional tests or test/documentation_test.rb for metadata validation. CI/release: Modify .github/workflows/test.yml for testing changes or script/release for deployment.

1. db/emoji.json is generated, not authored: Manual edits will be overwritten when db/emoji-test-parser.rb runs. Always modify source data or use Emoji.create/edit_emoji API. 2. Unicode version coupling: vendor/unicode-emoji-test.txt must match the Unicode release you're targeting; old emoji won't appear if file is out of sync. 3. Image filenames are not auto-generated: If you create custom emoji without specifying char.image_filename, it defaults to '{name}.png'—you must manually place that image in your app's assets. 4. No runtime dependencies but tight stdlib coupling: The gem assumes Ruby JSON parsing and basic String/Hash behavior; unusual Ruby versions may cause parse failures.

• Unicode codepoint aliasing — gemoji's core strength is mapping between multiple representation layers (shortcode → Unicode → filename); understanding codepoint vs. character vs. UTF-8 sequence is essential to avoid emoji normalization bugs.
• Build-time code generation — db/emoji-test-parser.rb generates db/emoji.json at build time so runtime doesn't pay parsing cost; this pattern separates mutable source data (Unicode files) from immutable runtime assets.
• Lazy loading and registry pattern — lib/emoji.rb loads emoji.json once at require time and caches it in memory; the static registry pattern avoids repeated parsing and makes lookups O(1) via hashes.
• Metadata-driven emoji representation — Each emoji is modeled as a Character object with multiple aliases and Unicode variants rather than hardcoded strings; this enables flexible querying and extensibility for custom emoji.
• Unicode Consortium emoji test format — vendor/unicode-emoji-test.txt follows a specific grammar (codepoints, status, names, tags) that db/emoji-test-parser.rb must parse correctly; understanding this format is required to update emoji data.
• Asset filename conventions for Unicode rendering — gemoji maps emoji to image_filename (e.g., 'unicode/1f431.png' for cat), enabling apps to serve platform-specific PNG/SVG assets instead of relying on system fonts, avoiding cross-platform rendering inconsistencies.

• iamcal/emoji-data — Alternative emoji database in JSON/CSV formats; often used alongside gemoji for projects needing richer metadata (skin tone variants, gender modifiers).
• wooorm/gemoji-unicode — Lighter Node.js alternative to gemoji; provides same alias-to-Unicode lookups for JavaScript environments without the Rails integration.
• github/emoji — GitHub's official emoji assets and API; gemoji pulls emoji test data from Unicode Consortium but GitHub maintains custom emoji and rendering rules.
• twbs/bootstrap — Commonly paired with gemoji in Rails apps to render emoji with Bootstrap styling and utilities for responsive emoji images.
• rails/rails — Primary consumer ecosystem; gemoji is typically added to Gemfile in Rails projects for content emojification in views and models.

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 Emoji.find_by_alias edge cases in test/emoji_test.rb

The README shows Emoji.find_by_alias() is a core API, but there are likely untested edge cases such as: nil/empty string inputs, case sensitivity, aliases with special characters (+-), and behavior when multiple aliases map to the same emoji. Adding these tests would prevent regressions and document expected behavior.

• [ ] Review existing tests in test/emoji_test.rb and test/test_helper.rb
• [ ] Add test cases for null/empty string inputs to find_by_alias
• [ ] Add test cases for case sensitivity variations
• [ ] Add test cases for special character handling in aliases (+ and - symbols)
• [ ] Add test cases for find_by_unicode() with invalid/edge case unicode values
• [ ] Run test suite via script/test to verify

Add validation tests in test/emoji_test.rb to ensure db/emoji.json stays in sync with vendor/unicode-emoji-test.txt

The repo maintains emoji data in db/emoji.json and has a parser (db/emoji-test-parser.rb) that reads vendor/unicode-emoji-test.txt, but there's no documented test ensuring the JSON is current. This is critical for preventing stale emoji data and broken unicode mappings.

• [ ] Review db/emoji-test-parser.rb to understand the parsing logic
• [ ] Create a new test in test/emoji_test.rb that validates emoji.json contains expected emoji counts
• [ ] Add test that spot-checks recent unicode emoji from vendor/unicode-emoji-test.txt exist in the loaded Emoji data
• [ ] Document the update process in CONTRIBUTING.md (when/how db/emoji.json should be regenerated)
• [ ] Consider adding a CI workflow check (see test.yml) that validates the data is current

Refactor lib/emoji.rb to separate the Emoji lookup API from the Character model in lib/emoji/character.rb

The main Emoji API (find_by_alias, find_by_unicode) likely lives in lib/emoji.rb alongside the Character class. Splitting these concerns would improve testability and maintainability. Currently test/emoji_test.rb likely tests both together, making it harder to isolate issues.

• [ ] Review lib/emoji.rb and lib/emoji/character.rb to identify the API layer vs data model
• [ ] Create lib/emoji/index.rb or lib/emoji/finder.rb to hold lookup methods (find_by_alias, find_by_unicode)
• [ ] Move Emoji.find_* methods into the new module/class
• [ ] Update lib/gemoji.rb exports to maintain backward compatibility
• [ ] Refactor test/emoji_test.rb to have separate test classes for Character and Finder behavior
• [ ] Run full test suite and verify no breaking changes

• Add comprehensive inline documentation to lib/emoji/character.rb describing the purpose of each emoji metadata field (name, aliases, unicode_aliases, tags) and how they map to the Unicode emoji-test.txt format—currently only hinted at in README examples.
• Extend test/emoji_test.rb with a test case that validates all emoji in db/emoji.json have at least one alias OR a valid image_filename to catch data integrity issues before gem release.
• Create a script/validate-unicode script that compares vendor/unicode-emoji-test.txt against a live Unicode release URL to warn maintainers when their local copy is stale, improving the release workflow.

The gemoji library has a relatively secure posture as a data-focused utility gem with minimal external dependencies. The primary concern is a potential XSS vulnerability in the example Rails helper code that uses .html_safe(). The recommended fixes involve stricter validation of emoji filenames and using Rails sanitization helpers. No hardcoded secrets, SQL injection risks, or infrastructure misconfigurations were detected. The codebase appears well-maintained with CI/CD and automated dependency management already in place.

• Medium · Potential XSS Vulnerability in Rails Helper Example — README.md - EmojiHelper example. The example Rails helper in README.md uses .html_safe after gsub operations. While the code does use h() for initial escaping, the regex replacement with emoji image tags could be vulnerable if the emoji.image_filename is not properly sanitized. The .html_safe call marks user-influenced content as safe without complete validation. Fix: Ensure emoji.image_filename is validated against a whitelist of known safe filenames. Consider using Rails' built-in sanitization helpers or Content Security Policy headers. Use sanitize() instead of html_safe() if possible.
• Low · Dependency Management Visibility — Gemfile, Gemfile.lock. The Gemfile and Gemfile.lock files were referenced but not provided in the analysis. Without seeing the actual dependencies, transitive dependency vulnerabilities cannot be assessed. This gem likely has minimal dependencies (it appears to be a data/utility library), but this should be verified. Fix: Regularly run bundle audit to check for known vulnerabilities in dependencies. Keep Ruby and all gems updated. Consider using Dependabot (already configured in .github/dependabot.yaml) to automate security updates.
• Low · Data Source Validation for Emoji Data — db/dump.rb, db/emoji-test-parser.rb, db/emoji.json, vendor/unicode-emoji-test.txt. The db/emoji.json and vendor/unicode-emoji-test.txt files contain data used by the library. If these files are not properly validated when loaded, malformed or malicious data could cause unexpected behavior. The db/dump.rb and db/emoji-test-parser.rb scripts should validate input. Fix: Implement schema validation for emoji.json (use JSON Schema). Verify unicode-emoji-test.txt format before parsing. Add unit tests for malformed input handling.

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.