rubycli 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9287ea2ca51772eb53c50fe717e648c7d23a9fb1e5cb0e25990eef7f07cde225
-  data.tar.gz: aab6e71f2beafb924bb4bc29689c6ce64391d55bc43936a789278ad764e91592
+  metadata.gz: '07113181085c0df0c8f4bc34aca661d4c29fb9bbc309012ace52b36e8bdf9ead'
+  data.tar.gz: 773d7de6a820fd1702e4e618c595237e2293c74dca6cc83f3ea57ba9eaaa18db
 SHA512:
-  metadata.gz: 98baa8a62366c9babedda68174dbc1fadaafbdf1ea4354393bf1a525b9b1d1f2ce0459f20ef8aff81cc4a3448f0686da9bf7940a8fde2526a3b42caf3d2feb63
-  data.tar.gz: ac5044eec17148e3bb26ef1aa2fd67b78e6578acd6693747bb9a95e8d043e1842f9ebc853e6e50297130d0351fdfb9cfad04c1d217738c6462eda94c1c5b039f
+  metadata.gz: dadd19c4c2081e6fd7f8d6e40750c3cbc727a2c7f0452a5eb81b6feb80ce878e50fac111589ea87415d7656db4d288591bf7352fd4ee80031998e5835e84e732
+  data.tar.gz: 0aef161e5d6fd30fb475de5afc908ecc94f1b5d4d1c96c0d735399c90b615e865e91286fa100008804d846d22e37874528b192dcbcea74b52484e45ef56273b6

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+# Changelog
+
+## [0.1.7] - 2025-11-12
+
+### Added
+- `--new` now optionally accepts constructor arguments inline (e.g., `--new=[...]`); YAML/JSON-like literals are safely parsed, and `--json-args` / `--eval-args` / `--eval-lax` still apply. Arrays become positional args, hashes become keyword args.
+- Positional argument coercion now runs through the same type-conversion pipeline as options/`--new`, including comment-driven array/element coercion and strict-mode validation; new tests cover arrays, hashes, booleans, and `--new` with JSON/eval modes.
+- Added `examples/new_mode_runner.rb` to showcase `--new` with constructor args, eval/JSON modes, and pre-script initialization for instance-only classes.
+- Strengthened tests for `--eval-lax` success/fallback with `--new` and end-to-end positional Hash coercion to guard against regressions.
+
+### Changed
+- `--new` arguments now flow through the same type-coercion pipeline as regular CLI arguments (including comment-driven type hints) before being passed to `initialize`.
+
+## [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,15 @@ Rubycli は「ファイル名を CamelCase にした定数」を公開対象だ
 
 大規模なコードベースでも安全側を保ちながら、どうしても自動選択したいときだけ 1 フラグで切り替えられます。
 
-> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。
+> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。`--new` を付ければ `rubycli --help` でもインスタンスメソッドが一覧に現れ、`rubycli --check --new` でコメントの lint も実行できます。初期化時に引数が必要なら `--new=VALUE` のように続けて指定できます（通常の引数と同様に YAML/JSON ライクな安全パースに加え、`--json-args` / `--eval-args` / `--eval-lax` も適用可能）。`initialize` に書いたコメントも通常の CLI メソッドと同様に型変換に反映されます。
+
+> 補足: `--new 1` のようにスペース区切りで 1 つだけ値を渡すと、後続トークンがパス扱いされやすいため `--new=VALUE` のように `=` 付きで指定するのが確実です。
 
 ## 開発方針
 
 - **便利さが最優先** – 既存の 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 は事前相談をお願いします。
 
 ## 特徴
@@ -172,18 +174,35 @@ Rubycli は「ファイル名を CamelCase にした定数」を公開対象だ
 - 引数はデフォルトで安全なリテラルとして解釈し、必要に応じて厳格 JSON モードや Ruby eval モードを切り替え可能
 - `--pre-script`（エイリアス: `--init`）で任意の Ruby コードを評価し、その結果オブジェクトを公開
 - `--check` でコメント整合性を lint、`--strict` で入力値をドキュメント通りに強制する二段構えのガード
