archsight 0.3.3 → 0.4.0

data/lib/archsight/diagram/routing/edge_router.rb

@@ -41,14 +41,15 @@ module Archsight
       def candidate_paths(a, b, style, from_shape: "rectangle", to_shape: "rectangle", obstacles: [])
         # A straight axis-aligned line joins the straight family (and the
         # automatic choice), listed first so it wins ties against the
-        # diagonal. An explicit `style "orthogonal"` keeps its bends.
+        # diagonal. It is orthogonal too (no bend at all), so an explicit
+        # `style "orthogonal"` takes it as well and only never goes diagonal.
         aligned = StraightPath.aligned_paths(a, b, from_shape: from_shape, to_shape: to_shape)
         straight = [StraightPath.straight_path(a, b, from_shape: from_shape, to_shape: to_shape)]
         orthogonal = OrthogonalPath.orthogonal_candidates(a, b, obstacles)
 
         case style
         when "straight" then aligned + straight
-        when "orthogonal" then orthogonal
+        when "orthogonal" then aligned + orthogonal
         else aligned + straight + orthogonal
         end
       end
@@ -71,8 +72,22 @@ module Archsight
       # Charged relative to the best candidate in the same crossing class
       # rather than absolutely, so however large it is it never tips the
       # balance against `CROSSING_PENALTY`: a bridge that clears a box still
-      # beats a bend-free line through it.
+      # beats a bend-free line through it. An extra bend never costs more
+      # than `TURN_LENGTH_FACTOR` times the route's own length, though: a
+      # short zig-zag still beats a one-corner detour more than three times
+      # its length (out of a box's side and all the way along it instead of
+      # a short jog off its top).
       TURN_PENALTY = 300.0
+      TURN_LENGTH_FACTOR = 2.0
+
+      # A bent route's run out of or into a box shorter than this hugs the
+      # box's border instead of reading as a connection to it (a turn right
+      # past the corner of the box it then enters). Every pixel short of it
+      # costs `SHORT_LEG_WEIGHT` pixels of length, so a route a little longer
+      # but with a real run in wins (see `OrthogonalPath::EXIT_SHIFT`). A
+      # straight line has no turn to hug with and is never charged.
+      MIN_END_LEG = BridgePath::BRIDGE_STUB
+      SHORT_LEG_WEIGHT = 3.0
 
       # Two edges running right along each other for a stretch reads as
       # clutter too, but far more mildly than either one cutting through a
@@ -130,7 +145,17 @@ module Archsight
           # Folded into `length` (rather than a separate term) so the native
           # selection kernels, which only know crossings and length, apply it too.
           extra_turns = turns[i] - fewest_turns[crossings[i]]
-          { path: path, crossing: crossings[i], length: lengths[i] + (TURN_PENALTY * extra_turns) + off_center_cost(path) }
+          turn_cost = [TURN_PENALTY, lengths[i] * TURN_LENGTH_FACTOR].min * extra_turns
+          { path: path, crossing: crossings[i], length: lengths[i] + turn_cost + off_center_cost(path) + short_leg_cost(path) }
+        end
+      end
+
+      # See `MIN_END_LEG`.
+      def short_leg_cost(path)
+        return 0.0 if path.length < 3
+
+        [path.first(2), path.last(2)].sum do |(p, q)|
+          [MIN_END_LEG - Math.hypot(q[0] - p[0], q[1] - p[1]), 0.0].max * SHORT_LEG_WEIGHT
         end
       end
 

data/lib/archsight/diagram/routing/edge_routing.rb

@@ -37,7 +37,9 @@ module Archsight
       # once it's `PORT_ORDER_PROBE` out from the side (see `order_key`);
       # `far` -- where it finally ends up, its far endpoint -- breaks ties
       # between lines still running together at that depth.
-      PortMember = Struct.new(:edge_path, :role, :box, :axis, :original, :approach, :order, :far, keyword_init: true)
+      # `slide` is the range a straight line may move within as a whole (see
+      # `sliding_range`), nil when it can only tilt.
+      PortMember = Struct.new(:edge_path, :role, :box, :axis, :original, :approach, :order, :far, :slide, keyword_init: true)
 
       # How many times `refine_line_overlap!` sweeps every edge. Each round
       # re-scores every edge against every other edge's *current* path, in
