clients

Documentation

Overview

Package clients defines the interface for RepoClient and related structs.

Index

• Constants
• Variables
• type BadgeLevel
  • func (badge BadgeLevel) String() string
• type BadgeResponse
  • func ParseBadgeResponseFromJSON(data []byte) ([]BadgeResponse, error)
  • func (resp BadgeResponse) AsJSON() ([]byte, error)
• type BranchProtectionRule
• type BranchRef
• type CIIBestPracticesClient
  • func BlobCIIBestPracticesClient(bucketURL string) CIIBestPracticesClient
  • func DefaultCIIBestPracticesClient() CIIBestPracticesClient
• type CheckRun
• type CheckRunApp
• type Commit
• type Issue
• type IssueComment
• type Label
• type Language
• type LanguageName
• type License
• type PullRequest
• type PullRequestReviewRule
• type Release
• type ReleaseAsset
• type Repo
• type RepoAssociation
  • func (r RepoAssociation) Gte(val RepoAssociation) bool
  • func (r RepoAssociation) String() string
• type RepoClient
• type Review
• type SearchCommitsOptions
• type SearchRequest
• type SearchResponse
• type SearchResult
• type Status
• type StatusChecksRule
• type User
• type VulnerabilitiesClient
  • func DefaultVulnerabilitiesClient() VulnerabilitiesClient
• type VulnerabilitiesResponse
• type Vulnerability
• type Webhook
• type WorkflowRun

Constants

const HeadSHA = "HEAD"

HeadSHA is default commitSHA value used to denote git HEAD.

Variables

var ErrUnsupportedFeature = errors.New("unsupported feature")

ErrUnsupportedFeature indicates an API that is not supported by the client.

Types

type BadgeLevel

type BadgeLevel uint

BadgeLevel corresponds to CII-Best-Practices badge levels. https://www.bestpractices.dev/en

const (
	// Unknown or non-parsable CII Best Practices badge.
	Unknown BadgeLevel = iota
	// NotFound represents when CII Best Practices returns an empty response for a project.
	NotFound
	// InProgress state of CII Best Practices badge.
	InProgress
	// Passing level for CII Best Practices badge.
	Passing
	// Silver level for CII Best Practices badge.
	Silver
	// Gold level for CII Best Practices badge.
	Gold
)

func (BadgeLevel) String

func (badge BadgeLevel) String() string

String returns a string value for BadgeLevel enum.

type BadgeResponse

type BadgeResponse struct {
	BadgeLevel string `json:"badge_level"`
}

BadgeResponse struct is used to read/write CII Best Practices badge data.

func ParseBadgeResponseFromJSON

func ParseBadgeResponseFromJSON(data []byte) ([]BadgeResponse, error)

ParseBadgeResponseFromJSON parses input []byte value into []BadgeResponse.

func (BadgeResponse) AsJSON

func (resp BadgeResponse) AsJSON() ([]byte, error)

AsJSON outputs BadgeResponse struct in JSON format.

type BranchProtectionRule

type BranchProtectionRule struct {
	RequiredPullRequestReviews PullRequestReviewRule
	AllowDeletions             *bool
	AllowForcePushes           *bool
	RequireLinearHistory       *bool
	EnforceAdmins              *bool
	RequireLastPushApproval    *bool
	CheckRules                 StatusChecksRule
}

BranchProtectionRule captures the settings enabled on a branch for security.

type BranchRef

type BranchRef struct {
	Name                 *string
	Protected            *bool
	BranchProtectionRule BranchProtectionRule
}

BranchRef represents a single branch reference and its protection rules.

type CIIBestPracticesClient

type CIIBestPracticesClient interface {
	GetBadgeLevel(ctx context.Context, uri string) (BadgeLevel, error)
}

CIIBestPracticesClient interface returns the BadgeLevel for a repo URL.

func BlobCIIBestPracticesClient

func BlobCIIBestPracticesClient(bucketURL string) CIIBestPracticesClient

BlobCIIBestPracticesClient returns a blob-based implementation of the interface.

func DefaultCIIBestPracticesClient

func DefaultCIIBestPracticesClient() CIIBestPracticesClient

DefaultCIIBestPracticesClient returns http-based implementation of the interface.

type CheckRun

type CheckRun struct {
	Status     string
	Conclusion string
	URL        string
	App        CheckRunApp
}

CheckRun is a single instance of a VCS CheckRun.

type CheckRunApp

type CheckRunApp struct {
	Slug string
}

CheckRunApp is the app running the Check.

type Commit

type Commit struct {
	CommittedDate          time.Time
	Message                string
	SHA                    string
	AssociatedMergeRequest PullRequest
	Committer              User
}

