ci

package
v0.10.8 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package ci defines TerraCI's CI-facing domain: persisted plan/report artifacts, review-comment contracts, and provider-shared CI config types.

Index

Examples

Constants

View Source 
const CommentMarker = "<!-- terraci-plan-comment -->"

CommentMarker is used to identify TerraCI review comments for updates.

View Source 
const RenderPayloadSchemaVersion = 2

RenderPayloadSchemaVersion is the current rendered payload wire schema.

Variables

This section is empty.

Functions

func DiffManagedLabels added in v0.10.5 

func DiffManagedLabels(previous, current []string) (add, remove []string)

DiffManagedLabels computes provider label operations for TerraCI-owned labels.

func EmbedManagedLabels added in v0.10.5 

func EmbedManagedLabels(body string, labels []string) string

EmbedManagedLabels records the labels currently owned by TerraCI in the review comment body. The encoded payload is intentionally hidden in an HTML comment so providers can remove only labels TerraCI created earlier.

func EncodeManagedLabelsMetadata added in v0.10.5 

func EncodeManagedLabelsMetadata(labels []string) string

EncodeManagedLabelsMetadata serializes labels into a hidden comment payload.

func ExtractManagedLabels added in v0.10.5 

func ExtractManagedLabels(body string) []string

ExtractManagedLabels returns the TerraCI-owned labels recorded in a comment body.

func HasCommentMarker added in v0.9.4 

func HasCommentMarker(body string) bool

HasCommentMarker reports whether the provided body contains the TerraCI review-comment marker.

func NormalizeManagedLabels added in v0.10.5 

func NormalizeManagedLabels(labels []string) []string

NormalizeManagedLabels trims labels, removes empty entries, deduplicates them, and returns deterministic case-preserving order.

func ReportFilename added in v0.9.0 

func ReportFilename(producer string) string

ReportFilename returns the canonical artifact name for a producer's report.

func ResultFilename added in v0.10.3 

func ResultFilename(producer string) string

ResultFilename returns the canonical artifact name for a producer's raw result.

func StripManagedLabelsMetadata added in v0.10.5 

func StripManagedLabelsMetadata(body string) string

StripManagedLabelsMetadata removes all TerraCI managed-label metadata comments.

Types

type ArtifactContext added in v0.10.5 

type ArtifactContext struct {
	// contains filtered or unexported fields
}

ArtifactContext describes the current artifact-producing run. Producers pass it to NewRenderedReport so provenance is derived consistently for every persisted report.

func NewArtifactContext added in v0.10.5 

func NewArtifactContext(opts ArtifactContextOptions) ArtifactContext

NewArtifactContext normalizes run metadata used by report producers.

func (ArtifactContext) CommitSHA added in v0.10.5 

func (c ArtifactContext) CommitSHA() string

CommitSHA returns the best-known source commit SHA.

func (ArtifactContext) GeneratedAt added in v0.10.5 

func (c ArtifactContext) GeneratedAt() time.Time

GeneratedAt returns the normalized UTC artifact timestamp.

func (ArtifactContext) PipelineID added in v0.10.5 

func (c ArtifactContext) PipelineID() string

PipelineID returns the best-known CI pipeline identifier.

func (ArtifactContext) PlanResultsFingerprint added in v0.10.5 

func (c ArtifactContext) PlanResultsFingerprint() string

PlanResultsFingerprint returns the plan result collection fingerprint.

func (ArtifactContext) Provenance added in v0.10.5 

func (c ArtifactContext) Provenance() *ReportProvenance

Provenance converts the artifact context into persisted report provenance.

func (ArtifactContext) ServiceDir added in v0.10.5 

func (c ArtifactContext) ServiceDir() string

ServiceDir returns the service directory used for report artifacts.

func (ArtifactContext) WorkDir added in v0.10.5 

func (c ArtifactContext) WorkDir() string

WorkDir returns the workspace directory for the artifact-producing run.

type ArtifactContextOptions added in v0.10.5 

type ArtifactContextOptions struct {
	ServiceDir             string
	WorkDir                string
	CommitSHA              string
	PipelineID             string
	PlanResultsFingerprint string
	GeneratedAt            time.Time
}

ArtifactContextOptions describes how to construct an ArtifactContext.

type ArtifactPublication added in v0.10.8 

type ArtifactPublication struct {
	// contains filtered or unexported fields
}

ArtifactPublication is a validated producer artifact publication intent.

func NewArtifactPublication added in v0.10.8 

func NewArtifactPublication(opts ArtifactPublicationOptions) (ArtifactPublication, error)

NewArtifactPublication validates and returns a publication intent.

type ArtifactPublicationOptions added in v0.10.8 

type ArtifactPublicationOptions struct {
	Producer    string
	Results     ArtifactResults
	BuildReport ArtifactReportBuilder
}

ArtifactPublicationOptions describes one canonical producer artifact write.

type ArtifactPublisher added in v0.10.8 

type ArtifactPublisher interface {
	PublishArtifacts(ctx context.Context, publication ArtifactPublication) error
}

