lagoon 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e61c00e57856f9b4ad31cdadc75bfcff1af554453d93a35804d32c29ea35fec
-  data.tar.gz: d3089dbe9a76eabc00e95d925981f2ff9c2d7418ea773209a72367789549b198
+  metadata.gz: 7608b72eca2bd31b6580ce38174a7f3e1be9c562e0f1f626790783d2a8425493
+  data.tar.gz: cef98a67e5c8b0906f12da0a49cb00343d19b5e2cd50b45aad35369a5212e665
 SHA512:
-  metadata.gz: 169036710b052193519bc94501fba05f7e6a9cc6b32d4a03883c5ef06fa628f043a4c2c48529e4c28b1bee7ad1cdc70cac5fe114e8570ef787a25d59f260515e
-  data.tar.gz: 43a2172c67d6d46fb7a1f11a89050e151548b2b07f904481d001456e04c3ae06815a6c498563174c0c62bc2229ee816207bc79553be4931f9bde767e948934a7
+  metadata.gz: a51572bf6c1d22840b7a78a85759a6fe8b37c25d8139b46ca4125328fcdc6441905cbc9540e73e445d75852bdda84cfa36ded562623c28d80e5940232249650c
+  data.tar.gz: 467721a37e4d66144a619e5366e07d5f1fbe18479e98e93e4e40da47ccc333fb2822ebf2f24c097c4914d92a9dbe720d02ff73abcac6e93873e07c918211122e

data/Appraisals

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+appraise 'rails-6.1' do
+  gem 'actionpack', '~> 6.1.0'
+  gem 'activerecord', '~> 6.1.0'
+  gem 'railties', '~> 6.1.0'
+  gem 'sqlite3', '~> 1.4'
+end
+
+appraise 'rails-7.0' do
+  gem 'actionpack', '~> 7.0.0'
+  gem 'activerecord', '~> 7.0.0'
+  gem 'railties', '~> 7.0.0'
+  gem 'sqlite3', '~> 1.4'
+end
+
+appraise 'rails-7.1' do
+  gem 'actionpack', '~> 7.1.0'
+  gem 'activerecord', '~> 7.1.0'
+  gem 'railties', '~> 7.1.0'
+end
+
+appraise 'rails-7.2' do
+  gem 'actionpack', '~> 7.2.0'
+  gem 'activerecord', '~> 7.2.0'
+  gem 'railties', '~> 7.2.0'
+end
+
+appraise 'rails-8.0' do
+  gem 'actionpack', '~> 8.0.0'
+  gem 'activerecord', '~> 8.0.0'
+  gem 'railties', '~> 8.0.0'
+end
+
+appraise 'rails-8.1' do
+  gem 'actionpack', '~> 8.1.0'
+  gem 'activerecord', '~> 8.1.0'
+  gem 'railties', '~> 8.1.0'
+end

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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]
+## Unreleased
 
-- Initial release
+## 0.2.0 - 2026-07-16
+
+- Added structured generation results with content, warnings, and counts.
+- Added application-only discovery, strict analysis, configurable current-principal helpers, multi-database ER generation, and atomic output.
+- Fixed all declared CLI and Rake options, including brief, exclude/specify, all-models, hide-magic, and hide-types.
+- Fixed ER relationship direction and cardinality using actual foreign key, primary key, unique index, and nullability metadata.
+- Changed controller-model output to UML dependency relationships and expanded AST analysis for callbacks, helper methods, namespaces, local variables, and association chains.
+- Added Prism as a runtime dependency while retaining lazy AST loading.
+- Added Ruby/Rails/adapter CI matrices, end-to-end Rails coverage, Mermaid parser validation, package smoke tests, linting, and RBS validation.
+
+## 0.1.0 - 2025-12-17
+
+- Initial release

data/README.md

@@ -1,229 +1,194 @@
 # 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.
+Lagoon generates deterministic Mermaid diagrams from Rails models, controllers, and database metadata.
 
 ## 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
