rubycli 0.1.2 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14562bc06b2479369c2951a54cac6f8f502e5ff81ae453b25bdb225b2017f671
-  data.tar.gz: 731a6704bac4ca7d9471b4ff00d7476745e81c442666e99ca3b710d70c9e4622
+  metadata.gz: 9287ea2ca51772eb53c50fe717e648c7d23a9fb1e5cb0e25990eef7f07cde225
+  data.tar.gz: aab6e71f2beafb924bb4bc29689c6ce64391d55bc43936a789278ad764e91592
 SHA512:
-  metadata.gz: 2ef973534a268ac8475f21f9d26ef16202ab5f4a89a69c3ea94a0700f1d89a5b17e533d5e821f8c6833855c91f72a5d5d6fcbfb75716c9a3648bf52e9c26600b
-  data.tar.gz: c2cc78a8dbc2ec9185c6fcb598ea5be2160ea336021932e2ab7ffb58b5b2be5f8fad078ed379a26a33c66241ed69a17c1edd9bd852663299747a630edd9da235
+  metadata.gz: 98baa8a62366c9babedda68174dbc1fadaafbdf1ea4354393bf1a525b9b1d1f2ce0459f20ef8aff81cc4a3448f0686da9bf7940a8fde2526a3b42caf3d2feb63
+  data.tar.gz: ac5044eec17148e3bb26ef1aa2fd67b78e6578acd6693747bb9a95e8d043e1842f9ebc853e6e50297130d0351fdfb9cfad04c1d217738c6462eda94c1c5b039f

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.1.5] - 2025-11-10
+
+### Added
+- `rubycli --check` gained a short `-c` alias and refuses to run target commands while linting, making documentation checks easier to script.
+- Bundled `examples/strict_choices_demo.rb` and `examples/typed_arguments_demo.rb` now illustrate literal choice validation and stdlib type coercions.
+
+### Changed
+- Runtime validation now reads the documented literal choices and inferred types for both positional and keyword arguments; invalid values emit `[WARN] …` guidance by default and raise `Rubycli::ArgumentError` under `--strict` with friendly suggestions.
+- Help output renders positional arguments and options as structured tables showing requirement level, types, defaults, and descriptions for quicker scanning.
+- Documentation comments are aligned with the actual method signature, and mismatches surface with file/line context during `rubycli --check`.
+- CLI warnings/errors are prefixed with `[WARN]` / `[ERROR]`, and the deprecated `--debug` flag was removed in favor of `RUBYCLI_DEBUG=true`.
+
+### Fixed
+- `--check` now rejects forwarded CLI arguments as well as JSON/Eval modes, ensuring documentation linting never executes user code and always starts from a clean issue list.
+- Placeholder parsing keeps option descriptions such as `--prefix` in the documentation showcase so README snippets and live behavior stay in sync.
+
+## [0.1.4] - 2025-11-08
+
+### Changed
+- Re-cut the release that was briefly published as 0.1.3 (and yanked) so RubyGems now hosts the complete set of changes listed below.
+
+> _Note:_ 0.1.3 was yanked before general availability; consumers should upgrade directly to 0.1.4.
+
+### Documentation
+- Clarified repeated-value guidance (type enforcement, eval mode workflows) and updated both READMEs to reflect the retirement of `(type: …)` annotations while preserving the historical changelog entry.
+
+## [0.1.3] - 2025-11-08
+
+### Added
+- TracePoint-backed constant capture so Rubycli can detect CLI classes/modules even when they are defined indirectly; bundled example and tests illustrate the behavior.
+- Strict/auto constant selection modes with the new `--auto-target` / `-a` flag so single callable constants are picked automatically when requested.
+- `--eval-lax` / `-E` argument mode that evaluates Ruby inputs but gracefully falls back to raw strings on parse failures.
+
+### Changed
+- Argument parsing internals were modularized so JSON/eval coercion now flows through a dedicated controller, simplifying future extensions.
+- `rubycli` now returns explicit status codes for success and failure, improving scriptability.
+- CLI constant selection errors provide clearer guidance, document the `--new` behavior, and consistently refer to the `--auto-target` flag.
+
+### Documentation
+- Clarified the authoritative source for documentation comments, reorganized helper logic in the showcase example, and expanded guidance around constant modes.
+
+### Fixed
+- CLI no longer dumps a Ruby backtrace when `Rubycli::Runner` reports user-facing errors; only the curated guidance is shown.
+
 ## [0.1.2] - 2025-11-06
 
 ### Added

