archsight 0.3.0 → 0.3.2

data/lib/archsight/import/handlers/go_module_parser.rb

@@ -133,9 +133,12 @@ module Archsight::Import::Handlers::GoModuleParser
   # Convert a Go module path to an ApplicationComponent name.
   # Strips the SCM host segment and joins remaining path segments with ":".
   # "github.com/example-org/billing-service/pkg" → "example-org:billing-service:pkg"
+  # A module path without a host ("module foo") has nothing left after stripping
+  # it and gets no component, rather than one with an empty name.
+  # @return [String, nil]
   def component_name(mod_name)
     parts = mod_name.split("/")
     parts.shift
-    parts.join(":")
+    parts.join(":") unless parts.empty?
   end
 end

data/lib/archsight/linter.rb

@@ -26,6 +26,12 @@ module Archsight
       @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
@@ -107,6 +113,8 @@ module Archsight
         @errors << "#{instance.path_ref}: Markdown syntax error in annotation '#{key}': #{e.message}"
       end
       validate_diagram_blocks(instance, key, value)
+      validate_view_blocks(instance, key, value)
+      validate_requirements_blocks(instance, key, value)
       validate_asset_images(instance, key, value)
       validate_embeds(instance, key, value)
     end
@@ -161,6 +169,25 @@ module Archsight
       end
     end
 
+    # Every ```view block must be a valid View, or the page shows an error box instead of the view
+    def validate_view_blocks(instance, key, value)
+      Helpers::ViewBlocks.sources(value).each_with_index do |source, index|
+        spec = Helpers::ViewBlocks.parse(source)
+        check_view_components(instance, spec[:fields])
+      rescue Helpers::ViewBlocks::Error => e
+        @errors << "#{instance.path_ref}: View error in annotation '#{key}' (view block #{index + 1}): #{e.message}"
+      end
+    end
+
+    # Every ```requirements block must be a valid filter, or the page shows an error box instead of the table
+    def validate_requirements_blocks(instance, key, value)
+      Helpers::RequirementsBlocks.sources(value).each_with_index do |source, index|
+        Helpers::RequirementsBlocks.parse(source)
+      rescue Helpers::RequirementsBlocks::Error => e
+        @errors << "#{instance.path_ref}: Requirements error in annotation '#{key}' (requirements block #{index + 1}): #{e.message}"
+      end
+    end
+
     # 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 = []
@@ -173,10 +200,11 @@ module Archsight
     end
 
     def validate_view_fields(instance)
-      fields = instance.annotations["view/fields"]
-      return unless fields
+      check_view_components(instance, instance.annotations["view/fields"].to_s.split(",").map(&:strip))
+    end
 
-      fields.split(",").map(&:strip).each do |field|
+    def check_view_components(instance, fields)
+      fields.each do |field|
         next unless field.start_with?("@")
 
         component_name = field[1..]

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

@@ -38,6 +38,20 @@ module Archsight::MCP
       result
     end
 
+    # The summary attributes of a resource's kind (annotations marked `summary: true`) that have a value,
+    # as [{key:, title:, value:, format:, type:}]. Computed annotations are included; they are precomputed
+    # at load and absent when empty. Lists (filter: :list) come back as arrays, Integer/Float typed values
+    # as numbers, `type` is the short type name ("Integer", "Time", "Person", ...) or nil.
+    def highlights(resource)
+      resource.class.summary_annotations.filter_map do |annotation|
+        value = highlight_value(annotation, resource)
+        next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+        { key: annotation.key, title: annotation.title, value: value, format: annotation.format,
+          type: short_type_name(annotation.type) }
+      end
+    end
+
     def extract_description(resource)
       description = resource.annotations["architecture/description"]
       return "No description" if description.nil?
@@ -45,6 +59,30 @@ module Archsight::MCP
       description.split("\n").first
     end
 
+    def short_type_name(type)
+      type&.name.to_s.split("::").last
+    end
+
+    # The hit's kind name ("TechnologyArtifact") and the number of hits per kind
+    def kind_of(resource)
+      resource.class.to_s.split("::").last
+    end
+
+    def count_by_kind(results)
+      results.group_by { |r| kind_of(r) }.transform_values(&:length)
+    end
+
+    def highlight_value(annotation, resource)
+      value = annotation.value_for(resource)
+      return value unless value.is_a?(String)
+
+      case annotation.type&.name
+      when "Integer" then value.match?(/\A-?\d+\z/) ? value.to_i : value
+      when "Float" then value.match?(/\A-?\d+(\.\d+)?\z/) ? value.to_f : value
+      else value
+      end
+    end
+
     def extract_relations(instance)
       relations = {}
 

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

