Extendable Param Files feature

docs/experimental-features.md

@@ -15,6 +15,9 @@ Should be enabled in tandem with `testFramework` experimental feature flag for e
 Requires `extensibility` to be enabled. If enabled, users are able to fetch the azure resource type definitions from an OCI Registry as a runtime dependency. To fetch the type definitions the following syntax can be used. For example `provider 'br:mcr.microsoft.com/bicep/providers/az@1.0.0' as az`.
 The provider definitions also support aliasing via `bicepconfig.json` similar to [`moduleAliases`](https://learn.microsoft.com/azure/azure-resource-manager/bicep/bicep-config-modules#aliases-for-modules). For example `provider 'br/public:az@1.0.0' as az`.
 
+### `extendableParamFiles`
+Enables the ability to extend bicepparam files from other bicepparam files.
+
 ### `extensibility`
 Allows Bicep to use a provider model to deploy non-ARM resources. Currently, we support Kubernetes provider ([Bicep extensibility Kubernetes provider](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-extensibility-kubernetes-provider)) and Microsoft Graph provider ([Bicep templates for Microsoft Graph](https://aka.ms/graphbicep)).
 

src/Bicep.Cli.IntegrationTests/BuildParamsCommandTests.cs

@@ -351,27 +351,6 @@ public async Task Build_Invalid_Single_Params_File_ShouldFail_WithExpectedErrorM
             }
         }
 
-        [TestMethod]
-        [EmbeddedFilesTestData(@"Files/BuildParamsCommandTests/.*/main\.bicepparam")]
-        [TestCategory(BaselineHelper.BaselineTestCategory)]
-        public async Task Build_params_to_stdout_with_non_bicep_references_should_succeed(EmbeddedFile paramFile)
-        {
-            var baselineFolder = BaselineFolder.BuildOutputFolder(TestContext, paramFile);
-            var outputFile = baselineFolder.GetFileOrEnsureCheckedIn("output.json");
-
-            var clients = await MockRegistry.Build();
-            var settings = new InvocationSettings(new(TestContext, RegistryEnabled: true), clients.ContainerRegistry, clients.TemplateSpec);
-
-            var result = await Bicep(settings, "build-params", baselineFolder.EntryFile.OutputFilePath, "--stdout");
-            result.Should().Succeed().And.NotHaveStderr();
-
-            var parametersStdout = result.Stdout.FromJson<BuildParamsStdout>();
-            // Force consistency for escaped newlines.
-            parametersStdout = parametersStdout with { templateJson = parametersStdout?.templateJson?.ReplaceLineEndings("\n") };
-            outputFile.WriteJsonToOutputFolder(parametersStdout);
-            outputFile.ShouldHaveExpectedJsonValue();
-        }
-
         [TestMethod]
         [EmbeddedFilesTestData(@"Files/BuildParamsCommandTests/.*/main\.bicepparam")]
         [TestCategory(BaselineHelper.BaselineTestCategory)]

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/Extends/bicepconfig.json

@@ -0,0 +1,5 @@
+{
+  "experimentalFeaturesEnabled": {
+    "extendableParamFiles": true
+  }
+}

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/Extends/main.bicepparam

@@ -0,0 +1,11 @@
+using 'br:mockregistry.io/parameters/basic:v1'
+
+extends 'shared.bicepparam'
+
+param intParam = 123
+
+param boolParam = false
+
+param arrayParam = []
+
+param objectParam = {}

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/Extends/main.json

@@ -0,0 +1,5 @@
+{
+  "parametersJson": "{\n  \"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\",\n  \"contentVersion\": \"1.0.0.0\",\n  \"parameters\": {\n    \"intParam\": {\n      \"value\": 123\n    },\n    \"boolParam\": {\n      \"value\": false\n    },\n    \"arrayParam\": {\n      \"value\": []\n    },\n    \"objectParam\": {\n      \"value\": {}\n    },\n    \"stringParam\": {\n      \"value\": \"foo\"\n    }\n  }\n}",
+  "templateJson": "{\n  \"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#\",\n  \"contentVersion\": \"1.0.0.0\",\n  \"metadata\": {\n    \"_generator\": {\n      \"name\": \"bicep\",\n      \"version\": \"dev\",\n      \"templateHash\": \"185348812090145868\"\n    }\n  },\n  \"parameters\": {\n    \"stringParam\": {\n      \"type\": \"string\"\n    },\n    \"intParam\": {\n      \"type\": \"int\"\n    },\n    \"boolParam\": {\n      \"type\": \"bool\"\n    },\n    \"objectParam\": {\n      \"type\": \"object\"\n    },\n    \"arrayParam\": {\n      \"type\": \"array\"\n    }\n  },\n  \"resources\": []\n}",
+  "templateSpecId": null
+}

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/Extends/shared.bicepparam

@@ -0,0 +1,3 @@
+using none
+
+param stringParam = 'foo'

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/Extends/shared.json

@@ -0,0 +1,5 @@
+{
+  "parametersJson": "{\n  \"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\",\n  \"contentVersion\": \"1.0.0.0\",\n  \"parameters\": {\n    \"stringParam\": {\n      \"value\": \"foo\"\n    }\n  }\n}",
+  "templateJson": null,
+  "templateSpecId": null
+}

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/UsingNone/bicepconfig.json

@@ -0,0 +1,5 @@
+{
+  "experimentalFeaturesEnabled": {
+    "extendableParamFiles": true
+  }
+}

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/UsingNone/shared.bicepparam

@@ -0,0 +1,3 @@
+using none
+
+param stringParam = 'foo'

src/Bicep.Cli.IntegrationTests/Files/BuildParamsCommandTests/UsingNone/shared.json

@@ -0,0 +1,5 @@
+{
+  "parametersJson": "{\n  \"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\",\n  \"contentVersion\": \"1.0.0.0\",\n  \"parameters\": {\n    \"stringParam\": {\n      \"value\": \"foo\"\n    }\n  }\n}",
+  "templateJson": null,
+  "templateSpecId": null
+}

src/Bicep.Core.Samples/BaselineData_Bicepparam.cs

@@ -99,6 +99,7 @@ private static IEnumerable<BaselineData_Bicepparam> GetAllExampleData()
             embeddedFiles.Select(x => x.StreamPath).Should().BeEquivalentTo(
                 "Files/baselines_bicepparam/Expressions/parameters.bicepparam",
                 "Files/baselines_bicepparam/Imports/parameters.bicepparam",
+                "Files/baselines_bicepparam/Extends/parameters.bicepparam",
                 "Files/baselines_bicepparam/Invalid_Expressions/parameters.bicepparam",
                 "Files/baselines_bicepparam/Invalid_Imports/parameters.bicepparam",
                 "Files/baselines_bicepparam/Invalid_Parameters/parameters.bicepparam",

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/bicepconfig.bicep

@@ -0,0 +1,6 @@
+var json = loadJsonContent('foo.json')
+func testFunction(b bool) bool => b
+@export()
+var directExport = json.bar.baz
+@export()
+var functionExport = testFunction(json.bar.baz)

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/bicepconfig.json

@@ -0,0 +1,5 @@
+{
+  "experimentalFeaturesEnabled": {
+    "extendableParamFiles": true
+  }
+}

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/foo.json

@@ -0,0 +1,5 @@
+{
+  "bar": {
+    "baz": true
+  }
+}

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/main.bicep

@@ -0,0 +1,3 @@
+param one string = ''
+param two string = ''
+param three string = ''

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.bicepparam

@@ -0,0 +1,6 @@
+using 'main.bicep'
+
+extends 'shared.bicepparam'
+
+param one = 'param one'
+param two = 'param two'

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.diagnostics.bicepparam

@@ -0,0 +1,7 @@
+using 'main.bicep'
+
+extends 'shared.bicepparam'
+
+param one = 'param one'
+param two = 'param two'
+

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.formatted.bicepparam

@@ -0,0 +1,6 @@
+using 'main.bicep'
+
+extends 'shared.bicepparam'
+
+param one = 'param one'
+param two = 'param two'

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "one": {
+      "value": "param one"
+    },
+    "two": {
+      "value": "param two"
+    },
+    "three": {
+      "value": "param three"
+    }
+  }
+}

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.symbols.bicepparam

