@sfdxy/mule-lint 1.7.1 → 1.8.2

package/docs/linter/folder-structure.md

@@ -0,0 +1,251 @@
+# Folder Structure
+
+> **Rationale:** This structure follows Node.js/TypeScript best practices and ensures clear separation of concerns.
+
+## Overview
+
+```
+mule-lint/
+├── bin/                      # CLI entry points
+│   └── mule-lint.ts         # Main CLI executable
+├── src/                      # Source code
+│   ├── core/                # Core utilities
+│   │   ├── XmlParser.ts     # XML parsing with error handling
+│   │   ├── XPathHelper.ts   # Namespace-aware XPath utilities
+│   │   ├── YamlParser.ts    # YAML parsing utilities
+│   │   ├── FileScanner.ts   # File discovery with glob patterns
+│   │   └── ComplexityCalculator.ts
+│   ├── engine/              # Lint engine
+│   │   ├── LintEngine.ts    # Main orchestrator
+│   │   └── types.ts         # Engine-specific types
+│   ├── rules/               # Rule implementations (40 rules)
+│   │   ├── index.ts         # Rule registry/exports
+│   │   ├── base/            # Base classes for rules
+│   │   │   └── BaseRule.ts  # Abstract rule with utilities
+│   │   ├── api-led/         # API-Led connectivity patterns
+│   │   │   └── ApiLedRules.ts (API-001, 002, 003)
+│   │   ├── complexity/      # Complexity analysis
+│   │   │   └── FlowComplexityRule.ts (MULE-801)
+│   │   ├── dataweave/       # DataWeave file validation
+│   │   │   └── DataWeaveRules.ts (DW-001, 002, 003)
+│   │   ├── documentation/   # Documentation requirements
+│   │   │   ├── FlowDescriptionRule.ts (MULE-601)
+│   │   │   └── MissingDocNameRule.ts (MULE-604)
+│   │   ├── error-handling/  # Error handling rules
+│   │   │   ├── GlobalErrorHandlerRule.ts (MULE-001)
+│   │   │   ├── MissingErrorHandlerRule.ts (MULE-003)
+│   │   │   ├── HttpStatusRule.ts (MULE-005)
+│   │   │   ├── CorrelationIdRule.ts (MULE-007)
+│   │   │   └── GenericErrorRule.ts (MULE-009)
+│   │   ├── experimental/    # Beta rules
+│   │   │   └── ExperimentalRules.ts (EXP-001, 002, 003)
+│   │   ├── http/            # HTTP configuration
+│   │   │   ├── HttpUserAgentRule.ts (MULE-401)
+│   │   │   ├── HttpContentTypeRule.ts (MULE-402)
+│   │   │   └── HttpTimeoutRule.ts (MULE-403)
+│   │   ├── logging/         # Logging rules
+│   │   │   ├── LoggerCategoryRule.ts (MULE-006)
+│   │   │   ├── LoggerPayloadRule.ts (MULE-301)
+│   │   │   └── LoggerInUntilSuccessfulRule.ts (MULE-303)
+│   │   ├── naming/          # Naming conventions
+│   │   │   ├── FlowNamingRule.ts (MULE-002)
+│   │   │   ├── FlowCasingRule.ts (MULE-101)
+│   │   │   └── VariableNamingRule.ts (MULE-102)
+│   │   ├── performance/     # Performance anti-patterns
+│   │   │   ├── ScatterGatherRoutesRule.ts (MULE-501)
+│   │   │   ├── AsyncErrorHandlerRule.ts (MULE-502)
+│   │   │   └── LargeChoiceBlockRule.ts (MULE-503)
+│   │   ├── security/        # Security rules
+│   │   │   ├── HardcodedHttpRule.ts (MULE-004)
+│   │   │   ├── HardcodedCredentialsRule.ts (MULE-201)
+│   │   │   └── InsecureTlsRule.ts (MULE-202)
+│   │   ├── standards/       # Best practices
+│   │   │   ├── ChoiceAntiPatternRule.ts (MULE-008)
+│   │   │   ├── DwlStandardsRule.ts (MULE-010)
+│   │   │   └── DeprecatedComponentRule.ts (MULE-701)
+│   │   ├── structure/       # Project structure
+│   │   │   └── StructureRules.ts (MULE-802, 803, 804)
+│   │   └── yaml/            # YAML validation
+│   │       └── YamlRules.ts (YAML-001, 003, 004)
+│   ├── formatters/          # Output formatters
+│   │   ├── index.ts         # Formatter factory
+│   │   ├── TableFormatter.ts
+│   │   ├── JsonFormatter.ts
+│   │   ├── SarifFormatter.ts
+│   │   └── HtmlFormatter.ts
+│   ├── config/              # Configuration handling
+│   │   ├── ConfigLoader.ts  # Load .mulelintrc.json
+│   │   ├── defaults.ts      # Default configuration
+│   │   └── schema.ts        # Config validation schema
+│   └── types/               # Shared type definitions
+│       ├── index.ts         # Re-exports
+│       ├── Rule.ts          # Rule interface
+│       ├── Issue.ts         # Issue/violation types
+│       ├── Config.ts        # Configuration types
+│       └── Report.ts        # Report types
+├── tests/                    # Test suite
+│   ├── fixtures/            # Test XML files
+│   │   ├── valid/           # Valid Mule configurations
+│   │   ├── invalid/         # Invalid configurations
+│   │   └── edge-cases/      # Edge case scenarios
+│   ├── unit/                # Unit tests
+│   │   ├── rules/           # Rule-specific tests
+│   │   └── core/            # Core utility tests
+│   ├── integration/         # Integration tests
+│   └── setup.ts             # Test configuration
+├── docs/                     # Documentation
+│   ├── README.md            # Documentation index
+│   ├── architecture.md      # System design
+│   ├── folder-structure.md  # This file
+│   ├── naming-conventions.md
+│   ├── rule-engine.md       # Rule engine internals
+│   ├── rules-catalog.md     # All rules documented
+│   └── extending.md         # Custom rules guide
+├── .mulelintrc.json         # Default configuration
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+├── .eslintrc.js
+├── .prettierrc
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+---
+
+## Directory Details
+
+### `/bin`
+
+**Purpose:** CLI entry points that get installed globally via npm.
+
+```json
+// package.json
+{
+  "bin": {
+    "mule-lint": "./dist/bin/mule-lint.js"
+  }
+}
+```
+
+### `/src/core`
+
+**Purpose:** Low-level utilities that don't depend on business logic.
+
+| File | Responsibility |
+|------|----------------|
+| `XmlParser.ts` | Parse XML string to DOM, handle errors gracefully |
+| `XPathHelper.ts` | Namespace-aware XPath queries |
+| `YamlParser.ts` | Parse YAML files, detect sensitive keys |
+| `FileScanner.ts` | Discover `.xml` and `.yaml` files using glob patterns |
+| `ComplexityCalculator.ts` | Calculate cyclomatic complexity of flows |
+
+### `/src/rules`
+
+**Purpose:** All validation rules, organized by category.
+
+**Rule Families (40 total):**
+
+| Family | Directory | Rules |
+|--------|-----------|-------|
+| API-Led | `api-led/` | API-001, 002, 003 |
+| Complexity | `complexity/` | MULE-801 |
+| DataWeave | `dataweave/` | DW-001, 002, 003 |
+| Documentation | `documentation/` | MULE-601, 604 |
+| Error Handling | `error-handling/` | MULE-001, 003, 005, 007, 009 |
+| Experimental | `experimental/` | EXP-001, 002, 003 |
+| HTTP | `http/` | MULE-401, 402, 403 |
+| Logging | `logging/` | MULE-006, 301, 303 |
+| Naming | `naming/` | MULE-002, 101, 102 |
+| Performance | `performance/` | MULE-501, 502, 503 |
+| Security | `security/` | MULE-004, 201, 202 |
+| Standards | `standards/` | MULE-008, 010, 701 |
+| Structure | `structure/` | MULE-802, 803, 804 |
+| YAML | `yaml/` | YAML-001, 003, 004 |
+
+**Convention:** Each rule file exports one or more classes implementing `Rule`.
+
+### `/src/formatters`
+
+**Purpose:** Transform `LintReport` to various output formats.
+
+| Formatter | Use Case |
+|-----------|----------|
+| `TableFormatter.ts` | Human-readable CLI output |
+| `JsonFormatter.ts` | Script/automation consumption |
+| `SarifFormatter.ts` | AI agents and IDE integration |
+| `HtmlFormatter.ts` | Standalone HTML reports |
+
+### `/src/config`
+
+**Purpose:** Handle `.mulelintrc.json` loading and validation.
+
+### `/tests/fixtures`
+
+**Purpose:** Sample XML files for testing rules.
+
+**Naming Convention:**
+- Prefix with rule ID: `MULE-001-global-error-handler.xml`
+- Or use descriptive names: `flow-with-missing-category.xml`
+
+---
+
+## Import Paths
+
+Use TypeScript path aliases for clean imports:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "baseUrl": "./src",
+    "paths": {
+      "@core/*": ["core/*"],
+      "@rules/*": ["rules/*"],
+      "@formatters/*": ["formatters/*"],
+      "@types/*": ["types/*"]
+    }
+  }
+}
+```
+
+**Example Usage:**
+
+```typescript
+import { Rule } from '@types/Rule';
+import { XPathHelper } from '@core/XPathHelper';
+```
+
+---
+
+## File Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Rule class | PascalCase + `Rule` suffix | `FlowNamingRule.ts` |
+| Multi-rule file | Feature + `Rules` suffix | `YamlRules.ts` |
+| Utility class | PascalCase | `XPathHelper.ts` |
+| Type definition | PascalCase | `Issue.ts` |
+| Test file | Match source + `.test.ts` | `FlowNamingRule.test.ts` |
+| Config | lowercase with dots | `jest.config.js` |
+
+---
+
+## Distribution
+
+After build, the `/dist` folder mirrors `/src`:
+
+```
+dist/
+├── bin/
+│   └── mule-lint.js
+├── core/
+├── engine/
+├── rules/
+├── formatters/
+└── types/
+```
+
+Only `/dist` is published to npm (configured in `package.json` files array).

