archsight 0.5.4 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 540f7640d06327e62c658d9bff6cb9e60475f10c63a36ba541170c8ca3077ef1
-  data.tar.gz: 8cfbe67e126f99e743e45935527b034f980531979ef76ee54295b81e7b27bbdc
+  metadata.gz: c8c3016b6533ac9d58b36bbf89d5bb34b6f62abe9579bd091f22e735b53cf3c9
+  data.tar.gz: 00e6854efc963f6c8916b0b16f8ffd2d4462ab5ccd6e2f84b1eb1d906e479d2a
 SHA512:
-  metadata.gz: 185739ca5a2c52b6c4e1df7ab29f58772908df3bc5bcb53452b7b2114e042ea2a62624fa5d2254c088a36bd2118b3daa81c48eb4b475aa76308ecbe0b32737e4
-  data.tar.gz: 32384cbe603e19c21e2bdc661979777aeba42e8faeb2a97e88479320bf31fc844ba42c995d11fc316711e9609ab7197a052aa914a74b6808e1cebd6b5cda5a75
+  metadata.gz: 9dbeaf9d8f3adf87ee96139436a145e888fbde2ac09feedfe7ddc3835583aa3a5e9d37c7a9e768ba7bb2e44935d2e81723d55af8cc0af7cd0531a0389689162e
+  data.tar.gz: 21d812087816f97bd171e5cdc30aea5ca81fec27ecab2e677817081305a721000a2ac604429c0be78d59170ed21ec01a79aa9f54492986ea81ce3e99ff5fd66f

data/docs/diagram.md

@@ -153,18 +153,25 @@ hint for near misses), never silently ignored.
 | `resource` | nodes, containers | a resource name (`Archsight:Web`) or `Kind/Name` (`ApplicationService/Archsight:Web`); see *Linking to resources* |
 | `extend` | nodes, containers | `true`, `false`; containers also `height`, and `width` on a direct child of a `layer` |
 | `width` | `text` | characters per line (positive integer); wraps the label |
-| `anchor` | containers | `top`, `bottom`, `left`, `right`, `center` |
+| `anchor` | containers; leaves with `no-extend` | `top`, `bottom`, `left`, `right`, `center` |
+| `badge` | nodes, ports | the id of a top-level `badge` definition (see *Badges and line styles*) |
+| `legend` | nodes, containers | the text of the node's tint row in the legend (see *Legend*) |
+| `align` | nodes, containers | `[edge] id` of another node to line up with, e.g. `top worker`; up to one horizontal and one vertical entry, comma-separated (see *Aligning across containers*) |
 
 `extend "height"` on a direct child of a `layer` grows it to its tallest sibling. Inside such a box (also through a `boundary` around a `stack`), a `stack` child carrying `extend "height"` takes the extra height and moves the ranks below it down, so e.g. a footer rank lines up across the columns. The child can be a `layer` too; its own `extend "height"` children then fill the layer's new height.
 
 `extend "width"` is the same for the other axis. When a `layer` is made wider than its content (for example it sits in a `stack` next to a wider sibling), its children normally stay together as one block placed by `anchor`. A direct child of the layer with `extend "width"` instead takes the spare width and pushes the siblings after it to the right edge, so `main` can sit at the left edge and `aside` at the right edge, and the `aside` columns line up across stacked layers. Several children with `extend "width"` share the spare width equally. The child's own content stays at its `anchor` (`left` by default) at its natural size. The attribute is an error anywhere but on a direct child of a `layer`; edges to boxes inside the pushed siblings follow their new positions.
 
 `anchor` says where a container's content sits when its box grows: `bottom` (or `top`) when it is made taller, `right` (or `left`) when it is made wider, `center` for the middle. Default: top for `extend "height"`, left for `extend "width"`, centered otherwise. It is not inherited, and has no effect on a box whose room is taken by a stack child with `extend "height"`.
+
+`no-extend` on a leaf keeps it at its own size inside a wider `stack` (which otherwise stretches every rank to the widest one), centered there; `anchor "left"`/`"right"` puts it at that edge instead (an error without `no-extend`).
 | `shape` | leaves | `rectangle`, `circle`, `cylinder`, `pipe`, `actor`, `file`, `module` |
 | `gap` | containers | pixels (`40`), a percentage (`150%`) or a signed one (`+20%`, `-50%`) |
