archsight 0.4.2 → 0.5.0

data/lib/archsight/diagram/includes.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Diagram
+    # Expands `include "<path>"` statements: each one is replaced, at its position, by the statements of the
+    # diagram it names. The renderer knows nothing about where diagrams live; the caller supplies a loader
+    # (`archsight://` and `file://` paths, see `Helpers::DiagramIncludes`).
+    #
+    # `loader.call(path)` returns the source of the included diagram, or `:missing` / `:forbidden` / `:invalid`.
+    # Included sources may include others. An include inside a container takes blocks and edges only: a
+    # `dataflow` or a `theme`/`legend`/`ranks` setting belongs to the whole diagram, so it is left out there
+    # and reported in `Result#warnings`.
+    # `include "x" { namespace "cs" }` puts `cs.` in front of every id the included diagram defines (nodes and
+    # dataflows, and the references to them inside it), so the same diagram can be included more than once;
+    # a node without a `label` keeps showing its unprefixed id. References to ids the diagram does not define
+    # are left alone: they name nodes of the including diagram.
+    # Edges need no such care, they are resolved by id once the whole graph is built, so a fragment may link to
+    # nodes of the diagram that includes it and the other way round.
+    class Includes
+      MAX_DEPTH = 8
+      MAX_INCLUDES = 100
+      REASONS = { missing: "not found", forbidden: "is not allowed", invalid: "is not a valid include path" }.freeze
+
+      # The expanded statements, the sources that were loaded (`{ path => source }`, in order) and what was
+      # left out of them (warning messages).
+      Result = Struct.new(:statements, :sources, :warnings, keyword_init: true)
+
+      # @param statements [Array] parsed statements of the main source
+      # @param loader [#call, nil]
+      # @raise [IncludeError]
+      def self.expand(statements, loader)
+        new(loader).expand(statements)
+      end
+
+      def self.includes?(statements)
+        statements.any? { |s| s.is_a?(AST::Include) || (s.is_a?(AST::Block) && includes?(s.children)) }
+      end
+
+      def initialize(loader)
+        @loader = loader
+        @sources = {}
+        @warnings = []
+        @count = 0
+      end
+
+      def expand(statements)
+        Result.new(statements: splice(statements, [], top: true), sources: @sources, warnings: @warnings)
+      end
+
+      private
+
+      def splice(statements, stack, top:)
+        statements.flat_map do |stmt|
+          case stmt
+          when AST::Include then included(stmt, stack, top: top)
+          when AST::Block
+            stmt.children = splice(stmt.children, stack, top: false)
+            [stmt]
+          else [stmt]
+          end
+        end
+      end
+
+      def included(stmt, stack, top:)
+        path = stmt.path
+        raise IncludeError, "include cycle: #{(stack + [path]).join(" -> ")} (line #{stmt.line})" if stack.include?(path)
+        raise IncludeError, "include #{path.inspect} (line #{stmt.line}) is nested deeper than #{MAX_DEPTH} levels" if stack.length >= MAX_DEPTH
+
+        @count += 1
+        raise IncludeError, "too many includes (more than #{MAX_INCLUDES})" if @count > MAX_INCLUDES
+
+        source = load(path, stmt.line)
+        @sources[path] = source
+        parsed = parse(path, source)
+        parsed = drop_whole_diagram_statements(path, parsed, stmt.line) unless top
+        statements = splice(parsed, stack + [path], top: top)
+        stmt.namespace ? Namespacer.new(stmt.namespace).apply(statements) : statements
+      end
+
+      def load(path, line)
+        raise IncludeError, "include #{path.inspect} (line #{line}) is not available here" unless @loader
+
+        result = @loader.call(path)
+        return result if result.is_a?(String)
+
+        reason = REASONS.fetch(result) { raise ArgumentError, "include loader returned #{result.inspect} for #{path.inspect}" }
+        raise IncludeError, "include #{path.inspect} #{reason} (line #{line})"
+      end
+
+      def parse(path, source)
+        Parser.parse(source, anon_scope: "i#{@count}_")
+      rescue ParseError, GraphError => e
+        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)
+      def drop_whole_diagram_statements(path, parsed, line)
+        dropped, kept = parsed.partition { |s| s.is_a?(AST::DataFlow) || s.is_a?(AST::Setting) }
+        dropped.each do |s|
+          what = s.is_a?(AST::DataFlow) ? "dataflow #{s.id.inspect}" : "#{s.key} setting"
+          @warnings << "include #{path.inspect} (line #{line}): the #{what} (line #{s.line}) is ignored, it only applies when included at the top level"
+        end
+        kept
+      end
+
+      # Puts `<namespace>.` in front of the ids a list of statements defines, and of the references to them
+      class Namespacer
+        def initialize(namespace)
+          @prefix = "#{namespace}."
+          @defined = {}
+        end
+
+        def apply(statements)
+          collect(statements)
+          statements.each { |stmt| rename(stmt) }
+          statements
+        end
+
+        private
+
+        # Anonymous layers/stacks have ids no one can reference and that are unique already
+        def collect(statements)
+          statements.each do |stmt|
+            case stmt
+            when AST::Block
+              @defined[stmt.id] = true unless stmt.anonymous?
+              collect(stmt.children)
+            when AST::DataFlow then @defined[stmt.id] = true
+            end
+          end
+        end
+
+        def rename(stmt)
+          case stmt
+          when AST::Block then rename_block(stmt)
+          when AST::Edge
+            stmt.from = ref(stmt.from)
+            stmt.to = ref(stmt.to)
+          when AST::DataFlow then rename_dataflow(stmt)
+          end
+        end
+
+        def rename_block(block)
+          unless block.anonymous?
+            block.attrs["label"] ||= block.id # the label defaults to the id
+            block.id = ref(block.id)
+          end
+          block.children.each { |child| rename(child) }
+        end
+
+        def rename_dataflow(flow)
+          flow.attrs["label"] ||= flow.id
+          flow.id = ref(flow.id)
+          flow.hops.map! { |hop| hop.is_a?(AST::DataFlowGroup) ? rename_group(hop) : ref(hop) }
+        end
+
+        def rename_group(group)
+          group.branches.each { |branch| branch.hops.map! { |hop| ref(hop) } }
+          group
+        end
+
+        def ref(id)
+          @defined[id] ? "#{@prefix}#{id}" : id
+        end
+      end
+    end
+  end
+end