data/README.ja.md

@@ -2,7 +2,7 @@
 
 ![Rubycli ロゴ](assets/rubycli-logo.png)
 
-Rubycli は Ruby のクラス／モジュールに書いたコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しています。
+Rubycli は Ruby のクラス／モジュールにある公開メソッドの定義と、そのメソッドに付けたドキュメントコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しており、コメントに書いた型ヒントや繰り返し指定が CLI の引数解釈もコントロールします。
 
 > English guide is available in [README.md](README.md).
 
@@ -33,7 +33,6 @@ Available commands:
     greet                <NAME>
 
 Detailed command help: hello_app.rb COMMAND help
-Enable debug logging: --debug or RUBYCLI_DEBUG=true
 ```
 
 ```bash
@@ -107,7 +106,6 @@ Available commands:
     greet                <NAME> [--shout]
 
 Detailed command help: hello_app_with_docs.rb COMMAND help
-Enable debug logging: --debug or RUBYCLI_DEBUG=true
 ```
 
 ```bash
@@ -147,11 +145,24 @@ end
 
 `ruby hello_app.rb ...` の形で呼び出したい場合だけ `require "rubycli"` を追加し、`Rubycli.run` に制御を渡します（後述のクイックスタート参照）。
 
+## 定数解決モード
+
+Rubycli は「ファイル名を CamelCase にした定数」を公開対象だと想定しています。ファイル名とクラス／モジュール名が一致しない場合は、次のモードで挙動を切り替えられます。
+
+| モード | 有効化方法 | 挙動 |
+| --- | --- | --- |
+| `strict`（デフォルト） | 何もしない / `RUBYCLI_AUTO_TARGET=strict` | CamelCase が一致しないとエラーになります。検出した定数一覧と再実行コマンド例を表示します。 |
+| `auto` | `--auto-target`（短縮 `-a`） または `RUBYCLI_AUTO_TARGET=auto` | ファイル内で CLI として実行できる定数が 1 つだけなら自動選択します。複数あれば従来通りエラーで案内します。 |
+
+大規模なコードベースでも安全側を保ちながら、どうしても自動選択したいときだけ 1 フラグで切り替えられます。
+
+> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。
+
 ## 開発方針
 
 - **便利さが最優先** – 既存の Ruby スクリプトを最小の手間で CLI 化できることを目的にしており、Python Fire の完全移植は目指していません。
 - **インスパイアであってポートではない** – アイデアの出自は Fire ですが、同等機能を揃える予定は基本的にありません。Fire 由来の未実装機能は仕様です。
-- **コードが一次情報、コメントは補助** – メソッド定義こそが真実であり、コメントはヘルプを豊かにする付加情報です。コメントと実装のズレを観測したいときだけ `RUBYCLI_STRICT=ON` で厳格モードを有効化し、警告を受け取ります。
+- **メソッド定義が土台、コメントが挙動を補強** – 公開メソッドのシグネチャが CLI に露出する範囲と必須／任意を決めますが、コメントに `TAG...` や `[Integer]` を書くと同じ引数でも配列化や型変換が行われます。さらに Rubycli は `--names='["Alice","Bob"]'` のような JSON/YAML らしい入力を自動的に安全なリテラルとして評価します。`rubycli --check パス/対象.rb` でコメントと実装のズレを検査しつつ、通常実行時に `--strict` を付ければドキュメント通りでない入力をその場でエラーにできます。（現状の `--check` は「コメントが揃っているか」を中心にチェックしており、`Booalean` のように型トークンを誤記しても検出できません。）
 - **軽量メンテナンス** – 実装の多くは AI 支援で作られており、深い Ruby メタプログラミングを伴う大規模拡張は想定外です。Fire 互換を求める PR は事前相談をお願いします。
 
 ## 特徴
