Help us shape the future of Go! Take the 2026 Go Developer Survey

adoption

package
v0.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: MPL-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package adoption reads an `adopt: v1` adoption file and the index version it names (GitHub issue #2286; ruled on #2284, Q1 and Q7). An adoption file says which indexed objects an engine should adopt and under which address: 

{
  "adopt": "v1",
  "index": {"scopeKey": "cloud/aws/123456789012/<scope digest>",
            "version": "<observedAt>-<digest12>.json", "digest": "sha256:..."},
  "select": [{"node": "aws/123456789012/us-east-1/AWS::S3::Bucket/my-bucket",
              "as": "aws_s3_bucket.my_bucket", "type": "aws_s3_bucket"}]
}

Its TypeScript type and JSON Schema live in chant core beside the index schema (INTENTIUS/chant#4536, vendored in testdata with its sha); the Go engines read the JSON through this package. `as` is the engine's address (a Terraform address for choudoufu, a URN name for plunge, an entity name for chant). `type` is the engine's type, and may be left out only when the inventory type joins to exactly one engine type: pkg/registry maps 19 CloudFormation types to more than one Terraform type, and those need it (Selection.EngineType).

The index proposes and the live read decides: this package checks only that the file and the version agree (scope key, version name, digest, every selected node present). Each engine then reads every object again through its own provider before it writes a marker. Like the rest of pkg/, it imports nothing from this module's internal tree, so plunge can import it.

Index

Constants

View Source 
const FormatVersion = "v1"

FormatVersion is the only adoption file version this package reads.

View Source 
const IndexDocumentVersion = "v1"

IndexDocumentVersion is the only index envelope version this reader takes.

Variables

This section is empty.

Functions

func IsVersionName 

func IsVersionName(name string) bool

IsVersionName reports whether name is an index version's file name.

func ScopeKey 

func ScopeKey(scope map[string]any) (string, error)

ScopeKey is chant's indexScopeKey for a decoded scope: <source path>/<identity segments>/<scope digest>.

func VersionName 

func VersionName(observedAt, digest string) (string, error)

VersionName is chant's indexVersionName: the observed time as yyyymmddThhmmssZ, a dash, the digest's first 12 hex, ".json".

func VersionPath 

func VersionPath(storeDir string, ref IndexRef) string

VersionPath is where a filesystem index store under storeDir keeps the version an index reference names: <storeDir>/index/<scopeKey>/<version>.

Types

type Adoption 

type Adoption struct {
	File    *File
	Index   *IndexVersion
	Entries []Entry
}

Adoption is an adoption file resolved against the index version it names.

func Open 

func Open(path, storeDir string) (*Adoption, error)

Open reads the adoption file at path and the version it names from the filesystem index store under storeDir (VersionPath), and resolves one against the other.

func Resolve 

func Resolve(f *File, v *IndexVersion) (*Adoption, error)

Resolve checks f against v, the index version read for it: the scope key, the version name and the digest are the ones f names, and v holds every selected node. A refusal names what disagrees.

type CoverageEntry 

type CoverageEntry struct {
	ListedType string `json:"listedType"`
	Location   string `json:"location"`
	Verdict    string `json:"verdict"`
	Detail     string `json:"detail,omitempty"`
}

CoverageEntry is what a read looked at, per type and location.

type Entry 

type Entry struct {
	Selection
	Node *Node
}

Entry is one selection with the index node it names.

type File 

type File struct {
	Adopt  string      `json:"adopt"`
	Index  IndexRef    `json:"index"`
	Select []Selection `json:"select"`
}

File is one adoption file.

func Parse 

func Parse(data []byte) (*File, error)

Parse decodes an adoption file and checks it on its own (File.Validate). A field this version does not know is refused rather than ignored, since it could narrow or widen what is adopted.

func ReadFile 

func ReadFile(path string) (*File, error)

ReadFile reads and parses the adoption file at path.

func (*File) Validate 

func (f *File) Validate() error

Validate checks the file on its own: the version, an index reference whose version name carries the digest's first 12 hex, and at least one selection, each naming a node and an address, with no node or address twice.

type IndexRef 

type IndexRef struct {
	// ScopeKey is the version's stamp.scopeKey, the store path its scope maps to.
	ScopeKey string `json:"scopeKey"`
	// Version is the version's file name, <observedAt>-<digest12>.json.
	Version string `json:"version"`
	// Digest is the version's stamp.digest, with or without "sha256:".
	Digest string `json:"digest"`
}

IndexRef names one index version.

type IndexVersion 

type IndexVersion struct {
	Stamp    Stamp
	Coverage []CoverageEntry
	Nodes    []Node
	// contains filtered or unexported fields
}

IndexVersion is one parsed and checked index version.

func ParseIndexVersion 

func ParseIndexVersion(data []byte) (*IndexVersion, error)

ParseIndexVersion parses one index version and checks its stamp and digest.

func ReadIndexVersion 

func ReadIndexVersion(path string) (*IndexVersion, error)

ReadIndexVersion reads and checks the index version at path. The file's name must be the version's own name.

func (*IndexVersion) Name 

func (v *IndexVersion) Name() (string, error)

Name is the version's file name, <observedAt>-<digest12>.json.

func (*IndexVersion) Node 

func (v *IndexVersion) Node(id string) (*Node, bool)

Node is the node with id, if the version holds it.

type Node 

type Node struct {
	ID         string            `json:"id"`
	Kind       string            `json:"kind"`
	Lexicon    string            `json:"lexicon"`
	PhysicalID string            `json:"physicalId,omitempty"`
	ListedType string            `json:"listedType,omitempty"`
	Location   string            `json:"location,omitempty"`
	NativeID   string            `json:"nativeId,omitempty"`
	Tags       map[string]string `json:"tags,omitempty"`
	Attrs      map[string]any    `json:"attrs,omitempty"`
	Facts      json.RawMessage   `json:"facts,omitempty"`
}

Node is the part of a GraphIR node adoption reads. Indexed nodes carry ListedType (the inventory API's type name), Location, NativeID (Cloud Control's identifier, the ARM id, the asset name, or namespace/name) and Tags.

type Selection 

type Selection struct {
	// Node is the index node's id.
	Node string `json:"node"`
	// As is the engine's address for it.
	As string `json:"as"`
	// Type is the engine's type; empty when the inventory type joins to one.
	Type string `json:"type,omitempty"`
}

Selection is one indexed object to adopt.

func (Selection) EngineType 

func (s Selection) EngineType(candidates []string) (string, error)

EngineType is the engine type to adopt the selection as, given the engine types the node's inventory type joins to (for aws, pkg/registry's TFTypesForCFNType). With Type set it must be one of them, when there are any; without it there must be exactly one. Every refusal lists the candidates.

type Source 

type Source struct {
	Kind    string `json:"kind"`
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

Source says who produced the index.

type Stamp 

type Stamp struct {
	Source      Source          `json:"source"`
	Scope       json.RawMessage `json:"scope"`
	ScopeKey    string          `json:"scopeKey"`
	ObservedAt  string          `json:"observedAt"`
	CompletedAt string          `json:"completedAt,omitempty"`
	Commit      string          `json:"commit,omitempty"`
	// Digest is sha256 hex of the canonical coverage and graph.
	Digest string `json:"digest"`
}

Stamp is the index version's stamp.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.