archsight 0.3.2 → 0.4.0

data/lib/archsight/linter/structure.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Archsight
+  class Linter
+    # Structural checks over the declared relations, the rules of "Choosing the Kind" and "Choosing the Kind:
+    # Infrastructure" in the modeling guide. All findings are warnings: they point at modeling decisions to review and
+    # have legitimate exceptions (internal services, capabilities that no product carries yet).
+    class Structure
+      # Network types that run over another network and need one that serves them
+      OVERLAY_TYPES = %w[overlay vpn].freeze
+      NETWORK_DEVICE_TYPES = %w[switch router].freeze
+
+      def initialize(database)
+        @database = database
+      end
+
+      # Findings in a stable order, each starting with the path reference of the resource
+      def warnings
+        [
+          component_in_several_services,
+          artifact_in_several_components,
+          service_with_same_named_component,
+          product_without_service,
+          service_reached_from_nothing,
+          capability_without_product,
+          generated_component_in_several_repositories,
+          link_not_between_two_facilities,
+          overlay_without_underlay,
+          facility_without_location,
+          equipment_without_facility,
+          device_without_facility,
+          device_connected_to_itself,
+          network_device_realizing_no_network,
+          device_served_apart_from_its_equipment
+        ].flatten.sort
+      end
+
+      private
+
+      def instances(kind)
+        @database.instances_by_kind(kind).values
+      end
+
+      def targets(instance, verb, key)
+        instance.relations(verb, key)
+      end
+
+      def warning(instance, message)
+        "#{instance.path_ref}: #{instance.klass} '#{instance.name}' #{message}"
+      end
+
+      def names(list)
+        list.map { |item| "'#{item.name}'" }.join(", ")
+      end
+
+      # { target => [owners that list it under verb/key] } for the instances of `kind`
+      def owners_by_target(kind, verb, key)
+        owners = Hash.new { |hash, target| hash[target] = [] }
+        instances(kind).each { |owner| targets(owner, verb, key).each { |target| owners[target] << owner } }
+        owners
+      end
+
+      def component_in_several_services
+        shared("ApplicationService", :realizedThrough, :applicationComponents, "services")
+      end
+
+      def artifact_in_several_components
+        shared("ApplicationComponent", :realizedThrough, :technologyArtifacts, "components")
+      end
+
+      def shared(kind, verb, key, plural)
+        owners_by_target(kind, verb, key).filter_map do |target, owners|
+          next if owners.length < 2
+
+          warning(target, "is realized by #{owners.length} #{plural}: #{names(owners.sort_by(&:name))}")
+        end
+      end
+
+      def service_with_same_named_component
+        instances("ApplicationService").filter_map do |service|
+          components = targets(service, :realizedThrough, :applicationComponents)
+          next unless components.length == 1 && components.first.name == service.name
+
+          warning(service, "has one component with the same name")
+        end
+      end
+
+      def product_without_service
+        instances("BusinessProduct").filter_map do |product|
+          next unless targets(product, :servedBy, :applicationServices).empty?
+
+          warning(product, "is served by no ApplicationService")
+        end
+      end
+
+      # A service is reached when a product or process is served by it, directly or through services that depend on it
+      def service_reached_from_nothing
+        reached = reached_services
+        instances("ApplicationService").filter_map do |service|
+          next if reached.include?(service)
+
+          warning(service, "is not served to any product or process")
+        end
+      end
+
+      def reached_services
+        reached = []
+        queue = (instances("BusinessProduct") + instances("BusinessProcess")).flat_map { |item| targets(item, :servedBy, :applicationServices) }
+        until queue.empty?
+          service = queue.shift
+          next if reached.include?(service)
+
+          reached << service
+          queue.concat(targets(service, :dependsOn, :applicationServices))
+        end
+        reached
+      end
+
+      def capability_without_product
+        realized = owners_by_target("BusinessProduct", :realizes, :strategyCapabilities)
+        instances("StrategyCapability").filter_map do |capability|
+          next if realized.key?(capability)
+
+          warning(capability, "is realized by no product")
+        end
+      end
+
+      # A generated component realized by several repositories is two components merged into one: the repositories
+      # declare the same module path. A re-import gives each its own name (GoModuleParser#owned_component_name).
+      def generated_component_in_several_repositories
+        instances("ApplicationComponent").filter_map do |component|
+          next unless component.annotations.key?("generated/script")
+
+          repositories = targets(component, :realizedThrough, :technologyArtifacts).select { |a| a.name.start_with?("Repo:") }
+          next if repositories.length < 2
+
+          warning(component, "is generated from #{repositories.length} repositories with the same module path: " \
+                             "#{names(repositories.sort_by(&:name))}")
+        end
+      end
+
+      # ---- infrastructure
+
+      def link_not_between_two_facilities
+        instances("TechnologyEquipment").filter_map do |equipment|
+          next unless equipment.annotations["equipment/type"] == "link"
+
+          count = targets(equipment, :locatedAt, :technologyFacilities).length
+          next if count == 2
+
+          warning(equipment, "is a link located at #{count} #{count == 1 ? "facility" : "facilities"}, not 2")
+        end
+      end
+
+      def overlay_without_underlay
+        instances("TechnologyCommunicationNetwork").filter_map do |network|
+          type = network.annotations["network/type"]
+          next unless OVERLAY_TYPES.include?(type)
+          next unless targets(network, :servedBy, :technologyCommunicationNetworks).empty?
+
+          warning(network, "is #{type == "overlay" ? "an" : "a"} #{type} network served by no network")
+        end
+      end
+
+      # Only the outermost facility needs a location; nested halls inherit it from their campus
+      def facility_without_location
+        nested = owners_by_target("TechnologyFacility", :composedOf, :technologyFacilities)
+        instances("TechnologyFacility").filter_map do |facility|
+          next if nested.key?(facility) || targets(facility, :locatedAt, :locations).any?
+
+          warning(facility, "is located at no Location")
+        end
+      end
+
+      # TechnologyEquipment that is part of other equipment is placed through its whole, and a whole (a backbone) through its
+      # parts (the links)
+      def equipment_without_facility
+        parts = owners_by_target("TechnologyEquipment", :composedOf, :technologyEquipment)
+        instances("TechnologyEquipment").filter_map do |equipment|
+          next if parts.key?(equipment) || targets(equipment, :composedOf, :technologyEquipment).any?
+          next if targets(equipment, :locatedAt, :technologyFacilities).any?
+
+          warning(equipment, "is located at no TechnologyFacility")
+        end
+      end
+
+      # A device that is part of equipment (a rack) or of another device (a virtual chassis) is placed through its
+      # whole, and a chassis through its members
+      def device_without_facility
+        parts = owners_by_target("TechnologyDevice", :composedOf, :technologyDevices)
+        racked = owners_by_target("TechnologyEquipment", :composedOf, :technologyDevices)
+        instances("TechnologyDevice").filter_map do |device|
+          next if parts.key?(device) || racked.key?(device) || targets(device, :composedOf, :technologyDevices).any?
+          next if targets(device, :locatedAt, :technologyFacilities).any?
+
+          warning(device, "is located at no TechnologyFacility")
+        end
+      end
+
+      def device_connected_to_itself
+        instances("TechnologyDevice").filter_map do |device|
+          next unless targets(device, :connectedTo, :technologyDevices).include?(device)
+
+          warning(device, "is connectedTo itself")
+        end
+      end
+
+      # The members of a virtual chassis or stack realize the network through the chassis
+      def network_device_realizing_no_network
+        realized = owners_by_target("TechnologyCommunicationNetwork", :realizedBy, :technologyDevices)
+        members = owners_by_target("TechnologyDevice", :composedOf, :technologyDevices)
+        instances("TechnologyDevice").filter_map do |device|
+          type = device.annotations["device/type"]
+          next unless NETWORK_DEVICE_TYPES.include?(type)
+          next if realized.key?(device) || members.key?(device)
+
+          warning(device, "is a #{type} that realizes no TechnologyCommunicationNetwork")
+        end
+      end
+
+      # A device in a partition (equipment servedBy a team) serves that team; one that names another team has been
+      # handed over without moving it. A device that names no team is served through its equipment.
+      def device_served_apart_from_its_equipment
+        holders = owners_by_target("TechnologyEquipment", :composedOf, :technologyDevices)
+        instances("TechnologyDevice").filter_map do |device|
+          teams = targets(device, :servedBy, :businessActors)
+          equipment_teams = holders.fetch(device, []).flat_map { |equipment| targets(equipment, :servedBy, :businessActors) }
+          next if teams.empty? || equipment_teams.empty?
+
+          others = teams - equipment_teams
+          next if others.empty?
+
+          warning(device, "is servedBy #{names(others.sort_by(&:name))}, not by the team of its equipment " \
+                          "(#{names(equipment_teams.uniq.sort_by(&:name))})")
+        end
+      end
+    end
+  end
+end

