archsight 0.3.3 → 0.4.1

data/lib/archsight/linter.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require "kramdown"
+require_relative "markdown"
 require_relative "helpers"
+require_relative "linter/structure"
 
 module Archsight
   class Linter
@@ -10,9 +11,15 @@ module Archsight
 
     # 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
+    # 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].freeze
+    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
@@ -20,6 +27,7 @@ module Archsight
     end
 
     def validate
+      validate_imports
       @database.instances.each_value do |instances_hash|
         instances_hash.each_value do |instance|
           validate_instance_annotations(instance)
@@ -29,18 +37,72 @@ module Archsight
         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
@@ -86,25 +148,62 @@ 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
+      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)
-        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(" ")})"
+        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
+    # { 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 [] if CYCLE_EXEMPT_VERBS.include?(verb)
+            next [] unless yield(verb)
 
             instance.relations(verb, key).map { |target| { verb: verb, to: target } }
           end
@@ -201,18 +300,26 @@ 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")
 
       begin
-        Kramdown::Document.new(value, input: "GFM")
+        Archsight::Markdown.document(value)
       rescue StandardError => e
         @errors << "#{instance.path_ref}: Markdown syntax error in annotation '#{key}': #{e.message}"
       end

data/lib/archsight/markdown.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Archsight
+  # The one way markdown is parsed, for the web, the export, the linter and the analysis output alike. GFM, but a
+  # single newline inside a paragraph is a space, as in CommonMark and GitHub's rendering of `.md` files (the GFM
+  # parser of kramdown would make it a `<br />`, as GitHub does in comments). A line break is two trailing spaces,
+  # a trailing backslash or `<br>`.
+  module Markdown
+    OPTIONS = { input: "GFM", hard_wrap: false }.freeze
+
+    # Raw HTML whose text is kept as it is
+    VERBATIM = %w[pre code script style textarea].freeze
+
+    def self.document(text, **)
+      Kramdown::Document.new(text.to_s, **OPTIONS, **)
+    end
+
+    # The document without the newlines of the source in its text, for a target that keeps a newline instead of
+    # reading it as a space (Confluence): a soft line break becomes a space, the newline after a line break goes.
+    # Inline code over two lines is one line (as in CommonMark). Paragraphs, breaks and code blocks are unchanged.
+    def self.unwrapped(text, **)
+      document(text, **).tap { |doc| unwrap(doc.root) }
+    end
+
+    def self.unwrap(element)
+      element.children.each_with_index do |child, index|
+        if child.type == :text
+          previous = index.positive? ? element.children[index - 1] : nil
+          joined = child.value.gsub(/[ \t]*\r?\n[ \t]*/, " ")
+          child.value = line_break?(previous) ? joined.lstrip : joined
+        elsif child.type == :codespan
+          child.value = child.value.gsub(/\r?\n/, " ")
+        elsif !(child.type == :html_element && VERBATIM.include?(child.value))
+          unwrap(child)
+        end
+      end
+    end
+    private_class_method :unwrap
+
+    def self.line_break?(element)
+      element && (element.type == :br || (element.type == :html_element && element.value == "br"))
+    end
+    private_class_method :line_break?
+  end
+end

