formats

Documentation

Overview

Package formats defines the data structures and interfaces for parsing package manifest files. It provides parsers for JSON, YAML, XML, and custom formats, with support for XPath/JSONPath-like field extraction.

Index

• func GetNestedField(data map[string]interface{}, field string) interface{}
• type FormatParser
  • func GetFormatParser(format string) (FormatParser, error)
• type JSONParser
  • func (p *JSONParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)
• type Package
  • func (p Package) GetName() string
  • func (p Package) GetRule() string
• type PackageList
• type RawParser
  • func (p *RawParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)
• type XMLParser
  • func (p *XMLParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)
• type YAMLParser
  • func (p *YAMLParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)

Functions

func GetNestedField

func GetNestedField(data map[string]interface{}, field string) interface{}

GetNestedField retrieves a value from a nested map using dot notation (e.g., "foo.bar.baz"). Returns nil if the path doesn't exist or if an intermediate value is not a map.

Types

type FormatParser

type FormatParser interface {
	// Parse parses raw file content and extracts package dependencies.
	//
	// Parameters:
	//   - content: The raw bytes of the package manifest file
	//   - cfg: The package manager configuration containing fields, patterns, and rules
	//
	// Returns:
	//   - []Package: A list of parsed packages with their versions and metadata
	//   - error: Returns an error if the content is invalid or cannot be parsed; returns nil on success
	Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)
}

FormatParser defines the interface for parsing package file contents.

Implementations should parse the raw file content according to their format (JSON, YAML, XML, or raw text) and extract package dependencies based on the provided configuration.

func GetFormatParser

func GetFormatParser(format string) (FormatParser, error)

GetFormatParser returns the appropriate parser for a given format.

It performs the following operations:

• Trims whitespace from the format string
• Validates that the format is not empty
• Returns the corresponding parser implementation

Parameters:

• format: The format name (e.g., "json", "yaml", "xml", "raw")

Returns:

• FormatParser: The parser implementation for the specified format
• error: Returns an error if format is empty or unsupported; returns nil on success

type JSONParser

type JSONParser struct{}

JSONParser parses JSON package files (e.g., package.json).

It supports JSON-based package managers such as npm, Yarn, and Composer, extracting dependencies from configured field names.

func (*JSONParser) Parse

func (p *JSONParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)

Parse parses JSON content and extracts package dependencies.

It performs the following operations:

• Unmarshals the JSON content into a map structure
• Iterates through configured fields (e.g., "dependencies", "devDependencies")
• Extracts package names and version strings from each field
• Applies version parsing, constraint mapping, and package overrides
• Filters ignored packages based on configuration

Parameters:

• content: The raw bytes of the JSON package manifest file
• cfg: The package manager configuration with field mappings and rules

Returns:

• []Package: A list of parsed packages with names, versions, and dependency types
• error: Returns an error if the JSON is invalid; returns nil on successful parse

type Package

type Package struct {
	Name             string `json:"name"`
	Version          string `json:"version"`
	Constraint       string `json:"constraint"`
	Type             string `json:"type"`
	PackageType      string `json:"package_type"`
	Rule             string `json:"rule"`
	Source           string `json:"source"`
	InstalledVersion string `json:"installed_version"`
	InstallStatus    string `json:"install_status"`
	Group            string `json:"group,omitempty"`
	IgnoreReason     string `json:"ignore_reason,omitempty"`
}

Package represents a declared dependency captured by a parser.

Fields:

• Name: The package name as declared in the manifest file
• Version: The parsed version number (e.g., "1.2.3")
• Constraint: The version constraint operator (e.g., "==", ">=", "~>")
• Type: The dependency type ("prod" for production, "dev" for development)
• PackageType: The package manager name (e.g., "npm", "pip", "nuget")
• Rule: The update rule name from configuration
• Source: The source file path where this package was declared
• InstalledVersion: The currently installed version (if known)
• InstallStatus: The installation status (e.g., "installed", "missing")
• Group: Optional dependency group or category
• IgnoreReason: If InstallStatus is "Ignored", explains why (e.g., "matches ignore pattern 'foo*'")

func (Package) GetName

func (p Package) GetName() string

GetName returns the package name and implements the config.PackageRef interface.

Returns:

• string: The package name from the Name field

func (Package) GetRule

func (p Package) GetRule() string

GetRule returns the update rule name and implements the config.PackageRef interface.

Returns:

• string: The update rule name from the Rule field

type PackageList

type PackageList struct {
	Packages []Package `json:"packages"`
	Source   string    `json:"source"`
}

PackageList is a collection of packages found in a single source file.

Fields:

• Packages: The list of Package objects parsed from the source file
• Source: The path to the source file containing these packages

type RawParser

type RawParser struct{}

RawParser parses raw text files using regex patterns (e.g., requirements.txt).

It supports plain text package managers such as pip (requirements.txt) and Go modules, using configurable regex patterns to extract package names, versions, and constraints.

func (*RawParser) Parse

func (p *RawParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)

Parse parses raw text content and extracts package dependencies using configured patterns.

It performs the following operations:

• Converts the raw bytes to text
• Extracts sections from INI-style files if multiple fields are configured
• Applies regex patterns to match package declarations
• Extracts package name, version, and constraint from regex named groups
• Applies constraint mapping and package overrides
• Filters ignored packages based on configuration

The regex pattern should use named groups: "name", "version", and optionally "constraint". Alternative group names "n" and "version_alt" are also supported.

Parameters:

• content: The raw bytes of the text package manifest file
• cfg: The package manager configuration with extraction patterns and field mappings

Returns:

• []Package: A list of parsed packages with names, versions, and constraints
• error: Returns an error if the regex pattern is invalid; returns nil on successful parse

type XMLParser

type XMLParser struct{}

XMLParser parses XML package files (e.g., .csproj, packages.config).

It supports various XML-based package managers including NuGet, .NET, and Maven, with configurable extraction paths and attribute mappings.

func (*XMLParser) Parse

func (p *XMLParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)

Parse parses XML content and extracts package dependencies.

It performs the following operations:

• Unmarshals the XML content into a node tree
• Searches for package nodes using XPath-like patterns from the configuration
• Extracts package names and versions from XML attributes
• Applies version parsing, constraints, and package overrides
• Identifies dev dependencies based on configured markers
• Falls back to PackageReference nodes for .NET/NuGet projects

Parameters:

• content: The raw bytes of the XML package manifest file
• cfg: The package manager configuration with extraction rules and field mappings

Returns:

• []Package: A list of parsed packages with names, versions, and dependency types
• error: Returns an error if the XML is invalid; returns nil on successful parse

type YAMLParser

type YAMLParser struct{}

YAMLParser parses YAML package files.

It supports YAML-based package managers such as Composer, Conda, and Docker Compose, handling both map-based and array-based dependency structures with nested field access.

func (*YAMLParser) Parse

func (p *YAMLParser) Parse(content []byte, cfg *config.PackageManagerCfg) ([]Package, error)

Parse parses YAML content and extracts package dependencies.

It performs the following operations:

• Unmarshals the YAML content into a nested map structure
• Retrieves dependency fields using dot notation (e.g., "dependencies.production")
• Handles both map-based dependencies (name: version) and array-based dependencies
• Extracts container image specifications for Docker Compose files
• Applies version parsing, constraint mapping, and package overrides
• Filters ignored packages based on configuration

Parameters:

• content: The raw bytes of the YAML package manifest file
• cfg: The package manager configuration with field mappings and extraction rules

Returns:

• []Package: A list of parsed packages with names, versions, and dependency types
• error: Returns an error if the YAML is invalid; returns nil on successful parse