archsight 0.1.0

data/lib/archsight/annotations/relation_resolver.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# ComputedRelationResolver provides methods for traversing resource relations.
+# It mirrors the relation traversal operators in the query language:
+# - outgoing (->): Direct outgoing relations
+# - outgoing_transitive (~>): Transitive outgoing relations
+# - incoming (<-): Direct incoming relations
+# - incoming_transitive (<~): Transitive incoming relations
+#
+# Filter parameter can be:
+# - Symbol: Simple kind filter (e.g., :TechnologyArtifact)
+# - String: Query selector (e.g., 'TechnologyArtifact: activity/status == "active"')
+class Archsight::Annotations::ComputedRelationResolver
+  MAX_DEPTH = 10
+
+  def initialize(instance, database)
+    @instance = instance
+    @database = database
+    @query_cache = {}
+  end
+
+  # Get direct outgoing relations (-> Kind)
+  # @param filter [Symbol, String, nil] Optional kind filter (Symbol) or query selector (String)
+  # @return [Array] Array of related instances
+  def outgoing(filter = nil)
+    results = []
+
+    @instance.class.relations.each do |_verb, kind_name, _klass_name|
+      rels = @instance.relations(_verb, kind_name)
+      rels.each do |rel|
+        results << rel if matches_filter?(rel, filter)
+      end
+    end
+
+    results.uniq
+  end
+
+  # Get transitive outgoing relations (~> Kind)
+  # Follows all relation chains up to max_depth
+  # @param filter [Symbol, String, nil] Optional kind filter (Symbol) or query selector (String)
+  # @param max_depth [Integer] Maximum traversal depth (default 10)
+  # @return [Array] Array of transitively related instances
+  def outgoing_transitive(filter = nil, max_depth: MAX_DEPTH)
+    visited = Set.new
+    results = []
+
+    collect_transitive_outgoing(@instance, filter, visited, 0, max_depth, results)
+    results.uniq
+  end
+
+  # Get direct incoming relations (<- Kind)
+  # Uses the references array maintained during relation resolution
+  # @param filter [Symbol, String, nil] Optional kind filter (Symbol) or query selector (String)
+  # @return [Array] Array of instances that reference this one
+  def incoming(filter = nil)
+    refs = @instance.references || []
+    # Extract instances from reference hashes
+    instances = refs.map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }.compact
+
+    if filter.nil?
+      instances
+    else
+      instances.select { |ref| matches_filter?(ref, filter) }
+    end
+  end
+
+  # Get transitive incoming relations (<~ Kind)
+  # Follows all reverse relation chains up to max_depth
+  # @param filter [Symbol, String, nil] Optional kind filter (Symbol) or query selector (String)
+  # @param max_depth [Integer] Maximum traversal depth (default 10)
+  # @return [Array] Array of instances that transitively reference this one
+  def incoming_transitive(filter = nil, max_depth: MAX_DEPTH)
+    visited = Set.new
+    results = []
+
+    collect_transitive_incoming(@instance, filter, visited, 0, max_depth, results)
+    results.uniq
+  end
+
+  private
+
+  # Check if an instance matches the given filter
+  # @param instance [Object] The instance to check
+  # @param filter [Symbol, String, nil] Kind filter or query selector
+  # @return [Boolean] true if instance matches
+  def matches_filter?(instance, filter)
+    return true if filter.nil?
+
+    instance_kind = instance.class.name.split("::").last
+
+    if filter.is_a?(Symbol)
+      # Simple kind check
+      instance_kind == filter.to_s
+    else
+      # Query selector - parse and evaluate
+      query_node = parse_query(filter)
+      evaluator.matches?(query_node, instance)
+    end
+  end
+
+  # Parse a query string (with caching)
+  def parse_query(query_string)
+    @query_cache[query_string] ||= begin
+      require_relative "../query/lexer"
+      require_relative "../query/parser"
+      tokens = Archsight::Query::Lexer.new(query_string).tokenize
+      Archsight::Query::Parser.new(tokens).parse
+    end
+  end
+
+  # Get or create the query evaluator
+  def evaluator
+    @evaluator ||= begin
+      require_relative "../query/evaluator"
+      Archsight::Query::Evaluator.new(@database)
+    end
+  end
+
+  # Recursively collect transitive outgoing relations
+  def collect_transitive_outgoing(inst, filter, visited, depth, max_depth, results)
+    return if depth >= max_depth
+
+    key = "#{inst.class}/#{inst.name}"
+    return if visited.include?(key)
+
+    visited.add(key)
+
+    inst.class.relations.each do |verb, kind_name, _klass_name|
+      rels = inst.relations(verb, kind_name)
+      rels.each do |rel|
+        # Add to results if matches filter (or no filter)
+        results << rel if matches_filter?(rel, filter)
+
+        # Continue traversal (regardless of whether this matched)
+        collect_transitive_outgoing(rel, filter, visited.dup, depth + 1, max_depth, results)
+      end
+    end
+  end
+
+  # Recursively collect transitive incoming relations
+  def collect_transitive_incoming(inst, filter, visited, depth, max_depth, results)
+    return if depth >= max_depth
+
+    key = "#{inst.class}/#{inst.name}"
+    return if visited.include?(key)
+
+    visited.add(key)
+
+    refs = inst.references || []
+    # Extract instances from reference hashes
+    instances = refs.map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }.compact
+    instances.each do |ref|
+      # Add to results if matches filter (or no filter)
+      results << ref if matches_filter?(ref, filter)
+
+      # Continue traversal (regardless of whether this matched)
+      collect_transitive_incoming(ref, filter, visited.dup, depth + 1, max_depth, results)
+    end
+  end
+end

