Devel

.github/workflows/codeql.yml

@@ -35,11 +35,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -53,7 +53,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -66,6 +66,6 @@ jobs:
     #     ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/go.yml

@@ -14,12 +14,13 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Go
-      uses: actions/setup-go@v5
+      uses: actions/setup-go@v6
       with:
-        go-version: 1.24
+        go-version: 1.25
+        go-version-file: 'go.mod'
 
     - name: Build
       run: go build -v ./...

.github/workflows/golangci-lint.yml

@@ -16,15 +16,15 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@v6
         with:
-          go-version: 1.24
-      - uses: actions/checkout@v4
+          go-version: 1.25
+      - uses: actions/checkout@v6
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v8
+        uses: golangci/golangci-lint-action@v9
         with:
           # Optional: version of golangci-lint to use in form of v1.2 or v1.2.3 or `latest` to use the latest version
-          version: v2.2.0
+          version: v2.11.3
 
           # Optional: working directory, useful for monorepos
           # working-directory: somedir

.github/workflows/release-binary.yml

@@ -11,14 +11,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "Check out code"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with: 
           fetch-depth: 0
 
       - name: "Set up Go"
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with: 
-          go-version: 1.24
+          go-version: 1.25
 
       - name: "Create release on GitHub"
         timeout-minutes: 10

.github/workflows/release-test.yml

@@ -12,14 +12,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "Check out code"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with: 
           fetch-depth: 0
 
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
-          go-version: 1.24
+          go-version: 1.25
 
       - name: release test
         uses: goreleaser/goreleaser-action@v6

.golangci.yml

@@ -44,6 +44,7 @@ linters:
       - third_party$
       - builtin$
       - examples$
+      - pkg/depsdev/v3alpha/api_test.go
 formatters:
   exclusions:
     generated: lax

cmd/findings.go

@@ -0,0 +1,67 @@
+/*
+
+depsdev - CLI client for deps.dev API.
+Free access to dependencies, licenses, advisories, and other critical health and security signals for open source package versions.
+
+
+@author: edoardottt, https://edoardottt.com/
+
+@repository: https://github.com/edoardottt/depsdev
+
+@license: https://github.com/edoardottt/depsdev/blob/main/LICENSE
+
+*/
+
+package cmd
+
+/*
+
+Not supported for now.
+Maybe will be shipped when stable.
+
+// findingsCmd represents the package command when called with findings subcommand.
+var findingsCmd = &cobra.Command{
+	Use:   "findings package-manager package-name [version]",
+	Short: "Get info about a safe dependency management",
+	Long:  `Findings evaluates a specified package or version and returns findings which are relevant to safe dependency management.`,
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) < minArgsTwo {
+			return fmt.Errorf("%s %w", "two", input.ErrArgumentsLeast)
+		}
+
+		if !input.IsValidPackageManager(args[0], input.AllValidPackageManagers) {
+			return input.ErrInvalidPackageManager
+		}
+
+		return nil
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		if len(args) >= minArgsThree {
+			v, err := api.GetFindingsVersion(args[0], args[1], args[2])
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			vJSON, err := output.IndentJSON(v)
+			if err != nil {
+				log.Fatal(err.Error())
+			}
+
+			fmt.Println(vJSON)
+		} else {
+			p, err := api.GetFindings(args[0], args[1])
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			pJSON, err := output.IndentJSON(p)
+			if err != nil {
+				log.Fatal(err.Error())
+			}
+
+			fmt.Println(pJSON)
+		}
+	},
+}
+
+*/

cmd/root.go

@@ -57,4 +57,5 @@ func init() {
 	rootCmd.AddCommand(graphCmd)
 	rootCmd.AddCommand(reqsCmd)
 	rootCmd.AddCommand(packagesCmd)
+	// rootCmd.AddCommand(findingsCmd) not supported in v3 for now.
 }

go.mod

@@ -1,6 +1,6 @@
 module github.com/edoardottt/depsdev
 
