rubycli 0.1.4 → 0.1.6

data/lib/rubycli/documentation/metadata_parser.rb

@@ -55,7 +55,7 @@ module Rubycli
             next
           end
 
-          if (return_meta = parse_return_metadata(stripped))
+          if (return_meta = parse_return_metadata(stripped, method_obj))
             metadata[:returns] << return_meta
             summary_phase = false
             next
@@ -68,7 +68,7 @@ module Rubycli
             next
           end
 
-          if (positional = parse_positional_line(stripped))
+          if (positional = parse_positional_line(stripped, method_obj))
             metadata[:positionals] << positional
             summary_phase = false
             next
@@ -122,7 +122,7 @@ module Rubycli
             file: source_file,
             line: line_number
           )
-          return nil if @environment.strict_mode?
+          return nil if @environment.doc_check_mode?
         end
 
         pattern = /\A@param\s+([a-zA-Z0-9_]+)(?:\s+\[([^\]]+)\])?(?:\s+\(([^)]+)\))?(?:\s+(.*))?\z/
@@ -130,12 +130,15 @@ module Rubycli
         return nil unless match
 
         param_name = match[1]
+        param_symbol = param_name.to_sym
         type_str = match[2]
         option_tokens = combine_bracketed_tokens(match[3]&.split(/\s+/) || [])
         description = match[4]&.strip
         description = nil if description&.empty?
 
-        types = parse_type_annotation(type_str)
+        raw_types = parse_type_annotation(type_str)
+        audit_type_annotation_tokens(raw_types, method_obj)
+        types, allowed_values = partition_type_tokens(raw_types)
 
         long_option = nil
         short_option = nil
@@ -179,23 +182,37 @@ module Rubycli
         end
 
         long_option ||= "--#{param_name.tr('_', '-')}"
+        role = parameter_role(method_obj, param_symbol)
+        if value_name.nil?
+          if role == :positional
+            value_name = default_placeholder_for(param_symbol)
+          elsif !types&.any? { |entry| boolean_type?(entry) }
+            # Most keywords expect a value; boolean flags should be documented with [Boolean].
+            value_name = default_placeholder_for(param_symbol)
+          end
+        end
 
-        types = parse_type_annotation(type_token) if (types.nil? || types.empty?) && type_token
+        if (types.nil? || types.empty?) && type_token
+          inline_raw_types = parse_type_annotation(type_token)
+          audit_type_annotation_tokens(inline_raw_types, method_obj)
+          inline_types, inline_allowed = partition_type_tokens(inline_raw_types)
+          types = inline_types
+          allowed_values = merge_allowed_values(allowed_values, inline_allowed)
+        end
 
+        # TODO: Derive primitive types from Ruby default values when explicit hints are absent.
         option_def = build_option_definition(
-          param_name.to_sym,
+          param_symbol,
           long_option,
           short_option,
           value_name,
           types,
           description,
           inline_type_annotation: !type_token.nil?,
-          doc_format: :tagged_param
+          doc_format: :tagged_param,
+          allowed_values: allowed_values
         )
 
-        param_symbol = param_name.to_sym
-        role = parameter_role(method_obj, param_symbol)
-
         if role == :positional
           placeholder = option_def.value_name || default_placeholder_for(option_def.keyword)
           return PositionalDefinition.new(
@@ -204,7 +221,8 @@ module Rubycli
             types: option_def.types,
             description: option_def.description,
             param_name: param_symbol,
-            doc_format: option_def.doc_format
+            doc_format: option_def.doc_format,
+            allowed_values: option_def.allowed_values
           )
         elsif role == :keyword
           return option_def
@@ -218,7 +236,8 @@ module Rubycli
             types: option_def.types,
             description: option_def.description,
             param_name: param_symbol,
-            doc_format: option_def.doc_format
+            doc_format: option_def.doc_format,
+            allowed_values: option_def.allowed_values
           )
         end
 
@@ -291,7 +310,9 @@ module Rubycli
 
         description = description_tokens.join(' ').strip
         description = nil if description.empty?