data/lib/archsight/linter.rb

@@ -2,18 +2,32 @@
 
 require "kramdown"
 require_relative "helpers"
+require_relative "linter/structure"
 
 module Archsight
   class Linter
     # 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, and `connectedTo` because cabling between devices is cyclic by nature (a ring, a mesh, both ends of
+    # a cable). The derived relations (`mentions`, `depicts`) are sideways views and are not declared, so they
+    # never enter the check.
+    CYCLE_EXEMPT_VERBS = %i[dependsOn connectedTo].freeze
+
+    # Structure relations between elements of one kind (specialization, composition, aggregation). Each verb is
+    # checked on its own: a chain of one of them must not lead back to where it started. They stay out of the
+    # general check above so that a cycle is reported once.
+    HIERARCHY_VERBS = %i[specializes composedOf aggregates].freeze
+
     def initialize(database)
       @database = database
       @errors = []
     end
 
     def validate
+      validate_imports
       @database.instances.each_value do |instances_hash|
         instances_hash.each_value do |instance|
           validate_instance_annotations(instance)
@@ -22,18 +36,73 @@ module Archsight
           validate_menu(instance) if instance.klass == "PageMenu"
         end
       end
+      validate_relation_cycles
+      validate_hierarchy_cycles
+      validate_unique_annotations
 
       @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.
