Mule-Lint

Enterprise-grade static analysis tool for MuleSoft applications

Installation •
Quick Start •
Rules •
Output •
Configuration •
Extending

---

Overview

Mule-Lint is a TypeScript-based linting tool designed to enforce best practices and standards for MuleSoft applications. It provides:

- ✅ 56 Built-in Rules covering error handling, security, naming, logging, performance, and more
- ✅ Multiple Output Formats - Table, JSON, SARIF, HTML, CSV
- ✅ CI/CD Ready - Exit codes and machine-readable output
- ✅ 156+ Unit Tests - Comprehensive test coverage for reliability
- ✅ TypeScript - Fully typed for VS Code extension integration
- ✅ Extensible - Add custom rules for your organization

$3

``mermaid
flowchart TB
subgraph CLI["CLI Layer"]
A[npx @sfdxy/mule-lint command]
end

subgraph Engine["LintEngine"]
B[FileScanner] --> C[XmlParser]
C --> D[Rule Executor]
end

subgraph Rules["Rules - Strategy Pattern"]
D --> E[MULE-001]
D --> F[MULE-002]
D --> G[...]
D --> H[MULE-010]
end

subgraph Output["Formatters"]
I[Table]
J[JSON]
K[SARIF]
L[HTML Dashboard]
M[CSV]
end

subgraph HTMLStack["HTML Report Stack"]
L --> N[Tailwind CSS]
L --> O[Chart.js]
L --> P[Tabulator]
end

A --> B
D --> I
D --> J
D --> K
D --> L
D --> M
`

$3

`mermaid
flowchart LR
A["XML Files"] --> B["Parse DOM"]
B --> C["Execute Rules"]
C --> D["Collect Issues"]
D --> E["Format Output"]
E --> F["Table / JSON / SARIF / HTML / CSV"]
`


---

Installation

`bash


Global installation

npm install -g @sfdxy/mule-lint

Or as a dev dependency

npm install --save-dev @sfdxy/mule-lint
`

---

Quick Start

`bash


Scan a directory

npx @sfdxy/mule-lint ./src/main/mule

Scan a single file

npx @sfdxy/mule-lint ./src/main/mule/implementation.xml

Output as JSON

npx @sfdxy/mule-lint ./src/main/mule -f json

Output as SARIF (for AI agents/VS Code)

npx @sfdxy/mule-lint ./src/main/mule -f sarif > report.sarif

Write to file

npx @sfdxy/mule-lint ./src/main/mule -o report.txt

Fail on warnings (for CI/CD)

npx @sfdxy/mule-lint ./src/main/mule --fail-on-warning
`

$3

| Option | Description |
|--------|-------------|
| -f, --format | Output format: table, json, sarif, html, csv (default: table) |
| -o, --output | Write output to file instead of stdout |
| -c, --config | Path to configuration file |
| -q, --quiet | Show only errors (suppress warnings and info) |
| -e, --experimental | Enable experimental rules (opt-in) |
| -g, --quality-gate | Apply quality gate: default, strict, or config |
| --fail-on-warning | Exit with error code if warnings found |
| -v, --verbose | Show verbose output |

---

Quality Gates

Quality gates provide pass/fail thresholds for your CI/CD pipelines. When a gate fails, the tool exits with code 1.

$3

| Gate | Description |
|------|-------------|
| default | Fails if errors > 0, warnings > 10, complexity > 20, or security hotspots > 0 |
| strict | Fails if any errors, warnings > 0, or complexity > 10 |

$3

`bash


Apply default quality gate

npx @sfdxy/mule-lint ./src/main/mule -g default

Apply strict quality gate

npx @sfdxy/mule-lint ./src/main/mule -g strict

Use custom gate from config

