repometrics

README

repometrics

Package repometrics provides functionality to gather and analyze metrics from software repositories.

It collects various metrics and information including:

• Basic repository information (name, URL, creation date)
• Project status (CNCF status, Kubernetes SIG status)
• License information
• Version information
• Security vulnerabilities
• Activity metrics:
  • Commit frequency
  • Release frequency
  • Contributor statistics
  • Issue and PR activity
  • Community engagement (stars, forks)

The information is used for individual project analytics as well as for more elaborate analytics of the product and the way the product is produced.

Documentation

Overview

Package repometrics provides functionality to analyze software repositories and gather metrics about their health, activity, and security status.

It can collect information from multiple sources including GitHub repositories, CNCF landscape data, and security vulnerability scans. The collected metrics provide insights into project activity, community engagement, release patterns, and security status.

The package is particularly useful for: - Evaluating project health and maintenance status - Understanding community engagement and contribution patterns - Monitoring security vulnerabilities - Analyzing release frequency and version management - Tracking project growth and adoption metrics

Index

• type CVE
• type Contributor
• type ExtRefs
• type Metrics
  • func New(t RepoType) (*Metrics, error)
  • func (m *Metrics) ProjectAge() time.Duration
  • func (m *Metrics) ScanVulnerabilities(ctx context.Context, s Scanner) error
  • func (m *Metrics) UpdateCNCFStatus(opts UpdateCNCFOptions) error
  • func (m *Metrics) UpdateGitHub(ctx context.Context, client *github.Client, owner, repository string) error
• type Release
• type ReleaseMetrics
  • func CalculateReleaseMetrics(firstRelease, lastRelease *time.Time, totalReleases int) ReleaseMetrics
• type RepoType
  • func (t RepoType) IsValid() bool
• type Scanner
• type Stats
  • func NewStats() *Stats
• type UpdateCNCFOptions

Types

type CVE

type CVE struct {
	Vulnerability  vul.ID   `json:"id"`             // the Vulnerability
	Exploitability string   `json:"exploitability"` // the Exploitability not correct type yet
	SBOMs          []string `json:"sboms"`          // the SBOMs not correct type yet
}

CVE is an assembly of the Vulnerability, Exploitability and SBOMs

type Contributor

type Contributor struct {
	Name    string `json:"name"`
	URL     string `json:"url"`
	Commits int    `json:"commits"`
}

Contributor represents a contributor to a repository

type ExtRefs

type ExtRefs struct {
	SBOMCDX string `json:"sbomCDX"`
	VEXCDX  string `json:"vexCDX"`
	VULNCDX string `json:"vulnerabilityCDX"`
	VULNMD  string `json:"vulnerabilityMD"`
	Latest  bool   `json:"actual"`
}

ExtRefs is information pointing to the SBOM, VEX and Vulnerabilities files that exists.

type Metrics

type Metrics struct {
	Name                string     `json:"name"`                 // Name of the repository
	Type                RepoType   `json:"type"`                 // Type of the repository
	URL                 string     `json:"url"`                  // URL of the repository
	CreatedAt           *time.Time `json:"created_at"`           // Creation timestamp of the repository
	IsCNCF              bool       `json:"is_cncf"`              // True if the repository is part of CNCF
	CNCFStatus          string     `json:"cncf_status"`          // CNCF status of the repository
	IsKubernetesSIG     bool       `json:"is_kubernetes_sig"`    // True if the repository is a Kubernetes SIG project
	IsApache            bool       `json:"is_apache"`            // True if the repository is an Apache project
	BackingOrganization string     `json:"backing_organization"` // Organization backing the repository
	License             string     `json:"license"`              // License of the repository

	Version                        string     `json:"version"`            // The desired version to work with
	VersionCreatedAt               *time.Time `json:"version_created_at"` // Creation timestamp of the repository version
	VersionCriticalVulnerabilities int        `json:"criticals"`
	VersionHighVulnerabilities     int        `json:"highs"`
	VersionMediumVulnerabilities   int        `json:"mediums"`
	VersionLowVulnerabilities      int        `json:"lows"`

	FilteredVersionCriticalVulnerabilities int `json:"filteredCriticals"`
	FilteredVersionHighVulnerabilities     int `json:"filteredHighs"`
	FilteredVersionMediumVulnerabilities   int `json:"filteredMediums"`
	FilteredVersionLowVulnerabilities      int `json:"filteredLows"`

	FixedVersionCriticalVulnerabilities int `json:"fixedCriticals"`
	FixedVersionHighVulnerabilities     int `json:"fixedHighs"`
	FixedVersionMediumVulnerabilities   int `json:"fixedMediums"`
	FixedVersionLowVulnerabilities      int `json:"fixedLows"`

	LatestVersion                        string `json:"recentVersion"` // Current version of the repository
	LatestVersionCriticalVulnerabilities int    `json:"latestCriticals"`
	LatestVersionHighVulnerabilities     int    `json:"latestHighs"`
	LatestVersionMediumVulnerabilities   int    `json:"latestMediums"`
	LatestVersionLowVulnerabilities      int    `json:"latestLows"`

	Performance     string                   `json:"performance"`     // Performance of the repository
	Vulnerabilities []types.VulnerabilityCDX `json:"vulnerabilities"` // Vulnerabilities found in the repository
	Vex             []types.VEXCDX           `json:"vex"`             // Exploits found in the repository
	Stats           *Stats                   `json:"stats"`           // Statistics of the repository
	Conclusion      string                   `json:"conclusion"`      // Conclusion of the exploration
}

