commento 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a65354f12eb0a8c66c0bc901f87bb35f1ddf2d9d18f2b399c8e13758bc779e7
-  data.tar.gz: b0d88b4c72e2b6e6404b762b2113a6c61779c2d7a3cc4a7732c09452599d895c
+  metadata.gz: ec9a9477c941a8b246f869b1e157c99c9cf49476ff1708abc1a4c1b0f57c847e
+  data.tar.gz: ddfc8c0308bbfa0933e7d580e57fe7a2f157ad73a02d066681d21993901e6fa4
 SHA512:
-  metadata.gz: def8375883745c14c5fa4b032bec57a3e4030299fc79c4a0a214e46f177d4e962c93d99a2f899d51e8db450cb4e14ca26d5805430f678b5489b85f14893a72f1
-  data.tar.gz: b7fe5588c90a2c072efb614a43201220c443410ed149b3965ea5baf65e93276506e85fe61c4d859e2a15556e4d8232b379e6425f9b288013f48918594689c168
+  metadata.gz: b39355f42447cbcf9d1b55e5adc35e8793f61a3514b4bcfdfbb3352fa2f66a6b41a38bcc6d9f1d8517cf4fa2f462ef5b7bc33bc1699bdff1715ac6e0e3324c17
+  data.tar.gz: 7a70ad3732e253860cb17f1dcc57152651e6229b9ad815d097093755f844553c38ff48e0c48fe5febeacd2688034bfdd273023598e977891242f8bd5c1cf6aed

data/README.md

@@ -27,31 +27,55 @@ require 'commento/adapters/active_record'
 
 Commento.configure do |config|
   config.adapter = Commento::Adapters::ActiveRecord.new
+  config.include_folders = %w[app lib] # folder for searching commento comments
+  config.exclude_folders = ['app/assets'] # folder for excluding searching commento comments
+  config.skip_table_names = %w[ar_internal_metadata schema_migrations] # ignoring tables
+  config.skip_column_names = %w[id uuid created_at updated_at] # ignoring columns
 end
 ```
 
-### Models
+## Rake tasks
 
-Update your application model
+### Generating reports
 
-```ruby
-class ApplicationRecord < ActiveRecord::Base
-  include Commento::Helpers
-end
+You can generate different types of reports (right now only html) with rake task
+
+```bash
+rails "commento:generate_report[html]"
 ```
 
-## Generating reports
+### Health check
 
-You can generate different types of reports
+You can check amount of missing comments for tables and columns with console report
 
-```ruby
-Commento::Reports::Html.new.create_report
+```bash
+rails commento:health
+```
+
+<img width="727" alt="Снимок экрана 2024-09-13 в 10 11 12" src="https://github.com/user-attachments/assets/f0b8fbf8-6a6a-4c7b-b6b6-2a0de6d19f45">
+
+### Generating migration for adding comments to tables and columns
+
+You can generate migration with adding comments for table and columns
+
+```bash
+rails g commento:active_record
 ```
 
 ## Usage
 
 Commento provides helpers for models for setting and getting comments.
 
+### Models configuration
+
+Update your application model
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Commento::Helpers
+end
+```
+
 ### Set table's comment
 
 ```ruby
@@ -63,13 +87,13 @@ or reset comment by skiping value
 User.set_table_comment
 ```
 
-### Read table's column comment
+### Read table's comment
 
 ```ruby
-User.get_table_comment
+User.fetch_table_comment
 ```
 
-### Set table's column comment
+### Set column's comment
 
 ```ruby
 User.set_column_comment(:email, 'Required field for user authentication')
@@ -80,10 +104,10 @@ or reset comment by skiping value
 User.set_column_comment(:email)
 ```
 
-### Read table's column comment
+### Read column's comment
 
 ```ruby
-User.get_column_comment(:email)
+User.fetch_column_comment(:email)
 ```
 
 ## License

data/lib/commento/adapters/active_record.rb

@@ -23,7 +23,7 @@ module Commento
       end
 
       # Public: Returns comment for table.
-      def table_comment(table_name)
+      def fetch_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
@@ -36,14 +36,14 @@ module Commento
       end
 
       # Public: Returns comment for table's column.
-      def column_comment(table_name, column_name)
+      def fetch_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
+      def fetch_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'])
 

data/lib/commento/dsl.rb

@@ -17,8 +17,8 @@ module Commento
     end
 
     # Public: Returns comment for table.
-    def table_comment(table_name)
-      adapter.table_comment(table_name)
+    def fetch_table_comment(table_name)
+      adapter.fetch_table_comment(table_name)
     end
 
     # Public: Sets comment for table's column.
@@ -27,13 +27,13 @@ module Commento
     end
 
     # Public: Returns comment for table's column.
-    def column_comment(table_name, column_name)
-      adapter.column_comment(table_name, column_name)
+    def fetch_column_comment(table_name, column_name)
+      adapter.fetch_column_comment(table_name, column_name)
     end
 
     # Public: Returns comments for tables and columns.
-    def comments_for_database
-      adapter.comments_for_database
+    def fetch_comments_for_database
+      adapter.fetch_comments_for_database
     end
   end
 end