-        types = parse_type_annotation(type_token)
+        raw_types = parse_type_annotation(type_token)
+        audit_type_annotation_tokens(raw_types, method_obj)
+        types, allowed_values = partition_type_tokens(raw_types)
 
         keyword = long_option.delete_prefix('--').tr('-', '_').to_sym
         return nil unless method_accepts_keyword?(method_obj, keyword)
@@ -304,11 +325,12 @@ module Rubycli
           types,
           description,
           inline_type_annotation: !type_token.nil?,
-          doc_format: :rubycli
+          doc_format: :rubycli,
+          allowed_values: allowed_values
         )
       end
 
-      def parse_positional_line(line)
+      def parse_positional_line(line, method_obj)
         return nil if line.start_with?('--') || line.start_with?('-')
 
         tokens = combine_bracketed_tokens(line.split(/\s+/))
@@ -326,7 +348,9 @@ module Rubycli
         description = tokens.join(' ').strip
         description = nil if description.empty?
 
-        types = parse_type_annotation(type_token)
+        raw_types = parse_type_annotation(type_token)
+        audit_type_annotation_tokens(raw_types, method_obj)
+        types, allowed_values = partition_type_tokens(raw_types)
         placeholder_info = analyze_placeholder(placeholder)
         inferred_types = infer_types_from_placeholder(
           normalize_type_list(types),
@@ -346,14 +370,16 @@ module Rubycli
           description: description,
           inline_type_annotation: inline_annotation,
           inline_type_text: inline_text,
-          doc_format: :rubycli
+          doc_format: :rubycli,
+          allowed_values: allowed_values
         )
       end
 
-      def parse_return_metadata(line)
+      def parse_return_metadata(line, method_obj)
         yard_match = /\A@return\s+\[([^\]]+)\](?:\s+(.*))?\z/.match(line)
         if yard_match
           types = parse_type_annotation(yard_match[1])
+          audit_type_annotation_tokens(types, method_obj)
           description = yard_match[2]&.strip
           return ReturnDefinition.new(types: types, description: description)
         end
@@ -361,6 +387,7 @@ module Rubycli
         shorthand_match = /\A=>\s+(\[[^\]]+\]|[^\s]+)(?:\s+(.*))?\z/.match(line)
         if shorthand_match
           types = parse_type_annotation(shorthand_match[1])
+          audit_type_annotation_tokens(types, method_obj)
           description = shorthand_match[2]&.strip
           return ReturnDefinition.new(types: types, description: description)
         end
@@ -369,11 +396,74 @@ module Rubycli
           stripped = line.sub(/\Areturn\s+/, '')
           type_token, description = stripped.split(/\s+/, 2)
           types = parse_type_annotation(type_token)
+          audit_type_annotation_tokens(types, method_obj)
           description = description&.strip
           return ReturnDefinition.new(types: types, description: description)
         end
       end
 
