@sfdxy/mule-lint 1.21.0 → 1.23.0

package/docs/README.md

@@ -1,17 +1,47 @@
 # Mule-Lint Documentation
 
-Welcome to the Mule-Lint documentation. This documentation is organized into two sections:
+Welcome to the Mule-Lint documentation. This documentation is organized into two sections: **MuleSoft Best Practices** (for integration developers and AI agents) and **Linter Technical Documentation** (for mule-lint contributors).
 
 ---
 
 ## 📘 MuleSoft Best Practices
 
-Comprehensive guidelines for building maintainable, secure, and performant Mule applications. These guidelines cover more than just what the linter validates - they represent industry best practices for MuleSoft development.
+Comprehensive guidelines for building maintainable, secure, and performant Mule 4 applications. Each guide is a focused, self-contained reference that can be read independently.
 
-| Document                                                          | Description                                  |
-| ----------------------------------------------------------------- | -------------------------------------------- |
-| [Best Practices Guide](best-practices/mulesoft-best-practices.md) | Complete MuleSoft development best practices |
-| [Rules Catalog](best-practices/rules-catalog.md)                  | All 56 linter rules with examples            |
+### Core Development
+
+| Document                                                          | Description                                                                  |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Best Practices Index](best-practices/mulesoft-best-practices.md) | Master index with quick reference card and API-Led overview                  |
+| [Error Handling](best-practices/error-handling.md)                | Global error handlers, HTTP vs. event-driven patterns, connector error types, CRM error log objects |
+| [Variable Contracts](best-practices/variable-contracts.md)        | Standard variables, correlation IDs, array mirroring, action routing         |
+| [Logging](best-practices/logging.md)                              | Categories, structured JSON logging, MDC/tracing, PII prevention             |
+| [Security](best-practices/security.md)                            | Secure properties, TLS 1.2+, credentials, zero-trust architecture            |
+| [Performance](best-practices/performance.md)                      | Timeouts, connection pooling, async error handling, streaming, bulk lookup (N+1 prevention)  |
+
+### Architecture & Patterns
+
+| Document                                                         | Description                                                       |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [Event-Driven Patterns](best-practices/event-driven-patterns.md) | Platform Events, Anypoint MQ, VM Queue Dispatcher, scheduler watermarking, deferred task polling |
+| [Connector Patterns](best-practices/connector-patterns.md)       | Entity config YAML, SF/NS connector gotchas, protocol negotiation, ObjectStore caching |
+| [DataWeave Patterns](best-practices/dataweave-patterns.md)       | Modules, type coercion, cross-system value mapping (4 strategies), import path rules            |
+
+### Project & Operations
+
+| Document                                                             | Description                                                  |
+| -------------------------------------------------------------------- | ------------------------------------------------------------ |
+| [Folder Structure](best-practices/folder-structure.md)               | Standard Maven layout for Mule 4 projects                    |
+| [Documentation Standards](best-practices/documentation-standards.md) | Flow documentation, README templates, commit messages        |
+| [Testing (MUnit)](best-practices/testing.md)                         | Test structure, error scenario testing, event-driven testing |
+| [CI/CD Integration](best-practices/ci-cd.md)                         | Pipeline stages, mule-lint integration, quality gates        |
+| [Deployment & Modernization](best-practices/deployment-2026.md)      | CloudHub 2.0, Java 17, Anypoint Code Builder, API Governance |
+
+### Reference
+
+| Document                                         | Description                                            |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| [Rules Catalog](best-practices/rules-catalog.md) | Complete reference for all 82 lint rules with examples |
 
 ---
 
@@ -19,13 +49,14 @@ Comprehensive guidelines for building maintainable, secure, and performant Mule
 
 For contributors and those extending mule-lint.
 
-| Document                                           | Description                            |
-| -------------------------------------------------- | -------------------------------------- |
-| [Architecture](linter/architecture.md)             | System design, patterns, and data flow |
-| [Rule Engine](linter/rule-engine.md)               | Rule engine internals and interfaces   |
-| [Extending](linter/extending.md)                   | How to create custom rules             |
-| [Folder Structure](linter/folder-structure.md)     | Project organization                   |
-| [Naming Conventions](linter/naming-conventions.md) | Code style and naming standards        |
+| Document                                           | Description                                      |
+| -------------------------------------------------- | ------------------------------------------------ |
+| [Architecture](linter/architecture.md)             | System design, patterns, and data flow           |
+| [Rule Engine](linter/rule-engine.md)               | Rule engine internals and interfaces             |
+| [Extending](linter/extending.md)                   | How to create custom rules                       |
+| [Folder Structure](linter/folder-structure.md)     | Linter project organization                      |
+| [Naming Conventions](linter/naming-conventions.md) | Code style and naming standards                  |
+| [MCP Design](mcp-design.md)                        | MCP server architecture and tool/resource design |
 
 ---
 
