@sfdxy/mule-lint 1.18.1 → 1.19.0

package/docs/linter/architecture.md

@@ -9,14 +9,14 @@ flowchart TB
     subgraph CLI["CLI Layer (commander)"]
         A["mule-lint ./path -f sarif"]
     end
-    
+
     subgraph Engine["LintEngine"]
         B[FileScanner<br/>fast-glob] --> C[XmlParser<br/>xmldom]
         C --> D[Rule Executor]
         B --> E[YamlParser<br/>yaml]
         E --> D
     end
-    
+
     subgraph Rules["Rules (56 Total)"]
         D --> R1[Error Handling<br/>MULE-001,003,005,007,009]
         D --> R2[Naming<br/>MULE-002,101,102]
@@ -33,14 +33,14 @@ flowchart TB
         D --> R13[API-Led<br/>API-001,002,003]
         D --> R14[Experimental<br/>EXP-001,002,003]
     end
-    
+
     subgraph Output["Formatters"]
         J[Table<br/>Human]
         K[JSON<br/>Scripts]
         L[SARIF<br/>AI Agents]
         M[HTML<br/>Reports]
     end
-    
+
     A --> B
     D --> J
     D --> K
@@ -59,27 +59,27 @@ sequenceDiagram
     participant YAML as YamlParser
     participant Rules
     participant Formatter
-    
+
     CLI->>Engine: scan(path)
     Engine->>Scanner: scanDirectory(path)
     Scanner-->>Engine: ScannedFile[]
-    
+
     loop Each XML File
         Engine->>Parser: parseXml(content)
         Parser-->>Engine: Document
-        
+
         loop Each Rule
             Engine->>Rules: validate(doc, context)
             Rules-->>Engine: Issue[]
         end
     end
-    
+
     loop YAML Rules
         Engine->>YAML: parseYaml(path)
         YAML-->>Engine: Properties
         Engine->>Rules: validate(props, context)
     end
-    
+
     Engine->>Formatter: format(report)
     Formatter-->>CLI: string output
 ```
@@ -89,6 +89,7 @@ sequenceDiagram
 ### LintEngine
 
 The central orchestrator that:
+
 1. Scans directories for XML and YAML files using FileScanner
 2. Parses each file with XmlParser or YamlParser
 3. Executes all enabled rules against each document
@@ -110,20 +111,20 @@ const flows = xpath.selectNodes('//mule:flow', document);
 
 Pre-configured namespaces:
 
-| Prefix | Namespace |
-|--------|-----------|
-| `mule` | http://www.mulesoft.org/schema/mule/core |
-| `http` | http://www.mulesoft.org/schema/mule/http |
-| `ee` | http://www.mulesoft.org/schema/mule/ee/core |
-| `db` | http://www.mulesoft.org/schema/mule/db |
-| `doc` | http://www.mulesoft.org/schema/mule/documentation |
-| `tls` | http://www.mulesoft.org/schema/mule/tls |
-| `file` | http://www.mulesoft.org/schema/mule/file |
-| `sftp` | http://www.mulesoft.org/schema/mule/sftp |
-| `vm` | http://www.mulesoft.org/schema/mule/vm |
-| `jms` | http://www.mulesoft.org/schema/mule/jms |
-| `apikit` | http://www.mulesoft.org/schema/mule/mule-apikit |
-| `batch` | http://www.mulesoft.org/schema/mule/batch |
+| Prefix   | Namespace                                         |
+| -------- | ------------------------------------------------- |
+| `mule`   | http://www.mulesoft.org/schema/mule/core          |
+| `http`   | http://www.mulesoft.org/schema/mule/http          |
+| `ee`     | http://www.mulesoft.org/schema/mule/ee/core       |
+| `db`     | http://www.mulesoft.org/schema/mule/db            |
+| `doc`    | http://www.mulesoft.org/schema/mule/documentation |
+| `tls`    | http://www.mulesoft.org/schema/mule/tls           |
+| `file`   | http://www.mulesoft.org/schema/mule/file          |
+| `sftp`   | http://www.mulesoft.org/schema/mule/sftp          |
+| `vm`     | http://www.mulesoft.org/schema/mule/vm            |
+| `jms`    | http://www.mulesoft.org/schema/mule/jms           |
+| `apikit` | http://www.mulesoft.org/schema/mule/mule-apikit   |
+| `batch`  | http://www.mulesoft.org/schema/mule/batch         |
 
 ### BaseRule
 
@@ -143,21 +144,22 @@ classDiagram
         #createIssue(node, message): Issue
         #getOption(context, key, default): T
     }
-    
+
     class FlowNamingRule {
         +validate()
     }
-    
+
     class YamlRuleBase {
         +validate()
         #findYamlFiles(): string[]
     }
-    
+
     BaseRule <|-- FlowNamingRule
     BaseRule <|-- YamlRuleBase
 ```
 
 **Issue Types for Quality Metrics:**
