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

Types

Dependency

type Dependency struct {
    Name        string // Package name
    Version     string // Version constraint or resolved version
    Scope       Scope  // runtime, development, test, build, optional
    Integrity   string // SRI hash (sha256-..., sha512-...)
    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)
}

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.

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
    Dependencies []Dependency
}

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.

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
)

Scope

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