Metadata-Version: 2.4
Name: vba-analyze
Version: 0.1.0
Summary: Code analysis tools for analyzing VBA procedure call trees, dead code/root/leaf procedures, and procedures with same name in multiple modules.
Author-email: Steven Schmitt <pypi.sheep797@passmail.net>
License-Expression: MIT
Keywords: Call Tree,Excel,Tree,VBA
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Visual Basic
Requires-Python: >=3.14
Requires-Dist: pathvalidate>=3.3.1
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```text
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

```text
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

```text
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.