data/lib/archsight/diagram/layout/expander.rb

@@ -97,29 +97,101 @@ module Archsight
               # their own (now wider) box -- explaining a rank that visibly
               # spills outside its container despite matching its siblings'
               # width exactly.
-              center = own_target / 2.0
+              #
+              # The room they get is the *inner* one -- the target minus the
+              # node's own padding (and title bar), as in the single-child
+              # case below -- or they would sit flush on its border; the
+              # centerline is the middle of that inner area.
+              inner = own_target - inset(node, axis)
+              center = leading_inset(node, axis) + (inner / 2.0)
               node.children.each do |c|
-                expand(c, axis, own_target, inherited: extend)
+                expand(c, axis, inner, inherited: extend)
                 axis.set_position(@boxes[c.id], center)
               end
             end
             return
           end
 
-          recenter_children(node, axis, extra / 2.0) if extra.positive?
+          recenter_children(node, axis, node.anchor_shift(axis, extra, default: :center)) if extra.positive?
 
           return unless node.children.length == 1
 
           expand(node.children.first, axis, own_target - inset(node, axis), inherited: extend)
         end
 
+        # `extend "height"`: grows `node` to `target` height keeping its
+        # content top-aligned (or at its `anchor`), then hands the extra room to whatever inside
+        # can absorb it -- a `stack` child carrying `extend "height"`
+        # itself (the first such one in a stack's column gets all of it, and
+        # the ranks below it move down, so e.g. a footer rank lines up
+        # across columns), reached through single-child wrappers such as a
+        # `boundary` around a `stack`.
+        def grow_height(node, target)
+          box = @boxes[node.id]
+          extra = target - box.height
+          return if extra <= 0
+
+          box.height = target
+          return if node.children.empty?
+
+          # An explicit `anchor` decides where the content sits; otherwise a
+          # stack (or a wrapper around one) hands the room to its
+          # `extend "height"` child, and anything else stays top-aligned.
+          delta = node.anchor_shift(Axis::HEIGHT, extra, default: :top)
+          return recenter_children(node, Axis::HEIGHT, delta) if delta.positive?
+
+          if node.layer?
+            fill_layer(node, extra)
+          elsif node.children.length == 1
+            inner = node.children.first
+            grow_top_aligned(inner, extra) if inner.stack? || inner.extend_height?
+          elsif node.stack?
+            absorb_in_stack(node, extra)
+          end
+        end
+
         private
 
