pferd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4cfbec7f22022f6fde8257a419ae16a322a33b1a5a3b808066615c9e5a36c49a
+  data.tar.gz: 725ae61787aa419a0e97f5fa3b82e285cf116b440884f94fbcd72300c70a3d01
+SHA512:
+  metadata.gz: 0b39ddbc987ef910722df3b0514b3a66a1402c0e9cba2cd516a74ad4992b55cdcfe9a89868fa1a42b5453cc3fed97aaf408e547554ddfc546fd2ee1f87482094
+  data.tar.gz: 945a120e05fa4107328ea6bdc1d5629b6e975d3a1fe387b190535ca7e8794e9e1c7d00ffbcf28b05641bf4311df49131896c324060d40be952decd76c74d1a54

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-02-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Bodacious
+
+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,97 @@
+# Pferd
+
+Pferd is a Ruby gem that generates an **Entity Relationship Diagram (ERD)** of your Ruby on Rails models, automatically **grouping models by their domain**. This is useful when you are in the process of modularising your codebase, and want to visualise various domain configurations without having to move code around.
+
+The diagram (optionally) highlights **domain boundary violations**, giving you insights into possible cross-domain coupling issues.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pferd'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly using:
+
+```bash
+gem install pferd
+```
+
+## Usage
+
+To generate an ERD, simply run:
+
+```bash
+rake pferd:generate
+```
+
+## Defining Domains
+
+Pferd groups your models by domain using the `@domain` YARD tag. To specify the domain of a model, add a YARD comment above the model class definition. For example:
+
+```ruby
+# @domain payments
+class Transaction < ApplicationRecord
+  # Model code
+end
+```
+
+If a model does not have a `@domain` tag, it will be placed in the default domain (`Global` by default).
+
+## Configuration
+
+Pferd comes with configurable options that you can customise. Below is the default configuration:
+
+```ruby
+# Establish some default configs
+Pferd.configure do |config|
+  # Classes without an explicit domain tag should be in this domain
+  config.default_domain_name = 'Global'
+
+  # Exclude these classes
+  config.ignored_classes = []
+
+  # Exclude classes nested in these modules
+  config.ignored_modules = ['ActiveStorage']
+
+  # Load models matching these glob-paths
+  config.model_dirs = ['app/models']
+
+  # The name of the generated output file
+  config.output_file_name = 'pferd.png'
+end
+```
+
+### **How to customise:**
+You can modify the configuration within an initializer (`config/initializers/pferd.rb`):
+
+```ruby
+Pferd.configure do |config|
+  config.default_domain_name = 'Core'
+  config.ignored_classes = ['SomeTemporaryModel']
+  config.ignored_modules = ['ActiveStorage', 'ActionMailbox']
+  config.model_dirs = ['app/models', 'engines/*/app/models']
+  config.output_file_name = 'custom_erd.png'
+end
+```
+
+## Domain Boundary Violations
+
+Pferd will analyse your model associations and **highlight where models reference entities from another domain**. Violations will be clearly marked in the ERD using special edge styles (e.g., dashed or highlighted lines).
+
+This feature helps you identify and address cases where models may be overstepping domain boundaries, promoting better separation of concerns within your codebase.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/your-github/pferd). This project is intended to be a safe, welcoming space for collaboration.
+
+## License
+
+Pferd is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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/lib/pferd/entity.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require_relative 'entity_relationship'
+module Pferd
+  class Entity
+    attr_accessor :klass_name, :associations, :domain
+    alias name klass_name
+
+    def initialize(klass_name, associations, domain)
+      @klass_name = klass_name
+      @associations = Set.new
+      @domain = domain
+    end
+
+    def add_relationship(name: , domain: )
+      boundary_violation = self.domain != domain
+      associations.add(
+        EntityRelationship.new(name:, domain:, boundary_violation: boundary_violation)
+      )
+    end
+    def to_h
+      { entity: klass_name, domain: domain, associations: associations.map(&:to_h) }
+    end
+  end
+end

data/lib/pferd/entity_relationship.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "entity_relationship"
+module Pferd
+  EntityRelationship = Data.define(:name, :domain, :boundary_violation)
+end

data/lib/pferd/version.rb

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

