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

Architecture

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

Data Flow

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

# Global installation
npm install -g @sfdxy/mule-lint

# Or as a dev dependency
npm install --save-dev @sfdxy/mule-lint

Quick Start

# 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

CLI Options

Quality Gates

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

Built-in Gates

Usage

# 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

Custom Gate Configuration

Add to your .mulelintrc.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" }
    ]
  }
}

Quality Ratings (A-E)

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

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%

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)

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)

Examples

# 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

Core Rules (MVP)

Extended Rules

DataWeave & API-Led Rules

Experimental Rules

2025-2026 Best Practices Rules (NEW)

Operations & Resilience Rules

Project Governance Rules

Total: 56 rules across 14 categories.

See Rules Catalog for detailed documentation.

Output Formats

Table (Default)

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

JSON

Machine-readable for scripting:

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

SARIF (For AI Agents)

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

{
  "$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": [...]
  }]
}

HTML (Interactive Dashboard)

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.

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

CSV (Spreadsheet)

Generates a comma-separated values file for Excel import:

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:

{
  "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:

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.

Features

• Tools: run_lint_analysis (scan project), get_rule_details (explain rule), validate_snippet (check XML/DWL).
• Resources: mule-lint://rules (list all available rules), mule-lint://docs/{slug} (best practices documentation).
• Prompts: analyze-project, explain-rule, fix-issue.

Setup for Claude Desktop

Add the following to your claude_desktop_config.json:

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

Setup for VS Code / Gemini Code Assist

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

{
  "servers": {
    "mule-lint": {
      "command": "npx",
      "args": ["-y", "@sfdxy/mule-lint", "mcp"]
    }
  }
}

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

Extending

Adding Custom Rules

See Extending Guide for detailed instructions on creating custom rules.

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

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

Credits

Contributing

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

License

MIT © 2024