schemerd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3882b4702bf8be5603646dd0b145838a000ba86f14f133aa9e6c93f5c967a555
+  data.tar.gz: 81efcf0b59b4aa78220591e6722d48222e59680d711967ece0bfbae3af8b811f
+SHA512:
+  metadata.gz: 60efa1723758b22ba9ec775e865b1a08c99a777a6f24b4346d248c39d18fc35c0d262ac307b1d9b10095a4c8fb8e5a26dcd39b11cec73e559b754f743645cfb5
+  data.tar.gz: fa4046b7dca821984dbd0d957a2e221b6fa3c65c44ec955d0fb59547ec25bfba91fcbfd6768166aaefd8b6707164cd342191ea8dc0277f7636cf407d7c1e91b3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Pablo
+
+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,108 @@
+# schemerd
+
+Auto-generate [Mermaid](https://mermaid.js.org/) ER diagrams from your ActiveRecord models. Keeps your schema documentation in sync by regenerating after every migration.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+group :development do
+  gem "schemerd"
+end
+```
+
+Run `bundle install`.
+
+## Usage
+
+### Generate the diagram
+
+```bash
+rake schemerd:generate
+```
+
+This creates `doc/erd.md` with a Mermaid `erDiagram` block containing all your models, columns, and associations.
+
+### Auto-generate on migrations
+
+By default, Schemerd hooks into `db:migrate`, `db:migrate:up`, `db:migrate:down`, and `db:migrate:redo` in development. The diagram regenerates automatically after each migration.
+
+To disable this:
+
+```ruby
+Schemerd.configure do |config|
+  config.auto_generate = false
+end
+```
+
+## Configuration
+
+Generate an initializer with all available options:
+
+```bash
+rails generate schemerd:install
+```
+
+This creates `config/initializers/schemerd.rb`. Available options:
+
+```ruby
+Schemerd.configure do |config|
+  # Output directory relative to Rails.root (default: "doc")
+  config.output_directory = "doc"
+
+  # Output filename (default: "erd.md")
+  config.output_filename = "erd.md"
+
+  # Header text at the top of the generated file
+  config.header = "# Entity Relationship Diagram\n\nAuto-generated. Do not edit manually."
+
+  # Model name prefixes to exclude from the diagram (default: [])
+  config.excluded_prefixes = ["Flipper::", "Ahoy::"]
+
+  # Automatically regenerate after migrations (default: true)
+  config.auto_generate = true
+
+  # Base class for model discovery (default: "ApplicationRecord")
+  config.base_class = "ApplicationRecord"
+end
+```
+
+## Output Example
+
+The generated file contains a fenced Mermaid code block:
+
+~~~markdown
+# Entity Relationship Diagram
+
+Auto-generated from ActiveRecord models. Do not edit manually.
+
+```mermaid
+erDiagram
+    Post }o--|| User : "author"
+    Comment ||--o{ Post : "comments"
+
+    User {
+        integer id PK
+        string name
+        string email
+        datetime created_at
+        datetime updated_at
+    }
+
+    Post {
+        integer id PK
+        string title
+        text body
+        integer user_id
+        datetime created_at
+        datetime updated_at
+    }
+```
+~~~
+
+Render it on GitHub, GitLab, or any Mermaid-compatible viewer.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/schemerd/install_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Schemerd
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Create a Schemerd initializer with default configuration"
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/schemerd.rb"
+      end
+    end
+  end
+end

data/lib/generators/schemerd/templates/initializer.rb

@@ -0,0 +1,19 @@
+Schemerd.configure do |config|
+  # Output directory relative to Rails.root
+  # config.output_directory = "doc"
+
+  # Output filename
+  # config.output_filename = "erd.md"
+
+  # Header text at the top of the generated file
+  # config.header = "# Entity Relationship Diagram\n\nAuto-generated from ActiveRecord models. Do not edit manually."
+
+  # Model name prefixes to exclude from the diagram
+  # config.excluded_prefixes = ["Flipper::", "Ahoy::"]
+
+  # Automatically regenerate after running migrations
+  # config.auto_generate = true
+
+  # Base class for model discovery
+  # config.base_class = "ApplicationRecord"
+end

data/lib/schemerd/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Schemerd
+  class Configuration
+    attr_accessor :output_directory,
+                  :output_filename,
+                  :header,
+                  :excluded_prefixes,
+                  :auto_generate,
+                  :base_class
+
+    def initialize
+      @output_directory  = "doc"
+      @output_filename   = "erd.md"
+      @header            = "# Entity Relationship Diagram\n\n" \
+                           "Auto-generated from ActiveRecord models. Do not edit manually."
+      @excluded_prefixes = []
+      @auto_generate     = true
+      @base_class        = "ApplicationRecord"
+    end
+
+    def output_path
+      Rails.root.join(output_directory, output_filename)
+    end
+  end
+end

data/lib/schemerd/generator.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "set"
+require "fileutils"
+
+module Schemerd
+  class Generator
+    def initialize(config)
+      @config = config
+    end
+
+    def call
+      models = load_models
+      content = build_diagram(models)
+
+      output_path = @config.output_path
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, content)
+
+      puts "Schemerd: ERD written to #{output_path}"
+      content
+    end
+
+    private
+
+    def load_models
+      Rails.application.eager_load!
+
+      base = @config.base_class.constantize
+      base.descendants
+        .reject(&:abstract_class?)
+        .reject { |m| excluded?(m.name) }
+        .select { |m| m.table_exists? rescue false }
+        .sort_by(&:name)
+    end
+
+    def excluded?(model_name)
+      @config.excluded_prefixes.any? { |prefix| model_name.start_with?(prefix) }
+    end
+
+    def build_diagram(models)
+      lines = []
+
+      lines << @config.header
+      lines << ""
+      lines << "```mermaid"
+      lines << "erDiagram"
+
+      lines.concat(associations_section(models))
+      lines << ""
+      lines.concat(entities_section(models))
+
+      lines << "```"
+      lines.join("\n") + "\n"
+    end
+
+    def associations_section(models)
+      lines = []
+      seen = Set.new
+      model_names = models.map(&:name).to_set
+
+      models.each do |model|
+        model.reflect_on_all_associations.each do |assoc|
+          target_name = assoc.klass.name rescue next
+          next unless model_names.include?(target_name)
+
+          pair = [model.name, target_name].sort
+          next if seen.include?(pair)
+          seen.add(pair)
+
+          line = relationship_line(model.name, target_name, assoc)
+          lines << "    #{line}" if line
+        end
+      end
+
+      lines
+    end
+
+    def entities_section(models)
+      lines = []
+
+      models.each do |model|
+        lines << "    #{model.name} {"
+        model.columns.each do |col|
+          pk = col.name == "id" ? "PK" : ""
+          type = col.type || "string"
+          lines << "        #{type} #{col.name} #{pk}".rstrip
+        end
+        lines << "    }"
+        lines << ""
+      end
+
+      lines
+    end
+
+    def relationship_line(source, target, assoc)
+      case assoc.macro
+      when :belongs_to
+        if assoc.options[:optional]
+          "#{source} }o--o| #{target} : \"#{assoc.name}\""
+        else
+          "#{source} }o--|| #{target} : \"#{assoc.name}\""
+        end
+      when :has_many
+        "#{source} ||--o{ #{target} : \"#{assoc.name}\""
+      when :has_one
+        "#{source} ||--o| #{target} : \"#{assoc.name}\""
+      end
+    end
+  end
+end

data/lib/schemerd/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Schemerd
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../../tasks/schemerd.rake", __dir__)
+    end
+  end
+end

data/lib/schemerd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Schemerd
+  VERSION = "0.1.0"
+end

data/lib/schemerd.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "schemerd/version"
+require "schemerd/configuration"
+require "schemerd/generator"
+require "schemerd/railtie" if defined?(Rails::Railtie)
+
+module Schemerd
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def generate
+      Generator.new(configuration).call
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/tasks/schemerd.rake

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+namespace :schemerd do
+  desc "Generate Mermaid ER diagram from ActiveRecord models"
+  task generate: :environment do
+    Schemerd.generate
+  end
+end
+
+# Auto-run after migrations in development
+if defined?(Rails) && Rails.env.development?
+  %w[db:migrate db:migrate:up db:migrate:down db:migrate:redo].each do |task_name|
+    next unless Rake::Task.task_defined?(task_name)
+
+    Rake::Task[task_name].enhance do
+      if Schemerd.configuration.auto_generate
+        Rake::Task["schemerd:generate"].invoke
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: schemerd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pablo Monfort
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Auto-generate Mermaid ERD markdown files from your ActiveRecord schema.
+  Hooks into db:migrate to keep diagrams in sync.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/schemerd/install_generator.rb
+- lib/generators/schemerd/templates/initializer.rb
+- lib/schemerd.rb
+- lib/schemerd/configuration.rb
+- lib/schemerd/generator.rb
+- lib/schemerd/railtie.rb
+- lib/schemerd/version.rb
+- lib/tasks/schemerd.rake
+homepage: https://github.com/pablo/schemerd
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate Mermaid ER diagrams from ActiveRecord models
+test_files: []