data/lib/archsight/cli.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Archsight
+  class CLI < Thor
+    class_option :resources,
+                 aliases: "-r",
+                 type: :string,
+                 desc: "Path to resources directory (default: ARCHSIGHT_RESOURCES_DIR or current directory)"
+
+    desc "web", "Start the web server"
+    option :port, aliases: "-p", type: :numeric, default: 4567, desc: "Port to listen on"
+    option :host, aliases: "-H", type: :string, default: "localhost", desc: "Host to bind to"
+    def web
+      configure_resources
+      require "archsight/web/application"
+      Archsight::Web::Application.run!(port: options[:port], bind: options[:host])
+    end
+
+    desc "lint", "Validate architecture resources"
+    def lint
+      configure_resources
+      require "archsight/database"
+      require "archsight/linter"
+      require "archsight/helpers"
+
+      db = Archsight::Database.new(Archsight.resources_dir, compute_annotations: false, verbose: true)
+      begin
+        db.reload!
+      rescue Archsight::ResourceError => e
+        display_error_with_context(e.to_s)
+        exit 1
+      end
+
+      linter = Archsight::Linter.new(db)
+      errors = linter.validate
+
+      if errors.any?
+        puts "Validation Errors (#{errors.count}):"
+        errors.each { |error| display_error_with_context(error) }
+        exit 1
+      end
+
+      puts "All validations passed!"
+    end
+
+    desc "template [KIND]", "Generate a YAML template for a resource kind"
+    def template(kind = nil)
+      require "archsight/template"
+      require "archsight/resources"
+
+      if kind.nil?
+        list_kinds
+      else
+        puts Archsight::Template.generate(kind)
+      end
+    end
+
+    desc "console", "Start an interactive console"
+    def console
+      configure_resources
+      require "archsight/database"
+      require "irb"
+
+      db = Archsight::Database.new(Archsight.resources_dir, verbose: true)
+      db.reload!
+
+      puts "Database loaded. Available: db"
+      binding.irb
+    end
+
+    desc "version", "Show version"
+    def version
+      puts "archsight #{Archsight::VERSION}"
+    end
+
+    default_task :version
+
+    private
+
+    def configure_resources
+      Archsight.resources_dir = options[:resources] if options[:resources]
+    end
+
+    def list_kinds
+      puts "Available resource kinds:\n\n"
+      Archsight::Resources.resource_classes.each_key { |kind| puts "  - #{kind}" }
+      puts "\nUsage: archsight template <kind>"
+    end
+
+    def display_error_with_context(error_string)
+      # Parse error to extract file path and line number
+      if error_string =~ /^(.+?):(\d+):/
+        file_path = ::Regexp.last_match(1)
+        line_number = ::Regexp.last_match(2).to_i
+        puts "\n#{error_string}"
+        show_file_context(file_path, line_number)
+      else
+        puts error_string
+      end
+    end
+
+    def show_file_context(file_path, line_number, context_lines: 3)
+      return unless File.exist?(file_path)
+
+      lines = File.readlines(file_path)
+      start_line = [line_number - context_lines - 1, 0].max
+      end_line = [line_number + context_lines - 1, lines.length - 1].min
+
+      puts ""
+      (start_line..end_line).each do |i|
+        line_num = i + 1
+        prefix = line_num == line_number ? ">> " : "   "
+        puts format("%s%4d | %s", prefix, line_num, lines[i])
+      end
+      puts ""
+    end
+  end
+end

