ecosystems

Ecosystems Package

The ecosystems package provides a unified plugin interface for discovering and building dependency graphs across multiple package managers and programming language ecosystems.

Purpose

Modern software projects use diverse package managers (pip, npm, maven, gradle, etc.) to manage dependencies. Each ecosystem has its own format for declaring and resolving dependencies. This package standardizes how dependency graphs are discovered, built, and represented, regardless of the underlying package manager.

Key Goals

1. Unified Interface: Provide a consistent API for dependency graph generation across all package managers
2. Extensibility: Make it easy to add support for new ecosystems without modifying core code
3. Type Safety: Leverage Go's type system to catch errors at compile time
4. Testability: Enable dependency injection and mocking for robust testing
5. Ecosystem Isolation: Keep ecosystem-specific logic contained within dedicated plugins

Architecture

Core Interface

Every plugin implements the SCAPlugin interface to:

• Discover dependency manifests in a directory (e.g., requirements.txt, package.json)
• Resolve dependencies using the ecosystem's native tooling
• Build a standardized dependency graph representation
• Return results with metadata about the analysis

Data Structures

DepGraph: Snyk Dependency Graph Format

The SCAResult.DepGraph field uses the standard Snyk dependency graph format from github.com/snyk/dep-graph/go/pkg/depgraph:

import "github.com/snyk/dep-graph/go/pkg/depgraph"

type SCAResult struct {
    DepGraph          *depgraph.DepGraph         `json:"depGraph,omitempty"`
    ProjectDescriptor identity.ProjectDescriptor `json:"projectDescriptor"`
    ResolverMetadata  *ResolverMetadata          `json:"meta,omitempty"`
    Error             error                      `json:"error,omitempty"`
}

DepGraph Structure

The depgraph.DepGraph type provides a standardized format for representing dependency graphs:

{
  "schemaVersion": "1.3.0",
  "pkgManager": {
    "name": "pip"
  },
  "pkgs": [
    {
      "id": "root@0.0.0",
      "info": {
        "name": "root",
        "version": "0.0.0"
      }
    },
    {
      "id": "requests@2.31.0",
      "info": {
        "name": "requests",
        "version": "2.31.0"
      }
    }
  ],
  "graph": {
    "rootNodeId": "root-node",
    "nodes": [
      {
        "nodeId": "root-node",
        "pkgId": "root@0.0.0",
        "deps": [
          { "nodeId": "requests@2.31.0" }
        ]
      },
      {
        "nodeId": "requests@2.31.0",
        "pkgId": "requests@2.31.0",
        "deps": []
      }
    ]
  }
}

Key Components

Building a DepGraph

Use the depgraph.Builder to construct dependency graphs:

import "github.com/snyk/dep-graph/go/pkg/depgraph"

// Create a builder with package manager and root package info
builder, err := depgraph.NewBuilder(
    &depgraph.PkgManager{Name: "pip"},
    &depgraph.PkgInfo{Name: "root", Version: "0.0.0"},
)
if err != nil {
    return nil, err
}

// Add package nodes
builder.AddNode("requests@2.31.0", &depgraph.PkgInfo{
    Name:    "requests",
    Version: "2.31.0",
})

// Connect dependencies
rootNode := builder.GetRootNode()
err = builder.ConnectNodes(rootNode.NodeID, "requests@2.31.0")
if err != nil {
    return nil, err
}

// Build the final graph
depGraph := builder.Build()

SCAResult: Analysis Output

type SCAResult struct {
    DepGraph          *depgraph.DepGraph         `json:"depGraph,omitempty"`
    ProjectDescriptor identity.ProjectDescriptor `json:"projectDescriptor"`
    ResolverMetadata  *ResolverMetadata          `json:"meta,omitempty"`
    Error             error                      `json:"error,omitempty"`
}

Each result contains:

• DepGraph: The complete dependency graph using Snyk's standard format
• ProjectDescriptor: Project identity information (type, target file, runtime)
• ResolverMetadata: Information about the resolver/plugin that performed the analysis
• Error: Any error encountered during analysis (optional)

ProjectDescriptor

type ProjectDescriptor struct {
    Identity ProjectIdentity `json:"identity"`
}

type ProjectIdentity struct {
    ProjectType       string  `json:"type,omitempty"`           // Project type (e.g., "npm", "maven", "pip")
    TargetFile        *string `json:"targetFile,omitempty"`     // Manifest/build file path
    TargetRuntime     *string `json:"targetRuntime,omitempty"`  // Runtime environment
    RootComponentName string  `json:"rootComponentName,omitempty"` // Root component name
}

The ProjectDescriptor contains project identity information that uniquely identifies what was analyzed. This includes the project type (ecosystem), the specific manifest file, and runtime details.

ResolverMetadata

type ResolverMetadata struct {
    PluginName       string            `json:"pluginName"`       // Name of the plugin/resolver
    VersionBuildInfo map[string]string `json:"versionBuildInfo"` // Version and build information
}

Standard keys are available in the metadata package:

import "github.com/snyk/cli-extension-dep-graph/v2/pkg/ecosystems/metadata"

