archsight 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00045b0530964a0ff8be08ceef27b47fe7e91b630ba09a243b087f4bce523add
-  data.tar.gz: 0abb8b4cf7d274318451a094f40a48992e6759ac2d56f6a5f70fd8d18e59cd06
+  metadata.gz: c249926b6ff6855b19ace38f11b9f256340e4d77cd00fe4d5f981fcbb0fd12f1
+  data.tar.gz: a0d7267da0223f8faed9a478a2c5ca029cdc23205fdff4feb945adb4d2b78f2e
 SHA512:
-  metadata.gz: 756394456261aca49ea0c828d9bf61996a8175da001c335ac802e06f9232641a587732765140395dc55e224a6f6d5d4facda26cdb26ddde27bb8272a6b3d09ee
-  data.tar.gz: 2f9584331b16063497e712f4b48b20abec72e946932af5986418d8e137ffa4eb55f393e05802974a7eec47edff0d6cf84b6de6d2614b2b553f8bcad51ebeed27
+  metadata.gz: 18ae964be21eded1e7be2560cd70a0ea63cb714c76b2d5295b3ec4b1f2b1fc46f5ec418591f53c5856babe389696b96be1436e905ee5ee2bc4b922ecee43d816
+  data.tar.gz: c8c8fbcba5d1f9db3b9d22c9fb2b1182569354fd08e2fd2cf44ba0bfe4b787ffac0446d48db5bd802f01269ea9ff6746383b2887bdf0a0f4b8d9e97e2ee2f9f6

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

@@ -36,7 +36,7 @@ There are two families of verbs:
 
 | Family | Verbs | Written on | Points to |
 |--------|-------|------------|-----------|
-| Responsibility and provider (down) | `performedBy`, `ownedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `representedBy`, `realizedThrough`, `exposes`, `connects`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
+| Responsibility and provider (down) | `performedBy`, `ownedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `representedBy`, `realizedThrough`, `exposes`, `provisions`, `connects`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
 | Realization (up) | `realizes`, `partiallyRealizes`, `plans`, `satisfies`, `evidencedBy` (on the evidenced element), `provides` | the concrete element | the abstract element it answers to (requirement, goal, capability, plateau) |
 
 Rules:
@@ -154,7 +154,7 @@ TechnologySystemSoftware, TechnologyService, TechnologyArtifact). The same princ
 | Location | In which region or country is it? | A place on a map, not a building; holds facilities | the place ("Location:Germany:Frankfurt") |
 | TechnologyFacility | In which building or site does hardware stand? | Has an address and can be visited; can be nested (campus, hall) | the site ("Facility:Frankfurt:HallA") |
 | TechnologyEquipment | Which physical thing can you touch? | Racks, fabrics, fibre routes, carrier circuits; no software of its own | the thing and its place ("Equipment:Link:Frankfurt-Madrid") |
-| TechnologyDevice | Which single machine stands in the room? | One server, switch, router, firewall or appliance with a serial number; it is cabled | the host ("Device:Frankfurt:Server01") |
+| TechnologyDevice | Which single machine stands in the room? | One server, switch, router, firewall or appliance with a serial number (it is cabled), or one laptop, workstation or phone of a person or team | the host ("Device:Frankfurt:Server01") |
 | TechnologyCommunicationNetwork | What carries data between nodes? | Has a network role (`network/type`); exists beyond any single link | role and scope ("Network:Management:Frankfurt") |
 | TechnologyNode | On which machine does software run? | A VM, host role or logical group of machines with a lifecycle of its own | the host or host role ("Node:Frankfurt:Web01") |
 | TechnologySystemSoftware | What software hosts other software or data? | An operating system, database cluster, routing stack, platform | the product and role ("Tech:Routing:EVPN") |
@@ -166,8 +166,8 @@ TechnologySystemSoftware, TechnologyService, TechnologyArtifact). The same princ
 1. Is it a country, metro or region? Location.
 2. Is it a building, campus, hall or site that can be visited? TechnologyFacility.
 3. Is it a physical thing (rack, switch fabric, fibre, circuit) without software of its own? TechnologyEquipment.
-4. Is it one physical machine (server, switch, router, firewall, appliance) whose room or cabling matters?
-   TechnologyDevice.
+4. Is it one physical machine (server, switch, router, firewall, appliance, laptop, workstation, phone) whose room,
+   cabling or operating system matters? TechnologyDevice.
 5. Does it carry data between nodes, with a role such as underlay, overlay, management, public or VPN?
    TechnologyCommunicationNetwork.
 6. Is it a machine (virtual, or a host role) that software runs on? TechnologyNode.