data/lib/archsight/openapi.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require_relative "resources"
+
+module Archsight
+  # The OpenAPI document of the REST API: the hand-written base (`web/api/openapi/spec.yaml`: the fixed endpoints such
+  # as pages, assets, search and the editor, with their prose, examples and error shapes) plus what the model knows and
+  # nobody should type twice: one schema per kind with its annotations (type, enum, description, default), its `spec`
+  # relations and its relations, the list of kinds, and the instance detail schema that is one of them. A new kind, a
+  # changed enum or another relation shows up in the documentation without touching the YAML.
+  #
+  #   Archsight::OpenAPI.document # => Hash, `.to_yaml` is what GET /api/v1/openapi.yaml serves
+  module OpenAPI
+    BASE = File.join(__dir__, "web", "api", "openapi", "spec.yaml")
+
+    # The operations that answer with the detail of one instance, whose kind the path names
+    DETAIL_PATHS = ["/api/v1/kinds/{kind}/instances/{name}", "/kinds/{kind}/instances/{name}.json"].freeze
+
+    # What an annotation of a type is in the JSON. The value is the one of the YAML file, so a number may also be its
+    # string ("100"); only a computed annotation is always a number. Everything else is a string.
+    TYPES = {
+      Integer => { "type" => %w[integer string] },
+      Float => { "type" => %w[number string] }
+    }.freeze
+
+    NAMES = { "type" => "array", "items" => { "type" => "string" } }.freeze
+
+    class << self
+      # @return [Hash] the complete document; built once, the model does not change while the server runs
+      def document
+        @document ||= build
+      end
+
+      # Forget the built document (the model was changed, in a test)
+      def reset!
+        @document = nil
+      end
+
+      # The name of the schema of a kind
+      def schema_name(kind) = "#{kind}Instance"
+
+      # The schema of one kind: the detail of an instance as GET /api/v1/kinds/{kind}/instances/{name} returns it
+      # @param kind [String] name of a kind
+      # @return [Hash]
+      def kind_schema(kind)
+        klass = Archsight::Resources[kind]
+        schema = {
+          "type" => "object",
+          "required" => %w[kind name metadata spec relations references],
+          "x-layer" => klass.layer,
+          "properties" => {
+            "kind" => { "type" => "string", "const" => kind },
+            "name" => { "type" => "string", "description" => "Name of the instance" },
+            "metadata" => { "type" => "object", "properties" => { "annotations" => annotations_schema(klass) } },
+            "annotation_formats" => { "type" => "object", "additionalProperties" => { "type" => "string" },
+                                      "description" => "How the UI shows each annotation that is set (markdown, link, tag_list, ...)" },
+            "annotation_links" => { "type" => "object", "additionalProperties" => true,
+                                    "description" => "Annotations whose value names resources, with the resources they resolve to" },
+            "spec" => spec_schema(klass),
+            "relations" => relations_schema(klass),
+            "references" => references_schema,
+            "diagram" => { "type" => %w[string null], "description" => "The `architecture/diagram` annotation as inline SVG" }
+          }
+        }
+        schema["description"] = klass.description.strip if klass.description
+        schema
+      end
+
+      private
+
+      def build
+        document = YAML.safe_load_file(BASE, permitted_classes: [], aliases: true)
+        kinds = Archsight::Resources.resource_classes.keys.sort
+        schemas = document.fetch("components").fetch("schemas")
+        add_schemas(schemas, kinds)
+        document.dig("components", "parameters", "kind")["schema"] = { "$ref" => "#/components/schemas/KindName" }
+        DETAIL_PATHS.each { |path| use_detail_schema(document.fetch("paths").fetch(path)) }
+        # the schemas share small hashes: a copy of each keeps YAML from writing anchors and aliases for them
+        JSON.parse(JSON.generate(document))
+      end
+
+      def add_schemas(schemas, kinds)
+        kinds.each do |kind|
+          name = schema_name(kind)
+          raise ArgumentError, "OpenAPI: the schema #{name} of #{kind} clashes with a schema of the base spec" if schemas.key?(name)
+
+          schemas[name] = kind_schema(kind)
+        end
+        schemas["KindName"] = {
+          "type" => "string", "enum" => kinds,
+          "description" => "Name of a resource kind. A kind that was renamed is still accepted under its old name."
+        }
+        schemas["InstanceDetail"] = {
+          "description" => "An instance with its relations and references: the schema depends on the kind",
+          "oneOf" => kinds.map { |kind| { "$ref" => "#/components/schemas/#{schema_name(kind)}" } },
+          "discriminator" => { "propertyName" => "kind", "mapping" => kinds.to_h { |kind| [kind, "#/components/schemas/#{schema_name(kind)}"] } }
+        }
+      end
+
+      def use_detail_schema(path_item)
+        path_item.dig("get", "responses", "200", "content", "application/json")["schema"] = { "$ref" => "#/components/schemas/InstanceDetail" }
+      end
+
+      # The annotations of the kind that are set; every annotation is optional. Other annotations are allowed.
+      def annotations_schema(klass)
+        fixed, patterns = klass.annotations.partition { |annotation| !annotation.pattern? }
+        schema = {
+          "type" => "object", "additionalProperties" => true,
+          "properties" => fixed.to_h { |annotation| [annotation.key, annotation_schema(annotation)] }
+        }
+        schema["patternProperties"] = patterns.to_h { |annotation| [pattern_of(annotation.key), annotation_schema(annotation)] } unless patterns.empty?
+        schema
+      end
+
+      def annotation_schema(annotation)
+        schema = (TYPES[annotation.type] || { "type" => "string" }).dup
+        description = annotation.description.to_s.strip
+        description = "#{description}\n\nRendered to HTML in the response." if annotation.format == :markdown && !description.empty?
+        schema["description"] = description unless description.empty?
+        if annotation.enum && annotation.list?
+          # a list is one string of comma separated values, each of them one of the enum
+          schema["description"] = "#{description}\n\nComma separated list of: #{annotation.enum.join(", ")}.".strip
+          schema["x-items-enum"] = annotation.enum
+        elsif annotation.enum
+          schema["enum"] = annotation.enum
+        end
+        schema["default"] = annotation.default unless annotation.default.nil?
+        schema["deprecated"] = true if annotation.deprecated
+        schema
+      end
+
+      # `link/*` -> a regular expression for the keys it matches
+      def pattern_of(key) = "^#{Regexp.escape(key).gsub('\*', ".+")}$"
+
+      # What the file says: spec.<verb>.<key>: [names]
+      def spec_schema(klass)
+        properties = {}
+        klass.declared_relations.each do |verb, key, target|
+          verb_schema = (properties[verb.to_s] ||= { "type" => "object", "properties" => {} })
+          verb_schema["properties"][key.to_s] = NAMES.merge("description" => "Names of #{target} resources")
+        end
+        { "type" => "object", "additionalProperties" => true, "properties" => properties,
+          "description" => "The relations as written in the resource: verb, then the kind's collection, then the names" }
+      end
+
+      # The outgoing relations that exist: verb, then the kind of the target, then the names
+      def relations_schema(klass)
+        properties = {}
+        klass.relations.each do |verb, _key, target|
+          verb_schema = (properties[verb.to_s] ||= { "type" => "object" })
+          if Archsight::Resources::DERIVED_VERBS.include?(verb)
+            verb_schema["additionalProperties"] = NAMES # targets of any kind, grouped by the kind they are
+          else
+            (verb_schema["properties"] ||= {})[target.to_s] = NAMES
+          end
+        end
+        { "type" => "object", "additionalProperties" => false, "properties" => properties,
+          "description" => "Outgoing relations that have targets, grouped by verb and the kind of the target" }
+      end
+
+      def references_schema
+        { "type" => "object", "additionalProperties" => { "type" => "object", "additionalProperties" => NAMES },
+          "description" => "Incoming relations grouped by the kind of the source and the verb" }
+      end
+    end
+  end
+end

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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "markdown"
 
 module Archsight
   # PageTree builds the sidebar tree, breadcrumbs and tables of contents for Page resources
