archsight 0.4.1 → 0.4.3

data/lib/archsight/diagram.rb

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

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

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

data/lib/archsight/helpers/diagram_blocks.rb

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

data/lib/archsight/helpers/diagram_includes.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../assets"
+
+module Archsight
+  module Helpers
+    # Loads the diagrams that `include "<path>"` names (see Archsight::Diagram::Includes):
+    #
+    #   archsight://Kind/name    the `architecture/diagram` of that resource
+    #   file://path/to/x.asd     an .asd file, relative to the resources directory (never outside it)
+    #
+    # #call returns the diagram source, or `:missing` / `:forbidden` / `:invalid`. Without a database only
+    # `file://` paths work (the standalone `archsight diagram`).
+    class DiagramIncludes
+      ARCHSIGHT = "archsight://"
+      FILE = "file://"
+      ANNOTATION = "architecture/diagram"
+      MAX_BYTES = 1_000_000
+
+      # The loader for a database, whose path is the resources directory
+      def self.for(database)
+        new(database, resources_dir: (database.path if database.respond_to?(:path)))
+      end
+
+      def initialize(database, resources_dir:)
+        @database = database
+        @resources_dir = resources_dir
+      end
+
+      def call(path)
+        if path.start_with?(ARCHSIGHT)
+          resource(path.delete_prefix(ARCHSIGHT))
+        elsif path.start_with?(FILE)
+          file(path.delete_prefix(FILE))
+        else
+          :invalid
+        end
+      end
+
+      private
+
+      # `Kind/name`; names contain `:` but a kind never contains `/`, so the first `/` separates them
+      def resource(reference)
+        return :forbidden unless @database
+
+        kind, name = reference.split("/", 2)
+        return :invalid if kind.to_s.empty? || name.to_s.empty? || !Archsight::Resources[kind]
+
+        source = @database.instance_by_kind(kind, name)&.annotations&.fetch(ANNOTATION, nil)
+        source.is_a?(String) && !source.strip.empty? ? source : :missing
+      end
+
+      def file(path)
+        return :invalid if @resources_dir.nil? || !Archsight::Assets.asd?(path)
+        return :forbidden if path.start_with?("/") # file:///etc/x.asd; relative to the resources directory only
+
+        real = Archsight::Assets.file_for(path, resources_dir: @resources_dir)
+        return :missing unless real
+        return :forbidden if File.size(real) > MAX_BYTES
+
+        File.read(real, encoding: "UTF-8")
+      rescue SystemCallError
+        :missing
+      end
+    end
+  end
+end

data/lib/archsight/helpers.rb

@@ -7,6 +7,7 @@ require_relative "helpers/fenced_blocks"
 require_relative "helpers/view_blocks"
 require_relative "helpers/requirements_blocks"
 require_relative "helpers/resource_resolver"
+require_relative "helpers/diagram_includes"
 require_relative "helpers/embeds"
 require_relative "helpers/wiki_links"
 require_relative "helpers/asset_images"

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

@@ -24,6 +24,7 @@ module Archsight
     def initialize(database)
       @database = database
       @errors = []
+      @diagram_warnings = []
     end
 
     def validate
@@ -47,7 +48,7 @@ module Archsight
     # annotations their kind marks `deprecated:`. They are not errors, so they do not make `archsight lint` fail.
     def warnings
       renamed = @database.respond_to?(:deprecations) ? @database.deprecations.map(&:to_s) : []
-      renamed + deprecated_annotations
+      renamed + deprecated_annotations + @diagram_warnings
     end
 
     # Structural modeling checks (rules of "Choosing the Kind", see Linter::Structure). Warnings, never errors.
@@ -402,7 +403,10 @@ module Archsight
     # Renders with the same resolver the web UI uses, so a `resource` reference that would show as a broken link there is reported here
     def render_diagram_source(instance, where, source)
       unresolved = []