Commit represents a Git commit.

type Issue

type Issue struct {
	URI               *string
	CreatedAt         *time.Time
	Author            *User
	AuthorAssociation *RepoAssociation
	Comments          []IssueComment
}

Issue represents a thread like GitHub issue comment thread.

type IssueComment

type IssueComment struct {
	CreatedAt         *time.Time
	Author            *User
	AuthorAssociation *RepoAssociation
}

IssueComment represents a comment on an issue.

type Label

type Label struct {
	Name string
}

Label represents a PR label.

type Language

type Language struct {
	// Name is the name of this language.
	Name LanguageName

	// NumLines is the total number of code lines of this language in the repo.
	NumLines int
}

Language represents a customized struct for languages used by clients. A language could be a programming language, or more general, such as Dockerfile, CMake, HTML, YAML, etc.

type LanguageName

type LanguageName string

LanguageName is the name of a language, a customized type of string.

const (
	// Go: https://go.dev/
	Go LanguageName = "go"

	// Python: https://www.python.org/
	Python LanguageName = "python"

	// JavaScript: https://www.javascript.com/
	JavaScript LanguageName = "javascript"

	// C++: https://cplusplus.com/
	Cpp LanguageName = "c++"

	// C: https://www.open-std.org/jtc1/sc22/wg14/
	C LanguageName = "c"

	// TypeScript: https://www.typescriptlang.org/
	TypeScript LanguageName = "typescript"

	// Java: https://www.java.com/en/
	Java LanguageName = "java"

	// C#: https://docs.microsoft.com/en-us/dotnet/csharp/
	CSharp LanguageName = "c#"

	// Ruby: https://www.ruby-lang.org/
	Ruby LanguageName = "ruby"

	// PHP: https://www.php.net/
	PHP LanguageName = "php"

	// Starlark: https://github.com/bazelbuild/starlark
	StarLark LanguageName = "starlark"

	// Scala: https://www.scala-lang.org/
	Scala LanguageName = "scala"

	// Kotlin: https://kotlinlang.org/
	Kotlin LanguageName = "kotlin"

	// Swift: https://github.com/apple/swift
	Swift LanguageName = "swift"

	// Rust: https://github.com/rust-lang/rust
	Rust LanguageName = "rust"

	// CMake: https://cmake.org/
	CMake LanguageName = "cmake"

	// Dockerfile: https://docs.docker.com/engine/reference/builder/
	Dockerfile LanguageName = "dockerfile"

	// Haskell: https://www.haskell.org/
	Haskell LanguageName = "haskell"

	// Other indicates other languages not listed by the GitHub API.
	Other LanguageName = "other"
)

TODO: retrieve all languages supported by GitHub, or add one manually if needed. Currently, this is still an incomplete list of languages.

type License

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

License represents a customized struct for licenses used by clients. from pkg.go.dev/github.com/google/go-github/github#RepositoryLicense.

type PullRequest

type PullRequest struct {
	Number   int
	MergedAt time.Time
	HeadSHA  string
	Author   User
	Labels   []Label
	Reviews  []Review
	MergedBy User
}

PullRequest struct represents a PR as returned by RepoClient.

type PullRequestReviewRule

type PullRequestReviewRule struct {
	RequiredApprovingReviewCount *int32
	DismissStaleReviews          *bool
	RequireCodeOwnerReviews      *bool
}

PullRequestReviewRule captures settings on a PullRequest.

type Release

type Release struct {
	TagName         string
	URL             string
	TargetCommitish string
	Assets          []ReleaseAsset
}

Release represents a release version of a package/repo.

type ReleaseAsset

type ReleaseAsset struct {
	Name string
	URL  string
}

ReleaseAsset is part of the Release bundle.

type Repo

type Repo interface {
	URI() string
	Host() string
	String() string
	IsValid() error
	Metadata() []string
	AppendMetadata(metadata ...string)
}

Repo interface uniquely identifies a repo.

type RepoAssociation

type RepoAssociation uint32

RepoAssociation is how a user is associated with a repository.

const (
	// Mannequin: Author is a placeholder for an unclaimed user.
	RepoAssociationMannequin RepoAssociation = iota
	// None: Author has no association with the repository.
	// NoPermissions: (GitLab).
	RepoAssociationNone
	// FirstTimer: Author has not previously committed to the VCS.
	RepoAssociationFirstTimer
	// FirstTimeContributor: Author has not previously committed to the repository.
	// MinimalAccessPermissions: (Gitlab).
	RepoAssociationFirstTimeContributor
	// Contributor: Author has been a contributor to the repository.
	RepoAssociationContributor
	// Collaborator: Author has been invited to collaborate on the repository.
	RepoAssociationCollaborator
	// Member: Author is a member of the organization that owns the repository.
	// DeveloperAccessPermissions: (GitLab).
	RepoAssociationMember
	// Maintainer: Author is part of the maintenance team for the repository (GitLab).
	RepoAssociationMaintainer
	// Owner: Author is the owner of the repository.
	// (Owner): (GitLab).
	RepoAssociationOwner
)

