cli API

パッケージ Luna-Flow/mooncake-impact-factor/cli は JavaScript ターゲット向けの実行可能プログラムです。スコアスナップショットの 8 つのシグナルを JSON ファイルから読み込み、compute_score_snapshot を呼び出して結果を JSON で出力します。MoonBit 以外のプログラム、とりわけ Python のインデックスビルダーが、評価規則を複製せずに MoonBit の規則そのものを使えるようにするためのものです。

ソース: src/cli/main.mbt。インターフェースファイルは空です。このパッケージは MoonBit の名前を一切エクスポートせず、ここで説明するコマンドラインがそのインターフェースです。

ビルド

このパッケージは supported_targets = "js" と pkgtype(kind: "executable") を宣言しています。リポジトリのルートでビルドします。

moon build src/cli --target js

インデックスビルダーはビルド結果が _build/js/debug/build/cli/cli.js にあることを前提とし、ファイルがなければビルドします。スクリプトの実行には process.getBuiltinModule を備えた Node.js（20.16、22.3 以降）が必要です。

score-snapshot

score-snapshot は 1 つの JSON 入力ファイルから 1 つのスコアスナップショットを計算します。

node cli.js score-snapshot --input <path>

スクリプトの直後の引数は score-snapshot でなければなりません。--input はその後ろのどこに置いてもかまいません。値が続く最初の --input が使われ、その他の引数は無視されます。

入力

ファイルには JSON オブジェクトを 1 つだけ含めます。各キーは省略可能です。

キー	シグナル
dependents	現在の被依存数。
recent_dependents	現在の最近の被依存数。
downloads	現在のダウンロード数。
days_since_release	現在の、最新リリースからの日数。
historical_dependents	30 日前の被依存数。
historical_recent_dependents	30 日前の最近の被依存数。
historical_downloads	30 日前のダウンロード数。
historical_days_since_release	30 日前の時点での、最新リリースからの日数。

値は JSON の数値である場合にのみ使われます。ゼロ方向への切り捨てで Int に変換され（12.9 は 12 になります）、Int の範囲を超える値はその境界に飽和します。キーの欠落、その他の JSON 型の値（"20" のような数値文字列を含む）、およびトップレベルがオブジェクトでない場合は、すべて 0 として扱われます。その後、スコア関数が負の値を 0 に切り上げます。未知のキーは無視されます。

{
  "dependents": 20,
  "recent_dependents": 4,
  "downloads": 300,
  "days_since_release": 40,
  "historical_dependents": 10,
  "historical_recent_dependents": 2,
  "historical_downloads": 0,
  "historical_days_since_release": 10
}

出力

成功すると、コマンドは ScoreSnapshot の JSON 形式を 1 行出力し、ステータス 0 で終了します。フィールドは宣言順に並びます。NaN のフィールド（2147483647 以上のカウントからのみ生じます）は文字列 "NaN" として書き出されます。上の入力に対する出力は次のとおりです。

{"score":301.7852882193072,"score_30d_ago":135.2764584196223,"score_growth_30d":166.5088297996849,"score_growth_ratio_30d":1.2308780976744749,"rank_label":"S","momentum_label":"Rising","activity_multiplier":1.06}

エラー

使い方の誤りと解析エラーでは、error キーを持つ JSON オブジェクトを 1 つ標準出力に書き出し、ステータス 1 で終了します。

状況	出力
引数がない、または最初の引数が score-snapshot でない	{"error":"Usage: score-snapshot --input <path>"}
値が続く --input がない	{"error":"Missing --input <path>"}
ファイルが正しい JSON でない	{"error":"Failed to parse JSON input"}

読み込めないファイルはこの方法では報告されません。Node.js が捕捉されない ENOENT（または同様の）エラーを送出し、スタックトレースを標準エラーに出力してステータス 1 で終了します。呼び出し側は 0 以外のステータスをすべて失敗とみなし、ステータスが 0 のときだけ標準出力を解析してください。