archsight 0.3.0 → 0.3.2

data/lib/archsight/annotations/relation_resolver.rb

@@ -11,12 +11,101 @@
 # - 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
 
-  def initialize(instance, database)
+  # TraversalCache holds what can be shared between all resolvers of one computation run: the unfiltered
+  # transitive neighbourhood of an instance (relations are fixed once the database is verified), parsed filter
+  # queries, one query evaluator and the short kind names. Filter results are never cached because they may
+  # depend on computed annotations that are set while the run progresses.
+  class TraversalCache
+    def initialize(database)
+      @database = database
+      @reach = {}
+      @queries = {}
+      @kind_names = {}.compare_by_identity
+    end
+
+    # Short kind name of a resource class ("ApplicationComponent")
+    def kind_name(klass)
+      @kind_names[klass] ||= klass.name.split("::").last
+    end
+
+    # Parsed query for a selector string
+    def query(selector)
+      @queries[selector] ||= begin
+        require_relative "../query/lexer"
+        require_relative "../query/parser"
+        Archsight::Query::Parser.new(Archsight::Query::Lexer.new(selector).tokenize).parse
+      end
+    end
+
+    def evaluator
+      @evaluator ||= begin
+        require_relative "../query/evaluator"
+        Archsight::Query::Evaluator.new(@database)
+      end
+    end
+
+    # All instances reachable from `start` within max_depth hops (direction :outgoing or :incoming),
+    # each once, in breadth-first order. `start` itself is included when a cycle leads back to it.
+    def reachable(start, direction, max_depth)
+      by_instance = (@reach[[direction, max_depth]] ||= {}.compare_by_identity)
+      by_instance[start] ||= walk(start, direction, max_depth)
+    end
+
+    private
+
+    def walk(start, direction, max_depth)
+      results = []
+      listed = {}.compare_by_identity
+      expanded = { start => true }.compare_by_identity
+      frontier = [start]
+      depth = 0
+      while depth < max_depth && !frontier.empty?
+        following = []
+        frontier.each do |node|
+          neighbours(node, direction).each do |other|
+            unless listed.key?(other)
+              listed[other] = true
+              results << other
+            end
+            next if expanded.key?(other)
+
+            expanded[other] = true
+            following << other
+          end
+        end
+        frontier = following
+        depth += 1
+      end
+      results
+    end
+
+    def neighbours(inst, direction)
+      if direction == :outgoing
+        inst.class.declared_relations.flat_map { |verb, kind_name, _klass_name| inst.relations(verb, kind_name) }
+      else
+        Archsight::Annotations::ComputedRelationResolver.modelled_references(inst)
+      end
+    end
+  end
+
+  # @param cache [TraversalCache, nil] shared per computation run; a private one is created when omitted
+  def initialize(instance, database, cache = nil)
     @instance = instance
     @database = database
-    @query_cache = {}
+    @cache = cache || TraversalCache.new(database)
   end
 
   # Get direct outgoing relations (-> Kind)
@@ -25,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)
@@ -41,11 +130,7 @@ class Archsight::Annotations::ComputedRelationResolver
   # @param max_depth [Integer] Maximum traversal depth (default 10)
   # @return [Array] Array of transitively related instances
   def outgoing_transitive(filter = nil, max_depth: MAX_DEPTH)
-    visited = Set.new
-    results = []
-
-    collect_transitive_outgoing(@instance, filter, visited, 0, max_depth, results)
-    results.uniq
+    filtered(@cache.reachable(@instance, :outgoing, max_depth), filter)
   end
 
   # Get direct incoming relations (<- Kind)
@@ -53,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
@@ -70,15 +153,23 @@ class Archsight::Annotations::ComputedRelationResolver
   # @param max_depth [Integer] Maximum traversal depth (default 10)
   # @return [Array] Array of instances that transitively reference this one
   def incoming_transitive(filter = nil, max_depth: MAX_DEPTH)
-    visited = Set.new
-    results = []
-
-    collect_transitive_incoming(@instance, filter, visited, 0, max_depth, results)
-    results.uniq
+    filtered(@cache.reachable(@instance, :incoming, max_depth), filter)
   end
 
   private
 
