archsight 0.3.1 → 0.3.3

data/lib/archsight/annotations/relation_resolver.rb

@@ -11,6 +11,17 @@
 # - Symbol: Simple kind filter (e.g., :TechnologyArtifact)
 # - String: Query selector (e.g., 'TechnologyArtifact: activity/status == "active"')
 class Archsight::Annotations::ComputedRelationResolver
+  # The instances that refer to a resource through relations that are written in files. Computed annotations sum up the
+  # modelled architecture (costs, teams, repositories): what a page or a description merely mentions or depicts (see
+  # Archsight::References) must not change them, so they follow modelled relations only.
+  def self.modelled_references(inst)
+    (inst.references || []).filter_map do |ref|
+      next ref unless ref.is_a?(Hash)
+
+      ref[:instance] unless Archsight::Resources::DERIVED_VERBS.include?(ref[:verb])
+    end
+  end
+
   MAX_DEPTH = 10
 
   # TraversalCache holds what can be shared between all resolvers of one computation run: the unfiltered
@@ -83,9 +94,9 @@ class Archsight::Annotations::ComputedRelationResolver
 
     def neighbours(inst, direction)
       if direction == :outgoing
-        inst.class.relations.flat_map { |verb, kind_name, _klass_name| inst.relations(verb, kind_name) }
+        inst.class.declared_relations.flat_map { |verb, kind_name, _klass_name| inst.relations(verb, kind_name) }
       else
-        (inst.references || []).filter_map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }
+        Archsight::Annotations::ComputedRelationResolver.modelled_references(inst)
       end
     end
   end
@@ -103,7 +114,7 @@ class Archsight::Annotations::ComputedRelationResolver
   def outgoing(filter = nil)
     results = []
 
-    @instance.class.relations.each do |_verb, kind_name, _klass_name|
+    @instance.class.declared_relations.each do |_verb, kind_name, _klass_name|
       rels = @instance.relations(_verb, kind_name)
       rels.each do |rel|
         results << rel if matches_filter?(rel, filter)
@@ -127,9 +138,7 @@ class Archsight::Annotations::ComputedRelationResolver
   # @param filter [Symbol, String, nil] Optional kind filter (Symbol) or query selector (String)
   # @return [Array] Array of instances that reference this one
   def incoming(filter = nil)
-    refs = @instance.references || []
-    # Extract instances from reference hashes
-    instances = refs.map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }.compact
+    instances = self.class.modelled_references(@instance).compact
 
     if filter.nil?
       instances

data/lib/archsight/annotations/risk_annotations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Risk module adds the annotations that group security and risk resources: the paper's "risk domain" and the
+# classification of the risk
+module Archsight::Annotations::Risk
+  def self.included(base)
+    base.class_eval do
+      annotation "risk/domain",
+                 description: "Risk domain(s) the resource belongs to (comma-separated); groups threats, risks, " \
+                              "vulnerabilities, measures and assets that share a context",
+                 title: "Risk domain",
+                 filter: :list
+
+      annotation "risk/category",
+                 description: "Classification of the risk (CAS enterprise risk classification, plus compliance and security)",
+                 title: "Risk category",
+                 enum: %w[hazard financial operational strategic compliance security],
+                 filter: :word
+    end
+  end
+end

data/lib/archsight/cli.rb

@@ -127,6 +127,12 @@ module Archsight
       linter = Archsight::Linter.new(db)
       errors = linter.validate
 
+      warnings = linter.warnings
+      if warnings.any?
+        puts "Deprecations (#{warnings.count}):"
+        warnings.each { |warning| puts "  #{warning}" }
+      end
+
       if errors.any?
         puts "Validation Errors (#{errors.count}):"
         errors.each { |error| display_error_with_context(error) }

data/lib/archsight/database.rb

@@ -5,6 +5,7 @@ require_relative "graph"
 require_relative "resources"
 require_relative "page_loader"
 require_relative "query"
+require_relative "references"
 
 module Archsight
   # LineReference combines a path and line reference
@@ -40,12 +41,19 @@ module Archsight
     end
   end
 
+  # Deprecation is a use of a renamed kind or relation key that was accepted under its old name
+  Deprecation = Struct.new(:ref, :message) do
+    def to_s
+      "#{ref}: #{message}"
+    end
+  end
+
   # Database loads yaml files and folders to create an in-memory representation
   # of the structure. The loading and parsing of files will raise errors
   # if invalid data is passed.
   class Database
     attr_accessor :instances, :verbose, :verify, :compute_annotations, :only_kinds