+- Active Record model class diagrams with attributes, declared methods, associations, inheritance, STI handling, and polymorphic/through labels
+- Controller class diagrams with declared public, protected, and private methods
+- ER diagrams based on actual primary keys, foreign keys, unique indexes, nullability, and one-to-one constraints
+- Controller-to-model dependency diagrams based on Prism AST analysis
+- Application-only discovery by default, with explicit opt-in for engine and gem classes
+- Atomic file output and structured results containing content, warnings, and counts
+- No external diagram-rendering binary required; Lagoon writes Mermaid source directly
+
+Lagoon depends on the Ruby gems Active Support, Prism, and Thor. A Rails application supplies Active Record and Action Pack.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add Lagoon to your application's Gemfile:
 
 ```ruby
-gem 'lagoon'
+gem "lagoon"
 ```
 
-And then execute:
+Then run:
 
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
+## CLI
+
+Run commands from the Rails application root, or pass `--root PATH`:
 
 ```bash
-gem install lagoon
+lagoon models -o doc/models.mermaid
+lagoon controllers -o doc/controllers.mermaid
+lagoon er -o doc/er_diagram.mermaid
+lagoon controller_models -o doc/controller_models.mermaid
+lagoon all -o doc/diagrams
 ```
 
-## Usage
+For `all`, `--output` is a directory. Lagoon writes `models.mermaid`, `controllers.mermaid`, `er_diagram.mermaid`, and `controller_models.mermaid` inside it.
 
-### Command Line Interface
-
-Lagoon provides a CLI tool for generating diagrams:
+Useful model options:
 
 ```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
+lagoon models --brief
+lagoon models --exclude Audit Event --specify User Post
+lagoon models --all-models --show-belongs-to --hide-through
+lagoon models --hide-magic --hide-types
+lagoon models --direction LR --no-inheritance
+```
 
-# Generate all diagrams
-lagoon all
+- `--brief` hides attributes and methods.
+- `--all-models` includes loaded models outside `app/models`; the default is application models only.
+- `--hide-magic` hides `id`, `created_at`, and `updated_at`. They are shown by default.
+- `--all-columns` overrides `--hide-magic`.
+- `--hide-types` keeps attribute names but omits their types.
 
-# Generate compact diagrams (no attributes/methods)
-lagoon models -b -i
+Controller and ER filtering use the same `--exclude` and `--specify` contract. `--strict` stops at the first analysis error; otherwise supported per-item failures are returned as warnings and generation continues. Use `--verbose` to print warnings and detailed CLI errors.
 
-# Specify diagram direction
-lagoon models -d LR  # Left to Right (default: TB - Top to Bottom)
+Controller commands also accept `--all-controllers` to include loaded controllers outside `app/controllers`.
 
-# Show help
-lagoon help models
-```
+Direction (`TB`, `BT`, `LR`, or `RL`) is exposed only for class-based diagrams: models, controllers, controller-model dependencies, and `all`.
 
-### Rake Tasks
+## Rake tasks
 
-In your Rails application, you can use Rake tasks:
+The Railtie provides:
 
 ```bash
-# Generate all diagrams
 rake mermaid:all
-
-# Generate specific diagrams
 rake mermaid:models
 rake mermaid:controllers
 rake mermaid:er
-
-# Generate brief diagrams
+rake mermaid:controller_models
 rake mermaid:brief
 ```
 
-### Programmatic Usage
+`mermaid:brief` passes the same normalized `brief: true` option used by the CLI.
 
-You can also use Lagoon programmatically in your Ruby code:
+## Programmatic API
 
 ```ruby
-require 'lagoon'
+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"]
+  config.exclude_models = ["Audit"]
+  config.exclude_controllers = ["HealthController"]
+  config.exclude_tables = ["solid_queue_jobs"]
+  config.internal_tables = %w[schema_migrations ar_internal_metadata]
+  config.helper_models = {
+    "current_user" => "User",
+    "current_account" => "Account"
+  }
+  config.strict = false
 end
 
