validator: introduce mode-aware constructors and validation API

code/go/internal/validator/modes.go

@@ -0,0 +1,30 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+package validator
+
+// Mode represents the validation context: which semantic rules run and how
+// linked (.link) files are handled during package validation.
+type Mode string
+
+const (
+	// LegacyMode preserves the original validation behavior: linked files are
+	// resolved transparently and no rules are mode-gated.
+	LegacyMode Mode = "legacy"
+	// SourceMode validates a package as a checked-out source tree: linked files
+	// are resolved transparently and source-only rules are enforced.
+	SourceMode Mode = "source"
+	// BuildMode validates a package as a built artifact: linked files are
+	// unconditionally blocked and build-only rules are enforced.
+	BuildMode Mode = "build"
+)
+
+// Valid reports whether m is a recognised validation mode.
+func (m Mode) Valid() bool {
+	switch m {
+	case LegacyMode, SourceMode, BuildMode:
+		return true
+	}
+	return false
+}

code/go/internal/validator/modes_test.go

@@ -0,0 +1,45 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+package validator
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValid(t *testing.T) {
+	tests := map[string]struct {
+		mode  Mode
+		valid bool
+	}{
+		"valid": {
+			mode:  LegacyMode,
+			valid: true,
+		},
+		"invalid": {
+			mode:  Mode("invalid"),
+			valid: false,
+		},
+		"source": {
+			mode:  SourceMode,
+			valid: true,
+		},
+		"build": {
+			mode:  BuildMode,
+			valid: true,
+		},
+		"": {
+			mode:  Mode(""),
+			valid: false,
+		},
+	}
+
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			assert.Equal(t, test.valid, test.mode.Valid(), "mode %s should be %v", test.mode, test.valid)
+		})
+	}
+}

code/go/internal/validator/spec.go

@@ -24,14 +24,17 @@ import (
 	"github.com/elastic/package-spec/v3/code/go/pkg/specerrors"
 )
 