data/lib/commento/helpers.rb

@@ -13,16 +13,16 @@ module Commento
         instance.set_table_comment(table_name, value)
       end
 
-      def table_comment
-        instance.table_comment(table_name)
+      def fetch_table_comment
+        instance.fetch_table_comment(table_name)
       end
 
       def set_column_comment(column_name, value=nil)
         instance.set_column_comment(table_name, column_name, value)
       end
 
-      def column_comment(column_name)
-        instance.column_comment(table_name, column_name)
+      def fetch_column_comment(column_name)
+        instance.fetch_column_comment(table_name, column_name)
       end
 
       def instance

data/lib/commento/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'commento'
+require 'rails'
+
+module Commento
+  class Railtie < Rails::Railtie
+    railtie_name :commento
+
+    rake_tasks do
+      path = File.expand_path(__dir__)
+      Dir.glob("#{path}/../tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/commento/report.rb

@@ -32,7 +32,7 @@ module Commento
       columns.map do |column_data|
         full_column_name = "#{table_name}.#{column_data[:column_name]}"
         column_template
-          .gsub('%column_name%', full_column_name)
+          .gsub('%column_name%', column_data[:column_name])
           .gsub('%column_comment%', column_data[:column_comment].presence || '')
           .gsub('%data_placeholder%', data_placeholder(full_column_name))
       end.join
@@ -47,7 +47,7 @@ module Commento
     end
 
     def database_comments
-      adapter.comments_for_database
+      adapter.fetch_comments_for_database
     end
 
     def main_template

data/lib/commento/scrapers/ruby.rb

@@ -9,6 +9,7 @@ module Commento
       # {
       #   'fantasy_sports.points' => [
       #     'app/services/some_service.rb:11'
+      #     'app/services/some_another_service.rb:12'
       #   ]
       # }
       # key - table_name.column_name
@@ -33,15 +34,15 @@ module Commento
       end
 
       # commento line looks like
-      # commento: fantasy_sports.points, fantasy_sports.statistics
+      # commento:fantasy_sports:points,statistics
       def iterate_filelines(lines, filename)
         lines.each.with_index(1) do |line, index|
           next unless COMMENTO_MATCH_REGEXP.match?(line)
 
-          fields = line.strip.split('# commento: ')[-1].split(',').map(&:strip)
-          fields.each do |field|
-            @data[field] ||= []
-            @data[field] << "#{filename}:#{index}"
+          table_name, columns = line.strip.split('# commento:')[-1].split(':').map(&:strip)
+          columns.split(',').each do |column|
+            @data["#{table_name}.#{column}"] ||= []
+            @data["#{table_name}.#{column}"] << "#{filename}:#{index}"
           end
         end
       end

data/lib/commento/version.rb

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

data/lib/commento.rb

@@ -9,6 +9,7 @@ require 'commento/helpers'
 require 'commento/report'
 require 'commento/reports/html'
 require 'commento/scrapers/ruby'
+require 'commento/railtie' if defined?(Rails)
 
 module Commento
   extend self

data/lib/generators/commento/active_record_generator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_record'
+
+module Commento
+  module Generators
+    class ActiveRecordGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      desc 'Generates migration for adding comments'
+
+      source_paths << File.join(File.dirname(__FILE__), 'templates')
+
+      attr_reader :tables_change_data, :columns_change_data
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def self.migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if requires_migration_number?
+      end
+
+      def self.requires_migration_number?
+        Rails::VERSION::MAJOR.to_i >= 5
+      end
+
+      def create_migration_file
+        generate_migration_data
+
+        migration_template 'migration.erb', 'db/migrate/commento_add_comments_to_tables_and_columns.rb'
+      end
+
+      def migration_version
+        self.class.migration_version
+      end
+
+      def generate_migration_data
+        @tables_without_comment = []
+        @table_report = {}
+
+        check_comments_for_database(Commento.adapter.fetch_comments_for_database)
+
+        @tables_change_data =
+          @tables_without_comment
+          .map { |table_name| "change_table_comment(:#{table_name}, from: nil, to: '')" }
+          .join("\n    ")
+
+        @columns_change_data =
+          @table_report.map do |table_name, column_names|
+            column_names.map do |column_name|
+              "change_column_comment(:#{table_name}, :#{column_name}, from: nil, to: '')"
+            end
+          end.flatten.join("\n    ")
+      end
+
+      private
+
+      def check_comments_for_database(comments_for_database)
+        comments_for_database.each do |table_data|
+          @tables_without_comment << table_data[:table_name] if table_data[:table_comment].nil?
+          table_data[:columns].each do |column_data|
+            next if column_data[:column_comment].present?
+
+            @table_report[table_data[:table_name]] ||= []
+            @table_report[table_data[:table_name]] << column_data[:column_name]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/commento/templates/migration.erb

@@ -0,0 +1,7 @@
+class CommentoAddCommentsToTablesAndColumns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    <%= tables_change_data %>
+
+    <%= columns_change_data %>
+  end
+end

data/lib/tasks/commento.rake

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'commento'
+require 'rainbow'
+require 'terminal-table'
+
+AVAILABLE_REPORT_FORMATS = %w[html].freeze
+
+# rubocop: disable Metrics/BlockLength
+namespace :commento do
+  desc 'Generates HTML report'
+  task :generate_report, [:format] => :environment do |_, args|
+    if args[:format].blank?
+      puts Rainbow('Please specify format').red.bright
+      next
+    end
+
+    unless args[:format].in?(AVAILABLE_REPORT_FORMATS)
+      puts Rainbow("Format is not supported, available options: #{AVAILABLE_REPORT_FORMATS.join(", ")}").red.bright
+      next
+    end
+
+    puts Rainbow('Generating report is started').green
+
+    case args[:format]
+    when 'html' then Commento::Reports::Html.new.create_report
+    end
+
+    puts Rainbow('✓ Good job! Report is generated').green.bright
+  end
+
+  desc 'Generates console report about missing table and column comments'
+  task health: :environment do
+    puts Rainbow("Starting commento health check\n").green
+
+    comments_for_database = Commento.adapter.fetch_comments_for_database
+
+    tables_with_comment_amount = 0
+    tables_without_comment = []
+    tables_without_comment_amount = 0
+    columns_with_comment_amount = 0
+    columns_without_comment_amount = 0
+
+    table_report_with_missing_comments = {}
+
+    comments_for_database.each do |table_data|
+      if table_data[:table_comment].nil?
+        tables_without_comment << table_data[:table_name]
+        tables_without_comment_amount += 1
+        table_report_with_missing_comments[table_data[:table_name]] = []
+      else
+        tables_with_comment_amount += 1
+      end
+      table_data[:columns].each do |column_data|
+        if column_data[:column_comment].nil?
+          columns_without_comment_amount += 1
+          table_report_with_missing_comments[table_data[:table_name]] ||= []
+          table_report_with_missing_comments[table_data[:table_name]] << column_data[:column_name]
+        else
+          columns_with_comment_amount += 1
+        end
+      end
+    end
+
+    total_tables_amount = tables_with_comment_amount + tables_without_comment_amount
+    tables_with_comment_ratio = total_tables_amount.zero? ? 0 : (tables_with_comment_amount * 100 / total_tables_amount)
+
+    if tables_with_comment_ratio == 100
+      puts Rainbow('✓ Amazing! All tables have comment').green.bright
+    elsif tables_with_comment_ratio > 50
+      puts Rainbow("✓ Good job! #{tables_with_comment_ratio}% of tables have comment").green.bright
+    elsif tables_with_comment_ratio.positive?
+      puts Rainbow("✓ Need to work! Only #{tables_with_comment_ratio}% of tables have comment").yellow.bright
+    else
+      puts Rainbow('✓ Something is missing! No single table have comment').red.bright
+    end
+
+    total_columns_amount = columns_with_comment_amount + columns_without_comment_amount
+    columns_ratio = total_columns_amount.zero? ? 0 : (columns_with_comment_amount * 100 / total_columns_amount)
+
+    if columns_ratio == 100
+      puts Rainbow('✓ Amazing! All columns have comment').green.bright
+    elsif columns_ratio > 50
+      puts Rainbow("✓ Good job! #{columns_ratio}% of columns have comment").green.bright
+    elsif columns_ratio.positive?
+      puts Rainbow("✓ Need to work! Only #{columns_ratio}% of columns have comment").yellow.bright
+    else
+      puts Rainbow('✓ Something is missing! No single column have comment').red.bright
+    end
+
+    if tables_without_comment_amount.positive? || columns_without_comment_amount.positive?
+      rows = []
+      table_report_with_missing_comments.each do |table_name, column_names|
+        rows << [
+          table_name.in?(tables_without_comment) ? Rainbow(table_name).cyan.bright : Rainbow(table_name).silver.bright,
+          column_names.map { |column_name| Rainbow(column_name).cyan.bright }.join("\n")
+        ]
+        rows << :separator
+      end
+      puts ''
+      puts Terminal::Table.new(
+        title: Rainbow('Missing comments report').silver.bright,
+        headings: [Rainbow('Table name').silver.bright, Rainbow('Column name').silver.bright],
+        rows: rows,
+        style: { width: 80, border_bottom: false }
+      )
+    end
+  end
+end
+# rubocop: enable Metrics/BlockLength

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: commento
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Bogdanov Anton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-01 00:00:00.000000000 Z
+date: 2024-09-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.2
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -80,10 +108,14 @@ files:
 - lib/commento/configuration.rb
 - lib/commento/dsl.rb
 - lib/commento/helpers.rb
+- lib/commento/railtie.rb
 - lib/commento/report.rb
 - lib/commento/reports/html.rb
 - lib/commento/scrapers/ruby.rb
 - lib/commento/version.rb
+- lib/generators/commento/active_record_generator.rb
+- lib/generators/commento/templates/migration.erb
+- lib/tasks/commento.rake
 homepage: https://github.com/kortirso/commento
 licenses:
 - MIT