rails-mmd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2439ad7662a9d94eefa0adc2a8805699f5fb606a5a336d136c99f5d0586f8d7a
+  data.tar.gz: 8d87bf76c08dcad2af3d27f05aed3c4edd9067d344f04760e5d1778bc30f295b
+SHA512:
+  metadata.gz: eb2d72e44b51ce0ff58748a3d2be4cafba64f1619cb8886871d417343431bcfcdf6f8b20c2bf035f0dec2a515b016c117bab3dbbe496eecbefc9ffca8d0f3652
+  data.tar.gz: fbcce4fff00660bf1049ee7e04097ea05a315c4169834b746084302314c0c004c978033e6e3082598074789596a0503dbe321e00442ac7503143958aa3d1abef

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Generate Mermaid ER and class diagrams from explicitly configured Rails model domains.
+- Include primary and foreign key attributes and supported direct, through, polymorphic, and HABTM associations. See the [support matrix](docs/active-record-association-support.md) for limits.
+- Write validated render plans and structured diagnostics alongside diagrams, with deterministic output and atomic file replacement.
+- Verify Rails 7.2 with Ruby 4.0.6, and Rails 8.1 with Ruby 3.3.12 and 4.0.6, using real SQLite fixture applications.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AudioStakes
+
+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,82 @@
+# rails-mmd
+
+![rails-mmd — Rails models to Mermaid diagrams](docs/assets/branding/rails-mmd-social-preview.jpg)
+
+Generate Mermaid ER and class diagrams from the models and database schema of a Rails application. `rails-mmd` runs in the application's bundle, loads its models, and writes local `.mmd` source files. Preview them with a Mermaid viewer or embed their contents in a Markdown `mermaid` code block.
+
+```mermaid
+erDiagram
+  direction LR
+  USER }o..|| ACCOUNT : account
+  USER {
+    bigint id PK
+    bigint account_id FK
+  }
+  ACCOUNT {
+    bigint id PK
+  }
+```
+
+The diagram above is illustrative. The actual output depends on your models, associations, and database metadata.
+
+## Try it in a Rails app
+
+You need an existing Rails application with Active Record models and a prepared database. Check the [tested Ruby/Rails combinations](#compatibility-and-limits) below before installing. All commands in this section run from that application's root, not this repository.
+
+In the **target Rails application's** `Gemfile`, add the published [RubyGems package](https://rubygems.org/gems/rails-mmd):
+
+```ruby
+gem 'rails-mmd', '~> 0.1.0', require: false
+```
+
+Run `bundle install`. The application's `Gemfile.lock` records the selected release. At the application root, create `rails_mmd.yml` and replace the model names with real models in your app:
+
+```yaml
+version: 1
+domains:
+  core:
+    include_models:
+      - User
+      - Post
+output:
+  directory: tmp/rails_mmd
+  format: both
+  attributes: keys
+  direction: LR
+```
+
+Then run:
+
+```sh
+RAILS_ENV=development bundle exec rails-mmd generate
+```
+
+Inspect `tmp/rails_mmd/core.er.mmd` and `tmp/rails_mmd/core.class.mmd`. A successful run can be silent; these generated files are the result. To view the diagrams, follow [Viewing a generated diagram](docs/usage.md#viewing-a-generated-diagram). The selected environment must be able to boot and read its database schema. The command eager-loads the Rails application; run it only with an application and configuration you trust.
+
+The configuration selects models explicitly for each domain. Relationships are drawn between supported models selected in the same domain. To see all options, output files, diagnostics, and exit codes, read [the usage guide](docs/usage.md).
+
+## Compatibility and limits
+
+The gem declares Ruby `>= 3.3, < 4.1`. The local real-app matrix verifies Rails 7.2 on Ruby 4.0.6, and Rails 8.1 on Ruby 3.3.12 and 4.0.6. Other combinations within the Ruby range have not been verified by that matrix. The real-app matrix uses SQLite; PostgreSQL and MySQL have not been verified in a real-app run.
+
+Supported associations and current limits are listed in the [Active Record support matrix](docs/active-record-association-support.md). In particular, a domain spanning multiple database connection contexts is unsupported, as are composite keys and several association options. Check diagnostics when a diagram omits a relationship.
+
+Generated diagrams and JSON artifacts can reveal model names, table names, columns, relationships, and connection identifiers in diagnostics. Review them before committing or sharing them. Output must stay inside the application's root; for private schemas, add the output directory to the application's `.gitignore` (for this example, `/tmp/rails_mmd/`).
+
+See the [security policy](https://github.com/AudioStakes/rails-mmd/blob/main/SECURITY.md) for the Rails boot trust boundary and vulnerability reporting.
+
+## How it works
+
+The [generation pipeline](https://github.com/AudioStakes/rails-mmd/blob/main/lib/rails_mmd/generation_pipeline.rb) separates model inventory, domain selection, schema probing, relationship construction, and rendering. It converts Rails metadata into an intermediate representation and validated render plans; Mermaid serialization consumes those plans without querying Rails or the database.
+
+Relationship cardinality uses database foreign-key, nullability, and unique-index evidence. Structured diagnostics explain omitted unsupported associations and degraded metadata. The [pipeline specs](https://github.com/AudioStakes/rails-mmd/blob/main/spec/rails_mmd/generation_pipeline_spec.rb) exercise these stages together, and the [publisher specs](https://github.com/AudioStakes/rails-mmd/blob/main/spec/rails_mmd/publisher_spec.rb) cover validation, selected-domain output, and rollback when file replacement fails. The [real-app matrix](https://github.com/AudioStakes/rails-mmd/blob/main/docs/development/ci.md) checks the public command against the declared Ruby/Rails pairs.
+
+## Contributing and development
+
+See [CONTRIBUTING.md](https://github.com/AudioStakes/rails-mmd/blob/main/CONTRIBUTING.md) for local setup and checks, the [changelog](https://github.com/AudioStakes/rails-mmd/blob/main/CHANGELOG.md) for released changes, and the [release guide](https://github.com/AudioStakes/rails-mmd/blob/main/docs/development/releasing.md) for the manual publishing process. Implementation contracts are in [docs/p0-contract.md](https://github.com/AudioStakes/rails-mmd/blob/main/docs/p0-contract.md); the [development notes](https://github.com/AudioStakes/rails-mmd/blob/main/docs/development/tooling.md) cover the Rake tasks. The contributor guide and development notes are maintained in the repository, outside the installed gem. Serena is optional local development tooling, not a runtime dependency.
+
+The [P0 blocking fixture matrix](https://github.com/AudioStakes/rails-mmd/blob/main/docs/p0-blocking-fixture-matrix.md) records the required verification cases.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,40 @@
+# Security
+
+## Reporting a vulnerability
+
+Please do not put credentials, private application code, database contents, or
+exploit details in a public issue or pull request.
+
+Use [GitHub private vulnerability reporting](https://github.com/AudioStakes/rails-mmd/security/advisories/new)
+to send a suspected vulnerability to the maintainer privately.
+
+If the private form is unavailable, open an
+[issue](https://github.com/AudioStakes/rails-mmd/issues/new) asking the maintainer
+for a private reporting channel. Include only that request, with no sensitive
+details, and wait for a private channel before sharing the report.
+
+Once a private channel is established, include the affected commit or version,
+Ruby and Rails versions, expected and actual behavior, and a minimal reproduction
+using synthetic data. There is no guaranteed response time or published security
+backport policy yet.
+
+## Running rails-mmd safely
+
+`rails-mmd generate` loads the target application's `config/environment.rb` and
+eager-loads its Ruby code in the current process. Initializers and application
+code run with your operating-system permissions, environment, and database
+credentials. Use only applications and configuration you trust. Prefer a local
+development environment with a disposable database; application startup can have
+side effects even though rails-mmd inspects schema metadata rather than records.
+
+The tool writes artifacts under the application directory and does not upload
+them. Application startup code may still contact services. The YAML configuration
+uses safe loading, and output paths are checked against the application root;
+these checks do not sandbox application code.
+
+Generated diagrams and JSON artifacts contain model, table, column, and
+relationship names. Treat them as application documentation that may be
+confidential. Review artifacts and console output before sharing them or pasting
+them into an online Mermaid viewer. Diagnostic redaction is a limited safeguard,
+not a guarantee that every secret is removed; application logs are outside its
+control.

data/docs/active-record-association-support.md

@@ -0,0 +1,37 @@
+# Active Record association support (Rails 7.2 / 8.1)
+
+The target Rails series are 7.2 and 8.1. "Supported" describes behavior covered by the current implementation and tests; it does not imply support for every option of that association. The real-app matrix currently uses SQLite. PostgreSQL and MySQL have not been verified in a real-app run.
+
+## Implemented features
+
+| Priority | Active Record feature | Status | Implemented behavior |
+|---|---|---|---|
+| P1-01 | Rails 7.2 / 8.1 runtime compatibility | Supported | Three Ruby/Rails pairs run through the local real-app matrix. |
+| P1-02 | Association macro detection | Supported | Reflections are classified; unsupported macros produce diagnostics. |
+| P1-03 | Direct `has_many` / `has_one` | Supported | Direct associations and self joins have verified cardinalities. |
+| P1-04 | `inverse_of` | Supported | Physical relationships are merged into a canonical edge independently of an inverse declaration. |
+| P1-05 | `has_many :through` / `has_one :through` | Supported | Inferred-source one-step and nested paths are rendered as semantic edges without duplicate endpoints. |
+| P1-06 | Polymorphic associations | Supported | Selected matching inverse candidates produce one normalized edge per concrete target. |
+| P1-07 | `has_and_belongs_to_many` | Supported | A hidden join table is verified and rendered as one normalized many-to-many relationship. |
+
+## Not yet supported
+
+| Priority | Active Record feature | Needed for support |
+|---|---|---|
+| P2-01 | Scoped associations | Retain scope presence as metadata. |
+| P2-02 | STI | Define how base and derived classes appear. |
+| P2-03 | `delegated_type` | Render the delegator and concrete types. |
+| P2-04 | Composite primary/foreign keys and `query_constraints` | Preserve and match key tuples. |
+| P2-05 | Non-default `primary_key`, `source`, `source_type`, and `as` options | Resolve the target and key for each option. The supported polymorphic inverse case already uses `as:`. |
+| P2-06 | Cross-domain and multi-database relationships | Represent external nodes or emit diagnostics. |
+| P2-07 | `dependent`, `touch`, and `counter_cache` | Decide which behavior belongs in the diagram metadata. |
+| P3-01 | `disable_joins`, `strict_loading`, and async | Decide whether execution properties belong in the diagram. |
+| P3-02 | Association extensions | Represent or diagnose structural extensions. |
+
+The supported baseline covers non-polymorphic, unscoped, scalar direct `belongs_to`; scalar `foreign_key` and `class_name`; conservative cardinalities from foreign keys, nullability, and unique indexes; same-domain ER/class output; diagnostics for excluded supported `belongs_to`; direct polymorphic `belongs_to` with selected `has_many` / `has_one ..., as:` inverse candidates; and unscoped scalar HABTM with a verified hidden join table.
+
+## References
+
+- [P0 contract](https://github.com/AudioStakes/rails-mmd/blob/main/docs/p0-contract.md)
+- [Relationship builder](../lib/rails_mmd/relationship_builder.rb) and [render plan builder](../lib/rails_mmd/render_plan_builder.rb)
+- [Rails Association Basics](https://guides.rubyonrails.org/association_basics.html), [Rails 7.2 API](https://api.rubyonrails.org/v7.2/classes/ActiveRecord/Associations/ClassMethods.html), [Rails 8.1 API](https://api.rubyonrails.org/v8.1/classes/ActiveRecord/Associations/ClassMethods.html)

data/docs/usage.md

@@ -0,0 +1,126 @@
+# rails-mmd Usage
+
+Run `rails-mmd generate` from the **target Rails application's root**, with `rails-mmd` in that application's `Gemfile` (see the [quick start](../README.md)). The command loads and eager-loads the Rails app, reads metadata for selected models, builds Mermaid render plans, and publishes local artifacts. Use an environment that can boot the app and read its database schema.
+
+Booting also executes the application's initializers. Use an application and environment you trust; the [security policy](../SECURITY.md) describes this boundary and how to handle generated schema information.
+
+## Command
+
+```sh
+RAILS_ENV=development bundle exec rails-mmd generate \
+  --config rails_mmd.yml \
+  --output-dir tmp/rails_mmd \
+  --domain core \
+  --format both \
+  --fail-on-warning
+```
+
+`--config` is optional as an option, but the resolved configuration file must exist. Paths for output are relative to the application root; the output directory must stay within it. `--config` may be an absolute path.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--config PATH` | `rails_mmd.yml` | Configuration file to load |
+| `--output-dir DIR` | Config value, then `docs/rails_mmd` | Application-root-relative artifact directory |
+| `--domain ID` | All configured domains | Render one configured domain |
+| `--format er\|class\|both` | Config value, then `both` | Artifact formats to publish |
+| `--fail-on-warning` | False | Return exit `1` when warning diagnostics are present |
+
+## Minimal configuration
+
+```yaml
+version: 1
+domains:
+  core:
+    include_models:
+      - User
+    exclude_models: []
+output:
+  directory: tmp/rails_mmd
+  format: both
+  attributes: keys
+  direction: LR
+```
+
+Replace `User` with a named Active Record model in your app. `include_models` is required and must be nonempty. A model must be loaded and have usable table metadata. The command does not search for models automatically or install Mermaid CLI.
+
+## Configuration reference
+
+Unknown keys are rejected. The [configuration schema](../schemas/config.schema.json) is the machine-readable reference.
+
+| Key | Default | Allowed values / meaning |
+|---|---|---|
+| `version` | Required | Integer `1` |
+| `domains` | Required | One or more named model groups |
+| `domains.<id>.include_models` | Required | Nonempty list of exact Ruby constant names, such as `User` or `Billing::Invoice` |
+| `domains.<id>.exclude_models` | `[]` | Exact model names to remove from that domain's included set |
+| `output.directory` | `docs/rails_mmd` | Relative path inside the application root |
+| `output.format` | `both` | `er`, `class`, or `both` |
+| `output.attributes` | `keys` | `keys` shows primary and foreign keys; `none` hides attributes |
+| `output.direction` | `LR` | `LR` left to right, `RL` right to left, `TB` top to bottom, `BT` bottom to top |
+
+Domain IDs use lowercase letters and digits, start with a letter, and may contain single underscores between nonempty segments: `core` and `billing_v2` are valid; `Core`, `billing-v2`, and `billing__v2` are not. Model names are case-sensitive; wildcards and regular expressions are not supported. Each domain renders independently. Include both endpoints of a relationship in the same domain to display it.
+
+CLI values for `--output-dir` and `--format` override their YAML equivalents. `--domain` selects one configured domain; omitting it renders all domains. `attributes` and `direction` are YAML settings only.
+
+## Viewing a generated diagram
+
+The `.mmd` files contain Mermaid source, not an image or an HTML page. Open them in a local viewer with Mermaid support, or copy the contents of one file into a Markdown file between these fences:
+
+````markdown
+```mermaid
+<paste the contents of core.er.mmd here, replacing this line>
+```
+````
+
+Open that Markdown file in a viewer that renders Mermaid code blocks. An ordinary text editor displays the source only. The illustrative diagram in the [README](../README.md) demonstrates this embedding. Keep private application diagrams in a local viewer; copying them to a hosted editor shares their schema content with that service.
+
+## Artifacts
+
+Successful domains can publish:
+
+- `<domain>.diagnostics.json`
+- `<domain>.er.mmd`
+- `<domain>.er.render_plan.json`
+- `<domain>.class.mmd`
+- `<domain>.class.render_plan.json`
+
+`global.diagnostics.json` is published only for post-output invocation-scope diagnostics when applicable. Empty diagnostics files are omitted. A run replaces the managed artifacts for selected domains in the output directory; keep unrelated files separate from these names.
+
+Blocking diagnostics usually publish diagnostics JSON when output is available and omit the affected Mermaid and render-plan artifacts. Publish failures may fall back to sanitized stderr and leave previous managed artifacts intact. Pre-output fatal failures write sanitized diagnostics to stderr and write no files.
+
+The artifacts include application schema information and can include connection identifiers in diagnostics. Review them before sharing or committing them; use a private or ignored output directory for private schemas.
+
+## Exit codes
+
+| Exit | Meaning |
+|---:|---|
+| 0 | success, including warning diagnostics when `--fail-on-warning` is absent |
+| 1 | warning diagnostics were present and `--fail-on-warning` was set |
+| 2 | config, output setup, Rails boot, domain, or schema probe error |
+| 3 | Mermaid serialization failure or unresolved safe-token collision |
+| 4 | output write or atomic publish failure |
+| 99 | internal error |
+
+CLI argument errors also return exit `1` before generation starts. These include unknown options, unexpected positional arguments, missing option values, and invalid boolean values. Check stderr for the argument error.
+
+If the command reports a Rails load failure, check that you ran it from the application's root, in its bundle, and that the selected Rails environment can boot. If a model is missing, check its constant name and whether it was loaded by Rails. Domain and association limits are described in the [support matrix](active-record-association-support.md).
+
+## Troubleshooting
+
+Start with `bundle exec rails-mmd generate --help` to verify that the executable is available in the application's bundle. After generation, inspect `<domain>.diagnostics.json` in the output directory, along with stderr. A warning can omit an unsupported relationship while still returning exit `0`; use `--fail-on-warning` when omissions should fail a check.
+
+| Symptom | What to check |
+|---|---|
+| Bundler cannot find `rails-mmd` | Add the gem to the target application's Gemfile and run `bundle install` there. |
+| Unknown option, unexpected argument, or invalid boolean | Compare the command with `bundle exec rails-mmd generate --help`. Pass model names through YAML, not positional arguments. Use `--fail-on-warning` as a flag, or set it explicitly to `true` or `false`. |
+| Configuration file not found or invalid | Create `rails_mmd.yml` in the application root; compare keys and values with the configuration reference above. |
+| Rails boot or database metadata error | Use the application's usual setup instructions to prepare its dependencies, environment, and database. Run `RAILS_ENV=development bundle exec rails runner 'puts Rails.env'` to isolate boot failures. |
+| Model not found | Use its full constant name, including namespace, and ensure Rails eager loading can load it. |
+| Expected relationship is missing | Include both models in the same domain, inspect warning diagnostics, and check the support matrix for unsupported options. |
+| Output directory rejected | Use an application-root-relative path such as `tmp/rails_mmd`; paths escaping the root are rejected. |
+| Output write or publish failure | Check stderr and inspect the output directory before retrying; follow the recovery steps below. |
+| Diagram appears as text | Use a Mermaid-capable viewer or the Markdown embedding instructions above. |
+
+If publication and rollback both fail, originals that could not be restored remain in a hidden `.rails-mmd-backup-*` directory inside the output directory. Inspect those backups first. Correct the filesystem problem, such as permissions or insufficient disk space, then manually restore the originals you need and verify them before running generation again. Keep the backups until recovery is confirmed.
+
+`rails-mmd generate` does not invoke Mermaid CLI or any hosted service.

data/exe/rails-mmd

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'rails_mmd/cli'
+
+RailsMmd::CLI.start(ARGV)

data/fixtures/schemas/diagnostics/valid/catalog.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": 1,
+  "scope": "domain",
+  "domain_id": "core",
+  "diagnostics": [
+    { "diagnostic_id": "d_config_not_found", "code": "CONFIG_NOT_FOUND", "severity": "error", "phase": "config", "scope": "invocation", "subject_id": null, "message": "config missing", "metadata": { "config_path": "rails_mmd.yml" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_config_schema_invalid", "code": "CONFIG_SCHEMA_INVALID", "severity": "error", "phase": "config", "scope": "invocation", "subject_id": null, "message": "invalid config", "metadata": { "config_path": "rails_mmd.yml", "field_path": "$.domains" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_config_domain_not_found", "code": "CONFIG_DOMAIN_NOT_FOUND", "severity": "error", "phase": "config", "scope": "domain", "subject_id": "missing", "message": "domain missing", "metadata": { "domain_id": "missing" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_output_directory_invalid", "code": "OUTPUT_DIRECTORY_INVALID", "severity": "error", "phase": "output_setup", "scope": "invocation", "subject_id": null, "message": "bad output dir", "metadata": { "field_path": "$.output.directory", "reason": "absolute" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_domain_model_not_found", "code": "DOMAIN_MODEL_NOT_FOUND", "severity": "error", "phase": "domain_resolution", "scope": "domain", "subject_id": "core:MissingUser", "message": "model missing", "metadata": { "domain_id": "core", "ruby_constant": "MissingUser" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_domain_model_not_renderable", "code": "DOMAIN_MODEL_NOT_RENDERABLE", "severity": "error", "phase": "domain_resolution", "scope": "model", "subject_id": "core:Admin::User", "message": "model not renderable", "metadata": { "domain_id": "core", "ruby_constant": "Admin::User", "renderability_reason": "abstract" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_domain_empty", "code": "DOMAIN_EMPTY", "severity": "error", "phase": "domain_resolution", "scope": "domain", "subject_id": "core", "message": "domain empty", "metadata": { "domain_id": "core" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_rails_load_failed", "code": "RAILS_LOAD_FAILED", "severity": "error", "phase": "rails_load", "scope": "invocation", "subject_id": null, "message": "rails load failed", "metadata": { "exception_class": "RuntimeError", "exception_summary": "load failed", "backtrace": null }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_rails_eager_load_failed", "code": "RAILS_EAGER_LOAD_FAILED", "severity": "error", "phase": "rails_load", "scope": "invocation", "subject_id": null, "message": "eager load failed", "metadata": { "exception_class": "RuntimeError", "exception_summary": "eager failed", "backtrace": null }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_multi_db_unsupported", "code": "MULTI_DB_UNSUPPORTED", "severity": "error", "phase": "schema_probe", "scope": "domain", "subject_id": "core", "message": "multi database unsupported", "metadata": { "domain_id": "core", "connection_context_ids": ["{\"name\":\"primary\",\"role\":\"writing\",\"shard\":\"default\"}", "{\"name\":\"animals\",\"role\":\"writing\",\"shard\":\"default\"}"] }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_model_table_missing", "code": "MODEL_TABLE_MISSING", "severity": "error", "phase": "schema_probe", "scope": "model", "subject_id": "core:User", "message": "table missing", "metadata": { "domain_id": "core", "ruby_constant": "User", "table_name": "users" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_model_primary_key_unsupported", "code": "MODEL_PRIMARY_KEY_UNSUPPORTED", "severity": "error", "phase": "schema_probe", "scope": "model", "subject_id": "core:User", "message": "pk unsupported", "metadata": { "domain_id": "core", "ruby_constant": "User", "table_name": "users" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_target_unresolved", "code": "ASSOCIATION_TARGET_UNRESOLVED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "users.account", "message": "target unresolved", "metadata": { "domain_id": "core", "owner_constant": "User", "association_name": "account", "target_constant": "Account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_through_unresolved", "code": "ASSOCIATION_THROUGH_UNRESOLVED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "authors.teams", "message": "through reflection unresolved", "metadata": { "domain_id": "core", "owner_constant": "Author", "association_name": "teams" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_source_unresolved", "code": "ASSOCIATION_SOURCE_UNRESOLVED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "authors.teams", "message": "source reflection unresolved", "metadata": { "domain_id": "core", "owner_constant": "Author", "association_name": "teams" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_target_not_renderable_omitted", "code": "ASSOCIATION_TARGET_NOT_RENDERABLE_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "users.account", "message": "target omitted", "metadata": { "domain_id": "core", "owner_constant": "User", "association_name": "account", "target_constant": "Account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_polymorphic_omitted", "code": "ASSOCIATION_POLYMORPHIC_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "comments.commentable", "message": "polymorphic omitted", "metadata": { "domain_id": "core", "owner_constant": "Comment", "association_name": "commentable" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_polymorphic_targets_unresolved", "code": "ASSOCIATION_POLYMORPHIC_TARGETS_UNRESOLVED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "comments.commentable", "message": "polymorphic targets unresolved", "metadata": { "domain_id": "core", "owner_constant": "Comment", "association_name": "commentable" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_join_table_invalid", "code": "ASSOCIATION_JOIN_TABLE_INVALID", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "authors.tags", "message": "join table invalid", "metadata": { "domain_id": "core", "owner_constant": "Author", "association_name": "tags", "target_constant": "Tag", "join_table": "authors_tags", "reason": "unresolved" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_scoped_omitted", "code": "ASSOCIATION_SCOPED_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "orders.account", "message": "scoped omitted", "metadata": { "domain_id": "core", "owner_constant": "Order", "association_name": "account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_composite_key_omitted", "code": "ASSOCIATION_COMPOSITE_KEY_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "orders.account", "message": "composite key omitted", "metadata": { "domain_id": "core", "owner_constant": "Order", "association_name": "account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_key_column_missing", "code": "ASSOCIATION_KEY_COLUMN_MISSING", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "orders.account", "message": "key column missing", "metadata": { "domain_id": "core", "owner_constant": "Order", "association_name": "account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_non_primary_key_omitted", "code": "ASSOCIATION_NON_PRIMARY_KEY_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "orders.account", "message": "non primary key omitted", "metadata": { "domain_id": "core", "owner_constant": "Order", "association_name": "account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_name_unsupported_omitted", "code": "ASSOCIATION_NAME_UNSUPPORTED_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "orders.Account", "message": "association name unsupported", "metadata": { "domain_id": "core", "owner_constant": "Order", "association_name": "Account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_association_macro_omitted", "code": "ASSOCIATION_MACRO_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "authors.posts", "message": "association macro omitted", "metadata": { "domain_id": "core", "owner_constant": "Author", "association_name": "posts", "association_macro": "has_many" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_domain_relationship_omitted", "code": "DOMAIN_RELATIONSHIP_OMITTED", "severity": "warning", "phase": "relationship_build", "scope": "relationship", "subject_id": "orders.account", "message": "outside domain omitted", "metadata": { "domain_id": "core", "owner_constant": "Order", "association_name": "account", "target_constant": "Account" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_db_metadata_degraded", "code": "DB_METADATA_DEGRADED", "severity": "warning", "phase": "schema_probe", "scope": "domain", "subject_id": "core", "message": "metadata degraded", "metadata": { "domain_id": "core", "ruby_constant": "User", "metadata_kind": "foreign_key", "reason": "permission" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_safe_token_collision", "code": "SAFE_TOKEN_COLLISION", "severity": "warning", "phase": "tokenization", "scope": "artifact", "subject_id": "core:er", "message": "token collision resolved", "metadata": { "artifact_kind": "er", "domain_id": "core", "token_kind": "entity", "base_safe_token": "USER", "collision_subject_count": 2, "resolved": true }, "artifact_refs": [{ "artifact_kind": "render_plan", "domain_id": "core", "path": "core.er.render_plan.json" }], "remediation": null },
+    { "diagnostic_id": "d_mermaid_serialization_failed", "code": "MERMAID_SERIALIZATION_FAILED", "severity": "error", "phase": "serialization", "scope": "artifact", "subject_id": "core:er", "message": "serialization failed", "metadata": { "artifact_kind": "er", "domain_id": "core", "reason": "invalid token" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_output_write_failed", "code": "OUTPUT_WRITE_FAILED", "severity": "error", "phase": "publish", "scope": "invocation", "subject_id": null, "message": "write failed", "metadata": { "operation": "rename", "path": "core.er.mmd" }, "artifact_refs": [], "remediation": null },
+    { "diagnostic_id": "d_internal_error", "code": "INTERNAL_ERROR", "severity": "error", "phase": "internal", "scope": "invocation", "subject_id": null, "message": "internal error", "metadata": { "exception_class": "RuntimeError", "exception_summary": "unexpected", "backtrace": null }, "artifact_refs": [], "remediation": null }
+  ],
+  "digest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+}

data/lib/rails_mmd/artifact_ref_sanitizer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'rails_mmd/redactor'
+
+module RailsMmd
+  # Sanitizes and validates diagnostic artifact references.
+  class ArtifactRefSanitizer
+    ALLOWED_KEYS = %w[artifact_kind domain_id path].freeze
+    ARTIFACT_KINDS = %w[diagnostics er class render_plan stderr].freeze
+    DOMAIN_ID_PATTERN = /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/
+    PATH_PATTERN = %r{\A(?!/)(?!.*(?:^|/)\.\.(?:/|$))(?!.*//)[A-Za-z0-9._/-]+\z}
+    REQUIRED_KEYS = %w[artifact_kind domain_id].freeze
+
+    def initialize(redactor: Redactor.new)
+      @redactor = redactor
+    end
+
+    def sanitize(artifact_refs)
+      artifact_refs.map do |artifact_ref|
+        sanitize_reference(artifact_ref)
+      end
+    end
+
+    private
+
+    attr_reader :redactor
+
+    def sanitize_reference(artifact_ref)
+      reference = artifact_ref.to_h.transform_keys(&:to_s)
+      unknown_keys = reference.keys - ALLOWED_KEYS
+      raise ArgumentError, "unknown artifact ref keys: #{unknown_keys.join(', ')}" unless unknown_keys.empty?
+
+      validate_reference!(reference)
+      reference['path'] = safe_path(reference.fetch('path')) if reference.key?('path')
+      reference
+    end
+
+    def validate_reference!(reference)
+      missing_keys = REQUIRED_KEYS - reference.keys
+      raise ArgumentError, "missing artifact ref keys: #{missing_keys.join(', ')}" unless missing_keys.empty?
+      unless ARTIFACT_KINDS.include?(reference.fetch('artifact_kind'))
+        raise ArgumentError,
+              "invalid artifact_kind: #{reference.fetch('artifact_kind')}"
+      end
+
+      domain_id = reference.fetch('domain_id')
+      return if domain_id.nil? || domain_id.match?(DOMAIN_ID_PATTERN)
+
+      raise ArgumentError, "invalid artifact domain_id: #{domain_id}"
+    end
+
+    def safe_path(path)
+      path = redactor.sanitize(path)
+      return path if path.match?(PATH_PATTERN)
+
+      raise ArgumentError, "invalid artifact path: #{path}"
+    end
+  end
+end

data/lib/rails_mmd/attribute_types.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsMmd
+  # Normalizes DB/Rails attribute type hints for Mermaid-facing render plans.
+  module AttributeTypes
+    SUPPORTED_TYPES = %w[
+      bigint
+      boolean
+      date
+      datetime
+      decimal
+      float
+      integer
+      string
+      text
+      time
+      unknown
+    ].freeze
+
+    module_function
+
+    def normalize(value)
+      type = value.to_s.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/\A_+|_+\z/, '')
+      return type if SUPPORTED_TYPES.include?(type)
+
+      'unknown'
+    end
+  end
+end

data/lib/rails_mmd/canonical_json.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json/canonicalization'
+
+module RailsMmd
+  # RFC 8785/JCS canonical JSON helpers.
+  module CanonicalJson
+    module_function
+
+    def dump(value)
+      value.to_json_c14n
+    end
+
+    def digest_sha256(value)
+      Digest::SHA256.hexdigest(dump(value))
+    end
+  end
+end

data/lib/rails_mmd/cli.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'rails_mmd/config'
+require 'rails_mmd/generate_command'
+require_relative 'version'
+
+module RailsMmd
+  # Minimal Thor shell for smokeable help and version output.
+  class CLI < Thor
+    MISSING_OPTION_VALUE = Object.new.freeze
+    GENERATE_HELP = <<~HELP
+      Usage:
+        rails-mmd generate
+
+      Options:
+        [--config=CONFIG]            Required YAML file (default: rails_mmd.yml)
+        [--output-dir=OUTPUT_DIR]    Project-relative directory (default: docs/rails_mmd)
+        [--domain=DOMAIN]            One configured domain ID (default: all domains)
+        [--format=FORMAT]            er, class, or both (default: both)
+        [--fail-on-warning]          Exit 1 if any warning is emitted (default: false)
+
+      Run from the target Rails application root with bundle exec rails-mmd generate.
+      Config output.directory and output.format override the defaults; CLI options take precedence.
+    HELP
+
+    package_name 'rails-mmd'
+    remove_command :tree
+    default_task :help
+    check_unknown_options! only: :generate
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'version', 'Print rails-mmd version'
+    map '--version' => :version, '-v' => :version
+    def version
+      say RailsMmd::VERSION
+    end
+
+    desc 'generate', 'Generate Mermaid diagrams from a Rails app'
+    method_option :config, type: :string, lazy_default: MISSING_OPTION_VALUE
+    method_option :output_dir, type: :string, lazy_default: MISSING_OPTION_VALUE
+    method_option :domain, type: :string, lazy_default: MISSING_OPTION_VALUE
+    method_option :format, type: :string, lazy_default: MISSING_OPTION_VALUE
+    method_option :fail_on_warning, type: :string
+    method_option :help, type: :boolean, hide: true, aliases: '-h'
+    def generate(*args)
+      return say(GENERATE_HELP) if options[:help]
+      raise Thor::Error, 'Unexpected arguments. Run rails-mmd generate --help for usage.' unless args.empty?
+
+      result = GenerateCommand.new.run(cli_options: cli_options, fail_on_warning: fail_on_warning?)
+      emit_result(result)
+    end
+
+    no_commands do
+      def cli_options
+        missing = options.key(MISSING_OPTION_VALUE)
+        raise Thor::Error, "No value provided for option '--#{missing.tr('_', '-')}'" if missing
+
+        Config::CliOptions.new(
+          config_path: options[:config],
+          output_dir: options[:output_dir],
+          domain: options[:domain],
+          format: options[:format]
+        )
+      end
+
+      def emit_result(result)
+        print result.stdout unless result.stdout.empty?
+        warn result.stderr unless result.stderr.empty?
+        exit(result.exit_code)
+      end
+
+      def fail_on_warning?
+        return false if options[:fail_on_warning].nil?
+        return false if options[:fail_on_warning] == 'false'
+        return true if options[:fail_on_warning] == true
+        return true if %w[true fail_on_warning].include?(options[:fail_on_warning]) || options[:fail_on_warning].empty?
+
+        raise Thor::Error, '--fail-on-warning must be true or false'
+      end
+    end
+  end
+end