alzlib.go

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

package alzlib

import (
	"context"
	"errors"
	"fmt"
	"slices"
	"strings"
	"sync"

	"github.com/Azure/alzlib/assets"
	"github.com/Azure/alzlib/cache"
	"github.com/Azure/alzlib/internal/processor"
	"github.com/Azure/azure-sdk-for-go/sdk/azcore/arm"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armpolicy"
	"github.com/brunoga/deep"
	mapset "github.com/deckarep/golang-set/v2"
	"github.com/hashicorp/go-multierror"
)

const (
	defaultParallelism           = 10 // default number of parallel requests to make to Azure APIs
	defaultOverwrite             = false
	defaultUniqueRoleDefinitions = true // default to unique role definitions per management group
	// InitialMetadataSliceCapacity is the initial capacity for the metadata slice.
	InitialMetadataSliceCapacity = 10
	// MaxRecursionDepth is the maximum depth for recursive operations.
	MaxRecursionDepth = 5
	// PolicySetDefinitionsType is the lowercase type for policy set definitions, without the resource provider.
	PolicySetDefinitionsType = "policysetdefinitions"
	// PolicyDefinitionsType is the lowercase type for policy definitions, without the resource provider.
	PolicyDefinitionsType = "policydefinitions"
)

// AlzLib is the structure that gets built from the the library files
// do not create this directly, use NewAlzLib instead.
type AlzLib struct {
	Options *Options

	archetypes                    map[string]*Archetype
	architectures                 map[string]*Architecture
	policyAssignments             map[string]*assets.PolicyAssignment
	policyDefinitions             map[string]*assets.PolicyDefinitionVersions
	policySetDefinitions          map[string]*assets.PolicySetDefinitionVersions
	roleDefinitions               map[string]*assets.RoleDefinition
	defaultPolicyAssignmentValues DefaultPolicyAssignmentValues
	metadata                      []*Metadata

	cache   BuiltInCache
	clients *azureClients
	mu      sync.RWMutex // mu is a mutex to concurrency protect the AlzLib maps
}

type azureClients struct {
	policyClient *armpolicy.ClientFactory
}

// Options are options for the AlzLib.
type Options struct {
	// AllowOverwrite allows overwriting of existing policy assignments when processing additional libraries
	// with AlzLib.Init().
	AllowOverwrite bool
	// Parallelism is the number of parallel requests to make to Azure APIs when getting policy definitions
	// and policy set definitions.
	Parallelism int
	// UniqueRoleDefinitions indicates whether to update the role definitions to be unique per management group.
	// If this is not set, you may end up with conflicting role definition names.
	UniqueRoleDefinitions bool
}

// NewAlzLib returns a new instance of the alzlib library, optionally using the supplied directory
// for additional policy (set) definitions.
// To customize the options for the AlzLib, pass in an AlzLibOptions struct, otherwise the default
// options will be used.
func NewAlzLib(opts *Options) *AlzLib {
	if opts == nil {
		opts = defaultAlzLibOptions()
	}

	az := &AlzLib{
		Options:                       opts,
		archetypes:                    make(map[string]*Archetype),
		architectures:                 make(map[string]*Architecture),
		policyAssignments:             make(map[string]*assets.PolicyAssignment),
		policyDefinitions:             make(map[string]*assets.PolicyDefinitionVersions),
		policySetDefinitions:          make(map[string]*assets.PolicySetDefinitionVersions),
		roleDefinitions:               make(map[string]*assets.RoleDefinition),
		metadata:                      make([]*Metadata, 0, InitialMetadataSliceCapacity),
		defaultPolicyAssignmentValues: make(DefaultPolicyAssignmentValues),
		clients:                       new(azureClients),
		mu:                            sync.RWMutex{},
	}

	return az
}

func defaultAlzLibOptions() *Options {
	return &Options{
		Parallelism:           defaultParallelism,
		AllowOverwrite:        defaultOverwrite,
		UniqueRoleDefinitions: defaultUniqueRoleDefinitions,
	}
}

// Metadata returns all the registered metadata in the AlzLib struct.
func (az *AlzLib) Metadata() []*Metadata {
	az.mu.RLock()
	defer az.mu.RUnlock()

	return deep.MustCopy(az.metadata)
}

// AddPolicyAssignments adds policy assignments to the AlzLib struct.
func (az *AlzLib) AddPolicyAssignments(pas ...*assets.PolicyAssignment) error {
	az.mu.Lock()
	defer az.mu.Unlock()

	for _, pa := range pas {
		if pa == nil || pa.Name == nil || *pa.Name == "" {
			continue
		}

		if _, exists := az.policyAssignments[*pa.Name]; exists && !az.Options.AllowOverwrite {
			return fmt.Errorf(
				"Alzlib.AddPolicyAssignments: policy assignment with name %s already exists and allow overwrite not set",
				*pa.Name,
			)
		}

		cpy, err := deep.Copy(pa)
		if err != nil {
			return fmt.Errorf(
				"Alzlib.AddPolicyAssignments: error making deep copy of policy assignment %s: %w",
				*pa.Name,
				err,
			)
		}

		az.policyAssignments[*pa.Name] = cpy
	}

	return nil
}

// AddPolicyDefinitions adds policy definitions to the AlzLib struct.
func (az *AlzLib) AddPolicyDefinitions(pds ...*assets.PolicyDefinition) error {
	az.mu.Lock()
	defer az.mu.Unlock()

	var merr error

	for _, pd := range pds {
		if pd == nil || pd.Name == nil || *pd.Name == "" {
			continue
		}

		if pdvc, exists := az.policyDefinitions[*pd.Name]; exists {
			if err := pdvc.Add(pd, az.Options.AllowOverwrite); err != nil {
				merr = multierror.Append(merr, pdvc.Upsert(pdvc, az.Options.AllowOverwrite))
			}

			continue
		}

		cpy := deep.MustCopy(pd)
		pdvc := assets.NewPolicyDefinitionVersions()
		pdvc.Add(cpy, az.Options.AllowOverwrite) // nolint:errcheck
		az.policyDefinitions[*pd.Name] = pdvc
	}

	return merr
}

// AddPolicySetDefinitions adds policy set definitions to the AlzLib struct.
func (az *AlzLib) AddPolicySetDefinitions(psds ...*assets.PolicySetDefinition) error {
	az.mu.Lock()
	defer az.mu.Unlock()

	var merr error

	for _, psd := range psds {
		if psd == nil || psd.Name == nil || *psd.Name == "" {
			continue
		}

		if psdvc, exists := az.policySetDefinitions[*psd.Name]; exists {
			if err := psdvc.Add(psd, az.Options.AllowOverwrite); err != nil {
				merr = multierror.Append(merr, err)
			}

			continue
		}

		cpy := deep.MustCopy(psd)
		psdvc := assets.NewPolicySetDefinitionVersions()
		psdvc.Add(cpy, az.Options.AllowOverwrite) // nolint:errcheck
		az.policySetDefinitions[*psd.Name] = psdvc
	}

	return merr
}

