✨ Added modules and helpers for carrying out operations on YAML and JSON (#872)

<!--
Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
### Description
<!--
Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
### Description

- added validation rules for paths
- added standard ways for serialising JSON and YAML content/files
- added a standard way to validate a JSON or YAML file against a JSON
Schema



### Test Coverage

<!--
Please put an `x` in the correct box e.g. `[x]` to indicate the testing
coverage of this change.
-->

- [x]  This change is covered by existing or additional automated tests.
- [ ] Manual testing has been performed (and evidence provided) as
automated testing was not feasible.
- [ ] Additional tests are not required for this change (e.g.
documentation update).

---------

Co-authored-by: Josh <josh.jennings@arm.com>

Author: acabarbaye

changes/20260521144643.feature

@@ -0,0 +1 @@
+:zap: add helpers for supporting `json` marshalling with better performance than `encoding/json`

changes/20260521162032.feature

@@ -0,0 +1 @@
+:sparkles: add helpers for serialising yaml

changes/20260521183044.feature

@@ -0,0 +1 @@
+:sparkles: add helpers to validate files against a JSON schema in `jsonschema`

changes/20260521184825.feature

@@ -0,0 +1 @@
+:sparkles: `[filesystem]` Added validation rules for checking that a file path has the required extension

utils/filesystem/filepath.go

@@ -1,13 +1,9 @@
 package filesystem
 
 import (
-	"io/fs"
 	"path"
 	"path/filepath"
 	"strings"
-	"syscall"
-
-	validation "github.com/go-ozzo/ozzo-validation/v4"
 
 	"github.com/ARM-software/golang-utils/utils/commonerrors"
 	"github.com/ARM-software/golang-utils/utils/platform"
@@ -282,103 +278,3 @@ func EvalSymlinks(fs FS, pathWithSymlinks string) (populatedPath string, err err
 func EndsWithPathSeparator(fs FS, filePath string) bool {
 	return strings.HasSuffix(filePath, "/") || strings.HasSuffix(filePath, string(fs.PathSeparator()))
 }
-
-// NewPathValidationRule returns a validation rule to use in configuration.
-// The rule checks whether a string is a valid not empty path.
-// `when` describes whether the rule is enforced or not
-func NewPathValidationRule(filesystem FS, when bool) validation.Rule {
-	return &pathValidationRule{condition: when, filesystem: filesystem}
-}
-
-// NewOSPathValidationRule returns a validation rule to use in configuration.
-// The rule checks whether a string is a valid path for the Operating System's filesystem.
-// `when` describes whether the rule is enforced or not
-func NewOSPathValidationRule(when bool) validation.Rule {
-	return NewPathValidationRule(GetGlobalFileSystem(), when)
-}
-
-type pathValidationRule struct {
-	condition  bool
-	filesystem FS
-}
-
-func (r *pathValidationRule) Validate(value interface{}) error {
-	err := validation.Required.When(r.condition).Validate(value)
-	if err != nil {
-		return commonerrors.WrapErrorf(commonerrors.ErrUndefined, err, "path [%v] is required", value)
-	}
-	if !r.condition {
-		return nil
-	}
-	pathString, err := validation.EnsureString(value)
-	if err != nil {
-		return commonerrors.WrapErrorf(commonerrors.ErrInvalid, err, "path [%v] must be a string", value)
-	}
-	pathString = strings.TrimSpace(pathString)
-	// This check is here because it validates the path on any platform (it is a cross-platform check)
-	// Indeed if the path exists, then it can only be valid.
-	if r.filesystem.Exists(pathString) {
-		return nil
-	}
-
-	// Inspired from https://github.com/go-playground/validator/blob/84254aeb5a59e615ec0b66ab53b988bc0677f55e/baked_in.go#L1604 and https://stackoverflow.com/questions/35231846/golang-check-if-string-is-valid-path
-	if pathString == "" {
-		return commonerrors.Newf(commonerrors.ErrUndefined, "the path [%v] is empty", value)
-	}
-	// This check is to catch errors on Linux. It does not work as well on Windows.
-	if _, err := r.filesystem.Stat(pathString); err != nil {
-		switch t := err.(type) {
-		case *fs.PathError:
-			if t.Err == syscall.EINVAL {
-				return commonerrors.WrapErrorf(commonerrors.ErrInvalid, err, "the path [%v] has invalid characters", value)
-			}
-		default:
-			// make the linter happy
-		}
-	}
-	// The following case is not caught on Windows by the check above.
-	if strings.Contains(pathString, "\n") {
-		return commonerrors.Newf(commonerrors.ErrInvalid, "the path [%v] has carriage returns characters", value)
-	}
-
-	// TODO add platform validation checks: e.g. https://learn.microsoft.com/en-gb/windows/win32/fileio/naming-a-file?redirectedfrom=MSDN on windows
-
-	return nil
-}
-
-// NewPathExistRule returns a validation rule to use in configuration.
-// The rule checks whether a string is a valid not empty path and actually exists.
-// `when` describes whether the rule is enforced or not.
-func NewPathExistRule(filesystem FS, when bool) validation.Rule {
-	return &pathExistValidationRule{filesystem: filesystem, condition: when}
-}
-
-// NewOSPathExistRule returns a validation rule to use in configuration.
-// The rule checks whether a string is a valid path for the Operating system's filesystem and actually exists.
-// `when` describes whether the rule is enforced or not.
-func NewOSPathExistRule(when bool) validation.Rule {
-	return NewPathExistRule(GetGlobalFileSystem(), when)
-}
-
-type pathExistValidationRule struct {
-	condition  bool
-	filesystem FS
-}
-
-func (r *pathExistValidationRule) Validate(value interface{}) error {
-	err := NewPathValidationRule(r.filesystem, r.condition).Validate(value)
-	if err != nil {
-		return err
-	}
-	if !r.condition {
-		return nil
-	}
-	path, err := validation.EnsureString(value)
-	if err != nil {
-		return commonerrors.WrapErrorf(commonerrors.ErrInvalid, err, "path [%v] must be a string", value)
-	}
-	if !r.filesystem.Exists(path) {
-		err = commonerrors.Newf(commonerrors.ErrNotFound, "path [%v] does not exist", path)
-	}
-	return err
-}

utils/filesystem/filepath_test.go

@@ -11,8 +11,6 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/ARM-software/golang-utils/utils/commonerrors"
-	"github.com/ARM-software/golang-utils/utils/commonerrors/errortest"
 	"github.com/ARM-software/golang-utils/utils/platform"
 )
 
@@ -219,72 +217,6 @@ func TestEndsWithPathSeparator(t *testing.T) {
 	}
 }
 
-func TestNewPathExistRule(t *testing.T) {
-	t.Run("disable", func(t *testing.T) {
-		err := NewOSPathExistRule(false).Validate(faker.URL())
-		require.NoError(t, err)
-	})
-	t.Run("happy existing path", func(t *testing.T) {
-		require.NoError(t, NewOSPathExistRule(true).Validate(TempDirectory()))
-		testDir, err := TempDirInTempDir("test-path-rule-")
-		require.NoError(t, err)
-		defer func() { _ = Rm(testDir) }()
-		require.NoError(t, NewOSPathExistRule(true).Validate(testDir))
-		testFile, err := TouchTempFile(testDir, "test-file*.test")
-		require.NoError(t, err)
-		require.NoError(t, NewOSPathExistRule(true).Validate(testFile))
-	})
-	t.Run("non-existent path but valid", func(t *testing.T) {
-		err := NewOSPathExistRule(true).Validate(strings.ReplaceAll(faker.Sentence(), " ", "/"))
-		require.Error(t, err)
-		errortest.AssertError(t, err, commonerrors.ErrNotFound)
-		err = NewOSPathValidationRule(true).Validate(strings.ReplaceAll(faker.Sentence(), " ", "/"))
-		require.NoError(t, err)
-		err = NewOSPathExistRule(true).Validate(faker.URL())
-		require.Error(t, err)
-		errortest.AssertError(t, err, commonerrors.ErrNotFound)
-		err = NewOSPathValidationRule(true).Validate(faker.URL())
-		require.NoError(t, err)
-	})
-
-	t.Run("invalid paths", func(t *testing.T) {
-		tests := []struct {
-			entry         any
-			expectedError []error
-		}{
-			{
-				entry:         nil,
-				expectedError: []error{commonerrors.ErrUndefined, commonerrors.ErrInvalid},
-			},
-			{
-				entry:         "                  ",
-				expectedError: []error{commonerrors.ErrUndefined, commonerrors.ErrInvalid},
-			},
-			{
-				entry:         123,
-				expectedError: []error{commonerrors.ErrInvalid},
-			},
-			{
-				entry:         fmt.Sprintf("%v\n%v\n%v", faker.Paragraph(), faker.Paragraph(), faker.Sentence()),
-				expectedError: []error{commonerrors.ErrInvalid},
-			},
-		}
-		for i := range tests {
-			test := tests[i]
-			t.Run(fmt.Sprintf("%v", test.entry), func(t *testing.T) {
-				err := NewOSPathValidationRule(true).Validate(test.entry)
-				require.Error(t, err)
-				errortest.AssertError(t, err, test.expectedError...)
-				err = NewOSPathExistRule(true).Validate(test.entry)
-				require.Error(t, err)
-				errortest.AssertError(t, err, test.expectedError...)
-			})
-		}
-
-	})
-
-}
-
 func TestFilePathJoin(t *testing.T) {
 	embedFS, err := NewEmbedFileSystem(&testContent)
 	require.NoError(t, err)