@@ -160,19 +171,19 @@ end
 - YARD 形式と `NAME [Type] 説明…` の簡潔記法を同時サポート
 - 引数はデフォルトで安全なリテラルとして解釈し、必要に応じて厳格 JSON モードや Ruby eval モードを切り替え可能
 - `--pre-script`（エイリアス: `--init`）で任意の Ruby コードを評価し、その結果オブジェクトを公開
-- `RUBYCLI_STRICT=ON` で有効化できる厳格モードにより、コメントとシグネチャの矛盾を警告として検知可能
+- `--check` でコメント整合性を lint、`--strict` で入力値をドキュメント通りに強制する二段構えのガード
 
 ## Python Fire との違い
 
 - **コメント対応のヘルプ生成**: コメントがあればヘルプに反映しつつ、最終的な判断は常にライブなメソッド定義に基づきます。
 - **型に基づく解析**: `NAME [String]` や YARD タグから型を推論し、真偽値・配列・数値などを自動変換します。
-- **厳密な整合性チェック**: 厳格モードを有効にすれば、コメントとメソッド定義が食い違う際に警告を出して保守性を高められます。
+- **厳密な整合性チェック**: `rubycli --check` でコメントと実装のズレを実行前に検査し、通常実行時に `--strict` を付ければドキュメントで宣言した型・許可値以外の入力を拒否できます。
 - **Ruby 向け拡張**: キーワード引数やブロック (`@yield*`) といった Ruby 固有の構文に合わせたパーサや `RUBYCLI_*` 環境変数を用意しています。
 
 | 機能 | Python Fire | Rubycli |
 | ---- | ----------- | -------- |
 | 属性の辿り方 | オブジェクトを辿ってプロパティ/属性を自動公開 | 対象オブジェクトの公開メソッドをそのまま公開（暗黙の辿りは無し） |
-| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` を指定した明示的な初期化のみ。引数はコメントで宣言 |
+| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` 指定時だけ引数なしで明示的に初期化（初期化引数の CLI 受け渡しは未対応なので、必要なら pre-script や自前ファクトリで注入） |
 | インタラクティブシェル | コマンド未指定時に Fire REPL を提供 | インタラクティブモード無し。コマンド実行専用 |
 | 情報源 | 反射で引数・プロパティを解析 | ライブなメソッド定義を基点にしつつコメントをヘルプへ反映 |
 | 辞書/配列 | dict/list を自動でサブコマンド化 | クラス/モジュールのメソッドに特化（辞書自動展開なし） |
@@ -271,15 +282,62 @@ README のサンプルは既定スタイルとして大文字プレースホル
 
 > 補足: コメント内で任意引数を角括弧で表す必要はありません。Ruby 側のメソッドシグネチャから必須／任意は自動判定され、ヘルプ出力では Rubycli が適切に角括弧を追加します。
 
-型ヒントは `[String]`, `(String)`, `(type: String)` のように角括弧・丸括弧・`type:` プレフィックスのいずれでも指定できます。複数型は `(String, nil)` や `(type: String, nil)` のように列挙してください。
+型ヒントは `[String]` や `(String)` のように角括弧／丸括弧で指定できます。複数型は `(String, nil)` のように列挙してください。
+
+`VALUE...` のような繰り返し指定（`TAG...` など）や、`[String[]]` / `Array<String>` といった配列型の注釈が付いたオプションは配列として扱われます。JSON/YAML 形式のリスト（例: `--tags '["build","test"]'`）を渡すか、カンマ区切り文字列（`--tags "build,test"`）を渡すことで配列に変換されます。スペース区切りの複数値入力（`--tags build test`）にはまだ対応しておらず、繰り返し注記のないオプションは従来どおりスカラーとして扱われます。`--strict` 実行時は各要素の型も検証されるため、`[String[]]` と書かれているのに `--tags [1,2]` のような数値配列を渡すと即エラーになります。
 
