archsight 0.3.0 → 0.3.1

data/lib/archsight/linter.rb

@@ -107,6 +107,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 +163,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 +194,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/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/requirements.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Archsight
+  # The business requirements of a selection of resources, as the "Business Requirements" table of an instance page
+  # shows them, merged over all resources of the selection: one entry per BusinessRequirement, 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 = :businessRequirements
+
+    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? ? "Business 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

data/lib/archsight/resources/application_interface.rb

@@ -34,11 +34,13 @@ 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",

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

data/lib/archsight/resources/base.rb

@@ -23,13 +23,29 @@ module Archsight
         @relations || []
       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 +64,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 +98,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)

data/lib/archsight/resources/business_actor.rb

@@ -36,7 +36,8 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
              sidebar: false,
              filter: :word,
              format: :tag_word,
-             type: Archsight::Annotations::EmailRecipient
+             type: Archsight::Annotations::EmailRecipient,
+             summary: true
 
   annotation "team/members",
              description: 'Team members (format: "Name <email>" or "email")',
@@ -108,7 +109,7 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
   computed_annotation "team/size",
                       title: "Team Size",
                       description: "Number of team members (including sub-teams)",
-                      list: true,
+                      summary: true,
                       type: Integer do
     # Count members from this team
     members = @instance.annotations["team/members"]
@@ -147,7 +148,8 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
   computed_annotation "repository/artifacts/total",
                       title: "Maintained Repositories",
                       description: "Number of git repositories maintained by this team",
