archsight 0.1.1 → 0.1.3

data/lib/archsight/analysis/sandbox.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require_relative "../annotations/relation_resolver"
+
+module Archsight
+  module Analysis
+    # Sandbox provides a safe execution context for Analysis scripts.
+    # Scripts are evaluated via instance_eval with access only to
+    # explicitly defined methods.
+    class Sandbox
+      # Output sections collected during script execution
+      attr_reader :sections
+
+      def initialize(database)
+        @database = database
+        @sections = []
+        @resolver_cache = {}
+      end
+
+      # Instance iteration methods
+
+      # Iterate over all instances of a kind
+      # @param kind [Symbol, String] Resource kind (e.g., :ApplicationService)
+      # @yield [instance] Block called for each instance
+      def each_instance(kind, &)
+        instances(kind).each(&)
+      end
+
+      # Get all instances of a kind
+      # @param kind [Symbol, String] Resource kind
+      # @return [Array] Array of instances
+      def instances(kind)
+        @database.instances_by_kind(kind.to_s).values
+      end
+
+      # Get a specific instance by kind and name
+      # @param kind [Symbol, String] Resource kind
+      # @param name [String] Instance name
+      # @return [Object, nil] Instance or nil if not found
+      def instance(kind, name)
+        @database.instance_by_kind(kind.to_s, name)
+      end
+
+      # Relation traversal methods (reuse ComputedRelationResolver)
+
+      # Get direct outgoing relations
+      # @param inst [Object] Source instance
+      # @param kind [Symbol, nil] Optional kind filter
+      # @return [Array] Related instances
+      def outgoing(inst, kind = nil)
+        resolver_for(inst).outgoing(kind)
+      end
+
+      # Get transitive outgoing relations
+      # @param inst [Object] Source instance
+      # @param kind [Symbol, nil] Optional kind filter
+      # @param max_depth [Integer] Maximum traversal depth
+      # @return [Array] Transitively related instances
+      def outgoing_transitive(inst, kind = nil, max_depth: 10)
+        resolver_for(inst).outgoing_transitive(kind, max_depth: max_depth)
+      end
+
+      # Get direct incoming relations (instances that reference this one)
+      # @param inst [Object] Target instance
+      # @param kind [Symbol, nil] Optional kind filter
+      # @return [Array] Instances referencing this one
+      def incoming(inst, kind = nil)
+        resolver_for(inst).incoming(kind)
+      end
+
+      # Get transitive incoming relations
+      # @param inst [Object] Target instance
+      # @param kind [Symbol, nil] Optional kind filter
+      # @param max_depth [Integer] Maximum traversal depth
+      # @return [Array] Instances transitively referencing this one
+      def incoming_transitive(inst, kind = nil, max_depth: 10)
+        resolver_for(inst).incoming_transitive(kind, max_depth: max_depth)
+      end
+
+      # Data access methods
+
+      # Get an annotation value from an instance
+      # @param inst [Object] Instance
+      # @param key [String] Annotation key
+      # @return [Object, nil] Annotation value
+      def annotation(inst, key)
+        inst.annotations[key]
+      end
+
+      # Get all annotations from an instance (frozen copy)
+      # @param inst [Object] Instance
+      # @return [Hash] Frozen hash of annotations
+      def annotations(inst)
+        inst.annotations.dup.freeze
+      end
+
+      # Get the name of an instance
+      # @param inst [Object] Instance
+      # @return [String] Instance name
+      def name(inst)
+        inst.name
+      end
+
+      # Get the kind of an instance
+      # @param inst [Object] Instance
+      # @return [String] Instance kind
+      def kind(inst)
+        inst.klass
+      end
+
+      # Query method
+
+      # Execute a query string
+      # @param query_string [String] Query string
+      # @return [Array] Matching instances
+      def query(query_string)
+        @database.query(query_string)
+      end
+
+      # Aggregation methods
+
+      # Sum numeric values
+      # @param values [Array<Numeric>] Values to sum
+      # @return [Numeric] Sum
+      def sum(values)
+        values.compact.sum
+      end
+
+      # Count items
+      # @param items [Array] Items to count
+      # @return [Integer] Count
+      def count(items)
+        items.compact.count
+      end
+
+      # Calculate average
+      # @param values [Array<Numeric>] Values to average
+      # @return [Float, nil] Average or nil if empty
+      def avg(values)
+        compact = values.compact
+        return nil if compact.empty?
+
+        compact.sum.to_f / compact.size
+      end
+
+      # Find minimum value
+      # @param values [Array<Numeric>] Values
+      # @return [Numeric, nil] Minimum
+      def min(values)
+        values.compact.min
+      end
+
+      # Find maximum value
+      # @param values [Array<Numeric>] Values
+      # @return [Numeric, nil] Maximum
+      def max(values)
+        values.compact.max
+      end
+
+      # Collect values into array
+      # @param items [Array] Items
+      # @param key [String, Symbol, nil] Optional key to extract
+      # @yield [item] Optional block to transform items
+      # @return [Array] Collected values
+      def collect(items, key = nil, &block)
+        if block
+          items.map(&block).compact
+        elsif key
+          items.map { |item| item.respond_to?(key) ? item.send(key) : item.annotations[key.to_s] }.compact
+        else
+          items.compact
+        end
+      end
+
+      # Group items by a key
+      # @param items [Array] Items to group
+      # @yield [item] Block that returns the grouping key
+      # @return [Hash] Grouped items
+      def group_by(items, &)
+        items.group_by(&)
+      end
+
+      # Output methods - Structured content building
+
+      # Add a heading
+      # @param text [String] Heading text
+      # @param level [Integer] Heading level (0-6, default 0)
+      #   Level 0 creates accordion sections in the web UI
+      #   Levels 1-6 map to HTML h2-h6 within sections
+      def heading(text, level: 0)
+        @sections << { type: :heading, text: text, level: level.clamp(0, 6) }
+      end
+
+      # Add a text paragraph
+      # @param content [String] Text content (supports markdown)
+      def text(content)
+        @sections << { type: :text, content: content }
+      end
+
+      # Add a table
+      # @param headers [Array<String>] Column headers
+      # @param rows [Array<Array>] Table rows (each row is an array of values)
+      def table(headers:, rows:)
+        return if rows.empty?
+
+        @sections << { type: :table, headers: headers, rows: rows }
+      end
+
+      # Add a bullet list
+      # @param items [Array<String, Hash>] List items (strings or hashes with :text key)
+      def list(items)
+        return if items.empty?
+
+        @sections << { type: :list, items: items }
+      end
+
+      # Add a code block
+      # @param content [String] Code content
+      # @param lang [String] Language for syntax highlighting (default: plain)
+      def code(content, lang: "")
+        @sections << { type: :code, content: content, lang: lang }
+      end
+
+      # Legacy output methods - still supported for backward compatibility
+
+      # Report findings (legacy method - creates appropriate section based on data type)
+      # @param data [Object] Report data (usually Array or Hash)
+      # @param title [String, nil] Optional report title
+      def report(data, title: nil)
+        heading(title, level: 1) if title
+
+        case data
+        when Array
+          report_array(data)
+        when Hash
+          report_hash(data)
+        else
+          text(data.to_s)
+        end
+      end
+
+      # Log a warning message
+      # @param message [String] Warning message
+      def warning(message)
+        @sections << { type: :message, level: :warning, message: message }
+      end
+
+      # Log an error message
+      # @param message [String] Error message
+      def error(message)
+        @sections << { type: :message, level: :error, message: message }
+      end
+
+      # Log an info message
+      # @param message [String] Info message
+      def info(message)
+        @sections << { type: :message, level: :info, message: message }
+      end
+
+      # Configuration access
+
+      # Get a configuration value from the analysis
+      # @param key [String] Configuration key (without 'analysis/config/' prefix)
+      # @return [Object, nil] Configuration value
+      def config(key)
+        @current_analysis&.annotations&.[]("analysis/config/#{key}")
+      end
+
+      # Set the current analysis being executed (called by Executor)
+      # @param analysis [Object] Analysis instance
+      # @api private
+      def _set_analysis(analysis)
+        @current_analysis = analysis
+      end
+
+      private
+
+      # Get or create a relation resolver for an instance
+      def resolver_for(inst)
+        @resolver_cache[inst.name] ||= Archsight::Annotations::ComputedRelationResolver.new(inst, @database)
+      end
+
+      # Report an array - auto-detect if it's a table or list
+      def report_array(data)
+        return if data.empty?
+
+        # If array of hashes with consistent keys, render as table
+        if data.all? { |item| item.is_a?(Hash) }
+          keys = data.first.keys
+          if data.all? { |item| item.keys == keys }
+            table(headers: keys.map(&:to_s), rows: data.map { |item| keys.map { |k| item[k] } })
+            return
+          end
+        end
+
+        # Otherwise render as list
+        list(data.map { |item| format_list_item(item) })
+      end
+
+      # Report a hash - render as definition list or table
+      def report_hash(data)
+        return if data.empty?
+
+        # Render as simple key-value list
+        list(data.map { |k, v| "**#{k}:** #{v}" })
+      end
+
+      # Format a list item for display
+      def format_list_item(item)
+        case item
+        when Hash
+          item.map { |k, v| "#{k}=#{v}" }.join(", ")
+        else
+          item.to_s
+        end
+      end
+    end
+  end
+end

