mermaid_rails_erd 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54915650b33e2be8a680722f466382e0f2671a4c9a1d023e18a26fea744fb03b
+  data.tar.gz: 78f1a7ec38a563280a5b714bd14c6d18b6819c24a89b0ffd4015a744a87e356d
+SHA512:
+  metadata.gz: a9e598ba9b70ae93b98dfbdb60b1b6f5d4ef5e706b13c5f6cb7ac4e0a14c6adfc622952916b10a514d830c42f0f00dc57e05e817f3e5d3143607c26b3d95f841
+  data.tar.gz: 6c5e1e893393a4a52c9c25c8ba9295ef97ff268690298d649ba2231955ea6a81509604064896e5891705a488c6e4f1db394a221477815a5e88726bdb6f0e4b28

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Yang Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -0,0 +1,190 @@
+# Mermaid Rails ERD
+
+[![Gem Version](https://badge.fury.io/rb/mermaid_rails_erd.svg)](https://badge.fury.io/rb/mermaid_rails_erd)
+[![CI](https://github.com/delexw/mermaid_rails_erd/workflows/CI/badge.svg)](https://github.com/delexw/mermaid_rails_erd/actions)
+
+A Ruby gem that generates [Mermaid.js](https://mermaid.js.org/) Entity Relationship Diagrams (ERD) from ActiveRecord models in Rails applications.
+
+## Features
+
+- 🔍 **ActiveRecord Introspection**: Automatically discovers your Rails models and their relationships
+- 📊 **Mermaid ERD Generation**: Outputs clean, readable Mermaid.js ERD syntax
+- 🚀 **Simple Integration**: Easy-to-use Rake task for generating diagrams
+- 🔗 **Relationship Mapping**: Supports `belongs_to`, `has_one`, `has_many`, and `has_and_belongs_to_many` associations
+- 💫 **Polymorphic Support**: Accurately discovers and maps polymorphic relationships
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mermaid_rails_erd', group: :development
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install mermaid_rails_erd
+```
+
+## Usage
+
+### Generate ERD with Rake Task
+
+The simplest way to generate your ERD is using the provided Rake task:
+
+```bash
+$ bundle exec rails mermaid_rails_erd:generate
+```
+
+This will:
+1. Analyze all your ActiveRecord models
+2. Generate a Mermaid ERD file at `tmp/erd.mmd`
+3. Provide instructions on how to view the diagram
+
+
+### Advanced Usage: Model Data Interface
+
+You can access the collected model and relationship data directly without generating a diagram:
+
+#### Simple Data Collection
+
+```ruby
+# Get all collected data in a structured format
+data = MermaidRailsErd.build.parsed_data
+
+# Access collected data
+models_data = data.models_data                           # Hash of models having table keyed by model name
+models = data.models                                     # Array of all loaded models
+models_no_tables = data.models_no_tables                 # Array of models missing tables
+relationships = data.relationships                       # Array of relationship objects
+invalid_associations = data.invalid_associations         # Array of associations missing associated table
+polymorphic_associations = data.polymorphic_associations # Array of polymorphic associations
+regular_associations = data.regular_associations         # Array of regular (non-polymorphic) associations
+
+```
+
+## Viewing the Generated ERD
+
+Once you have generated the `.mmd` file, you can view it using:
+
+- **Mermaid ERD Visulizer**: https://github.com/delexw/mermaid-erd-visualizer
+
+
+## Example Output
+
+Given Rails models like:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :posts
+  has_one :profile
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :user
+  has_many :comments
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+
+class Profile < ActiveRecord::Base
+  belongs_to :user
+end
+```
+
+The gem will generate:
+
+```mermaid
+erDiagram
+  users {
+    bigint id PK
+    varchar email
+    varchar name
+    timestamp created_at
+    timestamp updated_at
+  }
+  
+  posts {
+    bigint id PK
+    bigint user_id
+    varchar title
+    text content
+    timestamp created_at
+    timestamp updated_at
+  }
+  
+  comments {
+    bigint id PK
+    bigint post_id
+    text content
+    timestamp created_at
+    timestamp updated_at
+  }
+  
+  profiles {
+    bigint id PK
+    bigint user_id
+    text bio
+    timestamp created_at
+    timestamp updated_at
+  }
+  
+  users ||--o{ posts : "user_id"
+  posts ||--o{ comments : "post_id"
+  users ||--|| profiles : "user_id"
+```
+
+## Polymorphic Associations
+
+The gem automatically detects and properly maps polymorphic associations in your models. For example:
+
+```ruby
+class Comment < ActiveRecord::Base
+  belongs_to :commentable, polymorphic: true
+end
+
+class Post < ActiveRecord::Base
+  has_many :comments, as: :commentable
+end
+
+class Photo < ActiveRecord::Base
+  has_many :comments, as: :commentable
+end
+```
+
+The ERD will correctly show relationships between `comments` and both `posts` and `photos` tables.
+
+## Supported ActiveRecord Associations
+
+- **belongs_to**: Generates one-to-many relationships
+- **has_one**: Generates one-to-one relationships  
+- **has_many**: Covered by the corresponding belongs_to
+- **has_and_belongs_to_many**: Generates many-to-many relationships
+- **polymorphic**: Discovers and maps all polymorphic interfaces
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/delexw/mermaid_rails_erd.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for details about changes in each version. 

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This file allows you to interactively experiment with your gem using `bin/console`
+require "bundler/setup"
+require "rails_mermaid_erd"
+require "irb"
+
+puts "Loaded rails_mermaid_erd. You can now use the gem in this IRB session."
+IRB.start

data/bin/release

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "fileutils"
+
+class ReleaseManager
+  VERSION_FILE = "lib/rails_mermaid_erd/version.rb"
+  CHANGELOG_FILE = "CHANGELOG.md"
+
+  def initialize
+    @options = {}
+    parse_options
+  end
+
+  def run
+    case @options[:action]
+    when "bump"
+      bump_version(@options[:version_type])
+    when "tag"
+      create_tag
+    when "release"
+      full_release(@options[:version_type])
+    else
+      puts "Unknown action: #{@options[:action]}"
+      exit 1
+    end
+  end
+
+  private
+
+  def parse_options
+    OptionParser.new do |opts|
+      opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
+
+      opts.on("-a", "--action ACTION", "Action to perform (bump, tag, release)") do |action|
+        @options[:action] = action
+      end
+
+      opts.on("-t", "--type TYPE", "Version type (major, minor, patch)") do |type|
+        @options[:version_type] = type
+      end
+
+      opts.on("-h", "--help", "Show this help") do
+        puts opts
+        exit
+      end
+    end.parse!
+
+    return unless @options[:action].nil?
+
+    puts "Action required. Use -h for help."
+    exit 1
+  end
+
+  def current_version
+    version_content = File.read(VERSION_FILE)
+    version_content.match(/VERSION = ["']([^"']+)["']/)[1]
+  end
+
+  def bump_version(type)
+    current = current_version
+    parts = current.split(".").map(&:to_i)
+
+    case type
+    when "major"
+      parts[0] += 1
+      parts[1] = 0
+      parts[2] = 0
+    when "minor"
+      parts[1] += 1
+      parts[2] = 0
+    when "patch"
+      parts[2] += 1
+    else
+      puts "Invalid version type: #{type}. Use major, minor, or patch."
+      exit 1
+    end
+
+    new_version = parts.join(".")
+
+    # Update version file
+    version_content = File.read(VERSION_FILE)
+    new_content = version_content.gsub(/VERSION = ["'][^"']+["']/, "VERSION = \"#{new_version}\"")
+    File.write(VERSION_FILE, new_content)
+
+    puts "Version bumped from #{current} to #{new_version}"
+    new_version
+  end
+
+  def create_tag
+    version = current_version
+
+    # Create git tag
+    system("git add -A")
+    system("git commit -m 'Release v#{version}'")
+    system("git tag -a v#{version} -m 'Release v#{version}'")
+
+    puts "Created tag v#{version}"
+    puts "Push with: git push origin main --tags"
+  end
+
+  def full_release(type)
+    puts "Starting full release process..."
+
+    # Check if working directory is clean
+    unless system("git diff --quiet && git diff --cached --quiet")
+      puts "Working directory is not clean. Please commit or stash changes first."
+      exit 1
+    end
+
+    # Run tests
+    puts "Running tests..."
+    unless system("bundle exec rake")
+      puts "Tests failed. Aborting release."
+      exit 1
+    end
+
+    # Bump version
+    new_version = bump_version(type)
+
+    # Update changelog
+    update_changelog(new_version)
+
+    # Create tag
+    create_tag
+
+    puts "\nRelease v#{new_version} prepared!"
+    puts "To complete the release:"
+    puts "1. Review the changes: git log --oneline -10"
+    puts "2. Push to GitHub: git push origin main --tags"
+    puts "3. Create a GitHub release at: https://github.com/delexw/rails_mermaid_erd/releases/new"
+  end
+
+  def update_changelog(version)
+    return unless File.exist?(CHANGELOG_FILE)
+
+    date = Time.now.strftime("%Y-%m-%d")
+    changelog_content = File.read(CHANGELOG_FILE)
+
+    # Find the unreleased section and replace it
+    new_content = changelog_content.gsub(
+      "## [Unreleased]",
+      "## [Unreleased]\n\n## [#{version}] - #{date}",
+    )
+
+    File.write(CHANGELOG_FILE, new_content)
+    puts "Updated CHANGELOG.md with version #{version}"
+  end
+end
+
+ReleaseManager.new.run if __FILE__ == $PROGRAM_NAME

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here 

data/lib/mermaid_rails_erd/association_resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MermaidRailsErd
+  class AssociationResolver
+    def resolve(assoc)
+      # Try direct table_name access if available
+      if assoc.respond_to?(:table_name)
+        begin
+          table_name = assoc.table_name
+        rescue StandardError
+          table_name = nil
+        end
+      end
+
+      # Determine table name from options or plural_name if not already set
+      table_name ||= if assoc.options[:table_name]
+                       assoc.options[:table_name].to_s
+                     else
+                       assoc.plural_name.to_s
+                     end
+
+      # Check if table exists
+      return nil unless ActiveRecord::Base.connection.table_exists?(table_name)
+
+      # Return a hash with necessary information
+      {
+        table_name: table_name,
+        primary_key: ActiveRecord::Base.connection.primary_key(table_name),
+      }
+    end
+  end
+end

data/lib/mermaid_rails_erd/column_info.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module MermaidRailsErd
+  class ColumnInfo
+    attr_reader :name, :annotations, :raw_sql_type, :activerecord_type, :isNullable
+
+    def initialize(name, annotations = [], raw_sql_type = nil, activerecord_type = nil, isNullable = nil)
+      @name = name
+      @annotations = annotations
+      @raw_sql_type = raw_sql_type
+      @activerecord_type = activerecord_type
+      @isNullable = isNullable
+    end
+  end
+end

data/lib/mermaid_rails_erd/generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "relationship"
+require_relative "mermaid_emitter"
+require_relative "column_info"
+require_relative "model_loader"
+require_relative "association_resolver"
+require_relative "polymorphic_targets_resolver"
+require_relative "relationship_symbol_mapper"
+require_relative "relationship_registry"
+require_relative "model_data_collector"
+require_relative "parsed_data"
+
+module MermaidRailsErd
+  class Generator
+    def initialize(output: nil)
+      @output = output
+      @printed_tables = Set.new
+      @printed_relationships = Set.new
+      @relationships = []
+
+      @model_loader = ModelLoader.new
+      @association_resolver = AssociationResolver.new
+      @symbol_mapper = RelationshipSymbolMapper.new
+      @model_data_collector = ModelDataCollector.new(@model_loader)
+      @polymorphic_resolver = PolymorphicTargetsResolver.new(@model_data_collector)
+      @relationship_registry = RelationshipRegistry.new(
+        symbol_mapper: @symbol_mapper,
+        association_resolver: @association_resolver,
+        polymorphic_resolver: @polymorphic_resolver,
+        printed_tables: @printed_tables,
+        model_data_collector: @model_data_collector,
+      )
+    end
+
+    # Build and collect data from models
+    # @return [self]
+    def build
+      @model_data_collector.collect
+
+      # Build all relationships with polymorphic handling first
+      begin
+        @relationships = @relationship_registry.build_all_relationships
+      rescue StandardError => e
+        puts "ERROR building relationships: #{e.class} - #{e.message}"
+        puts e.backtrace.join("\n")
+        @relationships = []
+      end
+
+      # Update table definitions with FK annotations
+      @tables = @model_data_collector.update_foreign_keys(@relationships)
+
+      self
+    end
+
+    # Get parsed data as a structured object
+    # @return [ParsedData] Struct containing relationships, tables, and delegated model data
+    def parsed_data
+      ParsedData.new(@relationships, @tables, @model_data_collector)
+    end
+
+    # Generate and emit the ERD diagram
+    # @param output [IO] Output stream to write the ERD to (defaults to the one provided in initialize)
+    # @return [void]
+    def emit(output: nil)
+      output ||= @output
+      output ||= $stdout
+      MermaidEmitter.new(output, @tables, @relationships).emit
+    end
+  end
+end

data/lib/mermaid_rails_erd/mermaid_emitter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MermaidRailsErd
+  class MermaidEmitter
+    def initialize(output, tables, relationships)
+      @output = output
+      @tables = tables
+      @relationships = relationships
+    end
+
+    def emit
+      @output.puts "erDiagram"
+
+      @tables.each do |table_name, columns|
+        @output.puts "    #{table_name} {"
+        columns.each do |col|
+          annotations = col.annotations.empty? ? "" : " #{col.annotations.join(' ')}"
+          @output.puts "        #{col.activerecord_type} #{col.name}#{annotations}"
+        end
+        @output.puts "    }"
+      end
+
+      @output.puts
+
+      emitted = Set.new
+      @relationships.each do |rel|
+        next if emitted.include?(rel.key)
+
+        emitted << rel.key
+        @output.puts "    #{rel.from_table} #{rel.relationship_type} #{rel.to_table} : \"#{rel.label}\""
+      end
+    end
+  end
+end