feat!: introduce confidence scores for check facts

[behnazh-w]

Confidence score and justification type

• This PR allows specifying confidence scores for check results, which is especially useful when a check reports multiple candidate results. All of these confidence scores are added to the check tables in the database. However, the fact that has the highest confidence is shown in the HTML/JSON report only.

• The justifications are no longer required to be added manually to the CheckResultData. Instead, they are curated directly from the results in the table. If a column has specified JustificationType in the column mapping, it will be picked up automatically and rendered as plain text or href depending on the specified type. If a check fails or is skipped, we show a default Not Available. justification. This allows to create HTML/JSON reports from the database reproducibly.

Refactoring

For this feature to work, the following refactorings are done as well:

• The checks are changed to add multiple facts to a result table.
• The confidence score is added to CheckFacts ORM mapping, which all the check mappings inherit from. That caused some circular dependency issues for the Expectation ORM mapping. I have refactored and improved this mapping accordingly.
• I have improved the check table columns that needed to be added as justification. For example, I have added asset_url to ProvenanceAvailableFacts. That required adding a new SLSAProvenanceData wrapper class for GitHub release provenances.

Documentation

I have added elaborate instructions for adding a new check and explained the current interface.

[nicallen]

Under this new schema, the confidence score is recorded for a check_facts entry, which currently contains multiple pieces of information that would be forced to share a confidence score. For example, the build_as_code_check entries contain both ci_service_name and deploy_command which are derived by different means and hence may have different levels of confidence, which cannot be expressed in the current schema. This could be fixed this by splitting the build_as_code_check and similar tables into smaller tables with more granularity of information. Are you intending to do that in later changes?

[behnazh-w]

Under this new schema, the confidence score is recorded for a check_facts entry, which currently contains multiple pieces of information that would be forced to share a confidence score. For example, the build_as_code_check entries contain both ci_service_name and deploy_command which are derived by different means and hence may have different levels of confidence, which cannot be expressed in the current schema. This could be fixed this by splitting the build_as_code_check and similar tables into smaller tables with more granularity of information. Are you intending to do that in later changes?

For this particular example, I think of deploy_command as the main result of the build_as_code_check , which can have different confidence scores based on the analysis. The ci_service_name fact, however, is an informational column that shows in which CI configuration the deploy command was found. So, I don't see it necessary to split the table in this case. But if a check can generate more than one fact, and each fact needs to have a different score, I agree that splitting to two smaller tables would solve the problem.

[nathanwn]

I think the PR should be good to merge.
Thanks for the PR.

[benmss]

Looks good to me.