README
¶
contract
Package contract defines the core data types and interfaces for dependency comparison.
This package provides:
- PackageMap: A map for efficient O(1) lookup of package information
- PackageChange: Detailed information about how a package changed
- PkgWrapper and PkgVersion: Abstractions for package data from lock files
- Operation types: Semantic representation of what changed (added, removed, upgraded, etc.)
- Semver: Semantic version components (major, minor, patch, extra)
Types in this package are used as inputs to and outputs from the depsdiff.Diff function. They define the contract between package managers and the diff engine.
Types
type DiffMap
type DiffMap map[string]*PackageChange
DiffMap maps package names to information about what changed. Key is the package name (e.g., "vendor/package"), value is a pointer to PackageChange containing the operation type and version information.
type Operation
type Operation struct { ... }
Operation describes what changed about a package: the operation name and semantic version type.
Name indicates the type of change (addition, removal, upgrade, downgrade, etc.). SemverType indicates which semantic version component changed (for updated packages).
type OperationName
type OperationName string
OperationName describes what changed about a package (addition, removal, update direction).
Constants
const (
// AdditionOperation indicates a package was added (exists in current but not in previous).
AdditionOperation OperationName = "ADDITION"
// RemovalOperation indicates a package was removed (exists in previous but not in current).
RemovalOperation OperationName = "REMOVAL"
// UpgradeOperation indicates a package version was increased.
UpgradeOperation OperationName = "UPGRADE"
// DowngradeOperation indicates a package version was decreased.
DowngradeOperation OperationName = "DOWNGRADE"
// UnknownUpdateOperation indicates a package was updated but direction is unknown
// (typically for non-semver versions where comparison is not possible).
UnknownUpdateOperation OperationName = "UNKNOWN_UPDATE"
// NoChangeOperation indicates a package version has not changed.
NoChangeOperation OperationName = "NONE"
)
type OperationSemverType
type OperationSemverType string
OperationSemverType describes the semantic version component type for updated packages.
This indicates which semantic version component changed (e.g., MAJOR, MINOR, PATCH). It is only relevant for updated packages; for added and removed packages, the SemverType is SemverNoUpdate since only one version is available.
Constants
const (
// SemverMajorUpdate indicates the major version component differs between versions.
SemverMajorUpdate OperationSemverType = "MAJOR"
// SemverMinorUpdate indicates the minor version component differs between versions.
SemverMinorUpdate OperationSemverType = "MINOR"
// SemverPatchUpdate indicates the patch version component differs between versions.
SemverPatchUpdate OperationSemverType = "PATCH"
// SemverExtraUpdate indicates the extra/pre-release component differs between versions
// (major, minor, patch are equal but extra differs).
SemverExtraUpdate OperationSemverType = "EXTRA"
// SemverUnknownUpdate indicates the difference cannot be determined (e.g., one or both versions are non-semver).
SemverUnknownUpdate OperationSemverType = "UNKNOWN"
// SemverNoUpdate indicates no semantic version difference (used for added, removed, or unchanged packages).
SemverNoUpdate OperationSemverType = "NONE"
)
type PackageChange
type PackageChange struct { ... }
PackageChange contains detailed information about a package difference.
The Package field holds a reference to the package wrapper (agnostic of the package manager). See PkgWrapper for more information.
The Operation field indicates what changed (ADDITION, REMOVAL, UPGRADE, DOWNGRADE, etc.) and the semantic version type of the change (MAJOR, MINOR, PATCH, EXTRA, UNKNOWN, NONE).
PreviousVersion is only populated for updated packages (when Operation is UPGRADE or DOWNGRADE). For added and removed packages, PreviousVersion is empty (zero value).
type PackageMap
type PackageMap map[string]PkgWrapper
PackageMap holds package information for efficient lookup.
Key is the package name (e.g., "vendor/package"), value is a wrapper providing package details and helper methods. PackageMap is used as input to depsdiff.Diff to represent the state of dependencies at a point in time (typically parsed from a package lock file).
type PkgVersion
type PkgVersion struct { ... }
PkgVersion contains version information for a package.
Raw contains the exact version string as defined in the lock file. Label is the human-readable version representation. Semver is populated only if Raw is a valid semantic version, otherwise nil.
type PkgWrapper
type PkgWrapper interface { ... }
PkgWrapper is an interface that provides access to package metadata.
Implementations should provide information about a package from a lock file, including version, dependency type (regular/dev), and status information.
type Semver
type Semver struct { ... }
Semver represents semantic version components.
A semantic version follows the format MAJOR.MINOR.PATCH[+extra]. For example, version "1.2.3-beta" has Major=1, Minor=2, Patch=3, Extra="-beta".
This struct is only populated when a version string is determined to be valid semantic version format. See contract.PkgVersion.Semver.
Readme created from Go doc with goreadme
Documentation
¶
Overview ¶
Package contract defines the core data types and interfaces for dependency comparison.
This package provides:
- PackageMap: A map for efficient O(1) lookup of package information
- PackageChange: Detailed information about how a package changed
- PkgWrapper and PkgVersion: Abstractions for package data from lock files
- Operation types: Semantic representation of what changed (added, removed, upgraded, etc.)
- Semver: Semantic version components (major, minor, patch, extra)
Types in this package are used as inputs to and outputs from the depsdiff.Diff function. They define the contract between package managers and the diff engine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DiffMap ¶
type DiffMap map[string]*PackageChange
DiffMap maps package names to information about what changed. Key is the package name (e.g., "vendor/package"), value is a pointer to PackageChange containing the operation type and version information.
type Operation ¶
type Operation struct {
// Name describes the operation type (ADDITION, REMOVAL, UPGRADE, DOWNGRADE, UNKNOWN_UPDATE, NONE).
Name OperationName
// SemverType describes the semantic version component type for updated packages
// (MAJOR, MINOR, PATCH, EXTRA, UNKNOWN, NONE). Only relevant for updated packages.
SemverType OperationSemverType
}
Operation describes what changed about a package: the operation name and semantic version type.
Name indicates the type of change (addition, removal, upgrade, downgrade, etc.). SemverType indicates which semantic version component changed (for updated packages).
type OperationName ¶
type OperationName string
OperationName describes what changed about a package (addition, removal, update direction).
const ( // AdditionOperation indicates a package was added (exists in current but not in previous). AdditionOperation OperationName = "ADDITION" // RemovalOperation indicates a package was removed (exists in previous but not in current). RemovalOperation OperationName = "REMOVAL" // UpgradeOperation indicates a package version was increased. UpgradeOperation OperationName = "UPGRADE" // DowngradeOperation indicates a package version was decreased. DowngradeOperation OperationName = "DOWNGRADE" // UnknownUpdateOperation indicates a package was updated but direction is unknown // (typically for non-semver versions where comparison is not possible). UnknownUpdateOperation OperationName = "UNKNOWN_UPDATE" // NoChangeOperation indicates a package version has not changed. NoChangeOperation OperationName = "NONE" )
type OperationSemverType ¶
type OperationSemverType string
OperationSemverType describes the semantic version component type for updated packages.
This indicates which semantic version component changed (e.g., MAJOR, MINOR, PATCH). It is only relevant for updated packages; for added and removed packages, the SemverType is SemverNoUpdate since only one version is available.
const ( // SemverMajorUpdate indicates the major version component differs between versions. SemverMajorUpdate OperationSemverType = "MAJOR" // SemverMinorUpdate indicates the minor version component differs between versions. SemverMinorUpdate OperationSemverType = "MINOR" // SemverPatchUpdate indicates the patch version component differs between versions. SemverPatchUpdate OperationSemverType = "PATCH" // SemverExtraUpdate indicates the extra/pre-release component differs between versions // (major, minor, patch are equal but extra differs). SemverExtraUpdate OperationSemverType = "EXTRA" // SemverUnknownUpdate indicates the difference cannot be determined (e.g., one or both versions are non-semver). SemverUnknownUpdate OperationSemverType = "UNKNOWN" // SemverNoUpdate indicates no semantic version difference (used for added, removed, or unchanged packages). SemverNoUpdate OperationSemverType = "NONE" )
type PackageChange ¶
type PackageChange struct {
Package PkgWrapper
Operation Operation
PreviousVersion PkgVersion // Only available for updated packages ! Empty (zero value) otherwise.
}
PackageChange contains detailed information about a package difference.
The Package field holds a reference to the package wrapper (agnostic of the package manager). See PkgWrapper for more information.
The Operation field indicates what changed (ADDITION, REMOVAL, UPGRADE, DOWNGRADE, etc.) and the semantic version type of the change (MAJOR, MINOR, PATCH, EXTRA, UNKNOWN, NONE).
PreviousVersion is only populated for updated packages (when Operation is UPGRADE or DOWNGRADE). For added and removed packages, PreviousVersion is empty (zero value).
type PackageMap ¶
type PackageMap map[string]PkgWrapper
PackageMap holds package information for efficient lookup.
Key is the package name (e.g., "vendor/package"), value is a wrapper providing package details and helper methods. PackageMap is used as input to depsdiff.Diff to represent the state of dependencies at a point in time (typically parsed from a package lock file).
type PkgVersion ¶
type PkgVersion struct {
// Raw is the value as defined in the lock file (e.g., "1.2.3", "dev-master#abcd123", "1.0.0-beta").
Raw string
// Label is the human-readable title for the version (e.g., "1.2.3", "dev-master#abcd123").
Label string
// Semver will be defined only if Raw version is semver compliant, otherwise it will be nil.
// Check if this is non-nil before using semantic version components.
Semver *Semver
}
PkgVersion contains version information for a package.
Raw contains the exact version string as defined in the lock file. Label is the human-readable version representation. Semver is populated only if Raw is a valid semantic version, otherwise nil.
type PkgWrapper ¶
type PkgWrapper interface {
// GetName returns the package name (e.g., "vendor/package", "symfony/console").
GetName() string
// GetVersion returns the package version information.
// For removed packages in a comparison, this returns the last known version.
GetVersion() PkgVersion
// IsAbandoned returns true if the package is marked as abandoned (no longer maintained).
IsAbandoned() bool
// IsDevOnly returns true if the package is only for development environment (dev-only dependency).
// A package may exist only as a root dev requirement from user perspective, but actually used
// by a non-dev requirement.
IsDevOnly() bool
// IsRootRequirement returns true if the package is explicitly required (typically from a requirement/manifest file).
IsRootRequirement() bool
// IsRootDevRequirement returns true if the package is explicitly required for development only
// (e.g., in "require-dev" section for composer or "devDependencies" for npm).
IsRootDevRequirement() bool
// GetLink returns the best available link for the package (wiki, docs, source, homepage, etc.)
// or an empty string if no link is available.
GetLink() string
}
PkgWrapper is an interface that provides access to package metadata.
Implementations should provide information about a package from a lock file, including version, dependency type (regular/dev), and status information.
type Semver ¶
type Semver struct {
Major int // Major version component (e.g., 1 in "1.2.3")
Minor int // Minor version component (e.g., 2 in "1.2.3")
Patch int // Patch version component (e.g., 3 in "1.2.3")
Extra string // Additional version component (e.g., "-beta", "+build" in "1.2.3-beta+build")
}
Semver represents semantic version components.
A semantic version follows the format MAJOR.MINOR.PATCH[+extra]. For example, version "1.2.3-beta" has Major=1, Minor=2, Patch=3, Extra="-beta".
This struct is only populated when a version string is determined to be valid semantic version format. See contract.PkgVersion.Semver.
Source Files