rails2qdbd 0.1.0

data/lib/rails2qdbd/schema_parser.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "prism"
+require "active_support/inflector"
+
+module Rails2qdbd
+  # Reads the db/schema.rb dump DSL statically into a Catalog::Schema.
+  class SchemaParser
+    include Catalog
+
+    # Calls inside `create_table` that are not columns.
+    TABLE_IGNORED = %i[exclusion_constraint unique_constraint foreign_key].freeze
+    COLUMN_OPTIONS = %i[null default limit precision scale array comment].freeze
+
+    attr_reader :diagnostics
+
+    # inflector: anything answering #singularize and #pluralize (the project's Inflector later on).
+    def initialize(inflector: ActiveSupport::Inflector)
+      @inflector = inflector
+      @diagnostics = []
+    end
+
+    # paths are relative to root and are reported that way; tables share one namespace.
+    def parse_files(paths, root:)
+      merged = Schema.new
+      paths.each do |path|
+        full = File.expand_path(path, root)
+        raise Error, "schema file not found: #{path}" unless File.file?(full)
+
+        schema = parse(File.read(full), path: path)
+        merged.version ||= schema.version
+        merged.enums.merge!(schema.enums)
+        merged.foreign_keys.concat(schema.foreign_keys)
+        schema.tables.each do |name, table|
+          if (first = merged.tables[name])
+            error(%(table "#{name}" already defined at #{first.path}:#{first.line}), path, table.line)
+          else
+            merged.tables[name] = table
+          end
+        end
+      end
+      merged
+    end
+
+    def parse(source, path:)
+      @path = path
+      @schema = Schema.new
+      @pending_enums = []
+      result = Prism.parse(source)
+      if result.failure?
+        result.errors.each { |e| error("syntax error: #{e.message}", path, e.location.start_line) }
+        return @schema
+      end
+
+      statements(define_body(result.value)).each { |node| top_level(node) }
+      @pending_enums.each { |column, type| column.enum_values = @schema.enums[type] }
+      @schema
+    end
+
+    private
+
+    # The block of `ActiveRecord::Schema[8.1].define(...)`; falls back to the whole program.
+    def define_body(program)
+      define = statements(program).find { |n| n.is_a?(Prism::CallNode) && n.name == :define && n.block }
+      return program unless define
+
+      receiver = define.receiver
+      if receiver.is_a?(Prism::CallNode) && receiver.name == :[]
+        version = Literal.value(receiver.arguments&.arguments&.first)
+        @schema.version = version.to_s if Literal.known?(version)
+      end
+      define.block
+    end
+
+    def statements(node)
+      body = node.respond_to?(:statements) ? node.statements : node.body
+      body = body.body if body.is_a?(Prism::StatementsNode)
+      Array(body)
+    end
+
+    def top_level(node)
+      return unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+
+      args, options = Literal.arguments(node)
+      case node.name
+      when :create_table then create_table(node, args, options)
+      when :add_foreign_key then add_foreign_key(args, options)
+      when :add_index then add_index(args, options)
+      when :create_enum then create_enum(args)
+      end
+      # Anything else (enable_extension, execute, create_view, ...) is not drawn.
+    end
+
+    def create_table(node, args, options)
+      name = literal(args.first)
+      return warn("create_table without a literal table name", node) unless name.is_a?(String) || name.is_a?(Symbol)
+
+      table = Table.new(name: name.to_s, path: @path, line: node.location.start_line)
+      table.comment = literal(options[:comment])
+      add_primary_key(table, options)
+      statements(node.block).each { |statement| table_statement(table, statement) } if node.block&.body
+      @schema.tables[table.name] = table
+    end
+
+    def add_primary_key(table, options)
+      id = options.key?(:id) ? literal(options[:id]) : :bigint
+      primary_key = options.key?(:primary_key) ? literal(options[:primary_key]) : "id"
+      return if id == false
+
+      if primary_key.is_a?(Array) # composite: the columns are declared in the block
+        table.primary_key = primary_key.map(&:to_s)
+        return
+      end
+
+      # `id: :uuid`, or `id: { type: :string, limit: 2 }` with column options inline.
+      attrs = id.is_a?(Hash) ? id.slice(*COLUMN_OPTIONS).except(:null) : {}
+      type = id.is_a?(Hash) ? id.fetch(:type, :bigint) : id
+      attrs[:default] = literal(options[:default]) if options.key?(:default)
+      table.primary_key = [primary_key.to_s]
+      table.columns << Column.new(name: primary_key.to_s, type: type.to_s, null: false, **attrs)
+    end
+
+    def table_statement(table, node)
+      return unless node.is_a?(Prism::CallNode) && node.receiver
+
+      args, options = Literal.arguments(node)
+      case node.name
+      when :index then table.indexes << build_index(args.first, options)
+      when :references, :belongs_to then add_references(table, args, options)
+      when :timestamps then add_timestamps(table, options)
+      when :check_constraint then table.checks << literal(args.first).to_s
+      when :virtual then add_column(table, node, args.first, literal(options[:type]), options)
+      when :column then add_column(table, node, args.first, literal(args[1]), options)
+      when *TABLE_IGNORED then nil
+      else
+        return warn("unrecognized `#{node.name}` in create_table \"#{table.name}\"", node) if args.empty?
+
+        add_column(table, node, args.first, node.name, options)
+      end
+    end
+
+    def add_column(table, node, name_node, type, options)
+      name = literal(name_node)
+      return warn("column without a literal name in \"#{table.name}\"", node) unless name.is_a?(String) || name.is_a?(Symbol)
+
+      attrs = COLUMN_OPTIONS.filter_map { |key| [key, literal(options[key])] if options.key?(key) }.to_h
+      column = Column.new(name: name.to_s, type: type.to_s, **attrs)
+      column.null = true if column.null.nil?
+      column.generated = generated(options) if options.key?(:as)
+      if type.to_s == "enum" && options.key?(:enum_type)
+        column.type = literal(options[:enum_type]).to_s
+        @pending_enums << [column, column.type]
+      end
+      table.primary_key << column.name if literal(options[:primary_key]) == true
+      table.columns << column
+    end
+
+    def generated(options)
+      expression = literal(options[:as]).to_s
+      literal(options[:stored]) == true ? "#{expression} (stored)" : expression
+    end
+
+    def add_references(table, args, options)
+      null = options.key?(:null) ? literal(options[:null]) : true
+      type = options.key?(:type) ? literal(options[:type]).to_s : "bigint"
+      polymorphic = literal(options[:polymorphic])
+      args.each do |arg|
+        name = literal(arg).to_s
+        columns = ["#{name}_id"]
+        if polymorphic
+          table.columns << Column.new(name: "#{name}_type", type: "string", null: null)
+          columns.unshift("#{name}_type")
+        end
+        table.columns << Column.new(name: "#{name}_id", type: type, null: null)
+        table.indexes << Index.new(columns: columns) unless literal(options[:index]) == false
+        add_reference_fk(table, name, literal(options[:foreign_key])) unless polymorphic
+      end
+    end
+
+    def add_reference_fk(table, name, foreign_key)
+      return unless foreign_key
+
+      to_table = foreign_key.is_a?(Hash) && foreign_key[:to_table] ? foreign_key[:to_table].to_s : @inflector.pluralize(name)
+      @schema.foreign_keys << ForeignKey.new(from_table: table.name, from_column: "#{name}_id", to_table: to_table, to_column: "id")
+    end
+
+    def add_timestamps(table, options)
+      null = options.key?(:null) ? literal(options[:null]) : false
+      %w[created_at updated_at].each { |name| table.columns << Column.new(name: name, type: "datetime", null: null) }
+    end
+
+    def add_foreign_key(args, options)
+      from, to = args.map { |node| literal(node).to_s }
+      column = options.key?(:column) ? literal(options[:column]).to_s : "#{@inflector.singularize(to)}_id"
+      primary_key = options.key?(:primary_key) ? literal(options[:primary_key]).to_s : "id"
+      @schema.foreign_keys << ForeignKey.new(from_table: from, from_column: column, to_table: to, to_column: primary_key)
+    end
+
+    def add_index(args, options)
+      table = @schema.tables[literal(args.first).to_s]
+      table&.indexes&.<<(build_index(args[1], options))
+    end
+
+    # Arrays and symbols name columns; a string is a column only if it looks like an identifier.
+    def build_index(target, options)
+      value = literal(target)
+      columns, expression = case value
+                            when Array then [value.map(&:to_s), nil]
+                            when Symbol then [[value.to_s], nil]
+                            when /\A\w+\z/ then [[value], nil]
+                            else [[], value.to_s]
+                            end
+      Index.new(columns: columns, expression: expression, unique: literal(options[:unique]) == true,
+                where: options.key?(:where) ? literal(options[:where]) : nil,
+                name: options.key?(:name) ? literal(options[:name]) : nil)
+    end
+
+    def create_enum(args)
+      name, values = args.map { |node| literal(node) }
+      @schema.enums[name.to_s] = Array(values).map(&:to_s)
+    end
+
+    # Literal value, or the source text for anything computed (good enough for a diagram).
+    def literal(node)
+      return nil if node.nil?
+
+      value = Literal.value(node)
+      Literal.known?(value) ? value : node.slice
+    end
+
+    def warn(message, node)
+      @diagnostics << Diagnostic.new(severity: :warning, message: message, path: @path, line: node.location.start_line)
+      nil
+    end
+
+    def error(message, path, line)
+      @diagnostics << Diagnostic.new(severity: :error, message: message, path: path, line: line)
+    end
+  end
+end

data/lib/rails2qdbd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rails2qdbd
+  VERSION = "0.1.0"
+end

data/lib/rails2qdbd/writer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Rails2qdbd
+  # Renders Catalog tables as QuickDBD text, following qdbd's parser rules.
+  class Writer
+    HEADER = "# Generated by rails2qdbd"
+    IDENTIFIER = /\A[A-Za-z0-9_]+\z/
+    LIMITED_TYPES = %w[string text binary char varchar citext].freeze
+    OPERATORS = { many_to_one: ">-", one_to_one: "-" }.freeze
+
+    # Bare when qdbd accepts it as is, else double-quoted (qdbd has no escape for '"').
+    def self.quote_identifier(name)
+      name = name.to_s
+      name.match?(IDENTIFIER) ? name : %("#{name.tr('"', "'")}")
+    end
+
+    # The text after `default=`; nil when there is no default to show.
+    def self.format_default(value)
+      text = case value
+             when nil then return nil
+             when Array then "[#{value.map { |v| format_default(v).to_s.delete('"') }.join(',')}]"
+             when Hash then value.empty? ? "{}" : value.to_s
+             else value.to_s
+             end
+      text.empty? || text.match?(/[\s#"]/) ? %("#{text.tr('"', "'")}") : text
+    end
+
+    # One `# ` line per text line; '#' would end qdbd's comment, so it becomes a full-width ＃.
+    def self.comment_lines(text)
+      text.to_s.split(/\r?\n/).map { |line| line.split.join(" ").tr("#", "＃") }.reject(&:empty?).map { |line| "# #{line}" }
+    end
+
+    # relationships: { [table, column] => Relationship }; notes are extra documentation lines.
+    def render_table(table, relationships: {}, table_notes: [], column_notes: {})
+      lines = documentation([table.comment, *table_notes, *index_notes(table), *table.checks.map { |c| "check (#{c})" }])
+      lines << self.class.quote_identifier(table.name) << "-"
+      ordered_columns(table).each do |column|
+        lines.concat(documentation(column_docs(column) + column_notes.fetch(column.name, [])))
+        lines << column_line(table, column, relationships[[table.name, column.name]])
+      end
+      lines.join("\n")
+    end
+
+    def render_file(tables_text:, inputs:)
+      header = ["#{HEADER} #{VERSION} from #{inputs.join(', ')}.",
+                "# Re-run the conversion to refresh; manual edits will be overwritten."]
+      "#{[header.join("\n"), *tables_text].join("\n\n")}\n"
+    end
+
+    private
+
+    def documentation(texts) = texts.compact.flat_map { |text| self.class.comment_lines(text) }
+
+    def ordered_columns(table)
+      pk, rest = table.columns.partition { |column| table.primary_key.include?(column.name) }
+      pk + rest
+    end
+
+    def column_docs(column)
+      docs = [column.comment]
+      docs << "generated: #{column.generated}" if column.generated
+      docs << "enum: #{column.enum_values.join(', ')}" if column.enum_values&.any?
+      docs
+    end
+
+    def column_line(table, column, relationship)
+      pk = table.primary_key.include?(column.name)
+      parts = [self.class.quote_identifier(column.name)]
+      parts << "PK" if pk
+      parts << type(column)
+      parts << index_keyword(table, column) unless pk
+      parts << "NULL" if column.null && !pk
+      default = self.class.format_default(column.default)
+      parts << "default=#{default}" if default
+      if relationship
+        target = "#{self.class.quote_identifier(relationship.to_table)}.#{self.class.quote_identifier(relationship.to_column)}"
+        parts << "FK" << OPERATORS.fetch(relationship.cardinality) << target
+      end
+      parts.compact.join(" ")
+    end
+
+    # qdbd types are one token without '=', '#' or '"'.
+    def type(column)
+      base = column.type.to_s.strip.gsub(/\s+/, "_").tr("=", ":").delete('#"')
+      base = "unknown" if base.empty?
+      size = if column.precision && column.scale then "(#{column.precision},#{column.scale})"
+             elsif column.precision then "(#{column.precision})"
+             elsif column.limit && LIMITED_TYPES.include?(base) then "(#{column.limit})"
+             end
+      "#{base}#{size}#{'[]' if column.array}"
+    end
+
+    def index_keyword(table, column)
+      single = table.indexes.select { |index| index.single_column? && index.columns.first == column.name }
+      if single.any?(&:unique) then "UNIQUE"
+      elsif single.any? then "INDEX"
+      end
+    end
+
+    # Single-column indexes are column keywords, except on a PK column, which takes none: there it is
+    # redundant on a one-column key and noted on a composite one.
+    def keyword_index?(table, index)
+      index.single_column? && (table.primary_key.size == 1 || !table.primary_key.include?(index.columns.first))
+    end
+
+    # Indexes qdbd cannot express as a column keyword.
+    def index_notes(table)
+      table.indexes.reject { |index| keyword_index?(table, index) }.map do |index|
+        target = index.expression || index.columns.join(", ")
+        note = "#{'unique ' if index.unique}index (#{target})"
+        index.where ? "#{note} where #{index.where}" : note
+      end
+    end
+  end
+end

data/lib/rails2qdbd.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "rails2qdbd/version"
+require_relative "rails2qdbd/catalog"
+require_relative "rails2qdbd/literal"
+require_relative "rails2qdbd/inflector"
+require_relative "rails2qdbd/schema_parser"
+require_relative "rails2qdbd/model_scanner"
+require_relative "rails2qdbd/resolver"
+require_relative "rails2qdbd/writer"
+require_relative "rails2qdbd/config"
+require_relative "rails2qdbd/grouping"
+require_relative "rails2qdbd/converter"
+require_relative "rails2qdbd/output"
+require_relative "rails2qdbd/cli"
+
+# Converts a Rails project's db/schema.rb and app/models into qdbd schema files.
+# Pipeline (see Converter): SchemaParser + ModelScanner -> Resolver -> Writer -> Output.
+module Rails2qdbd
+  class Error < StandardError; end
+
+  # Converts the app at app_root. overrides: Config keys (output:, models:, exclude:, ...).
+  def self.convert(app_root, config_path: nil, **overrides)
+    Converter.new(Config.load(app_root, path: config_path, overrides: overrides)).run
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: rails2qdbd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- fastcatch
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: |
+  rails2qdbd reads db/schema.rb and app/models statically (no app boot, no database)
+  and writes QuickDBD-syntax schema files for qdbd, the ER-diagram toolkit.
+email:
+- fastcatch@gmail.com
+executables:
+- rails2qdbd
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/rails2qdbd
+- lib/rails2qdbd.rb
+- lib/rails2qdbd/catalog.rb
+- lib/rails2qdbd/cli.rb
+- lib/rails2qdbd/config.rb
+- lib/rails2qdbd/converter.rb
+- lib/rails2qdbd/grouping.rb
+- lib/rails2qdbd/inflector.rb
+- lib/rails2qdbd/literal.rb
+- lib/rails2qdbd/model_scanner.rb
+- lib/rails2qdbd/output.rb
+- lib/rails2qdbd/resolver.rb
+- lib/rails2qdbd/schema_parser.rb
+- lib/rails2qdbd/version.rb
+- lib/rails2qdbd/writer.rb
+homepage: https://github.com/fastcatch/rails2qdbd
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/fastcatch/rails2qdbd
+  changelog_uri: https://github.com/fastcatch/rails2qdbd/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/fastcatch/rails2qdbd/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Convert a Rails app's schema.rb and models into qdbd (QuickDBD) schema files.
+test_files: []