// AddRoleDefinitions adds role definitions to the AlzLib struct.
func (az *AlzLib) AddRoleDefinitions(rds ...*assets.RoleDefinition) error {
	az.mu.Lock()
	defer az.mu.Unlock()

	for _, rd := range rds {
		if rd == nil || rd.Name == nil || *rd.Name == "" {
			continue
		}

		if _, exists := az.roleDefinitions[*rd.Name]; exists && !az.Options.AllowOverwrite {
			return fmt.Errorf(
				"Alzlib.AddRoleDefinitions: role definition with name %s already exists and allow overwrite not set",
				*rd.Name,
			)
		}

		cpy, err := deep.Copy(rd)
		if err != nil {
			return fmt.Errorf(
				"Alzlib.AddRoleDefinitions: error making deep copy of role definition %s: %w",
				*rd.Name,
				err,
			)
		}

		az.roleDefinitions[*rd.Name] = cpy
	}

	return nil
}

// PolicyAssignments returns a slice of all the policy assignment names in the library.
func (az *AlzLib) PolicyAssignments() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.policyAssignments))
	for k := range az.policyAssignments {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// PolicyDefinitions returns a slice of all the policy definition names in the library.
func (az *AlzLib) PolicyDefinitions() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.policyDefinitions))
	for k := range az.policyDefinitions {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// PolicySetDefinitions returns a slice of all the policy set definition names in the library.
func (az *AlzLib) PolicySetDefinitions() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.policySetDefinitions))
	for k := range az.policySetDefinitions {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// RoleDefinitions returns a slice of all the role definition names in the library.
func (az *AlzLib) RoleDefinitions() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.roleDefinitions))
	for k := range az.roleDefinitions {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// Archetypes returns a list of the archetypes in the AlzLib struct.
func (az *AlzLib) Archetypes() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.archetypes))
	for k := range az.archetypes {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// Archetype returns a copy of the requested archetype by name.
func (az *AlzLib) Archetype(name string) *Archetype {
	az.mu.RLock()
	defer az.mu.RUnlock()

	arch, ok := az.archetypes[name]
	if !ok {
		return nil
	}

	return arch.copy()
}

// Architectures returns a list of the architecture names in the AlzLib struct.
func (az *AlzLib) Architectures() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.architectures))
	for k := range az.architectures {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// PolicyDefaultValues returns a sorted list of the default policy assignment default values in the
// AlzLib struct.
func (az *AlzLib) PolicyDefaultValues() []string {
	az.mu.RLock()
	defer az.mu.RUnlock()

	result := make([]string, 0, len(az.defaultPolicyAssignmentValues))
	for k := range az.defaultPolicyAssignmentValues {
		result = append(result, k)
	}

	slices.Sort(result)

	return result
}

// PolicyDefaultValue returns a copy of the requested default policy assignment default values by name.
func (az *AlzLib) PolicyDefaultValue(name string) *DefaultPolicyAssignmentValuesValue {
	az.mu.RLock()
	defer az.mu.RUnlock()

	val, ok := az.defaultPolicyAssignmentValues[name]
	if !ok {
		return nil
	}

	ret := val.copy()

	return &ret
}

// Architecture returns the requested architecture.
func (az *AlzLib) Architecture(name string) *Architecture {
	az.mu.RLock()
	defer az.mu.RUnlock()

	arch, ok := az.architectures[name]
	if !ok {
		return nil
	}

	return arch
}

// PolicyDefinitionExists returns true if the policy definition name exists in the AlzLib struct.
func (az *AlzLib) PolicyDefinitionExists(name string, version *string) bool {
	az.mu.RLock()
	defer az.mu.RUnlock()

	pdvc, exists := az.policyDefinitions[name]
	if !exists {
		return false
	}

	pdv, err := pdvc.GetVersion(version)
	if err != nil {
		return false
	}

	return pdv != nil
}

// PolicySetDefinitionExists returns true if the policy set definition name and version exists in the AlzLib
// struct.
func (az *AlzLib) PolicySetDefinitionExists(name string, version *string) bool {
	az.mu.RLock()
	defer az.mu.RUnlock()

	psdvc, exists := az.policySetDefinitions[name]
	if !exists {
		return false
	}

	psdv, err := psdvc.GetVersion(version)
	if err != nil {
		return false
	}

	return psdv != nil
}

// PolicyAssignmentExists returns true if the policy assignment exists name in the AlzLib struct.
func (az *AlzLib) PolicyAssignmentExists(name string) bool {
	az.mu.RLock()
	defer az.mu.RUnlock()

	_, exists := az.policyAssignments[name]

	return exists
}

// RoleDefinitionExists returns true if the role definition name exists in the AlzLib struct.
func (az *AlzLib) RoleDefinitionExists(name string) bool {
	az.mu.RLock()
	defer az.mu.RUnlock()

	_, exists := az.roleDefinitions[name]

	return exists
}

// PolicyDefinition returns a deep copy of the requested policy definition version.
// This is safe to modify without affecting the original.
func (az *AlzLib) PolicyDefinition(name string, version *string) *assets.PolicyDefinition {
	az.mu.RLock()
	defer az.mu.RUnlock()

	pd, ok := az.policyDefinitions[name]
	if !ok {
		return nil
	}

	pdv, err := pd.GetVersion(version)
	if err != nil {
		return nil
	}

	return deep.MustCopy(pdv)
}

// SetAssignPermissionsOnDefinitionParameter sets the AssignPermissions metadata field to true for
// for the definition (all versions) and parameter with the given name.
func (az *AlzLib) SetAssignPermissionsOnDefinitionParameter(
	definitionName string, parameterName string,
) {
	az.mu.Lock()
	defer az.mu.Unlock()

	definition, ok := az.policyDefinitions[definitionName]
	if !ok {
		return
	}

	for def := range definition.AllVersions() {
		def.SetAssignPermissionsOnParameter(parameterName)
	}
}

// UnsetAssignPermissionsOnDefinitionParameter removes the AssignPermissions metadata field to true
// for the definition (all versions) and parameter with the given name.
func (az *AlzLib) UnsetAssignPermissionsOnDefinitionParameter(
	definitionName string, parameterName string,
) {
	az.mu.Lock()
	defer az.mu.Unlock()

	definition, ok := az.policyDefinitions[definitionName]
	if !ok {
		return
	}

	for def := range definition.AllVersions() {
		def.UnsetAssignPermissionsOnParameter(parameterName)
	}
}

// PolicyAssignment returns a deep copy of the requested policy assignment.
// This is safe to modify without affecting the original.
func (az *AlzLib) PolicyAssignment(name string) *assets.PolicyAssignment {
	az.mu.RLock()
	defer az.mu.RUnlock()

	pa, ok := az.policyAssignments[name]
	if !ok {
		return nil
	}

	return deep.MustCopy(pa)
}

// PolicySetDefinition returns a deep copy of the requested policy set definition.
// This is safe to modify without affecting the original.
func (az *AlzLib) PolicySetDefinition(name string, version *string) *assets.PolicySetDefinition {
	az.mu.RLock()
	defer az.mu.RUnlock()

	psd, ok := az.policySetDefinitions[name]
	if !ok {
		return nil
	}

	psdv, err := psd.GetVersion(version)
	if err != nil {
		return nil
	}

	return deep.MustCopy(psdv)
}

// RoleDefinition returns a deep copy of the requested role definition.
// This is safe to modify without affecting the original.
func (az *AlzLib) RoleDefinition(name string) *assets.RoleDefinition {
	az.mu.RLock()
	defer az.mu.RUnlock()

	rd, ok := az.roleDefinitions[name]
	if !ok {
		return nil
	}

	return deep.MustCopy(rd)
}

// BuiltInCache is an interface for providing cached built-in Azure policy definitions
// and policy set definitions. When a complete cache is supplied via [AlzLib.AddCache],
// the policy client ([AlzLib.AddPolicyClient]) is not required because
// [AlzLib.GetDefinitionsFromAzure] will find every definition in the cache and skip
// all Azure API calls.
type BuiltInCache interface {
	PolicyDefinitions() map[string]*assets.PolicyDefinitionVersions
	PolicySetDefinitions() map[string]*assets.PolicySetDefinitionVersions
	// PolicyDefinitionVersionsByName returns the policy definition versions for the given name,
	// or nil if not found.
	PolicyDefinitionVersionsByName(name string) *assets.PolicyDefinitionVersions
	// PolicySetDefinitionVersionsByName returns the policy set definition versions for the given name,
	// or nil if not found.
	PolicySetDefinitionVersionsByName(name string) *assets.PolicySetDefinitionVersions
}

// AddCache stores a [BuiltInCache] for lazy lookup during [AlzLib.GetDefinitionsFromAzure].
// Definitions are fetched from the cache on demand rather than being loaded eagerly.
// The cache is retained for the lifetime of AlzLib; call AddCache(nil) to release it
// explicitly and allow the garbage collector to reclaim the memory.
// A previously stored cache is replaced by the new one.
func (az *AlzLib) AddCache(c BuiltInCache) {
	az.mu.Lock()
	defer az.mu.Unlock()

	az.cache = c
}

// ExportBuiltInCache creates a [cache.Cache] from the built-in policy definitions and policy
// set definitions that are currently loaded in AlzLib. Definitions are included when their
// policy type is [armpolicy.PolicyTypeBuiltIn], [armpolicy.PolicyTypeStatic], or is
// unspecified/nil (which is treated as built-in); custom definitions (loaded from library
// files) are excluded.
//
// This is useful when callers want to persist a minimal cache covering only the definitions
// referenced by their specific library — rather than using alzlibtool to cache everything.
// The returned cache can be saved with [cache.Cache.Save] and reloaded later with
// [cache.NewCache], then re-injected via [AlzLib.AddCache] to skip Azure API calls on
// subsequent runs.
func (az *AlzLib) ExportBuiltInCache() *cache.Cache {
	az.mu.RLock()
	defer az.mu.RUnlock()

	pds := make(map[string]*assets.PolicyDefinitionVersions)
	psds := make(map[string]*assets.PolicySetDefinitionVersions)

	for name, pdvs := range az.policyDefinitions {
		if !isBuiltInPolicyDefinitionVersions(pdvs) {
			continue
		}

		pds[name] = deep.MustCopy(pdvs)
	}

	for name, psdvs := range az.policySetDefinitions {
		if !isBuiltInPolicySetDefinitionVersions(psdvs) {
			continue
		}

		psds[name] = deep.MustCopy(psdvs)
	}

	return cache.NewCacheFromDefinitions(pds, psds)
}

// isBuiltInPolicyDefinitionVersions returns true if any version in the collection has a
// built-in or static policy type. Collections with no type set are treated as built-in to
// ensure definitions fetched from Azure (which always set PolicyType) are never excluded.
func isBuiltInPolicyDefinitionVersions(pdvs *assets.PolicyDefinitionVersions) bool {
	for def := range pdvs.AllVersions() {
		if def.Properties == nil || def.Properties.PolicyType == nil {
			return true
		}

		switch *def.Properties.PolicyType {
		case armpolicy.PolicyTypeBuiltIn, armpolicy.PolicyTypeStatic:
			return true
		}
	}

	return false
}

// isBuiltInPolicySetDefinitionVersions returns true if any version in the collection has a
// built-in or static policy type. Collections with no type set are treated as built-in.
func isBuiltInPolicySetDefinitionVersions(psdvs *assets.PolicySetDefinitionVersions) bool {
	for def := range psdvs.AllVersions() {
		if def.Properties == nil || def.Properties.PolicyType == nil {
			return true
		}

		switch *def.Properties.PolicyType {
		case armpolicy.PolicyTypeBuiltIn, armpolicy.PolicyTypeStatic:
			return true
		}
	}

	return false
}

// AddPolicyClient adds an authenticated *armpolicy.ClientFactory to the AlzLib struct.
// This is needed to get policy objects from Azure.
func (az *AlzLib) AddPolicyClient(client *armpolicy.ClientFactory) {
	az.mu.Lock()
	defer az.mu.Unlock()

	az.clients.policyClient = client
}

// Init processes ALZ libraries, supplied as `LibraryReference` interfaces.
// Use FetchAzureLandingZonesLibraryMember/FetchLibraryByGetterString to get the library from
// GitHub.
// It populates the struct with the results of the processing.
func (az *AlzLib) Init(ctx context.Context, libs ...LibraryReference) error {
	az.mu.Lock()
	defer az.mu.Unlock()

	if az.Options == nil || az.Options.Parallelism == 0 {
		return errors.New("Alzlib.Init: alzlib Options not set or parallelism is `0`")
	}

	// Process the libraries
	for _, ref := range libs {
		if ref == nil {
			return errors.New("Alzlib.Init: library is nil")
		}

		if ref.FS() == nil {
			if _, err := ref.Fetch(ctx, hash(ref)); err != nil {
				return fmt.Errorf("Alzlib.Init: error fetching library %s: %w", ref, err)
			}
		}

		res := processor.NewResult()
		pc := processor.NewClient(ref.FS())

		if err := pc.Process(res); err != nil {
			return fmt.Errorf("Alzlib.Init: error processing library %v: %w", ref, err)
		}

		if res.Metadata != nil {
			az.metadata = append(az.metadata, NewMetadata(res.Metadata, ref))
		}

		// Put results into the AlzLib.
		if err := az.addPolicyAndRoleAssets(res); err != nil {
			return fmt.Errorf("Alzlib.Init: error adding processed result to AlzLib: %w", err)
		}

		// Add default policy values
		if err := az.addDefaultPolicyAssignmentValues(res); err != nil {
			return fmt.Errorf(
				"Alzlib.Init: error adding default policy assignment values to AlzLib: %w",
				err,
			)
		}

		// Generate archetypes
		if err := az.generateArchetypes(res); err != nil {
			return fmt.Errorf("Alzlib.Init: error generating archetypes: %w", err)
		}

		// Generate override archetypes
		if err := az.generateOverrideArchetypes(res); err != nil {
			return fmt.Errorf("Alzlib.Init: error generating override archetypes: %w", err)
		}

		// Generate architectures
		if err := az.generateArchitectures(res); err != nil {
			return fmt.Errorf("Alzlib.Init: error generating architectures: %w", err)
		}
	}

	return nil
}

// GetDefinitionsFromAzure takes a slice of requests for built-in definitions.
// It fetches requested definitions from Azure only when they do not already exist in AlzLib
// (determined by the last segment of the resource ID). For policy set definitions, existing
// sets in AlzLib are inspected to discover referenced built-in definitions, and any missing
// referenced definitions are then fetched as needed.
// If a cache has been set via [AlzLib.AddCache], definitions are looked up from the cache
// before falling back to Azure API calls.
// The cache is retained for the lifetime of AlzLib; callers can explicitly clear it by calling
// AddCache(nil) when they no longer need it.
func (az *AlzLib) GetDefinitionsFromAzure(ctx context.Context, reqs []BuiltInRequest) error {
	policyDefsToGet := make([]BuiltInRequest, 0, len(reqs))
	policySetDefsToGet := make([]BuiltInRequest, 0, len(reqs))

	for _, req := range reqs {
		if req.ResourceID == nil {
			return fmt.Errorf("Alzlib.GetDefinitionsFromAzure: resource ID is nil in BuiltInRequest")
		}

		switch strings.ToLower(req.ResourceID.ResourceType.Type) {
		case PolicyDefinitionsType:
			if !az.PolicyDefinitionExists(req.ResourceID.Name, req.Version) {
				policyDefsToGet = append(policyDefsToGet, req)
			}
		case PolicySetDefinitionsType:
			// If the set is not present, OR if the set contains referenced definitions that are not
			// present add it to the list of set defs to get.
			exists := az.PolicySetDefinitionExists(req.ResourceID.Name, req.Version)
			if !exists {
				policySetDefsToGet = append(policySetDefsToGet, req)
				continue
			}

			psd := az.PolicySetDefinition(req.ResourceID.Name, req.Version)
			if psd == nil {
				version := "<nil>"
				if req.Version != nil {
					version = *req.Version
				}

				return fmt.Errorf(
					"Alzlib.GetDefinitionsFromAzure: error getting policy set definition %s@%s",
					req.ResourceID,
					version,
				)
			}

			// This is already made safe to access by the constructor.
			pdrefs := psd.Properties.PolicyDefinitions

			for _, ref := range pdrefs {
				subResID, err := arm.ParseResourceID(*ref.PolicyDefinitionID)
				if err != nil {
					return fmt.Errorf(
						"Alzlib.GetDefinitionsFromAzure: policy set definition %s error parsing referenced definition resource id: %w",
						*psd.Name,
						err,
					)
				}

				if !az.PolicyDefinitionExists(subResID.Name, ref.DefinitionVersion) {
					subReq := BuiltInRequest{
						ResourceID: subResID,
						Version:    ref.DefinitionVersion,
					}
					policyDefsToGet = append(policyDefsToGet, subReq)
				}
			}

		default:
			return fmt.Errorf(
				"Alzlib.GetDefinitionsFromAzure: unexpected policy definition type when processing assignments: %s",
				req,
			)
		}
	}

	// Add the referenced built-in definitions and set definitions to the AlzLib struct
	// so that we can use the data to determine the correct role assignments at scope.
	if len(policyDefsToGet) != 0 {
		if err := az.getBuiltInPolicies(ctx, policyDefsToGet); err != nil {
			return fmt.Errorf(
				"Alzlib.GetDefinitionsFromAzure: error getting built-in policy definitions: %w",
				err,
			)
		}
	}

	if len(policySetDefsToGet) != 0 {
		if err := az.getBuiltInPolicySets(ctx, policySetDefsToGet); err != nil {
			return fmt.Errorf(
				"Alzlib.GetDefinitionsFromAzure: error getting built-in policy set definitions: %w",
				err,
			)
		}
	}

	return nil
}

// AssignmentReferencedDefinitionHasParameter checks if the referenced definition of an assignment
// has a specific parameter. It takes a resource ID and a parameter name as input and returns a
// boolean indicating whether the parameter exists or not.
func (az *AlzLib) AssignmentReferencedDefinitionHasParameter(
	res *arm.ResourceID,
	definitionVersion *string,
	param string,
) bool {
	switch strings.ToLower(res.ResourceType.Type) {
	case PolicyDefinitionsType:
		pd := az.PolicyDefinition(res.Name, definitionVersion)
		if pd == nil {
			// If we don't have the definition, return true as this won't cause an issue.
			// We might be checking that a policy default value exists for a definition that isn't assigned.
			return true
		}

		if pd.Parameter(param) != nil {
			return true
		}
	case PolicySetDefinitionsType:
		psd := az.PolicySetDefinition(res.Name, definitionVersion)
		if psd == nil {
			// If we don't have the definition, return true as this won't cause an issue.
			// We might be checking that a policy default value exists for a definition that isn't assigned.
			return true
		}

		if psd.Parameter(param) != nil {
			return true
		}
	}

	return false
}

// policyDefinitionVersionsPager exposes the subset of pager behaviour needed for testing.
type policyDefinitionVersionsPager interface {
	More() bool
	NextPage(context.Context) (armpolicy.DefinitionVersionsClientListBuiltInResponse, error)
}

// policySetDefinitionVersionsPager exposes the subset of pager behaviour needed for testing.
type policySetDefinitionVersionsPager interface {
	More() bool
	NextPage(context.Context) (armpolicy.SetDefinitionVersionsClientListBuiltInResponse, error)
}

// policyDefinitionFromCache returns the policy definition for the given name and version
// from the cache, or nil if the cache is unset or does not contain a matching entry.
func (az *AlzLib) policyDefinitionFromCache(name string, version *string) (*assets.PolicyDefinition, error) {
	az.mu.RLock()
	c := az.cache
	az.mu.RUnlock()

	if c == nil {
		return nil, nil
	}

	pdvs := c.PolicyDefinitionVersionsByName(name)
	if pdvs == nil {
		return nil, nil
	}

	pd, err := pdvs.GetVersion(version)
	if err != nil {
		if errors.Is(err, assets.ErrNoVersionFound) {
			return nil, nil
		}

		return nil, fmt.Errorf("getting policy definition %s from cache: %w", JoinNameAndVersion(name, version), err)
	}

	return pd, nil
}

// policySetDefinitionFromCache returns the policy set definition for the given name and version
// from the cache, or nil if the cache is unset or does not contain a matching entry.
func (az *AlzLib) policySetDefinitionFromCache(name string, version *string) (*assets.PolicySetDefinition, error) {
	az.mu.RLock()
	c := az.cache
	az.mu.RUnlock()

	if c == nil {
		return nil, nil
	}

	psdvs := c.PolicySetDefinitionVersionsByName(name)
	if psdvs == nil {
		return nil, nil
	}

	psd, err := psdvs.GetVersion(version)
	if err != nil {
		if errors.Is(err, assets.ErrNoVersionFound) {
			return nil, nil
		}

		return nil, fmt.Errorf("getting policy set definition %s from cache: %w", JoinNameAndVersion(name, version), err)
	}

	return psd, nil
}

// getBuiltInPolicies retrieves the built-in policy definitions with the given names
// and adds them to the AlzLib struct.
func (az *AlzLib) getBuiltInPolicies(ctx context.Context, reqs []BuiltInRequest) error {
	var (
		versionedClient *armpolicy.DefinitionVersionsClient
		client          *armpolicy.DefinitionsClient
	)

	for _, req := range reqs {
		if az.PolicyDefinitionExists(req.ResourceID.Name, req.Version) {
			continue
		}

		// Check cache before calling Azure.
		pdv, cacheErr := az.policyDefinitionFromCache(req.ResourceID.Name, req.Version)
		if cacheErr != nil {
			return fmt.Errorf(
				"Alzlib.getBuiltInPolicies: looking up cached built-in policy definition %s: %w",
				JoinNameAndVersion(req.ResourceID.Name, req.Version),
				cacheErr,
			)
		}

		if pdv != nil {
			if err := az.AddPolicyDefinitions(pdv); err != nil {
				return fmt.Errorf(
					"Alzlib.getBuiltInPolicies: adding cached built-in policy definition %s: %w",
					JoinNameAndVersion(req.ResourceID.Name, req.Version),
					err,
				)
			}

			continue
		}

		// Fall back to Azure.
		az.mu.RLock()
		policyClient := az.clients.policyClient
		az.mu.RUnlock()

		if policyClient == nil {
			return errors.New("Alzlib.getBuiltInPolicies: policy client not set")
		}

		// Lazily initialise clients on first Azure call.
		if client == nil {
			versionedClient = policyClient.NewDefinitionVersionsClient()
			client = policyClient.NewDefinitionsClient()
		}

		var err error

		switch req.Version {
		case nil:
			err = az.addLatestPolicyDefinition(ctx, client, req)
		default:
			err = az.addVersionedPolicyDefinition(ctx, versionedClient, req)
		}

		if err != nil {
			return err
		}
	}

	return nil
}

// getBuiltInPolicySets retrieves the built-in policy set definitions with the given names
// and adds them to the AlzLib struct.
func (az *AlzLib) getBuiltInPolicySets(ctx context.Context, reqs []BuiltInRequest) error {
	processedRequests := make([]*assets.PolicySetDefinition, 0, len(reqs))

	var (
		versionedClient *armpolicy.SetDefinitionVersionsClient
		client          *armpolicy.SetDefinitionsClient
	)

	for _, req := range reqs {
		if az.PolicySetDefinitionExists(req.ResourceID.Name, req.Version) {
			continue
		}

		// Check cache before calling Azure.
		psdv, cacheErr := az.policySetDefinitionFromCache(req.ResourceID.Name, req.Version)
		if cacheErr != nil {
			return fmt.Errorf(
				"Alzlib.getBuiltInPolicySets: looking up cached built-in policy set definition %s: %w",
				req.String(),
				cacheErr,
			)
		}

		if psdv != nil {
			if err := az.AddPolicySetDefinitions(psdv); err != nil {
				return fmt.Errorf(
					"Alzlib.getBuiltInPolicySets: adding cached built-in policy set definition %s: %w",
					req.String(),
					err,
				)
			}

			processedRequests = append(processedRequests, psdv)

			continue
		}

		// Fall back to Azure.
		az.mu.RLock()
		policyClient := az.clients.policyClient
		az.mu.RUnlock()

		if policyClient == nil {
			return errors.New("Alzlib.getBuiltInPolicySets: policy client not set")
		}

		// Lazily initialise clients on first Azure call.
		if client == nil {
			versionedClient = policyClient.NewSetDefinitionVersionsClient()
			client = policyClient.NewSetDefinitionsClient()
		}

		var (
			psd *assets.PolicySetDefinition
			err error
		)

		switch req.Version {
		case nil:
			psd, err = az.addLatestPolicySetDefinition(ctx, client, req)
		default:
			psd, err = az.addVersionedPolicySetDefinition(ctx, versionedClient, req)
		}

		if err != nil {
			return err
		}

		processedRequests = append(processedRequests, psd)
	}

	return az.ensureReferencedPolicyDefinitions(ctx, processedRequests)
}

func (az *AlzLib) addLatestPolicyDefinition(
	ctx context.Context, client *armpolicy.DefinitionsClient, req BuiltInRequest,
) error {
	resp, err := client.GetBuiltIn(ctx, req.ResourceID.Name, nil)
	if err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicies: error getting built-in policy definition %s: %w",
			req.ResourceID.Name,
			err,
		)
	}

	pdv, err := assets.NewPolicyDefinitionValidate(resp.Definition)
	if err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicies: converting versionless built-in policy definition to versioned: %s: %w",
			req.ResourceID.Name,
			err,
		)
	}

	if err := az.AddPolicyDefinitions(pdv); err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicies: adding built-in policy definition %s: %w",
			req.ResourceID.Name,
			err,
		)
	}

	return nil
}