-# Generate diagrams
-Lagoon.generate_model_diagram
-Lagoon.generate_controller_diagram
-Lagoon.generate_er_diagram
+result = Lagoon.generate_model_diagram(
+  output: "doc/models.mermaid",
+  show_methods: true,
+  show_belongs_to: true
+)
 
-# Or generate all at once
-Lagoon.generate_all
+puts result.path
+puts result.content
+warn result.warnings.join("\n")
+p result.counts
 ```
 
-## Configuration Options
+Every generator returns `Lagoon::Result` with `path`, `content`, `warnings`, and `counts`. `Result#to_s` and `Result#to_path` return the output path.
 
-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
-```
+Configuration is snapshotted for each generation, so per-call options do not mutate global state. Unknown option keys and invalid directions raise `Lagoon::ConfigurationError`. Use `Lagoon.reset_configuration!` to restore defaults.
 
-## CLI Options
+`Lagoon.generate_all(output: "doc/diagrams", brief: true)` eager-loads Rails once and returns a hash of four `Lagoon::Result` objects.
 
-Lagoon CLI supports various options:
+### Multiple databases
 
-### Model Diagrams
+ER generation discovers the Active Record connection pools. Explicit connections can also be supplied:
 
-- `-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
+```ruby
+Lagoon.generate_er_diagram(
+  connections: {
+    primary: ActiveRecord::Base.connection,
+    archive: ArchiveRecord.connection
+  }
+)
+```
 
-### Controller Diagrams
+When more than one connection is used, entity identifiers are qualified with the connection name.
 
