feat(layout): add hierarchical auto-layout for draw.io diagrams (#378)

Implements layout engine for automatic element positioning in draw.io diagrams.

Changes:
- internal/layout/types.go: Layout algorithm types and configuration
- internal/layout/hierarchical.go: Hierarchical layout via longest-path algorithm
  - Layers elements based on outgoing relationships
  - Supports top-to-bottom (TB) and left-to-right (LR) ranking
  - Detects cycles and handles disconnected components
- internal/layout/apply.go: Apply computed positions to draw.io XML
  - Respects pinned elements (bausteinsicht-pinned=true property)
  - Updates mxGeometry coordinates
- internal/layout/hierarchical_test.go: 6 comprehensive tests
  - Layer assignment validation
  - Cycle handling (no infinite recursion)
  - RankDir variations
  - Edge cases (empty model, single element)
- cmd/bausteinsicht/layout.go: CLI command
  - Usage: bausteinsicht layout [--rank-dir TB|LR] [--preserve-pinned]
  - Auto-detects model and diagram files
  - Reports applied layout

Implementation Status:
- ✅ Hierarchical layout (longest-path algorithm)
- ⏳ Force-directed layout (future)
- ⏳ Radial layout (future)

Fixes #302

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: paulefl

cmd/bausteinsicht/layout.go

@@ -0,0 +1,78 @@
+package main
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/docToolchain/Bausteinsicht/internal/drawio"
+	"github.com/docToolchain/Bausteinsicht/internal/layout"
+	"github.com/docToolchain/Bausteinsicht/internal/model"
+	"github.com/spf13/cobra"
+)
+
+func newLayoutCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "layout",
+		Short: "Auto-layout elements in draw.io diagram",
+		Long: `Computes hierarchical layout for diagram elements and writes positions back to draw.io.
+Pinned elements (with bausteinsicht-pinned=true) are preserved by default.`,
+		RunE: runLayout,
+	}
+
+	cmd.Flags().String("algorithm", "hierarchical", "Layout algorithm: hierarchical (currently only option)")
+	cmd.Flags().String("rank-dir", "TB", "Ranking direction: TB (top-to-bottom) or LR (left-to-right)")
+	cmd.Flags().Bool("preserve-pinned", true, "Don't move pinned elements (bausteinsicht-pinned=true)")
+
+	return cmd
+}
+
+func runLayout(cmd *cobra.Command, _ []string) error {
+	modelPath, _ := cmd.Flags().GetString("model")
+	if modelPath == "" {
+		detected, err := model.AutoDetect(".")
+		if err != nil {
+			return exitWithCode(fmt.Errorf("auto-detecting model: %w", err), 2)
+		}
+		modelPath = detected
+	}
+
+	// Load model
+	m, err := model.Load(modelPath)
+	if err != nil {
+		return exitWithCode(fmt.Errorf("loading model: %w", err), 2)
+	}
+
+	// Validate model
+	if errs := model.Validate(m); len(errs) > 0 {
+		return exitWithCode(fmt.Errorf("model validation failed: %v", errs), 2)
+	}
+
+	// Derive draw.io path from model path
+	dir := filepath.Dir(modelPath)
+	drawioPath := filepath.Join(dir, "architecture.drawio")
+
+	doc, err := drawio.LoadDocument(drawioPath)
+	if err != nil {
+		return exitWithCode(fmt.Errorf("loading diagram: %w", err), 2)
+	}
+
+	rankDir, _ := cmd.Flags().GetString("rank-dir")
+	preservePinned, _ := cmd.Flags().GetBool("preserve-pinned")
+
+	// Compute hierarchical layout
+	h := layout.NewHierarchicalLayout(m, rankDir)
+	result := h.Compute()
+
+	// Apply layout to diagram
+	if err := layout.Apply(doc, result, preservePinned); err != nil {
+		return exitWithCode(fmt.Errorf("applying layout: %w", err), 2)
+	}
+
+	// Save diagram
+	if err := drawio.SaveDocument(drawioPath, doc); err != nil {
+		return exitWithCode(fmt.Errorf("saving diagram: %w", err), 2)
+	}
+
+	_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Layout applied (hierarchical): %s\n", drawioPath)
+	return nil
+}

