diffx

Documentation

Overview

Package diffx computes the semantic difference between two lockfiles.

Index

• type Change
• type FileDiff
  • func Diff(oldF, newF *lock.File) FileDiff
  • func Filter(diffs []FileDiff, patterns string) []FileDiff
• type Kind
• type ReleaseNote
• type Summary
  • func Summarize(diffs []FileDiff) Summary
• type Vuln

Types

type Change

type Change struct {
	Name        string     `json:"name"`
	Ecosystem   string     `json:"ecosystem"`
	Kind        Kind       `json:"kind"`
	Old         []string   `json:"old,omitempty"`
	New         []string   `json:"new,omitempty"`
	Level       vers.Level `json:"-"`
	LevelString string     `json:"level,omitempty"`

	// Why the package is in the tree, when the lockfile records its
	// dependency graph. Origin is "direct", "transitive" or "" (unknown).
	// Via is the chain of dependencies from a direct dependency down to
	// (but excluding) this package, e.g. ["react-scripts", "webpack"].
	Origin string   `json:"origin,omitempty"`
	Via    []string `json:"via,omitempty"`

	// Filled in by the OSV layer.
	IntroducedVulns []Vuln `json:"introduced_vulns,omitempty"` // affect new, not old
	FixedVulns      []Vuln `json:"fixed_vulns,omitempty"`      // affected old, not new
	ExistingVulns   []Vuln `json:"existing_vulns,omitempty"`   // affect both

	// Filled in by the deps.dev layer (registry metadata for the
	// version this change introduces).
	PublishedAt      string `json:"published_at,omitempty"` // RFC3339, UTC
	AgeDays          int    `json:"age_days,omitempty"`
	Fresh            bool   `json:"fresh,omitempty"` // younger than the cooldown window
	Deprecated       bool   `json:"deprecated,omitempty"`
	DeprecatedReason string `json:"deprecated_reason,omitempty"`

	// Unlisted: at least one incoming version is missing from the
	// registry metadata (deps.dev) even though other versions of the
	// same package are listed. That is what an unpublished or deleted
	// release looks like — registries pull malicious versions, so a
	// lockfile that still pins one is a red flag. (A release published
	// minutes ago may also not be indexed yet.)
	Unlisted         bool     `json:"unlisted,omitempty"`
	UnlistedVersions []string `json:"unlisted_versions,omitempty"`

	// ScriptsAdded: the outgoing version ran no install scripts, the
	// incoming one does (npm only; preinstall/install/postinstall, per
	// the registry's hasInstallScript). Adding execution-on-install in
	// an ordinary-looking bump is how several real npm supply-chain
	// attacks shipped their payload. ScriptedVersions lists the
	// incoming versions that carry scripts.
	ScriptsAdded     bool     `json:"install_scripts_added,omitempty"`
	ScriptedVersions []string `json:"scripted_versions,omitempty"`

	// ProvenanceDropped: every known outgoing version of this package
	// was published with sigstore provenance attestations, the incoming
	// one wasn't (npm, PyPI, crates.io). Legitimate CI keeps attesting; a stolen
	// publish token can publish but cannot make the pipeline attest,
	// so a silent drop is worth a look before trusting the release.
	// UnattestedVersions lists the incoming versions without provenance.
	ProvenanceDropped  bool     `json:"provenance_dropped,omitempty"`
	UnattestedVersions []string `json:"unattested_versions,omitempty"`

	// NonRegistry: the lockfile says this package doesn't come from the
	// public registry (workspace member, path/git dependency). Suppresses
	// the unlisted flag; not serialized.
	NonRegistry bool `json:"-"`

	// License strings as the registry reports them (per side), and
	// whether the bump changes the license. Only set when deps.dev
	// knows both sides.
	OldLicense     string `json:"old_license,omitempty"`
	NewLicense     string `json:"new_license,omitempty"`
	LicenseChanged bool   `json:"license_changed,omitempty"`

	// Filled in by the changelog layer: the upstream repository and, when
	// both versions match real tags there, links that are verified not
	// to 404.
	SourceRepo string `json:"source_repo,omitempty"`
	CompareURL string `json:"compare_url,omitempty"` // upstream diff old → new
	ReleaseURL string `json:"release_url,omitempty"` // release/tag page for new

	// Filled in by the release-notes layer (opt-in via -changelogs):
	// upstream release notes covering the versions this bump pulls in,
	// newest first.
	ReleaseNotes []ReleaseNote `json:"release_notes,omitempty"`
}

Change describes what happened to one package.

type FileDiff

type FileDiff struct {
	Path      string   `json:"path"`
	Kind      string   `json:"lockfile"`
	Ecosystem string   `json:"ecosystem"`
	Changes   []Change `json:"changes"`
}

FileDiff is the set of changes within one lockfile.

func Diff

func Diff(oldF, newF *lock.File) FileDiff

Diff compares two parsed lockfiles (either may be nil for created/deleted).

func Filter

func Filter(diffs []FileDiff, patterns string) []FileDiff

Filter keeps only the changes whose package name — or any package in their via chain — matches one of the comma-separated glob patterns. Matching is case-insensitive; '*' matches any run of characters (including '/', so "*sys*" matches "golang.org/x/sys") and '?' matches one character. Matching via chains means "-only jiff" also shows every transitive change that jiff dragged in.

type Kind

type Kind string

Kind of change for a single package.

const (
	Added      Kind = "added"
	Removed    Kind = "removed"
	Upgraded   Kind = "upgraded"
	Downgraded Kind = "downgraded"
	Changed    Kind = "changed" // multi-version set changed
)

type ReleaseNote

type ReleaseNote struct {
	Tag     string `json:"tag"`
	Title   string `json:"title,omitempty"`
	URL     string `json:"url"`
	Excerpt string `json:"excerpt,omitempty"`
}

ReleaseNote is one upstream release's notes, excerpted.

type Summary

type Summary struct {
	Total, Major, Minor, Patch, Added, Removed, Downgraded int
	VulnsIntroduced, VulnsFixed, VulnsExisting             int
	Fresh, Deprecated, LicenseChanged, Unlisted            int
	ScriptsAdded                                           int // npm bumps that newly run install scripts
	ProvenanceDropped                                      int // npm bumps that silently stop attesting provenance
	Direct, Transitive                                     int // 0/0 when the formats record no graph
}

Summary aggregates counts across file diffs.

func Summarize

func Summarize(diffs []FileDiff) Summary

Summarize computes totals for a set of file diffs.

type Vuln

type Vuln struct {
	ID       string `json:"id"`
	Summary  string `json:"summary,omitempty"`
	Severity string `json:"severity,omitempty"`
	URL      string `json:"url,omitempty"`
}

Vuln is a known vulnerability reference.