-      Archsight::Diagram.render(source, resolver: Helpers::ResourceResolver.new(@database), unresolved: unresolved)
+      warnings = []
+      Archsight::Diagram.render(source, resolver: Helpers::ResourceResolver.new(@database), unresolved: unresolved,
+                                        includes: diagram_includes, warnings: warnings)
+      warnings.each { |message| @diagram_warnings << "#{instance.path_ref}: Diagram in #{where}: #{message}" }
       unresolved.each do |u|
         @errors << "#{instance.path_ref}: Diagram resource link #{u[:reference].inspect} #{u[:reason]} in #{where} (node #{u[:node].inspect}, line #{u[:line]})"
       end
@@ -410,6 +414,10 @@ module Archsight
       @errors << "#{instance.path_ref}: Diagram error in #{where}: #{e.message}"
     end
 
+    def diagram_includes
+      @diagram_includes ||= Helpers::DiagramIncludes.for(@database)
+    end
+
     def validate_view_fields(instance)
       check_view_components(instance, instance.annotations["view/fields"].to_s.split(",").map(&:strip))
     end

data/lib/archsight/references.rb

@@ -26,9 +26,10 @@ module Archsight
     # Adds the derived relations to every resource of the database.
     def derive!(database)
       finder = Finder.new(database)
+      includes = Helpers::DiagramIncludes.for(database)
       database.instances.values.flat_map(&:values).each do |inst|
         text_sources(inst).each { |markdown| mentions(markdown, finder).each { |target| link(inst, :mentions, target) } }
-        diagram_sources(inst, database).each { |source| depictions(source, finder).each { |target| link(inst, :depicts, target) } }
+        diagram_sources(inst, database).each { |source| depictions(source, finder, includes).each { |target| link(inst, :depicts, target) } }
       end
     end
 
@@ -44,8 +45,8 @@ module Archsight
     # The resources the nodes of a diagram source name with `resource "..."`; a source that is not a valid diagram
     # names none.
     # @return [Array<Base>]
-    def depictions(source, finder)
-      Diagram.resource_references(source).filter_map { |reference| finder.reference(reference) }
+    def depictions(source, finder, includes = nil)
+      Diagram.resource_references(source, includes: includes).filter_map { |reference| finder.reference(reference) }
     rescue Diagram::Error
       []
     end

data/lib/archsight/resources/application_component.rb

@@ -55,6 +55,13 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     works in queries like a tag but is not a sidebar filter, as there are too many distinct values. Deployable forms (container image, chart, package) are `TechnologyArtifact`s, not
     component types.
 
