validator: introduce mode-aware constructors and validation API

code/go/internal/validator/modes/modes.go

@@ -0,0 +1,25 @@
+// 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 modes
+
+// Mode represents the validation mode used when validating a package.
+type Mode string
+
+// Validation modes for package validation: Legacy preserves existing behavior,
+// Source validates checked-out source trees, and Build validates built artifacts.
+const (
+	Legacy Mode = "legacy"
+	Source Mode = "source"
+	Build  Mode = "build"
+)
+
+// Valid reports whether m is a recognised validation mode.
+func (m Mode) Valid() bool {
+	switch m {
+	case Legacy, Source, Build:
+		return true
+	}
+	return false
+}

code/go/internal/validator/modes/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 modes
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValid(t *testing.T) {
+	tests := map[string]struct {
+		mode  Mode
+		valid bool
+	}{
+		"valid": {
+			mode:  Legacy,
+			valid: true,
+		},
+		"invalid": {
+			mode:  Mode("invalid"),
+			valid: false,
+		},
+		"source": {
+			mode:  Source,
+			valid: true,
+		},
+		"build": {
+			mode:  Build,
+			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

@@ -20,6 +20,7 @@ import (
 	"github.com/elastic/package-spec/v3/code/go/internal/loader"
 	"github.com/elastic/package-spec/v3/code/go/internal/packages"
 	"github.com/elastic/package-spec/v3/code/go/internal/spectypes"
+	"github.com/elastic/package-spec/v3/code/go/internal/validator/modes"
 	"github.com/elastic/package-spec/v3/code/go/internal/validator/semantic"
 	"github.com/elastic/package-spec/v3/code/go/pkg/specerrors"
 )
@@ -32,6 +33,8 @@ type Spec struct {
 	specVersion semver.Version
 	// fs contains the filesystem of the spec.
 	fs fs.FS
+	// mode is the validation mode (legacy, source, build).
+	mode modes.Mode
 
 	// WarningsAsErrors causes validation warnings to be reported as errors when true.
 	WarningsAsErrors bool
@@ -44,12 +47,15 @@ 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.
+func newSpec(version semver.Version, mode modes.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,11 +68,27 @@ func NewSpec(version semver.Version) (*Spec, error) {
 		version:     version,
 		specVersion: *specVersion,
 		fs:          spec.FS(),
+		mode:        mode,
 	}
 
 	return &s, nil
 }
 
+// NewLegacySpec creates a new Spec for the given version using the legacy specification.
+func NewLegacySpec(version semver.Version) (*Spec, error) {
+	return newSpec(version, modes.Legacy)
+}
+
+// NewBuildSpec creates a new Spec for the given version using the build specification.
+func NewBuildSpec(version semver.Version) (*Spec, error) {
+	return newSpec(version, modes.Build)
+}
+
+// NewSourceSpec creates a new Spec for the given version using the source specification.
+func NewSourceSpec(version semver.Version) (*Spec, error) {
+	return newSpec(version, modes.Source)
+}
+
 // ValidatePackage validates the given Package against the Spec
 func (s Spec) ValidatePackage(pkg packages.Package) specerrors.ValidationErrors {
 	var errs specerrors.ValidationErrors
@@ -199,6 +221,7 @@ func (s Spec) rules(pkgType string, rootSpec spectypes.ItemSpec) validationRules
 		since *semver.Version
 		until *semver.Version
 		types []string
+		modes []modes.Mode
 	}{
 		{fn: semantic.ValidateVersionIntegrity},
 		{fn: semantic.ValidateChangelogLinks},
@@ -260,6 +283,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

@@ -13,9 +13,10 @@ import (
 
 	"github.com/elastic/package-spec/v3/code/go/internal/fspath"
 	"github.com/elastic/package-spec/v3/code/go/internal/packages"
+	"github.com/elastic/package-spec/v3/code/go/internal/validator/modes"
 )
 
-func TestNewSpec(t *testing.T) {
+func TestNewLegacySpec(t *testing.T) {
 	tests := map[string]struct {
 		expectedErrContains string
 	}{
@@ -26,7 +27,7 @@ func TestNewSpec(t *testing.T) {
 	}
 
 	for version, test := range tests {
-		spec, err := NewSpec(*semver.MustParse(version))
+		spec, err := NewLegacySpec(*semver.MustParse(version))
 		if test.expectedErrContains == "" {
 			require.NoError(t, err)
 			require.IsType(t, &Spec{}, spec)
@@ -44,6 +45,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:        modes.Legacy,
 	}
 	pkg, err := packages.NewPackage("testdata/packages/features_ga")
 	require.NoError(t, err)
@@ -58,6 +60,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:        modes.Legacy,
 	}
 	pkg, err := packages.NewPackage("testdata/packages/features_beta")
 	require.NoError(t, err)
@@ -134,6 +137,7 @@ func TestFolderSpecInvalid(t *testing.T) {
 				version:     c.version,
 				specVersion: c.version,
 				fs:          c.spec,
+				mode:        modes.Legacy,
 			}
 			pkg, err := packages.NewPackage(c.pkgPath)
 			require.NoError(t, err)

code/go/pkg/validator/limits_test.go

@@ -15,9 +15,11 @@ import (
 	"testing"
 	"time"
 
+	"github.com/Masterminds/semver/v3"
 	"github.com/stretchr/testify/assert"
 
 	"github.com/elastic/package-spec/v3/code/go/internal/spectypes"
+	"github.com/elastic/package-spec/v3/code/go/internal/validator"
 )
 
 func TestLimitsValidation(t *testing.T) {
@@ -116,7 +118,11 @@ 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)
+
+			specFn := func(version semver.Version) (*validator.Spec, error) {
+				return validator.NewLegacySpec(version)
+			}
+			err := validateFromFS("test-package", c.fsys, specFn)
 			if c.valid {
 				assert.NoError(t, err)
 			} else {

code/go/pkg/validator/validator.go

@@ -11,21 +11,61 @@ import (
 	"io/fs"
 	"os"
 
+	"github.com/Masterminds/semver/v3"
+
 	"github.com/elastic/package-spec/v3/code/go/internal/linkedfiles"
 	"github.com/elastic/package-spec/v3/code/go/internal/packages"
 	"github.com/elastic/package-spec/v3/code/go/internal/validator"
 	"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.
+type specFn func(semver.Version) (*validator.Spec, error)
+
+// ValidateFromPath validates a package located at the given path using the legacy specification.
+// This function preserves byte-for-byte identical behavior with existing validation workflows.
+// Linked (.link) files are resolved transparently.
+// Deprecated: Use ValidateFromSourcePath or ValidateFromBuildPath depending on the package type.
 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)
+
+	legacySpec := func(version semver.Version) (*validator.Spec, error) {
+		return validator.NewLegacySpec(version)
+	}
+
+	return validateFromFS(packageRootPath, linksFS, legacySpec)
+}
+
+// ValidateFromBuildPath validates a built package located at the given path.
+// This function uses the build specification, appropriate for packages produced by
+// elastic-package build, distributed as zip files, or served by the package registry.
+// Linked files (.link) are blocked; source-only artifacts are rejected.
+func ValidateFromBuildPath(packageRootPath string) error {
+	fs := os.DirFS(packageRootPath)
+
+	buildSpec := func(version semver.Version) (*validator.Spec, error) {
+		return validator.NewBuildSpec(version)
+	}
+	return validateFromFS(packageRootPath, fs, buildSpec)
+}
+
+// ValidateFromSourcePath validates a package source tree located at the given path.
+// This function uses the source specification for checked-out source trees.
+// Linked (.link) files are resolved transparently.
+func ValidateFromSourcePath(packageRootPath string) error {
+	// We wrap the fs.FS with a linkedfiles.LinksFS to handle linked files.
+	linksFS := linkedfiles.NewFS(packageRootPath, os.DirFS(packageRootPath))
+
+	sourceSpec := func(version semver.Version) (*validator.Spec, error) {
+		return validator.NewSourceSpec(version)
+	}
+
+	return validateFromFS(packageRootPath, linksFS, sourceSpec)
 }
 
-// ValidateFromZip validates a package on its zip format.
+// ValidateFromZip validates a package in zip file format.
+// This function uses the build specification since zip files are by definition built packages.
+// Linked files (.link) are blocked; source-only artifacts are rejected.
 func ValidateFromZip(packagePath string) error {
 	r, err := zip.OpenReader(packagePath)
 	if err != nil {
@@ -46,16 +86,16 @@ func ValidateFromZip(packagePath string) error {
 		return err
 	}
 
-	return ValidateFromFS(packagePath, subDir)
-}
+	buildSpec := func(version semver.Version) (*validator.Spec, error) {
+		return validator.NewBuildSpec(version)
+	}
 
-// 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())
+	return validateFromFS(packagePath, subDir, buildSpec)
 }
 
-func validateFromFS(location string, fsys fs.FS, warningsAsErrors bool) error {
+// validateFromFS validates a package against the appropriate specification and returns any errors.
+// Package files are obtained through the given filesystem.
+func validateFromFS(location string, fsys fs.FS, specFn specFn) 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 {
@@ -70,11 +110,11 @@ func validateFromFS(location string, fsys fs.FS, warningsAsErrors bool) error {
 		return errors.New("could not determine specification version for package")
 	}
 
-	spec, err := validator.NewSpec(*pkg.SpecVersion)
+	spec, err := specFn(*pkg.SpecVersion)
 	if err != nil {
 		return err
 	}
-	spec.WarningsAsErrors = warningsAsErrors
+	spec.WarningsAsErrors = common.IsDefinedWarningsAsErrors()
 
 	if errs := spec.ValidatePackage(*pkg); len(errs) > 0 {
 		return errs