+    # Things that still work but should be changed: renamed kinds and relation keys that the files still use, and
+    # annotations their kind marks `deprecated:`. They are not errors, so they do not make `archsight lint` fail.
     def warnings
-      @database.respond_to?(:deprecations) ? @database.deprecations.map(&:to_s) : []
+      renamed = @database.respond_to?(:deprecations) ? @database.deprecations.map(&:to_s) : []
+      renamed + deprecated_annotations
+    end
+
+    # Structural modeling checks (rules of "Choosing the Kind", see Linter::Structure). Warnings, never errors.
+    def structural_warnings
+      Structure.new(@database).warnings
     end
 
     private
 
+    # Each use of an annotation the kind marks `deprecated:`, with what to use instead
+    def deprecated_annotations
+      @database.instances.each_value.flat_map do |instances_hash|
+        instances_hash.each_value.flat_map do |instance|
+          instance.annotations.keys.filter_map do |key|
+            annotation = instance.class.annotation_matching(key)
+            "#{instance.path_ref}: #{instance.klass} '#{instance.name}' uses deprecated annotation '#{key}': #{annotation.deprecated}" if annotation&.deprecated?
+          end
+        end
+      end
+    end
+
+    # Imports: the handlers of the resources repository load (before the `import/handler` names are checked against
+    # the registry), and every `import/dependsOn` entry names an import or is a pattern
+    def validate_imports
+      return unless @database.respond_to?(:instances_by_kind)
+
+      imports = @database.instances_by_kind("Import")&.values || []
+      return if imports.empty?
+
+      require "archsight/import/handler_loader"
+      Archsight::Import::HandlerLoader.load(@database).each { |problem| @errors << problem.to_s }
+      names = imports.to_set(&:name)
+      imports.each do |import|
+        Archsight::Import.declared_dependencies(import).each do |entry|
+          next if Archsight::Import.pattern?(entry) || names.include?(entry)
+
+          @errors << "#{import.path_ref}: Import '#{import.name}' depends on unknown import '#{entry}'"
+        end
+      end
+      validate_command_outputs(imports)
+    end
+
+    # A command import replaces its whole output file on every run, so no other import may write to it
+    def validate_command_outputs(imports)
+      file_of = ->(import) { File.expand_path(Archsight::Import.output_path(import), "/") }
+      imports.select { |import| import.annotations["import/handler"] == "command" }.each do |command|
+        others = imports.reject { |import| import.equal?(command) }.select { |import| file_of.call(import) == file_of.call(command) }
+        next if others.empty?
+
+        @errors << "#{command.path_ref}: Import '#{command.name}' runs a command, which replaces its output file " \
+                   "#{Archsight::Import.output_path(command)}, but #{others.map { |o| "'#{o.name}'" }.join(", ")} " \
+                   "also write#{"s" if others.one?} to it; give it a file of its own"
+      end
+    end
+
     # Pages need exactly one menu and their [[links]] must resolve
     def validate_page(page)
       menus = page.references.map { |r| r[:instance] }.select { |i| i.klass == "PageMenu" }.uniq
