(GH-538) Define TypeVersion as newtype

Prior to this change, the version fields for DSC used an arbitrary
`String` for both resources and extensions. The generated schema for
those types then reports that any string is valid and DSC must check
every time it needs to process the version for whether the version is
semantic or an arbitrary string.

This change follows the Rust "parse, don't validate pattern" by defining
a `TypeVersion` enum with the `Semantic` and `String` variants. If the
version can be parsed as a semantic version, the type creates it as
an instance of `TypeVersion::Semantic` and otherwise creates it as
`TypeVersion::String`.

The `TypeVersion` enum implements several conversion and comparison
traits to make using the newtype more ergonomic. It also defines helper
methods `is_semver()` and `matches_semver_req()` for easier usage.

When comparing an instance of `TypeVersion`:

- A semantic version is always greater than an arbitrary string version.
  This applies both when comparing `TypeVersion::String` instances to
  `TypeVersion::Semantic` and to `semver::Version`.
- Arbitrary string version comparisons are case-insensitive. `Foo` and
  `foo` are equal but `Foo` is greater than `Bar`.
- You can directly compare instances of `TypeVersion` to string slices,
  `String` instances, and `semver::Version` instances in addition to
  other instances of `TypeVersion`.
- The trait implementations support using `==`, `>`, and `<` operators
  for easier reading.

The newtype overhauls the JSON Schema for versions to help users get
better validation and IntelliSense when authoring manifests.

Finally, this change adds comprehensive integration tests for the
newtype and its implementations as well as documentation for the type
and its public methods.

Author: michaeltlombardi

Cargo.lock

@@ -225,8 +225,10 @@ ipnetwork = { version = "0.21" }
 cc = { version = "1.2" }
 
 # test-only dependencies
-# dsc-lib-jsonschema
+# dsc-lib-jsonschema, dsc-lib
 pretty_assertions = { version = "1.4.1" }
+# dsc-lib
+test-case = { version = "3.3" }
 
 # Workspace crates as dependencies
 dsc-lib = { path = "lib/dsc-lib" }

Cargo.toml

@@ -28,7 +28,7 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 serde_yaml = { workspace = true }
 thiserror = { workspace = true }