Values taken from https://docs.github.com/en/graphql/reference/enums#commentauthorassociation. Additional values may be added in the future for non-Github projects. NOTE: Values are present in increasing order of privilege. If adding new values maintain the order of privilege to ensure Gte() functionality is preserved.

func (RepoAssociation) Gte

func (r RepoAssociation) Gte(val RepoAssociation) bool

Gte is >= comparator for RepoAssociation enum.

func (RepoAssociation) String

func (r RepoAssociation) String() string

String returns an string value for RepoAssociation enum.

type RepoClient

type RepoClient interface {
	InitRepo(repo Repo, commitSHA string, commitDepth int) error
	URI() string
	IsArchived() (bool, error)
	ListFiles(predicate func(string) (bool, error)) ([]string, error)
	// Returns an absolute path to the local repository
	// in the format that matches the local OS
	LocalPath() (string, error)
	GetFileContent(filename string) ([]byte, error)
	GetBranch(branch string) (*BranchRef, error)
	GetCreatedAt() (time.Time, error)
	GetDefaultBranchName() (string, error)
	GetDefaultBranch() (*BranchRef, error)
	GetOrgRepoClient(context.Context) (RepoClient, error)
	ListCommits() ([]Commit, error)
	ListIssues() ([]Issue, error)
	ListLicenses() ([]License, error)
	ListReleases() ([]Release, error)
	ListContributors() ([]User, error)
	ListSuccessfulWorkflowRuns(filename string) ([]WorkflowRun, error)
	ListCheckRunsForRef(ref string) ([]CheckRun, error)
	ListStatuses(ref string) ([]Status, error)
	ListWebhooks() ([]Webhook, error)
	ListProgrammingLanguages() ([]Language, error)
	Search(request SearchRequest) (SearchResponse, error)
	SearchCommits(request SearchCommitsOptions) ([]Commit, error)
	Close() error
}

RepoClient interface is used by Scorecard checks to access a repo.

type Review

type Review struct {
	Author *User
	State  string
}

Review represents a PR review.

type SearchCommitsOptions

type SearchCommitsOptions struct {
	Author string
}

SearchCommitsOptions represents the parameters in the search commit query.

type SearchRequest

type SearchRequest struct {
	Query    string
	Filename string
	Path     string
}

SearchRequest queries a repo for `Query`. If `Filename` is provided, only matching filenames are queried. If `Path` is provided, only files with matching paths are queried.

type SearchResponse

type SearchResponse struct {
	Results []SearchResult
	Hits    int
}

SearchResponse returns the results from a search request on a repo.

type SearchResult

type SearchResult struct {
	Path string
}

SearchResult represents a matching result from the search query.

type Status

type Status struct {
	State     string
	Context   string
	URL       string
	TargetURL string
}

Status for a Git object/ref.

type StatusChecksRule

type StatusChecksRule struct {
	UpToDateBeforeMerge  *bool
	RequiresStatusChecks *bool
	Contexts             []string
}

StatusChecksRule captures settings on status checks.

type User

type User struct {
	Login            string
	Companies        []string
	Organizations    []User
	NumContributions int
	ID               int64
	IsBot            bool
}

User represents a Git user.

type VulnerabilitiesClient

type VulnerabilitiesClient interface {
	ListUnfixedVulnerabilities(
		context context.Context,
		commit string,
		localDir string,
	) (VulnerabilitiesResponse, error)
}

VulnerabilitiesClient checks for vulnerabilities in vuln DB.

func DefaultVulnerabilitiesClient

func DefaultVulnerabilitiesClient() VulnerabilitiesClient

DefaultVulnerabilitiesClient returns a new OSV Vulnerabilities client.

type VulnerabilitiesResponse

type VulnerabilitiesResponse struct {
	Vulnerabilities []Vulnerability
}

VulnerabilitiesResponse is the response from the vuln DB.

type Vulnerability

type Vulnerability struct {
	ID      string
	Aliases []string
}

Vulnerability uniquely identifies a reported security vuln.

type Webhook

type Webhook struct {
	Path           string
	ID             int64
	UsesAuthSecret bool
}

Webhook represents VCS Webhook.

type WorkflowRun

type WorkflowRun struct {
	HeadSHA *string `json:"head_sha"`
	URL     string
}

WorkflowRun represents VCS WorkflowRun.