fix: migrate external issues from SonarQube to SonarCloud (Issue #147)

[joshuaquek]

Summary

CloudVoyager was dropping all external issues (Ruff, Pylint, Flake8 linters) during migration to SonarCloud.

Root causes found and fixed:

1. add-protobuf-files.js: External issues were correctly built into protobuf messages but externalIssues-{ref}.pb and adhoerules.pb were never written to the upload zip archive.

2. source-methods.js: Unit test files (UTS qualifier) were excluded from source file extraction, causing their issues to be skipped from validComponentKeys.

3. build-file-components.js: Safety net added to ensure FIL components from the component tree are added even without source code.

Test plan

• Built and packaged successfully
• Ran full transfer on okorach-oss_sonar-tools project (SQ 2026.1)
• Before fix: 554 external issues skipped, 778/1332 SC issues migrated
• After fix: 0 external issues skipped, 1332/1332 SC issues migrated (100% match)
• Spot-checked SonarCloud — external_ruff rules confirmed migrated

Files changed

File	Change
src/pipelines/sq-2025/sonarcloud/uploader/helpers/add-protobuf-files.js	Added externalIssues and adHocRules to zip
src/pipelines/sq-2025/sonarqube/api-client/helpers/source-methods.js	Added UTS qualifier to include unit test files
src/pipelines/sq-2025/protobuf/build-components/helpers/build-file-components.js	Safety net for FIL components without source
docs/regression-testing.md	Generalized protocol to support any SQ project

🤖 Generated with Claude Code

[sonar-review-alpha]

Summary

What Changed

This PR fixes a data loss issue (#147) where external issues from SonarQube were not being migrated to SonarCloud. The fix has three parts:

1. Capture all file components (build-file-components.js): Ensures Text files and other FIL components are included even if their source code couldn't be fetched. Previously, these would be silently skipped.

2. Upload external issue files (add-protobuf-files.js): Adds support for serializing and uploading externalissues-{ref}.pb protobuf files to SonarCloud, which were previously omitted. Also adds support for ad-hoc rules files.

3. Include unit test source files (source-methods.js): Expands the qualifiers parameter from 'FIL' to 'FIL,UTS' so unit test source files are included in the migration.

Also updates regression testing documentation to be project-agnostic with expanded guidance on project selection and API commands.

What reviewers should know

For Reviewers

Start with the code changes (3 small hunks, ~50 LOC total):

• add-protobuf-files.js — the critical path: verify external issues are properly serialized and added to the zip
• build-file-components.js — verify the fallback logic doesn't break existing file matching for files with source code
• source-methods.js — simple change; confirm UTS (Unit Test Sources) is a valid SonarQube qualifier

Verify data flow integrity:

• External issues are fetched from SQ → serialized to protobuf → added to upload → parsed by SC
• Are external issues being fetched somewhere? (grep for externalissues or similar SQ API calls — this PR only handles upload/serialization)
• The Map approach in add-protobuf-files.js uses ref as the key — confirm ref uniquely identifies file components

Watch for edge cases:

• Empty external issues map: the guard if (...encodedReport.externalIssues && encodedReport.externalIssues.size > 0) handles it correctly
• Files with zero lines: Number.parseInt(...) || 0 provides a safe fallback
• UTS qualifier side effect: test that including unit test files doesn't duplicate issues or break matching

Testing note: Regression testing docs now generalize to any project, so manual testing should verify external issues transfer correctly on a project that has them.

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[joshua-quek-sonarsource]

Hi @okorach @okorach-sonar , Ruff migration issues are fixed 👍🏼