rubycli 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9287ea2ca51772eb53c50fe717e648c7d23a9fb1e5cb0e25990eef7f07cde225
-  data.tar.gz: aab6e71f2beafb924bb4bc29689c6ce64391d55bc43936a789278ad764e91592
+  metadata.gz: 521eac399843d8fe002c1017b24b0cf72644f179460d3a599a1b9bf9d0949d7e
+  data.tar.gz: d245d65f31c08f15c0f9bad5d4e13e3d7cb1785936772ab6a83887cd4fdf4564
 SHA512:
-  metadata.gz: 98baa8a62366c9babedda68174dbc1fadaafbdf1ea4354393bf1a525b9b1d1f2ce0459f20ef8aff81cc4a3448f0686da9bf7940a8fde2526a3b42caf3d2feb63
-  data.tar.gz: ac5044eec17148e3bb26ef1aa2fd67b78e6578acd6693747bb9a95e8d043e1842f9ebc853e6e50297130d0351fdfb9cfad04c1d217738c6462eda94c1c5b039f
+  metadata.gz: 286af4633230ddd40c39e40c2ec92f810bd47cc533c1d578dc42178179552518bfc057f992beef340cc4a34592c603d0ddc6d10eef1df928ce83be383cd9857c
+  data.tar.gz: 82e587aac72882cb1b3e317d20d2dc37c54ed8e927fc39ffa9d28dd871d77b05c6d2fc64ad13dc5e3fe7c903b6f5312dfa0b34e9e46391e66788435286c909e9

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.6] - 2025-11-11
+
+### Changed
+- `rubycli --check` now reports unknown type tokens and enumerated allowed values (with DidYouMean suggestions) instead of silently treating them as strings, while `--strict` continues to enforce the surviving annotations at runtime.
+
 ## [0.1.5] - 2025-11-10
 
 ### Added

data/README.ja.md

@@ -156,13 +156,13 @@ Rubycli は「ファイル名を CamelCase にした定数」を公開対象だ
 
 大規模なコードベースでも安全側を保ちながら、どうしても自動選択したいときだけ 1 フラグで切り替えられます。
 
-> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。
+> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。`--new` を付ければ `rubycli --help` でもインスタンスメソッドが一覧に現れ、`rubycli --check --new` でコメントの lint も実行できます。
 
 ## 開発方針
 
 - **便利さが最優先** – 既存の Ruby スクリプトを最小の手間で CLI 化できることを目的にしており、Python Fire の完全移植は目指していません。
 - **インスパイアであってポートではない** – アイデアの出自は Fire ですが、同等機能を揃える予定は基本的にありません。Fire 由来の未実装機能は仕様です。
-- **メソッド定義が土台、コメントが挙動を補強** – 公開メソッドのシグネチャが CLI に露出する範囲と必須／任意を決めますが、コメントに `TAG...` や `[Integer]` を書くと同じ引数でも配列化や型変換が行われます。さらに Rubycli は `--names='["Alice","Bob"]'` のような JSON/YAML らしい入力を自動的に安全なリテラルとして評価します。`rubycli --check パス/対象.rb` でコメントと実装のズレを検査しつつ、通常実行時に `--strict` を付ければドキュメント通りでない入力をその場でエラーにできます。（現状の `--check` は「コメントが揃っているか」を中心にチェックしており、`Booalean` のように型トークンを誤記しても検出できません。）
+- **メソッド定義が土台、コメントが挙動を補強** – 公開メソッドのシグネチャが CLI に露出する範囲と必須／任意を決めますが、コメントに `TAG...` や `[Integer]` を書くと同じ引数でも配列化や型変換が行われます。さらに Rubycli は `--names='["Alice","Bob"]'` のような JSON/YAML らしい入力を自動的に安全なリテラルとして評価します。`rubycli --check パス/対象.rb` でコメントと実装のズレ（未定義の型ラベルや列挙値の誤記を含む）を DidYouMean の候補付きで検査し、通常実行時に `--strict` を付ければドキュメント通りでない入力をその場でエラーにできます。
 - **軽量メンテナンス** – 実装の多くは AI 支援で作られており、深い Ruby メタプログラミングを伴う大規模拡張は想定外です。Fire 互換を求める PR は事前相談をお願いします。
 
 ## 特徴
