formatters

type Formatter interface {
	// Format converts a dependency graph to a formatted string representation.
	Format(g depgraph.FileDependencyGraph, opts RenderOptions) (string, error)
	// GenerateURL creates a shareable URL for the formatted output.
	// Returns the URL and true if supported, or ("", false) if not.
	GenerateURL(output string) (string, bool)
}

type GraphDirection string

type GraphHeader struct {
	// Orientation is the resolved layout direction (already defaulted).
	Orientation GraphDirection
	// Title is an optional graph label/title; empty when unset.
	Title string
	// TrailingNewline records whether the layout direction was set explicitly,
	// which both formatters use to decide a trailing newline.
	TrailingNewline bool
}

type NodeKind int

type OutputFormat int

type RenderOptions struct {
	// Label is an optional title or label for the graph output.
	Label string
	// Direction is the layout direction for the graph.
	Direction GraphDirection
	// BasePath is an optional filesystem base used to derive stable relative node IDs.
	BasePath string
	// EdgeLabels enables deterministic short labels on edges.
	EdgeLabels bool
}

type Renderer interface {
	// Begin emits the graph header/preamble from the resolved header primitive.
	Begin(GraphHeader)
	// OpenCluster begins a labeled boundary; the member node declarations that
	// follow are drawn inside it until CloseCluster.
	OpenCluster(SceneCluster)
	// CloseCluster ends the boundary opened by OpenCluster.
	CloseCluster()
	// Finish emits any trailer and returns the complete output.
	Finish() (string, error)
}

type Scene struct {
	Header GraphHeader
	// FilePaths are the graph's node keys, sorted for deterministic output.
	FilePaths []string
	// NodeNames maps each node key to its display name.
	NodeNames map[string]string
	// CycleNodes is the set of nodes that participate in a dependency cycle.
	CycleNodes map[string]bool
	// Nodes holds the resolved presentation for each graph node, keyed by node
	// key. Built once here so both formatters render identical content.
	Nodes map[string]SceneNode
	// Edges are the dependency edges in deterministic render order.
	Edges []SceneEdge
	// Cluster, when set, is the labeled module boundary to draw around its
	// member nodes; nil when no boundary is rendered.
	Cluster *SceneCluster
	// MajorityType is the most common file type; nodes of this type render
	// neutral rather than type-colored.
	MajorityType string
	// HasMultipleTypes is true when more than one file type is present.
	HasMultipleTypes bool
}

type SceneCluster struct {
	Name    string
	Members []string
}

type SceneEdge struct {
	From string
	To   string
	// State is the edge's lifecycle: present, deleted, or renamed.
	State depgraph.EdgeState
	// InCycle marks an edge that participates in a dependency cycle.
	InCycle bool
	// Labels are the underlying dependency labels, used when edge labels are on
	// (a collapsed module edge keeps one labeled arrow per original dependency).
	Labels []string
}

type SceneNode struct {
	Key        string
	Name       string
	LabelLines []string
	// Type is the file type: its extension, or its base name when extensionless.
	Type string
	// Kind is what the node fundamentally is: a regular file, a test file, or a
	// collapsed module. These are mutually exclusive.
	Kind NodeKind
	// State is the node's lifecycle: present, deleted, or renamed.
	State depgraph.FileState
	// IsPruned marks a node whose subtree was elided — orthogonal to Kind.
	IsPruned bool
	// InCycle marks a node in a dependency cycle — orthogonal to Kind.
	InCycle bool
	// Phantom describes the node's test-sibling, or nil when it has none.
	Phantom *depgraph.PhantomMetadata
}