archsight 0.1.0

data/lib/archsight/annotations/aggregators.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# ComputedAggregators provides static methods for aggregating annotation values.
+# These functions handle nil values gracefully and convert types as needed.
+module Archsight::Annotations::ComputedAggregators
+  class << self
+    # Sum numeric values
+    # @param values [Array] Array of values to sum
+    # @return [Float, nil] Sum of values converted to float, nil if no valid values
+    def sum(values)
+      numeric_values = to_numeric(values)
+      return nil if numeric_values.empty?
+
+      numeric_values.sum
+    end
+
+    # Count non-nil values
+    # @param values [Array] Array of values to count
+    # @return [Integer] Count of non-nil values
+    def count(values)
+      values.compact.length
+    end
+
+    # Calculate average of numeric values
+    # @param values [Array] Array of values to average
+    # @return [Float, nil] Average of values, nil if no valid values
+    def avg(values)
+      numeric_values = to_numeric(values)
+      return nil if numeric_values.empty?
+
+      numeric_values.sum / numeric_values.length.to_f
+    end
+
+    # Find minimum numeric value
+    # @param values [Array] Array of values
+    # @return [Float, nil] Minimum value, nil if no valid values
+    def min(values)
+      numeric_values = to_numeric(values)
+      return nil if numeric_values.empty?
+
+      numeric_values.min
+    end
+
+    # Find maximum numeric value
+    # @param values [Array] Array of values
+    # @return [Float, nil] Maximum value, nil if no valid values
+    def max(values)
+      numeric_values = to_numeric(values)
+      return nil if numeric_values.empty?
+
+      numeric_values.max
+    end
+
+    # Collect unique values, flattening arrays and sorting
+    # @param values [Array] Array of values (may contain nested arrays)
+    # @return [Array] Unique sorted values
+    def collect(values)
+      flat_values = values.flatten.compact
+      # Handle comma-separated strings (list annotations)
+      expanded = flat_values.flat_map do |v|
+        v.is_a?(String) ? v.split(",").map(&:strip) : v
+      end
+      expanded.compact.uniq.sort_by(&:to_s)
+    end
+
+    # Get first non-nil value
+    # @param values [Array] Array of values
+    # @return [Object, nil] First non-nil value
+    def first(values)
+      values.compact.first
+    end
+
+    # Find most common value (mode)
+    # @param values [Array] Array of values (may contain nested arrays)
+    # @return [Object, nil] Most frequent value, nil if no values
+    def most_common(values)
+      flat_values = values.flatten.compact
+      return nil if flat_values.empty?
+
+      # Handle comma-separated strings (list annotations)
+      expanded = flat_values.flat_map do |v|
+        v.is_a?(String) ? v.split(",").map(&:strip) : v
+      end
+
+      expanded.compact
+              .group_by(&:itself)
+              .max_by { |_, group| group.length }
+              &.first
+    end
+
+    private
+
+    # Convert values to numeric (float), filtering out non-convertible values
+    def to_numeric(values)
+      values.compact.filter_map do |v|
+        case v
+        when Numeric
+          v.to_f
+        when String
+          begin
+            Float(v)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archsight/annotations/annotation.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "email_recipient"
+
+# Annotation represents a single annotation definition with its schema and behavior
+class Archsight::Annotations::Annotation
+  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :list
+
+  def initialize(key, options = {})
+    @key = key
+    @description = options[:description]
+    @explicit_title = options[:title]
+    @filter = options[:filter]
+    @enum = options[:enum]
+    @sidebar = options.fetch(:sidebar, true)
+    @list = options.fetch(:list, false)
+    @type = options[:type]
+
+    # Auto-add filter if enum present
+    @filter ||= :word if @enum
+
+    # Derive format from filter if not explicitly set
+    @format = options[:format] || derive_format
+
+    # Build regex for pattern annotations
+    @regex = build_regex if pattern?
+  end
+
+  # === Schema Methods ===
+
+  def pattern?
+    key.include?("*")
+  end
+
+  def matches?(test_key)
+    pattern? ? @regex.match?(test_key) : key == test_key
+  end
+
+  def title
+    @explicit_title || key.split("/").last.capitalize
+  end
+
+  def filterable?
+    @filter && @sidebar != false
+  end
+
+  def list?
+    @filter == :list
+  end
+
+  def list_display?
+    @list == true
+  end
+
+  def has_validation?
+    @enum || @type.is_a?(Class)
+  end
+
+  # === Value Methods (for instance values) ===
+
+  # Get value(s) from instance
+  # Returns array for list annotations, coerced single value otherwise
+  def value_for(instance)
+    raw = instance.annotations[key]
+
+    if list?
+      return [] if raw.nil? || raw.to_s.empty?
+
+      raw.to_s.split(/,|\n/).map(&:strip).reject(&:empty?)
+    else
+      return nil if raw.nil?
+
+      case @type
+      when Integer then raw.to_i
+      when Float then raw.to_f
+      else raw
+      end
+    end
+  end
+
+  # Validate a value and return array of error messages (empty if valid)
+  def validate(value)
+    errors = []
+    return errors if value.nil?
+
+    # Check enum constraint
+    if @enum
+      values = list? ? value.to_s.split(",").map(&:strip) : [value.to_s]
+      invalid_values = values.reject { |v| @enum.include?(v) }
+      invalid_values.each do |v|
+        errors << "invalid value '#{v}'. Expected one of: #{@enum.join(", ")}"
+      end
+    end
+
+    # Check type constraint
+    if @type.is_a?(Class) && errors.empty?
+      values_to_check = list? ? value.to_s.split(/,|\n/).map(&:strip).reject(&:empty?) : [value.to_s]
+
+      values_to_check.each do |string_value|
+        valid = case @type.to_s
+                when "Integer"
+                  string_value.match?(/\A-?\d+\z/)
+                when "Float"
+                  string_value.match?(/\A-?\d+(\.\d+)?\z/)
+                when "URI"
+                  begin
+                    URI.parse(string_value)
+                    string_value.match?(%r{\Ahttps?://})
+                  rescue URI::InvalidURIError
+                    false
+                  end
+                when "Archsight::Annotations::EmailRecipient"
+                  Archsight::Annotations::EmailRecipient.valid?(string_value)
+                else
+                  true
+                end
+        errors << "invalid value '#{string_value}'. #{type_error_message}" unless valid
+      end
+    end
+
+    errors
+  end
+
+  # Check if value is valid (convenience method)
+  def valid?(value)
+    validate(value).empty?
+  end
+
+  def markdown?
+    @format == :markdown
+  end
+
+  # Example value for templates
+  def example_value
+    if @enum
+      @enum.first || "TODO"
+    elsif @type == Float
+      0.0
+    elsif @type == Integer
+      0
+    else
+      "TODO"
+    end
+  end
+
+  private
+
+  def type_error_message
+    case @type.to_s
+    when "URI" then "Expected valid HTTP/HTTPS URL"
+    when "Integer" then "Expected an integer value"
+    when "Float" then "Expected a float value"
+    when "Archsight::Annotations::EmailRecipient" then 'Expected email format: "Name <email@domain.com>" or "email@domain.com"'
+    else "Invalid value for type #{@type}"
+    end
+  end
+
+  def derive_format
+    case @filter
+    when :word then :tag_word
+    when :list then :tag_list
+    end
+  end
+
+  def build_regex
+    Regexp.new("^#{Regexp.escape(key).gsub('\*', ".+")}$")
+  end
+end

data/lib/archsight/annotations/architecture_annotations.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "uri"
+
+# Architecture module adds common architecture annotations to resource classes
+module Archsight::Annotations::Architecture
+  def self.included(base)
+    base.class_eval do
+      annotation "architecture/abbr",
+                 description: "Abbreviation or short name",
+                 title: "Abbreviation"
+      annotation "architecture/evidence",
+                 description: "Supporting evidence or notes",
+                 title: "Evidence",
+                 format: :markdown
+      annotation "architecture/description",
+                 description: "Textual description of the interface",
+                 title: "Description",
+                 format: :markdown
+      annotation "architecture/documentation",
+                 description: "Documentation URL or reference",
+                 title: "Documentation",
+                 type: URI
+      annotation "architecture/tags",
+                 description: "Comma-separated tags",
+                 filter: :list,
+                 title: "Tags"
+      annotation "architecture/encoding",
+                 description: "Data encoding format",
+                 filter: :list,
+                 title: "Encoding"
+      annotation "architecture/title",
+                 description: "Interface title",
+                 title: "Title"
+      annotation "architecture/openapi",
+                 description: "OpenAPI specification version",
+                 filter: :word,
+                 title: "OpenAPI"
+      annotation "architecture/version",
+                 description: "API or interface version",
+                 filter: :word,
+                 title: "Version",
+                 sidebar: false
+      annotation "architecture/status",
+                 description: "Lifecycle status (General-Availability, Early-Access, Development)",
+                 filter: :word,
+                 title: "Status"
+      annotation "architecture/visibility",
+                 description: "API visibility (public, private)",
+                 filter: :word,
+                 enum: %w[public private],
+                 title: "Visibility"
+      annotation "architecture/applicationSets",
+                 description: "Related ArgoCD ApplicationSets",
+                 title: "ApplicationSets",
+                 format: :markdown
+    end
+  end
+end

data/lib/archsight/annotations/backup_annotations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Backup module adds backup-related annotations to resource classes
+module Archsight::Annotations::Backup
+  def self.included(base)
+    base.class_eval do
+      annotation "backup/mode",
+                 description: "Backup mode strategy",
+                 title: "Backup Mode",
+                 enum: %w[none full incremental continuous offsite not-needed]
+      annotation "backup/rto",
+                 description: "Recovery Time Objective (RTO) in minutes - the maximum acceptable time to restore service after a failure",
+                 title: "Backup RTO (min)",
+                 type: Integer
+      annotation "backup/rpo",
+                 description: "Recovery Point Objective (RPO) in minutes - the maximum acceptable amount of data loss measured in time",
+                 title: "Backup RPO (min)",
+                 type: Integer
+    end
+  end
+end

data/lib/archsight/annotations/computed.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require_relative "aggregators"
+require_relative "relation_resolver"
+
+# Computed represents a computed annotation definition.
+# It stores the key, description, optional type, and the computation block.
+class Archsight::Annotations::Computed
+  attr_reader :key, :description, :type, :block
+
+  def initialize(key, description: nil, type: nil, &block)
+    @key = key
+    @description = description
+    @type = type
+    @block = block
+  end
+
+  # Check if this definition matches a given key
+  def matches?(other_key)
+    @key == other_key
+  end
+end
+
+# ComputedEvaluator provides the DSL context for computing annotation values.
+# It exposes aggregation functions and relation traversal methods.
+class Archsight::Annotations::ComputedEvaluator
+  def initialize(instance, database, manager)
+    @instance = instance
+    @database = database
+    @manager = manager
+    @resolver = Archsight::Annotations::ComputedRelationResolver.new(instance, database)
+  end
+
+  # Access a regular annotation value from the current instance
+  def annotation(key)
+    @instance.annotations[key]
+  end
+
+  # Access a computed annotation value (triggers computation if needed)
+  def computed(key)
+    @manager.compute_for_key(@instance, key)
+  end
+
+  # --- Relation Traversal Methods ---
+
+  # Get direct outgoing relations (-> Kind)
+  def outgoing(kind = nil)
+    @resolver.outgoing(kind)
+  end
+
+  # Get transitive outgoing relations (~> Kind)
+  def outgoing_transitive(kind = nil, max_depth: 10)
+    @resolver.outgoing_transitive(kind, max_depth: max_depth)
+  end
+
+  # Get direct incoming relations (<- Kind)
+  def incoming(kind = nil)
+    @resolver.incoming(kind)
+  end
+
+  # Get transitive incoming relations (<~ Kind)
+  def incoming_transitive(kind = nil, max_depth: 10)
+    @resolver.incoming_transitive(kind, max_depth: max_depth)
+  end
+
+  # --- Aggregation Functions ---
+
+  # Sum numeric annotation values from instances
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Float, nil] Sum of values or nil if no values
+  def sum(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.sum(values)
+  end
+
+  # Count instances or non-nil annotation values
+  # @param instances [Array] Array of resource instances
+  # @param key [String, nil] Optional annotation key; if nil, counts instances
+  # @return [Integer] Count
+  def count(instances, key = nil)
+    if key
+      values = extract_values(instances, key)
+      Archsight::Annotations::ComputedAggregators.count(values)
+    else
+      instances.length
+    end
+  end
+
+  # Average numeric annotation values
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Float, nil] Average or nil if no values
+  def avg(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.avg(values)
+  end
+
+  # Minimum numeric annotation value
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Float, nil] Minimum value or nil if no values
+  def min(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.min(values)
+  end
+
+  # Maximum numeric annotation value
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Float, nil] Maximum value or nil if no values
+  def max(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.max(values)
+  end
+
+  # Collect unique annotation values
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Array] Unique sorted values
+  def collect(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.collect(values)
+  end
+
+  # Get first non-nil annotation value
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Object, nil] First non-nil value
+  def first(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.first(values)
+  end
+
+  # Get most common annotation value (mode)
+  # @param instances [Array] Array of resource instances
+  # @param key [String] Annotation key to extract values from
+  # @return [Object, nil] Most frequent value
+  def most_common(instances, key)
+    values = extract_values(instances, key)
+    Archsight::Annotations::ComputedAggregators.most_common(values)
+  end
+
+  # Get an annotation value from an instance, triggering computation if needed
+  # @param instance [Object] Resource instance
+  # @param key [String] Annotation key to extract
+  # @return [Object, nil] Annotation value
+  def get(instance, key)
+    @manager.compute_for_key(instance, key) if instance.class.computed_annotations.any? { |d| d.matches?(key) }
+    instance.annotations[key]
+  end
+
+  private
+
+  # Extract annotation values from instances
+  # If the key corresponds to a computed annotation that hasn't been computed yet,
+  # trigger its computation to handle cross-kind dependencies
+  def extract_values(instances, key)
+    instances.map do |inst|
+      # Check if this is a computed annotation that needs to be computed
+      if inst.class.computed_annotations.any? { |d| d.matches?(key) }
+        # Trigger computation if not already computed
+        @manager.compute_for_key(inst, key)
+      end
+      inst.annotations[key]
+    end
+  end
+end
+
+# ComputedManager orchestrates the computation of all computed annotations.
+# It handles lazy evaluation, caching, and cycle detection.
+class Archsight::Annotations::ComputedManager
+  def initialize(database)
+    @database = database
+    @computed_cache = {}  # { [instance_object_id, key] => value }
+    @computing = Set.new  # For cycle detection
+  end
+
+  # Compute all computed annotations for all instances
+  def compute_all!
+    # Collect all resource classes that have computed annotations
+    @database.instances.each do |klass, instances_hash|
+      definitions = klass.computed_annotations
+      next if definitions.empty?
+
+      instances_hash.each_value do |instance|
+        definitions.each do |definition|
+          compute_for(instance, definition)
+        end
+      end
+    end
+  end
+
+  # Compute a specific annotation for an instance by key
+  def compute_for_key(instance, key)
+    definition = instance.class.computed_annotations.find { |d| d.matches?(key) }
+    return nil unless definition
+
+    compute_for(instance, definition)
+  end
+
+  # Compute a specific annotation for an instance
+  def compute_for(instance, definition)
+    cache_key = [instance.object_id, definition.key]
+
+    # Return cached value if available
+    return @computed_cache[cache_key] if @computed_cache.key?(cache_key)
+
+    # Cycle detection
+    raise "Circular dependency detected: #{definition.key} for #{instance.name}" if @computing.include?(cache_key)
+
+    @computing.add(cache_key)
+    begin
+      evaluator = Archsight::Annotations::ComputedEvaluator.new(instance, @database, self)
+      value = evaluator.instance_eval(&definition.block)
+
+      # Apply type coercion if specified
+      value = coerce_value(value, definition.type) if definition.type
+
+      # Cache the computed value (even if nil, to avoid recomputation)
+      @computed_cache[cache_key] = value
+
+      # Only store meaningful values to the instance annotations
+      # nil and empty arrays indicate "no data" and should not be stored
+      if meaningful_value?(value)
+        # Convert arrays to comma-separated strings for consistency with regular annotations
+        stored_value = value.is_a?(Array) ? value.join(", ") : value
+        instance.set_computed_annotation(definition.key, stored_value)
+      end
+
+      value
+    ensure
+      @computing.delete(cache_key)
+    end
+  end
+
+  private
+
+  # Check if a value is meaningful (should be stored)
+  # nil and empty collections indicate "no data" and should not be stored
+  def meaningful_value?(value)
+    return false if value.nil?
+    return false if value.is_a?(Array) && value.empty?
+    return false if value.is_a?(String) && value.empty?
+
+    true
+  end
+
+  # Coerce value to specified type
+  def coerce_value(value, type)
+    return nil if value.nil?
+
+    case type.to_s
+    when "Integer"
+      value.to_i
+    when "Float"
+      value.to_f
+    when "String"
+      value.to_s
+    else
+      value
+    end
+  end
+end

data/lib/archsight/annotations/email_recipient.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Custom type for email recipient validation
+# Accepts: "Name <email@domain.com>" or "email@domain.com"
+# Rejects: "Name" (no email)
+class Archsight::Annotations::EmailRecipient
+  # RFC 5322 simplified email pattern
+  EMAIL_PATTERN = /\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/
+  # Email recipient format: "Display Name <email@domain.com>"
+  RECIPIENT_PATTERN = /\A.+\s+<([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})>\z/
+
+  def self.valid?(value)
+    return false if value.nil? || value.to_s.strip.empty?
+
+    str = value.to_s.strip
+    # Check if it's a full recipient format "Name <email>"
+    return true if str.match?(RECIPIENT_PATTERN)
+
+    # Check if it's just an email address
+    return true if str.match?(EMAIL_PATTERN)
+
+    false
+  end
+
+  def self.extract_email(value)
+    return nil if value.nil?
+
+    str = value.to_s.strip
+    if (match = str.match(RECIPIENT_PATTERN))
+      match[1]
+    elsif str.match?(EMAIL_PATTERN)
+      str
+    end
+  end
+end

data/lib/archsight/annotations/generated_annotations.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Generated module adds annotations for tracking generated resources
+module Archsight::Annotations::Generated
+  def self.included(base)
+    base.class_eval do
+      annotation "generated/script",
+                 description: "Name of the script that generated this resource",
+                 title: "Generated By",
+                 sidebar: false
+      annotation "generated/at",
+                 description: "Timestamp when this resource was generated (ISO8601)",
+                 title: "Generated At",
+                 sidebar: false
+    end
+  end
+end

data/lib/archsight/annotations/git_annotations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Git module adds git tracking annotations to resource classes
+module Archsight::Annotations::Git
+  def self.included(base)
+    base.class_eval do
+      annotation "git/updatedAt",
+                 description: "Date when the resource was last updated",
+                 title: "Updated At"
+      annotation "git/updatedBy",
+                 description: "Email of person who last updated the resource",
+                 title: "Updated By"
+      annotation "git/reviewedAt",
+                 description: "Date when the resource was last reviewed",
+                 title: "Reviewed At"
+      annotation "git/reviewedBy",
+                 description: "Email of person who last reviewed the resource",
+                 title: "Reviewed By"
+    end
+  end
+end