Add @validate() decorator for custom validation (#17804)

Resolves #2922 and resolves #16988

###### Microsoft Reviewers: [Open in
CodeFlow](https://microsoft.github.io/open-pr/?codeflow=https://github.com/Azure/bicep/pull/17804)

Author: jeskew

Bicep.sln

@@ -52,6 +52,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "_SolutionItems", "_Solution
 		CONTRIBUTING.md = CONTRIBUTING.md
 		src\Directory.Build.props = src\Directory.Build.props
 		src\Directory.Build.targets = src\Directory.Build.targets
+		src\Directory.Packages.props = src\Directory.Packages.props
 		global.json = global.json
 		LICENSE = LICENSE
 		README.md = README.md

docs/experimental-features.md

@@ -71,6 +71,15 @@ Allows the ARM template layer to use a new schema to represent resources as an o
 
 Should be enabled in tandem with `assertions` experimental feature flag for expected functionality. Allows you to author client-side, offline unit-test test blocks that reference Bicep files and mock deployment parameters in a separate `test.bicep` file using the new `test` keyword. Test blocks can be run with the command *bicep test <filepath_to_file_with_test_blocks>* which runs all `assert` statements in the Bicep files referenced by the test blocks. For more information, see [Bicep Experimental Test Framework](https://github.com/Azure/bicep/issues/11967).
 
+### `userDefinedConstraints`
+
+Enables the `@validate()` decorator on types, type properties, parameters, and outputs. The decorator takes two arguments: 1) a lambda function that accepts the decorator target's value and returns a boolean indicating if the value is valid (`true`) or not (`false`), and 2) an optional error message to use if the lambda returns `false`.
+
+```bicep
+@validate(x => startsWith(x, 'foo')) // <-- Accepts 'food' or 'fool' but causes the deployment to fail if 'booed' was supplied
+param p string
+```
+
 ### `waitAndRetry`
 
 The feature introduces waitUntil and retryOn decorators on resource data type. waitUnitl() decorator waits for the resource until its usable based on the desired property's state. retryOn() will retry the deployment if one if the listed exception codes are encountered.

src/Bicep.Core.IntegrationTests/Decorators/DecoratorTests.cs

@@ -340,5 +340,47 @@ public void UnfinishedDecoratorInResourceBody_ShouldPromptForNamespaceOrDecorato
                 template.Should().BeNull();
             }
         }
+
+        [TestMethod]
+        public void Constant_decorator_arguments_must_be_block_expressions()
+        {
+            var result = CompilationHelper.Compile(
+                new ServiceBuilder().WithFeatureOverrides(new(TestContext, UserDefinedConstraintsEnabled: true)),
+                """
+                param env 'dev'|'prod'
+
+                @allowed([
+                  'f${'o'}o'
+                ])
+                @description(format('Le {0} est sur la {1}', 'singe', 'branche'))
+                @minLength(1 + 2)
+                @maxLength(2 + 1)
+                @validate(x => x == 'foo', 'Must be \'${'foo'}\'.')
+                @metadata({
+                  env: env
+                })
+                param foo string
+
+                @minValue(1 + 1)
+                @maxValue(2 + 2)
+                param bar int
+
+                @discriminator('k${'i'}n${'d'}')
+                param baz {kind: 'a', prop: string} | {kind: 'b', prop: int}
+                """);
+
+            result.ExcludingDiagnostics("no-unused-params").Should().HaveDiagnostics(
+            [
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+                ("BCP032", DiagnosticLevel.Error, "The value must be a compile-time constant."),
+            ]);
+        }
     }
 }

src/Bicep.Core.IntegrationTests/UserDefinedTypeTests.cs

@@ -1889,4 +1889,72 @@ param p recursiveType
 
         result.Should().NotHaveAnyDiagnostics();
     }