+      def doc_issue_location(method_obj)
+        return [nil, nil] unless method_obj.respond_to?(:source_location)
+
+        source_file, source_line = method_obj.source_location
+        line_number = source_line ? [source_line - 1, 1].max : nil
+        [source_file, line_number]
+      end
+
+      def audit_type_annotation_tokens(tokens, method_obj)
+        return if tokens.nil? || tokens.empty?
+        return unless @environment.doc_check_mode?
+
+        source_file, line_number = doc_issue_location(method_obj)
+        literal_tokens_present = Array(tokens).any? do |token|
+          literal_entry = literal_entry_from_token(token)
+          literal_entry || literal_hint_token?(token)
+        end
+
+        Array(tokens).each do |token|
+          audit_single_token(token, source_file, line_number, literal_tokens_present)
+        end
+      end
+
+      def audit_single_token(token, source_file, line_number, literal_context)
+        normalized = token.to_s.strip
+        return if normalized.empty?
+
+        if literal_hint_token?(normalized)
+          expand_annotation_token(normalized).each do |entry|
+            audit_literal_entry(entry, source_file, line_number)
+          end
+          return
+        end
+
+        literal_entry = literal_entry_from_token(normalized)
+        if literal_entry
+          return
+        end
+
+        if literal_context && literal_token_candidate?(normalized, include_uppercase: true) && !known_type_token?(normalized)
+          warn_unknown_allowed_value(normalized, source_file, line_number)
+          return
+        end
+
+        if literal_token_candidate?(normalized, include_uppercase: false)
+          warn_unknown_allowed_value(normalized, source_file, line_number)
+          return
+        end
+
+        return if inline_type_hint?(normalized)
+        return if known_type_token?(normalized)
+
+        warn_unknown_type_token(normalized, source_file, line_number)
+      end
+
+      def audit_literal_entry(token, source_file, line_number)
+        literal_entry = literal_entry_from_token(token)
+        return if literal_entry
+
+        warn_unknown_allowed_value(token, source_file, line_number)
+      end
+
       def extract_parameter_defaults(method_obj)
         location = method_obj.source_location
         return {} unless location
@@ -493,16 +583,18 @@ module Rubycli
                 file: source_file,
                 line: line_for_comment
               )
-              unless @environment.strict_mode?
+              unless @environment.doc_check_mode?
                 fallback = PositionalDefinition.new(
                   placeholder: name.to_s,
                   label: name.to_s.upcase,
-                  types: [],
+                  types: ['String'],
                   description: nil,
                   param_name: name,
                   default_value: defaults[name],
                   inline_type_annotation: false,
-                  inline_type_text: nil
+                  inline_type_text: nil,
+                  doc_format: :auto_generated,
+                  allowed_values: []
                 )
                 metadata[:positionals] << fallback
                 positional_map[name] = fallback
@@ -517,7 +609,7 @@ module Rubycli
                 file: source_file,
                 line: line_for_comment
               )
-              unless @environment.strict_mode?
+              unless @environment.doc_check_mode?
                 fallback_option = build_auto_option_definition(name)
                 ordered_options << fallback_option if fallback_option
               end
@@ -558,6 +650,11 @@ module Rubycli
                 opt.value_name = nil
                 opt.types = ['Boolean']
               end
+            elsif opt.boolean_flag
+              opt.boolean_flag = false
+              opt.requires_value = true
+              opt.value_name ||= default_placeholder_for(opt.keyword)
+              opt.types = ['String'] if opt.types.nil? || opt.types.empty?
             end
           end
         end
@@ -616,6 +713,185 @@ module Rubycli
         cleaned.split(/[,|]/).map { |token| normalize_type_token(token) }.reject(&:empty?)
       end
 
