foreign

type AttrMatch struct {
	Attr  string
	Value string
}

type Candidate struct {
	Resource

	// Addr is the declared instance it matches.
	Addr addrs.AbsResourceInstance

	// Matched are the identity-bearing arguments that matched, with the
	// value both sides agreed on, in argument order. This is the whole
	// evidence for the offer: an operator has to be able to see what the
	// match was made on before acting on it.
	Matched []AttrMatch

	// MarkerEstate and MarkerAddress are the two tag values that would
	// adopt this resource: tofu-estate and tofu-address, the latter already
	// escaped per live/MARKERS.md.
	MarkerEstate  string
	MarkerAddress string

	// Hint is a one-line command that stamps those two tags, for the
	// resource types whose adoption command this package knows. It is empty
	// for a type it does not, and the marker pair above is the contract
	// either way: any tool that writes those two tags adopts the resource.
	Hint string
}

type Class string

type EstateCount struct {
	// Estate is the other estate's name, or empty when the count came from
	// discovery's per-type tally, which records that a resource belonged to
	// some other estate without recording which. A count with no name is
	// still worth printing: it says another estate shares this account.
	Estate string

	// Count is the number of live resources.
	Count int

	// Types are the resource types they were listed as, sorted.
	Types []string
}

type Lookalike struct {
	// Addr is the declared instance the plan proposes to create.
	Addr addrs.AbsResourceInstance

	// TypeName is its resource type.
	TypeName string

	// LiveID is the unowned live resource's identity, the handle an operator
	// needs to go look at it. Empty when the provider sent no usable
	// identity, the same case [Resource.LiveID] covers.
	LiveID string

	// DisplayName is the provider's label for it, when it differs from
	// LiveID.
	DisplayName string

	// Matched are the identity-bearing arguments the live resource and the
	// declared instance agreed on exactly - the same evidence a
	// [Candidate] carries. Empty for the generic, no-[matchTable]-entry
	// case: there, nothing in configuration confirmed the match, only
	// cardinality did, and pretending otherwise would overstate the
	// evidence.
	Matched []AttrMatch

	// MarkerEstate and MarkerAddress are the tofu-estate and tofu-address
	// values that adopt the live resource instead of creating a duplicate
	// beside it.
	MarkerEstate  string
	MarkerAddress string

	// Hint is the one-line adoption command composed by the same machinery
	// [Candidate.Hint] uses, empty for a type this fork has no composable
	// tagging verb for.
	Hint string
}

type ParentReadFinding struct {
	// TypeName is the child's resource type.
	TypeName string

	// Parent is the admitted type whose identity led this pass to it.
	Parent string

	// ParentAddr is the parent's own resolved address in this estate.
	ParentAddr addrs.AbsResourceInstance

	// ParentValue is the parent identity value the read was scoped to, and
	// also the child's own whole identity for this shape.
	ParentValue string

	// LiveID is the child's live identity as the read found it.
	LiveID string

	// DisplayName is the provider's label for it. Display only.
	DisplayName string

	// Removal is true when this finding also entered the prior state as a
	// destroy; the plan's own resource diff carries the destroy itself, and
	// this is what says a parent read is the reason it could be proposed.
	Removal bool

	// Withheld is why Removal is false, empty when Removal is true.
	Withheld string
}

type Removal struct {
	Resource

	// Addr is the address its marker names, unescaped: where it sits in the
	// prior state, and the address the plan's destroy line prints.
	Addr addrs.AbsResourceInstance

	// Marker is the tofu-address tag value as carried, and Normalized its
	// escaped form.
	Marker     string
	Normalized string

	// BlockGone is true when the whole resource block is missing from the
	// configuration, as opposed to the block still existing and no longer
	// expanding to this instance key. The two are the same operation to the
	// cloud and different sentences to an operator.
	BlockGone bool

	// Swept is true when the estate-wide sweep found it rather than a scan
	// of a type the configuration declares. It is exactly the case that was
	// invisible before removal exactness landed.
	Swept bool
}

type RenameAmbiguity struct {
	// Block is the resource block, and TypeName its resource type.
	Block    string
	TypeName string

	// Live are the orphaned live resources of that block.
	Live []RenameLive

	// Declared are the addresses of its unclaimed declared instances,
	// sorted.
	Declared []string

	// Detail is one sentence saying what the obstacle is.
	Detail string
}

type RenameCandidate struct {
	Resource

	// Block is the resource block both sides belong to, which is the whole
	// basis of the pairing.
	Block string

	// Old is the address the live marker claims, unescaped: the address to
	// rename from.
	Old addrs.AbsResourceInstance

	// New is the declared instance nothing claimed: the address to rename to.
	New addrs.AbsResourceInstance

	// Marker is the tofu-address tag value exactly as the live resource
	// carries it, and Normalized is its escaped form - the string the block
	// match was made on.
	Marker     string
	Normalized string

	// MatchedOn are the identity-bearing arguments the live resource and the
	// block's configuration agreed on, when there were any. It is empty for
	// the ordinary pairing, which the block match alone decides; it is the
	// evidence when content is what resolved an ambiguity.
	MatchedOn []AttrMatch

	// Command is the exact, shell-quoted live-mv invocation that
	// rewrites the marker. Running it is the entire rename; nothing else has
	// to happen and no state is touched.
	Command string
}

type RenameLive struct {
	LiveID      string
	DisplayName string

	// Marker is the escaped tofu-address value it carries.
	Marker string
}