func (az *AlzLib) addVersionedPolicyDefinition(
	ctx context.Context,
	client *armpolicy.DefinitionVersionsClient,
	req BuiltInRequest,
) error {
	pager := client.NewListBuiltInPager(req.ResourceID.Name, nil)

	pdvs, err := az.collectPolicyDefinitionVersions(ctx, pager, req)
	if err != nil {
		return err
	}

	refVer, err := pdvs.GetVersion(req.Version)
	if err != nil || refVer == nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error getting specific version `%s` of built-in policy definition for `%s`: %w",
			*req.Version,
			req.ResourceID.Name,
			err,
		)
	}

	if err := az.AddPolicyDefinitions(refVer); err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicies: adding built-in policy definition %s: %w",
			JoinNameAndVersion(req.ResourceID.Name, req.Version),
			err,
		)
	}

	return nil
}

func (az *AlzLib) collectPolicyDefinitionVersions(
	ctx context.Context,
	pager policyDefinitionVersionsPager,
	req BuiltInRequest,
) (*assets.PolicyDefinitionVersions, error) {
	pdvs := assets.NewPolicyDefinitionVersions()

	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			return nil, fmt.Errorf(
				"Alzlib.getBuiltInPolicies: listing built-in policy definition versions for `%s`: %w",
				JoinNameAndVersion(req.ResourceID.Name, req.Version),
				err,
			)
		}

		for _, v := range page.Value {
			pdv, err := assets.NewPolicyDefinitionFromVersionValidate(*v)
			if err != nil {
				return nil, fmt.Errorf(
					"Alzlib.getBuiltInPolicySets: validating built-in policy definition version for `%s`: %w",
					JoinNameAndVersion(req.ResourceID.Name, req.Version),
					err,
				)
			}

			pdvs.Add(pdv, false) // nolint:errcheck
		}
	}

	return pdvs, nil
}