+    ## Teams
+
+    A component is `maintainedBy` the team (`BusinessActor`) that builds and changes it and `operatedBy` the team
+    (`BusinessActor` or `BusinessRole`) that runs it in production. Build and run are often different teams, which is
+    the point of writing both. Both are optional; without a direct `maintainedBy`, the build team is the one that
+    maintains the component's `TechnologyArtifact`s.
+
     ## Where it runs
 
     A component is `servedBy` the `TechnologyService` it is deployed on (a product's cluster, a managed platform) and
@@ -62,6 +69,13 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     importers write the service per component, so a sidecar or agent deployed into many clusters shows where it runs
     without making its own service look like it runs in all of them.
 
+    A component that creates technology services is `provisions` them: a controller, operator, pipeline or job that
+    builds and reconciles the clusters, database clusters or VM pools of a product (Crossplane, Cluster API, a
+    Terraform controller). It is written on the component, which points down to what it creates, like `servedBy`; the
+    service page lists the component as incoming "provisions". `servedBy` says where the component itself runs,
+    `provisions` what it builds, and a service that is built elsewhere keeps running while its provisioner is down,
+    only changes stop. The impact of a provisioner is what it reaches: its outgoing relations.
+
     The computed `component/dependents` counts the components that depend on this one, which tells shared libraries
     and modules from components nobody consumes.
 
@@ -418,6 +432,10 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :realizedBy, :technologyComponents, :TechnologyNode
   relation :servedBy, :technologyComponents, :TechnologySystemSoftware
   relation :servedBy, :technologyServices, :TechnologyService
+  relation :provisions, :technologyServices, :TechnologyService
+  relation :maintainedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessRoles, :BusinessRole
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent

data/lib/archsight/resources/application_service.rb

@@ -35,6 +35,12 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
     the other service's components listed again; a service that many others use is modeled once. A service whose only component has the same name is a smell. See
     the modeling guide, "Choosing the Kind".
 
+    ## Teams
+
+    A service is `maintainedBy` the team (`BusinessActor`) that builds and changes it and `operatedBy` the team
+    (`BusinessActor` or `BusinessRole`) that runs it in production. Build and run are often different teams, which is
+    the point of writing both. `servedBy` stays "who uses it". Both are optional.
+
     ## Security and risk modelling
 
     A service is an asset at risk (`asset/*` profile, protection needs) that loss events `affects`, a trigger target
@@ -230,6 +236,9 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   relation :dependsOn, :applicationServices, :ApplicationService
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
+  relation :maintainedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessRoles, :BusinessRole
   relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement

data/lib/archsight/resources/technology_device.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-# TechnologyDevice represents one physical machine: a server, switch, router, firewall or appliance
+# TechnologyDevice represents one physical machine: a server, switch, router, firewall, appliance or client machine
 class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
   include_annotations :git, :architecture, :asset, :risk
 
   description <<~MD
-    Represents one physical machine: a server, a switch, a router, a firewall, a terminal server or an appliance.
+    Represents one physical machine: a server, a switch, a router, a firewall, a terminal server, an appliance, or a
+    client machine (a laptop, a workstation, a phone).
 
     ## ArchiMate Definition
 
@@ -18,13 +19,34 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
     ## Usage
 
     Use TechnologyDevice when the individual machine matters: which room it stands in, which switch it is cabled to,
-    which machines a failure domain loses.
+    which machines a failure domain loses, which operating system and owner a workstation has.
 
     - One element per physical machine (name it after the host: "Device:Frankfurt:Server01")
     - A group of machines with one role ("the hypervisors of the platform") stays a logical `TechnologyNode` that is
       `realizedBy` its devices
     - A virtual chassis, a stack or a cluster pair is a device `composedOf` its member devices
 
+    ## Client devices
+
+    A developer workstation, a laptop, a thin client, a tablet or a phone is a device of the matching `device/type`;
+    `device/os`, `device/osVersion` and `device/arch` say what it runs on, `device/ownership` whether the company
+    owns it, `device/managed` whether it is centrally managed (MDM) and `device/encryption` whether the disk is
+    encrypted. The vendor and product go into `device/model`, also for a hardened workstation that runs the user's
+    operating system virtualized next to other isolated sessions: it is a `workstation`. The end of support is
+    `lifecycle/endOfLifeAt`, a group of machines is a tag (`architecture/tags`).
+
+    - Model the individual machine when it is inventoried (an MDM import can write them), otherwise one
+      `TechnologyNode` per client platform ("Node:Workstation:macOS") `realizedBy` the devices
+    - The operating system is `TechnologySystemSoftware` `realizedBy` that node; the image or packages it is
+      installed from are `TechnologyArtifact`s the node is `assignedTo`. Each isolated session of a hardened
+      workstation can be a node of its own, `realizedBy` the device
+    - Network access: the platform node is `servedBy` the networks it uses (the office, the VPN), a single named
+      machine is `connects`-ed by its network (the VPN it tunnels through, an isolated segment). A machine that
+      reaches no network (air-gapped) has neither relation. The device itself does not point to networks: a network
+      is `realizedBy` its switches, so the reverse arrow would close a cycle
+    - Who uses it is the team or role (`servedBy`), not a person; a client device needs no room, `locatedAt` an
+      office is optional
+
     ## Not this kind
 
     - A VM, a Kubernetes node or a host role is a `TechnologyNode`
@@ -57,7 +79,7 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
   annotation "device/type",
              description: "Kind of device",
              title: "Device Type",
-             enum: %w[server switch router firewall terminal-server appliance other],
+             enum: %w[server switch router firewall terminal-server appliance laptop desktop workstation thin-client tablet mobile other],
              filter: :word,
              summary: true
   annotation "device/role",
@@ -79,6 +101,36 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
              title: "Purpose",
              filter: :word
 
+  annotation "device/os",
+             description: "Operating system family of a client device",
+             title: "Operating System",
+             enum: %w[windows macos linux freebsd openbsd netbsd android ios chromeos other],
+             filter: :word,
+             summary: true
+  annotation "device/osVersion",
+             description: "Operating system version, e.g. 15.1 or 24.04 LTS",
+             title: "OS Version"
+  annotation "device/arch",
+             description: "CPU architecture",
+             title: "Architecture",
+             enum: %w[x86_64 arm64 riscv64 other],
+             filter: :word
+  annotation "device/ownership",
+             description: "Who owns the device",
+             title: "Ownership",
+             enum: %w[company-owned leased byod],
+             filter: :word
+  annotation "device/managed",
+             description: "Whether the device is managed centrally (MDM, configuration management)",
+             title: "Managed",
+             enum: %w[managed unmanaged],
+             filter: :word
+  annotation "device/encryption",
+             description: "Whether the disk is encrypted",
+             title: "Disk Encryption",
+             enum: %w[enabled disabled],
+             filter: :word
+
   relation :locatedAt, :technologyFacilities, :TechnologyFacility
   relation :connectedTo, :technologyDevices, :TechnologyDevice
   relation :composedOf, :technologyDevices, :TechnologyDevice

data/lib/archsight/resources/technology_service.rb

@@ -50,6 +50,19 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
     "servedBy" from ApplicationComponent on its page. An ApplicationService that is `servedBy` the service uses it as a
     whole; list a cluster there only when the service's own components run in it.
 
+    ## Teams
+
+    A service is `maintainedBy` the team (`BusinessActor`) that builds and changes it and `operatedBy` the team
+    (`BusinessActor` or `BusinessRole`) that runs it in production. Build and run are often different teams, which is
+    the point of writing both. `servedBy` stays "who uses it". Both are optional.
+
+    ## Provisioning
+
+    A service that software creates (clusters built by an infrastructure-as-code operator, a database cluster
+    reconciled by a controller) is `provisions`-ed by that `ApplicationComponent`. The relation is written on the
+    component and points down to the service; the service page lists it as incoming "provisions". It says who builds
+    the service, `suppliedBy` says what the service is made of (the system software).
+
     ## Concept and implementation
 
     A service can `specialize` another service (ArchiMate specialization): the general service is the concept, the
@@ -68,6 +81,9 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
   relation :suppliedBy, :technologyComponents, :TechnologySystemSoftware
   relation :specializes, :technologyServices, :TechnologyService
   relation :servedBy, :businessActors, :BusinessActor
+  relation :maintainedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessRoles, :BusinessRole
   relation :locatedAt, :technologyFacilities, :TechnologyFacility
   relation :realizedBy, :technologyEquipment, :TechnologyEquipment
   relation :realizes, :motivationRequirements, :MotivationRequirement

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.4.1"
+  VERSION = "0.4.3"
 end

data/lib/archsight/web/api/json_helpers.rb

@@ -106,7 +106,8 @@ module Archsight::Web::API::JsonHelpers
     source = annotations[DIAGRAM_ANNOTATION_KEY]
     return unless source.is_a?(String) && !source.strip.empty?
 
-    Archsight::Helpers::DiagramBlocks.render_diagram(source, resolver: Archsight::Helpers::ResourceResolver.new(db))
+    Archsight::Helpers::DiagramBlocks.render_diagram(source, resolver: Archsight::Helpers::ResourceResolver.new(db),
+                                                             includes: Archsight::Helpers::DiagramIncludes.for(db))
   end
 
   # The values of markdown annotations are rendered to HTML: architecture/description and every annotation the
@@ -190,7 +191,7 @@ module Archsight::Web::API::JsonHelpers
         title: annotation.title,
         description: annotation.description,
         filter_type: annotation.filter.to_s,
-        values: values
+        values: values.map { |value, count| { value: value, count: count } }
       }
     end
   end