-`VALUE...` のような繰り返し指定（`TAG...` など）や、`[String[]]` / `Array<String>` といった配列型の注釈が付いたオプションは配列として扱われます。JSON/YAML 形式のリスト（例: `--tags '["build","test"]'`）を渡すか、カンマ区切り文字列（`--tags "build,test"`）を渡すことで配列に変換されます。スペース区切りの複数値入力（`--tags build test`）にはまだ対応しておらず、繰り返し注記のないオプションは従来どおりスカラーとして扱われます。
+JSON やカンマ区切りで表現しづらいシンボル配列・ハッシュなどを渡したい場合は eval モード（`--eval-args`/`-e` または `--eval-lax`/`-E`）を有効にし、ドキュメントで宣言した型に合わせた Ruby リテラルを渡してください。スペース区切りが未対応でも、安全に複数選択を指定できます（後述の eval 例を参照）。
 
 代表的な推論例:
 
 - `ARG1` のように型ラベルを省略したプレースホルダは既定で `String` として扱われます。
 - `--name ARG1` のようにオプションへプレースホルダだけを指定しても同じく `String` が推論されます。
 - `--verbose` のように値プレースホルダを省略したオプションは Boolean フラグとして扱われます。
+- 位置引数を Boolean にしたい場合は必ず `[Boolean]` を明示してください。`NAME 説明` や `@param name 説明` のように型を省略すると、Ruby 側のデフォルト値に関わらず `String` とみなされます。
+
+### リテラル列挙による制約
+
+`--format MODE [:json, :yaml, :auto]` や `LEVEL [:info, :warn]` のように型注釈内へ許容リテラルを列挙すると、ヘルプに選択肢を表示しつつ Rubycli が入力制約として解釈します。シンボル・文字列（裸の単語も可）・真偽値・数値・`nil` に対応し、型ヒントと混在させて `--channel TARGET [:stdout, :stderr, Boolean]` のような宣言も書けます。`%i[info warn]` / `%w[debug info]` などの短縮記法も展開されるため、`LEVEL %i[info warn]` でも同じ効果になります。通常実行では許可外の入力に警告を表示して続行し、`--strict` を付けた場合は `Rubycli::ArgumentError` を送出して即座に停止します。
+
+> シンボルと文字列は厳密に区別されます。`[:info, :warn]` と書いた場合は `:info` のようにコロン付きで入力してください。`["info", "warn"]` を選んだ場合はプレーンな文字列のみ受け付けます。
+
+> 列挙は各スカラー値に適用されます。`[Symbol[]]` のような配列注釈に対して「許可される組み合わせ」をリテラルで書く構文（例: `[%i[foo bar][]]`）は未サポートなので、必要に応じて文章で説明するか、eval モードで Ruby の配列を渡してください。
+
+```bash
+# literal choice デモ (examples/strict_choices_demo.rb)
+ruby examples/strict_choices_demo.rb report warn --format json
+#=> [WARN] format=json
+
+# --strict を付けると仕様外の値で即エラー
+ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report debug
+#=> Rubycli::ArgumentError: Value "debug" for LEVEL is not allowed: allowed values are :info, :warn, :error
+```
+
+```bash
+# シンボル入力はコロンを付ける
+ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report :warn
+#=> [WARN] format=text
+
+ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report warn
+#=> Rubycli::ArgumentError: Value "warn" for LEVEL is not allowed: allowed values are :info, :warn, :error
+```
+
+### 標準ライブラリ型ヒント
+
+コメントに `Date` や `Time`, `BigDecimal`, `Pathname` など標準ライブラリの型名を書けば、Rubycli が必要な `require` を行った上で CLI 引数をその型へ変換します。
+
+```bash
+# examples/typed_arguments_demo.rb より
+ruby examples/typed_arguments_demo.rb ingest \
+  --date 2024-12-25 \
+  --moment 2024-12-25T10:00:00Z \
+  --budget 123.45 \
+  --input ./data/input.csv
+```
+
+ハンドラ側には `Date` / `Time` / `BigDecimal` / `Pathname` のインスタンスがそのまま渡るため、追加のパース処理は不要です。
+
+各オプションには既定値があるため、`ruby examples/typed_arguments_demo.rb ingest --budget 999.99` のように個別の型だけ試すこともできます。
 
 `@example` や `@raise`, `@see`, `@deprecated` などその他の YARD タグは、現状ヘルプ出力には反映されません。
 
@@ -318,7 +376,6 @@ Available commands:
     scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
 
 Detailed command help: fallback_example.rb COMMAND help
-Enable debug logging: --debug or RUBYCLI_DEBUG=true
 ```
 
 ```bash
