transformerv1

type AbstractLinkDefinition struct {
	// The type of the source abstract resource in the link relationship.
	// (e.g. "celerity/api").
	ResourceTypeA string

	// The type of the destination abstract resource in the link relationship.
	// (e.g. "celerity/handler").
	ResourceTypeB string

	// A summary of the link type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextSummary string

	// A summary of the link type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedSummary string

	// A description of the link type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextDescription string

	// A description of the link type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedDescription string

	// A mapping of annotation names prefixed by resource type that
	// can be used to fine tune the behaviour of a link in a blueprint spec.
	// The format should be as follows:
	// {resourceType}::{annotationName} -> LinkAnnotationDefinition
	// e.g. "celerity/handler::celerity.handler.http.method" -> LinkAnnotationDefinition
	AnnotationDefinitions map[string]*provider.LinkAnnotationDefinition

	// CardinalityA: how many B's each A may link to.
	//   Example: celerity/handler → celerity/api, CardinalityA = {Min: 0, Max: 1}
	//     means a handler may link to at most one api.
	CardinalityA provider.LinkCardinality

	// CardinalityB: how many A's may link to each B.
	//   Example: celerity/api ← celerity/handler, CardinalityB = {Min: 1, Max: 0}
	//     means every api must have at least one handler linking to it
	//     (Max: 0 = unlimited).
	CardinalityB provider.LinkCardinality

	// Custom validation function for constraints that can't be expressed declaratively.
	// Called once per resolved edge matching this definition. Runs after
	// the declarative checks; additional diagnostics are concatenated.
	ValidateFunc func(
		ctx context.Context,
		input *AbstractLinkValidateInput,
	) (*AbstractLinkValidateOutput, error)
}

type AbstractLinkValidateInput struct {
	Edge               *linktypes.ResolvedLink
	LinkGraph          linktypes.DeclaredLinkGraph
	TransformerContext transform.Context
}

type AbstractLinkValidateOutput struct {
	Diagnostics []*core.Diagnostic
}

type AbstractResourceDefinition struct {
	// The type of the abstract resource.
	// Example: "celerity/handler".
	Type string

	// A human-readable label for the abstract resource type.
	// This will be used in documentation and tooling.
	Label string

	// A summary of the abstract resource type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextSummary string

	// A summary of the abstract resource type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedSummary string

	// A description of the abstract resource type that is not formatted that can be used
	// to render descriptions in contexts that formatting is not supported.
	// This will be used in documentation and tooling.
	PlainTextDescription string

	// A description of the abstract resource type that can be formatted using markdown.
	// This will be used in documentation and tooling.
	FormattedDescription string

	// A list of plain text examples that can be used to
	// demonstrate how to use the abstract resource.
	// This will be used in documentation and tooling.
	PlainTextExamples []string

	// A list of markdown examples that can be used to
	// demonstrate how to use the abstract resource.
	// This will be used in documentation and tooling.
	FormattedExamples []string

	// The schema of the abstract resource specification that comes under the `spec` field
	// of a resource in a blueprint.
	Schema *provider.ResourceDefinitionsSchema

	// Holds the name of the field in the abstract resource schema
	// that holds the third-party
	// ID of the abstract resource.
	// This is used to resolve references to a resource in a blueprint
	// where only the name of the resource is specified.
	// For example, references such as `resources.processOrderHandler` or
	// `processOrderHandler` should resolve to the ID of the resource in the blueprint.
	// The ID field must be a top-level property of the resource spec schema.
	//
	// For abstract resources, this should point to an underlying ID value
	// in the primary concrete resource that the abstract resource expands to.
	IDField string

	// Specifies whether this abstract resource is expected to have a common use-case
	// as a terminal resource that does not link out to other resources.
	// This is useful for providing useful warnings to users about their blueprints
	// without overloading them with warnings for all resources that don't have any outbound
	// links that could have.
	// If CommonTerminalFunc is provided, this static value will not be used.
	CommonTerminal bool

	// A function that can be used to dynamically determine whether an abstract resource is likely
	// to be a common terminal resource (does not link out to other resources).
	CommonTerminalFunc func(
		ctx context.Context,
		input *transform.AbstractResourceIsCommonTerminalInput,
	) (*transform.AbstractResourceIsCommonTerminalOutput, error)

	// A function to apply custom validation for an abstract resource
	// that goes beyond validating against the resource spec schema which
	// the blueprint framework takes care of.
	// When not provided, the plugin will return a result with an empty list
	// of diagnostics.
	CustomValidateFunc func(
		ctx context.Context,
		input *transform.AbstractResourceValidateInput,
	) (*transform.AbstractResourceValidateOutput, error)
}

type TransformerPluginDefinition struct {

	// The transform name string that is to be used in the
	// `transform` field of a blueprint.
	TransformName string

	// Configuration definition for the transformer plugin.
	TransformerConfigDefinition *core.ConfigDefinition

	// A mapping of asbtract resource types to their
	// implementations.
	AbstractResources map[string]transform.AbstractResource

	// A set of link definitions between abstract resource types
	// owned by this transformer. Each entry is keyed by
	// "{ResourceTypeA}::{ResourceTypeB}" for fast edge-class lookup.
	// (e.g. "celerity/handler::celerity/api")
	AbstractLinks map[string]*AbstractLinkDefinition

	// A function to transform a blueprint.
	// If this function is not set, the default implementation
	// will return the input blueprint as the transformed blueprint.
	TransformFunc func(
		ctx context.Context,
		input *transform.SpecTransformerTransformInput,
	) (*transform.SpecTransformerTransformOutput, error)
}