manifests

manifests

A Go library for parsing package manager manifest and lockfiles. Extracts dependencies with version constraints, scopes, and integrity hashes.

Installation

go get github.com/git-pkgs/manifests

Usage

package main

import (
    "fmt"
    "os"
    "github.com/git-pkgs/manifests"
)

func main() {
    content, _ := os.ReadFile("package.json")
    result, err := manifests.Parse("package.json", content)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Ecosystem: %s\n", result.Ecosystem)
    fmt.Printf("Kind: %s\n", result.Kind)
    fmt.Printf("Package: %s %s\n", result.Name, result.Version)
    for _, dep := range result.Dependencies {
        fmt.Printf("  %s@%s (%s)\n", dep.Name, dep.Version, dep.Scope)
    }
}

Supported Ecosystems

Swift output

Swift manifests are read without executing Swift, so variables, conditions, helper functions and interpolated strings are not evaluated. Packages used by test targets get test scope, and plugin and macro dependencies get build. A package used in several places takes the widest scope, and a regular helper target used only by tests still counts as runtime. If any target reference doesn't match a declared package or local target, every dependency keeps the runtime default.

Package.resolved pins are Direct: false, since the file doesn't record which pins are direct. A pin with no release version uses its revision as Version.

Lockfile Feature Support

Supplement files: go.sum is parsed as a supplement rather than a lockfile. It provides integrity hashes that can be matched against go.mod dependencies by name and version, but it doesn't represent a standalone dependency tree.

API

Parse

Parses a manifest or lockfile and returns extracted dependencies.

func Parse(filename string, content []byte) (*ParseResult, error)

Identify

Returns the ecosystem and kind for a filename without parsing.

func Identify(filename string) (ecosystem string, kind Kind, ok bool)

IdentifyAll

Returns all matching ecosystems for a filename (some files match multiple parsers).

func IdentifyAll(filename string) []Match

Ecosystems

Returns a list of supported ecosystems.

func Ecosystems() []string

DiscoverManifests

Discovers root manifests, GitHub Actions workflows, and declared Cargo, Go, npm/Yarn, and pnpm workspace members. Discovery is repository-aware while Parse remains a pure single-file operation.

reader := manifests.NewFSReader(os.DirFS("."))
found, warnings := manifests.DiscoverManifests(reader)

Callers reading historical revisions can implement RepositoryReader over a Git tree. Paths and glob patterns are rooted, slash-separated repository paths. Workspace records set ParentPath to the configuration that selected them. Warnings report malformed workspace configuration or failed lookups without discarding manifests that were discovered successfully.

DiscoverVendors

Discovers package-manager vendor roots and exact package identities stored in the repository. The initial implementation recognizes npm node_modules trees exposed by the supplied reader, Go vendor/modules.txt, Python [tool.vendoring] configuration, and Cargo directory sources selected through .cargo/config.toml or .cargo/config.

reader := manifests.NewFSReader(os.DirFS("."))
found, warnings := manifests.DiscoverVendors(reader)

VendorDiscovery.Roots classifies each vendor directory by ecosystem and records the configuration or inventory that selected it. Each VendoredDependency has Kind == Vendor, an exact package identity and PURL, its vendor root, and the evidence file from which the identity was read. Results are normalized and deterministic. Invalid configuration, unreadable evidence, and incomplete package identities are returned as warnings without discarding successful discoveries.

Types

This module is pre-v1 and exported result structs may gain additive metadata fields in minor releases. Use keyed composite literals when constructing Dependency, Declaration, or ParseResult values.

Dependency

type Dependency struct {
    Name        string // Package name
    Version     string // Version constraint or resolved version
    Scope       Scope  // runtime, development, test, build, optional
    Integrity   string // Opaque verification value, when available
    Direct      bool   // True if declared directly, false if transitive
    PURL        string // Package URL (pkg:ecosystem/name@version)
    Ecosystem   string // Ecosystem name, in the same form as ParseResult.Ecosystem
    NoPURL      bool   // Source-only entry with no known package identity
    RegistryURL string // Source registry URL (if non-default)
    Source      Source // Explicit Git, path, or ecosystem source override
}