+
+    [TestMethod]
+    public void User_defined_validators_are_blocked_if_feature_flag_is_not_enabled()
+    {
+        var result = CompilationHelper.Compile("""
+            @validate(x => startsWith(x, 'foo'))
+            param foo string
+            """);
+
+        result.ExcludingLinterDiagnostics().Should().HaveDiagnostics(
+        [
+            ("BCP057", DiagnosticLevel.Error, "The name \"validate\" does not exist in the current context."),
+        ]);
+    }
+
+    [TestMethod]
+    public void User_defined_validator_can_be_attached_to_a_parameter_statement()
+    {
+        var result = CompilationHelper.Compile(
+            new ServiceBuilder().WithFeatureOverrides(new(TestContext, UserDefinedConstraintsEnabled: true)),
+            """
+            @validate(x => startsWith(x, 'foo'), 'Should have started with \'foo\'')
+            param foo string
+            """);
+
+        result.ExcludingLinterDiagnostics().Should().NotHaveAnyDiagnostics();
+        result.Template.Should().NotBeNull();
+        result.Template.Should().HaveJsonAtPath("$.parameters.foo.validate",
+            """["[lambda('x', startsWith(lambdaVariables('x'), 'foo'))]", "Should have started with 'foo'"]""");
+    }
+
+    [TestMethod]
+    public void User_defined_validator_checks_lambda_type_against_declared_type()
+    {
+        var result = CompilationHelper.Compile(
+            new ServiceBuilder().WithFeatureOverrides(new(TestContext, UserDefinedConstraintsEnabled: true)),
+            """
+            @validate(x => startsWith(x, 'foo'))
+            param foo int
+            """);
+
+        result.ExcludingLinterDiagnostics().Should().HaveDiagnostics(
+        [
+            ("BCP070", DiagnosticLevel.Error, "Argument of type \"int => error\" is not assignable to parameter of type \"any => bool\"."),
+        ]);
+    }
+
+    [TestMethod]
+    public void User_defined_validator_disallows_runtime_expressions()
+    {
+        var result = CompilationHelper.Compile(
+            new ServiceBuilder().WithFeatureOverrides(new(TestContext, UserDefinedConstraintsEnabled: true)),
+            """
+            resource sa 'Microsoft.Storage/storageAccounts@2025-01-01' existing = {
+              name: 'acct'
+            }
+
+            var indirection = sa.properties.allowBlobPublicAccess
+
+            @validate(x => x == !indirection)
+            param foo bool
+            """);
+
+        result.ExcludingLinterDiagnostics().Should().HaveDiagnostics(
+        [
+            ("BCP432", DiagnosticLevel.Error, "This expression is being used in parameter \"predicate\" of the function \"validate\", which requires a value that can be calculated at the start of the deployment. You are referencing a variable which cannot be calculated at the start (\"indirection\" -> \"sa\"). Properties of sa which can be calculated at the start include \"apiVersion\", \"id\", \"name\", \"type\"."),
+        ]);
+    }
 }

src/Bicep.Core.UnitTests/Configuration/ConfigurationManagerTests.cs

@@ -108,7 +108,8 @@ public void GetBuiltInConfiguration_NoParameter_ReturnsBuiltInConfigurationWithA
           "resourceInfoCodegen": false,
           "desiredStateConfiguration": false,
           "onlyIfNotExists": false,
