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/awesome-print/awesome_print 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

• 24+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

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

What it runs against: a local clone of awesome-print/awesome_print — 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 awesome-print/awesome_print | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 662 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "lib/awesome_print.rb" \\
  && ok "lib/awesome_print.rb" \\
  || miss "missing critical file: lib/awesome_print.rb"
test -f "lib/awesome_print/inspector.rb" \\
  && ok "lib/awesome_print/inspector.rb" \\
  || miss "missing critical file: lib/awesome_print/inspector.rb"
test -f "lib/awesome_print/formatter.rb" \\
  && ok "lib/awesome_print/formatter.rb" \\
  || miss "missing critical file: lib/awesome_print/formatter.rb"
test -f "lib/awesome_print/formatters/base_formatter.rb" \\
  && ok "lib/awesome_print/formatters/base_formatter.rb" \\
  || miss "missing critical file: lib/awesome_print/formatters/base_formatter.rb"
test -f "lib/awesome_print/colorize.rb" \\
  && ok "lib/awesome_print/colorize.rb" \\
  || miss "missing critical file: lib/awesome_print/colorize.rb"

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

Awesome Print is a Ruby gem that pretty-prints Ruby objects with full ANSI color syntax highlighting, proper indentation, and intelligent formatting of nested structures. It exposes the internal structure of objects (arrays, hashes, ActiveRecord models, etc.) in a human-readable format and integrates with Rails templates and multiple ORMs (Mongoid, Sequel, NoBrainer) via extension modules in lib/awesome_print/ext/. Modular monolith structure: core formatting engine in lib/awesome_print/formatter.rb and lib/awesome_print/formatters/ directory (base_formatter.rb, array_formatter.rb, hash_formatter.rb, etc.); optional ORM/framework extensions under lib/awesome_print/ext/ (active_record.rb, mongoid.rb, rails-specific action_view.rb); core_ext/ patches standard Ruby classes (Kernel, Object, String, Logger) to expose the ap method.

Ruby and Rails developers who need better debugging output in IRB/Pry consoles and development logs. Specifically: backend engineers working with complex object hierarchies, Rails developers inspecting ActiveRecord instances, and ops engineers reviewing logs with colored structured output.

Production-ready and actively maintained. The project has clear semantic versioning (v1.9.0 is current with v2.0 planned), comprehensive test coverage with RSpec, Travis CI integration (.travis.yml present), and code quality monitoring via CodeClimate. It supports Rails 5.0–6.1 and multiple ORM versions, indicating long-term stability.

Low-risk, single-maintainer project with stable API surface. Main concerns: explicit EOL stated for Ruby < 2.4 and Rails < 3.0 (note in README); last commit age not visible in provided data but .travis.yml and Appraisals suggest active CI/CD. Dependency surface is minimal (no Gemfile gems listed), making it safe to integrate.

No active PR/milestone data visible, but project structure suggests maintenance mode with occasional ORM version bumps (Appraisals lists Mongoid 5.0–7.1, Rails 5.0–6.1 gemfiles), indicating periodic updates to support new library versions.

git clone git://github.com/awesome-print/awesome_print.git
cd awesome_print
bundle install
bundle exec rspec

Daily commands:

bundle exec rspec              # Run test suite
bundle exec appraise rails-6.1 rspec  # Test against specific Rails version
bundle exec rubocop           # Check code style per .rubocop.yml

• lib/awesome_print.rb — Main entry point and public API setup that initializes the library and loads all core functionality
• lib/awesome_print/inspector.rb — Core orchestrator that coordinates the formatting pipeline, manages options, and delegates to specific formatters
• lib/awesome_print/formatter.rb — Central formatter dispatcher that routes objects to appropriate specialized formatters based on type
• lib/awesome_print/formatters/base_formatter.rb — Abstract base class defining the formatter interface and shared utility methods for all specific formatters
• lib/awesome_print/colorize.rb — Handles all ANSI color code generation and styling logic for pretty-printed output
• lib/awesome_print/core_ext/kernel.rb — Defines the global ap method injected into Kernel, making pretty-printing available everywhere in Ruby

• Inspector — Orchestrates the entire formatting pipeline; manages options, recursion depth, and output control

