Added support for Bicep imports Azure#2537 (Azure#2714)

Author: BernieWhite

bicepconfig.json

@@ -1,6 +1,6 @@
 {
   "experimentalFeaturesEnabled": {
-    "userDefinedTypes": true,
-    "optionalModuleNames": true
+    "optionalModuleNames": true,
+    "userDefinedFunctions": true
   }
 }

docs/CHANGELOG-v1.md

@@ -34,6 +34,9 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 What's changed since pre-release v1.34.0-B0022:
 
+- General improvements:
+  - Added support for type/ variable/ and function imports from Bicep files by @BernieWhite.
+    [#2537](https://github.com/Azure/PSRule.Rules.Azure/issues/2537)
 - Engineering:
   - Improved debugging experience by providing symbols for .NET code by @BernieWhite.
     [#2712](https://github.com/Azure/PSRule.Rules.Azure/issues/2712)

docs/troubleshooting.md

@@ -37,6 +37,8 @@ To resolve this issue:
 When expanding Bicep source files you may get an error relating to the Bicep version you have installed.
 For example if you attempt to use a Bicep feature that is not supported by the version used by PSRule for Azure.
 
+Check the Bicep version reported by PSRule supports the Bicep features you are using.
+
 PSRule for Azure uses the Bicep CLI installed on your machine or CI worker.
 By default, the Bicep CLI binary will be selected by your `PATH` environment variable.
 
@@ -51,6 +53,17 @@ For more details on installing and configuring the Bicep CLI, see [Setup Bicep][
   [10]: setup/setup-bicep.md#using-azure-cli
   [11]: setup/setup-bicep.md
 
+## Bicep features
+
+Generally PSRule for Azure plans to support any language features that are supported by the latest version of Bicep.
+New language features are often added behind an experimental feature flag for community feedback.
+Features flagged by Bicep as experimental may not be supported by PSRule for Azure immediately.
+PSRule for Azure will plan to add support as soon as possible after the feature flag is removed.
+
+If you are using a Bicep feature that is not supported by PSRule for Azure, please [join or start a discussion][4].
+
+  [4]: https://github.com/Azure/PSRule.Rules.Azure/discussions
+
 ## Bicep compilation timeout
 
 When expanding Bicep source files you may get an error similar to the following:
@@ -97,7 +110,6 @@ There is a few common causes of this issue including:
 
   [2]: using-templates.md
   [3]: using-bicep.md
-  [4]: https://github.com/Azure/PSRule.Rules.Azure/discussions
 
 ## Custom rules are not running
 

src/PSRule.Rules.Azure/Data/Template/CustomTypeDependencyGraph.cs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Resources;
+using System.Text;
+using Newtonsoft.Json.Linq;
+
+namespace PSRule.Rules.Azure.Data.Template
+{
+    /// <summary>
+    /// A graph that tracks dependencies between type definitions.
+    /// </summary>
+    internal sealed class CustomTypeDependencyGraph
+    {
+        private readonly Dictionary<string, Node> _ById = new(StringComparer.OrdinalIgnoreCase);
+
+        [DebuggerDisplay("{Resource.Id}")]
+        private sealed class Node
+        {
+            internal readonly string Id;
+            internal readonly JObject Value;
+
+            public Node(string id, JObject value)
+            {
+                Id = id;
+                Value = value;
+            }
+        }
+
+        /// <summary>
+        /// Add a custom type to the graph.
+        /// </summary>
+        /// <param name="name">The custom type node to add to the graph.</param>
+        /// <param name="value">The definition of the custom type.</param>
+        internal void Track(string name, JObject value)
+        {
+            if (value == null)
+                return;
+
+            var id = $"#/definitions/{name}";
+            var item = new Node(id, value);
+            _ById[id] = item;
+        }
+
+        /// <summary>
+        /// Get a list of ordered custom types.
+        /// </summary>
+        internal IEnumerable<KeyValuePair<string, JObject>> GetOrdered()
+        {
+            var stack = new List<KeyValuePair<string, JObject>>(_ById.Values.Count);
+            var visited = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+            foreach (var item in _ById.Values)
+            {
+                Visit(item, visited, stack);
+            }
+            return stack.ToArray();
+        }
+
+        private bool TryGet(string id, out Node item)
+        {
+            return _ById.TryGetValue(id, out item);
+        }
+
+        /// <summary>
+        /// Traverse a node and parent type.
+        /// </summary>
+        private void Visit(Node item, HashSet<string> visited, List<KeyValuePair<string, JObject>> stack)
+        {
+            if (visited.Contains(item.Id))
+                return;
+
+            visited.Add(item.Id);
+            if (item.Value.TryStringProperty("$ref", out var id) && TryGet(id, out var parent))
+            {
+                Visit(parent, visited, stack);
+            }
+            stack.Add(new KeyValuePair<string, JObject>(item.Id, item.Value));
+        }
+    }
+}

src/PSRule.Rules.Azure/Data/Template/TemplateVisitor.cs

@@ -940,7 +940,7 @@ protected virtual void Template(TemplateContext context, string deploymentName,
                     ContentVersion(context, contentVersion);
 
                 // Handle custom type definitions
-                if (TryObjectProperty(template, PROPERTY_DEFINITIONS, out var definitions))
+                if (!isNested && TryObjectProperty(template, PROPERTY_DEFINITIONS, out var definitions))
                     Definitions(context, definitions);
 
                 // Handle compile time function variables
@@ -993,24 +993,33 @@ protected virtual void Definitions(TemplateContext context, JObject definitions)
             if (definitions == null || definitions.Count == 0)
                 return;
 
+            var graph = new CustomTypeDependencyGraph();
             foreach (var definition in definitions)
-                Definition(context, definition.Key, definition.Value as JObject);
+            {
+                graph.Track(definition.Key, definition.Value as JObject);
+            }
+
+            var ordered = graph.GetOrdered();
+            foreach (var definition in ordered)
+            {
+                Definition(context, definition.Key, definition.Value);
+            }
         }
 
-        protected virtual void Definition(TemplateContext context, string definitionName, JObject definition)
+        protected virtual void Definition(TemplateContext context, string definitionId, JObject definition)
         {
-            if (TryDefinition(definition, out var value))
-                context.AddDefinition($"#/definitions/{definitionName}", value);
+            if (TryDefinition(context, definition, out var value))
+                context.AddDefinition(definitionId, value);
         }
 
-        private static bool TryDefinition(JObject definition, out ITypeDefinition value)
+        private static bool TryDefinition(TemplateContext context, JObject definition, out ITypeDefinition value)
         {
             value = null;
-            var type = GetTypePrimitive(definition);
+            var type = GetTypePrimitive(context, definition);
             if (type == TypePrimitive.None)
                 return false;
 
-            var isNullable = definition.TryBoolProperty(PROPERTY_NULLABLE, out var nullable) && nullable.HasValue;
+            var isNullable = GetTypeNullable(context, definition);
 
             value = new TypeDefinition(type, definition, isNullable);
             return true;
@@ -1121,7 +1130,7 @@ private static bool TryParameterType(ITemplateContext context, JObject parameter
                 value = new ParameterType(definition.Type, type);
 
             // Try type
-            if (parameter.TryGetProperty(PROPERTY_TYPE, out type) &&
+            else if (parameter.TryGetProperty(PROPERTY_TYPE, out type) &&
                 ParameterType.TrySimpleType(type, out var v))
                 value = v;
 
@@ -1396,7 +1405,7 @@ protected static bool IsDeploymentResource(string resourceType)
             return string.Equals(resourceType, RESOURCETYPE_DEPLOYMENT, StringComparison.OrdinalIgnoreCase);
         }
 
-        private static TemplateContext GetDeploymentContext(TemplateContext context, string deploymentName, JObject resource, JObject properties)
+        private TemplateContext GetDeploymentContext(TemplateContext context, string deploymentName, JObject resource, JObject properties)
         {
             if (!TryObjectProperty(properties, PROPERTY_EXPRESSIONEVALUATIONOPTIONS, out var options) ||
                 !TryStringProperty(options, PROPERTY_SCOPE, out var scope) ||
@@ -1420,12 +1429,17 @@ private static TemplateContext GetDeploymentContext(TemplateContext context, str
             TryObjectProperty(template, PROPERTY_PARAMETERS, out var templateParameters);
 
             var deploymentContext = new TemplateContext(context.Pipeline, subscription, resourceGroup, tenant, managementGroup, parameterDefaults);
+
+            // Handle custom type definitions early to allow type mapping of parameters if required.
+            if (TryObjectProperty(template, PROPERTY_DEFINITIONS, out var definitions))
+                Definitions(deploymentContext, definitions);
+
             if (TryObjectProperty(properties, PROPERTY_PARAMETERS, out var innerParameters))
             {
                 foreach (var parameter in innerParameters.Properties())
                 {
                     var parameterType = templateParameters.TryGetProperty<JObject>(parameter.Name, out var templateParameter) &&
-                        TryParameterType(context, templateParameter, out var t) ? t.Value.Type : TypePrimitive.None;
+                        TryParameterType(deploymentContext, templateParameter, out var t) ? t.Value.Type : TypePrimitive.None;
 
                     if (parameter.Value is JValue parameterValueExpression)
                         parameter.Value = ResolveToken(context, ResolveVariable(context, parameterType, parameterValueExpression));
@@ -1569,18 +1583,40 @@ protected void Outputs(TemplateContext context, JObject outputs)
 
         protected virtual void Output(TemplateContext context, string name, JObject output)
         {
-            ResolveProperty(context, output, PROPERTY_VALUE, GetTypePrimitive(output));
+            ResolveProperty(context, output, PROPERTY_VALUE, GetTypePrimitive(context, output));
             context.CheckOutput(name, output);
             context.AddOutput(name, output);
         }
 
         #endregion Outputs
 
-        private static TypePrimitive GetTypePrimitive(JObject value)
+        private static TypePrimitive GetTypePrimitive(TemplateContext context, JObject value)
+        {
+            if (value == null) return TypePrimitive.None;
+
+            // Find primitive.
+            if (value.TryGetProperty(PROPERTY_TYPE, out var t) && Enum.TryParse(t, ignoreCase: true, result: out TypePrimitive type))
+                return type;
+
+            // Find primitive from parent type.
+            if (context != null && value.TryGetProperty(PROPERTY_REF, out var id) && context.TryDefinition(id, out var definition))
+                return GetTypePrimitive(context, definition.Definition);
+
+            return TypePrimitive.None;
+        }
+
+        private static bool GetTypeNullable(TemplateContext context, JObject value)
         {
-            return value == null ||
-                !value.TryGetProperty(PROPERTY_TYPE, out var t) ||
-                !Enum.TryParse(t, ignoreCase: true, result: out TypePrimitive type) ? TypePrimitive.None : type;
+            if (value == null) return false;
+
+            // Find nullable from parent type.
+            if (value.TryBoolProperty(PROPERTY_NULLABLE, out var nullable) && nullable.Value)
+                return nullable.Value;
+
+            if (context != null && value.TryGetProperty(PROPERTY_REF, out var id) && context.TryDefinition(id, out var definition))
+                return definition.Nullable;
+
+            return false;
         }
 
         protected static StringExpression<T> Expression<T>(ITemplateContext context, string s)

src/PSRule.Rules.Azure/Data/Template/TypeDefinition.cs

@@ -9,6 +9,8 @@ internal interface ITypeDefinition
     {
         TypePrimitive Type { get; }
 
+        JObject Definition { get; }
+
         bool Nullable { get; }
     }
 

tests/PSRule.Rules.Azure.Tests/PSRule.Rules.Azure.Tests.csproj

@@ -203,6 +203,9 @@
     <None Update="Tests.Bicep.27.json">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>
+    <None Update="Tests.Bicep.28.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
     <None Update="Tests.Bicep.29.json">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>

tests/PSRule.Rules.Azure.Tests/TemplateVisitorTests.cs

@@ -933,6 +933,19 @@ public void NullableParameters()
             Assert.Equal("sourceId", result["value"].Value<string>());
         }
 
+        [Fact]
+        public void CompileTimeImports()
+        {
+            var resources = ProcessTemplate(GetSourcePath("Tests.Bicep.28.json"), null, out var templateContext);
+            Assert.Equal(2, resources.Length);
+
+            Assert.True(templateContext.RootDeployment.TryOutput("outValue", out JObject outValue));
+            Assert.Equal("t1", outValue["value"].Value<string>());
+
+            Assert.True(templateContext.RootDeployment.TryOutput("hello", out JObject helloValue));
+            Assert.Equal("Hello value!", helloValue["value"].Value<string>());
+        }
+
         [Fact]
         public void MockWellKnownProperties()
         {

tests/PSRule.Rules.Azure.Tests/Tests.Bicep.28.bicep

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+module child './Tests.Bicep.28.child.bicep' = {
+  name: 'child'
+  params: {
+    value: 't1'
+  }
+}
+
+output outValue string = child.outputs.outValue
+
+output hello string = child.outputs.hello

tests/PSRule.Rules.Azure.Tests/Tests.Bicep.28.child.bicep

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { myOtherStringType, myOtherStringTypeNullable2, globals } from './Tests.Bicep.28.export.bicep'
+import { sayHello } from './Tests.Bicep.28.export.bicep'
+
+param value myOtherStringType = 't2'
+
+param valueNullable myOtherStringTypeNullable2
+
+output outValue myOtherStringType = value
+
+output outValueNullable myOtherStringTypeNullable2 = valueNullable
+
+output hello string = sayHello('value')
+
+output outGlobal object = globals

tests/PSRule.Rules.Azure.Tests/Tests.Bicep.28.export.bicep

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+@export()
+type myStringType = 't1' | 't2'
+
+@export()
+type myOtherStringType = myStringType
+
+type myOtherStringTypeNullable = myOtherStringType?
+
+@export()
+type myOtherStringTypeNullable2 = myOtherStringTypeNullable
+
+@export()
+var globals = {
+  env: 'dev'
+  instance: 1
+}
+
+@export()
+func sayHello(name string) string => 'Hello ${name}!'