ArtifactPublisher publishes producer result/report artifacts.

type ArtifactReportBuilder added in v0.10.5 

type ArtifactReportBuilder func() (*Report, error)

ArtifactReportBuilder builds a render-ready report for a producer artifact write. Returning nil without an error intentionally removes any stale report while still preserving raw results.

type ArtifactResults added in v0.10.8 

type ArtifactResults struct {
	// contains filtered or unexported fields
}

ArtifactResults describes whether a producer publication should write raw results and, if so, what JSON-serializable value should be written.

func NoResults added in v0.10.8 

func NoResults() ArtifactResults

NoResults marks a report-only publication.

func RawResults added in v0.10.8 

func RawResults(value any) ArtifactResults

RawResults marks value for persistence as {producer}-results.json.

type ArtifactRun added in v0.10.5 

type ArtifactRun struct {
	// contains filtered or unexported fields
}

ArtifactRun describes one producer's report/result artifact write.

func NewArtifactRun added in v0.10.5 

func NewArtifactRun(opts ArtifactRunOptions) (ArtifactRun, error)

NewArtifactRun normalizes producer run metadata. When PlanResults is present and the artifact context has no explicit fingerprint, the plan collection fingerprint is used. Empty fingerprints remain valid for non-plan producers.

func (ArtifactRun) Artifact added in v0.10.5 

func (r ArtifactRun) Artifact() ArtifactContext

Artifact returns the normalized artifact context.

func (ArtifactRun) PlanResults added in v0.10.5 

func (r ArtifactRun) PlanResults() *PlanResultCollection

PlanResults returns a defensive copy of the plan result collection.

func (ArtifactRun) Producer added in v0.10.5 

func (r ArtifactRun) Producer() string

Producer returns the artifact-producing plugin key.

type ArtifactRunOptions added in v0.10.5 

type ArtifactRunOptions struct {
	Producer    string
	Artifact    ArtifactContext
	PlanResults *PlanResultCollection
}

ArtifactRunOptions describes how to construct an ArtifactRun.

type CommentService 

type CommentService interface {
	IsEnabled() bool
	UpsertComment(ctx context.Context, body string) error
}

CommentService defines the interface for posting plan summaries to PRs/MRs

type Image added in v0.9.4 

type Image struct {
	// Name is the image name (e.g., "hashicorp/terraform:1.6")
	Name string `yaml:"name,omitempty" json:"name,omitempty" jsonschema:"description=Docker image name"`
	// Entrypoint overrides the default entrypoint.
	Entrypoint []string `yaml:"entrypoint,omitempty" json:"entrypoint,omitempty" jsonschema:"description=Override default entrypoint"`
}

Image defines a Docker image configuration for CI jobs.

func (*Image) HasEntrypoint added in v0.9.4 

func (img *Image) HasEntrypoint() bool

HasEntrypoint returns true if entrypoint is configured.

func (Image) MarshalYAML added in v0.10.0 

func (img Image) MarshalYAML() (any, error)

MarshalYAML emits the short string form ("image:1.0") when only Name is set, preserving round-trip symmetry with UnmarshalYAML. Configs that started as shorthand stay shorthand after `terraci init` writes them back; only configs with an Entrypoint override expand to the full mapping.

func (*Image) String added in v0.9.4 

func (img *Image) String() string

String returns the image name.

func (*Image) UnmarshalYAML added in v0.9.4 

func (img *Image) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML supports both string shorthand ("image:1.0") and full object ({name: "image:1.0"}).

type ManagedLabelService added in v0.10.5 

type ManagedLabelService interface {
	CurrentCommentBody(ctx context.Context) (body string, found bool, err error)
	SyncLabels(ctx context.Context, previous, current []string) error
}

ManagedLabelService is an optional extension for comment services that can synchronize labels owned by the TerraCI summary comment.

type PlanResult 

type PlanResult struct {
	// contains filtered or unexported fields
}

PlanResult is the canonical representation of a single module's plan outcome — both for in-memory rendering and on-disk persistence.

func NewPlanResult added in v0.10.8 

func NewPlanResult(opts PlanResultOptions) (PlanResult, error)

NewPlanResult validates and returns a plan result value.

func (PlanResult) Clone added in v0.10.8 

func (r PlanResult) Clone() PlanResult

Clone returns a defensive copy of r.

func (PlanResult) Component added in v0.10.8 

func (r PlanResult) Component(name string) string

Component returns the value of a named component from the Components map.

func (PlanResult) Components 

func (r PlanResult) Components() map[string]string

Components returns a defensive copy of parsed module path components.

func (PlanResult) Duration added in v0.10.0 

func (r PlanResult) Duration() time.Duration

Duration returns the plan command duration.

func (PlanResult) ErrorMessage added in v0.10.8 

func (r PlanResult) ErrorMessage() string

ErrorMessage returns the plan result error message, if any.

func (PlanResult) ExitCode 

func (r PlanResult) ExitCode() int

ExitCode returns the Terraform plan exit code.

