archsight 0.1.0

data/lib/archsight/resources/base.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require_relative "../annotations/annotation"
+
+module Archsight
+  module Resources
+    # Base is the base for all assets, should not be used directly, only by inheritance
+    class Base
+      attr_accessor :raw, :path_ref, :references
+
+      def self.inherited(subclass)
+        super
+        # Auto-register when class is defined
+        Archsight::Resources.register(subclass)
+      end
+
+      def self.relation(verb, kind, klass_name)
+        @relations ||= []
+        @relations << [verb, kind, klass_name]
+      end
+
+      def self.relations
+        @relations || []
+      end
+
+      # Define an annotation using the Annotation class
+      def self.annotation(key, description: nil, filter: nil, title: nil, format: nil, enum: nil, sidebar: true,
+                          type: nil, list: false)
+        @annotations ||= []
+        options = { description: description, filter: filter, title: title, format: format, enum: enum,
+                    sidebar: sidebar, type: type, list: list }
+        @annotations << Archsight::Annotations::Annotation.new(key, options)
+      end
+
+      # Get all annotation definitions
+      def self.annotations
+        @annotations || []
+      end
+
+      # Define a computed annotation using a block
+      # Computed annotations are calculated from related resources after the database is loaded.
+      # Supports all the same options as regular annotations.
+      # @param key [String] The annotation key (e.g., 'computed/total_cost')
+      # @param description [String, nil] Human-readable description
+      # @param filter [Symbol, nil] Filter type (:word, :list, or nil)
+      # @param title [String, nil] Display title
+      # @param format [Symbol, nil] Rendering format (:markdown, :tag_word, :tag_list)
+      # @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)
+      # @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, &)
+        require_relative "../annotations/computed"
+        @computed_annotations ||= []
+        @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 ||= []
+        options = { description: description, filter: filter, title: title, format: format, enum: enum,
+                    sidebar: sidebar, type: type, list: list }
+        @annotations << Archsight::Annotations::Annotation.new(key, options)
+      end
+
+      # Get all computed annotation definitions
+      def self.computed_annotations
+        @computed_annotations || []
+      end
+
+      # Find annotation definition matching a key (handles patterns)
+      def self.annotation_matching(key)
+        annotations.find { |a| a.matches?(key) }
+      end
+
+      # Check if key matches any pattern annotation
+      def self.matches_annotation_pattern?(key)
+        annotations.any? { |a| a.pattern? && a.matches?(key) }
+      end
+
+      # Get filterable annotations as array of Annotation objects
+      def self.filterable_annotations
+        annotations.select(&:filterable?).reject(&:pattern?)
+      end
+
+      # Get annotations marked for list display
+      def self.list_annotations
+        annotations.select(&:list_display?).reject(&:pattern?)
+      end
+
+      def self.annotation_title(key)
+        annotation_matching(key)&.title || key.split("/").last.capitalize
+      end
+
+      def self.annotation_format(key)
+        annotation_matching(key)&.format
+      end
+
+      def self.annotation_enum(key)
+        annotation_matching(key)&.enum
+      end
+
+      def self.icon(icon_name = nil)
+        if icon_name
+          @icon = icon_name
+        else
+          @icon || "page" # default icon
+        end
+      end
+
+      def self.layer(layer_name = nil)
+        if layer_name
+          @layer = layer_name
+        else
+          @layer || "other" # default layer
+        end
+      end
+
+      def self.description(text = nil)
+        if text
+          @description = text
+        else
+          @description
+        end
+      end
+
+      # Include annotation modules by symbol name
+      # @example include_annotations :git, :architecture, :backup
+      # @param names [Array<Symbol>] Symbols representing annotation modules (:git, :architecture, :backup, :generated)
+      def self.include_annotations(*names)
+        names.each do |name|
+          # Convert snake_case to CamelCase (e.g., :git -> 'Git', :my_module -> 'MyModule')
+          module_name = name.to_s.split("_").map(&:capitalize).join
+          mod = Archsight::Annotations.const_get(module_name)
+          include mod
+        rescue NameError
+          available = Archsight::Annotations.constants
+                                            .select { |c| Archsight::Annotations.const_get(c).is_a?(Module) && Archsight::Annotations.const_get(c).respond_to?(:included) }
+                                            .map { |c| ":#{c.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}" }
+                                            .sort
+          Kernel.raise "Unknown annotation module :#{name}. Available: #{available.join(", ")}"
+        end
+      end
+
+      def self.discovered_annotations
+        @discovered_annotations ||= Set.new
+      end
+
+      def initialize(raw, path_ref)
+        @raw = raw
+        @path_ref = path_ref
+        @references = []
+        # Auto-discover annotation keys
+        return unless annotations
+
+        annotations.each_key do |key|
+          self.class.discovered_annotations.add(key)
+        end
+      end
+
+      def klass
+        self.class.name.split("::").last
+      end
+
+      def kind
+        @raw["kind"]
+      end
+
+      def name
+        metadata["name"]
+      end
+
+      def annotations
+        metadata["annotations"] || {}
+      end
+
+      # Set a computed annotation value
+      # This writes to both the computed values cache and the annotations hash
+      # so computed values are accessible via the normal annotations interface.
+      # @param key [String] The annotation key
+      # @param value [Object] The computed value
+      def set_computed_annotation(key, value)
+        @computed_values ||= {}
+        @computed_values[key] = value
+        # Write to annotations hash for query compatibility
+        @raw["metadata"] ||= {}
+        @raw["metadata"]["annotations"] ||= {}
+        @raw["metadata"]["annotations"][key] = value
+      end
+
+      # Get a computed annotation value from the cache
+      # @param key [String] The annotation key
+      # @return [Object, nil] The computed value or nil
+      def computed_annotation_value(key)
+        @computed_values&.[](key)
+      end
+
+      def metadata
+        @raw["metadata"] || {}
+      end
+
+      def spec
+        @raw["spec"] || {}
+      end
+
+      def to_s
+        "#<#{self.class} name=#{name}>"
+      end
+
+      def abandoned?
+        annotations["activity/status"] == "abandoned"
+      end
+
+      def has_relations?
+        spec.any? { |_verb, kinds| kinds.is_a?(Hash) && kinds.values.any? { |v| v.is_a?(Array) && v.any? } }
+      end
+
+      def verb_allowed?(verb)
+        self.class.relations.any? { |v, _, _| v.to_s == verb.to_s }
+      end
+
+      def verb_kind_allowed?(verb, kind)
+        self.class.relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
+      end
+
+      def relations(verb, kind)
+        (spec[verb.to_s] || {})[kind.to_s] || []
+      end
+
+      def set_relations(verb, kind, rels)
+        spec[verb.to_s][kind.to_s] = rels
+        rels.each { |rel| rel.referenced_by(self, verb) }
+      end
+
+      def referenced_by(inst, verb = nil)
+        # Store reference with verb information for grouped display
+        existing = @references.find { |r| r[:instance] == inst && r[:verb] == verb }
+        @references << { instance: inst, verb: verb } unless existing
+      end
+
+      # Get references grouped by kind and verb for display (incoming)
+      # Returns: { "Kind" => { "verb" => [instances...] } }
+      def references_grouped
+        grouped = {}
+        @references.each do |ref|
+          inst = ref[:instance]
+          verb = ref[:verb]
+          kind = inst.klass
+          grouped[kind] ||= {}
+          grouped[kind][verb] ||= []
+          grouped[kind][verb] << inst
+        end
+        # Sort by kind name, then by verb name
+        grouped.sort.to_h.transform_values { |verbs| verbs.sort.to_h }
+      end
+
+      # Get outgoing relations grouped by verb and kind for display
+      # Returns: { "verb" => { "Kind" => [instances...] } }
+      def relations_grouped
+        grouped = {}
+        spec.each do |verb, kinds|
+          next unless kinds.is_a?(Hash)
+
+          kinds.each_value do |instances|
+            next unless instances.is_a?(Array) && instances.any?
+
+            instances.each do |inst|
+              kind = inst.klass
+              grouped[verb] ||= {}
+              grouped[verb][kind] ||= []
+              grouped[verb][kind] << inst
+            end
+          end
+        end
+        # Sort by verb name, then by kind name
+        grouped.sort.to_h.transform_values { |kinds| kinds.sort.to_h }
+      end
+
+      def verify!
+        spec.each do |verb, kinds|
+          raise "unknown verb #{verb}" unless verb_allowed?(verb)
+
+          kinds.each_key do |kind, _|
+            raise "unknown verb #{verb} / kind #{kind} combination" unless verb_kind_allowed?(verb, kind)
+          end
+        end
+      end
+
+      def merge!(inst)
+        # NOTE: path reference is preserved from the original instance
+        @raw = Archsight::Helpers.deep_merge(@raw, inst.raw)
+      end
+
+      # raise provides a helper for better error messages including current path and line no
+      def raise(msg)
+        Kernel.raise(Archsight::ResourceError.new(msg, @path_ref))
+      end
+    end
+  end
+end