@@ -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
@@ -198,7 +201,8 @@ TechnologySystemSoftware, TechnologyService, TechnologyArtifact). The same princ
 10. One `TechnologyDevice` per physical machine, `locatedAt` its room (a TechnologyFacility of `facility/type: room`
     the data center is `composedOf`). A group of machines with one role stays a logical `TechnologyNode` that is
     `realizedBy` its devices; a rack or hardware block is TechnologyEquipment `composedOf` them; a virtual chassis or
-    stack is a device `composedOf` its members.
+    stack is a device `composedOf` its members. A client device (`device/type` laptop, desktop, workstation,
+    thin-client, tablet, mobile) moves and needs no room; it may be `locatedAt` an office.
 11. A network is `realizedBy` the devices that build it (switches, routers) and `connects` the devices attached to it.
     Both are written on the network, so a switch attached to the network it builds closes no cycle.
 12. Cables are `connectedTo` between devices, declared once on one of the two ends. Cabling runs both ways by nature
@@ -210,6 +214,17 @@ TechnologySystemSoftware, TechnologyService, TechnologyArtifact). The same princ
     `servedBy` its team and `composedOf` its devices, which then need no team of their own. Both relations point
     down to the team, which points to nothing further. On a TechnologyFacility, `servedBy` stays the operator of
     the site.
+14. A client device (developer workstation, laptop, phone) is a `TechnologyDevice` with a client `device/type` and
+    `device/os`, `device/osVersion`, `device/arch`, `device/ownership`, `device/managed` and `device/encryption`; the
+    vendor and product are in `device/model` (also for a hardened workstation that runs the user's operating system
+    virtualized beside other isolated sessions, which is a `workstation`). Model the individual machine when it is
+    inventoried, otherwise one `TechnologyNode` per client platform `realizedBy` the devices. The operating system is
+    `TechnologySystemSoftware` `realizedBy` the node, the image it is installed from an artifact the node is
+    `assignedTo`; each isolated session of a hardened workstation can be a node of its own. Network access is written
+    on the node (`servedBy` the networks it uses: the office, the VPN) or, for a single named machine, on the network
+    (`connects`), never on the device, because a network is `realizedBy` its switches and the reverse arrow would
+    close a cycle. A machine that reaches no network (air-gapped) has neither relation. Who uses it is the team or role
+    (`servedBy`), not a person; groups of machines are tags and the end of support is `lifecycle/endOfLifeAt`.
 
 **Checked by `archsight lint`**
 
@@ -221,7 +236,7 @@ As above, these are **warnings** in the "Modeling warnings" section and never fa
 | `TechnologyCommunicationNetwork 'Network:Overlay:EVPN' is an overlay network served by no network` | 3 |
 | `TechnologyFacility 'Facility:Madrid:DC' is located at no Location` | where |
 | `TechnologyEquipment 'Equipment:Rack01' is located at no TechnologyFacility` | where |
-| `TechnologyDevice 'Device:Server01' is located at no TechnologyFacility` | 10 |
+| `TechnologyDevice 'Device:Server01' is located at no TechnologyFacility` (not for client device types) | 10 |
 | `TechnologyDevice 'Device:Switch01' is connectedTo itself` | 12 |
 | `TechnologyDevice 'Device:Router01' is a router that realizes no TechnologyCommunicationNetwork` | 11 |
 | `TechnologyDevice 'Device:a:server-3' is servedBy 'Kernel:Team', not by the team of its equipment ('Compute:Team')` | 13 |