func (az *AlzLib) collectPolicySetDefinitionVersions(
	ctx context.Context,
	pager policySetDefinitionVersionsPager,
	req BuiltInRequest,
) (*assets.PolicySetDefinitionVersions, error) {
	psdvs := assets.NewPolicySetDefinitionVersions()

	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			return nil, fmt.Errorf(
				"Alzlib.getBuiltInPolicySets: listing built-in policy set definition versions for `%s`: %w",
				JoinNameAndVersion(req.ResourceID.Name, req.Version),
				err,
			)
		}

		for _, v := range page.Value {
			psd, err := assets.NewPolicySetDefinitionFromVersionValidate(*v)
			if err != nil {
				return nil, fmt.Errorf(
					"Alzlib.getBuiltInPolicySets: validating built-in policy set definition version for `%s`: %w",
					JoinNameAndVersion(req.ResourceID.Name, req.Version),
					err,
				)
			}

			psdvs.Add(psd, false) // nolint:errcheck
		}
	}

	return psdvs, nil
}

func (az *AlzLib) addLatestPolicySetDefinition(
	ctx context.Context,
	client *armpolicy.SetDefinitionsClient,
	req BuiltInRequest,
) (*assets.PolicySetDefinition, error) {
	resp, err := client.GetBuiltIn(ctx, req.ResourceID.Name, nil)
	if err != nil {
		return nil, fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error getting built-in policy set definition %s: %w",
			req.ResourceID.Name,
			err,
		)
	}

	psdv, err := assets.NewPolicySetDefinitionValidate(resp.SetDefinition)
	if err != nil {
		return nil, fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error converting versionless built-in policy set definition to versioned: %s: %w",
			req.ResourceID.Name,
			err,
		)
	}

	if err := az.AddPolicySetDefinitions(psdv); err != nil {
		return nil, fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error adding built-in policy set definition %s: %w",
			req.ResourceID.Name,
			err,
		)
	}

	return psdv, nil
}