data/lib/archsight/requirements.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Archsight
+  # The requirements of a selection of resources, as the "Requirements" table of an instance page
+  # shows them, merged over all resources of the selection: one entry per MotivationRequirement, with the status the
+  # resources give it (`realizes` = implemented, `partiallyRealizes` = partial, `plans` = planned).
+  #
+  #   Requirements.collect(db, of: 'ApplicationService: name =~ "Backup"', priority: ["must"])
+  #   # => [{ name: "Requirement:X", status: "partial", priority: "must", story: "...",
+  #   #       by: [{ kind: "ApplicationService", name: "Backup", status: "partial" }] }]
+  module Requirements
+    # Relation verb -> status, best first
+    STATUSES = { "realizes" => "implemented", "partiallyRealizes" => "partial", "plans" => "planned" }.freeze
+    PRIORITIES = %w[must should may].freeze
+    RELATION = :motivationRequirements
+
+    module_function
+
+    # @param of [String] query selecting the resources whose requirements are listed
+    # @param priority [Array<String>] only these priorities (empty: all)
+    # @param status [Array<String>] only requirements with one of these statuses (empty: all)
+    # @return [Array<Hash>] sorted by priority (must, should, may, none), then name
+    # @raise [Archsight::Query::QueryError] if `of` is not a valid query
+    def collect(database, of:, priority: [], status: [])
+      found = {}
+      Archsight::Query.parse(of).filter(database).each do |resource|
+        STATUSES.each do |verb, resource_status|
+          resource.relations(verb, RELATION).each do |requirement|
+            entry = (found[requirement.name] ||= { requirement: requirement, by: [] })
+            entry[:by] << { kind: resource.class.name.split("::").last, name: resource.name, status: resource_status }
+          end
+        end
+      end
+
+      entries = found.values.map { |entry| entry(entry[:requirement], entry[:by]) }
+      entries = entries.select { |e| priority.include?(e[:priority]) } unless priority.empty?
+      entries = entries.select { |e| status.include?(e[:status]) } unless status.empty?
+      entries.sort_by { |e| [PRIORITIES.index(e[:priority]) || PRIORITIES.size, e[:name]] }
+    end
+
+    # The requirements of a ```requirements block as a plain table (see ViewTable), for places that cannot run the frontend.
+    # "Realized by" is only there when more than one resource contributes.
+    # @param spec [Hash] the parsed block: `{ title:, of:, priority:, status: }` (Helpers::RequirementsBlocks.parse)
+    # @raise [Archsight::Query::QueryError]
+    def table(database, spec)
+      entries = collect(database, of: spec[:of], priority: spec[:priority], status: spec[:status])
+      with_by = entries.flat_map { |e| e[:by].map { |b| [b[:kind], b[:name]] } }.uniq.length > 1
+      cell = ViewTable::Cell
+      rows = entries.first(ViewTable::LIMIT).map do |e|
+        row = [cell.new(text: e[:status], as: :status), cell.new(text: e[:name]), cell.new(text: e[:priority].to_s, as: :priority),
+               cell.new(text: e[:story].to_s, as: :markdown)]
+        row << cell.new(text: e[:by].map { |b| b[:name] }.join("\n")) if with_by
+        row
+      end
+      ViewTable::Table.new(title: spec[:title].to_s.empty? ? "Requirements" : spec[:title],
+                           columns: ["Status", "Name", "Priority", "Story", ("Realized by" if with_by)].compact, rows: rows, total: entries.length)
+    end
+
+    def entry(requirement, by)
+      by = by.sort_by { |b| [STATUSES.values.index(b[:status]), b[:kind], b[:name]] }
+      {
+        name: requirement.name,
+        status: by.first[:status],
+        priority: requirement.annotations["requirement/priority"],
+        story: requirement.annotations["requirement/story"],
+        by: by
+      }
+    end
+  end
+end

data/lib/archsight/resources/analysis.rb

@@ -45,7 +45,8 @@ class Archsight::Resources::Analysis < Archsight::Resources::Base
   annotation "analysis/handler",
              description: "Script handler type (only 'ruby' currently supported)",
              title: "Handler",
-             enum: %w[ruby]
+             enum: %w[ruby],
+             summary: true
 
   # Script content
   annotation "analysis/script",

data/lib/archsight/resources/application_component.rb

