archsight 0.3.0 → 0.3.1

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

@@ -1,16 +1,22 @@
 # frozen_string_literal: true
 
 require "erb"
+require "uri"
 require "digest"
 require "kramdown"
 require "kramdown-parser-gfm"
 require_relative "../../assets"
 require_relative "../../diagram"
 require_relative "../../helpers/macros"
+require_relative "../../helpers/view_blocks"
+require_relative "../../helpers/requirements_blocks"
+require_relative "../../query"
+require_relative "../../requirements"
 require_relative "diagram_links"
 require_relative "drawio"
 require_relative "page_url"
 require_relative "rasterizer"
+require_relative "tables"
 
 module Archsight
   module Export
@@ -31,11 +37,18 @@ module Archsight
           def convert_codeblock(elem, _indent)
             language = elem.options[:lang].to_s
             return @options[:storage].diagram(elem.value, nil) if language == "asd"
+            return @options[:storage].view_block(elem.value) if language == "view"
+            return @options[:storage].requirements_block(elem.value) if language == "requirements"
 
             @options[:storage].code(elem.value, language)
           end
 
           def convert_p(elem, indent)
+            only = elem.children.length == 1 && elem.children.first.type == :text ? elem.children.first.value.strip : nil
+            if only && (table = @options[:storage].table_placeholder(only))
+              return table
+            end
+
             image = elem.children.reject { |c| c.type == :text && c.value.strip.empty? }
             if image.length == 1 && image.first.type == :img && (block = @options[:storage].block_image(image.first.attr))
               return "#{block}\n"
@@ -48,9 +61,15 @@ module Archsight
             @options[:storage].image(elem.attr["src"].to_s, elem.attr["alt"].to_s)
           end
 
-          # A macro whose output is a link of its own (Jira) is shown as plain text inside a link: no link in a link
+          # A link to a page of Archsight becomes a link to its Confluence page, or just its text if it has none;
+          # a macro whose output is a link of its own (Jira) is shown as plain text inside a link: no link in a link
           def convert_a(elem, indent)
-            @options[:storage].in_link { super }
+            storage = @options[:storage]
+            target = storage.link_target(elem.attr["href"].to_s)
+            return inner(elem, indent) unless target
+
+            elem.attr["href"] = target
+            storage.in_link { super }
           end
 
           def convert_text(elem, indent)
@@ -69,7 +88,8 @@ module Archsight
         }.freeze
         KNOWN_LANGUAGES = %w[actionscript3 applescript bash c# cpp css coldfusion delphi diff erlang groovy html/xml java javafx
                              javascript perl php text powershell python ruby scala sql vb yaml].freeze