+      def partition_type_tokens(tokens)
+        normalized = Array(tokens).dup
+        allowed = []
+
+        normalized.each do |token|
+          expand_annotation_token(token).each do |expanded|
+            literal_entry = literal_entry_from_token(expanded)
+            allowed << literal_entry if literal_entry
+          end
+        end
+
+        [normalized, allowed.compact.uniq]
+      end
+
+      def merge_allowed_values(primary, additional)
+        return Array(additional) if primary.nil? || primary.empty?
+        return Array(primary) if additional.nil? || additional.empty?
+
+        (primary + additional).uniq
+      end
+
+      def expand_annotation_token(token)
+        return [] unless token
+
+        stripped = token.strip
+        return [] if stripped.empty?
+
+        if stripped.start_with?('%i[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/).map { |entry| ":#{entry}" }
+        elsif stripped.start_with?('%I[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/).map { |entry| ":#{entry}" }
+        elsif stripped.start_with?('%w[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/)
+        elsif stripped.start_with?('%W[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/)
+        else
+          [stripped]
+        end
+      end
+
+      def literal_entry_from_token(token)
+        return nil unless token
+
+        stripped = token.strip
+        return nil if stripped.empty?
+        stripped = stripped[1..] if stripped.start_with?('[') && !stripped.end_with?(']')
+        if stripped.end_with?(']') && !stripped.include?('[')
+          stripped = stripped[0...-1]
+        end
+
+        lowered = stripped.downcase
+        return { kind: :literal, value: nil } if %w[nil null ~].include?(lowered)
+        return { kind: :literal, value: true } if lowered == 'true'
+        return { kind: :literal, value: false } if lowered == 'false'
+
+        if stripped.start_with?(':')
+          sym_name = stripped[1..]
+          return nil if sym_name.nil? || sym_name.empty?
+
+          return { kind: :literal, value: sym_name.to_sym }
+        end
+
+        if stripped.start_with?('"') && stripped.end_with?('"') && stripped.length >= 2
+          return { kind: :literal, value: stripped[1..-2] }
+        end
+
+        if stripped.start_with?("'") && stripped.end_with?("'") && stripped.length >= 2
+          return { kind: :literal, value: stripped[1..-2] }
+        end
+
+        if stripped.match?(/\A-?\d+\z/)
+          return { kind: :literal, value: Integer(stripped) }
+        end
+
+        if stripped.match?(/\A-?\d+\.\d+\z/)
+          return { kind: :literal, value: Float(stripped) }
+        end
+
+        if stripped.match?(/\A[a-z0-9._-]+\z/)
+          return { kind: :literal, value: stripped }
+        end
+
+        nil
+      rescue ArgumentError
+        nil
+      end
+
+      def literal_token_candidate?(token, include_uppercase: false)
+        return false unless token
+
+        stripped = token.strip
+        return false if stripped.empty?
+
+        lowered = stripped.downcase
+        return true if %w[true false nil null ~].include?(lowered)
+        return true if stripped.start_with?(':', '"', "'")
+        return true if stripped.match?(/\A-?\d/)
+
+        pattern = include_uppercase ? /\A[a-z0-9._-]+\z/i : /\A[a-z0-9._-]+\z/
+        stripped.match?(pattern)
+      end
+
+      def warn_unknown_type_token(token, source_file, line_number)
+        return if token.nil? || token.empty?
+
+        suggestions = type_token_suggestions(token)
+        message = "Unknown type token '#{token}'"
+        if suggestions.any?
+          hint = suggestions.first(2).join(' or ')
+          message = "#{message} (did you mean #{hint}?)"
+        end
+        @environment.handle_documentation_issue(message, file: source_file, line: line_number)
+      end
+
+      def warn_unknown_allowed_value(token, source_file, line_number)
+        return if token.nil? || token.empty?
+
+        suggestions = allowed_value_suggestions(token)
+        message = "Unknown allowed value token '#{token}'"
+        if suggestions.any?
+          hint = suggestions.first(2).join(' or ')
+          message = "#{message} (did you mean #{hint}?)"
+        end
+        @environment.handle_documentation_issue(message, file: source_file, line: line_number)
+      end
+
+      def type_token_suggestions(token)
+        dictionary = type_dictionary
+        return [] if dictionary.empty?
+
+        require 'did_you_mean'
+        checker = DidYouMean::SpellChecker.new(dictionary: dictionary)
+        checker.correct(token.to_s).take(3)
+      rescue LoadError, NameError
+        []
+      end
+
+      def allowed_value_suggestions(token)
+        stripped = token.to_s.strip
+        return [] if stripped.empty?
+
+        candidates = []
+        if stripped.match?(/\A[a-z0-9._-]+\z/i)
+          candidates << ":#{stripped.downcase}"
+          candidates << stripped.downcase.inspect
+        end
+        return [] if candidates.empty?
+
+        require 'did_you_mean'
+        checker = DidYouMean::SpellChecker.new(dictionary: candidates)
+        checker.correct(stripped).take(2)
+      rescue LoadError, NameError
+        candidates.first(1)
+      end
+
+      def type_dictionary
+        builtins = (INLINE_TYPE_HINTS + %w[NilClass Fixnum Decimal Struct]).uniq
+        constant_names = []
+        begin
+          ObjectSpace.each_object(Module) do |mod|
+            name = mod.name
+            next unless name && !name.empty?
+
+            constant_names << name
+            parts = name.split('::')
+            constant_names << parts.last if parts.size > 1
+          end
+        rescue StandardError
+          constant_names = Object.constants.map(&:to_s)
+        end
+
+        (builtins + constant_names).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+      end
+
+
       def placeholder_token?(token)
         return false unless token
 
@@ -652,18 +928,30 @@ module Rubycli
         return false if stripped.empty?
 
         return true if stripped.start_with?('@')
+        return true if stripped.start_with?('%')
+        return true if stripped.include?('::')
+        return true if stripped.start_with?('(') && stripped.end_with?(')')
+        return true if stripped.include?('[') && stripped.include?(']')
 
-        parsed = parse_type_annotation(stripped)
-        return false if parsed.empty?
+        normalized = normalize_type_token(stripped)
+        return false if normalized.empty?
 
-        parsed.all? { |entry| inline_type_hint?(entry) }
+        INLINE_TYPE_HINTS.include?(normalized)
       end
 
       def known_type_token?(token)
         return false unless token
 
-        candidate = token.start_with?('@') ? token[1..] : token
-        candidate =~ /\A[A-Z][A-Za-z0-9_:<>\[\]]*\z/
+        normalized = normalize_type_token(token)
+        return false if normalized.empty?
+
+        return true if primitive_type_token?(normalized)
+
+        if (inner = array_inner_type_token(normalized))
+          return known_type_token?(inner)
+        end
+
+        !safe_constant_lookup(normalized).nil?
       end
 
       def inline_type_hint?(token)
@@ -681,6 +969,53 @@ module Rubycli
         INLINE_TYPE_HINTS.include?(base)
       end
 
+      def primitive_type_token?(token)
+        return false if token.nil? || token.empty?
+
+        base = token.to_s
+        INLINE_TYPE_HINTS.include?(base) || %w[NilClass Fixnum Decimal Struct].include?(base)
+      end
+
+      def array_inner_type_token(token)
+        return nil unless token
+
+        stripped = token.to_s.strip
+        if stripped.end_with?('[]')
+          stripped[0..-3]
+        elsif stripped.start_with?('Array<') && stripped.end_with?('>')
+          stripped[6..-2].strip
+        else
+          nil
+        end
+      end
+
+      def safe_constant_lookup(name)
+        parts = name.to_s.split('::').reject(&:empty?)
+        return nil if parts.empty?
+
+        context = Object
+        parts.each do |const_name|
+          return nil unless context.const_defined?(const_name, false)
+
+          context = context.const_get(const_name)
+        end
+        context
+      rescue NameError
+        nil
+      end
+
+      def literal_hint_token?(token)
+        return false unless token
+
+        stripped = token.to_s.strip
+        return false if stripped.empty?
+
+        stripped.start_with?('%i[') ||
+          stripped.start_with?('%I[') ||
+          stripped.start_with?('%w[') ||
+          stripped.start_with?('%W[')
+      end
+
       def parameter_role(method_obj, keyword)
         return nil unless method_obj.respond_to?(:parameters)
 
@@ -723,6 +1058,9 @@ module Rubycli
           elsif token.start_with?('(') && !token.include?(')')
             buffer = token.dup
             closing = ')'
+          elsif token.start_with?('%') && token.include?('[') && !token.include?(']')
+            buffer = token.dup
+            closing = ']'
           else
             combined << token
           end
@@ -755,7 +1093,8 @@ module Rubycli
         types,
         description,
         inline_type_annotation: false,
-        doc_format: nil
+        doc_format: nil,
+        allowed_values: nil
       )
         normalized_long = normalize_long_option(long_option)
         normalized_short = normalize_short_option(short_option)
@@ -800,10 +1139,15 @@ module Rubycli
           optional_value: optional_value,
           inline_type_annotation: inline_type_annotation,
           inline_type_text: inline_type_text,
-          doc_format: doc_format
+          doc_format: doc_format,
+          allowed_values: normalize_allowed_values(allowed_values)
         )
       end
 
+      def normalize_allowed_values(values)
+        Array(values).compact.uniq
+      end
+
       def build_auto_option_definition(keyword)
         long_option = "--#{keyword.to_s.tr('_', '-')}"
         placeholder = default_placeholder_for(keyword)
@@ -815,7 +1159,8 @@ module Rubycli
           [],
           nil,
           inline_type_annotation: false,
-          doc_format: :auto_generated
+          doc_format: :auto_generated,
+          allowed_values: []
         )
       end
 
@@ -830,7 +1175,8 @@ module Rubycli
           default_value: option.default_value,
           inline_type_annotation: option.inline_type_annotation,
           inline_type_text: option.inline_type_text,
-          doc_format: option.doc_format
+          doc_format: option.doc_format,
+          allowed_values: option.allowed_values
         )
       end
     end

