From a9b145c6328b5a606b264ef008d625e9813dfa18 Mon Sep 17 00:00:00 2001 From: khalilmalla95 Date: Tue, 5 May 2026 15:53:38 +0200 Subject: [PATCH 1/2] Expand linter tool documentation with exclusion rules configuration and usage details. --- .../linter-tool/linter-tool.md | 219 +++++++++++++++--- 1 file changed, 187 insertions(+), 32 deletions(-) diff --git a/docs/src/process-development/linter-tool/linter-tool.md b/docs/src/process-development/linter-tool/linter-tool.md index 6966d2745..2740d4e53 100644 --- a/docs/src/process-development/linter-tool/linter-tool.md +++ b/docs/src/process-development/linter-tool/linter-tool.md @@ -13,9 +13,10 @@ A comprehensive linting tool for DSF (Data Sharing Framework) process plugins. V 3. [Installation](#installation) 4. [Usage](#usage) 5. [CLI Options](#cli-options) -6. [Report Generation](#report-generation) -7. [Architecture](#architecture) -8. [API Reference](#api-reference) +6. [Exclusion Rules](#exclusion-rules) +7. [Report Generation](#report-generation) +8. [Architecture](#architecture) +9. [API Reference](#api-reference) ## Overview @@ -36,6 +37,7 @@ The DSF Linter is a static analysis tool designed to validate DSF process plugin - ✅ CI/CD integration ready - ✅ Comprehensive error reporting with severity levels - ✅ Extensible architecture for custom validation rules +- ✅ Configurable exclusion rules to suppress known or accepted findings ### What is DSF? @@ -210,6 +212,7 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ | `--verbose` | `-v` | Enable verbose logging output | No | | `--no-color` | | Disable colored console output (default: enabled) | No | | `--no-fail` | | Exit with code 0 even if linter errors are found | No | +| `--exclusions ` | | Path to a JSON file containing exclusion rules. If omitted, `dsf-linter-exclusions.json` in the project root is used automatically. | No | | `--help` | `-h` | Display help message | No | | `--version` | | Display version information | No | @@ -230,6 +233,71 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ | 1 | Failure (errors found, or fatal error occurred) | +## Exclusion Rules + +The exclusion feature allows you to suppress specific lint findings from reports and optionally from the exit status. This is useful for accepting known issues, ignoring findings in legacy files, or gradually rolling out stricter linting rules. + +### Configuration File + +Exclusion rules are defined in a JSON file. By default the linter looks for `dsf-linter-exclusions.json` in the project root. A custom path can be passed with `--exclusions `. + +```json +{ + "affectsExitStatus": false, + "rules": [ + { "type": "BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING" }, + { "severity": "WARNING", "file": "update-allow-list.bpmn" }, + { "messageContains": "optional field" } + ] +} +``` + +### Top-Level Fields + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `affectsExitStatus` | `boolean` | `false` | When `false`, excluded items are fully suppressed — they do not contribute to error/warning counts or the exit code. When `true`, items are hidden from reports but still count toward the exit status. | +| `rules` | `array` | `[]` | List of exclusion rules. An item is excluded if it matches **any** rule. | + +### Rule Fields + +All fields within a single rule are **AND-combined** — all specified criteria must match for the item to be suppressed. Multiple rules are **OR-combined**. + +| Field | Match Semantics | Example | +|-------|-----------------|---------| +| `type` | Exact, case-insensitive match against the lint item's `LintingType` name | `"BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING"` | +| `severity` | Exact, case-insensitive match against `LinterSeverity` name | `"WARNING"` | +| `file` | Case-insensitive **substring** match against the item's file name | `"update-allow-list.bpmn"` | +| `messageContains` | Case-insensitive **substring** match against the item's message | `"optional field"` | + +Each rule must have **at least one** non-blank field. An empty rule is rejected. + +### Examples + +```json +{ + "affectsExitStatus": false, + "rules": [ + { "type": "BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING" }, + + { "severity": "WARNING", "file": "legacy-process.bpmn" }, + + { "messageContains": "optional field" }, + + { "type": "FHIR_ACTIVITY_DEFINITION_VERSION_MISSING", "file": "ActivityDefinition" } + ] +} +``` + +### Using Exclusions in CI/CD + +```bash +# Pass an explicit exclusion file +java -jar linter-cli/target/linter-cli-0.1.2.jar \ + --path plugin.jar --html --exclusions ci-exclusions.json + +``` + ## Report Generation ### Report Structure @@ -263,57 +331,57 @@ The HTML report provides a comprehensive, human-readable view of all linting res The summary page includes: - **Header**: - - DSF Linter version - - Execution timestamp - - Project path + - DSF Linter version + - Execution timestamp + - Project path - **Overall Statistics**: - - Total number of plugins - - Total errors - - Total warnings - - Execution time + - Total number of plugins + - Total errors + - Total warnings + - Execution time - **Plugin Summary Table**: - - Plugin name - - API version - - Error count - - Warning count - - Link to detailed report + - Plugin name + - API version + - Error count + - Warning count + - Link to detailed report - **Leftover Resource Summary**: - - Unreferenced BPMN files - - Unreferenced FHIR resources + - Unreferenced BPMN files + - Unreferenced FHIR resources #### Plugin Report (`plugin-name.html`) Each plugin has a detailed report page containing: - **Plugin Metadata**: - - Plugin name - - Plugin class name - - API version (v1 or v2) + - Plugin name + - Plugin class name + - API version (v1 or v2) - **BPMN Validation Results**: - - List of all BPMN files - - Errors and warnings per file - - Detailed error messages with file and line references + - List of all BPMN files + - Errors and warnings per file + - Detailed error messages with file and line references - **FHIR Validation Results**: - - List of all FHIR resources by type - - Errors and warnings per resource - - Detailed error messages with element paths + - List of all FHIR resources by type + - Errors and warnings per resource + - Detailed error messages with element paths - **Plugin Configuration Results**: - - ServiceLoader registration status - - Resource reference validation results + - ServiceLoader registration status + - Resource reference validation results - **Leftover Resource Analysis**: - - Unreferenced BPMN files - - Unreferenced FHIR resources + - Unreferenced BPMN files + - Unreferenced FHIR resources - **Severity Indicators**: - - Color-coded severity levels (ERROR, WARNING, INFO, SUCCESS) - - Expandable/collapsible sections + - Color-coded severity levels (ERROR, WARNING, INFO, SUCCESS) + - Expandable/collapsible sections ### JSON Report @@ -452,6 +520,11 @@ dsf-linter/ │ │ │ ├── ApiVersionUnknownException.java │ │ │ ├── MissingServiceRegistrationException.java │ │ │ └── ResourceLinterException.java +│ │ ├── exclusion/ # Exclusion rule engine +│ │ │ ├── ExclusionConfig.java +│ │ │ ├── ExclusionConfigLoader.java +│ │ │ ├── ExclusionFilter.java +│ │ │ └── ExclusionRule.java │ │ ├── fhir/ # FHIR parsing & validation │ │ │ ├── FhirResourceLinter.java │ │ │ ├── FhirFileLinter.java @@ -590,6 +663,8 @@ dsf-linter/ | `InputResolver` | Resolves and downloads remote JAR files | | `BpmnModelLinter` | Validates BPMN model structure and elements | | `FhirResourceLinter` | Validates FHIR resources using pluggable linters | +| `ExclusionConfigLoader` | Loads `dsf-linter-exclusions.json` (auto-discovery or explicit path) | +| `ExclusionFilter` | Applies exclusion rules to suppress matching lint items | ### Design Patterns @@ -634,6 +709,7 @@ DsfLinter.Config config = new DsfLinter.Config( generateHtmlReport, generateJsonReport, failOnErrors, + exclusionConfig, // null = no exclusions logger ); @@ -641,6 +717,8 @@ DsfLinter linter = new DsfLinter(config); DsfLinter.OverallLinterResult result = linter.lint(); ``` +A backward-compatible constructor without `exclusionConfig` is also available (sets exclusions to `null`). + #### `DsfLinter.Config` Configuration record for the linter. @@ -651,6 +729,7 @@ Configuration record for the linter. - `boolean generateHtmlReport`: Whether to generate HTML report - `boolean generateJsonReport`: Whether to generate JSON report - `boolean failOnErrors`: Whether to fail on errors +- `ExclusionConfig exclusionConfig`: Optional exclusion configuration; `null` disables exclusions - `Logger logger`: Logger instance #### `DsfLinter.OverallLinterResult` @@ -804,4 +883,80 @@ Discovers plugins and resources. **Methods**: ```java DiscoveryResult discover(ProjectContext context) +``` + +### Exclusion API + +#### `ExclusionConfigLoader` + +Loads an `ExclusionConfig` from a JSON file. + +**Constructor**: +```java +ExclusionConfigLoader() +``` + +**Methods**: +```java +// Auto-discover dsf-linter-exclusions.json in the project root +Optional loadFromProjectRoot(Path projectRoot) throws IOException + +// Load from an explicit file path +ExclusionConfig load(Path configFile) throws IOException +``` + +**Constant**: +```java +String DEFAULT_FILENAME = "dsf-linter-exclusions.json" +``` + +#### `ExclusionFilter` + +Applies exclusion rules against lint items. + +**Constructor**: +```java +ExclusionFilter(ExclusionConfig config) +``` + +**Methods**: +```java +// Returns true if the item is suppressed by at least one rule +boolean isExcluded(AbstractLintItem item) + +// Returns only items that are NOT excluded +List filter(List items) + +// Returns only items that ARE excluded +List getExcluded(List items) +``` + +#### `ExclusionConfig` + +Top-level configuration loaded from `dsf-linter-exclusions.json`. + +**Fields**: +- `List rules`: Ordered list of exclusion rules +- `boolean affectsExitStatus`: When `true`, suppressed items still count toward exit status + +**Key Methods**: +```java +boolean hasRules() // true if at least one valid rule exists +boolean isAffectsExitStatus() // getter for affectsExitStatus +List getRules() // unmodifiable view of rules +``` + +#### `ExclusionRule` + +A single exclusion rule with AND-combined criteria. + +**Fields**: +- `String type`: Exact match against `LintingType.name()` (case-insensitive) +- `String severity`: Exact match against `LinterSeverity.name()` (case-insensitive) +- `String file`: Substring match against the item's file name (case-insensitive) +- `String messageContains`: Substring match against the item's message (case-insensitive) + +**Key Methods**: +```java +boolean isValid() // true if at least one field is non-blank ``` \ No newline at end of file From e962057e5d085bc48bd47591ed6e8e060e5967b0 Mon Sep 17 00:00:00 2001 From: khalilmalla95 Date: Mon, 16 Nov 2026 18:39:28 +0100 Subject: [PATCH 2/2] Update linter tool documentation for version 0.1.3. --- .../linter-tool/changelog.md | 44 +- .../linter-tool/development.md | 15 +- .../linter-tool/linter-tool.md | 493 +++--- .../process-development/linter-tool/phases.md | 27 +- .../linter-tool/troubleshooting.md | 142 +- .../linter-tool/validation.md | 1352 ++++++++--------- 6 files changed, 1095 insertions(+), 978 deletions(-) diff --git a/docs/src/process-development/linter-tool/changelog.md b/docs/src/process-development/linter-tool/changelog.md index fee8f6a5a..1dc26c610 100644 --- a/docs/src/process-development/linter-tool/changelog.md +++ b/docs/src/process-development/linter-tool/changelog.md @@ -2,7 +2,47 @@ title: Changelog icon: code --- -## Version 0.1.2 (Latest) +## Version 0.1.3 (Latest) + +Released as GitHub artifact `linter-cli-0.1.3.jar` and Maven Central module `dev.dsf.linter:linter-core:0.1.3`. DSF integrates this release as a dependency of `dsf-maven-plugin` for the `lint` goal. + +### Features + +- **Lint exclusions** — Suppress selected findings via `dsf-linter-exclusions.json` (CLI `--exclusions` / Maven `dsf.lint.exclusionsFile`, plus auto-discovery). +- **HTML report source navigation** — Embedded BPMN/FHIR sources with a viewer modal and highlighting. +- **Remote JAR extraction lifecycle** — Extracted remote JAR directories are persisted across runs. +- **BPMN: process-level message start event** — Processes must have a message start event as a direct child of `` (`BPMN_MESSAGE_START_EVENT_NOT_FOUND`). +- **BPMN: finer-grained empty-name types** — Per-element lint types instead of a single generic empty-name type where applicable. +- **Spring / API v2: `ActivityPrototypeBeanCreator`** — Spring checks recognize APBC-registered activities and warn on V2 activities registered only as `@Bean` (or twice). +- **Spring bean scope checks** — Prototype vs singleton / mutable-state validation for BPMN-referenced beans. +- **Additional validation rules** — BPMN class references against Spring config, Task input coding (CodeSystem/ValueSet), and related BPMN/FHIR checks. + +### Integration + +- **`dsf-maven-plugin:lint`** — DSF depends on `linter-core` **0.1.3** and exposes build-time linting (default phase `verify`) with the same exclusion format as the CLI. See [Maven Plugin Integration](./linter-tool.md#maven-plugin-integration). + +### Bug Fixes + +- **Missing `ProcessPluginDefinition` no longer aborts** — Emits ERROR `PLUGIN_DEFINITION_NO_PLUGIN_FOUND` and still writes regular HTML/JSON reports (`--no-fail` / `dsf.lint.failOnErrors=false` control exit status). +- **False positives for API v2 Spring beans** — Correct handling when activities are registered via `ActivityPrototypeBeanCreator`. +- **FHIR Task input coding false positive** — Fixed incorrect “coding system not in value set” findings on valid ping tasks. +- **Message event implementation checks** — Aligned with DSF API v1/v2; Camunda field injection expressions allowed for API v2. +- **Lint type / message corrections** — Fixed incorrect types/messages for start/end events not part of a subprocess and related BPMN findings. + +### Severity Adjustments + +- Empty user-task name and empty inclusive-gateway name (multiple outgoing flows): **ERROR → WARN** +- `QUESTIONNAIRE_INVALID_META_PROFILE`: severity downgraded +- Message intermediate throw event message reference: reported as **INFO** (`BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_HAS_MESSAGE_REFERENCE`) + +### Build & Publishing + +- Maven Central publishing alignment and GitHub Release workflow (JAR + checksum) +- CI improvements (CodeQL, JavaDoc, Java 25 publish action) and dependency cleanups + +**Upgrade is recommended for all users of v0.1.2**, especially when linting API v2 plugins, using HTML reports, exclusions, or hitting abort-on-missing-plugin behavior. + +## Version 0.1.2 ### Bug Fixes @@ -37,4 +77,4 @@ icon: code - Task identifier system and value format validation (`FHIR_TASK_IDENTIFIER_MISSING_SYSTEM`, `FHIR_TASK_IDENTIFIER_INVALID_SYSTEM`, `FHIR_TASK_IDENTIFIER_INVALID_FORMAT`) - Plugin configuration validation: - Plugin resource version validation (`PLUGIN_DEFINITION_RESOURCE_VERSION_NULL`) -- HTML and JSON report generation \ No newline at end of file +- HTML and JSON report generation diff --git a/docs/src/process-development/linter-tool/development.md b/docs/src/process-development/linter-tool/development.md index 15c6c5d8c..c56ccfee4 100644 --- a/docs/src/process-development/linter-tool/development.md +++ b/docs/src/process-development/linter-tool/development.md @@ -12,7 +12,7 @@ icon: code 1. **Import Project**: - Import as Maven project - - Set JDK to 17 or higher + - Set JDK to **25** - Ensure Maven dependencies are resolved 2. **Code Style** (optional): @@ -75,12 +75,15 @@ vim linter-core/src/main/java/dev/dsf/linter/service/BpmnLintingService.java # 2. Build the project mvn clean package -DskipTests -# 3. Test with a sample plugin -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path test-plugin.jar --html --verbose +# 3. Test with a sample plugin (CLI) +java -jar linter-cli/target/linter-cli-0.1.3.jar \ + --path test-plugin.jar --html --verbose --exclusions dsf-linter-exclusions.json + +# Or exercise the Maven glue in a process plugin project: +# mvn -f path/to/process-plugin verify -Ddsf.lint.html=true -Ddsf.lint.verbose=true # 4. Check the generated report -open /tmp/dsf-linter-report-test-plugin/dsf-linter-report/index.html +open /tmp/dsf-linter-report-test-plugin/dsf-linter-report/report.html # 5. Run unit tests mvn test @@ -97,7 +100,7 @@ git commit -m "Description of changes" ```bash # Start the linter with debugger enabled java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 \ - -jar linter-cli/target/linter-cli-0.1.2.jar \ + -jar linter-cli/target/linter-cli-0.1.3.jar \ --path plugin.jar --html --verbose # Attach debugger from IDE to localhost:5005 diff --git a/docs/src/process-development/linter-tool/linter-tool.md b/docs/src/process-development/linter-tool/linter-tool.md index 2740d4e53..592c74b9c 100644 --- a/docs/src/process-development/linter-tool/linter-tool.md +++ b/docs/src/process-development/linter-tool/linter-tool.md @@ -12,11 +12,12 @@ A comprehensive linting tool for DSF (Data Sharing Framework) process plugins. V 2. [Quick Start](#quick-start) 3. [Installation](#installation) 4. [Usage](#usage) -5. [CLI Options](#cli-options) -6. [Exclusion Rules](#exclusion-rules) -7. [Report Generation](#report-generation) -8. [Architecture](#architecture) -9. [API Reference](#api-reference) +5. [Maven Plugin Integration](#maven-plugin-integration) +6. [CLI Options](#cli-options) +7. [Exclusion Rules](#exclusion-rules) +8. [Report Generation](#report-generation) +9. [Architecture](#architecture) +10. [API Reference](#api-reference) ## Overview @@ -37,7 +38,8 @@ The DSF Linter is a static analysis tool designed to validate DSF process plugin - ✅ CI/CD integration ready - ✅ Comprehensive error reporting with severity levels - ✅ Extensible architecture for custom validation rules -- ✅ Configurable exclusion rules to suppress known or accepted findings +- ✅ Configurable exclusion rules (`dsf-linter-exclusions.json`) for CLI and Maven +- ✅ Maven plugin integration (`dsf-maven-plugin:lint`) via `linter-core` dependency in DSF ### What is DSF? @@ -49,67 +51,83 @@ The Data Sharing Framework (DSF) is a framework for implementing interoperable h ## Quick Start -### Build the Project +### Option A: Maven plugin (recommended for process plugin projects) + +DSF ships `dsf-maven-plugin` with a `lint` goal that depends on `dev.dsf.linter:linter-core` **0.1.3**. Bind the goal to validate the built plugin JAR during `verify` / `install`: + +```xml + + dev.dsf + dsf-maven-plugin + + + lint-plugin + + lint + + + + +``` ```bash -# Full build with tests -mvn clean package +mvn verify +# or directly: +mvn dsf-maven-plugin:lint +``` -# Skip tests for faster build -mvn clean package -DskipTests +Details: [Maven Plugin Integration](#maven-plugin-integration). -# Verbose output -mvn clean package -X -``` +### Option B: Download pre-built CLI JAR -### Basic Usage +Download the latest `linter-cli-0.1.3.jar` from the [GitHub Releases page](https://github.com/datasharingframework/dsf-linter/releases) and run: ```bash # Lint a local JAR file -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path your-plugin.jar --html +java -jar linter-cli-0.1.3.jar --path your-plugin.jar --html # Lint a remote JAR file -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli-0.1.3.jar \ --path https://github.com/datasharingframework/dsf-process-ping-pong/releases/download/v2.0.0.1/dsf-process-ping-pong-2.0.0.1.jar --html -# View report at: /tmp/dsf-linter-report-/dsf-linter-report/index.html +# View report at: /tmp/dsf-linter-report-/dsf-linter-report/report.html ``` -## Installation - -### Requirements - -- **Java**: 17 or higher (Java 25+ required for API Version 2 validation) -- **Maven**: 3.6 or higher -- **Operating System**: Windows, Linux, or macOS - -### Building from Source +### Option C: Build CLI from source ```bash -# Clone the repository -git clone +git clone https://github.com/datasharingframework/dsf-linter.git cd dsf-linter - -# Build the project mvn clean package -# The executable JAR will be at: -# linter-cli/target/linter-cli-0.1.2.jar +java -jar linter-cli/target/linter-cli-0.1.3.jar --path your-plugin.jar --html ``` +## Installation + +### Requirements + +- **Java**: 25 or higher (required to build and run the linter) +- **Maven**: 3.6 or higher (only when building from source or using the Maven plugin) +- **Operating System**: Windows, Linux, or macOS + +> **Note:** DSF API v1 and v2 refer to the **plugin target API**, not the JVM version. The linter itself requires Java 25. + ### Distribution -The linter is distributed as a single executable JAR file that includes all dependencies. After building, the JAR can be used standalone: +| Artifact | Use case | +|----------|----------| +| `dev.dsf.linter:linter-core:0.1.3` (Maven Central) | Consumed by DSF `dsf-maven-plugin` for the `lint` goal | +| `linter-cli-0.1.3.jar` ([GitHub Releases](https://github.com/datasharingframework/dsf-linter/releases)) | Standalone executable CLI (all dependencies shaded) | ```bash -# Copy to a convenient location -cp linter-cli/target/linter-cli-0.1.2.jar ~/bin/dsf-linter.jar - -# Use from anywhere +# CLI: copy to a convenient location +cp linter-cli-0.1.3.jar ~/bin/dsf-linter.jar java -jar ~/bin/dsf-linter.jar --path plugin.jar --html ``` +Process plugin projects should prefer the Maven goal; the CLI remains useful for ad-hoc linting of local or remote JARs. + ## Usage ### Input Types @@ -156,11 +174,11 @@ plugin.jar ```bash # Local JAR file -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path C:\path\to\plugin.jar --html # Remote JAR file -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path https://github.com/datasharingframework/dsf-process-ping-pong/releases/download/v2.0.0.1/dsf-process-ping-pong-2.0.0.1.jar --html ``` @@ -168,11 +186,11 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ ```bash # Multiple report formats with custom path -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path plugin.jar --html --json --report-path ./reports # Verbose output (colors enabled by default, use --no-color to disable) -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path plugin.jar --html --verbose # Lint Maven project (two-step process) @@ -180,7 +198,7 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ cd /path/to/project && mvn clean package # Step 2: Lint the resulting JAR -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path /path/to/project/target/my-plugin-1.0.0.jar --html ``` @@ -188,19 +206,100 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ ```bash # GitHub Actions / GitLab CI -FORCE_COLOR=1 java -jar linter-cli/target/linter-cli-0.1.2.jar \ +FORCE_COLOR=1 java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path plugin.jar --html --json --verbose # Jenkins (fail on errors) -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path plugin.jar --html # Exit code: 0 = success, 1 = errors # Don't fail build (gradual adoption) -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli/target/linter-cli-0.1.3.jar \ --path plugin.jar --html --no-fail ``` +## Maven Plugin Integration + +The DSF Maven plugin (`dsf-maven-plugin`) integrates the linter into the Maven build lifecycle. This is the **recommended approach** for DSF process plugin projects: it validates the **built plugin JAR** automatically, fails the build on ERROR findings by default, and supports **exclusion rules** out of the box. + +**How it is wired:** DSF declares `dev.dsf.linter:linter-core` (**0.1.3**) as a dependency of `dsf-maven-plugin`. The `lint` goal (`LintPluginMojo`, default phase `verify`) resolves `${project.build.directory}/${project.build.finalName}.jar`, runs `DsfLinter`, and writes reports under `target/dsf-linter-report` by default. + +### Enable in `pom.xml` + +```xml + + dev.dsf + dsf-maven-plugin + + + lint-plugin + + lint + + + + +``` + +### Run + +The `lint` goal runs automatically during: + +- `mvn verify` +- `mvn install` +- `mvn deploy` + +Or invoke it directly: + +```bash +mvn dsf-maven-plugin:lint +``` + +### Maven Parameters + +| Property | Default | Description | +|----------|---------|-------------| +| `dsf.lint.skip` | `false` | Skip linting entirely | +| `dsf.lint.failOnErrors` | `true` | Fail the build when ERROR-severity findings exist | +| `dsf.lint.html` | `false` | Generate HTML report | +| `dsf.lint.json` | `false` | Generate JSON report | +| `dsf.lint.verbose` | `false` | Enable verbose logging | +| `dsf.lint.reportPath` | `target/dsf-linter-report` | Report output directory | +| `dsf.lint.exclusionsFile` | *(auto-discover)* | Path to exclusion JSON file | + +**Examples:** + +```bash +# Lint with HTML report, do not fail build +mvn verify -Ddsf.lint.html=true -Ddsf.lint.failOnErrors=false + +# Use explicit exclusion file +mvn verify -Ddsf.lint.exclusionsFile=ci/dsf-linter-exclusions.json +``` + +### Permanent configuration in `pom.xml` + +```xml + + dev.dsf + dsf-maven-plugin + + true + ${project.build.directory}/dsf-linter-report + ${project.basedir}/dsf-linter-exclusions.json + + + + lint-plugin + lint + + + +``` + +Exclusion file format and rule semantics are described in [Exclusion Rules](#exclusion-rules). + ## CLI Options | Option | Short | Description | Required | @@ -209,13 +308,15 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ | `--html` | | Generate HTML report | No | | `--json` | | Generate JSON report | No | | `--report-path ` | `-r` | Custom report directory (default: `/dsf-linter-report-/dsf-linter-report`) | No | +| `--exclusions ` | | Path to a JSON exclusion config (see [Exclusion Rules](#exclusion-rules)) | No | | `--verbose` | `-v` | Enable verbose logging output | No | | `--no-color` | | Disable colored console output (default: enabled) | No | | `--no-fail` | | Exit with code 0 even if linter errors are found | No | -| `--exclusions ` | | Path to a JSON file containing exclusion rules. If omitted, `dsf-linter-exclusions.json` in the project root is used automatically. | No | | `--help` | `-h` | Display help message | No | | `--version` | | Display version information | No | +When `--exclusions` is omitted, the CLI auto-discovers `dsf-linter-exclusions.json` in the project/extracted root if present. + ### Environment Variables | Variable | Effect | @@ -235,18 +336,35 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ ## Exclusion Rules -The exclusion feature allows you to suppress specific lint findings from reports and optionally from the exit status. This is useful for accepting known issues, ignoring findings in legacy files, or gradually rolling out stricter linting rules. +The exclusion feature allows you to suppress specific lint findings from reports and optionally from the build/CLI exit status. This is useful for accepting known issues, ignoring findings in legacy files, or gradually rolling out stricter linting rules. + +**Where exclusions are supported (v0.1.3):** + +| Integration | How to configure | +|-------------|------------------| +| `dsf-maven-plugin:lint` | `-Ddsf.lint.exclusionsFile=...` or auto-discovery of `dsf-linter-exclusions.json` | +| Standalone CLI | `--exclusions ` or auto-discovery of `dsf-linter-exclusions.json` | ### Configuration File -Exclusion rules are defined in a JSON file. By default the linter looks for `dsf-linter-exclusions.json` in the project root. A custom path can be passed with `--exclusions `. +Exclusion rules are defined in a JSON file named `dsf-linter-exclusions.json`. When no explicit path is set, the loader auto-discovers that file in the **resolved project root** (extracted JAR contents). Explicit configuration always wins and is the reliable choice for Maven module roots that are not packaged into the JAR: + +```bash +# CLI +java -jar linter-cli-0.1.3.jar --path plugin.jar --html \ + --exclusions path/to/dsf-linter-exclusions.json + +# Maven (recommended: point at the module basedir) +mvn verify -Ddsf.lint.exclusionsFile=${project.basedir}/dsf-linter-exclusions.json +``` + ```json { "affectsExitStatus": false, "rules": [ { "type": "BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING" }, - { "severity": "WARNING", "file": "update-allow-list.bpmn" }, + { "severity": "WARN", "file": "update-allow-list.bpmn" }, { "messageContains": "optional field" } ] } @@ -266,7 +384,7 @@ All fields within a single rule are **AND-combined** — all specified criteria | Field | Match Semantics | Example | |-------|-----------------|---------| | `type` | Exact, case-insensitive match against the lint item's `LintingType` name | `"BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING"` | -| `severity` | Exact, case-insensitive match against `LinterSeverity` name | `"WARNING"` | +| `severity` | Exact, case-insensitive match against `LinterSeverity` name | `"WARN"`, `"ERROR"`, `"INFO"` | | `file` | Case-insensitive **substring** match against the item's file name | `"update-allow-list.bpmn"` | | `messageContains` | Case-insensitive **substring** match against the item's message | `"optional field"` | @@ -280,11 +398,11 @@ Each rule must have **at least one** non-blank field. An empty rule is rejected. "rules": [ { "type": "BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING" }, - { "severity": "WARNING", "file": "legacy-process.bpmn" }, + { "severity": "WARN", "file": "legacy-process.bpmn" }, { "messageContains": "optional field" }, - { "type": "FHIR_ACTIVITY_DEFINITION_VERSION_MISSING", "file": "ActivityDefinition" } + { "type": "BPMN_END_EVENT_NOT_PART_OF_SUB_PROCESS", "file": "subprocess.bpmn" } ] } ``` @@ -292,10 +410,12 @@ Each rule must have **at least one** non-blank field. An empty rule is rejected. ### Using Exclusions in CI/CD ```bash -# Pass an explicit exclusion file -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path plugin.jar --html --exclusions ci-exclusions.json +# Maven plugin with explicit exclusion file +mvn verify -Ddsf.lint.exclusionsFile=ci-exclusions.json -Ddsf.lint.html=true +# Standalone CLI with exclusions +java -jar linter-cli-0.1.3.jar --path plugin.jar --html --json \ + --exclusions ci-exclusions.json ``` ## Report Generation @@ -306,18 +426,22 @@ Reports are generated in the following structure: ``` / -├── index.html # Summary report (all plugins) -├── plugin-name.html # Detailed report for each plugin -└── plugin-name.json # JSON report (if --json specified) +├── report.html # Master summary report (all plugins) +├── report.json # Master JSON report (if --json specified) +└── / + ├── lints.html # Detailed HTML report for the plugin + └── lints.json # Detailed JSON report (if --json specified) ``` The default `` resolves to `/dsf-linter-report-/dsf-linter-report`, for example: ``` /tmp/dsf-linter-report-my-plugin/dsf-linter-report/ -├── index.html -├── my-plugin.html -└── my-plugin.json +├── report.html +├── report.json +└── my-plugin/ + ├── lints.html + └── lints.json ``` Use `--report-path` to override this location. @@ -326,9 +450,9 @@ Use `--report-path` to override this location. The HTML report provides a comprehensive, human-readable view of all linting results. -#### Summary Page (`index.html`) +#### Master Report (`report.html`) -The summary page includes: +The master report includes: - **Header**: - DSF Linter version @@ -337,22 +461,25 @@ The summary page includes: - **Overall Statistics**: - Total number of plugins - - Total errors - - Total warnings - - Execution time + - Total errors, warnings, info, and success counts + - Resource discovery summary - **Plugin Summary Table**: - Plugin name - API version - - Error count - - Warning count - - Link to detailed report + - Error and warning counts + - Link to per-plugin report (`/lints.html`) - **Leftover Resource Summary**: - Unreferenced BPMN files - Unreferenced FHIR resources -#### Plugin Report (`plugin-name.html`) +- **Source navigation** (v0.1.3+): + - Embedded BPMN and FHIR source files + - Source viewer modal with highlighting of the affected location + - Jump from a finding to the corresponding source context + +#### Plugin Report (`/lints.html`) Each plugin has a detailed report page containing: @@ -380,82 +507,99 @@ Each plugin has a detailed report page containing: - Unreferenced FHIR resources - **Severity Indicators**: - - Color-coded severity levels (ERROR, WARNING, INFO, SUCCESS) + - Color-coded severity levels (ERROR, WARN, INFO, SUCCESS) - Expandable/collapsible sections + - Back link to master report (`report.html`) ### JSON Report The JSON report provides machine-readable output for CI/CD integration and automated processing. -#### Structure +#### Master Report Structure (`report.json`) ```json { - "version": "0.1.1", - "timestamp": "2025-06-15T10:30:00Z", - "projectPath": "/path/to/plugin.jar", - "executionTimeMs": 2300, - "success": true, + "projectName": "my-plugin.jar", + "projectPath": "/path/to/my-plugin.jar", + "timestamp": "2026-06-15T10:30:00Z", "summary": { "totalPlugins": 1, "totalErrors": 0, "totalWarnings": 1, - "totalLeftoverBpmn": 0, - "totalLeftoverFhir": 0 + "totalInfos": 0, + "totalSuccesses": 42 }, - "plugins": { - "plugin-name": { - "name": "plugin-name", - "class": "dev.dsf.bpe.plugin.ExamplePlugin", + "discovery": { + "bpmnFilesFound": 2, + "fhirFilesFound": 15, + "missingBpmn": 0, + "missingFhir": 0 + }, + "leftoverAnalysis": { + "totalLeftovers": 0, + "leftoverBpmn": [], + "leftoverFhir": [] + }, + "plugins": [ + { + "pluginName": "my-plugin", + "pluginClass": "dev.dsf.bpe.plugin.ExamplePlugin", "apiVersion": "V1", - "errors": 0, - "warnings": 1, - "bpmnFiles": [ - { - "path": "bpe/process.bpmn", - "errors": 0, - "warnings": 1, - "items": [...] - } - ], - "fhirResources": { - "ActivityDefinition": [...], - "Task": [...], - "StructureDefinition": [...] - }, - "pluginConfig": { - "serviceLoaderRegistered": true, - "items": [...] - } + "errorCount": 0, + "warningCount": 1, + "reportPath": "./my-plugin/lints.json" } + ] +} +``` + +#### Plugin Report Structure (`/lints.json`) + +```json +{ + "pluginName": "my-plugin", + "pluginClass": "dev.dsf.bpe.plugin.ExamplePlugin", + "apiVersion": "V1", + "timestamp": "2026-06-15T10:30:00Z", + "summary": { + "errorCount": 0, + "warningCount": 1, + "infoCount": 0, + "successCount": 42, + "totalItems": 43 }, - "leftoverAnalysis": { - "unreferencedBpmn": [], - "unreferencedFhir": [] + "items": { + "ERROR": [], + "WARN": [ { "...": "..." } ], + "INFO": [], + "SUCCESS": [ { "...": "..." } ] } } ``` #### Lint Item Structure -Each lint item in the JSON report has the following structure: +Each lint item in the JSON report has the following structure (fields vary by item type): ```json { - "severity": "ERROR", - "type": "BpmnServiceTaskNameEmptyLintItem", - "message": "Service task must have a non-empty name", - "file": "bpe/process.bpmn", - "element": "ServiceTask_1", - "line": 42, - "column": 10 + "severity": "WARN", + "type": "BpmnElementLintItem", + "elementId": "ServiceTask_1", + "processId": "testorg_myprocess", + "description": "Service task name is empty.", + "bpmnFile": "bpe/process.bpmn", + "issueType": "BPMN_SERVICE_TASK_NAME_EMPTY", + "fullMessage": "..." } ``` +`BPMN_FLOW_ELEMENT` items additionally include `flowElementType` (the sequence-flow subtype, e.g. `SEQUENCE_FLOW_HAS_NO_SOURCE_NODE`). + ### Example Console Output ``` -DSF Linter v0.1.1 +DSF Linter v0.1.3 ================================================================= Project: /path/to/plugin.jar Report: /tmp/dsf-linter-report-plugin/dsf-linter-report @@ -479,7 +623,7 @@ Phase 3: Linting Phase 4: Report Generation ✓ HTML report generated -Summary +Phase 5: Summary ================================================================= ✓ SUCCESS - No errors found Plugins: 1 @@ -495,11 +639,16 @@ Summary ``` dsf-linter/ -├── linter-core/ # Core linting logic +├── linter-core/ # Core linting logic (Maven artifact: linter-core) │ ├── src/main/java/dev/dsf/linter/ │ │ ├── DsfLinter.java # Main orchestrator │ │ ├── analysis/ # Resource analysis │ │ │ └── LeftoverResourceDetector.java +│ │ ├── exclusion/ # Exclusion config & filter +│ │ │ ├── ExclusionConfig.java +│ │ │ ├── ExclusionConfigLoader.java +│ │ │ ├── ExclusionFilter.java +│ │ │ └── ExclusionRule.java │ │ ├── bpmn/ # BPMN parsing & validation │ │ │ ├── BpmnLinter.java │ │ │ ├── BpmnModelLinter.java @@ -520,11 +669,6 @@ dsf-linter/ │ │ │ ├── ApiVersionUnknownException.java │ │ │ ├── MissingServiceRegistrationException.java │ │ │ └── ResourceLinterException.java -│ │ ├── exclusion/ # Exclusion rule engine -│ │ │ ├── ExclusionConfig.java -│ │ │ ├── ExclusionConfigLoader.java -│ │ │ ├── ExclusionFilter.java -│ │ │ └── ExclusionRule.java │ │ ├── fhir/ # FHIR parsing & validation │ │ │ ├── FhirResourceLinter.java │ │ │ ├── FhirFileLinter.java @@ -663,8 +807,8 @@ dsf-linter/ | `InputResolver` | Resolves and downloads remote JAR files | | `BpmnModelLinter` | Validates BPMN model structure and elements | | `FhirResourceLinter` | Validates FHIR resources using pluggable linters | -| `ExclusionConfigLoader` | Loads `dsf-linter-exclusions.json` (auto-discovery or explicit path) | -| `ExclusionFilter` | Applies exclusion rules to suppress matching lint items | +| `ExclusionConfigLoader` / `ExclusionFilter` | Loads `dsf-linter-exclusions.json` and filters matched findings (CLI + Maven) | +| `SpringConfigurationLinter` | Validates Spring `@Bean` / `ActivityPrototypeBeanCreator` registration and bean scope | ### Design Patterns @@ -709,7 +853,7 @@ DsfLinter.Config config = new DsfLinter.Config( generateHtmlReport, generateJsonReport, failOnErrors, - exclusionConfig, // null = no exclusions + exclusionConfig, // nullable — null means no exclusions logger ); @@ -717,19 +861,19 @@ DsfLinter linter = new DsfLinter(config); DsfLinter.OverallLinterResult result = linter.lint(); ``` -A backward-compatible constructor without `exclusionConfig` is also available (sets exclusions to `null`). +A backward-compatible constructor without `exclusionConfig` still exists (passes `null`). #### `DsfLinter.Config` Configuration record for the linter. **Fields**: -- `Path projectPath`: Path to the project root +- `Path projectPath`: Path to the project root (extracted JAR directory) - `Path reportPath`: Path for report generation - `boolean generateHtmlReport`: Whether to generate HTML report - `boolean generateJsonReport`: Whether to generate JSON report - `boolean failOnErrors`: Whether to fail on errors -- `ExclusionConfig exclusionConfig`: Optional exclusion configuration; `null` disables exclusions +- `ExclusionConfig exclusionConfig`: Optional exclusion rules (`null` = none) - `Logger logger`: Logger instance #### `DsfLinter.OverallLinterResult` @@ -741,7 +885,7 @@ Result record containing all linting results. - `LeftoverResourceDetector.AnalysisResult leftoverAnalysis`: Leftover resource analysis - `Path masterReportPath`: Path to master report - `long executionTimeMs`: Execution time in milliseconds -- `boolean success`: Whether linting succeeded +- `boolean success`: Whether linting succeeded (`false` only when `failOnErrors` is set and errors remain after exclusions) **Methods**: - `int getPluginErrors()`: Total error count from plugins @@ -757,9 +901,13 @@ Linting result for a single plugin. - `String pluginName`: Name of the plugin - `String pluginClass`: Fully qualified class name - `ApiVersion apiVersion`: DSF API version (V1 or V2) -- `LintingOutput output`: Detailed linting output +- `LintingOutput output`: Detailed linting output **after** exclusions have been applied +- `int excludedErrorCount`: Number of ERROR items suppressed by exclusion rules - `Path reportPath`: Path to generated report +### No plugin found + +If no `ProcessPluginDefinition` is discovered (empty/broken JAR, missing or invalid `META-INF/services` registration), the linter does **not** abort. It emits ERROR `PLUGIN_DEFINITION_NO_PLUGIN_FOUND`, still writes the regular HTML/JSON reports, and sets `success = !failOnErrors` (CLI: exit 1 by default, exit 0 with `--no-fail`). ### Linting Services #### `BpmnLintingService` @@ -820,9 +968,11 @@ LintingResult lintPlugin( PluginAdapter pluginAdapter, ApiVersion apiVersion, List collectedPluginItems -) throws MissingServiceRegistrationException +) ``` +Missing or invalid ServiceLoader registrations are reported as ERROR lint items (e.g. `PLUGIN_DEFINITION_MISSING_SERVICE_LOADER_REGISTRATION`, `PLUGIN_DEFINITION_NO_PLUGIN_FOUND`) rather than aborting the run. + ### Lint Items All lint items extend `AbstractLintItem` and implement specific interfaces. @@ -837,7 +987,7 @@ All lint items extend `AbstractLintItem` and implement specific interfaces. #### Severity Levels - `ERROR`: Critical issue that **must be fixed**. Will cause the plugin to fail at deployment or runtime. -- `WARNING`: Violation of DSF best practices, or something that **could be an error depending on context**. +- `WARN`: Violation of DSF best practices, or something that **could be an error depending on context**. - `INFO`: Technically valid, but something looks unusual or incomplete. Worth a second look — no immediate action required. - `SUCCESS`: Validation passed. Shown to confirm what was checked and give confidence in the covered areas. @@ -885,78 +1035,9 @@ Discovers plugins and resources. DiscoveryResult discover(ProjectContext context) ``` -### Exclusion API - -#### `ExclusionConfigLoader` - -Loads an `ExclusionConfig` from a JSON file. - -**Constructor**: -```java -ExclusionConfigLoader() -``` - -**Methods**: -```java -// Auto-discover dsf-linter-exclusions.json in the project root -Optional loadFromProjectRoot(Path projectRoot) throws IOException - -// Load from an explicit file path -ExclusionConfig load(Path configFile) throws IOException -``` - -**Constant**: -```java -String DEFAULT_FILENAME = "dsf-linter-exclusions.json" -``` - -#### `ExclusionFilter` - -Applies exclusion rules against lint items. - -**Constructor**: -```java -ExclusionFilter(ExclusionConfig config) -``` - -**Methods**: -```java -// Returns true if the item is suppressed by at least one rule -boolean isExcluded(AbstractLintItem item) - -// Returns only items that are NOT excluded -List filter(List items) - -// Returns only items that ARE excluded -List getExcluded(List items) -``` - -#### `ExclusionConfig` - -Top-level configuration loaded from `dsf-linter-exclusions.json`. - -**Fields**: -- `List rules`: Ordered list of exclusion rules -- `boolean affectsExitStatus`: When `true`, suppressed items still count toward exit status - -**Key Methods**: -```java -boolean hasRules() // true if at least one valid rule exists -boolean isAffectsExitStatus() // getter for affectsExitStatus -List getRules() // unmodifiable view of rules -``` - -#### `ExclusionRule` +### Exclusion Configuration -A single exclusion rule with AND-combined criteria. +Exclusion rules are configured via `dsf-linter-exclusions.json` (or an explicit path). See [Exclusion Rules](#exclusion-rules) for the file format. -**Fields**: -- `String type`: Exact match against `LintingType.name()` (case-insensitive) -- `String severity`: Exact match against `LinterSeverity.name()` (case-insensitive) -- `String file`: Substring match against the item's file name (case-insensitive) -- `String messageContains`: Substring match against the item's message (case-insensitive) - -**Key Methods**: -```java -boolean isValid() // true if at least one field is non-blank -``` \ No newline at end of file +- Maven: `dsf.lint.exclusionsFile` / auto-discovery +- CLI: `--exclusions` / auto-discovery diff --git a/docs/src/process-development/linter-tool/phases.md b/docs/src/process-development/linter-tool/phases.md index 05f358dd3..0b9eff77b 100644 --- a/docs/src/process-development/linter-tool/phases.md +++ b/docs/src/process-development/linter-tool/phases.md @@ -50,30 +50,37 @@ The linter executes in five phases: - For each discovered plugin: - Validates BPMN processes - Validates FHIR resources - - Validates plugin configuration + - Validates plugin configuration (ServiceLoader, Spring/`ActivityPrototypeBeanCreator`, scope) - Collects lint items -2. **Project-Level Analysis**: +2. **Exclusion Filtering** (optional): + - Applies rules from `dsf-linter-exclusions.json` / `--exclusions` / `dsf.lint.exclusionsFile` + - Removes matched items from report output + - Depending on `affectsExitStatus`, excluded ERRORs may still count toward failure + +3. **Project-Level Analysis**: - Performs leftover resource analysis - Aggregates referenced resources across all plugins - Identifies unreferenced resources -3. **Result Aggregation**: +4. **Result Aggregation**: - Combines results from all plugins - Calculates totals (errors, warnings) - - Determines overall success status + - Determines overall success status (`failOnErrors` / `--no-fail`) + +If no plugin definition is found, Phase 3 emits `PLUGIN_DEFINITION_NO_PLUGIN_FOUND` and continues to report generation instead of aborting. #### Phase 4: Report Generation 1. **HTML Report Generation**: - - Generates summary page - - Generates detailed plugin pages - - Applies templates and styling + - Generates master report (`report.html`) + - Generates per-plugin reports (`/lints.html`) + - Embeds source files with navigation and highlighting 2. **JSON Report Generation** (if requested): - - Serializes all results to JSON - - Includes metadata and statistics - - Provides machine-readable format + - Writes master report (`report.json`) and per-plugin reports (`/lints.json`) + - Serializes results grouped by severity + - Includes discovery and leftover analysis metadata #### Phase 5: Summary diff --git a/docs/src/process-development/linter-tool/troubleshooting.md b/docs/src/process-development/linter-tool/troubleshooting.md index 045830990..17a33ddc0 100644 --- a/docs/src/process-development/linter-tool/troubleshooting.md +++ b/docs/src/process-development/linter-tool/troubleshooting.md @@ -5,22 +5,50 @@ icon: config ## Troubleshooting -### "Input must be a JAR file" Error +### Maven: JAR not found / lint skipped -**Problem**: The linter only accepts JAR files as input. +**Problem**: `DSF Linter: JAR not found at …, skipping` or the `lint` goal does nothing useful. + +**Solution**: +- Ensure the plugin JAR exists: `${project.build.directory}/${project.build.finalName}.jar` +- Run a phase that builds the JAR first, e.g. `mvn verify` or `mvn package` then `mvn dsf-maven-plugin:lint` +- Confirm the `lint` execution is bound in the process plugin `pom.xml` + +### Maven: build fails on lint errors + +**Problem**: `MojoFailureException` with error counts after `verify`. + +**Solution**: +```bash +# Inspect HTML/JSON reports +mvn verify -Ddsf.lint.html=true -Ddsf.lint.json=true + +# Temporary: do not fail the build (gradual adoption) +mvn verify -Ddsf.lint.failOnErrors=false + +# Skip lint entirely +mvn verify -Ddsf.lint.skip=true +``` + +Use [exclusion rules](./linter-tool.md#exclusion-rules) for known accepted findings. + +### "Input must be a JAR file" Error (CLI) + +**Problem**: The CLI only accepts JAR files as input. **Solution**: ```bash -# Wrong - Maven project directly -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path /path/to/project --html +# Wrong - Maven project directory +java -jar linter-cli-0.1.3.jar --path /path/to/project --html -# Correct - Build first, then lint JAR +# Correct - build first, then lint the JAR cd /path/to/project && mvn clean package -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli-0.1.3.jar \ --path /path/to/project/target/my-plugin-1.0.0.jar --html ``` +Prefer `dsf-maven-plugin:lint` in process plugin builds so packaging and linting stay in one lifecycle. + ### JAR File Not Found **Problem**: The specified JAR file path cannot be found. @@ -29,47 +57,48 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ ```bash # Windows -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli-0.1.3.jar \ --path "C:\Users\Username\project\target\plugin.jar" --html # Linux/Mac -java -jar linter-cli/target/linter-cli-0.1.2.jar \ +java -jar linter-cli-0.1.3.jar \ --path /home/username/project/target/plugin.jar --html ``` -### Missing Dependencies +### Missing Dependencies / Class Hierarchy False Positives -**Problem**: ClassNotFoundException or similar errors during linting. +**Problem**: ClassNotFoundException or false “does not implement …” findings during linting. **Solution**: ```bash -# Check Maven settings -ls ~/.m2/settings.xml +# Use verbose mode +java -jar linter-cli-0.1.3.jar --path plugin.jar --html --verbose -# Use verbose mode to see detailed error messages -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path plugin.jar --html --verbose +# Or with Maven +mvn verify -Ddsf.lint.verbose=true -Ddsf.lint.html=true -# Check if dependencies are in the JAR +# Ensure the plugin JAR contains the expected classes jar -tf plugin.jar | grep -i "class" ``` +Use **linter-cli / linter-core 0.1.3+** (0.1.2 already fixed several V1 hierarchy false positives caused by missing Spring classes in the shaded CLI). + ### Report Not Generated **Problem**: No report files are created. **Solution**: ```bash -# --html or --json flag must be set -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path plugin.jar --html # ← Required +# CLI: --html and/or --json must be set +java -jar linter-cli-0.1.3.jar --path plugin.jar --html -# Use absolute path for report directory -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path plugin.jar --html --report-path $(pwd)/reports +# Maven: enable report flags +mvn verify -Ddsf.lint.html=true -Ddsf.lint.json=true -# Check write permissions -ls -ld /tmp/dsf-linter-report-* +# Custom report directory +java -jar linter-cli-0.1.3.jar \ + --path plugin.jar --html --report-path $(pwd)/reports +mvn verify -Ddsf.lint.reportPath=target/custom-linter-report -Ddsf.lint.html=true ``` ### Remote JAR Download Error @@ -78,30 +107,36 @@ ls -ld /tmp/dsf-linter-report-* **Solution**: ```bash -# Test download separately curl -L -o test.jar https://example.com/plugin.jar - -# Verify the download ls -lh test.jar +java -jar linter-cli-0.1.3.jar --path test.jar --html +``` -# Check network connectivity -ping example.com +### Plugin Not Found / `PLUGIN_DEFINITION_NO_PLUGIN_FOUND` -# Then use the local file -java -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path test.jar --html -``` +**Problem**: ERROR that no `ProcessPluginDefinition` was found. -### Plugin Not Found +**Behaviour in 0.1.3+**: The run does **not** abort mid-flight. Regular HTML/JSON reports are still written. Exit/build failure follows `failOnErrors` / `--no-fail`. -**Problem**: "No plugins found" message. +**Solution**: +- Verify ServiceLoader registration under `META-INF/services/`: + - `dev.dsf.bpe.v1.ProcessPluginDefinition` and/or + - `dev.dsf.bpe.v2.ProcessPluginDefinition` +- Ensure the registered class is present in the JAR and implements the correct interface +- Check for `ServiceConfigurationError` details in verbose logs (e.g. “not a subtype”) +- Confirm API version compatibility of the plugin JAR + +### Exclusion File Not Applied + +**Problem**: Findings that should be excluded still appear. **Solution**: -- Verify ServiceLoader registration exists in `META-INF/services/` -- Check that plugin class is in the JAR file -- Ensure plugin class implements the correct interface -- Use `--verbose` to see detailed discovery logs -- Check API version compatibility +- Prefer an **explicit** path (especially for Maven module roots): + - CLI: `--exclusions path/to/file.json` + - Maven: `-Ddsf.lint.exclusionsFile=${project.basedir}/dsf-linter-exclusions.json` +- Auto-discovery only finds `dsf-linter-exclusions.json` in the **extracted JAR root** (not automatically the Maven basedir unless the file is packaged there) +- Rule fields are AND-combined within a rule; check `type` / `severity` / `file` / `messageContains` spelling +- Invalid/empty rules cause load failure — check the log for exclusion load errors ### Out of Memory Errors @@ -109,33 +144,30 @@ java -jar linter-cli/target/linter-cli-0.1.2.jar \ **Solution**: ```bash -# Increase heap size -java -Xmx2g -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path plugin.jar --html +java -Xmx2g -jar linter-cli-0.1.3.jar --path plugin.jar --html # For very large projects -java -Xmx4g -Xms1g -jar linter-cli/target/linter-cli-0.1.2.jar \ - --path plugin.jar --html +java -Xmx4g -Xms1g -jar linter-cli-0.1.3.jar --path plugin.jar --html ``` +For Maven, set `MAVEN_OPTS` accordingly. + ### Slow Performance **Problem**: Linting takes too long. **Solution**: -- Use `-DskipTests` during build -- Disable verbose logging in production -- Check network latency for remote JARs +- Use `-DskipTests` during local builds when iterating +- Disable verbose logging in production CI unless needed +- Prefer local JARs over remote URLs when possible - Consider increasing heap size -- Profile with JVM tools if needed ### Class Loading Issues **Problem**: Classes cannot be loaded from plugin JAR. **Solution**: -- Verify JAR structure -- Check classpath configuration -- Ensure dependencies are included -- Use verbose mode to see classloader logs -- Check API version compatibility \ No newline at end of file +- Verify JAR structure (`META-INF/services`, `bpe/`, `fhir/`) +- Ensure dependencies needed for hierarchy checks are available (shaded CLI includes Spring artifacts since 0.1.2) +- Use verbose mode to inspect classloader / discovery logs +- Check API version compatibility diff --git a/docs/src/process-development/linter-tool/validation.md b/docs/src/process-development/linter-tool/validation.md index 015b33727..6ec3420f9 100644 --- a/docs/src/process-development/linter-tool/validation.md +++ b/docs/src/process-development/linter-tool/validation.md @@ -26,23 +26,23 @@ The linter performs comprehensive validation on BPMN 2.0 process definitions usi ##### Process ID Pattern Validation - **Pattern Requirement**: - - Process ID must follow the pattern: `domain_processname` - - Domain and process name must consist only of alphanumeric characters (a-z, A-Z, 0-9) and hyphens (-) - - Exactly one underscore must separate domain and process name - - Error: `BPMN_PROCESS_ID_PATTERN_MISMATCH` - - Error: `BPMN_PROCESS_ID_EMPTY` - - Success: `SUCCESS` when the pattern is matched + - Process ID must follow the pattern: `domain_processname` + - Domain and process name must consist only of alphanumeric characters (a-z, A-Z, 0-9) and hyphens (-) + - Exactly one underscore must separate domain and process name + - Error: `BPMN_PROCESS_ID_PATTERN_MISMATCH` + - Error: `BPMN_PROCESS_ID_EMPTY` + - Success: `SUCCESS` when the pattern is matched - **Valid Examples**: - - ✅ `testorg_myprocess` - - ✅ `dsf-dev_download-allowlist` - - ✅ `example123_process456` + - ✅ `testorg_myprocess` + - ✅ `dsf-dev_download-allowlist` + - ✅ `example123_process456` - **Invalid Examples**: - - ❌ `myProcess` (missing underscore) - - ❌ `test.org_myprocess` (dots not allowed) - - ❌ `test_my_process` (multiple underscores not allowed) - - ❌ `test_process_name` (only one underscore allowed) + - ❌ `myProcess` (missing underscore) + - ❌ `test.org_myprocess` (dots not allowed) + - ❌ `test_my_process` (multiple underscores not allowed) + - ❌ `test_process_name` (only one underscore allowed) - **Pattern Definition**: ```regex @@ -50,88 +50,107 @@ The linter performs comprehensive validation on BPMN 2.0 process definitions usi ``` - **DSF Framework Reference**: - - This validation is based on the DSF Framework requirement defined in: - - `dsf-bpe/dsf-bpe-process-api/src/main/java/dev/dsf/bpe/api/plugin/AbstractProcessPlugin.java` + - This validation is based on the DSF Framework requirement defined in: + - `dsf-bpe/dsf-bpe-process-api/src/main/java/dev/dsf/bpe/api/plugin/AbstractProcessPlugin.java` ##### Process Count Validation - **Requirement**: - - Each BPMN file must contain **exactly one** process definition - - Error: `BPMN_FILE_NO_PROCESS` (when no process is found) - - Error: `BPMN_FILE_MULTIPLE_PROCESSES` (when more than one process is found) - - Success: `SUCCESS` when exactly one process is found + - Each BPMN file must contain **exactly one** process definition + - Error: `BPMN_FILE_NO_PROCESS` (when no process is found) + - Error: `BPMN_FILE_MULTIPLE_PROCESSES` (when more than one process is found) + - Success: `SUCCESS` when exactly one process is found - **Valid Examples**: - - ✅ BPMN file with 1 process definition + - ✅ BPMN file with 1 process definition - **Invalid Examples**: - - ❌ BPMN file with 0 process definitions - - ❌ BPMN file with 2 or more process definitions + - ❌ BPMN file with 0 process definitions + - ❌ BPMN file with 2 or more process definitions - **DSF Framework Reference**: - - This validation is based on the DSF Framework requirement defined in: - - `dsf-bpe/dsf-bpe-process-api/src/main/java/dev/dsf/bpe/api/plugin/AbstractProcessPlugin.java` - - DSF validates: `if (processes.size() != 1) { return false; }` + - This validation is based on the DSF Framework requirement defined in: + - `dsf-bpe/dsf-bpe-process-api/src/main/java/dev/dsf/bpe/api/plugin/AbstractProcessPlugin.java` + - DSF validates: `if (processes.size() != 1) { return false; }` ##### Process History Time To Live Validation - **Requirement**: - - Process should have `camunda:historyTimeToLive` attribute set - - If not set (null or empty), DSF automatically uses default value `P30D` (30 days) - - Warning: `BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING` - - Success: `SUCCESS` when historyTimeToLive is explicitly set + - Process should have `camunda:historyTimeToLive` attribute set + - If not set (null or empty), DSF automatically uses default value `P30D` (30 days) + - Warning: `BPMN_PROCESS_HISTORY_TIME_TO_LIVE_MISSING` + - Success: `SUCCESS` when historyTimeToLive is explicitly set - **Valid Examples**: - - ✅ `` - - ✅ `` + - ✅ `` + - ✅ `` - **Warning Example**: - - ⚠️ `` (no historyTimeToLive attribute) + - ⚠️ `` (no historyTimeToLive attribute) - **DSF Framework Reference**: - - DSF Framework sets default at runtime if not specified: - - `process.setOperatonHistoryTimeToLiveString("P30D")` - - Best practice: Set explicitly in BPMN file + - DSF Framework sets default at runtime if not specified: + - `process.setOperatonHistoryTimeToLiveString("P30D")` + - Best practice: Set explicitly in BPMN file ##### Process Executable Validation - **Requirement**: - - Process must have `isExecutable="true"` attribute set - - Processes without this attribute cannot be deployed and executed by the process engine - - Error: `BPMN_PROCESS_NOT_EXECUTABLE` - - Success: `SUCCESS` when isExecutable is true + - Process must have `isExecutable="true"` attribute set + - Processes without this attribute cannot be deployed and executed by the process engine + - Error: `BPMN_PROCESS_NOT_EXECUTABLE` + - Success: `SUCCESS` when isExecutable is true - **Valid Examples**: - - ✅ `` + - ✅ `` - **Invalid Examples**: - - ❌ `` (no isExecutable attribute, defaults to false) - - ❌ `` + - ❌ `` (no isExecutable attribute, defaults to false) + - ❌ `` - **Reason**: - - The process engine only deploys and executes processes marked as executable - - Non-executable processes are typically used for documentation or as templates + - The process engine only deploys and executes processes marked as executable + - Non-executable processes are typically used for documentation or as templates + +##### Message Start Event Validation (Process Level) + +- **Requirement**: + - The process must have at least one **message** start event as a **direct child** of the `` element + - Start events inside `` elements are **not** counted + - Error: `BPMN_MESSAGE_START_EVENT_NOT_FOUND` (reported on the process ID when none is found) + - Success: `SUCCESS` when at least one message start event exists on process level + +- **Valid Examples**: + - ✅ Process with `` and `` as direct child of `` + - ✅ Subprocess with only a generic or message start event (does not satisfy the process-level requirement by itself) + +- **Invalid Examples**: + - ❌ Process with only a generic start event (no `messageEventDefinition`) + - ❌ Process with a message start event only inside a subprocess + +- **DSF Framework Reference**: + - DSF processes are started via incoming messages; see [DSF BPMN Messaging](https://dsf.dev/process-development/api-v2/bpmn/messaging.html) ##### Process Version Tag Validation - **Requirement**: - - Process must define `camunda:versionTag` - - Expected placeholder value in DSF process plugins: `#{version}` - - Error: `BPMN_PROCESS_VERSION_TAG_MISSING_OR_EMPTY` (missing, empty/blank, or literal `"null"`) - - Warning: `BPMN_PROCESS_VERSION_TAG_NO_PLACEHOLDER` (present but without `#{version}`) - - Success: `SUCCESS` when `camunda:versionTag` contains `#{version}` + - Process must define `camunda:versionTag` + - Expected placeholder value in DSF process plugins: `#{version}` + - Error: `BPMN_PROCESS_VERSION_TAG_MISSING_OR_EMPTY` (missing, empty/blank, or literal `"null"`) + - Warning: `BPMN_PROCESS_VERSION_TAG_NO_PLACEHOLDER` (present but without `#{version}`) + - Success: `SUCCESS` when `camunda:versionTag` contains `#{version}` - **Valid Example**: - - ✅ `` + - ✅ `` - **Error Examples**: - - ❌ `` (missing `camunda:versionTag`) - - ❌ `` (empty value) - - ❌ `` (literal `null`) + - ❌ `` (missing `camunda:versionTag`) + - ❌ `` (empty value) + - ❌ `` (literal `null`) - **Warning Examples**: - - ⚠️ `` - - ⚠️ `` + - ⚠️ `` + - ⚠️ `` #### Task Validation @@ -139,375 +158,321 @@ The linter performs comprehensive validation on BPMN 2.0 process definitions usi ##### Service Tasks - **Name Validation**: - - Task must have a non-empty name - - Error: `BPMN_SERVICE_TASK_NAME_EMPTY` + - Task must have a non-empty name + - Error: `BPMN_SERVICE_TASK_NAME_EMPTY` - **Implementation Class Validation**: - - `camunda:class` or `camunda:delegateExpression` must be specified - - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_NOT_EXIST` - - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_EMPTY` - - Implementation class must exist in the classpath - - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_NOT_FOUND` + - `camunda:class` or `camunda:delegateExpression` must be specified + - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_NOT_EXIST` + - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_EMPTY` + - Implementation class must exist in the classpath + - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_NOT_FOUND` - **API Version-Specific Requirements**: - - **V1 API**: - - Both checks are performed separately: - - Class must extend `dev.dsf.bpe.v1.activity.AbstractServiceDelegate` - - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_SERVICE_DELEGATE` (if not extending) - - Class must implement `org.camunda.bpm.engine.delegate.JavaDelegate` - - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_NOT_IMPLEMENTING_JAVA_DELEGATE` (if not implementing) - - Note: Both conditions are checked independently. A class should ideally satisfy both, but the linter reports separate errors for each missing requirement. - - **V2 API**: - - Class must implement `dev.dsf.bpe.v2.activity.ServiceTask` - - Error: `BPMN_SERVICE_TASK_NO_INTERFACE_CLASS_IMPLEMENTING` + - **V1 API** (both checks are independent): + - Class should extend `dev.dsf.bpe.v1.activity.AbstractServiceDelegate` + - Warning: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_SERVICE_DELEGATE` (if not extending) + - Class must implement `org.camunda.bpm.engine.delegate.JavaDelegate` + - Error: `BPMN_SERVICE_TASK_IMPLEMENTATION_CLASS_NOT_IMPLEMENTING_JAVA_DELEGATE` (if not implementing) + - **V2 API**: + - Class must implement `dev.dsf.bpe.v2.activity.ServiceTask` + - Error: `BPMN_SERVICE_TASK_NO_INTERFACE_CLASS_IMPLEMENTING` ##### User Tasks - **Name Validation**: - - Task must have a non-empty name - - Error: `BPMN_USER_TASK_NAME_EMPTY` + - Task should have a non-empty name + - Warning: `BPMN_USER_TASK_NAME_EMPTY` - **Form Key Validation**: - - `camunda:formKey` must be present and non-empty - - Error: `BPMN_USER_TASK_FORM_KEY_EMPTY` - - Must reference an external form (starting with "external:", "http://", or "https://") - - Error: `BPMN_USER_TASK_FORM_KEY_IS_NOT_AN_EXTERNAL_FORM` - - Must reference a valid Questionnaire resource - - Referenced Questionnaire must exist in the plugin - - Error: `BPMN_USER_TASK_QUESTIONNAIRE_NOT_FOUND` + - `camunda:formKey` must be present and non-empty + - Error: `BPMN_USER_TASK_FORM_KEY_EMPTY` + - Must reference an external form (starting with "external:", "http://", or "https://") + - Error: `BPMN_USER_TASK_FORM_KEY_IS_NOT_AN_EXTERNAL_FORM` + - Must reference a valid Questionnaire resource + - Referenced Questionnaire must exist in the plugin + - Error: `BPMN_USER_TASK_QUESTIONNAIRE_NOT_FOUND` - **Listener Validation**: - - Listener classes must exist - - Error: `BPMN_USER_TASK_LISTENER_JAVA_CLASS_NOT_FOUND` - - Listener must have class attribute - - Error: `BPMN_USER_TASK_LISTENER_MISSING_CLASS_ATTRIBUTE` + - Listener classes must exist + - Error: `BPMN_USER_TASK_LISTENER_JAVA_CLASS_NOT_FOUND` + - Listener must have class attribute + - Error: `BPMN_USER_TASK_LISTENER_MISSING_CLASS_ATTRIBUTE` - **API Version-Specific Requirements**: - - **V1 API**: - - Listener must extend `dev.dsf.bpe.v1.activity.DefaultUserTaskListener` OR implement `org.camunda.bpm.engine.delegate.TaskListener` - - Error: `BPMN_USER_TASK_LISTENER_NOT_EXTENDING_OR_IMPLEMENTING_REQUIRED_CLASS` - - **V2 API**: - - Listener must extend `dev.dsf.bpe.v2.activity.DefaultUserTaskListener` OR implement `dev.dsf.bpe.v2.activity.UserTaskListener` - - Error: `BPMN_USER_TASK_LISTENER_NOT_EXTENDING_OR_IMPLEMENTING_REQUIRED_CLASS` + - **V1 API**: + - Listener must extend `dev.dsf.bpe.v1.activity.DefaultUserTaskListener` OR implement `org.camunda.bpm.engine.delegate.TaskListener` + - Error: `BPMN_USER_TASK_LISTENER_NOT_EXTENDING_OR_IMPLEMENTING_REQUIRED_CLASS` + - **V2 API**: + - Listener must extend `dev.dsf.bpe.v2.activity.DefaultUserTaskListener` OR implement `dev.dsf.bpe.v2.activity.UserTaskListener` + - Error: `BPMN_USER_TASK_LISTENER_NOT_EXTENDING_OR_IMPLEMENTING_REQUIRED_CLASS` - **Task Listener Input Parameter Validation (V2 API only)**: - - Validates input parameters (`camunda:inputParameter`) within task listeners for API v2 - - Applies to all task listeners in API v2, with severity based on whether the listener extends `DefaultUserTaskListener` - - - **`practitionerRole` Parameter**: - - If a `practitionerRole` input parameter is defined in the task listener's `extensionElements`, its value must not be null or empty - - **Severity**: - - **ERROR**: When the task listener extends `dev.dsf.bpe.v2.activity.DefaultUserTaskListener` - - **WARN**: When the task listener does not extend `DefaultUserTaskListener` - - Error/Warning: `BPMN_PRACTITIONER_ROLE_HAS_NO_VALUE_OR_NULL` - - Success: `SUCCESS` (when value is present and non-empty) - - - **`practitioners` Parameter**: - - If a `practitioners` input parameter is defined in the task listener's `extensionElements`, its value must not be null or empty - - **Severity**: - - **ERROR**: When the task listener extends `dev.dsf.bpe.v2.activity.DefaultUserTaskListener` - - **WARN**: When the task listener does not extend `DefaultUserTaskListener` - - Error/Warning: `BPMN_PRACTITIONERS_HAS_NO_VALUE_OR_NULL` - - Success: `SUCCESS` (when value is present and non-empty) - - - **Validation Behavior**: - - Only validates input parameters if they are explicitly defined in the BPMN file - - Supports various value formats: direct text content, ``, or `` with `` elements - - Validation is skipped if the input parameter is not present (no lint items generated) - - Validation only applies to API v2 task listeners + - Validates input parameters (`camunda:inputParameter`) within task listeners for API v2 + - Applies to all task listeners in API v2, with severity based on whether the listener extends `DefaultUserTaskListener` + + - **`practitionerRole` Parameter**: + - If a `practitionerRole` input parameter is defined in the task listener's `extensionElements`, its value must not be null or empty + - **Severity**: + - **ERROR**: When the task listener extends `dev.dsf.bpe.v2.activity.DefaultUserTaskListener` + - **WARN**: When the task listener does not extend `DefaultUserTaskListener` + - Error/Warning: `BPMN_PRACTITIONER_ROLE_HAS_NO_VALUE_OR_NULL` + - Success: `SUCCESS` (when value is present and non-empty) + + - **`practitioners` Parameter**: + - If a `practitioners` input parameter is defined in the task listener's `extensionElements`, its value must not be null or empty + - **Severity**: + - **ERROR**: When the task listener extends `dev.dsf.bpe.v2.activity.DefaultUserTaskListener` + - **WARN**: When the task listener does not extend `DefaultUserTaskListener` + - Error/Warning: `BPMN_PRACTITIONERS_HAS_NO_VALUE_OR_NULL` + - Success: `SUCCESS` (when value is present and non-empty) + + - **Validation Behavior**: + - Only validates input parameters if they are explicitly defined in the BPMN file + - Supports various value formats: direct text content, ``, or `` with `` elements + - Validation is skipped if the input parameter is not present (no lint items generated) + - Validation only applies to API v2 task listeners - **Task Listener TaskOutput Field Injections Validation (V2 API only)**: - - Validates the taskOutput field injections (`taskOutputSystem`, `taskOutputCode`, `taskOutputVersion`) used to configure output parameters for UserTask listeners - - Applies to all task listeners in API v2 - - - **Completeness Check**: - - If any of the three fields (`taskOutputSystem`, `taskOutputCode`, `taskOutputVersion`) is set, all three must be set - - Error: `BPMN_USER_TASK_LISTENER_INCOMPLETE_TASK_OUTPUT_FIELDS` - - Message: "If taskOutputSystem, taskOutputCode, or taskOutputVersion is set, all three must be set" - - Validation is skipped if none of the fields are set - - - **FHIR Resource Validation**: - - **`taskOutputSystem`**: Should reference a valid CodeSystem URL - - Uses `FhirAuthorizationCache.containsSystem()` to check if the CodeSystem exists - - Error: `BPMN_USER_TASK_LISTENER_TASK_OUTPUT_SYSTEM_INVALID_FHIR_RESOURCE` if CodeSystem is unknown - - Success: `SUCCESS` when CodeSystem is valid - - - **`taskOutputCode`**: Should be a valid code in the referenced CodeSystem - - Uses `FhirAuthorizationCache.isUnknown()` to check if the code exists in the CodeSystem - - Error: `BPMN_USER_TASK_LISTENER_TASK_OUTPUT_CODE_INVALID_FHIR_RESOURCE` if code is unknown - - Success: `SUCCESS` when code is valid - - - **`taskOutputVersion`**: Must contain a placeholder (e.g., `#{version}`) - - Uses `LintingUtils.containsPlaceholder()` to check for placeholders - - Warning: `BPMN_USER_TASK_LISTENER_TASK_OUTPUT_VERSION_NO_PLACEHOLDER` if no placeholder found - - Success: `SUCCESS` when placeholder is present - - - **Validation Behavior**: - - Only validates field injections if they are explicitly defined in the task listener's `extensionElements` - - Field values are read from `camunda:field` elements with `camunda:stringValue` or nested `` elements - - Validation is skipped if none of the fields are set (no lint items generated) - - Validation only applies to API v2 task listeners - - FHIR resource validation is only performed if all three fields are set (completeness check passes) + - Validates the taskOutput field injections (`taskOutputSystem`, `taskOutputCode`, `taskOutputVersion`) used to configure output parameters for UserTask listeners + - Applies to all task listeners in API v2 + + - **Completeness Check**: + - If any of the three fields (`taskOutputSystem`, `taskOutputCode`, `taskOutputVersion`) is set, all three must be set + - Error: `BPMN_USER_TASK_LISTENER_INCOMPLETE_TASK_OUTPUT_FIELDS` + - Message: "If taskOutputSystem, taskOutputCode, or taskOutputVersion is set, all three must be set" + - Validation is skipped if none of the fields are set + + - **FHIR Resource Validation**: + - **`taskOutputSystem`**: Should reference a valid CodeSystem URL + - Uses `FhirAuthorizationCache.containsSystem()` to check if the CodeSystem exists + - Error: `BPMN_USER_TASK_LISTENER_TASK_OUTPUT_SYSTEM_INVALID_FHIR_RESOURCE` if CodeSystem is unknown + - Success: `SUCCESS` when CodeSystem is valid + + - **`taskOutputCode`**: Should be a valid code in the referenced CodeSystem + - Uses `FhirAuthorizationCache.isUnknown()` to check if the code exists in the CodeSystem + - Error: `BPMN_USER_TASK_LISTENER_TASK_OUTPUT_CODE_INVALID_FHIR_RESOURCE` if code is unknown + - Success: `SUCCESS` when code is valid + + - **`taskOutputVersion`**: Must contain a placeholder (e.g., `#{version}`) + - Uses `LintingUtils.containsPlaceholder()` to check for placeholders + - Warning: `BPMN_USER_TASK_LISTENER_TASK_OUTPUT_VERSION_NO_PLACEHOLDER` if no placeholder found + - Success: `SUCCESS` when placeholder is present + + - **Validation Behavior**: + - Only validates field injections if they are explicitly defined in the task listener's `extensionElements` + - Field values are read from `camunda:field` elements with `camunda:stringValue` or nested `` elements + - Validation is skipped if none of the fields are set (no lint items generated) + - Validation only applies to API v2 task listeners + - FHIR resource validation is only performed if all three fields are set (completeness check passes) ##### Send Tasks - **Name Validation**: - - Task must have a non-empty name + - Task should have a non-empty name + - Warning: `BPMN_EVENT_NAME_EMPTY` (when empty; same type as other unnamed events) - **Implementation Class Validation**: - - Implementation class must exist - - Error: `BPMN_MESSAGE_SEND_TASK_IMPLEMENTATION_CLASS_EMPTY` - - Error: `BPMN_MESSAGE_SEND_TASK_IMPLEMENTATION_CLASS_NOT_FOUND` - + - Implementation class must exist + - Error: `BPMN_MESSAGE_SEND_TASK_IMPLEMENTATION_CLASS_EMPTY` + - Error: `BPMN_MESSAGE_SEND_TASK_IMPLEMENTATION_CLASS_NOT_FOUND` + - **API Version-Specific Requirements**: - - **V1 API**: - - Both checks are performed separately: - - Class must extend `dev.dsf.bpe.v1.activity.AbstractTaskMessageSend` - - Error: `BPMN_SEND_TASK_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_TASK_MESSAGE_SEND` (if not extending) - - Class must implement `org.camunda.bpm.engine.delegate.JavaDelegate` - - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_NOT_IMPLEMENTING_JAVA_DELEGATE` (if not implementing) - - Note: Both conditions are checked independently. A class should ideally satisfy both, but the linter reports separate errors for each missing requirement. - - **V2 API**: - - Class must implement `dev.dsf.bpe.v2.activity.MessageSendTask` - - Error: `BPMN_SEND_TASK_NO_INTERFACE_CLASS_IMPLEMENTING` + - **V1 API** (both checks are independent): + - Class should extend `dev.dsf.bpe.v1.activity.AbstractTaskMessageSend` + - Warning: `BPMN_SEND_TASK_IMPLEMENTATION_CLASS_NOT_EXTENDING_ABSTRACT_TASK_MESSAGE_SEND` (if not extending) + - Class must implement `org.camunda.bpm.engine.delegate.JavaDelegate` + - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_NOT_IMPLEMENTING_JAVA_DELEGATE` (if not implementing) + - **V2 API**: + - Class must implement `dev.dsf.bpe.v2.activity.MessageSendTask` + - Error: `BPMN_SEND_TASK_NO_INTERFACE_CLASS_IMPLEMENTING` -- **Field Injection Validation**: - - Same field injections as Message Send Events are validated: `profile`, `messageName`, and `instantiatesCanonical` - - `profile` field injection: - - Must be non-empty - - Error: `BPMN_FIELD_INJECTION_PROFILE_EMPTY` - - Must contain version placeholder `#{version}` - - Error: `BPMN_FIELD_INJECTION_PROFILE_NO_VERSION_PLACEHOLDER` - - Must reference existing StructureDefinition - - Error: `BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE` - - `messageName` field injection: - - Must be non-empty - - Error: `BPMN_FIELD_INJECTION_MESSAGE_VALUE_EMPTY` - - Must be a string literal - - Error: `BPMN_FIELD_INJECTION_NOT_STRING_LITERAL` - - `instantiatesCanonical` field injection: - - Must be non-empty - - Error: `BPMN_FIELD_INJECTION_INSTANTIATES_CANONICAL_EMPTY` - - Must end with version placeholder `|#{version}` - - Error: `BPMN_FIELD_INJECTION_INSTANTIATES_CANONICAL_NO_VERSION_PLACEHOLDER` - - Must reference existing ActivityDefinition - - Error: `BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE` - - Unknown field injections are reported - - Error: `BPMN_UNKNOWN_FIELD_INJECTION` +- **Field Injection Validation**: see [Field Injection Validation](#field-injection-validation-message-send--start--throw--end--send-task) ##### Receive Tasks - **Name Validation**: - - Task must have a non-empty name - - Warning: `BPMN_EVENT_NAME_EMPTY` + - Task should have a non-empty name + - Warning: `BPMN_EVENT_NAME_EMPTY` (when empty) - **Message Definition Validation**: - - Message definition must be present and have a non-empty message name - - Error: `BPMN_MESSAGE_START_EVENT_MESSAGE_NAME_EMPTY` + - `messageRef` / message name must be set and non-empty + - Error: `BPMN_MESSAGE_START_EVENT_MESSAGE_NAME_EMPTY` (same type is also used for receive tasks) + +- **FHIR Resource Validation** (via `checkMessageName` when message name is set): + - Error: `BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE` + - Error: `BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE` -- **FHIR Resource Validation**: - - Message name must reference an existing ActivityDefinition - - Error: `BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE` - - Message name must reference an existing StructureDefinition - - Error: `BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE` +- **Execution Listeners**: same as other tasks (see [Execution Listeners](#execution-listeners)) #### Event Validation -##### Message Events (Start/Intermediate/End) +##### Message Start Events -- **Event Name Validation**: - - Event must have a non-empty name - - Error: `BPMN_EVENT_NAME_EMPTY` - - Error: `BPMN_MESSAGE_START_EVENT_MESSAGE_NAME_EMPTY` - - Error: `BPMN_MESSAGE_INTERMEDIATE_CATCH_EVENT_NAME_EMPTY` - - Error: `BPMN_MESSAGE_INTERMEDIATE_CATCH_EVENT_MESSAGE_NAME_EMPTY` - - Error: `BPMN_MESSAGE_BOUNDARY_EVENT_NAME_EMPTY` +- **Event Name**: should be set — Warning: `BPMN_EVENT_NAME_EMPTY` +- **Message Name**: must be set — Error: `BPMN_MESSAGE_START_EVENT_MESSAGE_NAME_EMPTY` +- **FHIR**: ActivityDefinition / StructureDefinition via message name — Errors: `BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE`, `BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE` +- **Field Injections**: same as send task (`profile`, `messageName`, `instantiatesCanonical`) +- **Implementation Class**: not required (no `camunda:class` on start events) -- **Implementation Class Validation**: - - For send events, implementation class must exist - - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_EMPTY` - - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_NOT_FOUND` - - Intermediate throw events should not have message definitions - - Error: `BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_HAS_MESSAGE` - -- **API Version-Specific Requirements**: - - **V1 API**: - - Class must implement `org.camunda.bpm.engine.delegate.JavaDelegate` - - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_NOT_IMPLEMENTING_JAVA_DELEGATE` - - Throw events must implement `org.camunda.bpm.engine.delegate.JavaDelegate` - - Error: `BPMN_END_EVENT_NO_INTERFACE_CLASS_IMPLEMENTING` - - **V2 API**: - - Message Intermediate Throw Events must implement `dev.dsf.bpe.v2.activity.MessageIntermediateThrowEvent` - - Message End Events must implement `dev.dsf.bpe.v2.activity.MessageEndEvent` - - Error: `BPMN_END_EVENT_NO_INTERFACE_CLASS_IMPLEMENTING` +##### Message Intermediate Catch Events -- **Field Injection Validation**: - - `profile` field injection: - - Must be non-empty - - Error: `BPMN_FIELD_INJECTION_PROFILE_EMPTY` - - Must contain version placeholder `#{version}` - - Error: `BPMN_FIELD_INJECTION_PROFILE_NO_VERSION_PLACEHOLDER` - - Must reference existing StructureDefinition - - Error: `BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE` - - - `messageName` field injection: - - Must be non-empty - - Error: `BPMN_FIELD_INJECTION_MESSAGE_VALUE_EMPTY` - - Must be a string literal - - Error: `BPMN_FIELD_INJECTION_NOT_STRING_LITERAL` - - - `instantiatesCanonical` field injection: - - Must be non-empty - - Error: `BPMN_FIELD_INJECTION_INSTANTIATES_CANONICAL_EMPTY` - - Must end with version placeholder `|#{version}` - - Error: `BPMN_FIELD_INJECTION_INSTANTIATES_CANONICAL_NO_VERSION_PLACEHOLDER` - - Must reference existing ActivityDefinition - - Error: `BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE` +- **Event Name**: Warning: `BPMN_MESSAGE_INTERMEDIATE_CATCH_EVENT_NAME_EMPTY` +- **Message Name**: Error: `BPMN_MESSAGE_INTERMEDIATE_CATCH_EVENT_MESSAGE_NAME_EMPTY` +- **FHIR**: same as message start (ActivityDefinition / StructureDefinition) -##### Timer Events +##### Message Intermediate Throw Events -- **Timer Type Validation**: - - At least one of `timeDate`, `timeCycle`, or `timeDuration` must be set - - Error: `BPMN_FLOATING_ELEMENT` (`TIMER_TYPE_IS_EMPTY`) +- **Event Name**: Warning: `BPMN_EVENT_NAME_EMPTY` +- **Implementation Class** (required): + - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_EMPTY` (missing) + - Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_NOT_FOUND` (not on classpath) + - **V1**: Error: `BPMN_MESSAGE_SEND_EVENT_IMPLEMENTATION_CLASS_NOT_IMPLEMENTING_JAVA_DELEGATE` + - **V2**: Error: `BPMN_END_EVENT_NO_INTERFACE_CLASS_IMPLEMENTING` (expects `MessageIntermediateThrowEvent`) +- **Message Reference**: message intermediate throw events should **not** have a message definition in the BPMN + - Info: `BPMN_MESSAGE_INTERMEDIATE_THROW_EVENT_HAS_MESSAGE_REFERENCE` (with or without message ref) +- **Field Injections**: same as send task -- **Fixed Date Warning**: - - `timeDate` expressions are flagged with an informational message to verify if a fixed date is intended - - Info: `BPMN_FLOATING_ELEMENT` (`TIMER_TYPE_IS_A_FIXED_DATE_TIME`) +##### Message End Events -- **Placeholder Validation**: - - `timeCycle` and `timeDuration` values should contain a placeholder (e.g., `#{interval}`) - - Warning: `BPMN_FLOATING_ELEMENT` (`TIMER_VALUE_APPEARS_FIXED_NO_PLACEHOLDER_FOUND`) +- **Event Name**: Warning: `BPMN_EVENT_NAME_EMPTY` +- **Implementation Class**: same as message intermediate throw (element-specific; V2: `MessageEndEvent`) +- **Field Injections**: same as send task + +##### Message Boundary Events + +- **Event Name**: Warning: `BPMN_MESSAGE_BOUNDARY_EVENT_NAME_EMPTY` +- **Message Name**: Error: `BPMN_MESSAGE_BOUNDARY_EVENT_MESSAGE_NAME_EMPTY` +- **FHIR**: via `BpmnMessageLinter.lintMessageEventDefinition` (ActivityDefinition / StructureDefinition) + +##### Field Injection Validation (Message Send / Start / Throw / End / Send Task) + +Applies to all elements with message-send field injections (`BpmnFieldInjectionLinter`): + +- `profile`: empty → Error `BPMN_FIELD_INJECTION_PROFILE_EMPTY`; missing `#{version}` placeholder → Warning `BPMN_FIELD_INJECTION_PROFILE_NO_VERSION_PLACEHOLDER`; StructureDefinition not found → Warning `BPMN_NO_STRUCTURE_DEFINITION_FOUND_FOR_MESSAGE` +- `messageName`: empty → Error `BPMN_FIELD_INJECTION_MESSAGE_VALUE_EMPTY`; not a string literal → Error `BPMN_FIELD_INJECTION_NOT_STRING_LITERAL` +- `instantiatesCanonical`: empty → Error `BPMN_FIELD_INJECTION_INSTANTIATES_CANONICAL_EMPTY`; missing version placeholder → Warning `BPMN_FIELD_INJECTION_INSTANTIATES_CANONICAL_NO_VERSION_PLACEHOLDER`; ActivityDefinition not found → Warning `BPMN_NO_ACTIVITY_DEFINITION_FOUND_FOR_MESSAGE` (cross-check; `messageName` mismatch on ActivityDefinition → Error) +- Unknown fields → Warning `BPMN_UNKNOWN_FIELD_INJECTION` + +##### Timer Events (Intermediate Catch) + +All timer findings use `BPMN_FLOATING_ELEMENT` with a **context-specific message** (not the enum default text). + +- **Event Name** (timer intermediate catch): empty name — Warning, message: *"Timer Intermediate Catch Event name is empty"* +- **Timer Type**: at least one of `timeDate`, `timeCycle`, `timeDuration` — Error, message: *"Timer type is empty (no timeDate, timeCycle, or timeDuration)"* +- **Fixed `timeDate`**: Info, message: *"Timer type is a fixed date/time (timeDate) – please verify if this is intended"* +- **Placeholder** (`timeCycle` / `timeDuration`): no placeholder — Warning, message: *"Timer value appears fixed (no placeholder found)"* ##### Error Boundary Events -- **Error Configuration Validation**: - - Error reference must be present - - Error code must not be empty - - Error: `BPMN_ERROR_BOUNDARY_EVENT_ERROR_CODE_EMPTY` - - Error name must not be empty (warning) - - Error: `BPMN_ERROR_BOUNDARY_EVENT_ERROR_NAME_EMPTY` - - Error: `BPMN_ERROR_BOUNDARY_EVENT_NAME_EMPTY` - - Error code variable must not be empty - - Error: `BPMN_ERROR_BOUNDARY_EVENT_ERROR_CODE_VARIABLE_EMPTY` +- **Boundary Event Name**: empty — Warning: `BPMN_ERROR_BOUNDARY_EVENT_NAME_EMPTY` +- **Error Name** (on the error element): empty — Warning: `BPMN_ERROR_BOUNDARY_EVENT_ERROR_NAME_EMPTY` +- **Error Code**: empty — Error: `BPMN_ERROR_BOUNDARY_EVENT_ERROR_CODE_EMPTY` +- **Error Code Variable** (`camunda:errorCodeVariable`): empty — Warning: `BPMN_ERROR_BOUNDARY_EVENT_ERROR_CODE_VARIABLE_EMPTY` ##### Signal Events -- **Signal Definition Validation**: - - Signal end events must have a non-empty name - - Error: `BPMN_SIGNAL_END_EVENT_NAME_EMPTY` - - Signal end events must have a signal definition - - Error: `BPMN_SIGNAL_END_EVENT_SIGNAL_EMPTY` - - Signal intermediate throw events must have a non-empty name - - Error: `BPMN_SIGNAL_INTERMEDIATE_THROW_EVENT_NAME_EMPTY` - - Signal intermediate throw events must have a signal definition - - Error: `BPMN_SIGNAL_INTERMEDIATE_THROW_EVENT_SIGNAL_EMPTY` - - Signal definitions must be valid - - Signal references must be correct +**Signal End Event** -##### Conditional Events +- Empty name — Warning: `BPMN_SIGNAL_END_EVENT_NAME_EMPTY` +- Missing/empty signal definition — Error: `BPMN_SIGNAL_END_EVENT_SIGNAL_EMPTY` -- **Event Name Validation**: - - Conditional Intermediate Catch Event should have a non-empty name - - Warning: `BPMN_FLOATING_ELEMENT` (`CONDITIONAL_INTERMEDIATE_CATCH_EVENT_NAME_IS_EMPTY`) +**Signal Intermediate Throw Event** -- **Variable Name Validation**: - - `camunda:variableName` attribute must not be empty - - Error: `BPMN_FLOATING_ELEMENT` (`CONDITIONAL_INTERMEDIATE_CATCH_EVENT_VARIABLE_NAME_IS_EMPTY`) +- Empty name — Warning: `BPMN_SIGNAL_INTERMEDIATE_THROW_EVENT_NAME_EMPTY` +- Missing/empty signal definition — Error: `BPMN_SIGNAL_INTERMEDIATE_THROW_EVENT_SIGNAL_EMPTY` -- **Variable Events Validation**: - - `camunda:variableEvents` attribute must not be empty - - Error: `BPMN_FLOATING_ELEMENT` (`CONDITIONAL_INTERMEDIATE_CATCH_EVENT_VARIABLE_EVENTS_IS_EMPTY`) +**Signal Intermediate Catch Event** -- **Condition Type Validation**: - - `camunda:conditionType` must be set, or a condition expression must be provided (in which case `"expression"` is assumed) - - Error: `BPMN_FLOATING_ELEMENT` (`CONDITIONAL_INTERMEDIATE_CATCH_EVENT_CONDITION_TYPE_IS_EMPTY`) +- Empty name — Warning: `BPMN_FLOATING_ELEMENT` (*"Signal Intermediate Catch Event name is empty"*) +- Missing/empty signal — Error: `BPMN_FLOATING_ELEMENT` (*"Signal is empty in Signal Intermediate Catch Event"*) -- **Condition Expression Validation**: - - When condition type is `"expression"`, the condition expression must not be empty - - Error: `BPMN_FLOATING_ELEMENT` (`CONDITIONAL_INTERMEDIATE_CATCH_EVENT_CONDITION_TYPE_IS_NOT_EXPRESSION`) +##### Conditional Events (Intermediate Catch) -#### Gateway and Flow Validation +All findings use `BPMN_FLOATING_ELEMENT` with a context-specific message. + +| Check | Severity | Message (excerpt) | +|-------|----------|-------------------| +| Empty event name | WARN | *"Conditional Intermediate Catch Event name is empty"* | +| Empty `camunda:variableName` | ERROR | *"... variable name is empty"* | +| Empty `camunda:variableEvents` | ERROR | *"... variableEvents is empty"* | +| Empty `conditionType` (no condition expression) | ERROR | *"... condition type is empty"* | +| `conditionType` set but not `expression` | INFO | *"... condition type is not 'expression': …"* | +| `conditionType` = `expression`, empty expression | ERROR | *"... expression is empty"* | -##### Flow Structure +If a condition expression is present but `conditionType` is missing, `expression` is assumed internally (success item). -- **Message Start Event**: - - Message-triggered processes must have a message start event - - Error: `BPMN_MESSAGE_START_EVENT_NOT_FOUND` +#### Gateway and Flow Validation ##### Exclusive Gateways -- **Sequence Flow Validation**: - - Outgoing sequence flows must have appropriate names - - When multiple outgoing flows exist, gateway must have a name - - Error: `BPMN_EXCLUSIVE_GATEWAY_HAS_MULTIPLE_OUTGOING_FLOWS_BUT_NAME_IS_EMPTY` - - Conditional expressions required when multiple paths exist - - Default flow validation +- When there are **multiple** outgoing sequence flows: gateway name should be set + - Warning: `BPMN_EXCLUSIVE_GATEWAY_HAS_MULTIPLE_OUTGOING_FLOWS_BUT_NAME_IS_EMPTY` +- Execution listeners: see [Execution Listeners](#execution-listeners) ##### Inclusive Gateways -- **Sequence Flow Validation**: - - Similar requirements as exclusive gateways - - When multiple outgoing flows exist, gateway must have a name - - Error: `BPMN_INCLUSIVE_GATEWAY_HAS_MULTIPLE_OUTGOING_FLOWS_BUT_NAME_IS_EMPTY` - - Multiple path handling +- When there are **multiple** outgoing sequence flows: gateway name should be set + - Warning: `BPMN_INCLUSIVE_GATEWAY_HAS_MULTIPLE_OUTGOING_FLOWS_BUT_NAME_IS_EMPTY` +- Execution listeners: see [Execution Listeners](#execution-listeners) ##### Event-Based Gateways -- **Configuration Validation**: - - Proper configuration required - - Outgoing flow setup validation +- Only **execution listeners** are validated (classpath / API version); no additional gateway naming or flow rules. ##### Sequence Flows -- **Naming and Conditions**: - - Naming conventions - - Conditional expressions for non-default flows from splitting gateways - - Error: `BPMN_FLOW_ELEMENT` +Type `BPMN_FLOW_ELEMENT` with `FlowElementType` in the message: + +| Situation | Severity | FlowElementType (internal) | +|-----------|----------|----------------------------| +| No source node | ERROR | `SEQUENCE_FLOW_HAS_NO_SOURCE_NODE` | +| Source with multiple outgoing flows, flow without name | WARN | `SEQUENCE_FLOW_ORIGINATES_FROM_A_SOURCE_WITH_MULTIPLE_OUTGOING_FLOWS_AND_NAME_IS_EMPTY` | +| Default flow from exclusive/inclusive gateway **with** condition | WARN | `DEFAULT_SEQUENCE_FLOW_HAS_CONDITION_EXPRESSION` | +| Non-default flow from exclusive/inclusive gateway **without** condition | WARN | `NON_DEFAULT_SEQUENCE_FLOW_IS_MISSING_A_CONDITION_EXPRESSION` | + +JSON reports include `flowElementType` for these items. Process-level message start events are validated separately — see [Message Start Event Validation (Process Level)](#message-start-event-validation-process-level) (`BPMN_MESSAGE_START_EVENT_NOT_FOUND`). #### SubProcess Validation ##### Multi-Instance SubProcesses - **Asynchronous Execution**: - - `asyncBefore` must be set to `true` for proper asynchronous execution - - Required for multi-instance subprocesses - - Error: `BPMN_SUB_PROCESS_HAS_MULTI_INSTANCE_BUT_IS_NOT_ASYNC_BEFORE_TRUE` + - Multi-instance subprocesses should have `asyncBefore="true"` + - Warning: `BPMN_SUB_PROCESS_HAS_MULTI_INSTANCE_BUT_IS_NOT_ASYNC_BEFORE_TRUE` -##### Start/End Events in SubProcesses +##### Start/End Events (outside / inside subprocesses) -- **Structural Validation**: - - Start events must be part of subprocess - - Error: `BPMN_START_EVENT_NOT_PART_OF_SUB_PROCESS` - - End events must be part of subprocess - - Error: `BPMN_END_EVENT_NOT_PART_OF_SUB_PROCESS` - - End events inside subprocesses should have `asyncAfter` set to `true` - - Error: `BPMN_END_EVENT_INSIDE_SUB_PROCESS_SHOULD_HAVE_ASYNC_AFTER_TRUE` +- **Generic Start Event** (not in a subprocess): name should be set + - Warning: `BPMN_START_EVENT_NOT_PART_OF_SUB_PROCESS` (empty name; the type name refers to start events **outside** a subprocess) +- **Generic End Event** (not in a subprocess): name should be set + - Warning: `BPMN_END_EVENT_NOT_PART_OF_SUB_PROCESS` +- **End Event in subprocess**: should have `asyncAfter="true"` + - Warning: `BPMN_END_EVENT_INSIDE_SUB_PROCESS_SHOULD_HAVE_ASYNC_AFTER_TRUE` -#### Floating Elements +#### `BPMN_FLOATING_ELEMENT` (note) -- **Element Placement**: - - Elements must be properly connected - - Error: `BPMN_FLOATING_ELEMENT` +The type `BPMN_FLOATING_ELEMENT` has the default text *"BPMN element is outside of message start event triggered flow."*, but the code **reuses** it for timer, conditional, and signal catch configuration (see above). There is **no** separate graph/reachability analysis for “floating” elements. #### Execution Listeners - **Execution Listener Validation**: - - Execution listener classes must exist in the classpath - - Error: `BPMN_EXECUTION_LISTENER_CLASS_NOT_FOUND` + - Execution listener classes must exist in the classpath + - Error: `BPMN_EXECUTION_LISTENER_CLASS_NOT_FOUND` - **API Version-Specific Requirements**: - - **V1 API**: - - Execution listener classes must implement `org.camunda.bpm.engine.delegate.ExecutionListener` - - Error: `BPMN_EXECUTION_LISTENER_NOT_IMPLEMENTING_REQUIRED_INTERFACE` - - **V2 API**: - - Execution listener classes must implement `dev.dsf.bpe.v2.activity.ExecutionListener` - - Error: `BPMN_EXECUTION_LISTENER_NOT_IMPLEMENTING_REQUIRED_INTERFACE` + - **V1 API**: + - Execution listener classes must implement `org.camunda.bpm.engine.delegate.ExecutionListener` + - Error: `BPMN_EXECUTION_LISTENER_NOT_IMPLEMENTING_REQUIRED_INTERFACE` + - **V2 API**: + - Execution listener classes must implement `dev.dsf.bpe.v2.activity.ExecutionListener` + - Error: `BPMN_EXECUTION_LISTENER_NOT_IMPLEMENTING_REQUIRED_INTERFACE` #### Unknown Field Injections - **Field Injection Validation**: - - Only known field injections are allowed - - Error: `BPMN_UNKNOWN_FIELD_INJECTION` + - Only known field injections (`profile`, `messageName`, `instantiatesCanonical`, …) are allowed + - Warning: `BPMN_UNKNOWN_FIELD_INJECTION` ### FHIR Resource Validation @@ -518,8 +483,8 @@ The linter validates FHIR resources against DSF-specific profiles and HL7 FHIR s #### Unparsable FHIR Resources - **Resource Parsing**: - - FHIR resources must be valid XML or JSON - - Error: `PLUGIN_DEFINITION_UNPARSABLE_FHIR_RESOURCE` + - FHIR resources must be valid XML or JSON + - Error: `PLUGIN_DEFINITION_UNPARSABLE_FHIR_RESOURCE` #### Task Resources @@ -528,74 +493,74 @@ Task resources are validated against the DSF Task base profile (`http://dsf.dev/ ##### Metadata and Profile Validation - **Profile Validation**: - - `meta.profile` must be present and point to a DSF Task profile - - Error: `FHIR_TASK_MISSING_PROFILE` - - Profile must be loadable - - Error: `FHIR_TASK_COULD_NOT_LOAD_PROFILE` + - `meta.profile` must be present and point to a DSF Task profile + - Error: `FHIR_TASK_MISSING_PROFILE` + - Profile must be loadable + - Error: `FHIR_TASK_COULD_NOT_LOAD_PROFILE` - **InstantiatesCanonical Validation**: - - `instantiatesCanonical` must be present - - Error: `FHIR_TASK_MISSING_INSTANTIATES_CANONICAL` - - Must end with version placeholder `|#{version}` - - Error: `FHIR_TASK_INSTANTIATES_CANONICAL_PLACEHOLDER` - - Must reference existing ActivityDefinition - - Error: `FHIR_TASK_UNKNOWN_INSTANTIATES_CANONICAL` + - `instantiatesCanonical` must be present + - Error: `FHIR_TASK_MISSING_INSTANTIATES_CANONICAL` + - Must end with version placeholder `|#{version}` + - Error: `FHIR_TASK_INSTANTIATES_CANONICAL_PLACEHOLDER` + - Must reference existing ActivityDefinition + - Error: `FHIR_TASK_UNKNOWN_INSTANTIATES_CANONICAL` ##### Fixed Elements - **Status Validation**: - - `status` must be present - - Error: `FHIR_TASK_MISSING_STATUS` - - Must be `"draft"` for template Task instances - - Error: `FHIR_TASK_STATUS_NOT_DRAFT` - - Must be a valid TaskStatus value - - Error: `FHIR_TASK_UNKNOWN_STATUS` + - `status` must be present + - Error: `FHIR_TASK_MISSING_STATUS` + - Must be `"draft"` for template Task instances + - Error: `FHIR_TASK_STATUS_NOT_DRAFT` + - Must be a valid TaskStatus value + - Error: `FHIR_TASK_UNKNOWN_STATUS` - **Intent Validation**: - - `intent` must be `"order"` - - Error: `FHIR_TASK_VALUE_IS_NOT_SET_AS_ORDER` + - `intent` must be `"order"` + - Error: `FHIR_TASK_VALUE_IS_NOT_SET_AS_ORDER` - **Requester Validation**: - - Requester must be present - - Error: `FHIR_TASK_MISSING_REQUESTER` - - `requester.identifier.system` must be `http://dsf.dev/sid/organization-identifier` - - Error: `FHIR_TASK_INVALID_REQUESTER` - - `requester.identifier.value` must be `#{organization}` (development) - - Error: `FHIR_TASK_REQUESTER_ORGANIZATION_NO_PLACEHOLDER` - - Error: `FHIR_TASK_REQUESTER_ID_NO_PLACEHOLDER` - - Error: `FHIR_TASK_REQUESTER_ID_NOT_EXIST` + - Requester must be present + - Error: `FHIR_TASK_MISSING_REQUESTER` + - `requester.identifier.system` must be `http://dsf.dev/sid/organization-identifier` + - Error: `FHIR_TASK_INVALID_REQUESTER` + - `requester.identifier.value` must be `#{organization}` (development) + - Error: `FHIR_TASK_REQUESTER_ORGANIZATION_NO_PLACEHOLDER` + - Error: `FHIR_TASK_REQUESTER_ID_NO_PLACEHOLDER` + - Error: `FHIR_TASK_REQUESTER_ID_NOT_EXIST` - **Recipient Validation**: - - Recipient must be present - - Error: `FHIR_TASK_MISSING_RECIPIENT` - - `restriction.recipient.identifier.system` must be `http://dsf.dev/sid/organization-identifier` - - Error: `FHIR_TASK_INVALID_RECIPIENT` - - `restriction.recipient.identifier.value` must be `#{organization}` (development) - - Error: `FHIR_TASK_RECIPIENT_ORGANIZATION_NO_PLACEHOLDER` - - Error: `FHIR_TASK_RECIPIENT_ID_NO_PLACEHOLDER` - - Error: `FHIR_TASK_RECIPIENT_ID_NOT_EXIST` + - Recipient must be present + - Error: `FHIR_TASK_MISSING_RECIPIENT` + - `restriction.recipient.identifier.system` must be `http://dsf.dev/sid/organization-identifier` + - Error: `FHIR_TASK_INVALID_RECIPIENT` + - `restriction.recipient.identifier.value` must be `#{organization}` (development) + - Error: `FHIR_TASK_RECIPIENT_ORGANIZATION_NO_PLACEHOLDER` + - Error: `FHIR_TASK_RECIPIENT_ID_NO_PLACEHOLDER` + - Error: `FHIR_TASK_RECIPIENT_ID_NOT_EXIST` ##### Development Placeholders - **Date Placeholder**: - - `authoredOn` must contain `#{date}` - - Error: `FHIR_TASK_DATE_NO_PLACEHOLDER` + - `authoredOn` must contain `#{date}` + - Error: `FHIR_TASK_DATE_NO_PLACEHOLDER` ##### Task Identifier Validation - **System Validation**: - - Task identifiers must have a valid system element - - Expected system: `http://dsf.dev/sid/task-identifier` - - Error: `FHIR_TASK_IDENTIFIER_MISSING_SYSTEM` (when system is missing or empty) - - Error: `FHIR_TASK_IDENTIFIER_INVALID_SYSTEM` (when system is set but incorrect) - - Success: When the system is correctly set to `http://dsf.dev/sid/task-identifier` + - Task identifiers must have a valid system element + - Expected system: `http://dsf.dev/sid/task-identifier` + - Error: `FHIR_TASK_IDENTIFIER_MISSING_SYSTEM` (when system is missing or empty) + - Error: `FHIR_TASK_IDENTIFIER_INVALID_SYSTEM` (when system is set but incorrect) + - Success: When the system is correctly set to `http://dsf.dev/sid/task-identifier` - **Value Format Validation**: - - Task identifiers with system `http://dsf.dev/sid/task-identifier` must follow a specific format - - Format: `{process-url}/{process-version}/{task-example-name}` - - Example: `http://test.org/bpe/Process/someProcessName/1.0/someExampleName` - - Error: `FHIR_TASK_IDENTIFIER_INVALID_FORMAT` - - Success: When the identifier format is valid + - Task identifiers with system `http://dsf.dev/sid/task-identifier` must follow a specific format + - Format: `{process-url}/{process-version}/{task-example-name}` + - Example: `http://test.org/bpe/Process/someProcessName/1.0/someExampleName` + - Error: `FHIR_TASK_IDENTIFIER_INVALID_FORMAT` + - Success: When the identifier format is valid - **Pattern Definition**: ```regex @@ -604,65 +569,65 @@ Task resources are validated against the DSF Task base profile (`http://dsf.dev/ The pattern accepts both actual version numbers (e.g., `1.0`) and placeholders (e.g., `#{version}`) for development-time validation. - **Valid Examples**: - - ✅ System: `http://dsf.dev/sid/task-identifier` - - ✅ Value: `http://test.org/bpe/Process/someProcessName/1.0/someExampleName` (with actual version) - - ✅ Value: `http://test.org/bpe/Process/someProcessName/#{version}/someExampleName` (with placeholder) - - ✅ Value: `https://dsf.dev/bpe/Process/myProcess/2.5/startTask` - - ✅ Value: `http://medizininformatik-initiative.de/bpe/Process/coordinateDataSharing/#{version}/coordinateDataSharing` + - ✅ System: `http://dsf.dev/sid/task-identifier` + - ✅ Value: `http://test.org/bpe/Process/someProcessName/1.0/someExampleName` (with actual version) + - ✅ Value: `http://test.org/bpe/Process/someProcessName/#{version}/someExampleName` (with placeholder) + - ✅ Value: `https://dsf.dev/bpe/Process/myProcess/2.5/startTask` + - ✅ Value: `http://medizininformatik-initiative.de/bpe/Process/coordinateDataSharing/#{version}/coordinateDataSharing` - **Invalid Examples**: - - ❌ System missing or empty - - ❌ System: `http://wrong.system/identifier` (wrong system URL) - - ❌ Value: `http://test.org/someProcessName/1.0/taskName` (missing `/bpe/Process/` segment) - - ❌ Value: `http://test.org/bpe/Process/myProcess/1/taskName` (version must be in `X.Y` format, e.g. `1.0`) - - ❌ Empty or blank identifier value + - ❌ System missing or empty + - ❌ System: `http://wrong.system/identifier` (wrong system URL) + - ❌ Value: `http://test.org/someProcessName/1.0/taskName` (missing `/bpe/Process/` segment) + - ❌ Value: `http://test.org/bpe/Process/myProcess/1/taskName` (version must be in `X.Y` format, e.g. `1.0`) + - ❌ Empty or blank identifier value - **DSF Framework Reference**: - - Based on the DSF NamingSystem definition: `http://dsf.dev/sid/task-identifier` - - See: [DSF Framework Repository](https://github.com/datasharingframework/dsf) + - Based on the DSF NamingSystem definition: `http://dsf.dev/sid/task-identifier` + - See: [DSF Framework Repository](https://github.com/datasharingframework/dsf) ##### Task.input Validation - **Input Presence**: - - `Task.input` must not be empty - - Error: `FHIR_TASK_MISSING_INPUT` + - `Task.input` must not be empty + - Error: `FHIR_TASK_MISSING_INPUT` - **Structural Validation**: - - Each input must have `type.coding.system` and `type.coding.code` - - Error: `FHIR_TASK_INPUT_REQUIRED_CODING_SYSTEM_AND_CODING_CODE` - - Each input must have a `value[x]` element - - Error: `FHIR_TASK_INPUT_MISSING_VALUE` + - Each input must have `type.coding.system` and `type.coding.code` + - Error: `FHIR_TASK_INPUT_REQUIRED_CODING_SYSTEM_AND_CODING_CODE` + - Each input must have a `value[x]` element + - Error: `FHIR_TASK_INPUT_MISSING_VALUE` - **Duplicate Detection**: - - No two inputs may share the same `system#code` combination - - Error: `FHIR_TASK_INPUT_DUPLICATE_SLICE` + - No two inputs may share the same `system#code` combination + - Error: `FHIR_TASK_INPUT_DUPLICATE_SLICE` - **BPMN Slice Validation**: - - `message-name` slice: Required (min=1, max=1) - - Error: `FHIR_TASK_REQUIRED_INPUT_WITH_CODE_MESSAGE_NAME` - - `business-key` slice: - - Required when status is "in-progress", "completed", or "failed" - - Error: `FHIR_TASK_STATUS_REQUIRED_INPUT_BUSINESS_KEY` - - Must be absent when status is "draft" - - Error: `FHIR_TASK_BUSINESS_KEY_EXISTS` - - Business key validation may be skipped in certain conditions - - Warning: `FHIR_TASK_BUSINESS_KEY_CHECK_IS_SKIPPED` - - `correlation-key` slice: - - Validated against StructureDefinition cardinality - - Error: `FHIR_TASK_CORRELATION_EXISTS` - - Error: `FHIR_TASK_CORRELATION_MISSING_BUT_REQUIRED` + - `message-name` slice: Required (min=1, max=1) + - Error: `FHIR_TASK_REQUIRED_INPUT_WITH_CODE_MESSAGE_NAME` + - `business-key` slice: + - Required when status is "in-progress", "completed", or "failed" + - Error: `FHIR_TASK_STATUS_REQUIRED_INPUT_BUSINESS_KEY` + - Must be absent when status is "draft" + - Error: `FHIR_TASK_BUSINESS_KEY_EXISTS` + - Business key validation may be skipped in certain conditions + - Warning: `FHIR_TASK_BUSINESS_KEY_CHECK_IS_SKIPPED` + - `correlation-key` slice: + - Validated against StructureDefinition cardinality + - Error: `FHIR_TASK_CORRELATION_EXISTS` + - Error: `FHIR_TASK_CORRELATION_MISSING_BUT_REQUIRED` - **Cardinality Validation**: - - Total input count validated against base cardinality - - Error: `FHIR_TASK_INPUT_INSTANCE_COUNT_BELOW_MIN` - - Error: `FHIR_TASK_INPUT_INSTANCE_COUNT_EXCEEDS_MAX` - - Slice occurrence counts validated against slice-specific cardinality - - Error: `FHIR_TASK_INPUT_SLICE_COUNT_BELOW_SLICE_MIN` - - Error: `FHIR_TASK_INPUT_SLICE_COUNT_EXCEEDS_SLICE_MAX` + - Total input count validated against base cardinality + - Error: `FHIR_TASK_INPUT_INSTANCE_COUNT_BELOW_MIN` + - Error: `FHIR_TASK_INPUT_INSTANCE_COUNT_EXCEEDS_MAX` + - Slice occurrence counts validated against slice-specific cardinality + - Error: `FHIR_TASK_INPUT_SLICE_COUNT_BELOW_SLICE_MIN` + - Error: `FHIR_TASK_INPUT_SLICE_COUNT_EXCEEDS_SLICE_MAX` - - **Terminology Validation**: - - Generic coding validation (outside `Task.input.type.coding`) checks code/system pairs against known DSF CodeSystems - - Error: `FHIR_TASK_UNKNOWN_CODE` + - **Terminology Validation**: + - Generic coding validation (outside `Task.input.type.coding`) checks code/system pairs against known DSF CodeSystems + - Error: `FHIR_TASK_UNKNOWN_CODE` - **Task.input.type.coding Terminology Validation (binding-driven)**: - Validation for `Task.input.type.coding` is performed in three strict, ordered checks: @@ -713,58 +678,58 @@ StructureDefinition resources are validated against DSF-specific constraints. ##### Metadata Validation - **Read Access Tag**: - - Must contain valid read-access tag - - Error: `STRUCTURE_DEFINITION_READ_ACCESS_TAG_MISSING` + - Must contain valid read-access tag + - Error: `STRUCTURE_DEFINITION_READ_ACCESS_TAG_MISSING` - **URL Validation**: - - `url` must be present and non-empty - - Error: `STRUCTURE_DEFINITION_URL_MISSING` + - `url` must be present and non-empty + - Error: `STRUCTURE_DEFINITION_URL_MISSING` - **Status Validation**: - - `status` must be `"unknown"` (DSF convention) - - Error: `STRUCTURE_DEFINITION_INVALID_STATUS` + - `status` must be `"unknown"` (DSF convention) + - Error: `STRUCTURE_DEFINITION_INVALID_STATUS` ##### Placeholder Validation - **Version Placeholder**: - - `version` must contain exactly `#{version}` - - Error: `STRUCTURE_DEFINITION_VERSION_NO_PLACEHOLDER` + - `version` must contain exactly `#{version}` + - Error: `STRUCTURE_DEFINITION_VERSION_NO_PLACEHOLDER` - **Date Placeholder**: - - `date` must contain exactly `#{date}` - - Error: `STRUCTURE_DEFINITION_DATE_NO_PLACEHOLDER` + - `date` must contain exactly `#{date}` + - Error: `STRUCTURE_DEFINITION_DATE_NO_PLACEHOLDER` ##### Structure Validation - **Differential**: - - `differential` element must exist - - Error: `STRUCTURE_DEFINITION_DIFFERENTIAL_MISSING` + - `differential` element must exist + - Error: `STRUCTURE_DEFINITION_DIFFERENTIAL_MISSING` - **Snapshot**: - - `snapshot` element should not be present (warning) - - Error: `STRUCTURE_DEFINITION_SNAPSHOT_PRESENT` + - `snapshot` element should not be present + - Warning: `STRUCTURE_DEFINITION_SNAPSHOT_PRESENT` - **Element IDs**: - - Every `element` must have an `@id` attribute - - Error: `STRUCTURE_DEFINITION_ELEMENT_ID_MISSING` - - Element IDs must be unique - - Error: `STRUCTURE_DEFINITION_ELEMENT_ID_DUPLICATE` + - Every `element` must have an `@id` attribute + - Error: `STRUCTURE_DEFINITION_ELEMENT_ID_MISSING` + - Element IDs must be unique + - Error: `STRUCTURE_DEFINITION_ELEMENT_ID_DUPLICATE` ##### Slice Cardinality Validation According to FHIR profiling specification §5.1.0.14: -- **SHOULD Rule**: - - Sum of all slice minimum cardinalities should be ≤ base element's minimum - - Error: `STRUCTURE_DEFINITION_SLICE_MIN_SUM_ABOVE_BASE_MIN` +- **SHOULD Rule** (FHIR Profiling §5.1.0.14; reported as Error by the linter): + - Sum of all slice minimum cardinalities should be ≤ base element's minimum + - Error: `STRUCTURE_DEFINITION_SLICE_MIN_SUM_ABOVE_BASE_MIN` - **MUST Rule (Min Sum)**: - - Sum of all slice minimum cardinalities must not exceed base element's maximum - - Error: `STRUCTURE_DEFINITION_SLICE_MIN_SUM_EXCEEDS_MAX` + - Sum of all slice minimum cardinalities must not exceed base element's maximum + - Error: `STRUCTURE_DEFINITION_SLICE_MIN_SUM_EXCEEDS_MAX` - **MUST Rule (Slice Max)**: - - No individual slice's maximum cardinality may exceed base element's maximum - - Error: `STRUCTURE_DEFINITION_SLICE_MAX_TOO_HIGH` + - No individual slice's maximum cardinality may exceed base element's maximum + - Error: `STRUCTURE_DEFINITION_SLICE_MAX_TOO_HIGH` ##### Binding and Fixed Coding Validation - **`binding.valueSet` Reference Validation**: @@ -791,81 +756,81 @@ ValueSet resources are validated against the DSF ValueSet base profile. ##### Metadata Validation - **Read Access Tags**: - - Must contain at least one read-access tag (ALL or LOCAL) - - Error: `FHIR_VALUE_SET_MISSING_READ_ACCESS_TAG_ALL_OR_LOCAL` - - Organization role codes must be valid - - Error: `FHIR_VALUE_SET_ORGANIZATION_ROLE_MISSING_VALID_CODE_VALUE` + - Must contain at least one read-access tag (ALL or LOCAL) + - Error: `FHIR_VALUE_SET_MISSING_READ_ACCESS_TAG_ALL_OR_LOCAL` + - Organization role codes must be valid + - Error: `FHIR_VALUE_SET_ORGANIZATION_ROLE_MISSING_VALID_CODE_VALUE` - **Required Elements**: - - `url` must be present - - Error: `FHIR_VALUE_SET_MISSING_URL` - - `name` must be present - - Error: `FHIR_VALUE_SET_MISSING_NAME` - - `title` must be present - - Error: `FHIR_VALUE_SET_MISSING_TITLE` - - `publisher` must be present - - Error: `FHIR_VALUE_SET_MISSING_PUBLISHER` - - `description` must be present - - Error: `FHIR_VALUE_SET_MISSING_DESCRIPTION` + - `url` must be present + - Error: `FHIR_VALUE_SET_MISSING_URL` + - `name` must be present + - Error: `FHIR_VALUE_SET_MISSING_NAME` + - `title` must be present + - Error: `FHIR_VALUE_SET_MISSING_TITLE` + - `publisher` must be present + - Error: `FHIR_VALUE_SET_MISSING_PUBLISHER` + - `description` must be present + - Error: `FHIR_VALUE_SET_MISSING_DESCRIPTION` ##### Placeholder Validation - **Version Placeholder**: - - `version` must be `#{version}` - - Error: `FHIR_VALUE_SET_VERSION_NO_PLACEHOLDER` + - `version` must be `#{version}` + - Error: `FHIR_VALUE_SET_VERSION_NO_PLACEHOLDER` - **Date Placeholder**: - - `date` must be `#{date}` - - Error: `FHIR_VALUE_SET_DATE_NO_PLACEHOLDER` + - `date` must be `#{date}` + - Error: `FHIR_VALUE_SET_DATE_NO_PLACEHOLDER` - **Include Version Placeholder**: - - `compose.include.version` must be `#{version}` - - Error: `FHIR_VALUE_SET_INCLUDE_VERSION_NO_PLACEHOLDER` + - `compose.include.version` must be `#{version}` + - Error: `FHIR_VALUE_SET_INCLUDE_VERSION_NO_PLACEHOLDER` ##### Compose Structure Validation - **Include Elements**: - - At least one `compose.include` required - - Error: `FHIR_VALUE_SET_MISSING_COMPOSE_INCLUDE` - - Each include must have a `system` attribute - - Error: `FHIR_VALUE_SET_INCLUDE_MISSING_SYSTEM` + - At least one `compose.include` required + - Error: `FHIR_VALUE_SET_MISSING_COMPOSE_INCLUDE` + - Each include must have a `system` attribute + - Error: `FHIR_VALUE_SET_INCLUDE_MISSING_SYSTEM` - **Concept Validation**: - - Concept codes must be non-blank - - Error: `FHIR_VALUE_SET_CONCEPT_MISSING_CODE` - - Duplicate codes detected - - Error: `FHIR_VALUE_SET_DUPLICATE_CONCEPT_CODE` + - Concept codes must be non-blank + - Error: `FHIR_VALUE_SET_CONCEPT_MISSING_CODE` + - Duplicate codes detected + - Error: `FHIR_VALUE_SET_DUPLICATE_CONCEPT_CODE` ##### Terminology Compliance - **CodeSystem Validation**: - - CodeSystem URLs validated against DSF terminology cache - - Warn: `FHIR_VALUE_SET_UNKNOWN_CODE` - - Code exists but in different CodeSystem - - Error: `FHIR_VALUE_SET_FALSE_URL_REFERENCED` + - CodeSystem URLs validated against DSF terminology cache + - Warning: `FHIR_VALUE_SET_UNKNOWN_CODE` (unknown code or missing system/code on include) + - Code exists but in different CodeSystem + - Error: `FHIR_VALUE_SET_FALSE_URL_REFERENCED` #### ActivityDefinition Resources ##### Profile Validation - **Profile**: - - Must have valid profile - - Error: `ACTIVITY_DEFINITION_MISSING_PROFILE` - - Profile must not have version number - - Error: `ACTIVITY_DEFINITION_PROFILE_NO_PLACEHOLDER` + - Must have valid profile + - Error: `ACTIVITY_DEFINITION_MISSING_PROFILE` + - Profile must not have version number + - Error: `ACTIVITY_DEFINITION_PROFILE_NO_PLACEHOLDER` ##### URL Validation - **URL Presence**: - - URL must be present and non-empty - - Error: `INVALID_FHIR_URL` + - URL must be present and non-empty + - Error: `INVALID_FHIR_URL` - **URL Pattern Validation**: - - ActivityDefinition URL must follow a specific pattern - - Format: `http[s]://domain/bpe/Process/processName` - - Example: `http://dsf.dev/bpe/Process/test` - - Error: `ACTIVITY_DEFINITION_INVALID_URL_PATTERN` - - Success: When the URL pattern is valid + - ActivityDefinition URL must follow a specific pattern + - Format: `http[s]://domain/bpe/Process/processName` + - Example: `http://dsf.dev/bpe/Process/test` + - Error: `ACTIVITY_DEFINITION_INVALID_URL_PATTERN` + - Success: When the URL pattern is valid - **Pattern Definition**: ```regex @@ -873,227 +838,227 @@ ValueSet resources are validated against the DSF ValueSet base profile. ``` - **Valid Examples**: - - ✅ `http://dsf.dev/bpe/Process/test` - - ✅ `https://example.org/bpe/Process/my-process` - - ✅ `http://test.example.com/bpe/Process/process123` + - ✅ `http://dsf.dev/bpe/Process/test` + - ✅ `https://example.org/bpe/Process/my-process` + - ✅ `http://test.example.com/bpe/Process/process123` - **Invalid Examples**: - - ❌ `http://dsf.dev/Process/test` (missing `/bpe/`) - - ❌ `http://dsf.dev/bpe/Process/test_invalid` (underscore not allowed in processName) - - ❌ `http://dsf.dev/bpe/Process/` (missing processName) - - ❌ `ftp://dsf.dev/bpe/Process/test` (only http/https allowed) + - ❌ `http://dsf.dev/Process/test` (missing `/bpe/`) + - ❌ `http://dsf.dev/bpe/Process/test_invalid` (underscore not allowed in processName) + - ❌ `http://dsf.dev/bpe/Process/` (missing processName) + - ❌ `ftp://dsf.dev/bpe/Process/test` (only http/https allowed) - **DSF Framework Reference**: - - Based on the DSF Framework requirement defined in: - - `dsf-bpe/dsf-bpe-process-api/src/main/java/dev/dsf/bpe/api/plugin/AbstractProcessPlugin.java` - - See: [DSF Framework Repository](https://github.com/datasharingframework/dsf) + - Based on the DSF Framework requirement defined in: + - `dsf-bpe/dsf-bpe-process-api/src/main/java/dev/dsf/bpe/api/plugin/AbstractProcessPlugin.java` + - See: [DSF Framework Repository](https://github.com/datasharingframework/dsf) ##### Status Validation - **Status**: - - Status must be valid - - Error: `INVALID_FHIR_STATUS` + - Status must be valid + - Error: `INVALID_FHIR_STATUS` ##### Authorization Validation - **Requester**: - - Requester entry must be present - - Error: `ACTIVITY_DEFINITION_ENTRY_MISSING_REQUESTER` - - Requester entry must be valid - - Error: `ACTIVITY_DEFINITION_ENTRY_INVALID_REQUESTER` + - Requester entry must be present + - Error: `ACTIVITY_DEFINITION_ENTRY_MISSING_REQUESTER` + - Requester entry must be valid + - Error: `ACTIVITY_DEFINITION_ENTRY_INVALID_REQUESTER` - **Recipient**: - - Recipient entry must be present - - Error: `ACTIVITY_DEFINITION_ENTRY_MISSING_RECIPIENT` - - Recipient entry must be valid - - Error: `ACTIVITY_DEFINITION_ENTRY_INVALID_RECIPIENT` + - Recipient entry must be present + - Error: `ACTIVITY_DEFINITION_ENTRY_MISSING_RECIPIENT` + - Recipient entry must be valid + - Error: `ACTIVITY_DEFINITION_ENTRY_INVALID_RECIPIENT` #### CodeSystem Resources ##### Metadata Validation - **Read Access Tag**: - - Must have read access tag - - Error: `MISSING_READ_ACCESS_TAG` + - Must have read access tag + - Error: `MISSING_READ_ACCESS_TAG` - **Required Elements**: - - Required elements must be present - - Error: `CODE_SYSTEM_MISSING_ELEMENT` + - Required elements must be present + - Error: `CODE_SYSTEM_MISSING_ELEMENT` ##### URL Validation - **URL Format**: - - URL must be valid - - Error: `INVALID_FHIR_URL` + - URL must be valid + - Error: `INVALID_FHIR_URL` ##### Status Validation - **Status**: - - Status must be valid - - Error: `CODE_SYSTEM_INVALID_STATUS` + - Status must be valid + - Error: `CODE_SYSTEM_INVALID_STATUS` ##### Concept Validation - **Concepts**: - - Must have at least one concept - - Error: `CODE_SYSTEM_MISSING_CONCEPT` - - Concepts must have code - - Error: `CODE_SYSTEM_CONCEPT_MISSING_CODE` - - Concepts must have display - - Error: `CODE_SYSTEM_CONCEPT_MISSING_DISPLAY` - - Duplicate codes detected - - Error: `CODE_SYSTEM_DUPLICATE_CODE` + - Must have at least one concept + - Error: `CODE_SYSTEM_MISSING_CONCEPT` + - Concepts must have code + - Error: `CODE_SYSTEM_CONCEPT_MISSING_CODE` + - Concepts must have display + - Error: `CODE_SYSTEM_CONCEPT_MISSING_DISPLAY` + - Duplicate codes detected + - Error: `CODE_SYSTEM_DUPLICATE_CODE` ##### Placeholder Validation - **Version Placeholder**: - - Version must be `#{version}` - - Error: `CODE_SYSTEM_VERSION_NO_PLACEHOLDER` + - Version must be `#{version}` + - Error: `CODE_SYSTEM_VERSION_NO_PLACEHOLDER` - **Date Placeholder**: - - Date must be `#{date}` - - Error: `CODE_SYSTEM_DATE_NO_PLACEHOLDER` + - Date must be `#{date}` + - Error: `CODE_SYSTEM_DATE_NO_PLACEHOLDER` #### Questionnaire Resources ##### Metadata Validation - **Meta Profile**: - - Must have meta profile - - Error: `QUESTIONNAIRE_MISSING_META_PROFILE` - - Meta profile must be valid - - Error: `QUESTIONNAIRE_INVALID_META_PROFILE` + - Should have meta profile + - Warning: `QUESTIONNAIRE_MISSING_META_PROFILE` + - Meta profile must be valid + - Warning: `QUESTIONNAIRE_INVALID_META_PROFILE` - **Read Access Tag**: - - Must have read access tag - - Error: `QUESTIONNAIRE_MISSING_READ_ACCESS_TAG` + - Must have read access tag + - Error: `QUESTIONNAIRE_MISSING_READ_ACCESS_TAG` ##### Status Validation - **Status**: - - Status must be valid - - Error: `QUESTIONNAIRE_INVALID_STATUS` + - Status must be valid + - Error: `QUESTIONNAIRE_INVALID_STATUS` ##### Item Validation - **Items**: - - Must have at least one item - - Error: `QUESTIONNAIRE_MISSING_ITEM` - - Items must have linkId - - Error: `QUESTIONNAIRE_ITEM_MISSING_ATTRIBUTES_LINK_ID` - - Items must have text - - Error: `QUESTIONNAIRE_ITEM_MISSING_ATTRIBUTES_TEXT` - - Items must have type - - Error: `QUESTIONNAIRE_ITEM_MISSING_ATTRIBUTES_TYPE` - - Link IDs must be unique - - Error: `QUESTIONNAIRE_DUPLICATE_LINK_ID` - - Unusual link IDs detected - - Error: `QUESTIONNAIRE_UNUSUAL_LINK_ID` + - Must have at least one item + - Error: `QUESTIONNAIRE_MISSING_ITEM` + - Items must have linkId + - Error: `QUESTIONNAIRE_ITEM_MISSING_ATTRIBUTES_LINK_ID` + - Items should have text + - Info: `QUESTIONNAIRE_ITEM_MISSING_ATTRIBUTES_TEXT` + - Items must have type + - Error: `QUESTIONNAIRE_ITEM_MISSING_ATTRIBUTES_TYPE` + - Link IDs must be unique + - Error: `QUESTIONNAIRE_DUPLICATE_LINK_ID` + - Unusual link IDs detected + - Warning: `QUESTIONNAIRE_UNUSUAL_LINK_ID` ##### Mandatory Item Validation - **Required Items**: - - Mandatory items must be required - - Error: `QUESTIONNAIRE_MANDATORY_ITEM_NOT_REQUIRED` - - Mandatory items must have valid type - - Error: `QUESTIONNAIRE_MANDATORY_ITEM_INVALID_TYPE` + - Mandatory items must be required + - Error: `QUESTIONNAIRE_MANDATORY_ITEM_NOT_REQUIRED` + - Mandatory items must have valid type + - Error: `QUESTIONNAIRE_MANDATORY_ITEM_INVALID_TYPE` ##### Placeholder Validation - **Version Placeholder**: - - Version must be `#{version}` - - Error: `QUESTIONNAIRE_VERSION_NO_PLACEHOLDER` + - Version must be `#{version}` + - Error: `QUESTIONNAIRE_VERSION_NO_PLACEHOLDER` - **Date Placeholder**: - - Date must be `#{date}` - - Error: `QUESTIONNAIRE_DATE_NO_PLACEHOLDER` + - Date must be `#{date}` + - Error: `QUESTIONNAIRE_DATE_NO_PLACEHOLDER` #### Common FHIR Validations ##### Access Tag Validation - **Read Access Tag**: - - Must have read access tag - - Error: `MISSING_FHIR_ACCESS_TAG` - - Access tag must be valid - - Error: `INVALID_FHIR_ACCESS_TAG` + - Must have read access tag + - Error: `MISSING_FHIR_ACCESS_TAG` + - Access tag must be valid + - Error: `INVALID_FHIR_ACCESS_TAG` ##### Kind Validation - **Kind**: - - Kind must be present - - Error: `INVALID_FHIR_KIND` - - Kind must be "Task" for Task resources - - Error: `FHIR_KIND_NOT_SET_AS_TASK` + - Kind must be present + - Error: `INVALID_FHIR_KIND` + - Kind must be "Task" for Task resources + - Error: `FHIR_KIND_NOT_SET_AS_TASK` ##### Status Validation - **Status**: - - Status must be "unknown" (DSF convention) - - Error: `FHIR_STATUS_IS_NOT_SET_AS_UNKNOWN` + - Status must be "unknown" (DSF convention) + - Error: `FHIR_STATUS_IS_NOT_SET_AS_UNKNOWN` ##### Extension Validation - **Process Authorization Extension**: - - Must have process authorization extension - - Error: `NO_EXTENSION_PROCESS_AUTHORIZATION_FOUND` + - Must have process authorization extension + - Error: `NO_EXTENSION_PROCESS_AUTHORIZATION_FOUND` ### Plugin Configuration Validation #### ServiceLoader Registration - **Registration File**: - - **V1 API**: Must be registered in `META-INF/services/dev.dsf.bpe.v1.ProcessPluginDefinition` - - **V2 API**: Must be registered in `META-INF/services/dev.dsf.bpe.v2.ProcessPluginDefinition` - - Error: `PLUGIN_DEFINITION_MISSING_SERVICE_LOADER_REGISTRATION` - - Plugin class must be loadable - - Error: `PLUGIN_DEFINITION_PROCESS_PLUGIN_RESOURCE_NOT_LOADED` + - **V1 API**: Must be registered in `META-INF/services/dev.dsf.bpe.v1.ProcessPluginDefinition` + - **V2 API**: Must be registered in `META-INF/services/dev.dsf.bpe.v2.ProcessPluginDefinition` + - Error: `PLUGIN_DEFINITION_MISSING_SERVICE_LOADER_REGISTRATION` + - Plugin class must be loadable + - Error: `PLUGIN_DEFINITION_PROCESS_PLUGIN_RESOURCE_NOT_LOADED` #### Resource References - **BPMN File References**: - - BPMN files referenced in plugin must exist - - Error: `PLUGIN_DEFINITION_BPMN_FILE_NOT_FOUND` - - BPMN files must be in expected root - - Error: `PLUGIN_DEFINITION_BPMN_FILE_OUTSIDE_ROOT` - - BPMN files must be parsable - - Error: `PLUGIN_DEFINITION_UNPARSABLE_BPMN_RESOURCE` + - BPMN files referenced in plugin must exist + - Error: `PLUGIN_DEFINITION_BPMN_FILE_NOT_FOUND` + - BPMN files must be in expected root + - Error: `PLUGIN_DEFINITION_BPMN_FILE_OUTSIDE_ROOT` + - BPMN files must be parsable + - Error: `PLUGIN_DEFINITION_UNPARSABLE_BPMN_RESOURCE` - **FHIR File References**: - - FHIR resources referenced in BPMN must exist - - Error: `PLUGIN_DEFINITION_FHIR_RESOURCE_NOT_FOUND` - - FHIR resources must be in expected root - - Error: `PLUGIN_DEFINITION_FHIR_FILE_OUTSIDE_ROOT` - - FHIR resources must be parsable - - Error: `PLUGIN_DEFINITION_UNPARSABLE_FHIR_RESOURCE` + - FHIR resources referenced in BPMN must exist + - Error: `PLUGIN_DEFINITION_FHIR_RESOURCE_NOT_FOUND` + - FHIR resources must be in expected root + - Error: `PLUGIN_DEFINITION_FHIR_FILE_OUTSIDE_ROOT` + - FHIR resources must be parsable + - Error: `PLUGIN_DEFINITION_UNPARSABLE_FHIR_RESOURCE` #### Resource Presence - **BPMN Processes**: - - At least one BPMN process must be defined - - Error: `PLUGIN_DEFINITION_NO_PROCESS_MODEL_DEFINED` + - At least one BPMN process must be defined + - Error: `PLUGIN_DEFINITION_NO_PROCESS_MODEL_DEFINED` - **FHIR Resources**: - - At least one FHIR resource must be defined - - Error: `PLUGIN_DEFINITION_NO_FHIR_RESOURCES_DEFINED` + - At least one FHIR resource must be defined + - Error: `PLUGIN_DEFINITION_NO_FHIR_RESOURCES_DEFINED` #### Version Validation ##### Resource Version Validation - **Version Pattern Requirement**: - - Plugin version must follow the pattern: `d.d.d.d` (e.g., `1.0.0.1`, `2.5.3.10`) - - Resource version is derived from the first two numbers (e.g., `1.0` from `1.0.0.1`) - - Error: `PLUGIN_DEFINITION_RESOURCE_VERSION_NULL` + - Plugin version must follow the pattern: `d.d.d.d` (e.g., `1.0.0.1`, `2.5.3.10`) + - Resource version is derived from the first two numbers (e.g., `1.0` from `1.0.0.1`) + - Error: `PLUGIN_DEFINITION_RESOURCE_VERSION_NULL` - **Valid Examples**: - - ✅ Version `1.0.0.1` → Resource Version `1.0` - - ✅ Version `2.5.3.10` → Resource Version `2.5` + - ✅ Version `1.0.0.1` → Resource Version `1.0` + - ✅ Version `2.5.3.10` → Resource Version `2.5` - **Invalid Examples**: - - ❌ Version `1.0.0` (missing fourth number) - - ❌ Version `1.0` (only two numbers) - - ❌ Version `invalid` (non-numeric) + - ❌ Version `1.0.0` (missing fourth number) + - ❌ Version `1.0` (only two numbers) + - ❌ Version `invalid` (non-numeric) - **Pattern Definition**: ```regex @@ -1101,113 +1066,102 @@ ValueSet resources are validated against the DSF ValueSet base profile. ``` - **DSF Framework Reference**: - - This validation is based on the DSF Framework requirement defined in: - - `dsf-bpe/dsf-bpe-process-api-v2/src/main/java/dev/dsf/bpe/v2/ProcessPluginDefinition.java` - - The `getResourceVersion()` method extracts the resource version from the plugin version + - This validation is based on the DSF Framework requirement defined in: + - `dsf-bpe/dsf-bpe-process-api-v2/src/main/java/dev/dsf/bpe/v2/ProcessPluginDefinition.java` + - The `getResourceVersion()` method extracts the resource version from the plugin version #### Spring Configuration Registration In the DSF runtime, the Camunda engine does not instantiate Java delegate or listener classes directly. Spring creates those instances via `@Bean` methods -declared in `@Configuration` classes. For those beans to be available to the -BPE at runtime, the corresponding `@Configuration` classes must be explicitly -returned by `ProcessPluginDefinition#getSpringConfigurations()`. Forgetting -to add a `@Bean` for a BPMN-referenced class typically surfaces as a -`BeanCreationException` or `ClassNotFoundException` only at deployment time. - -- **Every BPMN-referenced class must be provided as a `@Bean`**: - - The linter collects every `camunda:class` reference used by - `serviceTask`, `sendTask`, `messageEventDefinition`, - `camunda:executionListener` and `camunda:taskListener` elements in the - plugin's BPMN files (List 1). - - The linter calls `getSpringConfigurations()` to get the registered - `@Configuration` classes and inspects the return types of their - `@Bean` methods (List 2). - - For every class in List 1, the linter checks whether it is provided - as a `@Bean` (exact type or supertype) in any `@Configuration` from - List 2. - - If a BPMN-referenced class has **no matching `@Bean`** in any - registered configuration, this is reported as an error. - - Error: `PLUGIN_DEFINITION_SPRING_CONFIGURATION_MISSING` - - Success: `SUCCESS` when all BPMN delegate/listener references are - covered by a `@Bean` in a registered `@Configuration`, or when no - BPMN delegate/listener references exist. - -- **Code Example**: - ```java - @Override - public List> getSpringConfigurations() { - return List.of(DataSharingConfig.class, DataSharingVariablesConfig.class); - } - ``` - ```java - @Configuration - public class DataSharingConfig { - - // Every class referenced via camunda:class in the BPMN must have - // a corresponding @Bean here (or in another registered @Configuration). - @Bean - public SelectDicTargets selectDicTargets() { - return new SelectDicTargets(api); - } - - @Bean - public SelectDmsTarget selectDmsTarget() { - return new SelectDmsTarget(api); - } - } - ``` -#### Spring Bean Scope (`SpringConfigurationLinter`) - -In Camunda and the Data Sharing Framework (DSF), Spring beans that act as delegates, execution listeners, or task listeners should usually be configured with **prototype** scope (`SCOPE_PROTOTYPE`). If the `@Scope` annotation is omitted, Spring defaults to **singleton**. That can be acceptable for strictly stateless classes; as soon as someone adds mutable instance state, the risk of race conditions and hard-to-debug concurrency bugs rises sharply—often only visible under load. - -After a BPMN-referenced class is **covered** by a `@Bean` in a registered `@Configuration` (see [Spring Configuration Registration](#spring-configuration-registration)), the linter inspects the covering `@Bean` method for `@Scope` and the referenced implementation class for **mutable** instance fields (not `static`, not `final`). Emitted rules: - - - **Success** – `SPRING_BEAN_SCOPE_PROTOTYPE`: `@Scope` is **prototype** (e.g. `ConfigurableBeanFactory.SCOPE_PROTOTYPE` or `@Scope("prototype")`). No further scope items for that reference in this pass. - - **Error** – `SPRING_BEAN_SCOPE_MUTABLE_SINGLETON`: The bean is **effectively singleton** (missing `@Scope` *or* explicit non-prototype scope such as `singleton`) **and** the referenced class has **mutable** instance fields. Emitted **once** per reference before the following warnings. - - **Warning** – `SPRING_BEAN_SCOPE_MISSING`: The covering `@Bean` has **no** `@Scope` (Spring’s default is singleton, which is risky for Camunda hooks unless the implementation is provably stateless). - - **Warning** – `SPRING_BEAN_SCOPE_SINGLETON_EXPLICIT`: `@Scope` is **explicitly** set to a **non-prototype** value (typically `singleton`); the developer should verify that the delegate or listener is safe to share across process instances. +declared in `@Configuration` classes returned by +`ProcessPluginDefinition#getSpringConfigurations()`. A missing registration +typically surfaces only at deployment as `BeanCreationException` / +`ClassNotFoundException`. + +The linter (`SpringConfigurationLinter`) collects every `camunda:class` +reference from `serviceTask`, `sendTask`, message throw/end events, +`camunda:executionListener` and `camunda:taskListener` elements, then checks +coverage against the registered configurations. + +##### API V1 — `@Bean` per activity + +- Each BPMN-referenced class must be provided as a `@Bean` (exact type or + assignable supertype) in a registered `@Configuration`. +- Error: `PLUGIN_DEFINITION_SPRING_CONFIGURATION_MISSING` +- Success: `SUCCESS` when all references are covered (or none exist) + +```java +@Configuration +public class DataSharingConfig { + @Bean + @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) + public SelectDicTargets selectDicTargets() { + return new SelectDicTargets(api); + } +} +``` + +##### API V2 — `ActivityPrototypeBeanCreator` (preferred) + +API V2 may register activities via +`dev.dsf.bpe.v2.spring.ActivityPrototypeBeanCreator`, which creates prototype +beans from the `Class` literals passed to its constructor. That is the preferred +registration path for V2 activities. + +| Situation | Severity | Type | +|-----------|----------|------| +| Not in APBC and not a prototype `@Bean` | ERROR | `PLUGIN_DEFINITION_ACTIVITY_PROTOTYPE_BEAN_MISSING` | +| Registered only via APBC | SUCCESS | `SPRING_ACTIVITY_PROTOTYPE_BEAN_CREATOR` | +| Registered via APBC **and** as a dedicated `@Bean` | WARN | `SPRING_ACTIVITY_REGISTERED_TWICE` | +| Declared as `@Bean` but **not** passed to APBC | WARN | `SPRING_ACTIVITY_REGISTERED_AS_BEAN` | + +```java +@Configuration +public class PingPongConfig { + @Bean + public static ActivityPrototypeBeanCreator activityPrototypeBeanCreator() { + return new ActivityPrototypeBeanCreator( + SelectDicTargets.class, + SelectDmsTarget.class + ); + } +} +``` - **Why this matters:** The rule stays aligned with DSF wiring (only configurations from `getSpringConfigurations()`) and surfaces dangerous combinations—singleton or default-singleton scope plus mutable instance state—before they appear in production. - - **Example scenarios** - - *Missing `@Scope` → warning (and error if the delegate/listener class has mutable instance fields)* - - ```java - @Bean - // Missing @Scope annotation - public SetCorrelationKeyListener setCorrelationKeyListener() { - return new SetCorrelationKeyListener(api); - } - ``` +#### Spring Bean Scope (`SpringConfigurationLinter`) - *Explicit singleton → warning (and error if mutable instance fields exist)* - ```java - @Bean - @Scope(ConfigurableBeanFactory.SCOPE_SINGLETON) // or @Scope("singleton") - public SetCorrelationKeyListener setCorrelationKeyListener() { - return new SetCorrelationKeyListener(api); - } - ``` - *Prototype (recommended) → success* - ```java - @Bean - @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) // or @Scope("prototype") - public SetCorrelationKeyListener setCorrelationKeyListener() { - return new SetCorrelationKeyListener(api); - } - ``` +Delegates, execution listeners, and task listeners should usually use +**prototype** scope (`SCOPE_PROTOTYPE`). Omitting `@Scope` defaults Spring to +**singleton**, which is risky once mutable instance state is introduced. + +After a BPMN-referenced class is **covered**, the linter inspects scope (APBC +registrations are always treated as prototype) and mutable instance fields +(not `static`, not `final`): + +| Situation | Severity | Type | +|-----------|----------|------| +| `@Scope` is prototype | SUCCESS | `SPRING_BEAN_SCOPE_PROTOTYPE` | +| Effectively singleton **and** mutable fields | ERROR | `SPRING_BEAN_SCOPE_MUTABLE_SINGLETON` | +| No `@Scope` (Spring default singleton) | WARN | `SPRING_BEAN_SCOPE_MISSING` | +| Explicit non-prototype `@Scope` | WARN | `SPRING_BEAN_SCOPE_SINGLETON_EXPLICIT` | + +```java +@Bean +@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) // recommended +public SetCorrelationKeyListener setCorrelationKeyListener() { + return new SetCorrelationKeyListener(api); +} +``` #### Leftover Resource Detection -The linter performs project-level analysis to identify unreferenced resources: +Project-wide analysis: files under the resources root that are not referenced in any `ProcessPluginDefinition`. -- **Unreferenced BPMN Files**: - - BPMN files that are not referenced by any plugin - - Reported as warnings +| Resource | LintingType | Severity | Message (excerpt) | +|----------|-------------|----------|-------------------| +| BPMN | `PLUGIN_DEFINITION_PROCESS_PLUGIN_RESOURCE_NOT_LOADED` | WARN | *"BPMN file exists but is not referenced in ProcessPluginDefinition"* | +| FHIR | `PLUGIN_DEFINITION_PROCESS_PLUGIN_RESOURCE_NOT_LOADED` | WARN | *"FHIR file exists but is not referenced in ProcessPluginDefinition"* | -- **Unreferenced FHIR Resources**: - - FHIR resources that are not referenced by any BPMN process - - Reported as warnings +When all files are referenced: project-level `SUCCESS`. In multi-plugin projects, leftover findings are assigned to plugins (see `LeftoverResourceDetector`). -This analysis works uniformly for single-plugin and multi-plugin projects. \ No newline at end of file +Note: Unreferenced resources **within** a plugin (e.g. FHIR used only from BPMN) are covered by other rules (`PLUGIN_DEFINITION_FHIR_RESOURCE_NOT_FOUND`, FHIR references in BPMN) — not by leftover detection. \ No newline at end of file