+  def filtered(instances, filter)
+    return instances.dup if filter.nil?
+
+    if filter.is_a?(Symbol)
+      kind = filter.to_s
+      instances.select { |inst| @cache.kind_name(inst.class) == kind }
+    else
+      query_node = @cache.query(filter)
+      instances.select { |inst| @cache.evaluator.matches?(query_node, inst) }
+    end
+  end
+
   # Check if an instance matches the given filter
   # @param instance [Object] The instance to check
   # @param filter [Symbol, String, nil] Kind filter or query selector
@@ -86,75 +177,10 @@ class Archsight::Annotations::ComputedRelationResolver
   def matches_filter?(instance, filter)
     return true if filter.nil?
 
-    instance_kind = instance.class.name.split("::").last
-
     if filter.is_a?(Symbol)
-      # Simple kind check
-      instance_kind == filter.to_s
+      @cache.kind_name(instance.class) == filter.to_s
     else
-      # Query selector - parse and evaluate
-      query_node = parse_query(filter)
-      evaluator.matches?(query_node, instance)
-    end
-  end
-
-  # Parse a query string (with caching)
-  def parse_query(query_string)
-    @query_cache[query_string] ||= begin
-      require_relative "../query/lexer"
-      require_relative "../query/parser"
-      tokens = Archsight::Query::Lexer.new(query_string).tokenize
-      Archsight::Query::Parser.new(tokens).parse
-    end
-  end
-
-  # Get or create the query evaluator
-  def evaluator
-    @evaluator ||= begin
-      require_relative "../query/evaluator"
-      Archsight::Query::Evaluator.new(@database)
-    end
-  end
-
-  # Recursively collect transitive outgoing relations
-  def collect_transitive_outgoing(inst, filter, visited, depth, max_depth, results)
-    return if depth >= max_depth
-
-    key = "#{inst.class}/#{inst.name}"
-    return if visited.include?(key)
-
-    visited.add(key)
-
-    inst.class.relations.each do |verb, kind_name, _klass_name|
-      rels = inst.relations(verb, kind_name)
-      rels.each do |rel|
-        # Add to results if matches filter (or no filter)
-        results << rel if matches_filter?(rel, filter)
-
-        # Continue traversal (regardless of whether this matched)
-        collect_transitive_outgoing(rel, filter, visited.dup, depth + 1, max_depth, results)
-      end
-    end
-  end
-
-  # Recursively collect transitive incoming relations
-  def collect_transitive_incoming(inst, filter, visited, depth, max_depth, results)
-    return if depth >= max_depth
-
-    key = "#{inst.class}/#{inst.name}"
-    return if visited.include?(key)
-
-    visited.add(key)
-
-    refs = inst.references || []
-    # Extract instances from reference hashes
-    instances = refs.map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }.compact
-    instances.each do |ref|
-      # Add to results if matches filter (or no filter)
-      results << ref if matches_filter?(ref, filter)
-
-      # Continue traversal (regardless of whether this matched)
-      collect_transitive_incoming(ref, filter, visited.dup, depth + 1, max_depth, results)
+      @cache.evaluator.matches?(@cache.query(filter), instance)
     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) }
@@ -282,7 +288,7 @@ module Archsight
     desc "export [PAGE...]", "Export wiki pages to another system"
     long_desc <<~DESC
       Publishes wiki pages to the system named by --to. With no PAGE, every page that links to a target
-      page (for confluence: `confluence: <page URL>` in its frontmatter) is exported.
+      page (for confluence: `confluence: <page URL>` in its frontmatter) is exported. --tag TAG limits the export to pages carrying one of the given tags.
 
       confluence: a page is only overwritten when Confluence still holds what the last export wrote. Pages
       never exported before, or edited in Confluence since, are reported as blocked and not exported until
@@ -295,6 +301,7 @@ module Archsight
     option :force, type: :boolean, default: false, desc: "Overwrite pages that were edited in the target since the last export"
     option :lock, type: :boolean, default: true, desc: "Restrict editing of exported pages to the exporting user (--no-lock to skip)"
     option :dry_run, type: :boolean, default: false, desc: "Show what would be exported without writing anything"
