Add Annotator plugin type and move cachedir into an Annotator.

PiperOrigin-RevId: 760648867

Author: erikvarga

annotator/annotator.go

@@ -0,0 +1,65 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package annotator provides the interface for annotation plugins.
+package annotator
+
+import (
+	"context"
+
+	scalibrfs "github.com/google/osv-scalibr/fs"
+	"github.com/google/osv-scalibr/inventory"
+	"github.com/google/osv-scalibr/plugin"
+)
+
+// Annotator is the interface for an annotation plugin, used to add additional
+// information to scan results such as VEX statements. Annotators have access to
+// the filesystem but should ideally not query any external APIs. If you need to
+// modify the scan results based on the output of network calls you should use
+// the Enricher interface instead.
+type Annotator interface {
+	plugin.Plugin
+	// Annotate annotates the scan results with additional information.
+	Annotate(ctx context.Context, input *ScanInput, results *inventory.Inventory) error
+}
+
+// Config stores the config settings for the annotation run.
+type Config struct {
+	Annotators []Annotator
+	ScanRoot   *scalibrfs.ScanRoot
+}
+
+// ScanInput provides information for the annotator about the scan.
+type ScanInput struct {
+	// The root of the artifact being scanned.
+	ScanRoot *scalibrfs.ScanRoot
+}
+
+// Run runs the specified annotators on the scan results and returns their statuses.
+func Run(ctx context.Context, config *Config, inventory *inventory.Inventory) ([]*plugin.Status, error) {
+	var statuses []*plugin.Status
+	if len(config.Annotators) == 0 {
+		return statuses, nil
+	}
+
+	input := &ScanInput{
+		ScanRoot: config.ScanRoot,
+	}
+
+	for _, a := range config.Annotators {
+		err := a.Annotate(ctx, input, inventory)
+		statuses = append(statuses, plugin.StatusFromErr(a, false, err))
+	}
+	return statuses, nil
+}

annotator/annotator_test.go