@@ -0,0 +1,10 @@
+using 'main.bicep'
+//@[18:23) ParameterAssignment three. Type: 'param three'. Declaration start char: 12, length: 27
+
+extends 'shared.bicepparam'
+
+param one = 'param one'
+//@[06:09) ParameterAssignment one. Type: 'param one'. Declaration start char: 0, length: 23
+param two = 'param two'
+//@[06:09) ParameterAssignment two. Type: 'param two'. Declaration start char: 0, length: 23
+

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.syntax.bicepparam

@@ -0,0 +1,35 @@
+using 'main.bicep'
+//@[00:97) ProgramSyntax
+//@[00:18) ├─UsingDeclarationSyntax
+//@[00:05) | ├─Token(Identifier) |using|
+//@[06:18) | └─StringSyntax
+//@[06:18) |   └─Token(StringComplete) |'main.bicep'|
+//@[18:20) ├─Token(NewLine) |\n\n|
+
+extends 'shared.bicepparam'
+//@[00:27) ├─ExtendsDeclarationSyntax
+//@[00:07) | ├─Token(Identifier) |extends|
+//@[08:27) | └─StringSyntax
+//@[08:27) |   └─Token(StringComplete) |'shared.bicepparam'|
+//@[27:29) ├─Token(NewLine) |\n\n|
+
+param one = 'param one'
+//@[00:23) ├─ParameterAssignmentSyntax
+//@[00:05) | ├─Token(Identifier) |param|
+//@[06:09) | ├─IdentifierSyntax
+//@[06:09) | | └─Token(Identifier) |one|
+//@[10:11) | ├─Token(Assignment) |=|
+//@[12:23) | └─StringSyntax
+//@[12:23) |   └─Token(StringComplete) |'param one'|
+//@[23:24) ├─Token(NewLine) |\n|
+param two = 'param two'
+//@[00:23) ├─ParameterAssignmentSyntax
+//@[00:05) | ├─Token(Identifier) |param|
+//@[06:09) | ├─IdentifierSyntax
+//@[06:09) | | └─Token(Identifier) |two|
+//@[10:11) | ├─Token(Assignment) |=|
+//@[12:23) | └─StringSyntax
+//@[12:23) |   └─Token(StringComplete) |'param two'|
+//@[23:24) ├─Token(NewLine) |\n|
+
+//@[00:00) └─Token(EndOfFile) ||

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/parameters.tokens.bicepparam

