Add full XML coverage support: FSM, assertion, block, branch, toggle, userAttr

- xml_writer.py: add write_block_coverage, write_branch_coverage,
  write_toggle_coverage, write_fsm_coverage, write_assertion_coverage,
  write_user_attrs; fix writtenBy/writtenTime; emit parentId on history nodes;
  ctx.warn for condition scopes
- xml_reader.py: add readFsmCoverage, readAssertionCoverage, read_user_attrs;
  call read_user_attrs from all coverage readers; two-pass parentId wiring
- db_merger.py: extend _merge_code_coverage for FSM/ASSERT/COVER scope types;
  extend _merge_code_coverage_items for all assertion bin types; rewrite
  history node copy with depth sort and parent-at-create-time
- ucis_builders.py: add cc7 (FSM), as1 (cover assertion), as2 (assert property),
  sm6 (parent-child history) builders; ALL_BUILDERS now 15 entries
- test_xml_conversion.py: add schema_validate fixture; schema validation in all
  roundtrip and write tests; test_source_file_ids_consistent; test_read_golden_file
  parametrized over 5 golden fixtures
- test_api_attributes.py: remove xml skip guards for 5 attribute tests
- fixtures/xml/: 5 golden XML files (toggle, fsm, assertion, block, branch)
- xml_interchange.rst: document all new coverage types, userAttr, history nodes;
  update Feature Support Matrix

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mballance

doc/source/reference/xml_interchange.rst

@@ -192,6 +192,153 @@ Optional Elements
 - **cross** (minOccurs="0") - Cross coverage is optional
 - **crossBin** (minOccurs="0") - Crosses may have no bins
 
+Code Coverage
+=============
+
+PyUCIS supports reading and writing all major UCIS code coverage types within
+``instanceCoverages`` elements.
+
+Statement Coverage
+------------------
+
+Statement coverage is stored as ``blockCoverage`` → flat ``statement`` elements:
+
+.. code::
+
+  <blockCoverage>
+    <statement id="1" file="1" line="5" inlineCount="1">
+      <contents coverageCount="3"/>
+    </statement>
+  </blockCoverage>
+
+Each ``statement`` records one source location with its hit count.
+
+Branch Coverage
+---------------
+
+Branch coverage is stored as ``branchCoverage`` → ``branch`` elements, one per
+branching statement (``if``, ``case``, etc.). Each branch has one or more
+``branchBin`` arms:
+
+.. code::
+
+  <branchCoverage>
+    <branch id="1" branchType="if" file="1" line="10">
+      <branchBin alias="taken">
+        <contents coverageCount="2"/>
+      </branchBin>
+      <branchBin alias="not_taken">
+        <contents coverageCount="0"/>
+      </branchBin>
+    </branch>
+  </branchCoverage>
+
+Toggle Coverage
+---------------
+
+Toggle coverage is stored as ``toggleCoverage`` → ``toggleObject`` → ``toggleBit``
+elements. Each bit records a 0→1 and a 1→0 transition bin:
+
+.. code::
+
+  <toggleCoverage>
+    <toggleObject name="sig" canonical="sig">
+      <toggleBit name="sig[0]">
+        <toggle01Bin>
+          <contents coverageCount="1"/>
+        </toggle01Bin>
+        <toggle10Bin>
+          <contents coverageCount="1"/>
+        </toggle10Bin>
+      </toggleBit>
+    </toggleObject>
+  </toggleCoverage>
+
+FSM Coverage
+------------
+
+FSM coverage is stored as ``fsmCoverage`` → ``fsm`` elements. State coverage uses
+``stateBin`` and transition coverage uses ``transitionBin``:
+
+.. code::
+
+  <fsmCoverage>
+    <fsm name="state_machine">
+      <state stateName="IDLE">
+        <stateBin name="IDLE">
+          <contents coverageCount="5"/>
+        </stateBin>
+      </state>
+      <stateTransition>
+        <state>IDLE</state>
+        <state>ACTIVE</state>
+        <transitionBin name="IDLE->ACTIVE">
+          <contents coverageCount="2"/>
+        </transitionBin>
+      </stateTransition>
+    </fsm>
+  </fsmCoverage>
+
+Assertion Coverage
+------------------
+
+Assertion coverage is stored as ``assertionCoverage`` → ``assertion`` elements.
+The ``assertionKind`` attribute is either ``assert`` or ``cover``:
+
+.. code::
+
+  <assertionCoverage>
+    <assertion name="my_property" assertionKind="assert">
+      <passBin>
+        <contents coverageCount="10"/>
+      </passBin>
+      <failBin>
+        <contents coverageCount="0"/>
+      </failBin>
+      <attemptBin>
+        <contents coverageCount="10"/>
+      </attemptBin>
+    </assertion>
+  </assertionCoverage>
+
+Supported bin kinds for ``assert``: ``failBin``, ``passBin``, ``vacuousBin``,
+``disabledBin``, ``attemptBin``, ``activeBin``, ``peakActiveBin``.
+
+Supported bin kinds for ``cover``: ``coverBin``, ``failBin``, ``passBin``,
+``vacuousBin``, ``disabledBin``, ``attemptBin``, ``activeBin``, ``peakActiveBin``.
+
+User Attributes
+===============
+
+PyUCIS supports round-tripping user attributes (set via ``setAttribute`` /
+``getAttribute``) through XML ``userAttr`` child elements. These are written as
+the last children of each coverage container element:
+
+.. code::
+
+  <toggleCoverage>
+    <!-- ... toggle data ... -->
+    <userAttr key="tool_name" type="str">my_simulator</userAttr>
+    <userAttr key="version" type="str">2024.1</userAttr>
+  </toggleCoverage>
+
+User attributes attached to instance scopes are preserved across XML write/read
+round-trips. Tags (set via ``addTag``) are not currently serialized to XML.
+
+History Nodes
+=============
+
+History nodes record the provenance of coverage data (test runs, merges). PyUCIS
+preserves the parent/child relationships between history nodes using the ``id``
+and ``parentId`` attributes:
+
+.. code::
+
+  <historyNodes>
+    <historyNode id="1" logicalName="test_run_1" .../>
+    <historyNode id="2" logicalName="merge_result" parentId="1" .../>
+  </historyNodes>
+
 Known Format Limitations
 =========================
 