+- `examples/new_mode_runner.rb` ではインスタンス専用クラスを `--new=VALUE` で初期化し、eval/JSON モードや pre-script を組み合わせる例を示しています。
+
+### サンプル / 付属例
+
+- `examples/hello_app.rb` / `examples/hello_app_with_docs.rb`: 最小のモジュール関数とドキュメント付きの版
+- `examples/typed_arguments_demo.rb`: 標準ライブラリ型 (Date/Time/BigDecimal/Pathname) の coercion
+- `examples/strict_choices_demo.rb`: リテラル列挙と `--strict` の組み合わせ
+- `examples/new_mode_runner.rb`: インスタンス専用クラスを `--new=VALUE` で初期化し、eval/JSON/pre-script を組み合わせる例
+
+#### サンプルコマンド
+
+- `rubycli examples/new_mode_runner.rb run --new='["a","b","c"]' --mode reverse`
+- `rubycli --json-args --new='["x","y"]' examples/new_mode_runner.rb run --mode summary --options '{"source":"json"}'`
+- `rubycli --eval-args --new='["x","y"]' examples/new_mode_runner.rb run --mode summary --options '{tags: [:a, :b]}'`
+- `rubycli --pre-script 'NewModeRunner.new(%w[a b c], options: {from: :pre})' examples/new_mode_runner.rb run --mode summary`
+
+> 補足: `--strict` はコメントに書かれた型／許可値をそのまま信頼して検証するため、コメントが誤記だと実行時には検出できません。CI では必ず `rubycli --check` を走らせ、`--strict` は「 lint を通過したドキュメントを本番で厳密に守る」用途に使ってください。
 
 ## Python Fire との違い
 
 - **コメント対応のヘルプ生成**: コメントがあればヘルプに反映しつつ、最終的な判断は常にライブなメソッド定義に基づきます。
 - **型に基づく解析**: `NAME [String]` や YARD タグから型を推論し、真偽値・配列・数値などを自動変換します。
-- **厳密な整合性チェック**: `rubycli --check` でコメントと実装のズレを実行前に検査し、通常実行時に `--strict` を付ければドキュメントで宣言した型・許可値以外の入力を拒否できます。
+- **厳密な整合性チェック**: `rubycli --check` でコメントと実装のズレ（未定義の型ラベルや列挙値の誤記など）をコード実行前に検査し、通常実行時に `--strict` を付ければドキュメントで宣言した型・許可値以外の入力を拒否できます。
 - **Ruby 向け拡張**: キーワード引数やブロック (`@yield*`) といった Ruby 固有の構文に合わせたパーサや `RUBYCLI_*` 環境変数を用意しています。
 
 | 機能 | Python Fire | Rubycli |
 | ---- | ----------- | -------- |
 | 属性の辿り方 | オブジェクトを辿ってプロパティ/属性を自動公開 | 対象オブジェクトの公開メソッドをそのまま公開（暗黙の辿りは無し） |
-| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` 指定時だけ引数なしで明示的に初期化（初期化引数の CLI 受け渡しは未対応なので、必要なら pre-script や自前ファクトリで注入） |
+| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` 指定時だけ初期化（コンストラクタ引数は `--new=VALUE` で渡せる。YAML/JSON らしいリテラルは安全にパース、`--json-args` / `--eval-args` / `--eval-lax` も適用可能。より複雑なら pre-script や自前ファクトリを利用） |
 | インタラクティブシェル | コマンド未指定時に Fire REPL を提供 | インタラクティブモード無し。コマンド実行専用 |
 | 情報源 | 反射で引数・プロパティを解析 | ライブなメソッド定義を基点にしつつコメントをヘルプへ反映 |
 | 辞書/配列 | dict/list を自動でサブコマンド化 | クラス/モジュールのメソッドに特化（辞書自動展開なし） |

data/README.md

@@ -163,13 +163,15 @@ 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. When your constructor needs arguments, pass them inline with `--new=VALUE` (safe YAML/JSON-like parsing by default; `--json-args` for strict JSON, `--eval-args` / `--eval-lax` for Ruby literals). Any comments on `initialize` are respected for type coercion just like regular CLI methods.
+
+> Hint: Single values should be passed as `--new=value` so they aren’t mistaken for the next path/command. Space-separated single tokens like `--new 1` may be treated as the following path unless they look obviously structured.
 
 ## 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
@@ -179,22 +181,39 @@ This keeps large projects safe by default but still provides a one-flag escape h
 - Safe literal parsing out of the box (arrays / hashes / booleans) with opt-in strict JSON and Ruby eval modes
 - 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