@@ -72,25 +103,54 @@ mule-lint ./src/main/mule --fail-on-warning
 
 ## Rule Families
 
-| Family          | Prefix                    | Count | Description                                        |
-| --------------- | ------------------------- | ----- | -------------------------------------------------- |
-| Core MuleSoft   | MULE-XXX                  | 29    | Core Mule 4 XML validation                         |
-| Security        | SEC-XXX                   | 5     | Security best practices (TLS, rate limiting, etc.) |
-| Logging         | LOG-XXX                   | 2     | Structured logging and sensitive data              |
-| Operations      | OPS-XXX, RES-XXX, HYG-XXX | 7     | Reconnection, auto-discovery, hygiene              |
-| YAML Properties | YAML-XXX                  | 3     | YAML configuration validation                      |
-| DataWeave       | DW-XXX                    | 4     | DataWeave file validation                          |
-| API-Led         | API-XXX                   | 5     | API-Led connectivity patterns                      |
-| Governance      | PROJ-XXX                  | 2     | POM and Git hygiene                                |
-| Experimental    | EXP-XXX                   | 3     | Beta rules for evaluation                          |
-
-**Total: 56 rules**
+| Family          | Prefix                    | Count | Description                                  |
+| --------------- | ------------------------- | ----- | -------------------------------------------- |
+| Core MuleSoft   | MULE-XXX                  | 29    | Core Mule 4 XML validation                   |
+| Error Handling  | ERR-XXX                   | 4     | Advanced error handler rules                 |
+| Security        | SEC-XXX                   | 5     | Security best practices (TLS, rate limiting) |
+| Logging         | LOG-XXX, HYG-001          | 3     | Structured logging and sensitive data        |
+| HTTP            | HTTP-XXX                  | 1     | HTTP connector configuration                 |
+| Operations      | OPS-XXX, RES-XXX, HYG-XXX | 8     | Reconnection, auto-discovery, hygiene        |
+| YAML Properties | YAML-XXX                  | 3     | YAML configuration validation                |
+| DataWeave       | DW-XXX                    | 5     | DataWeave file validation                    |
+| API-Led         | API-XXX                   | 7     | API-Led connectivity patterns                |
+| Connectors      | SF-XXX                    | 2     | Salesforce and event connector rules         |
+| Standards       | CFG-XXX, STD-XXX          | 3     | Config and API standards                     |
+| Governance      | PROJ-XXX                  | 2     | POM and Git hygiene                          |
+| Experimental    | EXP-XXX                   | 3     | Beta rules for evaluation                    |
+
+**Total: 82 rules**
 
 ---
 
 ## For AI Agents
 