-        PLACEHOLDER = /ARCHSIGHT(LINK|EMBED)(\d+)X/
+        PLACEHOLDER = /ARCHSIGHT(LINK|EMBED|TABLE)(\d+)X/
+        TABLE_PLACEHOLDER = /\AARCHSIGHTTABLE(\d+)X\z/
         CODE = /(^[ \t]*(?:```|~~~).*?^[ \t]*(?:```|~~~)[ \t]*$|`[^`\n]*`)/m
 
         # @param page_name [String] used to name generated attachments
@@ -101,13 +121,12 @@ module Archsight
 
         # @param markdown [String] body of the page
         # @param toc [Boolean] add a table of contents
-        # @param header [String] storage format put between the banner and the body (the page properties)
+        # @param header [String] storage format of the page properties, shown top left next to the banner
         # @return [Converted]
         def convert(markdown, toc: false, header: "")
           document = Kramdown::Document.new(protect(markdown), input: "GFM", auto_ids: false, entity_output: :as_char, smart_quotes: %w[apos apos quot quot])
           html, = Converter.convert(document.root, document.options.merge(storage: self))
-          body = banner + header + (toc ? %(<ac:structured-macro ac:name="toc" />\n) : "") + html
-          Converted.new(body: body, attachments: @attachments, problems: @problems)
+          Converted.new(body: layout(header, banner, (toc ? %(<ac:structured-macro ac:name="toc" />\n) : "") + html), attachments: @attachments, problems: @problems)
         end
 
         # ---- called by the converter
@@ -149,11 +168,43 @@ module Archsight
 
         def restore(text)
           text.gsub(PLACEHOLDER) do
+            kind = Regexp.last_match(1)
             xml, plain = @placeholders.fetch(Regexp.last_match(2).to_i)
-            @in_link && plain ? plain : xml
+            # a table that is not alone in its paragraph (see table_placeholder) is shown as the note
+            kind == "TABLE" || (@in_link && plain) ? plain : xml
           end
         end
 
+        # A ```view block as a table (the data of the moment of the export), block XML
+        def view_block(source)
+          table_xml("view block") { Tables.xml(ViewTable.from_block(database!, source)) }
+        end
+
+        # A ```requirements block as a table, block XML
+        def requirements_block(source)
+          table_xml("requirements block") do
+            Tables.xml(Archsight::Requirements.table(database!, Helpers::RequirementsBlocks.parse(source)), empty: "No requirements")
+          end
+        end
+
+        # The table of a paragraph that holds nothing but the placeholder of a `![[View/Name]]` (a table cannot sit
+        # inside a paragraph), nil for any other text
+        def table_placeholder(text)
+          index = text[TABLE_PLACEHOLDER, 1]
+          index && @placeholders.fetch(index.to_i).first
+        end
+
+        # Where a markdown link leads in Confluence. The links of a page point into Archsight (`/pages/<name>`,
+        # `/kinds/...`), which does not exist there: a page that has a Confluence page is linked to it, any other
+        # Archsight path is not a link.
+        # @return [String, nil] the href to use, nil for the text only
+        def link_target(href)
+          return href unless href.start_with?("/") && !href.start_with?("//")
+
+          page = archsight_page(href)
+          page && confluence_url(page)
+        end
+
         # Runs the block for the content of a link
         def in_link
           previous = @in_link
@@ -165,6 +216,14 @@ module Archsight
 
         private
 