// Available keys:
const (
    // Gradle ecosystem
    metadata.GradleVersion  = "gradleVersion"
    metadata.JavaVersion    = "javaVersion" 
    
    // Python ecosystem
    metadata.PythonVersion  = "pythonVersion"
    
    // General build info
    metadata.BuildTimestamp = "buildTimestamp"
)

Example usage:

import "github.com/snyk/cli-extension-dep-graph/v2/pkg/ecosystems/metadata"

resolverMetadata := ResolverMetadata{
    PluginName: "gradle",
    VersionBuildInfo: map[string]string{
        metadata.GradleVersion:  "8.5",
        metadata.JavaVersion:    "17.0.1", 
        metadata.BuildTimestamp: "2024-01-01T12:00:00Z",
    },
}

Plugins return PluginResult, where:

• Results contains depgraphs and other data. Multiple findings are permitted to allow for workspaces and other scenarios where more than one project are found within an ecosytem.
• ProcessedFiles contains files that other plugins should not handle (either because the plugin has processed them directly, e.g. uv.lock for uv, or because it is associated with the handled project, e.g. pyproject.toml or requirements.txt associated with a uv project).

Usage Examples

Basic Usage

import (
    "context"
    "fmt"
    "github.com/snyk/cli-extension-dep-graph/v2/pkg/ecosystems"
    "github.com/snyk/cli-extension-dep-graph/v2/pkg/ecosystems/python/pip"
)

func main() {
    plugin := &pip.Plugin{}
    options := ecosystems.NewPluginOptions().
        WithTargetFile("requirements.txt")
    
    result, err := plugin.BuildDepGraphsFromDir(
        context.Background(),
        logger.Nop(),
        "/path/to/python/project",
        options,
    )
    if err != nil {
        // Handle error
    }
    
    for _, scaResult := range result.Results {
        if scaResult.Error != nil {
            fmt.Printf("Error analyzing with %s: %v\n", scaResult.ResolverMetadata.PluginName, scaResult.Error)
            continue
        }

        fmt.Printf("Package Manager: %s\n", scaResult.DepGraph.PkgManager.Name)
        fmt.Printf("Total Packages: %d\n", len(scaResult.DepGraph.Pkgs))
    }
}

Analyzing All Projects

options := ecosystems.NewPluginOptions().
    WithAllProjects(true)

result, err := plugin.BuildDepGraphsFromDir(ctx, logger.Nop(), "/path/to/monorepo", options)
// Returns results for all requirements.txt files found

Handling Errors in Results

for _, result := range result.Results {
    if result.Error != nil {
        // Individual file failed, but others may have succeeded
        log.Printf("Failed to analyze with %s: %v", result.ResolverMetadata.PluginName, result.Error)
        continue
    }
    
    // Process successful result
    processDepGraph(result.DepGraph)
}

Adding a New Plugin

To add support for a new ecosystem:

1. Create package directory:

   pkg/ecosystems/<ecosystem>/<tool>/
   

2. Implement the interface:

   package tool
   
   import (
       "context"
       "github.com/snyk/cli-extension-dep-graph/v2/pkg/ecosystems"
       "github.com/snyk/cli-extension-dep-graph/v2/pkg/ecosystems/logger"
   )
   
   type Plugin struct {
       // Plugin-specific fields
   }
   
   var _ ecosystems.SCAPlugin = (*Plugin)(nil)
   
   func (p *Plugin) BuildDepGraphsFromDir(
       ctx context.Context,
       log logger.Logger,
       dir string,
       options *ecosystems.SCAPluginOptions,
   ) (*ecosystems.PluginResult, error) {
       // 1. Discover manifest files in dir
       // 2. Resolve dependencies using ecosystem tooling
       // 3. Build depgraph.DepGraph using the builder
       // 4. Return PluginResult with results and processed files
   }
   

3. Add ecosystem-specific options (if needed):

   // In options.go
   type MyEcosystemOptions struct {
       SpecificOption string
   }
   
   type SCAPluginOptions struct {
       Global      GlobalOptions
       Python      *PythonOptions
       MyEcosystem *MyEcosystemOptions  // Add here
   }
   

4. Write tests:

   func TestPlugin_BuildDepGraphsFromDir(t *testing.T) {
       plugin := &Plugin{}
       options := ecosystems.NewPluginOptions()
   
       result, err := plugin.BuildDepGraphsFromDir(context.Background(), logger.Nop(), "./testdata", options)
       assert.NoError(t, err)
       assert.Len(t, result.Results, 1)
       assert.NotNil(t, result.Results[0].DepGraph)
       assert.Equal(t, "mymanager", result.Results[0].DepGraph.PkgManager.Name)
   }
   

Design Principles

1. Single Responsibility: Each plugin focuses only on its ecosystem
2. Dependency Inversion: Depend on abstractions (interfaces), not concrete implementations
3. Open/Closed: Open for extension (new plugins), closed for modification (core interface)
4. Interface Segregation: Keep interfaces minimal and focused
5. Don't Repeat Yourself: Common functionality should be extracted to shared utilities

References

• Interface definition
• Configuration options
• Python plugins
• Snyk dep-graph package