+| `padding` | containers | the room between the box and its content, same values as `gap` (default: the theme's) |
 | `ranks` | containers | `auto`, `on`, `down`, `right`, `off` |
 | `columns` | containers | a positive integer |
 | `style` | edges | `straight`, `orthogonal` |
+| `line` | edges | `solid` (default), `dashed`, `dotted`: the stroke only, the relation keeps its arrowhead |
 | `relation` | edges | `dependency`, `implements`, `control`, `data` |
 | `color` | dataflows | a hex color such as `#1a56db` |
 
@@ -182,8 +189,10 @@ empty id, and an edge from a node to itself are errors too.
 Any label anywhere (node, container, edge, dataflow) supports:
 
 - A small inline markdown-lite: `**bold**`, `*italic*`, `__underline__`,
-  and `[text](url)` for a link on just that run of text (independent of
-  a node-level `link` — a label can have both, or just one).
+  `` `code` `` (monospace, for commands, file names and ports), and
+  `[text](url)` for a link on just that run of text (independent of
+  a node-level `link` — a label can have both, or just one). Runs don't
+  nest: `` **`x`** `` shows the backticks.
 - Multi-line text, written either with an explicit `\n` escape
   (`label "Line one\nLine two"`) or by literally spanning multiple lines
   in the source; in the latter case each line's leading/trailing
@@ -214,6 +223,89 @@ Edge attributes:
   you pass `--relation=`, though layout always accounts for every edge
   regardless of what's shown.
 
+### Ports
+
+A port is a small labelled tab on a leaf's border -- a TCP port, a socket,
+a file a process listens on -- that edges attach to instead of the leaf as a
+whole. Declare it inside the leaf and name it in an edge as `leaf.port`:
+
+```
+component "mgr" {
+  label "**manager**"
+  port "tcp"  { label "tcp :8075"; side "top" }
+  port "sock" { label "unix mgr.sock"; side "top"; badge "beta" }
+}
+client -> mgr.tcp { label "requests" }
+agent -> mgr.sock
+mgr.sock -> logger
+```
+
+- `label` is drawn in monospace (default: the id), `side` is `top`,
+  `bottom`, `left` or `right`, `at` is `left`, `center`, `right` (`top`,
+  `center`, `bottom` on a left/right side) or a percentage of the side
+  (`25%`), and `badge` names a badge (see below).
+- Without `side`, the port goes on the side facing what its edges connect
+  it to (`top` without edges). Without `at`, it slides along its side to
+  line up with what its edges connect it to (the mean of their centers),
+  unless that spans the whole side; ports without a preference share the
+  side evenly in declaration order. Tabs on one side never overlap.
+- The leaf grows to hold its tabs, and a `stack` leaves room between two
+  ranks for tabs sticking out of the sides they face.
+- An edge to a port ends on the tab's outer side and never runs through
+  its own leaf; several edges on one tab are spread over it. Tabs are
+  obstacles to every other line, so no line ends on top of one.
+- Ports need a box-shaped leaf (`rectangle`, `file`, `module` shapes). A
+  port id is local to its leaf and has no `.`. `leaf.port` resolves to a
+  node with that whole id first (ids of a namespaced include contain dots),
+  and an unknown port is an error listing the leaf's ports. Dataflow hops
+  name nodes, not ports.
+
+### Badges and line styles
+
+Top-level definitions give the legend its text for a marker:
+
+```
+badge "beta" { tint "orange"; label "beta channel only" }
+line "dashed" { label "read only at start" }
+
+component "agent" { badge "beta" }
+config -> mgr { line "dashed"; label "read at start" }
+```
+
+- `badge "id" { tint; label }` defines a dot that nodes and ports carry
+  with `badge "id"` (inside a node's top-right corner, at a port tab's right
+  end). Each badge used gets a legend row.
+- `line "dashed" { label }` (or `"dotted"`) gives that line style its
+  legend row; without the definition, `line "dashed"` edges still draw
+  dashed but have no row. A diagram with ports gets a "Port" row.
+- An included diagram's definitions count at the top level; the same
+  definition twice is fine, two different ones with one id are an error.
+  Inside a container-level include they are ignored with a warning.
+
+### Aligning across containers
+
+`align "<edge> other"` moves a node (or container) until that edge of it
+lines up with the same edge of `other`, which may sit in a different
+container -- like the align buttons of a drawing editor:
+
+| edge | lines up |
+|---|---|
+| `left`, `center`, `right` | the left edges, centers, right edges (horizontally) |
+| `top`, `middle`, `bottom` | the top edges, centers, bottom edges (vertically) |
+
+A bare id means `center` (`align "api"` puts a node under `api`).
+One horizontal and one vertical entry can be combined with a comma:
+`align "left db, top worker"`.
+
+It only uses the room its container already has and never grows one.
+Where the container packs along that axis (a `layer` for left/right, a
+`stack` for up/down) the node's siblings keep their order and are pushed
+along only when they would come closer than the sibling gap (plus half a
+port tab on each facing side); elsewhere the node moves within its
+container's inner box (an anonymous `layer`/`stack` lends it the room of
+its own container on its packing axis). It stops as close as it gets. A
+leaf a `stack` stretches has no room to move sideways; give it `no-extend`.
+
 ### Dataflows
 
 `dataflow "id" { hop "..."; hop "..."; ...; color "#hex"; label "..." }`