data/lib/archsight/web/api/openapi/spec.yaml

@@ -1581,9 +1581,16 @@ components:
           description: Filter type (e.g., "select", "boolean")
         values:
           type: array
+          description: Available values with the number of instances using them, most used first
           items:
-            type: string
-          description: Available values for the filter
+            type: object
+            required: [value, count]
+            properties:
+              value:
+                type: string
+              count:
+                type: integer
+                description: Number of instances with this value
 
     AnalysisResult:
       type: object

data/lib/archsight/web/api/page_helpers.rb

@@ -24,7 +24,7 @@ module Archsight::Web::API::PageHelpers
       next if counts.empty?
 
       { key: annotation.key, title: annotation.title, filter_type: annotation.filter.to_s,
-        values: counts.sort.map { |value, count| { value: value, count: count } } }
+        values: counts.sort_by { |value, count| [-count, value.to_s] }.map { |value, count| { value: value, count: count } } }
     end
   end
 

data/lib/archsight/web/api/routes.rb

@@ -179,9 +179,10 @@ module Archsight::Web::API::Routes
       resolver = Archsight::Helpers::ResourceResolver.new(db)
       headers "Content-Security-Policy" => "default-src 'none'; style-src 'unsafe-inline'; sandbox"
       cache_control :public, :must_revalidate, max_age: 0
