commento 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2558be497fdf71eca0c553371dc0fb09fdb348a04bc930289ad3696a571a4fa
-  data.tar.gz: c4e41098d7c6ffcff077d5c18545e7c0d03fcb33b3b1273bb4cfac0406cabf38
+  metadata.gz: a3088eb93d7f0b937169a65a8c95efc36eecb202be76a6cd7c98ec5adc5b945e
+  data.tar.gz: d1ce5f3eaad3ccc2fead78cecde406a20067f4304364948f09027d66ff26b789
 SHA512:
-  metadata.gz: f93c37134940512adbe7fd03600d7aeb0f4af032b9196c55bc5d011a310138c5f2fbefc4b8962abd9aa7cbc88ab41156cff8121eb80142df91e057146c60f779
-  data.tar.gz: c66a4d0f5e6a626982a3842d743b712fe7023fd3303369426a9f911d4b4c3fbb7ebd00712b02de70f192857b4aa5adb0573bf7a782f4aa054ce3946c90e33da6
+  metadata.gz: 47cd00bf0babcd8ab1c10db8d3edcd4be3330e99c5233b4241fe9552f5a65df96d6494349cc60530781f6d41cead7e05b74c76e7fccff191c9e02de4d78a2031
+  data.tar.gz: 3d7dbf40b8b2783a32dd86208b32e452d142b3d13b3e4ce5e9325472d5e04343d4f594b707aa8454eca2adf014b7e59fbb3f8dc9a72a42d557377f3c2d0d4783

data/README.md

@@ -32,16 +32,42 @@ end
 
 ### Models
 
-Update you application model
+Update your application model
+
 ```ruby
 class ApplicationRecord < ActiveRecord::Base
   include Commento::Helpers
 end
 ```
 
+## Generating reports
+
+You can generate different types of reports
+
+```ruby
+Commento::Reports::Html.new.create_report
+```
+
 ## Usage
 
-Commento provides helpers for models for setting and getting table's column comments.
+Commento provides helpers for models for setting and getting comments.
+
+### Set table's comment
+
+```ruby
+User.set_table_comment('Users table')
+```
+
+or reset comment by skiping value
+```ruby
+User.set_table_comment
+```
+
+### Read table's column comment
+
+```ruby
+User.get_table_comment
+```
 
 ### Set table's column comment
 

data/lib/commento/adapters/active_record.rb

@@ -15,6 +15,19 @@ module Commento
         @name = options.fetch(:name, :active_record)
       end
 
+      # Public: Sets comment for table.
+      def set_table_comment(table_name, value)
+        sql = "COMMENT ON TABLE #{table_name} IS "
+        sql += value ? "'#{value}'" : 'NULL'
+        execute(sql)
+      end
+
+      # Public: Returns comment for table.
+      def table_comment(table_name)
+        table_data = execute(tables_comments_sql).to_a.find { |data| data['table_name'] == table_name }
+        table_data.present? ? table_data['obj_description'] : nil
+      end
+
       # Public: Sets comment for table's column.
       def set_column_comment(table_name, column_name, value)
         sql = "COMMENT ON COLUMN #{table_name}.#{column_name} IS "
@@ -23,27 +36,72 @@ module Commento
       end
 
       # Public: Returns comment for table's column.
-      def get_column_comment(table_name, column_name)
-        sql = <<-SQL.squish
+      def column_comment(table_name, column_name)
+        sql = columns_comments_sql(table_name)
+        column_data = execute(sql).to_a.find { |data| data['column_name'].to_sym == column_name }
+        column_data.present? ? column_data['col_description'] : nil
+      end
+
+      # Public: Returns comments for tables and columns.
+      def comments_for_database
+        execute(tables_comments_sql).to_a.filter_map do |table_data|
+          next if configuration.skip_table_names.include?(table_data['table_name'])
+
+          parse_data(table_data)
+        end
+      end
+
+      private
+
+      def parse_data(table_data)
+        {
+          table_name: table_data['table_name'],
+          table_comment: table_data['obj_description'],
+          columns: execute(columns_comments_sql(table_data['table_name'])).to_a.filter_map do |column_data|
+            next if configuration.skip_column_names.include?(column_data['column_name'])
+
+            {
+              column_name: column_data['column_name'],
+              column_comment: column_data['col_description']
+            }
+          end
+        }
+      end
+
+      def tables_comments_sql
+        <<-SQL.squish
+          SELECT
+            tables.table_name,
+            pg_catalog.obj_description(pgc.oid, 'pg_class')
+          FROM information_schema.tables tables
+          INNER JOIN pg_catalog.pg_class pgc ON tables.table_name = pgc.relname
+          WHERE
+            tables.table_type='BASE TABLE' AND
+            tables.table_schema='public'
+        SQL
+      end
+
+      def columns_comments_sql(table_name)
+        <<-SQL.squish
           SELECT
             cols.column_name,
