#89: add normalize-tests service and lineage handling (#90)

* feat: add normalize-tests service and lineage handling

- Implemented the `normalize-tests` command to validate, build, and write UI test catalogs.
- Introduced a lineage table to map input scenarios to user stories and functionalities.
- Created unit tests for the new service, ensuring proper functionality and lineage coverage.
- Added shared fixtures for testing and established expected output for the UI test catalog.
- Updated requirements to include the new normalize_tests package.

* fix: refine logic for qualified scenario IDs and enhance unit tests for fallback behavior

* feat: implement centralized error handling for CLI commands and update documentation

Author: miroslavpojer

.claude/commands/implement-task.md

@@ -47,7 +47,7 @@ Task-list source (optional override): `$2`
 ## 4. Run the `make qa` loop until green
 
 - Run `make qa` for a full-repo change, or `make qa-<alias>` for the package you touched
-  (`<alias>` ∈ `core`, `normalize-docs`, `cli`) — the same targets CI runs.
+  (`<alias>` ∈ `core`, `normalize-docs`, `normalize-tests`, `cli`) — the same targets CI runs.
 - Fix every failure and re-run. Repeat until QA exits clean per package:
   Pylint ≥ 9.5, Black clean, mypy clean, deptry clean, `pytest --cov-fail-under=80` passing,
   and `make no-vendored-schemas` clean.

.github/agents/devops-engineer.agent.md

@@ -87,7 +87,7 @@ Repo specifics
   - Python 3.10+ (supported floor); the CI matrix runs `3.10` through `3.14`.
 - Quality gates (use the `Makefile` targets — `.github/workflows/test.yml` and `integration.yml` run the same)
   - Full gate, all packages: `make qa`
-  - Per package: `make qa-<alias>` (`<alias>` ∈ `core`, `normalize-docs`, `cli`)
+  - Per package: `make qa-<alias>` (`<alias>` ∈ `core`, `normalize-docs`, `normalize-tests`, `cli`)
   - Individual: `make lint-<alias>` (Pylint ≥ 9.5), `make format-check-<alias>` (Black, line length 120), `make types-<alias>` (mypy), `make deptry-<alias>` (deptry), `make test-<alias>`, `make coverage-<alias>` (`--cov-fail-under=80`)
   - Whole repository: `make no-vendored-schemas` (R12 check 1, in `make qa`)
   - Must keep the per-package invocation (each gate runs from inside the package directory) — do not flatten it to a repo-root command.

.github/agents/senior-developer.agent.md

@@ -101,7 +101,7 @@ Repo specifics
   - Must keep Python imports at top of file (not inside functions/methods).
 - Quality gates (use the `Makefile` targets — `.github/workflows/test.yml` runs the same)
   - Full gate, all packages: `make qa`
-  - Per package: `make qa-<alias>` (`<alias>` ∈ `core`, `normalize-docs`, `cli`)
+  - Per package: `make qa-<alias>` (`<alias>` ∈ `core`, `normalize-docs`, `normalize-tests`, `cli`)
   - Individual: `make format-<alias>` (check-only `make format-check-<alias>`), `make lint-<alias>` (Pylint ≥ 9.5), `make types-<alias>`, `make deptry-<alias>`, `make test-<alias>`, `make coverage-<alias>` (`--cov-fail-under=80`)
 - Contract-sensitive outputs
   - CLI argument names/defaults; the action's inputs and `output-path` output; `main.py`'s error lines.

.github/copilot-instructions.md

@@ -21,8 +21,8 @@ Tooling and quality gates → Common pitfalls → Learned rules.
 (`living-doc`) and one composite GitHub Action. It sits between the upstream `living-doc-*`
 collector actions and the downstream generator actions: it reads collector output as
 `living-doc-utilities` contract artifacts, validates a command's inputs together, and
-transforms them into the contracts the generators read. `normalize-docs` runs;
-`normalize-tests` and `coverage-matrix` each land in a later change.
+transforms them into the contracts the generators read. `normalize-docs` and `normalize-tests` run;
+`coverage-matrix` lands in a later change.
 
 - Must treat the `living-doc` CLI running as a step in a GitHub Actions workflow as the supported path; running `living-doc <command>` locally is a development and debugging affordance only.
 - Must keep the whole collect → normalize → generate pipeline AI-free — deterministic Python only, no LLM call and no network call anywhere in that path.
