✨ Add Additional Details to License Check

[shissam]

What kind of change does this PR introduce?

This is a proposed feature enhancement to the License Check which servers two purposes

• Provide specific details as to which license was detected

• Provide the basis to add gradation to license analysis

• PR title follows the guidelines defined in our pull request documentation

What is the current behavior?

License check looks in the repo for specific license files and some matching content. Score is either min or max depending if a file is found - regardless of the license content.

What is the new behavior (if this is a feature change)?**

• introduce clients/licenses.go which embodies this github api (similar to clients/languages.go) - it would be plural as it may come down to the point where gitlab returns multiple licenses for a repo (I have a real-world example).
• This github client would populate a structure like the following:

type License struct {
        Key      string // RepositoryLicense.GetLicense().GetKey()
        Name     string // RepositoryLicense.GetLicense().GetName()
        Path     string // RepositoryLicense.GetName()
        Size     int    // RepositoryLicense.GetSize()
        SPDXId   string // RepositoryLicense.GetLicense().GetSPDXID()
        Type     string // RepositoryLicense.GetType()
}

where (example from ossf/scorecard):

{
 Key:apache-2.0
 Name:Apache License 2.0
 Path:LICENSE
 Size:11356
 SPDXId:Apache-2.0 
Type:file
}

• modify checks/raw/license.go to follow one of two possible paths:
  -- pathOne try the repoClient (as in c.RepoClient.ListLicenses()), if a license is reported by github USE that and return
  -- pathTwo if the repoClient returns nil, continue with the legacy logic and return what is always returned
• there are a number of advantages to this approach:
  -- speedup: for github, my test of c.RepoClient.ListLicenses() returns in less than 5 seconds, when compared to other repos with many files (like torvalds/linux this check takes over a minute
  -- extensibility: this test with github is promising, and gitlab does appear to have a api for getting this information (https://docs.gitlab.com/ee/api/templates/licenses.html)
  -- confidence: using the github api for 'sensing' which specific license is in use I assume is higher (more review on their algorithm which might use NLP)--I tried a license on my site which changed the work Apache to Apacje in the complete Apache License 2.0 file and github still sensed it was APL-2.0 (very cool).
  -- standardization: I am encouraged by the use of the SPDXId in the github API, if it is true that gitlab using the same standard identifier for licenses - this would be great for the community
  -- usability: using scorecard to retrieve the specific license detected would a) make this information more readily available to the end-user; and b) would support develop pipelines that need to sense the license (by name) as a risk management activity without having to move to other means to acquire such license information
• with this approach, propose changing checker.LicenseData{}:

type License struct {
        Key      string // from clients.License.Key
        Name     string // from clients.License.Name
        Size     int    // clients.License.Size (Size maybe not here but in type File struct
        SPDXId   string // clients.License.SPDXId
        Attribution     AttributionType // license sourced from LicenseRepoAPI or ScorecardEngine
}

// one file contains one license.
type LicenseFile struct {
        License License
        File    File
}

// LicenseData contains the raw results
// for the License check.
// Some repos may have more than one license.
type LicenseData struct {
        LicenseFiles []LicenseFile
}

Which issue(s) this PR fixes

Fixes #1369

With a more complete proposal at https://github.com/ossf/scorecard/issues/1369#issuecomment-1304831531

Special notes for your reviewer

I would like to have a discussion with the owners/maintainer about idea for gradating the evaluation, with additional information from the repo API, that may lead to greater confidence in scores. This PR would take a step in that direction.

Does this PR introduce a user-facing change?

format=raw would have the entire LicenseData found by scorecard in the file or the repo API
format=[json|default] would have the rational for any such decided on gradation.

For user-facing changes, please add a concise, human-readable release note to
the release-note

(In particular, describe what changes users might need to make in their
application as a result of this pull request.)

[github-actions]

Integration tests success for
[1f55b7a]
(https://github.com/ossf/scorecard/actions/runs/3559735104)

[github-actions]

Integration tests success for
[1ef1703]
(https://github.com/ossf/scorecard/actions/runs/3565703124)

[github-actions]

Integration tests success for
[c1b7373]
(https://github.com/ossf/scorecard/actions/runs/3567344961)

[laurentsimon]

LGTM. Thanks for explaining everything in such details, and the amount of work you've put in this PR!