Enhance error message for BOM_COMPARE mode failures in rapid scan

[zahidblackduck]

JIRA Ticket
IDETECT-4728

Issue
When running rapid scans with BOM_COMPARE or BOM_COMPARE_STRICT modes, users receive a generic "400 Bad Request" error message without clear guidance on how to resolve the issue. The root cause is typically that the target project version doesn't exist in Black Duck Hub, but this wasn't communicated effectively to users.

Proposed Fix
Enhanced error handling in the waitForRapidResults method to:

• Intercept when BAD_REQUEST errors occur during BOM_COMPARE operations
• Provide specific guidance to users about project version requirements
• Suggest running a full scan first if the version hasn't been uploaded yet
• Update the FAILURE_BLACKDUCK_FEATURE_ERROR exit code to reflect the BOM_COMPARE error

Implementation Details

• Added specific error handling for IntegrationRestException with HTTP 400 status code when BOM_COMPARE or BOM_COMPARE_STRICT modes are used
• Enhanced error message includes actionable guidance directing users to verify their detect.project.version.name matches an existing project version in Black Duck Hub
• Refactored error handling logic into separate methods (handleRapidScanException, isBomCompareError, createBomCompareErrorMessage) for better maintainability and testability

Before/After Error Message
Before:

There was a problem trying to `GET {baseHubUrl}/api/developer-scans/{scanId}`, response was 400 Bad Request.

After:

There was a problem trying to `GET {baseHubUrl}/api/developer-scans/{scanId}`, response was 400 Bad Request. BOM_COMPARE mode requires the target project version to exist in Black Duck Hub. Please ensure 'detect.project.version.name' match an existing project version. Consider running a full scan first if the version hasn't been uploaded yet.

---

N.B: This merge request is meant for detect release 10.7

[Copilot]

Pull Request Overview

Enhance error message for BOM_COMPARE mode failures in rapid scans by intercepting 400 Bad Request errors and providing actionable guidance.

• Wrap rapid scan API call in a try-catch to handle IntegrationRestException
• Introduce handleRapidScanException, isBomCompareError, and createBomCompareErrorMessage methods for targeted error logic
• Augment user-facing error message with instructions on project version existence and running full scans

Comments suppressed due to low confidence (2)

src/main/java/com/blackduck/integration/detect/lifecycle/run/operation/OperationRunner.java:733

• New error handling logic in handleRapidScanException, isBomCompareError, and createBomCompareErrorMessage would benefit from dedicated unit tests to verify the enhanced error message and branch behavior.

    private OperationException handleRapidScanException(IntegrationRestException e) {

src/main/java/com/blackduck/integration/detect/lifecycle/run/operation/OperationRunner.java:748

• The method assumes rapidCompareMode is non-null, which could lead to a NullPointerException. Consider adding a null check before comparing.

    private boolean isBomCompareError(IntegrationRestException e, RapidCompareMode rapidCompareMode) {

[Copilot]

[nitpick] The string concatenation for the enhanced error message is lengthy; consider using a text block (Java 15+) or String.format for improved readability and maintainability.

Suggested change

	return originalMessage + " BOM_COMPARE mode requires the target project version to exist in Black Duck Hub. " +
	"Please ensure 'detect.project.version.name' matches an existing project version. " +
	"Consider running a full scan first if the version hasn't been uploaded yet.";
	return """
	%s BOM_COMPARE mode requires the target project version to exist in Black Duck Hub.
	Please ensure 'detect.project.version.name' matches an existing project version.
	Consider running a full scan first if the version hasn't been uploaded yet.
	""".formatted(originalMessage);

[Copilot]

Wrapping the original exception loses the original stack trace. Consider passing the original e as the cause to preserve debugging context, e.g., new OperationException(new IntegrationRestException(...), e).

Suggested change

	e.getHttpStatusMessage(), e.getHttpResponseContent(), enhancedMessage));
	e.getHttpStatusMessage(), e.getHttpResponseContent(), enhancedMessage, e));

[cpottsbd]

Suggest tweak:
"While trying to perform an operation on Black Duck SCA, Detect encountered an error. Ensure that your Black Duck SCA version is compatible with this version of Detect, your Black Duck user account has the required roles, and the project version exists in Black Duck when using BOM_COMPARE mode in a rapid scan."

[zahidblackduck]

Thanks for the suggestion. I made a small tweak to start the sentence with "Detect" to stay consistent with the style used in the other exit codes.