@@ -0,0 +1,24 @@
+using 'main.bicep'
+//@[00:05) Identifier |using|
+//@[06:18) StringComplete |'main.bicep'|
+//@[18:20) NewLine |\n\n|
+
+extends 'shared.bicepparam'
+//@[00:07) Identifier |extends|
+//@[08:27) StringComplete |'shared.bicepparam'|
+//@[27:29) NewLine |\n\n|
+
+param one = 'param one'
+//@[00:05) Identifier |param|
+//@[06:09) Identifier |one|
+//@[10:11) Assignment |=|
+//@[12:23) StringComplete |'param one'|
+//@[23:24) NewLine |\n|
+param two = 'param two'
+//@[00:05) Identifier |param|
+//@[06:09) Identifier |two|
+//@[10:11) Assignment |=|
+//@[12:23) StringComplete |'param two'|
+//@[23:24) NewLine |\n|
+
+//@[00:00) EndOfFile ||

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/shared.bicepparam

@@ -0,0 +1,3 @@
+using none
+
+param three = 'param three'

src/Bicep.Core.Samples/Files/baselines_bicepparam/Extends/shared.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "three": {
+      "value": "three"
+    }
+  }
+}

src/Bicep.Core.Samples/Files/baselines_bicepparam/Invalid_Parameters/parameters.diagnostics.bicepparam

