init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Events/TestSetups/TestSetupsList.md

@@ -0,0 +1,80 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Events/TestSetups/TestSetupsList/CurrentTestIdChangedEvent.cs
+  - Common/DTS.CommonCore/Events/TestSetups/TestSetupsList/CurrentTestChangedEvent.cs
+  - Common/DTS.CommonCore/Events/TestSetups/TestSetupsList/TestSetupsListEditTestSetupEvent.cs
+  - Common/DTS.CommonCore/Events/TestSetups/TestSetupsList/TestSetupsListTestSetupSelectedEvent.cs
+generated_at: "2026-04-16T02:50:37.794496+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "0a7d14a1bfb658a4"
+---
+
+# TestSetupsList
+
+## Documentation: TestSetupsList Events Module
+
+### 1. Purpose  
+This module defines a set of Prism-based events used to coordinate state and user actions within the *Test Setups List* feature of the system. Specifically, it enables decoupled communication between UI components (e.g., a test list view and detail editors) regarding changes to the currently selected or edited test setup, as well as user-initiated actions like selecting or editing a test setup. All events are strongly typed subclasses of `CompositePresentationEvent<TPayload>` and carry string or string array payloads to identify test setups.
+
+---
+
+### 2. Public Interface  
+
+| Event Class | Payload Type | Behavior |
+|-------------|--------------|----------|
+| `CurrentTestIdChangedEvent` | `string` | Signals that the *ID* of the current test setup has changed. Payload is the new test setup ID (or `null` if none). |
+| `CurrentTestChangedEvent` | `string` | Signals that the *entire current test setup* (not just its ID) has changed. Payload is the test setup ID of the new current test setup (or `null` if none). |
+| `TestSetupsListEditTestSetupEvent` | `string` | Fires when the user requests to edit a specific test setup. Payload is the ID of the test setup to be edited. |
+| `TestSetupsListTestSetupSelectedEvent` | `string[]` | Fires when one or more test setups are selected (e.g., via UI). Payload is an array of test setup IDs representing the selected items. |
+
+> **Note**: All events inherit from `Microsoft.Practices.Prism.Events.CompositePresentationEvent<T>`, meaning they support subscription from multiple views/modules and are published on the UI thread by default (Prism behavior).
+
+---
+
+### 3. Invariants  
+
+- **Payload semantics**:  
+  - For events with `string` payload (`CurrentTestIdChangedEvent`, `CurrentTestChangedEvent`, `TestSetupsListEditTestSetupEvent`), the payload is expected to be a valid test setup ID (non-empty string) when indicating a real selection/edit. A `null` or empty string may indicate "no current test" or "clear selection", though this is not explicitly documented and must be inferred from usage.  
+  - For `TestSetupsListTestSetupSelectedEvent`, the payload is a non-null array of test setup IDs (though the array may be empty to indicate deselection).  
+
+- **Event ordering**:  
+  - No guaranteed ordering between event publication and handling. Subscribers must be prepared to handle events asynchronously.  
+  - `CurrentTestChangedEvent` *may* imply `CurrentTestIdChangedEvent` in typical usage, but this is **not enforced** by the event definitions themselves.  
+
+- **No validation**:  
+  - The events themselves perform no validation on payload contents (e.g., no check for existence or format of test setup IDs). Validation is the responsibility of subscribers.
+
+---
+
+### 4. Dependencies  
+
+- **Dependencies *of* this module**:  
+  - `Microsoft.Practices.Prism.Events` (Prism library, version not specified).  
+  - Namespace `DTS.Common.Events.TestSetups.TestSetupsList` (internal to the codebase).  
+
+- **Dependencies *on* this module**:  
+  - Any module/view responsible for managing the test setups list UI (e.g., a list view, editor dialog, or summary step) likely subscribes to or publishes these events.  
+  - Specifically, the *Summary step* is documented to publish `TestSetupsListTestSetupSelectedEvent` (see comment in `TestSetupsListTestSetupSelectedEvent.cs`).  
+  - Other modules (e.g., test setup detail view, edit dialog) likely subscribe to `TestSetupsListEditTestSetupEvent` or `CurrentTestChangedEvent`.
+
+---
+
+### 5. Gotchas  
+
+- **Naming inconsistency**:  
+  - The class `TestSetupsListTestSetupSelectedEvent` has a misleading summary comment: it incorrectly refers to `TTSImportSummaryImportEvent` in its `<summary>` tag. This appears to be a copy-paste error and may cause confusion during documentation review.  
+
+- **Ambiguous semantics of `CurrentTestIdChangedEvent` vs `CurrentTestChangedEvent`**:  
+  - The distinction between "ID changed" and "test changed" is not clarified in the source. In practice, if only the ID changes (e.g., due to renaming), does `CurrentTestChangedEvent` fire? The source does not specify. Subscribers should assume both events may fire independently and handle accordingly.  
+
+- **No payload validation or error signaling**:  
+  - Events carry no error or status metadata. If a subscriber cannot act on a payload (e.g., invalid ID), it must handle failure silently or via separate mechanisms (e.g., logging, exceptions, or additional events).  
+
+- **String-based IDs are fragile**:  
+  - Using `string` (and `string[]`) as the payload type offers no compile-time safety. Typos or ID mismatches (e.g., mixing internal vs. external IDs) could lead to runtime errors.  
+
+- **No deprecation or lifecycle guidance**:  
+  - No indication of whether these events are stable, deprecated, or subject to change. Subscribers should assume they are part of the stable public API unless otherwise documented elsewhere.  
+
+None identified beyond the above.