Metrics represents the metrics of a repository

func New

func New(t RepoType) (*Metrics, error)

New creates a new Metrics

func (*Metrics) ProjectAge

func (m *Metrics) ProjectAge() time.Duration

ProjectAge returns the age of the project

func (*Metrics) ScanVulnerabilities

func (m *Metrics) ScanVulnerabilities(ctx context.Context, s Scanner) error

ScanVulnerabilities scans for vulnerabilities and updates the metrics

func (*Metrics) UpdateCNCFStatus

func (m *Metrics) UpdateCNCFStatus(opts UpdateCNCFOptions) error

UpdateCNCFStatus updates the CNCF status of the repository

func (*Metrics) UpdateGitHub

func (m *Metrics) UpdateGitHub(ctx context.Context, client *github.Client, owner, repository string) error

UpdateGitHub updates the metrics using data from a GitHub repository

type Release

type Release struct {
	AssetsURL   string    `json:"assets_url,omitempty"`   // URL of the release assets.
	Date        time.Time `json:"date"`                   // Date of the release.
	Name        string    `json:"name"`                   // Name of the release.
	TarballURL  string    `json:"tarball_url,omitempty"`  // URL of the release tarball.
	VulnRefs    ExtRefs   `json:"vuln_refs,omitempty"`    // List of references to SBOM, VEX and Vulnerabilities.
	MissingRefs ExtRefs   `json:"missing_refs,omitempty"` // List of missing references to SBOM, VEX and Vulnerabilities.
	ReleaseURL  string    `json:"release_url,omitempty"`  // URL of the release.
	UploadURL   string    `json:"uploaded,omitempty"`     // URL of the release upload.
}

Relase represents a release from a repository

type ReleaseMetrics

type ReleaseMetrics struct {
	PerDay   float64
	PerWeek  float64
	PerMonth float64
	PerYear  float64
}

func CalculateReleaseMetrics

func CalculateReleaseMetrics(firstRelease, lastRelease *time.Time, totalReleases int) ReleaseMetrics

CalculateReleaseMetrics calculates the release metrics based on the first and last release dates and the total number of releases.

type RepoType

type RepoType string

const (
	RepoTypeGitHub RepoType = "github"
)

func (RepoType) IsValid

func (t RepoType) IsValid() bool

type Scanner

type Scanner interface {
	// Scan scans for vulnerabilities
	Scan(context.Context) ([]types.VulnerabilityCDX, error)
}

Scanner is the interface for vulnerability scanners

type Stats