package/docs/linter/naming-conventions.md

@@ -0,0 +1,300 @@
+# Naming Conventions
+
+> **Scope:** This document covers naming conventions for the mule-lint codebase and the MuleSoft projects being validated.
+
+---
+
+## Rule Naming
+
+### Rule IDs
+
+mule-lint uses multiple rule prefixes to organize rules by domain:
+
+| Prefix | Format | Domain | Example |
+|--------|--------|--------|---------|
+| `MULE` | `MULE-NNN` | Core MuleSoft XML validation | `MULE-001` |
+| `YAML` | `YAML-NNN` | YAML properties validation | `YAML-001` |
+| `DW` | `DW-NNN` | DataWeave file validation | `DW-001` |
+| `API` | `API-NNN` | API-Led patterns | `API-001` |
+| `EXP` | `EXP-NNN` | Experimental rules | `EXP-001` |
+
+### MULE ID Ranges
+
+| Range | Category | Description |
+|-------|----------|-------------|
+| 001-099 | Error Handling | Error handler configuration and patterns |
+| 100-199 | Naming | Naming conventions for flows, variables |
+| 200-299 | Security | Security vulnerabilities, 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 |
+
+### Rule Names
+
+```typescript
+// ✅ Good - Concise, action-oriented
+name = 'Flow Naming Convention';
+name = 'Missing Error Handler';
+name = 'Hardcoded HTTP URLs';
+
+// ❌ Bad - Too long, passive
+name = 'This rule checks if flow names follow the naming convention';
+name = 'Error handler is missing from flow';
+```
+
+### Rule Descriptions
+
+```typescript
+// ✅ Good - What + Why
+description = 'Flows must end with "-flow" for consistent identification';
+description = 'Error handlers must set httpStatus for proper API responses';
+
+// ❌ Bad - Just what, no why
+description = 'Checks flow names';
+description = 'Finds missing error handlers';
+```
+
+---
+
+## Source File Naming
+
+### Source Files
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Rule class | PascalCase + `Rule` suffix | `FlowNamingRule.ts` |
+| Multi-rule file | Feature + `Rules` suffix | `YamlRules.ts`, `ApiLedRules.ts` |
+| Base class | PascalCase + `Base` prefix | `BaseRule.ts` |
+| Utility/Helper | PascalCase + `Helper`/`Utils` | `XPathHelper.ts` |
+| Type definitions | PascalCase, singular | `Issue.ts`, `Rule.ts` |
+| Constants | PascalCase or SCREAMING_SNAKE | `Defaults.ts` |
+| Index/barrel files | Lowercase `index.ts` | `index.ts` |
+
+### Test Files
+
+| Convention | Example |
+|------------|---------|
+| Unit test | `{ClassName}.test.ts` | `FlowNamingRule.test.ts` |
+| Integration test | `{feature}.integration.test.ts` | `engine.integration.test.ts` |
+| Fixture | Descriptive kebab-case | `flow-with-error-handler.xml` |
+
+---
+
+## Code Naming
+
+### Classes
+
+```typescript
+// ✅ Good - PascalCase, descriptive
+class FlowNamingRule { }
+class XPathHelper { }
+class SarifFormatter { }
+
+// ❌ Bad
+class flowrule { }
+class Helper { }  // Too generic
+```
+
+### Interfaces
+
+```typescript
+// ✅ Good - PascalCase, noun-based
+interface Rule { }
+interface ValidationContext { }
+interface LintReport { }
+
+// ❌ Bad - I-prefix (not TypeScript convention)
+interface IRule { }
+```
+
+### Type Aliases
+
+```typescript
+// ✅ Good - PascalCase
+type Severity = 'error' | 'warning' | 'info';
+type RuleCategory = 'naming' | 'security';
+
+// ❌ Bad
+type severity = string;
+```
+
+### Constants
+
+```typescript
+// ✅ Good - SCREAMING_SNAKE for true constants
+const DEFAULT_SEVERITY = 'warning';
+const MULE_NAMESPACE = 'http://www.mulesoft.org/schema/mule/core';
+
+// ✅ Also acceptable - Object of related constants
+const ExitCodes = {
+    Success: 0,
+    Error: 1,
+} as const;
+```
+
+### Functions & Methods
+
+```typescript
+// ✅ Good - camelCase, verb-based
+function validateDocument(doc: Document): Issue[] { }
+function getLineNumber(node: Node): number { }
+function loadConfiguration(): Config { }
+
+// ✅ Good - boolean getters with is/has/should prefix
+function isEnabled(rule: Rule): boolean { }
+function hasErrorHandler(flow: Node): boolean { }
+```
+
+### Variables
+
+```typescript
+// ✅ Good - camelCase, descriptive
+const filePath = '/path/to/file.xml';
+const errorCount = 0;
+const validationResults: Issue[] = [];
+
+// ❌ Bad - single letters, abbreviations
+const f = '/path/to/file.xml';
+const ec = 0;
+```
+
+---
+
+## MuleSoft Project Naming (Validated by Rules)
+
+These are the conventions that mule-lint rules enforce:
+
+### Flow Names (MULE-002, MULE-101)
+
+```xml
+<!-- ✅ Good - kebab-case with suffix -->
+<flow name="process-order-flow">
+<sub-flow name="validate-input-subflow">
+
+<!-- ❌ Bad - no suffix, wrong casing -->
+<flow name="processOrder">
+<sub-flow name="ValidateInput">
+```
+
+### Variable Names (MULE-102)
+
+```xml
+<!-- ✅ Good - camelCase -->
+<set-variable variableName="orderId" />
+<set-variable variableName="customerData" />
+
+<!-- ❌ Bad -->
+<set-variable variableName="order_id" />
+<set-variable variableName="OrderId" />
+```
+
+### YAML Properties (YAML-003)
+
+```yaml
+# ✅ Good - category.property format
+db.host: localhost
+api.timeout: 30000
+http.request.port: 8081
+
+# ❌ Bad
+DBHOST: localhost
+ApiTimeout: 30000
+DB_HOST: localhost
+```
+
+### DataWeave Files (DW-002)
+
+```
+# ✅ Good - kebab-case
+transform-order.dwl
+validate-input.dwl
+common-utils.dwl
+
+# ❌ Bad
+transformOrder.dwl
+ValidateInput.dwl
+COMMON_UTILS.dwl
+```
+
+### Connector Configs (EXP-002)
+
+```xml
+<!-- ✅ Good - PascalCase with underscores -->
+<http:request-config name="HTTP_Request_Config" />
+<db:config name="Database_Config" />
+
+<!-- ❌ Bad -->
+<http:request-config name="httpConfig" />
+<db:config name="db-config" />
+```
+
+---
+
+## Documentation Naming
+
+### Files
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Main docs | lowercase-kebab | `rule-engine.md` |
+| Rule docs | Rule ID | `MULE-001.md` |
+| Guides | lowercase-kebab | `getting-started.md` |
+
+### Sections
+
+Use sentence case for headers:
+
+```markdown
+# Getting started
+## How to install
+### Running in CI/CD
+```
+
+---
+
+## Git Conventions
+
+### Branch Names
+
+```
+feature/MULE-001-flow-naming-rule
+fix/sarif-output-line-numbers
+docs/update-readme
+chore/upgrade-dependencies
+```
+
+### Commit Messages
+
+Follow Conventional Commits:
+
+```
+feat(rules): add MULE-011 API versioning rule
+fix(parser): handle malformed XML gracefully
+docs: update rule engine documentation
+test: add integration tests for SARIF output
+chore: upgrade xmldom to 0.9.0
+```
+
+---
+
+## Summary Table
+
+| Entity | Convention | Example |
+|--------|------------|---------|
+| File (rule class) | PascalCase + Rule | `FlowNamingRule.ts` |
+| File (multi-rule) | Feature + Rules | `YamlRules.ts` |
+| File (test) | {Class}.test.ts | `FlowNamingRule.test.ts` |
+| Class | PascalCase | `class FlowNamingRule` |
+| Interface | PascalCase | `interface Rule` |
+| Type | PascalCase | `type Severity` |
+| Constant | SCREAMING_SNAKE | `const MAX_FILES` |
+| Function | camelCase, verb | `validateDocument()` |
+| Variable | camelCase | `const filePath` |
+| Rule ID (MULE) | MULE-NNN | `MULE-001` |
+| Rule ID (YAML) | YAML-NNN | `YAML-001` |
+| Rule ID (DW) | DW-NNN | `DW-001` |
+| Rule ID (API) | API-NNN | `API-001` |
+| Rule ID (EXP) | EXP-NNN | `EXP-001` |