ci

package
v0.10.6 Latest Latest
Warning

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

 Go to latest Published: May 29, 2026 License: MIT Imports: 14 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 PublishArtifacts added in v0.10.5 

func PublishArtifacts(ctx context.Context, req PublishArtifactsRequest) error

PublishArtifacts persists raw producer results and replaces the matching render-ready report. Raw results are always passed to the writer. If report construction fails or returns nil, a nil report is written so stale report artifacts for the producer are removed.

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 {
	ServiceDir             string
	WorkDir                string
	CommitSHA              string
	PipelineID             string
	PlanResultsFingerprint string
	GeneratedAt            time.Time
}

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) Provenance added in v0.10.5 

func (c ArtifactContext) Provenance() *ReportProvenance

Provenance converts the artifact context into persisted report provenance.

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 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 ArtifactRun added in v0.10.5 

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

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.

type ArtifactRunOptions added in v0.10.5 

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

ArtifactRunOptions describes how to construct an ArtifactRun.

type ArtifactWriter added in v0.10.5 

type ArtifactWriter interface {
	SaveResults(ctx context.Context, producer string, results any) error
	ReplaceResultsAndReport(ctx context.Context, producer string, results any, report *Report) error
}

ArtifactWriter persists producer result/report artifacts.

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 {
	ModuleID          string            `json:"module_id"`
	ModulePath        string            `json:"module_path"`
	Components        map[string]string `json:"components,omitempty"`
	Status            PlanStatus        `json:"status"`
	Summary           string            `json:"summary"`
	StructuredDetails string            `json:"structured_details,omitempty"`
	RawPlanOutput     string            `json:"raw_plan_output,omitempty"`
	Error             string            `json:"error,omitempty"`
	ExitCode          int               `json:"exit_code,omitempty"`
	Duration          time.Duration     `json:"duration,omitempty"`
}

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

func (*PlanResult) Get 

func (r *PlanResult) Get(name string) string

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

type PlanResultCollection 

type PlanResultCollection struct {
	Results     []PlanResult `json:"results"`
	PipelineID  string       `json:"pipeline_id,omitempty"`
	CommitSHA   string       `json:"commit_sha,omitempty"`
	GeneratedAt time.Time    `json:"generated_at"`
}

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

func (*PlanResultCollection) Fingerprint added in v0.10.0 

func (c *PlanResultCollection) Fingerprint() string

Fingerprint returns a stable content fingerprint for the collection.

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.

type PublishArtifactsRequest added in v0.10.5 

type PublishArtifactsRequest struct {
	Producer    string
	Writer      ArtifactWriter
	Results     any
	BuildReport ArtifactReportBuilder
}

PublishArtifactsRequest describes one canonical producer artifact write.

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 {
	Producer   string            `json:"producer"`
	Title      string            `json:"title"`
	Status     ReportStatus      `json:"status"`
	Summary    string            `json:"summary"`
	Provenance *ReportProvenance `json:"provenance,omitempty"`
	Sections   []ReportSection   `json:"sections,omitempty"`
}

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) Validate added in v0.10.0 

func (r *Report) Validate() error

Validate verifies the persisted report artifact contract.

type ReportFreshness added in v0.10.5 

type ReportFreshness struct {
	Status  ReportFreshnessStatus
	Warning string
}

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.

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 ReportProvenance added in v0.10.0 

type ReportProvenance struct {
	GeneratedAt            time.Time `json:"generated_at"`
	CommitSHA              string    `json:"commit_sha,omitempty"`
	PipelineID             string    `json:"pipeline_id,omitempty"`
	PlanResultsFingerprint string    `json:"plan_results_fingerprint,omitempty"`
}

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.

type ReportPublisher added in v0.10.5 

type ReportPublisher interface {
	Publish(report *Report)
	SaveReport(ctx context.Context, report *Report) error
}

ReportPublisher publishes renderer-ready producer reports.

type ReportReader added in v0.10.5 

type ReportReader interface {
	Get(producer string) (*Report, bool)
	All() []*Report
	LoadReports(ctx context.Context) ([]*Report, error)
}

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

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 {
	Reports  []*Report
	Warnings []string
}

ReportSelection is the canonical selected-report result for consumers.

func SelectCurrentReports added in v0.10.5 

func SelectCurrentReports(collection *PlanResultCollection, reports []*Report, 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.

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 {
	ReportPublisher
	ReportReader
	ArtifactWriter
}

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.