callidescope-configure

callidescope に実行内容を指示する

毎回の実行では、2 つの設定面を組み合わせて読み込みます。コマンドラインのフラグと、そのフラグを重ねて適用する callidescope.config.ts です。どちらか一方だけでは不完全です。--check で指定する制限は設定ファイルにも設定されている必要があり、ファイルの保存先に書き込まれるのは、フラグで指示した場合だけです。

実行時に決める 2 つのこと

実行のたびに、互いに独立した 2 つの問いに答えます。一方が他方を意味することはありません。

問い	答え
この実行では何を基準に失敗とするか？	--check で指定する、カンマ区切りの項目
この実行では何を書き換えるか？	--write と、設定ファイルで指定した保存先

--write も --check reports も指定せずに実行すると、保存先を読み込まず、何も書き換えません。トレースを行い、結果を表示して終了します。これにより、誰かのチェックアウト内で何も指定せずに実行しても安全です。また、プルリクエストのゲートで実行しても、コミット済みのレポートがすべて変更されずに保たれます。

フラグ

フラグ	意味
-a, --addresses	呼び出し可能なアドレスをカンマ区切りで指定します。各項目は <file>#<qualified-name> です。depth と breadth のみで使用します。省略すると入力を求められます
--config	必須です。ワークスペースの callidescope.config.ts へのパスです。検索は行われません。省略すると、フラグ名を指定するよう求められます
-d, --directories	トレースするプロジェクトディレクトリをカンマ区切りで指定します。各ディレクトリには独自の tsconfig.json が必要です
--entry-point-addresses, --entry-point-decorators, --include-exported-functions, --include-orphans, --include-tests	対応する entryPoints フィールドを上書きします。2つのリストはカンマ区切りで指定し、3つのスイッチには true または false を指定するか、フラグのみを指定すると true になります
--exclude, --exclude-callees	グロブと呼び出し先パターンをカンマ区切りで指定し、authored フィールドを上書きします。設定で exclude を指定した場合と同様に、このツール独自のデフォルト除外設定も再び適用されます
-f, --format	出力形式として markdown、mermaid、json のいずれかを指定します。デフォルトは Markdown です。それ以外は書き換えずに拒否されます。コマンドライン専用で、対応する設定フィールドはありません
--json, -m, --markdown, --mermaid	各レポートの出力先を指定します。宣言された write 出力先のパスを上書きしますが、それ以外は変更しません。--write または --check reports が必要です
--maximum-depth, --maximum-breadth	数値を指定し、プロジェクトで宣言された該当する上限を上書きします。上限が宣言されていない設定に対して --maximum-breadth を指定すると拒否されます。上書きするデフォルト値が存在しないためです
--check, --write	上記の2つの判断を指定します。breadth、depth、reports から選んだ値をカンマ区切りで指定すると失敗させ、設定済みのすべての出力先に書き込みます

設定済みのフィールドには、1つを除いてすべて上書き用のフラグがあります。 excludeFrom は、実行時に読み込む無視ファイルを指定するためのフィールドで、対応するフラグはありません。上書きによって宣言済みの値を変更することはできますが、値を新たに補うことはできません。そのため、フラグを使って未設定の項目がある実行を有効にすることはできず、空のリストは未指定として扱われます。depth と breadth には、必須の --config と --format、出力先と上限を除き、上記のすべての上書きが適用されます。--addresses はこの2つ専用です。

すべてのオーバーライドを支配する優先順位ルール

コマンドラインの値と設定済みの値のあらゆる組み合わせは、単一のルールに従って FlagResolutionService の一か所で解決されます。

実行時に何を判定するか、または何を書き込むかを変えるフラグは、設定ですでに宣言されている値にのみ上書きできます。モードまたは表示形式を選択するフラグは、コマンドライン専用です。どちらも、設定不足の実行を許可するものではないためです。