@@ -269,7 +361,12 @@ isn't affected.
 ### Legend
 
 A legend is added automatically, listing only the shapes, relations,
-boundary styles and dataflows actually used. It's left out entirely for a
+boundary styles, dataflows, ports, badges and defined line styles actually used.
+A tint set on a leaf gets a row named after the leaves carrying it (the first
+line of each label, without markup, joined with commas), or by the `legend`
+text of one of them; a tint whose leaves all sit inside a container of the
+same tint gets none, the container's row explains it. A tinted container's
+row reads `Boundary <label>` (or `Group <label>`), unless it has a `legend` text. It's left out entirely for a
 plain diagram of components and dependency edges.
 
 It's laid out like the rest of the drawing: a `layer` of `stack`s (its

data/lib/archsight/diagram/graph/attributes.rb

@@ -24,15 +24,25 @@ module Archsight
       # container. Keep these tables in step with the readers in
       # `Graph::Node`/`Graph::Edge`/`Graph::DataFlow` and with `docs/diagram.md`.
       module Attributes
-        NODE = %w[label tint link resource extend].freeze
+        NODE = %w[label tint link resource extend badge align legend].freeze
         LEAF_KINDS = %i[component application api database queue actor file text].freeze
-        LEAF = (NODE + %w[shape]).freeze
+        # `anchor` places a leaf that keeps its own size (`extend "false"`) inside a wider stack.
+        LEAF = (NODE + %w[shape anchor]).freeze
         # A `text` has no box to restyle (no `shape`), but may wrap at `width` characters.
         TEXT = (NODE + %w[width]).freeze
         WIDTH_FORMAT = /\A[1-9]\d*\z/
-        CONTAINER = (NODE + %w[gap ranks columns anchor]).freeze
-        EDGE = %w[label style relation tint].freeze
+        CONTAINER = (NODE + %w[gap padding ranks columns anchor]).freeze
+        EDGE = %w[label style relation tint line].freeze
         DATAFLOW = %w[label color].freeze
+        PORT = %w[label side at badge].freeze
+        BADGE_DEFINITION = %w[label tint].freeze
+        LINE_DEFINITION = %w[label].freeze
+
+        LINE_STYLES = %w[solid dashed dotted].freeze
+        PORT_SIDES = %w[top bottom left right].freeze
+        # A named spot on the port's side, or a percentage of its length (from the left or top).
+        PORT_AT = /\A(left|center|right|top|bottom|(100|[1-9]?\d)(\.\d+)?%)\z/
+        PORT_SHAPES = %w[rectangle file module].freeze
 
         EDGE_STYLES = %w[straight orthogonal].freeze
         LEAF_EXTEND = %w[true false].freeze