-            pg_catalog.col_description(c.oid, cols.ordinal_position::int)
-          FROM pg_catalog.pg_class c, information_schema.columns cols
+            pg_catalog.col_description(pgc.oid, cols.ordinal_position::int)
+          FROM pg_catalog.pg_class pgc, information_schema.columns cols
           WHERE
             cols.table_catalog = '#{Rails.configuration.database_configuration[Rails.env]["database"]}' AND
             cols.table_schema = 'public' AND
             cols.table_name = '#{table_name}' AND
-            cols.table_name = c.relname
+            cols.table_name = pgc.relname
         SQL
-        column_data = execute(sql).to_a.find { |column| column['column_name'].to_sym == column_name }
-        column_data.presence ? column_data['col_description'] : nil
       end
 
-      private
-
       def execute(sql)
         ::ActiveRecord::Base.connection.execute(sql)
       end
+
+      def configuration
+        Commento.configuration
+      end
     end
   end
 end

data/lib/commento/configuration.rb

@@ -2,10 +2,14 @@
 
 module Commento
   class Configuration
-    attr_accessor :adapter
+    attr_accessor :adapter, :include_folders, :exclude_folders, :skip_table_names, :skip_column_names
 
     def initialize
       @adapter = nil
+      @include_folders = %w[app lib]
+      @exclude_folders = ['app/assets']
+      @skip_table_names = %w[ar_internal_metadata schema_migrations]
+      @skip_column_names = %w[id uuid created_at updated_at]
     end
   end
 end

data/lib/commento/dsl.rb

@@ -11,14 +11,29 @@ module Commento
       @adapter = adapter
     end
 
+    # Public: Sets comment for table.
+    def set_table_comment(table_name, value)
+      adapter.set_table_comment(table_name, value)
+    end
+
+    # Public: Returns comment for table.
+    def table_comment(table_name)
+      adapter.table_comment(table_name)
+    end
+
     # Public: Sets comment for table's column.
     def set_column_comment(table_name, column_name, value)
       adapter.set_column_comment(table_name, column_name, value)
     end
 
     # Public: Returns comment for table's column.
-    def get_column_comment(table_name, column_name)
-      adapter.get_column_comment(table_name, column_name)
+    def column_comment(table_name, column_name)
+      adapter.column_comment(table_name, column_name)
+    end
+
+    # Public: Returns comments for tables and columns.
+    def comments_for_database
+      adapter.comments_for_database
     end
   end
 end

data/lib/commento/helpers.rb

@@ -9,12 +9,20 @@ module Commento
     end
 
     module ClassMethods
+      def set_table_comment(value=nil)
+        instance.set_table_comment(table_name, value)
+      end
+
+      def table_comment
+        instance.table_comment(table_name)
+      end
+
       def set_column_comment(column_name, value=nil)
         instance.set_column_comment(table_name, column_name, value)
       end
 
-      def get_column_comment(column_name)
-        instance.get_column_comment(table_name, column_name)
+      def column_comment(column_name)
+        instance.column_comment(table_name, column_name)
       end
 
       def instance

data/lib/commento/report.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Commento
+  class Report
+    COMMENTO_FOLDER_NAME = 'commento'
+
+    def initialize(data_collect_service: Commento::Services::DataCollect)
+      @data_collect_service = data_collect_service.new
+    end
+
+    def create_report
+      @commento_data = @data_collect_service.call
+      FileUtils.mkdir_p(COMMENTO_FOLDER_NAME)
+      File.write(
+        "#{COMMENTO_FOLDER_NAME}/#{file_name}",
+        main_template.gsub('%tables_placeholder%', tables_placeholder)
+      )
+    end
+
+    private
+
+    def tables_placeholder
+      database_comments.map do |table_data|
+        table_template
+          .gsub('%table_name%', table_data[:table_name])
+          .gsub('%table_comment%', table_data[:table_comment].presence || '')
+          .gsub('%columns_placeholder%', columns_placeholder(table_data[:table_name], table_data[:columns]))
+      end.join
+    end
+
+    def columns_placeholder(table_name, columns)
+      columns.map do |column_data|
+        full_column_name = "#{table_name}.#{column_data[:column_name]}"
+        column_template
+          .gsub('%column_name%', full_column_name)
+          .gsub('%column_comment%', column_data[:column_comment].presence || '')
+          .gsub('%data_placeholder%', data_placeholder(full_column_name))
+      end.join
+    end
+
+    def data_placeholder(full_column_name)
+      return '' if @commento_data[full_column_name].blank?
+
+      @commento_data[full_column_name].map do |filename|
+        data_template.gsub('%commento_data%', filename)
+      end.join
+    end
+
+    def database_comments
+      adapter.comments_for_database
+    end
+
+    def main_template
+      raise NotImplementedError
+    end
+
+    def table_template
+      raise NotImplementedError
+    end
+
+    def column_template
+      raise NotImplementedError
+    end
+
+    def data_template
+      raise NotImplementedError
+    end
+
+    def file_name
+      raise NotImplementedError
+    end
+
+    def adapter
+      Commento.adapter
+    end
+  end
+end