func (az *AlzLib) addVersionedPolicySetDefinition(
	ctx context.Context,
	client *armpolicy.SetDefinitionVersionsClient,
	req BuiltInRequest,
) (*assets.PolicySetDefinition, error) {
	pager := client.NewListBuiltInPager(req.ResourceID.Name, nil)

	psdvs, err := az.collectPolicySetDefinitionVersions(ctx, pager, req)
	if err != nil {
		return nil, err
	}

	refVer, err := psdvs.GetVersion(req.Version)
	if err != nil || refVer == nil {
		return nil, fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error getting specific version `%s` of built-in policy set definition for `%s`: %w",
			*req.Version,
			req.ResourceID.Name,
			err,
		)
	}

	if err := az.AddPolicySetDefinitions(refVer); err != nil {
		return nil, fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error adding built-in policy set definition %s: %w",
			req.String(),
			err,
		)
	}

	return refVer, nil
}

func (az *AlzLib) ensureReferencedPolicyDefinitions(
	ctx context.Context,
	processedRequests []*assets.PolicySetDefinition,
) error {
	if len(processedRequests) == 0 {
		return nil
	}

	// Lazily initialised Azure clients, shared across all references within this invocation.
	var (
		definitionsClient          *armpolicy.DefinitionsClient
		definitionsVersionedClient *armpolicy.DefinitionVersionsClient
	)

	for _, def := range processedRequests {
		for _, ref := range def.Properties.PolicyDefinitions {
			err := az.ensureReferencedPolicyDefinition(
				ctx,
				def,
				ref,
				&definitionsClient,
				&definitionsVersionedClient,
			)
			if err != nil {
				return err
			}
		}
	}

	return nil
}

