@sfdxy/mule-lint 1.18.1 → 1.20.0

package/docs/best-practices/rules-catalog.md

@@ -30,38 +30,38 @@
 
 ## Rule Categories
 
-| Family | Prefix | Count | Description |
-|--------|--------|-------|-------------|
-| Error Handling | MULE-001/003/005/007/009, ERR-001 | 6 | Error handler configuration and best practices |
-| Naming | MULE-002/101/102 | 3 | Naming conventions for flows and variables |
-| Security | MULE-004/201/202, SEC-002/003/004/006 | 7 | Security vulnerabilities, TLS, rate limiting |
-| Logging | MULE-006/301/303, LOG-001/004, HYG-001 | 6 | Logging standards, structured logging, hygiene |
-| HTTP | MULE-401/402/403 | 3 | HTTP configuration and headers |
-| Performance | MULE-501/502/503, PERF-002, RES-001 | 5 | Performance anti-patterns and resilience |
-| Documentation | MULE-601/604, DOC-001 | 3 | Documentation requirements |
-| Standards | MULE-008/010/701, OPS-001/002/003, API-005 | 7 | Coding standards and operations |
-| Complexity | MULE-801 | 1 | Code complexity |
-| Structure | MULE-802/803/804 | 3 | Project structure |
-| YAML | YAML-001/003/004 | 3 | YAML configuration validation |
-| DataWeave | DW-001/002/003/004 | 4 | DataWeave file validation |
-| API-Led | API-001/002/003/004 | 4 | API-Led connectivity patterns |
-| Governance | PROJ-001/002 | 2 | POM and Git hygiene |
-| Code Hygiene | HYG-002/003 | 2 | Commented code and unused flows |
-| Experimental | EXP-001/002/003 | 3 | Beta rules for evaluation |
+| Family         | Prefix                                     | Count | Description                                    |
+| -------------- | ------------------------------------------ | ----- | ---------------------------------------------- |
+| Error Handling | MULE-001/003/005/007/009, ERR-001          | 6     | Error handler configuration and best practices |
+| Naming         | MULE-002/101/102                           | 3     | Naming conventions for flows and variables     |
+| Security       | MULE-004/201/202, SEC-002/003/004/006      | 7     | Security vulnerabilities, TLS, rate limiting   |
+| Logging        | MULE-006/301/303, LOG-001/004, HYG-001     | 6     | Logging standards, structured logging, hygiene |
+| HTTP           | MULE-401/402/403                           | 3     | HTTP configuration and headers                 |
+| Performance    | MULE-501/502/503, PERF-002, RES-001        | 5     | Performance anti-patterns and resilience       |
+| Documentation  | MULE-601/604, DOC-001                      | 3     | Documentation requirements                     |
+| Standards      | MULE-008/010/701, OPS-001/002/003, API-005 | 7     | Coding standards and operations                |
+| Complexity     | MULE-801                                   | 1     | Code complexity                                |
+| Structure      | MULE-802/803/804                           | 3     | Project structure                              |
+| YAML           | YAML-001/003/004                           | 3     | YAML configuration validation                  |
+| DataWeave      | DW-001/002/003/004                         | 4     | DataWeave file validation                      |
+| API-Led        | API-001/002/003/004                        | 4     | API-Led connectivity patterns                  |
+| Governance     | PROJ-001/002                               | 2     | POM and Git hygiene                            |
+| Code Hygiene   | HYG-002/003                                | 2     | Commented code and unused flows                |
+| Experimental   | EXP-001/002/003                            | 3     | Beta rules for evaluation                      |
 
 ### MULE Category ID Ranges
 
-| Range | Category | Description |
-|-------|----------|-------------|
-| 001-099 | Error Handling | Error handler configuration and best practices |
-| 100-199 | Naming | Naming conventions for flows, variables, files |
-| 200-299 | Security | Security vulnerabilities and hardcoded values |
-| 300-399 | Logging | Logging standards and structured logging |
-| 400-499 | HTTP | HTTP configuration and headers |
-| 500-599 | Performance | Performance anti-patterns |
-| 600-699 | Documentation | Documentation requirements |
-| 700-799 | Standards | General coding standards |
-| 800-899 | Complexity/Structure | Code complexity and project structure |
+| Range   | Category             | Description                                    |
+| ------- | -------------------- | ---------------------------------------------- |
+| 001-099 | Error Handling       | Error handler configuration and best practices |
+| 100-199 | Naming               | Naming conventions for flows, variables, files |
+| 200-299 | Security             | Security vulnerabilities and hardcoded values  |
+| 300-399 | Logging              | Logging standards and structured logging       |
+| 400-499 | HTTP                 | HTTP configuration and headers                 |
+| 500-599 | Performance          | Performance anti-patterns                      |
+| 600-699 | Documentation        | Documentation requirements                     |
+| 700-799 | Standards            | General coding standards                       |
+| 800-899 | Complexity/Structure | Code complexity and project structure          |
 
 ---
 
