pgdd 0.1.0

data/lib/pgdd/model_inspector.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Pgdd
+  # Reads what the application code says about one ActiveRecord model
+  class ModelInspector
+    SHOWN_OPTIONS = %i[through source source_type as polymorphic dependent inverse_of
+                       counter_cache optional required touch primary_key foreign_type
+                       autosave validate].freeze
+    ACTIVE_STORAGE = %w[ActiveStorage::Attachment ActiveStorage::Blob].freeze
+
+    def self.models
+      Rails.application.eager_load!
+      ActiveRecord::Base.descendants.select { |m| reportable?(m) }.sort_by(&:name)
+    end
+
+    def self.reportable?(model)
+      name = model.name
+      return false if name.nil? || model.abstract_class?
+
+      !name.include?('HABTM_') && !name.start_with?('ActiveRecord::', 'Pgdd::')
+    end
+
+    def initialize(model, root: Dir.pwd)
+      @model = model
+      @root  = root
+    end
+
+    def call
+      Model.new(
+        name:                 @model.name,
+        table_name:           @model.table_name,
+        database:             database_name,
+        source:               source,
+        sti_parent:           sti_parent,
+        sti_column:           sti_column,
+        associations:         associations,
+        **own_definitions
+      )
+    rescue StandardError => e
+      Model.new(name: @model.name, table_name: (@model.table_name rescue nil), error: "#{e.class}: #{e.message}")
+    end
+
+    # Definitions that can be inherited; an STI subclass only reports what it adds
+    def definitions
+      {
+        enums:                enums,
+        validations:          validations,
+        stored_attributes:    stored_attributes,
+        attachments:          attachments,
+        encrypted_attributes: encrypted_attributes,
+        virtual_attributes:   virtual_attributes
+      }
+    end
+
+    def own_definitions
+      mine = definitions
+      return mine unless sti_parent
+
+      inherited = self.class.new(@model.superclass, root: @root).definitions
+      mine.to_h { |key, value| [key, value.is_a?(Hash) ? value.reject { |k, v| inherited[key][k] == v } : value - inherited[key]] }
+    end
+
+    def database_name
+      @model.connection_db_config.name
+    rescue StandardError
+      'primary'
+    end
+
+    def source
+      path = Object.const_source_location(@model.name)&.first
+      return nil unless path
+
+      path = File.expand_path(path)
+      return path.delete_prefix("#{@root}/") if path.start_with?("#{@root}/")
+
+      path[%r{/gems/(.+)}, 1] || path
+    end
+
+    def sti_parent
+      @model.superclass.name unless @model.base_class == @model
+    end
+
+    # The inheritance column, when this model is the base of an STI hierarchy
+    def sti_column
+      column = @model.inheritance_column
+      return nil unless @model.base_class == @model && @model.descendants.any?
+
+      column if @model.column_names.include?(column)
+    rescue StandardError
+      nil
+    end
+
+    def associations
+      inherited = sti_parent ? @model.superclass.reflect_on_all_associations.map(&:name) : []
+
+      @model.reflect_on_all_associations.filter_map do |r|
+        next if inherited.include?(r.name) || ACTIVE_STORAGE.include?(r.options[:class_name].to_s)
+
+        options = r.options.slice(*SHOWN_OPTIONS)
+        options[:scope] = :lambda if r.scope
+        Association.new(
+          macro:       r.macro,
+          name:        r.name,
+          class_name:  r.polymorphic? ? nil : r.class_name,
+          foreign_key: (r.options[:through] ? nil : (r.foreign_key rescue nil)),
+          options:     options
+        )
+      end
+    end
+
+    # { attribute => { key => stored_value } }
+    def enums
+      @model.defined_enums.transform_values(&:to_h)
+    end
+
+    def validations
+      validators = @model.validators.map do |v|
+        Validation.new(kind: v.kind, attributes: v.attributes.map(&:to_s), options: v.options)
+      end
+      validators + custom_validations
+    end
+
+    # `validate :method_name` style validations, skipping the ones Rails adds itself
+    def custom_validations
+      @model._validate_callbacks.map(&:filter).grep(Symbol).filter_map do |name|
+        next if rails_method?(name)
+
+        Validation.new(kind: :validate, attributes: [name.to_s], options: {})
+      end
+    rescue StandardError
+      []
+    end
+
+    def rails_method?(name)
+      path = @model.instance_method(name).source_location&.first.to_s
+      path.match?(%r{/(activerecord|activemodel|activesupport)-[^/]+/})
+    rescue NameError
+      false
+    end
+
+    def stored_attributes
+      @model.stored_attributes.to_h { |store, keys| [store.to_s, keys.map(&:to_s)] }
+    end
+
+    def attachments
+      return [] unless @model.respond_to?(:reflect_on_all_attachments)
+
+      @model.reflect_on_all_attachments.map { |a| "#{a.name} (#{a.macro})" }
+    end
+
+    def encrypted_attributes
+      @model.respond_to?(:encrypted_attributes) ? @model.encrypted_attributes.to_a.map(&:to_s) : []
+    end
+
+    # Attributes declared with the attribute API that have no database column
+    def virtual_attributes
+      @model.attribute_types.keys - @model.column_names
+    rescue StandardError
+      []
+    end
+  end
+end

