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

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)
    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.

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
    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, Parse preserves it so one manifest can refer to packages from different ecosystems. Otherwise Parse builds the PURL from the parser's 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 cookbook 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.

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
}

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.

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"
)