migflow 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d55af79f429534cba3daaff17a931b4ab66da0d78e0d183c96beb1101a70c91
+  data.tar.gz: cf93ff82fddc5c3e14d969fc0b25a8aea21415ec601d841f8406661dadb677b6
+SHA512:
+  metadata.gz: ac99ca3d89000e918cadeb4964abf7398ec5b80f4776b6ffac93e53f35eb4407d3964a3ca057028d3bafa14f7e6ab07406a36c09222c1ac996ada95f56c460c3
+  data.tar.gz: ba27f668b0d91263c48a4050bb42a2e2bd796f4e099c76beb59160edb62a039b8f75bf32e4d11ab7756664c5eefa80e3c06d3df582f19a7b72e0b7107d5b6235

data/.rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Internal engine; class/module doc comments add noise without public API docs.
+Style/Documentation:
+  Enabled: false
+
+# Defaults (e.g. MethodLength Max: 10) are too strict for this codebase.
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/ClassLength:
+  Max: 500
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/MethodLength:
+  Max: 55
+  CountComments: false
+
+Metrics/PerceivedComplexity:
+  Max: 18
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
+Layout/LineLength:
+  Exclude:
+    - "spec/**/*"

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-04-22
+
+### Fixed
+- Infinite "Loading schemas…" spinner in Flow and Schema views caused by `loadingBasePrevious` blocking rendering even when the previous-migration query was disabled or optional
+
+### Added
+- **Risk score** — every migration receives a numeric score (0–100) and a level (safe / low / medium / high) derived from six audit rules, displayed in the detail panel and exposed in the API
+- **CI report** — `bundle exec rails migflow:report` generates a Markdown or JSON audit report without starting a server; supports `FORMAT`, `FAIL_ON`, `FAIL_ON_SCORE`, and `OUTPUT` options
+- **GitHub Actions workflow** — `.github/workflows/ci-report.yml` triggers on pull requests touching `db/migrate/` and posts a Markdown summary to the step summary
+- `JsonReporter` and `MarkdownReporter` classes for structured report output
+- `ReportGenerator` service orchestrating parser → snapshot → diff → risk scoring pipeline
+
+### Changed
+- Minimum Ruby version raised to 3.2 (`Data.define` is not available in 3.1)
+- CI matrix extended to Ruby 3.2 and 3.3 across Rails 7.0, 7.1, and 7.2
+- RuboCop `TargetRubyVersion` aligned to 3.2
+
+## [0.1.0] - 2026-02-28
+
+### Added
+- Rails engine mounting at a configurable path (default `/migflow`)
+- Migration timeline — ordered list of all migrations with version, name, and one-line summary
+- Detail view — raw migration source, schema snapshot (`schema_after`), and audit warnings
+- Schema diff — focused and full unified diff of `schema.rb` between any two versions
+- Compare mode — pick any two migration versions to see a side-by-side schema delta
+- Schema graph (ERD) — interactive canvas with tables, columns, foreign-key edges, and diff highlights (added/removed coloring)
+- Audit rules: `MissingIndexRule`, `MissingForeignKeyRule`, `StringWithoutLimitRule`, `MissingTimestampsRule`, `DangerousMigrationRule`, `NullColumnWithoutDefaultRule`
+- REST API (`GET /api/migrations`, `GET /api/migrations/:version`, `GET /api/diff`)
+- Authentication hooks — `parent_controller`, `authentication_hook`, `unauthenticated_redirect`
+- `bin/setup` for one-command development setup
+- CI pipeline with RSpec, RuboCop, Vitest, ESLint, and frontend build
+- SimpleCov coverage enforcement (80% minimum)
+
+[Unreleased]: https://github.com/jv4lentim/migflow/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jv4lentim/migflow/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/jv4lentim/migflow/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Backend (Ruby gem)
+
+```bash
+bundle exec rake          # run tests + lint (default)
+bundle exec rake spec     # run RSpec tests only
+bundle exec rspec spec/path/to/file_spec.rb          # run a single spec file
+bundle exec rspec spec/path/to/file_spec.rb:42       # run a single example by line
+bundle exec rubocop       # lint
+bundle exec rubocop -a    # auto-correct safe offenses
+```
+
+### Frontend (React/TypeScript)
+
+```bash
+npm ci                    # install dependencies
+npm test                  # run Vitest unit tests
+npm run lint              # ESLint
+npm run build             # build to app/assets/
+npm run dev               # dev server (Vite)
+```
+
+### Environment matrix (CI)
+
+Tests run across Ruby 3.2/3.3 × Rails 7.0/7.1/7.2. Set `RAILS_VERSION` env var when running locally against a specific version (see Gemfile).
+
+## Architecture
+
+Migflow is a **mountable Rails engine** that provides migration visualization, schema diffs, and audit warnings via a REST API consumed by a React SPA.
+
+### Data flow
+
+```
+db/migrate/*.rb  →  MigrationParser   →  Array<MigrationSnapshot>
+db/schema.rb     →  SchemaParser      →  Hash of tables/columns/indexes
+
+MigrationSnapshot  →  MigrationDslScanner  →  SnapshotBuilder
+                                              (replays DSL calls to reconstruct
+                                               schema state at any point in history)
+
+before_snapshot + after_snapshot  →  DiffBuilder  →  SchemaDiff
+                                  →  SchemaPatchBuilder  →  unified diff hunks
+                                  →  AuditAnalyzer + 6 rules  →  Array<Warning>
+                                  →  MigrationSummaryBuilder  →  human summary
+```
+
+### Key layers
+
+| Layer | Location | Purpose |
+|---|---|---|
+| Parsers | `lib/migflow/parsers/` | Extract raw metadata from files on disk |
+| Models | `lib/migflow/models/` | Immutable `Data.define` value objects |
+| Services | `lib/migflow/services/` | Business logic (snapshot, diff, patch, summary) |
+| Analyzers | `lib/migflow/analyzers/` | Audit rules returning `Warning` objects |
+| Controllers | `app/controllers/migflow/api/` | JSON REST API |
+| Frontend | `frontend/src/` | React SPA (Timeline, ERD canvas, diff panel) |
+
+### API endpoints (mounted at `/migflow`)
+
+- `GET /api/migrations` — list all migrations with summaries
+- `GET /api/migrations/:id` — detail: schema before/after, patch hunks, warnings
+- `GET /api/diff?from=&to=` — compare two arbitrary migration versions
+
+### `SnapshotBuilder` — the core engine
+
+`SnapshotBuilder` is the most complex service. It replays migration DSL calls sequentially using `MigrationDslScanner` (regex-based parser for `create_table`, `add_column`, `add_index`, `add_foreign_key`, etc.) to reconstruct exact schema state at any historical point. Understanding this file is essential before touching snapshot or diff logic.
+
+### Audit rules (`lib/migflow/analyzers/rules/`)
+
+Six rule classes, each implementing `#check(migration_content, tables:) → Array<Warning>`:
+- `MissingIndexRule` — unindexed foreign keys
+- `MissingForeignKeyRule` — `_id` columns without DB constraints
+- `StringWithoutLimitRule` — string columns without `:limit`
+- `MissingTimestampsRule` — tables missing `created_at`/`updated_at`
+- `DangerousMigrationRule` — destructive ops (`remove_column`, `drop_table`, `rename_column`)
+- `NullColumnWithoutDefaultRule` — `null: false` column added without `:default`
+
+### Frontend
+
+State is managed with **Zustand** (`src/store/`) and server state with **@tanstack/react-query**. The ERD canvas uses **@xyflow/react**. Build output lands in `app/assets/` and is served by the engine's asset pipeline.
+
+## Conventions
+
+- Commits follow **Conventional Commits** (`feat:`, `fix:`, `chore:`, etc.)
+- Code coverage minimum: **80%** (enforced by SimpleCov in CI)
+- String literals use **double quotes** (RuboCop enforced)
+- Models use `Data.define` (Ruby 3.2+), not plain structs or `Struct.new`
+- RuboCop metrics are relaxed (AbcSize: 60, MethodLength: 55) — do not lower them without discussion
+
+## Development guidelines
+
+### After every change
+
+Always run the relevant checks after writing or modifying code — do not report a task complete before doing this:
+
+- **New feature / new files:** update `CLAUDE.md` (architecture section if the new layer/service/rule is non-trivial), `README.md` (if the feature is user-facing — new API endpoint, config option, or UI capability), and `CONTRIBUTING.md` (if the feature introduces a new pattern contributors must follow). Skip a file only when the change genuinely does not affect it.
+
+
+- **Backend change:** `bundle exec rspec` then `bundle exec rubocop`
+- **Frontend change:** `npm test` then `npm run lint` then `npm run build`
+- **Both touched:** run all five
+
+If any check fails, fix it before finishing.
+
+### Ruby / Rails
+
+- **SRP:** one class, one reason to change. Controllers only serialize/delegate; services own business logic; parsers own I/O and extraction. Do not mix concerns.
+- **No fat services:** if a service method exceeds ~15 lines or handles more than one distinct concern, extract a collaborator.
+- **DRY:** extract shared logic to a private method or a dedicated class. Never duplicate non-trivial logic across files.
+- **No code smells:** avoid long parameter lists (prefer keyword args), deep conditional nesting, feature envy, and primitive obsession (use value objects / `Data.define`).
+- **Query objects / service objects over callbacks:** keep models as plain value objects; do not add ActiveRecord callbacks or business logic to them.
+- **Explicit over magic:** prefer explicit method calls over `method_missing`, `define_method` loops, or `send` unless there is a strong justification.
+
+### React / TypeScript
+
+- **SRP for components:** one component, one visual responsibility. Extract sub-components when a component grows beyond ~80 lines or handles more than one distinct piece of UI.
+- **No business logic in components:** keep components presentational. Data fetching belongs in hooks (`src/hooks/`) or query hooks (`@tanstack/react-query`); derived state belongs in utils (`src/utils/`).
+- **DRY hooks:** shared stateful logic (e.g., selecting a migration, toggling a panel) belongs in a custom hook, not copy-pasted across components.
+- **Type everything:** no implicit `any`. Define domain types in `src/types/` and reuse them.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+joaovictorvalentim@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,157 @@
+# Contributing to Migflow
+
+Thank you for your interest in contributing. This document covers everything you need to get started.
+
+---
+
+## Table of Contents
+
+- [Getting started](#getting-started)
+- [Workflow](#workflow)
+- [Commit conventions](#commit-conventions)
+- [Validation](#validation)
+- [Backend guidelines](#backend-guidelines)
+- [Frontend guidelines](#frontend-guidelines)
+- [Opening a pull request](#opening-a-pull-request)
+
+---
+
+## Getting started
+
+**Prerequisites:** Ruby 3.3, Node 22.
+
+```bash
+git clone https://github.com/jv4lentim/migflow.git
+cd migflow
+bin/setup
+```
+
+`bin/setup` installs Ruby gems and frontend dependencies in one step.
+
+---
+
+## Workflow
+
+1. **Open an issue first** for bugs or features — agree on the approach before writing code.
+2. Fork the repo and create a branch from `main`:
+  ```bash
+   git checkout -b fix/missing-index-warning
+  ```
+3. Make your changes, keep commits focused (one logical change per commit).
+4. Run the full validation suite locally before pushing (see [Validation](#validation)).
+5. Open a pull request against `main`.
+
+Branch naming conventions:
+
+
+| Prefix      | Use for                              |
+| ----------- | ------------------------------------ |
+| `feat/`     | New features                         |
+| `fix/`      | Bug fixes                            |
+| `ci/`       | CI/CD changes                        |
+| `docs/`     | Documentation only                   |
+| `refactor/` | Refactoring without behavior change  |
+| `chore/`    | Maintenance (deps, tooling, configs) |
+
+
+---
+
+## Commit conventions
+
+Migflow follows [Conventional Commits](https://www.conventionalcommits.org/).
+
+### Format
+
+```
+<type>(<optional scope>): <short description>
+
+<optional body — explain the WHY, not the what>
+```
+
+### Rules
+
+- **Subject line:** 72 characters max, imperative mood, no period at the end.
+- **Body:** use it when the why is not obvious. Separate from subject with a blank line.
+- **Breaking changes:** add `!` after the type and a `BREAKING CHANGE:` footer.
+
+### Types
+
+
+| Type       | Use for                                              |
+| ---------- | ---------------------------------------------------- |
+| `feat`     | New user-facing feature                              |
+| `fix`      | Bug fix                                              |
+| `ci`       | CI/CD pipeline changes (workflows, scripts)          |
+| `docs`     | Documentation only                                   |
+| `refactor` | Code change with no behavior change                  |
+| `test`     | Adding or fixing tests                               |
+| `chore`    | Maintenance — deps, tooling, configs that are not CI |
+| `perf`     | Performance improvement                              |
+
+
+### Examples
+
+```
+feat(warnings): add null column without default rule
+
+fix(parser): handle migrations with frozen string literal comment
+
+ci: add Ruby/Rails compatibility matrix to backend job
+
+docs: add compatibility table to README
+
+chore: bump rubocop to 1.70
+```
+
+---
+
+## Validation
+
+Run these before opening a PR. All must pass.
+
+```bash
+# Backend tests
+bundle exec rake spec
+
+# Ruby linter
+bundle exec rubocop
+
+# Frontend — from the frontend/ directory
+npm ci
+npm run lint
+npm test
+npm run build
+```
+
+The CI pipeline runs the same steps across Ruby 3.2/3.3 × Rails 7.0/7.1/7.2. If your change is only backend, you do not need to rebuild frontend assets.
+
+---
+
+## Backend guidelines
+
+- Logic lives in `lib/migflow/` — keep it framework-agnostic where possible.
+- Controllers under `app/controllers/migflow/` should stay thin: delegate to services.
+- New rules belong in `lib/migflow/analyzers/rules/`, inheriting from `BaseRule`.
+- Write RSpec specs for every new class. Keep unit tests isolated from Rails when the class does not need it.
+- Do not lower the SimpleCov threshold (currently 80%). New code must be covered.
+
+---
+
+## Frontend guidelines
+
+- Components live in `frontend/src/components/`.
+- Use TypeScript. Avoid `any`.
+- New components need at least a render test with Vitest + Testing Library.
+- Do not add new npm dependencies without discussing in the issue first.
+- Keep the bundle size in mind — check `npm run build` output for size regressions.
+
+---
+
+## Opening a pull request
+
+- Fill in the PR description with what changed and why.
+- Link the related issue (`Closes #N`).
+- Keep PRs focused — one concern per PR is easier to review and revert.
+- A PR that only touches documentation does not need new tests.
+- Maintainers may ask for changes; address them in new commits (do not force-push during review).
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Joao Victor Valentim
+
+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.