@@ -73,17 +73,26 @@
 
 ### MULE-001: Global Error Handler Exists
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value          |
+| ------------ | -------------- |
+| **Severity** | Warning        |
 | **Category** | Error Handling |
-| **Fixable** | No |
+| **Fixable**  | No             |
 
-**Description:** Every Mule project should have a global error handler file with a reusable error-handler configuration.
+**Description:** Every Mule project should have a global error handler — either a dedicated file (`src/main/mule/global-error-handler.xml` by default) **or** any XML flow file that contains a named `<error-handler>` element.
 
 **Check Logic:**
-1. Verify file exists: `src/main/mule/global-error-handler.xml`
-2. Verify contains: `<error-handler name="global-error-handler">`
+
+1. If the expected file exists (`src/main/mule/global-error-handler.xml`), the rule passes.
+2. Otherwise, checks each flow file for a named `<error-handler name="...">` or `<error-handler ref="...">` element.
+3. If neither is found in a flow file (a file containing `<flow>` or `<sub-flow>` elements), a warning is reported.
+4. Pure configuration files (no flows) are skipped to reduce noise.
+
+**Options:**
+
+| Option     | Default                                  | Description                    |
+| ---------- | ---------------------------------------- | ------------------------------ |
+| `filePath` | `src/main/mule/global-error-handler.xml` | Relative path to expected file |
 
 **Why This Matters:** A global error handler ensures consistent error responses across all flows and reduces code duplication.
 
@@ -91,15 +100,16 @@
 
 ### MULE-003: Missing Error Handler
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value          |
+| ------------ | -------------- |
+| **Severity** | Error          |
 | **Category** | Error Handling |
-| **Fixable** | No |
+| **Fixable**  | No             |
 
 **Description:** Every flow should have an error handler or reference the global one.
 
 **XPath:**
+
 ```xpath
 //mule:flow[not(mule:error-handler) and not(contains(@name, 'api-main'))]
 ```
@@ -108,37 +118,63 @@
 
 ### MULE-005: HTTP Status in Error Handler
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value          |
+| ------------ | -------------- |
+| **Severity** | Warning        |
 | **Category** | Error Handling |
-| **Fixable** | No |
+| **Fixable**  | No             |
 
 **Description:** Error handlers should set an `httpStatus` variable for proper API responses.
 
+**Project Detection:** This rule is automatically skipped for non-HTTP projects. When `mule-lint` scans a project, it detects whether any `http:listener` or `apikit:router` element is present. If neither is found, the rule is suppressed to avoid false positives in event-driven or batch Mule applications.
+
+**Options:**
+
+| Option         | Default      | Description                 |
+| -------------- | ------------ | --------------------------- |
+| `variableName` | `httpStatus` | Name of the variable to set |
+
 **Best Practice:** Always set httpStatus in error handlers to return appropriate HTTP codes (400, 404, 500, etc.).
 
 ---
 
 ### MULE-007: Correlation ID in Error Handler
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value          |
+| ------------ | -------------- |
+| **Severity** | Warning        |
 | **Category** | Error Handling |
-| **Fixable** | No |
+| **Fixable**  | No             |
 
 **Description:** Error handlers should reference `correlationId` for traceability across distributed systems.
 
+**Check Logic:**
+
+1. Checks inline XML text and attributes for correlation ID patterns (`correlationId`, `correlation_id`, `x-correlation-id`, `x-request-id`, etc.)
+2. For `ee:set-payload` elements with a `resource="..."` attribute, reads the referenced `.dwl` file from `src/main/resources/<resourcePath>` and checks its content.
+3. If a resource file is referenced but cannot be read (e.g. not yet generated), downgrades to `info` severity to avoid false positives.
+
+**Example (inline):**
+
+```xml
+<on-error-continue>
+  <ee:transform>
+    <ee:set-payload resource="classpath:dwl/error-response.dwl"/>
+  </ee:transform>
+</on-error-continue>
+```
+
+The DWL file at `src/main/resources/dwl/error-response.dwl` will be checked for `correlationId` usage.
+
 ---
 
 ### MULE-009: Generic Error Type
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value          |
+| ------------ | -------------- |
+| **Severity** | Warning        |
 | **Category** | Error Handling |
-| **Fixable** | No |
+| **Fixable**  | No             |
 
 **Description:** Avoid catching `type="ANY"` in error handlers. Be specific about error types.
 
