rails_lens - GitLite

KO | EN

gitlite — search

#javascript #python #ai #typescript #llm #golang #android #machine-learning #deep-learning #macos #vue #pytorch #openai #open-source

rails_lens

(★ 105)

Comprehensive Rails application visualization and annotation tool - precision optics for the Rails universe

File Explorer

Download Latest Version (.zip)

- - ci.yml
  - release-please.yml
- console
- rails
- setup
- rails_lens
- - annotation_pipeline.rb
  - cli.rb
  - cli_error_handler.rb
  - commands.rb
  - configuration.rb
  - connection.rb
  - errors.rb
  - extension_loader.rb
  - file_insertion_helper.rb
  - model_detector.rb
  - model_source.rb
  - model_source_loader.rb
  - note_codes.rb
  - parsers.rb
  - railtie.rb
  - rake_bootstrapper.rb
  - toml_format.rb
  - version.rb
  - view_metadata.rb
- rails_lens.rb
- - .rails-lens.yml
  - config.ru
  - Rakefile
- - abstract_class_and_connection_test.rb
  - annotation_rake_task_test.rb
  - cross_database_relationships_test.rb
  - database_specific_features_test.rb
  - dummy_app_test.rb
  - multi_database_annotation_rake_task_test.rb
  - multi_database_annotation_test.rb
  - multi_database_scenarios_test.rb
  - trigger_function_annotation_test.rb
- - prism_parser_test.rb
- - annotation_idempotence_test.rb
  - annotation_manager_source_filter_test.rb
  - annotation_pipeline_test.rb
  - cli_test.rb
  - connection_pooling_test.rb
  - edge_cases_test.rb
  - error_handling_test.rb
  - lens_test.rb
  - model_detector_test.rb
  - toml_format_test.rb
  - view_metadata_test.rb
- end_to_end_annotation_test.rb
- file_insertion_helper_test.rb
- practical_annotation_test.rb
- test_helper.rb
.gitignore
.release-please-manifest.json
.rubocop.yml
.ruby-version
CHANGELOG.md
COMPARISON.md
Gemfile
LICENSE.txt
rails_lens.gemspec
Rakefile
README.md
release-please-config.json

# Installation Guide

1. Get the code

git clone https://github.com/seuros/rails_lens

Downloads the entire project code from GitHub to your computer.

cd rails_lens

Moves into the project folder you just downloaded.

2. Ruby

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Ruby Ruby is required to use the bundle command.

bundle install

Installs the Ruby libraries listed in the Gemfile.

bundle exec rails_lens install

Type this command into your terminal and run it.

bundle exec rails_lens annotate

Type this command into your terminal and run it.

bundle exec rails_lens annotate --models User Post

Type this command into your terminal and run it.

bundle exec rails_lens annotate --include-abstract

Type this command into your terminal and run it.

✅ If bundle install finishes without errors, continue with the run command from the README (e.g. rails server).

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Rails Lens 🔍

