cli API

Luna-Flow/mare_mark/cli は mare-mark 実行ファイルです。JSONL イベントファイルを HTML レポートとして描画し、記録された検証失敗を再実行（リプレイ）します。このページでは、コマンドラインとパッケージの公開ヘルパー関数を説明します。cli の設計も参照してください。

ソース: src/cli/cli.mbt、src/cli/main.mbt（native）、src/cli/main_unimplemented.mbt（その他のターゲット）、src/cli/replay_native.mbt。

コマンドライン

チェックアウトしたリポジトリから moon run src/cli --target native -- <arguments> で実行します。

mare-mark <replay|report> [options] [input] [output]

呼び出し方	動作
`mare-mark report <input.jsonl> <output.html>`	イベントを解析し、自己完結型の HTML レポートを書き出します
`mare-mark report - -`	stdin からイベントを読み込み、HTML を stdout に書き出します
`mare-mark report --quiet ...`	進捗の要約を表示しません
`mare-mark report --open ...`	書き出したファイルを `open` で開きます（macOS）
`mare-mark replay <artifact.jsonl> --dry-run`	最初の `validation_failure` のコマンド、引数、タイムアウトを表示します
`mare-mark replay <artifact.jsonl> --yes`	そのコマンドをタイムアウト付きで実行し、その stdout を表示します
`mare-mark --version`, `-V`	`mare-mark 0.3.0` を表示します
`mare-mark --help`、`-h`、または引数なし	使い方を表示します。コマンドを指定した場合は、そのコマンドのヘルプを表示します

オプションはコマンドの後ならどこに置いても構いません。未知のオプションや 3 つ以上の位置引数はエラーになります。replay は入力として - を受け付けず、--yes なしでは実行を拒否します。

終了コード: 成功時は 0、ファイルを読み書きできない場合、JSONL が不正な場合、リプレイが失敗またはタイムアウトした場合は 1、使い方の誤り（未知のコマンドやオプション、引数の不足、--yes の欠落）では 2 です。native 以外のターゲットでは、report は render_jsonl_report を通じて動作し、replay は 2 で終了します。

ファイルを書き出した後、report は出力先の絶対パス、空でない入力行の数、経過時間を表示します。経過時間はマイクロ秒単位で計測されますが、ラベルは ms になっています。

パッケージ関数

このパッケージは実行ファイルです（pkgtype(kind: "executable")）。公開関数は main を構成する部品であり、パッケージのテストでカバーされています。MoonBit 0.10 では他のパッケージから実行ファイルパッケージをインポートできますが、将来エラーになるという警告が出ます。そのため、自分のパッケージからこれらの関数に依存しないでください。

リクエスト

`Command`

Command は最初の引数で選択されるサブコマンドです。

pub enum Command {
  Replay
  Report
  Help
  Version
  Unknown(String)
}

`CliRequest`

CliRequest は解析済みのコマンドラインです。

pub struct CliRequest {
  command : Command
  input : String?
  output : String?
  dry_run : Bool
  yes : Bool
  quiet : Bool
  open : Bool
  show_help : Bool
  error : String?
}

input と output は最初の 2 つの位置引数です。error には最初の使い方の誤り（"unknown option '…'"、"too many positional arguments"）が入ります。

`parse_args`

parse_args はプログラム名を含む引数ベクタ全体を解析します。

pub fn parse_args(Array[String]) -> CliRequest

インデックス 1 がコマンドを選択します（replay、report、--version/-V、--help/-h。引数が 2 つ未満の場合は Help）。--help または -h がどこかに現れた場合、結果には show_help = true とコマンドだけが設定されます。それ以外の場合、インデックス 2 以降の引数はフラグ（--dry-run、--yes、--quiet、--open）、位置引数、またはエラーのいずれかです。- は位置引数として扱われます。

test "parse a report command" {
  let request = @cli.parse_args(["mare-mark", "report", "--quiet", "events.jsonl", "report.html"])
  inspect(request.command is Report, content="true")
  inspect(request.input == Some("events.jsonl"), content="true")
  inspect(request.quiet, content="true")
  let wrong = @cli.parse_args(["mare-mark", "report", "--fast", "a", "b"])
  inspect(wrong.error == Some("unknown option '--fast'"), content="true")
}

`usage`, `command_help`

usage は全体のヘルプテキストを返します。command_help は Report または Replay のヘルプを返し、その他のコマンドでは usage() を返します。

pub fn usage() -> String
pub fn command_help(Command) -> String

レポート

`render_jsonl_report`

render_jsonl_report は JSONL ファイルを読み込んで描画し、HTML を書き出します。

pub fn render_jsonl_report(String, String, target? : String) -> Result[String, String]

引数: 入力パス、出力パス、ターゲットラベル（既定値 "unknown"）。出力パスを返します。入力が読めない場合、イベントが不正な場合、出力に書き込めない場合はエラーメッセージを返します。

`report_html`

report_html は @report.html です。

pub fn report_html(@ir_model.PlotDocument) -> String

リプレイ

`replay_spec_from_jsonl`

replay_spec_from_jsonl は JSONL テキスト中の最初の validation_failure イベントからリプレイコマンドを取り出します。

pub fn replay_spec_from_jsonl(String) -> Result[@model.ReplaySpec, String]

それより前の行は、有効な JSON オブジェクトであることとサポートされた artifact_version を持つことが検査され、それ以外の点では読み飛ばされます。イベントは文字列の replay_command を持つ必要があります。replay_arguments はその文字列要素だけを保持し、replay_timeout_ms の既定値は 5000 です。エラー: 不正な JSON、オブジェクトでない行、サポートされないバージョン、コマンドの欠落、失敗イベントがまったくない場合。

test "read a replay artifact" {
  let artifact =
    #|{"type":"observation","implementation":"a","dataset_id":0,"elapsed_us":1.0}
    #|{"type":"validation_failure","replay_command":"worker","replay_arguments":["fast","42"],"replay_timeout_ms":250}
  let spec = @cli.replay_spec_from_jsonl(artifact).unwrap()
  inspect(spec.command, content="worker")
  debug_inspect(spec.arguments, content="[\"fast\", \"42\"]")
  inspect(spec.timeout_ms, content="250")
  inspect(@cli.replay_spec_from_jsonl("") is Err("no validation_failure event found"), content="true")
}

`load_replay_spec`

load_replay_spec はファイルを読み込み、replay_spec_from_jsonl を呼び出します。

pub fn load_replay_spec(String) -> Result[@model.ReplaySpec, String]

cli API

コマンドライン

パッケージ関数

リクエスト

Command

CliRequest

parse_args

usage, command_help