npx @sfdxy/mule-lint ./src/main/mule -g config -c .mulelintrc.json
`

$3

Add to your .mulelintrc.json:

`json
{
"qualityGate": {
"name": "Custom Gate",
"conditions": [
{ "metric": "errors", "operator": ">", "threshold": 0, "status": "fail" },
{ "metric": "warnings", "operator": ">", "threshold": 5, "status": "warn" },
{ "metric": "complexity_max", "operator": ">", "threshold": 15, "status": "fail" }
]
}
}
`

$3

The HTML report displays quality ratings for four key dimensions. These follow industry-standard methodologies adapted for MuleSoft:

#### Complexity Rating

What it measures: Average cyclomatic complexity across all flows.

Calculation:
- Count decision points per flow: choice/when, foreach, try, scatter-gather, async, until-successful, error-handlers
- Base complexity = 1 + (total decision points)
- Rating = Average of all flow complexities

| Rating | Threshold | Interpretation |
|--------|-----------|----------------|
| A | Avg ≤ 5 | Simple, easy to test |
| B | Avg ≤ 10 | Moderate complexity |
| C | Avg ≤ 15 | Complex, consider splitting |
| D | Avg ≤ 20 | High complexity, refactor recommended |
| E | Avg > 20 | Very complex, critical refactoring needed |

#### Maintainability Rating

What it measures: Technical debt as a percentage of estimated development time.

Calculation:
- Debt minutes = (code smells × 5min) + (bugs × 15min) + (vulnerabilities × 30min)
- Development estimate = (flows × 10min) + (subflows × 5min), minimum 60min
- Debt Ratio = (Debt minutes / Development estimate) × 100%

| Rating | Debt Ratio | Interpretation |
|--------|-----------|----------------|
| A | ≤ 5% | Excellent maintainability |
| B | ≤ 10% | Good maintainability |
| C | ≤ 20% | Moderate technical debt |
| D | ≤ 50% | High debt, plan remediation |
| E | > 50% | Critical debt, immediate action needed |

#### Reliability Rating

What it measures: Number of bug-type issues detected.

Bug-type rules: All error-handling category rules are classified as bugs, including:
- Missing error handlers (MULE-003)
- Missing correlation ID (MULE-007)
- Generic error handling (MULE-009)
- HTTP status in error handlers (MULE-005)
- Global error handler (MULE-001)
- Try scope usage (ERR-001)

| Rating | Bug Count | Interpretation |
|--------|-----------|----------------|
| A | 0 bugs | No reliability issues |
| B | 1-2 bugs | Minor reliability concerns |
| C | 3-5 bugs | Moderate reliability risk |
| D | 6-10 bugs | High reliability risk |
| E | > 10 bugs | Critical reliability issues |

#### Security Rating

What it measures: Vulnerability and security hotspot count.

Vulnerability rules: All security category rules are classified as vulnerabilities, including:
- Hardcoded credentials (MULE-201)
- Insecure TLS (MULE-202)
- Plaintext secrets (YAML-004)
- Hardcoded URLs (MULE-004)
- TLS version check (SEC-002)
- Rate limiting (SEC-003)
- Input validation (SEC-004)

| Rating | Vulnerabilities | Interpretation |
|--------|-----------------|----------------|
| A | 0 vulns | Secure configuration |
| B | 1 vuln | Minor security finding |
| C | 2-3 vulns | Security review needed |
| D | 4-5 vulns | Security remediation required |
| E | > 5 vulns | Critical security issues |

$3

`bash


Basic scan

npx @sfdxy/mule-lint .

Scan with experimental rules

npx @sfdxy/mule-lint . --experimental

Output SARIF for VS Code