data/lib/archsight/resources/business_actor.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# BusinessActor represents teams or organizational units
+class Archsight::Resources::BusinessActor < Archsight::Resources::Base
+  include_annotations :git, :architecture, :generated
+
+  description <<~MD
+    Represents a team, organizational unit, or external entity that performs business behavior.
+
+    ## ArchiMate Definition
+
+    **Layer:** Business
+    **Aspect:** Active Structure
+
+    A business actor represents a business entity that is capable of performing behavior.
+    Actors can be individuals, teams, departments, or external organizations that participate
+    in business processes or own/maintain system components.
+
+    ## Usage
+
+    Use BusinessActor to represent:
+
+    - Development teams
+    - Operations teams
+    - External vendors or partners
+    - Support organizations
+    - Cross-functional groups
+  MD
+
+  icon "community"
+  layer "business"
+
+  annotation "team/lead",
+             description: 'Team lead (format: "Name <email>" or "email")',
+             title: "Team Lead",
+             sidebar: false,
+             filter: :word,
+             format: :tag_word,
+             type: Archsight::Annotations::EmailRecipient
+
+  annotation "team/members",
+             description: 'Team members (format: "Name <email>" or "email")',
+             title: "Team Members",
+             sidebar: false,
+             filter: :list,
+             format: :tag_list,
+             type: Archsight::Annotations::EmailRecipient
+
+  annotation "team/jira",
+             description: "Jira project keys for issue tracking (primary queue first)",
+             title: "Jira Projects",
+             sidebar: false,
+             filter: :list,
+             format: :tag_list
+
+  annotation "jira/issues/created",
+             description: "Issues created per month (comma-separated, last 6 months)",
+             title: "Issues Created",
+             sidebar: false
+
+  annotation "jira/issues/resolved",
+             description: "Issues resolved per month (comma-separated, last 6 months)",
+             title: "Issues Resolved",
+             sidebar: false
+
+  # ITIL 4 General Management Practices
+  annotation "itil/general",
+             description: "ITIL general management practices",
+             title: "ITIL General Practices",
+             filter: :list,
+             format: :tag_list,
+             enum: %w[
+               strategy-management portfolio-management architecture-management
+               risk-management workforce-management continual-improvement
+               knowledge-management measurement-reporting change-management
+               project-management relationship-management supplier-management
+               financial-management
+             ]
+
+  # ITIL 4 Service Management Practices
+  annotation "itil/service",
+             description: "ITIL service management practices",
+             title: "ITIL Service Practices",
+             filter: :list,
+             format: :tag_list,
+             enum: %w[
+               service-design service-catalog service-level-management
+               availability-management capacity-management continuity-management
+               security-management configuration-management
+             ]
+
+  # ITIL 4 Technical Management Practices
+  annotation "itil/technical",
+             description: "ITIL technical management practices",
+             title: "ITIL Technical Practices",
+             filter: :list,
+             format: :tag_list,
+             enum: %w[
+               deployment-management infrastructure-management software-development
+               release-management change-enablement service-validation
+               incident-management problem-management service-desk
+               monitoring-management
+             ]
+
+  relation :compositeOf, :businessActors, :BusinessActor
+
+  # Computed Annotations
+  computed_annotation "team/size",
+                      title: "Team Size",
+                      description: "Number of team members (including sub-teams)",
+                      list: true,
+                      type: Integer do
+    # Count members from this team
+    members = @instance.annotations["team/members"]
+    count = if members.nil? || members.empty?
+              0
+            else
+              members.split(/[,\n]/).map(&:strip).reject(&:empty?).size
+            end
+
+    # Add members from sub-teams (teams that are composites of this team)
+    incoming_transitive(:BusinessActor).each do |subteam|
+      subteam_members = subteam.annotations["team/members"]
+      next if subteam_members.nil? || subteam_members.empty?
+
+      count += subteam_members.split(/[,\n]/).map(&:strip).reject(&:empty?).size
+    end
+
+    count
+  end
+
+  computed_annotation "team/lead/size",
+                      title: "Team Leads",
+                      description: "Number of team leads (including sub-teams)",
+                      type: Integer do
+    # Count lead from this team
+    count = @instance.annotations["team/lead"] ? 1 : 0
+
+    # Add leads from sub-teams
+    incoming_transitive(:BusinessActor).each do |subteam|
+      count += 1 if subteam.annotations["team/lead"]
+    end
+
+    count
+  end
+
+  computed_annotation "repository/artifacts/total",
+                      title: "Maintained Repositories",
+                      description: "Number of git repositories maintained by this team",
+                      type: Integer do
+    count(incoming_transitive('TechnologyArtifact: artifact/type == "repo"'))
+  end
+
+  computed_annotation "repository/artifacts/active",
+                      title: "Active Repositories",
+                      description: "Number of active git repositories maintained by this team",
+                      type: Integer do
+    count(incoming_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "active"'))
+  end
+
+  computed_annotation "repository/artifacts/highBusFactor",
+                      title: "High Bus Factor Repositories",
+                      description: "Number of active git repositories with high bus factor maintained by this team",
+                      type: Integer do
+    count(incoming_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "active" & activity/busFactor == "high"'))
+  end
+
+  computed_annotation "repository/artifacts/abandoned",
+                      title: "Abandoned Repositories",
+                      description: "Number of abandoned git repositories maintained by this team",
+                      type: Integer do
+    count(incoming_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "abandoned"'))
+  end
+
+  computed_annotation "repository/artifacts/archived",
+                      title: "Archived Repositories",
+                      description: "Number of archived git repositories maintained by this team",
+                      type: Integer do
+    count(incoming_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "archived"'))
+  end
+
+  computed_annotation "jira/projectUrl",
+                      title: "Jira Board",
+                      description: "Link to Jira board (computed from team/jira)",
+                      format: :link do
+    jira_key = @instance.annotations["team/jira"]
+    next nil if jira_key.nil? || jira_key.empty?
+
+    # Use first key if multiple (comma/newline separated)
+    primary_key = jira_key.split(/[,\n]/).first&.strip
+    next nil if primary_key.nil? || primary_key.empty?
+
+    "https://jira.example.com/projects/#{primary_key}/issues"
+  end
+end

data/lib/archsight/resources/business_constraint.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# BusinessConstraint represents restrictions or limitations on architecture
+class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a factor that limits the realization of goals or influences architecture decisions.
+
+    ## ArchiMate Definition
+
+    **Layer:** Motivation
+    **Aspect:** Passive Structure
+
+    A constraint represents a factor that prevents or obstructs the realization of goals.
+    Constraints are typically imposed by external factors such as regulations, organizational
+    policies, or technical limitations.
+
+    ## Usage
+
+    Use BusinessConstraint to represent:
+
+    - Regulatory requirements (GDPR, SOX, PCI-DSS)
+    - Security policies
+    - Organizational standards
+    - Technical limitations
+    - Budget or resource constraints
+  MD
+
+  icon "prohibition"
+  layer "business"
+end

data/lib/archsight/resources/business_process.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# BusinessProcess represents a structured business workflow or procedure
+class Archsight::Resources::BusinessProcess < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a sequence of business behaviors that achieves a specific outcome.
+
+    ## ArchiMate Definition
+
+    **Layer:** Business
+    **Aspect:** Behavior
+
+    A business process represents a sequence of business behaviors that achieves a specific
+    outcome such as a defined set of products or business services. It orchestrates the
+    activities performed by business actors using application services.
+
+    ## Usage
+
+    Use BusinessProcess to represent:
+
+    - Customer onboarding workflows
+    - Incident response procedures
+    - Change management processes
+    - Release deployment pipelines
+    - Support escalation processes
+  MD
+
+  icon "kanban-board"
+  layer "business"
+
+  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :servedBy, :applicationServices, :ApplicationService
+  relation :performedBy, :businessActors, :BusinessActor
+end