dependents

README

dependents

Go library for finding and ranking repositories that depend on a package. It uses enrichment for dependent package metadata and clone for local checkouts. Candidates are deduplicated by repository while retaining the package-level dependency relationships. The package supports Go 1.26 or later.

Install

go get github.com/git-pkgs/dependents

Usage

client, err := enrichment.NewEcosystemsClient()
if err != nil {
    log.Fatal(err)
}

candidates, err := dependents.DiscoverRepository(ctx, client,
    "https://github.com/acme/library", dependents.DiscoverOptions{})
if err != nil {
    log.Fatal(err)
}

kept, rejected := dependents.Filter(candidates, dependents.FilterOptions{
    ExcludeForks:    true,
    ExcludeArchived: true,
    ExcludeMirrors:  true,
    MaxAge:          2 * 365 * 24 * time.Hour,
})
for _, rejection := range rejected {
    log.Printf("skip %s: %s", rejection.Candidate.Repository, rejection.Reason)
}
ranked := dependents.Rank(kept, 10, nil)

Build accepts the package's neutral Group type when the caller already has dependent data. BuildEnrichmentCandidates adapts enrichment.RepositoryDependents directly.

DefaultScore favors source references and tests after checkout analysis. Callers can pass another ScoreFunc to Rank, so security exposure and contract-test selection can use different policies.

Analyze accepts any Checkout. CloneCheckout uses a direct checkout and supports full history for Hyrum, while CacheCheckout copies from a persistent git-pkgs/clone cache for Scrutineer. A caller that supplies Workdir or sets Keep receives the checkout path on each analyzed candidate for follow-up work. Set DetectNativeExtensions to record native-extension toolchains and their build commands, including Maturin, napi-rs, Neon, rb-sys, Rustler, and setuptools-rust.

After analysis, FilterOptions.RequireTests and RequireImports reproduce the contract-test eligibility used by downstream. Scrutineer can require upstream references without excluding repositories that have no conventional test files.

License

MIT

Documentation

Overview

Package dependents finds and ranks repositories that depend on a package.

Index

• Constants
• func DefaultScore(candidate Candidate) int64
• func Filter(candidates []Candidate, opts FilterOptions) ([]Candidate, []Rejection)
• func PopularityScore(candidate Candidate) int64
• type Analysis
  • func AnalyzeDirectory(root string, upstreams []string) (Analysis, error)
• type AnalysisFailure
• type AnalysisResult
  • func Analyze(ctx context.Context, candidates []Candidate, opts AnalyzeOptions) (AnalysisResult, error)
• type AnalyzeOptions
• type CacheCheckout
  • func (c CacheCheckout) Prepare(ctx context.Context, repository, destination string) (string, error)
• type Candidate
  • func Build(groups []Group) []Candidate
  • func BuildEnrichmentCandidates(groups []enrichment.RepositoryDependents) []Candidate
  • func DiscoverRepository(ctx context.Context, client RepositoryDependentsClient, repository string, ...) ([]Candidate, error)
  • func ExcludeRepositories(candidates []Candidate, repositories ...string) []Candidate
  • func Rank(candidates []Candidate, limit int, scorer ScoreFunc) []Candidate
• type Checkout
• type CheckoutFunc
  • func (f CheckoutFunc) Prepare(ctx context.Context, repository, destination string) (string, error)
• type CloneCheckout
  • func (c CloneCheckout) Prepare(ctx context.Context, repository, destination string) (string, error)
• type Dependent
• type DiscoverOptions
• type FilterOptions
• type Group
• type NativeExtension
• type Package
• type PackageRef
• type Rejection
• type Relationship
• type RepositoryDependentsClient
• type RepositoryMetadata
• type ScoreFunc

Constants

const (
	DefaultMaxPackages             = 25
	DefaultMaxDependentsPerPackage = 30
)

const (
	ReasonFork        = "fork"
	ReasonArchived    = "archived"
	ReasonMirror      = "mirror"
	ReasonStale       = "stale"
	ReasonNotAnalyzed = "not analyzed"
	ReasonNoTests     = "no tests"
	ReasonNoImports   = "no upstream references"
)

Functions

func DefaultScore

func DefaultScore(candidate Candidate) int64

DefaultScore favors repositories with source references and tests after analysis, with popularity as a tiebreaker. Before analysis it returns the popularity score.

func Filter

func Filter(candidates []Candidate, opts FilterOptions) ([]Candidate, []Rejection)

Filter applies repository health policy without changing candidates.

func PopularityScore

func PopularityScore(candidate Candidate) int64

PopularityScore returns registry downloads when available and otherwise uses dependent repository count.

Types

type Analysis

type Analysis struct {
	TestFiles        int
	ImportFiles      int
	NativeExtensions []NativeExtension
}

Analysis contains checkout-derived ranking signals and integrations.

func AnalyzeDirectory

func AnalyzeDirectory(root string, upstreams []string) (Analysis, error)

AnalyzeDirectory counts conventional test files and files whose content mentions at least one upstream package name.

type AnalysisFailure

type AnalysisFailure struct {
	Repository string
	Err        error
}

AnalysisFailure records one candidate that could not be checked out or scanned. The candidate remains in AnalysisResult.Candidates unchanged.

type AnalysisResult

type AnalysisResult struct {
	Candidates []Candidate
	Failures   []AnalysisFailure
}

AnalysisResult contains every candidate and any per-repository failures.

func Analyze

func Analyze(ctx context.Context, candidates []Candidate, opts AnalyzeOptions) (AnalysisResult, error)