-                      type: Integer do
+                      type: Integer,
+                      summary: true do
     count(incoming_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 

data/lib/archsight/resources/business_product.rb

@@ -33,7 +33,8 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   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
 
@@ -110,7 +111,7 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   computed_annotation "activity/createdAt",
                       title: "Created",
                       description: "Earliest repository creation date across all related application services",
-                      list: true,
+                      summary: true,
                       type: Time do
     services = outgoing_transitive(:ApplicationService)
     next nil if services.empty?
@@ -170,7 +171,7 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   computed_annotation "activity/contributors/6m",
                       title: "Contributors (6 months)",
                       description: "Sum of unique contributors in the last 6 months across related services",
-                      list: true,
+                      summary: true,
                       type: Integer do
     services = outgoing_transitive(:ApplicationService)
     next nil if services.empty?

data/lib/archsight/resources/business_requirement.rb

@@ -32,20 +32,21 @@ class Archsight::Resources::BusinessRequirement < Archsight::Resources::Base
 
   annotation "requirement/type",
              description: "Type of requirement (business or legal)",
-             enum: %w[business legal compliance functional non-functional]
+             enum: %w[business legal compliance functional non-functional],
+             summary: true
 
   annotation "requirement/reference",
              description: "Regulatory or standard reference (comma-separated for multiple)",
              filter: :list,
              enum: %w[c5-2020 itgs-2023 gdpr-2018 nis1 nis2 iso27001 sox pci-dss hipaa eu-data-act-2025 ens
                       iso27001-2022],
-             list: true
+             summary: true
 
   annotation "requirement/priority",
              description: "Implementation priority (must, should, may)",
              filter: :word,
              enum: %w[must should may],
-             list: true
+             summary: true
 
   annotation "requirement/story",
              description: "One-line business value statement explaining what the requirement enables",

data/lib/archsight/resources/compliance_evidence.rb

@@ -32,11 +32,13 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
 
   annotation "evidence/type",
              description: "Type of evidence",
-             enum: %w[documentation process configuration audit-log technical-control]
+             enum: %w[documentation process configuration audit-log technical-control],
+             summary: true
 
   annotation "evidence/status",
              description: "Current status of evidence",
-             enum: %w[implemented partial not-implemented]
+             enum: %w[implemented partial not-implemented],
+             summary: true
 
   relation :satisfies, :businessRequirements, :BusinessRequirement
 end

data/lib/archsight/resources/data_object.rb

@@ -38,7 +38,8 @@ class Archsight::Resources::DataObject < Archsight::Resources::Base
   annotation "data/visibility",
              description: "API visibility level",
              title: "Visibility",
-             enum: %w[public private internal]
+             enum: %w[public private internal],
+             summary: true
 
   annotation "generated/variants",
              description: "OpenAPI schema variants compacted into this DataObject",

data/lib/archsight/resources/import.rb

@@ -38,7 +38,9 @@ class Archsight::Resources::Import < Archsight::Resources::Base
   # Handler selection
   annotation "import/handler",
              description: "Handler class name to execute this import",
-             title: "Handler", enum: %w[
+             title: "Handler",
+             summary: true,
+             enum: %w[
                gitlab github repository
                rest-api rest-api-index
                jira-discover jira-metrics
@@ -57,7 +59,8 @@ class Archsight::Resources::Import < Archsight::Resources::Base
   annotation "import/enabled",
              description: "Whether this import is enabled",
              title: "Enabled",
-             enum: %w[true false]
+             enum: %w[true false],
+             summary: true
 
   annotation "import/priority",
              description: "Execution priority (lower runs first among ready imports)",

data/lib/archsight/resources/page.rb

@@ -38,11 +38,13 @@ class Archsight::Resources::Page < Archsight::Resources::Base
              description: "Owner responsible for keeping the page up to date (Name <email@domain.com>, or just a name)",
              title: "Owner",
              type: Archsight::Annotations::Person,
-             sidebar: false
+             sidebar: false,
+             summary: true
   annotation "page/status",
              description: "Lifecycle status (e.g. rfc, wip, approved)",
              filter: :word,
-             title: "Status"
+             title: "Status",
+             summary: true
   annotation "page/tags",
              description: "Comma-separated tags",
              filter: :list,

data/lib/archsight/resources/technology_artifact.rb

@@ -74,7 +74,7 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
              description: "Repository activity status",
              title: "Activity Status",
              enum: %w[active abandoned bot-only archived inaccessible empty no-code],
-             list: true
+             summary: true
   annotation "activity/reason",
              description: "Reason for activity status (for non-standard statuses)",
              title: "Status Reason",
@@ -83,7 +83,7 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
              description: "Bus factor assessment",
              title: "Bus Factor",
              enum: %w[high medium low unknown],
-             list: true
+             summary: true
   annotation "activity/createdAt",
              description: "Date of first commit (repository creation)",
              title: "Created",
@@ -130,7 +130,8 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   annotation "repository/visibility",
              description: "Repository visibility classification",
              title: "Visibility",
-             enum: %w[private internal open-source public]
+             enum: %w[private internal open-source public],
+             summary: true
   annotation "repository/recentTags",
              description: "Recent git tags (releases)",
              title: "Recent Tags",

data/lib/archsight/resources/technology_node.rb

@@ -34,7 +34,7 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
              description: "Type of infrastructure node",
              title: "Infrastructure Type",
              enum: %w[vm bare-metal kubernetes-node network-appliance storage-array],
-             list: true
+             summary: true
 
   relation :realizes, :businessConstraints, :BusinessConstraint
   relation :servedBy, :technologyServices, :TechnologyService

data/lib/archsight/resources/technology_service.rb

@@ -37,4 +37,8 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
 
   relation :suppliedBy, :technologyComponents, :TechnologySystemSoftware
   relation :servedBy, :businessActors, :BusinessActor
+  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :partiallyRealizes, :businessRequirements, :BusinessRequirement
+  relation :plans, :businessRequirements, :BusinessRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/technology_system_software.rb

@@ -34,4 +34,8 @@ class Archsight::Resources::TechnologySystemSoftware < Archsight::Resources::Bas
   relation :realizedThrough, :technologyArtifacts, :TechnologyArtifact
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
+  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :partiallyRealizes, :businessRequirements, :BusinessRequirement
+  relation :plans, :businessRequirements, :BusinessRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/view.rb

@@ -42,7 +42,8 @@ class Archsight::Resources::View < Archsight::Resources::Base
              description: "Display type for results",
              title: "Display Type",
              enum: %w[list:name list:name+kind],
-             sidebar: false
+             sidebar: false,
+             summary: true
 
   annotation "view/sort",
              description: 'Comma-separated list of fields to sort by. Prefix with - for descending (e.g., "-scc/language/Go/loc,name"). Special fields: name, kind',

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end