Add Support for a New Object Type

1. Create a new formatter class in lib/awesome_print/formatters/ that extends BaseFormatter (lib/awesome_print/formatters/base_formatter.rb)
2. Implement the _format method to return the formatted string representation (lib/awesome_print/formatters/your_formatter.rb)
3. Register the formatter in lib/awesome_print/formatter.rb by adding a case statement in the dispatcher (lib/awesome_print/formatter.rb)
4. Add tests in spec/formats_spec.rb or create a new spec file for your type (spec/formats_spec.rb)

Add Integration with an External Library

1. Create a new extension file in lib/awesome_print/ext/ following the pattern of existing extensions (lib/awesome_print/ext/active_record.rb)
2. Define an extension module that overrides _format method for the library's objects (lib/awesome_print/ext/your_library.rb)
3. Load the extension conditionally in lib/awesome_print/formatter.rb when the library is available (lib/awesome_print/formatter.rb)
4. Add integration tests in spec/ext/ directory (spec/ext/your_library_spec.rb)

Customize Color Scheme

1. Review the default color configuration in lib/awesome_print/colorize.rb (lib/awesome_print/colorize.rb)
2. Set custom defaults using AwesomePrint.defaults hash in your application initializer (lib/awesome_print/custom_defaults.rb)
3. Pass color options to individual ap() calls via the :color parameter (lib/awesome_print/inspector.rb)

Add a New Configuration Option

1. Define the option and default value in AwesomePrint.defaults hash handling (lib/awesome_print/custom_defaults.rb)
2. Add option parsing in lib/awesome_print/inspector.rb constructor (lib/awesome_print/inspector.rb)
3. Use the option in the appropriate formatter classes (lib/awesome_print/formatters/base_formatter.rb)
4. Add tests verifying the option behavior in spec/formats_spec.rb or spec/misc_spec.rb (spec/misc_spec.rb)

• Ruby (core language) — This is a Ruby library for Ruby developers; uses Ruby's reflection and metaprogramming capabilities
• ANSI color codes — Standard for terminal coloring across Unix/Linux/macOS and modern Windows terminals; no external dependencies
• Monkey-patching via core_ext — Allows injection of ap method globally and seamless integration into existing Ruby applications without explicit imports in every file
• Strategy pattern (formatters) — Extensible architecture allowing new formatters for different object types without modifying core logic

• Monkey-patching Kernel and Object classes

  • Why: Makes the library extremely convenient for users (just ap object)
  • Consequence: Can cause namespace pollution and conflicts with other libraries that similarly extend Kernel; requires careful naming

• Recursive formatting with indentation tracking

  • Why: Produces readable, hierarchical output of nested structures
  • Consequence: Requires careful stack management and cycle detection to avoid infinite recursion on circular references

• Optional framework extensions loaded conditionally

  • Why: Keeps core library lightweight; only loads ActiveRecord/Mongoid support if those gems are present
  • Consequence: Adds complexity to formatter dispatcher logic with library detection checks

• ANSI color codes baked into output

  • Why: Defaults to colorized, readable output for terminal display
  • Consequence: Colors appear as escape sequences in non-terminal contexts; users must disable colors for file/log output

• Not a JSON/YAML serializer — this is for human-readable debugging output, not data interchange
• Not a replacement for logging frameworks — integrates with loggers but is primarily a REPL/console tool
• Not cross-platform terminal support for Windows cmd.exe without modern terminal emulators — targets ANSI-compliant terminals
• Not a performance profiler — prints objects, doesn't analyze execution time

1. Ruby version cliff: Code explicitly does not support Ruby 2.4 or older (see README NOTE) — check RUBY_VERSION in tests. 2. Rails-optional: awesome_print works standalone but some features (action_view.rb, active_record.rb) only load if Rails is present; conditional requires in lib/awesome_print/ext/ handle this. 3. Gemfile appraisals: Testing against multiple Rails/Mongoid versions requires bundle exec appraise, not plain bundle exec. 4. Color output assumes terminal: html: false (default) outputs ANSI codes; set html: true for non-terminal environments or strip codes manually.