@@ -337,7 +394,7 @@ Options:
   --notify         [Boolean]  optional  (default: false)
 ```
 
-`AMOUNT` だけがドキュメント化されていますが、`factor` や `clamp`, `notify` も自動的に補完され、既定値や型が推論されていることがわかります。コメントとシグネチャの矛盾を早期に検知したい場合は `RUBYCLI_STRICT=ON` で厳格モードを有効化してください。
+`AMOUNT` だけがドキュメント化されていますが、`factor` や `clamp`, `notify` も自動的に補完され、既定値や型が推論されていることがわかります。開発時は `rubycli --check 対象.rb` でコメントとシグネチャの矛盾を検出し、本番実行で `--strict` を付ければ仕様外の入力をその場で弾けます。
 
 #### 存在しない引数やオプションをコメントに書いた場合
 
@@ -374,7 +431,17 @@ YAML 固有の書き方は拒否され、無効な JSON であれば `JSON::Pars
 
 `--eval-args`（短縮形 `-e`）を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON や YAML では表現しづらいオブジェクトを扱いたいときに便利ですが、評価は `Object.new.instance_eval { binding }` 上で行われるため、信頼できる入力に限定してください。コード内では `Rubycli.with_eval_mode(true) { … }` で切り替えられます。
 
-`--eval-args`/`-e` と `--json-args`/`-j` は同時指定できません。どちらのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval のどちらかを選択してください。
+Ruby 評価はシンボルや配列／ハッシュもそのまま扱えるため、列挙値の組み合わせをオプションへ渡すときにも役立ちます。
+
+```bash
+rubycli -E scripts/report_runner.rb publish \
+  --targets '[:marketing, :sales]' \
+  --channels '[:email, :slack]'
+```
+
+Ruby 評価を使いつつ、構文エラーが出たときは元の文字列にフォールバックさせたい場合は `--eval-lax`（短縮形 `-E`）を指定します。`--eval-args` と同じく eval モードを有効にしますが、Ruby として解釈できなかったトークン（例: 素の `https://example.com`）は警告を出した上でそのまま渡すため、`60*60*24*14` のような式と文字列を気軽に混在させられます。
+
+`--json-args`/`-j` は `--eval-args`/`-e` および `--eval-lax`/`-E` と同時指定できません。どのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval（通常／lax）のいずれかを選択してください。
 
 ## Pre-script ブートストラップ
 
@@ -412,8 +479,9 @@ rubycli --pre-script scripts/bootstrap_runner.rb \
 
 | 変数 / フラグ | 説明 | 既定値 |
 | ------------- | ---- | ------ |
-| `--debug` / `RUBYCLI_DEBUG=true` | デバッグログ表示 | `false` |
-| `RUBYCLI_STRICT=ON` | 厳格モードを有効化（コメントとシグネチャの矛盾を警告） | `OFF` |
+| `RUBYCLI_DEBUG=true` | デバッグログ表示 | `false` |
+| `--check` | コメント／実装のズレを検査し、コマンドは実行しない | `off` |
+| `--strict` | ドキュメントで許可した型・値以外をエラーとして拒否 | `off` |
 | `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` | レガシーな `@param` 記法を無効化（互換性のため既定では ON） | `ON` |
 
 ## Rubycli API

data/README.md

@@ -2,7 +2,7 @@
 
 ![Rubycli logo](assets/rubycli-logo.png)
 
-Rubycli turns existing Ruby classes and modules into CLIs by reading their documentation comments. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations.
+Rubycli turns existing Ruby classes and modules into CLIs by inspecting their public method definitions and the doc comments attached to those methods. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations, and those annotations can actively change how a CLI argument is coerced (for example, `TAG... [String[]]` forces array parsing).
 
 > 🇯🇵 Japanese documentation is available in [README.ja.md](README.ja.md).
 
@@ -35,7 +35,6 @@ Available commands:
     greet                <NAME>
 
 Detailed command help: hello_app.rb COMMAND help
-Enable debug logging: --debug or RUBYCLI_DEBUG=true
 ```
 
 ```bash
@@ -109,7 +108,6 @@ Available commands:
     greet                <NAME> [--shout]
 
 Detailed command help: hello_app_with_docs.rb COMMAND help