@@ -183,6 +185,7 @@ module Archsight
           add_port_member(groups, ep, :end, ep.to_box, ep.points.last)
         end
 
+        groups.each_value { |members| members.each { |m| m.slide = sliding_range(m, groups) } }
         groups.each_value { |members| apply_port_slots(members) if members.length > 1 }
       ensure
         @original_crossings = nil
@@ -199,6 +202,38 @@ module Archsight
         end
       end
 
+      # Where a straight line (two points, perpendicular to the side) can
+      # move as a whole, both ends together, and stay straight: within the
+      # span both boxes share on the side's axis, clear of their corners.
+      # Only when its far end is alone on its side, so moving it there
+      # never collides with that side's own port slots. Nil otherwise.
+      def sliding_range(member, groups)
+        points = member.edge_path.points
+        return nil unless points.length == 2 && EdgeRouter::PathMetrics.close?(member.approach, member.original)
+
+        far_box = member.role == :start ? member.edge_path.to_box : member.edge_path.from_box
+        far_point = member.role == :start ? points.last : points.first
+        far_side = far_box&.side_of(far_point)
+        return nil unless far_side && groups[[far_box.object_id, far_side]].length == 1
+
+        span = ->(box) { member.axis == :x ? [box.left, box.right] : [box.top, box.bottom] }
+        margin = EdgeRouter::StraightPath::ALIGNED_CORNER_MARGIN
+        low = [span.call(member.box).first, span.call(far_box).first].max + margin
+        high = [span.call(member.box).last, span.call(far_box).last].min - margin
+        low <= high ? (low..high) : nil
+      end
+
+      # `member`'s route with its endpoint moved to `pos`: a straight line
+      # that may slide there moves as a whole, anything else only at this end.
+      def moved_points(member, pos)
+        delta = pos - member.original
+        points = member.edge_path.points
+        return EdgeRouter::Attachment.shift_attachment(points, member.axis, delta, at: member.role) unless member.slide&.cover?(pos)
+
+        index = member.axis == :x ? 0 : 1
+        points.map { |point| point.dup.tap { |p| p[index] += delta } }
+      end
+
       def positioned(node)
         Layout::PositionedNode.new(node, @boxes[node.id])
       end
@@ -353,7 +388,7 @@ module Archsight
       end
 
       def slot_path(member, pos)
-        EdgeRouter::Attachment.shift_attachment(member.edge_path.points, member.axis, pos - member.original, at: member.role)
+        moved_points(member, pos)
       end
 
       def port_order(m, n)
@@ -365,8 +400,11 @@ module Archsight
       # Whether moving `member`'s endpoint keeps its route's shape: it
       # arrives perpendicular, along a run `EdgeRouter::Attachment.shift_attachment`
       # moves as a whole -- unlike a straight two-point line, whose far end
-      # stays put, so it only ever tilts.
+      # stays put, so it only ever tilts -- unless it may slide as a whole
+      # (`sliding_range`).
       def flexible?(member)
+        return true if member.slide
+
         member.edge_path.points.length > 2 && EdgeRouter::PathMetrics.close?(member.approach, member.original)
       end
 
@@ -381,8 +419,12 @@ module Archsight
       # the side) first tries to stay exactly where it is, anywhere along
       # the side and not just within its band: moving only its box end
       # would tilt it, and `place_members` already keeps it clear of every
-      # endpoint placed before it.
+      # endpoint placed before it. One that may slide as a whole
+      # (`sliding_range`) is `flexible?` instead and takes its band like the
+      # rest, so it makes room for a line that turns in beside it.
       def band_shifts(member, band_low, band_high, side_low, side_high)
+        return shifts_for(member, slide_positions(member, band_low, band_high)) if member.slide
+
         straight = member.approach.clamp(band_low, band_high)
         center = (band_low + band_high) / 2.0
         preferred = flexible?(member) ? [center, straight] : [straight, center]
@@ -392,6 +434,20 @@ module Archsight
         shifts_for(member, positions)
       end
 
+      # Where a line that may slide (`sliding_range`) tries to go, all of it
+      # inside its range so it stays straight: where it is, if that is in its
+      # band, else the band's center, then the band's ends -- clamped to the
+      # part of the band within the range. A band entirely outside the range
+      # leaves it where it is.
+      def slide_positions(member, band_low, band_high)
+        low = [band_low, member.slide.begin].max
+        high = [band_high, member.slide.end].min
+        return [member.original] if low > high
+
+        keep = member.original.between?(low, high) ? [member.original] : []
+        [*keep, ((band_low + band_high) / 2.0).clamp(low, high), low, high].uniq
+      end
+
       # `[pos, shifted points]` for moving `member`'s endpoint to `pos`, or
       # nil when that would make its route cross more obstacles than it
       # already does.