+
 - `code-smell` (default) - Maintainability issues
 - `bug` - Reliability issues (error-handling rules)
 - `vulnerability` - Security issues (security rules)
@@ -170,10 +172,10 @@ Each rule is a strategy implementing the same interface:
 
 ```typescript
 interface Rule {
-    id: string;
-    name: string;
-    severity: Severity;
-    validate(doc: Document, context: ValidationContext): Issue[];
+  id: string;
+  name: string;
+  severity: Severity;
+  validate(doc: Document, context: ValidationContext): Issue[];
 }
 ```
 
@@ -183,12 +185,16 @@ Formatters are selected via factory function:
 
 ```typescript
 function getFormatter(type: FormatterType): Formatter {
-    switch (type) {
-        case 'table': return formatTable;
-        case 'json': return formatJson;
-        case 'sarif': return formatSarif;
-        case 'html': return formatHtml;
-    }
+  switch (type) {
+    case 'table':
+      return formatTable;
+    case 'json':
+      return formatJson;
+    case 'sarif':
+      return formatSarif;
+    case 'html':
+      return formatHtml;
+  }
 }
 ```
 
@@ -256,22 +262,22 @@ src/
 
 ## Rule Categories
 
-| Category | ID Prefix | Count | Description |
-|----------|-----------|-------|-------------|
-| Error Handling | MULE-00X | 5 | Error handler presence and configuration |
-| Naming | MULE-002, 10X | 3 | Flow, variable, and file naming |
-| Security | MULE-004, 20X | 3 | Hardcoded values and security |
-| Logging | MULE-006, 30X | 3 | Logger configuration |
-| HTTP | MULE-40X | 3 | HTTP request configuration |
-| Performance | MULE-50X | 3 | Performance anti-patterns |
-| Documentation | MULE-60X | 2 | Component documentation |
-| Standards | MULE-008, 010, 70X | 3 | Best practices |
-| Complexity | MULE-80X | 1 | Cyclomatic complexity |
-| Structure | MULE-80X | 3 | Project structure |
-| YAML | YAML-XXX | 3 | Properties validation |
-| DataWeave | DW-XXX | 3 | DWL file validation |
-| API-Led | API-XXX | 3 | API-Led patterns |
-| Experimental | EXP-XXX | 3 | Beta rules |
+| Category       | ID Prefix          | Count | Description                              |
+| -------------- | ------------------ | ----- | ---------------------------------------- |
+| Error Handling | MULE-00X           | 5     | Error handler presence and configuration |
+| Naming         | MULE-002, 10X      | 3     | Flow, variable, and file naming          |
+| Security       | MULE-004, 20X      | 3     | Hardcoded values and security            |
+| Logging        | MULE-006, 30X      | 3     | Logger configuration                     |
+| HTTP           | MULE-40X           | 3     | HTTP request configuration               |
+| Performance    | MULE-50X           | 3     | Performance anti-patterns                |
+| Documentation  | MULE-60X           | 2     | Component documentation                  |
+| Standards      | MULE-008, 010, 70X | 3     | Best practices                           |
+| Complexity     | MULE-80X           | 1     | Cyclomatic complexity                    |
+| Structure      | MULE-80X           | 3     | Project structure                        |
+| YAML           | YAML-XXX           | 3     | Properties validation                    |
+| DataWeave      | DW-XXX             | 3     | DWL file validation                      |
+| API-Led        | API-XXX            | 3     | API-Led patterns                         |
+| Experimental   | EXP-XXX            | 3     | Beta rules                               |
 
 ## Extension Points
 
@@ -296,18 +302,18 @@ src/
 
 ## Performance Specifications
 
-| Metric | Target |
-|--------|--------|
-| Files per second | > 100 |
-| Memory per file | < 10MB |
-| Rule execution | < 50ms per rule |
-| Total for 100 files | < 5 seconds |
+| Metric              | Target          |
+| ------------------- | --------------- |
+| Files per second    | > 100           |
+| Memory per file     | < 10MB          |
+| Rule execution      | < 50ms per rule |
+| Total for 100 files | < 5 seconds     |
 
 ## Exit Codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | No errors or warnings |
-| 1 | At least one error found |
-| 2 | Configuration error |
-| 3 | Critical error (parse failure) |
+| Code | Meaning                        |
+| ---- | ------------------------------ |
+| 0    | No errors or warnings          |
+| 1    | At least one error found       |
+| 2    | Configuration error            |
+| 3    | Critical error (parse failure) |

package/docs/linter/extending.md

@@ -35,42 +35,45 @@ import { Document, Node } from '@xmldom/xmldom';
 import { BaseRule, Issue, ValidationContext, Severity, RuleCategory } from '@types';
 
 export class ApiNamingRule extends BaseRule {
-    // Required properties
-    id = 'MULE-103';
-    name = 'API Naming Convention';
-    description = 'API implementation flows should follow the pattern: {api-name}-{version}-{operation}';
-    severity: Severity = 'warning';
-    category: RuleCategory = 'naming';
-    
-    // Optional: Link to documentation
-    docsUrl = 'https://your-wiki/mule-standards#api-naming';
-    
-    validate(doc: Document, context: ValidationContext): Issue[] {
-        const issues: Issue[] = [];
-        
-        // Your XPath query
-        const flows = this.select('//mule:flow', doc);
-        
-        // Pattern for API flows
-        const apiPattern = /^[\w-]+-v\d+-(?:get|post|put|delete|patch)-[\w-]+$/;
-        
-        for (const flow of flows) {
-            const name = this.getAttribute(flow, 'name');
-            
-            // Only check flows that look like API implementations
-            if (name && name.includes('-api') && !apiPattern.test(name)) {
-                issues.push(this.createIssue(
-                    flow,
-                    `API flow "${name}" doesn't follow naming convention: {api-name}-v{N}-{method}-{resource}`,
-                    {
-                        suggestion: 'Example: orders-api-v1-get-order-by-id'
-                    }
-                ));
-            }
-        }
-        
-        return issues;
+  // Required properties
+  id = 'MULE-103';
+  name = 'API Naming Convention';
+  description =
+    'API implementation flows should follow the pattern: {api-name}-{version}-{operation}';
+  severity: Severity = 'warning';
+  category: RuleCategory = 'naming';
+
+  // Optional: Link to documentation
+  docsUrl = 'https://your-wiki/mule-standards#api-naming';
+
+  validate(doc: Document, context: ValidationContext): Issue[] {
+    const issues: Issue[] = [];
+
+    // Your XPath query
+    const flows = this.select('//mule:flow', doc);
+
+    // Pattern for API flows
+    const apiPattern = /^[\w-]+-v\d+-(?:get|post|put|delete|patch)-[\w-]+$/;
+
+    for (const flow of flows) {
+      const name = this.getAttribute(flow, 'name');
+
+      // Only check flows that look like API implementations
+      if (name && name.includes('-api') && !apiPattern.test(name)) {
+        issues.push(
+          this.createIssue(
+            flow,
+            `API flow "${name}" doesn't follow naming convention: {api-name}-v{N}-{method}-{resource}`,
+            {
+              suggestion: 'Example: orders-api-v1-get-order-by-id',
+            },
+          ),
+        );
+      }
     }
+
+    return issues;
+  }
 }
 ```
 
@@ -82,8 +85,8 @@ Add to `src/rules/index.ts`:
 import { ApiNamingRule } from './naming/ApiNamingRule';
 
 export const RULES: Rule[] = [
-    // ... existing rules
-    new ApiNamingRule(),
+  // ... existing rules
+  new ApiNamingRule(),
 ];
 ```
 
@@ -97,51 +100,51 @@ import { parseXml } from '../../../src/core/XmlParser';
 import { createMockContext } from '../../helpers';
 
 describe('ApiNamingRule', () => {
-    const rule = new ApiNamingRule();
-    const context = createMockContext('api.xml');
-    
-    it('should pass for correctly named API flow', () => {
-        const xml = `
+  const rule = new ApiNamingRule();
+  const context = createMockContext('api.xml');
+
+  it('should pass for correctly named API flow', () => {
+    const xml = `
             <mule xmlns="http://www.mulesoft.org/schema/mule/core">
                 <flow name="orders-api-v1-get-order-by-id">
                     <logger message="test"/>
                 </flow>
             </mule>
         `;
-        const doc = parseXml(xml);
-        const issues = rule.validate(doc, context);
-        
-        expect(issues).toHaveLength(0);
-    });
-    
-    it('should fail for incorrectly named API flow', () => {
-        const xml = `
+    const doc = parseXml(xml);
+    const issues = rule.validate(doc, context);
+
+    expect(issues).toHaveLength(0);
+  });
+
+  it('should fail for incorrectly named API flow', () => {
+    const xml = `
             <mule xmlns="http://www.mulesoft.org/schema/mule/core">
                 <flow name="orders-api-getOrders">
                     <logger message="test"/>
                 </flow>
             </mule>
         `;
-        const doc = parseXml(xml);
-        const issues = rule.validate(doc, context);
-        
-        expect(issues).toHaveLength(1);
-        expect(issues[0].ruleId).toBe('MULE-103');
-    });
-    
-    it('should ignore non-API flows', () => {
-        const xml = `
+    const doc = parseXml(xml);
+    const issues = rule.validate(doc, context);
+
+    expect(issues).toHaveLength(1);
+    expect(issues[0].ruleId).toBe('MULE-103');
+  });
+
+  it('should ignore non-API flows', () => {
+    const xml = `
             <mule xmlns="http://www.mulesoft.org/schema/mule/core">
                 <flow name="utility-flow">
                     <logger message="test"/>
                 </flow>
             </mule>
         `;
-        const doc = parseXml(xml);
-        const issues = rule.validate(doc, context);
-        
-        expect(issues).toHaveLength(0);
-    });
+    const doc = parseXml(xml);
+    const issues = rule.validate(doc, context);
+
+    expect(issues).toHaveLength(0);
+  });
 });
 ```
 
@@ -153,20 +156,24 @@ Create `docs/rules/MULE-103.md`:
 # MULE-103: API Naming Convention
 
 ## Overview
-| Property | Value |
-|----------|-------|
-| **ID** | MULE-103 |
-| **Severity** | Warning |
-| **Category** | Naming |
-| **Fixable** | No |
+
+| Property     | Value    |
+| ------------ | -------- |
+| **ID**       | MULE-103 |
+| **Severity** | Warning  |
+| **Category** | Naming   |
+| **Fixable**  | No       |
 
 ## Description
+
 API implementation flows should follow a consistent naming pattern that includes the API name, version, HTTP method, and resource.
 
 ## Pattern
 ```
+
 {api-name}-v{version}-{method}-{resource}
-```
+
+````
 
 ## Examples
 
@@ -175,9 +182,10 @@ API implementation flows should follow a consistent naming pattern that includes
 <flow name="orders-api-getOrders">
 <flow name="OrdersGetFlow">
 <flow name="get-orders">
-```
+````
 
 ### ✅ Good
+
 ```xml
 <flow name="orders-api-v1-get-orders">
 <flow name="orders-api-v1-post-order">
@@ -185,6 +193,7 @@ API implementation flows should follow a consistent naming pattern that includes
 ```
 
 ## Configuration
+
 ```json
 {
   "MULE-103": {
@@ -197,8 +206,10 @@ API implementation flows should follow a consistent naming pattern that includes
 ```
 
 ## Related Rules
+
 - MULE-002: Flow Naming Convention
 - MULE-101: Flow Name Casing
+
 ```
 
 ---
@@ -210,15 +221,17 @@ For organization-specific rules, create a separate npm package:
 ### Package Structure
 
 ```
+
 mule-lint-rules-acme/
 ├── src/
-│   ├── rules/
-│   │   ├── AcmeLoggingRule.ts
-│   │   └── AcmeSecurityRule.ts
-│   └── index.ts
+│ ├── rules/
+│ │ ├── AcmeLoggingRule.ts
+│ │ └── AcmeSecurityRule.ts
+│ └── index.ts
 ├── package.json
 └── tsconfig.json
-```
+
+````
 
 ### package.json
 
@@ -233,7 +246,7 @@ mule-lint-rules-acme/
   },
   "keywords": ["mule-lint", "mule-lint-rules"]
 }
-```
+````
 
 ### Export Rules
 
@@ -243,10 +256,7 @@ import { Rule } from 'mule-lint';
 import { AcmeLoggingRule } from './rules/AcmeLoggingRule';
 import { AcmeSecurityRule } from './rules/AcmeSecurityRule';
 
-export const rules: Rule[] = [
-    new AcmeLoggingRule(),
-    new AcmeSecurityRule(),
-];
+export const rules: Rule[] = [new AcmeLoggingRule(), new AcmeSecurityRule()];
 
 // Named exports for individual rules
 export { AcmeLoggingRule, AcmeSecurityRule };
@@ -291,16 +301,16 @@ import { BaseRule, Issue, ValidationContext } from 'mule-lint';
 import { Document } from '@xmldom/xmldom';
 
 export class ProjectSpecificRule extends BaseRule {
-    id = 'PROJECT-001';
-    name = 'Project Specific Check';
-    description = 'Custom check for this project';
-    severity = 'warning' as const;
-    category = 'standards' as const;
-    
-    validate(doc: Document, context: ValidationContext): Issue[] {
-        // Your custom logic
-        return [];
-    }
+  id = 'PROJECT-001';
+  name = 'Project Specific Check';
+  description = 'Custom check for this project';
+  severity = 'warning' as const;
+  category = 'standards' as const;
+
+  validate(doc: Document, context: ValidationContext): Issue[] {
+    // Your custom logic
+    return [];
+  }
 }
 ```
 
@@ -322,18 +332,20 @@ const nodes = this.select('//http:request[@url]', doc);
 
 ```typescript
 // ❌ Vague
-message: 'Naming violation detected'
+message: 'Naming violation detected';
 
 // ✅ Specific and actionable
-message: `Flow "${name}" should end with "-flow". Rename to "${name}-flow"`
+message: `Flow "${name}" should end with "-flow". Rename to "${name}-flow"`;
 ```
 
 ### 3. Include Suggestions
 
 ```typescript
-issues.push(this.createIssue(node, message, {
-    suggestion: 'Add category attribute: category="com.acme.integration"'
-}));
+issues.push(
+  this.createIssue(node, message, {
+    suggestion: 'Add category attribute: category="com.acme.integration"',
+  }),
+);
 ```
 
 ### 4. Support Configuration
@@ -342,7 +354,7 @@ issues.push(this.createIssue(node, message, {
 validate(doc: Document, context: ValidationContext): Issue[] {
     // Read from rule config
     const suffix = context.config.options?.flowSuffix ?? '-flow';
-    
+
     // Use in validation
     if (!name.endsWith(suffix)) {
         // ...
@@ -355,16 +367,16 @@ validate(doc: Document, context: ValidationContext): Issue[] {
 ```typescript
 validate(doc: Document, context: ValidationContext): Issue[] {
     const flows = this.select('//mule:flow', doc);
-    
+
     for (const flow of flows) {
         const name = this.getAttribute(flow, 'name');
-        
+
         // Guard against missing attributes
         if (!name) continue;
-        
+
         // Skip excluded patterns
         if (this.isExcluded(name, context)) continue;
-        
+
         // Actual validation
         // ...
     }
@@ -381,32 +393,29 @@ When building a VS Code extension, import rules directly:
 import { LintEngine, RULES, Rule, Issue } from 'mule-lint';
 
 class MuleLintDiagnosticProvider {
-    private engine: LintEngine;
-    
-    constructor() {
-        this.engine = new LintEngine({
-            rules: RULES,
-            // Or filter rules
-            // rules: RULES.filter(r => r.severity === 'error')
-        });
-    }
-    
-    async provideDiagnostics(document: vscode.TextDocument): Promise<vscode.Diagnostic[]> {
-        const issues = await this.engine.scanContent(
-            document.getText(),
-            document.uri.fsPath
-        );
-        
-        return issues.map(issue => this.toDiagnostic(issue));
-    }
-    
-    private toDiagnostic(issue: Issue): vscode.Diagnostic {
-        return new vscode.Diagnostic(
-            new vscode.Range(issue.line - 1, 0, issue.line - 1, 100),
-            `[${issue.ruleId}] ${issue.message}`,
-            this.toSeverity(issue.severity)
-        );
-    }
+  private engine: LintEngine;
+
+  constructor() {
+    this.engine = new LintEngine({
+      rules: RULES,
+      // Or filter rules
+      // rules: RULES.filter(r => r.severity === 'error')
+    });
+  }
+
+  async provideDiagnostics(document: vscode.TextDocument): Promise<vscode.Diagnostic[]> {
+    const issues = await this.engine.scanContent(document.getText(), document.uri.fsPath);
+
+    return issues.map((issue) => this.toDiagnostic(issue));
+  }
+
+  private toDiagnostic(issue: Issue): vscode.Diagnostic {
+    return new vscode.Diagnostic(
+      new vscode.Range(issue.line - 1, 0, issue.line - 1, 100),
+      `[${issue.ruleId}] ${issue.message}`,
+      this.toSeverity(issue.severity),
+    );
+  }
 }
 ```