data/lib/archsight/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Archsight
+  class Configuration
+    attr_accessor :resources_dir, :verbose, :verify, :compute_annotations
+
+    def initialize
+      @resources_dir = ENV["ARCHSIGHT_RESOURCES_DIR"] || Dir.pwd
+      @verbose = true
+      @verify = true
+      @compute_annotations = true
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def resources_dir
+      configuration.resources_dir
+    end
+
+    def resources_dir=(path)
+      configuration.resources_dir = File.absolute_path(path)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/archsight/database.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "graph"
+require_relative "resources"
+require_relative "query"
+
+module Archsight
+  # LineReference combines a path and line reference
+  class LineReference
+    attr_accessor :path, :line_no
+
+    def initialize(path, line_no)
+      @path = path
+      @line_no = line_no
+    end
+
+    def to_s
+      "#{@path}:#{@line_no}"
+    end
+
+    def at_line(line_no)
+      self.class.new(@path, line_no)
+    end
+  end
+
+  # ResourceError is an error with a path and line no attached
+  class ResourceError < StandardError
+    attr_reader :ref, :message
+
+    def initialize(msg, ref)
+      super(msg)
+      @message = msg
+      @ref = ref
+    end
+
+    def to_s
+      "#{ref}: #{super}"
+    end
+  end
+
+  # Database loads yaml files and folders to create an in-memory representation
+  # of the structure. The loading and parsing of files will raise errors
+  # if invalid data is passed.
+  class Database
+    attr_accessor :instances, :verbose, :verify, :compute_annotations
+
+    def initialize(path, verbose: false, verify: true, compute_annotations: true)
+      @path = path
+      @verbose = verbose
+      @verify = verify
+      @compute_annotations = compute_annotations
+      @instances = {}
+    end
+
+    def reload!
+      @instances = {}
+
+      # load all resources
+      Dir.glob(File.join(@path, "**/*.yaml")).each do |path|
+        @current_ref = LineReference.new(path, 0)
+        puts "parsing #{path}..." if @verbose
+        load_file(path)
+      end
+
+      verify! if @verify
+      compute_all_annotations! if @verify && @compute_annotations
+    rescue Psych::SyntaxError => e
+      # Wrap YAML syntax errors in ResourceError for consistent handling
+      ref = LineReference.new(e.file || @current_ref&.path || "unknown", e.line || 0)
+      Kernel.raise(ResourceError.new(e.problem || e.message, ref))
+    end
+
+    def instances_by_kind(kind)
+      @instances[Archsight::Resources[kind]] || {}
+    end
+
+    def instance_by_kind(kind, instance)
+      @instances[Archsight::Resources[kind]][instance]
+    end
+
+    # Collect unique annotation values across all instances of a kind
+    def annotation_values(kind, annotation)
+      instances = instances_by_kind(kind).values
+      values = instances.flat_map { |inst| Array(annotation.value_for(inst)) }
+      values.compact.uniq.sort
+    end
+
+    # Get filterable annotations with their values for a kind (excludes empty)
+    def filters_for_kind(kind)
+      klass = Archsight::Resources[kind]
+      return [] unless klass
+
+      klass.filterable_annotations
+           .map { |a| [a, annotation_values(kind, a)] }
+           .reject { |_, values| values.empty? }
+    end
+
+    # Execute a query string and return matching instances
+    def query(query_string)
+      q = Archsight::Query.parse(query_string)
+      q.filter(self)
+    end
+
+    # Check if a specific instance matches a query
+    def instance_matches?(instance, query_string)
+      q = Archsight::Query.parse(query_string)
+      q.matches?(instance, database: self)
+    end
+
+    private
+
+    def create_valid_instance(obj)
+      raise("invalid api version") if obj["apiVersion"] != "architecture/v1alpha1"
+
+      kind = obj["kind"] || raise("kind not defined")
+      klass = Archsight::Resources[kind] || raise("#{kind} is not a valid kind")
+      inst = klass.new(obj, @current_ref)
+      inst.name || raise("metadata name of #{kind} not present")
+      inst
+    end
+
+    def load_file(path)
+      File.open(path, "r") do |f|
+        YAML.parse_stream(f) do |node|
+          @current_ref = @current_ref.at_line(node.children.first.start_line)
+          obj = node.to_ruby
+          next unless obj # skip empty / unknown documents
+
+          self << create_valid_instance(obj)
+        end
+      end
+    end
+
+    def <<(inst)
+      inst.verify!
+      klass = inst.class
+      @instances[klass] ||= {}
+      if (existing_inst = @instances[klass][inst.name])
+        existing_inst.merge!(inst)
+      else
+        @instances[klass][inst.name] = inst
+      end
+    end
+
+    # raise provides a helper for better error messages including current path and line no
+    def raise(msg)
+      Kernel.raise(ResourceError.new(msg, @current_ref))
+    end
+
+    # raise_for provides error messages with the instance's path reference
+    def raise_for(inst, msg)
+      Kernel.raise(ResourceError.new(msg, inst.path_ref))
+    end
+
+    # verify and resolve relations between resources
+    def verify!
+      @instances.each_value do |instances|
+        instances.each_value do |inst|
+          verify_instance_relations!(inst)
+        end
+      end
+    end
+
+    def verify_instance_relations!(inst)
+      inst.class.relations.each do |verb, kind, klass_name|
+        rels = inst.relations(verb, kind).map do |rel_name|
+          rel_klass = Archsight::Resources[klass_name] || raise_for(inst, "#{klass_name} is not a valid relation kind")
+          kind_display = rel_klass.to_s.sub(/^Archsight::Resources::/, "")
+          @instances[rel_klass] || raise_for(inst, "#{rel_name} is not defined as kind #{kind_display}")
+          @instances[rel_klass][rel_name] || raise_for(inst, "#{rel_name} is not defined as kind #{kind_display}")
+        end
+        inst.set_relations(verb, kind, rels) unless rels.empty?
+      end
+    end
+
+    # Compute all computed annotations for all instances
+    def compute_all_annotations!
+      manager = Archsight::Annotations::ComputedManager.new(self)
+      manager.compute_all!
+    end
+  end
+end

