archsight 0.3.3 → 0.4.1

data/lib/archsight/renderer.rb

@@ -40,9 +40,11 @@ module Archsight
     def gnode(graph, inst, opts = {})
       label = "<TABLE><TR><TD><B>#{inst.name}</B></TD></TR><TR><TD>#{inst.klass}</TD></TR></TABLE>"
       label = inst.name if opts[:simple_label]
-      graph.node gname(inst), class: css_class(inst), shape: :box,
-                              style: "rounded,filled", fontname: FONT, label: label,
-                              href: "/kinds/#{inst.klass}/instances/#{inst.name}"
+      attrs = { class: css_class(inst), shape: :box, style: "rounded,filled", fontname: FONT, label: label,
+                href: "/kinds/#{inst.klass}/instances/#{inst.name}" }
+      # A resource at the depth limit with more dependencies: dashed, its own page shows them
+      attrs.merge!(style: "rounded,filled,dashed", tooltip: "More dependencies: open it to explore them") if opts[:truncated]
+      graph.node gname(inst), attrs
     end
 
     def gedge(graph, a_inst, b_inst, label)
@@ -104,29 +106,84 @@ module Archsight
       end
     end
 
-    def create_graph_one(db, klass_pat, name_pat)
-      name = "#{klass_pat}:#{name_pat}"
-      nodes = {}
-      edges = {}
-      Archsight::Graphvis.new(name).draw_dot do |g|
-        klass = Archsight::Resources[klass_pat] || raise("kind #{klass_pat} unknown")
-        instances = db.instances[klass]
-        inst = instances[name_pat] || raise("name #{name_pat} for kind #{klass_pat} not found")
-        create_graph_one_inst(db, g, inst, nodes, edges)
+    # The layer an instance graph also follows by default, below the instance's own layer (technology is the bottom
+    # of the stack; implementation points at what it changes)
+    NEXT_LAYER = { "motivation" => "strategy", "strategy" => "business", "business" => "application",
+                   "application" => "technology", "implementation" => "application" }.freeze
+
+    # The layers the graph of a resource of this layer follows when its page opens: its own and the next one below,
+    # every layer for `other` (pages, views, locations, ... refer to anything)
+    def self.default_graph_layers(layer)
+      return Archsight::Resources::LAYERS.dup unless Archsight::Resources::LAYERS.include?(layer) && layer != "other"
+
+      [layer, NEXT_LAYER[layer]].compact
+    end
+
+    # The dependency graph of one instance: the resources its relations lead to, breadth first, so a resource gets
+    # the depth of its shortest path.
+    # @param max_depth [Integer, nil] follow relations this many steps from the instance (nil: all the way). A
+    #   resource at the limit that has more relations is drawn dashed.
+    # @param layers [Array<String>, nil] follow only relations to resources of these layers (nil: every layer); the
+    #   instance itself is always shown
+    def create_graph_one(db, klass_pat, name_pat, max_depth: nil, layers: nil)
+      klass = Archsight::Resources[klass_pat] || raise("kind #{klass_pat} unknown")
+      root = db.instances[klass]&.[](name_pat) || raise("name #{name_pat} for kind #{klass_pat} not found")
+
+      Archsight::Graphvis.new("#{klass_pat}:#{name_pat}").draw_dot do |g|
+        nodes = {}
+        edges = {}
+        queue = [[root, 0]]
+        while queue.any?
+          inst, depth = queue.shift
+          next if nodes[inst]
+
+          nodes[inst] = true
+          targets = graph_targets(inst, layers)
+          if max_depth && depth >= max_depth
+            gnode(g, inst, truncated: targets.any?)
+            next
+          end
+
+          gnode(g, inst)
+          targets.each do |verb, rel|
+            edge_name = "#{gname(inst)}|#{verb}|#{gname(rel)}"
+            gedge(g, inst, rel, verb) unless edges[edge_name]
+            edges[edge_name] = true
+            queue << [rel, depth + 1] unless nodes[rel]
+          end
+        end
+      end
+    end
+
+    # The relations of a kind to its own kind (a team's sub-teams, a service's dependencies on other services) as
+    # [verb, key] pairs
+    def self.self_relations(klass)
+      kind = klass.name.to_s.split("::").last
+      klass.declared_relations.filter_map { |verb, key, target| [verb, key] if target.to_s == kind }
+    end
+
+    # The graph of a kind: its resources that are related to each other by its relations to its own kind (an org
+    # chart for BusinessActor). Resources without such a relation are left out, the kind's list shows them.
+    def create_graph_kind(db, klass_pat)
+      klass = Archsight::Resources[klass_pat] || raise("kind #{klass_pat} unknown")
+      relations = Archsight::GraphvisRenderer.self_relations(klass)
+      sources = (db.instances[klass] || {}).values.reject(&:abandoned?)
+      edges = sources.flat_map do |inst|
+        relations.flat_map { |verb, key| inst.relations(verb, key).reject(&:abandoned?).map { |rel| [inst, verb, rel] } }
+      end
+      edges.uniq! { |inst, verb, rel| "#{gname(inst)}|#{verb}|#{gname(rel)}" }
+
+      Archsight::Graphvis.new(klass_pat).draw_dot do |g|
+        edges.flat_map { |inst, _, rel| [inst, rel] }.uniq.each { |inst| gnode(g, inst, simple_label: true) }
+        edges.each { |inst, verb, rel| gedge(g, inst, rel, verb) }
       end
     end
 
