ci

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(opts ArtifactContextOptions) ArtifactContext

func (c ArtifactContext) Provenance() *ReportProvenance

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(opts ArtifactRunOptions) (ArtifactRun, error)

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 (img *Image) HasEntrypoint() bool

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

func (img *Image) String() string

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

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 (r *PlanResult) Get(name string) string

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 (c *PlanResultCollection) Fingerprint() string

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(hasChanges bool) PlanStatus

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 {
	Kind    RenderBlockKind `json:"kind"`
	Title   string          `json:"title,omitempty"`
	Text    string          `json:"text,omitempty"`
	Items   []string        `json:"items,omitempty"`
	Table   *RenderTable    `json:"table,omitempty"`
	Details *RenderDetails  `json:"details,omitempty"`
}

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

func RenderDetailsBlock(summary, body, language string) RenderBlock

func RenderListBlock(title string, items []string) RenderBlock

func RenderTableBlock(title string, columns []string, rows [][]string) RenderBlock

func RenderTextBlock(text string) RenderBlock

func (b RenderBlock) Validate() error

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

type RenderDetails struct {
	Summary  string `json:"summary"`
	Body     string `json:"body,omitempty"`
	Language string `json:"language,omitempty"`
}

RenderDetails is a collapsible detail block.

func (d RenderDetails) Validate() error

type RenderSection ¶ added in v0.10.5

type RenderSection struct {
	Blocks []RenderBlock `json:"blocks,omitempty"`
}

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

func DecodeRenderSection(section ReportSection) (RenderSection, error)

func (s RenderSection) Validate() error

type RenderTable ¶ added in v0.10.5

type RenderTable struct {
	Columns []string   `json:"columns"`
	Rows    [][]string `json:"rows,omitempty"`
}

RenderTable is an ordered table payload.

func (t RenderTable) Validate() error

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(path string) (*Report, error)

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

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.RenderTableBlock("Warnings", []string{"Module", "Message"}, [][]string{{"svc/prod/vpc", "tag missing"}}),
			},
		}},
	})
	if err != nil {
		panic(err)
	}

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

Output:
policy rendered

func (r *Report) Clone() *Report

func (r *Report) Validate() error

type ReportFreshness ¶ added in v0.10.5

type ReportFreshness struct {
	Status  ReportFreshnessStatus
	Warning string
}

ReportFreshness is the freshness decision for one report.

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

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(opts RenderedSectionOptions) (ReportSection, error)

func (s ReportSection) Clone() ReportSection

func (s ReportSection) Kind() ReportSectionKind

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

func (s ReportSection) Status() ReportStatus

func (s ReportSection) Summary() string

func (s ReportSection) Title() string

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

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"

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(collection *PlanResultCollection, reports []*Report, opts ReportSelectionOptions) ReportSelection

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(fail, warn int) ReportStatus

func (s ReportStatus) Valid() bool

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(serviceDir string) ReportStore

func NewMemoryReportStore() ReportStore