-          "moduleIdentity": false
+          "moduleIdentity": false,
+          "userDefinedConstraints": false
         },
         "formatting": {
           "indentKind": "Space",
@@ -190,7 +191,8 @@ public void GetBuiltInConfiguration_DisableAllAnalyzers_ReturnsBuiltInConfigurat
           "moduleExtensionConfigs": false,
           "desiredStateConfiguration": false,
           "onlyIfNotExists": false,
-          "moduleIdentity": false
+          "moduleIdentity": false,
+          "userDefinedConstraints": false
         },
         "formatting": {
           "indentKind": "Space",
@@ -294,7 +296,8 @@ public void GetBuiltInConfiguration_DisableAnalyzers_ReturnsBuiltInConfiguration
           "moduleExtensionConfigs": false,
           "desiredStateConfiguration": false,
           "onlyIfNotExists": false,
-          "moduleIdentity": false
+          "moduleIdentity": false,
+          "userDefinedConstraints": false
         },
         "formatting": {
           "indentKind": "Space",
@@ -387,7 +390,8 @@ public void GetBuiltInConfiguration_EnableExperimentalFeature_ReturnsBuiltInConf
                 ModuleExtensionConfigs: false,
                 DesiredStateConfiguration: false,
                 OnlyIfNotExists: false,
-                ModuleIdentity: false);
+                ModuleIdentity: false,
+                UserDefinedConstraints: false);
 
             configuration.WithExperimentalFeaturesEnabled(experimentalFeaturesEnabled).Should().HaveContents(/*lang=json,strict*/ """
             {
@@ -470,7 +474,8 @@ public void GetBuiltInConfiguration_EnableExperimentalFeature_ReturnsBuiltInConf
                 "moduleExtensionConfigs": false,
                 "desiredStateConfiguration": false,
                 "onlyIfNotExists": false,
-                "moduleIdentity": false
+                "moduleIdentity": false,
+                "userDefinedConstraints": false
             },
             "formatting": {
                 "indentKind": "Space",
@@ -837,7 +842,8 @@ public void GetConfiguration_ValidCustomConfiguration_OverridesBuiltInConfigurat
           "moduleExtensionConfigs": false,
           "desiredStateConfiguration": false,
           "onlyIfNotExists": false,
-          "moduleIdentity": false
+          "moduleIdentity": false,
+          "userDefinedConstraints": false
         },
         "formatting": {
           "indentKind": "Space",

src/Bicep.Core.UnitTests/Features/FeatureProviderOverrides.cs

@@ -25,7 +25,8 @@ public record FeatureProviderOverrides(
     bool? ModuleExtensionConfigsEnabled = default,
     bool? DesiredStateConfigurationEnabled = default,
     bool? OnlyIfNotExistsEnabled = default,
-    bool? ModuleIdentityEnabled = default)
+    bool? ModuleIdentityEnabled = default,
+    bool? UserDefinedConstraintsEnabled = default)
 {
     public FeatureProviderOverrides(
         TestContext testContext,
@@ -45,25 +46,25 @@ public FeatureProviderOverrides(
         bool? ModuleExtensionConfigsEnabled = default,
         bool? DesiredStateConfigurationEnabled = default,
         bool? OnlyIfNotExistsEnabled = default,
-        bool? ModuleIdentityEnabled = default
-    ) : this(
-        FileHelper.GetCacheRootDirectory(testContext),
-        RegistryEnabled,
-        SymbolicNameCodegenEnabled,
-        AdvancedListComprehensionEnabled,
-        ResourceTypedParamsAndOutputsEnabled,
-        SourceMappingEnabled,
-        LegacyFormatterEnabled,
-        TestFrameworkEnabled,
-        AssertsEnabled,
-        WaitAndRetryEnabled,
-        LocalDeployEnabled,
-        ResourceInfoCodegenEnabled,
-        ExtendableParamFilesEnabled,
-        AssemblyVersion,
-        ModuleExtensionConfigsEnabled,
-        DesiredStateConfigurationEnabled,
-        OnlyIfNotExistsEnabled,
-        ModuleIdentityEnabled)
-    { }
+        bool? ModuleIdentityEnabled = default,
+        bool? UserDefinedConstraintsEnabled = default) : this(
+            FileHelper.GetCacheRootDirectory(testContext),
+            RegistryEnabled,
+            SymbolicNameCodegenEnabled,
+            AdvancedListComprehensionEnabled,
+            ResourceTypedParamsAndOutputsEnabled,
+            SourceMappingEnabled,
+            LegacyFormatterEnabled,
+            TestFrameworkEnabled,
+            AssertsEnabled,
+            WaitAndRetryEnabled,
+            LocalDeployEnabled,
+            ResourceInfoCodegenEnabled,
+            ExtendableParamFilesEnabled,
+            AssemblyVersion,
+            ModuleExtensionConfigsEnabled,
+            DesiredStateConfigurationEnabled,
+            OnlyIfNotExistsEnabled,
+            ModuleIdentityEnabled,
+            UserDefinedConstraintsEnabled) { }
 }

src/Bicep.Core.UnitTests/Features/OverriddenFeatureProvider.cs

@@ -48,4 +48,6 @@ public OverriddenFeatureProvider(IFeatureProvider features, FeatureProviderOverr
     public bool DesiredStateConfigurationEnabled => overrides.DesiredStateConfigurationEnabled ?? features.DesiredStateConfigurationEnabled;
 
     public bool ModuleIdentityEnabled => overrides.ModuleIdentityEnabled ?? features.ModuleIdentityEnabled;
+
+    public bool UserDefinedConstraintsEnabled => overrides.UserDefinedConstraintsEnabled ?? features.UserDefinedConstraintsEnabled;
 }

src/Bicep.Core/Configuration/ExperimentalFeaturesEnabled.cs

@@ -23,7 +23,8 @@ public record ExperimentalFeaturesEnabled(
     bool ModuleExtensionConfigs,
     bool DesiredStateConfiguration,
     bool OnlyIfNotExists,
-    bool ModuleIdentity)
+    bool ModuleIdentity,
+    bool UserDefinedConstraints)
 {
     public static ExperimentalFeaturesEnabled Bind(JsonElement element)
         => element.ToNonNullObject<ExperimentalFeaturesEnabled>();
@@ -44,5 +45,6 @@ public static ExperimentalFeaturesEnabled Bind(JsonElement element)
         ModuleExtensionConfigs: false,
         DesiredStateConfiguration: false,
         OnlyIfNotExists: false,
-        ModuleIdentity: false);
+        ModuleIdentity: false,
+        UserDefinedConstraints: false);
 }

src/Bicep.Core/Diagnostics/DiagnosticBuilder.cs

@@ -1962,6 +1962,16 @@ public Diagnostic FoundFileInsteadOfDirectory(string filePath) => CoreError(
             public Diagnostic InvalidModuleExtensionConfigAssignmentExpression(string propertyName) => CoreError(
                 "BCP431",
                 $"The value of the \"{propertyName}\" property must be an object literal or a valid extension config inheritance expression.");
+
+            public Diagnostic RuntimeValueNotAllowedInFunctionArgument(string? functionName, string? parameterName, string? accessedSymbolName, IEnumerable<string>? accessiblePropertyNames, IEnumerable<string>? variableDependencyChain)
+            {
+                var variableDependencyChainClause = BuildVariableDependencyChainClause(variableDependencyChain);
+                var accessiblePropertiesClause = BuildAccessiblePropertiesClause(accessedSymbolName, accessiblePropertyNames);
+
+                return CoreError(
+                    "BCP432",
+                    $"This expression is being used in parameter \"{parameterName ?? "unknown"}\" of the function \"{functionName ?? "unknown"}\", which requires a value that can be calculated at the start of the deployment.{variableDependencyChainClause}{accessiblePropertiesClause}");
+            }
         }
 
         public static DiagnosticBuilderInternal ForPosition(TextSpan span)

src/Bicep.Core/Emit/TemplateWriter.cs

@@ -246,6 +246,7 @@ private static ObjectExpression ApplyTypeModifiers(TypeDeclaringExpression expre
                 (expression.MaxLength, LanguageConstants.ParameterMaxLengthPropertyName),
                 (expression.MinValue, LanguageConstants.ParameterMinValuePropertyName),
                 (expression.MaxValue, LanguageConstants.ParameterMaxValuePropertyName),
+                (expression.UserDefinedConstraint, LanguageConstants.ParameterUserDefinedConstraintPropertyName),
             })
             {
                 if (modifier is not null)