data/lib/archsight/analysis.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Archsight
+  # Analysis module provides sandboxed execution of Analysis scripts
+  module Analysis
+  end
+end
+
+require_relative "analysis/result"
+require_relative "analysis/sandbox"
+require_relative "analysis/executor"

data/lib/archsight/annotations/architecture_annotations.rb

@@ -46,9 +46,9 @@ module Archsight::Annotations::Architecture
                  filter: :word,
                  title: "Status"
       annotation "architecture/visibility",
-                 description: "API visibility (public, private)",
+                 description: "API visibility (public, private, internal)",
                  filter: :word,
-                 enum: %w[public private],
+                 enum: %w[public private internal],
                  title: "Visibility"
       annotation "architecture/applicationSets",
                  description: "Related ArgoCD ApplicationSets",

data/lib/archsight/cli.rb

@@ -4,6 +4,10 @@ require "thor"
 
 module Archsight
   class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
     class_option :resources,
                  aliases: "-r",
                  type: :string,
@@ -12,10 +16,21 @@ module Archsight
     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"
+    option :production, type: :boolean, default: false, desc: "Run in production mode"
+    option :disable_reload, type: :boolean, default: false, desc: "Disable the reload button in the UI"
+    option :enable_logging, type: :boolean, default: nil, desc: "Enable request logging (default: false in dev, true in prod)"
     def web
       configure_resources
       require "archsight/web/application"