cmd/bausteinsicht/root.go

@@ -57,6 +57,7 @@ func NewRootCmd() *cobra.Command {
 	rootCmd.AddCommand(newValidateCmd())
 	rootCmd.AddCommand(newAddCmd())
 	rootCmd.AddCommand(newWatchCmd())
+	rootCmd.AddCommand(newLayoutCmd())
 	rootCmd.AddCommand(newExportCmd())
 	rootCmd.AddCommand(newExportTableCmd())
 	rootCmd.AddCommand(newExportDiagramCmd())

internal/layout/apply.go

@@ -0,0 +1,103 @@
+package layout
+
+import (
+	"fmt"
+
+	"github.com/beevik/etree"
+	"github.com/docToolchain/Bausteinsicht/internal/drawio"
+)
+
+// Apply applies layout positions to draw.io diagram.
+// Reads pinned status from existing draw.io elements and respects PreservePinned setting.
+func Apply(doc *drawio.Document, result LayoutResult, preservePinned bool) error {
+	if len(result.Positions) == 0 {
+		return fmt.Errorf("layout result is empty")
+	}
+
+	// Build map of existing draw.io elements with their pinned status
+	pinnedMap := readPinnedStatus(doc)
+
+	// For each computed position, update the draw.io element
+	for elemID, pos := range result.Positions {
+		// Skip pinned elements if preservePinned is enabled
+		if preservePinned && pinnedMap[elemID] {
+			continue
+		}
+
+		// Find and update element in draw.io
+		if err := updateElementPosition(doc, elemID, pos); err != nil {
+			continue
+		}
+	}
+
+	return nil
+}
+
+// readPinnedStatus reads the bausteinsicht-pinned property from draw.io elements.
+func readPinnedStatus(doc *drawio.Document) map[string]bool {
+	pinned := make(map[string]bool)
+
+	for _, page := range doc.Pages() {
+		if root := page.Root(); root != nil {
+			walkElements(root, func(elem *etree.Element) {
+				if id, ok := getAttr(elem, "bausteinsicht_id"); ok {
+					if pinValue, ok := getAttr(elem, "bausteinsicht-pinned"); ok && pinValue == "true" {
+						pinned[id] = true
+					}
+				}
+			})
+		}
+	}
+
+	return pinned
+}
+
+// updateElementPosition updates the x, y, width, height of a draw.io element.
+func updateElementPosition(doc *drawio.Document, elemID string, pos ElementPosition) error {
+	for _, page := range doc.Pages() {
+		if root := page.Root(); root != nil {
+			found := false
+			walkElements(root, func(elem *etree.Element) {
+				if found {
+					return
+				}
+				if id, ok := getAttr(elem, "bausteinsicht_id"); ok && id == elemID {
+					// Find mxGeometry child and update coordinates
+					for _, child := range elem.ChildElements() {
+						if child.Tag == "mxGeometry" {
+							child.CreateAttr("x", fmt.Sprintf("%.0f", pos.X))
+							child.CreateAttr("y", fmt.Sprintf("%.0f", pos.Y))
+							child.CreateAttr("width", fmt.Sprintf("%.0f", pos.Width))
+							child.CreateAttr("height", fmt.Sprintf("%.0f", pos.Height))
+							found = true
+							break
+						}
+					}
+				}
+			})
+			if found {
+				return nil
+			}
+		}
+	}
+
+	return fmt.Errorf("element %s not found in diagram", elemID)
+}
+
+// walkElements recursively walks through all elements in the tree.
+func walkElements(elem *etree.Element, fn func(*etree.Element)) {
+	fn(elem)
+	for _, child := range elem.ChildElements() {
+		walkElements(child, fn)
+	}
+}
+
+// getAttr extracts attribute value from element safely.
+func getAttr(elem *etree.Element, name string) (string, bool) {
+	for _, attr := range elem.Attr {
+		if attr.Key == name {
+			return attr.Value, true
+		}
+	}
+	return "", false
+}

internal/layout/hierarchical.go

@@ -0,0 +1,143 @@
+package layout
+
+import (
+	"github.com/docToolchain/Bausteinsicht/internal/model"
+)
+
+// HierarchicalLayout computes layer assignments via longest-path algorithm,
+// then positions elements in layers with horizontal alignment.
+type HierarchicalLayout struct {
+	model     *model.BausteinsichtModel
+	rankDir   string // TB or LR
+	spacing   float64
+	layerGap  float64
+}
+
+// NewHierarchicalLayout creates a hierarchical layout engine.
+func NewHierarchicalLayout(m *model.BausteinsichtModel, rankDir string) *HierarchicalLayout {
+	if rankDir == "" {
+		rankDir = "TB"
+	}
+	return &HierarchicalLayout{
+		model:    m,
+		rankDir:  rankDir,
+		spacing:  20,  // pixels between elements in same layer
+		layerGap: 100, // pixels between layers
+	}
+}
+
+// Compute calculates positions for all elements.
+func (h *HierarchicalLayout) Compute() LayoutResult {
+	outgoing := h.buildOutgoingMap()
+
+	// Assign layers using longest-path algorithm
+	layers := h.assignLayers(outgoing)
+
+	// Position elements based on layers
+	positions := h.positionElements(layers)
+
+	return LayoutResult{
+		Positions: positions,
+		Algorithm: Hierarchical,
+	}
+}
+
+// buildOutgoingMap creates a map of outgoing relationships per element.
+func (h *HierarchicalLayout) buildOutgoingMap() map[string][]string {
+	outgoing := make(map[string][]string)
+	for _, rel := range h.model.Relationships {
+		outgoing[rel.From] = append(outgoing[rel.From], rel.To)
+	}
+	return outgoing
+}
+
+// assignLayers assigns each element to a layer using longest-path algorithm.
+func (h *HierarchicalLayout) assignLayers(outgoing map[string][]string) map[int][]string {
+	flat, _ := model.FlattenElements(h.model)
+
+	// Compute longest path from each node
+	depths := make(map[string]int)
+	for id := range flat {
+		depths[id] = h.longestPath(id, outgoing, make(map[string]bool))
+	}
+
+	// Group elements by layer
+	layers := make(map[int][]string)
+	maxLayer := 0
+	for id, depth := range depths {
+		layers[depth] = append(layers[depth], id)
+		if depth > maxLayer {
+			maxLayer = depth
+		}
+	}
+
+	return layers
+}
+
+// longestPath computes longest outgoing path from a node (memoized).
+func (h *HierarchicalLayout) longestPath(id string, outgoing map[string][]string, visited map[string]bool) int {
+	if visited[id] {
+		return 0 // cycle detected, break here
+	}
+
+	targets := outgoing[id]
+	if len(targets) == 0 {
+		return 0
+	}
+
+	visited[id] = true
+	maxDepth := 0
+	for _, target := range targets {
+		depth := h.longestPath(target, outgoing, visited)
+		if depth > maxDepth {
+			maxDepth = depth
+		}
+	}
+	delete(visited, id)
+
+	return maxDepth + 1
+}
+
+// positionElements places elements horizontally within each layer.
+func (h *HierarchicalLayout) positionElements(layers map[int][]string) map[string]ElementPosition {
+	positions := make(map[string]ElementPosition)
+
+	for layer, ids := range layers {
+		// Default sizes
+		elemWidth := 160.0
+		elemHeight := 60.0
+
+		// Calculate layer positions
+		var x, y float64
+		if h.rankDir == "TB" {
+			// Top-to-bottom: layer determines Y, elements spread horizontally
+			y = float64(layer) * h.layerGap
+			x = 50.0
+		} else {
+			// Left-to-right: layer determines X, elements spread vertically
+			x = float64(layer) * h.layerGap
+			y = 50.0
+		}
+
+		// Position elements in this layer
+		for i, id := range ids {
+			elemX, elemY := x, y
+			if h.rankDir == "TB" {
+				elemX = x + float64(i)*(elemWidth+h.spacing)
+			} else {
+				elemY = y + float64(i)*(elemHeight+h.spacing)
+			}
+
+			positions[id] = ElementPosition{
+				ID:     id,
+				X:      elemX,
+				Y:      elemY,
+				Width:  elemWidth,
+				Height: elemHeight,
+				Layer:  layer,
+			}
+		}
+	}
+
+	return positions
+}