+- Example `examples/new_mode_runner.rb` demonstrates instance-only classes with `--new=VALUE` constructor arguments, eval/JSON modes, and a pre-script initialization pattern.
+
+### Examples
+
+- `examples/hello_app.rb` / `examples/hello_app_with_docs.rb`: minimal module-function variants, with and without docs
+- `examples/typed_arguments_demo.rb`: stdlib type coercions (Date/Time/BigDecimal/Pathname)
+- `examples/strict_choices_demo.rb`: literal enumerations and `--strict`
+- `examples/new_mode_runner.rb`: instance-only class initialized via `--new=VALUE` with eval/JSON/pre-script combinations
+
+> 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 |
 | ---------- | ----------- | -------- |
 | Attribute traversal | Recursively exposes attributes/properties on demand | Exposes public methods defined on the target; no implicit traversal |
-| Constructor handling | Automatically prompts for `__init__` args when instantiating classes | `--new` simply instantiates without passing CLI args (use pre-scripts or your own factories if you need injected dependencies) |
+| Constructor handling | Automatically prompts for `__init__` args when instantiating classes | `--new` instantiates and accepts constructor arguments via `--new=VALUE` (safe YAML/JSON-like parsing by default; `--json-args` for strict JSON, `--eval-args` / `--eval-lax` for Ruby literals). Use pre-scripts or your own factories for more complex wiring. |
 | Interactive shell | Offers Fire-specific REPL when invoked without command | No interactive shell mode; strictly command execution |
 | Input discovery | Pure reflection, no doc comments required | Doc comments drive option names, placeholders, and validation |
 | Data structures | Dictionaries / lists become subcommands by default | Focused on class or module methods; no automatic dict/list expansion |
 
+#### Example commands
+
+- `rubycli examples/new_mode_runner.rb run --new='["a","b","c"]' --mode reverse`
+- `rubycli --json-args --new='["x","y"]' examples/new_mode_runner.rb run --mode summary --options '{"source":"json"}'`
+- `rubycli --eval-args --new='["x","y"]' examples/new_mode_runner.rb run --mode summary --options '{tags: [:a, :b]}'`
+- `rubycli --pre-script 'NewModeRunner.new(%w[a b c], options: {from: :pre})' examples/new_mode_runner.rb run --mode summary`
+
 ## Installation
 
 Rubycli is published on RubyGems.

data/lib/rubycli/argument_parser.rb

@@ -59,6 +59,7 @@ module Rubycli
         end
       end
 
+      pos_args = convert_positional_arguments(pos_args, method, metadata)
       debug_log "Final parsed - pos_args: #{pos_args.inspect}, kw_args: #{kw_args.inspect}"
       [pos_args, kw_args]
     end
@@ -186,6 +187,60 @@ module Rubycli
       [key, value]
     end
 
+    def convert_positional_arguments(pos_args, method, metadata)
+      return pos_args unless method
+
+      positional_map = metadata[:positionals_map] || {}
+      return pos_args if positional_map.empty?
+
+      converted = pos_args.dup
+      method.parameters.each_with_index do |(type, name), index|
+        next unless %i[req opt].include?(type)
+        definition = positional_map[name]
+        next unless definition
+        next if index >= converted.size
+
+        converter = converter_for_definition(definition)
+        next unless converter
+
+        begin
+          converted[index] = converter.call(converted[index])
+        rescue StandardError => e
+          label = definition.label || definition.placeholder || name.to_s.upcase
+          raise ArgumentError, "Value '#{converted[index]}' for #{label} is invalid: #{e.message}"
+        end
+      end
+
+      converted
+    end
+
+    def converter_for_definition(definition)
+      types = Array(definition.types).compact
+      return nil if types.empty?
+
+      types.each do |type|
+        normalized = type.to_s.strip
+        next if normalized.empty?
+
+        if normalized.start_with?('Array<') && normalized.end_with?('>')
+          inner = normalized[6..-2].strip
+          element_converter = converter_for_single_type(inner)
+          return ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+        elsif normalized.end_with?('[]')
+          inner = normalized[0..-3]
+          element_converter = converter_for_single_type(inner)
+          return ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+        elsif normalized.casecmp('Array').zero?
+          return ->(value) { TypeUtils.parse_list(value) }
+        else
+          single = converter_for_single_type(normalized)
+          return single if single
+        end
+      end
+
+      nil
+    end
+
     def resolve_keyword_parameter(cli_key, kw_param_names)
       exact_match = kw_param_names.find { |name| name == cli_key }
       return exact_match if exact_match