+
+      env = options[:production] ? :production : :development
+      Archsight::Web::Application.configure_environment!(env, logging: options[:enable_logging])
+      Archsight::Web::Application.set :reload_enabled, !options[:disable_reload]
+      Archsight::Web::Application.setup_mcp!
       Archsight::Web::Application.run!(port: options[:port], bind: options[:host])
+    rescue Archsight::ResourceError => e
+      display_error_with_context(e.to_s)
+      exit 1
     end
 
     desc "lint", "Validate architecture resources"
@@ -70,6 +85,80 @@ module Archsight
       binding.irb
     end
 
+    desc "import", "Execute pending imports"
+    option :verbose, aliases: "-v", type: :boolean, default: false, desc: "Verbose output"
+    option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Show execution plan without running"
+    option :filter, aliases: "-f", type: :string, desc: "Filter imports by name (regex pattern)"
+    option :force, aliases: "-F", type: :boolean, default: false, desc: "Ignore cache and re-run all imports"
+    def import
+      configure_resources
+      require "archsight/database"
+      require "archsight/import/executor"
+
+      resources_dir = Archsight.resources_dir
+
+      # Load all handlers
+      require_import_handlers
+
+      # Create database that loads from resources directory
+      # Only load Import resources to avoid validation errors on incomplete resources
+      db = Archsight::Database.new(resources_dir, verbose: options[:verbose], only_kinds: ["Import"], verify: false)
+
+      if options[:dry_run]
+        puts "Execution Plan:"
+        executor = Archsight::Import::Executor.new(
+          database: db,
+          resources_dir: resources_dir,
+          verbose: true,
+          filter: options[:filter],
+          force: options[:force]
+        )
+        executor.execution_plan
+      else
+        executor = Archsight::Import::Executor.new(
+          database: db,
+          resources_dir: resources_dir,
+          verbose: options[:verbose],
+          filter: options[:filter],
+          force: options[:force]
+        )
+        executor.run!
+        puts "All imports completed successfully."
+      end
+    rescue Archsight::Import::InterruptedError
+      # Graceful shutdown already handled by executor
+      exit 130
+    rescue Archsight::Import::DeadlockError => e
+      puts "Error: #{e.message}"
+      exit 1
+    rescue Archsight::Import::ImportError => e
+      puts "Error: #{e.message}"
+      exit 1
+    rescue Archsight::ResourceError => e
+      display_error_with_context(e.to_s)
+      exit 1
+    end
+
+    desc "analyze", "Execute analysis scripts"
+    option :verbose, aliases: "-v", type: :boolean, default: false, desc: "Verbose output"
+    option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "List analyses without running"
+    option :filter, aliases: "-f", type: :string, desc: "Filter analyses by name (regex pattern)"
+    def analyze
+      configure_resources
+      require "archsight/database"
+      require "archsight/analysis"
+
+      db = load_database_for_analysis
+      analyses = filter_analyses(db)
+
+      return puts("No analyses found#{" matching '#{options[:filter]}'" if options[:filter]}.") if analyses.empty?
+      return print_analysis_dry_run(analyses) if options[:dry_run]
+
+      results = execute_analyses(db, analyses)
+      print_analysis_results(results)
+      exit 1 if results.any?(&:failed?)
+    end
+
     desc "version", "Show version"
     def version
       puts "archsight #{Archsight::VERSION}"