data/lib/commento/reports/html.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Commento
+  module Reports
+    class Html < Commento::Report
+      private
+
+      def main_template
+        [
+          '<!DOCTYPE html>',
+          '<html>',
+          '  <head>',
+          "    #{styles}",
+          '    <meta charset="utf-8" />',
+          '  </head>',
+          '  <body>',
+          '%tables_placeholder%',
+          '  </body>',
+          '</html>'
+        ].join("\n")
+      end
+
+      def table_template
+        [
+          "    <div class='table'>",
+          "      <div class='table-header'>",
+          '        <h3>%table_name%</h3>',
+          '        <p>%table_comment%</p>',
+          '      </div>',
+          "      <div class='table-body'>",
+          '%columns_placeholder%',
+          '      </div>',
+          "    </div>\n"
+        ].join("\n")
+      end
+
+      def column_template
+        [
+          "        <div class='column-body'>",
+          '          <p>%column_name%: %column_comment%</p>',
+          "          <div class='column-data'>",
+          '%data_placeholder%',
+          '          </div>',
+          "        </div>\n"
+        ].join("\n")
+      end
+
+      def data_template
+        '            <span>%commento_data%</span>'
+      end
+
+      def file_name
+        'index.html'
+      end
+
+      def styles
+        [
+          '<style>',
+          'h3 { margin: 0 0 .25rem }',
+          'p { margin: 0 0 .5rem }',
+          '.table { padding: 0 .5rem; margin-bottom: 1rem }',
+          '.table-header { border-bottom: 1px solid #ddd; margin-bottom: .5rem }',
+          '.table-header h3 { padding: .25rem; background: #bbb }',
+          '.table-header p { padding: .25rem; margin: 0 }',
+          '.table-body { padding: 0 .25rem }',
+          '.column-body { margin-bottom: .5rem; }',
+          '.column-body p { margin: 0 }',
+          '.column-data { display: flex; flex-direction: column; margin: .5rem 0 }',
+          '.column-data span { font-style: italic; padding-left: 1rem }',
+          '</style>'
+        ].join
+      end
+    end
+  end
+end

data/lib/commento/services/data_collect.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Commento
+  module Services
+    class DataCollect
+      COMMENTO_MATCH_REGEXP = /^[ \t]*# commento:.+$/.freeze
+
+      # @data contains data with next format
+      # {
+      #   'fantasy_sports.points' => [
+      #     'app/services/some_service.rb:11'
+      #   ]
+      # }
+      # key - table_name.column_name
+      # values - lines of files where these columns are changed in the code
+      def initialize
+        @data = {}
+      end
+
+      def call
+        configuration.include_folders.each { |include_folder| iterate_folder(include_folder) }
+        @data
+      end
+
+      private
+
+      def iterate_folder(include_folder)
+        Dir.glob("#{include_folder}/**/*.rb").each do |filename|
+          next if exclude_folders.include?(filename.split('/')[0..-2].join('/'))
+
+          File.open(filename) { |lines| iterate_filelines(lines, filename) }
+        end
+      end
+
+      def iterate_filelines(lines, filename)
+        lines.each.with_index(1) do |line, index|
+          next unless COMMENTO_MATCH_REGEXP.match?(line)
+
+          field = line.strip.split('# commento: ')[-1]
+          @data[field] ||= []
+          @data[field] << "#{filename}:#{index}"
+        end
+      end
+
+      def exclude_folders
+        @exclude_folders ||= configuration.exclude_folders
+      end
+
+      def configuration
+        Commento.configuration
+      end
+    end
+  end
+end

data/lib/commento/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Commento
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/commento.rb

@@ -6,17 +6,20 @@ require 'commento/version'
 require 'commento/configuration'
 require 'commento/dsl'
 require 'commento/helpers'
+require 'commento/report'
+require 'commento/reports/html'
+require 'commento/services/data_collect'
 
 module Commento
   extend self
   extend Forwardable
 
-  # Public: Given an adapter returns a handy DSL to all the commentp goodness.
+  # Public: Given an adapter returns a handy DSL to all the commento goodness.
   def new(adapter)
     DSL.new(adapter)
   end
 
-  # Public: Configure commentp.
+  # Public: Configure commento.
   #
   #   Commento.configure do |config|
   #     config.adapter = Commento::Adapters::ActiveRecord.new
@@ -31,7 +34,7 @@ module Commento
     @configuration ||= Configuration.new
   end
 
-  # Public: Default per thread commentp instance if configured.
+  # Public: Default per thread commento instance if configured.
   # Returns Commento::DSL instance.
   def instance
     Thread.current[:commento_instance] ||= new(configuration.adapter)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: commento
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Bogdanov Anton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-01 00:00:00.000000000 Z
+date: 2023-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -80,6 +80,9 @@ files:
 - lib/commento/configuration.rb
 - lib/commento/dsl.rb
 - lib/commento/helpers.rb
+- lib/commento/report.rb
+- lib/commento/reports/html.rb
+- lib/commento/services/data_collect.rb
 - lib/commento/version.rb
 homepage: https://github.com/kortirso/commento
 licenses: