@sfdxy/mule-lint 1.7.1 → 1.8.2

package/docs/linter/architecture.md

@@ -0,0 +1,294 @@
+# Architecture
+
+This document describes the architecture, design patterns, and best practices used in mule-lint.
+
+## System Overview
+
+```mermaid
+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 (40 Total)"]
+        D --> R1[Error Handling<br/>MULE-001,003,005,007,009]
+        D --> R2[Naming<br/>MULE-002,101,102]
+        D --> R3[Security<br/>MULE-004,201,202]
+        D --> R4[Logging<br/>MULE-006,301,303]
+        D --> R5[HTTP<br/>MULE-401,402,403]
+        D --> R6[Performance<br/>MULE-501,502,503]
+        D --> R7[Documentation<br/>MULE-601,604]
+        D --> R8[Standards<br/>MULE-008,010,701]
+        D --> R9[Complexity<br/>MULE-801]
+        D --> R10[Structure<br/>MULE-802-804]
+        D --> R11[YAML<br/>YAML-001,003,004]
+        D --> R12[DataWeave<br/>DW-001,002,003]
+        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
+    D --> L
+    D --> M
+```
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant CLI
+    participant Engine as LintEngine
+    participant Scanner as FileScanner
+    participant Parser as XmlParser
+    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
+```
+
+## Core Components
+
+### 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
+4. Aggregates results into a LintReport
+
+```typescript
+const engine = new LintEngine({ rules: ALL_RULES, config });
+const report = await engine.scan('./project');
+```
+
+### XPathHelper
+
+Singleton utility for namespace-aware XPath queries:
+
+```typescript
+const xpath = XPathHelper.getInstance();
+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 |
+
+### BaseRule
+
+Abstract base class providing utilities to all rules:
+
+```mermaid
+classDiagram
+    class BaseRule {
+        +id: string
+        +name: string
+        +severity: Severity
+        +category: RuleCategory
+        +validate(doc, context): Issue[]
+        #select(xpath, doc): Node[]
+        #getAttribute(node, name): string
+        #createIssue(node, message): Issue
+        #getOption(context, key, default): T
+    }
+    
+    class FlowNamingRule {
+        +validate()
+    }
+    
+    class YamlRuleBase {
+        +validate()
+        #findYamlFiles(): string[]
+    }
+    
+    BaseRule <|-- FlowNamingRule
+    BaseRule <|-- YamlRuleBase
+```
+
+## Design Patterns
+
+### Strategy Pattern (Rules)
+
+Each rule is a strategy implementing the same interface:
+
+```typescript
+interface Rule {
+    id: string;
+    name: string;
+    severity: Severity;
+    validate(doc: Document, context: ValidationContext): Issue[];
+}
+```
+
+### Factory Pattern (Formatters)
+
+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;
+    }
+}
+```
+
+### Singleton Pattern (XPathHelper)
+
+XPathHelper uses singleton to avoid recreating namespace resolver:
+
+```typescript
+XPathHelper.getInstance(); // Same instance always
+```
+
+## Directory Structure
+
+```
+src/
+├── index.ts              # Package entry point
+├── types/                # TypeScript interfaces
+│   ├── Rule.ts          # Rule, Issue, Severity
+│   ├── Report.ts        # LintReport, FileResult
+│   └── Config.ts        # LintConfig, CliOptions
+├── core/                 # Core utilities
+│   ├── XPathHelper.ts   # Namespace-aware XPath
+│   ├── XmlParser.ts     # DOM parsing
+│   ├── YamlParser.ts    # YAML parsing
+│   ├── FileScanner.ts   # File discovery
+│   └── ComplexityCalculator.ts
+├── engine/               # Orchestration
+│   └── LintEngine.ts    # Main engine
+├── rules/                # All rules (40 total)
+│   ├── index.ts         # Rule registry
+│   ├── base/            # BaseRule class
+│   ├── api-led/         # API-001, 002, 003
+│   ├── complexity/      # MULE-801
+│   ├── dataweave/       # DW-001, 002, 003
+│   ├── documentation/   # MULE-601, 604
+│   ├── error-handling/  # MULE-001, 003, 005, 007, 009
+│   ├── experimental/    # EXP-001, 002, 003
+│   ├── http/            # MULE-401, 402, 403
+│   ├── logging/         # MULE-006, 301, 303
+│   ├── naming/          # MULE-002, 101, 102
+│   ├── performance/     # MULE-501, 502, 503
+│   ├── security/        # MULE-004, 201, 202
+│   ├── standards/       # MULE-008, 010, 701
+│   ├── structure/       # MULE-802, 803, 804
+│   └── yaml/            # YAML-001, 003, 004
+└── formatters/           # Output formatters
+    ├── TableFormatter.ts
+    ├── JsonFormatter.ts
+    ├── SarifFormatter.ts
+    └── HtmlFormatter.ts
+```
+
+## 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 |
+
+## Extension Points
+
+### Adding Rules
+
+1. Create class extending `BaseRule`
+2. Implement `validate()` method
+3. Register in `src/rules/index.ts`
+4. Add documentation to `docs/rules-catalog.md`
+
+### Adding Formatters
+
+1. Create function implementing formatter interface
+2. Add to factory in `src/formatters/index.ts`
+3. Update `FormatterType` in types
+
+## Error Handling
+
+- **Parse Errors**: Captured and reported, don't stop scan
+- **Rule Errors**: Caught and logged, continue with next rule
+- **File Errors**: Reported in results, continue scanning
+
+## Performance Specifications
+
+| 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) |

package/docs/linter/extending.md

@@ -0,0 +1,426 @@
+# Extending mule-lint
+
+> A guide for adding custom rules to mule-lint
+
+---
+
+## Overview
+
+mule-lint is designed to be easily extensible. You can add new rules by:
+
+1. **Built-in rules**: Adding to the core package (for contributors)
+2. **External rules**: Creating a separate npm package
+3. **Local rules**: Adding project-specific rules via configuration
+
+---
+
+## Creating a New Rule
+
+### Step 1: Create Rule File
+
+Create a new file in the appropriate category folder:
+
+```bash
+# For a naming rule
+touch src/rules/naming/ApiNamingRule.ts
+
+# For a security rule
+touch src/rules/security/ApiKeyExposureRule.ts
+```
+
+### Step 2: Implement the Rule
+
+```typescript
+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;
+    }
+}
+```
+
+### Step 3: Register the Rule
+
+Add to `src/rules/index.ts`:
+
+```typescript
+import { ApiNamingRule } from './naming/ApiNamingRule';
+
+export const RULES: Rule[] = [
+    // ... existing rules
+    new ApiNamingRule(),
+];
+```
+
+### Step 4: Write Tests
+
+Create `tests/unit/rules/ApiNamingRule.test.ts`:
+
+```typescript
+import { ApiNamingRule } from '../../../src/rules/naming/ApiNamingRule';
+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 = `
+            <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 = `
+            <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 = `
+            <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);
+    });
+});
+```
+
+### Step 5: Document the Rule
+
+Create `docs/rules/MULE-103.md`:
+
+```markdown
+# MULE-103: API Naming Convention
+
+## Overview
+| 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
+
+### ❌ Bad
+```xml
+<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">
+<flow name="orders-api-v1-get-order-by-id">
+```
+
+## Configuration
+```json
+{
+  "MULE-103": {
+    "enabled": true,
+    "options": {
+      "pattern": "^[\\w-]+-v\\d+-(?:get|post|put|delete|patch)-[\\w-]+$"
+    }
+  }
+}
+```
+
+## Related Rules
+- MULE-002: Flow Naming Convention
+- MULE-101: Flow Name Casing
+```
+
+---
+
+## Creating External Rule Packages
+
+For organization-specific rules, create a separate npm package:
+
+### Package Structure
+
+```
+mule-lint-rules-acme/
+├── src/
+│   ├── rules/
+│   │   ├── AcmeLoggingRule.ts
+│   │   └── AcmeSecurityRule.ts
+│   └── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+### package.json
+
+```json
+{
+  "name": "@acme/mule-lint-rules",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "peerDependencies": {
+    "mule-lint": "^1.0.0"
+  },
+  "keywords": ["mule-lint", "mule-lint-rules"]
+}
+```
+
+### Export Rules
+
+```typescript
+// src/index.ts
+import { Rule } from 'mule-lint';
+import { AcmeLoggingRule } from './rules/AcmeLoggingRule';
+import { AcmeSecurityRule } from './rules/AcmeSecurityRule';
+
+export const rules: Rule[] = [
+    new AcmeLoggingRule(),
+    new AcmeSecurityRule(),
+];
+
+// Named exports for individual rules
+export { AcmeLoggingRule, AcmeSecurityRule };
+```
+
+### Configure mule-lint
+
+```json
+// .mulelintrc.json
+{
+  "extends": ["@acme/mule-lint-rules"],
+  "rules": {
+    "ACME-001": { "enabled": true },
+    "ACME-002": { "enabled": true, "severity": "error" }
+  }
+}
+```
+
+---
+
+## Local/Project-Specific Rules
+
+For one-off project rules without creating a package:
+
+### Configuration
+
+```json
+// .mulelintrc.json
+{
+  "customRulesPath": "./lint-rules",
+  "rules": {
+    "PROJECT-001": { "enabled": true }
+  }
+}
+```
+
+### Local Rule File
+
+```typescript
+// lint-rules/ProjectSpecificRule.ts
+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 [];
+    }
+}
+```
+
+---
+
+## Rule Best Practices
+
+### 1. Be Specific with XPath
+
+```typescript
+// ❌ Too broad - may have false positives
+const nodes = this.select('//*[@url]', doc);
+
+// ✅ Specific - targets only http:request
+const nodes = this.select('//http:request[@url]', doc);
+```
+
+### 2. Provide Actionable Messages
+
+```typescript
+// ❌ Vague
+message: 'Naming violation detected'
+
+// ✅ Specific and actionable
+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"'
+}));
+```
+
+### 4. Support Configuration
+
+```typescript
+validate(doc: Document, context: ValidationContext): Issue[] {
+    // Read from rule config
+    const suffix = context.config.options?.flowSuffix ?? '-flow';
+    
+    // Use in validation
+    if (!name.endsWith(suffix)) {
+        // ...
+    }
+}
+```
+
+### 5. Handle Edge Cases
+
+```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
+        // ...
+    }
+}
+```
+
+---
+
+## VS Code Extension Integration
+
+When building a VS Code extension, import rules directly:
+
+```typescript
+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)
+        );
+    }
+}
+```
+
+---
+
+## Contributing Rules Upstream
+
+To contribute rules to the core mule-lint package:
+
+1. Fork the repository
+2. Create a feature branch: `feature/MULE-XXX-rule-name`
+3. Implement the rule following this guide
+4. Write comprehensive tests
+5. Document the rule
+6. Submit a Pull Request
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed guidelines.