@@ -141,13 +141,15 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   annotation "deployment/cluster",
              description: "Target cluster name",
              title: "Cluster",
-             filter: :word
+             filter: :word,
+             summary: true
 
   # Computed Annotations
   computed_annotation "repository/artifacts/total",
                       title: "Total Git Repositories",
                       description: "Number of related git repositories",
-                      type: Integer do
+                      type: Integer,
+                      summary: true do
     count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 
@@ -190,7 +192,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
 
   computed_annotation "scc/language",
                       title: "Primary Language",
-                      list: true,
+                      summary: true,
                       description: "Programming language with most lines of code across related artifacts",
                       filter: :word,
                       sidebar: true do
@@ -344,4 +346,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/application_interface.rb

@@ -34,17 +34,19 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
   annotation "api/responsiveness",
              description: "API 99th percentile responsiveness target",
              title: "API Responsiveness (99p)",
-             enum: %w[10ms 100ms 1000ms 2s 5s 10s unresponsive]
+             enum: %w[10ms 100ms 1000ms 2s 5s 10s unresponsive],
+             summary: true
   annotation "api/authenticationMethod",
              description: "API authentication method",
              title: "API Authentication Method",
-             enum: ["none", "hard coded", "token", "oidc"]
+             enum: ["none", "hard coded", "token", "oidc"],
+             summary: true
   annotation "api/authorization",
              description: "API authorization mechanism",
              title: "API Authorization",
              enum: ["none", "hard coded", "pbac", "abac", "rbac"]
 
   relation :servedBy, :technologyComponents, :TechnologyInterface
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :serves, :dataObjects, :DataObject
 end

data/lib/archsight/resources/application_service.rb

@@ -34,13 +34,14 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
              description: "Service plane classification (control manages resources, data handles traffic)",
              title: "Service Plane",
              enum: %w[control data],
-             list: true
+             summary: true
 
   # Computed Annotations
   computed_annotation "repository/artifacts/total",
                       title: "Total Git Repositories",
                       description: "Number of related git repositories",
-                      type: Integer do
+                      type: Integer,
+                      summary: true do
     count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 
@@ -83,7 +84,7 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
 
   computed_annotation "scc/languages",
                       title: "Primary Languages",
-                      list: true,
+                      summary: true,
                       description: "Top 4 programming languages by lines of code across related artifacts",
                       filter: :list,
                       sidebar: true do
@@ -213,10 +214,10 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   relation :realizedThrough, :applicationComponents, :ApplicationComponent
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
-  relation :partiallyRealizes, :businessRequirements, :BusinessRequirement
-  relation :plans, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
   relation :realizes, :dataObjects, :DataObject
   relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/base.rb

@@ -15,21 +15,46 @@ module Archsight
       end
 
       def self.relation(verb, kind, klass_name)
-        @relations ||= [] #: Array[[Symbol, Symbol, String]]
-        @relations << [verb, kind, klass_name]
+        @declared_relations ||= [] #: Array[[Symbol, Symbol, String]]
+        @declared_relations << [verb, kind, klass_name]
+        @relations = nil
       end
 
+      # The relations a resource of this kind may be written with in a file (`spec`)
+      def self.declared_relations
+        @declared_relations || []
+      end
+
+      # Every relation a resource of this kind can have: the declared ones and the derived ones (`mentions`,
+      # `depicts`, see Archsight::References). Everything that follows relations (queries, graphs, impact analysis)
+      # uses this; what lets a user write or choose relations uses declared_relations.
       def self.relations
-        @relations || []
+        @relations ||= (declared_relations + Archsight::Resources::DERIVED_RELATIONS).freeze
       end
 
+      # A kind may mark at most this many annotations as summary (see Base.annotation)
+      MAX_SUMMARY_ANNOTATIONS = 3
+
       # 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, list: false, editor: true, validator: nil)
-        @annotations ||= [] #: Array[Archsight::Annotations::Annotation]
+                          type: nil, summary: false, editor: true, validator: nil)
         options = { description: description, filter: filter, title: title, format: format, enum: enum,
-                    sidebar: sidebar, type: type, list: list, editor: editor, validator: validator }
-        @annotations << Archsight::Annotations::Annotation.new(key, options)
+                    sidebar: sidebar, type: type, summary: summary, editor: editor, validator: validator }
+        register_annotation(Archsight::Annotations::Annotation.new(key, options))
+      end
+
+      # Append an annotation definition, enforcing the limit of summary annotations per kind.
+      # Annotations of included modules (include_annotations) come through here as well.
+      def self.register_annotation(annotation)
+        @annotations ||= [] #: Array[Archsight::Annotations::Annotation]
+        if annotation.summary? && @annotations.count(&:summary?) >= MAX_SUMMARY_ANNOTATIONS
+          raise ArgumentError,
+                "#{name}: at most #{MAX_SUMMARY_ANNOTATIONS} annotations can be summary attributes, " \
+                "cannot add #{annotation.key}"
+        end
+
+        @annotations << annotation
       end
 
       # Get all annotation definitions
