codequalityReportsComparer GraphQL Query polling State Issue

This is a follow up from: !135148 (comment 1618997073).

The codequalityReportsComparer query has:

1. Incorrect description for status field

• The status field in the query is not representing what is described in the docs (coming from StatusEnum < BaseEnum).
• The documentation needs to be updated to reflect the logic of the status field correctly.

More details can be found here.

2. No indication if the report is still being created

When a project with no existing CodeQuality report is queried the response looks like this:

{
  "data": {
    "project": {
      "mergeRequest": {
        "title": "Update file index3.js",
        "hasSecurityReports": true,
        "codequalityReportsComparer": {
          "report": null
        }
      }
    }
  }
}

When a project with an existing CodeQuality report is queried but the report is not yet ready. The response looks the same:

{
  "data": {
    "project": {
      "mergeRequest": {
        "title": "Update file index3.js",
        "hasSecurityReports": true,
        "codequalityReportsComparer": {
          "report": null
        }
      }
    }
  }
}

As a consumer there is no way to tell whether or not this MR does not have a CodeQuality Report or if we should keep polling.

We should introduce another field to represent the state of the report generation.

For the values of this field, let's stay consistent with the wording we're using for the SAST reports in: status_enum.rb

The current workaround for the client is to keep polling until there is a report since we know from the template if a report should be available. This is a bad-practice that should be refactored once the query is adjusted.

Example Query:

query getSASTAndCodeQualityReports {
  project(fullPath: "root/sast-and-cq") {
    mergeRequest(iid: "2") {
      title
      hasSecurityReports
      codequalityReportsComparer {
        report {
          status
          newErrors {
            description
            fingerprint
            severity
            filePath
            line
            webUrl
            engineName
          }
          resolvedErrors {
            description
            fingerprint
            severity
            filePath
            line
            webUrl
            engineName
          }
          existingErrors {
            description
            fingerprint
            severity
            filePath
            line
            webUrl
            engineName
          }
          summary {
            errored
            resolved
            total
          }
        }
      }
    }
  }
}

3. Reassess Polling Necessity

• After transitioning this endpoint from REST to GraphQL, it's essential to re-evaluate the continued necessity of polling.
• We might also consider adopting the GraphQL subscription feature, offering a more sophisticated and real-time solution.
• If polling remains indispensable, it's crucial that this requirement is clearly documented within the Query documentation, ensuring unambiguous communication between the server and client.