func (PlanResult) MarshalJSON added in v0.10.8 

func (r PlanResult) MarshalJSON() ([]byte, error)

MarshalJSON preserves the public plan result artifact shape.

func (PlanResult) ModuleID 

func (r PlanResult) ModuleID() string

ModuleID returns the stable module identifier.

func (PlanResult) ModulePath 

func (r PlanResult) ModulePath() string

ModulePath returns the module path used for plan artifact discovery.

func (PlanResult) RawPlanOutput 

func (r PlanResult) RawPlanOutput() string

RawPlanOutput returns filtered raw plan text, when available.

func (PlanResult) Status 

func (r PlanResult) Status() PlanStatus

Status returns the module plan status.

func (PlanResult) StructuredDetails 

func (r PlanResult) StructuredDetails() string

StructuredDetails returns structured rendered plan details, when available.

func (PlanResult) Summary 

func (r PlanResult) Summary() string

Summary returns the short plan summary.

func (*PlanResult) UnmarshalJSON added in v0.10.8 

func (r *PlanResult) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the public plan result artifact shape.

type PlanResultCollection 

type PlanResultCollection struct {
	// contains filtered or unexported fields
}

PlanResultCollection is the persisted CI artifact collection for a pipeline run.

func EmptyPlanResultCollection added in v0.10.8 

func EmptyPlanResultCollection() *PlanResultCollection

EmptyPlanResultCollection returns an empty plan result collection.

func NewPlanResultCollection added in v0.10.8 

func NewPlanResultCollection(opts PlanResultCollectionOptions) (*PlanResultCollection, error)

NewPlanResultCollection validates and returns an immutable plan result collection.

func (*PlanResultCollection) Clone added in v0.10.8 

func (c *PlanResultCollection) Clone() *PlanResultCollection

Clone returns a defensive copy of c.

func (*PlanResultCollection) CommitSHA 

func (c *PlanResultCollection) CommitSHA() string

CommitSHA returns the collection commit SHA, if known.

func (*PlanResultCollection) Fingerprint added in v0.10.0 

func (c *PlanResultCollection) Fingerprint() string

Fingerprint returns a stable content fingerprint for the collection.

func (*PlanResultCollection) GeneratedAt 

func (c *PlanResultCollection) GeneratedAt() time.Time

GeneratedAt returns the collection generation timestamp.

func (*PlanResultCollection) Len added in v0.10.8 

func (c *PlanResultCollection) Len() int

Len returns the number of plan results.

func (*PlanResultCollection) MarshalJSON added in v0.10.8 

func (c *PlanResultCollection) MarshalJSON() ([]byte, error)

MarshalJSON preserves the public plan result collection artifact shape.

func (*PlanResultCollection) PipelineID 

func (c *PlanResultCollection) PipelineID() string

PipelineID returns the collection CI pipeline ID, if known.

func (*PlanResultCollection) Results 

func (c *PlanResultCollection) Results() []PlanResult

Results returns defensive copies of module plan results.

func (*PlanResultCollection) UnmarshalJSON added in v0.10.8 

func (c *PlanResultCollection) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the public plan result collection artifact shape.

type PlanResultCollectionOptions added in v0.10.8 

type PlanResultCollectionOptions struct {
	Results     []PlanResult
	PipelineID  string
	CommitSHA   string
	GeneratedAt time.Time
}

PlanResultCollectionOptions describes a plan result collection.

type PlanResultOptions added in v0.10.8 

type PlanResultOptions struct {
	ModuleID          string
	ModulePath        string
	Components        map[string]string
	Status            PlanStatus
	Summary           string
	StructuredDetails string
	RawPlanOutput     string
	Error             string
	ExitCode          int
	Duration          time.Duration
}

PlanResultOptions describes one module's Terraform plan outcome.

type PlanStatus 

type PlanStatus string

PlanStatus represents the status of a terraform plan. 

const (
	PlanStatusPending   PlanStatus = "pending"
	PlanStatusRunning   PlanStatus = "running"
	PlanStatusSuccess   PlanStatus = "success"
	PlanStatusNoChanges PlanStatus = "no_changes"
	PlanStatusChanges   PlanStatus = "changes"
	PlanStatusFailed    PlanStatus = "failed"
)

func PlanStatusFromPlan added in v0.7.4 

func PlanStatusFromPlan(hasChanges bool) PlanStatus

PlanStatusFromPlan determines the CI plan status from a parsed plan.

func (PlanStatus) Valid added in v0.10.8 

func (s PlanStatus) Valid() bool

Valid reports whether the status is one of the supported plan outcomes.

type RenderBlock added in v0.10.5 

type RenderBlock struct {
	// contains filtered or unexported fields
}

RenderBlock is a generic block used by markdown and CLI renderers.

func NewDetailsBlock added in v0.10.6 

func NewDetailsBlock(summary, body, language string) RenderBlock

NewDetailsBlock returns a collapsible detail block.

func NewListBlock added in v0.10.6 

func NewListBlock(title string, items []RenderValue) RenderBlock

