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)

	// Resolve is a target-agnostic resolver function for the abstract
	// resource type. This is auto-registered by the framework against
	// this definition's Type when the parent TransformerPluginDefinition is
	// first used.
	Resolve transformutils.Resolver

	// PropertyMaps registers declarative property maps per target.
	// PropertyMaps are consumed in two places:
	//   - The capability matrix is auto-derived from each map (the
	//     SupportedAbstractPaths set is the union of Renames keys,
	//     ValueRefs keys, and Custom rule MatchPaths).
	//   - transformutils.RewriterFromPropertyMap converts a map plus a
	//     concrete-naming function into a RewriterRegistration suitable
	//     for the Rewriters field below.
	// PropertyMaps alone do not produce a rewriter — concrete naming is
	// per-target and must be supplied via RewriterFromPropertyMap (or a
	// hand-written TypedRewriter factory).
	PropertyMaps map[string]transformutils.PropertyMap

	// Emitters registers per-target emit functions.
	// Each value is expected to be a typed-emitter registration function
	// produced by transformutils.TypedEmitter[T] to enable your emitter functions
	// to be written with concrete resolved types while maintaining type safety
	// in the registry.
	Emitters map[string]transformutils.EmitterRegistration

	// Rewriters registers per-target rewriter factories.
	// Each value is a RewriterRegistration produced by either:
	//   - transformutils.RewriterFromPropertyMap[T] — when rewriting is
	//     fully described by a PropertyMap plus a per-target concrete
	//     name. This is the typical path.
	//   - transformutils.TypedRewriter[T] — when you need a hand-written
	//     factory, e.g. compound primaries or multi-rewriter contributions.
	// A target with no Rewriters entry will not have any rewriter
	// registered for that target — a PropertyMap on its own does not
	// auto-register.
	Rewriters map[string]transformutils.RewriterRegistration
}

type TransformFunc func(
	ctx context.Context,
	input *transform.SpecTransformerTransformInput,
) (*transform.SpecTransformerTransformOutput, 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]*AbstractResourceDefinition

	// 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 utilise the built-in transform pipeline using aggregators
	// defined for the transform plugin and resolve, property maps, emitters
	// and rewriters defined in abstract resources.
	TransformFunc TransformFunc

	// Aggregators registers per-target aggregators for transformer plugins
	// using the built-in transform pipeline.
	// The key is a deployment target identifier (e.g. "aws-serverless").
	// Don't set this if you are implementing your own TransformFunc.
	Aggregators map[string]transformutils.Aggregator

	// Registry holds advanced registrations that don't fit into any of the
	// abstract resource definitions (most commonly compound resolved types
	// that combine abstract resources).
	// The framework merges this with the registry auto-derived from
	// abstract resources and aggregators at first transform invocation.
	// Collisions between auto-derived and explicit registrations will cause a panic.
	// Don't set this if you are implementing your own TransformFunc.
	Registry *transformutils.TransformerRegistry

	// DeployTargetConfigKey allows plugins to specify the config key name
	// from which the deploy target is read in the default Transform implementation.
	// If not set, defaults to "deployTarget" based on the convention established
	// for the Celerity transformer plugin.
	// This is expected to be in the context variables passed into a deploy engine action.
	DeployTargetConfigKey string
	// contains filtered or unexported fields
}