Integrity is an opaque verification value derived from the source file. The digest encoding remains ecosystem-specific, and parsers may add an algorithm prefix such as sha256- when the source stores it separately. That prefix does not imply Subresource Integrity: the digest may use hexadecimal, base64, Nix base32, or another ecosystem-specific form. Consumers should only decode or convert the value with knowledge of the source format.

When a dependency comes from a non-default registry, the PURL includes a repository_url qualifier (e.g., pkg:npm/foo@1.0.0?repository_url=https://npm.mycompany.com/). Default registries like registry.npmjs.org, pypi.org, and rubygems.org are not included in the PURL.

A file can refer to packages from more than one ecosystem, such as npm: imports in deno.json. A parser marks those entries by setting Ecosystem to an ecosystem name in the same form as ParseResult.Ecosystem. Parse sets Ecosystem on every dependency, using the file's ecosystem when the parser did not set one, so consumers never need to fall back to ParseResult.Ecosystem. Entries with NoPURL keep an empty Ecosystem because they have no package identity.

Parse resolves each dependency's PURL in this order:

1. NoPURL leaves the PURL empty. Source-only entries, such as direct download URLs, keep their location in Source without an invented package identity.
2. A PURL supplied by the parser is preserved as written. A parser that supplies a PURL from another ecosystem should also set Ecosystem.
3. Otherwise the PURL is built from Ecosystem. Manifest PURLs omit the version. Lockfile and supplement PURLs include it.

Declaration follows the same rules and its PURL always omits the version.

Declaration

type Declaration struct {
    Name      string // Package name
    Version   string // Version requirement as written in the manifest
    Scope     Scope  // runtime, development, test, build, optional
    Direct    bool   // Direct rather than generated or transitive
    PURL      string // Versionless Package URL
    Ecosystem string // Ecosystem name, in the same form as ParseResult.Ecosystem
    NoPURL    bool   // Source-only entry with no known package identity
    Location  string // Opaque parser-defined identity within the manifest
    Source    Source // Explicit source override as written
}

Declarations preserve source-level references without applying inheritance, merging, interpolation, or other effective-model resolution. Consumers can use Location to match the same logical entry across edits, but should not parse its ecosystem-specific value. A declaration PURL omits the version because the raw requirement may be a range or property expression. When a parser supplies its own PURL or Ecosystem, Parse uses it so one manifest can refer to packages from different ecosystems. Otherwise Parse builds the PURL from the file's ecosystem and records that ecosystem in Ecosystem.

Direct distinguishes explicit requirements from generated or transitive entries when the source format records that distinction, such as go.mod.

Source

type Source struct {
    Kind   SourceKind // registry, git, path, github, or url
    Value  string     // Literal URL, path, or ecosystem coordinate
    Branch string     // Literal branch selector
    Tag    string     // Literal tag selector
    Ref    string     // Literal revision selector
    Rel    string     // Literal repository-relative package path
}

Source records source syntax without claiming that dependency resolution used that location. Manifest-level source configuration is preserved in ParseResult.Sources in declaration order. An explicit dependency override is stored on both its Dependency and Declaration; dependencies with no override have an empty Source. RegistryURL remains reserved for resolved or otherwise attributable package registries and is not used for Git repositories or local paths. Chef Git and GitHub sources also retain literal branch, tag, ref, and rel options without resolving them.

Direct artifact or catalog URLs, such as Vagrant box_url values, use the url source kind and retain the complete literal URL.

In deno.json, remote URL imports use the url source kind. Local path and file: imports use the path source kind. Both are source-only entries named by their import map key, with NoPURL set. Runtime builtins such as node:fs, inline data: modules and bare values are not reported as dependencies.

In renv.lock, packages installed from a repository use the registry source kind with the recorded repository name. CRAN packages keep a cran PURL, as do packages from Posit Package Manager recorded as RSPM, PPM or P3M. Bioconductor packages, including those from repositories such as BioCsoft, use a bioconductor PURL. Packages from other repositories keep a cran PURL with a repository_url taken from the lockfile's repository list, or from the repository value when it is a URL. A repository with no known URL has no package identity. GitHub packages use the github source kind with an owner/repo value. GitLab and Bitbucket packages use the git source kind with a gitlab::owner/repo or bitbucket::owner/repo coordinate. git, URL and Local packages use the git, url and path source kinds with their recorded RemoteUrl. Git sources keep RemoteSha, or RemoteRef when no commit is recorded, in Ref and RemoteSubdir in Rel. These source-only entries and packages with an unrecognised source have NoPURL set. Packages with no recorded source keep a cran PURL.

Parsers that do not preserve source locations leave Declarations empty. Declarations are available for package.json, Cargo manifests, go.mod, Python requirements files, pyproject.toml, GitHub Actions workflows, gleam.toml, pom.xml, NuGet project and package files, Directory.Packages.props, Chef manifests, and Vagrantfile. The Maven parser includes parents, dependencies, dependency management, plugins, plugin dependencies, plugin management, build extensions, and their profile-scoped forms.

ParseResult

type ParseResult struct {
    Ecosystem    string       // npm, gem, pypi, golang, cargo, etc.
    Kind         Kind         // manifest, lockfile, or supplement
    Name         string       // the package's own name, when the format declares one
    Version      string       // the package's own version, when declared
    Licenses     []string     // raw declared license values
    LicenseFile  string       // manifest-relative path to a declared license file
    Digest       string       // file-level verification value, when present
    Dependencies []Dependency
    Declarations []Declaration
    Sources      []Source      // Ordered manifest-level source declarations
    Scripts      map[string][]string // Hook or task names with ordered commands or paths
}

Name and Version are populated for manifest formats that declare their own package identity (Cargo.toml [package], package.json "name", go.mod module, .gemspec, and so on). They are empty for lockfiles and for dependency-only files like Gemfile or requirements.txt.

Licenses contains decoded values as declared by the manifest; it does not normalize them into SPDX expressions. LicenseFile is populated when a format explicitly identifies a license file. Both are empty for formats without license metadata.

Digest contains a file-level verification value when the format defines one. For Chart.lock, it covers the dependency declarations from Chart.yaml and is separate from each dependency's Integrity value.

Scripts contains declared commands, callbacks or script paths, including named tasks as well as install hooks. For example, result.Scripts["postinstall"] holds the command from npm's scripts.postinstall. Lists preserve declaration order; empty declarations are omitted.

Parsing does not execute scripts, evaluate conditions or follow script paths. Ruby string bodies retain source escapes and heredoc indentation. Dynamic Ruby expressions and arbitrary build code are not resolved. A missing entry does not establish that a package has no install hooks: files such as an undeclared build.rs or deps/build.jl require separate filesystem discovery.

Chef cookbook and Vagrant box PURLs remain empty while chef and vagrant are only candidate Package URL types without accepted name and namespace rules.

Vendor Discovery

type VendorDiscovery struct {
    Roots        []VendorRoot
    Dependencies []VendoredDependency
}

type VendorRoot struct {
    Path       string
    Ecosystem  string
    ConfigPath string
}

type VendoredDependency struct {
    Name         string
    Version      string
    Ecosystem    string
    Kind         Kind
    PURL         string
    RootPath     string
    EvidencePath string
}

Kind

const (
    Manifest   Kind = "manifest"   // Declared dependencies with version constraints
    Lockfile   Kind = "lockfile"   // Resolved dependencies with exact versions
    Supplement Kind = "supplement" // Provides extra data (e.g. integrity hashes) for a manifest's dependencies
    Vendor     Kind = "vendor"     // Exact package identity stored under a vendor root
)

Scope

const (
    Runtime     Scope = "runtime"
    Development Scope = "development"
    Test        Scope = "test"
    Build       Scope = "build"
    Optional    Scope = "optional"
)

License

MIT.