--check、--write、--format はモードまたは表示形式であり、設定に書き込まれることはありません。--config はそのどちらでもありません。必須であり、既定値が設定されたり、検索されたりすることはありません。また、ほかのすべての値を解決する対象となるファイルを選択するため、それ以降の解決処理が始まる前に役割を終えています。ほかのすべてのフラグはオーバーライドであり、設定がすでに尋ねた問いに答えるものです。パスフラグが置き換えるのは、すでに宣言されている出力先の path だけであり、見出し、説明、アンカー、フックはそのまま維持されます。--maximum-breadth は、プロジェクト自身のファイルで未設定の上限を生み出すことはできません。これは、ワークスペースのファイルで宣言されていない write.json を --json が生み出せないのと同じです。上限のオーバーライドは、実際に各プロジェクトに適用される数値に反映されます。オーバーライド対象の上限を宣言しているすべてのプロジェクトに適用され、宣言していないプロジェクトには適用されません。判定を上書きすることと、判定を逆転させることは同じではないためです。

解決時のエラーは、最初のエラーで処理を中断するのではなく、すべて収集されます。そのため、コマンドラインに誤りが2つあれば、修正すべき誤りは2つであり、実行を2回行う必要はありません。

--check は対象の集合を受け取り、その集合が重要です

値	実行が失敗する条件
depth	呼び出しスタックが limits.maximumDepth を超える深さである場合
breadth	呼び出し可能な要素が、limits.maximumBreadth を超える数の要素を直接呼び出す場合
reports	設定済みの出力先に、最新の実行で書き込まれる内容が保持されていない場合

意図的に拒否されるものが2つあります。

• 値なしの --check は拒否されます。 中身のない集合は、フラグを指定していない状態と区別できません。そのため、変数が未設定のまま --check "$GATES" を実行すると、許容される深さの2倍に及ぶスタックでも永遠に成功してしまいます。これは保護がない状態よりも悪質です。保護されているように見えるためです。
• 認識されない値は拒否され、メッセージには有効な値が一覧表示されます。

depth と reports をプルリクエストの別々の側に置く理由

Depth はゲートです。 この変更でスタックが長くなり、この変更でそれを修正しています。すべてのプルリクエストで実行し、必要ならすべてのコミットでも実行してください。depth はソースを読み込むだけでビルドが不要なため、コミットフックで実行できるほど低コストです。

npx callidescope --config configuration/callidescope.config.ts --check depth

Nx ワークスペースでは、このフラグよりプロジェクトごとの gate ターゲットを優先してください。 ワークスペース全体に対する --check depth でも適切な判定は得られますが、リポジトリ全体を毎コミット、キャッシュ不能な処理で実行するため、コストのかかる方法です。代わりに @callidescope/nx は各プロジェクトに gate を推論して設定し、Nx の依存関係をたどって、そのプロジェクトが所有する検出結果がある場合にのみ失敗します。そのため、nx affected --target=gate は変更が及んだ対象だけを判定します。depth にはデフォルト値があるため、すべてのプロジェクトでゲートされます。breadth は、プロジェクト自身の callidescope.config.ts で limits.maximumBreadth が宣言されている場合にのみゲートされます。Nx を使わない場合は、引き続きこのフラグを使います。

古さはゲートではありません。 呼び出しグラフがどこかで変わるたびにレポートは古くなります。これはほぼすべての変更で起こるため、これをゲートにすると、変更が原因ではない差分のせいでプルリクエストが失敗します。代わりにデフォルトブランチで公開してください。同じブロックを書き換えようと競合するものがほかにない場所です。

npx callidescope --config configuration/callidescope.config.ts --write

--write --check reports は明示的に拒否されます。レポートは、書き込んだ直後の実行では古くなり得ないため、本来検出するはずの内容にかかわらずパスしてしまいます。プルリクエストをゲートするほかの項目と並べて、ゲートを直接指定してください。ブランチから将来 --configuration=write を転送する可能性がある、lint 形式の集約コマンドを介して指定するのは避けてください。

--directories と、指定しない場合に実行が遅くなる理由

ワークスペース全体の分析と、数秒で完了するチェックの違いを生みます。指定する各ディレクトリには、それぞれ独自の tsconfig.json が必要です。構築されるプログラムは、そのファイルと、そこから推移的にインポートされるすべてのプロジェクトです。そのため、依存先への呼び出しも実際のフレームに解決されます。

npx callidescope --config configuration/callidescope.config.ts -d packages/foo,packages/bar --check depth

省略すると、callidescope は作業ディレクトリを検索し、見つかったすべての tsconfig.json を対象にします。これはワークスペース全体の状況を把握するものであり、単一パッケージについての回答ではありません。