data/lib/pgdd/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pgdd
+  # Adds the pgdd:generate rake task to applications that bundle the gem
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path('../tasks/pgdd.rake', __dir__)
+    end
+  end
+end

data/lib/pgdd/readme_template.md

@@ -0,0 +1,61 @@
+# <%= app.name %> Database Documentation
+
+**Start with [<%= index %>](<%= index %>).** It is the primary file in this directory: it describes each database the application uses, lists every table with a link to that table's own page, and ends with the enum types and a data element index of every column.
+
+## As built, not as designed
+
+This documentation is **as built**. It is generated automatically, not written by hand, from two sources:
+
+- the schema of the database in the <%= app.environment %> environment, as it exists after every migration has run: tables, columns, types, indexes, foreign keys, constraints, triggers and enum types;
+- the ActiveRecord model definitions in the codebase: associations, enums, validations, STI hierarchies and delegated types.
+
+It therefore records what the application actually has, not what any design document says it should have. Where the two disagree, this directory is the one that is right about the current state, and the design document is the one that needs a conversation. The generation date and the schema version are recorded at the top of [<%= index %>](<%= index %>), and a warning appears there if the database had pending migrations when the report was generated.
+
+Do not edit these files by hand; regenerate them instead (see below). This README is generated too.
+
+## What is in this directory
+
+<%= files_table %>
+<%- if multi -%>
+
+There is more than one database, so page and diagram names are prefixed with the database name: `queue.jobs.md`.
+<%- end -%>
+<%- if erd_format -%>
+
+## Reading the diagrams
+
+Each table's page <%= image ? 'embeds' : 'has' %> a diagram of the table and the tables it is related to.
+
+**The table the page is about is drawn in full, with every column. The related tables are not.** A related table shows only its primary key and the columns that take part in the relationship being drawn, such as the foreign key column that points at the table in focus. This keeps a diagram readable: a table with a dozen children would otherwise stack a dozen full column lists on top of each other, and the picture becomes several screens tall.
+
+**The full schema of any table is one click away.** Every table name in a diagram is a link to that table's own markdown page, where all of its columns, indexes and constraints are listed. Column cells are links too.
+
+`<%= schema_stem %>.<%= erd_format %>` draws every table the same compact way, keys only, so that the shape of the whole database fits on one page.
+
+### Notation
+
+- An edge runs from the foreign key column of the child table to the primary key of the parent. The crow's foot marks the many side; the bar and ring mark the one, optional parent.
+- **Solid edges** are foreign keys that exist in the database.
+- **Dashed edges** are polymorphic associations declared in the models (`has_one`/`has_many ..., as:`), which Rails cannot back with a database foreign key. The related table shows the `_id` and `_type` column pair for these. A single bar instead of a crow's foot on the child end means the inverse is `has_one`.
+- Hovering over a table, a column or an edge shows its comment, where one exists, and for a dashed edge the model the type column must name.
+
+### Links inside the diagrams
+
+The table names and columns in each diagram are hyperlinks to the table pages, but **they do not work on GitHub**. GitHub shows an SVG as a static image, both when it is embedded in a page and when the file itself is viewed, and clicking an image on GitHub opens the image file. The same is true of most Markdown renderers. The links only work when the diagram is opened on its own in a browser from a checkout of the repository, where the pages sit next to it.
+
+For navigation that works everywhere, every page's Relations section starts with a list of the tables it references and the tables that reference it, each one a link, including the polymorphic associations. The Foreign Keys and Referenced By tables further down link to the related tables as well.
+<%- end -%>
+
+## Migrations
+
+Each table page lists every migration that changed the table, oldest first, with a link to the file and a summary of what it did to this table (`create_table`, `add_column availability`, `ALTER TABLE (SQL)`, and so on). The list is built by reading the migration files, not by replaying them, so it covers the schema DSL calls, the SQL inside `execute`, and backfills that go through a model with an explicit table name. A migration that touches a table only through application models it does not name will not appear. Only the forward direction is read; `down` methods are ignored.
+
+## Regenerating
+
+The files are produced by the `pgdd` gem, which boots the application, reads the database and the models, and writes the pages<%= ' and diagrams' if erd_format %> into this directory.<%= ' The diagrams are rendered with Graphviz, so `dot` has to be on the `PATH`.' if erd_format && erd_format != 'dot' %> This copy was generated on <%= date %> with:
+
+```bash
+<%= command %>
+```
+
+Run it after any migration that changes the schema and commit the result together with the migration.