@@ -405,7 +461,7 @@ module Archsight
         path = member.edge_path
         moves = positions.map do |pos|
           delta = pos - member.original
-          [pos, delta.zero? ? path.points : EdgeRouter::Attachment.shift_attachment(path.points, member.axis, delta, at: member.role), delta.zero?]
+          [pos, delta.zero? ? path.points : moved_points(member, pos), delta.zero?]
         end
         moved = moves.reject(&:last)
         return moves.map { |pos, points, _| [pos, points] } if moved.empty?

data/lib/archsight/diagram/style/theme.rb

@@ -4,7 +4,7 @@ module Archsight
   module Diagram
     # Every spacing/sizing/font-size value the layout and renderer use, in
     # one place, so a diagram can pick a denser set for larger graphs:
-    # `default` > `cozy` > `compact`. Selected per diagram with a top-level
+    # `default` > `cozy` > `compact` > `tight`. Selected per diagram with a top-level
     # `theme "cozy"` statement, or overridden from outside
     # (`render(theme:)`, `--theme`).
     #
@@ -113,7 +113,12 @@ module Archsight
         title_inset_x: 6.0, group_title_baseline: 14.0, boundary_title_baseline: 15.0
       )
 
-      THEMES = [DEFAULT, COZY, COMPACT].to_h { |t| [t.name, t] }.freeze
+      # `compact` with component boxes that hug their label: ~6px above and
+      # below it instead of ~15px, 4px beside it instead of 8px, for very
+      # large graphs. Fonts, containers, gaps and actors stay as `compact`.
+      TIGHT = COMPACT.with(name: "tight", node_height: 26.0, node_label_padding: 8.0)
+
+      THEMES = [DEFAULT, COZY, COMPACT, TIGHT].to_h { |t| [t.name, t] }.freeze
     end
   end
 end

data/lib/archsight/documentation.rb

@@ -6,17 +6,17 @@ require_relative "template"
 module Archsight
   # Documentation generates markdown documentation for architecture resources
   class Documentation
-    # Layer display order (top to bottom)
-    LAYER_ORDER = %w[motivation strategy business application technology implementation].freeze
+    # Layer display order (top to bottom), without the tool's own kinds
+    LAYER_ORDER = (Archsight::Resources::LAYERS - ["other"]).freeze
 
     # Layer display names
     LAYER_NAMES = {
       "motivation" => "Motivation Layer",
       "strategy" => "Strategy Layer",
+      "implementation" => "Implementation & Migration Layer",
       "business" => "Business Layer",
       "application" => "Application Layer",
-      "technology" => "Technology Layer",
-      "implementation" => "Implementation & Migration Layer"
+      "technology" => "Technology Layer"
     }.freeze
 
     # Resource kinds to exclude from the diagram

data/lib/archsight/editor/page_source.rb

@@ -12,7 +12,7 @@ module Archsight
     # the counterpart of Editor.to_yaml for kinds that are stored as YAML.
     module PageSource
       # Frontmatter keys the form knows, in the order they are written
-      KNOWN_KEYS = %w[title tags author owner status toc confluence created updated properties].freeze
+      KNOWN_KEYS = %w[title tags author owner status toc created updated properties].freeze
       TIMESTAMPS = %w[created updated].freeze
       ISO_TIMESTAMP = /\A\d{4}-\d{2}-\d{2}(?:T[\d:.]+(?:Z|[+-]\d\d:\d\d))?\z/
 
@@ -33,6 +33,7 @@ module Archsight
       def render_fields(annotations, existing_source)
         extras = existing_meta(existing_source)
         extras.delete_if { |key, _| KNOWN_KEYS.include?(key) }
+        migrate_legacy_links(extras)
         lines = []
         lines << scalar_line("name", extras.delete("name")) if extras.key?("name")
         KNOWN_KEYS.each do |key|
@@ -46,6 +47,17 @@ module Archsight
         "---\n#{lines.join}---\n#{body(annotations["page/content"])}"
       end
 