指定するのはプロジェクト名ではなくパスです。callidescope はワークスペースのツールを認識せず、tsconfig.json を含むディレクトリだけが契約のすべてです。同じリストは、ワークスペース設定ファイルの directories に一度だけ設定することもできます。

breadth の検索範囲を狭める場合、実際にトレードオフがあります。指定したディレクトリと、その下の依存関係の閉包の外にある呼び出し元は、実行の対象に存在しません。閉包は下方向にたどるため、呼び出してくる依存プロジェクトはビルドされないからです。名前変更の影響範囲を調べることが目的なら、すべての利用側を含むよう、十分に広い範囲をたどってください。

Nx ワークスペースでは、別個の @callidescope/nx プラグインを通じて、選択を Nx に任せることもできます。プラグインは各プロジェクトに trace、depth、breadth、gate ターゲットを推論して設定し、それぞれのプロジェクトを _Nx の依存関係とともに_たどります。そのため、実行対象は依存関係の閉包を通じて単に到達したプロジェクトではなく、スコープとして指定したプロジェクトになります。最初の 3 つは出力のみを行い、gate は終了コードを決定するため、ブランチで実行するのはこちらです。除外されたプロジェクトでは、そのコードがたどられないため、出力のみを行う 3 つのターゲットは残りますが、ゲートは実行できません。CLI が Nx 関連のものに依存しないよう、このパッケージは意図的に分離されています。

--format が決めるのは出力形式であり、書き込み内容ではありません

出力と書き込みは独立しており、両方を同時に有効にできます。--format は標準出力の形式として、markdown（デフォルト）、mermaid、json のいずれかを指定します。ファイルに書き込む内容は、プロジェクトまたはワークスペース自身の write で宣言した出力先によって決まります。markdown を先頭にしているのは、ターミナルで読めて、issue に貼り付けられ、ファイルにもすでに使われている形式だからです。write.format フィールドはありません。コンソールの出力形式はコマンドラインでのみ指定するものです。

プロンプト入力と、スクリプトがハングしない理由

callidescope、depth、breadth はいずれも、コマンドラインで省略された値をプロンプトで入力できます。depth と breadth では --addresses の値がない場合に、3つすべてでは --format の値がない場合に入力を求めます。無効にするフラグはありません。ターミナルに接続されていることが唯一の条件だからです。スクリプト、フック、CI ジョブにはターミナルがないため、プロンプトは表示されません。--addresses が指定されていない場合は、ほかに値を指定できる方法がないため、拒否され、ゼロ以外の終了コードになります。--format が指定されていない場合は、既定値の markdown にフォールバックして実行が続行されます。

拒否の仕組みが重要です。prompts は stdin がターミナルでない場合に失敗しません。メニューを表示したまま解決せず、何もせずにプロセスを 終了コード 0 で終了させます。そのため、必須の値がある場合はプロンプトを表示する前にターミナルがあることを確認し、代わりに不正なコマンドラインとして報告します。この仕組みがなければ、引数を指定し忘れた CI の実行が成功したように見えてしまいます。

ワークスペース設定ファイル

callidescope.config.{ts,mts,cts,js,mjs,cjs,json,jsonc} のいずれかを使用します。型チェックが行われるため、TypeScript が優先されます。これはワークスペースの設定で、必須の --config で実行時に指定するファイルです（Nx ターゲットの configuration、プラグインの configurationPath）。自動検索は行われません。ここでは configuration/callidescope.config.ts を指定します。

import { type CallidescopeConfiguration } from "@callidescope/configuration";

const callidescopeConfiguration: CallidescopeConfiguration = {
  excludeFrom: ["configuration/.callidescopeignore"],
  limits: { maximumDepth: 6 },
};

export default callidescopeConfiguration;

設定できるトップレベルキーは directories、entryPoints、exclude、excludeCallees、excludeFrom、limits、write の7つです。ワークスペースファイルでは、既定エクスポートに加えて projectDefaults もエクスポートします。これはこの型のメンバーではなく、プロジェクト独自の callidescope.config.ts でスプレッドするための別のバインディングです。

limits

制限は2種類あり、どちらもプロジェクトごとに設定し、ゲートで判定します。

