rubycli 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 521eac399843d8fe002c1017b24b0cf72644f179460d3a599a1b9bf9d0949d7e
-  data.tar.gz: d245d65f31c08f15c0f9bad5d4e13e3d7cb1785936772ab6a83887cd4fdf4564
+  metadata.gz: '07113181085c0df0c8f4bc34aca661d4c29fb9bbc309012ace52b36e8bdf9ead'
+  data.tar.gz: 773d7de6a820fd1702e4e618c595237e2293c74dca6cc83f3ea57ba9eaaa18db
 SHA512:
-  metadata.gz: 286af4633230ddd40c39e40c2ec92f810bd47cc533c1d578dc42178179552518bfc057f992beef340cc4a34592c603d0ddc6d10eef1df928ce83be383cd9857c
-  data.tar.gz: 82e587aac72882cb1b3e317d20d2dc37c54ed8e927fc39ffa9d28dd871d77b05c6d2fc64ad13dc5e3fe7c903b6f5312dfa0b34e9e46391e66788435286c909e9
+  metadata.gz: dadd19c4c2081e6fd7f8d6e40750c3cbc727a2c7f0452a5eb81b6feb80ce878e50fac111589ea87415d7656db4d288591bf7352fd4ee80031998e5835e84e732
+  data.tar.gz: 0aef161e5d6fd30fb475de5afc908ecc94f1b5d4d1c96c0d735399c90b615e865e91286fa100008804d846d22e37874528b192dcbcea74b52484e45ef56273b6

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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

data/README.ja.md

@@ -156,7 +156,9 @@ Rubycli は「ファイル名を CamelCase にした定数」を公開対象だ
 
 大規模なコードベースでも安全側を保ちながら、どうしても自動選択したいときだけ 1 フラグで切り替えられます。
 
-> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。`--new` を付ければ `rubycli --help` でもインスタンスメソッドが一覧に現れ、`rubycli --check --new` でコメントの lint も実行できます。
+> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`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` のように `=` 付きで指定するのが確実です。
 
 ## 開発方針
 
@@ -172,6 +174,21 @@ 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 を通過したドキュメントを本番で厳密に守る」用途に使ってください。
 
@@ -185,7 +202,7 @@ Rubycli は「ファイル名を CamelCase にした定数」を公開対象だ
 | 機能 | 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,7 +163,9 @@ 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`. Passing `--new` also makes those instance methods appear in `rubycli --help` output and allows `rubycli --check --new` to lint their documentation.
+> **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
 
@@ -179,6 +181,14 @@ 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`.
 
@@ -192,11 +202,18 @@ This keeps large projects safe by default but still provides a one-flag escape h
 | 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

@@ -873,6 +873,8 @@ module Rubycli
       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
@@ -888,7 +890,11 @@ module Rubycli
           constant_names = Object.constants.map(&:to_s)
         end
 
-        (builtins + constant_names).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+        @type_dictionary = (builtins + constant_names).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+      end
+
+      def reset_type_dictionary_cache!
+        @type_dictionary = nil
       end
 
 

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.6'
+  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
@@ -536,7 +592,7 @@ module Rubycli
 
       if defined_constants && !defined_constants.empty?
         sample = defined_constants.first(5)
-        suffix = defined_constants.size > sample.size ? " … (#{defined_constants.size} total)" : ''
+        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.'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubycli
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-11 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