Documentation
¶
Overview ¶
Package npm reads npm and pnpm data: package.json manifests, pnpm lockfiles, registry metadata and package tarballs.
Index ¶
- Constants
- Variables
- func IsExactVersion(s string) bool
- func NewerStable(current string, versions []string) ([]string, error)
- func PackFileName(name, version string) string
- func SatisfiesNode(rangeExpr, nodeVersion string) (bool, error)
- func StripPublishConfig(w io.Writer, r io.Reader) error
- func TarballURL(registry, name, version string) string
- type Client
- type Dependency
- type DependencyKind
- type Deprecation
- type Engines
- type LockPackage
- type Manifest
- type Packument
- type Platform
- type Problem
- type TarballInfo
- type VersionMeta
Constants ¶
const DefaultRegistry = "https://registry.npmjs.org"
DefaultRegistry is the public npm registry.
Variables ¶
var ErrIntegrity = errors.New("integrity mismatch")
ErrIntegrity reports downloaded bytes that do not match the expected integrity.
var ErrNotFound = errors.New("not found in registry")
ErrNotFound reports a package or tarball the registry does not have.
var ErrUnsafePath = errors.New("unsafe path in tarball")
ErrUnsafePath reports a tarball entry with an absolute path or a ".." segment.
Functions ¶
func IsExactVersion ¶
IsExactVersion reports whether s is a single SemVer 2.0.0 version.
func NewerStable ¶
NewerStable returns the versions greater than current without a prerelease tag, in ascending order. It skips strings that are not versions.
func PackFileName ¶
PackFileName returns the file name npm pack gives a package: name-1.2.3.tgz, or scope-name-1.2.3.tgz for @scope/name.
func SatisfiesNode ¶
SatisfiesNode reports whether nodeVersion falls inside an engines.node range written with npm syntax. An empty range accepts every version.
func StripPublishConfig ¶
StripPublishConfig copies a package tarball from r to w without the publishConfig key of its first-level package.json. That file gets re-encoded with sorted keys and two-space indentation; every other entry keeps its header and bytes. It rejects tarballs with multiple first-level package.json files. The same input gives the same output.
func TarballURL ¶
TarballURL returns the registry URL of a package tarball, such as <registry>/@scope/name/-/name-1.2.3.tgz.
Types ¶
type Client ¶
type Client struct {
Registry string // defaults to DefaultRegistry
HTTP *http.Client // defaults to http.DefaultClient
Attempts int // tries per request, defaults to 3
Backoff func(retry int) time.Duration // wait before retry n, defaults to 500ms doubling
}
Client reads an npm registry. The zero value reads DefaultRegistry.
func (*Client) DownloadFile ¶
func (c *Client) DownloadFile(ctx context.Context, name, version, integrity, path string) (string, error)
DownloadFile saves a package tarball at path after checking it against an SRI integrity string (sha512 or sha1). It writes path+".part" and renames it on success, so path never holds a partial or corrupt file. Network and server errors get retried; ErrNotFound and ErrIntegrity do not.
It also returns the sha512 hex digest of the downloaded bytes, computed whatever the integrity algorithm was: an export's cache key and manifest always use sha512, even for the legacy packages that publish sha1 only.
type Dependency ¶
type Dependency struct {
Name string
Version string
Kind DependencyKind
}
Dependency is a direct dependency declared in a package.json.
type DependencyKind ¶
type DependencyKind string
DependencyKind names the package.json field a dependency comes from.
const ( Prod DependencyKind = "dependencies" Dev DependencyKind = "devDependencies" Optional DependencyKind = "optionalDependencies" )
Dependency kinds, in the order ParseManifest returns them.
type Deprecation ¶
type Deprecation string
Deprecation holds a deprecation message. A value that is not a string decodes to "".
func (*Deprecation) UnmarshalJSON ¶
func (d *Deprecation) UnmarshalJSON(b []byte) error
UnmarshalJSON implements json.Unmarshaler.
type Engines ¶
Engines maps an engine name to its version range. Old packages publish an array instead; it decodes to an empty map.
func (*Engines) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type LockPackage ¶
type LockPackage struct {
Name string
Version string
Integrity string // SRI string, such as "sha512-..."
OS []string
CPU []string
Libc []string
Engines map[string]string
}
LockPackage is one resolved package of a pnpm lockfile.
func ParseLockfile ¶
func ParseLockfile(r io.Reader) ([]LockPackage, error)
ParseLockfile reads a pnpm lockfile in format 9.0 and returns its packages sorted by name, then version. Every package must come from a registry.
func (LockPackage) Key ¶
func (p LockPackage) Key() string
Key returns "name@version", the form Trivy findings and rank indexes use.
type Manifest ¶
type Manifest struct {
Name string
Dependencies []Dependency
// contains filtered or unexported fields
}
Manifest holds the parts of a package.json that sealift reads.
func ParseManifest ¶
ParseManifest reads a package.json. Dependencies come back grouped by kind and sorted by name within each kind.
type Packument ¶
type Packument struct {
Name string `json:"name"`
Versions map[string]VersionMeta `json:"versions"`
Time map[string]json.RawMessage `json:"time"`
}
Packument is the registry document of a package.
type Platform ¶
Platform is the system packages get installed on.
func (Platform) Accepts ¶
func (pl Platform) Accepts(p LockPackage) bool
Accepts reports whether npm would install p on the platform. It follows npm's rules: an empty list or ["any"] accepts every value, "!value" excludes a value, and the libc list only applies on linux.
func (Platform) Filter ¶
func (pl Platform) Filter(pkgs []LockPackage) []LockPackage
Filter returns the packages the platform accepts, in their original order.
type Problem ¶
type Problem struct {
Field string // "dependencies", "pnpm.overrides", ...
Name string // dependency name, empty for a field-level problem
Value string
Reason string
}
Problem describes one package.json entry that blocks an analysis.
type TarballInfo ¶
type TarballInfo struct {
ManifestPath string // first-level package.json, such as "package/package.json"
HasPublishConfig bool
}
TarballInfo describes a package tarball.
func InspectTarball ¶
func InspectTarball(r io.Reader) (TarballInfo, error)
InspectTarball reads a gzip-compressed package tarball, rejects unsafe entry paths and tarballs with multiple first-level package.json files, and reports whether its package.json holds publishConfig.
type VersionMeta ¶
type VersionMeta struct {
Version string `json:"version"`
Deprecated Deprecation `json:"deprecated"`
Engines Engines `json:"engines"`
Scripts map[string]json.RawMessage `json:"scripts"`
PeerDependencies map[string]string `json:"peerDependencies"`
NPMUser struct {
Name string `json:"name"`
} `json:"_npmUser"`
Dist struct {
Integrity string `json:"integrity"`
Attestations json.RawMessage `json:"attestations"`
} `json:"dist"`
}
VersionMeta holds the fields of one published version that sealift reads.
func (VersionMeta) HasInstallScript ¶
func (v VersionMeta) HasInstallScript() bool
HasInstallScript reports whether the version runs a preinstall, install or postinstall script.
func (VersionMeta) HasProvenance ¶
func (v VersionMeta) HasProvenance() bool
HasProvenance reports whether the registry lists attestations for the version.
Source Files