@sfdxy/mule-lint 1.7.1 → 1.8.2

package/docs/linter/rule-engine.md

@@ -0,0 +1,532 @@
+# Rule Engine Documentation
+
+> **Version:** 1.0.0  
+> **Purpose:** Comprehensive guide to the mule-lint rule engine internals, extensibility, and best practices.
+
+---
+
+## Overview
+
+The Rule Engine is the heart of mule-lint. It orchestrates:
+
+1. **Discovery** - Finding XML files to analyze
+2. **Parsing** - Converting XML to queryable DOM
+3. **Validation** - Running rules against the DOM
+4. **Reporting** - Aggregating and formatting results
+
+---
+
+## Core Interfaces
+
+### Rule Interface
+
+Every rule must implement this contract:
+
+```typescript
+import { Document } from '@xmldom/xmldom';
+
+export type Severity = 'error' | 'warning' | 'info';
+
+export type RuleCategory = 
+    | 'naming'
+    | 'error-handling'
+    | 'security'
+    | 'logging'
+    | 'standards'
+    | 'performance'
+    | 'documentation';
+
+export interface Issue {
+    line: number;
+    column?: number;
+    message: string;
+    ruleId: string;
+    severity: Severity;
+    suggestion?: string;     // Optional fix suggestion
+    codeSnippet?: string;    // Relevant code context
+}
+
+export interface ValidationContext {
+    filePath: string;        // Absolute path to file
+    relativePath: string;    // Path relative to project root
+    projectRoot: string;     // Project root directory
+    config: RuleConfig;      // Rule-specific configuration
+}
+
+export interface Rule {
+    // Unique identifier (e.g., "MULE-001")
+    id: string;
+    
+    // Human-readable name
+    name: string;
+    
+    // Detailed description for documentation
+    description: string;
+    
+    // Default severity (can be overridden by config)
+    severity: Severity;
+    
+    // Category for grouping in reports
+    category: RuleCategory;
+    
+    // Optional: documentation URL
+    docsUrl?: string;
+    
+    // The validation function
+    validate(doc: Document, context: ValidationContext): Issue[];
+}
+```
+
+### RuleConfig Interface
+
+Per-rule configuration:
+
+```typescript
+export interface RuleConfig {
+    enabled: boolean;
+    severity?: Severity;        // Override default
+    options?: Record<string, unknown>;  // Rule-specific options
+}
+```
+
+---
+
+## Base Rule Class
+
+All rules should extend `BaseRule` for common utilities:
+
+```typescript
+import { Document, Node } from '@xmldom/xmldom';
+import { Rule, Issue, Severity, RuleCategory, ValidationContext } from '@types';
+import { XPathHelper } from '@core/XPathHelper';
+
+export abstract class BaseRule implements Rule {
+    abstract id: string;
+    abstract name: string;
+    abstract description: string;
+    abstract severity: Severity;
+    abstract category: RuleCategory;
+    
+    docsUrl?: string;
+    
+    protected xpath = XPathHelper.getInstance();
+    
+    abstract validate(doc: Document, context: ValidationContext): Issue[];
+    
+    // --- Utility Methods ---
+    
+    /**
+     * Execute XPath and return matching nodes
+     */
+    protected select(expression: string, doc: Document): Node[] {
+        return this.xpath.select(expression, doc);
+    }
+    
+    /**
+     * Create an issue with consistent formatting
+     */
+    protected createIssue(
+        node: Node,
+        message: string,
+        options?: {
+            suggestion?: string;
+            severity?: Severity;
+        }
+    ): Issue {
+        return {
+            line: this.getLineNumber(node),
+            column: this.getColumnNumber(node),
+            message,
+            ruleId: this.id,
+            severity: options?.severity ?? this.severity,
+            suggestion: options?.suggestion,
+        };
+    }
+    
+    /**
+     * Get line number from node (xmldom stores this)
+     */
+    protected getLineNumber(node: Node): number {
+        // xmldom stores line info in columnNumber/lineNumber
+        return (node as any).lineNumber ?? 1;
+    }
+    
+    /**
+     * Get column number from node
+     */
+    protected getColumnNumber(node: Node): number | undefined {
+        return (node as any).columnNumber;
+    }
+    
+    /**
+     * Check if a node has a specific attribute
+     */
+    protected hasAttribute(node: Node, attrName: string): boolean {
+        const element = node as Element;
+        return element.hasAttribute?.(attrName) ?? false;
+    }
+    
+    /**
+     * Get attribute value from node
+     */
+    protected getAttribute(node: Node, attrName: string): string | null {
+        const element = node as Element;
+        return element.getAttribute?.(attrName) ?? null;
+    }
+}
+```
+
+---
+
+## XPath Reference for MuleSoft
+
+### Namespace Map
+
+```typescript
+const MULE_NAMESPACES = {
+    'mule': 'http://www.mulesoft.org/schema/mule/core',
+    'http': 'http://www.mulesoft.org/schema/mule/http',
+    'https': 'http://www.mulesoft.org/schema/mule/https',
+    'ee': 'http://www.mulesoft.org/schema/mule/ee/core',
+    'doc': 'http://www.mulesoft.org/schema/mule/documentation',
+    'tls': 'http://www.mulesoft.org/schema/mule/tls',
+    'db': 'http://www.mulesoft.org/schema/mule/db',
+    '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',
+    'api-gateway': 'http://www.mulesoft.org/schema/mule/api-gateway',
+    'secure-properties': 'http://www.mulesoft.org/schema/mule/secure-properties',
+    'os': 'http://www.mulesoft.org/schema/mule/os',
+    'batch': 'http://www.mulesoft.org/schema/mule/batch',
+};
+```
+
+### Common XPath Patterns
+
+| Purpose | XPath Expression |
+|---------|------------------|
+| All flows | `//mule:flow` |
+| All sub-flows | `//mule:sub-flow` |
+| Flow by name | `//mule:flow[@name='my-flow']` |
+| All loggers | `//mule:logger` |
+| Loggers without category | `//mule:logger[not(@category)]` |
+| All error handlers | `//mule:error-handler` |
+| All on-error blocks | `//mule:on-error-continue \| //mule:on-error-propagate` |
+| All HTTP listeners | `//http:listener` |
+| All HTTP requests | `//http:request` |
+| Choice blocks | `//mule:choice` |
+| DataWeave transforms | `//ee:transform` |
+| Set-variable | `//mule:set-variable` |
+| Flows without error handler | `//mule:flow[not(mule:error-handler)]` |
+| Attributes starting with http | `//*[@*[starts-with(., 'http:')]]` |
+
+---
+
+## Rule Implementation Examples
+
+### Example 1: Flow Naming Rule
+
+```typescript
+import { Document, Node } from '@xmldom/xmldom';
+import { BaseRule, Issue, ValidationContext } from '@types';
+
+export class FlowNamingRule extends BaseRule {
+    id = 'MULE-002';
+    name = 'Flow Naming Convention';
+    description = 'Flows must end with "-flow", sub-flows with "-subflow"';
+    severity = 'warning' as const;
+    category = 'naming' as const;
+    
+    validate(doc: Document, context: ValidationContext): Issue[] {
+        const issues: Issue[] = [];
+        
+        // Check flows
+        const flows = this.select('//mule:flow', doc);
+        for (const flow of flows) {
+            const name = this.getAttribute(flow, 'name');
+            if (name && !name.endsWith('-flow')) {
+                issues.push(this.createIssue(
+                    flow,
+                    `Flow "${name}" should end with "-flow"`,
+                    { suggestion: `Rename to "${name}-flow"` }
+                ));
+            }
+        }
+        
+        // Check sub-flows
+        const subflows = this.select('//mule:sub-flow', doc);
+        for (const subflow of subflows) {
+            const name = this.getAttribute(subflow, 'name');
+            if (name && !name.endsWith('-subflow')) {
+                issues.push(this.createIssue(
+                    subflow,
+                    `Sub-flow "${name}" should end with "-subflow"`,
+                    { suggestion: `Rename to "${name}-subflow"` }
+                ));
+            }
+        }
+        
+        return issues;
+    }
+}
+```
+
+### Example 2: Logger Category Rule
+
+```typescript
+import { Document, Node } from '@xmldom/xmldom';
+import { BaseRule, Issue, ValidationContext } from '@types';
+
+export class LoggerCategoryRule extends BaseRule {
+    id = 'MULE-006';
+    name = 'Logger Category Required';
+    description = 'All loggers must have a category attribute for proper log filtering';
+    severity = 'warning' as const;
+    category = 'logging' as const;
+    
+    validate(doc: Document, context: ValidationContext): Issue[] {
+        const issues: Issue[] = [];
+        
+        const loggers = this.select('//mule:logger[not(@category)]', doc);
+        
+        for (const logger of loggers) {
+            const message = this.getAttribute(logger, 'message') || 'unknown';
+            issues.push(this.createIssue(
+                logger,
+                `Logger is missing 'category' attribute`,
+                { 
+                    suggestion: `Add category="com.myorg.${context.relativePath.replace(/\//g, '.')}"` 
+                }
+            ));
+        }
+        
+        return issues;
+    }
+}
+```
+
+### Example 3: Hardcoded HTTP Rule (Security)
+
+```typescript
+import { Document, Node, Element } from '@xmldom/xmldom';
+import { BaseRule, Issue, ValidationContext } from '@types';
+
+export class HardcodedHttpRule extends BaseRule {
+    id = 'MULE-004';
+    name = 'Hardcoded HTTP URLs';
+    description = 'HTTP/HTTPS URLs should use properties, not hardcoded values';
+    severity = 'error' as const;
+    category = 'security' as const;
+    
+    private readonly URL_PATTERN = /^https?:\/\//i;
+    private readonly ALLOWED_PATTERNS = [
+        /\$\{[^}]+\}/,  // Property placeholders ${...}
+        /\#\[[^\]]+\]/,  // DataWeave expressions #[...]
+    ];
+    
+    validate(doc: Document, context: ValidationContext): Issue[] {
+        const issues: Issue[] = [];
+        
+        // Find all elements with attributes containing http:// or https://
+        const allElements = doc.getElementsByTagName('*');
+        
+        for (let i = 0; i < allElements.length; i++) {
+            const element = allElements[i];
+            const attrs = element.attributes;
+            
+            for (let j = 0; j < attrs.length; j++) {
+                const attr = attrs[j];
+                const value = attr.value;
+                
+                if (this.URL_PATTERN.test(value) && !this.isAllowedPattern(value)) {
+                    issues.push(this.createIssue(
+                        element,
+                        `Hardcoded URL "${this.truncate(value)}" found in attribute "${attr.name}"`,
+                        { 
+                            suggestion: 'Use property placeholder: ${http.url}' 
+                        }
+                    ));
+                }
+            }
+        }
+        
+        return issues;
+    }
+    
+    private isAllowedPattern(value: string): boolean {
+        return this.ALLOWED_PATTERNS.some(pattern => pattern.test(value));
+    }
+    
+    private truncate(value: string, maxLen = 50): string {
+        return value.length > maxLen ? value.substring(0, maxLen) + '...' : value;
+    }
+}
+```
+
+---
+
+## Rule Registration
+
+Rules are registered in `src/rules/index.ts`:
+
+```typescript
+import { Rule } from '@types';
+
+// Import all rules
+import { FlowNamingRule } from './naming/FlowNamingRule';
+import { GlobalErrorHandlerRule } from './error-handling/GlobalErrorHandlerRule';
+import { MissingErrorHandlerRule } from './error-handling/MissingErrorHandlerRule';
+import { HardcodedHttpRule } from './security/HardcodedHttpRule';
+import { HttpStatusRule } from './error-handling/HttpStatusRule';
+import { LoggerCategoryRule } from './logging/LoggerCategoryRule';
+import { CorrelationIdRule } from './error-handling/CorrelationIdRule';
+import { ChoiceAntiPatternRule } from './standards/ChoiceAntiPatternRule';
+import { GenericErrorRule } from './error-handling/GenericErrorRule';
+import { DwlStandardsRule } from './standards/DwlStandardsRule';
+
+// Rule registry
+export const RULES: Rule[] = [
+    new FlowNamingRule(),
+    new GlobalErrorHandlerRule(),
+    new MissingErrorHandlerRule(),
+    new HardcodedHttpRule(),
+    new HttpStatusRule(),
+    new LoggerCategoryRule(),
+    new CorrelationIdRule(),
+    new ChoiceAntiPatternRule(),
+    new GenericErrorRule(),
+    new DwlStandardsRule(),
+];
+
+// Export for external use
+export * from './naming/FlowNamingRule';
+export * from './error-handling/GlobalErrorHandlerRule';
+// ... etc
+```
+
+---
+
+## Engine Processing Flow
+
+```mermaid
+flowchart TD
+    START[Start Scan] --> CONFIG[Load Configuration]
+    CONFIG --> DISCOVER[Discover XML Files]
+    DISCOVER --> PARSE[Parse XML to DOM]
+    PARSE --> CHECK{Parse Error?}
+    CHECK -- Yes --> CRITICAL[Report Critical Error]
+    CHECK -- No --> RULES[Run All Rules]
+    RULES --> COLLECT[Collect Issues]
+    COLLECT --> AGGREGATE[Aggregate Results]
+    AGGREGATE --> FORMAT[Format Output]
+    FORMAT --> EXIT[Set Exit Code]
+    CRITICAL --> COLLECT
+```
+
+---
+
+## Configuration
+
+### `.mulelintrc.json` Schema
+
+```json
+{
+  "$schema": "./node_modules/mule-lint/config-schema.json",
+  "rules": {
+    "MULE-001": { "enabled": true, "severity": "error" },
+    "MULE-002": { "enabled": true, "severity": "warning" },
+    "MULE-003": { 
+      "enabled": true, 
+      "options": {
+        "excludePatterns": ["*-api-main"]
+      }
+    }
+  },
+  "include": ["src/main/mule/**/*.xml"],
+  "exclude": ["**/test/**", "**/*.munit.xml"],
+  "formatters": {
+    "default": "table",
+    "ci": "sarif"
+  }
+}
+```
+
+### Rule-Specific Options
+
+Some rules support additional options:
+
+| Rule | Option | Type | Default | Description |
+|------|--------|------|---------|-------------|
+| MULE-002 | `flowSuffix` | string | `-flow` | Expected flow name suffix |
+| MULE-002 | `subflowSuffix` | string | `-subflow` | Expected sub-flow suffix |
+| MULE-003 | `excludePatterns` | string[] | `[]` | Flow name patterns to exclude |
+| MULE-006 | `requirePrefix` | string | `null` | Required category prefix |
+
+---
+
+## Testing Rules
+
+### Test Structure
+
+```typescript
+import { FlowNamingRule } from '../rules/naming/FlowNamingRule';
+import { parseXml } from '../core/XmlParser';
+
+describe('FlowNamingRule', () => {
+    const rule = new FlowNamingRule();
+    
+    it('should pass for correctly named flow', () => {
+        const xml = `
+            <mule xmlns="http://www.mulesoft.org/schema/mule/core">
+                <flow name="my-process-flow">
+                    <logger message="test"/>
+                </flow>
+            </mule>
+        `;
+        const doc = parseXml(xml);
+        const issues = rule.validate(doc, mockContext);
+        
+        expect(issues).toHaveLength(0);
+    });
+    
+    it('should fail for incorrectly named flow', () => {
+        const xml = `
+            <mule xmlns="http://www.mulesoft.org/schema/mule/core">
+                <flow name="myProcess">
+                    <logger message="test"/>
+                </flow>
+            </mule>
+        `;
+        const doc = parseXml(xml);
+        const issues = rule.validate(doc, mockContext);
+        
+        expect(issues).toHaveLength(1);
+        expect(issues[0].ruleId).toBe('MULE-002');
+        expect(issues[0].message).toContain('myProcess');
+    });
+});
+```
+
+---
+
+## 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/mcp-design.md

