rails-flow-map 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f78da594cc75cdfdb7e606ab9eab72645b6a0752f6ff7096728ac7f3c86cd7d8
+  data.tar.gz: e479a8b273c9a1edda38170e91ae4638ecae27f74cfe33eb40f58464d6f6a777
+SHA512:
+  metadata.gz: 265c5fb6f05374d7c03d1019b98657714de4235aeaaca08a942cb0ff9adcb215c84b7b623ace2e0d13eddaf151c458e2e9865273cd7c0ca4996493ceb63ba221
+  data.tar.gz: 86619f1eeffea1277cf4ff4cfcddb73ab983b91658a77a19d26cb3bf1405ca7f73eb7bbb3e039e6459f54ab586944ad8867f963d252359d344ac8a1f089cdeb8

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# 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]
+
+## [0.1.0] - 2024-07-12
+
+### Added
+- Initial release of Rails Flow Map
+- Support for multiple visualization formats:
+  - Mermaid diagrams (GitHub-friendly)
+  - PlantUML class diagrams
+  - GraphViz network diagrams
+  - Interactive D3.js visualizations
+  - OpenAPI specifications
+  - Sequence diagrams
+  - ERD diagrams
+  - Metrics reports
+  - Git diff visualizations
+- Enterprise-grade security features:
+  - Path traversal protection
+  - XSS prevention
+  - Input validation
+  - Security event logging
+- Performance and reliability:
+  - Structured logging with performance metrics
+  - Robust error handling with context
+  - Retry logic for transient failures
+  - Memory optimization for large applications
+- Developer experience:
+  - Zero configuration setup
+  - Rake tasks integration
+  - VS Code task definitions
+  - Comprehensive documentation
+- Rail Engine integration
+- Configurable analysis options
+- Comprehensive test suite with security tests
+- YARD documentation for all public APIs
+- Usage examples and quick reference guides
+- Multi-language documentation (English, Japanese, Chinese)
+
+### Dependencies
+- Ruby >= 2.7.0
+- Rails >= 6.0
+- parser gem for AST analysis
+
+[Unreleased]: https://github.com/railsflowmap/rails-flow-map/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/railsflowmap/rails-flow-map/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rails Flow Map Team
+
+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,314 @@
+# Rails Flow Map 🚀
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/railsflowmap/rails-flow-map)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)
+
+> 🎯 **Comprehensive Rails Application Architecture Visualization Tool**
+
+Rails Flow Map is a powerful gem that analyzes your Rails application structure and generates beautiful, interactive visualizations to help understand architecture, dependencies, and data flow patterns.
+
+**[日本語](README_ja.md) | [中文](README_zh.md)**
+
+---
+
+## ✨ Features
+
+### 🎨 Multiple Visualization Formats
+- **🌊 Mermaid Diagrams** - GitHub-friendly markdown diagrams
+- **🏗️ PlantUML** - Detailed UML class diagrams  
+- **🔗 GraphViz** - Network-style relationship graphs
+- **⚡ Interactive D3.js** - Zoomable, draggable web visualizations
+- **📊 Metrics Reports** - Code quality and complexity analysis
+- **🔄 Sequence Diagrams** - API endpoint flow visualization
+- **📋 OpenAPI Specs** - Auto-generated API documentation
+- **📈 ERD Diagrams** - Database schema visualization
+- **🔍 Git Diff Views** - Architecture change comparisons
+
+### 🛡️ Enterprise-Grade Security
+- **Path Traversal Protection** - Prevents malicious file access
+- **XSS Prevention** - Sanitizes all HTML outputs
+- **Input Validation** - Comprehensive parameter checking
+- **Security Event Logging** - Tracks potential threats
+
+### ⚡ Performance & Reliability
+- **Structured Logging** - Performance metrics and debugging info
+- **Error Handling** - Robust exception management with context
+- **Retry Logic** - Automatic recovery from transient failures
+- **Memory Optimization** - Efficient processing for large applications
+
+### 🔧 Developer Experience
+- **Zero Configuration** - Works out of the box
+- **Flexible Integration** - Rake tasks, Ruby API, CI/CD support
+- **Comprehensive Documentation** - Examples and best practices
+- **VS Code Integration** - Built-in task definitions
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'rails-flow-map'
+```
+
+```bash
+bundle install
+rails generate rails_flow_map:install
+```
+
+### Basic Usage
+
+```ruby
+# Generate architecture overview
+graph = RailsFlowMap.analyze
+RailsFlowMap.export(graph, format: :mermaid, output: 'docs/architecture.md')
+
+# Create interactive visualization
+RailsFlowMap.export(graph, format: :d3js, output: 'public/architecture.html')
+
+# Generate API documentation
+RailsFlowMap.export(graph, format: :openapi, output: 'docs/api.yaml')
+```
+
+### Using Rake Tasks
+
+```bash
+# Generate all visualizations
+rake flow_map:generate
+
+# Specific format
+rake flow_map:generate FORMAT=mermaid OUTPUT=docs/flow.md
+
+# Analyze API endpoint
+rake flow_map:endpoint ENDPOINT=/api/v1/users FORMAT=sequence
+```
+
+---
+
+## 📊 Visualization Examples
+
+### 🌊 Mermaid Architecture Diagram
+
+```mermaid
+graph TD
+    User[User] --> Post[Post]
+    User --> Comment[Comment]
+    Post --> Comment
+    UsersController --> User
+    PostsController --> Post
+    API[/api/v1/users] --> UsersController
+```
+
+### ⚡ Interactive D3.js Visualization
+
+*Features: Zoom, drag, filter by component type, search functionality*
+
+### 📋 OpenAPI Documentation
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Rails API Documentation
+  version: 1.0.0
+paths:
+  /api/v1/users:
+    get:
+      summary: List all users
+      responses:
+        200:
+          description: Successful response
+```
+
+---
+
+## 🎯 Use Cases
+
+### 👥 For Development Teams
+
+- **📚 Documentation** - Auto-generate always up-to-date architecture docs
+- **🔍 Code Reviews** - Visualize architectural changes in PRs
+- **🎓 Onboarding** - Help new team members understand the codebase
+- **🏗️ Refactoring** - Identify dependencies before making changes
+
+### 🚀 For DevOps & CI/CD
+
+- **📊 Monitoring** - Track architecture complexity over time
+- **🔄 Automation** - Generate docs automatically on deployment
+- **📈 Metrics** - Collect code quality and dependency metrics
+- **🚨 Alerts** - Detect breaking architectural changes
+
+### 📋 For API Teams
+
+- **📖 API Docs** - Auto-generate OpenAPI specifications
+- **🔄 Flow Diagrams** - Visualize request/response flows
+- **🧪 Testing** - Understand endpoint dependencies
+- **📚 Client SDKs** - Provide clear API structure documentation
+
+---
+
+## 🔧 Configuration
+
+### Basic Configuration
+
+```ruby
+# config/initializers/rails_flow_map.rb
+RailsFlowMap.configure do |config|
+  config.output_directory = 'doc/flow_maps'
+  config.exclude_paths = ['vendor/', 'tmp/']
+  config.default_format = :mermaid
+end
+```
+
+### Advanced Configuration
+
+```ruby
+RailsFlowMap.configure do |config|
+  # Analysis options
+  config.include_models = true
+  config.include_controllers = true
+  config.include_routes = true
+  
+  # Performance options
+  config.streaming_mode = true
+  config.memory_limit = 512.megabytes
+  
+  # Security options
+  config.sanitize_output = true
+  config.allow_system_paths = false
+end
+```
+
+---
+
+## 📚 Documentation
+
+### Quick References
+- 📖 [**Usage Examples**](USAGE_EXAMPLES.md) - Comprehensive usage guide
+- ⚡ [**Quick Reference**](QUICK_REFERENCE.md) - Common commands and patterns
+- 🔧 [**API Documentation**](https://rubydoc.info/github/railsflowmap/rails-flow-map) - YARD documentation
+
+### Integration Guides
+- 🔄 [**CI/CD Integration**](docs/ci_cd_integration.md) - GitHub Actions, GitLab CI
+- 💻 [**VS Code Integration**](doc/vscode_integration.md) - Editor setup and tasks
+- 🐳 [**Docker Integration**](docs/docker_integration.md) - Containerized workflows
+
+### Examples
+- 🚀 [**Basic Examples**](examples/basic_usage.rb) - Getting started code samples
+- 🔬 [**Advanced Patterns**](examples/advanced_patterns.rb) - Complex use cases
+
+---
+
+## 🛠️ Supported Formats
+
+| Format | Description | Best For | Output |
+|--------|-------------|----------|---------|
+| `mermaid` | GitHub-friendly diagrams | Documentation, README | `.md` |
+| `plantuml` | Detailed UML diagrams | Technical documentation | `.puml` |
+| `d3js` | Interactive visualizations | Exploration, presentations | `.html` |
+| `openapi` | API specifications | API documentation | `.yaml` |
+| `sequence` | Request flow diagrams | API analysis | `.md` |
+| `erd` | Database schemas | Data modeling | `.md` |
+| `metrics` | Code quality reports | Code reviews, monitoring | `.md` |
+| `graphviz` | Network diagrams | Complex relationships | `.dot` |
+
+---
+
+## 🔗 Integrations
+
+### GitHub Actions
+
+```yaml
+name: Generate Architecture Docs
+on: [push]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+      - run: bundle exec rake flow_map:generate_all
+```
+
+### VS Code Tasks
+
+```json
+{
+  "label": "Generate Architecture Docs",
+  "type": "shell",
+  "command": "bundle exec rake flow_map:generate_all"
+}
+```
+
+### Pre-commit Hooks
+
+```bash
+#!/bin/bash
+bundle exec rake flow_map:diff > ARCHITECTURE_CHANGES.md
+git add ARCHITECTURE_CHANGES.md
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+git clone https://github.com/railsflowmap/rails-flow-map.git
+cd rails-flow-map
+bundle install
+rake spec
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test
+bundle exec rspec spec/rails_flow_map/formatters/mermaid_formatter_spec.rb
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+```
+
+---
+
+## 📄 License
+
+Rails Flow Map is released under the [MIT License](LICENSE).
+
+---
+
+## 🙏 Acknowledgments
+
+- Thanks to all [contributors](https://github.com/railsflowmap/rails-flow-map/contributors)
+- Inspired by the Rails community's need for better architecture visualization
+- Built with ❤️ for the Rails ecosystem
+
+---
+
+## 🔗 Links
+
+- 📖 [Documentation](https://docs.railsflowmap.org)
+- 🐛 [Bug Reports](https://github.com/railsflowmap/rails-flow-map/issues)
+- 💬 [Discussions](https://github.com/railsflowmap/rails-flow-map/discussions)
+- 🐦 [Twitter](https://twitter.com/railsflowmap)
+
+---
+
+<div align="center">
+
+**⭐ Star us on GitHub if Rails Flow Map helps your team! ⭐**
+
+[⬆ Back to top](#rails-flow-map-)
+
+</div>

data/README_ja.md

@@ -0,0 +1,314 @@
+# Rails Flow Map 🚀
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/railsflowmap/rails-flow-map)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)
+
+> 🎯 **包括的なRailsアプリケーションアーキテクチャ可視化ツール**
+
+Rails Flow MapはRailsアプリケーションの構造を解析し、アーキテクチャ、依存関係、データフローパターンの理解を助ける美しいインタラクティブな可視化を生成する強力なgemです。
+
+**[English](README.md) | [中文](README_zh.md)**
+
+---
+
+## ✨ 機能
+
+### 🎨 複数の可視化フォーマット
+- **🌊 Mermaid図** - GitHub対応のMarkdown図
+- **🏗️ PlantUML** - 詳細なUMLクラス図  
+- **🔗 GraphViz** - ネットワーク型関係図
+- **⚡ インタラクティブD3.js** - ズーム・ドラッグ可能なWeb可視化
+- **📊 メトリクスレポート** - コード品質・複雑性解析
+- **🔄 シーケンス図** - APIエンドポイントフロー可視化
+- **📋 OpenAPI仕様** - 自動生成API文書
+- **📈 ERD図** - データベーススキーマ可視化
+- **🔍 Git差分表示** - アーキテクチャ変更比較
+
+### 🛡️ エンタープライズレベルのセキュリティ
+- **パストラバーサル保護** - 悪意のあるファイルアクセスを防止
+- **XSS防止** - 全HTMLアウトプットのサニタイズ
+- **入力検証** - 包括的なパラメータチェック
+- **セキュリティイベントログ** - 潜在的脅威のトラッキング
+
+### ⚡ パフォーマンス・信頼性
+- **構造化ログ** - パフォーマンスメトリクスとデバッグ情報
+- **エラーハンドリング** - コンテキスト付き堅牢な例外管理
+- **リトライロジック** - 一時的な障害からの自動復旧
+- **メモリ最適化** - 大規模アプリケーション向け効率的処理
+
+### 🔧 開発者体験
+- **ゼロ設定** - すぐに使える
+- **柔軟な統合** - Rakeタスク、Ruby API、CI/CDサポート
+- **包括的ドキュメント** - 例とベストプラクティス
+- **VS Code統合** - 組み込みタスク定義
+
+---
+
+## 🚀 クイックスタート
+
+### インストール
+
+Gemfileに追加:
+
+```ruby
+gem 'rails-flow-map'
+```
+
+```bash
+bundle install
+rails generate rails_flow_map:install
+```
+
+### 基本的な使用方法
+
+```ruby
+# アーキテクチャ概要を生成
+graph = RailsFlowMap.analyze
+RailsFlowMap.export(graph, format: :mermaid, output: 'docs/architecture.md')
+
+# インタラクティブ可視化を作成
+RailsFlowMap.export(graph, format: :d3js, output: 'public/architecture.html')
+
+# API文書を生成
+RailsFlowMap.export(graph, format: :openapi, output: 'docs/api.yaml')
+```
+
+### Rakeタスクの使用
+
+```bash
+# 全ての可視化を生成
+rake flow_map:generate
+
+# 特定のフォーマット
+rake flow_map:generate FORMAT=mermaid OUTPUT=docs/flow.md
+
+# APIエンドポイント解析
+rake flow_map:endpoint ENDPOINT=/api/v1/users FORMAT=sequence
+```
+
+---
+
+## 📊 可視化例
+
+### 🌊 Mermaidアーキテクチャ図
+
+```mermaid
+graph TD
+    User[User] --> Post[Post]
+    User --> Comment[Comment]
+    Post --> Comment
+    UsersController --> User
+    PostsController --> Post
+    API[/api/v1/users] --> UsersController
+```
+
+### ⚡ インタラクティブD3.js可視化
+
+*機能: ズーム、ドラッグ、コンポーネントタイプ別フィルタ、検索機能*
+
+### 📋 OpenAPI文書
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Rails API Documentation
+  version: 1.0.0
+paths:
+  /api/v1/users:
+    get:
+      summary: 全ユーザーを取得
+      responses:
+        200:
+          description: 成功レスポンス
+```
+
+---
+
+## 🎯 使用例
+
+### 👥 開発チーム向け
+
+- **📚 文書化** - 常に最新のアーキテクチャ文書を自動生成
+- **🔍 コードレビュー** - PRでアーキテクチャ変更を可視化
+- **🎓 オンボーディング** - 新メンバーがコードベースを理解する支援
+- **🏗️ リファクタリング** - 変更前に依存関係を特定
+
+### 🚀 DevOps・CI/CD向け
+
+- **📊 モニタリング** - アーキテクチャ複雑性の経時変化を追跡
+- **🔄 自動化** - デプロイ時に文書を自動生成
+- **📈 メトリクス** - コード品質と依存関係メトリクスを収集
+- **🚨 アラート** - 破壊的なアーキテクチャ変更を検出
+
+### 📋 APIチーム向け
+
+- **📖 API文書** - OpenAPI仕様書を自動生成
+- **🔄 フロー図** - リクエスト/レスポンスフローを可視化
+- **🧪 テスト** - エンドポイント依存関係を理解
+- **📚 クライアントSDK** - 明確なAPI構造文書を提供
+
+---
+
+## 🔧 設定
+
+### 基本設定
+
+```ruby
+# config/initializers/rails_flow_map.rb
+RailsFlowMap.configure do |config|
+  config.output_directory = 'doc/flow_maps'
+  config.exclude_paths = ['vendor/', 'tmp/']
+  config.default_format = :mermaid
+end
+```
+
+### 高度な設定
+
+```ruby
+RailsFlowMap.configure do |config|
+  # 解析オプション
+  config.include_models = true
+  config.include_controllers = true
+  config.include_routes = true
+  
+  # パフォーマンスオプション
+  config.streaming_mode = true
+  config.memory_limit = 512.megabytes
+  
+  # セキュリティオプション
+  config.sanitize_output = true
+  config.allow_system_paths = false
+end
+```
+
+---
+
+## 📚 ドキュメント
+
+### クイックリファレンス
+- 📖 [**使用例**](USAGE_EXAMPLES.md) - 包括的な使用ガイド
+- ⚡ [**クイックリファレンス**](QUICK_REFERENCE.md) - 一般的なコマンドとパターン
+- 🔧 [**APIドキュメント**](https://rubydoc.info/github/railsflowmap/rails-flow-map) - YARD文書
+
+### 統合ガイド
+- 🔄 [**CI/CD統合**](docs/ci_cd_integration.md) - GitHub Actions、GitLab CI
+- 💻 [**VS Code統合**](doc/vscode_integration.md) - エディタ設定とタスク
+- 🐳 [**Docker統合**](docs/docker_integration.md) - コンテナ化ワークフロー
+
+### 例
+- 🚀 [**基本例**](examples/basic_usage.rb) - 入門コードサンプル
+- 🔬 [**高度なパターン**](examples/advanced_patterns.rb) - 複雑な使用例
+
+---
+
+## 🛠️ サポートされるフォーマット
+
+| フォーマット | 説明 | 適用場面 | 出力 |
+|--------|-------------|----------|---------|
+| `mermaid` | GitHub対応図 | 文書、README | `.md` |
+| `plantuml` | 詳細UML図 | 技術文書 | `.puml` |
+| `d3js` | インタラクティブ可視化 | 探索、プレゼン | `.html` |
+| `openapi` | API仕様書 | API文書 | `.yaml` |
+| `sequence` | リクエストフロー図 | API解析 | `.md` |
+| `erd` | データベーススキーマ | データモデリング | `.md` |
+| `metrics` | コード品質レポート | コードレビュー、監視 | `.md` |
+| `graphviz` | ネットワーク図 | 複雑な関係 | `.dot` |
+
+---
+
+## 🔗 統合
+
+### GitHub Actions
+
+```yaml
+name: アーキテクチャ文書生成
+on: [push]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+      - run: bundle exec rake flow_map:generate_all
+```
+
+### VS Codeタスク
+
+```json
+{
+  "label": "アーキテクチャ文書生成",
+  "type": "shell",
+  "command": "bundle exec rake flow_map:generate_all"
+}
+```
+
+### Pre-commitフック
+
+```bash
+#!/bin/bash
+bundle exec rake flow_map:diff > ARCHITECTURE_CHANGES.md
+git add ARCHITECTURE_CHANGES.md
+```
+
+---
+
+## 🤝 貢献
+
+貢献を歓迎します！詳細は[貢献ガイド](CONTRIBUTING.md)をご覧ください。
+
+### 開発環境設定
+
+```bash
+git clone https://github.com/railsflowmap/rails-flow-map.git
+cd rails-flow-map
+bundle install
+rake spec
+```
+
+### テスト実行
+
+```bash
+# 全テスト実行
+bundle exec rspec
+
+# 特定テスト実行
+bundle exec rspec spec/rails_flow_map/formatters/mermaid_formatter_spec.rb
+
+# カバレッジ付き実行
+COVERAGE=true bundle exec rspec
+```
+
+---
+
+## 📄 ライセンス
+
+Rails Flow Mapは[MITライセンス](LICENSE)でリリースされています。
+
+---
+
+## 🙏 謝辞
+
+- 全ての[貢献者](https://github.com/railsflowmap/rails-flow-map/contributors)に感謝
+- より良いアーキテクチャ可視化を求めるRailsコミュニティにインスパイア
+- Railsエコシステムへの❤️で構築
+
+---
+
+## 🔗 リンク
+
+- 📖 [ドキュメント](https://docs.railsflowmap.org)
+- 🐛 [バグレポート](https://github.com/railsflowmap/rails-flow-map/issues)
+- 💬 [ディスカッション](https://github.com/railsflowmap/rails-flow-map/discussions)
+- 🐦 [Twitter](https://twitter.com/railsflowmap)
+
+---
+
+<div align="center">
+
+**⭐ Rails Flow Mapがチームの役に立ったらGitHubでスターを！ ⭐**
+
+[⬆ トップに戻る](#rails-flow-map-)
+
+</div>