-go 1.24
+go 1.25
 
 require (
 	github.com/avast/retry-go v3.0.0+incompatible

pkg/depsdev/definitions/batch.go

@@ -112,3 +112,37 @@ func (p *PurlBatchResponse) Items() []Purl {
 
 	return l
 }
+
+type FindingBatchRequest struct {
+	VersionKey VersionKey `json:"versionKey,omitempty"`
+	PackageKey PackageKey `json:"packageKey,omitempty"`
+}
+
+type FindingBatchBody struct {
+	Requests  []FindingBatchRequest `json:"requests"`
+	PageToken string                `json:"pageToken"`
+}
+
+func (p *FindingBatchBody) SetNextPageToken(token string) {
+	p.PageToken = token
+}
+
+type FindingBatchResponse struct {
+	Responses []struct {
+		Findings Findings            `json:"findings"`
+		Request  FindingBatchRequest `json:"request"`
+	} `json:"responses"`
+	NextPageToken string `json:"nextPageToken"`
+}
+
+func (p *FindingBatchResponse) GetNextPageToken() string {
+	return p.NextPageToken
+}
+func (p *FindingBatchResponse) Items() []Findings {
+	l := make([]Findings, 0, len(p.Responses))
+	for _, r := range p.Responses {
+		l = append(l, r.Findings)
+	}
+
+	return l
+}

pkg/depsdev/definitions/finding.go

@@ -0,0 +1,57 @@
+/*
+
+depsdev - CLI client for deps.dev API.
+Free access to dependencies, licenses, advisories, and other critical health and security signals for open source package versions.
+
+
+@author: edoardottt, https://edoardottt.com/
+
+@repository: https://github.com/edoardottt/depsdev
+
+@license: https://github.com/edoardottt/depsdev/blob/main/LICENSE
+
+*/
+
+package depsdev
+
+// Findings represents the root JSON object.
+type Findings struct {
+	PackageKey          *PackageKey      `json:"packageKey,omitempty"`
+	VersionKey          *VersionKey      `json:"versionKey,omitempty"`
+	RecommendedVersions []VersionDetails `json:"recommendedVersions,omitempty"`
+	RequestedVersion    *VersionDetails  `json:"requestedVersion,omitempty"`
+	DefaultVersion      *VersionDetails  `json:"defaultVersion,omitempty"`
+	PackageFindings     []Finding        `json:"packageFindings,omitempty"`
+}
+
+// VersionDetails contains findings and metadata for a specific version.
+type VersionDetails struct {
+	VersionKey  *VersionKey `json:"versionKey,omitempty"`
+	IsDefault   bool        `json:"isDefault,omitempty"`
+	Findings    []Finding   `json:"findings,omitempty"`
+	CooldownEnd string      `json:"cooldownEnd,omitempty"`
+}
+
+// Finding indicates specific risks or statuses associated with a package or version.
+type Finding struct {
+	Type              string             `json:"type,omitempty"`
+	Risk              string             `json:"risk,omitempty"`
+	DeprecatedContext *DeprecatedContext `json:"deprecatedContext,omitempty"`
+	CooldownContext   *CooldownContext   `json:"cooldownContext,omitempty"`
+	LowUsageContext   *LowUsageContext   `json:"lowUsageContext,omitempty"`
+}
+
+// DeprecatedContext provides the reason for deprecation.
+type DeprecatedContext struct {
+	Reason string `json:"reason,omitempty"`
+}
+
+// CooldownContext indicates the cooldown period for a specific version.
+type CooldownContext struct {
+	End string `json:"end,omitempty"`
+}
+
+// LowUsageContext provides alternative packages with higher usage.
+type LowUsageContext struct {
+	AlternativePackages []string `json:"alternativePackages,omitempty"`
+}

pkg/depsdev/v3/api.go

@@ -131,6 +131,55 @@ func getAdvisory(c *client.Client, advisory string) (def.Advisory, error) {
 	return response, nil
 }
 
+/*
+
+Not supported for now.
+Maybe will be shipped when stable.
+
+// GetFindings returns information about safe dependency management on a package.
+func (a *APIv3) GetFindings(packageManager, packageName string) (def.Findings, error) {
+	if !input.IsValidPackageManager(packageManager, input.AllValidPackageManagers) {
+		return def.Findings{}, input.ErrInvalidPackageManager
+	}
+
+	return getFindings(a.client, packageManager, packageName)
+}
+
+// getFindings returns a Version object.
+func getFindings(c *client.Client, packageManager, packageName string) (def.Findings, error) {
+	var response def.Findings
+
+	var path = fmt.Sprintf(GetFindingsPath, packageManager, url.PathEscape(packageName))
+	if err := c.Get(path, &response); err != nil {
+		return def.Findings{}, err
+	}
+
+	return response, nil
+}
+
+// GetFindingsVersion returns information about safe dependency management on a specific version of a package.
+func (a *APIv3) GetFindingsVersion(packageManager, packageName, version string) (def.Findings, error) {
+	if !input.IsValidPackageManager(packageManager, input.AllValidPackageManagers) {
+		return def.Findings{}, input.ErrInvalidPackageManager
+	}
+
+	return getFindingsVersion(a.client, packageManager, packageName, version)
+}
+
+// getFindingsVersion returns a Version object.
+func getFindingsVersion(c *client.Client, packageManager, packageName, version string) (def.Findings, error) {
+	var response def.Findings
+
+	var path = fmt.Sprintf(GetFindingsVersionPath, packageManager, url.PathEscape(packageName), version)
+	if err := c.Get(path, &response); err != nil {
+		return def.Findings{}, err
+	}
+
+	return response, nil
+}
+
+*/
+
 // Query returns information about multiple package versions, which can be specified by name, content hash, or both.
 // If a hash was specified in the request, it returns the artifacts that matched the hash.
 // Querying by content hash is currently supported for npm, Cargo, Maven, NuGet, PyPI and RubyGems.

pkg/depsdev/v3/routes.go

@@ -19,11 +19,13 @@ const (
 	V3BasePath = `https://api.deps.dev/v3`
 
 	// API routes.
-	GetPackagePath                = `/systems/%s/packages/%s`
-	GetVersionPath                = `/systems/%s/packages/%s/versions/%s`
-	GetDependenciesPath           = `/systems/%s/packages/%s/versions/%s:dependencies`
-	GetProjectPath                = `/projects/%s`
-	GetAdvisoryPath               = `/advisories/%s`
+	GetPackagePath      = `/systems/%s/packages/%s`
+	GetVersionPath      = `/systems/%s/packages/%s/versions/%s`
+	GetDependenciesPath = `/systems/%s/packages/%s/versions/%s:dependencies`
+	GetProjectPath      = `/projects/%s`
+	GetAdvisoryPath     = `/advisories/%s`
+	// GetFindingsPath               = `/systems/%s/packages/%s:findings`.
+	// GetFindingsVersionPath        = `/systems/%s/packages/%s/versions/%s:findings`.
 	QueryPath                     = `/query`
 	GetRequirementsPath           = `/systems/%s/packages/%s/versions/%s:requirements`
 	GetProjectPackageVersionsPath = `/projects/%s:packageversions`