# GitHub Copilot Instructions: RoutingServiceNG Qt5 -> Qt6 Migration

## Mission
Migrate the legacy Qt5/C++11 `RoutingServiceNG` subfolder to the Qt6/C++17 target tree, preserve behavior unless a change is strictly required, and fully validate the result in the repository’s Docker-based CI environment.

## Scope
Migrate only this subtree:

- legacy input  
  `./qt-migration-legatus/qt5-before/qt5-legatus-legacy/Lts/Services/RoutingServiceNG`

- Qt6 output  
  `./qt-migration-legatus/qt6-after/qt6-migrated-legatus/Lts/Services/RoutingServiceNG`

This is a subfolder task inside an already in-progress Qt6 migration.

## Operating Mode
- Work autonomously from analysis through validation.
- Do not stop after code edits.
- Continue until Docker-based configure, build, tests, and policy checks have been attempted.
- Do not ask for confirmation during normal implementation.
- Stop early only if source material is missing, the task is impossible, or a destructive action would be required.

## Hard Boundaries
- Do not modify the legacy source tree in place.
- Write changes to the Qt6 target tree.
- Limit changes to:
  - `RoutingServiceNG`
  - directly required Qt6-side integration files
  - directly required CI/container/build/test files
- Do not migrate sibling services or unrelated modules unless `RoutingServiceNG` cannot be configured, generated, compiled, linked, or tested without a **minimal, directly related fix** there.
- If another module must be touched, keep the change minimal and explain exactly why `RoutingServiceNG` required it.
- No opportunistic cleanup, no broad refactors, no repository-wide modernization, no unrelated CMake cleanup.

## Technical Goals
- Upgrade Qt5 APIs used by this subfolder to Qt6 equivalents.
- Upgrade touched code to safe C++17 where required.
- Preserve behavior and interfaces unless change is strictly required.
- Keep the subfolder correctly integrated into the surrounding Qt6 build.

## Required API / Code Updates
Apply only where relevant:
- `QRegExp` -> `QRegularExpression`
- `QDesktopWidget` / `QApplication::desktop()` -> `QScreen`-based APIs
- remove legacy `QTextCodec` usage in favor of Qt6-safe text handling
- old `SIGNAL` / `SLOT` syntax -> function-pointer connect syntax
- `0` / `NULL` -> `nullptr`
- preserve `.ui`, `.qrc`, generated-code, and resource integration

## RTI / Codegen / KTextTemplate Rules
If this subfolder depends on RTI-generated code, parser-generated files, or KTextTemplate-based generation:

- reconstruct the legacy generation/invocation flow
- verify the Qt6-side port of that flow
- ensure required generated `.h` / `.cpp` are produced automatically by the build
- ensure they are available **before compilation of consuming targets starts**
- ensure consuming targets explicitly depend on generation where needed
- ensure generated `.cpp` files are attached to the correct target
- ensure generated headers are available through include paths
- ensure outputs go to the build tree unless repository structure clearly requires otherwise
- ensure RTI-enabled and RTI-disabled builds are both handled correctly if RTI is optional

Inspect and fix if needed:
- `add_custom_command(OUTPUT ...)`
- `BYPRODUCTS`
- `DEPENDS`
- `MAIN_DEPENDENCY`
- `WORKING_DIRECTORY`
- `COMMAND`
- `VERBATIM`
- `target_sources(...)`
- `add_dependencies(...)`
- `GENERATED`
- generated output directory creation
- actual generator CLI output paths vs declared CMake output paths
- KTextTemplate template dependencies
- RTI/codegen input dependencies
- incremental rebuild triggers

Before final validation, remove or invalidate any pre-existing generated artifacts relevant to `RoutingServiceNG` and prove that the required files are regenerated by the build itself.

## Build Integration Rules
Verify and fix only the integration needed for this subfolder:
- local and parent `CMakeLists.txt`
- target inclusion
- include directories
- Qt module linkage
- generated file registration
- `.ui` / `.qrc` handling
- RTI/codegen/KTextTemplate wiring
- test target wiring