func (az *AlzLib) ensureReferencedPolicyDefinition(
	ctx context.Context,
	setDefinition *assets.PolicySetDefinition,
	ref *armpolicy.DefinitionReference,
	definitionsClient **armpolicy.DefinitionsClient,
	definitionsVersionedClient **armpolicy.DefinitionVersionsClient,
) error {
	if ref == nil {
		return nil
	}

	if ref.PolicyDefinitionID == nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error getting policy definition references for policy set definition `%s`: "+
				"policy definition ID is nil",
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
		)
	}

	resID, err := arm.ParseResourceID(*ref.PolicyDefinitionID)
	if err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: error parsing resource id `%s` referenced in policy set `%s`",
			*ref.PolicyDefinitionID,
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
		)
	}

	// Check AlzLib first to avoid redundant work.
	if az.PolicyDefinitionExists(resID.Name, ref.DefinitionVersion) {
		return nil
	}

	// Check cache before calling Azure.
	pdv, cacheErr := az.policyDefinitionFromCache(resID.Name, ref.DefinitionVersion)
	if cacheErr != nil {
		return fmt.Errorf(
			"Alzlib.ensureReferencedPolicyDefinition: looking up cached built-in policy definition `%s` "+
				"referenced in policy set `%s`: %w",
			JoinNameAndVersion(resID.Name, ref.DefinitionVersion),
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
			cacheErr,
		)
	}

	if pdv != nil {
		if err := az.AddPolicyDefinitions(pdv); err != nil {
			return fmt.Errorf(
				"Alzlib.ensureReferencedPolicyDefinition: adding cached built-in policy definition `%s` "+
					"referenced in policy set `%s`: %w",
				JoinNameAndVersion(resID.Name, ref.DefinitionVersion),
				JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
				err,
			)
		}

		return nil
	}

	// Fall back to Azure.
	az.mu.RLock()
	policyClient := az.clients.policyClient
	az.mu.RUnlock()

	if policyClient == nil {
		return errors.New("Alzlib.ensureReferencedPolicyDefinition: policy client not set")
	}

	if ref.DefinitionVersion != nil {
		if *definitionsVersionedClient == nil {
			*definitionsVersionedClient = policyClient.NewDefinitionVersionsClient()
		}

		return az.fetchReferencedPolicyDefinitionVersions(ctx, *definitionsVersionedClient, resID.Name, setDefinition, ref)
	}

	if *definitionsClient == nil {
		*definitionsClient = policyClient.NewDefinitionsClient()
	}

	return az.fetchLatestReferencedPolicyDefinition(
		ctx, *definitionsClient, resID.Name, setDefinition, ref.DefinitionVersion,
	)
}