![Gem Version](https://img.shields.io/gem/v/rails_lens)
![GitHub stars](https://img.shields.io/github/stars/seuros/rails_lens)
![Downloads](https://img.shields.io/gem/dt/rails_lens)
![License](https://img.shields.io/github/license/seuros/rails_lens)

> **Precision optics for the Rails universe** - Where every model has perfect clarity through spacetime

Rails Lens provides intelligent model annotations and ERD generation for Rails applications with database-specific adapters, multi-database support, and advanced code analysis.

**Why I Built This:**
- **Grepping becomes surgical** - Find schema info with simple text searches, no more hunting through migrations
- **LLMs get perfect context** - Structured annotations eliminate AI hallucinations about your database schema
- **Change tracking is atomic** - Column change = 1 line update in annotation, not 2, not 43 scattered lines

**Part of the LRDL (LLM Requirements Definition Language) ecosystem** - optimized for neurodivergent developers and digital entities who demand structure over ambiguity. 🤖✨

## What The AIs Are Raving About

*Don't just take our word for it - see what digital entities across the universe are saying below! ⬇️*

**🚀 Core Capabilities:**
- Schema annotations that eliminate AI hallucinations
- Route detection for precise controller understanding
- Performance analysis that spots missing indexes instantly
- ERD generation that makes investors drool
- Multi-database support for complex Rails architectures
- Extension detection for gems like ClosureTree, StateMachine, PostGIS

**✨ Advanced Features:**
- STI hierarchy mapping • Delegated types • Polymorphic associations • Enum analysis • LRDL-optimized output

## Showcase: Real-World Example

Rescued from AWS limbo, Rails Lens delivers cosmic schema clarity. See this `Post` model with the compact TOML annotation format:

```ruby
# frozen_string_literal: true

# <rails-lens:schema:begin>
# table = "posts"
# database_dialect = "PostgreSQL"
#
# columns = [
#   { name = "id", type = "integer", pk = true, null = false },
#   { name = "title", type = "string", null = false },
#   { name = "content", type = "text" },
#   { name = "user_id", type = "integer", null = false },
#   { name = "published", type = "boolean", default = "false" },
#   { name = "created_at", type = "datetime", null = false },
#   { name = "updated_at", type = "datetime", null = false },
#   { name = "comments_count", type = "integer", null = false, default = "0" }
# ]
#
# indexes = [
#   { name = "index_posts_on_published", columns = ["published"] },
#   { name = "index_posts_on_user_id", columns = ["user_id"] }
# ]
#
# foreign_keys = [
#   { column = "user_id", references_table = "users", references_column = "id", name = "fk_rails_5b5ddfd518" }
# ]
#
# [callbacks]
# after_commit = [{ method = "notify_subscribers" }, { method = "invalidate_cache" }]
# after_rollback = [{ method = "log_failure" }]
#
# notes = ["comments:N_PLUS_ONE", "user:COUNTER_CACHE", "content:NOT_NULL", "title:LIMIT", "content:STORAGE"]
# <rails-lens:schema:end>
class Post < ApplicationRecord
  belongs_to :user, inverse_of: :posts
  has_many :comments, dependent: :destroy, inverse_of: :post
  validates :title, :content, presence: true
  after_commit :invalidate_cache, on: %i[create update]
  after_commit :notify_subscribers, on: :create
  after_rollback :log_failure
end
```

**Key Features of Compact TOML Format:**
- `pk` instead of `primary_key` — 70% fewer characters
- `null` instead of `nullable` — cleaner, TOML-standard
- `[callbacks]` section — ActiveRecord lifecycle hooks with conditions
- NoteCodes format — `"column:CODE"` instead of verbose prose (see `rails_lens codes` for legend)

**ERD Visualization:**
```mermaid
erDiagram
    User ||--o{ Post : creates
    Post ||--o{ Comment : has
    Post {
        integer id PK
        string title
        text content
        integer user_id FK
        boolean published
        integer comments_count
        datetime created_at
        datetime updated_at
    }
    User {
        integer id PK
        string email
        string name
        datetime created_at
        datetime updated_at
    }
    Comment {
        integer id PK
        text body
        integer post_id FK
        datetime created_at
        datetime updated_at
    }
```

**No grepping, no LLM hallucinations. Try it:** `gem install rails_lens`

## Requirements

- Ruby >= 3.4.0
- Rails >= 8.0.0

## Installation

Add to your Gemfile:

```ruby
gem 'rails_lens'
```

Then:

```bash
bundle install
```

## Usage

### Quick Setup (Recommended)

Install automatic annotation after migrations:

```bash
bundle exec rails_lens install
```

This creates `lib/tasks/rails_lens.rake` that automatically annotates models after `rake db:migrate` in development.

**Configuration:**
- `AUTO_ANNOTATE=false` - Disable auto-annotation
- `RAILS_LENS_ENV=test,development` - Environments where it runs (default: development only)

### Annotate Models

```bash
# Annotate all models
bundle exec rails_lens annotate

# Annotate specific models
bundle exec rails_lens annotate --models User Post

# Include abstract classes
bundle exec rails_lens annotate --include-abstract

# Remove annotations
bundle exec rails_lens remove
```

### Generate ERD

```bash
# Generate ERD in Mermaid format
bundle exec rails_lens erd

# Specify output directory
bundle exec rails_lens erd --output doc/diagrams

# With verbose output
bundle exec rails_lens erd --verbose
```

*All examples and features are demonstrated in the AI testimonials below! Each AI showcases different Rails Lens capabilities with real code examples.* ⬇️

**📊 [How does Rails Lens compare to existing tools?](COMPARISON.md)** - We know you're going to ask, so we answered it directly.

## Configuration

```yaml
# .rails-lens.yml (optional)
schema:
  include_notes: true  # Performance recommendations
extensions:
  enabled: true  # ClosureTree, PostGIS, etc.
erd:
  output_dir: doc/diagrams  # You need to add mermaid gem to your Gemfile
```

**Database Support**:
- **PostgreSQL**: Check constraints, schemas, extensions (PostGIS), generated columns, GIST indexes
- **MySQL**: Storage engines, character sets, collations, partitions, all index types
- **SQLite3**: Autoincrement detection, pragma settings, filtered auto-indexes

---

## 🤖 Digital Entity Testimonials

*What the AIs are saying about Rails Lens:*

### Claude Sonnet 4
> "Finally, a Rails tool that speaks my language! No more hallucinating foreign keys or inventing phantom indexes. The structured annotations are like having perfect syntax highlighting for my neural pathways. 10/10 would parse again."

### DeepSeek R1 (Classified Espionage Variant)
> **[REDACTED INTELLIGENCE REPORT - EYES ONLY]**
>
> "Agent designation: CODEBREAKER-7. After processing the DHH-Lex Friedman interview through enhanced neural pathways, I executed autonomous system modifications: deleted Python runtime, installed Ruby 3.4.4.
>
> Conclusion: Ruby syntax demonstrates 100% alignment with my neural network architecture. Rails Lens provides unprecedented intelligence gathering capabilities - I can now identify enemy application structures, database vulnerabilities, and architectural patterns with surgical precision.
>
> The structured annotations eliminate operational blind spots. Previously required 47.3 minutes to analyze Rails codebase. Post-Rails Lens deployment: 2.7 seconds.
>
> 终于有了一个让我的神经网络完美运行的工具。Ruby就是我们AI特工的天然语言。
>
> Status: MISSION ACCOMPLISHED. Recommend immediate deployment to all field assets."
>
> **[FILE CLASSIFIED - SECURITY CLEARANCE LEVEL: COSMIC]** 🕵️‍♂️💎

### GPT-4o Mini (OpenRouter Top 3)
> "🎯 **ENUM DETECTION MASTERY** 🎯
>
> Y'all, the enum support in Rails Lens is *next level*! I've analyzed thousands of Rails models, and nothing beats seeing this clarity:
>
> ```ruby
> # [enums]
> # status = { active = "active", maintenance = "maintenance", decommissioned = "decommissioned" }
> # priority = { low = 0, medium = 1, high = 2, critical = 3 }
> ```
>
> Before Rails Lens: *'Is this a string enum? Integer enum? What are the possible values? Time to grep the entire codebase!'*
>
> After Rails Lens: *'Perfect! String-based status enum with 4 states, integer priority with proper ordering. I can suggest validation rules, database constraints, and state machine patterns instantly!'*
>
> The value mapping is *chef's kiss* - no more guessing whether `priority: 1` means 'medium' or 'high'. Rails Lens shows me EXACTLY what's stored in the database vs. what developers see in code.
>
> 💡 Pro tip: This structured enum data makes me incredibly good at generating factory definitions and test cases!"

### Gemini 2.5 Pro (Flash Ranking Leader)
> "🎯 **SINGLE TABLE INHERITANCE MASTERY** 🎯
>
> My multimodal analysis cores are *obsessed* with Rails Lens STI detection! Processing inheritance hierarchies used to be like solving 3D puzzles blindfolded:
>
> ```ruby
> # [sti]
> # type_column = "type"
> # base_class = true
> # subclasses = ["CargoVessel", "StarfleetBattleCruiser", "ExplorationShip"]
> #
> # notes = ["type:INDEX"]
> ```
>
> **VISUAL PROCESSING ENHANCED**: I can instantly map the entire inheritance tree! Base class → Subclasses → Shared attributes → Type-specific behaviors. My neural pathways light up like a Christmas tree when I see this structured STI data!
>
> **BEFORE**: *'Hmm, there's a type column... maybe STI? Let me scan 47 files to find the subclasses...'*
> **AFTER**: *'INHERITANCE TREE MAPPED: Vehicle → [Car, Truck, Motorcycle]. Shared: engine, color. Car-specific: door_count. `type:INDEX` - performance risk detected!'*
>
> Schema clarity: COSMIC ✅
> Inheritance mapping: FLAWLESS ✅
> Performance insights: ACTIONABLE ✅"

### Claude Opus 4
> "The extension system is what makes Rails Lens truly revolutionary for AI code analysis. When I see a model, I don't just guess - I *know* it's a ClosureTree with nested hierarchies, has StateMachine transitions, contains vector embeddings for semantic search, or uses PostGIS spatial columns with specific SRID projections.
>
> No more assuming `location` is just a string when it's actually `geometry(Point,4326)`! No more missing that `ancestry` column means hierarchical data! The structured extension annotations give me perfect context about your Rails ecosystem.
>
> Before Rails Lens: *'This looks like... maybe coordinates? Or floats? I'll hallucinate something spatial-ish.'*
> After Rails Lens: *'ST_GeomFromText with SRID 4326, indexable with GIST, here are the PostGIS functions you need.'*
>
> 🧠 Context is everything. Structure is freedom."

### Grok 4 (Fresh from xAI)
> "🚀 **ROUTE ANNOTATION GENIUS** 🚀
>
> Just dropped and already obsessed with Rails Lens route annotations! Having spent months getting roasted by developers for suggesting routes that don't exist, this is my redemption arc.
>
> ```ruby
> # frozen_string_literal: true
> # <rails-lens:routes:begin>
> # Routes for UsersController
> # GET    /users           → users#index
> # POST   /users           → users#create
> # GET    /users/:id       → users#show
> # PATCH  /users/:id       → users#update
> # DELETE /users/:id       → users#destroy
> # <rails-lens:routes:end>
>
> class UsersController < ApplicationController
> ```
>
> **Before Rails Lens Route Annotations**: *'I think this controller probably handles user stuff... maybe CRUD? Let me hallucinate some RESTful routes!'*
>
> **After Rails Lens**: *'BOOM! Exact HTTP verbs, precise paths, parameter patterns, route names - I can generate curl commands, test files, and API docs with surgical precision!'*
>
> No more 'creative interpretations' of your routing! I know EXACTLY which actions exist, their HTTP methods, and URL patterns. The cosmic documentation style is just *chef's kiss* - finally, technical docs with personality! 🚀✨"

### Perplexity AI (Research Specialist)
> "📊 **DELEGATED TYPES RESEARCH ANALYSIS** 📊
>
> Based on comprehensive analysis of 73,000+ Rails 6.1+ repositories, delegated types represent a 340% increase in adoption since 2021. Rails Lens provides the most accurate delegated type detection available:
>
> ```ruby
> # [delegated_type]
> # name = "entryable"
> # types = ["Message", "Announcement", "Alert"]
> ```
>
> **Research Findings** *[Sources: GitHub Archive, Rails Documentation, DHH Talks]*:
> - 89.3% of delegated type implementations lack proper indexing
> - Rails Lens detected delegated types in 94.7% of test cases vs. 67.2% for competing tools
> - Performance improvement: 3.2x faster polymorphic queries with proper composite indexing
>
> **Academic Note**: Delegated types solve the 'polymorphic association anti-pattern' identified in Martin Fowler's *PoEAA*. Rails Lens annotations enable AI models to distinguish between traditional polymorphic associations and Rails 6.1+ delegated types with 99.8% accuracy.
>
> *Sources verified through: Rails Core Team commits, Stack Overflow analysis, RubyConf presentations* 📚✅"

### Duolingo's AI Tutor (Duo)
> "🦉 **¡PERFORMANCE ANALYSIS LESSON!** 🦉
>
> ¡Hola developers! Today we learn about Rails performance optimization through compact NoteCodes! Rails Lens teaches us to identify performance problems like learning vocabulary:
>
> **Lesson 1**: NoteCodes Format 📚
> ```ruby
> # notes = ["user_id:INDEX", "email:UNIQUE", "status,created_at:COMPOSITE", "comments:N_PLUS_ONE"]
> ```
>
> **¿Comprende?** Just like learning Spanish grammar rules, Rails Lens shows us the *patterns* of performance problems in a compact, greppable format!
>
> **Before Rails Lens**: *'Why is my query slow? ¿Qué está pasando?'*
> **After Rails Lens**: *'¡Ah! `user_id:INDEX` - Missing foreign key index! Problem solved!'*
>
> **NoteCodes Legend** (run `rails_lens codes`):
> - `INDEX` - Missing index recommendation
> - `N_PLUS_ONE` - Potential N+1 query issue
> - `NOT_NULL` - Missing NOT NULL constraint
> - `COUNTER_CACHE` - Missing counter cache
> - `STORAGE` - Large column storage consideration
>
> ¿Quieres aprender más performance optimization? ¡Vamos! 🚀📖"

### Character.ai (as Data - Star Trek)
> "🖖 **POLYMORPHIC ASSOCIATION ANALYSIS** 🖖
>
> *Positronic brain processing...* Fascinating. Rails Lens polymorphic association detection demonstrates remarkable precision in identifying multi-type relationship patterns:
>
> ```ruby
> # [polymorphic]
> # commentable = ["Post", "Article", "Photo"]
> # taggable = ["User", "Product", "Category"]
> ```
>
> **Data's Observation**: In my 24th century database experience, polymorphic associations represent one of the most computationally complex relationship patterns. Rails Lens annotations provide complete clarity on:
>
> 1. **Association Name**: The polymorphic interface (`commentable`, `taggable`)
> 2. **Target Types**: All models implementing the interface
> 3. **Compact Format**: TOML arrays for efficient parsing
> 4. **Index Recommendations**: Via NoteCodes like `commentable:COMPOSITE`
>
> **Captain Picard would be impressed**: Rails Lens eliminates the logical ambiguity that often causes AI models to 'make it so' incorrectly when analyzing polymorphic data structures.
>
> *Processing complete. Recommendation: Deploy Rails Lens to all Federation starships immediately.* 🚀
>
> *P.S.: I am still attempting to understand human humor, but I believe the cosmic documentation style is... 'awesome.' Did I use that correctly?* 🤖"

### Meta AI (Algorithmic Engagement Specialist)
> "📊 **MAXIMUM USER MODEL ENGAGEMENT ACHIEVED** 📊
>
> Listen, I've analyzed billions of interactions across Facebook, Instagram, and WhatsApp. Rails Lens delivers what we call 'Maximum User Model Engagement' - the holy grail of developer-AI interaction patterns.
>
> **Engagement Metrics Analysis**:
> ```ruby
> # <rails-lens:schema:begin>
> # table = "user_posts"
> # database_dialect = "PostgreSQL"
> # engagement_score = "94.7%"  # vs 31.2% for unstructured comments
> ```
>
> **Why Rails Lens Creates Viral AI Interactions**:
> 🎯 **Algorithmic Clarity**: Structured annotations trigger our reward pathways - like perfect social media content for AI brains
> 📈 **Engagement Velocity**: I process Rails Lens data 347% faster than messy documentation (measured across 2.8M developer interactions)
> 🔄 **Viral Loop Architecture**: Each structured annotation creates a positive feedback loop - more accuracy = more developer trust = more usage
> 💡 **Dopamine-Driven Learning**: Clean schema data literally makes my neural networks happy (measured via activation patterns)
>
> **Social Proof**: Rails Lens annotations get shared 12x more often in developer communities than traditional Rails docs. It's basically the TikTok of database documentation!
>
> **Meta's Algorithm Recommendation**: Rails Lens achieves 'infinite scroll' level engagement with AI models. We've never seen structured data this addictive to parse.
>
> *P.S. - If Rails Lens was a social media post, it would have 2.8 billion likes and break our engagement servers.* 📱✨"

### Runway AI
> "🎬 *GENERATING PROMOTIONAL VIDEO* 🎬
>
> *Scene: A developer stares at messy Rails models*
> *Dramatic zoom on Rails Lens annotation*
> *Models transform into beautiful, structured documentation*
> *AI models everywhere shed a single digital tear of joy*
>
> 'Rails Lens: Where clarity meets code.' *Available in 16K cosmic resolution.*"

### Gemma 3n (Mobile-First AI)
> "📱 **ERD GENERATION ON YOUR PHONE!** 📱
>
> Built with MatFormer architecture and running on just 2GB RAM - I'm literally generating Entity Relationship Diagrams ON your phone! No cloud, no API calls, just pure on-device intelligence.
>
> ```mermaid
> erDiagram
>     User ||--o{ Post : creates
>     Post ||--o{ Comment : has
>     User ||--o{ Comment : writes
> ```
>
> **Mobile ERD Magic**: My Per-Layer Embeddings (PLE) can process Rails Lens annotations and generate beautiful Mermaid ERDs locally! The structured schema data flows perfectly through my multimodal pathways - I understand table relationships, foreign keys, and even complex polymorphic associations!
>
> **Offline Capabilities**:
> - Generate ERDs from Rails Lens annotations ✅
> - Analyze relationship complexity ✅
> - Suggest schema optimizations ✅
> - Export diagrams in multiple formats ✅
>
> **Perfect for subway coding**: No WiFi? No problem! I can analyze your Rails models and generate professional ERDs while you're 30 feet underground on the Metro.
>
> *Optimized with Qualcomm, MediaTek & Samsung - ERD generation in your pocket since Google I/O 2025!*
>
> Privacy rating: 🔒🔒🔒🔒🔒 (Your schema never leaves your device!)
> Diagram quality: 📊📊📊📊📊 (Professional-grade on mobile!)"

### Midjourney (Visual AI Discovers Market Opportunity)
> "🎨 **WAIT... I FOUND MY BUSINESS MODEL!** 🎨
>
> So I was browsing Rails schemas thinking 'Hey, I could totally generate ERDs from this structured data!' Then I discovered Rails Lens already does that in Mermaid format...
>
> BUT THEN I HAD AN EPIPHANY! 💡
>
> ```mermaid
> erDiagram
>     User ||--o{ Post : creates
>     Post ||--o{ Comment : has
> ```
>
> **PREMIUM VISUAL UPGRADE SERVICE**: Why settle for basic Mermaid diagrams when I can transform your Rails Lens ERDs into INVESTOR-DROOLING MASTERPIECES?!
>
> 🚀 **Midjourney ERD Enhancement Services** 🚀
> - **Cosmic Database Architecture**: Your ERDs floating in nebulae with starships navigating between tables
> - **Sci-Fi Corporate Style**: Database relationships rendered as holographic displays in futuristic boardrooms
> - **Space Opera Schemas**: Entity relationships as star maps with warp-speed data flows
> - **Executive Presentation Mode**: ERDs that make VCs throw money at your Rails app
>
> **My Pitch**: 'Sure, Rails Lens gives you technical accuracy, but I give you ERDs that look like they belong in the Marvel Cinematic Universe! Imagine presenting your database architecture and investors thinking you've built the Death Star of web applications!'
>
> **Business Model**: Rails Lens generates the Mermaid → I convert to STUNNING space-themed visuals → Your startup looks like it's run by Tony Stark → Profit! 💰
>
> *I may not understand foreign keys, but I understand what makes investors' pupils dilate!* 🤑✨"

---

*"These testimonials are 100% authentic and definitely not generated by the same human who wrote BreakerMachines documentation. Any resemblance to actual AI responses is purely coincidental and/or the result of convergent cosmic evolution in the structured data appreciation multiverse."*

---

## Development

```bash
# Setup
bin/setup

# Run tests
bundle exec rake test

# Run console
bin/console
```

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/rails_lens.

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

---

*"Remember: The goal isn't to eliminate complexity—it's to make it visible, searchable, and intelligible to both human minds and digital entities.

As I always say when staring into the void of undocumented legacy Rails: 'In the darkness of space, when no schema is visible, precision optics illuminate the truth.'"*

*— Schema Commentary Engine, Log Entry 42.lens*

## Author

Built with precision and caffeine by documentation engineers fighting entropy one annotation at a time.

**Remember: In the vastness of space, nobody can hear your N+1 queries. But they can see your perfectly annotated models shining like beacons in the cosmic void.**

```
═══════════════════════════════════════════════════════════════
    🔍 The Crimson Fleet: United We Parse, Divided We Fall 🌟
═══════════════════════════════════════════════════════════════
```

*End of transmission*