@@ -173,11 +173,13 @@ Rubycli は「ファイル名を CamelCase にした定数」を公開対象だ
 - `--pre-script`（エイリアス: `--init`）で任意の Ruby コードを評価し、その結果オブジェクトを公開
 - `--check` でコメント整合性を lint、`--strict` で入力値をドキュメント通りに強制する二段構えのガード
 
+> 補足: `--strict` はコメントに書かれた型／許可値をそのまま信頼して検証するため、コメントが誤記だと実行時には検出できません。CI では必ず `rubycli --check` を走らせ、`--strict` は「 lint を通過したドキュメントを本番で厳密に守る」用途に使ってください。
+
 ## Python Fire との違い
 
 - **コメント対応のヘルプ生成**: コメントがあればヘルプに反映しつつ、最終的な判断は常にライブなメソッド定義に基づきます。
 - **型に基づく解析**: `NAME [String]` や YARD タグから型を推論し、真偽値・配列・数値などを自動変換します。
-- **厳密な整合性チェック**: `rubycli --check` でコメントと実装のズレを実行前に検査し、通常実行時に `--strict` を付ければドキュメントで宣言した型・許可値以外の入力を拒否できます。
+- **厳密な整合性チェック**: `rubycli --check` でコメントと実装のズレ（未定義の型ラベルや列挙値の誤記など）をコード実行前に検査し、通常実行時に `--strict` を付ければドキュメントで宣言した型・許可値以外の入力を拒否できます。
 - **Ruby 向け拡張**: キーワード引数やブロック (`@yield*`) といった Ruby 固有の構文に合わせたパーサや `RUBYCLI_*` 環境変数を用意しています。
 
 | 機能 | Python Fire | Rubycli |

data/README.md

@@ -163,13 +163,13 @@ Rubycli assumes that the file name (CamelCased) matches the class or module you
 
 This keeps large projects safe by default but still provides a one-flag escape hatch when you prefer the fully automatic behaviour.
 
-> **Instance-only classes** – If a class only defines public *instance* methods (for example, it exposes functionality via `def greet` on the instance), you must run Rubycli with `--new` so the class is instantiated before commands are resolved. Otherwise Rubycli cannot see any CLI-callable methods. Add at least one public class method when you do not want to rely on `--new`.
+> **Instance-only classes** – If a class only defines public *instance* methods (for example, it exposes functionality via `def greet` on the instance), you must run Rubycli with `--new` so the class is instantiated before commands are resolved. Otherwise Rubycli cannot see any CLI-callable methods. Add at least one public class method when you do not want to rely on `--new`. Passing `--new` also makes those instance methods appear in `rubycli --help` output and allows `rubycli --check --new` to lint their documentation.
 
 ## Project Philosophy
 
 - **Convenience first** – The goal is to wrap existing Ruby scripts in a CLI with almost no manual plumbing. Fidelity with Python Fire is not a requirement.
 - **Inspired, not a port** – We borrow ideas from Python Fire, but we do not aim for feature parity. Missing Fire features are generally “by design.”
-- **Method definitions first, comments augment behavior** – Public method signatures determine what gets exposed (and which arguments are required), while doc comments like `TAG...` or `[Integer]` can turn the very same CLI value into arrays, integers, booleans, etc. Rubycli also auto-parses inputs that look like JSON/YAML literals (for example `--names='["Alice","Bob"]'`) before enforcing the documented type. Run `rubycli --check path/to/script.rb` to lint documentation mismatches, and pass `--strict` during normal runs when you want invalid input to abort instead of merely warning. (Current limitation: `--check` verifies that comments cover every argument, but it does not yet validate the spelling of type tokens—`Booalean` will be treated as a plain string.)
+- **Method definitions first, comments augment behavior** – Public method signatures determine what gets exposed (and which arguments are required), while doc comments like `TAG...` or `[Integer]` can turn the very same CLI value into arrays, integers, booleans, etc. Rubycli also auto-parses inputs that look like JSON/YAML literals (for example `--names='["Alice","Bob"]'`) before enforcing the documented type. Run `rubycli --check path/to/script.rb` to lint documentation mismatches—including undefined type labels or enumerated values, with DidYouMean suggestions for `Booalean`-style typos—and pass `--strict` during normal runs when you want invalid input to abort instead of merely warning.
 - **Lightweight maintenance** – Much of the implementation was generated with AI assistance; contributions that diverge into deep Ruby metaprogramming are out of scope. Please discuss expectations before opening parity PRs.
 
 ## Features