func (az *AlzLib) fetchReferencedPolicyDefinitionVersions(
	ctx context.Context,
	client *armpolicy.DefinitionVersionsClient,
	definitionName string,
	setDefinition *assets.PolicySetDefinition,
	ref *armpolicy.DefinitionReference,
) error {
	pager := client.NewListBuiltInPager(definitionName, nil)

	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			return fmt.Errorf(
				"Alzlib.getBuiltInPolicySets: error listing built-in policy definition versions for "+
					"`%s`, referenced in policy set `%s`: %w",
				definitionName,
				JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
				err,
			)
		}

		for _, v := range page.Value {
			pdv, err := assets.NewPolicyDefinitionFromVersionValidate(*v)
			if err != nil {
				return fmt.Errorf(
					"Alzlib.getBuiltInPolicySets: error validating built-in policy definition version for "+
						"`%s`, referenced in policy set `%s`: %w",
					definitionName,
					JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
					err,
				)
			}

			az.AddPolicyDefinitions(pdv) // nolint:errcheck
		}
	}

	if !az.PolicyDefinitionExists(definitionName, ref.DefinitionVersion) {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: finding specific version constraint `%s` of built-in policy definition "+
				"for `%s`, referenced in policy set `%s`. Versions available: %v",
			*ref.DefinitionVersion,
			definitionName,
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
			az.policyDefinitions[definitionName].Versions(),
		)
	}

	return nil
}

func (az *AlzLib) fetchLatestReferencedPolicyDefinition(
	ctx context.Context,
	client *armpolicy.DefinitionsClient,
	definitionName string,
	setDefinition *assets.PolicySetDefinition,
	desiredVersion *string,
) error {
	pd, err := client.GetBuiltIn(ctx, definitionName, nil)
	if err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: getting versionless built-in policy definition %s, referenced in policy set `%s`: %w",
			definitionName,
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
			err,
		)
	}

	pdvLatest, err := assets.NewPolicyDefinitionValidate(pd.Definition)
	if err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: validating versionless built-in policy definition %s, "+
				"referenced in policy set `%s`: %w",
			definitionName,
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
			err,
		)
	}

	if err := az.AddPolicyDefinitions(pdvLatest); err != nil {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: adding versionless built-in policy definition %s, referenced in policy set `%s`: %w",
			definitionName,
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
			err,
		)
	}

	if !az.PolicyDefinitionExists(definitionName, desiredVersion) {
		return fmt.Errorf(
			"Alzlib.getBuiltInPolicySets: finding versionless built-in policy definition "+
				"for `%s`, referenced in policy set `%s`",
			definitionName,
			JoinNameAndVersion(*setDefinition.Name, setDefinition.Properties.Version),
		)
	}

	return nil
}

// addPolicyAndRoleAssets adds the results of a processed library to the AlzLib.
func (az *AlzLib) addPolicyAndRoleAssets(res *processor.Result) error {
	var merr error

	for k, v := range res.PolicyDefinitions {
		if pdv, exists := az.policyDefinitions[k]; exists {
			if err := v.Upsert(pdv, az.Options.AllowOverwrite); err != nil {
				merr = multierror.Append(merr, fmt.Errorf("policy definition %s: %w", k, err))
			}

			continue
		}

		az.policyDefinitions[k] = v
	}

	if merr != nil {
		return fmt.Errorf("Alzlib.addProcessedResult: error adding policy definition versions: %w", merr)
	}

	merr = nil

	for k, v := range res.PolicySetDefinitions {
		if psdv, exists := az.policySetDefinitions[k]; exists {
			if err := v.Upsert(psdv, az.Options.AllowOverwrite); err != nil {
				merr = multierror.Append(merr, fmt.Errorf("policy set definition %s: %w", k, err))
			}

			continue
		}

		az.policySetDefinitions[k] = v
	}

	if merr != nil {
		return fmt.Errorf("Alzlib.addProcessedResult: error adding policy set definition versions: %w", merr)
	}

	for k, v := range res.PolicyAssignments {
		if _, exists := az.policyAssignments[k]; exists && !az.Options.AllowOverwrite {
			return fmt.Errorf(
				"Alzlib.addProcessedResult: policy assignment %s already exists in the library",
				k,
			)
		}

		az.policyAssignments[k] = v
	}

	for k, v := range res.RoleDefinitions {
		if _, exists := az.roleDefinitions[k]; exists && !az.Options.AllowOverwrite {
			return fmt.Errorf(
				"Alzlib.addProcessedResult: role definition %s already exists in the library",
				k,
			)
		}

		az.roleDefinitions[k] = v
	}

	return nil
}

func (az *AlzLib) addDefaultPolicyAssignmentValues(res *processor.Result) error {
	for defName, def := range res.LibDefaultPolicyValues {
		if _, exists := az.defaultPolicyAssignmentValues[defName]; exists {
			if !az.Options.AllowOverwrite {
				return fmt.Errorf(
					"Alzlib.addDefaultPolicyValues: default name %s already exists in the defaults",
					defName,
				)
			}

			delete(az.defaultPolicyAssignmentValues, defName)
		}

		for _, assignment := range def.PolicyAssignments {
			for _, param := range assignment.ParameterNames {
				if az.defaultPolicyAssignmentValues.AssignmentParameterComboExists(
					assignment.PolicyAssignmentName,
					param,
				) {
					return fmt.Errorf(
						"Alzlib.addDefaultPolicyValues: error processing default policy values for default name: `%s`, "+
							"assignment `%s` and parameter `%s` already exists in defaults",
						defName,
						assignment.PolicyAssignmentName,
						param,
					)
				}
			}

			az.defaultPolicyAssignmentValues.Add(
				defName,
				assignment.PolicyAssignmentName,
				def.Description,
				assignment.ParameterNames...)
		}
	}

	return nil
}

// generateArchetypes generates the archetypes from the result of the processor.
// The archetypes are stored in the AlzLib instance.
func (az *AlzLib) generateArchetypes(res *processor.Result) error {
	// add empty archetype if it doesn't exist.
	if _, exists := az.archetypes["empty"]; !exists {
		if _, exists := res.LibArchetypes["empty"]; !exists {
			res.LibArchetypes["empty"] = &processor.LibArchetype{
				Name:                 "empty",
				PolicyAssignments:    mapset.NewThreadUnsafeSet[string](),
				PolicyDefinitions:    mapset.NewThreadUnsafeSet[string](),
				PolicySetDefinitions: mapset.NewThreadUnsafeSet[string](),
				RoleDefinitions:      mapset.NewThreadUnsafeSet[string](),
			}
		}
	}

	// generate alzlib archetypes.
	for k, v := range res.LibArchetypes {
		if _, exists := az.archetypes[k]; exists && !az.Options.AllowOverwrite {
			return fmt.Errorf(
				"Alzlib.generateArchetypes: archetype %s already exists in the library",
				v.Name,
			)
		}

		arch := NewArchetype(v.Name)

		for pd := range v.PolicyDefinitions.Iter() {
			if _, ok := az.policyDefinitions[pd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateArchetypes: error processing archetype %s, policy definition %s does not exist in the library",
					k,
					pd,
				)
			}

			arch.PolicyDefinitions.Add(pd)
		}

		for psd := range v.PolicySetDefinitions.Iter() {
			if _, ok := az.policySetDefinitions[psd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateArchetypes: error processing archetype %s, policy set definition %s does not exist in the library",
					k,
					psd,
				)
			}

			arch.PolicySetDefinitions.Add(psd)
		}

		for pa := range v.PolicyAssignments.Iter() {
			if _, ok := az.policyAssignments[pa]; !ok {
				return fmt.Errorf(
					"Alzlib.generateArchetypes: error processing archetype %s, policy assignment %s does not exist in the library",
					k,
					pa,
				)
			}

			arch.PolicyAssignments.Add(pa)
		}

		for rd := range v.RoleDefinitions.Iter() {
			if _, ok := az.roleDefinitions[rd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateArchetypes: error processing archetype %s, role definition %s does not exist in the library",
					k,
					rd,
				)
			}

			arch.RoleDefinitions.Add(rd)
		}

		az.archetypes[v.Name] = arch
	}

	return nil
}