-Use SARIF output format for structured results:
+### MCP Resources
+
+All best practice guides are available via the MuleSoft Lint MCP server:
+
+```
+mule-lint://rules                          → JSON catalog of all 82 rules
+mule-lint://docs/best-practices            → Master index and quick reference
+mule-lint://docs/error-handling            → Error handling patterns
+mule-lint://docs/event-driven              → Event-driven architecture
+mule-lint://docs/connectors                → Connector configuration
+mule-lint://docs/variables                 → Variable contracts
+mule-lint://docs/dataweave                 → DataWeave patterns
+mule-lint://docs/security                  → Security best practices
+mule-lint://docs/logging                   → Logging standards
+mule-lint://docs/performance               → Performance optimization
+mule-lint://docs/testing                   → MUnit testing
+mule-lint://docs/deployment                → Deployment & modernization
+mule-lint://docs/ci-cd                     → CI/CD integration
+mule-lint://docs/folder-structure          → Project structure
+mule-lint://docs/documentation-standards   → Documentation standards
+mule-lint://docs/rules-catalog             → Complete rules reference
+```
+
+### SARIF Output
+
+Use SARIF output for structured results:
 
 ```bash
 mule-lint ./src/main/mule -f sarif > report.sarif

package/docs/best-practices/ci-cd.md

@@ -0,0 +1,135 @@
+# CI/CD Integration
+
+> **Applies to:** All  
+> **Related Rules:** `PROJ-001` · `PROJ-002`  
+> **Last Updated:** April 2026
+
+## When to Read This
+
+Read this when setting up CI/CD pipelines, integrating mule-lint into builds, or configuring quality gates.
+
+---
+
+## Pipeline Stages
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│  Build   │ →  │  Lint    │ →  │  Test    │ →  │  Package │ →  │  Deploy  │
+│          │    │          │    │          │    │          │    │          │
+│ mvn      │    │ mule-    │    │ mvn test │    │ mvn      │    │ anypoint │
+│ compile  │    │ lint     │    │          │    │ package  │    │ deploy   │
+└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
+```
+
+---
+
+## mule-lint Integration
+
+### Quality Gate Configuration
+
+```json
+// .mulelintrc.json
+{
+  "include": ["src/main/mule/**/*.xml"],
+  "exclude": ["src/test/munit/**/*.xml"],
+  "qualityGate": {
+    "name": "Project Quality Gate",
+    "conditions": [
+      { "metric": "errors", "operator": ">", "threshold": 0, "status": "fail" },
+      { "metric": "warnings", "operator": ">", "threshold": 10, "status": "warn" }
+    ]
+  },
+  "rules": {
+    "MULE-001": {
+      "enabled": false,
+      "reason": "Global error handler in non-standard location — documented exception"
+    }
+  }
+}
+```
+
+**Rule suppression:** When disabling a rule, always include a `reason` or `comment` field explaining why. This documents the engineering decision for future reviewers.
+
+### Output Formats
+
+| Format   | Use Case                        | Command                              |
+| -------- | ------------------------------- | ------------------------------------ |
+| `pretty` | Local development               | `mule-lint . -f pretty`              |
+| `json`   | CI/CD parsing                   | `mule-lint . -f json`                |
+| `sarif`  | GitHub Code Scanning, AI agents | `mule-lint . -f sarif -o lint.sarif` |
+| `html`   | Human review reports            | `mule-lint . -f html -o report.html` |
+
+---
+
+## GitHub Actions Example
+
+```yaml
+name: Mule CI/CD
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+
+      - name: Cache Maven packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.m2
+          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+
+      - name: Build
+        run: mvn -B clean compile
+
+      - name: Run mule-lint
+        run: npx @sfdxy/mule-lint . -c .mulelintrc.json -f sarif -o lint.sarif
+
+      - name: Upload SARIF results
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: lint.sarif
+
+      - name: Run MUnit tests
+        run: mvn -B test -Dmule.env=dev -Dsecure.key=test
+```
+
+---
+
+## Git Branch Strategy
+
+| Branch      | Purpose               | Deployment Target |
+| ----------- | --------------------- | ----------------- |
+| `main`      | Production-ready code | Production        |
+| `develop`   | Integration branch    | QA/Staging        |
+| `feature/*` | New features          | Development       |
+| `hotfix/*`  | Production fixes      | Production        |
+
+---
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new order processing logic
+fix: resolve null pointer in mapping
+docs: update README with deployment steps
+chore: upgrade mule maven plugin
+refactor: extract common DWL functions to module
+```
+
+---
+
+**See also:** [Testing](testing.md) · [Deployment & Modernization](deployment-2026.md) · [Folder Structure](folder-structure.md)

package/docs/best-practices/connector-patterns.md

@@ -0,0 +1,253 @@
+# Connector Configuration Patterns
+
+> **Applies to:** All (System APIs, Process APIs)  
+> **Related Rules:** `SEC-007` · `SEC-008` · `PERF-002` · `RES-001` · `RES-002` · `SF-001` · `SF-002`  
+> **Last Updated:** April 2026
+
+## When to Read This
+
+Read this when configuring Salesforce, NetSuite, HTTP, or Database connectors in Mule 4. Covers connector attribute gotchas, the entity-config pattern, and protocol negotiation.
+
+---
+
+## Patterns
+
+### Pattern 1: Entity Configuration (YAML-Driven)
+
+**Use when:** building a System API that supports multiple entity types (Account, Contact, Order, etc.) with consistent CRUD operations.
+
+Instead of hardcoding entity-specific details in flow XML, externalize them to per-entity YAML files:
+
+```
+src/main/resources/entity-config/
+├── account.yaml
+├── contact.yaml
+├── opportunity.yaml
+└── order.yaml
+```
+
+**Entity config structure:**
+
+```yaml
+# entity-config/account.yaml
+entity:
+  account:
+    sObjectType: 'Account'
+    enabled: true
+    externalIdField: 'NetSuite_ID__c'
+    queryFields: 'Id, Name, BillingStreet, BillingCity, Phone, Website'
+    queryTemplate: 'SELECT {fields} FROM Account WHERE {filter} LIMIT {limit}'
+    writeback:
+      netSuiteIdField: 'NetSuite_ID__c'
+      errorField: 'NetSuite_Error__c'
+      lastSyncField: 'Last_NetSuite_Sync__c'
+```
+
+**Load in global-config.xml:**
+
+```xml
+<configuration-properties doc:name="Account Config"
+    file="entity-config/account.yaml"/>
+<configuration-properties doc:name="Contact Config"
+    file="entity-config/contact.yaml"/>
+```
+
+**Benefits:**
+
+- Add a new entity by creating a YAML file — no flow XML changes
+- Entity behavior is visible, auditable, and environment-independent
+- LLMs can read entity configs to understand available operations
+
+### Pattern 2: Salesforce JWT Connector
+
+**Use when:** authenticating to Salesforce via OAuth 2.0 JWT Bearer flow.
+
+```xml
+<salesforce:sfdc-config name="Salesforce_Config">
+    <salesforce:jwt-connection
+        consumerKey="${secure::salesforce.jwt.consumerKey}"
+        keyStore="${salesforce.jwt.keystorePath}"
+        storePassword="${secure::salesforce.jwt.storePassword}"
+        principal="${salesforce.jwt.principal}"
+        tokenEndpoint="${salesforce.jwt.tokenEndpoint}"
+        audienceUrl="${salesforce.jwt.audienceUrl}">
+        <reconnection>
+            <reconnect count="3" frequency="5000"/>
+        </reconnection>
+    </salesforce:jwt-connection>
+</salesforce:sfdc-config>
+```
+
+> ⚠️ **Gotchas** (common mistakes that cause runtime failures):
+>
+> | Incorrect                           | Correct                  | Notes                              |
+> | ----------------------------------- | ------------------------ | ---------------------------------- |
+> | `salesforce:jwt-connection-config`  | `salesforce:sfdc-config` | Outer config element name          |
+> | `keyStorePath="..."`                | `keyStore="..."`         | JWT connection attribute           |
+> | `type="Account"` (on upsert)        | `objectType="Account"`   | Upsert operation attribute         |
+> | `type="Account"` (on create/update) | `type="Account"`         | Create/Update use `type` (correct) |
+
+### Pattern 3: Protocol Negotiation (Dual-Protocol SAPI)
+
+**Use when:** a System API must support both SOAP and REST protocols to the same backend (e.g., NetSuite).
+
+The calling PAPI sends an `x-integration-protocol` header. The SAPI routes internally:
+
+```xml
+<!-- common/netsuite-process-subflow.xml -->
+<sub-flow name="netsuite-process-subflow">
+    <choice>
+        <when expression="#[vars.protocol == 'SOAP']">
+            <flow-ref name="netsuite-soap-upsert-subflow"/>
+        </when>
+        <when expression="#[vars.protocol == 'REST']">
+            <flow-ref name="netsuite-rest-upsert-subflow"/>
+        </when>
+    </choice>
+</sub-flow>
+```
+
+**Protocol support matrix:**
+
+| Record Type | SOAP | REST           |
+| ----------- | ---- | -------------- |
+| Customer    | ✅   | ✅             |
+| Contact     | ✅   | ✅             |
+| Sales Order | ✅   | ❌ (SOAP-only) |
+| Credit Memo | ✅   | ❌ (SOAP-only) |
+
+### Pattern 4: HTTP Request Connector (with Pooling)
+
+**Use when:** making outbound HTTP calls to downstream APIs.
+
+```xml
+<http:request-config name="SAPI_HTTP_Config"
+    responseTimeout="${https.request.responseTimeout}">
+    <http:request-connection host="${https.request.host}"
+                             port="${https.request.port}"
+                             connectionIdleTimeout="${https.connection.idleTimeout}"
+                             maxConnections="${https.connection.maxConnections}">
+        <reconnection>
+            <reconnect frequency="${reconnection.frequency}"
+                       count="${reconnection.attempts}"/>
+        </reconnection>
+    </http:request-connection>
+    <!-- Set correlation ID once — applied to every request automatically -->
+    <http:default-headers>
+        <http:default-header key="X-Correlation-Id" value="#[correlationId]"/>
+    </http:default-headers>
+</http:request-config>
+```
+
+**Rules:**
+
+- Always set `responseTimeout` (avoid hanging connections)
+- Set `connectionIdleTimeout >= responseTimeout` (Grizzly kills connections if idle fires first)
+- Configure connection pooling for production (`maxConnections`)
+
+### Pattern 5: Reconnection Strategies
+
+**Use when:** configuring any connector that connects to an external system.
+
+| Connector Type                         | Strategy              | Example                            |
+| -------------------------------------- | --------------------- | ---------------------------------- |
+| **Event listeners** (SF, MQ)           | `reconnect-forever`   | Must auto-recover from disconnects |
+| **Outbound connectors** (HTTP, SF, DB) | `reconnect count="3"` | Bounded retries with frequency     |
+| **HTTP Listener**                      | `reconnect-forever`   | Server must always be up           |
+
+```xml
+<!-- Listener — always reconnect -->
+<http:listener-config name="httpListenerConfig">
+    <http:listener-connection host="0.0.0.0" port="${http.port}">
+        <reconnection>
+            <reconnect-forever frequency="5000"/>
+        </reconnection>
+    </http:listener-connection>
+</http:listener-config>
+
+<!-- Outbound — bounded retries -->
+<salesforce:sfdc-config name="Salesforce_Config">
+    <salesforce:jwt-connection ...>
+        <reconnection>
+            <reconnect count="3" frequency="5000"/>
+        </reconnection>
+    </salesforce:jwt-connection>
+</salesforce:sfdc-config>
+```
+
+### Pattern 6: ObjectStore for Reference Data Caching
+
+**Use when:** frequently-accessed reference data (customer records, config lookups) is fetched repeatedly during batch processing. Cache in ObjectStore with TTL to reduce API calls.
+
+```xml
+<!-- global.xml — configure the cache store -->
+<os:object-store name="customer-cache-store"
+    entryTtl="${customer.cache.ttl}"
+    expirationInterval="${customer.cache.expirationInterval}"
+    maxEntries="200"/>
+```
+
+**Key rules:**
+
+- Set `maxEntries` to prevent unbounded memory growth
+- Set `entryTtl` appropriate to data volatility (e.g., 1 hour for customer data, 24 hours for country codes)
+- Use `os:contains` + `os:retrieve` to check-then-get, not just `os:retrieve` with default (avoids computing defaults unnecessarily)
+
+---
+
+## DWL Utility Module: `parseAndConvert`
+
+The Salesforce connector requires Java-typed values (DateTime, Date, Boolean) — not strings. Use a shared DWL module for type coercion:
+
+```dataweave
+%dw 2.0
+// dwl/modules/salesforceUtility.dwl
+
+var dateTimePattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})?$/
+var dateOnlyPattern = /^\d{4}-\d{2}-\d{2}$/
+
+fun parseAndConvert(obj: Object) =
+    obj mapObject ((value, key) ->
+        if ((value is String) and ((value as String) matches dateTimePattern))
+            (key): (value as String) as DateTime
+        else if ((value is String) and ((value as String) matches dateOnlyPattern))
+            (key): (value as String) as Date
+        else if ((value is String) and ((value as String) == ""))
+            (key): null
+        else if (value is Object)
+            (key): parseAndConvert(value)
+        else
+            (key): value
+    )
+```
+
+**Usage in flow XML:**
+
+```xml
+<ee:transform>
+    <ee:set-payload><![CDATA[%dw 2.0
+import dwl::modules::salesforceUtility
+output application/java
+---
+salesforceUtility::parseAndConvert(payload)
+]]></ee:set-payload>
+</ee:transform>
+```
+
+> ⚠️ **DWL import path rule:** Always use the full path prefix `dwl::modules::moduleName`. Short paths like `modules::moduleName` will fail at runtime.
+
+---
+
+## Checklist
+
+- [ ] Entity configs externalized to `entity-config/{entity}.yaml`
+- [ ] All connector credentials use `${secure::...}` property placeholders
+- [ ] Reconnection strategies configured on all connectors
+- [ ] `responseTimeout` explicitly set on HTTP request configs
+- [ ] No hardcoded connector attribute values (hosts, ports, keys)
+- [ ] DWL modules imported with full `dwl::modules::` path prefix
+- [ ] Salesforce payloads pass through `parseAndConvert()` before connector call
+
+---
+
+**See also:** [Security](security.md) · [Performance](performance.md) · [DataWeave Patterns](dataweave-patterns.md)