matlab-analyze-dependencies

matlab-analyze-dependencies — 依存関係アナライザー

依存関係マニフェストを作成します。ツールボックスの実行時に必要なもの、.mltbx に含まれるもの、含まれないものをすべて示します。含まれないものについては、その理由を説明し、解決方法を提示します。

使用するタイミング

• matlab-define-toolbox-api の仕様が承認された後、またはユーザーから「このコードには何が依存していますか？」と尋ねられたとき
• コードの変更後にマニフェストを更新するため、再実行するとき

使用しないタイミング

• コードの作成やバグ修正 — このスキルは分析のみを行い、ソースを変更しません
• .mltbx のビルド — 依存関係を解決した後、matlab-build-toolbox を使用してください
• プロジェクトの初期設定 — まず matlab-define-toolbox-api を使用して、ツールボックスの仕様を定義してください

主な関数

関数	目的
matlab.addons.toolbox.ToolboxOptions	有効なファイルセット（パッケージに含まれるファイル）を特定する
matlab.codetools.requiredFilesAndProducts	ファイルと製品の推移的な依存関係を追跡する
which	名前空間修飾された関数名を解決する
exist	修飾子のない関数名が解決されるか確認する
matlab.addons.installedAddons	アドオンのファイルパスとメタデータを対応付ける

重要な落とし穴

次の3つの問題はサイレント障害を引き起こします。エラーは発生しませんが、分類結果が誤ります。必ず以下の修正を適用してください。

落とし穴1：パス区切り文字の不一致（Windows）

Windows では、入力に関係なく fList はバックスラッシュを返します。toolboxRoot にスラッシュが含まれている場合、startsWith(fList, toolboxRoot) はすべてのファイルに対して、気付かないうちに false を返します。比較する前に、両方を正規化してください。

toolboxRoot = replace(toolboxRoot, '/', filesep);
fList = replace(fList, '/', filesep);

落とし穴2：matlabroot 配下のファイル混入

matlabroot 配下のファイル（例：toolbox/local/userpath.m）は、製品のフォルダー構造に含まれないため、まれに fList に現れることがあります。これらを除外してください。

mroot = matlabroot;
fList = fList(~startsWith(fList, mroot));

落とし穴3：名前空間の解決には which() が必要

関数が有効でパス上にあっても、exist('pkg.subpkg.func', 'file') は 0 を返します。ドットを含む名前や名前空間修飾された名前には、代わりに which() を使用してください。

% exist() FAILS for namespace calls:
exist('statskit.internal.computeRange', 'file')  % returns 0 (wrong!)

% which() WORKS:
which('statskit.internal.computeRange')  % returns full path

解決方法：

• 修飾子のない名前（ドットなし）：exist(name, 'file') > 0 || exist(name, 'builtin') > 0
• ドットを含む名前：~isempty(which(name))

基本概念

パッケージ化の制約： .mltbx に含められるのは、ツールボックスのルートフォルダー内のファイルのみです。外部ファイルをインストール時に取り込むことはできません。選択肢は、ファイルをコピーする、アドオン依存関係を宣言する、Additional Software（URL の zip）を指定する、またはリファクタリングすることだけです。

有効なファイルセット： ツールボックスのルート内にあるすべてのファイルから、ignore ファイルとデフォルトの除外設定で除外されるファイルを取り除いたものです。これを正式に判定するには、ToolboxOptions を使用してください。ignore ファイルの名前は toolbox.ignore（R2026a 以前）または package.ignore（R2026b 以降）の場合があります。どちらのファイルも確認してください。ToolboxOptions が存在するファイル名に応じて処理します。

ワークフロー

フェーズ1 — 有効なファイルセットの特定

identifier = matlab.lang.internal.uuid();
opts = matlab.addons.toolbox.ToolboxOptions(toolboxRoot, identifier);
effectiveFiles = opts.ToolboxFiles;

ignore ファイルのロジックを手動で再実装しないでください。ToolboxOptions が両方のファイル名、デフォルトの除外設定、エッジケースに対応します。

フェーズ 2 — 依存関係を追跡する

mFiles = effectiveFiles(endsWith(effectiveFiles, ".m") | endsWith(effectiveFiles, ".mlx"));
[fList, pList] = matlab.codetools.requiredFilesAndProducts(mFiles);
fList = string(fList(:));

Pitfall 1（パスの正規化）と Pitfall 2（matlabroot の除外）を、fList の取得直後、分類を始める前にすぐに適用します。

fList 内のファイルを分類します：

• 含める：toolboxRoot で始まり、有効なセットに含まれる
• アドオン：fullfile(getenv('APPDATA'), 'MathWorks', 'MATLAB Add-Ons') の下にある
• 外部の未解決項目：上記以外すべて — ユーザーによる判断が必要

pList 内の製品を分類します：

• Certain == 1：確認済みの製品依存関係 — メタデータに宣言します
• Certain == 0：ヒューリスティックによる推測 — ユーザーの確認が必要であることを示します