@@ -0,0 +1,133 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package annotator_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	"github.com/google/go-cpy/cpy"
+	"github.com/google/osv-scalibr/annotator"
+	"github.com/google/osv-scalibr/annotator/cachedir"
+	"github.com/google/osv-scalibr/extractor"
+	"github.com/google/osv-scalibr/inventory"
+	"github.com/google/osv-scalibr/plugin"
+	"google.golang.org/protobuf/proto"
+)
+
+type succeedingAnnotator struct{}
+
+func (succeedingAnnotator) Name() string                       { return "succeeding-annotator" }
+func (succeedingAnnotator) Version() int                       { return 1 }
+func (succeedingAnnotator) Requirements() *plugin.Capabilities { return &plugin.Capabilities{} }
+func (succeedingAnnotator) Annotate(ctx context.Context, input *annotator.ScanInput, results *inventory.Inventory) error {
+	return nil
+}
+
+type failingAnnotator struct{}
+
+func (failingAnnotator) Name() string                       { return "failing-annotator" }
+func (failingAnnotator) Version() int                       { return 2 }
+func (failingAnnotator) Requirements() *plugin.Capabilities { return &plugin.Capabilities{} }
+func (failingAnnotator) Annotate(ctx context.Context, input *annotator.ScanInput, results *inventory.Inventory) error {
+	return errors.New("some error")
+}
+
+func TestRun(t *testing.T) {
+	inv := &inventory.Inventory{
+		Packages: []*extractor.Package{
+			{Name: "package1", Version: "1.0", Locations: []string{"tmp/package.json"}},
+		},
+	}
+
+	copier := cpy.New(
+		cpy.Func(proto.Clone),
+		cpy.IgnoreAllUnexported(),
+	)
+
+	tests := []struct {
+		desc    string
+		cfg     *annotator.Config
+		inv     *inventory.Inventory
+		want    []*plugin.Status
+		wantErr error
+		wantInv *inventory.Inventory // Inventory after annotation.
+	}{
+		{
+			desc: "no_annotators",
+			cfg:  &annotator.Config{},
+			want: nil,
+		},
+		{
+			desc: "annotator_modifies_inventory",
+			cfg: &annotator.Config{
+				Annotators: []annotator.Annotator{cachedir.New()},
+			},
+			inv: inv,
+			want: []*plugin.Status{
+				{Name: "vex/cachedir", Version: 0, Status: &plugin.ScanStatus{Status: plugin.ScanStatusSucceeded}},
+			},
+			wantInv: &inventory.Inventory{
+				Packages: []*extractor.Package{
+					{
+						Name:        "package1",
+						Version:     "1.0",
+						Locations:   []string{"tmp/package.json"},
+						Annotations: []extractor.Annotation{extractor.InsideCacheDir},
+					},
+				},
+			},
+		},
+		{
+			desc: "annotator_fails",
+			cfg: &annotator.Config{
+				Annotators: []annotator.Annotator{&failingAnnotator{}},
+			},
+			want: []*plugin.Status{
+				{Name: "failing-annotator", Version: 2, Status: &plugin.ScanStatus{Status: plugin.ScanStatusFailed, FailureReason: "some error"}},
+			},
+		},
+		{
+			desc: "one_fails_one_succeeds",
+			cfg: &annotator.Config{
+				Annotators: []annotator.Annotator{&succeedingAnnotator{}, &failingAnnotator{}},
+			},
+			want: []*plugin.Status{
+				{Name: "succeeding-annotator", Version: 1, Status: &plugin.ScanStatus{Status: plugin.ScanStatusSucceeded}},
+				{Name: "failing-annotator", Version: 2, Status: &plugin.ScanStatus{Status: plugin.ScanStatusFailed, FailureReason: "some error"}},
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.desc, func(t *testing.T) {
+			// Deep copy the inventory to avoid modifying the original inventory that is used in other tests.
+			inv := copier.Copy(tc.inv).(*inventory.Inventory)
+			got, err := annotator.Run(context.Background(), tc.cfg, inv)
+			if !cmp.Equal(err, tc.wantErr, cmpopts.EquateErrors()) {
+				t.Errorf("Run(%+v) error: got %v, want %v\n", tc.cfg, err, tc.wantErr)
+			}
+			if diff := cmp.Diff(tc.want, got); diff != "" {
+				t.Errorf("Run(%+v) returned an unexpected diff of statuses (-want +got): %v", tc.cfg, diff)
+			}
+			if diff := cmp.Diff(tc.wantInv, inv); diff != "" {
+				t.Errorf("Run(%+v) returned an unexpected diff of mutated inventory (-want +got): %v", tc.cfg, diff)
+			}
+		})
+	}
+}

extractor/annotator/cachedir.go renamed to annotator/cachedir/cachedir.go

@@ -12,11 +12,23 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package annotator
+// Package cachedir implements an annotator for packages that are in cache directories.
+package cachedir
 
 import (
+	"context"
 	"path/filepath"
 	"regexp"
+
+	"github.com/google/osv-scalibr/annotator"
+	"github.com/google/osv-scalibr/extractor"
+	"github.com/google/osv-scalibr/inventory"
+	"github.com/google/osv-scalibr/plugin"
+)
+
+const (
+	// Name of the Annotator.
+	Name = "vex/cachedir"
 )
 
 // patterns to match cache directories
@@ -38,12 +50,41 @@ var cacheDirPatterns = []*regexp.Regexp{
 	regexp.MustCompile(`(C:/)?Windows/Temp/`),
 }
 
-// IsInsideCacheDir checks if the given path is inside a cache directory.
-func IsInsideCacheDir(path string) bool {
+// Annotator adds annotations to packages that are in cache directories.
+type Annotator struct{}
+
+// New returns a new Annotator.
+func New() annotator.Annotator { return &Annotator{} }
+
+// Name of the annotator.
+func (Annotator) Name() string { return Name }
+
+// Version of the annotator.
+func (Annotator) Version() int { return 0 }
+
+// Requirements of the annotator.
+func (Annotator) Requirements() *plugin.Capabilities { return &plugin.Capabilities{} }
+
+// Annotate adds annotations to packages that are in cache directories.
+func (Annotator) Annotate(ctx context.Context, input *annotator.ScanInput, results *inventory.Inventory) error {
+	for _, pkg := range results.Packages {
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		for _, loc := range pkg.Locations {
+			if isInsideCacheDir(loc) {
+				pkg.Annotations = append(pkg.Annotations, extractor.InsideCacheDir)
+				break
+			}
+		}
+	}
+	return nil
+}
+
+func isInsideCacheDir(path string) bool {
 	path = filepath.ToSlash(path)
 
 	// Check if the absolute path matches any of the known cache directory patterns
-
 	for _, r := range cacheDirPatterns {
 		if r.MatchString(path) {
 			return true

annotator/cachedir/cachedir_test.go

@@ -0,0 +1,88 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cachedir_test
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/osv-scalibr/annotator/cachedir"
+	"github.com/google/osv-scalibr/extractor"
+	"github.com/google/osv-scalibr/inventory"
+)
+
+func TestIsInsideCacheDir(t *testing.T) {
+	// Define test cases with different platform-specific paths
+	testCases := []struct {
+		inputPath           string
+		separator           rune // defaulting to '/'
+		wantCacheAnnotation bool
+	}{
+		// Linux/Unix
+		{inputPath: "/tmp/somefile", wantCacheAnnotation: true},
+		{inputPath: "/var/cache/apt/archives", wantCacheAnnotation: true},
+		{inputPath: "/home/user/.local/share/Trash/files/file.txt", wantCacheAnnotation: true},
+		{inputPath: "/home/user/.cache/thumbnails", wantCacheAnnotation: true},
+		{inputPath: "/home/user/projects/code", wantCacheAnnotation: false},
+
+		// macOS
+		{inputPath: "/Users/username/Library/Caches/com.apple.Safari", wantCacheAnnotation: true},
+		{inputPath: "/private/tmp/mytmpfile", wantCacheAnnotation: true},
+		{inputPath: "/System/Volumes/Data/private/var/tmp/file", wantCacheAnnotation: true},
+		{inputPath: "/System/Volumes/Data/private/tmp/file", wantCacheAnnotation: true},
+		{inputPath: "/Users/username/Documents", wantCacheAnnotation: false},
+
+		// Windows
+		{inputPath: "C:\\Users\\testuser\\AppData\\Local\\Temp\\tempfile.txt", separator: '\\', wantCacheAnnotation: true},
+		{inputPath: "C:\\Windows\\Temp\\log.txt", separator: '\\', wantCacheAnnotation: true},
+		{inputPath: "C:\\Program Files\\MyApp", separator: '\\', wantCacheAnnotation: false},
+
+		// Edge cases
+		{inputPath: "", wantCacheAnnotation: false},
+		{inputPath: "some/relative/path", wantCacheAnnotation: false},
+	}
+
+	for _, tt := range testCases {
+		t.Run(tt.inputPath, func(t *testing.T) {
+			if tt.separator == 0 {
+				tt.separator = '/'
+			}
+
+			if os.PathSeparator != tt.separator {
+				t.Skipf("Skipping IsInsideCacheDir(%q)", tt.inputPath)
+			}
+
+			inv := &inventory.Inventory{
+				Packages: []*extractor.Package{&extractor.Package{
+					Locations: []string{tt.inputPath},
+				}},
+			}
+			if err := cachedir.New().Annotate(context.Background(), nil, inv); err != nil {
+				t.Errorf("Annotate(%v): %v", inv, err)
+			}
+			var want []extractor.Annotation
+			if tt.wantCacheAnnotation {
+				want = []extractor.Annotation{extractor.InsideCacheDir}
+			}
+
+			got := inv.Packages[0].Annotations
+			if diff := cmp.Diff(want, got); diff != "" {
+				t.Errorf("Annotate(%v) (-want +got):\n%s", inv, diff)
+			}
+		})
+	}
+}