制限	既定値	意味
maximumDepth	6	呼び出しスタックが保持できるフレーム数。エントリーポイントを含みます
maximumBreadth	なし	1つの呼び出し可能要素が直接呼び出せる呼び出し可能要素の数

maximumBreadth に既定値がないのは意図的です。 数値が設定されるまでは、幅はゲート判定なしで報告されます。また、--check breadth は、合格とまったく同じように見える無制限の値にフォールバックするのではなく、拒否されます。さらに、設定する値はプロジェクト独自のものでなければならず、ワークスペースの値だけでは設定できません。詳しくはプロジェクトで設定できる項目を参照してください。

最初の maximumDepth を決めるには、ゲートを設定せずに一度実行し、最も深いスタックを確認します。現在のコードの値ではなく、目標とする構造に合わせて制限を設定してください。現在の最悪値に制限を合わせても、何も判定できません。

プロジェクトごとに、実行結果に表示された数値を読むのではなく、境界値をテストして各制限を決めてください。 候補値を設定してそのプロジェクトのゲートを実行し、次に1つ小さい値で実行します。設定する意味のある制限なら、記載した値では合格し、その1つ下では失敗します。スコープを指定した実行の要約には、依存関係の閉包も含め、トレース全体が表示されるため、報告される深さは判定対象のプロジェクトが所有するものより、通常は深くなります。どの検出結果がプロジェクトに属するかを判別できるのは、ゲートの判定だけです。

現在、制限はスキーマのフィールドにすぎません。 スキーマは厳格で、limits が受け付けるのは maximumDepth と maximumBreadth のみです。廃止されたフィールドである spreadThreshold、directSpreadThreshold、minimumCallers、callerMajorityRatio は、黙って削除されるのではなく拒否されます。これら4つの制限、それらが調整していた2つの検出結果、およびその根底にあったモジュール同一性の概念は、ツールから完全に削除されています。リポジトリの ADR 0006「Narrow callidescope to depth and breadth」を参照してください。

実装候補の上限は定数であり、設定フィールドではありません。 この上限は、構造的なインターフェイス解決で推測を打ち切る位置を決めるものです。これは解決処理の性質であり、実行ごとに判定する数値ではないため、@callidescope/graph に置かれており、callidescope.config.ts のどこにも記述しません。

entryPoints

オプション	デフォルト	意味
addresses	なし	ルートとして明示的に指定する呼び出し可能な要素。各項目は <file>#<qualified-name>
decorators	13 個のフレームワークデコレーター	フレームワークがメソッドを呼び出すデコレーター
includeExportedFunctions	true	すべての src/index.ts のエクスポートをルートとして扱います
includeOrphans	true	リポジトリ内のどこからも呼び出されない呼び出し可能な要素をルートに昇格します
includeTests	false	テストファイルもトレースします

addresses は、パッケージの計測対象となる範囲を指定する方法です。 depth と breadth が受け付け、すべてのフレームに表示されるものと同じ <file>#<qualified-name> 形式なので、レポートからアドレスをそのまま 設定にコピーできます。同じ名前を 1 つのファイル内で 2 回宣言している場合は、 末尾に :<line> を付けます。

entryPoints: {
  addresses: ["packages/foo/src/modules/read/read.service.ts#ReadService.read"],
},

宣言したアドレスはルートを追加するもので、削除はしません。以下のルールは 引き続き先に適用され、孤立要素の昇格によって名前のない要素も拾われます。 すでにルートになっている呼び出し可能な要素は、ルート 1 つのままです。

グラフの下位に位置するパッケージには、addresses を指定してください。スタックは ルートを所有するプロジェクトに記録されるため、そのようなパッケージが公開する 要素の大半は上位から呼び出されます。そのためルートがなく、パッケージに対する 制限が何も制御できないことがあります。 アドレスが何も解決できない場合、複数の宣言に解決される場合、または解析可能な ものがない場合は、実行全体が失敗します。callidescope-triage が各メッセージと その修正方法を示します。

decorators は組み込みリストに追加するのではなく、置き換えます。そのため、 独自のフレームワークのデコレーターを指定する設定では、引き続き必要なデコレーターも 再度記述してください。ほぼすべてが孤立したルートになるレポートは、通常、使用中の デコレーターが設定に含まれていないことを意味します。