無視設定との競合を確認します： toolboxRoot 内にあり、fList に含まれているものの、effectiveFiles には含まれていないファイルを確認します — コードで必要ですが、出荷されません。

実行時のファイル参照を確認します： fList にはデータファイル（.mat、.csv、画像など）は含まれません。.m ファイルをスキャンし、文字列リテラルのパス引数を取る I/O 関数を探して、コードの実行時に必要だが出荷されないファイルを検出します。関数の全リスト、正規表現パターン、分類ロジックについては、references/runtime-file-references.md を参照してください。

フェーズ 2b — 未解決シンボルを検出する

requiredFilesAndProducts は、解決できないシンボルを黙ってスキップします。これらのシンボルを検出するには、別のステップが必要です。

checkcode／codeIssues に頼らないでください — MATLAB の静的解析ツールは、未解決の関数を意図的に許容します。

各ファイルについて、候補となる関数名を抽出します（mtree または正規表現 (?<![%.\w])([a-zA-Z]\w*)\s*\( を使用）。次の項目は除外します：

• MATLAB のキーワード（if、for、while、switch、function、arguments、end、return）
• 関数自身の名前
• 同じファイル内で定義されているローカル関数
• arguments ブロック内の変数（検証構文が正規表現では関数呼び出しのように見えるため）
• localfunctions パターン内の関数（テストファイル）

ドット付き識別子（正規表現：([a-zA-Z]\w*(?:\.[a-zA-Z]\w*)*)(?=\s*\()）については、Pitfall 3 を適用します — which() を使用します。

未解決のシンボルを分類し、解決方法の候補とともに提示します。分類表と表示形式の詳細については、references/unresolved-symbol-classification.md を参照してください。

フェーズ 3 — 外部ファイルの推移的閉包

各外部ファイルについて、その依存関係のサブツリーを追跡します。各階層で子ファイルを分類します。取り込みコストを示すツリーを作成します。

早期終了： サブツリーが複数のディレクトリにまたがって約 15 ファイルを超える場合は、「広範」として印を付けます — ファイルごとのコピーではなく、アーキテクチャ上の解決が必要です。

重複排除： 各ツールボックスファイルに対して 'toponly' を使用し、直接呼び出される外部ファイルを特定します。他の外部ファイルを経由して推移的にのみ到達する外部ファイルは、トップレベルの判断項目として表示せず、親の下にネストします。

パターンを検出します： 同じディレクトリから複数の外部ファイルがある場合はグループ化します。親フォルダーに .prj または resources/project/ がある場合は、MATLAB Project に属します。

フェーズ 4 — 結果を提示する

直接呼び出される外部ファイルと呼び出しチェーン、推移的なコストを示すツリービューと、概要表を作成します。書式設定のガイダンスについては、references/tree-view-format.md を参照してください。

フェーズ 5 — 解決方法を提案する

未解決の外部ファイルまたはグループごとに、トレードオフを含む選択肢を提示します。選択肢の一覧と外部リファクタリングへの引き継ぎテンプレートについては、references/resolution-options.md を参照してください。

このスキルは解決を実行しません。ユーザー（またはツールボックス構造を扱う後続のスキル）が対応できるよう、選択肢を提示します。ファイルのコピー、無視設定ファイルの編集、コードのリファクタリングは行わないでください。

フェーズ 6 — マニフェストを保存する

ユーザーが分析を確認した後、buildUtilities/tbxManifest.m として保存します。マニフェストには現在の状態 — 出荷されるもの、外部にあるもの、未解決のもの — を記録します。解決方法の判断は記録しません。テンプレートの構造については、scripts/tbxManifest-template.m を参照してください。

出力

• 主な成果物：buildUtilities/tbxManifest.m
• 表示：会話内のツリービュー＋概要表＋推奨事項

範囲の境界

このスキルは分析と推奨のみを行います。以下の操作は行いません。

• ツールボックスへのファイルのコピーまたは移動
• ignore ファイルの編集
• コードのリファクタリングや誤字の修正
• MATLAB パスの変更

これらの操作はユーザーの責任で行うか、ツールボックスの構成方法を理解している後続のスキルに任せてください。外部で解決策を適用した後、このスキルを再実行して進捗を確認してください。

主なルール

• 外部要素を取り込む際は、その推移的なコストをすべて示す
• 同じフォルダー内のグループは、個別に N 個の判断事項としてではなく、1 つのアーキテクチャ上の判断事項として提示する
• 解決策の選択肢とトレードオフを提示し、実行はしない
• 解決後（外部で実施）、再実行すると進捗が表示されるようにする（外部要素が含まれるようになるか、アドオンになる）
• ignore との競合に注意を促す。必要なファイルが除外されていると、パッケージング時に気づきにくい不具合になる

次のステップ

• /matlab-create-project — 解決済みの依存関係構造でファイルを MATLAB プロジェクトに整理する

---

Copyright 2026 The MathWorks, Inc.

---