@@ -6,10 +6,10 @@ param para1 = 'value
 //@[14:20) [BCP004 (Error)] The string at this location is not terminated due to an unexpected new line character. (CodeDescription: none) |'value|
 
 para
-//@[00:04) [BCP337 (Error)] This declaration type is not valid for a Bicep Parameters file. Specify a "using", "param" or "var" declaration. (CodeDescription: none) |para|
+//@[00:04) [BCP337 (Error)] This declaration type is not valid for a Bicep Parameters file. Specify a "using", "extends", "param" or "var" declaration. (CodeDescription: none) |para|
 
 para2
-//@[00:05) [BCP337 (Error)] This declaration type is not valid for a Bicep Parameters file. Specify a "using", "param" or "var" declaration. (CodeDescription: none) |para2|
+//@[00:05) [BCP337 (Error)] This declaration type is not valid for a Bicep Parameters file. Specify a "using", "extends", "param" or "var" declaration. (CodeDescription: none) |para2|
 
 param expr = 1 + 2
 //@[00:18) [BCP259 (Error)] The parameter "expr" is assigned in the params file without being declared in the Bicep file. (CodeDescription: none) |param expr = 1 + 2|

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

@@ -106,6 +106,7 @@ public void GetBuiltInConfiguration_NoParameter_ReturnsBuiltInConfigurationWithA
           }
         },
         "experimentalFeaturesEnabled": {
+          "extendableParamFiles": false,
           "symbolicNameCodegen": false,
           "extensibility": false,
           "resourceTypedParamsAndOutputs": false,
@@ -195,6 +196,7 @@ public void GetBuiltInConfiguration_DisableAllAnalyzers_ReturnsBuiltInConfigurat
         ],
         "analyzers": {},
         "experimentalFeaturesEnabled": {
+          "extendableParamFiles": false,
           "symbolicNameCodegen": false,
           "extensibility": false,
           "resourceTypedParamsAndOutputs": false,
@@ -309,6 +311,7 @@ public void GetBuiltInConfiguration_DisableAnalyzers_ReturnsBuiltInConfiguration
           }
         },
         "experimentalFeaturesEnabled": {
+          "extendableParamFiles": false,
           "symbolicNameCodegen": false,
           "extensibility": false,
           "resourceTypedParamsAndOutputs": false,
@@ -751,6 +754,7 @@ public void GetConfiguration_ValidCustomConfiguration_OverridesBuiltInConfigurat
         },
         "cacheRootDirectory": "/home/username/.bicep/cache",
         "experimentalFeaturesEnabled": {
+          "extendableParamFiles": false,
           "symbolicNameCodegen": false,
           "extensibility": true,
           "resourceTypedParamsAndOutputs": false,

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

@@ -22,6 +22,7 @@ public record FeatureProviderOverrides(
     bool? OptionalModuleNamesEnabled = default,
     bool? LocalDeployEnabled = default,
     bool? ResourceDerivedTypesEnabled = default,
+    bool? ExtendableParamFilesEnabled = default,
     string? AssemblyVersion = BicepTestConstants.DevAssemblyFileVersion)
 {
     public FeatureProviderOverrides(
@@ -40,6 +41,7 @@ public FeatureProviderOverrides(
         bool? OptionalModuleNamesEnabled = default,
         bool? LocalDeployEnabled = default,
         bool? ResourceDerivedTypesEnabled = default,
+        bool? ExtendableParamFilesEnabled = default,
         string? AssemblyVersion = BicepTestConstants.DevAssemblyFileVersion
     ) : this(
         FileHelper.GetCacheRootPath(testContext),
@@ -57,6 +59,7 @@ public FeatureProviderOverrides(
         OptionalModuleNamesEnabled,
         LocalDeployEnabled,
         ResourceDerivedTypesEnabled,
+        ExtendableParamFilesEnabled,
         AssemblyVersion)
     { }
 }

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

@@ -43,4 +43,6 @@ public OverriddenFeatureProvider(IFeatureProvider features, FeatureProviderOverr
     public bool LocalDeployEnabled => overrides.LocalDeployEnabled ?? features.LocalDeployEnabled;
 
     public bool ResourceDerivedTypesEnabled => overrides.ResourceDerivedTypesEnabled ?? features.ResourceDerivedTypesEnabled;
+
+    public bool ExtendableParamFilesEnabled => overrides.ExtendableParamFilesEnabled ?? features.ExtendableParamFilesEnabled;
 }

src/Bicep.Core/Configuration/ExperimentalFeaturesEnabled.cs

@@ -10,6 +10,7 @@ namespace Bicep.Core.Configuration;
 public record ExperimentalFeaturesEnabled(
     bool SymbolicNameCodegen,
     bool Extensibility,
+    bool ExtendableParamFiles,
     bool ResourceTypedParamsAndOutputs,
     bool SourceMapping,
     bool LegacyFormatter,

src/Bicep.Core/Diagnostics/DiagnosticBuilder.cs

@@ -1878,7 +1878,7 @@ public ErrorDiagnostic IndexOutOfBounds(string typeName, long tupleLength, long
             public ErrorDiagnostic UnrecognizedParamsFileDeclaration() => new(
                 TextSpan,
                 "BCP337",
-                $@"This declaration type is not valid for a Bicep Parameters file. Specify a ""{LanguageConstants.UsingKeyword}"", ""{LanguageConstants.ParameterKeyword}"" or ""{LanguageConstants.VariableKeyword}"" declaration.");
+                $@"This declaration type is not valid for a Bicep Parameters file. Specify a ""{LanguageConstants.UsingKeyword}"", ""{LanguageConstants.ExtendsKeyword}"", ""{LanguageConstants.ParameterKeyword}"" or ""{LanguageConstants.VariableKeyword}"" declaration.");
 
             public ErrorDiagnostic FailedToEvaluateParameter(string parameterName, string message) => new(
                 TextSpan,
@@ -2196,6 +2196,21 @@ public FixableDiagnostic ProviderDeclarationViaImportKeywordIsDeprecated(Provide
                 warnInsteadOfError ? DiagnosticLevel.Warning : DiagnosticLevel.Error,
                 "BCP403",
                 $"The enclosing array expects elements of type \"{expectedType}\", but the array being spread contains elements of incompatible type \"{actualType}\".");
+
+            public ErrorDiagnostic ExtendsPathHasNotBeenSpecified() => new(
+                TextSpan,
+                "BCP404",
+                $"The \"{LanguageConstants.ExtendsKeyword}\" declaration is missing a bicepparam file path reference.");
+
+            public ErrorDiagnostic MoreThanOneExtendsDeclarationSpecified() => new(
+                TextSpan,
+                "BCP405",
+                $"More than one \"{LanguageConstants.ExtendsKeyword}\" declaration are present");
+
+            public ErrorDiagnostic ExtendsNotSupported() => new(
+                TextSpan,
+                "BCP406",
+                $"The \"{LanguageConstants.ExtendsKeyword}\" keyword is not supported");
         }
 
         public static DiagnosticBuilderInternal ForPosition(TextSpan span)

src/Bicep.Core/Emit/CompilationEmitter.cs

@@ -40,7 +40,7 @@ public CompilationEmitter(Compilation compilation)
     public ParametersResult Parameters()
     {
         var model = compilation.GetEntrypointSemanticModel();
-        if (model.SourceFileKind != Workspaces.BicepSourceFileKind.ParamsFile)
+        if (model.SourceFileKind != BicepSourceFileKind.ParamsFile)
         {
             throw new InvalidOperationException($"Entry-point {model.Root.FileUri} is not a parameters file");
         }
@@ -78,6 +78,10 @@ public ParametersResult Parameters()
                 {
                     return new ParametersResult(true, diagnostics, parametersData, templateSpecModel.SourceFile.TemplateSpecId, null);
                 }
+            case EmptySemanticModel _:
+                {
+                    return new ParametersResult(true, diagnostics, parametersData, null, null);
+                }
         }
 
         throw new InvalidOperationException($"Invalid semantic model of type {usingModel.GetType()}");