Documentation
¶
Overview ¶
Package visualize builds a render-agnostic view of a cascade pipeline and emits it as a diagram. The view model carries no diagram syntax; concrete Emitter implementations (Mermaid is the first) turn it into renderer-specific source. The separation keeps the projection independently testable and lets a richer renderer be added later without reshaping the model.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultTheme = Theme{Name: "default"}
DefaultTheme is the neutral theme used when a caller does not supply one.
Functions ¶
This section is empty.
Types ¶
type Edge ¶
Edge is one dependency from a job to one of its dependencies. From is the dependent job ID, To is the job it depends on, and Kind separates hard from optional dependencies.
type EdgeKind ¶
type EdgeKind string
EdgeKind classifies a dependency edge. Hard edges come from Edges (they both order a job and skip-gate it); optional edges come from OptionalEdges (they order only). Emitters render the two with visually distinct styling so a reader can tell a blocking dependency from an ordering-only one.
type Emitter ¶
type Emitter interface {
// Emit renders vm using theme and any options, returning the diagram source.
// It returns an error only when the model cannot be expressed as valid
// source; a well-formed model always emits successfully.
Emit(vm ViewModel, theme Theme, opts ...Option) (string, error)
}
Emitter turns a render-agnostic ViewModel into diagram source. It is the pluggable seam of the package: Mermaid is the first implementation, and a future renderer is added by writing another Emitter without touching the view model. Required inputs (the model and a theme) are positional; optional behavior arrives as a variadic Option tail.
type MermaidEmitter ¶
type MermaidEmitter struct{}
MermaidEmitter renders a ViewModel as Mermaid flowchart source that GitHub renders natively in Markdown. It is the first concrete Emitter. Output is deterministic: it ranges the model's ordered slices and never iterates a map, so the same model always yields byte-identical source.
func NewMermaidEmitter ¶
func NewMermaidEmitter() *MermaidEmitter
NewMermaidEmitter returns a ready MermaidEmitter. The type is stateless, so the constructor exists only to give callers a stable construction point.
func (MermaidEmitter) Emit ¶
Emit renders vm as a top-down Mermaid flowchart. Nodes are declared first in model order with class-tagged shapes per kind, then hard edges (solid arrows) and optional edges (dotted arrows) in model order, so the two dependency kinds are visually distinct. theme is accepted for interface conformance and future styling; the current output does not vary by theme. A title option, if set, is emitted as a Mermaid title in the frontmatter block.
type Node ¶
Node is one pipeline job in the view. ID is the stable, prefixed job ID (validate, build-app, deploy-app) used as the diagram node identity. Label is the human-facing display name. Kind drives styling.
type NodeKind ¶
type NodeKind string
NodeKind classifies a pipeline node for rendering. The set mirrors the callback types cascade already models (validate, build, deploy). It is a rendering hint only; an emitter may map several kinds to one visual style.
type Option ¶
type Option func(*Options)
Option configures emit behavior. Following the repo convention, required inputs are positional on Emit and optional behavior arrives as a variadic Option tail, so capabilities can be added without changing the signature.
type Options ¶
type Options struct {
// Title, when set, is rendered as a diagram heading by emitters that
// support one. An empty title emits no heading.
Title string
}
Options holds optional emit behavior. It is populated by the functional Option tail rather than constructed directly, so new knobs are additive. The zero value is valid and selects each emitter's defaults.
type Theme ¶
type Theme struct {
// Name identifies the theme. The zero value selects the emitter's built-in
// default, so callers that do not care about theming pass DefaultTheme.
Name string
}
Theme carries presentation choices an emitter may honor. It is a stub in this iteration (a default value is threaded through every emit path); later work fills it with concrete styling slots. Keeping it in the signature now means adding fields later is additive, never a breaking change.
type ViewModel ¶
ViewModel is the deterministic, render-agnostic description of a pipeline's job DAG. Nodes follow manifest declaration order (the graph's Order seed) and edges follow node order then dependency-list order, so two builds of the same manifest produce byte-identical emitter output. The model holds no diagram syntax.
func BuildViewModel ¶
func BuildViewModel(g *generate.DependencyGraph) (ViewModel, error)
BuildViewModel projects a generated DependencyGraph into a render-agnostic ViewModel. It walks the graph in Order (the same deterministic seed TopologicalSort uses) so node and edge slices are stable run to run, and it rejects a cyclic graph by surfacing the cycle TopologicalSort detects rather than emitting a malformed diagram. The returned model depends only on the cascade model and carries no Mermaid (or other) syntax.
Source Files