NewListBlock returns an ordered list of typed items.

func NewTableBlock added in v0.10.6 

func NewTableBlock(title string, columns []RenderColumn, rows []RenderRow) RenderBlock

NewTableBlock returns an ordered typed table render block.

func NewTextBlock added in v0.10.6 

func NewTextBlock(values ...RenderValue) RenderBlock

NewTextBlock returns a paragraph-like render block.

func (RenderBlock) Clone added in v0.10.6 

func (b RenderBlock) Clone() RenderBlock

Clone returns a defensive copy of the render block.

func (RenderBlock) Details added in v0.10.5 

func (b RenderBlock) Details() *RenderDetails

Details returns a defensive copy of the details block payload.

func (RenderBlock) Items added in v0.10.5 

func (b RenderBlock) Items() []RenderValue

Items returns a defensive copy of list block items.

func (RenderBlock) Kind added in v0.10.5 

func (b RenderBlock) Kind() RenderBlockKind

Kind returns the block type.

func (RenderBlock) MarshalJSON added in v0.10.6 

func (b RenderBlock) MarshalJSON() ([]byte, error)

MarshalJSON preserves the render block wire shape.

func (RenderBlock) Table added in v0.10.5 

func (b RenderBlock) Table() *RenderTable

Table returns a defensive copy of the table block payload.

func (RenderBlock) Text added in v0.10.5 

func (b RenderBlock) Text() RenderValue

Text returns the text block content.

func (RenderBlock) Title added in v0.10.5 

func (b RenderBlock) Title() string

Title returns the optional block title.

func (*RenderBlock) UnmarshalJSON added in v0.10.6 

func (b *RenderBlock) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the render block wire shape.

func (RenderBlock) Validate added in v0.10.5 

func (b RenderBlock) Validate() error

Validate verifies one render block.

type RenderBlockKind added in v0.10.5 

type RenderBlockKind string

RenderBlockKind identifies one render-ready block type. 

const (
	RenderBlockKindText    RenderBlockKind = "text"
	RenderBlockKindTable   RenderBlockKind = "table"
	RenderBlockKindList    RenderBlockKind = "list"
	RenderBlockKindDetails RenderBlockKind = "details"
)

type RenderColumn added in v0.10.6 

type RenderColumn struct {
	// contains filtered or unexported fields
}

RenderColumn is one typed table column.

func NewRenderColumn added in v0.10.6 

func NewRenderColumn(title string) RenderColumn

NewRenderColumn builds a text table column.

func NewRenderValueColumn added in v0.10.6 

func NewRenderValueColumn(title RenderValue) RenderColumn

NewRenderValueColumn builds a table column from a typed value.

func (RenderColumn) Clone added in v0.10.6 

func (c RenderColumn) Clone() RenderColumn

Clone returns a defensive copy of the column.

func (RenderColumn) MarshalJSON added in v0.10.6 

func (c RenderColumn) MarshalJSON() ([]byte, error)

MarshalJSON preserves the table column wire shape.

func (RenderColumn) Title added in v0.10.6 

func (c RenderColumn) Title() RenderValue

Title returns the typed column title.

func (*RenderColumn) UnmarshalJSON added in v0.10.6 

func (c *RenderColumn) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the table column wire shape.

type RenderDetails added in v0.10.5 

type RenderDetails struct {
	// contains filtered or unexported fields
}

RenderDetails is a collapsible detail block.

func (RenderDetails) Body added in v0.10.5 

func (d RenderDetails) Body() string

Body returns the details body.

func (RenderDetails) Clone added in v0.10.6 

func (d RenderDetails) Clone() RenderDetails

Clone returns a defensive copy of the details value.

func (RenderDetails) Language added in v0.10.5 

func (d RenderDetails) Language() string

Language returns the optional details language.

func (RenderDetails) MarshalJSON added in v0.10.6 

func (d RenderDetails) MarshalJSON() ([]byte, error)

MarshalJSON preserves the details wire shape.

func (RenderDetails) Summary added in v0.10.5 

func (d RenderDetails) Summary() string

Summary returns the details summary.

func (*RenderDetails) UnmarshalJSON added in v0.10.6 

func (d *RenderDetails) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the details wire shape.

func (RenderDetails) Validate added in v0.10.5 

func (d RenderDetails) Validate() error

Validate verifies details shape.

type RenderMoneyOptions added in v0.10.6 

type RenderMoneyOptions struct {
	Unit RenderMoneyUnit
}

RenderMoneyOptions configures money rendering.

type RenderMoneyUnit added in v0.10.6 

type RenderMoneyUnit string

RenderMoneyUnit identifies a display unit suffix for money values. 

const (
	RenderMoneyUnitNone  RenderMoneyUnit = ""
	RenderMoneyUnitMonth RenderMoneyUnit = "mo"
)

func (RenderMoneyUnit) Valid added in v0.10.6 

func (u RenderMoneyUnit) Valid() bool

Valid reports whether the money unit is supported by renderers.

type RenderRow added in v0.10.6 