• ANSI Escape Codes — awesome_print's core visual feature relies on terminal color escapes; lib/awesome_print/colorize.rb generates these sequences, and understanding them is essential to extending color support
• Strategy Pattern (Formatters) — Formatters in lib/awesome_print/formatters/ implement the Strategy pattern; each subclass of BaseFormatter handles a different object type, allowing new types to be plugged in without modifying core dispatcher
• Ruby Introspection & Reflection — awesome_print relies on Ruby's Method, Class, Object#instance_variables, respond_to?, and kind_of? to inspect object internals; understanding these APIs is critical for extending formatters
• Mixin & Monkey-Patching — awesome_print injects the ap method globally via lib/awesome_print/core_ext/kernel.rb; core_ext modules show safe patterns for extending built-in classes without breaking compatibility
• Recursive Tree Formatting — The formatter must handle arbitrarily nested structures (arrays within hashes, custom objects with instance variables); understanding the recursion strategy in lib/awesome_print/formatter.rb is key to extending it
• ORM Adapter Pattern — lib/awesome_print/ext/ contains adapters for ActiveRecord, Mongoid, Sequel, etc.; each adapter hooks into awesome_print's type detection to provide custom formatting — useful model for supporting external libraries

• thoughtbot/airborne — HTTP API testing DSL for Ruby; often used alongside awesome_print to debug JSON response bodies in tests
• pry/pry — Advanced Ruby REPL; awesome_print integrates with Pry and is frequently used in Pry sessions for object inspection
• rails/rails — Rails framework; awesome_print provides first-class extensions (active_record.rb, action_view.rb) for Rails objects
• mongoid/mongoid — MongoDB ORM for Ruby; awesome_print includes dedicated Mongoid formatter (lib/awesome_print/ext/mongoid.rb) with multi-version Appraisals
• ruby/ruby — Core Ruby language; awesome_print relies on introspection APIs (Method, Class, respond_to?) and follows Ruby style conventions

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 custom formatter extensions

The repo has 11 formatter extensions in lib/awesome_print/ext/ (active_record, mongoid, sequel, nokogiri, etc.) but the spec/ext/ directory only contains tests for 4 of them. Missing tests for action_view, mongo_mapper, active_support, ripple, ostrich, nobrainer, and nokogiri extensions create blind spots for regressions when these ORMs/libraries release new versions.

• [ ] Create spec/ext/ripple_spec.rb with integration tests for Ripple models
• [ ] Create spec/ext/sequel_spec.rb with integration tests for Sequel models
• [ ] Create spec/ext/nobrainer_spec.rb with integration tests for NoBrainer models
• [ ] Create spec/ext/ostruct_spec.rb with tests for OpenStruct formatting
• [ ] Create spec/ext/nokogiri_spec.rb with tests for XML/HTML node formatting
• [ ] Add missing tests for lib/awesome_print/ext/mongo_mapper.rb in spec/ext/mongo_mapper_spec.rb
• [ ] Verify each test file covers both basic and edge-case object formatting

Add GitHub Actions CI workflow to replace/supplement Travis CI

The repo uses .travis.yml for CI but GitHub Actions is now the native GitHub platform solution. The Appraisals file and multiple gemfiles (rails_5.0 through rails_6.1, mongoid versions) suggest the repo tests against many dependency combinations. A GitHub Actions workflow would provide faster, more reliable CI with better integration into pull request reviews.

• [ ] Create .github/workflows/test.yml with matrix strategy for Ruby versions 2.5-3.1
• [ ] Add matrix jobs for each gemfile in gemfiles/ directory (Rails 5.0-6.1, Mongoid 5.0-7.1)
• [ ] Include linting step using .rubocop.yml configuration
• [ ] Add CodeClimate coverage reporting using CODECLIMATE_REPO_TOKEN
• [ ] Test that workflow passes on a feature branch before merging
• [ ] Optionally deprecate .travis.yml in a follow-up PR

Add missing unit tests for core_ext extensions and colorize module

The lib/awesome_print/core_ext/ directory contains 7 core extension files (awesome_method_array, class, kernel, logger, method, object, string) but spec/core_ext/ only has tests for logger and string. Additionally, lib/awesome_print/colorize.rb has no corresponding test file. These extensions add methods to Ruby core classes and need robust test coverage to ensure compatibility across Ruby versions.

