archsight 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00045b0530964a0ff8be08ceef27b47fe7e91b630ba09a243b087f4bce523add
-  data.tar.gz: 0abb8b4cf7d274318451a094f40a48992e6759ac2d56f6a5f70fd8d18e59cd06
+  metadata.gz: 0312d7e0c0790b8b2a117ad6277e49bfb18c61545134b27510fa3209e951697d
+  data.tar.gz: 94915564bbbab8c59e139422c1a99317ec7fd5a87370e9905b16ed330cd56951
 SHA512:
-  metadata.gz: 756394456261aca49ea0c828d9bf61996a8175da001c335ac802e06f9232641a587732765140395dc55e224a6f6d5d4facda26cdb26ddde27bb8272a6b3d09ee
-  data.tar.gz: 2f9584331b16063497e712f4b48b20abec72e946932af5986418d8e137ffa4eb55f393e05802974a7eec47edff0d6cf84b6de6d2614b2b553f8bcad51ebeed27
+  metadata.gz: 7b15fc5fb4130fe0783efe8e20cf7aa2ce3962e6566d54ae5c1c85834692e5363cc3a9667eb2f7cfbf17832badc0461cbf684c1d5a5c04711e5e529d1fb11bb2
+  data.tar.gz: 36e154fb3fefd3dd0de59ced6d6f404e4238242ec182d78f5ced051fec01002a3af8dbe11c8eced3ff16fc978791301627fe3f06641e0ea859e9a529326ea814

data/docs/configuration.md

@@ -37,7 +37,7 @@ that is set but empty counts as not set.
 | `jira.server` | `ARCHSIGHT_JIRA_SERVER` | Name of the Jira server as Confluence knows it (the `server` parameter of its Jira macro). Needed by the Confluence export when Confluence has more than one Jira server: without it the exported `{jira:KEY}` macros have no server and Confluence shows an error |
 | `jira.server_id` | `ARCHSIGHT_JIRA_SERVER_ID` | Id of that server (the `serverId` parameter). Copy both from the storage format of a Jira macro that already works in Confluence (page "Edit in storage format") |
 | `jira.token` | `ARCHSIGHT_JIRA_TOKEN` | Reserved, nothing uses it yet |
-| `import.cache_root` | `ARCHSIGHT_IMPORT_CACHE_ROOT` | Where the GitHub, GitLab and repository imports clone repositories, and what importers of the resources repository get as `cache_root` / `ARCHSIGHT_CACHE_DIR`. Default `~/.cache/archsight/git`; an import's own `import/config/cacheRoot` wins, see [Importers of the Resources Repository](/doc/import#importers-of-the-resources-repository) |
+| `import.cache_root` | `ARCHSIGHT_IMPORT_CACHE_ROOT` | Where the GitHub, GitLab and repository imports clone repositories, and what importers of the resources repository get as `cache_root` / `ARCHSIGHT_CACHE_DIR`. Default `~/.cache/archsight/git`; an import's own `import/config/cacheRoot` wins, see [Importers of the Resources Repository](/doc/import#importers-of-the-resources-repository). Every import makes sure the clones are not indexed by Spotlight (macOS): an empty `.metadata_never_index` in `~/.cache/archsight`, or in the cache root when it is elsewhere |
 
 ## Command line
 

data/docs/modeling.md

@@ -190,6 +190,9 @@ TechnologySystemSoftware, TechnologyService, TechnologyArtifact). The same princ
    with `composedOf` (metro network → site networks, campus → halls, backbone → links).
 7. A network that supports a metro region is `locatedAt` the Location and `composedOf` the networks of its sites.
 8. Nodes attach to networks with `servedBy` and stand in facilities with `locatedAt`.
+   An `ApplicationInterface` is `servedBy` the networks on which it can be reached. Write them only when they are
+   known: an interface without a network makes no claim about its reachability, and an analysis cannot tell "not
+   reachable" from "not recorded".
 9. An overlay that software builds (an SDN agent wiring tenant networks on each host, an operator creating VXLAN
    segments, a load-balancer controller announcing public addresses) is `realizedBy` that `ApplicationComponent` or
    `ApplicationService` (ArchiMate cross-layer realization). This holds even when the software runs on the nodes the