-semver = { workspace = true }
+semver = { workspace = true, features = ["serde"] }
 tokio = { workspace = true, features = [
     "io-util",
     "macros",
@@ -38,7 +38,7 @@ tokio = { workspace = true, features = [
 tracing = { workspace = true }
 tracing-indicatif = { workspace = true }
 tree-sitter = { workspace = true }
-tree-sitter-rust = { workspace = true}
+tree-sitter-rust = { workspace = true }
 uuid = { workspace = true }
 url = { workspace = true }
 urlencoding = { workspace = true }
@@ -52,6 +52,10 @@ tree-sitter-dscexpression = { workspace = true }
 
 [dev-dependencies]
 serde_yaml = { workspace = true }
+# Helps review complex comparisons, like schemas
+pretty_assertions = { workspace = true }
+# Enables parameterized test cases
+test-case = { workspace = true }
 
 [build-dependencies]
 cc = { workspace = true }

lib/dsc-lib/Cargo.toml

@@ -733,6 +733,7 @@ resourceManifestNotFound = "Resource manifest not found"
 schema = "Schema"
 schemaNotAvailable = "No Schema found and `validate` is not supported"
 securityContext = "Security context"
+typeVersionToSemverConversion = "Can't convert arbitrary string `Version` to `semver::Version`"
 utf8Conversion = "UTF-8 conversion"
 unknown = "Unknown"
 validation = "Validation"

lib/dsc-lib/locales/en-us.toml

@@ -2,34 +2,106 @@ _version: 2
 schemas:
   definitions:
     resourceType:
-      title: Fully qualified type name
-      description: >-
-        Uniquely identifies a DSC resource or extension.
-      markdownDescription: |-
-        The fully qualified type name of a DSC resource or extension uniquely identifies a resource
-        or extension.
-
-        Fully qualified type names use the following syntax:
-
-        ```yaml
-        <owner>[.<namespace>...]/<name>
-        ```
-
-        Where the type may have zero or more namespace segments for organizing the type. The
-        `owner`, `namespace`, and `name` segments must consist only of alphanumeric characters and
-        underscores.
-
-        Conventionally, the first character of each segment is capitalized. When a segment
-        contains a brand or proper name, use the correct casing for that word, like
-        `TailspinToys/Settings`, not `Tailspintoys/Settings`.
-
-        Example fully qualified type names include:
-
-        - `Microsoft/OSInfo`
-        - `Microsoft.SqlServer/Database`
-        - `Microsoft.Windows.IIS/WebApp`
-      patternErrorMessage: >-
-        Invalid type name. Valid resource type names always define an owner and a name separated by
-        a slash, like `Microsoft/OSInfo`. Type names may optionally include the group, area, and
-        subarea segments to namespace the resource under the owner, like
-        `Microsoft.Windows/Registry`.
+      title:
+        en-us: Fully qualified type name
+      description:
+        en-us: >-
+          Uniquely identifies a DSC resource or extension.
+      markdownDescription:
+        en-us: |-
+          The fully qualified type name of a DSC resource or extension uniquely identifies a resource
+          or extension.
+
+          Fully qualified type names use the following syntax:
+
+          ```yaml
+          <owner>[.<namespace>...]/<name>
+          ```
+
+          Where the type may have zero or more namespace segments for organizing the type. The
+          `owner`, `namespace`, and `name` segments must consist only of alphanumeric characters and
+          underscores.
+
+          Conventionally, the first character of each segment is capitalized. When a segment
+          contains a brand or proper name, use the correct casing for that word, like
+          `TailspinToys/Settings`, not `Tailspintoys/Settings`.
+
+            Example fully qualified type names include:
+
+            - `Microsoft/OSInfo`
+            - `Microsoft.SqlServer/Database`
+            - `Microsoft.Windows.IIS/WebApp`
+      patternErrorMessage:
+        en-us: >-
+          Invalid type name. Valid resource type names always define an owner and a name separated
+          by a slash, like `Microsoft/OSInfo`. Type names may optionally include the group, area,
+          and subarea segments to namespace the resource under the owner, like
+          `Microsoft.Windows/Registry`.
+
+    semver:
+      title:
+        en-us: Semantic version
+      description:
+        en-us: |-
+          A valid semantic version (semver) string.
+
+          For reference, see https://semver.org/
+      markdownDescription:
+        en-us: |-
+          A valid semantic version ([semver][01]) string.
+
+          This value uses the [suggested regular expression][02] to validate whether the string is
+          valid semver. This is the same pattern, made multi-line for easier readability:
+
+          ```regex
+          ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)
+          (?:-(
+            (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)
+            (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))
+          *))?
+          (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
+          ```
+
+          The first line matches the `major.minor.patch` components of the version. The middle
+          lines match the pre-release components. The last line matches the build metadata
+          component.
+
+          [01]: https://semver.org/
+          [02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+      patternErrorMessage:
+        en-us: |-
+          Invalid value, must be a semantic version like `<major>.<minor>.<patch>`, such as `1.2.3`.
+
+          The value may also include pre-release version information and build metadata.
+
+    version:
+      title:
+        en-us: Version
+      description:
+        en-us: >-
+          Defines the version for the type as either a semantic version (semver) or arbitrary string.
+      markdownDescription:
+        en-us: |-
+          Defines the version for the type as either a semantic version (semver) or arbitrary string.
+
+          If the type adheres to [semantic versioning][01], its manifest should define the version as
+          a valid semantic version like `1.2.3`. When a resource or extension specifies a semantic
+          version, DSC uses the latest available version of that resource or extension by default.
+
+          Instead of specifying a semantic version, the type can specify any arbitrary string. In
+          that case, DSC uses simple string sorting to determine the default version to use.
+
+          Users can override the default behavior and require a specific version of a resource with
+          the `something` field.
+      stringVariant:
+        title:
+          en-us: Arbitrary version string
+        description:
+          en-us: >-
+            Defines the version for the type as an arbitrary string.
+        markdownDescription:
+          en-us: |-
+            Defines the version for the type as an arbitrary string. When the version for the type
+            isn't a valid semantic version, DSC treats the version as a string. This enables
+            DSC to support non-semantically-versioned types, such as using a release date as the
+            version.

lib/dsc-lib/locales/schemas.definitions.yaml

@@ -121,6 +121,9 @@ pub enum DscError {
     #[error("semver: {0}")]
     SemVer(#[from] semver::Error),
 
+    #[error("{t}: '{0}'", t = t!("dscerror.typeVersionToSemverConversion"))]
+    TypeVersionToSemverConversion(String),
+
     #[error("{t}: {0}", t = t!("dscerror.utf8Conversion"))]
     Utf8Conversion(#[from] Utf8Error),
 

lib/dsc-lib/src/dscerror.rs

@@ -3,3 +3,5 @@
 
 mod fully_qualified_type_name;
 pub use fully_qualified_type_name::FullyQualifiedTypeName;
+mod type_version;
+pub use type_version::TypeVersion;