npx @sfdxy/mule-lint src/main/mule -f sarif -o results.sarif
`

---

Rules

$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| MULE-001 | Global Error Handler | Error | Error Handling | Project should have global error handler |
| MULE-002 | Flow Naming | Warning | Naming | Flows end with -flow, sub-flows with -subflow |
| MULE-003 | Missing Error Handler | Error | Error Handling | Flows should have error handlers |
| MULE-004 | Hardcoded URLs | Error | Security | Use property placeholders for URLs |
| MULE-005 | HTTP Status Check | Warning | Error Handling | Error handlers should set httpStatus |
| MULE-006 | Logger Category | Warning | Logging | Loggers should have category attribute |
| MULE-007 | Correlation ID | Warning | Error Handling | Error handlers should reference correlationId |
| MULE-008 | Choice Anti-Pattern | Warning | Standards | Avoid raise-error in otherwise |
| MULE-009 | Generic Error Type | Warning | Error Handling | Avoid catching type="ANY" |
| MULE-010 | DWL Standards | Info | Standards | Standard DataWeave files should exist |

$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| MULE-101 | Flow Casing | Warning | Naming | kebab-case for flows |
| MULE-102 | Variable Naming | Warning | Naming | camelCase for variables |
| MULE-201 | Hardcoded Credentials | Error | Security | Use ${secure::} |
| MULE-202 | Insecure TLS | Error | Security | No insecure="true" |
| MULE-301 | Logger Payload | Warning | Logging | Don't log entire payload |
| MULE-303 | Logger in Retry | Warning | Logging | Avoid loggers in until-successful |
| MULE-401 | HTTP User-Agent | Warning | HTTP | Include User-Agent |
| MULE-402 | HTTP Content-Type | Warning | HTTP | POST/PUT needs Content-Type |
| MULE-403 | HTTP Timeout | Warning | HTTP | Set responseTimeout |
| MULE-501 | Scatter-Gather | Info | Performance | Limit parallel routes |
| MULE-502 | Async Error | Warning | Performance | Async needs error handling |
| MULE-503 | Large Choice | Warning | Performance | Max 7 when clauses |
| MULE-601 | Flow Description | Info | Documentation | Add doc:description |
| MULE-604 | Missing doc:name | Warning | Documentation | Key components need doc:name |
| MULE-701 | Deprecated | Warning | Standards | Detect deprecated elements |
| MULE-801 | Flow Complexity | Warning | Complexity | Cyclomatic complexity threshold |
| MULE-802 | Project Structure | Warning | Structure | Validate folder structure |
| MULE-803 | Global Config | Warning | Structure | global.xml should exist |
| MULE-804 | Monolithic XML | Warning | Structure | Split large XML files |

$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| DW-001 | External DWL | Warning | DataWeave | Externalize complex transforms |
| DW-002 | DWL Naming | Info | DataWeave | kebab-case for .dwl files |
| DW-003 | DWL Modules | Info | DataWeave | Use common modules |
| API-001 | Experience Layer | Info | API-Led | Experience API patterns |
| API-002 | Process Layer | Info | API-Led | Process layer orchestration |
| API-003 | System Layer | Info | API-Led | System layer connections |
| API-004 | Single SAPI | Warning | API-Led | Single system per SAPI |

$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| EXP-001 | Flow Ref Depth | Info | Experimental | Limit flow-ref chains |
| EXP-002 | Config Naming | Info | Experimental | Connector config naming |
| EXP-003 | MUnit Coverage | Info | Experimental | Check for MUnit tests |
| YAML-001 | Env Files | Warning | Standards | Environment YAML files |
| YAML-003 | Property Naming | Info | Standards | Property key format |


$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| SEC-002 | TLS Version | Error | Security | Detect deprecated TLS versions (< 1.2) |
| SEC-003 | Rate Limiting | Warning | Security | APIs should have rate limiting configured |
| SEC-004 | Input Validation | Warning | Security | Incoming payloads should be validated |
| LOG-001 | Structured Logging | Info | Logging | Recommend JSON logger format |
| LOG-004 | Sensitive Data Logging | Error | Logging | Detect PII/secrets in log statements |
| ERR-001 | Try Scope | Info | Error Handling | Complex operations should use Try scope |
| PERF-002 | Connection Pooling | Warning | Performance | DB/HTTP should configure connection pools |

$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| RES-001 | Reconnection Strategy | Warning | Performance | Connectors should have reconnection strategies |
| OPS-001 | Auto-Discovery | Info | Standards | APIs should have auto-discovery for API Manager |
| OPS-002 | HTTP Port Placeholder | Warning | Standards | HTTP ports should use property placeholders |
| OPS-003 | Externalized Cron | Warning | Standards | Cron expressions should use placeholders |
| SEC-006 | Encryption Key in Logs | Error | Security | Detect sensitive data in log messages |
| HYG-001 | Excessive Loggers | Warning | Logging | Flows should not have too many loggers |
| HYG-002 | Commented Code | Info | Standards | Detect commented-out code blocks |
| HYG-003 | Unused Flow | Warning | Standards | Detect flows/sub-flows never referenced |
| API-005 | APIKit Validation | Info | Standards | APIs should use APIKit for interfaces |
| DOC-001 | Display Name | Info | Documentation | Key components should have meaningful names |

$3

| ID | Name | Severity | Category | Description |
|----|------|----------|----------|-------------|
| PROJ-001 | POM Validation | Error | Structure | Validates pom.xml existence and plugins |
| PROJ-002 | Git Hygiene | Warning | Structure | Validates .gitignore existence and entries |

Total: 56 rules across 14 categories.

See Rules Catalog for detailed documentation.

---

Output Formats

$3

Human-readable colorized output:

`
Mule-Lint Report
Scanned 5 files in 123ms

src/main/mule/impl.xml
45:0 error Flow "getOrders" is missing an error handler (MULE-003)
67:0 warning Logger is missing 'category' attribute (MULE-006)