@@ -528,7 +583,11 @@ module Rubycli
         require 'time'
         ->(value) { Time.parse(value) }
       when 'JSON', 'Hash'
-        ->(value) { JSON.parse(value) }
+        ->(value) {
+          return value if value.is_a?(Hash)
+
+          JSON.parse(value)
+        }
       when 'Pathname'
         require 'pathname'
         ->(value) {

data/lib/rubycli/command_line.rb

@@ -3,15 +3,16 @@
 module Rubycli
   module CommandLine
     USAGE = <<~USAGE
-      Usage: rubycli [--new|-n] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] [--strict] [--check|-c] <target-path> [<class-or-module>] [-- <cli-args>...]
+      Usage: rubycli [--new|-n[=<value>]] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] [--strict] [--check|-c] <target-path> [<class-or-module>] [-- <cli-args>...]
 
       Examples:
         rubycli scripts/sample_runner.rb echo --message hello
         rubycli scripts/sample_runner.rb AlternateRunner greet --name Ruby
         rubycli --new lib/akiya_fetcher.rb fetch_simplified_html https://example.com
+        rubycli --json-args --new='["a","b"]' examples/new_mode_runner.rb run --mode summary --options '{"source":"json"}'
 
       Options:
-        --new, -n            Instantiate the class/module before invoking CLI commands
+        --new, -n [<value>]  Instantiate the class/module before invoking CLI commands; optional constructor arguments can follow (array/hash recommended; respects --json-args/--eval-args/--eval-lax)
         --pre-script=<src>   Evaluate Ruby code and use its result as the exposed target (--init alias; also accepts space-separated form)
         --json-args, -j      Parse all following arguments strictly as JSON (no YAML literals)
         --eval-args, -e      Evaluate following arguments as Ruby code
@@ -40,6 +41,7 @@ module Rubycli
       end
 
       new_flag = false
+      new_args_expr = nil
       json_mode = false
       eval_mode = false
       eval_lax_mode = false
@@ -55,9 +57,23 @@ module Rubycli
         when '-h', '--help', 'help'
           $stdout.puts(USAGE)
           return 0
-        when '--new', '-n'
+        when /\A--new(?:=(.+))?\z/
           new_flag = true
+          new_args_expr = Regexp.last_match(1)
           args.shift
+          if new_args_expr.nil?
+            possible = args.first
+            if possible && !possible.start_with?('-') && likely_new_args_value?(possible)
+              new_args_expr = args.shift
+            end
+          end
+        when '-n'
+          new_flag = true
+          args.shift
+          possible = args.first
+          if possible && !possible.start_with?('-') && likely_new_args_value?(possible)
+            new_args_expr = args.shift
+          end
         when /\A--pre-script=(.+)\z/, /\A--init=(.+)\z/
           label = Regexp.last_match(0).start_with?('--pre-script') ? '--pre-script' : '--init'
           expr = Regexp.last_match(1)
@@ -141,6 +157,7 @@ module Rubycli
           target_path,
           class_or_module,
           new: new_flag,
+          new_args: new_args_expr,
           pre_scripts: pre_script_sources,
           constant_mode: constant_mode
         )
@@ -151,6 +168,7 @@ module Rubycli
         class_or_module,
         args,
         new: new_flag,
+        new_args: new_args_expr,
         json: json_mode,
         eval_args: eval_mode,
         eval_lax: eval_lax_mode,
@@ -166,5 +184,9 @@ module Rubycli
       warn "[ERROR] #{e.message}"
       1
     end
+
+    def likely_new_args_value?(token)
+      token.include?(',') || token.start_with?('[', '{')
+    end
   end
 end

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,99 @@ 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
+        return @type_dictionary if defined?(@type_dictionary) && @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
+
+        @type_dictionary = (builtins + constant_names).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+      end
+
+      def reset_type_dictionary_cache!
+        @type_dictionary = nil
+      end
+
 
       def placeholder_token?(token)
         return false unless token
@@ -786,8 +948,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 +975,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/documentation_registry.rb

