Metadata-Version: 2.4
Name: mule-flow-analyzer
Version: 1.0.0
Summary: A tool for analyzing Mule integration projects to generate sequence diagrams or natural language descriptions of each flow
Author-email: Brad McNaughton <hello@bradmcnaughton.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/bradmcnaughton/mule-flow-analyzer
Project-URL: Bug Tracker, https://github.com/bradmcnaughton/mule-flow-analyzer/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xmltodict
Requires-Dist: pyyaml
Requires-Dist: plantweb
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# Mule Flow Analyzer

A library for analyzing Mule integration projects to generate sequence diagrams or natural language descriptions of each flow.

Before analysis, placeholders in code will attempt to be replaced using values from the property files in the project directory. If there are multiple properties files, you can supply a hierarchy to follow and any omitted properties will not be referenced. This can be helpful if multiple environment property files are in the project.

Depending on your output format, text files and/or diagrams will be generated with file names based on the flow name (with special characters replaced with underscores).

## Table of Contents

- [Example Outputs](#example-outputs)
- [Installation](#installation)
- [IDE agent skill (VS Code / GitHub Copilot)](#ide-agent-skill-vs-code--github-copilot)
- [Diagram Generation](#diagram-generation)
- [Overriding Configuration](#overriding-configuration)
- [Instructions for LLMs](#instructions-for-llms)
- [Troubleshooting](#troubleshooting)

## Example Outputs

Real examples generated by this project are copied under `docs/examples/plantuml/`.

### Nested Flow Refs

![analyzer-test-nested-flowrefs](https://raw.githubusercontent.com/bradmcnaughton/mule-flow-analyzer/main/docs/examples/plantuml/analyzer-test-nested-flowrefs.png)

Full UML source: [`docs/examples/plantuml/analyzer-test-nested-flowrefs.txt`](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/docs/examples/plantuml/analyzer-test-nested-flowrefs.txt)

```plantuml
box #LightBlue-6FBBD3
participant "http:basic-security-filter\n[Basic security filter]"
participant "ee:transform\n[Set Variable: myMainVar1]"
participant "ee:transform\n[Set Variable: mySubflowVar]"
participant "ee:transform\n[Set Variable: myMainVar2]"
participant "ee:transform\n[Set Variable: mySubflowVar2]"
participant "sftp:read\n[Read File for Payload]"
participant "set-payload\n[Set Payload]"
end box
participant "<size:30><&globe>\nHTTP" as HTTP
participant "<size:30><&file>\nLocalFileServer SFTP" as LocalFileServer
title analyzer-test-nested-flowrefs
 -> "http:basic-security-filter\n[Basic security filter]" :
"http:basic-security-filter\n[Basic security filter]" -> "HTTP" : HTTP Request (Basic security filter)
"HTTP" --> "http:basic-security-filter\n[Basic security filter]" :
```

### Nested Flow Refs (`create_mode: true`)

![analyzer-test-nested-flowrefs-create-mode-true](https://raw.githubusercontent.com/bradmcnaughton/mule-flow-analyzer/main/docs/examples/plantuml/analyzer-test-nested-flowrefs-create-mode-true.png)

Full UML source: [`docs/examples/plantuml/analyzer-test-nested-flowrefs-create-mode-true.txt`](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/docs/examples/plantuml/analyzer-test-nested-flowrefs-create-mode-true.txt)

```plantuml
box #LightBlue-6FBBD3
participant "http:basic-security-filter\n[Basic security filter]"
participant "ee:transform\n[Set Variable: myMainVar1]"
participant "ee:transform\n[Set Variable: mySubflowVar]"
participant "ee:transform\n[Set Variable: myMainVar2]"
participant "ee:transform\n[Set Variable: mySubflowVar2]"
participant "sftp:read\n[Read File for Payload]"
participant "set-payload\n[Set Payload]"
end box
participant "<size:30><&globe>\nHTTP" as HTTP
participant "<size:30><&file>\nLocalFileServer SFTP" as LocalFileServer
title analyzer-test-nested-flowrefs
 -> "http:basic-security-filter\n[Basic security filter]" ** :
"http:basic-security-filter\n[Basic security filter]" -> "HTTP" ** : HTTP Request (Basic security filter)
"HTTP" --> "http:basic-security-filter\n[Basic security filter]" :
```

### Anypoint MQ Queues

![anypoint-mq-queues](https://raw.githubusercontent.com/bradmcnaughton/mule-flow-analyzer/main/docs/examples/plantuml/anypoint-mq-queues.png)

Full UML source: [`docs/examples/plantuml/anypoint-mq-queues.txt`](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/docs/examples/plantuml/anypoint-mq-queues.txt)

```plantuml
queue "Queue\nmy-test-subscription"
box #LightBlue-6FBBD3
participant "anypoint-mq:subscriber\n[Subscriber]"
participant "anypoint-mq:consume\n[Consume]"
participant "anypoint-mq:publish\n[Publish]"
end box
queue "Queue\nmy-test-queue"
queue "Queue\nmy-destination"
'source event
"Queue\nmy-test-subscription" -> "anypoint-mq:subscriber\n[Subscriber]" : Message (my-test-subscription)
title anypoint-mq-queues
"anypoint-mq:subscriber\n[Subscriber]" -> "anypoint-mq:consume\n[Consume]" :
"anypoint-mq:consume\n[Consume]" -> "Queue\nmy-test-queue" : Message (my-test-queue)
"Queue\nmy-test-queue" --> "anypoint-mq:consume\n[Consume]" :
"anypoint-mq:consume\n[Consume]" -> "anypoint-mq:publish\n[Publish]" :
```

### Async Operation

![async-operation](https://raw.githubusercontent.com/bradmcnaughton/mule-flow-analyzer/main/docs/examples/plantuml/async-operation.png)

Full UML source: [`docs/examples/plantuml/async-operation.txt`](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/docs/examples/plantuml/async-operation.txt)

```plantuml
participant "<size:30><color:#00A1E0><&cloud>\nExperience Cloud" as Experience
box #LightBlue-6FBBD3
participant "salesforce:subscribe-channel-listener\n[Subscribe channel listener]"
participant "db:insert\n[Insert Subscription]"
participant "set-variable\n[customerId]"
participant "email:send\n[New Subscription Email]"
participant "db:update\n[Update Subscription Emails]"
participant "salesforce:delete\n[Delete Subscription]"
end box
database "Database\nA"
participant "<size:30><&envelope-closed>\nSMTP" as Email
participant "<size:30><color:#00A1E0><&cloud>\nExperience Cloud" as Experience_4
'source event
"Experience" -> "salesforce:subscribe-channel-listener\n[Subscribe channel listener]" : subscribe-channel-listener
title async-operation
```

## Installation

Install from [PyPI](https://pypi.org/project/mule-flow-analyzer/):

```bash
pip install mule-flow-analyzer
```

To install a specific version:

```bash
pip install mule-flow-analyzer==1.0.0
```

For development, clone the repository and install in editable mode with test dependencies:

```bash
pip install -e ".[dev]"
```

## IDE agent skill (VS Code / GitHub Copilot)

This repo ships an [Agent Skill](https://code.visualstudio.com/docs/copilot/customization/agent-skills) for analyzing flows from inside a Mule workspace using Copilot or compatible agents.

**Where it lives here:** [`.cursor/skills/mule-flow-analyzer/`](https://github.com/bradmcnaughton/mule-flow-analyzer/tree/main/.cursor/skills/mule-flow-analyzer/) (`SKILL.md` plus [`scripts/run_analyzer.py`](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/.cursor/skills/mule-flow-analyzer/scripts/run_analyzer.py)).

**Where to use it:** Copy the whole `mule-flow-analyzer` folder into a skill discovery location used by your IDE/agent. This can be inside your Mule application repository (the project that contains `src/main/mule/`) **or** in a shared/global skills directory configured in your IDE. Do not rely on this library clone for analyzing your apps unless you open that app as the workspace. Examples:

- `.github/skills/mule-flow-analyzer/` (commonly used by GitHub Copilot in VS Code), or
- `.cursor/skills/mule-flow-analyzer/` in the target workspace, or
- any shared/global folder configured for skill discovery (for example via `chat.skillsLocations`).

The `name` field in `SKILL.md` must match the parent directory name (`mule-flow-analyzer`). After copying, install the package in a venv (`pip install mule-flow-analyzer`) and run the helper from the Mule app root; see the script’s `--help` for flags.

## Diagram Generation

Sequence diagram generation supports two syntax engines. PlantUML is the recommended output format for sequence diagrams.

- `plantuml` (default): writes PlantUML source and can render PNG/SVG through a server, local JAR, or CLI.
- `mermaid` (experimental): writes Mermaid `.mmd` source and can optionally render through Mermaid CLI.

Select the engine with `analyzer_properties.diagram_engine`. Existing configurations continue to use PlantUML by default.

### PlantUML

PlantUML image generation supports three rendering approaches:

- `server`: HTTP PlantUML server URL (local Docker-hosted or hosted service)
- `jar`: local `java -jar plantuml.jar` execution (offline, no Docker)
- `cli`: local `plantuml` command execution (offline)

If no mode is explicitly set, the library defaults to `server` mode for backward compatibility.

### Running the PlantUML server locally with Docker

No Mule application source is required to be sent to a public server, only the generated UML. If you don't want to send the UML to a public server, you can run the PlantUML server locally.

Pull the PlantUML server image:

```bash
docker pull plantuml/plantuml-server
```

Run the PlantUML server. (In this example, the server will be available on port 8087)

```bash
docker run -d -p 8087:8080 plantuml/plantuml-server:jetty
```

Use `server` mode with `http://localhost:8087/`:

```yaml
analyzer_properties:
  plantuml:
    mode: "server"
    server: "http://localhost:8087/"
    format: "png"
    output_directory: "./output/plantuml"
```

### Running with local PlantUML JAR (no Docker, offline)

Requirements:

- Java installed and on `PATH`
- `plantuml.jar` downloaded locally (for example `./tools/plantuml.jar`)

Use `jar` mode:

```yaml
analyzer_properties:
  plantuml:
    mode: "jar"
    java_command: "java"
    jar_path: "./tools/plantuml.jar"
    format: "png"
    output_directory: "./output/plantuml"
```

### Running with local PlantUML CLI (offline)

If `plantuml` is installed as a command:

```yaml
analyzer_properties:
  plantuml:
    mode: "cli"
    cli_command: "plantuml"
    format: "png"
    output_directory: "./output/plantuml"
```

### Quick validation commands

Check local server:

```bash
curl -I http://localhost:8087/
```

Check Java:

```bash
java -version
```

Check PlantUML CLI:

```bash
plantuml -version
```

Refer to [Overriding Configuration](#overriding-configuration) for full configuration details.

### Mermaid

Mermaid support is experimental. PlantUML is the recommended sequence diagram output because it has the most complete mapping for Mule flow constructs and formatting.

Mermaid output can still be useful when you want syntax that can be rendered by GitHub, GitLab, documentation tools, editor extensions, or Mermaid CLI.

By default, Mermaid mode writes source only:

```yaml
analyzer_properties:
  diagram_engine: "mermaid"
  mermaid:
    mode: "file"
    output_directory: "./output/mermaid"
    source_extension: "mmd"
```

To render with Mermaid CLI, install `@mermaid-js/mermaid-cli` and use `cli` mode:

```bash
npm install -g @mermaid-js/mermaid-cli
mmdc --version
```

```yaml
analyzer_properties:
  diagram_engine: "mermaid"
  mermaid:
    mode: "cli"
    cli_command: "mmdc"
    format: "svg"
    output_directory: "./output/mermaid"
```

Mermaid support intentionally degrades PlantUML-only features. Custom PlantUML actor icons, `skinparam`, scale settings, colored arrows, colored notes/groups, and the generated PlantUML legend do not have direct Mermaid equivalents.

## Overriding Configuration

For detailed configuration options, see [Configuration Documentation](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/docs/configuration.md).

## Instructions for LLMs

LLMs can be shown the [python usage instructions](https://github.com/bradmcnaughton/mule-flow-analyzer/blob/main/docs/python_usage.md) to help them generate code.

## Troubleshooting

If you encounter an error, check the log file for more information. The default path in configuration metadata is `mfa-logs/mule_flow_analyzer.log` (relative to the process working directory where Python is run). Override it under `analyzer_properties.logging.file` in your merged configuration or YAML.

If the log file is not found, check the default properties file for the correct path.

The log level can be set to DEBUG to get more information in the configuration file.