@@ -48,19 +73,18 @@ module Archsight
       # @param enum [Array, nil] Allowed values
       # @param sidebar [Boolean] Show in sidebar (default false for computed)
       # @param type [Class, nil] Type for value coercion (Integer, Float, String)
-      # @param list [Boolean] Whether values are lists (default false)
+      # @param summary [Boolean] Return the value with every search hit of this kind (default false, max 3 per kind)
       # @yield Block that computes the annotation value, evaluated in Evaluator context
       def self.computed_annotation(key, description: nil, filter: nil, title: nil, format: nil, enum: nil,
-                                   sidebar: false, type: nil, list: false, editor: true, &)
+                                   sidebar: false, type: nil, summary: false, editor: true, &)
         require_relative "../annotations/computed"
         @computed_annotations ||= [] #: Array[Archsight::Annotations::Computed]
         @computed_annotations << Archsight::Annotations::Computed.new(key, description: description, type: type, &)
 
         # Also register as a regular annotation so it passes validation and is recognized
-        @annotations ||= [] #: Array[Archsight::Annotations::Annotation]
         options = { description: description, filter: filter, title: title, format: format, enum: enum,
-                    sidebar: sidebar, type: type, list: list, editor: editor }
-        @annotations << Archsight::Annotations::Annotation.new(key, options)
+                    sidebar: sidebar, type: type, summary: summary, editor: editor }
+        register_annotation(Archsight::Annotations::Annotation.new(key, options))
       end
 
       # Get all computed annotation definitions
@@ -83,9 +107,9 @@ module Archsight
         annotations.select(&:filterable?).reject(&:pattern?)
       end
 
-      # Get annotations marked for list display
-      def self.list_annotations
-        annotations.select(&:list_display?).reject(&:pattern?)
+      # Get the annotations marked as summary attributes (returned with search hits)
+      def self.summary_annotations
+        annotations.select(&:summary?).reject(&:pattern?)
       end
 
       def self.annotation_title(key)
@@ -96,6 +120,17 @@ module Archsight
         annotation_matching(key)&.format
       end
 
+      # The formats this kind defines for the given annotation keys, `{ "evidence/gaps" => "markdown" }` (keys without
+      # a format are left out). The frontend shows each value accordingly.
+      def self.annotation_formats(keys)
+        formats = {} #: Hash[String, String]
+        keys.each do |key|
+          format = annotation_format(key)
+          formats[key] = format.to_s if format
+        end
+        formats
+      end
+
       def self.annotation_enum(key)
         annotation_matching(key)&.enum
       end
@@ -216,17 +251,32 @@ module Archsight
       end
 
       def verb_allowed?(verb)
-        self.class.relations.any? { |v, _, _| v.to_s == verb.to_s }
+        self.class.declared_relations.any? { |v, _, _| v.to_s == verb.to_s }
       end
 
       def verb_kind_allowed?(verb, kind)
-        self.class.relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
+        self.class.declared_relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
       end
 
       def relations(verb, kind)
         (spec[verb.to_s] || {})[kind.to_s] || []
       end
 
+      # Records a relation that is derived from this resource's text or diagram, not written in its file: the target
+      # goes into `spec` where the relations of this verb are read (so queries and graphs see it like any other) and
+      # learns about this resource as one that refers to it.
+      def add_derived_relation(verb, target)
+        key = Archsight::Resources::DERIVED_KEY.to_s
+        spec_root = (@raw["spec"] ||= {}) #: Hash[String, untyped]
+        by_key = (spec_root[verb.to_s] ||= {}) #: Hash[String, Array[Base]]
+        by_key[key] ||= [] #: Array[Base]
+        targets = by_key.fetch(key)
+        return if targets.any? { |known| known.equal?(target) }
+
+        targets << target
+        target.referenced_by(self, verb.to_sym)
+      end
+
       def set_relations(verb, kind, rels)
         spec[verb.to_s][kind.to_s] = rels
         rels.each { |rel| rel.referenced_by(self, verb) }