validator: introduce mode-aware constructors and validation API

code/go/internal/validator/modes/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 modes
+
+// Mode represents the validation context: which semantic rules run and how
+// linked (.link) files are handled during package validation.
+type Mode string
+
+const (
+	// Legacy preserves the original validation behavior: linked files are
+	// resolved transparently and no rules are mode-gated.
+	Legacy Mode = "legacy"
+	// Source validates a package as a checked-out source tree: linked files
+	// are resolved transparently and source-only rules are enforced.
+	Source Mode = "source"
+	// Build validates a package as a built artifact: linked files are
+	// unconditionally blocked and build-only rules are enforced.
+	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,18 +20,22 @@ 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"
 )
 
-// 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 modes.Mode
 
 	// WarningsAsErrors causes validation warnings to be reported as errors when true.
 	WarningsAsErrors bool
@@ -44,12 +48,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 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,12 +70,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 +210,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 +272,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 := NewSpec(*semver.MustParse(version), modes.Legacy)
 		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

@@ -116,7 +116,12 @@ 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)
+
+			v, err := NewFromFS(ModeLegacy, "test-package", c.fsys)
+			if !assert.NoError(t, err) {
+				return
+			}
+			err = v.Validate()
 			if c.valid {
 				assert.NoError(t, err)
 			} else {

code/go/pkg/validator/modes.go

@@ -0,0 +1,55 @@
+// 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 (
+	"io/fs"
+
+	"github.com/elastic/package-spec/v3/code/go/internal/linkedfiles"
+	"github.com/elastic/package-spec/v3/code/go/internal/validator/modes"
+)
+
+// Mode represents the validation context: which rules apply and how linked files
+// are handled when creating a Validator from a path.
+// Use ModeLegacy, ModeSource, or ModeBuild.
+type Mode struct {
+	internal modes.Mode
+	// wrapFS builds the filesystem for path-based validation (NewFromPath).
+	// It is not applied by NewFromFS, which takes the caller's filesystem as-is.
+	wrapFS func(location string, fsys fs.FS) fs.FS
+}
+
+var (
+	// ModeLegacy preserves the original validation behavior: linked (.link) files
+	// are resolved transparently and no rules are mode-gated.
+	// Use this mode when backward compatibility with existing callers is required.
+	ModeLegacy = Mode{
+		internal: modes.Legacy,
+		wrapFS: func(location string, fsys fs.FS) fs.FS {
+			return linkedfiles.NewFS(location, fsys)
+		},
+	}
+
+	// ModeSource validates a package as a checked-out source tree.
+	// Linked (.link) files are resolved transparently.
+	// Source-only rules (e.g. dev-folder checks) are enforced; build-only rules are skipped.
+	ModeSource = Mode{
+		internal: modes.Source,
+		wrapFS: func(location string, fsys fs.FS) fs.FS {
+			return linkedfiles.NewFS(location, fsys)
+		},
+	}
+
+	// ModeBuild validates a package as a built artifact — the output of
+	// elastic-package build, a zip archive, or a package served by the registry.
+	// Linked (.link) files are unconditionally blocked.
+	// Build-only rules are enforced; source-only rules are skipped.
+	ModeBuild = Mode{
+		internal: modes.Build,
+		wrapFS: func(_ string, fsys fs.FS) fs.FS {
+			return linkedfiles.NewBlockFS(fsys)
+		},
+	}
+)