@@ -148,18 +184,19 @@
 
 ### ERR-001: Try Scope Best Practice
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
-| **Category** | Error Handling |
-| **Issue Type** | Bug |
-| **Fixable** | No |
+| Property       | Value          |
+| -------------- | -------------- |
+| **Severity**   | Info           |
+| **Category**   | Error Handling |
+| **Issue Type** | Bug            |
+| **Fixable**    | No             |
 
 **Description:** Complex operations (DB calls, HTTP requests) should use Try scope for granular error isolation and handling.
 
 **Check Logic:** Flags flows that have 2+ external calls (HTTP requests, DB operations) without any Try scope wrapping them.
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad - multiple calls without Try -->
 <flow name="process-order-flow">
@@ -188,15 +225,16 @@
 
 ### MULE-002: Flow Naming Convention
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
-| **Category** | Naming |
-| **Fixable** | Yes |
+| **Category** | Naming  |
+| **Fixable**  | Yes     |
 
-**Description:** Flows must end with `-flow` suffix, sub-flows with `-subflow`.
+**Description:** Flows must end with `-flow` suffix, sub-flows with `-subflow`. Both flow and sub-flow naming are enforced by this rule.
 
 **Examples:**
+
 ```xml
 <!-- ✅ Good -->
 <flow name="process-order-flow">
@@ -207,19 +245,28 @@
 <sub-flow name="validateInput">
 ```
 
+**Options:**
+
+| Option            | Default                                            | Description                               |
+| ----------------- | -------------------------------------------------- | ----------------------------------------- |
+| `flowSuffix`      | `-flow`                                            | Required suffix for `<flow>` elements     |
+| `subflowSuffix`   | `-subflow`                                         | Required suffix for `<sub-flow>` elements |
+| `excludePatterns` | `['*-api-main', '*-main', 'get:*', 'post:*', ...]` | Glob patterns to skip                     |
+
 ---
 
 ### MULE-101: Flow Name Casing
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
-| **Category** | Naming |
-| **Fixable** | No |
+| **Category** | Naming  |
+| **Fixable**  | No      |
 
 **Description:** Flow names should follow consistent casing (kebab-case recommended).
 
 **Options:**
+
 - `kebab-case`: `my-flow-name` (recommended)
 - `camelCase`: `myFlowName`
 - `snake_case`: `my_flow_name`
@@ -228,11 +275,11 @@
 
 ### MULE-102: Variable Naming Convention
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
-| **Category** | Naming |
-| **Fixable** | No |
+| **Category** | Naming  |
+| **Fixable**  | No      |
 
 **Description:** Variables set via `set-variable` should follow camelCase naming.
 
@@ -244,15 +291,16 @@
 
 ### MULE-004: Hardcoded HTTP URLs
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value    |
+| ------------ | -------- |
+| **Severity** | Error    |
 | **Category** | Security |
-| **Fixable** | No |
+| **Fixable**  | No       |
 
 **Description:** HTTP/HTTPS URLs should use property placeholders, not hardcoded values.
 
 **Examples:**
+
 ```xml
 <!-- ❌ Bad -->
 <http:request url="https://api.example.com/orders" />
@@ -265,11 +313,11 @@
 
 ### MULE-201: Hardcoded Credentials
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value    |
+| ------------ | -------- |
+| **Severity** | Error    |
 | **Category** | Security |
-| **Fixable** | No |
+| **Fixable**  | No       |
 
 **Description:** Passwords and secrets should never be hardcoded. Use secure properties.
 
@@ -279,11 +327,11 @@
 
 ### MULE-202: Insecure TLS Configuration
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value    |
+| ------------ | -------- |
+| **Severity** | Error    |
 | **Category** | Security |
-| **Fixable** | No |
+| **Fixable**  | No       |
 
 **Description:** TLS configurations should not use insecure protocols or disable certificate verification.
 
@@ -291,18 +339,19 @@
 
 ### SEC-002: TLS Version Check
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
-| **Category** | Security |
+| Property       | Value         |
+| -------------- | ------------- |
+| **Severity**   | Error         |
+| **Category**   | Security      |
 | **Issue Type** | Vulnerability |
-| **Fixable** | No |
+| **Fixable**    | No            |
 
 **Description:** Detect use of deprecated TLS versions (< 1.2). TLS 1.0 and 1.1 are deprecated and should not be used per current security standards.
 
 **Deprecated Protocols:** `TLSv1`, `TLSv1.0`, `TLSv1.1`, `SSLv3`, `SSLv2`
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad - deprecated protocol -->
 <tls:context enabledProtocols="TLSv1.1,TLSv1.2">
@@ -315,12 +364,12 @@
 
 ### SEC-003: Rate Limiting Policy
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
-| **Category** | Security |
+| Property       | Value         |
+| -------------- | ------------- |
+| **Severity**   | Warning       |
+| **Category**   | Security      |
 | **Issue Type** | Vulnerability |
-| **Fixable** | No |
+| **Fixable**    | No            |
 
 **Description:** APIs should have rate limiting or throttling configured to prevent DoS attacks and manage API consumption.
 
@@ -332,18 +381,19 @@
 
 ### SEC-004: Input Validation
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
-| **Category** | Security |
+| Property       | Value         |
+| -------------- | ------------- |
+| **Severity**   | Warning       |
+| **Category**   | Security      |
 | **Issue Type** | Vulnerability |
-| **Fixable** | No |
+| **Fixable**    | No            |
 
 **Description:** Incoming payloads should be validated using JSON or XML schema validation to prevent injection attacks and malformed data processing.
 
 **Check Logic:** Flags flows accepting POST/PUT/PATCH requests that have no schema validation or DataWeave validation patterns.
 
 **Example:**
+
 ```xml
 <!-- ✅ Good - schema validation -->
 <flow name="post:\orders:api-config">