@@ -34,6 +34,7 @@ module Rubycli
     def reset!
       @metadata_cache.clear
       @comment_extractor.reset!
+      @parser.reset_type_dictionary_cache! if @parser.respond_to?(:reset_type_dictionary_cache!)
     end
 
     private

data/lib/rubycli/version.rb

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

data/lib/rubycli.rb

@@ -209,6 +209,7 @@ module Rubycli
       class_name = nil,
       cli_args = nil,
       new: false,
+      new_args: nil,
       json: false,
       eval_args: false,
       eval_lax: false,
@@ -224,6 +225,10 @@ module Rubycli
         target_path,
         class_name,
         new: new,
+        new_args: new_args,
+        json_mode: json,
+        eval_mode: eval_args,
+        eval_lax: eval_lax,
         pre_scripts: pre_scripts,
         constant_mode: constant_mode
       )
@@ -243,8 +248,12 @@ module Rubycli
       target_path,
       class_name = nil,
       new: false,
+      new_args: nil,
       pre_scripts: [],
-      constant_mode: nil
+      constant_mode: nil,
+      json_mode: false,
+      eval_mode: false,
+      eval_lax: false
     )
       raise ArgumentError, 'target_path must be specified' if target_path.nil? || target_path.empty?
       previous_doc_check = Rubycli.environment.doc_check_mode?
@@ -255,6 +264,10 @@ module Rubycli
         target_path,
         class_name,
         new: new,
+        new_args: new_args,
+        json_mode: json_mode,
+        eval_mode: eval_mode,
+        eval_lax: eval_lax,
         pre_scripts: pre_scripts,
         constant_mode: constant_mode
       )
@@ -348,10 +361,18 @@ module Rubycli
       raise Error.new(message), cause: nil
     end
 
-    def instantiate_target(target)
+    def instantiate_target(target, initializer_args = nil)
+      positional_args, keyword_args = Array(initializer_args || [[], {}])
+      positional_args ||= []
+      keyword_args ||= {}
+
       case target
       when Class
-        target.new
+        if keyword_args.empty?
+          target.new(*positional_args)
+        else
+          target.new(*positional_args, **keyword_args)
+        end
       when Module
         Object.new.extend(target)
       else
@@ -373,10 +394,43 @@ module Rubycli
       end
     end
 
+    def parse_initializer_arguments(raw_value, target, json_mode:, eval_mode:, eval_lax:)
+      return [[], {}] if raw_value.nil?
+      raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if json_mode && eval_mode
+
+      initializer_method = initializer_method_for(target)
+      tokens = Array(raw_value)
+
+      positional_args = []
+      keyword_args = {}
+
+      Rubycli.argument_mode_controller.with_json_mode(json_mode) do
+        Rubycli.argument_mode_controller.with_eval_mode(eval_mode, lax: eval_lax) do
+          positional_args, keyword_args = Rubycli.argument_parser.parse(tokens.dup, initializer_method)
+          Rubycli.apply_argument_coercions(positional_args, keyword_args)
+          Rubycli.argument_parser.validate_inputs(initializer_method, positional_args, keyword_args)
+        end
+      end
+
+      [positional_args || [], keyword_args || {}]
+    rescue Rubycli::ArgumentError => e
+      raise Runner::Error, "Failed to parse --new arguments: #{e.message}"
+    end
+
+    def initializer_method_for(target)
+      return nil unless target.is_a?(Class)
+
+      target.instance_method(:initialize) rescue nil
+    end
+
     def prepare_runner_target(
       target_path,
       class_name,
       new: false,
+      new_args: nil,
+      json_mode: false,
+      eval_mode: false,
+      eval_lax: false,
       pre_scripts: [],
       constant_mode: nil
     )
@@ -403,7 +457,9 @@ module Rubycli
                  )
                end
 
-      runner_target = new ? instantiate_target(target) : target
+      initializer_args = new ? parse_initializer_arguments(new_args, target, json_mode: json_mode, eval_mode: eval_mode, eval_lax: eval_lax) : nil
+
+      runner_target = new ? instantiate_target(target, initializer_args) : target
       runner_target = apply_pre_scripts(pre_scripts, target, runner_target)
       [runner_target, full_path]
     end
@@ -531,19 +587,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}"
+        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.7
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-09 00:00:00.000000000 Z
+date: 2025-11-16 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