glib-web 4.39.1 → 4.39.2

data/lib/glib/doc_generator.rb

@@ -0,0 +1,386 @@
+require 'parser/current'
+require 'yaml'
+require 'fileutils'
+require 'time'
+
+module Glib
+  class DocGenerator
+    def initialize
+      @parser = Parser::CurrentRuby
+    end
+
+    # Generate YAML documentation for a single Ruby file
+    def generate_for_file(file_path, output_path)
+      unless File.exist?(file_path)
+        puts "Warning: File not found: #{file_path}"
+        return
+      end
+
+      source = File.read(file_path)
+      ast = @parser.parse(source)
+
+      components = extract_components(ast, source)
+
+      # Generate YAML
+      yaml_data = {
+        'meta' => {
+          'source_file' => file_path,
+          'generated_at' => Time.now.iso8601,
+          'generator_version' => '1.0.0'
+        },
+        'components' => components
+      }
+
+      # Ensure output directory exists
+      FileUtils.mkdir_p(File.dirname(output_path))
+
+      # Write YAML file
+      File.write(output_path, yaml_data.to_yaml)
+    end
+
+    private
+
+    # Extract component information from AST
+    def extract_components(node, source)
+      components = {}
+
+      traverse_ast(node, source) do |class_node, class_name, parent_class, comment|
+        next unless class_node.type == :class
+
+        # Parse YARD comment
+        yard_doc = parse_yard_comment(comment)
+
+        # Extract properties
+        properties = extract_properties(class_node, source)
+
+        # Build component hash
+        component_key = underscore(class_name)
+        components[component_key] = {
+          'class_name' => class_name,
+          'extends' => parent_class,
+          'description' => yard_doc[:description],
+          'properties' => properties,
+          'examples' => yard_doc[:examples],
+          'references' => yard_doc[:references],
+          'notes' => yard_doc[:notes],
+          'deprecated' => yard_doc[:deprecated]
+        }.compact
+      end
+
+      components
+    end
+
+    # Traverse AST and yield class nodes with their comments
+    def traverse_ast(node, source, &block)
+      return unless node.is_a?(Parser::AST::Node)
+
+      if node.type == :class
+        class_name = extract_class_name(node)
+        parent_class = extract_parent_class(node)
+        comment = extract_comment(node, source)
+
+        yield node, class_name, parent_class, comment
+      end
+
+      # Recursively traverse child nodes
+      node.children.each do |child|
+        traverse_ast(child, source, &block)
+      end
+    end
+
+    # Extract class name from class node
+    def extract_class_name(class_node)
+      const_node = class_node.children[0]
+      if const_node.type == :const
+        const_node.children[1].to_s
+      else
+        'Unknown'
+      end
+    end
+
+    # Extract parent class name
+    def extract_parent_class(class_node)
+      parent_node = class_node.children[1]
+      return nil unless parent_node
+
+      if parent_node.type == :const
+        parent_node.children[1].to_s
+      else
+        nil
+      end
+    end
+
+    # Extract comment before a node
+    def extract_comment(node, source)
+      return '' unless node.location
+
+      # Get all lines before the node
+      lines = source.lines
+      node_line = node.location.line - 1
+
+      # Walk backwards to collect comment lines
+      comment_lines = []
+      (node_line - 1).downto(0) do |i|
+        line = lines[i].strip
+        break unless line.start_with?('#') || line.empty?
+
+        if line.start_with?('#')
+          # Remove leading # and whitespace
+          comment_lines.unshift(line.sub(/^#\s?/, ''))
+        end
+      end
+
+      comment_lines.join("\n")
+    end
+
+    # Parse YARD comment into structured data
+    def parse_yard_comment(comment)
+      return {} if comment.empty?
+
+      result = {
+        description: '',
+        examples: [],
+        references: [],
+        notes: [],
+        deprecated: nil
+      }
+
+      current_section = :description
+      current_example = nil
+      description_lines = []
+
+      comment.lines.each do |line|
+        line = line.chomp
+
+        # Check for YARD tags
+        if line =~ /^@example\s*(.*)/
+          # Save current example if exists
+          result[:examples] << current_example if current_example
+
+          current_example = {
+            'label' => $1.strip,
+            'code' => ''
+          }
+          current_section = :example
+        elsif line =~ /^@see\s+(.*)/
+          reference = $1.strip
+          # Parse URL and description
+          if reference =~ /^(https?:\/\/\S+)\s+(.*)/
+            result[:references] << { 'url' => $1, 'description' => $2 }
+          elsif reference =~ /^(https?:\/\/\S+)/
+            result[:references] << { 'url' => $1 }
+          else
+            result[:references] << { 'text' => reference }
+          end
+          current_section = :description
+        elsif line =~ /^@note\s+(.*)/
+          result[:notes] << $1.strip
+          current_section = :description
+        elsif line =~ /^@deprecated\s*(.*)/
+          result[:deprecated] = $1.strip
+          result[:deprecated] = true if result[:deprecated].empty?
+          current_section = :description
+        else
+          # Regular content
+          if current_section == :example && current_example
+            # Remove leading spaces from example code (preserve relative indentation)
+            current_example['code'] += line + "\n"
+          elsif current_section == :description
+            description_lines << line unless line.strip.empty? && description_lines.empty?
+          end
+        end
+      end
+
+      # Save last example
+      result[:examples] << current_example if current_example
+
+      # Clean up example code (remove extra leading whitespace)
+      result[:examples].each do |example|
+        example['code'] = unindent(example['code'])
+      end
+
+      # Join description lines
+      result[:description] = description_lines.join("\n").strip
+
+      # Remove empty arrays/nils
+      result.delete(:examples) if result[:examples].empty?
+      result.delete(:references) if result[:references].empty?
+      result.delete(:notes) if result[:notes].empty?
+      result.delete(:deprecated) if result[:deprecated].nil?
+
+      result
+    end
+
+    # Extract properties from class body
+    def extract_properties(class_node, source)
+      properties = {}
+
+      class_body = class_node.children[2]
+      return properties unless class_body
+
+      traverse_class_body(class_body, source) do |method_name, args, comment|
+        # These are the DSL property definition methods
+        if [:string, :int, :bool, :float, :action, :views, :array, :hash,
+            :icon, :color, :length, :date, :date_time, :text, :any,
+            :panels_builder, :menu, :singleton_array].include?(method_name)
+
+          property_name = args.first
+          next unless property_name
+
+          # Parse property comment
+          prop_doc = parse_property_comment(comment)
+
+          # Extract options if present (for hash, singleton_array, etc.)
+          options = extract_property_options(args)
+
+          properties[property_name] = {
+            'type' => method_name.to_s,
+            'description' => prop_doc[:description],
+            'required' => options[:required] || false,
+            'options' => options[:options],
+            'examples' => prop_doc[:examples],
+            'notes' => prop_doc[:notes],
+            'deprecated' => prop_doc[:deprecated]
+          }.compact
+
+          # Remove empty arrays
+          properties[property_name].delete('examples') if properties[property_name]['examples']&.empty?
+          properties[property_name].delete('notes') if properties[property_name]['notes']&.empty?
+        end
+      end
+
+      properties
+    end
+
+    # Traverse class body to find method calls (property definitions)
+    def traverse_class_body(node, source, &block)
+      return unless node.is_a?(Parser::AST::Node)
+
+      if node.type == :send
+        receiver = node.children[0]
+        method_name = node.children[1]
+        args = node.children[2..-1].map { |arg| extract_symbol_or_string(arg) }
+        comment = extract_comment(node, source)
+
+        # Only process calls without a receiver (DSL methods)
+        yield method_name, args, comment if receiver.nil?
+      end
+
+      node.children.each do |child|
+        traverse_class_body(child, source, &block)
+      end
+    end
+
+    # Extract symbol or string value from AST node
+    def extract_symbol_or_string(node)
+      return nil unless node.is_a?(Parser::AST::Node)
+
+      case node.type
+      when :sym
+        node.children[0].to_s
+      when :str
+        node.children[0]
+      when :hash
+        extract_hash(node)
+      else
+        nil
+      end
+    end
+
+    # Extract hash from AST node
+    def extract_hash(node)
+      return nil unless node.type == :hash
+
+      result = {}
+      node.children.each do |pair|
+        next unless pair.type == :pair
+        key = extract_symbol_or_string(pair.children[0])
+        value = extract_symbol_or_string(pair.children[1]) || extract_array(pair.children[1])
+        result[key] = value if key
+      end
+      result
+    end
+
+    # Extract array from AST node
+    def extract_array(node)
+      return nil unless node.is_a?(Parser::AST::Node) && node.type == :array
+
+      node.children.map { |child| extract_symbol_or_string(child) }.compact
+    end
+
+    # Extract property options from arguments
+    def extract_property_options(args)
+      options = { required: false }
+
+      args.each do |arg|
+        if arg.is_a?(Hash)
+          if arg['required']
+            options[:required] = true
+          end
+          if arg['optional']
+            options[:options] = { 'optional' => arg['optional'] }
+          end
+        end
+      end
+
+      options
+    end
+
+    # Parse property comment
+    def parse_property_comment(comment)
+      return {} if comment.empty?
+
+      result = {
+        description: '',
+        examples: [],
+        notes: [],
+        deprecated: nil
+      }
+
+      description_lines = []
+
+      comment.lines.each do |line|
+        line = line.chomp
+
+        if line =~ /^@example\s+(.*)/
+          result[:examples] << $1.strip
+        elsif line =~ /^@note\s+(.*)/
+          result[:notes] << $1.strip
+        elsif line =~ /^@deprecated\s*(.*)/
+          result[:deprecated] = $1.strip
+          result[:deprecated] = true if result[:deprecated].empty?
+        else
+          description_lines << line unless line.strip.empty? && description_lines.empty?
+        end
+      end
+
+      result[:description] = description_lines.join("\n").strip
+
+      result
+    end
+
+    # Convert CamelCase to snake_case
+    def underscore(string)
+      string.gsub(/::/, '_')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+    end
+
+    # Remove common leading whitespace from multi-line strings
+    def unindent(text)
+      return text if text.empty?
+
+      lines = text.lines
+      # Find minimum indentation (ignoring empty lines)
+      min_indent = lines
+        .reject { |line| line.strip.empty? }
+        .map { |line| line.match(/^(\s*)/)[1].length }
+        .min || 0
+
+      # Remove that amount of indentation from each line
+      lines.map { |line| line.strip.empty? ? line : line[min_indent..-1] }.join
+    end
+  end
+end

data/lib/glib/rubocop/cops/test_name_parentheses.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Glib
+      # Prevents test method names from containing parentheses which can cause issues with test runners
+      #
+      # @example
+      #   # bad
+      #   test 'user creation (with email)' do
+      #   end
+      #
+      #   # good
+      #   test 'user creation with email' do
+      #   end
+      class TestNameParentheses < Base
+        MSG = "Test name should not contain parentheses because for some reason, this will produce: 'Syntax error: \"(\" unexpected'."
+
+        def_node_matcher :test_method?, <<~PATTERN
+          (send nil? :test (str $_) ...)
+        PATTERN
+
+        def on_send(node)
+          test_method?(node) do |test_name|
+            if test_name.include?('(') || test_name.include?(')')
+              add_offense(node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/glib/rubocop.rb

@@ -3,3 +3,4 @@ require_relative 'rubocop/cops/multiline_method_call_style'
 require_relative 'rubocop/cops/json_ui/base_nested_parameter'
 require_relative 'rubocop/cops/json_ui/nested_block_parameter'
 require_relative 'rubocop/cops/json_ui/nested_action_parameter'
+require_relative 'rubocop/cops/test_name_parentheses'

data/lib/tasks/db.rake

@@ -63,7 +63,7 @@ namespace :db do
 
           entries.each do |a|
             attrs = Hash[a.attributes.sort]
-            attrs.delete_if { |k, v| v.nil? }
+            # attrs.delete_if { |k, v| v.nil? }
 
             id = if attrs.include?('id')
               [a.id]

data/lib/tasks/docs.rake

@@ -0,0 +1,59 @@
+namespace :glib do
+  namespace :docs do
+    desc 'Generate component documentation in YAML format'
+    task :generate do
+      require_relative '../glib/doc_generator'
+
+      generator = Glib::DocGenerator.new
+
+      # Generate documentation for different component categories
+      categories = [
+        {
+          name: 'panels',
+          file: 'app/helpers/glib/json_ui/view_builder/panels.rb',
+          output: 'doc/components/panels.yml'
+        },
+        {
+          name: 'fields',
+          file: 'app/helpers/glib/json_ui/view_builder/fields.rb',
+          output: 'doc/components/fields.yml'
+        },
+        {
+          name: 'views',
+          file: 'app/helpers/glib/json_ui/view_builder.rb',
+          output: 'doc/components/views.yml'
+        },
+        {
+          name: 'actions',
+          file: 'app/helpers/glib/json_ui/action_builder.rb',
+          output: 'doc/components/actions.yml'
+        }
+      ]
+
+      categories.each do |category|
+        puts "Generating documentation for #{category[:name]}..."
+        generator.generate_for_file(category[:file], category[:output])
+        puts "  -> #{category[:output]}"
+      end
+
+      # Also scan action subdirectories
+      Dir.glob('app/helpers/glib/json_ui/action_builder/*.rb').each do |file|
+        basename = File.basename(file, '.rb')
+        output = "doc/components/actions_#{basename}.yml"
+        puts "Generating documentation for actions/#{basename}..."
+        generator.generate_for_file(file, output)
+        puts "  -> #{output}"
+      end
+
+      puts "\nDocumentation generation complete!"
+    end
+
+    desc 'Validate YARD documentation'
+    task :validate do
+      puts "Validating YARD documentation..."
+      system('yard stats --list-undoc')
+      system('yard doc --fail-on-warning --no-output')
+      puts "\nValidation complete!"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glib-web
 version: !ruby/object:Gem::Version
-  version: 4.39.1
+  version: 4.39.2
 platform: ruby
 authors:
 - ''
@@ -156,6 +156,7 @@ files:
 - app/controllers/concerns/glib/json/traversal.rb
 - app/controllers/concerns/glib/json/ui.rb
 - app/controllers/concerns/glib/json/validation.rb
+- app/controllers/glib/api_docs_controller.rb
 - app/controllers/glib/blob_url_generators_controller.rb
 - app/controllers/glib/errors_controller.rb
 - app/controllers/glib/glib_direct_uploads_controller.rb
@@ -220,6 +221,9 @@ files:
 - app/validators/mutually_exclusive_with_validator.rb
 - app/validators/presence_only_if_validator.rb
 - app/validators/url_validator.rb
+- app/views/glib/api_docs/component.json.jbuilder
+- app/views/glib/api_docs/index.json.jbuilder
+- app/views/glib/api_docs/show.json.jbuilder
 - app/views/json_ui/garage/_nav_menu.json.jbuilder
 - app/views/json_ui/garage/actions/_commands.json.jbuilder
 - app/views/json_ui/garage/actions/_components.json.jbuilder
@@ -423,6 +427,7 @@ files:
 - lib/glib-web.rb
 - lib/glib/all_helpers.rb
 - lib/glib/crypt/utils.rb
+- lib/glib/doc_generator.rb
 - lib/glib/dynamic_text.rb
 - lib/glib/dynamic_text/config.rb
 - lib/glib/engine.rb
@@ -448,6 +453,7 @@ files:
 - lib/glib/rubocop/cops/json_ui/nested_block_parameter.rb
 - lib/glib/rubocop/cops/localize.rb
 - lib/glib/rubocop/cops/multiline_method_call_style.rb
+- lib/glib/rubocop/cops/test_name_parentheses.rb
 - lib/glib/snapshot.rb
 - lib/glib/test/parallel_coverage.rb
 - lib/glib/test_helpers.rb
@@ -456,6 +462,7 @@ files:
 - lib/glib/value.rb
 - lib/glib/version.rb
 - lib/tasks/db.rake
+- lib/tasks/docs.rake
 homepage:
 licenses: []
 metadata: {}