@@ -31,20 +31,21 @@ transforms them into the contracts the generators read. `normalize-docs` runs;
 
 ## Repo specifics
 
-Module map — three packages under `packages/` and `apps/`, each with its own `pyproject.toml`,
+Module map — four packages under `packages/` and `apps/`, each with its own `pyproject.toml`,
 `src/` layout, and `tests/` directory:
 
 | Path | Package (`pip` name) | Responsibility |
 |---|---|---|
-| `packages/core` | `living-doc-core` | `logging_config.py` (`setup_logging`), `readers.py` (the reader table, `read_documentation`, `read_tests`), `input_validation.py` (`validate_inputs`, the shared input validation), `views.py` (`select_records`, the view filter), `run_context.py` (`run_context`, the CI run for `metadata.run`). Depends on `living-doc-utilities==0.8.0`. |
+| `packages/core` | `living-doc-core` | `logging_config.py` (`setup_logging`), `envelope.py` (`PRODUCER_NAME`, `TOOLKIT_VERSION`, `forwarded`, the producer identity and warning forwarding every transform shares), `readers.py` (the reader table, `read_documentation`, `read_tests`), `input_validation.py` (`validate_inputs`, the shared input validation), `views.py` (`select_records`, the view filter), `run_context.py` (`run_context`, the CI run for `metadata.run`). Depends on `living-doc-utilities==0.8.0`. |
 | `packages/services/normalize_docs` | `living-doc-service-normalize-docs` | `builder.py` (`build_generator_ready`), `lineage.py` (`LINEAGE_TABLE`), `service.py` (`normalize_docs`, the command, and `check_no_field_loss`). |
-| `apps/cli` | `living-doc-cli` | CLI entry point — `main.py` (`cli()` click group), one module per command under `commands/`. Registers `normalize-docs`. |
+| `packages/services/normalize_tests` | `living-doc-service-normalize-tests` | `builder.py` (`build_ui_test_catalog`), `lineage.py` (`LINEAGE_TABLE`), `service.py` (`normalize_tests`, the command, and the runtime field-loss check). |
+| `apps/cli` | `living-doc-cli` | CLI entry point — `main.py` (`cli()` click group), one module per command under `commands/`. Registers `normalize-docs` and `normalize-tests`. |
 
 - Must treat the repository root as the action — `action.yml`, its entry point `main.py` (input checks, `COMMAND_INPUTS`, `NOT_AVAILABLE_YET`), and the root `tests/`.
 - Must treat `apps/cli/src/living_doc_cli/main.py` `cli()` as the CLI entry point — each command is registered there as it lands.
 - Must read every contract artifact through `living_doc_core.readers`, which calls `living-doc-utilities`' `read_artifact`, and must write one only through `write_artifact` (R12 check 2).
 - Must run `living_doc_core.input_validation.validate_inputs` over a command's inputs before it transforms them.
-- Must select a view's records only through `living_doc_core.views.select_records`, and Must keep each command's lineage table in its own service package, checked by `assert_complete` in its tests and never at run time.
+- Must select view records only through `living_doc_core.views.select_records`, and Must keep each command's lineage table in its own service package, checked by `assert_complete` in its tests and never at run time; `normalize-tests` has no view input and always writes `document.view` as `inner`.
 - Must declare the toolkit's one version in every package, and Must read `metadata.producer.version` from the installed `living-doc-core`, never from a literal.
 
 Inputs — the action's inputs (full reference in [`README.md`](../README.md#inputs)):
@@ -65,7 +66,7 @@ Contract-sensitive outputs:
 QA commands — the per-package `Makefile` targets (`.github/workflows/test.yml` runs the same targets):
 
 - Full gate, every package: `make qa` (runs `format-check` → `lint` → `types` → `deptry` → `test` per package, then the root checks, then `no-vendored-schemas`, failing on the first).