+      # The old `confluence:` key becomes `links: { confluence: ... }` when the page is saved; the links mapping is
+      # not a form field, so it is kept as it is
+      def migrate_legacy_links(extras)
+        legacy = extras.delete("confluence")
+        return if legacy.nil?
+
+        links = extras["links"].is_a?(Hash) ? extras["links"] : {}
+        links["confluence"] ||= legacy
+        extras["links"] = links
+      end
+
       # Check that a submitted file still is the page it replaces
       # @raise [FileWriter::WriteError]
       def validate!(source, path:, name:)

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "erb"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Archsight
+  module Export
+    module Confluence
+      # The result of an analysis (`![[Analysis/Name]]` in a page, run at the export) in storage format: headings,
+      # text, tables and lists as Confluence content, messages as info/note/warning panels, code as a code macro.
+      # Like a view, it is the data of the moment of the export. The XML holds nothing that changes between two
+      # runs on the same data (no time, no duration), so an unchanged result leaves the page unchanged.
+      class AnalysisOutput
+        # level of a message -> Confluence panel macro
+        PANELS = { error: "warning", warning: "note", info: "info" }.freeze
+        LINK = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/
+        BREAK = %r{<br\s*/?>|\r?\n}i
+
+        # @param link [Proc] (target, label) -> inline XML of a `[[...]]` link
+        # @param code [Proc] (source, language) -> block XML of a code macro
+        def initialize(link:, code:)
+          @link = link
+          @code = code
+        end
+
+        # @return [String] block XML
+        def xml(name, result)
+          out = %(<p><strong>#{h(name)}</strong> (result of the analysis at the export)</p>\n)
+          return out << %(<p><em>The analysis failed: #{h(result.error)}</em></p>\n) unless result.success?
+
+          result.sections.each { |section| out << section_xml(section).to_s }
+          out
+        end
+
+        private
+
+        def section_xml(section)
+          case section[:type]
+          when :heading then heading(section)
+          when :text then block_markdown(section[:content])
+          when :table then table(section)
+          when :list then "<ul>#{section[:items].map { |item| "<li>#{inline(item)}</li>" }.join}</ul>\n"
+          when :message then panel(section)
+          when :code then @code.call(section[:content].to_s, section[:lang].to_s)
+          end
+        end
+
+        # level 0 is a section of the analysis: below the page's own headings
+        def heading(section)
+          level = (section[:level].to_i + 3).clamp(3, 6)
+          "<h#{level}>#{h(section[:text])}</h#{level}>\n"
+        end
+
+        def table(section)
+          head = "<tr>#{section[:headers].map { |header| "<th>#{h(header)}</th>" }.join}</tr>\n"
+          rows = section[:rows].map { |cells| "<tr>#{cells.map { |cell| "<td>#{inline(cell)}</td>" }.join}</tr>\n" }
+          "<table><tbody>\n#{head}#{rows.join}</tbody></table>\n"
+        end
+
+        def panel(section)
+          macro = PANELS.fetch(section[:level], "info")
+          %(<ac:structured-macro ac:name="#{macro}"><ac:rich-text-body><p>#{inline(section[:message])}</p></ac:rich-text-body></ac:structured-macro>\n)
+        end
+
+        # A cell, list item or message: markdown and [[links]] inline, a `<br>` or newline breaks the line, other
+        # HTML is text
+        def inline(value)
+          value.to_s.split(BREAK).map { |line| inline_markdown(line) }.join("<br />")
+        end
+
+        def inline_markdown(text)
+          with_links(text) do |marked|
+            html = markdown(marked)
+            html.match(%r{\A<p>((?:(?!</?p>).)*)</p>\z}m) ? Regexp.last_match(1) : html
+          end
+        end
+
+        def block_markdown(text) = "#{with_links(text.to_s) { |marked| markdown(marked) }}\n"
+
+        # Keeps the [[links]] out of kramdown (it would split the brackets) and puts their XML into its result
+        def with_links(text)
+          links = []
+          marked = text.gsub(LINK) { (links << [Regexp.last_match(1).strip, Regexp.last_match(2)&.strip]) && "ARCHSIGHTAL#{links.size - 1}X" }
+          yield(marked).gsub(/ARCHSIGHTAL(\d+)X/) { @link.call(*links[Regexp.last_match(1).to_i]) }
+        end
+
+        # kramdown HTML of the text: raw HTML is shown as text (it would not be well-formed storage XML)
+        def markdown(text)
+          return "" if text.strip.empty?
+
+          safe = text.gsub(%r{<(?!(?:https?://|mailto:))}, "&lt;")
+          Kramdown::Document.new(safe, input: "GFM", entity_output: :as_char, auto_ids: false, hard_wrap: false).to_html.strip
+                            .gsub(%r{<(br|hr|img)([^>]*?)\s*/?>}, '<\1\2 />')
+        end
+
+        def h(text) = ERB::Util.html_escape(text)
+      end
+    end
+  end
+end

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

@@ -97,6 +97,19 @@ module Archsight
           call("DELETE", "/rest/api/content/#{attachment_id}")
         end
 
+        # The names of the labels of a content
+        def labels(id)
+          (get("/rest/api/content/#{id}/label", limit: 500)["results"] || []).map { |label| label["name"] }
+        end
+
+        def add_labels(id, names)
+          post("/rest/api/content/#{id}/label", names.map { |name| { prefix: "global", name: name } })
+        end
+
+        def remove_label(id, name)
+          call("DELETE", "/rest/api/content/#{id}/label", query: { name: name })
+        end
+
         # Let only this user edit the page (best effort: the caller reports a failure).
         def restrict_update_to(id, username)
           put("/rest/api/content/#{id}/restriction", [{ operation: "update", restrictions: { user: [{ type: "known", username: username }] } }])

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

@@ -26,7 +26,7 @@ module Archsight
 
         # @return [String, nil] where the page lives in Confluence, nil if it has no Confluence page
         def self.confluence_url(page)
-          link = page&.annotations&.fetch("page/confluence", nil).to_s.strip
+          link = page&.annotations&.fetch("link/confluence", nil).to_s.strip
           return nil if link.empty?
 
           parsed = PageUrl.parse(link)

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

@@ -12,6 +12,7 @@ require_relative "credentials"
 require_relative "page_url"
 require_relative "storage"
 require_relative "page_properties"
+require_relative "labels"
 
 module Archsight
   module Export
@@ -21,7 +22,8 @@ module Archsight
       # A page is only written when Confluence still holds what Archsight wrote last time: the exporter leaves a
       # marker (a content property with the page version it created) and refuses to overwrite a page that has
       # no marker or a newer version, unless `force` is set. Every written version says in its message that it
-      # was generated, and the page is locked for other editors where the server allows it.
+      # was generated, and the page is locked for other editors where the server allows it. The page's tags
+      # become its labels; the exporter only removes labels it added itself (recorded in the marker).
       class Exporter
         PROPERTY = "archsight"
 
@@ -76,7 +78,7 @@ module Archsight
         end
 
         def link(page)
-          value = page.annotations["page/confluence"].to_s.strip
+          value = page.annotations["link/confluence"].to_s.strip
           value.empty? ? nil : value
         end
 
@@ -138,23 +140,48 @@ module Archsight
           current = content.dig("version", "number")
           body_hash = Digest::SHA256.hexdigest(converted.body)
           files = converted.attachments.transform_values(&:sha)
-          return Result.new(page: page.name, status: :unchanged, message: "version #{current}") if !blocked && marker["bodyHash"] == body_hash && marker["attachments"] == files
-          return would_export(page, current, blocked) if @dry_run
+          labels = Labels.for(page)
+          body_changed = blocked || marker["bodyHash"] != body_hash || marker["attachments"] != files
+          labels_changed = (marker&.fetch("labels", nil) || []) != labels
+          return Result.new(page: page.name, status: :unchanged, message: "version #{current}") unless body_changed || labels_changed
+          return would_export(page, current, blocked, body_changed, labels) if @dry_run
+
+          version = body_changed ? write_body(page, client, content, converted, marker, blocked, id) : current
+          own = marker&.fetch("ownLabels", nil) || []
+          own = sync_labels(client, id, labels, own) if labels_changed
+          state = { "version" => version, "bodyHash" => body_hash, "attachments" => files, "labels" => labels,
+                    "ownLabels" => own, "page" => page.name, "exportedAt" => Time.now.utc.iso8601,
+                    "archsight" => Archsight::VERSION }
+          client.save_property(id, PROPERTY, state, property)
+          return Result.new(page: page.name, status: :exported, message: "labels updated (version #{version})") unless body_changed
+
+          remove_stale_attachments(client, id, marker, files)
+          Result.new(page: page.name, status: :exported, message: "version #{version}#{lock(client, id)}")
+        end
 
+        # Uploads the attachments and writes the new version; returns its number
+        def write_body(page, client, content, converted, marker, blocked, id)
+          current = content.dig("version", "number")
           upload(client, id, converted.attachments, marker&.fetch("attachments", nil) || {})
           updated = client.update_page(id, title: content["title"], space: content.dig("space", "key"), body: converted.body,
                                            version: current + 1, message: message(page, blocked, marker, current))
-          version = updated.dig("version", "number")
-          state = { "version" => version, "bodyHash" => body_hash, "attachments" => files, "page" => page.name,
-                    "exportedAt" => Time.now.utc.iso8601, "archsight" => Archsight::VERSION }
-          client.save_property(id, PROPERTY, state, property)
-          remove_stale_attachments(client, id, marker, files)
-          Result.new(page: page.name, status: :exported, message: "version #{version}#{lock(client, id)}")
+          updated.dig("version", "number")
+        end
+
+        # Gives the page the labels of its tags and removes the labels an earlier export added that are no tag any
+        # more; labels somebody else set are left alone. Returns the labels the exporter owns now.
+        def sync_labels(client, id, labels, own)
+          present = client.labels(id)
+          added = labels - present
+          client.add_labels(id, added) if added.any?
+          (own - labels).each { |name| client.remove_label(id, name) if present.include?(name) }
+          ((own & labels) + added).uniq.sort
         end
 
-        def would_export(page, current, blocked)
-          Result.new(page: page.name, status: :would_export,
-                     message: "would write version #{current + 1}#{" (overwriting: #{blocked})" if blocked}")
+        def would_export(page, current, blocked, body_changed, labels)
+          message = body_changed ? "would write version #{current + 1}#{" (overwriting: #{blocked})" if blocked}" : "would update the labels"
+          message += " with the labels #{labels.join(", ")}" if body_changed && labels.any?
+          Result.new(page: page.name, status: :would_export, message: message)
         end
 
         def upload(client, id, attachments, known)

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Export
+    module Confluence
+      # The `page/tags` of a page as Confluence labels. A label is lowercase and cannot contain spaces or any of
+      # `!#&()*,.:;<>?@[]^`, so those become a dash: `Team:BSS` is the label `team-bss`.
+      module Labels
+        FORBIDDEN = /[\s!#&()*,.:;<>?@\[\]^]+/
+        MAX_LENGTH = 255
+
+        # @return [Array<String>] the labels of the page, sorted, without duplicates
+        def self.for(page)
+          page.annotations["page/tags"].to_s.split(",").filter_map { |tag| label(tag) }.uniq.sort
+        end
+
+        # @return [String, nil] the label for a tag, nil if nothing of it is left
+        def self.label(tag)
+          name = tag.to_s.downcase.gsub(FORBIDDEN, "-").squeeze("-").delete_prefix("-").delete_suffix("-")[0, MAX_LENGTH]
+          name.empty? ? nil : name
+        end
+      end
+    end
+  end
+end

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

@@ -9,9 +9,9 @@ module Archsight
   module Export
     module Confluence
       # The frontmatter of a page as the Page Properties (`details`) macro of Confluence: a two column table
-      # with the status, owner, author, teams, tags and every further property. It is the counterpart of what the
+      # with the status, owner, author, teams and every further property. It is the counterpart of what the
       # import lifts out of such a table, and keeps Confluence's property reports working. People are written as
-      # text (a name), not as user links.
+      # text (a name), not as user links. The other tags are no property: they are the page's labels (`Labels`).
       module PageProperties
         STATUS_COLOURS = {
           "wip" => "yellow", "draft" => "yellow", "rfc" => "blue", "review" => "blue", "proposed" => "blue",
@@ -36,13 +36,11 @@ module Archsight
         # @return [Array<Array(String, String)>] label and the storage XML of the value
         def rows(page)
           annotations = page.annotations
-          tags = annotations["page/tags"].to_s.split(",").map(&:strip).reject(&:empty?)
-          teams, other = tags.partition { |tag| tag.start_with?(TEAM_PREFIX) }
+          teams = annotations["page/tags"].to_s.split(",").map(&:strip).select { |tag| tag.start_with?(TEAM_PREFIX) }
           rows = [["Document status", status(annotations["page/status"])],
                   ["Document owner", text(person(annotations["page/owner"]))],
                   ["Document author", text(person(annotations["page/author"]))],
-                  ["Teams", text(teams.map { |t| t.delete_prefix(TEAM_PREFIX).strip }.join(", "))],
-                  ["Tags", text(other.join(", "))]]
+                  ["Teams", text(teams.map { |t| t.delete_prefix(TEAM_PREFIX).strip }.join(", "))]]
           rows += page.properties.map { |key, value| [key, text(value)] }
           rows.reject { |_, value| value.empty? }
         end

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

@@ -17,6 +17,7 @@ require_relative "drawio"
 require_relative "page_url"
 require_relative "rasterizer"
 require_relative "tables"
+require_relative "analysis_output"
 
 module Archsight
   module Export
@@ -229,9 +230,31 @@ module Archsight
         end
 
         # {macros}, [[Target|label]] and ![[View/Name]] become placeholders before kramdown sees them (it would split the
-        # brackets), except in code.
+        # brackets), except in code; embedded descriptions are written in first.
         def protect(markdown)
-          markdown.split(CODE).each_with_index.map { |part, i| i.odd? ? part : protect_text(part) }.join
+          outside_code(embed_descriptions(markdown)) { |text| protect_text(text) }
+        end
+
+        def outside_code(markdown, &)
+          markdown.split(CODE).each_with_index.map { |part, i| i.odd? ? part : yield(part) }.join
+        end
+
+        # The description of a resource embedded on a line of its own (`![[MotivationGoal/Name]]`) is written into the
+        # page: it is text, not live content. Embeds in that description stay notes (they are not expanded again).
+        def embed_descriptions(markdown)
+          outside_code(markdown) do |text|
+            text.gsub(/^[ \t]*!\[\[([^\]|]+)\]\][ \t]*$/) { embedded_description(Regexp.last_match(1).strip) || Regexp.last_match(0) }
+          end
+        end
+
+        def embedded_description(reference)
+          kind, name = reference.split("/", 2)
+          return if name.nil? || Archsight::Helpers::Embeds::LIVE_KINDS.include?(kind) ||
+                    !Archsight::Helpers::Embeds.embeddable_kind?(kind)
+
+          instance = @database&.instances_by_kind(kind)&.[](name)
+          description = instance&.annotations.to_h["architecture/description"].to_s.strip
+          description.empty? ? nil : description
         end
 
         def protect_text(text)
@@ -240,6 +263,7 @@ module Archsight
             xml && placeholder("LINK", xml, plain: (macro.plain(value) if macro.respond_to?(:plain)))
           end
           text = text.gsub(%r{^[ \t]*!\[\[View/([^\]|]+)\]\][ \t]*$}) { view_embed(Regexp.last_match(1).strip) || Regexp.last_match(0) }
+          text = text.gsub(%r{^[ \t]*!\[\[Analysis/([^\]|]+)\]\][ \t]*$}) { analysis_embed(Regexp.last_match(1).strip) || Regexp.last_match(0) }
           text = text.gsub(/!\[\[([^\]|]+)\]\]/) { placeholder("EMBED", embed_note(Regexp.last_match(1).strip)) }
           text.gsub(Archsight::Helpers::WikiLinks::PATTERN) do
             placeholder("LINK", wiki_link(Regexp.last_match(1).strip, Regexp.last_match(2)&.strip))
@@ -256,6 +280,18 @@ module Archsight
           placeholder("TABLE", xml, plain: embed_note("View/#{name}"))
         end
 
+        # An Analysis on a line of its own is run and its result written into the page (the data of the moment, like a
+        # view); an unknown Analysis stays an embed (a note), the linter reports it.
+        def analysis_embed(name)
+          analysis = @database&.instances_by_kind("Analysis")&.[](name)
+          return nil unless analysis
+
+          require_relative "../../analysis"
+          result = Archsight::Analysis::Executor.new(@database).execute(analysis)
+          output = AnalysisOutput.new(link: ->(target, label) { wiki_link(target, label) }, code: ->(source, language) { code(source, language) })
+          placeholder("TABLE", output.xml(name, result), plain: embed_note("Analysis/#{name}"))
+        end
+
         # The XML of a table, or nothing and a problem (the page is not exported) if it cannot be built
         def table_xml(what)
           yield