schema: Revisit `LiteralType`.`SkipComplexTypes` workaround

[radeksimko]

Context

As part of #232 in order to avoid duplicate completion we decided to introduce two "toggle" fields, such that we can nest and reuse LiteralType and AnyExpression constraints without those negative side effects.

hcl-lang/schema/constraint_any_expression.go

Lines 21 to 23 in 9c3a246

	// SkipLiteralComplexTypes avoids descending into complex literal types, such as {} and [].
	// It might be required when AnyExpression is used in OneOf to avoid duplicates.
	SkipLiteralComplexTypes bool

hcl-lang/schema/constraint_literal_type.go

Lines 29 to 31 in 9c3a246

	// SkipComplexTypes avoids descending into complex literal types, such as {} and [].
	// It might be required when LiteralType is used in OneOf to avoid duplicates.
	SkipComplexTypes bool

We implemented this as the easiest way of addressing the problem as we were nearing the planned release date.

However, this introduced new API surface which should ideally in practice remain an implementation detail. i.e. a schema author shouldn't have to be concerned about this detail and should have some easier way of expressing e.g. "list or any expression evaluating to list" and similar constraints.

i.e. this does not make for the most readable code

Constraint: schema.OneOf{
	schema.AnyExpression{OfType: cty.Map(cty.String), SkipLiteralComplexTypes: true},
	schema.Map{
		Elem: schema.AnyExpression{OfType: cty.String},
	},
},

Notes

One additional complexity to consider is that there's certain metadata in complex types which we should be surfacing somewhere, esp. in completion and hover and this metadata often applies not just to the literal expression but to any expression which - when evaluated - complies with the constraint.

For example:

• List/Set - Description, MinItems, MaxItems
• Tuple - Description
• Map - Description, Name, MinItems, MaxItems
• Object - Description, Name

This suggests that we could re-implement this such that e.g. schema.Map complies with any interpretation of a map (including references or function calls), and leave AnyExpression only for situations where the extra metadata isn't needed.

Proposal

• Explore other ways the same constraint could be expressed in the schema
• Look at other products (other than Terraform) to understand their needs in this area