data/lib/rubycli/documentation_registry.rb

@@ -20,7 +20,7 @@ module Rubycli
       location = method_obj.source_location
       return empty_metadata unless location
 
-      cache_key = [location[0], location[1], @environment.strict_mode?, @environment.allow_param_comments?]
+      cache_key = [location[0], location[1], @environment.doc_check_mode?, @environment.allow_param_comments?]
       return deep_dup(@metadata_cache[cache_key]) if @metadata_cache.key?(cache_key)
 
       comment_lines = @comment_extractor.extract(location[0], location[1])

data/lib/rubycli/environment.rb

@@ -6,6 +6,9 @@ module Rubycli
       @argv = argv
       @debug = env['RUBYCLI_DEBUG'] == 'true'
       @print_result = env['RUBYCLI_PRINT_RESULT'] == 'true'
+      @doc_check_mode = false
+      @strict_input = false
+      @documentation_issues = []
       scrub_argv_flags!
     end
 
@@ -17,16 +20,39 @@ module Rubycli
       @print_result
     end
 
-    def strict_mode?
-      value = fetch_env_value('RUBYCLI_STRICT', 'OFF')
-      !%w[off 0 false].include?(value.downcase)
-    end
-
     def allow_param_comments?
       value = fetch_env_value('RUBYCLI_ALLOW_PARAM_COMMENT', 'ON')
       %w[on 1 true].include?(value)
     end
 