-- `-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
+## Output semantics
 
-### Common Options
+ER relationships are oriented from the referenced table to the table containing the foreign key. For a required, non-unique `posts.user_id` foreign key, Lagoon emits:
 
-- `-o, --output`: Output file path
-- `-d, --direction`: Diagram direction (TB/BT/LR/RL)
-- `-r, --root`: Application root path
-- `-v, --verbose`: Enable verbose output
+```mermaid
+erDiagram
+    USERS ||..o{ POSTS : "has many"
+```
 
-## Output Examples
+The dotted line denotes a non-identifying relationship. A foreign key that is part of the child's primary key is emitted as identifying; nullable and unique foreign keys adjust both cardinalities.
 
-### Model Class Diagram
+Controller-model output uses UML dependencies rather than ER cardinalities:
 
 ```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
+    UsersController ..> User : index, show
+    UsersController ..> Post : show
 ```
 
-### ER Diagram
+## Controller-model analysis
 
-```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
-    }
-```
+Lagoon validates references against loaded `ActiveRecord::Base.descendants` and association reflection. It recognizes:
 
-## Requirements
+- direct and namespaced constants, including acronym names
+- standalone model constants
+- instance and local variables
+- block parameters and chained associations
+- `before_action` methods
+- argument-free controller helper/private method calls
+- configurable current-principal helpers such as `current_user`
+- inherited actions and source locations outside the conventional controller path
 
-- Ruby >= 3.0.0
-- Rails >= 6.0 (for Rails integration)
+It deliberately ignores arbitrary calls such as `@user.save` and non-model constants such as service objects. Dynamic constantization, metaprogrammed references, and model use hidden behind service objects remain outside static analysis.
 
-## Development
+## Requirements
 
-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.
+- Ruby 3.2 or newer
+- Rails 6.1 or newer
 
-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).
+CI exercises Ruby 3.2 through 4.0, Rails 6.1 through 8.1, and SQLite/PostgreSQL/MySQL schema integrations.
 
-## Contributing
+## Development
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/lagoon.
+```bash
+bundle install
+bundle exec rake
+```
 
-## License
+The default task runs RSpec (including a minimal Rails end-to-end fixture), Ruby syntax compilation, all RuboCop checks, RBS validation, and gem build. Mermaid CLI parsing runs when `MERMAID_CLI` is set, for example:
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```bash
+MERMAID_CLI=mmdc bundle exec rspec spec/integration/mermaid_syntax_spec.rb
+```
 
-## Acknowledgments
+## License
 
-Lagoon is inspired by [RailRoady](https://github.com/preston/railroady), which has been a valuable tool for Rails developers for many years.
+Lagoon is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -1,8 +1,22 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+RuboCop::RakeTask.new
+
+desc 'Validate RBS signatures'
+task 'rbs:validate' do
+  sh 'bundle exec rbs -I sig validate'
+end
+
+desc 'Compile every Ruby file'
+task :syntax do
+  ruby_files = FileList['lib/**/*.rb', 'exe/*', 'spec/**/*.rb', '*.gemspec', 'Rakefile']
+  ruby_files.each { |file| RubyVM::InstructionSequence.compile_file(file) }
+end
+
+task default: %i[spec syntax rubocop rbs:validate build]

data/exe/lagoon

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

data/gemfiles/adapters.gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '>= 6.1'
+gem 'activerecord', '>= 6.1'
+gem 'mysql2', '~> 0.5'
+gem 'pg', '~> 1.5'
+gem 'railties', '>= 6.1'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'simplecov', '~> 0.22', require: false
+gem 'sqlite3', '>= 1.4'
+
+gemspec path: '../'

data/gemfiles/rails_6.1.gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '~> 6.1.0'
+gem 'activerecord', '~> 6.1.0'
+gem 'irb'
+gem 'railties', '~> 6.1.0'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'sqlite3', '~> 1.4'
+
+group :development, :test do
+  gem 'appraisal', '~> 2.5'
+  gem 'mutex_m'
+  gem 'rbs', '>= 3.0'
+  gem 'rubocop', '>= 1.70', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end
+
+gemspec path: '../'

data/gemfiles/rails_7.0.gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '~> 7.0.0'
+gem 'activerecord', '~> 7.0.0'
+gem 'irb'
+gem 'railties', '~> 7.0.0'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'sqlite3', '~> 1.4'
+
+group :development, :test do
+  gem 'appraisal', '~> 2.5'
+  gem 'mutex_m'
+  gem 'rbs', '>= 3.0'
+  gem 'rubocop', '>= 1.70', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end
+
+gemspec path: '../'

data/gemfiles/rails_7.1.gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '~> 7.1.0'
+gem 'activerecord', '~> 7.1.0'
+gem 'irb'
+gem 'railties', '~> 7.1.0'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'sqlite3', '>= 1.4'
+
+group :development, :test do
+  gem 'appraisal', '~> 2.5'
+  gem 'mutex_m'
+  gem 'rbs', '>= 3.0'
+  gem 'rubocop', '>= 1.70', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end
+
+gemspec path: '../'

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '~> 7.2.0'
+gem 'activerecord', '~> 7.2.0'
+gem 'irb'
+gem 'railties', '~> 7.2.0'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'sqlite3', '>= 1.4'
+
+group :development, :test do
+  gem 'appraisal', '~> 2.5'
+  gem 'mutex_m'
+  gem 'rbs', '>= 3.0'
+  gem 'rubocop', '>= 1.70', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end
+
+gemspec path: '../'

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '~> 8.0.0'
+gem 'activerecord', '~> 8.0.0'
+gem 'irb'
+gem 'railties', '~> 8.0.0'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'sqlite3', '>= 1.4'
+
+group :development, :test do
+  gem 'appraisal', '~> 2.5'
+  gem 'mutex_m'
+  gem 'rbs', '>= 3.0'
+  gem 'rubocop', '>= 1.70', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end
+
+gemspec path: '../'

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'actionpack', '~> 8.1.0'
+gem 'activerecord', '~> 8.1.0'
+gem 'irb'
+gem 'railties', '~> 8.1.0'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'sqlite3', '>= 1.4'
+
+group :development, :test do
+  gem 'appraisal', '~> 2.5'
+  gem 'mutex_m'
+  gem 'rbs', '>= 3.0'
+  gem 'rubocop', '>= 1.70', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end
+
+gemspec path: '../'