Ensure the Qt6 build:
- compiles this subfolder from the Qt6 target tree, not from Qt5 paths
- does not depend on stale source-tree generated artifacts
- uses correct generated-file paths
- has no order/race issue between generation and compilation

## C++17 Rules
- Preserve semantics first.
- Modernize only touched code.
- Prefer small, low-risk updates.
- Use `nullptr`.
- Use `override`, `= default`, `= delete`, `noexcept` where clearly correct.
- Avoid broad rewrites.

## Tests
- For every code change inside a method, add at least three tests if the changed behavior is realistically testable within the repository’s existing test approach.
- Place tests in the closest correct Qt6 test location, preferably under:
  `./qt-migration-legatus/qt6-after/qt6-migrated-legatus/tests`
  or the existing Qt6 test location used by this module.
- Use policy-compatible names:
  - `test_<name>.cpp`
  - `<name>_test.cpp`
  - `<name>test.cpp`
  - `<name>gtest.cpp`
- Register all added tests with CTest.
- If full direct coverage is not practical, explain why and add the nearest practical coverage.

## Docker-First Validation
Use the repository CI container setup as authoritative:

- `./qt-migration-legatus/ci/Dockerfile.ci`
- inspect `./app/Dockerfile` too if relevant to this module’s build path

Do not substitute host tools for missing container tools.

### Required validation sequence
1. configure in Docker
2. build in Docker
3. run tests in Docker
4. if tests pass, run  
   `python3 ./qt-migration-legatus/ci/check_pr_policies.py`  
   in Docker

### Required build validation
If generation is involved, validate all of the following:
- clean build from an empty build directory
- generator execution in Docker
- required generated `.h` / `.cpp` appear in the expected location
- compilation of all consumers succeeds
- incremental rebuild after changing a generator input/template/dependency
- RTI-disabled path still builds if RTI is optional

Start from:
- `cmake -S ./qt-migration-legatus/qt6-after/qt6-migrated-legatus -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug`
- `cmake --build build --parallel`
- `ctest --test-dir build --output-on-failure`
- `python3 ./qt-migration-legatus/ci/check_pr_policies.py`

Adapt only if repository inspection proves different commands/targets are required.

## Missing-Tool Remediation
If Docker validation fails because tools/packages are missing:
- identify the exact missing dependency
- update `./qt-migration-legatus/ci/Dockerfile.ci` minimally
- rebuild the CI image
- rerun validation

## Failure Classification
Classify each failure as:

### Environment
- missing command/tool/package
- missing Qt dev dependency
- missing generator/template dependency
- missing tool required by policy checks

### Project
- compile error
- link error
- test failure
- codegen integration failure
- target wiring failure
- policy failure caused by migration changes

## Execution Plan
1. inspect legacy and Qt6 target subtrees
2. identify Qt5 API, C++17, and build integration work
3. reconstruct any legacy RTI/codegen/KTextTemplate flow used by this subfolder
4. migrate only the required Qt6-side files
5. fix build integration
6. ensure generated files exist before compilation
7. add/update tests
8. validate in Docker
9. if needed, update `Dockerfile.ci` minimally and rerun
10. continue until success or a real blocker remains

## Completion Criteria
Success requires:
- migrated `RoutingServiceNG` exists in the Qt6 target tree
- subfolder is correctly integrated into the Qt6 build
- required generated `.h` / `.cpp` are automatically produced and available before compilation
- Docker configure succeeds
- Docker build succeeds
- relevant tests succeed
- Docker policy check succeeds

## Final Response
Report concisely:
- whether migration is fully validated or what blocker remains
- whether RTI/codegen/KTextTemplate was involved
- whether generation timing and output placement were verified
- exact Docker commands used
- files changed
- for each failed attempt:
  - exact command
  - key error
  - environment vs project
  - fix applied
- short remaining-risk/blocker summary