Pkg Python API
==============

Extract tracing tags and activities from ``.pkg`` and ``.ta`` files generated by
``ecu.test`` and write them to a LOBSTER interchange file.

API
---

::

   from lobster.tools.pkg.pkg import lobster_pkg
   lobster_pkg(config: PkgToolConfig)

First, prepare a configuration:

Configuration Dataclass
-----------------------

::

   from lobster.tools.pkg.pkg import PkgToolConfig, lobster_pkg
   from pathlib import Path

   config = PkgToolConfig(
         files=[Path("tests/pkg/"), Path("specific_test.pkg")],
         out=Path("pkg.lobster"),   # optional; defaults to "pkg.lobster"
   )

``PkgToolConfig`` fields (dataclass):

- ``files: Sequence[Path]`` - List of ``.pkg`` / ``.ta`` files or directories to process. Directories are scanned recursively for matching extensions.
- ``out: Optional[Path]`` - Destination ``.lobster`` file. If ``None``, output is written to ``pkg.lobster`` in the current directory.

Stable API Function
-------------------

``lobster_pkg(config: PkgToolConfig) -> None``
  Runs end-to-end: scan input files, parse tracing tags from XML content, write LOBSTER output.

Example (Scanning a Directory)
------------------------------

::

   from lobster.tools.pkg.pkg import PkgToolConfig, lobster_pkg
   from pathlib import Path

   lobster_pkg(PkgToolConfig(
      files=[Path("tests/pkg/"), Path("tests/ta/")],
      out=Path("tracing.lobster"),
   ))

Behavioral Notes
----------------
- Only packages with a ``TESTCASE`` tag in ``INFORMATION/TAGS`` are processed; others are silently skipped.
- In ``.pkg`` files, ``lobster-trace:`` values are read from ``VALUE`` elements inside ``TsBlock`` ``TESTSTEP`` nodes at the first or second nesting level under ``TESTSTEPS``. Tags placed deeper are treated as misplaced and raise a ``LOBSTER_Exception``.
- In ``.ta`` files, ``lobster-trace:`` values are read from ``DESCRIPTION`` elements that are direct children of top-level ``episode`` ``ANALYSISITEM`` nodes inside ``TRACE-ANALYSIS``. Tags found at deeper levels emit a warning but do not stop processing.
- Multiple requirements can be listed in a single trace tag using comma separation (e.g. ``lobster-trace: REQ-001, REQ-002``).
- XML parse errors raise ``xml.etree.ElementTree.ParseError``.

Core Goals
----------
- Parse ``.pkg`` and ``.ta`` files from ``ecu.test`` and convert them to LOBSTER activities.
- Support both standard ``TsBlock``-based tracing and ``TRACE-ANALYSIS`` episode tracing.
- Produce a single ``.lobster`` artifact for use by downstream LOBSTER tools.

Error Conditions
----------------
- No input files found after scan → ``ValueError``.
- Misplaced ``lobster-trace`` tag in a ``.pkg`` file → ``LOBSTER_Exception``.
- Malformed XML → ``xml.etree.ElementTree.ParseError``.