type Request struct {
	// Estate is the estate whose ownership boundary this classification is
	// drawn around. A live resource carrying this value in its tofu-estate
	// tag is owned and never reaches this package.
	Estate string

	// Config is the configuration the discovery pass ran against, which is
	// where the declared instances and their identity-bearing arguments are
	// read from.
	Config *configs.Config

	// Discovery is the result of one discovery pass. It must have been
	// gathered with [discovery.Request.CollectUnclaimed] set, or there is
	// nothing to classify - and the scan rows will say so, which is what
	// [Result.Unswept] reports.
	Discovery *discovery.Result

	// Region is the region the discovery pass listed in, as the provider
	// configuration knows it - the same value handed to
	// [discovery.Request.Region]. It travels into the adoption hint as a
	// --region flag, so that the printed command talks to the same region
	// the resource was found in rather than whatever the operator's CLI
	// profile defaults to. Empty leaves the flag off the hint.
	Region string

	// EndpointURL is the custom endpoint the provider configuration reaches
	// the cloud through, when one is configured - a LocalStack-style
	// emulator, a VPC endpoint. It travels into the adoption hint as an
	// --endpoint-url flag for the same reason Region does. Empty leaves the
	// flag off the hint.
	EndpointURL string
}

type Resource struct {
	// TypeName is the resource type it was listed as.
	TypeName string

	// LiveID is the identity the provider serves for it, which is what an
	// operator needs to find it in a console or a CLI. Empty when the
	// provider sent no usable identity.
	LiveID string

	// DisplayName is the provider's label for it. Display only.
	DisplayName string

	// Tags is the resource's whole tag set, sorted by key. It is the
	// evidence for the classification: an operator reading a foreign line
	// wants to see that no tofu-estate is there, and usually recognizes the
	// resource from whatever tags it does carry.
	Tags []Tag

	// Why is one sentence saying why this resource is in the class it is in
	// - for a foreign resource, why it is not a bind candidate.
	Why string
}

type Result struct {
	// Estate is the estate the classification was made against.
	Estate string

	// Foreign lists the unclaimed live resources that belong to nobody, in
	// type and live-ID order. Every one of them is report-only.
	Foreign []Resource

	// Candidates lists the unclaimed live resources that exactly match a
	// declared, unbound instance, in declared-address order. Nothing is
	// bound: each carries the marker pair an operator would stamp to adopt
	// it.
	Candidates []Candidate

	// Renames lists the live resources this estate owns whose marker names a
	// for_each key the configuration no longer declares, each paired with the
	// one declared instance of the same resource block that nothing claimed,
	// in declared-address order. Like a bind candidate it is an offer and
	// nothing more: the marker is not rewritten, the plan still proposes
	// creating the new key, and the live resource is still an orphan.
	Renames []RenameCandidate

	// Removals lists the live resources this estate owns and no longer
	// declares, which the plan therefore proposes destroying, in address
	// order. They are the one part of this pass that is not report-only:
	// every one of them is in the prior state the plan ran against, as an
	// instance with no configuration.
	//
	// It is a section of this report rather than of the plan's own output
	// because the plan can only say "this will be destroyed"; the fact that
	// makes it legitimate - that the resource carries this estate's marker
	// at an address the configuration used to declare - is a marker fact,
	// and this is where marker facts are printed.
	Removals []Removal

	// SweepGaps lists the resource types the estate-wide removal sweep could
	// not enumerate, carried through from discovery. An estate with a sweep
	// gap has resources it may own and cannot see, so an empty Removals list
	// is not a claim that nothing is undeclared.
	SweepGaps []SweepGap

	// SweepCovered lists the types the sweep did enumerate, sorted.
	SweepCovered []string

	// Ambiguous lists the resource blocks that have orphans and unclaimed
	// declared instances but no one-to-one pairing between them, sorted by
	// block address. They carry no command: which live resource became which
	// key is exactly what a marker cannot say.
	Ambiguous []RenameAmbiguity

	// OtherEstates counts the live resources carrying another estate's
	// marker, by estate name, sorted. An entry with an empty Estate is the
	// count discovery kept without recording which estate it belonged to
	// (see [EstateCount.Estate]).
	OtherEstates []EstateCount

	// Swept lists the resource types that were listed in full, so that
	// their unclaimed resources are the complete set the provider would
	// admit - subject to the provider-side filters described in the package
	// doc. Sorted.
	Swept []string

	// Unswept lists the types this pass cannot speak for at all, sorted by
	// type name. It is the difference between "there are none" and "nobody
	// looked", and it is never omitted from output on the grounds of being
	// empty-looking.
	Unswept []Unswept

	// ParentReads lists the untaggable children a marked, admitted parent's
	// own identity led the sweep to (issue #60), carried straight through
	// from the discovery pass: each already knows whether it also became a
	// removal ([Removals] and the plan's own resource diff both show that
	// half; this list is what says a parent read is why).
	ParentReads []ParentReadFinding
}

type SweepGap struct {
	TypeName string
	Reason   SweepGapReason
	Detail   string
}

type SweepGapReason string

type Tag struct {
	Key   string
	Value string
}

type Unswept struct {
	// TypeName is the type.
	TypeName string

	// Reason is the machine-readable why.
	Reason UnsweptReason

	// Detail is one sentence for an operator.
	Detail string
}

type UnsweptReason string