+        # A grown `layer`'s `extend "height"` children fill the new height
+        # too (they were only matched to their tallest sibling before).
+        def fill_layer(node, extra)
+          room = @boxes[node.id].height - inset(node, Axis::HEIGHT)
+          node.children.select(&:extend_height?).each do |c|
+            grow = room - @boxes[c.id].height
+            grow_top_aligned(c, grow) if grow.positive? && extra.positive?
+          end
+        end
+
+        # Grows a child by `extra` keeping its top edge where it is (box
+        # positions are centers, so the center moves down by half of it).
+        def grow_top_aligned(node, extra)
+          grow_height(node, @boxes[node.id].height + extra)
+          @boxes[node.id].y += extra / 2.0
+        end
+
+        # Gives `extra` to the first child of the `stack` `node` marked
+        # `extend "height"`, and shifts every later rank down by it.
+        def absorb_in_stack(node, extra)
+          ordered = node.children.sort_by { |c| @boxes[c.id].y }
+          index = ordered.index(&:extend_height?)
+          return unless index
+
+          grower = ordered[index]
+          grow_top_aligned(grower, extra)
+          ordered[(index + 1)..].each { |c| @boxes[c.id].y += extra }
+        end
+
         # How much of a container's size on `axis` is reserved by its own
         # padding (and, on the height axis, its title bar) rather than
         # available to a single child filling it -- the node's own
         # `layout_padding`/`layout_title_height` (nothing, for an anonymous
         # `layer`/`stack`, since it renders no box to pad).
+        # The padding (plus title bar, on the height axis) before the content.
+        def leading_inset(node, axis)
+          padding = node.layout_padding(@theme)
+          axis == Axis::HEIGHT ? padding + node.layout_title_height(@theme) : padding
+        end
+
         def inset(node, axis)
           padding = 2 * node.layout_padding(@theme)
           axis == Axis::HEIGHT ? padding + node.layout_title_height(@theme) : padding

data/lib/archsight/diagram/layout/rank_arranger.rb

@@ -74,7 +74,9 @@ module Archsight
         def arrange_layer(group, children)
           max_height = children.map { |c| @boxes[c.id].height }.max
           children.each do |c|
-            @boxes[c.id].height = max_height if !c.leaf? && c.extend_height?
+            next if c.leaf? || !c.extend_height?
+
+            Expander.new(@boxes, theme: @theme).grow_height(c, max_height)
           end
 
           gap = group.gap(@theme.sibling_gap)

data/lib/archsight/diagram/parser/ast.rb

@@ -43,6 +43,11 @@ module Archsight
       # own attrs at graph-resolution time).
       DataFlowBranch = Struct.new(:hops, :attrs, :line, keyword_init: true)
 
+      # `include "<path>" [{ namespace "cs" }]` -- another diagram spliced in at this position (see `Includes`).
+      # Parsed like any statement, replaced by the included statements before the graph is built, so nothing
+      # downstream sees it. `namespace`, if any, puts `<namespace>.` in front of every id the included diagram defines.
+      Include = Struct.new(:path, :namespace, :line, keyword_init: true)
+
       # A top-level diagram-wide `key "value"` setting -- currently only
       # `theme "compact"` (see `Theme`).
       Setting = Struct.new(:key, :value, :line, keyword_init: true)

data/lib/archsight/diagram/parser/table_layout.rb