@@ -63,7 +62,7 @@ module Archsight
 
     # Flat table of contents [{level:, id:, text:}] of a markdown body
     def self.toc(markdown)
-      doc = Kramdown::Document.new(markdown.to_s, input: "GFM")
+      doc = Archsight::Markdown.document(markdown)
       entries = [] #: Array[Hash[String, untyped]]
       collect_toc(doc.to_toc, entries)
       entries

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

data/lib/archsight/query.rb

@@ -52,7 +52,7 @@ module Archsight
       def parse(source)
         lexer = Lexer.new(source)
         tokens = lexer.tokenize
-        parser = Parser.new(tokens)
+        parser = Parser.new(tokens, source: source)
         parser.parse
       rescue LexerError, ParseError, InvalidRegexError => e
         # Re-raise with source context

data/lib/archsight/references.rb

@@ -32,7 +32,7 @@ module Archsight
       end
     end
 
-    # The resources a markdown text mentions with `[[...]]` links and `![[View/...]]` embeds, outside code.
+    # The resources a markdown text mentions with `[[...]]` links and `![[Kind/...]]` embeds, outside code.
     # @return [Array<Base>]
     def mentions(markdown, finder)
       visible = markdown.to_s.gsub(FENCE, "").gsub(INLINE_CODE, "")
@@ -111,10 +111,10 @@ module Archsight
         @links.exact_target_for(target)
       end
 
-      # An `![[Kind/Name]]` embed: only views and analyses can be embedded
+      # An `![[Kind/Name]]` embed: any resource but a page
       def embed(reference)
         kind = reference.split("/", 2).first
-        return unless Helpers::Embeds::KINDS.include?(kind)
+        return unless Helpers::Embeds.embeddable_kind?(kind)
 
         reference(reference)
       end