-- Per package: `make qa-<alias>` where `<alias>` is one of `core`, `normalize-docs`, `cli`.
+- Per package: `make qa-<alias>` where `<alias>` is one of `core`, `normalize-docs`, `normalize-tests`, `cli`.
 - Individual gate per package: `make lint-<alias>`, `make format-<alias>`, `make format-check-<alias>`, `make types-<alias>`, `make deptry-<alias>`, `make test-<alias>`, `make coverage-<alias>`.
 - `lint-<alias>` runs ruff (`E` / `F` / `I` / `B`, `tests` excluded per each package's `[tool.ruff]`) then Pylint; `format-<alias>` runs `ruff check --fix` then Black.
 - Must not use repo-root `pylint $(git ls-files '*.py')` / `pytest tests/` as the QA command — CI gates changes per package from inside each package directory.

.github/dependabot.yml

@@ -91,6 +91,29 @@ updates:
         patterns:
           - "*"
 
+  - package-ecosystem: "pip"
+    directory: "/packages/services/normalize_tests"
+    target-branch: "master"
+    schedule:
+      interval: "weekly"
+      day: "sunday"
+    labels:
+      - "auto update"
+      - "infrastructure"
+      - "no RN"
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    allow:
+      - dependency-type: "direct"
+    ignore:
+      - dependency-name: "living-doc-utilities"
+    groups:
+      pip-normalize-tests:
+        patterns:
+          - "*"
+
   - package-ecosystem: "pip"
     directory: "/apps/cli"
     target-branch: "master"

.github/workflows/integration.yml

@@ -86,6 +86,45 @@ jobs:
           ' "$OUTPUT_PATH" "$GITHUB_RUN_ID"
           echo '::notice::normalize-docs wrote a valid generator-ready file in the release view, with this run, at the output-path.'
 
+      - name: Run normalize-tests
+        id: normalize-tests
+        uses: ./
+        with:
+          command: normalize-tests
+          input: tests/fixtures/collector-gh/ui-tests.json
+          output: output/ui-test-catalog.json
+
+      - name: normalize-tests wrote a valid catalog with this run, and output-path names it
+        env:
+          VENV: ${{ runner.temp }}/living-doc-toolkit-venv
+          OUTPUT_PATH: ${{ steps.normalize-tests.outputs.output-path }}
+        run: |
+          set -euo pipefail
+          if [[ "$OUTPUT_PATH" != "$GITHUB_WORKSPACE/output/ui-test-catalog.json" ]]; then
+            echo "::error::output-path must be the absolute path of the file written; it is '$OUTPUT_PATH'."; exit 1
+          fi
+          "$VENV/bin/python" -I -c '
+          import sys
+          from living_doc_utilities.contracts.io import read_artifact
+          from living_doc_utilities.contracts.ui_test_catalog import UiTestCatalogResult
+          result = read_artifact(sys.argv[1], expected="ui-test-catalog")
+          assert isinstance(result, UiTestCatalogResult), type(result)
+          assert result.document.view == "inner", result.document
+          assert [feature_file.feature_file for feature_file in result.feature_files] == [
+              "AbsaOSS/living-doc/docs/examples/gherkin/liv_doc_func/func-001-validate-password-strength.feature",
+              "AbsaOSS/living-doc/docs/examples/gherkin/liv_doc_us/us-001-customer-login.feature",
+          ]
+          functionality_file, user_story_file = result.feature_files
+          assert [(group.entity_id, len(group.scenarios)) for group in functionality_file.linked_to_functionality] == [("FUNC-001", 4)]
+          assert [(group.entity_id, len(group.scenarios)) for group in user_story_file.linked_to_user_story] == [("US-001", 2)]
+          assert not any(feature_file.unlinked for feature_file in result.feature_files)
+          assert result.metadata.run.run_id == sys.argv[2], (result.metadata.run, sys.argv[2])
+          assert result.metadata.producer.build is None, result.metadata.producer
+          print(result.document.view)
+          print(result.metadata.run)
+          ' "$OUTPUT_PATH" "$GITHUB_RUN_ID"
+          echo '::notice::normalize-tests wrote a valid ui-test-catalog file with this run at the output-path.'
+
   action-venv-isolation:
     runs-on: ubuntu-latest
     name: Action Venv - Isolation and Reuse