@@ -73,10 +83,53 @@ module Archsight
             when "style" then check_value!(key, value, EDGE_STYLES, where, ast_edge.line)
             when "relation" then check_value!(key, value, Relations.names, where, ast_edge.line)
             when "tint" then check_value!(key, value, Tints.names, where, ast_edge.line)
+            when "line" then check_value!(key, value, LINE_STYLES, where, ast_edge.line)
+            end
+          end
+        end
+
+        # A port's attrs, and that its leaf has a box shape to put a tab on.
+        def check_port!(ast_port, node)
+          where = "port #{ast_port.id.inspect} of #{node.kind} #{node.id.inspect}"
+          unless node.leaf? && node.kind != :text && PORT_SHAPES.include?(node.shape)
+            raise GraphError, "#{where} (line #{ast_port.line}): ports need a box-shaped leaf (shape #{PORT_SHAPES.join(", ")}), " \
+                              "not #{node.kind == :text ? "a text" : "shape #{node.shape.inspect}"}"
+          end
+
+          ast_port.attrs.each do |key, value|
+            check_name!(key, PORT, where, ast_port.line)
+            case key
+            when "label" then check_label!(value, where, ast_port.line)
+            when "side" then check_value!(key, value, PORT_SIDES, where, ast_port.line)
+            when "at" then check_port_at!(value, ast_port.attrs["side"], where, ast_port.line)
             end
           end
         end
 
+        def check_port_at!(value, side, where, line)
+          check_format!("at", value, PORT_AT, "left, center, right, top, bottom or a percentage (25%)", where, line)
+          along = side.nil? || %w[top bottom].include?(side) ? %w[left right] : %w[top bottom]
+          return unless (%w[left right top bottom] - along).include?(value)
+
+          raise GraphError, "at #{value.inspect} on #{where} (line #{line}) does not lie along its #{side || "top"} side; expected #{along.join(", ")}, center or a percentage"
+        end
+
+        # A top-level `badge`/`line` definition.
+        def check_definition!(definition)
+          where = "#{definition.kind} #{definition.id.inspect}"
+          allowed = definition.kind == :badge ? BADGE_DEFINITION : LINE_DEFINITION
+          if definition.kind == :line && !(LINE_STYLES - ["solid"]).include?(definition.id)
+            raise GraphError, "unknown line style #{definition.id.inspect} (line #{definition.line}); expected dashed or dotted" \
+                              "#{suggestion(definition.id, LINE_STYLES - ["solid"])}"
+          end
+
+          definition.attrs.each do |key, value|
+            check_name!(key, allowed, where, definition.line)
+            check_label!(value, where, definition.line) if key == "label"
+            check_value!(key, value, Tints.names, where, definition.line) if key == "tint"
+          end
+        end
+
         # A dataflow's own attrs and each of its branches'.
         def check_dataflow!(ast_dataflow)
           where = "dataflow #{ast_dataflow.id.inspect}"
@@ -119,13 +172,13 @@ module Archsight
         def check_node_value!(key, value, block, where, ranks_modes)
           line = block.line
           case key
-          when "label" then check_label!(value, where, line)
+          when "label", "legend" then check_label!(value, where, line)
           when "shape" then check_value!(key, value, Representers.names, where, line)
           when "tint" then check_value!(key, value, Tints.names, where, line)
           when "ranks" then check_value!(key, value, ranks_modes, where, line)
           when "extend" then check_value!(key, value, leaf?(block) ? LEAF_EXTEND : CONTAINER_EXTEND, where, line)
           when "anchor" then check_value!(key, value, ANCHORS, where, line)
-          when "gap" then check_format!(key, value, GAP_FORMAT, "a pixel count (40), a percentage (150%) or a signed one (+20%, -50%)", where, line)
+          when "gap", "padding" then check_format!(key, value, GAP_FORMAT, "a pixel count (40), a percentage (150%) or a signed one (+20%, -50%)", where, line)
           when "width" then check_format!(key, value, WIDTH_FORMAT, "a positive number of characters per line", where, line)
           when "link" then check_link!(value, where, line)
           when "resource" then check_resource!(value, block, where, line)