@@ -20,6 +20,8 @@ module Archsight
 
           raise ParseError, "#{label} at line #{line}: columns must be a positive integer, got #{raw.inspect}" unless raw.match?(/\A[1-9]\d*\z/)
 
+          raise ParseError, "#{label} at line #{line}: columns cannot be combined with include (the included blocks are not known yet)" if children.any?(AST::Include)
+
           blocks, edges = children.partition { |c| c.is_a?(AST::Block) }
           count = [raw.to_i, blocks.length].min
           return children if blocks.empty?

data/lib/archsight/diagram/parser.rb

@@ -14,9 +14,11 @@ module Archsight
     #
     # Grammar (informal):
     #   program    := statement*
-    #   statement  := block | dataflow | edge | setting
+    #   statement  := block | dataflow | edge | setting | include
+    #   include    := "include" STRING ["{" "namespace" STRING "}"] [";"]
+    #                 -- top level, or where a container may hold blocks and edges
     #   setting    := ("theme" | "legend" | "ranks") STRING [";"]   -- top level only
-    #   block      := (CONTAINER_KEYWORD | LEAF_KEYWORD) [STRING] "{" (attr | block | edge)* "}"
+    #   block      := (CONTAINER_KEYWORD | LEAF_KEYWORD) [STRING] "{" (attr | block | edge | include)* "}"
     #                 -- the id is required except for ANONYMOUS_KEYWORDS
     #   dataflow   := "dataflow" STRING "{" (hop | hop_group | attr)* "}"
     #                 -- needs >= 2 hops (per branch, if a hop_group is present);
@@ -45,6 +47,7 @@ module Archsight
       # `layer`/`stack` may be used without an id, purely as a layout hint
       # (see AST::Block#anonymous) — a `group`/`boundary` always renders a
       # visible box, so an unnamed one wouldn't make sense the same way.