type RenderRow struct {
	// contains filtered or unexported fields
}

RenderRow is one typed table row.

func NewRenderRow added in v0.10.6 

func NewRenderRow(cells ...RenderValue) RenderRow

NewRenderRow builds a table row from typed values.

func (RenderRow) Cells added in v0.10.6 

func (r RenderRow) Cells() []RenderValue

Cells returns a defensive copy of the row cells.

func (RenderRow) Clone added in v0.10.6 

func (r RenderRow) Clone() RenderRow

Clone returns a defensive copy of the row.

func (RenderRow) MarshalJSON added in v0.10.6 

func (r RenderRow) MarshalJSON() ([]byte, error)

MarshalJSON preserves the table row wire shape.

func (*RenderRow) UnmarshalJSON added in v0.10.6 

func (r *RenderRow) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the table row wire shape.

type RenderSection added in v0.10.5 

type RenderSection struct {
	// contains filtered or unexported fields
}

RenderSection is a plugin-produced, renderer-facing section body.

func DecodeRenderSection added in v0.10.5 

func DecodeRenderSection(section ReportSection) (RenderSection, error)

DecodeRenderSection decodes and validates a render-ready report section.

func (RenderSection) Blocks added in v0.10.5 

func (s RenderSection) Blocks() []RenderBlock

Blocks returns a defensive copy of the section blocks.

func (RenderSection) MarshalJSON added in v0.10.6 

func (s RenderSection) MarshalJSON() ([]byte, error)

MarshalJSON preserves the rendered section wire shape while keeping the Go value object immutable to external packages.

func (RenderSection) SchemaVersion added in v0.10.6 

func (s RenderSection) SchemaVersion() int

SchemaVersion returns the rendered payload schema version.

func (*RenderSection) UnmarshalJSON added in v0.10.6 

func (s *RenderSection) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the rendered section wire shape.

func (RenderSection) Validate added in v0.10.5 

func (s RenderSection) Validate() error

Validate verifies that all render blocks are well-formed.

type RenderTable added in v0.10.5 

type RenderTable struct {
	// contains filtered or unexported fields
}

RenderTable is an ordered table payload.

func (RenderTable) Clone added in v0.10.6 

func (t RenderTable) Clone() RenderTable

Clone returns a defensive copy of the table.

func (RenderTable) Columns added in v0.10.5 

func (t RenderTable) Columns() []RenderColumn

Columns returns a defensive copy of table columns.

func (RenderTable) MarshalJSON added in v0.10.6 

func (t RenderTable) MarshalJSON() ([]byte, error)

MarshalJSON preserves the table wire shape.

func (RenderTable) Rows added in v0.10.5 

func (t RenderTable) Rows() []RenderRow

Rows returns a defensive copy of table rows.

func (*RenderTable) UnmarshalJSON added in v0.10.6 

func (t *RenderTable) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the table wire shape.

func (RenderTable) Validate added in v0.10.5 

func (t RenderTable) Validate() error

Validate verifies table shape.

type RenderTone added in v0.10.6 

type RenderTone string

RenderTone describes presentation intent for labels. 

const (
	RenderToneNeutral RenderTone = "neutral"
	RenderToneInfo    RenderTone = "info"
	RenderToneSuccess RenderTone = "success"
	RenderToneWarning RenderTone = "warning"
	RenderToneFailure RenderTone = "failure"
)

func (RenderTone) Valid added in v0.10.6 

func (t RenderTone) Valid() bool

Valid reports whether the tone is supported by renderers.

type RenderValue added in v0.10.6 

type RenderValue struct {
	// contains filtered or unexported fields
}

RenderValue is a typed semantic value rendered by the shared renderers.

func RenderCode added in v0.10.6 

func RenderCode(text string) RenderValue

RenderCode builds a monospace code render value.

func RenderInline added in v0.10.6 

func RenderInline(parts ...RenderValue) RenderValue

RenderInline builds a composite inline value from typed fragments.

func RenderLabel added in v0.10.6 

func RenderLabel(text string, tone RenderTone) RenderValue

RenderLabel builds a tone-aware label render value.

func RenderModulePath added in v0.10.6 

func RenderModulePath(path string) RenderValue

RenderModulePath builds a Terraform module path render value.

func RenderMoney added in v0.10.6 

func RenderMoney(amount float64, opts RenderMoneyOptions) RenderValue

RenderMoney builds a money render value.

func RenderMoneyDelta added in v0.10.6 

func RenderMoneyDelta(amount float64, opts RenderMoneyOptions) RenderValue

RenderMoneyDelta builds a signed money delta render value.

func RenderResourceAddress added in v0.10.6 

func RenderResourceAddress(address string) RenderValue

RenderResourceAddress builds a Terraform resource address render value.

func RenderStatus added in v0.10.6 

func RenderStatus(status ReportStatus) RenderValue

RenderStatus builds a report status render value.

func RenderText added in v0.10.6 

func RenderText(text string) RenderValue

RenderText builds a plain text render value.

func (RenderValue) Amount added in v0.10.6 