Analyze checks out and scans each candidate. Individual repository failures are collected without stopping the remaining candidates.

type AnalyzeOptions

type AnalyzeOptions struct {
	Upstreams              []string
	Workdir                string
	Checkout               Checkout
	Keep                   bool
	DetectNativeExtensions bool
}

AnalyzeOptions controls checkout analysis.

type CacheCheckout

type CacheCheckout struct {
	Cache *gitclone.Cache
	Ref   string
}

CacheCheckout prepares job-local copies through a git-pkgs/clone cache.

func (CacheCheckout) Prepare

func (c CacheCheckout) Prepare(ctx context.Context, repository, destination string) (string, error)

type Candidate

type Candidate struct {
	Repository         string
	Packages           []Package
	Upstreams          []PackageRef
	Relationships      []Relationship
	RepositoryMetadata RepositoryMetadata
	Downloads          int64
	DependentRepos     int
	Analysis           Analysis
	Analyzed           bool
	Commit             string
	Directory          string
}

Candidate is one repository containing packages that depend on one or more upstream packages. Packages and Upstreams are deduplicated and sorted.

func Build

func Build(groups []Group) []Candidate

Build combines dependent packages by repository. Popularity values use the maximum reported by any package in the repository so a monorepo is not rewarded merely for publishing more packages.

func BuildEnrichmentCandidates

func BuildEnrichmentCandidates(groups []enrichment.RepositoryDependents) []Candidate

BuildEnrichmentCandidates converts enrichment results into repository-level candidates.

func DiscoverRepository

func DiscoverRepository(ctx context.Context, client RepositoryDependentsClient, repository string, opts DiscoverOptions) ([]Candidate, error)

DiscoverRepository fetches dependent packages for repository and combines packages from the same dependent repository into one candidate.

func ExcludeRepositories

func ExcludeRepositories(candidates []Candidate, repositories ...string) []Candidate

ExcludeRepositories returns a copy without candidates whose canonical repository URL appears in repositories.

func Rank

func Rank(candidates []Candidate, limit int, scorer ScoreFunc) []Candidate

Rank returns a ranked copy of candidates. A non-positive limit keeps all candidates. A nil scorer uses DefaultScore.

type Checkout

type Checkout interface {
	Prepare(context.Context, string, string) (string, error)
}

Checkout prepares repository at destination and returns its HEAD commit.

type CheckoutFunc

type CheckoutFunc func(context.Context, string, string) (string, error)

CheckoutFunc adapts a function to Checkout.

func (CheckoutFunc) Prepare

func (f CheckoutFunc) Prepare(ctx context.Context, repository, destination string) (string, error)

type CloneCheckout

type CloneCheckout struct {
	Retry gitclone.Retry
	Ref   string
	Full  bool
}

CloneCheckout prepares shallow checkouts with git-pkgs/clone. Set Full for full history or Ref to select a branch, tag, or commit.

func (CloneCheckout) Prepare

func (c CloneCheckout) Prepare(ctx context.Context, repository, destination string) (string, error)

type Dependent

type Dependent struct {
	Package
	Repository         string
	RepositoryMetadata RepositoryMetadata
}

Dependent associates a package with the repository that publishes it.

type DiscoverOptions

type DiscoverOptions struct {
	MaxPackages             int
	MaxDependentsPerPackage int
}

DiscoverOptions bounds the packages and dependents fetched from enrichment.

type FilterOptions

type FilterOptions struct {
	ExcludeForks    bool
	ExcludeArchived bool
	ExcludeMirrors  bool
	MaxAge          time.Duration
	Now             time.Time
	RequireAnalyzed bool
	RequireTests    bool
	RequireImports  bool
}

FilterOptions lets each consumer choose its repository eligibility policy. A zero MaxAge does not filter stale repositories. Missing push dates are retained.

type Group

type Group struct {
	Upstream   PackageRef
	Dependents []Dependent
}

Group contains the packages that depend on one upstream package.

type NativeExtension

type NativeExtension struct {
	Name         string
	BuildCommand string
}

NativeExtension describes a detected native-extension toolchain.

type Package

type Package struct {
	Name           string
	Ecosystem      string
	PURL           string
	RegistryURL    string
	LatestVersion  string
	Downloads      int64
	DependentRepos int
}

Package describes a dependent package published from a candidate repository.

type PackageRef

type PackageRef struct {
	Name      string
	Ecosystem string
	PURL      string
}

PackageRef identifies a package published by the repository whose dependents are being discovered.

type Rejection

type Rejection struct {
	Candidate Candidate
	Reason    string
}

Rejection records a candidate excluded by Filter and the first matching reason.

type Relationship

type Relationship struct {
	Upstream  PackageRef
	Dependent PackageRef
}

Relationship records one package-level dependency edge inside a candidate repository.

type RepositoryDependentsClient

type RepositoryDependentsClient interface {
	GetDependentsByRepositoryURL(context.Context, string, int, int) ([]enrichment.RepositoryDependents, error)
}

RepositoryDependentsClient is implemented by enrichment.EcosystemsClient.

type RepositoryMetadata

type RepositoryMetadata struct {
	Fork            bool
	Archived        bool
	MirrorURL       string
	SourceName      string
	PushedAt        time.Time
	StargazersCount int
	Language        string
}

RepositoryMetadata contains repository facts used by caller-selected filtering and ranking policies.

type ScoreFunc

type ScoreFunc func(Candidate) int64

ScoreFunc assigns a ranking score to a candidate.