@@ -243,6 +390,30 @@ Feature Support Matrix
    * - Cross Bins
      - ✅ Yes
      - With index reconstruction
+   * - Statement Coverage
+     - ✅ Yes
+     - Flat statement mode
+   * - Branch Coverage
+     - ✅ Yes
+     - if/case branching statements
+   * - Toggle Coverage
+     - ✅ Yes
+     - Per-bit 0→1 and 1→0 bins
+   * - FSM Coverage
+     - ✅ Yes
+     - State and transition coverage
+   * - Assertion Coverage
+     - ✅ Yes
+     - cover and assert kinds, all bin types
+   * - User Attributes
+     - ✅ Yes
+     - Via ``userAttr`` child elements
+   * - History Node Hierarchy
+     - ✅ Yes
+     - Parent/child via ``parentId``
+   * - Condition/Expression Coverage
+     - ❌ No
+     - Not in Python DM; writer emits ctx.warn
    * - Instance Weights
      - ❌ No
      - Not in XML schema
@@ -255,6 +426,9 @@ Feature Support Matrix
    * - Standalone File Handles
      - ❌ No
      - Requires instanceCoverages
+   * - Tags
+     - ❌ No
+     - No direct XML representation
 
 Workarounds
 -----------

src/ucis/merge/db_merger.py

@@ -80,14 +80,33 @@ def merge(self, dst_db, src_db_l : List[UCIS]):
             self._merge_code_coverage(dst_iscope, src_scopes)
 
         # Copy history nodes from all source databases
+        def _node_key(n):
+            """Stable key for a history node regardless of backend."""
+            return getattr(n, 'history_id', id(n))
+
         for db in src_db_l:
-            for src_hn in db.historyNodes(HistoryNodeKind.ALL):
+            src_nodes = list(db.historyNodes(HistoryNodeKind.ALL))
+            src_to_dst = {}  # maps _node_key(src_node) → dst_node
+
+            # Sort so parents are created before children
+            def _sort_key(n):
+                depth = 0
+                p = n.getParent()
+                while p is not None:
+                    depth += 1
+                    p = p.getParent()
+                return depth
+
+            for src_hn in sorted(src_nodes, key=_sort_key):
+                src_parent = src_hn.getParent()
+                dst_parent = src_to_dst.get(_node_key(src_parent)) if src_parent is not None else None
                 dst_hn = dst_db.createHistoryNode(
-                    None,
+                    dst_parent,
                     src_hn.getLogicalName(),
                     src_hn.getPhysicalName(),
                     src_hn.getKind()
                 )
+                src_to_dst[_node_key(src_hn)] = dst_hn
                 dst_hn.setTestStatus(src_hn.getTestStatus())
                 if src_hn.getSimTime() is not None:
                     dst_hn.setSimTime(src_hn.getSimTime())
@@ -304,6 +323,13 @@ def _merge_code_coverage(self, dst_scope, src_scopes):
 
         # Merge TOGGLE scopes (toggle coverage)
         self._merge_scopes_by_type(dst_scope, src_scopes, ScopeTypeT.TOGGLE)
+
+        # Merge FSM scopes (FSM state/transition coverage)
+        self._merge_scopes_by_type(dst_scope, src_scopes, ScopeTypeT.FSM)
+
+        # Merge assertion scopes (assert/cover directives)
+        self._merge_scopes_by_type(dst_scope, src_scopes, ScopeTypeT.ASSERT)
+        self._merge_scopes_by_type(dst_scope, src_scopes, ScopeTypeT.COVER)
 
     def _merge_scopes_by_type(self, dst_parent, src_scopes, scope_type):
         """Merge scopes of a specific type.
@@ -362,6 +388,15 @@ def _merge_code_coverage_items(self, dst_scope, src_scopes):
             CoverTypeT.EXPRBIN,     # Expression coverage
             CoverTypeT.CONDBIN,     # Condition coverage
             CoverTypeT.FSMBIN,      # FSM coverage
+            CoverTypeT.ASSERTBIN,   # Assertion directive bins
+            CoverTypeT.COVERBIN,
+            CoverTypeT.PASSBIN,
+            CoverTypeT.FAILBIN,
+            CoverTypeT.VACUOUSBIN,
+            CoverTypeT.DISABLEDBIN,
+            CoverTypeT.ATTEMPTBIN,
+            CoverTypeT.ACTIVEBIN,
+            CoverTypeT.PEAKACTIVEBIN,
         ]
 
         for cvg_type in coverage_types: