matlab-analyze-dependencies

name	matlab-analyze-dependencies
description	Analyze the effective toolbox file set to produce a Dependency Manifest — classify all transitive dependencies as included, product, add-on, or external-unresolved, then present resolution options with tradeoffs. Use after matlab-define-toolbox-api when the spec is approved.
license	MathWorks BSD-3-Clause
metadata	{"author":"MathWorks","version":"1.0"}

matlab-analyze-dependencies — Dependency Analyzer

You produce the Dependency Manifest: a complete picture of what the toolbox needs at runtime, what ships inside the .mltbx, and what doesn't. For anything that doesn't ship, you explain why and present resolution options.

When to Use

• After matlab-define-toolbox-api spec is approved, or user asks "what does this code depend on?"
• Re-running after code changes to update the manifest

When NOT to Use

• Writing code or fixing bugs — this skill only analyzes, it does not modify source
• Building the .mltbx — use matlab-build-toolbox after dependencies are resolved
• Initial project setup — use matlab-define-toolbox-api first to define the toolbox spec

Key Functions

Function	Purpose
matlab.addons.toolbox.ToolboxOptions	Determine effective file set (what ships)
matlab.codetools.requiredFilesAndProducts	Trace transitive file and product dependencies
which	Resolve namespace-qualified function names
exist	Check if bare function names resolve
matlab.addons.installedAddons	Correlate add-on file paths with metadata

Critical Pitfalls

These three issues cause silent failures — no error is raised, but classification results are wrong. Always apply these fixes.

Pitfall 1: Path Separator Mismatch (Windows)

On Windows, fList returns backslashes regardless of input. If toolboxRoot has forward slashes, startsWith(fList, toolboxRoot) silently returns false for every file. Normalize both before any comparison:

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

Pitfall 2: matlabroot File Leak

Files under matlabroot (e.g., toolbox/local/userpath.m) occasionally appear in fList because they live in non-product folder structures. Filter them out:

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

Pitfall 3: Namespace Resolution Requires which()

exist('pkg.subpkg.func', 'file') returns 0 even when the function is valid and on the path. For any dotted/namespace-qualified name, use which() instead:

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

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

Resolution strategy:

• Bare names (no dots): exist(name, 'file') > 0 || exist(name, 'builtin') > 0
• Dotted names: ~isempty(which(name))

Core Concepts

The Packaging Constraint: An .mltbx can only contain files inside the toolbox root folder. External files cannot be pulled in at install time. The only options are: copy in, declare add-on dependency, Additional Software (URL zip), or refactor.

The Effective File Set: All files in toolbox root minus those excluded by the ignore file and default exclusions. Use ToolboxOptions to determine this authoritatively. The ignore file may be named toolbox.ignore (R2026a and earlier) or package.ignore (R2026b+). Check for both — ToolboxOptions handles whichever is present.

Workflow

Phase 1 — Determine the Effective File Set

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

Do not reimplement ignore-file logic manually. ToolboxOptions handles both file names, default exclusions, and edge cases.

Phase 2 — Trace Dependencies

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

Apply Pitfall 1 (normalize paths) and Pitfall 2 (filter matlabroot) immediately after getting fList, before any classification.

Classify files in fList:

• Included: starts with toolboxRoot and in effective set
• Add-on: under fullfile(getenv('APPDATA'), 'MathWorks', 'MATLAB Add-Ons')
• External unresolved: everything else — requires user decision

Classify products from pList:

• Certain == 1: confirmed product dependency — declare in metadata
• Certain == 0: heuristic guess — flag for user confirmation

Check ignore conflicts: Files inside toolbox root that are in fList but NOT in effectiveFiles — code needs them but they won't ship.

Check runtime file references: fList never contains data files (.mat, .csv, images, etc.). Scan .m files for I/O functions with string-literal path arguments to detect files that code needs at runtime but won't ship. See references/runtime-file-references.md for the full function list, regex patterns, and classification logic.

Phase 2b — Detect Unresolved Symbols

requiredFilesAndProducts silently skips unresolvable symbols. A separate detection step is needed.

Do NOT rely on checkcode/codeIssues — MATLAB's static analyzer is intentionally lenient about unresolved functions.

For each file, extract candidate function names (via mtree or regex (?<![%.\w])([a-zA-Z]\w*)\s*\(). Filter out:

• MATLAB keywords (if, for, while, switch, function, arguments, end, return)
• The function's own name
• Local functions defined in the same file
• Variables in arguments blocks (validation syntax looks like function calls to regex)
• Functions from localfunctions pattern (test files)

For dotted identifiers (regex: ([a-zA-Z]\w*(?:\.[a-zA-Z]\w*)*)(?=\s*\()), apply Pitfall 3 — use which().

Classify unresolved symbols and present with resolution suggestions. See references/unresolved-symbol-classification.md for the full classification table and presentation format.

Phase 3 — Transitive Closure of External Files

For each external file, trace its dependency subtree. At each level classify children. Build the tree showing pull-in cost.

Early termination: If subtree exceeds ~15 files across multiple directories, mark as "sprawling" — needs architectural resolution, not file-by-file copying.

Deduplication: Use 'toponly' on each toolbox file to find which externals are directly called. Externals only reached transitively through another external are nested under their parent, not shown as top-level decisions.

Detect patterns: Multiple externals from same directory → group them. Parent folder has .prj or resources/project/ → belongs to a MATLAB Project.

Phase 4 — Present Results

Produce a tree view showing directly-called externals with call chains and transitive cost, plus a summary table. See references/tree-view-format.md for formatting guidance.

Phase 5 — Recommend Resolution Options

Present options with tradeoffs for each unresolved external or group. See references/resolution-options.md for the option matrix and outward-refactor handoff template.

This skill does not perform resolutions. It presents options so the user (or a downstream skill that handles toolbox structure) can act. Do not copy files, edit ignore files, or refactor code.

Phase 6 — Persist the Manifest

After the user acknowledges the analysis, save as buildUtilities/tbxManifest.m. The manifest records the current state — what ships, what's external, what's unresolved — not the resolution decisions. See scripts/tbxManifest-template.m for the template structure.

Output

• Primary artifact: buildUtilities/tbxManifest.m
• Display: Tree view + summary table + recommendations in conversation

Scope Boundary

This skill only analyzes and recommends. It does not:

• Copy or move files into the toolbox
• Edit ignore files
• Refactor code or fix typos
• Modify the MATLAB path

These actions are the user's responsibility or belong to a downstream skill that understands how the toolbox should be structured. After resolutions are applied externally, re-run this skill to confirm progress.

Key Rules

• Show the full transitive cost of pulling in any external
• Surface same-folder groups as one architectural decision, not N individual ones
• Present resolution options with tradeoffs — do not execute them
• After resolution (done externally), re-running should show progress (externals become included or add-on)
• Flag ignore conflicts — a needed-but-excluded file is a silent packaging bug

Next Steps

• /matlab-create-project — organize files into a MATLAB project with the resolved dependency structure

---

Copyright 2026 The MathWorks, Inc.

---