func (v RenderValue) Amount() float64

Amount returns the money amount.

func (RenderValue) Clone added in v0.10.6 

func (v RenderValue) Clone() RenderValue

Clone returns a defensive copy of the render value.

func (RenderValue) Kind added in v0.10.6 

func (v RenderValue) Kind() RenderValueKind

Kind returns the semantic value type.

func (RenderValue) MarshalJSON added in v0.10.6 

func (v RenderValue) MarshalJSON() ([]byte, error)

MarshalJSON preserves the render value wire shape.

func (RenderValue) Parts added in v0.10.6 

func (v RenderValue) Parts() []RenderValue

Parts returns a defensive copy of inline fragments.

func (RenderValue) Status added in v0.10.6 

func (v RenderValue) Status() ReportStatus

Status returns the report status for status values.

func (RenderValue) Text added in v0.10.6 

func (v RenderValue) Text() string

Text returns the value text for text-like values.

func (RenderValue) Tone added in v0.10.6 

func (v RenderValue) Tone() RenderTone

Tone returns the label tone.

func (RenderValue) Unit added in v0.10.6 

func (v RenderValue) Unit() RenderMoneyUnit

Unit returns the money unit.

func (*RenderValue) UnmarshalJSON added in v0.10.6 

func (v *RenderValue) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the render value wire shape.

func (RenderValue) Validate added in v0.10.6 

func (v RenderValue) Validate() error

Validate verifies one render value.

type RenderValueKind added in v0.10.6 

type RenderValueKind string

RenderValueKind identifies one semantic value carried by rendered reports. 

const (
	RenderValueKindText            RenderValueKind = "text"
	RenderValueKindCode            RenderValueKind = "code"
	RenderValueKindStatus          RenderValueKind = "status"
	RenderValueKindLabel           RenderValueKind = "label"
	RenderValueKindMoney           RenderValueKind = "money"
	RenderValueKindMoneyDelta      RenderValueKind = "money_delta"
	RenderValueKindModulePath      RenderValueKind = "module_path"
	RenderValueKindResourceAddress RenderValueKind = "resource_address"
	RenderValueKindInline          RenderValueKind = "inline"
)

type RenderedReportOptions added in v0.10.5 

type RenderedReportOptions struct {
	Producer string
	Title    string
	Status   ReportStatus
	Summary  string
	Artifact ArtifactContext
	Sections []RenderedSectionOptions
}

RenderedReportOptions describes a complete producer report assembled from render-ready sections.

type RenderedSectionOptions added in v0.10.5 

type RenderedSectionOptions struct {
	Title   string
	Summary string
	Status  ReportStatus
	Blocks  []RenderBlock
}

RenderedSectionOptions describes one render-ready report section.

type Report added in v0.7.4 

type Report struct {
	// contains filtered or unexported fields
}

Report is a CI enrichment artifact written by a tool and consumed by report aggregation flows. Producers persist reports as {serviceDir}/{producer}-report.json.

func LoadReport added in v0.9.0 

func LoadReport(path string) (*Report, error)

LoadReport reads and validates a single report file from disk. It is intended for low-level tests and store internals; producers should use ReportStore.

func NewRenderedReport added in v0.10.5 

func NewRenderedReport(opts RenderedReportOptions) (*Report, error)

NewRenderedReport builds and validates a producer report from render-ready sections. Section statuses default to the report status when omitted.

Example 
package main

import (
	"fmt"

	"github.com/edelwud/terraci/pkg/ci"
)