@@ -544,8 +559,9 @@ Which kind to pick is in [Choosing the Kind: Infrastructure](#choosing-the-kind-
 | `TechnologyCommunicationNetwork` | `realizedBy` | `TechnologyEquipment` (the fabric), `TechnologySystemSoftware` (routing stack, VPN software) |
 | `TechnologyCommunicationNetwork` | `realizedBy` | `ApplicationComponent`, `ApplicationService` (software that builds the network: an SDN agent, a network operator) |
 | `TechnologyCommunicationNetwork` | `realizedBy` | `TechnologyDevice` (the switches and routers that build it) |
-| `TechnologyCommunicationNetwork` | `connects` | `TechnologyDevice` (the devices attached to it) |
+| `TechnologyCommunicationNetwork` | `connects` | `TechnologyDevice` (the devices attached to it, a named workstation behind a VPN) |
 | `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 +576,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
@@ -585,7 +605,7 @@ center is not a computational resource.
 | Location | For a country, metro or region |
 | TechnologyFacility | For a data center, colocation, office or edge site (`facility/type`), also a campus or hall inside one |
 | TechnologyEquipment | Optional: racks, network fabrics, physical clusters inside a facility (`equipment/type`) |
-| TechnologyDevice | Optional: one physical machine, `locatedAt` its room (`facility/type: room`) |
+| TechnologyDevice | Optional: one physical machine, `locatedAt` its room (`facility/type: room`); a client device (laptop, workstation, phone) needs no room |
 
 Relations are written on the element that is placed (see [Direction of Relations](#direction-of-relations)):
 
@@ -680,13 +700,19 @@ depend on each other, so `dependsOn` is exempt from the cycle check. In `example
 
 ### Where a Component Runs
 
-Three relations say what something runs on; each answers a different question:
+These relations say what something runs on or builds; each answers a different question:
 
 | Relation | Means | Example |
 |----------|-------|---------|
 | ApplicationComponent `servedBy technologyServices` | the platform service the component is deployed on | `Payments:API` runs in `Payments:Cluster` |
 | ApplicationComponent `servedBy technologySystemSoftware` | the runtime it runs on | a Kubernetes distribution, a JVM |
 | ApplicationService `servedBy technologyServices` | a platform service the service as a whole uses | a managed database, the clusters of its own components |
+| ApplicationComponent `provisions technologyServices` | the platform service the component creates and keeps in its desired state | an operator that builds the clusters of a product |
+
+`provisions` is written on the component, like every relation, so it points down to what the component creates: the
+service page lists its provisioner as incoming, and the impact of a provisioner is its outgoing relations (the
+services it builds). It is not a runtime dependency: a provisioned service keeps running while its provisioner is
+down, only changes stop. `suppliedBy` on the service stays for what it is made of (the system software).
 
 Deployment importers (Argo CD, Helm, Cluster API) know every cluster a deployable runs in and write the relation per
 component. Keep the service-level relation to the clusters of the service's own components: a sidecar or agent that
@@ -989,7 +1015,7 @@ is a sidebar filter and query term (`lifecycle/status == "deprecated"`).
 |------------|---------|
 | `lifecycle/status` | The state above |
 | `lifecycle/activeAt`, `lifecycle/deprecatedAt`, `lifecycle/sunsetAt`, `lifecycle/endOfLifeAt` | When it happened or will happen (ISO 8601 date or time, checked by `archsight lint`) |
-| `lifecycle/replacedBy` | The resource that replaces it: a name for a resource of the same kind, `Kind/Name` for another kind (a component replaced by an `ApplicationService/...`). Shown as a link, `archsight lint` checks that it exists |
+| `lifecycle/replacedBy` | The resource that replaces it: a name for a resource of the same kind, `Kind/Name` for another kind (a component replaced by an `ApplicationService/...`). Shown as a link behind the status, `archsight lint` checks that it exists |
 | `lifecycle/reason` | Why, in markdown |
 
 ```yaml
@@ -1002,6 +1028,9 @@ metadata:
     lifecycle/replacedBy: ApplicationService/ExportV2
 ```
 
+The detail page shows the status, the replacement as a link and, for a `deprecated`, `sunset` or `end-of-life`
+resource, the number of resources that still refer to it (a link to its Incoming relations) on one line.
+
 ## Common Patterns
 
 ### Microservice

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/structure.rb

@@ -9,6 +9,8 @@ module Archsight
       # Network types that run over another network and need one that serves them
       OVERLAY_TYPES = %w[overlay vpn].freeze
       NETWORK_DEVICE_TYPES = %w[switch router].freeze
+      # Client machines move: they need no room
+      CLIENT_DEVICE_TYPES = %w[laptop desktop workstation thin-client tablet mobile].freeze
 
       def initialize(database)
         @database = database
@@ -185,12 +187,13 @@ module Archsight
       end
 
       # A device that is part of equipment (a rack) or of another device (a virtual chassis) is placed through its
-      # whole, and a chassis through its members
+      # whole, and a chassis through its members. A client device (laptop, workstation, phone) is not placed.
       def device_without_facility
         parts = owners_by_target("TechnologyDevice", :composedOf, :technologyDevices)
         racked = owners_by_target("TechnologyEquipment", :composedOf, :technologyDevices)
         instances("TechnologyDevice").filter_map do |device|
           next if parts.key?(device) || racked.key?(device) || targets(device, :composedOf, :technologyDevices).any?
+          next if CLIENT_DEVICE_TYPES.include?(device.annotations["device/type"])
           next if targets(device, :locatedAt, :technologyFacilities).any?
 
           warning(device, "is located at no TechnologyFacility")

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