(GH-538) Use DateVersion in ResourceVersion

Prior to this change, `ResourceVersion` defined the `Semantic` and
`Arbitrary` variants, where the arbitrary variant was a fall-through
for any version defined as a non-semantic version.

This change:

- Replaces the `Arbitrary` variant with a `Date` variant that wraps a
  `DateVersion` type. This allows us to maintain the distinction between
  semantic versions and date versions in the type system, which is
  preferable to having a catch-all arbitrary version type.
- Defines the `ResourceVersionError` type with the `Error` and
  `Diagnostic` traits to represent errors that can occur when parsing
  and converting resource versions. This allows us to provide more
  detailed error messages and diagnostics when resource version parsing
  fails.

  To ensure these errors are properly surfaced during deserialization,
  this change also tells serde explicitly to deserialize from and
  serialize into strings, avoiding the untagged enum variant generic
  error message.
- Replaces the `ResourceVersionToSemverConversion` variant for `DscError`
  with the `ResourceVersion` variant that transparently wraps
  `ResourceVersionError`.

Author: michaeltlombardi

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

@@ -792,7 +792,6 @@ parser = "Parser"
 progress = "Progress"
 resourceNotFound = "Resource not found"
 resourceManifestNotFound = "Resource manifest not found"
-resourceVersionToSemverConversion = "Unable to convert arbitrary string resource version to semantic version"
 resourceVersionReqToSemverConversion = "Unable to convert arbitrary string resource version requirement to semantic version requirement"
 schema = "Schema"
 schemaNotAvailable = "No Schema found and `validate` is not supported"
@@ -835,6 +834,13 @@ invalidDate = "unable to parse '%{text}' as a date version - %{errors}"
 successText = "Success"
 failureText = "Error"
 
+[types.resource_version]
+unparseableVersion = "unable to parse '%{text}' as resource version - input doesn't seem to be a semantic or date version"
+invalidDateVersion = "invalid date resource version: %{err}"
+invalidSemanticVersion = "invalid semantic resource version: %{err}"
+invalidConversionToSemanticVersion = "unable to convert date resource version '%{version}' to semantic version"
+invalidConversionToDateVersion = "unable to convert semantic resource version '%{version}' to date version"
+
 [types.semantic_version]
 invalidSemanticVersion = "invalid semantic version '%{text}': %{err}"
 

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

@@ -130,26 +130,24 @@ schemas:
         en-us: |-
           Defines the version of a DSC resource.
 
-          DSC supports both semantic versioning and arbitrary versioning for resources. Semantic
+          DSC supports both semantic versioning and date versioning for resources. Semantic
           versioning is the preferred and recommended versioning strategy. DSC only supports
-          arbitrary versioning for compatibility scenarios.
+          date versioning for compatibility scenarios.
 
           When the version is defined as a valid [semantic version][01], DSC can correctly compare
           versions to determine the latest version or match a [semantic version requirement][02].
           Where possible, resource and extension authors should follow semantic versioning for the
           best user experience.
 
-          When the version is an arbitrary string, DSC compares the strings
-          [lexicographically][03]. Arbitrary string versions are only equivalent when they contain
-          exactly the same characters - the comparison is case-sensitive. If you're defining a
-          resource that doesn't follow semantic versioning, consider defining the version as an
-          [ISO 8601 date][04], like `2026-01-15`. When you do, DSC can correctly determine that a
-          later date should be treated as a newer version.
+          When the version is defined as a valid [date version][03], DSC compares the dates to see
+          which one is newer. Date versions are only equivalent when they define the same date and
+          optional prerelease segment. Both versions must define or omit the prerelease segment. If
+          the prerelease segment is defined, the segments must be identical - the comparison is
+          case sensitive.
 
           [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/semver
-          [02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/semverReq
-          [03]: https://doc.rust-lang.org/std/cmp/trait.Ord.html#lexicographical-comparison
-          [04]: https://www.iso.org/iso-8601-date-and-time-format.html
+          [02]: https://learn.microsoft.com/en-us/powershell/dsc/concepts/defining-semver-reqs.md
+          [03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/dateVersion
       semanticVariant:
         title:
           en-us: Semantic resource version
@@ -167,36 +165,31 @@ schemas:
 
             [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/semver
             [02]: https://semver.org
-      arbitraryVariant:
+      dateVariant:
         title:
-          en-us: Arbitrary string resource version
+          en-us: Date resource version
         description:
           en-us: >-
-            Defines the resource's version as an arbitrary string.
+            Defines the resource's version as a date version.
         deprecationMessage:
           en-us: >-
-            Defining a resource version as an arbitrary string is supported only for compatibility
+            Defining a resource version as a date version is supported only for compatibility
             purposes. If possible, define your resource version as a valid semantic version. For
             more information about defining a semantic version, see [semver.org](https://semver.org).
         markdownDescription:
           en-us: |-
-            Defines the resource's version as an arbitrary string.
+            Defines the resource's version as a date version.
 
-            DSC uses this variant for the version of any DSC resource that defines its version as a
-            string that can't be parsed as a semantic version. This variant remains supported for
-            compatibility purposes but is _not_ recommended for production usage.
+            This variant remains supported for compatibility purposes but is _not_ recommended for
+            production usage.
 
-            When a resource defines the version as an arbitrary string:
+            When a resource defines the version as a date version:
 
-            1. You can only use exact match version requirements for that resource.
-            1. When a resource defines the version as an arbitrary string, DSC uses Rust's
-               [lexicographic comparison][01] logic to determine the "latest" version of the
-               resource to use as the default version when no version requirement is specified.
+            1. The resource only matches a resource version requirement that is defined as a date
+               version when the date and optional prerelease segments are exactly the same. The
+               comparison is case-sensitive for the prerelease segment.
             1. When DSC discovers a multiple manifests for a resource, DSC always treats
-               semantically versioned resources as newer than resources with an arbitrary string
-               version.
-
-            [01]: https://doc.rust-lang.org/std/cmp/trait.Ord.html#lexicographical-comparison
+               semantically versioned resources as newer than resources with a date version.
 
     resourceVersionReq:
       title:

lib/dsc-lib/src/dscerror.rs

@@ -140,8 +140,8 @@ pub enum DscError {
     #[error("{t}: {0}", t = t!("dscerror.resourceManifestNotFound"))]
     ResourceManifestNotFound(String),
 
-    #[error("{t}: '{0}'", t = t!("dscerror.resourceVersionToSemverConversion"))]
-    ResourceVersionToSemverConversion(String),
+    #[error(transparent)]
+    ResourceVersion(#[from] crate::types::ResourceVersionError),
 
     #[error("{t}: '{0}'", t = t!("dscerror.resourceVersionReqToSemverConversion"))]
     ResourceVersionReqToSemverConversion(String),

lib/dsc-lib/src/types/mod.rs

@@ -10,7 +10,7 @@ pub use exit_codes_map::ExitCodesMap;
 mod fully_qualified_type_name;
 pub use fully_qualified_type_name::FullyQualifiedTypeName;
 mod resource_version;
-pub use resource_version::ResourceVersion;
+pub use resource_version::{ResourceVersion, ResourceVersionError};
 mod resource_version_req;
 pub use resource_version_req::ResourceVersionReq;
 mod semantic_version;