-Enable debug logging: --debug or RUBYCLI_DEBUG=true
 ```
 
 ```bash
@@ -154,11 +152,24 @@ ruby examples/hello_app_with_require.rb greet Hanako --shout
 #=> HELLO, HANAKO!
 ```
 
+## Constant resolution modes
+
+Rubycli assumes that the file name (CamelCased) matches the class or module you want to expose. When that is not the case you can choose how eagerly Rubycli should pick a constant:
+
+| Mode | How to enable | Behaviour |
+| --- | --- | --- |
+| `strict` (default) | do nothing / `RUBYCLI_AUTO_TARGET=strict` | Fails unless the CamelCase name matches. The error lists the detected constants and gives explicit rerun instructions. |
+| `auto` | `--auto-target`, `-a`, or `RUBYCLI_AUTO_TARGET=auto` | If exactly one constant in that file defines CLI-callable methods, Rubycli auto-selects it; otherwise you still get the friendly error message. |
+
+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`.
+
 ## 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.”
-- **Comments enrich, code decides** – Method signatures remain the source of truth; optional documentation comments add richer help output and can surface warnings when you opt into strict mode (`RUBYCLI_STRICT=ON`).
+- **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.)
 - **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
@@ -167,19 +178,19 @@ ruby examples/hello_app_with_require.rb greet Hanako --shout
 - Automatic option signature inference (`NAME [Type] Description…`) without extra DSLs
 - 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
-- Opt-in strict mode (`RUBYCLI_STRICT=ON`) that emits warnings whenever comments contradict method signatures
+- Dedicated CLI flags for quality gates: `--check` lints documentation/comments without running commands, and `--strict` treats documented types/choices as hard requirements
 
 ## 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** – Opt-in strict mode surfaces warnings when comments fall out of sync with method signatures, helping teams keep help text accurate.
+- **Strict validation** – `rubycli --check` lint runs catch documentation drift before execution, while runtime `--strict` runs turn 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 | Requires explicit `--new` plus comment docs; no automatic prompting |
+| 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) |
 | 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 |
@@ -280,15 +291,62 @@ The CLI treats `--flag VALUE`, `--flag <value>`, and `--flag=<value>` identicall
 
 > Tip: You do not need to wrap optional arguments in brackets inside the comment. Rubycli already knows which parameters are optional from the Ruby signature and will introduce the brackets in generated help.
 
-You can annotate types using `[String]`, `(String)`, or `(type: String)`—they all convey the same hint, and you can list multiple types such as `(String, nil)` or `(type: String, nil)`.
+You can annotate types using `[String]` or `(String)`—they both convey the same hint, and you can list multiple types such as `(String, nil)`.
+
+Repeated values (`VALUE...`) now materialize as arrays automatically whenever the option is documented with an ellipsis (for example `TAG...`) or an explicit array type hint (`[String[]]`, `Array<String>`). Supply either JSON/YAML list syntax (`--tags "[\"build\",\"test\"]"`) or a comma-delimited string (`--tags "build,test"`); Rubycli will coerce both forms to arrays. Space-separated multi-value flags (`--tags build test`) are still not supported, and options without a repeated/array hint continue to be parsed as scalars. Strict mode still verifies each element against the documented type, so `--tags [1,2]` will fail when the docs say `[String[]]`.
 
-Repeated values (`VALUE...`) now materialize as arrays automatically whenever the option is documented with an ellipsis (for example `TAG...`) or an explicit array type hint (`[String[]]`, `Array<String>`). Supply either JSON/YAML list syntax (`--tags "[\"build\",\"test\"]"`) or a comma-delimited string (`--tags "build,test"`); Rubycli will coerce both forms to arrays. Space-separated multi-value flags (`--tags build test`) are still not supported, and options without a repeated/array hint continue to be parsed as scalars.
+Need to pass structures that are awkward to express as JSON (for example symbol arrays or hashes)? Enable eval mode (`--eval-args`/`-e` or `--eval-lax`/`-E`) and supply a Ruby literal that matches the documented type; the example in the eval section below shows how to pass multiple enum selections safely even though space-separated syntax remains unsupported.
 
 Common inference rules:
 
 - Writing a placeholder such as `ARG1` (without `[String]`) makes Rubycli treat it as a `String`.
 - Using that placeholder in an option line (`--name ARG1`) also infers a `String`.
 - Omitting the placeholder entirely (`--verbose`) produces a Boolean flag.