+    option :tag, type: :array, default: [], desc: "Only export pages with at least one of these tags (repeatable, case-insensitive)"
     option :config, type: :string, desc: "Configuration file (default: ARCHSIGHT_CONFIG or ~/.config/archsight/archsight.yaml)"
     option :drawio, type: :boolean, desc: "The target has the draw.io app: export diagrams as draw.io macros, else as images (default: `confluence.drawio` of the configuration)"
     def export(*names)
@@ -317,7 +324,7 @@ module Archsight
       end
       exporter = Archsight::Export.exporter_for(options[:to]).new(
         database: db, resources_dir: Archsight.resources_dir, force: options[:force], lock: options[:lock],
-        dry_run: options[:dry_run], settings: settings, drawio: options[:drawio]
+        dry_run: options[:dry_run], settings: settings, drawio: options[:drawio], tags: options[:tag]
       )
       results = exporter.run(names)
       print_export_results(results)

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,11 +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)
-      inst.name || raise("metadata name of #{kind} not present")
+      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|
@@ -131,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
@@ -185,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::/, "")
@@ -196,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

@@ -104,7 +104,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)
 
@@ -142,19 +142,23 @@ module Archsight
         rows = ["| Annotation | Description | Values |", "|------------|-------------|--------|"]
         annotations.each do |a|
           values = format_values(a)
-          rows << "| `#{a.key}` | #{a.description || "-"} | #{values} |"
+          description = a.summary? ? "#{a.description || "-"} _(summary: shown with search hits)_" : (a.description || "-")
+          rows << "| `#{a.key}` | #{description} | #{values} |"
         end
         rows.join("\n")
       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/export/confluence/exporter.rb

@@ -31,8 +31,9 @@ module Archsight
         # @param database [Archsight::Database]
         # @param settings [Credentials::Settings, nil] token and draw.io support; default: Credentials.load
         # @param drawio [Boolean, nil] overrides the settings' draw.io flag
+        # @param tags [Array<String>] only export pages that have at least one of these `page/tags` (case-insensitive)
         # @param client_factory [#call, nil] `(base_url, token) -> Client`, for tests
-        def initialize(database:, resources_dir:, force: false, lock: true, dry_run: false, settings: nil, drawio: nil, client_factory: nil)
+        def initialize(database:, resources_dir:, force: false, lock: true, dry_run: false, settings: nil, drawio: nil, tags: [], client_factory: nil)
           @database = database
           @resources_dir = resources_dir
           @force = force
@@ -40,6 +41,7 @@ module Archsight
           @dry_run = dry_run
           @settings = settings
           @drawio = drawio
+          @tags = Array(tags).map { |t| t.to_s.strip.downcase }.reject(&:empty?)
           @client_factory = client_factory || ->(base, secret) { Client.new(base: base, token: secret) }
           @clients = {}
         end
@@ -55,17 +57,24 @@ module Archsight
         # @return [Array<Array(Page|String, Result|nil)>]
         def select(names)
           all = @database.instances_by_kind("Page")
-          return all.values.select { |p| link(p) }.sort_by(&:name).map { |p| [p, nil] } if names.empty?
+          return all.values.select { |p| link(p) && tagged?(p) }.sort_by(&:name).map { |p| [p, nil] } if names.empty?
 
           names.map do |name|
             page = all[name]
             if page.nil? then [name, Result.new(page: name, status: :failed, message: "no such page")]
             elsif link(page).nil? then [page, Result.new(page: name, status: :skipped, message: "no `confluence:` link in the frontmatter")]
+            elsif !tagged?(page) then [page, Result.new(page: name, status: :skipped, message: "has none of the tags #{@tags.join(", ")}")]
             else [page, nil]
             end
           end
         end
 
+        def tagged?(page)
+          return true if @tags.empty?
+
+          page.annotations["page/tags"].to_s.split(",").map { |t| t.strip.downcase }.intersect?(@tags)
+        end
+
         def link(page)
           value = page.annotations["page/confluence"].to_s.strip
           value.empty? ? nil : value