@@ -79,6 +148,140 @@ module Archsight
       nil
     end
 
+    # The values of a unique annotation (aliases) must not be shared by two resources of a kind
+    def validate_unique_annotations
+      @database.instances.each do |klass, instances_hash|
+        next unless klass.respond_to?(:annotations)
+
+        klass.annotations.select(&:unique?).reject(&:pattern?).each do |annotation|
+          owners = {}
+          instances_hash.each_value { |instance| check_unique_values(annotation, instance, owners) }
+        end
+      end
+    end
+
+    def check_unique_values(annotation, instance, owners)
+      Array(annotation.value_for(instance)).each do |value|
+        owner = owners[value]
+        if owner.nil?
+          owners[value] = instance
+        elsif !owner.equal?(instance)
+          @errors << "#{instance.path_ref}: #{instance.klass} '#{instance.name}': #{annotation.key} '#{value}' " \
+                     "is already used by '#{owner.name}' (#{owner.path_ref})"
+        end
+      end
+    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 { |verb| !CYCLE_EXEMPT_VERBS.include?(verb) && !HIERARCHY_VERBS.include?(verb) }
+      report_cycles(graph) { |start, path| "#{start.path_ref}: #{start.klass} '#{start.name}' is part of a relation cycle (#{path})" }
+    end
+
+    # `specializes`, `composedOf` and `aggregates` (one chain per verb) must not lead back to where they started
+    def validate_hierarchy_cycles
+      HIERARCHY_VERBS.each do |hierarchy_verb|
+        graph = relation_graph { |verb| verb == hierarchy_verb }
+        report_cycles(graph) { |start, path| "#{start.path_ref}: #{start.klass} '#{start.name}' is part of a cycle of #{hierarchy_verb} relations (#{path})" }
+      end
+    end
+
+    # Adds one error per group of instances that reach each other; the block builds the message from the first
+    # instance of the group and the path of one concrete cycle
+    def report_cycles(graph)
+      strongly_connected_groups(graph).each do |group|
+        cycle = cycle_through(group.first, group, graph)
+        start = group.first
+        path = ([start.name] + cycle.map { |step| step[:to].name }).zip(cycle.map { |step| step[:verb] }).flat_map { |name, verb| [name, verb && "-#{verb}->"] }.compact
+        @errors << yield(start, path.join(" "))
+      end
+    end
+
+    # { instance => [{ verb:, to: }] } over the declared relations whose verb the block accepts
+    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 [] unless yield(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)
@@ -97,12 +300,20 @@ module Archsight
         next unless annotation.has_validation?
 
         # Validate value against annotation schema (type and enum constraints)
