codometer-measure

Codometer の測定を実行する

Codometer はディレクトリを走査し、認識できるすべてのものを解析して、数えた内容を報告します。コンソール出力、JSON レポート、Markdown ドキュメント、または既存ファイルに挿入するバッジブロックとして出力できます。ファイル、行、クラス、関数など、一般的なアナライザーと同じように言語を数えるだけでなく、リポジトリが自らに課している規約も数えます。通常、こちらのほうが興味深い数値です。

一度に 1 つのディレクトリ

Codometer が測定するのは 1 つのディレクトリであり、ワークスペース、タスクランナー、プロジェクトグラフについては何も把握していません。 プロジェクトを指定すると、そのプロジェクト独自のソースと、設定で宣言された入力だけを測定します。それ以外のものや、兄弟プロジェクトについては何も測定しません。--directory はありません。実行時には常にプロセスの作業ディレクトリが測定され、実行ごとの上書きはできません。

cd packages/widgets && codometer --config codometer.config.ts --check limits

プロジェクト名、パッケージ名、またはタスクランナーが解決するようなものを受け取ると思い込まないでください。ワークスペースがプロジェクトごとに実行する場合、その反復処理はランナーの役割であり、codometer の役割ではありません。--inputs [globs...] を指定すると、1 回の実行を指定した glob だけに絞り込み、language 解析のみを実行します。設定済みの入力は一切有効にならず、組み込みの codebase も対象外です。

設定の指定

--config <path> は必須です。 Codometer は設定ファイルを検索せず、デフォルトの設定もありません。このフラグなしで実行すると、フラグ名を示すエラーで拒否されます。指定したファイルだけが設定として使われ、他のファイルの内容が取り込まれることはありません。相対パスは作業ディレクトリを基準に解決され、その後リポジトリルートを基準に解決されます。このリポジトリでは、ワークスペースファイルは configuration/codometer.config.ts、各プロジェクト独自のファイルは codometer.config.ts です。設定ファイルは常にプレーンオブジェクトとして読み込まれます。関数をエクスポートしても認識されず、空の設定にフォールバックします。

ファイルの検出では .gitignore がすでに適用されるため、ignore ファイルによって除外されたビルドディレクトリや仮想環境を、改めて除外指定する必要はありません。また、git 自体は実行されないため、バージョン管理されていないディレクトリもリポジトリと同じように測定されます。

すべてのフラグは独立

--output-json、--output-markdown、--check、--format は個別に指定するものであり、いずれかを指定しても他のフラグが有効になることはありません。

実行コマンド	書き込み	古さがある場合に失敗	違反がある場合に失敗
codometer --config <path>	いいえ	いいえ	いいえ
codometer --config <path> --check limits	いいえ	いいえ	はい
codometer --config <path> --check reports	いいえ	はい	いいえ
codometer --config <path> --check limits,reports	いいえ	はい	はい
codometer --config <path> --output-json	はい	いいえ	いいえ
codometer --config <path> --output-json --check limits	はい	いいえ	はい。書き込み後

単独で渡された --output-json／--output-markdown は、その種類の出力先として解決済み設定に宣言された場所に書き込みます。設定に該当する出力先が宣言されていない場合は、書き込み先がないため、測定を始める前に拒否されます。パスを指定して渡した場合は、設定にその種類の出力先が宣言されているかどうかにかかわらず、その実行でのみ指定したパスが使われます。codometer --config <path> --output-json report.json は、outputs の内容に関係なく、そこに書き込みます。

--output-* フラグと --check reports を組み合わせることはできません。実行直後に書き込んだものが古くなることはないため、組み合わせると拒否されます。書き込みとゲート判定を両方行う実行では、失敗する場合でも、解決されたすべての出力を生成します。そのため、実行の終了コードが失敗を示す場合でも、ディスク上のレポートには最新の測定結果が反映されます。

違反と古さは異なる判定であり、1 つにまとめて報告されることはありません。重大度が warn の違反は出力されますが、終了コードには影響しません。重大度が fail の違反は終了コード 1 になり、--check limits でゲート判定を要求した場合に限ります。どちらへの対処方法についても、codometer-triage スキルを参照してください。

- run: npx @codometer/cli --config codometer.config.ts --check limits,reports

レポートの読み方

JSON レポートでは、メトリクスがターゲットごとにまとめられています。各メトリクスには、値、ターゲット内のパス、単位（"bytes" または null）、そのメトリクスに設定されたすべての上限が含まれます。また、comment セレクターのメトリクスには、上限を超えた各ブロックが見つかった instances も含まれます。

{
  "failures": [],
  "targets": [
    {
      "empty": false,
      "files": 42,
      "name": "codebase",
      "metrics": [
        {
          "instances": null,
          "limits": [{ "breached": false, "label": null, "severity": "fail", "value": 500 }],
          "name": "codebase.typescript.interfaces",
          "path": "typescript.interfaces",
          "unit": null,
          "value": 118
        },
        {
          "instances": [{ "file": "src/main.ts", "line": 4, "measured": 214 }],
          "limits": [{ "breached": true, "label": null, "severity": "fail", "value": 0 }],
          "name": "codebase.custom.TypeScript Comment Budget",
          "path": "custom.TypeScript Comment Budget",
          "unit": null,
          "value": 1
        }
      ]
    }
  ]
}

上限を超えていない場合も、超えている場合とまったく同じ形式で出力されるため、利用側では違反だけでなく、上限までの余裕も表示できます。comment セレクターの value は、独自の予算を超えたブロックの数を表し、instances は各ブロックのファイルと行を示します。件数だけを数えるメトリクスでは null になります。failures には、実行できなかったことが格納されます。たとえば、上限が設定されているのにファイルに一致しなかったターゲットや、測定されたメトリクスがない上限などです。違反や古さとは関係ありません。

出力先

実行時に表示する内容と書き込む内容は、別々に指定します。--format json はレポートを表示し、--format markdown は描画したバッジを表示します。パスを指定した場合は常にファイルを指し、コンソールは指しません。--format を省略すると、解決済み設定に必須項目として指定された format フィールドが使われます。他のフラグから形式が推測されることはありません。

ファイルへの出力先は 2 種類あります。--output-json [path] と --output-markdown [path] は、互いを有効にすることも、コンソールへの出力を有効にすることもありません。

--output-markdown は、ほかの内容がすでに書き込まれている可能性のあるファイルに出力します。ブロックは 2 つのマーカーで囲まれます。設定で名前が変更されていない限り、マーカーは / です。マーカーがあればその間に挿入され、なければマーカーとともに末尾へ追加されます。ファイルが存在しない場合は作成されます。

codometer が書き込むすべてのファイルは、フラグの指定にかかわらず、実行のたびに測定対象から除外されます。書き込んだレポートをカウント対象にすると、書き込まれた瞬間に古くなります。また、挿入によって、書き込んだばかりの markdown メトリクス自体が測定対象に入ってしまいます。

バグのように見えるランタイムの詳細

圧縮サイズは Node のバージョンによって異なります。リリースごとに同梱されている zlib が異なるためです。ある Node ランタイムで書き込んだレポートを別のランタイムで確認すると、ソースに変更がなくても古いと判定されます。--check reports は、リポジトリで他の用途に固定されているものと同じランタイムで実行してください。レポートが古いときは、実際のリグレッションだと結論づける前に codometer-triage スキルを利用してください。