+    def enable_doc_check!
+      @doc_check_mode = true
+    end
+
+    def doc_check_mode?
+      @doc_check_mode
+    end
+
+    def disable_doc_check!
+      @doc_check_mode = false
+    end
+
+    def enable_strict_input!
+      @strict_input = true
+    end
+
+    def strict_input?
+      @strict_input
+    end
+
+    def documentation_issues
+      @documentation_issues.dup
+    end
+
+    def clear_documentation_issues!
+      @documentation_issues.clear
+    end
+
     def constant_resolution_mode
       value = fetch_env_value('RUBYCLI_AUTO_TARGET', 'strict')
       return :auto if %w[auto on true yes 1].include?(value)
@@ -49,7 +75,17 @@ module Rubycli
         message
       end
 
-      warn "[WARN] Rubycli documentation mismatch: #{formatted_message}" if strict_mode?
+      entry = { message: formatted_message, location: location }
+      @documentation_issues << entry
+      warn "[WARN] Rubycli documentation mismatch: #{formatted_message}" if doc_check_mode?
+    end
+
+    def handle_input_violation(message)
+      if strict_input?
+        raise Rubycli::ArgumentError, message
+      else
+        warn "[WARN] #{message} (use --strict to abort on invalid input)"
+      end
     end
 
     def enable_print_result!
@@ -65,7 +101,6 @@ module Rubycli
     def scrub_argv_flags!
       return unless @argv
 
-      remove_all_flags!(@argv, '--debug') { @debug = true }
       remove_all_flags!(@argv, '--print-result') { @print_result = true }
     end