-        annotation.validate(value).each do |error|
-          @errors << "#{instance.path_ref}: Annotation '#{key}' #{error}"
-        end
+        errors = annotation.validate(value)
+        errors.each { |error| @errors << "#{instance.path_ref}: Annotation '#{key}' #{error}" }
+        validate_resource_reference(instance, key, value) if annotation.resource? && errors.empty?
       end
     end
 
+    # The resource a `Name` / `Kind/Name` annotation points to must exist; a bare `Name` means the same kind
+    def validate_resource_reference(instance, key, value)
+      return if Archsight::Helpers::ResourceResolver.new(@database).find_annotated(value, instance.klass).is_a?(Array)
+
+      hint = value.to_s.include?("/") ? "" : " (a name without Kind/ is a #{instance.klass}, use Kind/Name for another kind)"
+      @errors << "#{instance.path_ref}: Annotation '#{key}' resource '#{value}' not found#{hint}"
+    end
+
     def validate_markdown(instance, key, value)
       # Skip markdown validation for generated files
       return if instance.annotations.key?("generated/script")

data/lib/archsight/page_loader.rb

@@ -62,12 +62,23 @@ module Archsight
       meta.each do |key, value|
         next if value.nil?
 
-        result["page/#{key}"] = format_value(key, value)
+        if key == "links" && value.is_a?(Hash)
+          links(value).each { |name, url| result["link/#{name}"] = url }
+        else
+          result["page/#{key}"] = format_value(key, value)
+        end
       end
       result["page/content"] = body
       result
     end
 
+    # `links: { confluence: <url> }` of the frontmatter: one link/<name> annotation per entry
+    def links(mapping)
+      mapping.each_with_object({}) do |(name, url), result|
+        result[name.to_s] = url.to_s unless url.nil?
+      end
+    end
+
     def format_value(key, value)
       case value
       when Hash then value.map { |k, v| "#{k}: #{v.to_s.gsub(/\s*\n\s*/, " ")}" }.join("\n")

data/lib/archsight/query/evaluator.rb

@@ -307,17 +307,24 @@ class Archsight::Query::Evaluator
     query_values.include?(instance_kind)
   end
 
+  # The name of a resource and its aliases (architecture/aliases): the name shortcut finds a resource by either
+  def names_of(instance)
+    aliases = instance.respond_to?(:annotations) ? instance.annotations&.[]("architecture/aliases") : nil
+    [instance.name, *aliases.to_s.split(",").map(&:strip).reject(&:empty?)].compact
+  end
+
   def evaluate_name_condition(node, instance)
-    name = instance.name
-    return false unless name
+    return false unless instance.name
 
+    names = names_of(instance)
     case node.operator
     when "=="
-      name == node.value.value.to_s
+      names.include?(node.value.value.to_s)
     when "!="
-      name != node.value.value.to_s
+      names.none?(node.value.value.to_s)
     when "=~"
-      !!(name =~ build_regex_from_value(node.value))
+      regex = build_regex_from_value(node.value)
+      names.any? { |name| name.match?(regex) }
     else
       false
     end
@@ -328,7 +335,7 @@ class Archsight::Query::Evaluator
     return false unless name
 
     query_values = node.values.map { |v| v.value.to_s }
-    query_values.include?(name)
+    names_of(instance).intersect?(query_values)
   end
 
   # Outgoing relations: what does this resource point to?

data/lib/archsight/query/parser.rb

@@ -5,16 +5,21 @@ require_relative "ast"
 
 # Recursive descent parser for the architecture query language.
 class Archsight::Query::Parser
-  def initialize(tokens)
+  # Characters a resource name is made of, as the lexer reads an identifier
+  NAME_CHAR = %r{[a-zA-Z0-9_\-/.]}
+
+  # @param source [String, nil] the query text; with it, names that contain colons (`Archsight:CLI`, `ITGS:A001`)
+  #   are read as one name instead of a kind prefix and a condition
+  def initialize(tokens, source: nil)
     @tokens = tokens