-      etag Archsight::Helpers::DiagramBlocks.fingerprint(source, resolver: resolver)
+      includes = Archsight::Helpers::DiagramIncludes.for(db)
+      etag Archsight::Helpers::DiagramBlocks.fingerprint(source, resolver: resolver, includes: includes)
       content_type "image/svg+xml"
-      Archsight::Helpers::DiagramBlocks.standalone_svg(source, resolver: resolver)
+      Archsight::Helpers::DiagramBlocks.standalone_svg(source, resolver: resolver, includes: includes)
     rescue Archsight::Diagram::Error => e
       json_error("Diagram does not render: #{e.message}", status: 422, error_type: "DiagramError")
     end
@@ -201,7 +202,7 @@ module Archsight::Web::API::Routes
     json_error("A JSON body with a 'source' string is required", status: 400, error_type: "BadRequest") unless source.is_a?(String)
 
     resolver = Archsight::Helpers::ResourceResolver.new(db)
-    json_response(Archsight::Helpers::DiagramBlocks.preview(source, resolver: resolver))
+    json_response(Archsight::Helpers::DiagramBlocks.preview(source, resolver: resolver, includes: Archsight::Helpers::DiagramIncludes.for(db)))
   end
 
   # POST /api/v1/kinds/Analysis/instances/:name/execute - Execute an analysis

data/lib/archsight/web/application.rb

@@ -161,7 +161,8 @@ class Archsight::Web::Application < Sinatra::Base
       html = Archsight::Markdown.document(data).to_html
       html = Archsight::Helpers::AssetImages.rewrite(html, base_dir: base, resources_dir: Archsight.resources_dir) if base
       # ```asd blocks become placeholders until the text passes below are done (see DiagramBlocks)