Summary:
Errors: 1
Warnings: 1
Infos: 0
`

$3

Machine-readable for scripting:

`json
[
{
"filePath": "/path/to/impl.xml",
"line": 45,
"message": "Flow \"getOrders\" is missing an error handler",
"ruleId": "MULE-003",
"severity": "error"
}
]
`

$3

SARIF 2.1.0 format for VS Code, GitHub, and AI agents:

`json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [{
"tool": {
"driver": {
"name": "@sfdxy/mule-lint",
"version": "1.0.0"
}
},
"results": [...]
}]
}
`

$3

Generates a modern, interactive single-page report with:

- Dashboard View: Summary cards, severity donut chart, top violated rules bar chart, issues by category
- Issues Browser: Full-width searchable table with multiselect filters
- Frozen Headers: Table header stays visible when scrolling
- Export: Download filtered results as CSV
- Responsive: Works on desktop and mobile

Built with Tailwind CSS, Chart.js, and Tabulator.

!HTML Report Dashboard

`bash
npx @sfdxy/mule-lint src/main/mule -f html -o report.html
`

$3

Generates a comma-separated values file for Excel import:

`csv
Severity,Rule,File,Line,Column,Message
error,MULE-001,src/main/mule/app.xml,10,5,"Global Error Handler missing"
warning,MULE-002,src/main/mule/app.xml,15,4,"Flow name not kebab-case"
`

---

Configuration

Create a .mulelintrc.json file in your project root:

`json
{
"rules": {
"MULE-001": { "enabled": true },
"MULE-002": {
"enabled": true,
"options": {
"flowSuffix": "-flow",
"subflowSuffix": "-subflow",
"excludePatterns": ["*-api-main"]
}
},
"MULE-006": {
"enabled": true,
"severity": "error",
"options": {
"requiredPrefix": "com.myorg"
}
}
},
"include": ["src/main/mule/*/.xml"],
"exclude": ["/test/", "*/.munit.xml"],
"failOnWarning": false
}
`

---

Using as a Library

Import directly into your TypeScript/JavaScript projects:

`typescript
import { LintEngine, ALL_RULES, formatSarif } from '@sfdxy/mule-lint';

// Create engine with all rules
const engine = new LintEngine({
rules: ALL_RULES,
config: {
include: ['src/main/mule/*/.xml'],
},
});

// Scan a project
const report = await engine.scan('./my-mule-project');
console.log(formatSarif(report));

// Scan content directly (useful for VS Code extensions)
const issues = engine.scanContent(xmlContent, 'file.xml');
`

---

AI Agent Integration (MCP)

This tool exposes a Model Context Protocol (MCP) server, allowing AI agents (like Claude Desktop, IDE assistants) to directly interact with the linter to discover rules, scan projects, and explain violations.

$3


- Tools: run_lint_analysis (scan project), get_rule_details (explain rule), validate_snippet (check XML/DWL).
- Resources: mule-lint://rules (list all available rules).

$3

Add the following to your claude_desktop_config.json:

`json
{
"mcpServers": {
"mule-lint": {
"command": "npx",
"args": ["-y", "--package=@sfdxy/mule-lint", "mule-lint-mcp"]
}
}
}
`

$3

Create a .vscode/mcp.json file in your project root:

`json
{
"mule-lint": {
"command": "npx",
"args": ["-y", "--package=@sfdxy/mule-lint", "mule-lint-mcp"]
}
}
`

The agent will now be able to "see" your MuleSoft project structure and offer linting actions autonomously.

---

Extending

$3

See Extending Guide for detailed instructions on creating custom rules.

`typescript
import { BaseRule, ValidationContext, Issue } from '@sfdxy/mule-lint';

export class MyCustomRule extends BaseRule {
id = 'CUSTOM-001';
name = 'My Custom Rule';
description = 'Enforces my organization standards';
severity = 'warning' as const;
category = 'standards' as const;

validate(doc: Document, context: ValidationContext): Issue[] {
// Your validation logic using XPath
const flows = this.select('//mule:flow', doc);
// ...
}
}
`

---

Project Inspiration

This project is inspired by and builds upon the ideas from:

- mule-lint/mule-lint - The original Groovy-based MuleSoft linting tool with DSL-based rule definitions

While the original project uses Groovy and a custom DSL, this TypeScript implementation was created to:
- Enable easier VS Code extension integration
- Provide better AI agent compatibility via SARIF output
- Leverage the modern npm ecosystem
- Offer simpler CI/CD integration

---

Documentation

| Document | Description |
|----------|-------------|
| Architecture | System design and data flow |
| Rules Catalog | Complete list of all rules |
| Best Practices | MuleSoft development guidelines |
| Extending | How to add custom rules |
| Naming Conventions | Code style guide |

---

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Lint

npm run lint
``

---

Credits

Built with AI Assistance This project was developed with the assistance of: 🚀 Antigravity (Google DeepMind) 🤖 GitHub Copilot

---

Contributing

Contributions are welcome! Please read the Contributing Guide for details.

---

License

MIT © 2024