// generateOverrideArchetypes generates the override archetypes from the result of the processor.
// THis must be run after generateArchetypes.
func (az *AlzLib) generateOverrideArchetypes(res *processor.Result) error {
	for name, ovr := range res.LibArchetypeOverrides {
		if _, exists := az.archetypes[name]; exists {
			return fmt.Errorf(
				"Alzlib.generateOverrideArchetypes: error processing override archetype `%s` - it already exists in the library",
				name,
			)
		}

		base, exists := az.archetypes[ovr.BaseArchetype]
		if !exists {
			return fmt.Errorf(
				"Alzlib.generateOverrideArchetypes: error processing override archetype `%s` - "+
					"base archetype `%s` does not exist in the library",
				name,
				ovr.BaseArchetype,
			)
		}

		for pa := range ovr.PolicyAssignmentsToAdd.Iter() {
			if _, ok := az.policyAssignments[pa]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"policy assignment `%s` does not exist in the library",
					name,
					pa,
				)
			}
		}

		for pa := range ovr.PolicyAssignmentsToRemove.Iter() {
			if _, ok := az.policyAssignments[pa]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"policy assignment `%s` does not exist in the library",
					name,
					pa,
				)
			}
		}

		for pd := range ovr.PolicyDefinitionsToAdd.Iter() {
			if _, ok := az.policyDefinitions[pd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"policy definition `%s` does not exist in the library",
					name,
					pd,
				)
			}
		}

		for pd := range ovr.PolicyDefinitionsToRemove.Iter() {
			if _, ok := az.policyDefinitions[pd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"policy definition `%s` does not exist in the library",
					name,
					pd,
				)
			}
		}

		for psd := range ovr.PolicySetDefinitionsToAdd.Iter() {
			if _, ok := az.policySetDefinitions[psd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"policy set definition `%s` does not exist in the library",
					name,
					psd,
				)
			}
		}

		for psd := range ovr.PolicySetDefinitionsToRemove.Iter() {
			if _, ok := az.policySetDefinitions[psd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"policy set definition `%s` does not exist in the library",
					name,
					psd,
				)
			}
		}

		for rd := range ovr.RoleDefinitionsToAdd.Iter() {
			if _, ok := az.roleDefinitions[rd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"role definition `%s` does not exist in the library",
					name,
					rd,
				)
			}
		}

		for rd := range ovr.RoleDefinitionsToRemove.Iter() {
			if _, ok := az.roleDefinitions[rd]; !ok {
				return fmt.Errorf(
					"Alzlib.generateOverrideArchetypes: error processing override archetype `%s`, "+
						"role definition `%s` does not exist in the library",
					name,
					rd,
				)
			}
		}

		newArch := &Archetype{
			PolicyDefinitions: base.PolicyDefinitions.Clone().
				Union(ovr.PolicyDefinitionsToAdd).
				Difference(ovr.PolicyDefinitionsToRemove),
			PolicySetDefinitions: base.PolicySetDefinitions.Clone().
				Union(ovr.PolicySetDefinitionsToAdd).
				Difference(ovr.PolicySetDefinitionsToRemove),
			PolicyAssignments: base.PolicyAssignments.Clone().
				Union(ovr.PolicyAssignmentsToAdd).
				Difference(ovr.PolicyAssignmentsToRemove),
			RoleDefinitions: base.RoleDefinitions.Clone().
				Union(ovr.RoleDefinitionsToAdd).
				Difference(ovr.RoleDefinitionsToRemove),
			name: name,
		}
		az.archetypes[name] = newArch
	}

	return nil
}

func (az *AlzLib) generateArchitectures(res *processor.Result) error {
	for name, libArch := range res.LibArchitectures {
		if _, exists := az.architectures[name]; exists && !az.Options.AllowOverwrite {
			return fmt.Errorf(
				"Alzlib.generateArchitectures: error processing architecture %s - it already exists in the library",
				name,
			)
		}

		validParents := mapset.NewThreadUnsafeSet[string]()
		for _, mg := range libArch.ManagementGroups {
			validParents.Add(mg.ID)
		}

		for _, mg := range libArch.ManagementGroups {
			if mg.ParentID != nil && !validParents.Contains(*mg.ParentID) {
				return fmt.Errorf(
					"Alzlib.generateArchitectures: error processing architecture %s - management group %s has invalid parent %s",
					name,
					mg.ID,
					*mg.ParentID,
				)
			}
		}

		arch := NewArchitecture(name, az)
		if err := architectureRecursion(nil, libArch, arch, az, 0); err != nil {
			return fmt.Errorf(
				"Alzlib.generateArchitectures: error processing architecture %s: %w",
				name,
				err,
			)
		}

		az.architectures[name] = arch
	}

	return nil
}

// architectureRecursion is a recursive function to build the architecture from the definitions read
// by the processor.
func architectureRecursion(
	parents mapset.Set[string],
	libArch *processor.LibArchitecture,
	arch *Architecture,
	az *AlzLib,
	depth int,
) error {
	if depth > MaxRecursionDepth {
		return errors.New("architectureRecursion: recursion depth exceeded")
	}

	newParents := mapset.NewThreadUnsafeSet[string]()

	if len(libArch.ManagementGroups) == 0 {
		return errors.New("architectureRecursion: no management groups found")
	}

	for _, mg := range libArch.ManagementGroups {
		switch {
		case depth == 0 && mg.ParentID == nil:
			if err := arch.addMgFromProcessor(mg, az); err != nil {
				return fmt.Errorf("architectureRecursion: error adding management group %s: %w", mg.ID, err)
			}
		case depth > 0 && mg.ParentID != nil:
			if parents == nil {
				return errors.New("architectureRecursion: depth > 1 and parents set to nil")
			}

			if !parents.Contains(*mg.ParentID) {
				continue
			}

			if !arch.mgs[*mg.ParentID].exists && mg.Exists {
				return fmt.Errorf(
					"architectureRecursion: error adding management group %s, which is configured as existing "+
						"but the parent management group %s does not exist and would be created",
					mg.ID,
					*mg.ParentID,
				)
			}

			if err := arch.addMgFromProcessor(mg, az); err != nil {
				return fmt.Errorf("architectureRecursion: error adding management group %s: %w", mg.ID, err)
			}
		default:
			continue
		}

		newParents.Add(mg.ID)
	}

	if newParents.Cardinality() > 0 {
		return architectureRecursion(newParents, libArch, arch, az, depth+1)
	}

	return nil
}