+- Positional arguments only become booleans when you annotate `[Boolean]`; a bare `NAME Description` (or `@param name Description`) falls back to `String`, regardless of the Ruby default value.
+
+### Literal choices and enums
+
+You can express a finite set of accepted values directly inside the type annotation, for example `--format MODE [:json, :yaml, :auto]` or `LEVEL [:info, :warn]`. Symbols, strings (including barewords), booleans, numbers, and `nil` are supported, and you can mix literal entries with broader types such as `--channel TARGET [:stdout, :stderr, Boolean]`. `%i[info warn]` / `%w[debug info]` short-hands expand as expected, so `LEVEL %i[info warn]` works the same as the explicit array form. Rubycli always records these choices in the generated help; when you run with `--strict`, any value outside the documented set results in `Rubycli::ArgumentError`, otherwise a warning is printed and execution proceeds.
+
+> Symbols and strings are compared strictly. `[:info, :warn]` requires symbol inputs such as `:info`, while `["info", "warn"]` only accepts plain strings. Prefix a value with `:` at the CLI to pass a symbol.
+
+> Literal enums currently apply to each scalar argument. If an option is documented as an array (for example `[Symbol[]]`), spell out the allowed members in prose for now—combined literal arrays such as `[%i[foo bar][]]` are not supported.
+
+```bash
+# literal choices + booleans (see examples/strict_choices_demo.rb)
+ruby examples/strict_choices_demo.rb report warn --format json
+#=> [WARN] format=json
+
+# the same command with --strict will abort when values drift
+ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report debug
+#=> Rubycli::ArgumentError: Value "debug" for LEVEL is not allowed: allowed values are :info, :warn, :error
+```
+
+```bash
+# symbol values stay distinct
+ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report :warn
+#=> [WARN] format=text
+
+ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report warn
+#=> Rubycli::ArgumentError: Value "warn" for LEVEL is not allowed: allowed values are :info, :warn, :error
+```
+
+### Standard library type hints
+
+Doc comments can reference standard classes such as `Date`, `Time`, `BigDecimal`, or `Pathname`. Rubycli loads the necessary stdlib files on demand and coerces CLI inputs using the documented types.
+
+```bash
+# see examples/typed_arguments_demo.rb
+ruby examples/typed_arguments_demo.rb ingest \
+  --date 2024-12-25 \
+  --moment 2024-12-25T10:00:00Z \
+  --budget 123.45 \
+  --input ./data/input.csv
+```
+
+This command prints a normalized summary and the handler receives real `Date`, `Time`, `BigDecimal`, and `Pathname` objects without manual parsing.
+
+Each option has a sensible default, so you can also experiment one at a time (for example `ruby examples/typed_arguments_demo.rb ingest --budget 999.99`).
 
 Other YARD tags such as `@example`, `@raise`, `@see`, and `@deprecated` are currently ignored by the CLI renderer.
 
@@ -327,7 +385,6 @@ Available commands:
     scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
 
 Detailed command help: fallback_example.rb COMMAND help
-Enable debug logging: --debug or RUBYCLI_DEBUG=true
 ```
 
 ```bash
