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

livegraph

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 livegraph builds the estate graph "choudoufu live-graph -json" prints (GitHub issue #2285): one GraphIR version 1 document in the engine graph shape of INTENTIUS/chant#4520 (design section 3, ruled 2026-10-26), which chant's terraform lexicon reads for facts on its IR nodes and behold's graph pane loads as it is.

The document is built from the configuration tree alone: one node per resource and data block, keyed by its address, one node per instance when a literal count or for_each (or a live-plan row) names it, and one edge per reference found by walking the configuration's expressions. The walk needs no provider schema, so no provider starts and nothing is read from a cloud (the #2275 ruling, Q1). Cross-estate reads are edges to one node per read estate (Q2). Live facts come only from a live-plan -json document handed in (PlanDoc); this package performs no live read of its own.

The document carries addresses, types, the import ids a live plan bound and record version ids. It carries no attribute value, no record payload and nothing from a state file. PlanDoc decodes only the fields this package uses, so a value elsewhere in a live-plan document (a matched argument, an identity broken out by component, a diagnostic) is never even read into memory here.

Index

Constants

View Source 
const (
	// GapJSONConfig: the block is in a .tf.json file, whose body cannot be
	// walked for references without the provider's schema. Its node is
	// there and its outgoing edges are not.
	GapJSONConfig = "json-config"
	// GapBodyUnread: the block's body is not native syntax for another
	// reason (an override merged into it), so its references were not
	// walked.
	GapBodyUnread = "references-unread"
	// GapCrossEstate: a data block reads another estate by a value that
	// is not a literal, so which estate cannot be told from configuration.
	GapCrossEstate = "cross-estate-read-unresolved"
	// GapNotDeclared: the live plan names an address that no block of
	// this configuration declares.
	GapNotDeclared = "not-in-configuration"
	// GapHistoryUnkept: -history was asked for, and the record store
	// replaces records in place.
	GapHistoryUnkept = "history-not-kept"
)

Gap reasons.

View Source 
const EstateNodeKind = "estate"

EstateNodeKind is the kind of a node that stands for a read estate.

View Source 
const GrainBlock = "block"

GrainBlock is every edge's grain until instance edges land (#2256): the reference was found between two blocks, and an instance's edge points at the block it reads, never at that block's instances.

Variables

This section is empty.

Functions

func EstateNodeID 

func EstateNodeID(estate string) string

EstateNodeID is the id of the node standing for estate.

Types

type Built 

type Built struct {
	Doc *Document
	// contains filtered or unexported fields
}

Built is a document and what -history needs to know about its nodes.

func Build 

func Build(cfg *configs.Config, o Options) *Built

Build builds the graph of cfg. It reads nothing but cfg and o.Plan.

func (*Built) AddHistory 

func (bt *Built) AddHistory(ctx context.Context, list HistoryLister) error

AddHistory sets recordVersions on every node a record can exist for: a managed resource's instance (-history, the chant#4520 ruling Q6).

type CloudID 

type CloudID struct {
	Kind  string `json:"kind"`
	Value string `json:"value"`
}

CloudID is one cloud identifier of a node.

type Document 

type Document struct {
	Version int      `json:"version"`
	Meta    Meta     `json:"meta"`
	Nodes   []Node   `json:"nodes"`
	Edges   []Edge   `json:"edges"`
	Groups  struct{} `json:"groups"`
}

Document is one engine graph document.

type Edge 

type Edge struct {
	From    string `json:"from"`
	To      string `json:"to"`
	Kind    string `json:"kind"`
	ViaAttr string `json:"viaAttr,omitempty"`
	Grain   string `json:"grain"`
}

Edge is a reference from one node to another.

type Engine 

type Engine struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

Engine names what printed the document.

type EngineGraph 

type EngineGraph struct {
	Format       int           `json:"format"`
	Engine       Engine        `json:"engine"`
	Scope        Scope         `json:"scope"`
	ObservedAt   string        `json:"observedAt,omitempty"`
	MarkerScheme *MarkerScheme `json:"markerScheme,omitempty"`
	Gaps         []Gap         `json:"gaps,omitempty"`
}

EngineGraph is meta.engineGraph.

type Facts 

type Facts struct {
	Ownership      string          `json:"ownership,omitempty"`
	Markers        *Markers        `json:"markers,omitempty"`
	OwnedBy        string          `json:"ownedBy,omitempty"`
	CloudIDs       []CloudID       `json:"cloudIds,omitempty"`
	RecordVersions *RecordVersions `json:"recordVersions,omitempty"`
	ObservedAt     string          `json:"observedAt,omitempty"`
}

Facts is chant#4520's EngineFacts. Every field is absent when this run did not observe it.

type Gap 

type Gap struct {
	Address string `json:"address"`
	Reason  string `json:"reason"`
	Detail  string `json:"detail,omitempty"`
}

Gap is a block the graph could not describe in full, and why.

type HistoryLister 

type HistoryLister func(ctx context.Context, addr addrs.AbsResourceInstance) (kept bool, versions []RecordVersion, err error)

HistoryLister lists the versions of one record. kept is false for a store that replaces records in place; versions carry no values.

type MarkerEncoding 

type MarkerEncoding struct {
	Tags   string `json:"tags"`
	Labels string `json:"labels"`
}

MarkerEncoding is how marker values are written on tags and on labels.

type MarkerScheme 

type MarkerScheme struct {
	OwnerKey         string         `json:"ownerKey"`
	AddressKey       string         `json:"addressKey"`
	ContinuationKeys []string       `json:"continuationKeys,omitempty"`
	Encoding         MarkerEncoding `json:"encoding"`
}

MarkerScheme is the marker vocabulary choudoufu hands the public sweeps (pkg/markerkeys, #2281), printed once.

type Markers 

type Markers struct {
	Owner    string `json:"owner,omitempty"`
	Address  string `json:"address,omitempty"`
	Encoding string `json:"encoding"`
	Source   string `json:"source"`
}

Markers are the marker values the live plan read off the object.

type Meta 

type Meta struct {
	EngineGraph EngineGraph `json:"engineGraph"`
}

Meta is the document's meta bag.

type Node 

type Node struct {
	ID            string     `json:"id"`
	Kind          string     `json:"kind"`
	Lexicon       string     `json:"lexicon"`
	Attrs         NodeAttrs  `json:"attrs"`
	SourceLoc     *SourceLoc `json:"sourceLoc,omitempty"`
	PhysicalID    string     `json:"physicalId,omitempty"`
	InstanceOf    string     `json:"instanceOf,omitempty"`
	InstanceKey   string     `json:"instanceKey,omitempty"`
	InstanceScope string     `json:"instanceScope,omitempty"`
	Facts         *Facts     `json:"facts,omitempty"`
}

Node is one resource or data block, one instance of one, or one estate this configuration reads.

type NodeAttrs 

type NodeAttrs struct {
	Address string `json:"address,omitempty"`
	Estate  string `json:"estate,omitempty"`
}

NodeAttrs is a node's attrs: its address, or for an estate node the estate's name. Never a resource argument's value.

type Options 

type Options struct {
	// Dir is the root module's directory; source locations are relative
	// to it.
	Dir string
	// Estate is the estate the graph is of.
	Estate string
	// EngineVersion is choudoufu's release, empty on a development build.
	EngineVersion string
	// Plan, when set, is the live-plan document live facts come from.
	Plan *PlanDoc
	// Markers is the marker vocabulary choudoufu passes the public sweeps,
	// and ContinuationKeys the keys a long address continues into.
	Markers          markerkeys.Keys
	ContinuationKeys []string
}

Options is one graph build.

type PlanAdoptable 

type PlanAdoptable struct {
	Addr     string `json:"addr"`
	Type     string `json:"type"`
	Identity string `json:"identity"`
}

PlanAdoptable is an adoptable[] row.

type PlanBound 

type PlanBound struct {
	Addr     string `json:"addr"`
	Type     string `json:"type"`
	Identity string `json:"identity"`
	Source   string `json:"source"`
}

PlanBound is a bound[] row.

type PlanDoc 

type PlanDoc struct {
	Estate     string          `json:"estate"`
	ObservedAt string          `json:"observed_at"`
	Bound      []PlanBound     `json:"bound"`
	Unowned    []PlanUnowned   `json:"unowned"`
	Adoptable  []PlanAdoptable `json:"adoptable"`
	Omissions  []PlanOmission  `json:"omissions"`
}

PlanDoc is the part of a "choudoufu live-plan -json" document (views.LivePlanDocument) the graph takes facts from. Nothing else in that document is decoded.

type PlanOmission 

type PlanOmission struct {
	Addr   string `json:"addr"`
	Reason string `json:"reason"`
}

PlanOmission is an omissions[] row. Its detail is not decoded.

type PlanUnowned 

type PlanUnowned struct {
	Addr     string `json:"addr"`
	Type     string `json:"type"`
	Identity string `json:"identity"`
	HeldBy   string `json:"tofu_estate"`
}

PlanUnowned is an unowned[] row.

type RecordVersion 

type RecordVersion struct {
	ID        string `json:"id"`
	WrittenAt string `json:"writtenAt"`
	Current   bool   `json:"current"`
	Deleted   bool   `json:"deleted"`
}

RecordVersion is one version of a record.

type RecordVersions 

type RecordVersions struct {
	Kept     bool            `json:"kept"`
	Versions []RecordVersion `json:"versions"`
}

RecordVersions are a record's versions, newest first, with no values.

type Scope 

type Scope struct {
	Kind   string `json:"kind"`
	Estate string `json:"estate"`
}

Scope is the estate the graph covers.

type SourceLoc 

type SourceLoc struct {
	File string `json:"file"`
	Line int    `json:"line,omitempty"`
}

SourceLoc is where a block is declared, relative to the root directory.

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.