@@ -0,0 +1,80 @@
+# Mule Lint MCP Server Design
+
+## Executive Summary
+This document outlines the strategy for exposing `mule-lint` capabilities via the Model Context Protocol (MCP). By wrapping the linter in an MCP server, we enable AI agents (like Claude, IDE assistants, etc.) to autonomously discover linting rules, validate MuleSoft projects, and retrieve detailed rule documentation without needing to shell out or parse CLI text output.
+
+## Architecture Decision: Monorepo vs. Separate Repo
+**Recommendation: Same Repo (Monorepo)**
+
+We should implement the MCP server directly in the `mule-lint` repository, likely under `src/mcp` or as a separate package if this was a workspace.
+*   **Pros**: Direct access to `src/core`, `src/rules`, and types without publishing/installing packages. Easier to keep rule definitions and agent-exposed descriptions in sync.
+*   **Cons**: Adds a dependency on `@modelcontextprotocol/sdk` to the main repo (or requires a build split).
+
+## Features & Capabilities
+
+### 1. Tools
+Tools allow the agent to perform actions.
+
+| Tool Name | Arguments | Description |
+| :--- | :--- | :--- |
+| `run_lint_analysis` | `projectPath` (string) | Runs the scanning engine on a specified directory. Returns a JSON summary of errors, warnings, and code references. |
+| `validate_snippet` | `code` (string), `type` (xml/dwl) | quickly validates a small chunk of code without a full project structure. Useful for agents generating code on the fly. |
+| `get_rule_details` | `ruleId` (string) | Returns the full documentation, examples, and rationale for a specific rule (e.g., `MULE-001`). |
+
+### 2. Resources
+Resources allow the agent to read context.
+
+| Resource URI | Description |
+| :--- | :--- |
+| `mule-lint://rules` | A JSON list of all registered rules, their categories, and severity levels. |
+| `mule-lint://config/schema` | The JSON schema for `.mule-lintrc` to help agents author valid configurations. |
+| `mule-lint://docs/{slug}` | Access internal documentation (e.g., `best-practices`, `architecture`, `naming`). |
+
+### 3. Prompts
+Pre-defined prompts to help users interacting with the agent.
+
+| Prompt Name | Description |
+| :--- | :--- |
+| `analyze_current_project` | "Run a comprehensive analysis on this project and summarize the top 3 critical issues." |
+| `explain_violation` | "Here is an error I found: {{ErrorString}}. Explain why this is bad and how to fix it using `get_rule_details`." |
+
+## Implementation Phases
+
+### Phase 1: Foundation (The "Reader" Agent)
+> [!NOTE]
+> **Status**: Completed. Available on NPM as `@sfdxy/mule-lint`.
+
+*Goal: Allow an agent to see what rules exist and run a scan.*
+- [x] Install `@modelcontextprotocol/sdk`.
+- [x] Create `McpServer` class in `src/mcp/index.ts`.
+- [x] Implement `mule-lint://rules` resource.
+- [x] Implement `run_lint_analysis` tool (wrapping `LintEngine`).
+- [x] Add `stdio` transport for local running.
+
+### Phase 2: Interactive Context (The "Helper" Agent)
+> [!NOTE]
+> **Status**: Completed.
+
+*Goal: Allow the agent to understand *why* things failed.*
+- [x] Implement `get_rule_details` tool.
+- [x] Expose internal documentation of rules via MCP.
+- [x] Add `validate_snippet` for real-time code generation checks.
+
+### Phase 3: Remediation (The "Fixer" Agent)
+> [!NOTE]
+> **Status**: Partially Completed. `apply_fix` deferred. Enhanced reporting added.
+
+*Goal: Allow the agent to automatically fix issues.*
+- [ ] Implement `apply_fix` tool (Deferred: requires AST write support).
+- [x] Enhanced error reporting with precise range/location data (Added column/suggestion).
+
+## Libraries & Dependencies
+*   **Core**: `@modelcontextprotocol/sdk`
+*   **Transport**: Stdio (standard input/output) for local CLI integration.
+*   **Runtime**: Node.js (uses existing project runtime).
+
+## Agent Workflow Example
+1.  **Discovery**: Agent connects and reads `mule-lint://rules` to know what it is looking for.
+2.  **Action**: User asks "Check my code". Agent calls `run_lint_analysis(cwd)`.
+3.  **Context**: Agent sees error `DW-004`. Agent calls `get_rule_details("DW-004")` to read the "Java 17 DataWeave" docs.
+4.  **Result**: Agent explains the error to the user with specific context from the official rule definitions.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sfdxy/mule-lint",
-    "version": "1.7.1",
+    "version": "1.8.2",
     "description": "Static analysis tool for MuleSoft applications - supports humans, AI agents, and CI/CD pipelines",
     "author": "Avinava",
     "license": "MIT",
@@ -14,14 +14,16 @@
         "cli"
     ],
     "bin": {
-        "mule-lint": "./dist/bin/mule-lint.js"
+        "mule-lint": "./dist/bin/mule-lint.js",
+        "mule-lint-mcp": "./dist/bin/mule-lint-mcp.js"
     },
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "files": [
         "dist",
         "README.md",
-        "LICENSE"
+        "LICENSE",
+        "docs"
     ],
     "scripts": {
         "build": "tsc",
@@ -37,6 +39,7 @@
         "release": "git tag v$(node -p 'require(\"./package.json\").version') && git push origin v$(node -p 'require(\"./package.json\").version')"
     },
     "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.25.2",
         "@xmldom/xmldom": "^0.8.10",
         "chalk": "^4.1.2",
         "commander": "^11.1.0",