-// Spec represents a package specification
+// Spec represents a versioned package specification and the validation mode
+// used to evaluate packages against it.
 type Spec struct {
 	// version is the version requested, what is included in the package, possibly without prerelease tags.
 	version semver.Version
 	// specVersion is the version of the spec actually loaded, what can include prerelease tags.
 	specVersion semver.Version
 	// fs contains the filesystem of the spec.
 	fs fs.FS
+	// mode is the validation mode (legacy, source, build).
+	mode Mode
 
 	// WarningsAsErrors causes validation warnings to be reported as errors when true.
 	WarningsAsErrors bool
@@ -44,12 +47,16 @@ type validationRules []validationRule
 // GASpecCheckVersion represents minimum version to start checking for unreleased version of the spec
 var GASpecCheckVersion = semver.MustParse("3.0.1")
 
-// NewSpec creates a new Spec for the given version
-func NewSpec(version semver.Version) (*Spec, error) {
+// NewSpec creates a new Spec for the given version and validation mode.
+// Returns an error if version is not a known spec version or if mode is invalid.
+func NewSpec(version semver.Version, mode Mode) (*Spec, error) {
 	specVersion, err := spec.CheckVersion(version)
 	if err != nil {
 		return nil, fmt.Errorf("could not load specification for version [%s]: %w", version.String(), err)
 	}
+	if !mode.Valid() {
+		return nil, fmt.Errorf("invalid validation mode %q", mode)
+	}
 
 	// With more current versions this is reported as a filterable validation error for GA packages.
 	if version.LessThan(GASpecCheckVersion) {
@@ -62,12 +69,15 @@ func NewSpec(version semver.Version) (*Spec, error) {
 		version:     version,
 		specVersion: *specVersion,
 		fs:          spec.FS(),
+		mode:        mode,
 	}
 
 	return &s, nil
 }
 
-// ValidatePackage validates the given Package against the Spec
+// ValidatePackage validates the given Package against the Spec, running both
+// syntactic and semantic rules. The mode embedded in the Spec controls which
+// semantic rules are active.
 func (s Spec) ValidatePackage(pkg packages.Package) specerrors.ValidationErrors {
 	var errs specerrors.ValidationErrors
 
@@ -199,6 +209,7 @@ func (s Spec) rules(pkgType string, rootSpec spectypes.ItemSpec) validationRules
 		since *semver.Version
 		until *semver.Version
 		types []string
+		modes []Mode
 	}{
 		{fn: semantic.ValidateVersionIntegrity},
 		{fn: semantic.ValidateChangelogLinks},
@@ -260,6 +271,10 @@ func (s Spec) rules(pkgType string, rootSpec spectypes.ItemSpec) validationRules
 			continue
 		}
 
+		if rule.modes != nil && !slices.Contains(rule.modes, s.mode) {
+			continue
+		}
+
 		validationRules = append(validationRules, rule.fn)
 	}
 

code/go/internal/validator/spec_test.go

@@ -26,7 +26,7 @@ func TestNewSpec(t *testing.T) {
 	}
 
 	for version, test := range tests {
-		spec, err := NewSpec(*semver.MustParse(version))
+		spec, err := NewSpec(*semver.MustParse(version), LegacyMode)
 		if test.expectedErrContains == "" {
 			require.NoError(t, err)
 			require.IsType(t, &Spec{}, spec)
@@ -44,6 +44,7 @@ func TestNoBetaFeatures_Package_GA(t *testing.T) {
 		version:     *semver.MustParse("1.0.0"),
 		specVersion: *semver.MustParse("1.0.0"),
 		fs:          fspath.DirFS("testdata/fakespec"),
+		mode:        LegacyMode,
 	}
 	pkg, err := packages.NewPackage("testdata/packages/features_ga")
 	require.NoError(t, err)
@@ -58,6 +59,7 @@ func TestBetaFeatures_Package_GA(t *testing.T) {
 		version:     *semver.MustParse("1.0.0"),
 		specVersion: *semver.MustParse("1.0.0"),
 		fs:          fspath.DirFS("testdata/fakespec"),
+		mode:        LegacyMode,
 	}
 	pkg, err := packages.NewPackage("testdata/packages/features_beta")
 	require.NoError(t, err)
@@ -134,6 +136,7 @@ func TestFolderSpecInvalid(t *testing.T) {
 				version:     c.version,
 				specVersion: c.version,
 				fs:          c.spec,
+				mode:        LegacyMode,
 			}
 			pkg, err := packages.NewPackage(c.pkgPath)
 			require.NoError(t, err)

code/go/pkg/validator/limits_test.go

@@ -116,6 +116,7 @@ func TestLimitsValidation(t *testing.T) {
 	for _, c := range cases {
 		t.Run(c.title, func(t *testing.T) {
 			t.Parallel()
+
 			err := ValidateFromFS("test-package", c.fsys)
 			if c.valid {
 				assert.NoError(t, err)

code/go/pkg/validator/validator.go

@@ -9,6 +9,7 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"log"
 	"os"
 
 	"github.com/elastic/package-spec/v3/code/go/internal/linkedfiles"
@@ -17,25 +18,80 @@ import (
 	"github.com/elastic/package-spec/v3/code/go/internal/validator/common"
 )
 
-// ValidateFromPath validates a package located at the given path against the
-// appropriate specification and returns any errors.
-func ValidateFromPath(packageRootPath string) error {
-	// We wrap the fs.FS with a linkedfiles.LinksFS to handle linked files.
-	linksFS := linkedfiles.NewFS(packageRootPath, os.DirFS(packageRootPath))
-	return ValidateFromFS(packageRootPath, linksFS)
+// Mode is the validation context that controls semantic rules and linked-file handling.
+type Mode = validator.Mode
+
+var (
+	// LegacyMode preserves the original validation behavior.
+	LegacyMode Mode = validator.LegacyMode
+	// SourceMode validates a checked-out source tree.
+	SourceMode Mode = validator.SourceMode
+	// BuildMode validates a built package artifact.
+	BuildMode Mode = validator.BuildMode
+)
+
+// Validator holds the configuration for a package validation run.
+// Create one with NewValidator, then call ValidateFromPath, ValidateFromZip, or ValidateFromFS.
+type Validator struct {
+	mode             Mode
+	warningsAsErrors bool
+}
+
+// Option configures a Validator.
+type Option func(*Validator)
+
+// WithWarningsAsErrors controls whether validation warnings are promoted to errors.
+// When enabled is true, warnings are reported as errors regardless of the
+// PACKAGE_SPEC_WARNINGS_AS_ERRORS environment variable. When enabled is false,
+// warnings remain warnings even if the environment variable is set.
+func WithWarningsAsErrors(enabled bool) Option {
+	return func(v *Validator) { v.warningsAsErrors = enabled }
+}
+
+// New creates a Validator for the given mode and options.
+func New(mode Mode, opts ...Option) (*Validator, error) {
+	if !mode.Valid() {
+		return nil, fmt.Errorf("invalid validation mode %q", mode)
+	}
+	v := &Validator{
+		mode:             mode,
+		warningsAsErrors: common.IsDefinedWarningsAsErrors(),
+	}
+	for _, opt := range opts {
+		opt(v)
+	}
+
+	return v, nil
+}
+
+// ValidateFromPath validates the package at path on disk.
+func (v *Validator) ValidateFromPath(path string) error {
+	fsys := os.DirFS(path)
+	if v.mode == BuildMode {
+		fsys = linkedfiles.NewBlockFS(fsys)
+	} else {
+		fsys = linkedfiles.NewFS(path, fsys)
+	}
+
+	return v.validate(path, fsys)
 }
 
-// ValidateFromZip validates a package on its zip format.
-func ValidateFromZip(packagePath string) error {
-	r, err := zip.OpenReader(packagePath)
+// ValidateFromZip validates the package stored in a zip file.
+// Zip files are supported in LegacyMode and BuildMode only.
+func (v *Validator) ValidateFromZip(zipPath string) error {
+	if v.mode != LegacyMode && v.mode != BuildMode {
+		return errors.New("zip files are only supported in LegacyMode or BuildMode")
+	}
+
+	r, err := zip.OpenReader(zipPath)
 	if err != nil {
-		return fmt.Errorf("failed to open zip file (%s): %w", packagePath, err)
+		return fmt.Errorf("failed to open zip file (%s): %w", zipPath, err)
 	}
 	defer r.Close()
 
 	dirs, err := fs.ReadDir(r, ".")
 	if err != nil {
-		return fmt.Errorf("failed to read root directory in zip file (%s): %w", packagePath, err)
+		return fmt.Errorf("failed to read root directory in zip file (%s): %w", zipPath, err)
 	}
 	if len(dirs) != 1 {
 		return fmt.Errorf("a single directory is expected in zip file, %d found", len(dirs))
@@ -46,39 +102,78 @@ func ValidateFromZip(packagePath string) error {
 		return err
 	}
 
-	return ValidateFromFS(packagePath, subDir)
+	fsys := linkedfiles.NewBlockFS(subDir)
+	return v.validate(zipPath, fsys)
 }
 
-// ValidateFromFS validates a package against the appropiate specification and returns any errors.
-// Package files are obtained through the given filesystem.
-func ValidateFromFS(location string, fsys fs.FS) error {
-	return validateFromFS(location, fsys, common.IsDefinedWarningsAsErrors())
+// ValidateFromFS validates the package accessible through fsys at location.
+func (v *Validator) ValidateFromFS(location string, fsys fs.FS) error {
+	if v.mode == LegacyMode {
+		// If we are not explicitly using the linkedfiles.FS, we wrap fsys with
+		// a linkedfiles.BlockFS to block the use of linked files.
+		if _, ok := fsys.(*linkedfiles.FS); !ok {
+			fsys = linkedfiles.NewBlockFS(fsys)
+		}
+	} else if _, ok := fsys.(*linkedfiles.FS); ok && v.mode == BuildMode {
+		return errors.New("linked files are not supported in BuildMode")
+	} else if _, ok := fsys.(*linkedfiles.BlockFS); ok && v.mode == SourceMode {
+		return errors.New("block linked files are not supported in SourceMode")
+	}
+
+	return v.validate(location, fsys)
 }
 
-func validateFromFS(location string, fsys fs.FS, warningsAsErrors bool) error {
-	// If we are not explicitly using the linkedfiles.FS, we wrap fsys with
-	// a linkedfiles.BlockFS to block the use of linked files.
-	if _, ok := fsys.(*linkedfiles.FS); !ok {
-		fsys = linkedfiles.NewBlockFS(fsys)
-	}
+func (v *Validator) validate(location string, fsys fs.FS) error {
 	pkg, err := packages.NewPackageFromFS(location, fsys)
 	if err != nil {
 		return err
 	}
-
 	if pkg.SpecVersion == nil {
 		return errors.New("could not determine specification version for package")
 	}
 
-	spec, err := validator.NewSpec(*pkg.SpecVersion)
+	spec, err := validator.NewSpec(*pkg.SpecVersion, v.mode)
 	if err != nil {
 		return err
 	}
-	spec.WarningsAsErrors = warningsAsErrors
+	spec.WarningsAsErrors = v.warningsAsErrors
+
+	if v.mode != LegacyMode {
+		log.Printf("Warning: validation mode '%s' is in technical preview", v.mode)
+	}
 
 	if errs := spec.ValidatePackage(*pkg); len(errs) > 0 {
 		return errs
 	}
-
 	return nil
 }
+
+// ValidateFromPath is a convenience function that creates a new Validator in LegacyMode and calls ValidateFromPath.
+// Deprecated: Use NewValidator and ValidateFromPath instead.
+func ValidateFromPath(path string) error {
+	v, err := New(LegacyMode)
+	if err != nil {
+		return err
+	}
+	return v.ValidateFromPath(path)
+}
+
+// ValidateFromZip is a convenience function that creates a new Validator in LegacyMode and calls ValidateFromZip.
+// Deprecated: Use NewValidator and ValidateFromZip instead.
+func ValidateFromZip(zipPath string) error {
+	v, err := New(LegacyMode)
+	if err != nil {
+		return err
+	}
+	return v.ValidateFromZip(zipPath)
+}
+
+// ValidateFromFS is a convenience function that creates a new Validator in LegacyMode and calls ValidateFromFS.
+// Deprecated: Use NewValidator and ValidateFromFS instead.
+func ValidateFromFS(location string, fsys fs.FS) error {
+	v, err := New(LegacyMode)
+	if err != nil {
+		return err
+	}
+	return v.ValidateFromFS(location, fsys)
+}