(GH-538) Enhance schema export functionality and add error handling for duplicate paths (#1672)

* (GH-538) Enhance schema export functionality and add error handling for duplicate paths

* (GH-538) Enhance schema export functionality and add error handling for duplicate paths

* Update lib/dsc-lib/src/dscresources/adapted_resource_manifest.rs

Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com>

* Update schema URIs in adapted resource manifests to use the new resource schema

* Remove comment

* Add deprecated endpoint shipped

* (GH-538) Enhance schema export functionality and add error handling for duplicate paths

* Update lib/dsc-lib/src/dscresources/adapted_resource_manifest.rs

Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com>

* Update schema URIs in adapted resource manifests to use the new resource schema

* Remove comment

* Add deprecated endpoint shipped

* Move tests

* Rename error types for consistency

* Fix clippy

* Fix Clippy

* Fix Pester test

---------

Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com>

Author: Gijsreyn

adapters/powershell/Tests/PSAdaptedTestClassResource.dsc.adaptedResource.json

@@ -1,5 +1,5 @@
 {
-    "$schema": "https://aka.ms/dsc/schemas/v3/bundled/adaptedresource/manifest.json",
+    "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/adapted/manifest.json",
     "type": "PSAdaptedTestClassResource/PSAdaptedTestClass",
     "kind": "resource",
     "version": "0.1.0",

dsc/src/util.rs

@@ -41,6 +41,7 @@ use dsc_lib::{
         extension_manifest::ExtensionManifest,
     },
     functions::FunctionDefinition,
+    schemas::dsc_repo::{DscRepoSchema, RecognizedSchemaVersion, SchemaForm, SchemaUriPrefix},
     util::{
         get_setting,
         parse_input_to_json,
@@ -162,37 +163,37 @@ pub fn add_fields_to_json(json: &str, fields_to_add: &HashMap<String, String>) -
 pub fn get_schema(schema: SchemaType) -> Schema {
     match schema {
         SchemaType::AdaptedDscResourceManifest => {
-            schema_for!(AdaptedDscResourceManifest)
+            repo_schema::<AdaptedDscResourceManifest>()
         },
         SchemaType::Configuration => {
-            schema_for!(Configuration)
+            repo_schema::<Configuration>()
         },
         SchemaType::ConfigurationExportResult => {
-            schema_for!(ConfigurationExportResult)
+            repo_schema::<ConfigurationExportResult>()
         },
         SchemaType::ConfigurationGetResult => {
-            schema_for!(ConfigurationGetResult)
+            repo_schema::<ConfigurationGetResult>()
         },
         SchemaType::ConfigurationSetResult => {
-            schema_for!(ConfigurationSetResult)
+            repo_schema::<ConfigurationSetResult>()
         },
         SchemaType::ConfigurationTestResult => {
-            schema_for!(ConfigurationTestResult)
+            repo_schema::<ConfigurationTestResult>()
         },
         SchemaType::DscResource => {
-            schema_for!(DscResource)
+            repo_schema::<DscResource>()
         },
         SchemaType::ExtensionDiscoverResult => {
-            schema_for!(DiscoverResult)
+            repo_schema::<DiscoverResult>()
         },
         SchemaType::ExtensionManifest => {
-            schema_for!(ExtensionManifest)
+            repo_schema::<ExtensionManifest>()
         },
         SchemaType::FunctionDefinition => {
-            schema_for!(FunctionDefinition)
+            repo_schema::<FunctionDefinition>()
         },
         SchemaType::GetResult => {
-            schema_for!(GetResult)
+            repo_schema::<GetResult>()
         },
         SchemaType::Include => {
             schema_for!(Include)
@@ -201,35 +202,48 @@ pub fn get_schema(schema: SchemaType) -> Schema {
             schema_for!(ManifestList)
         },
         SchemaType::ResolveResult => {
-            schema_for!(ResolveResult)
+            repo_schema::<ResolveResult>()
         },
         SchemaType::Resource => {
-            schema_for!(Resource)
+            repo_schema::<Resource>()
         },
         SchemaType::ResourceGetResult => {
-            schema_for!(ResourceGetResult)
+            repo_schema::<ResourceGetResult>()
         },
         SchemaType::ResourceSetResult => {
-            schema_for!(ResourceSetResult)
+            repo_schema::<ResourceSetResult>()
         },
         SchemaType::ResourceTestResult => {
-            schema_for!(ResourceTestResult)
+            repo_schema::<ResourceTestResult>()
         },
         SchemaType::ResourceManifest => {
-            schema_for!(ResourceManifest)
+            repo_schema::<ResourceManifest>()
         },
         SchemaType::RestartRequired => {
-            schema_for!(RestartRequired)
+            repo_schema::<RestartRequired>()
         },
         SchemaType::SetResult => {
-            schema_for!(SetResult)
+            repo_schema::<SetResult>()
         },
         SchemaType::TestResult => {
-            schema_for!(TestResult)
+            repo_schema::<TestResult>()
         },
     }
 }
 
+fn repo_schema<T: DscRepoSchema>() -> Schema {
+    let schema_form = if T::SCHEMA_SHOULD_BUNDLE {
+        SchemaForm::Bundled
+    } else {
+        SchemaForm::Canonical
+    };
+    T::generate_schema(
+        RecognizedSchemaVersion::default(),
+        schema_form,
+        SchemaUriPrefix::AkaDotMs
+    )
+}
+
 /// Write the JSON object to the console
 ///
 /// # Arguments

extensions/powershell/powershell.discover.tests.ps1

@@ -22,7 +22,7 @@ BeforeAll {
     $fakeManifest | ConvertTo-Json -Depth 10 | Set-Content -Path $manifestPath
 
     $fakeAdaptedManifest = @{
-        '$schema'      = "https://aka.ms/dsc/schemas/v3/bundled/adaptedresource/manifest.json"
+        '$schema'      = "https://aka.ms/dsc/schemas/v3/bundled/resource/adapted/manifest.json"
         type           = "Test/FakeAdaptedResource"
         kind           = "resource"
         version        = "0.1.0"

extensions/test/discover/discover.ps1

@@ -14,7 +14,7 @@ if ($Extensions) {
     foreach ($extension in $Extensions.Split(',')) {
         $resource = [pscustomobject]@{
             manifestContent = @{
-                '$schema' = "https://aka.ms/dsc/schemas/v3/bundled/adaptedresource/manifest.json"
+                '$schema' = "https://aka.ms/dsc/schemas/v3/bundled/resource/adapted/manifest.json"
                 type = "TestDiscover/$count"
                 kind = "resource"
                 version = "1.0.0"

lib/dsc-lib-jsonschema-macros/src/derive/dsc_repo_schema.rs

@@ -153,11 +153,11 @@ fn generate_with_schema_field(
 
             #schema_property_metadata
 
-            fn validate_schema_uri(&self) -> Result<(), dsc_lib_jsonschema::dsc_repo::UnrecognizedSchemaUri> {
+            fn validate_schema_uri(&self) -> Result<(), dsc_lib_jsonschema::dsc_repo::UnrecognizedSchemaUriError> {
                 if Self::is_recognized_schema_uri(&self.#field) {
                     Ok(())
                 } else {
-                    Err(dsc_lib_jsonschema::dsc_repo::UnrecognizedSchemaUri(
+                    Err(dsc_lib_jsonschema::dsc_repo::UnrecognizedSchemaUriError(
                         self.#field.clone(),
                         Self::recognized_schema_uris(),
                     ))
@@ -196,12 +196,12 @@ fn generate_schema_property_metadata_fn(schema_field: &DscRepoSchemaField) -> pr
 /// required to ensure that the translations use the correct locale definitions.
 fn generate_schema_i18n_fn() -> proc_macro2::TokenStream {
     quote! {
-        fn schema_i18n(suffix: &str) -> Result<String, dsc_lib_jsonschema::dsc_repo::DscRepoSchemaMissingTranslation> {
+        fn schema_i18n(suffix: &str) -> Result<String, dsc_lib_jsonschema::dsc_repo::DscRepoSchemaMissingTranslationError> {
             let i18n_key = format!("{}.{}", Self::SCHEMA_I18N_ROOT_KEY, suffix);
             if let Some(translated) = crate::_rust_i18n_try_translate(&rust_i18n::locale(), &i18n_key) {
                 Ok(translated.into())
             } else {
-                Err(dsc_lib_jsonschema::dsc_repo::DscRepoSchemaMissingTranslation { i18n_key })
+                Err(dsc_lib_jsonschema::dsc_repo::DscRepoSchemaMissingTranslationError { i18n_key })
             }
         }
     }

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

@@ -5,6 +5,10 @@ unrecognizedSchemaUri = "Unrecognized $schema URI"
 validSchemaUrisAre = "Valid schema URIs are"
 missingTranslation = "unable to retrieve translation for undefined key '#{key}'"
 
+[dsc_repo.recognized_schema_version]
+unrecognizedVersion = "Unrecognized schema version folder"
+validVersionsAre = "Valid schema version folders are"
+
 [transforms.idiomaticize_externally_tagged_enum]
 applies_to = "invalid application of idiomaticize_externally_tagged_enum; missing 'oneOf' keyword in transforming schema: %{transforming_schema}"
 oneOf_array = "invalid application of idiomaticize_externally_tagged_enum; 'oneOf' isn't an array in transforming schema: %{transforming_schema}"

lib/dsc-lib-jsonschema/src/dsc_repo/dsc_repo_schema.rs

@@ -327,8 +327,8 @@ pub trait DscRepoSchema : JsonSchema {
     /// # Errors
     ///
     /// If the value for the schema field isn't a recognized schema, the method should raise the
-    /// [`UnrecognizedSchemaUri`] error.
-    fn validate_schema_uri(&self) -> Result<(), UnrecognizedSchemaUri> {
+    /// [`UnrecognizedSchemaUriError`] error.
+    fn validate_schema_uri(&self) -> Result<(), UnrecognizedSchemaUriError> {
         Ok(())
     }
 
@@ -355,8 +355,8 @@ pub trait DscRepoSchema : JsonSchema {
     /// 
     /// # Errors
     /// 
-    /// Returns a [`DscRepoSchemaMissingTranslation`] error if the translation key doesn't exist.
-    fn schema_i18n(suffix: &str) -> Result<String, DscRepoSchemaMissingTranslation>;
+    /// Returns a [`DscRepoSchemaMissingTranslationError`] error if the translation key doesn't exist.
+    fn schema_i18n(suffix: &str) -> Result<String, DscRepoSchemaMissingTranslationError>;
 }
 
 /// Defines the error when a user-defined JSON Schema references an unrecognized schema URI.
@@ -366,13 +366,13 @@ pub trait DscRepoSchema : JsonSchema {
     t = t!("dsc_repo.dsc_repo_schema.unrecognizedSchemaUri"),
     t2 = t!("dsc_repo.dsc_repo_schema.validSchemaUrisAre")
 )]
-pub struct UnrecognizedSchemaUri(pub String, pub Vec<String>);
+pub struct UnrecognizedSchemaUriError(pub String, pub Vec<String>);
 
 #[derive(Error, Debug, Clone, PartialEq)]
 #[error("{t}", t = t!(
     "dsc_repo.dsc_repo_schema.missingTranslation",
     "key" => i18n_key
 ))]
-pub struct DscRepoSchemaMissingTranslation {
+pub struct DscRepoSchemaMissingTranslationError {
     pub i18n_key: String
 }

lib/dsc-lib-jsonschema/src/dsc_repo/mod.rs

@@ -5,15 +5,16 @@ use schemars::{Schema, json_schema};
 
 mod dsc_repo_schema;
 pub use dsc_repo_schema::DscRepoSchema;
-pub use dsc_repo_schema::UnrecognizedSchemaUri;
-pub use dsc_repo_schema::DscRepoSchemaMissingTranslation;
+pub use dsc_repo_schema::UnrecognizedSchemaUriError;
+pub use dsc_repo_schema::DscRepoSchemaMissingTranslationError;
 
 #[macro_use]
 mod macros;
 pub use crate::schema_i18n;
 
 mod recognized_schema_version;
 pub use recognized_schema_version::RecognizedSchemaVersion;
+pub use recognized_schema_version::UnrecognizedSchemaVersionError;
 
 mod schema_form;
 pub use schema_form::SchemaForm;

lib/dsc-lib-jsonschema/src/dsc_repo/recognized_schema_version.rs

@@ -6,4 +6,31 @@
 //! checks the git tags for non-prerelease versions of DSC to generate the enum type with all of the
 //! correct values. The enum can be used transparently throughout the rest of the libraries.
 
+use rust_i18n::t;
+use thiserror::Error;
+
 include!(concat!(env!("OUT_DIR"), "/recognized_schema_version.rs"));
+
+/// Defines the error when parsing a string that isn't a recognized schema version folder.
+#[derive(Error, Debug, Clone, PartialEq)]
+#[error(
+    "{t}: {0}. {t2}: {1:?}",
+    t = t!("dsc_repo.recognized_schema_version.unrecognizedVersion"),
+    t2 = t!("dsc_repo.recognized_schema_version.validVersionsAre")
+)]
+pub struct UnrecognizedSchemaVersionError(pub String, pub Vec<String>);
+
+impl std::str::FromStr for RecognizedSchemaVersion {
+    type Err = UnrecognizedSchemaVersionError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let candidate = s.trim();
+        Self::all()
+            .into_iter()
+            .find(|version| version.to_string().eq_ignore_ascii_case(candidate))
+            .ok_or_else(|| UnrecognizedSchemaVersionError(
+                candidate.to_string(),
+                Self::all().iter().map(ToString::to_string).collect()
+            ))
+    }
+}

lib/dsc-lib-jsonschema/src/tests/dsc_repo.rs

@@ -5,7 +5,7 @@ use schemars::{JsonSchema, Schema, json_schema};
 use serde::{Deserialize, Serialize};
 
 use crate::dsc_repo::{
-    DscRepoSchema, DscRepoSchemaMissingTranslation, RecognizedSchemaVersion, SchemaForm, SchemaUriPrefix, get_default_schema_uri, get_recognized_schema_uri
+    DscRepoSchema, DscRepoSchemaMissingTranslationError, RecognizedSchemaVersion, SchemaForm, SchemaUriPrefix, get_default_schema_uri, get_recognized_schema_uri
 };
 
 #[test]
@@ -52,12 +52,12 @@ fn test_dsc_repo_schema_bundled() {
         const SCHEMA_SHOULD_BUNDLE: bool = true;
         const SCHEMA_I18N_ROOT_KEY: &'static str = "example.schema";
 
-        fn schema_i18n(suffix: &str) -> Result<String, DscRepoSchemaMissingTranslation> {
+        fn schema_i18n(suffix: &str) -> Result<String, DscRepoSchemaMissingTranslationError> {
             let i18n_key = format!("{}.{}", Self::SCHEMA_I18N_ROOT_KEY, suffix);
             if let Some(translated) = crate::_rust_i18n_try_translate(&rust_i18n::locale(), &i18n_key) {
                 Ok(translated.into())
             } else {
-                Err(DscRepoSchemaMissingTranslation { i18n_key })
+                Err(DscRepoSchemaMissingTranslationError { i18n_key })
             }
         }
 
@@ -107,12 +107,12 @@ fn test_dsc_repo_schema_not_bundled() {
         const SCHEMA_SHOULD_BUNDLE: bool = false;
         const SCHEMA_I18N_ROOT_KEY: &'static str = "example.schema";
 
-        fn schema_i18n(suffix: &str) -> Result<String, DscRepoSchemaMissingTranslation> {
+        fn schema_i18n(suffix: &str) -> Result<String, DscRepoSchemaMissingTranslationError> {
             let i18n_key = format!("{}.{}", Self::SCHEMA_I18N_ROOT_KEY, suffix);
             if let Some(translated) = crate::_rust_i18n_try_translate(&rust_i18n::locale(), &i18n_key) {
                 Ok(translated.into())
             } else {
-                Err(DscRepoSchemaMissingTranslation { i18n_key })
+                Err(DscRepoSchemaMissingTranslationError { i18n_key })
             }
         }