-    attr_reader :path
+    attr_reader :path, :deprecations
 
     def initialize(path, verbose: false, verify: true, compute_annotations: true, only_kinds: nil)
       @path = path
@@ -54,10 +62,12 @@ module Archsight
       @compute_annotations = compute_annotations
       @only_kinds = only_kinds
       @instances = {}
+      @deprecations = []
     end
 
     def reload!
       @instances = {}
+      @deprecations = []
 
       # load all resources
       Dir.glob(File.join(@path, "**/*.{yaml,md}")).each do |path|
@@ -67,6 +77,7 @@ module Archsight
       end
 
       verify! if @verify
+      derive_references! if @verify
       compute_all_annotations! if @verify && @compute_annotations
     rescue Psych::SyntaxError => e
       # Wrap YAML syntax errors in ResourceError for consistent handling
@@ -118,12 +129,49 @@ module Archsight
 
       kind = obj["kind"] || raise("kind not defined")
       klass = Archsight::Resources[kind] || raise("#{kind} is not a valid kind")
+      accept_old_names(obj)
       inst = klass.new(obj, @current_ref)
       raise("metadata name of #{kind} not present") if inst.name.to_s.strip.empty?
 
       inst
     end
 
+    # Documents may still use the old name of a renamed kind and the old relation keys. They are rewritten to the
+    # current names here, so everything after loading only sees those, and each rewrite is kept as a deprecation
+    # (reported by `archsight lint`).
+    def accept_old_names(obj)
+      kind = obj["kind"]
+      current = Archsight::Resources.canonical(kind)
+      if current != kind
+        deprecate("kind '#{kind}' is renamed to '#{current}'")
+        obj["kind"] = current
+      end
+
+      return unless obj["spec"].is_a?(Hash)
+
+      obj["spec"].each do |verb, keys|
+        next unless keys.is_a?(Hash)
+
+        Archsight::Resources::RELATION_KEY_ALIASES.each do |old_key, new_key|
+          next unless keys.key?(old_key)
+
+          deprecate("relation key '#{old_key}' under '#{verb}' is renamed to '#{new_key}'")
+          keys[new_key] = (Array(keys[new_key]) + Array(keys.delete(old_key))).uniq
+        end
+      end
+    end
+
+    def deprecate(message)
+      @deprecations << Deprecation.new(@current_ref, "#{message} (the old name will be removed in a future release)")
+    end
+
+    # Whether a document of this kind is wanted by the only_kinds filter, whichever of its names either side uses
+    def kind_wanted?(kind)
+      return true unless @only_kinds
+
+      @only_kinds.map { |k| Archsight::Resources.canonical(k) }.include?(Archsight::Resources.canonical(kind))
+    end
+
     def load_file(path)
       File.open(path, "r") do |f|
         YAML.parse_stream(f) do |node|
@@ -132,7 +180,7 @@ module Archsight
           next unless obj # skip empty / unknown documents
 
           # Skip resources that don't match only_kinds filter
-          next if @only_kinds && !@only_kinds.include?(obj["kind"])
+          next unless kind_wanted?(obj["kind"])
 
           self << create_valid_instance(obj)
         end
@@ -186,7 +234,7 @@ module Archsight
     end
 
     def verify_instance_relations!(inst)
-      inst.class.relations.each do |verb, kind, klass_name|
+      inst.class.declared_relations.each do |verb, kind, klass_name|
         rels = inst.relations(verb, kind).map do |rel_name|
           rel_klass = Archsight::Resources[klass_name] || raise_for(inst, "#{klass_name} is not a valid relation kind")
           kind_display = rel_klass.to_s.sub(/^Archsight::Resources::/, "")
@@ -197,6 +245,12 @@ module Archsight
       end
     end
 
+    # Adds the relations that the text and the diagrams of the resources imply (`mentions`, `depicts`), after all
+    # written relations are resolved and before the computed annotations are calculated, which follow relations.
+    def derive_references!
+      Archsight::References.derive!(self)
+    end
+
     # Compute all computed annotations for all instances
     def compute_all_annotations!
       manager = Archsight::Annotations::ComputedManager.new(self)