+      NAMESPACE = /\A[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*\z/
       ANONYMOUS_KEYWORDS = %w[layer stack].freeze
       SETTING_KEYWORDS = %w[theme legend ranks].freeze
       EDGE_ARROWS = {
@@ -55,13 +58,16 @@ module Archsight
 
       attr_reader :cursor
 
-      def self.parse(source)
-        new(source).parse
+      # `anon_scope` namespaces the ids of anonymous layers/stacks, so the statements of an included
+      # source (parsed on its own) never collide with those of the including one.
+      def self.parse(source, anon_scope: nil)
+        new(source, anon_scope: anon_scope).parse
       end
 
-      def initialize(source)
+      def initialize(source, anon_scope: nil)
         @cursor = TokenCursor.new(Lexer.new(source).tokenize)
         @anon_counter = 0
+        @anon_scope = anon_scope
       end
 
       def parse
@@ -75,6 +81,8 @@ module Archsight
       def statement
         if check_block_keyword?
           block
+        elsif include_directive?
+          include_statement
         elsif cursor.check(:ident, "dataflow") && cursor.peek_type(1) == :string
           DataflowParser.new(cursor).parse
         elsif cursor.check(:ident) && EDGE_ARROWS.key?(cursor.peek_type(1))
@@ -108,22 +116,16 @@ module Archsight
         children = []
 
         parse_attrs_until_rbrace(attrs, label, expected: "an attribute, a nested block, an edge") do
-          if check_block_keyword?
-            children << block
-            true
-          elsif cursor.check(:ident) && EDGE_ARROWS.key?(cursor.peek_type(1))
-            children << edge
-            true
-          else
-            false
-          end
+          child = container_child
+          children << child if child
+          child
         end
 
         cursor.expect(:rbrace, "expected '}' to close #{label}")
 
         if LEAF_KEYWORDS.include?(kind_token.value) && !children.empty?
           raise ParseError, "#{label} at line #{kind_token.line} cannot " \
-                            "contain nested blocks or edges (did you mean 'group'?)"
+                            "contain nested blocks, edges or includes (did you mean 'group'?)"
         end
 
         raise ParseError, "#{label} at line #{kind_token.line}: columns only applies to containers" if LEAF_KEYWORDS.include?(kind_token.value) && attrs.key?("columns")
@@ -133,6 +135,46 @@ module Archsight
         AST::Block.new(kind: kind, id: id, anonymous: anonymous, attrs: attrs, children: children, line: kind_token.line)
       end
 
+      # The nested block, edge or include at the cursor, nil if it is something else (an attribute)
+      def container_child
+        if check_block_keyword?
+          block
+        elsif include_directive?
+          include_statement
+        elsif cursor.check(:ident) && EDGE_ARROWS.key?(cursor.peek_type(1))
+          edge
+        end
+      end
+
+      # `include "<path>"` -- `include -> x` is still an edge, so a node may be named "include"
+      def include_directive?
+        cursor.check(:ident, "include") && cursor.peek_type(1) == :string
+      end
+
+      def include_statement
+        keyword = cursor.advance
+        path = cursor.advance
+        namespace = include_options(path.value) if cursor.check(:lbrace)
+        cursor.consume(:semi)
+        AST::Include.new(path: path.value, namespace: namespace, line: keyword.line)
+      end
+
+      # `{ namespace "cs" }` after an include: the only option
+      def include_options(path)
+        cursor.advance
+        options = {}
+        until cursor.check(:rbrace)
+          line = cursor.current.line
+          key, value = cursor.check(:ident) ? attr : cursor.expect(:ident, "expected 'namespace' in the options of include #{path.inspect}")
+          raise ParseError, "unknown option '#{key}' of include #{path.inspect} at line #{line} (only 'namespace')" unless key == "namespace"
+          raise ParseError, "the namespace #{value.inspect} of include #{path.inspect} at line #{line} must be a name like \"cs\" or \"a.b\"" unless value.match?(NAMESPACE)
+
+          store_attr(options, key, value, line, "include #{path.inspect}")
+        end
+        cursor.expect(:rbrace, "expected '}' to close the options of include #{path.inspect}")
+        options["namespace"]
+      end
+
       # `theme "compact"`, `legend "right"` -- `theme -> x` is still an edge
       # (an arrow, not a string, follows the id), so a node may still be
       # named "theme" or "legend".
@@ -145,7 +187,7 @@ module Archsight
 
       def next_anonymous_id
         @anon_counter += 1
-        "__asd_anon_#{@anon_counter}"
+        "__asd_anon_#{@anon_scope}#{@anon_counter}"
       end
 
       # What a human should see identifying this block in an error message

data/lib/archsight/diagram.rb

@@ -5,6 +5,7 @@ require_relative "diagram/style/theme"
 require_relative "diagram/parser/lexer"
 require_relative "diagram/parser"
 require_relative "diagram/parser/ast"
+require_relative "diagram/includes"
 require_relative "diagram/graph"
 require_relative "diagram/resource_links"
 require_relative "diagram/layout"
@@ -33,9 +34,14 @@ module Archsight
     # `resolver` turns a node's `resource "..."` reference into a link (see
     # `ResourceLinks`); `unresolved`, if an Array, collects the references it
     # couldn't resolve.
+    # `includes` loads the diagrams that `include "<path>"` statements name (see `Includes`); without it
+    # a source that includes anything does not render. `warnings`, if an Array, collects what the includes left
+    # out (see `Includes`).
     def self.render(source, relation_filter: Relations::DEFAULT_FILTER, profile: nil, style: nil, theme: nil, legend: nil, id_prefix: nil,
-                    resolver: nil, unresolved: nil)
-      statements = time(profile, :parse) { Parser.parse(source) }
+                    resolver: nil, unresolved: nil, includes: nil, warnings: nil)
+      statements = time(profile, :parse) do
+        expand(source, includes: includes).tap { |expanded| warnings&.concat(expanded.warnings) }.statements
+      end
       graph = time(profile, :graph) do
         Graph.build(statements).tap { |g| ResourceLinks.apply(g, resolver, unresolved) }
       end
@@ -47,8 +53,18 @@ module Archsight
     # The `resource "..."` references of the nodes of a diagram source, in order and without duplicates. Parses and
     # builds the graph but does not lay it out, so it is cheap enough to run over every diagram of a model.
     # @raise [Archsight::Diagram::Error] if the source is not a valid diagram
-    def self.resource_references(source)
-      Graph.build(Parser.parse(source)).nodes_by_id.values.filter_map { |node| node.attrs["resource"] }.uniq
+    def self.resource_references(source, includes: nil)
+      Graph.build(expand(source, includes: includes).statements).nodes_by_id.values.filter_map { |node| node.attrs["resource"] }.uniq
+    end
+
+    # Parses `source` and splices in the diagrams it includes.
+    # @return [Includes::Result] the statements, and the sources that were included (`{ path => source }`)
+    # @raise [Archsight::Diagram::Error] if the source or an included one is not a valid diagram
+    def self.expand(source, includes: nil)
+      statements = Parser.parse(source)
+      return Includes::Result.new(statements: statements, sources: {}, warnings: []) unless Includes.includes?(statements)
+
+      Includes.expand(statements, includes)
     end
 
     def self.time(profile, key)

data/lib/archsight/export/confluence/storage.rb

@@ -146,12 +146,17 @@ module Archsight
         # A diagram from asd source (fenced block, .asd file) as block XML
         def diagram(source, stem)
           stem ||= "#{@page_name}-diagram-#{@diagrams += 1}"
-          figure(Archsight::Diagram.render(source, resolver: @diagram_links), stem)
+          figure(Archsight::Diagram.render(source, resolver: @diagram_links, includes: diagram_includes), stem)
         rescue Archsight::Diagram::Error => e
           problem("diagram #{stem}: #{e.message}")
           ""
         end
 
+        # `include "file://..."` / `archsight://...` in a diagram: the page's database, else only files of the resources directory
+        def diagram_includes
+          Helpers::DiagramIncludes.new(@database, resources_dir: @resources_dir)
+        end
+
         # An image that must not sit inside a paragraph (a diagram), nil for ordinary images
         def block_image(attr)
           path = asset_path(attr["src"].to_s)

data/lib/archsight/helpers/diagram_blocks.rb

@@ -18,6 +18,7 @@ module Archsight
     module DiagramBlocks
       BLOCK = %r{<pre><code class="language-asd">(.*?)</code></pre>}m
       CACHE_LIMIT = 256
+      INCLUDE = /\binclude\s+"/
 
       @cache = {}
       @cache_lock = Mutex.new
@@ -26,11 +27,11 @@ module Archsight
 
       # @return [Array(String, Hash{String => String})] HTML with a placeholder per
       #   asd block, and the rendered replacement for each placeholder
-      def extract(html, resolver: nil)
+      def extract(html, resolver: nil, includes: nil)
         diagrams = {}
         replaced = html.gsub(BLOCK) do |block|
           placeholder = "<!--asd-diagram:#{diagrams.size}-->"
-          diagrams[placeholder] = render_block(::CGI.unescapeHTML(Regexp.last_match(1)), block, resolver: resolver)
+          diagrams[placeholder] = render_block(::CGI.unescapeHTML(Regexp.last_match(1)), block, resolver: resolver, includes: includes)
           placeholder
         end
         [replaced, diagrams]
@@ -44,9 +45,9 @@ module Archsight
 
       # A whole diagram definition (the `architecture/diagram` annotation) as
       # inline SVG, or the error box plus the source if it doesn't render.
-      def render_diagram(source, resolver: nil)
+      def render_diagram(source, resolver: nil, includes: nil)
         escaped = ::Rack::Utils.escape_html(source)
-        render_block(source, %(<pre><code class="language-asd">#{escaped}</code></pre>), resolver: resolver)
+        render_block(source, %(<pre><code class="language-asd">#{escaped}</code></pre>), resolver: resolver, includes: includes)
       end
 
       # A diagram for the editor preview: the same SVG (and cache) as a rendered page, but a diagram that
@@ -54,8 +55,8 @@ module Archsight
       # that repeats the source, which the editor already shows.
       #
       # @return [Hash] `{ html: "<figure ...>", error: nil }` or `{ html: nil, error: "message" }`
-      def preview(source, resolver: nil)
-        { html: render_svg(source, resolver: resolver), error: nil }
+      def preview(source, resolver: nil, includes: nil)
+        { html: render_svg(source, resolver: resolver, includes: includes), error: nil }
       rescue Archsight::Diagram::Error => e
         { html: nil, error: e.message }
       end
@@ -73,40 +74,54 @@ module Archsight
       # `resource "..."` references resolve against the database, which can
       # change under a cached render (a reload, an edit), so the outcome of
       # each reference is part of the key.
-      def render_block(source, original, resolver: nil)
-        render_svg(source, resolver: resolver)
+      def render_block(source, original, resolver: nil, includes: nil)
+        render_svg(source, resolver: resolver, includes: includes)
       rescue Archsight::Diagram::Error => e
         message = ::Rack::Utils.escape_html(e.message)
         %(<div class="asd-diagram-error"><p><strong>Diagram error:</strong> #{message}</p>#{original}</div>)
       end
 
       # @raise [Archsight::Diagram::Error] if the source does not render
-      def render_svg(source, resolver: nil)
-        key = fingerprint(source, resolver: resolver)
+      def render_svg(source, resolver: nil, includes: nil)
+        key = fingerprint(source, resolver: resolver, includes: includes)
         cached(key) do
-          svg = Archsight::Diagram.render(source, id_prefix: "asd#{key}", resolver: resolver)
+          warnings = [] #: Array[String]
+          svg = Archsight::Diagram.render(source, id_prefix: "asd#{key}", resolver: resolver, includes: includes, warnings: warnings)
+          warnings.each { |message| warn "Diagram: #{message}" }
           %(<figure class="asd-diagram">#{svg.sub(/\A<\?xml[^>]*\?>\s*/, "")}</figure>)
         end
       end
 
       # The cache key of a diagram: its source plus how each `resource` reference resolves right now. It
-      # changes exactly when the rendered diagram would, so it is also a good ETag.
-      def fingerprint(source, resolver: nil)
-        ::Digest::SHA256.hexdigest([source, resolutions(source, resolver)].inspect)[0, 12]
+      # changes exactly when the rendered diagram would, so it is also a good ETag. The diagrams it includes
+      # are part of it: their sources, and how their `resource` references resolve.
+      def fingerprint(source, resolver: nil, includes: nil)
+        included = included_sources(source, includes)
+        ::Digest::SHA256.hexdigest([source, included, resolutions([source, *included.values], resolver)].inspect)[0, 12]
       end
 
       # A diagram as a standalone SVG document (what the assets API serves for an .asd file), cached by
       # fingerprint like the inline diagrams.
       # @raise [Archsight::Diagram::Error] if the source does not render
-      def standalone_svg(source, resolver: nil)
-        key = fingerprint(source, resolver: resolver)
-        cached("svg-#{key}") { Archsight::Diagram.render(source, id_prefix: "asd#{key}", resolver: resolver) }
+      def standalone_svg(source, resolver: nil, includes: nil)
+        key = fingerprint(source, resolver: resolver, includes: includes)
+        cached("svg-#{key}") { Archsight::Diagram.render(source, id_prefix: "asd#{key}", resolver: resolver, includes: includes) }
       end
 
-      def resolutions(source, resolver)
+      # `{ path => source }` of the diagrams `source` includes, recursively; empty for a source that includes
+      # none (checked on the text first: most diagrams include nothing and need not be parsed twice)
+      # @raise [Archsight::Diagram::Error] if the source or an included one is not a valid diagram
+      def included_sources(source, includes)
+        return {} unless includes && source.match?(INCLUDE)
+
+        Archsight::Diagram.expand(source, includes: includes).sources
+      end
+
+      def resolutions(sources, resolver)
         return [] unless resolver
 
-        source.scan(/\bresource\s+"([^"]*)"/).flatten.uniq.map { |reference| [reference, resolver.call(reference)] }
+        references = sources.flat_map { |source| source.scan(/\bresource\s+"([^"]*)"/).flatten }
+        references.uniq.map { |reference| [reference, resolver.call(reference)] }
       end
 
       def cached(key)