ukiryu 0.1.1 → 0.1.3

data/lib/ukiryu/definition/documentation_generator.rb

@@ -0,0 +1,429 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Definition
+    # Generate documentation from tool definitions
+    #
+    # This class generates human-readable documentation from tool definitions
+    # in various formats (Markdown, AsciiDoc).
+    class DocumentationGenerator
+      # Supported formats
+      FORMATS = %i[markdown asciidoc md].freeze
+
+      class << self
+        # Generate documentation for a definition
+        #
+        # @param definition [Hash] the definition
+        # @param format [Symbol] output format (:markdown, :asciidoc)
+        # @return [String] generated documentation
+        def generate(definition, format: :markdown)
+          format = normalize_format(format)
+
+          case format
+          when :markdown
+            generate_markdown(definition)
+          when :asciidoc
+            generate_asciidoc(definition)
+          else
+            raise ArgumentError, "Unsupported format: #{format}"
+          end
+        end
+
+        # Generate documentation to a file
+        #
+        # @param definition [Hash] the definition
+        # @param file_path [String] output file path
+        # @param format [Symbol] output format
+        def generate_to_file(definition, file_path, format: :markdown)
+          content = generate(definition, format: format)
+          File.write(file_path, content)
+        end
+
+        # Generate documentation for a specific command
+        #
+        # @param command_name [String] the command name
+        # @param command_def [Hash] the command definition
+        # @param format [Symbol] output format
+        # @return [String] generated command documentation
+        def generate_command_docs(command_name, command_def, format: :markdown)
+          format = normalize_format(format)
+
+          case format
+          when :markdown
+            generate_command_markdown(command_name, command_def)
+          when :asciidoc
+            generate_command_asciidoc(command_name, command_def)
+          else
+            raise ArgumentError, "Unsupported format: #{format}"
+          end
+        end
+
+        private
+
+        # Normalize format
+        #
+        # @param format [Symbol] the format
+        # @return [Symbol] normalized format
+        def normalize_format(format)
+          return :markdown if format == :md
+
+          format
+        end
+
+        # Generate Markdown documentation
+        #
+        # @param definition [Hash] the definition
+        # @return [String] Markdown documentation
+        def generate_markdown(definition)
+          output = []
+          tool_name = definition[:name] || 'Unknown'
+          version = definition[:version]
+
+          # Title
+          output << "# #{tool_name}"
+          output << '' if version
+          output << "Version: #{version}" if version
+          output << ''
+
+          # Description
+          if definition[:description]
+            output << definition[:description]
+            output << ''
+          end
+
+          # Metadata
+          output << '## Overview'
+          output << ''
+          output << '| Property | Value |'
+          output << '|----------|-------|'
+          output << "| Name | `#{tool_name}` |"
+          output << "| Version | `#{version}` |" if version
+          output << "| Homepage | #{definition[:homepage]} |" if definition[:homepage]
+          output << ''
+
+          # Platforms
+          platforms = extract_platforms(definition)
+          if platforms.any?
+            output << '### Supported Platforms'
+            output << ''
+            platforms.each do |platform|
+              shells = extract_shells_for_platform(definition, platform)
+              output << "- **#{platform.to_s.capitalize}**: #{shells.join(', ')}"
+            end
+            output << ''
+          end
+
+          # Installation
+          if definition[:install]
+            output << '## Installation'
+            output << ''
+            output << render_installation_markdown(definition[:install])
+            output << ''
+          end
+
+          # Commands
+          commands = extract_commands(definition)
+          if commands.any?
+            output << '## Commands'
+            output << ''
+            commands.each do |cmd_name, cmd_def|
+              output << generate_command_markdown(cmd_name, cmd_def)
+            end
+          end
+
+          # Options reference
+          if commands.any?
+            output << '## Options Reference'
+            output << ''
+            commands.each do |cmd_name, cmd_def|
+              options = cmd_def[:options] || []
+              flags = cmd_def[:flags] || []
+
+              next unless options.any? || flags.any?
+
+              output << "### `#{cmd_name}`"
+              output << ''
+
+              if options.any?
+                output << '#### Options'
+                output << ''
+                options.each do |opt|
+                  output << render_option_markdown(opt)
+                end
+              end
+
+              if flags.any?
+                output << '#### Flags'
+                output << ''
+                flags.each do |flag|
+                  output << render_flag_markdown(flag)
+                end
+              end
+
+              output << ''
+            end
+          end
+
+          output.join("\n")
+        end
+
+        # Generate command documentation in Markdown
+        #
+        # @param command_name [String] the command name
+        # @param command_def [Hash] the command definition
+        # @return [String] command documentation
+        def generate_command_markdown(command_name, command_def)
+          output = []
+          output << "### `#{command_name}`"
+          output << ''
+
+          if command_def[:description]
+            output << command_def[:description]
+            output << ''
+          end
+
+          # Arguments
+          if command_def[:arguments]
+            output << '#### Arguments'
+            output << ''
+            command_def[:arguments].each do |arg|
+              output << render_argument_markdown(arg)
+            end
+            output << ''
+          end
+
+          output.join("\n")
+        end
+
+        # Render option in Markdown
+        #
+        # @param opt [Hash] the option
+        # @return [String] rendered option
+        def render_option_markdown(opt)
+          cli = opt[:cli] || opt[:name]
+          required = opt[:required] ? '**(required)**' : '(optional)'
+          desc = opt[:description] || ''
+
+          output = "- `#{cli}` #{required}"
+          output << " - #{desc}" if desc
+          output << "\n\n  Type: `#{opt[:type]}`" if opt[:type]
+          output
+        end
+
+        # Render flag in Markdown
+        #
+        # @param flag [Hash] the flag
+        # @return [String] rendered flag
+        def render_flag_markdown(flag)
+          cli = flag[:cli] || flag[:name]
+          desc = flag[:description] || ''
+
+          output = "- `#{cli}`"
+          output << " - #{desc}" if desc
+          output
+        end
+
+        # Render argument in Markdown
+        #
+        # @param arg [Hash] the argument
+        # @return [String] rendered argument
+        def render_argument_markdown(arg)
+          name = arg[:name]
+          type = arg[:type] || 'any'
+          desc = arg[:description] || ''
+          required = arg[:required] ? '**required**' : 'optional'
+
+          output = "- **`#{name}`** (#{type}, #{required})"
+          output << " - #{desc}" if desc
+          output
+        end
+
+        # Render installation instructions in Markdown
+        #
+        # @param install [Hash] installation instructions
+        # @return [String] rendered installation
+        def render_installation_markdown(install)
+          output = []
+
+          if install[:macos]
+            output << '#### macOS'
+            output << '```bash'
+            output << install[:macos]
+            output << '```'
+            output << ''
+          end
+
+          if install[:linux]
+            output << '#### Linux'
+            output << '```bash'
+            output << install[:linux]
+            output << '```'
+            output << ''
+          end
+
+          if install[:windows]
+            output << '#### Windows'
+            output << '```powershell'
+            output << install[:windows]
+            output << '```'
+            output << ''
+          end
+
+          output.join("\n")
+        end
+
+        # Generate AsciiDoc documentation
+        #
+        # @param definition [Hash] the definition
+        # @return [String] AsciiDoc documentation
+        def generate_asciidoc(definition)
+          output = []
+          tool_name = definition[:name] || 'Unknown'
+          version = definition[:version]
+
+          # Title
+          output << "= #{tool_name}"
+          output << '' if version
+          output << ':toc:' if definition[:profiles] # Only add TOC if there's content
+          output << ''
+
+          if version
+            output << "Version: #{version}"
+            output << ''
+          end
+
+          # Description
+          if definition[:description]
+            output << definition[:description]
+            output << ''
+          end
+
+          # Overview
+          output << '== Overview'
+          output << ''
+          output << '[cols="1,2"]'
+          output << '|==='
+          output << '| Property | Value'
+          output << "| Name | `#{tool_name}`"
+          output << "| Version | `#{version}`" if version
+          output << "| Homepage | #{definition[:homepage]}" if definition[:homepage]
+          output << '|==='
+          output << ''
+
+          # Platforms
+          platforms = extract_platforms(definition)
+          if platforms.any?
+            output << '=== Supported Platforms'
+            output << ''
+            platforms.each do |platform|
+              shells = extract_shells_for_platform(definition, platform)
+              output << "* *#{platform.to_s.capitalize}*: #{shells.join(', ')}"
+            end
+            output << ''
+          end
+
+          # Commands
+          commands = extract_commands(definition)
+          if commands.any?
+            output << '== Commands'
+            output << ''
+            commands.each do |cmd_name, cmd_def|
+              output << generate_command_asciidoc(cmd_name, cmd_def)
+            end
+          end
+
+          output.join("\n")
+        end
+
+        # Generate command documentation in AsciiDoc
+        #
+        # @param command_name [String] the command name
+        # @param command_def [Hash] the command definition
+        # @return [String] command documentation
+        def generate_command_asciidoc(command_name, command_def)
+          output = []
+          output << "=== `#{command_name}`"
+          output << ''
+
+          if command_def[:description]
+            output << command_def[:description]
+            output << ''
+          end
+
+          if command_def[:arguments]
+            output << '==== Arguments'
+            output << ''
+            command_def[:arguments].each do |arg|
+              name = arg[:name]
+              type = arg[:type] || 'any'
+              desc = arg[:description] || ''
+              required = arg[:required] ? '*required*' : 'optional'
+
+              output << "* **`#{name}`** (#{type}, #{required})"
+              output << ": #{desc}" if desc
+            end
+            output << ''
+          end
+
+          output.join("\n")
+        end
+
+        # Extract all platforms from definition
+        #
+        # @param definition [Hash] the definition
+        # @return [Array<Symbol>] platforms
+        def extract_platforms(definition)
+          platforms = Set.new
+          return platforms.to_a unless definition[:profiles]
+
+          definition[:profiles].each do |profile|
+            next unless profile[:platforms]
+
+            profile[:platforms].each { |p| platforms.add(p) }
+          end
+
+          platforms.to_a
+        end
+
+        # Extract shells for a specific platform
+        #
+        # @param definition [Hash] the definition
+        # @param platform [Symbol] the platform
+        # @return [Array<Symbol>] shells
+        def extract_shells_for_platform(definition, platform)
+          shells = Set.new
+          return shells.to_a unless definition[:profiles]
+
+          definition[:profiles].each do |profile|
+            next unless profile[:platforms]&.include?(platform)
+            next unless profile[:shells]
+
+            profile[:shells].each { |s| shells.add(s) }
+          end
+
+          shells.to_a.sort
+        end
+
+        # Extract all commands from definition
+        #
+        # @param definition [Hash] the definition
+        # @return [Hash] commands
+        def extract_commands(definition)
+          commands = {}
+
+          return commands unless definition[:profiles]
+
+          definition[:profiles].each do |profile|
+            next unless profile[:commands]
+
+            profile[:commands].each do |name, cmd_def|
+              commands[name] = cmd_def unless commands.key?(name)
+            end
+          end
+
+          commands
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/definition/lint_issue.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Definition
+    # A linting issue found in a definition
+    #
+    # This class represents a single linting issue with severity,
+    # message, location, and optional suggestion.
+    class LintIssue
+      # Severity levels
+      SEVERITY_ERROR = :error
+      SEVERITY_WARNING = :warning
+      SEVERITY_INFO = :info
+      SEVERITY_STYLE = :style
+
+      attr_reader :severity, :message, :location, :suggestion, :rule_id
+
+      def initialize(severity:, message:, location: nil, suggestion: nil, rule_id: nil)
+        @severity = severity
+        @message = message
+        @location = location
+        @suggestion = suggestion
+        @rule_id = rule_id
+      end
+
+      # Check if this is an error
+      #
+      # @return [Boolean] true if severity is error
+      def error?
+        @severity == SEVERITY_ERROR
+      end
+
+      # Check if this is a warning
+      #
+      # @return [Boolean] true if severity is warning
+      def warning?
+        @severity == SEVERITY_WARNING
+      end
+
+      # Check if this is info
+      #
+      # @return [Boolean] true if severity is info
+      def info?
+        @severity == SEVERITY_INFO
+      end
+
+      # Check if this is style
+      #
+      # @return [Boolean] true if severity is style
+      def style?
+        @severity == SEVERITY_STYLE
+      end
+
+      # Check if this issue has a suggestion
+      #
+      # @return [Boolean] true if suggestion is present
+      def has_suggestion?
+        !@suggestion.nil? && !@suggestion.empty?
+      end
+
+      # Check if this issue has a location
+      #
+      # @return [Boolean] true if location is present
+      def has_location?
+        !@location.nil? && !@location.empty?
+      end
+
+      # Get severity as a readable string
+      #
+      # @return [String] severity string
+      def severity_string
+        @severity.to_s.upcase
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] hash representation
+      def to_h
+        {
+          severity: @severity,
+          severity_string: severity_string,
+          message: @message,
+          location: @location,
+          suggestion: @suggestion,
+          rule_id: @rule_id
+        }
+      end
+
+      # Format as string
+      #
+      # @return [String] formatted issue
+      def to_s
+        output = "[#{severity_string}] #{@message}"
+        output += " (at #{@location})" if has_location?
+        output += "\n  Suggestion: #{@suggestion}" if has_suggestion?
+        output
+      end
+
+      # Create an error issue
+      #
+      # @param message [String] error message
+      # @param location [String, nil] issue location
+      # @param suggestion [String, nil] fix suggestion
+      # @param rule_id [String, nil] rule identifier
+      # @return [LintIssue] error issue
+      def self.error(message, location: nil, suggestion: nil, rule_id: nil)
+        new(
+          severity: SEVERITY_ERROR,
+          message: message,
+          location: location,
+          suggestion: suggestion,
+          rule_id: rule_id
+        )
+      end
+
+      # Create a warning issue
+      #
+      # @param message [String] warning message
+      # @param location [String, nil] issue location
+      # @param suggestion [String, nil] fix suggestion
+      # @param rule_id [String, nil] rule identifier
+      # @return [LintIssue] warning issue
+      def self.warning(message, location: nil, suggestion: nil, rule_id: nil)
+        new(
+          severity: SEVERITY_WARNING,
+          message: message,
+          location: location,
+          suggestion: suggestion,
+          rule_id: rule_id
+        )
+      end
+
+      # Create an info issue
+      #
+      # @param message [String] info message
+      # @param location [String, nil] issue location
+      # @param suggestion [String, nil] fix suggestion
+      # @param rule_id [String, nil] rule identifier
+      # @return [LintIssue] info issue
+      def self.info(message, location: nil, suggestion: nil, rule_id: nil)
+        new(
+          severity: SEVERITY_INFO,
+          message: message,
+          location: location,
+          suggestion: suggestion,
+          rule_id: rule_id
+        )
+      end
+
+      # Create a style issue
+      #
+      # @param message [String] style message
+      # @param location [String, nil] issue location
+      # @param suggestion [String, nil] fix suggestion
+      # @param rule_id [String, nil] rule identifier
+      # @return [LintIssue] style issue
+      def self.style(message, location: nil, suggestion: nil, rule_id: nil)
+        new(
+          severity: SEVERITY_STYLE,
+          message: message,
+          location: location,
+          suggestion: suggestion,
+          rule_id: rule_id
+        )
+      end
+    end
+  end
+end