+        # The page layout: the page properties top left, the hint that the page is generated top right (a narrow
+        # sidebar), then the content in a section of its own, full width
+        def layout(properties, banner, content)
+          cell = ->(xml) { %(<ac:layout-cell>#{xml.empty? ? "<p />" : xml}</ac:layout-cell>) }
+          %(<ac:layout><ac:layout-section ac:type="two_right_sidebar">#{cell.call(properties)}#{cell.call(banner)}</ac:layout-section>) +
+            %(<ac:layout-section ac:type="single">#{cell.call(content)}</ac:layout-section></ac:layout>)
+        end
+
         def banner
           %(<ac:structured-macro ac:name="info"><ac:rich-text-body><p>#{format(BANNER, source: h(@source))}</p></ac:rich-text-body></ac:structured-macro>\n)
         end
@@ -180,12 +239,35 @@ module Archsight
             xml = macro.confluence(value, Archsight::Helpers::Macros::Context.new(@database, nil))
             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(/!\[\[([^\]|]+)\]\]/) { 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))
           end
         end
 
+        # A View on a line of its own becomes its table; an unknown View stays an embed (a note), the linter reports it.
+        # Next to other text of its paragraph the table cannot be placed and the note is shown (`plain`).
+        def view_embed(name)
+          view = @database&.instances_by_kind("View")&.[](name)
+          return nil unless view
+
+          xml = table_xml("view #{name}") { Tables.xml(ViewTable.from_view(@database, view)) }
+          placeholder("TABLE", xml, plain: embed_note("View/#{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
+        rescue Helpers::ViewBlocks::Error, Helpers::RequirementsBlocks::Error, Archsight::Query::QueryError => e
+          problem("#{what}: #{e.message}")
+          ""
+        end
+
+        def database!
+          @database || raise(Helpers::ViewBlocks::Error, "the export has no database to read the data from")
+        end
+
         def placeholder(kind, xml, plain: nil)
           @placeholders << [xml, plain]
           "ARCHSIGHT#{kind}#{@placeholders.length - 1}X"
@@ -195,9 +277,18 @@ module Archsight
           "<em>#{h(reference)} (live content, shown in Archsight only)</em>"
         end
 
+        # The page an Archsight path (`/pages/<name>`, `/kinds/Page/instances/<name>`, optionally with #anchor or ?query) shows
+        def archsight_page(href)
+          path = href.split(/[#?]/, 2).first.to_s
+          name = path[%r{\A/pages/(.+)\z}, 1] || path[%r{\A/kinds/Page/instances/([^/]+)\z}, 1]
+          name && @wiki.page_for(URI.decode_uri_component(name))
+        rescue ArgumentError
+          nil
+        end
+
         def wiki_link(target, label)
           page = @wiki.page_for(target)
-          text = label || page&.title || target
+          text = label || @wiki.label_for(target)
           url = page && confluence_url(page)
           url ? %(<a href="#{h(url)}">#{h(text)}</a>) : h(text)
         end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "erb"
+require "kramdown"
+require "kramdown-parser-gfm"
+require_relative "../../view_table"
+require_relative "../../helpers/macros"
+require_relative "diagram_links"
+
+module Archsight
+  module Export
+    module Confluence
+      # A ViewTable::Table (the result of a view or of the requirements of some resources) as a regular table in
+      # storage format. Views and requirements are live in Archsight; in Confluence they are the data of the moment
+      # of the export.
+      module Tables
+        # status of a requirement -> colour of the Confluence status macro (as the web UI colours them)
+        STATUS_COLOURS = { "implemented" => "green", "partial" => "yellow", "planned" => "blue" }.freeze
+
+        # priority of a requirement -> colour of the Confluence status macro
+        PRIORITY_COLOURS = { "must" => "red", "should" => "yellow", "may" => "grey" }.freeze
+
+        module_function
+
+        # @param empty [String] shown instead of the table when there are no rows
+        # @return [String] block XML
+        def xml(table, empty: "No resources found")
+          out = +""
+          out << %(<p><strong>#{h(table.title)}</strong> (#{table.total} #{table.total == 1 ? "item" : "items"})</p>\n) unless table.title.to_s.empty?
+          if table.rows.empty?
+            out << %(<p><em>#{h(empty)}</em></p>\n)
+          else
+            out << "<table><tbody>\n#{row(table.columns.map { |c| "<th>#{h(c)}</th>" })}"
+            table.rows.each { |cells| out << row(cells.map { |cell| "<td>#{cell_xml(cell)}</td>" }) }
+            out << "</tbody></table>\n"
+          end
+          out << %(<p><em>#{table.cut} more #{table.cut == 1 ? "row" : "rows"} not shown, see Archsight</em></p>\n) if table.cut.positive?
+          out
+        end
+
+        def row(cells) = "<tr>#{cells.join}</tr>\n"
+
+        def cell_xml(cell)
+          return cell.resources.map { |resource| resource_xml(resource) }.join("<br />") unless cell.resources.empty?
+
+          case cell.as
+          when :status then lozenge(cell.text, STATUS_COLOURS)
+          when :priority then cell.text.empty? ? "" : lozenge(cell.text, PRIORITY_COLOURS)
+          when :markdown then markdown_xml(cell.text)
+          else h(cell.text).gsub("\n", "<br />")
+          end
+        end
+
+        # A link where the resource has a page in Confluence, else its name
+        def resource_xml(resource)
+          url = DiagramLinks.confluence_url(resource)
+          url ? %(<a href="#{h(url)}">#{h(resource.name)}</a>) : h(resource.name)
+        end
+
+        def lozenge(text, colours)
+          Helpers::Macros::Status.confluence(Helpers::Macros::Status::Value.new(colours.fetch(text, "grey"), text))
+        end
+
+        # Inline markdown (a requirement's story): the HTML of kramdown without the paragraph around a single line.
+        # Raw HTML in the text is shown as text (it would not be well-formed storage XML); `<https://..>` links stay.
+        def markdown_xml(text)
+          return "" if text.to_s.strip.empty?
+
+          safe = text.gsub(%r{<(?!(?:https?://|mailto:))}, "&lt;")
+          html = Kramdown::Document.new(safe, input: "GFM", entity_output: :as_char, auto_ids: false).to_html.strip
+          html.match(%r{\A<p>((?:(?!</?p>).)*)</p>\z}m) ? Regexp.last_match(1) : html
+        end
+
+        def h(text) = ERB::Util.html_escape(text)
+      end
+    end
+  end
+end

data/lib/archsight/helpers/fenced_blocks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "erb"
+require "yaml"
+
+module Archsight
+  module Helpers
+    # What the ```lang blocks of rendered markdown that become something else (ViewBlocks, RequirementsBlocks) have
+    # in common. Two steps, so what a block becomes stays out of the markdown post-processing (URL auto-linking,
+    # macros and `[[Name]]` links are plain-text passes over the whole HTML):
+    #
+    #   html, blocks = FencedBlocks.extract(html, language: "view", prefix: "view-block") { |source, original| ... }
+    #   ...further processing of html...
+    #   html = FencedBlocks.restore(html, blocks, prefix: "view-block")
+    module FencedBlocks
+      module_function
+
+      # @yield [source, original] the block's source and its `<pre><code>` HTML; returns the HTML to put in its place
+      # @return [Array(String, Hash{String => String})] HTML with a placeholder per block, and the replacement for each
+      def extract(html, language:, prefix:)
+        blocks = {}
+        pattern = %r{<pre><code class="language-#{Regexp.escape(language)}">(.*?)</code></pre>}m
+        replaced = html.gsub(pattern) do |block|
+          placeholder = "<!--#{prefix}:#{blocks.size}-->"
+          blocks[placeholder] = yield(::CGI.unescapeHTML(Regexp.last_match(1)), block)
+          placeholder
+        end
+        [replaced, blocks]
+      end
+
+      def restore(html, blocks, prefix:)
+        return html if blocks.empty?
+
+        html.gsub(/<!--#{Regexp.escape(prefix)}:\d+-->/) { |placeholder| blocks.fetch(placeholder, placeholder) }
+      end
+
+      # Source of every block of that language in `markdown` (for the linter).
+      def sources(markdown, language:)
+        markdown.scan(/^[ \t]*(?:```|~~~)#{Regexp.escape(language)}[ \t]*\n(.*?)^[ \t]*(?:```|~~~)[ \t]*$/m).flatten
+      end
+
+      # `<div class="css-class"><p><strong>Label:</strong> message</p>original</div>`
+      def error_box(css_class, label, message, original)
+        %(<div class="#{css_class}"><p><strong>#{label}:</strong> #{::ERB::Util.html_escape(message)}</p>#{original}</div>)
+      end
+
+      # `<div class="css-class" data-a="..." ...>original</div>`, the values escaped
+      def placeholder(css_class, data, original)
+        attributes = data.map { |name, value| %( data-#{name}="#{::ERB::Util.html_escape(value)}") }.join
+        %(<div class="#{css_class}"#{attributes}>#{original}</div>)
+      end
+
+      # A YAML mapping, without aliases or arbitrary objects
+      # @raise [Psych::Exception]
+      def load_yaml(source)
+        YAML.safe_load(source, aliases: false)
+      end
+    end
+  end
+end

data/lib/archsight/helpers/requirements_blocks.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "fenced_blocks"
+
+module Archsight
+  module Helpers
+    # Turns ```requirements fenced blocks in rendered markdown into the table of business requirements of a
+    # selection of resources (see Archsight::Requirements):
+    #
+    #   ```requirements
+    #   title: Requirements of the backup services     # optional
+    #   of: 'ApplicationService: name =~ "Backup"'     # required: query selecting the resources
+    #   priority: must                                 # optional: must, should, may (one or a list)
+    #   status: [implemented, partial]                 # optional: implemented, partial, planned
+    #   ```
+    #
+    # Like views and embeds, rendering never runs the query: the block becomes a placeholder carrying the filter and
+    # the frontend asks the API (`GET /api/v1/requirements`). The source stays inside the placeholder for consumers
+    # that do not run the frontend (API, MCP). Extract and restore like DiagramBlocks, see FencedBlocks.
+    module RequirementsBlocks
+      KEYS = %w[title of priority status].freeze
+
+      class Error < StandardError; end
+
+      module_function
+
+      def extract(html)
+        FencedBlocks.extract(html, language: "requirements", prefix: "requirements-block") { |source, original| render_block(source, original) }
+      end
+
+      def restore(html, blocks)
+        FencedBlocks.restore(html, blocks, prefix: "requirements-block")
+      end
+
+      # Source of every ```requirements block in `markdown` (for the linter).
+      def sources(markdown)
+        FencedBlocks.sources(markdown, language: "requirements")
+      end
+
+      # The filter a block describes.
+      # @return [Hash] `{ title:, of:, priority: [String], status: [String] }`
+      # @raise [Error] if the block is not a valid filter
+      def parse(source)
+        doc = load(source)
+        raise Error, "expected a mapping with `of`, got #{doc.class.name.downcase}" unless doc.is_a?(Hash)
+
+        unknown = doc.keys.map(&:to_s) - KEYS
+        raise Error, "unknown key #{unknown.first.inspect}, known are #{KEYS.join(", ")}" unless unknown.empty?
+
+        of = doc["of"].to_s.strip
+        raise Error, "`of` is missing: the query selecting the resources" if of.empty?
+
+        check_query(of)
+        { title: doc["title"].to_s, of: of,
+          priority: values(doc["priority"], Archsight::Requirements::PRIORITIES, "priority"),
+          status: values(doc["status"], Archsight::Requirements::STATUSES.values, "status") }
+      end
+
+      def render_block(source, original)
+        spec = parse(source)
+        data = { title: spec[:title], of: spec[:of], priority: spec[:priority].join(","), status: spec[:status].join(",") }
+        FencedBlocks.placeholder("requirements-embed", data, original)
+      rescue Error => e
+        FencedBlocks.error_box("requirements-block-error", "Requirements error", e.message, original)
+      end
+
+      def load(source)
+        FencedBlocks.load_yaml(source)
+      rescue Psych::Exception => e
+        raise Error, "invalid YAML: #{e.message}"
+      end
+
+      def check_query(query)
+        Archsight::Query.parse(query)
+      rescue Archsight::Query::QueryError => e
+        raise Error, "invalid query: #{e.message}"
+      end
+
+      # A scalar or a list, each value one of `allowed`
+      def values(value, allowed, name)
+        list = Array(value).map { |v| v.to_s.strip }.reject(&:empty?)
+        invalid = list - allowed
+        raise Error, "#{name} must be #{allowed.join(", ")}, not #{invalid.first.inspect}" unless invalid.empty?
+
+        list
+      end
+    end
+  end
+end

data/lib/archsight/helpers/view_blocks.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "fenced_blocks"
+
+module Archsight
+  module Helpers
+    # Turns ```view fenced blocks in rendered markdown into inline views: a View defined in place, written as the
+    # View resource itself, shown like an embedded `![[View/Name]]`:
+    #
+    #   ```view
+    #   kind: View
+    #   metadata:
+    #     name: Services without backup      # the title, optional
+    #     annotations:
+    #       view/query: 'ApplicationService: backup/mode == "none"'
+    #       view/fields: name, @owner
+    #   ```
+    #
+    # Like embeds, rendering never runs the query: the block becomes a placeholder carrying the spec, the frontend
+    # runs the query. The source stays inside the placeholder for consumers that do not run the frontend (API, MCP).
+    #
+    # Two steps, like DiagramBlocks, so the query text stays out of the markdown post-processing (URL auto-linking,
+    # macros and `[[Name]]` links are plain-text passes over the whole HTML):
+    #
+    #   html, blocks = ViewBlocks.extract(html)   # blocks -> placeholders
+    #   ...further processing of html...
+    #   html = ViewBlocks.restore(html, blocks)   # placeholders -> view placeholders / error boxes
+    module ViewBlocks
+      TYPES = %w[list:name list:name+kind].freeze
+      KEYS = %w[view/query view/fields view/sort view/type].freeze
+
+      class Error < StandardError; end
+
+      module_function
+
+      # @return [Array(String, Hash{String => String})] HTML with a placeholder per view block, and the rendered
+      #   replacement for each placeholder
+      def extract(html)
+        FencedBlocks.extract(html, language: "view", prefix: "view-block") { |source, original| render_block(source, original) }
+      end
+
+      def restore(html, blocks)
+        FencedBlocks.restore(html, blocks, prefix: "view-block")
+      end
+
+      # Source of every ```view block in `markdown` (for the linter).
+      def sources(markdown)
+        FencedBlocks.sources(markdown, language: "view")
+      end
+
+      # The View a block describes.
+      # @return [Hash] `{ title:, query:, fields: [String], sort: [String], type: String }`
+      # @raise [Error] if the block is not a valid View
+      def parse(source)
+        doc = load(source)
+        raise Error, "expected a View resource (a YAML mapping), got #{doc.class.name.downcase}" unless doc.is_a?(Hash)
+        raise Error, "kind must be View, not #{doc["kind"].inspect}" if doc.key?("kind") && doc["kind"] != "View"
+
+        annotations = annotations(doc)
+        query = annotations["view/query"].to_s.strip
+        raise Error, "view/query is missing" if query.empty?
+
+        check_query(query)
+        type = annotations["view/type"]&.to_s || TYPES.last
+        raise Error, "view/type must be one of #{TYPES.join(", ")}, not #{type.inspect}" unless TYPES.include?(type)
+
+        { title: doc.dig("metadata", "name").to_s, query: query, type: type,
+          fields: list(annotations["view/fields"]), sort: list(annotations["view/sort"]) }
+      end
+
+      def render_block(source, original)
+        spec = parse(source)
+        data = { title: spec[:title], query: spec[:query], fields: spec[:fields].join(","), sort: spec[:sort].join(","), type: spec[:type] }
+        FencedBlocks.placeholder("view-embed", data, original)
+      rescue Error => e
+        FencedBlocks.error_box("view-block-error", "View error", e.message, original)
+      end
+
+      def load(source)
+        FencedBlocks.load_yaml(source)
+      rescue Psych::Exception => e
+        raise Error, "invalid YAML: #{e.message}"
+      end
+
+      def annotations(doc)
+        annotations = doc.dig("metadata", "annotations")
+        raise Error, "metadata.annotations must be a mapping" unless annotations.nil? || annotations.is_a?(Hash)
+
+        annotations ||= {}
+        unknown = annotations.keys.map(&:to_s).select { |key| key.start_with?("view/") } - KEYS
+        raise Error, "unknown annotation #{unknown.first.inspect}, a view knows #{KEYS.join(", ")}" unless unknown.empty?
+
+        annotations.transform_keys(&:to_s)
+      end
+
+      def check_query(query)
+        Archsight::Query.parse(query)
+      rescue Archsight::Query::QueryError => e
+        raise Error, "invalid query: #{e.message}"
+      end
+
+      def list(value)
+        value.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/archsight/helpers/wiki_links.rb

@@ -11,6 +11,7 @@ module Archsight
     # render as a `broken-link` span.
     class WikiLinks
       PATTERN = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/
+      HOVER_LENGTH = 200
 
       def initialize(database, resolver: ResourceResolver.new(database))
         @database = database
@@ -43,6 +44,26 @@ module Archsight
         find_page(target)
       end
 
+      # The text of a link without an explicit label: a page by its title, a resource named `Kind/Name` by its name
+      # (the kind is in the hover text), anything else as written (so a broken reference shows what must be fixed)
+      def label_for(target)
+        page = find_page(target)
+        return page.title if page
+
+        found = target.include?("/") ? @resolver.find(target) : nil
+        found.is_a?(Array) ? found.last : target
+      end
+
+      # The page or resource a target names, nil if it names none or is ambiguous
+      def target_for(target)
+        page = find_page(target)
+        return page if page
+
+        found = @resolver.find(target)
+        found = find_partial(target) || found if found == :missing && !target.include?("/")
+        found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
+      end
+
       # Page path for a page name, nil if there is no such page
       def page_path(page)
         "/pages/#{ERB::Util.url_encode(page.name)}"
@@ -55,19 +76,32 @@ module Archsight
           target = ::Regexp.last_match(1).strip
           explicit_label = ::Regexp.last_match(2)&.strip
           href = resolve(target)
-          label = explicit_label || default_label(target)
+          label = explicit_label || label_for(target)
           text = ERB::Util.html_escape(label)
           if href.is_a?(String)
-            %(<a href="#{ERB::Util.html_escape(href)}">#{text}</a>)
+            %(<a href="#{ERB::Util.html_escape(href)}"#{hover(target_for(target))}>#{text}</a>)
           else
             %(<span class="broken-link" title="#{href == :ambiguous ? "Ambiguous reference" : "Resource not found"}">#{text}</span>)
           end
         end
       end
 
-      # Pages are shown by title, everything else by the text as written
-      def default_label(target)
-        find_page(target)&.title || target
+      # `title` attribute of a link: the kind and the first line of the description (the status of a page)
+      def hover(instance)
+        return "" unless instance
+
+        kind = instance.class.name.split("::").last
+        detail = kind == "Page" ? instance.annotations["page/status"] : plain_line(instance.annotations["architecture/description"])
+        text = [kind, detail].map(&:to_s).reject(&:empty?).join("\n")
+        %( title="#{ERB::Util.html_escape(text)}")
+      end
+
+      # The first line of a markdown text as plain text, at most HOVER_LENGTH characters
+      def plain_line(markdown)
+        line = markdown.to_s.lines.map(&:strip).find { |l| !l.empty? }.to_s
+        line = line.gsub(%r{!?\[\[([^\]|]+/)?([^\]|]+)(?:\|([^\]]+))?\]\]}) { Regexp.last_match(3) || Regexp.last_match(2) }
+                   .gsub(/!?\[([^\]]*)\]\([^)]*\)/, '\1').gsub(/\A[#>*\-\s]+/, "").delete("`*_")
+        line.length > HOVER_LENGTH ? "#{line[0, HOVER_LENGTH - 1].rstrip}…" : line
       end
 
       def find_page(target)

data/lib/archsight/helpers.rb

@@ -3,6 +3,9 @@
 require_relative "helpers/formatting"
 require_relative "helpers/analysis_renderer"
 require_relative "helpers/diagram_blocks"
+require_relative "helpers/fenced_blocks"
+require_relative "helpers/view_blocks"
+require_relative "helpers/requirements_blocks"
 require_relative "helpers/resource_resolver"
 require_relative "helpers/embeds"
 require_relative "helpers/wiki_links"

data/lib/archsight/import/handlers/go_grapher.rb

@@ -55,6 +55,9 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
     output = +""
 
     modules.each do |rel_dir, mod_name|
+      comp_name = component_name(mod_name)
+      next unless comp_name
+
       mod_dir = rel_dir == "." ? path : File.join(path, rel_dir)
       specs = detect_openapi_specs(mod_dir)
       existing_interfaces = database&.instances_by_kind("ApplicationInterface") || {}
@@ -69,7 +72,7 @@ class Archsight::Import::Handlers::GoGrapher < Archsight::Import::Handlers::Grap
       # is expected to keep and refine, not auto-regenerated on each run.
       component = untracked_resource_yaml(
         kind: "ApplicationComponent",
-        name: component_name(mod_name),
+        name: comp_name,
         spec: comp_spec
       )
       output << YAML.dump(component)

data/lib/archsight/import/handlers/go_module_parser.rb

@@ -133,9 +133,12 @@ module Archsight::Import::Handlers::GoModuleParser
   # Convert a Go module path to an ApplicationComponent name.
   # Strips the SCM host segment and joins remaining path segments with ":".
   # "github.com/example-org/billing-service/pkg" → "example-org:billing-service:pkg"
+  # A module path without a host ("module foo") has nothing left after stripping
+  # it and gets no component, rather than one with an empty name.
+  # @return [String, nil]
   def component_name(mod_name)
     parts = mod_name.split("/")
     parts.shift
-    parts.join(":")
+    parts.join(":") unless parts.empty?
   end
 end