@@ -83,6 +172,81 @@ module Archsight
       Archsight.resources_dir = options[:resources] if options[:resources]
     end
 
+    def require_import_handlers
+      handlers_dir = File.expand_path("import/handlers", __dir__)
+      Dir.glob(File.join(handlers_dir, "*.rb")).each do |handler_file|
+        require handler_file
+      end
+    end
+
+    def load_database_for_analysis
+      db = Archsight::Database.new(Archsight.resources_dir, verbose: options[:verbose])
+      db.reload!
+      db
+    rescue Archsight::ResourceError => e
+      display_error_with_context(e.to_s)
+      exit 1
+    end
+
+    def filter_analyses(db)
+      analyses = db.instances_by_kind("Analysis").values
+      analyses = analyses.select { |a| Regexp.new(options[:filter], Regexp::IGNORECASE).match?(a.name) } if options[:filter]
+      analyses.reject { |a| a.annotations["analysis/enabled"] == "false" }
+    end
+
+    def print_analysis_dry_run(analyses)
+      puts "Analyses to run#{" (filter: #{options[:filter]})" if options[:filter]}:"
+      analyses.sort_by(&:name).each_with_index do |analysis, idx|
+        timeout = analysis.annotations["analysis/timeout"] || "30s"
+        desc = analysis.annotations["analysis/description"] || "(no description)"
+        puts "  #{idx + 1}. #{analysis.name} [#{timeout}]"
+        puts "     #{desc}"
+      end
+    end
+
+    def execute_analyses(db, analyses)
+      executor = Archsight::Analysis::Executor.new(db)
+      analyses.map { |analysis| executor.execute(analysis) }
+    end
+
+    def print_analysis_results(results)
+      require "tty-markdown"
+
+      results.each do |result|
+        print_single_result(result)
+        puts ""
+      end
+
+      summary_md = build_analysis_summary_markdown(results)
+      puts TTY::Markdown.parse(summary_md)
+    end
+
+    def print_single_result(result)
+      # Print status header
+      header = "# #{result.status_emoji} #{result.name}"
+      header += " (#{result.duration_str})" unless result.duration_str.empty?
+      puts TTY::Markdown.parse(header)
+
+      # Print error if failed
+      puts TTY::Markdown.parse(result.error_markdown(verbose: options[:verbose])) if result.failed?
+
+      # Print script output
+      output = result.to_s(verbose: options[:verbose])
+      puts output unless output.empty?
+    end
+
+    def build_analysis_summary_markdown(results)
+      passed = results.count(&:success?)
+      failed = results.count(&:failed?)
+      with_findings = results.count(&:has_findings?)
+
+      lines = ["---", "", "# Summary", ""]
+      lines << "- ✅ **#{passed}** passed"
+      lines << "- ❌ **#{failed}** failed" if failed.positive?
+      lines << "- ⚠️ **#{with_findings}** with findings" if with_findings.positive?
+      lines.join("\n")
+    end
+
     def list_kinds
       puts "Available resource kinds:\n\n"
       Archsight::Resources.resource_classes.each_key { |kind| puts "  - #{kind}" }

data/lib/archsight/database.rb

@@ -43,13 +43,14 @@ module Archsight
   # 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
+    attr_accessor :instances, :verbose, :verify, :compute_annotations, :only_kinds
 
-    def initialize(path, verbose: false, verify: true, compute_annotations: true)
+    def initialize(path, verbose: false, verify: true, compute_annotations: true, only_kinds: nil)
       @path = path
       @verbose = verbose
       @verify = verify
       @compute_annotations = compute_annotations
+      @only_kinds = only_kinds
       @instances = {}
     end
 
@@ -127,6 +128,9 @@ module Archsight
           obj = node.to_ruby
           next unless obj # skip empty / unknown documents
 
+          # Skip resources that don't match only_kinds filter
+          next if @only_kinds && !@only_kinds.include?(obj["kind"])
+
           self << create_valid_instance(obj)
         end
       end

data/lib/archsight/helpers/analysis_renderer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module Archsight
+  module Helpers
+    # AnalysisRenderer provides HTML rendering for analysis result sections
+    module AnalysisRenderer
+      module_function
+
+      # HTML escape helper
+      def escape_html(text)
+        Rack::Utils.escape_html(text.to_s)
+      end
+
+      # Render a single analysis section to HTML
+      # @param section [Hash] Section data with :type and content
+      # @param markdown_renderer [Proc, nil] Optional proc to render markdown
+      def render_analysis_section(section, markdown_renderer: nil)
+        case section[:type]
+        when :heading
+          render_heading(section)
+        when :text
+          render_text(section, markdown_renderer)
+        when :message
+          render_message(section)
+        when :table
+          render_table(section)
+        when :list
+          render_list(section)
+        when :code
+          render_code(section)
+        else
+          ""
+        end
+      end
+
+      # Render analysis table section to HTML
+      def render_analysis_table(section)
+        render_table(section)
+      end
+
+      # Private rendering methods
+
+      def render_heading(section)
+        %(<div class="analysis-heading level-#{section[:level]}">#{escape_html(section[:text])}</div>)
+      end
+
+      def render_text(section, markdown_renderer)
+        content = markdown_renderer ? markdown_renderer.call(section[:content]) : escape_html(section[:content])
+        %(<div class="analysis-text">#{content}</div>)
+      end
+
+      def render_message(section)
+        icon = case section[:level]
+               when :error then "xmark-circle"
+               when :warning then "warning-triangle"
+               else "info-circle"
+               end
+        %(<div class="analysis-message message-#{section[:level]}"><i class="iconoir-#{icon}"></i> #{escape_html(section[:message])}</div>)
+      end
+
+      def render_table(section)
+        headers = section[:headers].map { |h| "<th>#{escape_html(h)}</th>" }.join
+        rows = section[:rows].map do |row|
+          cells = row.map { |cell| "<td>#{escape_html(cell.to_s)}</td>" }.join
+          "<tr>#{cells}</tr>"
+        end.join
+        %(<div class="analysis-table-wrapper"><table><thead><tr>#{headers}</tr></thead><tbody>#{rows}</tbody></table></div>)
+      end
+
+      def render_list(section)
+        items = section[:items].map { |item| "<li>#{escape_html(item)}</li>" }.join
+        %(<ul class="analysis-list">#{items}</ul>)
+      end
+
+      def render_code(section)
+        lang_class = section[:lang] ? " class=\"language-#{section[:lang]}\"" : ""
+        %(<pre class="code"><code#{lang_class}>#{escape_html(section[:content])}</code></pre>)
+      end
+    end
+  end
+end