data/lib/archsight/diagram/graph/builder.rb

@@ -10,6 +10,9 @@ module Archsight
         raise GraphError, "#{block.kind} has an empty id (line #{block.line})" if block.id.strip.empty?
 
         Attributes.check_node!(block, ranks_modes: RANKS_MODES)
+        if Attributes.leaf?(block) && block.attrs.key?("anchor") && block.attrs["extend"] != "false"
+          raise GraphError, "anchor on #{block.kind} #{block.id.inspect} (line #{block.line}) only places a leaf that keeps its own size: add no-extend"
+        end
         raise GraphError, "extend \"width\" on #{block.kind} #{block.id.inspect} (line #{block.line}) only applies to a direct child of a layer" if block.attrs["extend"] == "width" && !parent&.layer?
 
         node = Node.for(id: block.id, kind: block.kind, attrs: block.attrs, children: [], parent: parent,
@@ -22,12 +25,82 @@ module Archsight
             node.children << build_node(child, node, raw_edges)
           when AST::Edge
             raw_edges << child
+          when AST::Port
+            add_port(node, child)
           end
         end
 
         node
       end
 
+      def add_port(node, ast_port)
+        Attributes.check_port!(ast_port, node)
+        if (first = node.port(ast_port.id))
+          raise GraphError, "duplicate port #{ast_port.id.inspect} on #{node.id.inspect} (line #{ast_port.line}, first defined at line #{first.line})"
+        end
+
+        node.ports << Port.new(id: ast_port.id, node: node, attrs: ast_port.attrs, line: ast_port.line)
+      end
+
+      # A top-level `badge "id" { ... }` / `line "dashed" { ... }`: each id once per kind.
+      def add_definition(ast_definition)
+        Attributes.check_definition!(ast_definition)
+        key = [ast_definition.kind, ast_definition.id]
+        if (first = @definitions[key])
+          return if first.attrs == ast_definition.attrs # the same definition, e.g. from two included diagrams
+
+          raise GraphError, "#{ast_definition.kind} #{ast_definition.id.inspect} already defined at line #{first.line} (line #{ast_definition.line})"
+        end
+
+        @definitions[key] = Definition.new(kind: ast_definition.kind, id: ast_definition.id, attrs: ast_definition.attrs, line: ast_definition.line)
+      end
+
+      # `badge "id"` on nodes and ports names a definition, `align "id"` another node.
+      def check_references!
+        @nodes_by_id.each_value do |node|
+          check_badge!(node.badge, "#{node.kind} #{node.id.inspect}", node.line) if node.badge
+          node.ports.each { |port| check_badge!(port.badge, "port #{port.ref.inspect}", port.line) if port.badge }
+          check_align!(node) if node.align
+        end
+      end
+
+      def check_badge!(id, where, line)
+        return if @definitions.key?([:badge, id])
+
+        known = @definitions.values.select { |d| d.kind == :badge }.map(&:id)
+        hint = known.empty? ? " (define it at the top level: badge #{id.inspect} { tint \"orange\"; label \"...\" })" : Attributes.suggestion(id, known)
+        raise GraphError, "unknown badge #{id.inspect} on #{where} (line #{line})#{hint}"
+      end
+
+      def check_align!(node)
+        where = "#{node.kind} #{node.id.inspect} (line #{node.line})"
+        entries = node.alignments
+        raise GraphError, "align #{node.align.inspect} on #{where} has an empty entry" if entries.any? { |_, _, id| id.empty? }
+
+        entries.group_by(&:first).each_value do |same_axis|
+          next if same_axis.length == 1
+
+          raise GraphError, "align #{node.align.inspect} on #{where} lines up #{same_axis.map { |_, e, _| e }.join(" and ")} on one axis; " \
+                            "use one of left/center/right and one of top/middle/bottom"
+        end
+        entries.each { |_, _, id| check_align_target!(node, id, where) }
+      end
+
+      def check_align_target!(node, id, where)
+        target = @nodes_by_id[id]
+        unless target
+          word, rest = id.split(/\s+/, 2)
+          if rest
+            raise GraphError, "unknown edge #{word.inspect} in align #{node.align.inspect} on #{where}; expected one of " \
+                              "#{Node::ALIGN_EDGES.keys.join(", ")}#{Attributes.suggestion(word, Node::ALIGN_EDGES.keys)}"
+          end
+          raise GraphError, "align #{node.align.inspect} on #{where} names no node #{id.inspect}#{Attributes.suggestion(id, @nodes_by_id.keys)}"
+        end
+        return unless target.ancestors.include?(node) || node.ancestors.include?(target)
+
+        raise GraphError, "align #{node.align.inspect} on #{where} names #{target == node ? "the node itself" : "a node it is nested with"}"
+      end
+
       # A top-level `theme "..."`/`legend "..."` statement: each may appear
       # once, with one of its own allowed values.
       def apply_setting(setting)
@@ -49,13 +122,38 @@ module Archsight
       end
 
       def resolve_edge(ast_edge)
-        from = node(ast_edge.from)
-        to = node(ast_edge.to)
-        Edge.new(from: from, to: to, attrs: ast_edge.attrs, direction: ast_edge.direction, line: ast_edge.line)
+        from, from_port = endpoint(ast_edge.from)
+        to, to_port = endpoint(ast_edge.to)
+        raise GraphError, "connects #{from.id.inspect} to itself, which has no line to draw" if from == to
+
+        Edge.new(from: from, to: to, attrs: ast_edge.attrs, direction: ast_edge.direction, line: ast_edge.line,
+                 from_port: from_port, to_port: to_port)
       rescue GraphError => e
         raise GraphError, "#{e.message} (edge at line #{ast_edge.line})"
       end
 
+      # An edge end: a node id, or `node.port` when no node has that whole id (namespaced ids contain dots too).
+      def endpoint(ref)
+        return [@nodes_by_id[ref], nil] if @nodes_by_id.key?(ref)
+
+        owner = port_owner(ref)
+        return [node(ref), nil] unless owner
+
+        port_id = ref.delete_prefix("#{owner.id}.")
+        port = owner.port(port_id)
+        return [owner, port] if port
+
+        known = owner.ports.map(&:id)
+        listed = known.empty? ? "it has no ports" : "its ports: #{known.join(", ")}"
+        raise GraphError, "unknown port #{port_id.inspect} on #{owner.id.inspect} (#{listed})#{Attributes.suggestion(port_id, known)}"
+      end
+
+      # The node `node.port` names, `nil` if the part before the last dot is no node
+      def port_owner(ref)
+        owner_id, dot, = ref.rpartition(".")
+        dot.empty? ? nil : @nodes_by_id[owner_id]
+      end
+
       def resolve_dataflow(ast_dataflow)
         group_index = ast_dataflow.hops.index { |h| h.is_a?(AST::DataFlowGroup) }
 

data/lib/archsight/diagram/graph/edge.rb

@@ -3,7 +3,8 @@
 module Archsight
   module Diagram
     class Graph
-      Edge = Struct.new(:from, :to, :attrs, :direction, :line, keyword_init: true) do
+      # `from_port`/`to_port` are the `Graph::Port` an end attaches to (`a -> b.port`), `nil` for the node itself.
+      Edge = Struct.new(:from, :to, :attrs, :direction, :line, :from_port, :to_port, keyword_init: true) do
         def label
           attrs["label"]
         end
@@ -16,6 +17,11 @@ module Archsight
           attrs.fetch("relation", "dependency")
         end
 
+        # `solid` (the relation's own stroke), `dashed` or `dotted`.
+        def line_style
+          attrs.fetch("line", "solid")
+        end
+
         # The explicit `tint` attr, if any -- `nil` when unset, meaning
         # "use this relation's own fixed color" rather than falling back to
         # some default tint the way `Node#effective_tint` does (an edge

data/lib/archsight/diagram/graph/node.rb

@@ -165,6 +165,30 @@ module Archsight
           attrs["link"]
         end
 
+        # The leaf's `port "id" { ... }` tabs, in declaration order (see `Graph::Port`).
+        def ports = (@ports ||= [])
+        def port(id) = ports.find { |p| p.id == id }
+
+        # The id of the top-level `badge` definition this node shows, if any.
+        def badge = attrs["badge"]
+
+        # The explicit text of this node's legend row (`legend "..."`), if any.
+        def legend_label = attrs["legend"]
+
+        # The raw `align` attr (see `Layout::Alignment`), if any.
+        def align = attrs["align"]
+
+        # `align "top a, left b"` as `[[axis, edge, id], ...]`; a bare id means `center`. The first word is an
+        # edge only when an id follows it, so a node named "top" can still be aligned to.
+        def alignments
+          return [] unless align
+
+          align.split(",").map(&:strip).map do |entry|
+            word, rest = entry.split(/\s+/, 2)
+            rest && Node::ALIGN_EDGES.key?(word) ? [Node::ALIGN_EDGES[word], word, rest.strip] : [:x, "center", entry]
+          end
+        end
+
         # Why this node's `resource` reference couldn't be resolved (see
         # `ResourceLinks`), or `nil` when it has none or it resolved.
         def broken_link
@@ -174,7 +198,8 @@ module Archsight
         # The padding and title band `Layout` reserves inside a container's
         # box -- none for an anonymous `layer`/`stack`, which never draws a
         # box of its own; `Legend::Frame` has its own fixed ones.
-        def layout_padding(theme) = anonymous? ? 0.0 : theme.padding
+        # `padding` (same syntax as `gap`) overrides the theme's on a named container.
+        def layout_padding(theme) = anonymous? ? 0.0 : GapSpec.parse(attrs["padding"]).apply(theme.padding)
         def layout_title_height(theme) = anonymous? ? 0.0 : theme.title_height
 
         # See `Legend::Entry`, sized by `Layout` from its row instead of from
@@ -267,6 +292,9 @@ module Archsight
         def main_axis = Axis::HEIGHT
       end
 
+      # Which edge of another node an `align` entry lines a node up with, and on which axis.
+      Node::ALIGN_EDGES = { "left" => :x, "center" => :x, "right" => :x, "top" => :y, "middle" => :y, "bottom" => :y }.freeze
+
       Node::KIND_CLASSES = {
         component: Component, application: Application, api: Api, database: Database,
         queue: Queue, actor: Actor, file: FileNode, text: TextNode, group: Group, boundary: Boundary, layer: Layer, stack: Stack

data/lib/archsight/diagram/graph/port.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Diagram
+    class Graph
+      # A labelled tab on a leaf's border (`port "id" { ... }`) that edges attach to with
+      # `leaf.id`. `side`/`at` are the explicit placement, `nil` when left to `PortPlacement`.
+      Port = Struct.new(:id, :node, :attrs, :line, keyword_init: true) do
+        def label = attrs["label"] || id
+        def side = attrs["side"]
+        def at = attrs["at"]
+        def badge = attrs["badge"]
+
+        # `node.port`, as an edge names it
+        def ref = "#{node.id}.#{id}"
+      end
+
+      # A top-level `badge "id" { tint; label }` or `line "style" { label }` (see `AST::Definition`).
+      Definition = Struct.new(:kind, :id, :attrs, :line, keyword_init: true) do
+        def label = attrs["label"] || id
+        def tint = attrs.fetch("tint", "gray")
+      end
+    end
+  end
+end

data/lib/archsight/diagram/graph.rb

@@ -8,6 +8,7 @@ require_relative "style/relations"
 require_relative "style/theme"
 require_relative "legend/modes"
 require_relative "graph/node"
+require_relative "graph/port"
 require_relative "graph/edge"
 require_relative "graph/dataflow"
 require_relative "graph/attributes"
@@ -30,7 +31,7 @@ module Archsight
       SETTING_VALUES = { "theme" => -> { Theme.names }, "legend" => -> { Legend::MODES }, "ranks" => -> { RANKS_MODES } }.freeze
       SETTING_IVARS = { "theme" => :@theme_name, "legend" => :@legend_mode, "ranks" => :@ranks_mode }.freeze
 
-      attr_reader :roots, :nodes_by_id, :edges, :dataflows, :theme_name, :legend_mode, :ranks_mode
+      attr_reader :roots, :nodes_by_id, :edges, :dataflows, :theme_name, :legend_mode, :ranks_mode, :definitions
 
       def self.build(statements)
         new(statements)
@@ -38,6 +39,7 @@ module Archsight
 
       def initialize(statements)
         @nodes_by_id = {}
+        @definitions = {}
         @roots = []
         raw_edges = []
         raw_dataflows = []
@@ -52,8 +54,11 @@ module Archsight
             raw_dataflows << stmt
           when AST::Setting
             apply_setting(stmt)
+          when AST::Definition
+            add_definition(stmt)
           end
         end
+        check_references!
 
         raw_edges.each { |e| Attributes.check_edge!(e) }
         raw_dataflows.each_with_object({}) do |df, seen|
@@ -70,9 +75,21 @@ module Archsight
 
       def node(id)
         @nodes_by_id.fetch(id) do
+          owner = port_owner(id)
+          raise GraphError, "#{id.inspect} is a port of #{owner.id.inspect}; only edges attach to ports" if owner&.port(id.delete_prefix("#{owner.id}."))
+
           raise GraphError, "unknown id #{id.inspect}"
         end
       end
+
+      # The `badge "id"` definition, `nil` if there is none.
+      def badge_definition(id) = @definitions[[:badge, id]]
+
+      # The legend text a top-level `line "dashed" { label }` gives that line style, `nil` without one.
+      def line_definition(style) = @definitions[[:line, style]]
+
+      # Every port of every leaf, in declaration order.
+      def ports = @nodes_by_id.values.flat_map(&:ports)
     end
   end
 end

data/lib/archsight/diagram/includes.rb

@@ -93,11 +93,16 @@ module Archsight
         raise IncludeError, "in include #{path.inspect}: #{e.message}"
       end
 
-      # Dataflows and settings apply to the whole diagram, so inside a container they are ignored (with a warning)
+      # Dataflows, settings and badge/line definitions apply to the whole diagram, so inside a container they are
+      # ignored (with a warning)
       def drop_whole_diagram_statements(path, parsed, line)
-        dropped, kept = parsed.partition { |s| s.is_a?(AST::DataFlow) || s.is_a?(AST::Setting) }
+        dropped, kept = parsed.partition { |s| s.is_a?(AST::DataFlow) || s.is_a?(AST::Setting) || s.is_a?(AST::Definition) }
         dropped.each do |s|
-          what = s.is_a?(AST::DataFlow) ? "dataflow #{s.id.inspect}" : "#{s.key} setting"
+          what = case s
+                 when AST::DataFlow then "dataflow #{s.id.inspect}"
+                 when AST::Definition then "#{s.kind} #{s.id.inspect}"
+                 else "#{s.key} setting"
+                 end
           @warnings << "include #{path.inspect} (line #{line}): the #{what} (line #{s.line}) is ignored, it only applies when included at the top level"
         end
         kept
@@ -145,9 +150,18 @@ module Archsight
             block.attrs["label"] ||= block.id # the label defaults to the id
             block.id = ref(block.id)
           end
+          block.attrs["align"] = rename_align(block.attrs["align"]) if block.attrs.key?("align")
           block.children.each { |child| rename(child) }
         end
 
+        # `top a, b` -> `top ns.a, ns.b`: the id of each entry, after its edge word if it has one
+        def rename_align(value)
+          value.split(",").map(&:strip).map do |entry|
+            word, rest = entry.split(/\s+/, 2)
+            rest && Graph::Node::ALIGN_EDGES.key?(word) ? "#{word} #{ref(rest.strip)}" : ref(entry)
+          end.join(", ")
+        end
+
         def rename_dataflow(flow)
           flow.attrs["label"] ||= flow.id
           flow.id = ref(flow.id)
@@ -159,8 +173,12 @@ module Archsight
           group
         end
 
+        # A defined id, or `node.port` of a defined node
         def ref(id)
-          @defined[id] ? "#{@prefix}#{id}" : id
+          return "#{@prefix}#{id}" if @defined[id]
+
+          owner, dot, = id.rpartition(".")
+          !dot.empty? && @defined[owner] ? "#{@prefix}#{id}" : id
         end
       end
     end