-      html, diagrams = Archsight::Helpers::DiagramBlocks.extract(html, resolver: Archsight::Helpers::ResourceResolver.new(db))
+      html, diagrams = Archsight::Helpers::DiagramBlocks.extract(html, resolver: Archsight::Helpers::ResourceResolver.new(db),
+                                                                       includes: Archsight::Helpers::DiagramIncludes.for(db))
       # so are ```view and ```requirements blocks (see ViewBlocks, RequirementsBlocks)
       html, views = Archsight::Helpers::ViewBlocks.extract(html)
       html, requirements = Archsight::Helpers::RequirementsBlocks.extract(html)

data/lib/archsight/web/public/vue/{DocPage-C2ubTXH7.js → DocPage-L0GzDFiV.js}

@@ -1 +1 @@
-import{F as e,L as t,P as n,Q as r,d as i,q as a,t as o,tt as s}from"./index-CLuLTE5I.js";import{t as c}from"./WikiPage-B2FYmeHL.js";var l={key:1},u={__name:`DocPage`,props:{filename:String},setup(u){let d=u,f=s(null);function p(e,t){let n=new DOMParser().parseFromString(e,`text/html`).body,r=n.querySelector(`:scope > article`)||n,i=r.querySelector(`h1`),a=i?.textContent.trim()||t.split(`/`).pop().replace(/[-_]/g,` `);i?.remove();let o=[...r.querySelectorAll(`h2[id], h3[id], h4[id]`)].map(e=>({level:Number(e.tagName[1]),id:e.id,text:e.textContent.trim()})),s=[{title:`Documentation`}];return t.startsWith(`resources/`)&&s.push({title:`Resource types`}),{title:a,html:r.innerHTML,toc:o.length>=2?o:[],breadcrumb:s}}async function m(){let e=await i(d.filename);f.value=e?p(e,d.filename):{title:`Not found`,html:`<p>Documentation not found.</p>`,toc:[],breadcrumb:[{title:`Documentation`}]},o(f.value.title)}return r(()=>d.filename,m,{immediate:!0}),(r,i)=>f.value?(a(),e(c,{key:0,title:f.value.title,html:f.value.html,breadcrumb:f.value.breadcrumb,toc:f.value.toc},null,8,[`title`,`html`,`breadcrumb`,`toc`])):(a(),t(`article`,l,[...i[0]||=[n(`p`,null,`Loading...`,-1)]]))}};export{u as default};
+import{F as e,L as t,P as n,Q as r,d as i,q as a,t as o,tt as s}from"./index-DMhBow5t.js";import{t as c}from"./WikiPage-Bfx92Iig.js";var l={key:1},u={__name:`DocPage`,props:{filename:String},setup(u){let d=u,f=s(null);function p(e,t){let n=new DOMParser().parseFromString(e,`text/html`).body,r=n.querySelector(`:scope > article`)||n,i=r.querySelector(`h1`),a=i?.textContent.trim()||t.split(`/`).pop().replace(/[-_]/g,` `);i?.remove();let o=[...r.querySelectorAll(`h2[id], h3[id], h4[id]`)].map(e=>({level:Number(e.tagName[1]),id:e.id,text:e.textContent.trim()})),s=[{title:`Documentation`}];return t.startsWith(`resources/`)&&s.push({title:`Resource types`}),{title:a,html:r.innerHTML,toc:o.length>=2?o:[],breadcrumb:s}}async function m(){let e=await i(d.filename);f.value=e?p(e,d.filename):{title:`Not found`,html:`<p>Documentation not found.</p>`,toc:[],breadcrumb:[{title:`Documentation`}]},o(f.value.title)}return r(()=>d.filename,m,{immediate:!0}),(r,i)=>f.value?(a(),e(c,{key:0,title:f.value.title,html:f.value.html,breadcrumb:f.value.breadcrumb,toc:f.value.toc},null,8,[`title`,`html`,`breadcrumb`,`toc`])):(a(),t(`article`,l,[...i[0]||=[n(`p`,null,`Loading...`,-1)]]))}};export{u as default};