validator: introduce mode-aware constructors and validation API

.gitignore

@@ -6,3 +6,5 @@ fuzz
 /build/
 .vscode/
 .DS_Store
+
+.scratch/

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

@@ -0,0 +1,24 @@
+// 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. The public API re-exports these as validator.Mode* constants.
+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/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,8 +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.
+// If mode is empty, it defaults to modes.Legacy.
+func NewSpec(version semver.Version, mode modes.Mode) (*Spec, error) {
+	if mode == "" {
+		mode = modes.Legacy
+	}
+	if !mode.Valid() {
+		return nil, fmt.Errorf("invalid validation mode %q", mode)
+	}
+
 	specVersion, err := spec.CheckVersion(version)
 	if err != nil {
 		return nil, fmt.Errorf("could not load specification for version [%s]: %w", version.String(), err)
@@ -62,6 +73,7 @@ func NewSpec(version semver.Version) (*Spec, error) {
 		version:     version,
 		specVersion: *specVersion,
 		fs:          spec.FS(),
+		mode:        mode,
 	}
 
 	return &s, nil
@@ -199,6 +211,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 +273,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,6 +13,7 @@ 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) {
@@ -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)

code/go/pkg/validator/api.go

@@ -0,0 +1,203 @@
+// 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 (
+	"archive/zip"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+
+	"github.com/elastic/package-spec/v3/code/go/internal/linkedfiles"
+	"github.com/elastic/package-spec/v3/code/go/internal/packages"
+	internalvalidator "github.com/elastic/package-spec/v3/code/go/internal/validator"
+	"github.com/elastic/package-spec/v3/code/go/internal/validator/common"
+)
+
+// Validator holds the configuration for a package validation run.
+// Create one with NewFromPath, NewFromZip, or NewFromFS, then call Validate.
+type Validator struct {
+	mode             Mode
+	location         string
+	fsys             fs.FS
+	warningsAsErrors bool
+	// closer is non-nil when the Validator owns a resource (e.g. a zip reader)
+	// that must be released after Validate returns.
+	closer io.Closer
+}
+
+// Option configures a Validator.
+type Option func(*Validator)
+
+// WithWarningsAsErrors makes validation warnings count as errors when enabled is true.
+func WithWarningsAsErrors(enabled bool) Option {
+	return func(v *Validator) { v.warningsAsErrors = enabled }
+}
+
+// NewFromPath returns a Validator for the package rooted at packageRootPath.
+//
+// For ModeLegacy and ModeSource the filesystem honours linked (.link) files;
+// for ModeBuild linked files are blocked (matching a built package artifact).
+func NewFromPath(mode Mode, packageRootPath string, opts ...Option) (*Validator, error) {
+	if !mode.Valid() {
+		return nil, fmt.Errorf("invalid validation mode %q", mode)
+	}
+
+	info, err := os.Stat(packageRootPath)
+	if err != nil {
+		return nil, fmt.Errorf("invalid package path %q: %w", packageRootPath, err)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("invalid package path %q: not a directory", packageRootPath)
+	}
+
+	var fsys fs.FS
+	if mode == ModeBuild {
+		fsys = linkedfiles.NewBlockFS(os.DirFS(packageRootPath))
+	} else {
+		// ModeLegacy and ModeSource: resolve linked files transparently.
+		fsys = linkedfiles.NewFS(packageRootPath, os.DirFS(packageRootPath))
+	}
+	return buildValidator(mode, packageRootPath, fsys, nil, opts), nil
+}
+
+// NewFromZip returns a Validator for the package stored in the zip file at zipPath.
+//
+// Zip files always contain built packages — they are the output format produced
+// by elastic-package build and consumed by the package registry and Fleet.
+// Validation always runs in ModeBuild; source-only artifacts (_dev/, .link files,
+// external: ecs references) are therefore rejected.
+//
+// NOTE: ModeBuild-specific validation rules are not yet implemented; ModeBuild
+// and ModeLegacy currently produce identical rule sets. This is intentional —
+// the mode is set here so that future PRs can attach build-only rules without
+// changing the public API.
+//
+// The returned Validator owns the underlying zip reader; calling Validate closes it.
+// Do not call Validate more than once on a Validator created by NewFromZip.
+func NewFromZip(zipPath string, opts ...Option) (_ *Validator, err error) {
+	r, openErr := zip.OpenReader(zipPath)
+	if openErr != nil {
+		return nil, fmt.Errorf("failed to open zip file (%s): %w", zipPath, openErr)
+	}
+	// Close the reader on any error path; on success the Validator takes ownership.
+	defer func() {
+		if err != nil {
+			if cerr := r.Close(); cerr != nil {
+				err = errors.Join(err, cerr)
+			}
+		}
+	}()
+
+	dirs, err := fs.ReadDir(r, ".")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read root directory in zip file (%s): %w", zipPath, err)
+	}
+	if len(dirs) != 1 {
+		return nil, fmt.Errorf("a single directory is expected in zip file, %d found", len(dirs))
+	}
+
+	subDir, err := fs.Sub(r, dirs[0].Name())
+	if err != nil {
+		return nil, err
+	}
+
+	// Zip archives contain built packages; linked files are always blocked.
+	fsys := linkedfiles.NewBlockFS(subDir)
+	return buildValidator(ModeBuild, zipPath, fsys, r, opts), nil
+}
+
+// NewFromFS returns a Validator for the package accessible through fsys at location.
+//
+// Linked-file handling depends on mode:
+//   - ModeSource: if fsys is not already a *linkedfiles.FS it is wrapped with
+//     linkedfiles.NewFS so .link files are resolved transparently.
+//   - ModeLegacy: a pre-wrapped *linkedfiles.FS is preserved as-is (links
+//     resolved); any other filesystem is wrapped with BlockFS. This matches the
+//     behaviour of the deprecated ValidateFromFS.
+//   - ModeBuild: BlockFS is always applied, even if fsys is already a
+//     *linkedfiles.FS, so linked files are unconditionally rejected.
+func NewFromFS(mode Mode, location string, fsys fs.FS, opts ...Option) (*Validator, error) {
+	if !mode.Valid() {
+		return nil, fmt.Errorf("invalid validation mode %q", mode)
+	}
+
+	info, err := fs.Stat(fsys, ".")
+	if err != nil {
+		return nil, fmt.Errorf("invalid package filesystem at %q: %w", location, err)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("invalid package filesystem at %q: root is not a directory", location)
+	}
+
+	_, isLinkedFS := fsys.(*linkedfiles.FS)
+	switch mode {
+	case ModeSource:
+		if !isLinkedFS {
+			fsys = linkedfiles.NewFS(location, fsys)
+		}
+	case ModeBuild:
+		// Always block, even a pre-wrapped *linkedfiles.FS.
+		fsys = linkedfiles.NewBlockFS(fsys)
+	default: // ModeLegacy
+		// Preserve a pre-wrapped *linkedfiles.FS; block everything else.
+		// Matches the old validateFromFS behaviour.
+		if !isLinkedFS {
+			fsys = linkedfiles.NewBlockFS(fsys)
+		}
+	}
+	return buildValidator(mode, location, fsys, nil, opts), nil
+}
+
+// buildValidator is the shared internal constructor.
+func buildValidator(mode Mode, location string, fsys fs.FS, closer io.Closer, opts []Option) *Validator {
+	v := &Validator{
+		mode:             mode,
+		location:         location,
+		fsys:             fsys,
+		warningsAsErrors: common.IsDefinedWarningsAsErrors(),
+		closer:           closer,
+	}
+	for _, opt := range opts {
+		opt(v)
+	}
+	return v
+}
+
+// Validate runs package validation and returns any errors encountered.
+//
+// If the Validator was created by NewFromZip it owns an open zip reader;
+// Validate closes it on return, so Validate must not be called more than once
+// on such a Validator.
+func (v *Validator) Validate() (err error) {
+	if v.closer != nil {
+		defer func() {
+			if cerr := v.closer.Close(); cerr != nil {
+				err = errors.Join(err, cerr)
+			}
+		}()
+	}
+
+	pkg, err := packages.NewPackageFromFS(v.location, v.fsys)
+	if err != nil {
+		return err
+	}
+	if pkg.SpecVersion == nil {
+		return errors.New("could not determine specification version for package")
+	}
+
+	spec, err := internalvalidator.NewSpec(*pkg.SpecVersion, v.mode)
+	if err != nil {
+		return err
+	}
+	spec.WarningsAsErrors = v.warningsAsErrors
+
+	if errs := spec.ValidatePackage(*pkg); len(errs) > 0 {
+		return errs
+	}
+	return nil
+}