improve dependency version constraint and errors

Overhauls the parsing of the Dependency structs and subfields to
actually use semver constraint checks and improve the error messages
returned when an invalid dependency struct is specified or a dependency
version doesn't meet the specified constraint, as shown in this example:

```
$ gdt run scenario/testdata/depends-not-satisfied-version-constraint.yaml
Error: runtime error: dependency not satisfied: "ls" failed version constraint ">99.9.9"
```

Issue gdt-dev/gdt#60

Signed-off-by: Jay Pipes <jaypipes@gmail.com>

Author: jaypipes

README.md

@@ -26,17 +26,26 @@ All `gdt` scenarios have the following fields:
 * `fixtures`: (optional) list of strings indicating named fixtures that will be
   started before any of the tests in the file are run
 * `depends`: (optional) list of [`Dependency`][dependency] objects that
-  describe a program or package that should be available in the host's `PATH`
+  describe a program binary that should be available in the host's `PATH`
   that the test scenario depends on.
-* `depends.name`: string name of the program or package the test scenario
-  depends on.
+* `depends.name`: string name of the program the test scenario depends on.
 * `depends.when`: (optional) object describing any constraints/conditions that
   should apply to the evaluation of the dependency.
 * `depends.when.os`: (optional) string operating system. if set, the dependency
   is only checked for that OS.
-* `depends.when.version`: (optional) string version constraint. if set, the
+* `depends.version`: (optional) struct containing version constraint and
+  selector instructions.
+* `depends.version.constraint`: optional string version constraint. if set, the
   program or package must be available on the host `PATH` and must satisfy the
   version constraint.
+* `depends.version.selector`: (optional) struct containing selector
+  instructions for gdt to determine the version of a dependent binary.
+* `depends.version.selector.args`: (optional) set of string arguments to call
+  the dependency binary with in order to get the program's version information.
+  If empty, we default to []string{`-v`}.
+* `depends.version.selector.filter`: (optional) regular expression to run
+  against the returned output from executing the dependency binary with the
+  `selector.args` arguments. If empty, we use a loose semver matching regex.
 * `skip-if`: (optional) list of [`Spec`][basespec] specializations that will be
   evaluated *before* running any test in the scenario. If any of these
   conditions evaluates successfully, the test scenario will be skipped.