data/lib/archsight/documentation.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "resources"
+require_relative "template"
+
+module Archsight
+  # Documentation generates markdown documentation for architecture resources
+  class Documentation
+    # Layer display order (top to bottom)
+    LAYER_ORDER = %w[motivation strategy business application technology].freeze
+
+    # Layer display names
+    LAYER_NAMES = {
+      "motivation" => "Motivation Layer",
+      "strategy" => "Strategy Layer",
+      "business" => "Business Layer",
+      "application" => "Application Layer",
+      "technology" => "Technology Layer"
+    }.freeze
+
+    # Resource kinds to exclude from the diagram
+    EXCLUDED_KINDS = %w[View].freeze
+
+    @mermaid_cache = nil
+
+    class << self
+      attr_accessor :mermaid_cache
+
+      # Generate mermaid flowchart diagram showing all resource types and relationships
+      # Results are cached for performance
+      # @return [String] Mermaid flowchart diagram
+      def generate_mermaid_diagram
+        return @mermaid_cache if @mermaid_cache
+
+        @mermaid_cache = build_mermaid_diagram
+      end
+
+      # Clear the mermaid cache (call when resources change)
+      def clear_cache
+        @mermaid_cache = nil
+      end
+
+      # Build the mermaid diagram from resource definitions
+      # Layer colors are defined in CSS (public/css/mermaid-layers.css)
+      def build_mermaid_diagram
+        lines = []
+        lines << "flowchart TB"
+
+        # Group resources by layer (excluding certain kinds)
+        resources_by_layer = Hash.new { |h, k| h[k] = [] }
+        Archsight::Resources.each do |kind_name|
+          next if EXCLUDED_KINDS.include?(kind_name.to_s)
+
+          klass = Archsight::Resources.const_get(kind_name)
+          layer = klass.layer
+          next unless LAYER_ORDER.include?(layer) # Skip resources in unlisted layers
+
+          resources_by_layer[layer] << kind_name.to_s
+        end
+
+        # Generate subgraphs for each layer in order
+        LAYER_ORDER.each do |layer|
+          next unless resources_by_layer.key?(layer)
+
+          kinds = resources_by_layer[layer].sort
+          next if kinds.empty?
+
+          lines << ""
+          lines << "    subgraph #{layer.capitalize}[\"#{LAYER_NAMES[layer]}\"]"
+          kinds.each do |kind|
+            lines << "        #{kind}:::#{layer}"
+          end
+          lines << "    end"
+        end
+
+        # Collect all relations and deduplicate
+        relations = collect_relations
+        lines << ""
+        relations.each do |from_kind, verb, to_kind|
+          lines << "    #{from_kind} -->|#{verb}| #{to_kind}"
+        end
+
+        # Add click handlers for each kind
+        lines << ""
+        all_kinds = resources_by_layer.values.flatten
+        all_kinds.sort.each do |kind_name|
+          lines << "    click #{kind_name} \"/kinds/#{kind_name}\""
+        end
+
+        lines.join("\n")
+      end
+
+      # Collect all unique relations from resource definitions
+      # @return [Array<Array>] Array of [from_kind, verb, to_kind] tuples
+      def collect_relations
+        relations = []
+        seen = Set.new
+
+        Archsight::Resources.each do |kind_name|
+          # Skip excluded kinds
+          next if EXCLUDED_KINDS.include?(kind_name.to_s)
+
+          klass = Archsight::Resources.const_get(kind_name)
+          # Skip kinds not in a displayed layer
+          next unless LAYER_ORDER.include?(klass.layer)
+
+          klass.relations.each do |verb, _relation_kind, target_klass|
+            # Skip relations to excluded kinds
+            next if EXCLUDED_KINDS.include?(target_klass.to_s)
+
+            key = "#{kind_name}|#{verb}|#{target_klass}"
+            next if seen.include?(key)
+
+            seen.add(key)
+            relations << [kind_name.to_s, verb.to_s.delete_prefix(":"), target_klass.to_s]
+          end
+        end
+
+        relations.sort_by { |from, verb, to| [from, to, verb] }
+      end
+
+      def generate(kind_name)
+        klass = Archsight::Resources[kind_name.to_s]
+        raise "Unknown resource kind '#{kind_name}'" unless klass
+
+        md = []
+        md << "# #{kind_name}\n"
+        md << klass.description if klass.description
+        md << "\n## Annotations\n"
+        md << generate_annotations_table(klass)
+        md << "\n## Relations\n"
+        md << generate_relations_table(klass)
+        md << "\n## Example\n"
+        md << "```yaml\n#{Archsight::Template.generate(kind_name)}```"
+        md.compact.join("\n")
+      end
+
+      def generate_annotations_table(klass)
+        annotations = klass.annotations.reject(&:pattern?)
+        return "_No annotations defined._" if annotations.empty?
+
+        rows = ["| Annotation | Description | Values |", "|------------|-------------|--------|"]
+        annotations.each do |a|
+          values = format_values(a)
+          rows << "| `#{a.key}` | #{a.description || "-"} | #{values} |"
+        end
+        rows.join("\n")
+      end
+
+      def generate_relations_table(klass)
+        return "_No relations defined._" if klass.relations.empty?
+
+        rows = ["| Relation | Target | Kind |", "|----------|--------|------|"]
+        klass.relations.each do |verb, kind, target_klass|
+          rows << "| #{verb} | #{target_klass} | #{kind} |"
+        end
+        rows.join("\n")
+      end
+
+      def format_values(annotation)
+        if annotation.enum
+          annotation.enum.join(", ")
+        elsif annotation.type
+          annotation.type.to_s.split("::").last
+        else
+          "-"
+        end
+      end
+    end
+  end
+end