vba-analyze 0.1.0

Code analysis tools for analyzing VBA procedure call trees, dead code/root/leaf procedures, and procedures with same name in multiple modules.

vba-analyze

Code analysis tools for exploring VBA (Visual Basic for Applications) procedure scope and call relationships.

This project provides command-line tools to:

• Build call-tree reports (upstream/downstream)
• Identify dead, root, and leaf procedures
• Find procedures with the same name across multiple modules

What This Analyzes

The tools expect a directory containing exported VBA source code files (.bas, .cls, and .frm).

Installation

Requirements

• Python 3.14+

Install package

Using pip:

pip install vba-analyze

Using uv (preferred, installs globally - scripts available everywhere):

uv tool install vba-analyze

Command-Line Tools

Installing this package exposes three scripts:

• vbadrl
• vbasame
• vbatree

By default, reports are written to a vba_reports directory under the parent of the input directory unless --console is used.

1) vbadrl: Dead/Root/Leaf Procedure Report

Lists procedures by type:

• Dead code procedures (not called within project, scope prohibits being externally called)
• Root procedures (not called within project, can be externally called)
• Leaf procedures (does not call any procedure within project)

Basic usage:

vbadrl

• Analyzes VBA files in current directory
• Applies no filters
• Writes report to ..\vba_reports\vbadrl_report.txt

Common options:

• -i, --input_dir_path: Input VBA source code directory (default: current directory)
• -m, --module_filters: One or more module filters (supports wildcards)
• -c, --console: Print to console instead of writing a file
• -o, --output_dir_path: Output directory for report file
• -d, --exclude_dead: Exclude dead-code section
• -r, --exclude_root: Exclude root-procedure section
• -l, --exclude_leaf: Exclude leaf-procedure section

Examples:

vbadrl -i .\exports

• Analyzes VBA files in .\exports directory
• Applies no filters
• Writes report to .\vba_reports\vbadrl_report.txt

vbadrl -i .\exports -m Mod* Utility* -c

• Analyzes VBA files in .\exports directory
• Only examines files starting with Mod or starting with Utility
• Prints report to console

vbadrl -i .\exports -o .\reports -d

• Analyzes VBA files in .\exports directory
• Applies no filters
• Writes report to .\reports\vbadrl_report.txt
• Excludes dead code from report

2) vbasame: Procedures with Same Name in Multiple Modules

Lists procedures that share the same procedure name but are declared in different modules.

Basic usage:

vbasame

• Analyzes VBA files in current directory
• Applies no filters
• Writes report to ..\vba_reports\vbasame_report.txt

Common options:

• -i, --input_dir_path: Input VBA directory (default: current directory)
• -p, --procedure_filters: One or more procedure-name filters (supports wildcards)
• -c, --console: Print to console instead of writing a file
• -o, --output_dir_path: Output directory for report file

Examples:

vbasame -i .\exports

• Analyzes VBA files in .\exports directory
• Applies no filters
• Writes report to .\vba_reports\vbasame_report.txt

vbasame -i .\exports -p Send* Init* -c

• Analyzes VBA files in .\exports directory
• Only examines procedure that start with Send or Init
• Prints report to console

vbasame -i .\exports -o .\reports

• Analyzes VBA files in .\exports directory
• Applies no filters
• Only examines procedures that start with Send or Init
• Writes report to .\reports\vbasame_report.txt

3) vbatree: Procedure Call-Tree Reports

Generates procedure call trees with configurable direction:

• Downstream (default)
• Upstream
• Both

Output can be:

• One file per module (default)
• A single combined file (--single_file)
• Console output (--console)

Basic usage:

vbatree

Common options:

• -i, --input_dir_path: Input VBA directory (default: current directory)
• -m, --module_filters: One or more module filters (supports wildcards)
• -p, --procedure_filters: One or more procedure-name filters (supports wildcards)
• -n, --nest-depth: Maximum tree nest depth to display (default is 1).
• -d, --down: Include downstream calls
• -u, --up: Include upstream calls
• -c, --console: Print report to console
• -o, --output_dir_path: Output directory for report file(s)
• -s, --single_file: Write all report content to one file

Examples:

vbatree -i .\exports
vbatree -i .\exports -u -s -o ./reports
vbatree -i .\exports -m ModuleA* -p Process* -d -u -c

Typical Workflow

1. Compile the VBA project and ensure it is syntactically correct.
2. Export VBA modules/forms/classes from your host application (e.g., MS Excel IDE) into a directory.
3. Run one or more analyzers against that directory.
4. Review generated text reports in the console or vba_reports (or your custom output directory per --output_dir_path).

Sample Output Snippets

These are abbreviated examples of what each report looks like.

vbadrl sample

VBA Procedures by Type (Dead Code/Root/Leaf)
Report generated on: 2026-04-18 10:15:42
Input Path: C:\work\vba\exports
Module Filter(s): None
Output Path: C:\work\vba\vba_reports\vbadrl_report.txt

==================== Dead Code Procedures ==================
Qualified_Name                  Declare_Line  Is_Function  Is_Private  Is_Externally_Called
ModuleA.OrphanProc                       120  False        True        False

vbasame sample

VBA Procedures with Same Name in Multiple Modules
Report generated on: 2026-04-18 10:16:03
Input Path: C:\work\vba\exports
Procedure Filter(s): None
Output Path: C:\work\vba\vba_reports\vbasame_report.txt

==================== Same Name Procedures ==================
Procedure_Name.Module_Name      Declare_Line  Is_Function  Is_Private  Is_Externally_Called
Send.ModuleA                             55  True         True        False
Send.ModuleB                            178  True         False       False

vbatree sample

VBA Call Tree Report
Report generated on: 2026-04-18 10:17:11
Input Path: C:\work\vba\exports
Module Filter(s): None
Procedure Filter(s): ["Process*"]
Tree Depth Limit: 1

==================== Module: ModuleA ====================
ProcessOrder
├─ ValidateOrder
├─ CalculateTotals
└─ SaveOrder

Notes

• Path filters for modules and procedures support wildcard patterns.
• If no filters are provided, all discovered modules/procedures are analyzed.
• Reports are plain text and intended for quick review and diff-friendly workflows.

Limitations And Assumptions

• Input should be exported VBA source files on disk; this tool does not read directly from live Office project objects.
• Call relationships are derived from static source analysis and may not fully capture runtime-dynamic behavior (for example indirect dispatch patterns).
• Report semantics depend on parseable declarations/calls in the provided source; malformed or heavily nonstandard code can reduce accuracy.