manifests.go

// Package manifests parses dependency manifest and lockfile formats across package ecosystems.
//
// It supports 40+ ecosystems including npm, gem, pypi, cargo, maven, and more.
// Each ecosystem uses its PURL type as the identifier.
//
// Basic usage:
//
//	result, err := manifests.Parse("package.json", content)
//	if err != nil {
//	    log.Fatal(err)
//	}
//	fmt.Printf("Ecosystem: %s, Kind: %s\n", result.Ecosystem, result.Kind)
//	for _, dep := range result.Dependencies {
//	    fmt.Printf("  %s %s\n", dep.Name, dep.Version)
//	}
package manifests

import (
	"github.com/git-pkgs/manifests/internal/core"
	"github.com/git-pkgs/purl"
)

// Re-export types from internal/core for public API.
type (
	Kind       = core.Kind
	Scope      = core.Scope
	Dependency = core.Dependency
)

// Re-export constants.
const (
	Manifest   Kind = core.Manifest
	Lockfile   Kind = core.Lockfile
	Supplement Kind = core.Supplement

	Runtime     Scope = core.Runtime
	Development Scope = core.Development
	Test        Scope = core.Test
	Build       Scope = core.Build
	Optional    Scope = core.Optional
)

// ParseResult contains the parsed dependencies from a manifest or lockfile.
type ParseResult struct {
	Ecosystem string
	Kind      Kind
	// Name is the package's own name as declared in the manifest, when
	// the format has one. Empty for lockfiles and for formats that
	// only list dependencies (Gemfile, requirements.txt, etc.).
	Name string
	// Version is the package's own version as declared in the
	// manifest, when present.
	Version      string
	Dependencies []Dependency
}

// Options configures Parse.
type Options struct {
	// FSRoot, when non-empty, allows parsers that consult neighbouring
	// files on disk (currently only pom.xml, for parent <relativePath>
	// resolution) to do so within this directory. Paths outside it are
	// refused. When empty, parsing is a pure function of content and no
	// filesystem access occurs; this is the safe choice for untrusted
	// input.
	FSRoot string
}

// Parse parses a manifest or lockfile and returns its dependencies.
func Parse(filename string, content []byte, opts ...Options) (*ParseResult, error) {
	var o Options
	if len(opts) > 0 {
		o = opts[0]
	}

	parser, eco, kind := core.IdentifyParser(filename)
	if parser == nil {
		return nil, &UnknownFileError{Filename: filename}
	}

	var res *core.Result
	var err error
	if fp, ok := parser.(core.FSRootParser); ok {
		res, err = fp.ParseInRoot(filename, content, o.FSRoot)
	} else {
		res, err = parser.Parse(filename, content)
	}
	if err != nil {
		return nil, err
	}
	if res == nil {
		res = &core.Result{}
	}

	// Generate PURLs for all dependencies
	for i := range res.Dependencies {
		version := ""
		if kind == Lockfile || kind == Supplement {
			version = res.Dependencies[i].Version
		}
		res.Dependencies[i].PURL = makePURL(eco, res.Dependencies[i].Name, version, res.Dependencies[i].RegistryURL)
	}

	return &ParseResult{
		Ecosystem:    eco,
		Kind:         kind,
		Name:         res.Name,
		Version:      res.Version,
		Dependencies: res.Dependencies,
	}, nil
}

// makePURL creates a Package URL for a dependency.
func makePURL(ecosystem, name, version, registryURL string) string {
	return purl.BuildPURLString(ecosystem, name, version, registryURL)
}

// Identify returns the ecosystem and kind for a filename without parsing.
func Identify(filename string) (ecosystem string, kind Kind, ok bool) {
	_, eco, k := core.IdentifyParser(filename)
	if eco == "" {
		return "", "", false
	}
	return eco, k, true
}

// Match represents a file type match.
type Match = core.Match

// IdentifyAll returns all matching ecosystems for a filename.
func IdentifyAll(filename string) []Match {
	return core.IdentifyAllParsers(filename)
}

// Ecosystems returns a list of all supported PURL ecosystem types.
func Ecosystems() []string {
	return core.SupportedEcosystems()
}

// UnknownFileError is returned when a file type is not recognized.
type UnknownFileError struct {
	Filename string
}

func (e *UnknownFileError) Error() string {
	return "unknown manifest file: " + e.Filename
}

// ParseError is re-exported from internal/core.
type ParseError = core.ParseError