-    def create_graph_one_inst(db, graph, inst, nodes, edges)
-      return if nodes[inst] # Already visited - prevent infinite recursion
-
-      gnode(graph, inst)
-      nodes[inst] = true
-      inst.class.relations.each do |verb, kind|
-        inst.relations(verb, kind).each do |rel|
-          edge_name = "#{inst}|#{verb}|#{rel}"
-          gedge(graph, inst, rel, verb) unless edges[edge_name]
-          edges[edge_name] = true
-          create_graph_one_inst(db, graph, rel, nodes, edges)
+    # The [verb, target] pairs of an instance's relations the graph follows: those to resources of the layers
+    def graph_targets(inst, layers)
+      inst.class.relations.flat_map do |verb, kind|
+        inst.relations(verb, kind).filter_map do |rel|
+          [verb, rel] if layers.nil? || layers.include?(rel.class.layer)
         end
       end
     end

data/lib/archsight/resources/analysis.rb

@@ -57,8 +57,9 @@ class Archsight::Resources::Analysis < Archsight::Resources::Base
 
   # Description
   annotation "analysis/description",
-             description: "Human-readable description of what this analysis validates",
-             title: "Description"
+             description: "Human-readable description of what this analysis validates (markdown)",
+             title: "Description",
+             format: :markdown
 
   # Execution configuration
   annotation "analysis/timeout",

data/lib/archsight/resources/application_component.rb

@@ -25,6 +25,46 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     - Frontend applications
     - Background workers
 