• [ ] Create spec/core_ext/awesome_method_array_spec.rb testing AwesomePrint::AwesomeMethodArray integration
• [ ] Create spec/core_ext/class_spec.rb testing Class#awesome_print method injection
• [ ] Create spec/core_ext/kernel_spec.rb testing ap() and its options
• [ ] Create spec/core_ext/method_spec.rb testing Method#awesome_print behavior
• [ ] Create spec/core_ext/object_spec.rb testing Object#awesome_print integration
• [ ] Create spec/colorize_spec.rb testing color application, ANSI codes, and color disable options
• [ ] Add edge cases: nil values, empty collections, deeply nested structures, color output in non-TTY environments

• Add formatter for Set (lib/awesome_print/formatters/set_formatter.rb): Set is a stdlib type but not in the visible formatters list; pattern-match off Hash formatter logic.
• Document all color option keys in README: the code defines :bigdecimal, :rational, :struct, :keyword but README color example doesn't show all keys — add missing entries with examples.
• Add test coverage for lib/awesome_print/custom_defaults.rb: file appears important (custom_defaults.rb) but no test file mentioned; write spec to cover custom configuration merging.

The awesome_print library has moderate security posture. Primary concerns are: (1) potential XSS risks when formatting output for web views without proper escaping, (2) exposure of sensitive object attributes during inspection, and (3) risk of code execution from custom inspect methods on untrusted objects. The codebase lacks explicit security hardening for handling untrusted input. Recommendations include implementing output escaping in view integrations, adding attribute filtering/whitelisting, and documenting security implications of inspecting untrusted objects. Dependencies should be regularly audited and CI/CD security should be strengthened.

• Medium · Potential XSS Risk in HTML Output Formatting — lib/awesome_print/ext/action_view.rb, lib/awesome_print/formatters/. The awesome_print library is designed to format and display Ruby objects, including Rails views via action_view extension. Without explicit output escaping, formatted strings containing user-controlled data could be rendered as HTML in views, potentially leading to XSS attacks. Fix: Ensure all user-controlled data is properly escaped before rendering in views. Use Rails' built-in XSS protection mechanisms. Review action_view extension to confirm HTML safety markers are properly applied to output strings.
• Medium · Unsafe Object Inspection of User Data — lib/awesome_print/inspector.rb, lib/awesome_print/formatters/object_formatter.rb. The library introspects arbitrary Ruby objects including their internal attributes and methods. When used with untrusted objects (e.g., from external sources), this could expose sensitive internal state, database connection details, or API credentials stored in object attributes. Fix: Implement filtering mechanisms to prevent exposure of sensitive attributes. Add configuration options to blacklist/whitelist which attributes are displayed. Document security considerations for users displaying untrusted objects.
• Medium · Potential Code Execution via Custom Inspect Methods — lib/awesome_print/inspector.rb, lib/awesome_print/formatters/base_formatter.rb. The library calls inspect and other methods on arbitrary objects. Maliciously crafted objects with overridden inspect methods could execute arbitrary code during the formatting process. Fix: Implement timeout protections for inspect operations. Consider using safer inspection mechanisms with restricted method calls. Add warnings in documentation about inspecting untrusted objects.
• Low · Missing or Incomplete Security Headers in CI/CD Configuration — .travis.yml, .codeclimate.yml. The Travis CI configuration (.travis.yml) and testing infrastructure may not enforce security best practices. Build artifacts could potentially be intercepted or compromised. Fix: Ensure all CI/CD pipelines use HTTPS, verify GPG signatures, and implement security scanning in the build process. Enable branch protection and require reviews for main branch merges.
• Low · Dependency Version Pinning Issues — gemfiles/, Gemfile, awesome_print.gemspec. The gemfiles directory contains multiple compatibility gemfiles for different Rails/Mongoid versions. Without strict version constraints, transitive dependencies could pull in vulnerable versions. Fix: Review and lock dependency versions to known secure versions. Implement automated dependency scanning (e.g., Dependabot, Bundler Audit). Add security scanning to CI/CD pipeline to detect vulnerable dependencies.

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.