data/lib/pferd.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "pferd/version"
+require_relative "pferd/entity"
+require "ostruct"
+module Pferd
+  class Error < StandardError; end
+
+  module_function
+
+  # just use an OpenStruct for flexible config until we know what configs we need
+  def configuration
+    @configuration ||= OpenStruct.new
+  end
+
+  def configure
+    yield(configuration)
+  end
+
+  # Establish some default configs
+  configure do |config|
+    # Classes without an explicit domain tag should be in this domain
+    config.default_domain_name = "Global"
+    # Exclude these classes
+    config.ignored_classes = []
+    # Exclude classes nested in these modules
+    config.ignored_modules = ["ActiveStorage"]
+    # Load models from these directories
+    config.model_dirs = ["app/models"]
+    # The name of the generated output file
+    config.output_file_name = "pferd.png"
+    # Highlight boundary violations
+    config.highlight_boundary_violations = true
+  end
+end
+# Load this last so that the Rake file has access to the above config.
+load "pferd/lib/tasks/pferd.rake"

data/lib/tasks/pferd.rake

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "rake"
+require "yard"
+require "pferd"
+require "graphviz"
+
+namespace :pferd do
+  # Load the models specified in config and generate their Docs
+  # (this is required to get the domain tag from the doc metadata)
+  YARD::Rake::YardocTask.new do |t|
+    t.files = Pferd.configuration.model_dirs.map { |dir| File.join(dir, "**", "*.rb") }
+    t.options = ["--tag", 'domain:"App domain"']
+  end
+
+  desc "Generate an ERD that shows models grouped by domain"
+  task draw_relationships: %i[environment pferd:yard] do
+    # Load the Yard registry
+    YARD::Registry.load!
+    MODEL_DOMAINS = Hash.new(Pferd.configuration.default_domain_name)
+
+    # Populate MODEL_DOMAINS with model names and their domains
+    YARD::Registry.all(:class).find_each do |klass_info|
+      domain_tag = klass_info.tags.find { |tag| tag.tag_name == "domain" }
+      MODEL_DOMAINS[klass_info.name.to_s] = domain_tag.text if domain_tag
+    end
+
+    # Load all models
+    Rails.application.eager_load!
+
+    entities = ApplicationRecord.descendants.map do |model|
+      next unless MODEL_DOMAINS.key?(model.name)
+
+      entity = Pferd::Entity.new(model.name, Set.new, MODEL_DOMAINS[model.name])
+      associations = (model.reflect_on_all_associations(:has_many) |
+        model.reflect_on_all_associations(:has_one))
+      associations.each do |assoc|
+        next if Pferd.configuration.ignored_classes.include?(assoc.klass.name)
+        next if Pferd.configuration.ignored_modules.any? do |module_name|
+          assoc.klass.name.start_with?(module_name)
+        end
+        # TODO: Figure out what to do with polymorphic relations
+        next if assoc.polymorphic?
+
+        entity.add_relationship(name: assoc.klass.name, domain: MODEL_DOMAINS[assoc.klass.name])
+      end.compact
+      entity
+    end.compact
+
+    g = GraphViz.new(:G, type: :digraph)
+    node_map = Hash.new { |hash, key| hash[key] = g.add_graph("cluster_#{key}", label: key) }
+
+    # Create subgraphs and nodes by domains
+    # Note: This has to be done as a complete loop before the next step, because we'll
+    # get an exception if we try to define edges before all of the nodes are defined.
+    entities.each do |entity|
+      subgraph = node_map[entity.domain]
+      subgraph.add_nodes(entity.name)
+    end
+    ##
+    # See above comment
+    # rubocop:disable Style/CombinableLoops
+    entities.each do |entity|
+      entity.associations.each do |relationship|
+        color = if Pferd.configuration.highlight_boundary_violations && relationship.boundary_violation
+                  "red"
+                else
+                  "black"
+                end
+        g.add_edges(entity.name, relationship.name, color: color, style: "dashed")
+      end
+    end
+    # rubocop:enable Style/CombinableLoops
+
+    # Generate output as PNG file
+    g.output(png: Pferd.configuration.output_file_name)
+  end
+  task default: :draw_relationships
+end

data/sig/pferd.rbs

@@ -0,0 +1,4 @@
+module Pferd
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: pferd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bodacious
+bindir: bin
+cert_chain: []
+date: 2025-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-graphviz
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Generate domain-based ERDs for Rails. Useful for modelling potential
+  conformations before committing to them
+email:
+- gavin@gavinmorrice.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pferd.rb
+- lib/pferd/entity.rb
+- lib/pferd/entity_relationship.rb
+- lib/pferd/version.rb
+- lib/tasks/pferd.rake
+- sig/pferd.rbs
+homepage: https://github.com/bodacious/pferd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bodacious/pferd
+  source_code_uri: https://github.com/bodacious/pferd
+  changelog_uri: https://github.com/bodacious/pferd
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Generate domain-based ERDs for Rails
+test_files: []