+    @source = source
     @position = 0
   end
 
   def parse
     # Check for kind filter prefix: "Kind: expression"
     kind_filter = nil
-    # Check it's a valid Kind (starts with capital letter)
-    if current_token.type == :IDENTIFIER && peek_token&.type == :COLON && (current_token.value =~ /^[A-Z]/)
+    if kind_prefix?
       kind_filter = current_token.value
       advance # consume identifier
       advance # consume colon
@@ -256,8 +261,7 @@ class Archsight::Query::Parser
 
     # Parse inner query: optional kind filter + optional expression
     kind_filter = nil
-    # Check it's a valid Kind (starts with capital letter)
-    if current_token.type == :IDENTIFIER && peek_token&.type == :COLON && (current_token.value =~ /^[A-Z]/)
+    if kind_prefix?
       kind_filter = current_token.value
       advance # consume identifier
       advance # consume colon
@@ -395,8 +399,71 @@ class Archsight::Query::Parser
       Archsight::Query::AST::AnnotationExistsCondition.new(path)
     else
       # Bare identifier - treat as name =~ "identifier"
-      Archsight::Query::AST::NameCondition.new("=~", Archsight::Query::AST::StringValue.new(path))
+      Archsight::Query::AST::NameCondition.new("=~", Archsight::Query::AST::StringValue.new(glue_name(path)))
+    end
+  end
+
+  # Names contain colons (`Archsight:CLI`, `ITGS:A001`). A bare name written without spaces around its colons is
+  # one word: `ApplicationService:ITGS:A001` is the kind and the name `ITGS:A001`.
+  def glue_name(first)
+    name = first
+    while (word = word_after_colon)
+      name += ":#{word}"
+      advance # consume the colon
+      advance while current_token.type != :EOF && current_token.position < @colon_end
+    end
+    name
+  end
+
+  # The name word right after the current colon token, when the colon touches a name character on both sides
+  def word_after_colon
+    return nil unless @source && current_token.type == :COLON
+
+    colon = current_token.position
+    return nil unless colon.positive? && @source[colon - 1]&.match?(NAME_CHAR)
+
+    word = @source[(colon + 1)..].to_s[/\A#{NAME_CHAR}+/]
+    @colon_end = colon + 1 + word.length if word
+    word
+  end
+
+  # `Kind: expression` or `Kind:`. The prefix is a kind when it starts with a capital letter and the colon is followed
+  # by a space or nothing; `Name:Word` without a space, where the prefix is no kind, is a name with a colon
+  # (`ITGS:A001`) that the bare word search handles.
+  def kind_prefix?
+    return false unless current_token.type == :IDENTIFIER && peek_token&.type == :COLON && current_token.value =~ /^[A-Z]/
+    return true if known_kind?(current_token.value)
+
+    !colon_glued?
+  end
+
+  def known_kind?(name)
+    defined?(Archsight::Resources) && !Archsight::Resources[name].nil?
+  end
+
+  # Whether the current token starts a name with colons (`ITGS:A001`) that is a bare word, not the start of a
+  # condition: the colons touch name characters, and no operator or `?` follows the name
+  def colon_glued?
+    return false unless @source
+
+    stop = name_run_end(peek_token.position)
+    return false unless stop
+
+    following = @tokens.find { |token| token.position >= stop }
+    !(following && %i[EQ NEQ MATCH GT LT GTE LTE IN QUESTION].include?(following.type))
+  end
+
+  # Where `a:b:c` ends, starting at its first colon; nil when that colon does not touch a name character on both sides
+  def name_run_end(colon)
+    stop = nil
+    while @source[colon] == ":" && colon.positive? && @source[colon - 1].match?(NAME_CHAR)
+      word = @source[(colon + 1)..].to_s[/\A#{NAME_CHAR}+/]
+      break unless word
+
+      stop = colon + 1 + word.length
+      colon = stop
     end
+    stop
   end
 
   def parse_quoted_annotation_path