@@ -249,6 +258,54 @@ $ gdt run myapp.yaml
 Error: runtime error: exec: "myapp": executable file not found in $PATH
 ```
 
+You may also specify a particular version constraint that must pass for a
+dependent binary with the `depends.version.constraint` field. For example,
+let's assume I want to declare my test scenario requires that at least version
+`1.2.3` of `myapp` must be present on the host machine, I would do this:
+
+```yaml
+depends:
+ - name: myapp
+   version:
+     constraint: ">=1.2.3"
+```
+
+The `depends.version.constraint` field should be a valid Semantic Versioning
+constraint. Read more about [Semantic Version constraints][semver-constraints].
+
+By default to determine a binary's version, we pass a `-v` flag to the binary
+itself. If you know that a binary uses a different way of returning its version
+information, you can use the `depends.version.selector.args` field. As an
+example, the `ls` command line utility on Linux returns its version information
+when you pass the `--version` CLI flag, as shown here:
+
+```
+> ls --version
+ls (GNU coreutils) 9.4
+Copyright (C) 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by Richard M. Stallman and David MacKenzie.
+```
+
+If you wanted to require that, say, version 9.1 and later of the `ls`
+command-line utility was present on the host machine, you would do the
+following:
+
+```yaml
+depends:
+ - name: ls
+   version:
+     constraint: ">=9.1"
+     selector:
+       args:
+        - "--version"
+```
+
+[semver-constraints]: https://github.com/Masterminds/semver/blob/master/README.md#checking-version-constraints
+
 ### Passing variables to subsequent test specs
 
 A `gdt` test scenario is comprised of a list of test specs. These test specs

api/dependency.go

@@ -1,23 +1,220 @@
 package api
 
-// Dependency describes a prerequisite binary or package that must be present.
+import (
+	"regexp"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/samber/lo"
+	"gopkg.in/yaml.v3"
+
+	"github.com/gdt-dev/core/parse"
+)
+
+var (
+	ValidOSs = []string{
+		"linux",
+		"darwin",
+		"windows",
+	}
+)
+
+// Dependency describes a prerequisite binary that must be present.
 type Dependency struct {
-	// Name is the name of the binary or package
+	// Name is the name of the binary that must be present.
 	Name string `yaml:"name"`
 	// When describes any constraining conditions that apply to this
 	// Dependency.
-	When *DependencyConstraints `yaml:"when,omitempty"`
+	When *DependencyConditions `yaml:"when,omitempty"`
+	// Version contains instructions for constraining and selecting the
+	// dependency's version.
+	Version *DependencyVersion `yaml:"version,omitempty"`
 }
 
-// DependencyConstraints describes constraining conditions that apply to a
+func (d *Dependency) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "name":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedScalarAt(valNode)
+			}
+			d.Name = valNode.Value
+		case "when":
+			if valNode.Kind != yaml.MappingNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			var when DependencyConditions
+			if err := valNode.Decode(&when); err != nil {
+				return err
+			}
+			d.When = &when
+		case "version":
+			if valNode.Kind != yaml.MappingNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			var dv DependencyVersion
+			if err := valNode.Decode(&dv); err != nil {
+				return err
+			}
+			d.Version = &dv
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
+}
+
+// DependencyConditions describes constraining conditions that apply to a
 // Dependency, for instance whether the dependency is only required on a
-// particular OS or whether a particular version constraint applies to the
-// dependency.
-type DependencyConstraints struct {
+// particular OS.
+type DependencyConditions struct {
 	// OS indicates that the dependency only applies when the tests are run on
 	// a particular operating system.
 	OS string `yaml:"os,omitempty"`
-	// Version indicates a version constraint to apply to the dependency, e.g.
-	// >= 1.2.3
-	Version string `yaml:"version,omitempty"`
+}
+
+func (c *DependencyConditions) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "os":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedScalarAt(valNode)
+			}
+			os := valNode.Value
+			if os != "" {
+				if !lo.Contains(ValidOSs, os) {
+					return parse.InvalidOSAt(valNode, os, ValidOSs)
+				}
+				c.OS = os
+			}
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
+}
+
+// DependencyVersion expresses a version constraint that must be met for a
+// particular dependency and instructs gdt how to get the version for a
+// dependency from a binary or package manager.
+type DependencyVersion struct {
+	// Constraint indicates a version constraint to apply to the dependency,
+	// e.g.  '>= 1.2.3' would indicate that a version of the dependency binary
+	// after and including 1.2.3 must be present on the host.
+	Constraint        string              `yaml:"constraint"`
+	SemVerConstraints *semver.Constraints `yaml:"-"`
+	// Selector provides instructions to select the version from the binary.
+	Selector *DependencyVersionSelector `yaml:"selector,omitempty"`
+}
+
+func (v *DependencyVersion) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "constraint":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedScalarAt(valNode)
+			}
+			conStr := valNode.Value
+			if conStr != "" {
+				con, err := semver.NewConstraint(conStr)
+				if err != nil {
+					return parse.InvalidVersionConstraintAt(
+						valNode, conStr, err,
+					)
+				}
+				v.Constraint = conStr
+				v.SemVerConstraints = con
+			}
+		case "selector":
+			if valNode.Kind != yaml.MappingNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			var selector DependencyVersionSelector
+			if err := valNode.Decode(&selector); err != nil {
+				return err
+			}
+			v.Selector = &selector
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
+}
+
+// DependencyVersionSelector instructs gdt how to get the version of a binary.
+type DependencyVersionSelector struct {
+	// Args is the command-line to execute the dependency binary to output
+	// version information, e.g. '-v' or '--version-json'.
+	Args []string `yaml:"args,omitempty"`
+	// Filter is an optional regex to run against the output returned by
+	// Command, e.g. 'v?(\d)+\.(\d+)(\.(\d)+)?'.
+	Filter      string         `yaml:"filter,omitempty"`
+	FilterRegex *regexp.Regexp `yaml:"-"`
+}
+
+func (s *DependencyVersionSelector) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "args":
+			if valNode.Kind != yaml.SequenceNode {
+				return parse.ExpectedSequenceAt(valNode)
+			}
+			var args []string
+			if err := valNode.Decode(&args); err != nil {
+				return err
+			}
+			s.Args = args
+		case "filter":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			filter := valNode.Value
+			if filter != "" {
+				re, err := regexp.Compile(filter)
+				if err != nil {
+					return parse.InvalidRegexAt(valNode, filter, err)
+				}
+				s.Filter = filter
+				s.FilterRegex = re
+			}
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
 }

api/error.go

@@ -147,19 +147,29 @@ var (
 // DependencyNotSatified returns an ErrDependencyNotSatisfied with the supplied
 // dependency name and optional constraints.
 func DependencyNotSatisfied(dep *Dependency) error {
-	constraintsStr := ""
-	constraints := []string{}
+	conditionsStr := ""
+	conditions := []string{}
 	progName := dep.Name
 	if dep.When != nil {
 		if dep.When.OS != "" {
-			constraints = append(constraints, "OS:"+dep.When.OS)
+			conditions = append(conditions, "OS:"+dep.When.OS)
 		}
-		if dep.When.Version != "" {
-			constraints = append(constraints, "VERSION:"+dep.When.Version)
-		}
-		constraintsStr = fmt.Sprintf(" (%s)", strings.Join(constraints, ","))
 	}
-	return fmt.Errorf("%w: %s%s", ErrDependencyNotSatisfied, progName, constraintsStr)
+	conditionsStr = fmt.Sprintf(" (%s)", strings.Join(conditions, ","))
+	return fmt.Errorf("%w: %s%s", ErrDependencyNotSatisfied, progName, conditionsStr)
+}
+
+// DependencyNotSatifiedVersionConstraint returns an ErrDependencyNotSatisfied with the supplied
+// dependency name and version constraint failure.
+func DependencyNotSatisfiedVersionConstraint(
+	dep *Dependency,
+	constraintStr string,
+) error {
+	progName := dep.Name
+	return fmt.Errorf(
+		"%w: %q failed version constraint %q",
+		ErrDependencyNotSatisfied, progName, constraintStr,
+	)
 }
 
 // RequiredFixtureMissing returns an ErrRequiredFixture with the supplied

go.mod

@@ -3,6 +3,7 @@ module github.com/gdt-dev/core
 go 1.24.3
 
 require (
+	github.com/Masterminds/semver/v3 v3.4.0
 	github.com/cenkalti/backoff v2.2.1+incompatible
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510
 	github.com/google/uuid v1.6.0

go.sum

@@ -1,3 +1,5 @@
+github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
+github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
 github.com/cenkalti/backoff v2.2.1+incompatible h1:tNowT99t7UNflLxfYYSlKYsBpXdEet03Pg2g16Swow4=
 github.com/cenkalti/backoff v2.2.1+incompatible/go.mod h1:90ReRw6GdpyfrHakVjL/QHaoyV4aDUVVkXQJJJ3NXXM=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=