type Stats struct {
	LastCommit                *time.Time `json:"last_commit"`                   // Date of the last commit.
	CommitsPerMonth6M         int        `json:"commits_per_month_6m"`          // Number of commits in the last 6 months.
	VerifiedCommitsPerMonth6M int        `json:"verified_commits_per_month_6m"` // Number of verified commits in the last 6 months.
	Contributors1Y            int        `json:"contributors_1y"`               // Number of contributors in the last year.
	FirstRelease              *time.Time `json:"first_release"`                 // Date of the first release.
	LastRelease               *time.Time `json:"last_release"`                  // Date of the last release.
	NoOfReleases              int        `json:"no_of_releases"`                // Total number of releases.
	ReleasesPerDay            float64    `json:"releases_per_day"`              // Number of releases per day.
	ReleasesPerWeek           float64    `json:"releases_per_week"`             // Number of releases per week.
	ReleasesPerMonth          float64    `json:"releases_per_month"`            // Number of releases per month.
	ReleasesPerYear           float64    `json:"releases_per_year"`             // Number of releases per year.
	Releases                  []Release  `json:"releases"`                      // List of releases.

	OpenedIssuesNow   int `json:"open_issues_now"`     // Number of currently open issues.
	ClosedIssuesNow   int `json:"closed_issues_now"`   // Number of currently closed issues.
	OpenedPRsNow      int `json:"opened_prs_now"`      // Number of pull requests opened in the last month.
	ClosedPRsNow      int `json:"closed_prs_now"`      // Number of pull requests closed in the last month.
	OpenedFeaturesNow int `json:"opened_features_now"` // Number of issues opened in the last month.
	ClosedFeaturesNow int `json:"closed_features_now"` // Number of issues closed in the last month.
	OpenedBugsNow     int `json:"opened_bugs_now"`     // Number of pull requests opened in the last month.
	ClosedBugsNow     int `json:"closed_bugs_now"`     // Number of pull requests closed in the last month.

	OpenedIssues1M   int `json:"opened_issues_1m"`   // Number of issues opened in the last month.
	ClosedIssues1M   int `json:"closed_issues_1m"`   // Number of issues closed in the last month.
	OpenedPRs1M      int `json:"opened_prs_1m"`      // Number of pull requests opened in the last month.
	ClosedPRs1M      int `json:"closed_prs_1m"`      // Number of pull requests closed in the last month.
	OpenedFeatures1M int `json:"opened_features_1m"` // Number of issues opened in the last month.
	ClosedFeatures1M int `json:"closed_features_1m"` // Number of issues closed in the last month.
	OpenedBugs1M     int `json:"opened_bugs_1m"`     // Number of pull requests opened in the last month.
	ClosedBugs1M     int `json:"closed_bugs_1m"`     // Number of pull requests closed in the last month.

	OpenedIssues3M   int `json:"opened_issues_3m"`   // Number of issues opened in the last 3 months.
	ClosedIssues3M   int `json:"closed_issues_3m"`   // Number of issues closed in the last 3 months.
	OpenedPRs3M      int `json:"opened_prs_3m"`      // Number of pull requests opened in the last 3 months.
	ClosedPRs3M      int `json:"closed_prs_3m"`      // Number of pull requests closed in the last 3 months.
	OpenedFeatures3M int `json:"opened_features_3m"` // Number of issues opened in the last 3 months.
	ClosedFeatures3M int `json:"closed_features_3m"` // Number of issues closed in the last 3 months.
	OpenedBugs3M     int `json:"opened_bugs_3m"`     // Number of pull requests opened in the last 3 months.
	ClosedBugs3M     int `json:"closed_bugs_3m"`     // Number of pull requests closed in the last 3 months.

	OpenedIssues6M   int `json:"opened_issues_6m"`   // Number of issues opened in the last 6 months.
	ClosedIssues6M   int `json:"closed_issues_6m"`   // Number of issues closed in the last 6 months.
	OpenedPRs6M      int `json:"opened_prs_6m"`      // Number of pull requests opened in the last 6 months.
	ClosedPRs6M      int `json:"closed_prs_6m"`      // Number of pull requests closed in the last 6 months.
	OpenedFeatures6M int `json:"opened_features_6m"` // Number of issues opened in the last 6 months.
	ClosedFeatures6M int `json:"closed_features_6m"` // Number of issues closed in the last 6 months.
	OpenedBugs6M     int `json:"opened_bugs_6m"`     // Number of pull requests opened in the last 6 months.
	ClosedBugs6M     int `json:"closed_bugs_6m"`     // Number of pull requests closed in the last 6 months.

	OpenedIssues9M   int `json:"opened_issues_9m"`   // Number of issues opened in the last 9 months.
	ClosedIssues9M   int `json:"closed_issues_9m"`   // Number of issues closed in the last 9 months.
	OpenedPRs9M      int `json:"opened_prs_9m"`      // Number of pull requests opened in the last 9 months.
	ClosedPRs9M      int `json:"closed_prs_9m"`      // Number of pull requests closed in the last 9 months.
	OpenedFeatures9M int `json:"opened_features_9m"` // Number of issues opened in the last 9 months.
	ClosedFeatures9M int `json:"closed_features_9m"` // Number of issues closed in the last 9 months.
	OpenedBugs9M     int `json:"opened_bugs_9m"`     // Number of pull requests opened in the last 9 months.
	ClosedBugs9M     int `json:"closed_bugs_9m"`     // Number of pull requests closed in the last 9 months.

	OpenedIssues1Y   int `json:"opened_issues_1y"`   // Number of issues opened in the last year.
	ClosedIssues1Y   int `json:"closed_issues_1y"`   // Number of issues closed in the last year.
	OpenedPRs1Y      int `json:"opened_prs_1y"`      // Number of pull requests opened in the last year.
	ClosedPRs1Y      int `json:"closed_prs_1y"`      // Number of pull requests closed in the last year.
	OpenedFeatures1Y int `json:"opened_features_1y"` // Number of issues opened in the last year.
	ClosedFeatures1Y int `json:"closed_features_1y"` // Number of issues closed in the last year.
	OpenedBugs1Y     int `json:"opened_bugs_1y"`     // Number of pull requests opened in the last year.
	ClosedBugs1Y     int `json:"closed_bugs_1y"`     // Number of pull requests closed in the last year.

	Likes           int           `json:"likes"`             // Number of likes/hearts/stars.
	Forks           int           `json:"forks"`             // Number of forks.
	TopCommitters   []Contributor `json:"top_committers"`    // Top committers overall.
	TopCommitters1Y []Contributor `json:"top_committers_1y"` // Top committers in the last year.
	TopCommitters9M []Contributor `json:"top_committers_9m"` // Top committers in the last 9 months.
	TopCommitters6M []Contributor `json:"top_committers_6m"` // Top committers in the last 6 months.
	TopCommitters3M []Contributor `json:"top_committers_3m"` // Top committers in the last 3 months.
	TopCommitters1M []Contributor `json:"top_committers_1m"` // Top committers in the last 1 month.

	InactiveContributors1Y []Contributor `json:"inactive_contributors1Y"` // Inactive contributors.
	InactiveContributors9M []Contributor `json:"inactive_contributors9M"` // Inactive contributors.
	InactiveContributors6M []Contributor `json:"inactive_contributors6M"` // Inactive contributors.
	InactiveContributors3M []Contributor `json:"inactive_contributors3M"` // Inactive contributors.

	VulnerabilitiesIndex1Y int `json:"vulnerabilities_index_1y"` // Vulnerabilities index in the last year.
	VulnerabilitiesIndex9M int `json:"vulnerabilities_index_9m"` // Vulnerabilities index in the last 9 months.
	VulnerabilitiesIndex6M int `json:"vulnerabilities_index_6m"` // Vulnerabilities index in the last 6 months.
	VulnerabilitiesIndex3M int `json:"vulnerabilities_index_3m"` // Vulnerabilities index in the last 3 months.
	VulnerabilitiesIndex1M int `json:"vulnerabilities_index_1m"` // Vulnerabilities index in the last 1 month.

	ReleasesIndex1Y int `json:"releases_index_1y"` // Releases index in the last year.
	ReleasesIndex9M int `json:"releases_index_9m"` // Releases index in the last 9 months.
	ReleasesIndex6M int `json:"releases_index_6m"` // Releases index in the last 6 months.
	ReleasesIndex3M int `json:"releases_index_3m"` // Releases index in the last 3 months.
	ReleasesIndex1M int `json:"releases_index_1m"` // Releases index in the last 1 month.
}

Stats represents the metrics of a repository TODO: maybe separate these into individual structs.

func NewStats

func NewStats() *Stats

NewStats resets the statistics

type UpdateCNCFOptions

type UpdateCNCFOptions struct {
	Client             cncf.HTTPClient
	ProjectName        string
	ProjectRepoURL     string
	ProjectHomepageURL string
}

UpdateCNCFOptions represents the options for updating the CNCF status of a

ProjectName, ProjectRepoURL, and ProjectHomepageURL are used to find the project.

The order of precedence is: 1. ProjectRepoURL 2. ProjectHomepageURL 3. ProjectName (case-insensitive)