init

enriched-qwen3-coder-next/Common/DTS.Common.Import/Parsers.md

@@ -0,0 +1,69 @@
+---
+source_files:
+  - Common/DTS.Common.Import/Parsers/ParseVariantBase.cs
+  - Common/DTS.Common.Import/Parsers/DefaultParseImport.cs
+  - Common/DTS.Common.Import/Parsers/DTSXMLParseImport.cs
+generated_at: "2026-04-16T02:06:24.270866+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "6317dc1ace913c30"
+---
+
+# Parsers
+
+## Documentation: Import Parsing Module
+
+### 1. Purpose  
+This module provides foundational infrastructure and concrete implementations for parsing import files into a structured `ImportObject`. It defines an extensible parsing pipeline via the `IParseImport` interface, with base abstractions (`ParseVariantBase`) for variant-specific parsing logic and two concrete import processors: `DefaultParseImport` (generic, variant-driven parsing) and `DTSXMLParseImport` (XML-specific parsing with UI integration, cancellation support, and post-processing for DAS-linked hardware). The module serves as the core engine for transforming raw file inputs into domain objects used throughout the DTS import workflow.
+
+### 2. Public Interface  
+
+#### `ParseVariantBase` (abstract class)  
+- **`string FileName { get; set; }`**  
+  Gets or sets the name of the file being parsed by this variant. Set by the caller before `Parse` is invoked.  
+- **`abstract void Parse(ref ImportObject importObject)`**  
+  Parses the file (identified by `FileName`) and mutates the provided `ImportObject` by adding or updating its contents. Must be implemented by derived classes.
+
+#### `DefaultParseImport` (concrete class)  
+- **`DefaultParseImport(ImportObject importObject, IEnumerable<IParseVariant> parseVariants)`**  
+  Constructor. Initializes the parser with a target `ImportObject` and a sequence of `IParseVariant` implementations to apply.  
+- **`ImportObject Parse(IEnumerable<string> importFiles)`**  
+  Processes each file in `importFiles` using the configured `IParseVariant`s via a `ParseProcessor`. Returns the mutated `_importObject`.  
+  *Note:* The same `ImportObject` instance passed to the constructor is returned (though mutated internally).
+
+#### `DTSXMLParseImport` (concrete class)  
+- **`DTSXMLParseImport(ImportObject importObject, IImportNotification importNotification, Func<bool> isCancelled = null, bool skipNormalizing = false)`**  
+  Constructor. Initializes the XML parser with a target `ImportObject`, notification sink, optional cancellation delegate, and flag to skip normalization.  
+- **`List<IUIItems> UIItems { get; set; }`**  
+  Gets or sets UI-related items (e.g., progress indicators, messages) to be used by the underlying processor.  
+- **`ImportObject Parse(IEnumerable<string> importFiles)`**  
+  Processes XML files via `XMLParseProcessor`, applies post-processing (`AssignLinkedDASSerials`), and returns the mutated `_importObject`.  
+  *Note:* `UIItems` is assigned to the processor before processing.
+
+#### `AssignLinkedDASSerials` (private method in `DTSXMLParseImport`)  
+- **`void AssignLinkedDASSerials(ref ImportObject importObject)`**  
+  Post-processes `importObject.Hardware()` to populate `LinkedDASSerials` for pseudo-rack hardware: for each pseudo-rack (`IsPseudoRack() == true`), collects all hardware items whose `ParentDAS` matches the rack’s `SerialNumber`, and stores their serials in `LinkedDASSerials`.
+
+### 3. Invariants  
+- **`ParseVariantBase.Parse` must mutate `importObject` in-place** (via `ref`), not replace it.  
+- **`FileName` must be set on each `IParseVariant` instance before calling `Parse(ref ImportObject)`** (enforced by caller, not by class).  
+- **`DTSXMLParseImport.Parse` always calls `AssignLinkedDASSerials` after processing**, ensuring `LinkedDASSerials` is populated for pseudo-rack hardware.  
+- **`DefaultParseImport` does not modify the `importFiles` sequence**; it only iterates over it.  
+- **`DTSXMLParseImport` supports cancellation** via the `_isCancelled` delegate (behavior depends on `XMLParseProcessor` implementation, not visible here).  
+
+### 4. Dependencies  
+- **Depends on:**  
+  - `DTS.Common.Import.Interfaces` namespace (`IParseImport`, `IParseVariant`, `IImportNotification`, `IUIItems`).  
+  - `DTS.Slice.Users` namespace (for `IImportNotification`, `IUIItems`).  
+  - `ImportObject` type (used throughout; definition not provided here).  
+  - Internal types: `ParseProcessor`, `XMLParseProcessor` (referenced but not documented here).  
+- **Depended on by:**  
+  - Unknown from source alone. Likely consumed by higher-level import orchestration (e.g., UI layers, batch import services).  
+
+### 5. Gotchas  
+- **`DefaultParseImport` reuses the same `ImportObject` instance** passed to its constructor; callers must be aware that the returned object is the *same reference*, not a copy.  
+- **`DTSXMLParseImport.AssignLinkedDASSerials` only processes hardware where `IsPseudoRack()` returns `true`**; non-rack hardware is skipped.  
+- **`DTSXMLParseImport` does not validate `importFiles` for XML format**—assumes correctness (handled by `XMLParseProcessor`).  
+- **`UIItems` must be set on `DTSXMLParseImport` *before* calling `Parse`** to be effective (assigned to processor inside `Parse`).  
+- **`skipNormalizing` flag behavior is not visible in this module**—depends on `XMLParseProcessor` implementation.  
+- **`AssignLinkedDASSerials` uses LINQ query materialization (`as string[] ?? matches.ToArray()`) but does not guard against null `Hardware()`**—potential `NullReferenceException` if `importObject.Hardware()` returns `null`.