func main() {
	report, err := ci.NewRenderedReport(ci.RenderedReportOptions{
		Producer: "policy",
		Title:    "Policy Check",
		Status:   ci.ReportStatusWarn,
		Summary:  "1 warning",
		Artifact: ci.NewArtifactContext(ci.ArtifactContextOptions{
			CommitSHA:              "abc123",
			PlanResultsFingerprint: "fingerprint",
		}),
		Sections: []ci.RenderedSectionOptions{{
			Title:   "Findings",
			Summary: "1 warning",
			Blocks: []ci.RenderBlock{
				ci.NewTableBlock("Warnings", []ci.RenderColumn{
					ci.NewRenderColumn("Module"),
					ci.NewRenderColumn("Message"),
				}, []ci.RenderRow{
					ci.NewRenderRow(ci.RenderModulePath("svc/prod/vpc"), ci.RenderText("tag missing")),
				}),
			},
		}},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(report.Producer(), report.Sections()[0].Kind())
}

Output:
policy rendered

func (*Report) Clone added in v0.10.5 

func (r *Report) Clone() *Report

Clone returns a defensive copy of the report.

func (*Report) MarshalJSON added in v0.10.8 

func (r *Report) MarshalJSON() ([]byte, error)

MarshalJSON preserves the public report artifact shape while keeping the in-process report immutable to external packages.

func (*Report) Producer added in v0.10.0 

func (r *Report) Producer() string

Producer returns the report producer key.

func (*Report) Provenance added in v0.10.0 

func (r *Report) Provenance() *ReportProvenance

Provenance returns a defensive copy of report provenance.

func (*Report) Sections added in v0.10.0 

func (r *Report) Sections() []ReportSection

Sections returns defensive copies of render-ready report sections.

func (*Report) Status added in v0.7.4 

func (r *Report) Status() ReportStatus

Status returns the report status.

func (*Report) Summary added in v0.7.4 

func (r *Report) Summary() string

Summary returns the short report summary.

func (*Report) Title added in v0.7.4 

func (r *Report) Title() string

Title returns the report title.

func (*Report) UnmarshalJSON added in v0.10.8 

func (r *Report) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the public report artifact shape.

func (*Report) Validate added in v0.10.0 

func (r *Report) Validate() error

Validate verifies the persisted report artifact contract.

type ReportCollection added in v0.10.8 

type ReportCollection struct {
	// contains filtered or unexported fields
}

ReportCollection is a deterministic read-only set of reports keyed by producer.

func NewReportCollection added in v0.10.8 

func NewReportCollection(reports ...*Report) ReportCollection

NewReportCollection returns reports sorted by producer. When duplicate producers are present, the last report wins.

func (ReportCollection) Find added in v0.10.8 

func (c ReportCollection) Find(producer string) (*Report, bool)

Find returns a defensive copy for producer.

func (ReportCollection) Len added in v0.10.8 

func (c ReportCollection) Len() int

Len returns the number of reports.

func (ReportCollection) Producers added in v0.10.8 

func (c ReportCollection) Producers() []string

Producers returns report producer names in deterministic order.

func (ReportCollection) Reports added in v0.10.8 

func (c ReportCollection) Reports() []*Report

Reports returns defensive report copies in deterministic producer order.

func (ReportCollection) WithoutProducers added in v0.10.8 

func (c ReportCollection) WithoutProducers(producers ...string) ReportCollection

WithoutProducers returns a collection excluding the supplied producer names.

type ReportFreshness added in v0.10.5 

type ReportFreshness struct {
	// contains filtered or unexported fields
}

ReportFreshness is the freshness decision for one report.

func EvaluateReportFreshness added in v0.10.5 

func EvaluateReportFreshness(collection *PlanResultCollection, report *Report, consumer string) ReportFreshness

EvaluateReportFreshness evaluates one report against the current plan collection.

func (ReportFreshness) Diagnostic added in v0.10.7 

func (f ReportFreshness) Diagnostic() diagnostic.Diagnostic

Diagnostic returns the freshness diagnostic, if any.

func (ReportFreshness) Status added in v0.10.5 

func (f ReportFreshness) Status() ReportFreshnessStatus

Status returns the freshness decision.

type ReportFreshnessStatus added in v0.10.5 

type ReportFreshnessStatus string

ReportFreshnessStatus describes whether a producer report belongs to the current plan-result collection. 

const (
	ReportFreshnessCurrent  ReportFreshnessStatus = "current"
	ReportFreshnessDegraded ReportFreshnessStatus = "degraded"
	ReportFreshnessStale    ReportFreshnessStatus = "stale"
)

type ReportLoader added in v0.10.8 

type ReportLoader interface {
	LoadReports(ctx context.Context) (ReportCollection, error)
}

ReportLoader loads reports from the current process and/or service dir.

type ReportProvenance added in v0.10.0 

type ReportProvenance struct {
	// contains filtered or unexported fields
}

ReportProvenance captures the source run identity for a persisted report.

Producers should populate provenance for every persisted report so local consumers (e.g. localexec/render) can decide whether the artifact still matches the current workspace. Producers should derive it from ArtifactContext instead of assembling it by hand.

func (*ReportProvenance) Clone added in v0.10.8 

func (p *ReportProvenance) Clone() *ReportProvenance

Clone returns a defensive copy of p.

func (*ReportProvenance) CommitSHA added in v0.10.0 

func (p *ReportProvenance) CommitSHA() string

CommitSHA returns the best-known source commit SHA.

func (*ReportProvenance) GeneratedAt added in v0.10.0 

func (p *ReportProvenance) GeneratedAt() time.Time

GeneratedAt returns the report generation timestamp.

func (*ReportProvenance) MarshalJSON added in v0.10.8 

func (p *ReportProvenance) MarshalJSON() ([]byte, error)

MarshalJSON preserves the public provenance artifact shape.

func (*ReportProvenance) PipelineID added in v0.10.0 

func (p *ReportProvenance) PipelineID() string

PipelineID returns the best-known CI pipeline identifier.

func (*ReportProvenance) PlanResultsFingerprint added in v0.10.0 

func (p *ReportProvenance) PlanResultsFingerprint() string

PlanResultsFingerprint returns the plan result collection fingerprint used to decide whether a report is fresh for local consumers.

func (*ReportProvenance) UnmarshalJSON added in v0.10.8 

func (p *ReportProvenance) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes persisted provenance.

type ReportSection added in v0.10.0 

type ReportSection struct {
	// contains filtered or unexported fields
}

ReportSection is a neutral value object describing one slice of a CI report. Persisted producer reports must publish ReportSectionKindRendered payloads. Use NewRenderedSection or NewRenderedReport instead of constructing report JSON or payloads by hand.

func NewRenderedSection added in v0.10.5 

func NewRenderedSection(opts RenderedSectionOptions) (ReportSection, error)

NewRenderedSection builds and validates a render-ready report section.

func (ReportSection) Clone added in v0.10.5 

func (s ReportSection) Clone() ReportSection

Clone returns a defensive copy of the report section.

func (ReportSection) Kind added in v0.10.0 

func (s ReportSection) Kind() ReportSectionKind

Kind returns the section payload shape.

func (ReportSection) MarshalJSON added in v0.10.5 

func (s ReportSection) MarshalJSON() ([]byte, error)

MarshalJSON preserves the public persisted report section shape while keeping the in-process value object immutable from external packages.

func (ReportSection) Status added in v0.10.0 

func (s ReportSection) Status() ReportStatus

Status returns the section status.

func (ReportSection) Summary added in v0.10.5 

func (s ReportSection) Summary() string

Summary returns the short section summary.

func (ReportSection) Title added in v0.10.0 

func (s ReportSection) Title() string

Title returns the section title.

func (*ReportSection) UnmarshalJSON added in v0.10.5 

func (s *ReportSection) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves the public persisted report section shape while keeping direct payload construction out of the Go API.

type ReportSectionKind added in v0.10.0 

type ReportSectionKind string

ReportSectionKind identifies a report section payload shape. Summary-facing producer reports should use ReportSectionKindRendered so consumers can render plugin output without knowing the producer's domain model. 

const ReportSectionKindRendered ReportSectionKind = "rendered"

ReportSectionKindRendered is the canonical render-ready report payload. It is intentionally generic: producer plugins own their domain model and publish only typed view values needed by summary/local renderers.

type ReportSelection added in v0.10.5 

type ReportSelection struct {
	// contains filtered or unexported fields
}

ReportSelection is the canonical selected-report result for consumers.

func EmptyReportSelection added in v0.10.8 

func EmptyReportSelection() ReportSelection

EmptyReportSelection returns an empty selected-report result.

func SelectCurrentReports added in v0.10.5 

func SelectCurrentReports(collection *PlanResultCollection, reports ReportCollection, opts ReportSelectionOptions) ReportSelection

SelectCurrentReports selects reports safe to render for the supplied plan collection. Reports with missing provenance or fingerprints are considered degraded but renderable; reports with mismatched non-empty fingerprints are skipped and returned as warnings.

func (ReportSelection) Diagnostics added in v0.10.7 

func (s ReportSelection) Diagnostics() diagnostic.List

Diagnostics returns selection diagnostics.

func (ReportSelection) Len added in v0.10.8 

func (s ReportSelection) Len() int

Len returns the number of selected reports.

func (ReportSelection) Producers added in v0.10.8 

func (s ReportSelection) Producers() []string

Producers returns selected report producer names in deterministic order.

func (ReportSelection) ReportCollection added in v0.10.8 

func (s ReportSelection) ReportCollection() ReportCollection

ReportCollection returns selected reports in deterministic producer order.

type ReportSelectionOptions added in v0.10.5 

type ReportSelectionOptions struct {
	Consumer         string
	ExcludeProducers []string
}

ReportSelectionOptions controls report freshness selection.

type ReportStatus added in v0.7.4 

type ReportStatus string

ReportStatus indicates the outcome of a producer's check. 

const (
	ReportStatusPass ReportStatus = "pass"
	ReportStatusWarn ReportStatus = "warn"
	ReportStatusFail ReportStatus = "fail"
)

func StatusFromCounts added in v0.10.0 

func StatusFromCounts(fail, warn int) ReportStatus

StatusFromCounts returns the strictest status implied by the given fail / warn counts: any failure → Fail; any warning → Warn; otherwise Pass. Producers can still override (e.g. tfupdate treats "updates available" as a warning); this helper covers the common case.

func (ReportStatus) Valid added in v0.10.0 

func (s ReportStatus) Valid() bool

Valid reports whether the status is one of the supported CI report outcomes.

type ReportStore added in v0.10.5 

type ReportStore interface {
	ReportLoader
	ArtifactPublisher
}

ReportStore is the canonical producer/consumer boundary for CI reports. Memory stores support in-process exchange; file stores additionally persist artifacts using the canonical {producer}-report.json / {producer}-results.json filenames.

func NewFileReportStore added in v0.10.5 

func NewFileReportStore(serviceDir string) ReportStore

NewFileReportStore creates a report store backed by serviceDir. It also keeps an in-memory overlay for reports published by in-process plugins.

func NewMemoryReportStore added in v0.10.5 

func NewMemoryReportStore() ReportStore

NewMemoryReportStore creates an in-process report store.

Source Files

View all Source files

Directories

Path Synopsis
Package citest hosts test-only helpers for pkg/ci consumers and producers.
 Package citest hosts test-only helpers for pkg/ci consumers and producers.

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.