+    ## Choosing this kind
+
+    **Question:** What is built, deployed and versioned?
+    **Test:** It has artifacts and a `component/type`, and can be deployed or linked.
+    **Name:** The part, by runtime role (API, Operator, Worker) as in "Payments:API", not by repository category
+    ("Testing", "Tools", "Infrastructure"). Test, tooling and infrastructure-as-code repositories belong to the
+    component they build, test or deploy.
+
+    A component belongs to exactly one service. See the modeling guide, "Choosing the Kind".
+
+    ## Component types
+
+    Set `component/type` to say what the component is built as; importers set it from the manifests:
+
+    - `executable`: has an entry point and is run or deployed (services, workers, operators, command-line tools)
+    - `library`: imported by other components and not run on its own (shared libraries, SDKs)
+    - `module`: a unit of versioning or dependency that bundles executables and importable libraries (a Go module
+      with `cmd/` and shared packages, a Maven parent, an npm workspace root)
+    - `plugin`: loaded by a host program (kubectl, Terraform, Grafana)
+    - `frontend`: runs in the browser
+    - `other`
+
+    `component/role` refines an executable or plugin (`service`, `cli`, `job`, `operator`, `agent`); importers cannot
+    tell these apart, so it is set by hand and never overwritten. Importers also add machine tags
+    (`namespace:value`) to the regular `architecture/tags`: `ecosystem:go`, `packaging:go-module`,
+    `linkage:shared`; the tags a person set stay, and a re-import only replaces the machine tags of these
+    namespaces. The entry points (main packages such as `cmd/api`) go to `component/entrypoints`, a list that
+    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.
+
+    ## Where it runs
+
+    A component is `servedBy` the `TechnologyService` it is deployed on (a product's cluster, a managed platform) and
+    `servedBy` the `TechnologySystemSoftware` it runs on (the runtime, such as a Kubernetes distribution). Deployment
+    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.
+
+    The computed `component/dependents` counts the components that depend on this one, which tells shared libraries
+    and modules from components nobody consumes.
+
     ## Security and risk modelling
 
     - **Asset at risk:** set `asset/value` and the protection needs; `assesses` from a vulnerability or risk.
@@ -46,6 +86,18 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
              title: "Architecture Size",
              enum: %w[microservice monolith]
 
+  # Classification
+  annotation "component/type",
+             description: "What the component is built as (executable, library, module, ...)",
+             title: "Component Type",
+             enum: %w[executable library module plugin frontend other],
+             filter: :word
+  annotation "component/role",
+             description: "What an executable or plugin does; set by hand",
+             title: "Component Role",
+             enum: %w[service cli job operator agent],
+             filter: :word
+
   # Availability
   annotation "availability/quality",
              description: "Service availability quality target per year",
@@ -129,6 +181,12 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
              enum: ["no support", "support by dev", "support by ops", "support by api",
                     "self service support via a frontend"]
 
+  annotation "component/entrypoints",
+             description: "Comma-separated entry points (main packages or commands such as cmd/api), set by importers",
+             title: "Entry points",
+             sidebar: false,
+             filter: :list
+
   # Deployment (from ArgoCD/cluster)
   annotation "deployment/images",
              description: "Deployed container images",
@@ -136,20 +194,21 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
              sidebar: false,
              filter: :list
   annotation "deployment/chart",
-             description: "Deployed Helm chart name",
+             description: "Deployed Helm charts, comma separated",
              title: "Helm Chart",
              sidebar: false,
-             filter: :word
+             filter: :list
   annotation "deployment/namespace",
-             description: "Kubernetes namespace",
+             description: "Kubernetes namespaces, comma separated",
              title: "Namespace",
              sidebar: false,
-             filter: :word
+             filter: :list
   annotation "deployment/cluster",
-             description: "Target cluster name",
+             description: "Target clusters, comma separated",
              title: "Cluster",
-             filter: :word,
-             summary: true
+             filter: :list,
+             summary: true,
+             deprecated: "list the clusters as spec.servedBy.technologyServices"
 
   # Computed Annotations
   computed_annotation "repository/artifacts/total",
@@ -197,6 +256,14 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     end
   end
 
+  computed_annotation "component/dependents",
+                      title: "Dependents",
+                      description: "Number of components that depend directly on this one",
+                      type: Integer,
+                      sidebar: true do
+    count(incoming(:ApplicationComponent))
+  end
+
   computed_annotation "scc/language",
                       title: "Primary Language",
                       summary: true,
@@ -350,6 +417,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :realizedThrough, :technologyArtifacts, :TechnologyArtifact
   relation :realizedBy, :technologyComponents, :TechnologyNode
   relation :servedBy, :technologyComponents, :TechnologySystemSoftware
+  relation :servedBy, :technologyServices, :TechnologyService
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent

data/lib/archsight/resources/application_interface.rb

@@ -25,6 +25,17 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
     - gRPC services
     - Message queues (producer/consumer interfaces)
     - WebSocket endpoints
+
+    ## Reachability
+
+    An interface is `servedBy` the `TechnologyInterface` that carries it (a protocol, an authentication method) and
+    by the `TechnologyCommunicationNetwork`s on which it can be reached, just as a `TechnologyNode` attaches to the
+    networks it is on. Together with `api/authenticationMethod` this decides the exposure of the interface: an
+    interface without authentication on an internal network is a different risk than on a network that
+    internet-facing components attach to. The network page lists the interfaces as incoming "served by".
+
+    Write the networks only when they are known. An interface without a network makes no claim about where it can
+    be reached.
   MD
 
   icon "usb"
@@ -47,6 +58,7 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
              enum: ["none", "hard coded", "pbac", "abac", "rbac"]
 
   relation :servedBy, :technologyComponents, :TechnologyInterface
+  relation :servedBy, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
   relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :serves, :dataObjects, :DataObject
 end

data/lib/archsight/resources/application_service.rb

@@ -20,11 +20,21 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
 
     Use ApplicationService to represent:
 
-    - Complete product offerings (ManagedKubernetes, DBaaS PostgreSQL)
+    - Behaviour software offers to a user or another system ("Payment Authorization", "Document Search")
     - Logical groupings of application components
     - Services exposed to business processes
     - APIs and their implementations as a cohesive unit
 
+    ## Choosing this kind
+
+    **Question:** What behaviour does software offer a consumer?
+    **Test:** It can be described without naming repositories, deployments or runtime objects, and has one owning actor.
+    **Name:** The function, not the technology or a deployment object ("Payment Authorization").
+
+    A component belongs to exactly one service. One service using another is `dependsOn` between the two services, not
+    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".
+
     ## Security and risk modelling
 
     A service is an asset at risk (`asset/*` profile, protection needs) that loss events `affects`, a trigger target
@@ -217,6 +227,7 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   end
 
   relation :realizedThrough, :applicationComponents, :ApplicationComponent
+  relation :dependsOn, :applicationServices, :ApplicationService
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
   relation :realizes, :motivationConstraints, :MotivationConstraint

data/lib/archsight/resources/base.rb

@@ -35,12 +35,20 @@ module Archsight
       # A kind may mark at most this many annotations as summary (see Base.annotation)
       MAX_SUMMARY_ANNOTATIONS = 3
 
+      # The options `annotation` accepts (see Archsight::Annotations::Annotation)
+      ANNOTATION_OPTIONS = %i[description filter title format enum sidebar type summary editor validator unique
+                              deprecated default].freeze
+
       # Define an annotation using the Annotation class
       # `summary: true` marks it as a summary attribute: it is returned with every search hit of this kind.
-      def self.annotation(key, description: nil, filter: nil, title: nil, format: nil, enum: nil, sidebar: true,
-                          type: nil, summary: false, editor: true, validator: nil)
-        options = { description: description, filter: filter, title: title, format: format, enum: enum,
-                    sidebar: sidebar, type: type, summary: summary, editor: editor, validator: validator }
+      # `unique: true` makes it an identifier: its values (each element of a list) are unique among the resources
+      # of the kind, which `archsight lint` checks, and its values are shown as chips without links (not tags).
+      # `deprecated: "what to use instead"` keeps it working while `archsight lint` lists every use.
+      # `default: "value"` is the value of a resource that does not set it (see #apply_annotation_defaults!).
+      def self.annotation(key, **options)
+        unknown = options.keys - ANNOTATION_OPTIONS
+        raise ArgumentError, "unknown annotation option(s) #{unknown.join(", ")} for #{key}" if unknown.any?
+
         register_annotation(Archsight::Annotations::Annotation.new(key, options))
       end
 
@@ -143,8 +151,11 @@ module Archsight
         end
       end
 
+      # The layer of the kind, one of Archsight::Resources::LAYERS (default `other`)
       def self.layer(layer_name = nil)
         if layer_name
+          raise ArgumentError, "unknown layer #{layer_name.inspect} for #{name}" unless Archsight::Resources::LAYERS.include?(layer_name)
+
           @layer = layer_name
         else
           @layer || "other" # default layer
@@ -223,6 +234,26 @@ module Archsight
         @raw["metadata"]["annotations"][key] = value
       end
 
+      # Gives every annotation with a `default:` that the file does not set its default, in the annotations hash like
+      # a written value, so queries, filters and the page see it. The editor leaves these out (#defaulted?), so a
+      # save does not write them into the file.
+      def apply_annotation_defaults!
+        self.class.annotations.each do |annotation|
+          next if annotation.default.nil? || annotation.pattern? || annotations.key?(annotation.key)
+
+          defaulted = (@defaulted ||= []) #: Array[String]
+          defaulted << annotation.key
+          @raw["metadata"] ||= {}
+          @raw["metadata"]["annotations"] = @raw["metadata"]["annotations"] || {} #: Hash[String, untyped]
+          @raw["metadata"]["annotations"][annotation.key] = annotation.default
+        end
+      end
+
+      # Whether the value of the annotation is its default, not written in the file
+      def defaulted?(key)
+        @defaulted&.include?(key) || false
+      end
+
       # Get a computed annotation value from the cache
       # @param key [String] The annotation key
       # @return [Object, nil] The computed value or nil
@@ -338,7 +369,29 @@ module Archsight
 
       def merge!(inst)
         # NOTE: path reference is preserved from the original instance
-        @raw = Archsight::Helpers.deep_merge(@raw, inst.raw)
+        merged = Archsight::Helpers.deep_merge(@raw, inst.raw)
+        union_list_annotations!(merged, inst.raw)
+        @raw = merged
+      end
+
+      # Annotations hold strings, which replace each other on merge. The values of a list annotation (tags, aliases)
+      # are joined instead, so two documents of one resource can each add to it.
+      def union_list_annotations!(merged, other_raw)
+        mine = @raw.dig("metadata", "annotations")
+        theirs = other_raw.dig("metadata", "annotations")
+        return unless mine.is_a?(Hash) && theirs.is_a?(Hash)
+
+        theirs.each do |key, value|
+          next unless mine[key].is_a?(String) && value.is_a?(String)
+          next unless self.class.annotation_matching(key)&.list?
+
+          values = (split_list(mine[key]) + split_list(value)).uniq
+          merged["metadata"]["annotations"][key] = values.join(",")
+        end
+      end
+
+      def split_list(text)
+        text.split(/,|\n/).map(&:strip).reject(&:empty?)
       end
 
       # raise provides a helper for better error messages including current path and line no

data/lib/archsight/resources/business_actor.rb

@@ -25,6 +25,11 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
     - External vendors or partners
     - Support organizations
     - Cross-functional groups
+    - Customers and providers: the parties a `BusinessContract` is `agreedBy`
+    - The party behind a `MotivationStakeholder`: the stakeholder is `representedBy` it
+    - The team behind infrastructure: a `TechnologyDevice`, `TechnologyEquipment`, `TechnologyNode` or
+      `TechnologyCommunicationNetwork` is `ownedBy` the team that operates it, and a device, equipment or node is
+      `servedBy` the team it is dedicated to (a test server, a cluster partition)
 
     ## Security and risk modelling
 

data/lib/archsight/resources/business_contract.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# BusinessContract represents an agreement between a provider and a consumer
+class Archsight::Resources::BusinessContract < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents an agreement between a provider and a consumer: the rights and obligations both agreed to.
+
+    ## ArchiMate Definition
+
+    **Layer:** Business
+    **Aspect:** Passive Structure
+
+    A contract is a formal or informal specification of an agreement between a provider and a consumer that
+    specifies rights and obligations. It is a specialization of a business object. A product is accompanied by a
+    contract, and a contract can consist of parts.
+
+    ## Usage
+
+    Use BusinessContract to represent:
+
+    - Framework contracts with a customer
+    - Call-offs under a framework contract (an order for one more block of capacity)
+    - Service level agreements
+    - Amendments of a contract
+
+    A contract is a `BusinessContract`, not a `DataObject` and not text in a description: only then do the graph,
+    views and analyses see what it agrees, who agreed it and what delivered it.
+
+    ## How it connects
+
+    - A `BusinessProduct` `aggregates` the contract that comes with it
+    - It is `agreedBy` its parties: the actual organisations (the customer, the provider), not a generic role
+    - It is `composedOf` its parts: call-offs, SLAs and amendments, which are contracts themselves (no cycles)
+    - It `covers` what it obliges the provider to deliver: equipment, nodes, technology and application services
+    - It is `realizedThrough` the `ImplementationDeliverable` that fulfils it; the `ImplementationWorkPackage` that
+      `realizes` the deliverable `affects` the equipment it installs
+
+    The other side shows these as incoming relations: the contracts an actor agreed, what covers a piece of
+    equipment or a service, the contract a deliverable fulfils.
+  MD
+
+  icon "journal-page"
+  layer "business"
+
+  annotation "contract/type",
+             description: "What kind of contract this is",
+             enum: %w[framework call-off sla amendment other],
+             filter: :word,
+             summary: true
+  annotation "contract/reference",
+             description: "The contract number",
+             title: "Reference",
+             summary: true
+  annotation "contract/from",
+             description: "When the contract starts (ISO 8601 date or time)",
+             title: "From",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+  annotation "contract/until",
+             description: "When the contract ends (ISO 8601 date or time)",
+             title: "Until",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :agreedBy, :businessActors, :BusinessActor
+  relation :composedOf, :businessContracts, :BusinessContract
+  relation :covers, :technologyEquipment, :TechnologyEquipment
+  relation :covers, :technologyNodes, :TechnologyNode
+  relation :covers, :technologyServices, :TechnologyService
+  relation :covers, :applicationServices, :ApplicationService
+  relation :realizedThrough, :implementationDeliverables, :ImplementationDeliverable
+end

data/lib/archsight/resources/business_product.rb

@@ -25,6 +25,17 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
     - Kubernetes services
     - Enterprise support packages
     - API products
+
+    ## Choosing this kind
+
+    **Question:** What does a customer buy or contract?
+    **Test:** It appears on a price list, catalog or customer documentation.
+    **Name:** The market name ("Online Checkout").
+
+    A product `realizes` a capability and is `servedBy` the services that deliver it. A product that nearly every
+    service serves is a catalog, not a product. See the modeling guide, "Choosing the Kind".
+
+    The contract that comes with the product is a `BusinessContract` the product `aggregates`.
   MD
 
   icon "box-iso"
@@ -204,4 +215,5 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   relation :servedBy, :applicationServices, :ApplicationService
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :provides, :complianceEvidences, :ComplianceEvidence
+  relation :aggregates, :businessContracts, :BusinessContract
 end

data/lib/archsight/resources/business_role.rb

@@ -37,6 +37,7 @@ class Archsight::Resources::BusinessRole < Archsight::Resources::Base
     - A `BusinessProcess` is `performedBy` the role, a `BusinessControl` is `ownedBy` and `executedBy` it
     - Assessments, principles, work packages, deliverables and implementation events are `ownedBy` it
     - The role is `performedBy` the actors that hold it
+    - A `MotivationStakeholder` can be `representedBy` the role (the interest belongs to the role, whoever holds it)
     - Pointing straight at an actor stays valid; use a role where the responsibility has a name of its own
 
     ## Security and risk modelling

data/lib/archsight/resources/implementation_deliverable.rb

@@ -26,6 +26,7 @@ class Archsight::Resources::ImplementationDeliverable < Archsight::Resources::Ba
     ## How it connects
 
     - A `ImplementationWorkPackage` `realizes` it
+    - A `BusinessContract` is `realizedThrough` it: the delivery that fulfils the contract (a call-off)
     - It is `ownedBy` an actor and `realizes` plateaus, requirements, goals, outcomes and `ComplianceEvidence`
 
     ## Security and risk modelling

data/lib/archsight/resources/implementation_plateau.rb

@@ -25,9 +25,12 @@ class Archsight::Resources::ImplementationPlateau < Archsight::Resources::Base
 
     ## How it connects
 
-    - A plateau `contains` the components, services, nodes, processes and requirements that belong to it
+    - A plateau `contains` the application components and services, technology nodes, services, system
+      software and artifacts, business processes and requirements that belong to it. Listing the technology
+      elements lets a platform migration (platform A to platform B) be described state by state
     - It `triggers` the next plateau (migration path)
-    - A `ImplementationDeliverable` `realizes` it; a `ImplementationGap` `compares` two plateaus
+    - A `ImplementationDeliverable` `realizes` it; a `ImplementationGap` `compares` two plateaus, so
+      the elements added, kept or removed between them show up per plateau
   MD
 
   icon "packages"
@@ -55,6 +58,9 @@ class Archsight::Resources::ImplementationPlateau < Archsight::Resources::Base
   relation :contains, :applicationComponents, :ApplicationComponent
   relation :contains, :applicationServices, :ApplicationService
   relation :contains, :technologyNodes, :TechnologyNode
+  relation :contains, :technologyServices, :TechnologyService
+  relation :contains, :technologySystemSoftware, :TechnologySystemSoftware
+  relation :contains, :technologyArtifacts, :TechnologyArtifact
   relation :contains, :businessProcesses, :BusinessProcess
   relation :contains, :motivationRequirements, :MotivationRequirement
   relation :triggers, :implementationPlateaus, :ImplementationPlateau

data/lib/archsight/resources/implementation_work_package.rb

@@ -28,7 +28,7 @@ class Archsight::Resources::ImplementationWorkPackage < Archsight::Resources::Ba
 
     - `ownedBy` the accountable actor or role, `performedBy` the actors or roles that carry it out
     - `realizes` deliverables (its results), requirements and goals
-    - `affects` the assets it changes; the assessments (risks, findings) it treats are `mitigatedBy` it (written on the assessment)
+    - `affects` the assets it changes, for example the `TechnologyEquipment` a project installs; the assessments (risks, findings) it treats are `mitigatedBy` it (written on the assessment)
     - `triggers` the work packages that follow it; an `ImplementationEvent` can trigger it
     - A `ImplementationGap` is `closedBy` it
 
@@ -79,5 +79,6 @@ class Archsight::Resources::ImplementationWorkPackage < Archsight::Resources::Ba
   relation :affects, :applicationComponents, :ApplicationComponent
   relation :affects, :applicationServices, :ApplicationService
   relation :affects, :technologyNodes, :TechnologyNode
+  relation :affects, :technologyEquipment, :TechnologyEquipment
   relation :triggers, :implementationWorkPackages, :ImplementationWorkPackage
 end

data/lib/archsight/resources/import.rb

@@ -35,26 +35,52 @@ class Archsight::Resources::Import < Archsight::Resources::Base
   icon "download"
   layer "other"
 
-  # Handler selection
+  # Handler selection: a built-in handler or one the resources repository registers (import/handlerPath)
   annotation "import/handler",
-             description: "Handler class name to execute this import",
+             description: "Name of the handler that executes this import: a built-in one or one registered by the file " \
+                          "in import/handlerPath",
              title: "Handler",
              summary: true,
-             enum: %w[
-               gitlab github repository
-               rest-api rest-api-index
-               jira-discover jira-metrics
-               go-grapher go-dep-resolver
-               cpp-grapher ruby-grapher python-grapher
-               java-grapher javascript-grapher
-               rust-grapher crystal-grapher elixir-grapher
-             ]
+             filter: :word,
+             validator: lambda { |value|
+               require "archsight/import/handler_loader"
+               Archsight::Import::HandlerLoader.load_builtin!
+               next if Archsight::Import::Registry[value]
+
+               "unknown import handler '#{value}'. Registered: #{Archsight::Import::Registry.handlers.sort.join(", ")}; " \
+                 "a handler of the resources repository needs import/handlerPath"
+             }
+
+  annotation "import/handlerPath",
+             description: "Ruby file of a handler that lives in the resources repository, relative to the resources " \
+                          "root (e.g., 'importers/deployments.rb'). It registers the name used in import/handler.",
+             title: "Handler Path"
+
+  annotation "import/dependsOn",
+             description: "Imports that must run first, by name or glob pattern (e.g., 'Import:Repo:*'), comma " \
+                          "separated. Adds to the dependency on the import that generated this one.",
+             title: "Depends On",
+             filter: :list,
+             sidebar: false
 
   # Output configuration
   annotation "import/outputPath",
              description: "Output file path relative to resources root (e.g., 'imports/generated/gitlab.yaml')",
              title: "Output Path"
 
+  annotation "generated/inputsHash",
+             description: "Hash of the files matched by import/config/inputs at the last run (for change detection)",
+             title: "Inputs Hash",
+             sidebar: false,
+             editor: false
+
+  annotation "generated/outputs",
+             description: "Files the last run wrote, relative to the resources root",
+             title: "Outputs",
+             filter: :list,
+             sidebar: false,
+             editor: false
+
   # Control flags
   annotation "import/enabled",
              description: "Whether this import is enabled",