@@ -356,17 +406,18 @@
 
 ### SEC-006: Encryption Key in Logs
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value    |
+| ------------ | -------- |
+| **Severity** | Error    |
 | **Category** | Security |
-| **Fixable** | No |
+| **Fixable**  | No       |
 
 **Description:** Encryption keys, passwords, and sensitive credentials should not appear in log statements.
 
 **Detected Patterns:** `encrypt.*key`, `password`, `credentials`, `api_key`, `secret.*key`, `mule.key`, `secure::.*key`
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad -->
 <logger message="Key: #[vars.encryptionKey]"/>
@@ -383,15 +434,16 @@
 
 ### MULE-006: Logger Category Required
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
 | **Category** | Logging |
-| **Fixable** | Yes |
+| **Fixable**  | Yes     |
 
 **Description:** All loggers must have a `category` attribute for proper log filtering.
 
 **Example:**
+
 ```xml
 <!-- ✅ Good -->
 <logger category="com.myorg.orders" message="Processing order" level="INFO"/>
@@ -401,15 +453,16 @@
 
 ### MULE-301: Logger Payload Reference
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
 | **Category** | Logging |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Loggers should not directly reference `#[payload]` as it may log sensitive data and cause performance issues.
 
 **Examples:**
+
 ```xml
 <!-- ❌ Bad - logs entire payload -->
 <logger message="#[payload]" />
@@ -422,11 +475,11 @@
 
 ### MULE-303: Logger in Until-Successful
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
 | **Category** | Logging |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Having a logger inside `until-successful` may flood logs on retries.
 
@@ -434,11 +487,11 @@
 
 ### LOG-001: Structured Logging
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value   |
+| ------------ | ------- |
+| **Severity** | Info    |
 | **Category** | Logging |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Recommend JSON logger format over plain text for production applications to enable better log parsing and analysis.
 
@@ -450,17 +503,18 @@
 
 ### LOG-004: Sensitive Data in Logs
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value   |
+| ------------ | ------- |
+| **Severity** | Error   |
 | **Category** | Logging |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Log statements should not contain sensitive data values (passwords, tokens, SSNs, PII).
 
 **Detected Patterns:** Variable references like `vars.password`, `payload.token`, `${secure::*}`, concatenated sensitive values.
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad - logs sensitive variable value -->
 <logger message="#['Token: ' ++ vars.accessToken]"/>
@@ -473,15 +527,16 @@
 
 ### HYG-001: Excessive Loggers
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
 | **Category** | Logging |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Flows should not have too many loggers, which can impact performance.
 
 **Configuration:**
+
 ```json
 {
   "HYG-001": {
@@ -502,11 +557,11 @@
 
 ### MULE-401: HTTP Request Missing User-Agent
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
-| **Category** | HTTP |
-| **Fixable** | No |
+| **Category** | HTTP    |
+| **Fixable**  | No      |
 
 **Description:** All HTTP requests should include a `User-Agent` header for API identification.
 
@@ -514,23 +569,33 @@
 
 ### MULE-402: HTTP Request Missing Content-Type
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
-| **Category** | HTTP |
-| **Fixable** | No |
+| **Category** | HTTP    |
+| **Fixable**  | No      |
 
 **Description:** POST/PUT HTTP requests should include a `Content-Type` header.
 
+**Detection Patterns:**
+
+| Pattern                   | Description                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------- |
+| A — Static header         | `<http:header headerName="Content-Type" value="..."/>` inside `<http:headers>`                    |
+| B — CDATA DataWeave block | `<http:headers><![CDATA[#[output application/java --- {"Content-Type": "..."}]]]></http:headers>` |
+| C — Inline DW expression  | `<http:headers value='#[{"Content-Type": "..."}]'/>`                                              |
+
+When headers are set via a DataWeave expression (patterns B/C) but `Content-Type` is not visible in the expression text, the issue is downgraded to **info** severity to acknowledge the static analysis limitation of evaluating dynamic expressions.
+
 ---
 
 ### MULE-403: HTTP Request Timeout
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
-| **Category** | HTTP |
-| **Fixable** | No |
+| **Category** | HTTP    |
+| **Fixable**  | No      |
 
 **Description:** HTTP requests should have explicit timeout configuration.
 
@@ -544,11 +609,11 @@
 
 ### MULE-501: Scatter-Gather Routes
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value       |
+| ------------ | ----------- |
+| **Severity** | Info        |
 | **Category** | Performance |
-| **Fixable** | No |
+| **Fixable**  | No          |
 
 **Description:** Scatter-gather with many routes may cause memory issues. Consider limiting routes.
 
@@ -556,11 +621,11 @@
 
 ### MULE-502: Async Without Error Handler
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value       |
+| ------------ | ----------- |
+| **Severity** | Warning     |
 | **Category** | Performance |
-| **Fixable** | No |
+| **Fixable**  | No          |
 
 **Description:** Async scopes should have their own error handling since they don't propagate errors to the parent flow.
 
@@ -570,11 +635,11 @@
 
 ### MULE-503: Large Choice Blocks
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value       |
+| ------------ | ----------- |
+| **Severity** | Warning     |
 | **Category** | Performance |
-| **Fixable** | No |
+| **Fixable**  | No          |
 
 **Description:** Choice blocks with many when clauses should be refactored to DataWeave lookups or routing slip pattern.
 
@@ -582,20 +647,28 @@
 
 ### PERF-002: Connection Pooling
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value       |
+| ------------ | ----------- |
+| **Severity** | Warning     |
 | **Category** | Performance |
-| **Fixable** | No |
+| **Fixable**  | No          |
 
 **Description:** DB and HTTP connectors should configure connection pools for optimal performance and resource management.
 
-**Check Logic:** Flags HTTP request configs missing `maxConnections`/`connectionIdleTimeout` and DB configs missing `pooling-profile`.
+**Check Logic:** Flags HTTP `request-config` elements missing `maxConnections`/`connectionIdleTimeout` — checks both the `<http:request-config>` element and its nested `<http:request-connection>` child (XSD-correct placement). Also flags DB configs missing `pooling-profile`.
 
 **Example:**
+
 ```xml
-<!-- ✅ Good - HTTP with pooling -->
-<http:request-config name="API_Config" maxConnections="20" connectionIdleTimeout="30000"/>
+<!-- ✅ Good - HTTP with pooling on request-connection (XSD-correct) -->
+<http:request-config name="API_Config">
+  <http:request-connection>
+    <http:client-socket-properties>
+      <http:tcp-client-socket-properties connectionTimeout="30000"/>
+    </http:client-socket-properties>
+  </http:request-connection>
+</http:request-config>
+<!-- maxConnections on http:request-connection avoids SAXParseException -->
 
 <!-- ✅ Good - DB with pooling -->
 <db:config name="Database_Config">
@@ -607,17 +680,18 @@
 
 ### RES-001: Reconnection Strategy
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value       |
+| ------------ | ----------- |
+| **Severity** | Warning     |
 | **Category** | Performance |
-| **Fixable** | No |
+| **Fixable**  | No          |
 
 **Description:** Connectors should have reconnection strategies configured for resilience.
 
 **Checked Connectors:** HTTP Request, HTTP Listener, JMS, AMQP, SFTP, FTP, VM, Database
 
 **Example:**
+
 ```xml
 <!-- ✅ Good -->
 <http:request-config name="API_Config">
@@ -637,11 +711,11 @@
 
 ### MULE-601: Flow Missing Description
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value         |
+| ------------ | ------------- |
+| **Severity** | Info          |
 | **Category** | Documentation |
-| **Fixable** | No |
+| **Fixable**  | No            |
 
 **Description:** Flows should have a `doc:description` attribute for documentation.
 
@@ -649,11 +723,11 @@
 
 ### MULE-604: Missing doc:name
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value         |
+| ------------ | ------------- |
+| **Severity** | Warning       |
 | **Category** | Documentation |
-| **Fixable** | No |
+| **Fixable**  | No            |
 
 **Description:** Key components (logger, set-variable, transform, etc.) should have `doc:name` for Anypoint Studio visibility.
 
@@ -661,17 +735,18 @@
 
 ### DOC-001: Display Name Enforcement
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value         |
+| ------------ | ------------- |
+| **Severity** | Info          |
 | **Category** | Documentation |
-| **Fixable** | No |
+| **Fixable**  | No            |
 
 **Description:** Key components should have meaningful `doc:name` attributes, not default/generic names.
 
 **Flagged Defaults:** `Set Payload`, `Set Variable`, `Transform Message`, `Flow Reference`, `Logger`, `Choice`
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad - generic default name -->
 <set-payload doc:name="Set Payload" value="#[output application/json --- {}]"/>
@@ -686,11 +761,11 @@
 
 ### MULE-008: Choice Anti-Pattern
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Avoid using `raise-error` directly inside `choice/otherwise`. Use a more descriptive error type.
 
@@ -698,11 +773,11 @@
 
 ### MULE-010: DWL Standards File
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Project should have a standard error DataWeave file at `src/main/resources/dwl/standard-error.dwl`.
 
@@ -710,11 +785,11 @@
 
 ### MULE-701: Deprecated Component Usage
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Detect usage of deprecated Mule components.
 
@@ -722,17 +797,18 @@
 
 ### OPS-001: Auto-Discovery Configuration
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** APIs should have auto-discovery configured for API Manager integration.
 
 **Check Logic:** Flags API projects (those with APIKit router) that are missing `<api-gateway:autodiscovery>`. Also verifies that `apiId` uses a property placeholder.
 
 **Example:**
+
 ```xml
 <!-- ✅ Good -->
 <api-gateway:autodiscovery apiId="${api.id}" flowRef="api-main"/>
@@ -742,15 +818,16 @@
 
 ### OPS-002: HTTP Port Placeholder
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** HTTP listener ports should use property placeholders, not hardcoded values.
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad -->
 <http:listener-config port="8081"/>
@@ -763,15 +840,16 @@
 
 ### OPS-003: Externalized Cron Expression
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Cron expressions in schedulers should use property placeholders to allow environment-specific scheduling.
 
 **Example:**
+
 ```xml
 <!-- ❌ Bad -->
 <scheduling-strategy>
@@ -788,11 +866,11 @@
 
 ### API-005: APIKit Validation
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** APIs should use APIKit for auto-generated implementation interfaces.
 
@@ -808,11 +886,11 @@
 
 ### MULE-801: Flow Complexity
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value      |
+| ------------ | ---------- |
+| **Severity** | Warning    |
 | **Category** | Complexity |
-| **Fixable** | No |
+| **Fixable**  | No         |
 
 **Description:** Flow cyclomatic complexity should not exceed threshold.
 
@@ -831,6 +909,7 @@
 | `<on-error-*>` | Error handlers |
 
 **Configuration:**
+
 ```json
 {
   "MULE-801": {
@@ -850,32 +929,39 @@
 
 ### MULE-802: Project Structure
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Structure |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Validate standard MuleSoft project folder structure.
 
 **Required Directories:**
+
 - `src/main/mule`
 - `src/main/resources`
 
-**Recommended Directories:**
+**Recommended Directories** (configurable via `recommendedDirs` option):
+
 - `src/main/resources/dwl`
-- `src/main/resources/api`
 - `src/test/munit`
 
+> **Note:** `src/main/resources/api` was removed from the default recommended list in v1.20.0. Many Mule 4 projects reference their API specification from Anypoint Exchange and do not bundle it locally. To restore this check, configure the rule explicitly:
+>
+> ```json
+> "MULE-802": { "enabled": true, "options": { "recommendedDirs": ["src/main/resources/dwl", "src/main/resources/api", "src/test/munit"] } }
+> ```
+
 ---
 
 ### MULE-803: Global Config File
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Structure |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Project should have `global.xml` with shared configurations (HTTP listeners, error handlers, etc.).
 
@@ -883,11 +969,11 @@
 
 ### MULE-804: Monolithic XML File
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Structure |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** XML files should not exceed 10 flows/sub-flows. Split large files by domain.
 
@@ -899,32 +985,48 @@
 
 ### YAML-001: Environment Properties Files
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Environment-specific YAML property files should exist for each environment.
 
-**Expected Files:**
+**Expected Files** (default environments: `dev`, `qa`, `prod`):
+
 - `dev.yaml` or `config-dev.yaml`
 - `qa.yaml` or `config-qa.yaml`
 - `prod.yaml` or `config-prod.yaml`
 
+Files can also live in `src/main/resources/config/` or `src/main/resources/properties/` subdirectories.
+
+**Options:**
+
+| Option         | Default                 | Description                        |
+| -------------- | ----------------------- | ---------------------------------- |
+| `environments` | `["dev", "qa", "prod"]` | List of required environment names |
+
+**Example configuration** to add `staging` or change defaults:
+
+```json
+"YAML-001": { "enabled": true, "options": { "environments": ["dev", "staging", "prod"] } }
+```
+
 ---
 
 ### YAML-003: Property Naming Convention
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Property keys should follow `category.property` format.
 
 **Examples:**
+
 ```yaml
 # ✅ Good
 db.host: localhost
@@ -939,15 +1041,16 @@ ApiTimeout: 30000
 
 ### YAML-004: No Plaintext Secrets
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value    |
+| ------------ | -------- |
+| **Severity** | Error    |
 | **Category** | Security |
-| **Fixable** | No |
+| **Fixable**  | No       |
 
 **Description:** Sensitive properties (passwords, keys, secrets) should be encrypted with `![...]` syntax.
 
 **Example:**
+
 ```yaml
 # ❌ Bad - plaintext secret
 db.password: mySecretPassword
@@ -964,11 +1067,11 @@ db.password: "![encryptedValue]"
 
 ### DW-001: External DWL for Complex Transforms
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | DataWeave |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Complex DataWeave (10+ lines) should be externalized to `.dwl` files.
 
@@ -976,23 +1079,38 @@ db.password: "![encryptedValue]"
 
 ### DW-002: DWL File Naming
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | DataWeave |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** DataWeave files should use kebab-case naming (`my-transform.dwl`).
 
+> **Note on DataWeave module directories:** DataWeave module files **must** use camelCase because hyphens (`-`) are invalid in DataWeave module identifiers (importing `my-module` would be a compile error). Use the `exemptPaths` option to exclude module directories from kebab-case enforcement.
+
+**Options:**
+
+| Option        | Default      | Description                                                |
+| ------------- | ------------ | ---------------------------------------------------------- |
+| `convention`  | `kebab-case` | Naming convention: `kebab-case`, `camelCase`, or `any`     |
+| `exemptPaths` | `[]`         | Glob patterns for paths to skip (e.g. `["**/modules/**"]`) |
+
+**Example configuration** to exempt a modules directory:
+
+```json
+"DW-002": { "enabled": true, "options": { "exemptPaths": ["**/modules/**", "**/lib/**"] } }
+```
+
 ---
 
 ### DW-003: DWL Modules
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | DataWeave |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Project should have common reusable DataWeave modules (`common.dwl`, `utils.dwl`).
 
@@ -1000,24 +1118,25 @@ db.password: "![encryptedValue]"
 
 ### DW-004: Java 17 DataWeave Error Handling
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Error     |
 | **Category** | DataWeave |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Enforces DataWeave error handling patterns compatible with Java 17 encapsulation. Detects restricted property access patterns that fail at runtime on Java 17.
 
 **Forbidden Patterns & Replacements:**
 
-| Forbidden | Replacement |
-|-----------|-------------|
-| `error.description` | `error.detailedDescription` |
+| Forbidden                  | Replacement                                                      |
+| -------------------------- | ---------------------------------------------------------------- |
+| `error.description`        | `error.detailedDescription`                                      |
 | `error.errorType.asString` | `error.errorType.namespace ++ ":" ++ error.errorType.identifier` |
-| `error.muleMessage` | `error.errorMessage` |
-| `error.errors` | `error.childErrors` |
+| `error.muleMessage`        | `error.errorMessage`                                             |
+| `error.errors`             | `error.childErrors`                                              |
 
 **Example:**
+
 ```dataweave
 // ❌ Bad - restricted in Java 17
 error.description
@@ -1033,17 +1152,18 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 ## API-Led Rules
 
 > **Best Practice**: Follow API-Led Connectivity architecture with clear layer separation:
+>
 > - **Experience Layer**: Channel-specific APIs (web, mobile)
 > - **Process Layer**: Orchestration and business logic
 > - **System Layer**: Backend system connectivity
 
 ### API-001: Experience Layer Pattern
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value   |
+| ------------ | ------- |
+| **Severity** | Info    |
 | **Category** | API-Led |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Experience layer APIs (with `-exp-` in name) should have HTTP listeners as entry points.
 
@@ -1051,11 +1171,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### API-002: Process Layer Pattern
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value   |
+| ------------ | ------- |
+| **Severity** | Info    |
 | **Category** | API-Led |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** Process layer APIs (with `-proc-` in name) should orchestrate other APIs via flow-refs or HTTP requests.
 
@@ -1063,11 +1183,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### API-003: System Layer Pattern
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value   |
+| ------------ | ------- |
+| **Severity** | Info    |
 | **Category** | API-Led |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** System layer APIs (with `-sys-` in name) should connect to external systems (databases, HTTP services).
 
@@ -1075,11 +1195,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### API-004: Single System Per SAPI
 
-| Property | Value |
-|----------|-------|
+| Property     | Value   |
+| ------------ | ------- |
 | **Severity** | Warning |
 | **Category** | API-Led |
-| **Fixable** | No |
+| **Fixable**  | No      |
 
 **Description:** System API should integrate with only one backend system. This promotes clear separation of concerns, easier maintenance, better reusability, and simplified error handling.
 
@@ -1093,11 +1213,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### HYG-002: Commented Code Detection
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Info      |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Detects potentially commented-out code blocks in Mule configurations.
 
@@ -1109,16 +1229,18 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### HYG-003: Unused Flow Detection
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Standards |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
-**Description:** Detects flows and sub-flows that are never referenced by `flow-ref` within the same file.
+**Description:** Detects flows and sub-flows that are never referenced by `flow-ref` across the entire project.
 
 **Check Logic:**
-- **Sub-flows**: Always expected to be referenced; flagged if no `flow-ref` points to them.
+
+- **Cross-file detection**: The engine pre-scans all XML files to collect every `<flow-ref name="...">` target before running rules. A sub-flow or flow is only flagged if it is not referenced in _any_ file in the project.
+- **Sub-flows**: Always expected to be referenced; flagged if no `flow-ref` points to them anywhere in the project.
 - **Flows without triggers**: Flows that have no HTTP listener, scheduler, or VM listener and aren't referenced are flagged.
 - **Exclusions**: Flows matching common external patterns (`-main`, `-api`, `api-`, `-console`, `-error-handler`, `global`) are excluded.
 
@@ -1128,15 +1250,16 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### PROJ-001: POM Validation
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Error |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Error     |
 | **Category** | Structure |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Validates `pom.xml` existence and critical plugins.
 
 **Checks:**
+
 1. `pom.xml` exists in project root
 2. Contains `mule-maven-plugin` in build configuration
 3. Contains `munit-maven-plugin` if test files exist
@@ -1145,11 +1268,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### PROJ-002: Git Hygiene
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Warning |
+| Property     | Value     |
+| ------------ | --------- |
+| **Severity** | Warning   |
 | **Category** | Structure |
-| **Fixable** | No |
+| **Fixable**  | No        |
 
 **Description:** Validates `.gitignore` existence and standard entries in git repositories.
 
@@ -1163,11 +1286,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### EXP-001: Flow Reference Depth
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value        |
+| ------------ | ------------ |
+| **Severity** | Info         |
 | **Category** | Experimental |
-| **Fixable** | No |
+| **Fixable**  | No           |
 
 **Description:** Limit the number of flow-refs in a single flow to avoid deep call chains.
 
@@ -1175,11 +1298,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### EXP-002: Connector Config Naming
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value        |
+| ------------ | ------------ |
+| **Severity** | Info         |
 | **Category** | Experimental |
-| **Fixable** | No |
+| **Fixable**  | No           |
 
 **Description:** Connector configurations should follow `Convention_Type` pattern (e.g., `HTTP_Request_Config`).
 
@@ -1187,11 +1310,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ### EXP-003: MUnit Coverage
 
-| Property | Value |
-|----------|-------|
-| **Severity** | Info |
+| Property     | Value        |
+| ------------ | ------------ |
+| **Severity** | Info         |
 | **Category** | Experimental |
-| **Fixable** | No |
+| **Fixable**  | No           |
 
 **Description:** Flows should have corresponding MUnit tests in `src/test/munit`.
 
@@ -1199,11 +1322,11 @@ error.errorType.namespace ++ ":" ++ error.errorType.identifier
 
 ## Rule Priority Matrix
 
-| Severity | Count | Rules |
-|----------|-------|-------|
-| Error | 10 | MULE-001, 003, 004, 201, 202, SEC-002, SEC-006, LOG-004, DW-004, YAML-004, PROJ-001 |
-| Warning | 25 | MULE-002, 005, 006, 007, 008, 009, 101, 102, 301, 303, 401, 402, 403, 502, 503, 604, 701, 801, 802, 803, 804, SEC-003, SEC-004, PERF-002, RES-001, OPS-002, OPS-003, HYG-001, HYG-003, API-004, PROJ-002 |
-| Info | 21 | MULE-010, 501, 601, YAML-001, 003, DW-001, 002, 003, API-001, 002, 003, 005, EXP-001, 002, 003, ERR-001, LOG-001, OPS-001, DOC-001, HYG-002 |
+| Severity | Count | Rules                                                                                                                                                                                                    |
+| -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error    | 10    | MULE-001, 003, 004, 201, 202, SEC-002, SEC-006, LOG-004, DW-004, YAML-004, PROJ-001                                                                                                                      |
+| Warning  | 25    | MULE-002, 005, 006, 007, 008, 009, 101, 102, 301, 303, 401, 402, 403, 502, 503, 604, 701, 801, 802, 803, 804, SEC-003, SEC-004, PERF-002, RES-001, OPS-002, OPS-003, HYG-001, HYG-003, API-004, PROJ-002 |
+| Info     | 21    | MULE-010, 501, 601, YAML-001, 003, DW-001, 002, 003, API-001, 002, 003, 005, EXP-001, 002, 003, ERR-001, LOG-001, OPS-001, DOC-001, HYG-002                                                              |
 
 ---