data/lib/archsight/diagram.rb

@@ -44,6 +44,13 @@ module Archsight
       time(profile, :render) { Renderer.render(graph, layout, relation_filter: relation_filter, style: style, id_prefix: id_prefix) }
     end
 
+    # 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
+    end
+
     def self.time(profile, key)
       return yield unless profile
 

data/lib/archsight/documentation.rb

@@ -7,7 +7,7 @@ module Archsight
   # Documentation generates markdown documentation for architecture resources
   class Documentation
     # Layer display order (top to bottom)
-    LAYER_ORDER = %w[motivation strategy business application technology].freeze
+    LAYER_ORDER = %w[motivation strategy business application technology implementation].freeze
 
     # Layer display names
     LAYER_NAMES = {
@@ -15,7 +15,8 @@ module Archsight
       "strategy" => "Strategy Layer",
       "business" => "Business Layer",
       "application" => "Application Layer",
-      "technology" => "Technology Layer"
+      "technology" => "Technology Layer",
+      "implementation" => "Implementation & Migration Layer"
     }.freeze
 
     # Resource kinds to exclude from the diagram
@@ -104,7 +105,7 @@ module Archsight
           # Skip kinds not in a displayed layer
           next unless LAYER_ORDER.include?(klass.layer)
 
-          klass.relations.each do |verb, _relation_kind, target_klass|
+          klass.declared_relations.each do |verb, _relation_kind, target_klass|
             # Skip relations to excluded kinds
             next if EXCLUDED_KINDS.include?(target_klass.to_s)
 
@@ -149,13 +150,16 @@ module Archsight
       end
 
       def generate_relations_table(klass)
-        return "_No relations defined._" if klass.relations.empty?
+        derived = "Every resource also has the derived relations #{Archsight::Resources::DERIVED_VERBS.map { |v| "`#{v}`" }.join(" and ")} " \
+                  "towards any kind: they follow from links in its text and from its diagrams, so they are not written in files " \
+                  "(see the Modeling Guide)."
+        return "_No relations defined._\n\n#{derived}" if klass.declared_relations.empty?
 
         rows = ["| Relation | Target | Kind |", "|----------|--------|------|"]
-        klass.relations.each do |verb, kind, target_klass|
+        klass.declared_relations.each do |verb, kind, target_klass|
           rows << "| #{verb} | #{target_klass} | #{kind} |"
         end
-        rows.join("\n")
+        "#{rows.join("\n")}\n\n#{derived}"
       end
 
       def format_values(annotation)

data/lib/archsight/editor.rb

