Initial commit

2025-11-30 08:55:38 +08:00
commit 4e7b2cfa56
19 changed files with 6651 additions and 0 deletions
--- a/references/configuration.md
+++ b/references/configuration.md
@@ -0,0 +1,845 @@
+# UI5 Linter - Configuration Complete Reference
+
+**Source**: [https://github.com/UI5/linter/blob/main/README.md](https://github.com/UI5/linter/blob/main/README.md)
+**Last Updated**: 2025-11-21
+**UI5 Linter Version**: 1.20.5
+
+---
+
+## Configuration Overview
+
+UI5 Linter supports configuration files to customize linting behavior, define ignore patterns, and specify target files. Configuration is optional but recommended for projects with specific requirements.
+
+---
+
+## Configuration File Location
+
+### Requirements
+
+Configuration files **must**:
+- Reside in the project root directory
+- Be in the same directory as `ui5.yaml` and `package.json`
+- Use one of the supported filenames
+
+### Supported Filenames
+
+| Filename | Module Type | Recommended |
+|----------|-------------|-------------|
+| `ui5lint.config.js` | Auto-detected (based on package.json) | ✅ General use |
+| `ui5lint.config.mjs` | ES Module | ✅ ESM projects |
+| `ui5lint.config.cjs` | CommonJS | ✅ CJS projects |
+
+**Detection Order**:
+1. `ui5lint.config.js`
+2. `ui5lint.config.mjs`
+3. `ui5lint.config.cjs`
+
+The first file found is used.
+
+---
+
+## Configuration File Formats
+
+### ES Module (ESM) Format
+
+**File**: `ui5lint.config.mjs` or `ui5lint.config.js` (with `"type": "module"` in package.json)
+
+```javascript
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/test/**",
+    "!webapp/test/integration/**",
+  ],
+  files: [
+    "webapp/**/*.js",
+    "webapp/**/*.xml",
+  ],
+};
+```
+
+**When to Use**:
+- Modern JavaScript projects
+- Projects using `"type": "module"` in package.json
+- New projects (recommended)
+
+---
+
+### CommonJS Format
+
+**File**: `ui5lint.config.cjs` or `ui5lint.config.js` (without `"type": "module"`)
+
+```javascript
+module.exports = {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/test/**",
+    "!webapp/test/integration/**",
+  ],
+  files: [
+    "webapp/**/*.js",
+    "webapp/**/*.xml",
+  ],
+};
+```
+
+**When to Use**:
+- Traditional Node.js projects
+- Projects without ESM support
+- Legacy projects
+
+---
+
+## Configuration Options
+
+### ignores
+
+**Type**: `string[]`
+
+**Description**: Array of glob patterns to exclude files from analysis.
+
+**Default**: `[]` (no files ignored)
+
+**Pattern Characteristics**:
+- Relative to project root
+- Supports glob syntax (`*`, `**`, `?`, `[]`, `{}`)
+- Supports negation with `!` prefix
+- **Order matters**: Later patterns override earlier ones
+
+**Basic Examples**:
+
+```javascript
+export default {
+  ignores: [
+    // Ignore entire directory
+    "webapp/thirdparty/**",
+
+    // Ignore all test files
+    "**/*.test.js",
+    "**/*.spec.js",
+
+    // Ignore specific file
+    "webapp/libs/legacy.js",
+  ],
+};
+```
+
+**Advanced Patterns**:
+
+```javascript
+export default {
+  ignores: [
+    // Ignore all test directories
+    "webapp/test/**",
+
+    // BUT include integration tests (negation)
+    "!webapp/test/integration/**",
+
+    // Ignore generated files
+    "dist/**",
+    "build/**",
+
+    // Ignore third-party libraries
+    "webapp/thirdparty/**",
+    "webapp/vendor/**",
+    "node_modules/**", // Usually excluded by default
+
+    // Ignore specific file types
+    "**/*.min.js",
+    "**/*.bundle.js",
+  ],
+};
+```
+
+**Negation Example**:
+
+```javascript
+export default {
+  ignores: [
+    // Ignore all test files
+    "webapp/test/**",
+
+    // Except integration tests
+    "!webapp/test/integration/**",
+
+    // And except this specific file
+    "!webapp/test/TestUtils.js",
+  ],
+};
+```
+
+**Pattern Order Matters**:
+
+```javascript
+// ❌ WRONG: Negation comes first, then overridden
+export default {
+  ignores: [
+    "!webapp/test/integration/**", // Won't work as expected
+    "webapp/test/**",              // This overrides above
+  ],
+};
+
+// ✅ CORRECT: Broader pattern first, then negation
+export default {
+  ignores: [
+    "webapp/test/**",              // Ignore all tests
+    "!webapp/test/integration/**", // Except integration tests
+  ],
+};
+```
+
+**Common Use Cases**:
+
+```javascript
+// UI5 Application
+export default {
+  ignores: [
+    "webapp/thirdparty/**",     // Third-party libs
+    "webapp/localService/**",   // Mock data
+    "webapp/test/**",           // Tests
+    "!webapp/test/integration/**", // Keep integration tests
+  ],
+};
+
+// UI5 Library
+export default {
+  ignores: [
+    "test/**",                  // Test files
+    "docs/**",                  // Documentation
+    ".internal/**",             // Internal dev files
+  ],
+};
+
+// Fiori Elements App
+export default {
+  ignores: [
+    "webapp/ext/**",            // Extensions (might use legacy patterns)
+    "webapp/localService/**",   // Mock server
+    "webapp/test/**",           // Tests
+  ],
+};
+```
+
+---
+
+### files
+
+**Type**: `string[]`
+
+**Description**: Array of glob patterns specifying which files to lint.
+
+**Default**: All files in project (except default exclusions)
+
+**Restrictions**:
+- ❌ Cannot include files typically excluded (e.g., `node_modules/`)
+- ❌ Cannot include non-webapp directories in applications
+- ✅ Must use POSIX separators (`/`) regardless of platform
+
+**Basic Examples**:
+
+```javascript
+export default {
+  files: [
+    // Lint all JavaScript in webapp
+    "webapp/**/*.js",
+
+    // Lint all XML views
+    "webapp/**/*.xml",
+
+    // Lint manifest
+    "webapp/manifest.json",
+  ],
+};
+```
+
+**Target Specific Areas**:
+
+```javascript
+export default {
+  files: [
+    // Controllers only
+    "webapp/controller/**/*.js",
+
+    // Views and fragments
+    "webapp/view/**/*.xml",
+    "webapp/fragment/**/*.xml",
+
+    // Component and manifest
+    "webapp/Component.js",
+    "webapp/manifest.json",
+  ],
+};
+```
+
+**Multi-Language Projects**:
+
+```javascript
+export default {
+  files: [
+    // JavaScript
+    "webapp/**/*.js",
+
+    // TypeScript
+    "webapp/**/*.ts",
+
+    // XML
+    "webapp/**/*.xml",
+
+    // YAML
+    "ui5.yaml",
+    "ui5-*.yaml",
+  ],
+};
+```
+
+**Library Projects**:
+
+```javascript
+export default {
+  files: [
+    "src/**/*.js",          // Source files
+    "src/**/*.xml",         // Control templates
+    "src/**/*.json",        // Metadata
+  ],
+};
+```
+
+---
+
+## Complete Configuration Examples
+
+### Example 1: Basic UI5 Application
+
+```javascript
+// ui5lint.config.mjs
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/test/**",
+  ],
+};
+```
+
+**Explanation**:
+- Ignores third-party libraries
+- Ignores all test files
+- Lints everything else in the project
+
+---
+
+### Example 2: Advanced Application with Selective Testing
+
+```javascript
+// ui5lint.config.mjs
+export default {
+  ignores: [
+    // Third-party code
+    "webapp/thirdparty/**",
+    "webapp/vendor/**",
+
+    // Mock data
+    "webapp/localService/**",
+
+    // All tests
+    "webapp/test/**",
+
+    // Except integration and unit tests
+    "!webapp/test/integration/**",
+    "!webapp/test/unit/**",
+
+    // Ignore generated files
+    "dist/**",
+    "build/**",
+
+    // Ignore minified files
+    "**/*.min.js",
+  ],
+  files: [
+    "webapp/**/*.js",
+    "webapp/**/*.xml",
+    "webapp/manifest.json",
+  ],
+};
+```
+
+---
+
+### Example 3: UI5 Library
+
+```javascript
+// ui5lint.config.mjs
+export default {
+  ignores: [
+    "test/**",
+    "docs/**",
+    ".internal/**",
+    "playground/**",
+  ],
+  files: [
+    "src/**/*.js",
+    "src/**/*.xml",
+    "src/**/*.json",
+  ],
+};
+```
+
+---
+
+### Example 4: TypeScript Project
+
+```javascript
+// ui5lint.config.mjs
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "dist/**",
+    "**/*.d.ts", // Ignore type definitions
+  ],
+  files: [
+    "webapp/**/*.ts",
+    "webapp/**/*.xml",
+    "webapp/manifest.json",
+  ],
+};
+```
+
+---
+
+### Example 5: Monorepo with Multiple Apps
+
+```javascript
+// ui5lint.config.mjs (in root)
+export default {
+  ignores: [
+    "**/thirdparty/**",
+    "**/test/**",
+    "**/dist/**",
+    "node_modules/**",
+  ],
+  files: [
+    "apps/*/webapp/**/*.js",
+    "apps/*/webapp/**/*.xml",
+    "apps/*/webapp/manifest.json",
+  ],
+};
+```
+
+---
+
+### Example 6: Fiori Elements Application
+
+```javascript
+// ui5lint.config.mjs
+export default {
+  ignores: [
+    // Standard ignores
+    "webapp/localService/**",
+    "webapp/test/**",
+
+    // Fiori Elements ignores
+    "webapp/ext/**", // Extensions might use legacy patterns
+
+    // Generated files
+    "webapp/changes/**", // UI Adaptation changes
+  ],
+  files: [
+    "webapp/manifest.json",
+    "webapp/Component.js",
+    "webapp/ext/**/*.js", // Lint extensions separately if needed
+  ],
+};
+```
+
+---
+
+## Using CLI Options to Override Config
+
+CLI options can override or extend configuration file settings.
+
+### Override Ignore Patterns
+
+```bash
+# Add additional ignore pattern
+ui5lint --ignore-pattern "webapp/experimental/**"
+
+# Multiple additional patterns
+ui5lint --ignore-pattern "**/*.old.js" --ignore-pattern "webapp/archive/**"
+```
+
+**Note**: CLI patterns are **added to** config file patterns, not replaced.
+
+---
+
+### Override File Patterns
+
+```bash
+# Lint specific files (ignores config file 'files' option)
+ui5lint "webapp/controller/**/*.js"
+
+# Lint specific areas
+ui5lint "webapp/view/" "webapp/fragment/"
+```
+
+**Note**: Positional file arguments **override** the config file `files` option.
+
+---
+
+### Use Custom Config File
+
+```bash
+# Use different config
+ui5lint --config config/lint-strict.config.js
+
+# Use environment-specific config
+ui5lint --config .ui5lint.ci.config.js
+```
+
+---
+
+## Integration with package.json
+
+### Add npm Script
+
+```json
+{
+  "scripts": {
+    "lint": "ui5lint",
+    "lint:fix": "ui5lint --fix",
+    "lint:ci": "ui5lint --quiet --format json > lint-results.json"
+  }
+}
+```
+
+### Usage
+
+```bash
+npm run lint
+npm run lint:fix
+npm run lint:ci
+```
+
+---
+
+## Integration with ui5.yaml
+
+UI5 Linter reads `ui5.yaml` to understand project structure.
+
+### Custom ui5.yaml Location
+
+```bash
+ui5lint --ui5-config config/ui5-dev.yaml
+```
+
+### Example ui5.yaml
+
+```yaml
+specVersion: "3.0"
+type: application
+metadata:
+  name: my.app
+
+resources:
+  configuration:
+    paths:
+      webapp: webapp
+
+builder:
+  resources:
+    excludes:
+      - "/test/**"
+      - "/localService/**"
+```
+
+**Note**: UI5 Linter respects UI5 Tooling configuration but uses its own ignore patterns from config file.
+
+---
+
+## Platform-Specific Considerations
+
+### Path Separators
+
+**Always use POSIX separators (`/`)** in configuration files, regardless of platform:
+
+```javascript
+// ✅ CORRECT (works on all platforms)
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+  ],
+};
+
+// ❌ WRONG (doesn't work)
+export default {
+  ignores: [
+    "webapp\\thirdparty\\**", // Windows-style separators
+  ],
+};
+```
+
+### Case Sensitivity
+
+**File systems**:
+- Linux/macOS: Case-sensitive
+- Windows: Case-insensitive (usually)
+
+**Recommendation**: Always match exact case in patterns.
+
+```javascript
+// ✅ CORRECT: Match exact case
+export default {
+  ignores: [
+    "webapp/ThirdParty/**", // If directory is "ThirdParty"
+  ],
+};
+```
+
+---
+
+## Debugging Configuration
+
+### Verbose Output
+
+See which files are being processed:
+
+```bash
+ui5lint --verbose
+```
+
+**Output**:
+```
+verbose Loading configuration from /project/ui5lint.config.js
+verbose Ignoring: webapp/thirdparty/**
+verbose Processing: webapp/controller/Main.controller.js
+verbose Processing: webapp/view/Main.view.xml
+...
+```
+
+### Test Patterns
+
+Use `--ignore-pattern` to test without modifying config:
+
+```bash
+# Test if pattern works
+ui5lint --ignore-pattern "webapp/test/**" --verbose
+```
+
+---
+
+## Common Configuration Patterns
+
+### Gradual Migration
+
+```javascript
+// Start with strict ignores, gradually reduce
+export default {
+  ignores: [
+    // Ignore everything except what we've migrated
+    "webapp/**",
+
+    // Include migrated files
+    "!webapp/controller/Main.controller.js",
+    "!webapp/view/Main.view.xml",
+  ],
+};
+```
+
+### Focus on Specific Issues
+
+```javascript
+// Lint manifest and component only
+export default {
+  files: [
+    "webapp/manifest.json",
+    "webapp/Component.js",
+  ],
+};
+```
+
+### Exclude Generated Code
+
+```javascript
+export default {
+  ignores: [
+    "**/*.gen.js",           // Generated JavaScript
+    "**/gen/**",             // Generated directory
+    "dist/**",               // Distribution build
+    "build/**",              // Build output
+    "webapp/changes/**",     // UI Adaptation changes
+  ],
+};
+```
+
+---
+
+## Environment-Specific Configurations
+
+### Development Config
+
+```javascript
+// ui5lint.config.js
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    // Allow test files in development
+  ],
+};
+```
+
+### CI/CD Config
+
+```javascript
+// .ui5lint.ci.config.js
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/test/**",        // Ignore all tests in CI
+    "webapp/localService/**",
+  ],
+};
+```
+
+**Usage**:
+```bash
+# CI pipeline
+ui5lint --config .ui5lint.ci.config.js --quiet --format json
+```
+
+---
+
+## Best Practices
+
+### 1. Start Broad, Then Narrow
+
+```javascript
+// Start with broad ignores
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/test/**",
+  ],
+};
+
+// Later, as code improves, reduce ignores
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/test/**",
+    "!webapp/test/integration/**", // Now lint integration tests
+  ],
+};
+```
+
+### 2. Document Complex Patterns
+
+```javascript
+export default {
+  ignores: [
+    // Third-party libraries (no control over code quality)
+    "webapp/thirdparty/**",
+
+    // Mock data (auto-generated from OData metadata)
+    "webapp/localService/**",
+
+    // Legacy code (planned for refactor in Q2)
+    "webapp/legacy/**",
+  ],
+};
+```
+
+### 3. Use Consistent Patterns
+
+```javascript
+// ✅ GOOD: Consistent pattern style
+export default {
+  ignores: [
+    "webapp/thirdparty/**",
+    "webapp/vendor/**",
+    "webapp/test/**",
+  ],
+};
+
+// ❌ BAD: Inconsistent patterns
+export default {
+  ignores: [
+    "webapp/thirdparty/**",    // Double star
+    "webapp/vendor/*",         // Single star
+    "webapp/test",             // No star
+  ],
+};
+```
+
+### 4. Version Control Configuration
+
+**Commit** configuration file:
+```bash
+git add ui5lint.config.js
+git commit -m "Add UI5 Linter configuration"
+```
+
+**Document** in README:
+```markdown
+## Linting
+
+```bash
+npm run lint
+```
+
+Configuration: `ui5lint.config.js`
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Config File Not Found
+
+**Symptoms**: Linter uses default settings despite config file existing.
+
+**Solutions**:
+1. Verify filename exactly matches: `ui5lint.config.{js,mjs,cjs}`
+2. Ensure file is in project root (same as `ui5.yaml`)
+3. Check file extension matches module type
+4. Verify no syntax errors in config file
+
+---
+
+### Issue: Patterns Not Working
+
+**Symptoms**: Files still linted despite ignore patterns.
+
+**Solutions**:
+1. Verify POSIX separators (`/` not `\`)
+2. Check pattern order (broad first, negations last)
+3. Use `--verbose` to see what's being processed
+4. Test patterns with `--ignore-pattern` flag first
+
+---
+
+### Issue: Negation Patterns Not Working
+
+**Symptoms**: Negated files still ignored.
+
+**Solutions**:
+1. Ensure negation comes **after** broader pattern:
+   ```javascript
+   ignores: [
+     "webapp/test/**",              // First: broad
+     "!webapp/test/integration/**", // Then: negation
+   ]
+   ```
+2. Verify `!` prefix is directly before pattern (no space)
+
+---
+
+## Further Reading
+
+- **Main Repository**: [https://github.com/UI5/linter](https://github.com/UI5/linter)
+- **README**: [https://github.com/UI5/linter/blob/main/README.md](https://github.com/UI5/linter/blob/main/README.md)
+- **CLI Options**: See cli-options.md reference
+- **Node.js Glob Patterns**: [https://github.com/isaacs/node-glob#glob-primer](https://github.com/isaacs/node-glob#glob-primer)
+
+---
+
+**Document Version**: 1.0
+**Last Verified**: 2025-11-21
+**Next Review**: 2026-02-21