includeOrphans は機能ではなく、安全網です。 これを無効にすると、エントリー ポイントのルール不足によってサブツリー全体がすべての計測対象からひそかに除外されます。 有効にすると、それらは孤立したルートとして表面化します。つまり、デッドコードか、 追加が必要なルールです。

実行対象からコードを除外する

異なる 2 つの目的に使うツールが 2 つあります。

• exclude は glob パターンを受け取り、組み込みのデフォルト （node_modules、dist、coverage、output、.nx、.conformetry）に 追加されます。そのため、設定で独自のノイズを指定しても、これらを再度記述する 必要はありません。
• excludeFrom は gitignore 構文のファイルを指定します。ワークスペース内でのみ 使用できます。長い除外リストを設定ファイル自体に記述せずに済み、意図的に問題のある フィクスチャーパッケージを配置するのにも適しています。
• excludeCallees は呼び出し可能な要素の表示名（Type.member）に照合する glob パターンを受け取り、一致する呼び出しをグラフから完全に除外します。深さにも 幅にもカウントされません。これは横断的な計測に使います。ロガーの呼び出しは、 周囲のコードの構造ではなく、計測に関する事実です。これをカウントすると、関係のない 変更によって、ほかのすべての呼び出し可能な要素の数値が変わってしまいます。

exclude と excludeFrom は収集対象から ファイル を除外します。 excludeCallees は エッジ を除外します。後者の代わりに前者を使うと、 実際にある検出結果が削除されます。いずれも ts.Program からは除外しません。 除外されたファイルも引き続きコンパイルされ、そのファイルへの呼び出しは消えるのではなく 追跡不能になり、tsconfig.json を含むディレクトリは exclude でプロジェクト対象から 外せません。プロジェクト独自の exclude も同様に動作します。

directories

--directories が受け取るものと同じリストを一度だけ設定します。ワークスペース内でのみ 使用できます。

write

すべての出力先は任意で、設定しないのが通常です。出力先を指定せずに実行すると、違反をコンソールに報告してゼロ以外の終了コードで終了するため、書き込まれた内容が古くなることはありません。

キー	用途
write.json	path にインデントを indentation で指定した、機械可読なレポートです。ワークスペース専用です
write.markdown	マーカーで区切られたブロックを path に挿入します
write.mermaid	同じブロックを、スタックをひとつのフローチャートとして描いて挿入します

write.mermaid は write.markdown と同じキーを受け取ります。異なるのはマーカーの間に入る内容であり、ブロックの配置方法ではありません。また、1 回の実行で両方を公開できるよう、別個に用意されています。ツリーは各フレームが何を受け取り、何を返し、何を文書化するかを示し、図はそれらを組み合わせたときの形を示します。

write: {
  json: { indentation: 2, path: "output/callidescope.json" },
  markdown: { path: "docs/call-stacks.md" },
  mermaid: { path: "docs/call-stacks-diagram.md" },
},

どちらも description（見出しの下に配置）、heading（デフォルトは # 🔭 Callidescope です。ブロックをすでにタイトルがあるファイルに挿入する場合は設定してください。多くの Markdown リンターは 2 つ目の第 1 レベル見出しを拒否するためです）、および previewCount（開示部分に残りが折りたたまれるまでに表示するスタックの数。デフォルトは 3）を受け取ります。previewCount は実行ではなく出力先に属します。これは、ブロックが挿入されるドキュメントに関する設定だからです。プロジェクト独自の README では 3 件、ワークスペース全体のレポートファイルではすべてを表示したい場合があります。実行全体のブロックは、まず集計数、各プロジェクトの独自の深さ制限に対する 1 行ずつの一覧、さらに制限を超過・ちょうど・下回っているプロジェクト数の集計表を表示します。その後に検出結果の表が続きます。

すべてのプロジェクトの README にセクションを書き込む一括出力機能はありません。 各プロジェクトは、それぞれの callidescope.config.ts で独自の write.markdown（および図が必要なら write.mermaid）を宣言します。プロジェクトで設定できる項目を参照してください。ワークスペース独自の write.markdown は、ワークスペースについてのブロックです。つまり、集計数、各プロジェクトの独自の深さ制限に対する 1 行ずつの一覧、および集計表を表示します。

