init

enriched-partialglm/Common/DTS.CommonCore/XMLUtils.md

@@ -0,0 +1,83 @@
+---
+source_files:
+  - Common/DTS.CommonCore/XMLUtils/DTSXMLFile.cs
+  - Common/DTS.CommonCore/XMLUtils/TestMetadataXml.cs
+generated_at: "2026-04-16T12:04:29.540782+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "8848a0560473ca7f"
+---
+
+# Documentation: DTS.Common.XMLUtils
+
+## 1. Purpose
+
+This module provides XML parsing and metadata extraction utilities for DTS application files. It contains two static classes: `DTSXMLFile` for extracting item count information from XML files, and `TestMetadataXml` for aggregating and parsing multiple DTS test metadata XML files into a unified `XDocument` structure. The module serves as a bridge between raw XML file storage and the application's test management system.
+
+---
+
+## 2. Public Interface
+
+### Class: `DTSXMLFile` (static)
+
+#### `public static double GetItemsToCompleteCount(string fileName)`
+- **Returns**: The value of the `TotalItems` attribute from an XML node as a `double`.
+- **Behavior**: Retrieves an import XML node via `FileUtils.GetImportXmlNode()`, then extracts and converts the `TotalItems` attribute using `CultureInfo.InvariantCulture`. The `importVersion` parameter is passed as an `out` parameter to the internal call but is not returned to the caller.
+
+---
+
+### Class: `TestMetadataXml` (static)
+
+#### `public static XDocument GetTestMetadataXml(string path, string file = "", string pattern = "")`
+- **Returns**: An `XDocument` with a root element named `"Tests"` containing aggregated test metadata.
+- **Parameters**:
+  - `path` - Directory path to search for files.
+  - `file` - Optional specific file path. If provided, only this file is processed.
+  - `pattern` - File pattern for search. Defaults to `".dts"` if null or empty.
+- **Behavior**: 
+  - Clears and populates the static `FileUtils.FileList` property.
+  - If `file` is provided, adds it directly to the file list.
+  - Otherwise, calls `FileUtils.FindFiles(path, pattern)` to discover files.
+  - Delegates to `SetTestMetadataType()` for XML processing.
+
+---
+
+## 3. Invariants
+
+- **FileUtils.FileList state**: The static property `FileUtils.FileList` is cleared (`new List<string>()`) at the start of every `GetTestMetadataXml()` call. Concurrent calls could result in race conditions.
+- **Return value for `GetItemsToCompleteCount`**: Always returns a `double`. The initial `importVersion` is set to `-1` before calling `FileUtils.GetImportXmlNode()`.
+- **XML structure assumption**: `SetTestMetadataType()` expects XML fragments to contain either a `"Test"` root element or a `"TestSetup"` root element. Other structures are silently ignored (the element is not added).
+- **Error handling**: `SetTestMetadataType()` catches exceptions at both the file level (logs and continues) and the overall level (returns an empty `XDocument`).
+
+---
+
+## 4. Dependencies
+
+### This module depends on:
+- **`DTS.Common.Utils`** (`FileUtils` class)
+  - `FileUtils.GetImportXmlNode()` - used in `DTSXMLFile`
+  - `FileUtils.FileList` - static list property used in `TestMetadataXml`
+  - `FileUtils.FindFiles()` - file discovery method used in `TestMetadataXml`
+- **`DTS.Common.Utilities.Logging`** (`APILogger` class)
+  - `APILogger.Log()` - used for error logging in `TestMetadataXml`
+- **`System.Xml.Linq`** - `XDocument`, `XElement` for XML manipulation
+- **`System.IO`** - `StreamReader`, `StringReader`, `File` for file I/O
+
+### What depends on this module:
+- **Unknown from source alone** - No consumers are shown in the provided files.
+
+---
+
+## 5. Gotchas
+
+1. **Multiple XML documents in a single file**: `SetTestMetadataType()` splits file contents by the string `"<?xml version="`, meaning a single file can contain multiple concatenated XML documents. This is a specific format requirement that is not validated—malformed files will cause silent failures.
+
+2. **Static state mutation**: `FileUtils.FileList` is a static property that is cleared and repopulated on every call to `GetTestMetadataXml()`. This is not thread-safe and could cause issues in concurrent scenarios.
+
+3. **Unused variable warning suppression**: The file includes `// ReSharper disable UnusedVariable`, suggesting there may be dead code or the developer wanted to suppress warnings about variables like `xmlCounter` and `fullstring` that could potentially be unused in certain code paths.
+
+4. **DataType attribute logic**: The `DataType` attribute is set to `"ALL"` if the file path contains the substring `"ALL"` (case-sensitive), otherwise `"ROI"`. This simple string check could produce unexpected results if `"ALL"` appears elsewhere in the path.
+
+5. **Empty XDocument on total failure**: If an exception occurs at the outer `try-catch` in `SetTestMetadataType()`, an empty `XDocument` is returned (no root element), which may cause null reference exceptions in consumers expecting a `"Tests"` root.
+
+6. **importVersion not exposed**: In `GetItemsToCompleteCount()`, the `importVersion` value is retrieved via `out` parameter but never returned or used by the caller. Its purpose is unclear from the source.