@@ -346,7 +403,7 @@ Options:
   --notify         [Boolean]  optional  (default: false)
 ```
 
-Here only `AMOUNT` is documented, yet `factor`, `clamp`, and `notify` are still presented with sensible defaults and inferred types. Enable strict mode (`RUBYCLI_STRICT=ON`) if you want mismatches between comments and signatures to surface as warnings during development.
+Here only `AMOUNT` is documented, yet `factor`, `clamp`, and `notify` are still presented with sensible defaults and inferred types. Run `rubycli --check path/to/script.rb` during development to surface mismatches between comments and signatures, and pass `--strict` when executing commands to enforce the documented types/choices.
 
 #### What if the docs mention arguments that do not exist?
 
@@ -382,7 +439,17 @@ rubycli -e scripts/data_cli.rb DataCLI run '(1..10).to_a'
 
 Under the hood Rubycli evaluates each argument inside an isolated binding (`Object.new.instance_eval { binding }`). Treat this as unsafe input: do not enable it for untrusted callers. The mode can also be toggled programmatically via `Rubycli.with_eval_mode(true) { … }`.
 
-`--eval-args`/`-e` and `--json-args`/`-j` are mutually exclusive; Rubycli will raise an error if both are present. Both modes augment the default literal parsing, so you can pick either strict JSON or full Ruby evaluation when the defaults are not enough.
+Because Ruby evaluation understands symbols, arrays, and hashes, it’s a convenient way to pass literal enum combinations to options that expect arrays:
+
+```bash
+rubycli -E scripts/report_runner.rb publish \
+  --targets '[:marketing, :sales]' \
+  --channels '[:email, :slack]'
+```
+
+Need Ruby evaluation plus a safety net? Pass `--eval-lax` (or `-E`). It flips on eval mode just like `--eval-args`, but if Ruby fails to parse a token (for example, a bare `https://example.com`), Rubycli emits a warning and forwards the original string unchanged. This lets you mix inline math (`60*60*24*14`) with literal values without constantly juggling quotes.
+
+`--json-args`/`-j` cannot be combined with either `--eval-args`/`-e` or `--eval-lax`/`-E`; Rubycli will raise an error if both are present. Both modes augment the default literal parsing, so you can pick either strict JSON or one of the Ruby eval variants when the defaults are not enough.
 
 ## Pre-script bootstrap
 
@@ -420,8 +487,9 @@ This keeps `--new` available for quick zero-argument instantiation while allowin
 
 | Flag / Env | Description | Default |
 | ---------- | ----------- | ------- |
-| `--debug` / `RUBYCLI_DEBUG=true` | Print debug logs | `false` |
-| `RUBYCLI_STRICT=ON` | Enable strict mode validation (prints warnings on comment/signature drift) | `OFF` |
+| `RUBYCLI_DEBUG=true` | Print debug logs | `false` |
+| `--check` | Validate documentation/comments without executing commands | `off` |
+| `--strict` | Enforce documented choices/types; invalid input aborts | `off` |
 | `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` | Disable legacy `@param` lines (defaults to on today for compatibility) | `ON` |
 
 ## Library helpers

data/lib/rubycli/argument_mode_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Rubycli
+  # Coordinates json/eval argument modes and enforces mutual exclusion.
+  class ArgumentModeController
+    def initialize(json_coercer:, eval_coercer:)
+      @json_coercer = json_coercer
+      @eval_coercer = eval_coercer
+    end
+
+    def json_mode?
+      @json_coercer.json_mode?
+    end
+
+    def eval_mode?
+      @eval_coercer.eval_mode?
+    end
+
+    def with_json_mode(enabled = true, &block)
+      enforce_mutual_exclusion!(:json, enabled)
+      @json_coercer.with_json_mode(enabled, &block)
+    end
+
+    def with_eval_mode(enabled = true, **options, &block)
+      enforce_mutual_exclusion!(:eval, enabled)
+      @eval_coercer.with_eval_mode(enabled, **options, &block)
+    end
+
+    def apply_argument_coercions(positional_args, keyword_args)
+      ensure_modes_compatible!
+
+      if json_mode?
+        coerce_values!(positional_args, keyword_args) { |value| @json_coercer.coerce_json_value(value) }
+      end
+
+      if eval_mode?
+        coerce_values!(positional_args, keyword_args) { |value| @eval_coercer.coerce_eval_value(value) }
+      end
+    rescue ::ArgumentError => e
+      raise Rubycli::ArgumentError, e.message
+    end
+
+    private
+
+    def enforce_mutual_exclusion!(mode, enabled)
+      return unless enabled
+
+      case mode
+      when :json
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if eval_mode?
+      when :eval
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if json_mode?
+      end
+    end
+
+    def ensure_modes_compatible!
+      if json_mode? && eval_mode?
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax'
+      end
+    end
+
+    def coerce_values!(positional_args, keyword_args)
+      positional_args.map! { |value| yield(value) }
+      keyword_args.keys.each do |key|
+        keyword_args[key] = yield(keyword_args[key])
+      end
+    end
+  end
+end