Markdown の出力先には render を指定して組み込みの表を置き換えたり、writeBlock を指定してブロック自体の配置方法を定義したりできます。後者には syncAnchoredBlock と wrapInAnchors が渡されるため、同じ挿入処理を再利用できます。false を返すと出力先は古いものとして報告されます。それ以外の値は、undefined も含め、最新の状態として扱われます。

トレース対象となるすべてのプロジェクトに、完全な独自設定が必要です

トレース対象となる各プロジェクトのルートにも、2 つ目の callidescope.config.ts を置きます。ルートとは、そのプロジェクトを構成する tsconfig.json があるディレクトリです。設定ファイルはそのディレクトリ内だけで名前を使って検索され、上位ディレクトリへはたどりません。対象となる拡張子は同じ 8 種類です。

トレース対象となるすべてのプロジェクトに設定ファイルが必要であり、どのファイルにも設定項目をすべて記述する必要があります。 設定ファイルがないトレース対象のプロジェクトは、名前を指定して拒否されます。項目を省略したファイルも同様です。完全な設定を必須とするのは意図的です。項目が未設定の場合と、デフォルト値と同じ値が設定されている場合は、差分上では同じように見えますが、決定があったのは後者だけです。maximumBreadth が未設定の場合と maximumBreadth: undefined の場合は、以前はそれぞれ「設定し忘れた」と「このプロジェクトでは幅ではなく深さを制限する」を意味していましたが、項目ごとのフォールバックでは両者を区別できませんでした。リポジトリの ADR 0007「トレース対象となるすべてのプロジェクトに完全な設定を必須とする」を参照してください。

実行時に指定されたファイルが、プロジェクトの設定ファイルとして読み込まれることはありません。1 つのファイルが 1 回の実行で担う役割は 1 つです。タスクで独自の設定ファイルを指定したパッケージが自身をトレースすると、そのファイルに正当に設定されたワークスペース専用の項目が原因で拒否されてしまいます。そのため、両方が必要なパッケージでは、別々の名前で 2 つのファイルを用意します。

プロジェクトで設定できる項目

項目	説明
entryPoints	addresses を含め、どのプロジェクトの呼び出し可能な要素をスタックの起点にするか
limits.maximumDepth	そのプロジェクトを起点とするすべてのスタックの判定に使う深さ
limits.maximumBreadth	そのプロジェクトが宣言するすべての呼び出し可能な要素の判定に使う幅
exclude	トレース対象から除外する、そのプロジェクト自身のファイルを指定するグロブ
write.markdown	そのプロジェクト自身の公開セクションの出力先
write.mermaid	必要な場合に、そのプロジェクト自身の図を出力する場所

