lagoon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e61c00e57856f9b4ad31cdadc75bfcff1af554453d93a35804d32c29ea35fec
+  data.tar.gz: d3089dbe9a76eabc00e95d925981f2ff9c2d7418ea773209a72367789549b198
+SHA512:
+  metadata.gz: 169036710b052193519bc94501fba05f7e6a9cc6b32d4a03883c5ef06fa628f043a4c2c48529e4c28b1bee7ad1cdc70cac5fe114e8570ef787a25d59f260515e
+  data.tar.gz: 43a2172c67d6d46fb7a1f11a89050e151548b2b07f904481d001456e04c3ae06815a6c498563174c0c62bc2229ee816207bc79553be4931f9bde767e948934a7

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Yudai Takada
+
+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,229 @@
+# Lagoon
+
+Generate Mermaid diagrams from Rails models and controllers.
+
+Lagoon is a Ruby gem that generates Mermaid class diagrams and ER diagrams from Rails applications, inspired by [RailRoady](https://github.com/preston/railroady). Unlike RailRoady, which outputs DOT/SVG format and depends on Graphviz, Lagoon outputs Mermaid syntax that can be directly displayed on GitHub, GitLab, Notion, and other platforms that support Mermaid.
+
+## Features
+
+- Generate Mermaid class diagrams from ActiveRecord models
+- Generate Mermaid class diagrams from Rails controllers
+- Generate Mermaid ER diagrams from database schema
+- No external dependencies (no Graphviz required)
+- CLI tool and Rake tasks for easy integration
+- Configurable output options
+- Support for associations, inheritance, and foreign key relationships
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lagoon'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install lagoon
+```
+
+## Usage
+
+### Command Line Interface
+
+Lagoon provides a CLI tool for generating diagrams:
+
+```bash
+# Generate model class diagram
+lagoon models -o doc/models.mermaid
+
+# Generate controller class diagram
+lagoon controllers -o doc/controllers.mermaid
+
+# Generate ER diagram
+lagoon er -o doc/er_diagram.mermaid
+
+# Generate all diagrams
+lagoon all
+
+# Generate compact diagrams (no attributes/methods)
+lagoon models -b -i
+
+# Specify diagram direction
+lagoon models -d LR  # Left to Right (default: TB - Top to Bottom)
+
+# Show help
+lagoon help models
+```
+
+### Rake Tasks
+
+In your Rails application, you can use Rake tasks:
+
+```bash
+# Generate all diagrams
+rake mermaid:all
+
+# Generate specific diagrams
+rake mermaid:models
+rake mermaid:controllers
+rake mermaid:er
+
+# Generate brief diagrams
+rake mermaid:brief
+```
+
+### Programmatic Usage
+
+You can also use Lagoon programmatically in your Ruby code:
+
+```ruby
+require 'lagoon'
+
+# Configure Lagoon
+Lagoon.configure do |config|
+  config.output_dir = "doc/diagrams"
+  config.diagram_direction = "LR"
+  config.show_attributes = true
+  config.show_methods = false
+  config.include_inheritance = true
+  config.exclude_models = ["ApplicationRecord"]
+end
+
+# Generate diagrams
+Lagoon.generate_model_diagram
+Lagoon.generate_controller_diagram
+Lagoon.generate_er_diagram
+
+# Or generate all at once
+Lagoon.generate_all
+```
+
+## Configuration Options
+
+You can configure Lagoon globally or per-diagram:
+
+```ruby
+Lagoon.configure do |config|
+  config.output_dir = "doc/diagrams"          # Default: "doc/diagrams"
+  config.diagram_direction = "TB"              # Default: "TB" (Top to Bottom)
+                                               # Options: "TB", "BT", "LR", "RL"
+  config.show_attributes = true                # Default: true
+  config.show_methods = false                  # Default: false
+  config.include_inheritance = true            # Default: true
+  config.exclude_models = []                   # Default: []
+  config.exclude_controllers = []              # Default: []
+  config.diagram_format = :class_diagram       # Default: :class_diagram
+                                               # Options: :class_diagram, :er_diagram
+end
+```
+
+## CLI Options
+
+Lagoon CLI supports various options:
+
+### Model Diagrams
+
+- `-b, --brief`: Compact diagram (no attributes/methods)
+- `-i, --inheritance`: Include inheritance relationships
+- `-e, --exclude`: Exclude specified models
+- `-s, --specify`: Only process specified models
+- `-a, --all-models`: Include all models
+- `--show-belongs-to`: Show belongs_to associations
+- `--hide-through`: Hide through associations
+- `--all-columns`: Show all columns
+- `--hide-magic`: Hide magic fields (id, timestamps)
+- `--hide-types`: Hide attribute types
+
+### Controller Diagrams
+
+- `-b, --brief`: Compact diagram (no methods)
+- `-i, --inheritance`: Include inheritance relationships
+- `-e, --exclude`: Exclude specified controllers
+- `-s, --specify`: Only process specified controllers
+- `--hide-public`: Hide public methods
+- `--hide-protected`: Hide protected methods
+- `--hide-private`: Hide private methods
+
+### Common Options
+
+- `-o, --output`: Output file path
+- `-d, --direction`: Diagram direction (TB/BT/LR/RL)
+- `-r, --root`: Application root path
+- `-v, --verbose`: Enable verbose output
+
+## Output Examples
+
+### Model Class Diagram
+
+```mermaid
+classDiagram
+    direction TB
+
+    class User {
+        +Integer id
+        +String name
+        +String email
+        +DateTime created_at
+    }
+
+    class Post {
+        +Integer id
+        +String title
+        +Text content
+        +Integer user_id
+    }
+
+    User "1" --> "*" Post : has_many posts
+```
+
+### ER Diagram
+
+```mermaid
+erDiagram
+    USER ||--o{ POST : "has many"
+
+    USER {
+        int id PK
+        string name
+        string email
+        datetime created_at
+    }
+
+    POST {
+        int id PK
+        string title
+        text content
+        int user_id FK
+    }
+```
+
+## Requirements
+
+- Ruby >= 3.0.0
+- Rails >= 6.0 (for Rails integration)
+
+## 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/ydah/lagoon.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+Lagoon is inspired by [RailRoady](https://github.com/preston/railroady), which has been a valuable tool for Rails developers for many years.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/lagoon

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "lagoon"
+require "lagoon/cli"
+
+Lagoon::CLI.start(ARGV)

data/lib/lagoon/cli.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Lagoon
+  class CLI < Thor
+    class_option :verbose, type: :boolean, aliases: "-v", desc: "Enable verbose output"
+    class_option :output, type: :string, aliases: "-o", desc: "Output file path"
+    class_option :direction, type: :string, aliases: "-d", desc: "Diagram direction (TB/BT/LR/RL)"
+    class_option :root, type: :string, aliases: "-r", desc: "Application root path"
+
+    desc "models", "Generate Mermaid model diagram"
+    method_option :brief, type: :boolean, aliases: "-b", desc: "Compact diagram (no attributes/methods)"
+    method_option :inheritance, type: :boolean, aliases: "-i", desc: "Include inheritance relationships"
+    method_option :exclude, type: :array, aliases: "-e", desc: "Exclude specified models"
+    method_option :specify, type: :array, aliases: "-s", desc: "Only process specified models"
+    method_option :all_models, type: :boolean, aliases: "-a", desc: "Include all models"
+    method_option :show_belongs_to, type: :boolean, desc: "Show belongs_to associations"
+    method_option :hide_through, type: :boolean, desc: "Hide through associations"
+    method_option :all_columns, type: :boolean, desc: "Show all columns"
+    method_option :hide_magic, type: :boolean, desc: "Hide magic fields (id, timestamps)"
+    method_option :hide_types, type: :boolean, desc: "Hide attribute types"
+    def models
+      load_rails_environment
+      setup_configuration
+
+      output_file = Lagoon.generate_model_diagram(build_options)
+      say "Model diagram generated: #{output_file}", :green
+    end
+
+    desc "controllers", "Generate Mermaid controller diagram"
+    method_option :brief, type: :boolean, aliases: "-b", desc: "Compact diagram (no attributes/methods)"
+    method_option :inheritance, type: :boolean, aliases: "-i", desc: "Include inheritance relationships"
+    method_option :exclude, type: :array, aliases: "-e", desc: "Exclude specified controllers"
+    method_option :specify, type: :array, aliases: "-s", desc: "Only process specified controllers"
+    method_option :hide_public, type: :boolean, desc: "Hide public methods"
+    method_option :hide_protected, type: :boolean, desc: "Hide protected methods"
+    method_option :hide_private, type: :boolean, desc: "Hide private methods"
+    def controllers
+      load_rails_environment
+      setup_configuration
+
+      output_file = Lagoon.generate_controller_diagram(build_options)
+      say "Controller diagram generated: #{output_file}", :green
+    end
+
+    desc "er", "Generate Mermaid ER diagram"
+    method_option :exclude, type: :array, aliases: "-e", desc: "Exclude specified tables"
+    method_option :specify, type: :array, aliases: "-s", desc: "Only process specified tables"
+    def er
+      load_rails_environment
+      setup_configuration
+
+      output_file = Lagoon.generate_er_diagram(build_options)
+      say "ER diagram generated: #{output_file}", :green
+    end
+
+    desc "all", "Generate all diagrams"
+    method_option :brief, type: :boolean, aliases: "-b", desc: "Compact diagrams (no attributes/methods)"
+    def all
+      load_rails_environment
+      setup_configuration
+
+      results = Lagoon.generate_all(build_options)
+      say "All diagrams generated:", :green
+      say "  Models: #{results[:models]}", :green
+      say "  Controllers: #{results[:controllers]}", :green
+      say "  ER: #{results[:er]}", :green
+    end
+
+    desc "version", "Show version"
+    def version
+      say "Lagoon version #{Lagoon::VERSION}"
+    end
+
+    private
+
+    def load_rails_environment
+      rails_root = options[:root] || Dir.pwd
+
+      unless File.exist?(File.join(rails_root, "config", "environment.rb"))
+        say "Error: Rails application not found. Please run from Rails root or use --root option.", :red
+        exit 1
+      end
+
+      Dir.chdir(rails_root)
+      require File.expand_path("config/environment", rails_root)
+    rescue LoadError => e
+      say "Error loading Rails environment: #{e.message}", :red
+      exit 1
+    end
+
+    def setup_configuration
+      Lagoon.configure do |config|
+        config.diagram_direction = options[:direction] if options[:direction]
+        config.show_attributes = !options[:brief] if options.key?(:brief)
+        config.show_methods = !options[:brief] if options.key?(:brief)
+        config.include_inheritance = options[:inheritance] if options.key?(:inheritance)
+        config.exclude_models = options[:exclude] if options[:exclude]
+      end
+    end
+
+    def build_options
+      opts = options.dup
+      opts[:show_belongs_to] = true if opts[:show_belongs_to]
+      opts[:hide_through] = true if opts[:hide_through]
+      opts[:all_columns] = true if opts[:all_columns]
+      opts[:hide_magic] = true if opts[:hide_magic]
+      opts
+    end
+  end
+end

data/lib/lagoon/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Lagoon
+  class Configuration
+    attr_accessor :output_dir, :diagram_direction, :show_attributes,
+                  :show_methods, :include_inheritance, :exclude_models,
+                  :exclude_controllers, :diagram_format
+
+    def initialize
+      @output_dir = "doc/diagrams"
+      @diagram_direction = "TB"
+      @show_attributes = true
+      @show_methods = false
+      @include_inheritance = true
+      @exclude_models = []
+      @exclude_controllers = []
+      @diagram_format = :class_diagram # or :er_diagram
+    end
+  end
+end

data/lib/lagoon/diagram/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Lagoon
+  module Diagram
+    class Base
+      attr_reader :options, :config
+
+      def initialize(options = {})
+        @options = options
+        @config = Lagoon.configuration
+      end
+
+      def generate
+        raise NotImplementedError, "Subclasses must implement #generate"
+      end
+
+      protected
+
+      def output_path
+        @output_path ||= File.join(@config.output_dir, default_filename)
+      end
+
+      def default_filename
+        raise NotImplementedError, "Subclasses must implement #default_filename"
+      end
+
+      def ensure_output_directory
+        FileUtils.mkdir_p(@config.output_dir)
+      end
+
+      def write_to_file(content)
+        ensure_output_directory
+        File.write(output_path, content)
+        output_path
+      end
+    end
+  end
+end

data/lib/lagoon/diagram/controller_diagram.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Lagoon
+  module Diagram
+    class ControllerDiagram < Base
+      def generate
+        parser = Parser::ControllerParser.new(@options)
+        parsed_data = parser.parse
+
+        renderer = Renderer::ClassDiagramRenderer.new(
+          direction: @options[:direction] || @config.diagram_direction
+        )
+        content = renderer.render(parsed_data)
+
+        output_file = @options[:output] || output_path
+        ensure_output_directory
+        File.write(output_file, content)
+
+        output_file
+      end
+
+      protected
+
+      def default_filename
+        "controllers.mermaid"
+      end
+    end
+  end
+end

data/lib/lagoon/diagram/er_diagram.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Lagoon
+  module Diagram
+    class ErDiagram < Base
+      def generate
+        parser = Parser::SchemaParser.new(@options)
+        parsed_data = parser.parse
+
+        renderer = Renderer::ErDiagramRenderer.new(
+          direction: @options[:direction] || @config.diagram_direction
+        )
+        content = renderer.render(parsed_data)
+
+        output_file = @options[:output] || output_path
+        ensure_output_directory
+        File.write(output_file, content)
+
+        output_file
+      end
+
+      protected
+
+      def default_filename
+        "er_diagram.mermaid"
+      end
+    end
+  end
+end

data/lib/lagoon/diagram/model_diagram.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Lagoon
+  module Diagram
+    class ModelDiagram < Base
+      def generate
+        parser = Parser::ModelParser.new(@options)
+        parsed_data = parser.parse
+
+        renderer = Renderer::ClassDiagramRenderer.new(
+          direction: @options[:direction] || @config.diagram_direction
+        )
+        content = renderer.render(parsed_data)
+
+        output_file = @options[:output] || output_path
+        ensure_output_directory
+        File.write(output_file, content)
+
+        output_file
+      end
+
+      protected
+
+      def default_filename
+        "models.mermaid"
+      end
+    end
+  end
+end

data/lib/lagoon/parser/controller_parser.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Lagoon
+  module Parser
+    class ControllerParser
+      attr_reader :options, :config
+
+      def initialize(options = {})
+        @options = options
+        @config = Lagoon.configuration
+      end
+
+      def parse
+        controllers = load_controllers
+        classes = []
+        relationships = []
+
+        controllers.each do |controller|
+          next if excluded?(controller)
+
+          classes << parse_controller(controller)
+          relationships.concat(extract_inheritance(controller)) if config.include_inheritance
+        end
+
+        {
+          classes: classes,
+          relationships: relationships
+        }
+      end
+
+      private
+
+      def load_controllers
+        # Railsアプリケーションの全コントローラをロード
+        return [] unless defined?(Rails)
+
+        Rails.application.eager_load!
+        ActionController::Base.descendants
+      end
+
+      def excluded?(controller)
+        controller_name = controller.name
+        config.exclude_controllers.include?(controller_name)
+      end
+
+      def parse_controller(controller)
+        {
+          name: controller.name,
+          abstract: false,
+          attributes: [],
+          methods: extract_methods(controller)
+        }
+      end
+
+      def extract_methods(controller)
+        methods = []
+
+        # Public methods
+        unless options[:hide_public]
+          public_methods = controller.action_methods.to_a
+          methods.concat(public_methods.map { |m| { name: m, visibility: "+" } })
+        end
+
+        # Protected methods
+        unless options[:hide_protected]
+          protected_methods = controller.protected_instance_methods(false)
+          methods.concat(protected_methods.map { |m| { name: m, visibility: "#" } })
+        end
+
+        # Private methods
+        unless options[:hide_private]
+          private_methods = controller.private_instance_methods(false)
+          methods.concat(private_methods.map { |m| { name: m, visibility: "-" } })
+        end
+
+        methods
+      end
+
+      def extract_inheritance(controller)
+        return [] if controller.superclass == ActionController::Base
+        return [] unless controller.superclass.name
+
+        [{
+          source: controller.superclass.name,
+          target: controller.name,
+          type: :inheritance,
+          label: nil
+        }]
+      rescue StandardError
+        []
+      end
+    end
+  end
+end