@@ -21,7 +21,7 @@ module Archsight
     def build_resource(kind:, name:, annotations: {}, relations: [])
       resource = {
         "apiVersion" => "architecture/v1alpha1",
-        "kind" => kind,
+        "kind" => Archsight::Resources.canonical(kind), # saving a resource that had the old name migrates it
         "metadata" => {
           "name" => name
         }
@@ -129,7 +129,7 @@ module Archsight
       klass = Archsight::Resources[kind]
       return [] unless klass
 
-      klass.relations
+      klass.declared_relations # derived relations are not written in files
     end
 
     # Get unique verbs for a resource kind's relations

data/lib/archsight/helpers/requirements_blocks.rb

@@ -5,7 +5,7 @@ require_relative "fenced_blocks"
 
 module Archsight
   module Helpers
-    # Turns ```requirements fenced blocks in rendered markdown into the table of business requirements of a
+    # Turns ```requirements fenced blocks in rendered markdown into the table of requirements of a
     # selection of resources (see Archsight::Requirements):
     #
     #   ```requirements

data/lib/archsight/helpers/resource_resolver.rb

@@ -38,7 +38,7 @@ module Archsight
         klass = Archsight::Resources[kind]
         return [] unless klass && @database.instances.fetch(klass, {}).key?(name)
 
-        [[kind, name]]
+        [[Archsight::Resources.canonical(kind), name]] # a renamed kind is linked under its new name
       end
 
       def in_any_kind(name)

data/lib/archsight/helpers/wiki_links.rb

@@ -64,6 +64,17 @@ module Archsight
         found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
       end
 
+      # Like target_for, but only an exact name counts: a page by name or title, `Kind/Name`, or a resource name that
+      # exists in one kind. A target that only matches part of a name does not name anything. For relations that are
+      # derived from text, where a wrong guess would be a wrong relation.
+      def exact_target_for(target)
+        page = find_page(target)
+        return page if page
+
+        found = @resolver.find(target)
+        found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
+      end
+
       # Page path for a page name, nil if there is no such page
       def page_path(page)
         "/pages/#{ERB::Util.url_encode(page.name)}"

data/lib/archsight/linter.rb

@@ -8,6 +8,12 @@ module Archsight
     # Valid @component references in View annotations
     VALID_COMPONENTS = %w[activity git jira languages owner repositories status].freeze
 
+    # Relations the cycle check leaves out. Relations are followed from the dependent to what it relies on, so
+    # the declared ones form a DAG; `dependsOn` is the exception because components may depend on each other at
+    # runtime. The derived relations (`mentions`, `depicts`) are sideways views and are not declared, so they
+    # never enter the check.
+    CYCLE_EXEMPT_VERBS = %i[dependsOn].freeze
+
     def initialize(database)
       @database = database
       @errors = []
@@ -22,10 +28,17 @@ module Archsight
           validate_menu(instance) if instance.klass == "PageMenu"
         end
       end
+      validate_relation_cycles
 
       @errors
     end
 
+    # Things that still work but should be changed: renamed kinds and relation keys that the files still use.
+    # They are not errors, so they do not make `archsight lint` fail.
+    def warnings
+      @database.respond_to?(:deprecations) ? @database.deprecations.map(&:to_s) : []
+    end
+
     private
 
     # Pages need exactly one menu and their [[links]] must resolve
@@ -73,6 +86,103 @@ module Archsight
       nil
     end
 
+    # Declared relations must not lead back to where they started (see the "Direction of Relations" modeling guide)
+    def validate_relation_cycles
+      graph = relation_graph
+      strongly_connected_groups(graph).each do |group|
+        cycle = cycle_through(group.first, group, graph)
+        names = cycle.map { |step| step[:to].name }
+        start = group.first
+        path = ([start.name] + names).zip(cycle.map { |step| step[:verb] }).flat_map { |name, verb| [name, verb && "-#{verb}->"] }.compact
+        @errors << "#{start.path_ref}: #{start.klass} '#{start.name}' is part of a relation cycle (#{path.join(" ")})"
+      end
+    end
+
+    # { instance => [{ verb:, to: }] } over the declared relations
+    def relation_graph
+      graph = {}
+      @database.instances.each_value do |instances_hash|
+        instances_hash.each_value do |instance|
+          graph[instance] = instance.class.declared_relations.flat_map do |verb, key, _kind|
+            next [] if CYCLE_EXEMPT_VERBS.include?(verb)
+
+            instance.relations(verb, key).map { |target| { verb: verb, to: target } }
+          end
+        end
+      end
+      graph
+    end
+
+    # Groups of instances that reach each other (iterative Tarjan, the graph can be deep); a single instance counts
+    # only when it points at itself
+    def strongly_connected_groups(graph)
+      index = {}
+      lowlink = {}
+      on_stack = {}
+      stack = []
+      groups = []
+      counter = 0
+
+      graph.each_key do |root|
+        next if index.key?(root)
+
+        work = [[root, 0]]
+        until work.empty?
+          node, edge = work.last
+          if edge.zero?
+            index[node] = lowlink[node] = counter
+            counter += 1
+            stack << node
+            on_stack[node] = true
+          end
+
+          edges = graph[node] || []
+          if edge < edges.length
+            work.last[1] += 1
+            target = edges[edge][:to]
+            if !index.key?(target)
+              work << [target, 0]
+            elsif on_stack[target]
+              lowlink[node] = [lowlink[node], index[target]].min
+            end
+          else
+            work.pop
+            lowlink[work.last.first] = [lowlink[work.last.first], lowlink[node]].min unless work.empty?
+            next unless lowlink[node] == index[node]
+
+            group = []
+            loop do
+              member = stack.pop
+              on_stack[member] = false
+              group << member
+              break if member.equal?(node)
+            end
+            groups << group if group.length > 1 || edges.any? { |e| e[:to].equal?(node) }
+          end
+        end
+      end
+      groups
+    end
+
+    # One concrete cycle through `start` inside its group: [{ verb:, to: }, ...] ending at `start`
+    def cycle_through(start, group, graph)
+      members = group.to_h { |member| [member, true] }
+      queue = [[start, []]]
+      seen = { start => true }
+      until queue.empty?
+        node, path = queue.shift
+        graph[node].each do |edge|
+          next unless members[edge[:to]]
+          return path + [edge] if edge[:to].equal?(start)
+          next if seen[edge[:to]]
+
+          seen[edge[:to]] = true
+          queue << [edge[:to], path + [edge]]
+        end
+      end
+      []
+    end
+
     def validate_instance_annotations(instance)
       instance.annotations.each do |key, value|
         # Find matching annotation definition (handles both exact and pattern matches)

data/lib/archsight/mcp/analyze_resource_tool.rb

@@ -24,13 +24,13 @@ class Archsight::MCP::AnalyzeResourceTool < FastMcp::Tool
        Example: kind="ApplicationInterface", name="Kubernetes:RestAPI", impact=true
 
     RESOURCE KINDS: TechnologyArtifact, ApplicationComponent, ApplicationInterface,
-    ApplicationService, BusinessRequirement, ComplianceEvidence, and more.
+    ApplicationService, MotivationRequirement, ComplianceEvidence, and more.
   DESC
   arguments do
     required(:kind).filled(:string).description(
       "Resource type to analyze. Common kinds: TechnologyArtifact (repos, code), " \
       "ApplicationComponent (services), ApplicationInterface (APIs), " \
-      "BusinessRequirement (compliance controls), ComplianceEvidence (compliance proof)"
+      "MotivationRequirement (compliance and legal requirements), ComplianceEvidence (compliance proof)"
     )
     required(:name).filled(:string).description(
       "Exact name of the resource (case-sensitive). Use QueryTool first if unsure of exact name."

data/lib/archsight/mcp/resource_doc_tool.rb

@@ -23,7 +23,7 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
     • ApplicationComponent - Services and application building blocks
     • ApplicationInterface - APIs and interfaces exposed by components
     • ApplicationService - Business services provided by applications
-    • BusinessRequirement - Compliance controls and business requirements
+    • MotivationRequirement - Statements of need, such as compliance and legal requirements
     • ComplianceEvidence - Evidence linking artifacts to compliance requirements
   DESC
   arguments do
@@ -61,7 +61,7 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
         kind: kind_symbol.to_s,
         description: klass.description || "No description available",
         annotation_count: klass.annotations.count,
-        relation_count: klass.relations.count
+        relation_count: klass.declared_relations.count
       }
     end
 

data/lib/archsight/query/ast.rb

@@ -218,7 +218,8 @@ module Archsight::Query::AST
     attr_reader :kind_name
 
     def initialize(kind_name)
-      @kind_name = kind_name
+      # a renamed kind keeps matching under its old name
+      @kind_name = Archsight::Resources.canonical(kind_name)
     end
   end
 

data/lib/archsight/query/evaluator.rb

@@ -292,7 +292,7 @@ class Archsight::Query::Evaluator
 
     case node.operator
     when "=="
-      instance_kind == node.value.value.to_s
+      instance_kind == Archsight::Resources.canonical(node.value.value)
     when "=~"
       regex = build_regex_from_value(node.value)
       !!(instance_kind =~ regex)
@@ -303,7 +303,7 @@ class Archsight::Query::Evaluator
 
   def evaluate_kind_in_condition(node, instance)
     instance_kind = instance.class.to_s.split("::").last
-    query_values = node.values.map { |v| v.value.to_s }
+    query_values = node.values.map { |v| Archsight::Resources.canonical(v.value) }
     query_values.include?(instance_kind)
   end
 

data/lib/archsight/references.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Archsight
+  # References derives relations from what the text and the diagrams of resources say, so that nobody has to repeat in
+  # YAML what is already written:
+  #
+  # - `mentions`: `[[Target]]`, `[[Kind/Name]]` and `![[View/Name]]` in a markdown text (a page's content, the
+  #   description of any resource, any annotation a kind defines as markdown)
+  # - `depicts`: the `resource "..."` of the nodes of a diagram: an ```asd block in such a text, an `.asd` file embedded
+  #   with `![](file.asd)`, and the `architecture/diagram` annotation of any resource
+  #
+  # The relations are added to the resources like written ones (see Base#add_derived_relation), after the written ones
+  # are resolved, and are rebuilt on every load. Only what names a resource exactly counts: a target that is missing,
+  # ambiguous or only matches part of a name is skipped (the linter reports the broken ones), and so are links in code.
+  # Views and requirements blocks select resources with a query when they run, so they name nothing.
+  module References
+    # A fenced code block, and an inline code span: links in them are shown as written
+    FENCE = /^[ \t]*(?:```|~~~).*?^[ \t]*(?:```|~~~)[ \t]*$/m
+    INLINE_CODE = /`[^`\n]*`/
+
+    # Annotations that are markdown besides those a kind defines with `format: :markdown`
+    MARKDOWN_KEYS = %w[page/content architecture/description].freeze
+
+    module_function
+
+    # Adds the derived relations to every resource of the database.
+    def derive!(database)
+      finder = Finder.new(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) } }
+      end
+    end
+
+    # The resources a markdown text mentions with `[[...]]` links and `![[View/...]]` embeds, outside code.
+    # @return [Array<Base>]
+    def mentions(markdown, finder)
+      visible = markdown.to_s.gsub(FENCE, "").gsub(INLINE_CODE, "")
+      embeds = visible.scan(Helpers::Embeds::PATTERN).flatten.map(&:strip).filter_map { |reference| finder.embed(reference) }
+      targets = visible.gsub(Helpers::Embeds::PATTERN, "").scan(Helpers::WikiLinks::PATTERN).map { |match| match.first.strip }
+      (embeds + targets.filter_map { |target| finder.link(target) }).uniq
+    end
+
+    # 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) }
+    rescue Diagram::Error
+      []
+    end
+
+    # The markdown texts of a resource: a page's content, the description, and every annotation its kind defines as
+    # markdown.
+    def text_sources(inst)
+      inst.annotations.filter_map do |key, value|
+        value if value.is_a?(String) && value.include?("[[") && markdown_annotation?(inst, key)
+      end
+    end
+
+    # The diagram sources of a resource: ```asd blocks and embedded `.asd` files of its markdown texts, and its
+    # annotations that are diagrams (`architecture/diagram`).
+    def diagram_sources(inst, database)
+      sources = [] #: Array[String]
+      inst.annotations.each do |key, value|
+        next unless value.is_a?(String)
+
+        if inst.class.annotation_format(key) == :asd
+          sources << value
+        elsif markdown_annotation?(inst, key)
+          sources.concat(Helpers::DiagramBlocks.sources(value))
+          sources.concat(embedded_diagrams(inst, value, database)) if value.include?(".asd")
+        end
+      end
+      sources
+    end
+
+    def markdown_annotation?(inst, key)
+      MARKDOWN_KEYS.include?(key) || inst.class.annotation_format(key) == :markdown
+    end
+
+    # The sources of the `.asd` files a markdown text embeds, found next to the file the resource comes from
+    def embedded_diagrams(inst, markdown, database)
+      resources_dir = database.path.to_s
+      base_dir = Assets.base_dir_for(inst, resources_dir: resources_dir)
+      return [] unless base_dir
+
+      Helpers::AssetImages.asd_files(markdown, base_dir: base_dir, resources_dir: resources_dir).filter_map do |_path, file|
+        File.read(file) if File.size(file) <= Helpers::AssetImages::MAX_ASD
+      end
+    rescue SystemCallError
+      []
+    end
+
+    def link(inst, verb, target)
+      return if target.equal?(inst)
+
+      inst.add_derived_relation(verb, target)
+    end
+
+    # Finds the resource a reference in a text names, exactly (see WikiLinks#exact_target_for)
+    class Finder
+      def initialize(database)
+        @database = database
+        @resolver = Helpers::ResourceResolver.new(database)
+        @links = Helpers::WikiLinks.new(database, resolver: @resolver)
+      end
+
+      # A `[[...]]` target: a page by name or title, `Kind/Name`, or a resource name
+      def link(target)
+        @links.exact_target_for(target)
+      end
+
+      # An `![[Kind/Name]]` embed: only views and analyses can be embedded
+      def embed(reference)
+        kind = reference.split("/", 2).first
+        return unless Helpers::Embeds::KINDS.include?(kind)
+
+        reference(reference)
+      end
+
+      # A `resource "..."` of a diagram or an embed: `Name` across all kinds, or `Kind/Name`
+      def reference(reference)
+        found = @resolver.find(reference)
+        found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
+      end
+    end
+  end
+end