@@ -546,6 +549,7 @@ Which kind to pick is in [Choosing the Kind: Infrastructure](#choosing-the-kind-
 | `TechnologyCommunicationNetwork` | `realizedBy` | `TechnologyDevice` (the switches and routers that build it) |
 | `TechnologyCommunicationNetwork` | `connects` | `TechnologyDevice` (the devices attached to it) |
 | `TechnologyNode` | `servedBy` | `TechnologyCommunicationNetwork` |
+| `ApplicationInterface` | `servedBy` | `TechnologyCommunicationNetwork` (the networks on which it can be reached) |
 
 - **Underlay and overlay:** the underlay *serves* the overlay, so the overlay is `servedBy` the underlay. A BGP-EVPN
   network that carries customer workloads is one `overlay` network served by the underlay and realized by the routing
@@ -560,6 +564,10 @@ Which kind to pick is in [Choosing the Kind: Infrastructure](#choosing-the-kind-
 - **Attachment:** a node is `servedBy` the networks it is attached to; the network page lists them. A physical
   device is attached the other way round: the network `connects` it, so the network can also be `realizedBy` the
   same switch without a cycle.
+- **Reachability of an interface:** an `ApplicationInterface` is `servedBy` the networks on which it can be reached,
+  next to the `TechnologyInterface` that carries it. With `api/authenticationMethod` this is the exposure of the
+  interface (see the example analysis `Analysis:Interface:ExposedWithoutAuthentication`). Leave it out when the
+  networks are not known.
 
 ```
 # all overlay networks

data/docs/pages.md

@@ -339,9 +339,9 @@ confluence:
 With `drawio` off nothing draw.io-specific is written, so any Confluence shows the diagrams. Rendering a `.drawio` needs the
 draw.io desktop CLI (`drawio`, or `ARCHSIGHT_DRAWIO_CLI`) on the machine that exports; the preview of an SVG needs
 `rsvg-convert` or that CLI. A diagram that cannot be rendered fails the page instead of leaving a blank diagram. Attachments an
-earlier export added and the page no longer uses are removed; attachments added by others are left alone. `[[links]]` and markdown links to pages (`[text](/pages/name)`) that have a Confluence link
+earlier export added and the page no longer uses are removed (a draw.io diagram is attached under its name and a hash of its content, so a changed diagram is a new attachment, because the draw.io macro would keep showing the first version of an attachment it names); attachments added by others are left alone. `[[links]]` and markdown links to pages (`[text](/pages/name)`) that have a Confluence link
 become links to them, other links to Archsight (pages without a Confluence link, resources, searches) are plain text. A page with a broken image, a diagram that does not render or an invalid
-```` ```view ````/```` ```requirements ```` block is not exported and reported as failed. The Confluence title is kept. The exported page uses the Confluence layout: the page properties top left, the note that the page is generated by Archsight top right, and the content below in a section of its own.
+```` ```view ````/```` ```requirements ```` block is not exported and reported as failed. The Confluence title is kept. The exported page uses the Confluence layout: the page properties top left, the note that the page is generated by Archsight top right, and the content below in a section of its own. When the resources are a git checkout with an `origin` remote, the note names the repository and links the source file to its page on the git host (GitHub `/blob/`, GitLab `/-/blob/`, on the checked out branch, or the commit when the HEAD is detached; other hosts get only the repository link, and so does a file git does not track). User names and tokens in the remote URL never appear in the link.
 
 **Views and requirements** are live in Archsight, so Confluence gets a regular table with the data of the moment of the export (every
 export writes the current data; a page whose tables did not change is `unchanged`): `![[View/Name]]` on a line of its own, a

data/lib/archsight/analysis/typst_renderer.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "../markdown"
 require_relative "../diagram"
 
 module Archsight
@@ -192,7 +191,7 @@ module Archsight
       # ---- markdown -> Typst
 
       def markdown(source, inline: false)
-        root = Kramdown::Document.new(source.to_s, input: "GFM").root
+        root = Archsight::Markdown.document(source).root
         out = blocks(root.children)
         inline ? out.gsub(/\n\n+/, " #linebreak() ") : out
       end

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

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "erb"
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "../../markdown"
 
 module Archsight
   module Export
@@ -90,8 +89,8 @@ module Archsight
           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 />')
+          Archsight::Markdown.unwrapped(safe, entity_output: :as_char, auto_ids: false).to_html.strip
+                             .gsub(%r{<(br|hr|img)([^>]*?)\s*/?>}, '<\1\2 />')
         end
 
         def h(text) = ERB::Util.html_escape(text)

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

@@ -7,6 +7,7 @@ require "time"
 require_relative "../../version"
 require_relative "../../assets"
 require_relative "../../helpers"
+require_relative "../../git_source"
 require_relative "client"
 require_relative "credentials"
 require_relative "page_url"
@@ -117,7 +118,8 @@ module Archsight
           storage = Storage.new(page_name: page.name, source: relative_source(page),
                                 base_dir: Assets.base_dir_for(page, resources_dir: @resources_dir).to_s,
                                 resources_dir: @resources_dir, wiki: Helpers::WikiLinks.new(@database), page_id: id, base: url.base,
-                                drawio: drawio?, diagram_links: DiagramLinks.new(@database), database: @database)
+                                drawio: drawio?, diagram_links: DiagramLinks.new(@database), database: @database,
+                                git: GitSource.locate(page.path_ref.path.to_s))
           storage.convert(body_of(page), toc: page.annotations["page/toc"] == "yes", header: PageProperties.xml(page))
         end
 

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

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "erb"
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "../../markdown"
 require_relative "../../helpers/macros"
 
 module Archsight
@@ -69,7 +68,7 @@ module Archsight
             kept << live(match)
             "ARCHSIGHTKEPT#{kept.length - 1}X"
           end.gsub("<", "&lt;") # raw HTML is not allowed, it could break the storage XML
-          html = Kramdown::Document.new(marked, input: "GFM", auto_ids: false, entity_output: :as_char, smart_quotes: %w[apos apos quot quot]).to_html.strip
+          html = Archsight::Markdown.unwrapped(marked, auto_ids: false, entity_output: :as_char, smart_quotes: %w[apos apos quot quot]).to_html.strip
           html.sub(%r{\A<p>(.*)</p>\z}m, '\1').gsub(/ARCHSIGHTKEPT(\d+)X/) { kept.fetch(Regexp.last_match(1).to_i) }
         end
 

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

@@ -3,8 +3,7 @@
 require "erb"
 require "uri"
 require "digest"
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "../../markdown"
 require_relative "../../assets"
 require_relative "../../diagram"
 require_relative "../../helpers/macros"
@@ -80,8 +79,9 @@ module Archsight
 
         MXFILE = "application/vnd.jgraph.mxfile"
 
-        BANNER = "This page is generated by Archsight from <code>%<source>s</code>. " \
-                 "Changes made here are overwritten by the next export: edit the source instead."
+        HOMEPAGE = "https://github.com/ionos-cloud/archsight"
+        BANNER = "This page is generated by <a href=\"#{HOMEPAGE}\">Archsight</a> from %<source>s. " \
+                 "Changes made here are overwritten by the next export: edit the source instead.".freeze
 
         LANGUAGES = {
           "sh" => "bash", "shell" => "bash", "zsh" => "bash", "yml" => "yaml", "json" => "javascript", "js" => "javascript",
@@ -95,6 +95,8 @@ module Archsight
 
         # @param page_name [String] used to name generated attachments
         # @param source [String] the markdown file, shown in the banner
+        # @param git [Archsight::GitSource::Location, nil] where the file is in its git repository: the banner then
+        #   links it to the file in the web UI of the git host and names the repository
         # @param base_dir [String] directory of the markdown file relative to the resources directory
         # @param resources_dir [String]
         # @param wiki [Archsight::Helpers::WikiLinks] resolves [[Targets]]
@@ -103,8 +105,10 @@ module Archsight
         # @param database [Archsight::Database, nil] lets macros that name pages (pagetree) find them
         # @param diagram_links [#call, nil] resolves a diagram's `resource` references (DiagramLinks); none leaves them inert
         # @param drawio [Boolean] the Confluence has the draw.io app: diagrams go in as draw.io macros, else as images
-        def initialize(page_name:, source:, base_dir:, resources_dir:, wiki:, page_id: nil, base: nil, drawio: false, diagram_links: nil, database: nil)
+        def initialize(page_name:, source:, base_dir:, resources_dir:, wiki:, page_id: nil, base: nil, drawio: false, diagram_links: nil, database: nil,
+                       git: nil)
           @database = database
+          @git = git
           @page_name = page_name
           @source = source
           @base_dir = base_dir
@@ -125,7 +129,7 @@ module Archsight
         # @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])
+          document = Archsight::Markdown.unwrapped(protect(markdown), auto_ids: false, entity_output: :as_char, smart_quotes: %w[apos apos quot quot])
           html, = Converter.convert(document.root, document.options.merge(storage: self))
           Converted.new(body: layout(header, banner, (toc ? %(<ac:structured-macro ac:name="toc" />\n) : "") + html), attachments: @attachments, problems: @problems)
         end
@@ -226,7 +230,17 @@ module Archsight
         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)
+          %(<ac:structured-macro ac:name="info"><ac:rich-text-body><p>#{format(BANNER, source: banner_source)}</p></ac:rich-text-body></ac:structured-macro>\n)
+        end
+
+        # `<code>path</code>`, in a git repository the path from its root, linked to the file on the git host, and
+        # the repository
+        def banner_source
+          return "<code>#{h(@source)}</code>" unless @git
+
+          file = "<code>#{h(@git.path)}</code>"
+          file = %(<a href="#{h(@git.url)}">#{file}</a>) if @git.url
+          %(#{file} in the repository <a href="#{h(@git.repository_url)}">#{h(@git.repository)}</a>)
         end
 
         # {macros}, [[Target|label]] and ![[View/Name]] become placeholders before kramdown sees them (it would split the
@@ -394,13 +408,12 @@ module Archsight
           %(<p><ac:image><ri:attachment ri:filename="#{h(filename)}" /></ac:image></p>\n)
         end
 
-        # The diagram file of a draw.io macro and its `.png` preview, which must share the name
+        # The diagram file of a draw.io macro and its `.png` preview, which must share the name. The name carries a hash
+        # of the content: the macro shows revision 1 of the attachment it names, so a changed diagram uploaded under the
+        # old name (as a new version of it) would not be shown. A new name is a new attachment, the old one is removed.
         # @return [String] the name the macro refers to
         def attach_diagram(stem, xml, png)
-          sha = Digest::SHA256.hexdigest(xml)
-          name = stem
-          taken = ->(file, data) { @attachments.key?(file) && @attachments[file].data != data }
-          name = "#{stem}-#{sha[0, 8]}" if taken.call(stem, xml) || taken.call("#{stem}.png", png)
+          name = "#{stem}-#{Digest::SHA256.hexdigest(xml)[0, 8]}"
           @attachments[name] = Attachment.new(filename: name, data: xml, content_type: MXFILE)
           @attachments["#{name}.png"] = Attachment.new(filename: "#{name}.png", data: png, content_type: "image/png")
           name

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

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "erb"
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "../../markdown"
 require_relative "../../view_table"
 require_relative "../../helpers/macros"
 require_relative "diagram_links"
@@ -67,7 +66,7 @@ module Archsight
           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 = Archsight::Markdown.unwrapped(safe, 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
 

data/lib/archsight/git_source.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "erb"
+require "open3"
+require "pathname"
+require "uri"
+
+module Archsight
+  # Where a file lives in its git repository and its page in the web UI of the git host, for links to the source of
+  # generated content (the banner of an exported Confluence page). Only local git is asked (the repository of the
+  # file, its `origin` remote, the checked out branch), nothing goes over the network.
+  #
+  # The web URL is `https://<host>/<owner>/<repo>` of the remote, without the user, password or token a remote URL
+  # may carry. GitHub files are `/blob/<ref>/<path>`, GitLab files `/-/blob/<ref>/<path>`; on other hosts, and for a
+  # file git does not track, only the repository is linked. The ref is the checked out branch, the commit when the
+  # HEAD is detached (CI).
+  module GitSource
+    # repository: "owner/repo"; repository_url: its web page; path: the file relative to the repository root;
+    # url: the web page of the file, nil if the host is not known
+    Location = Struct.new(:repository, :repository_url, :path, :url, keyword_init: true)
+
+    module_function
+
+    # @param file [String] path of a file
+    # @return [Location, nil] nil if the file is not in a git repository with an `origin` remote
+    def locate(file)
+      dir = File.dirname(File.expand_path(file))
+      root = git(dir, "rev-parse", "--show-toplevel") or return nil
+      remote = git(dir, "remote", "get-url", "origin") or return nil
+      host, repository = host_and_repository(remote)
+      return nil unless host && repository
+
+      path = Pathname.new(File.realpath(file)).relative_path_from(Pathname.new(File.realpath(root))).to_s
+      ref = git(dir, "symbolic-ref", "--short", "-q", "HEAD") || git(dir, "rev-parse", "HEAD")
+      repository_url = "https://#{host}/#{repository}"
+      url = tracked?(root, path) ? file_url(host, repository_url, ref, path) : nil
+      Location.new(repository: repository, repository_url: repository_url, path: path, url: url)
+    rescue SystemCallError, ArgumentError
+      nil
+    end
+
+    # `git@host:owner/repo.git`, `ssh://git@host:22/owner/repo.git`, `https://user:token@host/owner/repo` ->
+    # ["host", "owner/repo"]; the port of an ssh remote is not the port of the web UI and is left out
+    def host_and_repository(remote)
+      if (scp = remote.match(%r{\A(?:[^@/\s]+@)?([^:/\s]+):(?!//)(.+)\z}))
+        host, path = scp.captures
+      else
+        uri = URI.parse(remote)
+        return [nil, nil] unless uri.host && %w[http https ssh git].include?(uri.scheme)
+
+        host = uri.scheme.start_with?("http") && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        path = uri.path
+      end
+      repository = path.delete_prefix("/").delete_suffix("/").delete_suffix(".git")
+      repository.empty? ? [nil, nil] : [host, repository]
+    rescue URI::InvalidURIError
+      [nil, nil]
+    end
+
+    def file_url(host, repository_url, ref, path)
+      blob = if host.match?(/(\A|\.)github\./) then "blob"
+             elsif host.match?(/(\A|\.)gitlab\./) then "-/blob"
+             end
+      return nil unless blob && ref
+
+      "#{repository_url}/#{blob}/#{escape(ref)}/#{escape(path)}"
+    end
+
+    # An untracked or ignored file is not on the git host: no link that leads nowhere
+    def tracked?(root, path) = !git(root, "ls-files", "--", path).nil?
+
+    # each segment escaped, the slashes kept
+    def escape(path) = path.split("/").map { |segment| ERB::Util.url_encode(segment) }.join("/")
+
+    def git(dir, *)
+      out, _err, status = Open3.capture3("git", "-C", dir, *)
+      value = out.strip
+      status.success? && !value.empty? ? value : nil
+    end
+  end
+end

data/lib/archsight/helpers/asset_images.rb

@@ -2,8 +2,7 @@
 
 require "cgi"
 require "erb"
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "../markdown"
 require_relative "../assets"
 
 module Archsight
@@ -52,7 +51,7 @@ module Archsight
       # Problems with the image references of a markdown text.
       # @return [Array<Hash>] `{ reference:, status: :outside|:type|:missing, path: }`
       def audit(markdown, base_dir:, resources_dir:)
-        html = Kramdown::Document.new(markdown.to_s, input: "GFM").to_html
+        html = Archsight::Markdown.document(markdown).to_html
         html.scan(IMG).filter_map do |tag|
           reference = attribute(tag, SRC)
           next if reference.nil? || Assets.external?(reference)
@@ -65,7 +64,7 @@ module Archsight
       # The existing .asd files a markdown text embeds (for the linter)
       # @return [Array<Array(String, String)>] normalized asset path and real file
       def asd_files(markdown, base_dir:, resources_dir:)
-        html = Kramdown::Document.new(markdown.to_s, input: "GFM").to_html
+        html = Archsight::Markdown.document(markdown).to_html
         html.scan(IMG).filter_map do |tag|
           reference = attribute(tag, SRC)
           next if reference.nil? || Assets.external?(reference)

data/lib/archsight/import/executor.rb

@@ -442,6 +442,7 @@ class Archsight::Import::Executor
       progress: import_progress,
       shared_writer: @shared_writer
     )
+    Archsight::Import.never_index(handler.cache_root)
     handler.execute
     remove_stale_outputs(import, handler.owned_outputs)
     @mutex.synchronize { @ran_this_run.add(import.name) }

data/lib/archsight/import.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 # Define import module namespaces
 module Archsight
   module Import
@@ -13,8 +15,31 @@ module Archsight
     #   expand it before use)
     def self.cache_root(override = nil)
       require "archsight/user_config"
-      override || Archsight::UserConfig.setting("import", "cache_root")&.to_s ||
-        File.join(Dir.home, ".cache", "archsight", "git")
+      override || Archsight::UserConfig.setting("import", "cache_root")&.to_s || File.join(cache_dir, "git")
+    end
+
+    # The cache directory of Archsight, ~/.cache/archsight
+    def self.cache_dir = File.join(Dir.home, ".cache", "archsight")
+
+    # Tells Spotlight (macOS) not to index this
+    NEVER_INDEX = ".metadata_never_index"
+
+    # Makes sure the clones are not indexed by Spotlight: the marker file in ~/.cache/archsight, or in the cache root
+    # itself when it is somewhere else. Run before every import; a directory that cannot be written is left alone,
+    # the import does not depend on it.
+    # @param root [String] the cache root (Handler#cache_root)
+    # @return [String, nil] the marker file, nil if it could not be written
+    def self.never_index(root)
+      dir = File.expand_path(root)
+      dir = cache_dir if dir.start_with?("#{cache_dir}/")
+      marker = File.join(dir, NEVER_INDEX)
+      return marker if File.exist?(marker)
+
+      FileUtils.mkdir_p(dir)
+      FileUtils.touch(marker)
+      marker
+    rescue SystemCallError
+      nil
     end
 
     # The entries of `import/dependsOn`: import names and glob patterns

data/lib/archsight/linter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "kramdown"
+require_relative "markdown"
 require_relative "helpers"
 require_relative "linter/structure"
 
@@ -319,7 +319,7 @@ module Archsight
       return if instance.annotations.key?("generated/script")
 
       begin
-        Kramdown::Document.new(value, input: "GFM")
+        Archsight::Markdown.document(value)
       rescue StandardError => e
         @errors << "#{instance.path_ref}: Markdown syntax error in annotation '#{key}': #{e.message}"
       end

data/lib/archsight/markdown.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Archsight
+  # The one way markdown is parsed, for the web, the export, the linter and the analysis output alike. GFM, but a
+  # single newline inside a paragraph is a space, as in CommonMark and GitHub's rendering of `.md` files (the GFM
+  # parser of kramdown would make it a `<br />`, as GitHub does in comments). A line break is two trailing spaces,
+  # a trailing backslash or `<br>`.
+  module Markdown
+    OPTIONS = { input: "GFM", hard_wrap: false }.freeze
+
+    # Raw HTML whose text is kept as it is
+    VERBATIM = %w[pre code script style textarea].freeze
+
+    def self.document(text, **)
+      Kramdown::Document.new(text.to_s, **OPTIONS, **)
+    end
+
+    # The document without the newlines of the source in its text, for a target that keeps a newline instead of
+    # reading it as a space (Confluence): a soft line break becomes a space, the newline after a line break goes.
+    # Inline code over two lines is one line (as in CommonMark). Paragraphs, breaks and code blocks are unchanged.
+    def self.unwrapped(text, **)
+      document(text, **).tap { |doc| unwrap(doc.root) }
+    end
+
+    def self.unwrap(element)
+      element.children.each_with_index do |child, index|
+        if child.type == :text
+          previous = index.positive? ? element.children[index - 1] : nil
+          joined = child.value.gsub(/[ \t]*\r?\n[ \t]*/, " ")
+          child.value = line_break?(previous) ? joined.lstrip : joined
+        elsif child.type == :codespan
+          child.value = child.value.gsub(/\r?\n/, " ")
+        elsif !(child.type == :html_element && VERBATIM.include?(child.value))
+          unwrap(child)
+        end
+      end
+    end
+    private_class_method :unwrap
+
+    def self.line_break?(element)
+      element && (element.type == :br || (element.type == :html_element && element.value == "br"))
+    end
+    private_class_method :line_break?
+  end
+end