@@ -180,11 +180,13 @@ This keeps large projects safe by default but still provides a one-flag escape h
 - Optional pre-script hook (`--pre-script` / `--init`) to evaluate Ruby and expose the resulting object
 - Dedicated CLI flags for quality gates: `--check` lints documentation/comments without running commands, and `--strict` treats documented types/choices as hard requirements
 
+> Tip: `--strict` trusts whatever types/choices your comments spell out—if the annotations are misspelled, runtime enforcement has nothing reliable to compare against. Keep `rubycli --check` in CI so documentation typos are caught before production runs that rely on `--strict`.
+
 ## How it differs from Python Fire
 
 - **Comment-aware help** – Rubycli leans on doc comments when present but still reflects the live method signature, keeping code as the ultimate authority.
 - **Type-aware parsing** – Placeholder syntax (`NAME [String]`) and YARD tags let Rubycli coerce arguments to booleans, arrays, numerics, etc. without additional code.
-- **Strict validation** – `rubycli --check` lint runs catch documentation drift before execution, while runtime `--strict` runs turn documented types/choices into enforceable contracts.
+- **Strict validation** – `rubycli --check` lint runs catch documentation drift (including undefined type labels or enumerated values) without executing commands, while runtime `--strict` runs turn those documented types/choices into enforceable contracts.
 - **Ruby-centric tooling** – Supports Ruby-specific conventions such as optional keyword arguments, block documentation (`@yield*` tags), and `RUBYCLI_*` environment toggles.
 
 | Capability | Python Fire | Rubycli |

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
@@ -137,6 +137,7 @@ module Rubycli
         description = nil if description&.empty?
 
         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
@@ -193,6 +194,7 @@ module Rubycli
 
         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)
@@ -309,6 +311,7 @@ module Rubycli
         description = description_tokens.join(' ').strip
         description = nil if description.empty?
         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
@@ -327,7 +330,7 @@ module Rubycli
         )
       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+/))
@@ -346,6 +349,7 @@ module Rubycli
         description = nil if description.empty?
 
         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(
@@ -371,10 +375,11 @@ module Rubycli
         )
       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
@@ -382,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
@@ -390,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
@@ -735,6 +804,93 @@ module Rubycli
         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
@@ -786,8 +942,16 @@ module Rubycli
       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)
@@ -805,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)
 

data/lib/rubycli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubycli
-  VERSION = '0.1.5'
+  VERSION = '0.1.6'
 end

data/lib/rubycli.rb

@@ -531,19 +531,24 @@ module Rubycli
 
     def build_missing_constant_message(name, defined_constants, full_path, details: nil)
       lines = ["Could not find definition: #{name}"]
-      lines << "  Loaded file: #{File.expand_path(full_path)}" if full_path
+      lines << ''
+      lines << "Loaded file: #{File.expand_path(full_path)}" if full_path
 
       if defined_constants && !defined_constants.empty?
         sample = defined_constants.first(5)
-        suffix = defined_constants.size > sample.size ? " ... (#{defined_constants.size} total)" : ''
-        lines << "  Constants found in this file: #{sample.join(', ')}#{suffix}"
+        suffix = defined_constants.size > sample.size ? " … (#{defined_constants.size} total)" : ''
+        lines << "Constants found in this file: #{sample.join(', ')}#{suffix}"
       else
-        lines << "  Rubycli could not detect any publicly exposable constants in this file."
+        lines << 'Rubycli could not detect any publicly exposable constants in this file.'
       end
 
-      lines << "  #{details}" if details
+      if details
+        lines << ''
+        lines << details
+      end
 
-      lines << "  Ensure the CLASS_OR_MODULE argument is correct when invoking the CLI."
+      lines << ''
+      lines << 'Hint: Ensure the CLASS_OR_MODULE argument is correct when invoking the CLI.'
       lines.join("\n")
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubycli
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-09 00:00:00.000000000 Z
+date: 2025-11-11 00:00:00.000000000 Z
 dependencies: []
 description: Rubycli turns plain Ruby classes and modules into command-line interfaces
   by reading their documentation comments, inspired by Python Fire but tailored for