プロジェクト自身の出力先と exclude グロブは、ワークスペースではなく、そのプロジェクトのルートを基準にします。packages/thing の独自ファイルにある exclude: ["src/generated/**"] は packages/thing/src/generated/** を指定し、同じ場所にある write: { markdown: { path: "docs/CALLS.md" } } は packages/thing/docs/CALLS.md に書き込みます。どちらの指定でも、兄弟プロジェクトには影響しません。出力先を undefined のままにすると、そのプロジェクトからは何も公開されません。

実行時の exclude は引き続きワークスペース基準で、その下に追加されます。そのため、プロジェクト側でさらに除外することはできますが、実行時に除外されたものを再び対象に戻すことはできません。複数のプロジェクトにまたがるノイズは、引き続きワークスペースのファイルで指定します。

write.json は引き続きワークスペース専用です。これは実行時の単一レポートであり、プロジェクト側で出力先を変更するものではありません。

それ以外の項目は、トレースを開始する前に項目名を指定して拒否されます。メッセージには上記の6項目が示されるため、このスキルを開かなくても対処できます。

デフォルトを展開し、その後に上書きする

ワークスペース設定では、デフォルトエクスポートと並んで projectDefaults をエクスポートしています。プロジェクトはこれを展開し、必要な値を上書きします。これにより、完全なファイルを1行で記述できます。

import { projectDefaults } from "../../configuration/callidescope.config.js";

export default {
  ...projectDefaults,
  limits: { maximumBreadth: undefined, maximumDepth: 10 },
};

実際に数値が設定されているのは一方だけですが、両方の上限に名前が付いています。maximumBreadth: undefined は、このプロジェクトが幅ではなく深さを制限すると明示しています。フィールドを省略しただけでは、そのプロジェクトが設定を忘れた場合と区別できないため、この明示が必要です。同じことが write.mermaid: undefined と、図を公開しない設定にも当てはまります。

ワークスペースのデフォルトエクスポートではなく、projectDefaults を展開してください。 この2つは意図的に異なるオブジェクトです。デフォルトエクスポートには directories、excludeFrom、write.json など、ワークスペースだけが設定できる項目が含まれています。そのため、これを展開すると、最初に見つかったそのようなフィールドを示すエラーになります。projectDefaults にはプロジェクトに許可された項目だけが含まれているので、出力先や除外ファイルを誤って引き継ぐことはありません。

2つのファイルをまたいで解決することはなく、数値の出所を記録する仕組みもありません。 プロジェクトの判定に使われる数値はすべて、そのプロジェクト自身のファイルに記述します。プロジェクトのファイルが存在する場合、フィールドごとにワークスペースへフォールバックすることはありません。また、数値は展開によって読み手に見える形でこのファイルに置かれるため、「宣言済み」と「継承済み」を区別する必要もありません。上限が「継承」されると説明するドキュメントや、プロジェクトの README に「Origin」列がある場合は、この要件より前のツールについて記述しています。この変更で置き換えられたエラーについては、callidescope-triage スキルを参照してください。

projectDefaults に含まれるワークスペースの数値は、上限ではなくデフォルトです。これを展開した後に、より高い上限へ上書きしたプロジェクトは、その値を維持します。ワークスペース内で最も深いスタックを基準に固定されたワークスペースの数値では、その値に遠く及ばないプロジェクトは何も制限されないためです。

entryPoints はメンバーごとにマージされず、全体が置き換えられます。プロジェクト独自の entryPoints オブジェクトを記述すると、そのプロジェクトの呼び出し可能な対象について、展開された設定が丸ごと置き換わります。そのため、ワークスペースのデコレーター一覧と独自の addresses の両方を使いたいプロジェクトは、...projectDefaults.entryPoints を使ってデコレーター一覧を明示的に引き継ぐ必要があります。

ほかのフィールドをプロジェクトごとに変更できない理由。 maximumDepth と maximumBreadth は、一度構築した呼び出しグラフを判定するため、同じ辺について2つのプロジェクトが異なる問いを求めても問題ありません。一方、excludeCallees、directories、excludeFrom、write.json は異なります。これらは、実行時に読み込む対象、レポートの出力先、またはワークスペースの分割方法を指定するものであり、プロジェクトがそれをトレースする実行とは異なる設定にすることはできません。

設定全体を確認する

プロジェクトごとに1つのファイルに記述されたラチェットは、以前のように1つのファイルだけを見てレビューできなくなります。代わりに、limits コマンドで設定全体をレビューできます。

npx callidescope limits --config configuration/callidescope.config.ts

Markdown の表には、プロジェクトと上限の組み合わせごとに1行があり、Project、Limit、Value、Declared in が表示されます。各数値が記述されているファイルも示されます。none は、その上限がどこにも宣言されていないことを意味します。幅の場合は、これが一般的です。workspace の行は最初に表示され、ファイル名がない場合があるのはこの行だけです。この行は各プロジェクトが自身のファイルで展開するデフォルトであり、どのファイルにもそのまま記述される数値ではないためです。設定を解決するだけで、計測は行わないため、実行時間はトレースではなく数ミリ秒です。

これらを変更した後

設定の変更では数値が変わることが多く、コミット済みのレポートはすべて古くなります。同じ変更で書き込み設定を再実行し、再生成の前にリンターを実行してください。各フレームには file:line が含まれるため、クラスメンバーを並べ替えるフォーマッターを実行すると行番号が変わります。その並べ替えの前に書かれたレポートは、反映された時点で古くなります。

実行が拒否された場合や、レポートが古いと表示された場合は、callidescope-triage を使ってください。実行時の出力を確認する場合は、callidescope-trace を使ってください。