archsight 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5daf787a0535e787bb31a5abbe46e8da7621256e710dd59ec7328c116b988df4
-  data.tar.gz: e662425404ec865eef3701723135c103e688e43bb8d560708f936dd9021acd88
+  metadata.gz: 697c02b1e33af4fde32636af6020b7ab6513245216b694453d03dab186f0dd99
+  data.tar.gz: 58a8cd9b7e530796d04424f885e931863a1bf6ed2c2d0366bf76d28453eb80fb
 SHA512:
-  metadata.gz: c31f6486348cd3e4e2b3a8247071f3f1ddbe139b0cb20faeba51167122d860d74cf205128532d6184ac78a9eac5be64ccee28c41dec9fff094963d77e1ee34bc
-  data.tar.gz: cb36b1eb48ed9c44985925e2e54ffa7c74d66ee51ca0407882151db27ce34168f747dc9cb4aadbfe35c19d1fb5c5a1b3860741635a6a342a810faac926638885
+  metadata.gz: a80fc22f8b7030c71cb2422b839521e96f31ecced71386ed075c51d9ca2d53d2a057ced240a4085ad032c895ce8526d44a585b6970c67f2217fe15232a2209cd
+  data.tar.gz: 3d0648dca25e6337679d6a236b256b5580d9a5260df927a792680e5e9187e289b0c781aa36d0fb81893fea3889e57b7ec1b7a397d731039d5f5dcbebdff2f587

data/README.md

@@ -44,6 +44,9 @@ Access at: <http://localhost:4567>
 # Run web server (default)
 docker run -p 4567:4567 -v "/path/to/resources:/resources" ghcr.io/ionos-cloud/archsight
 
+# Run in production mode with logging
+docker run -p 4567:4567 -v "/path/to/resources:/resources" ghcr.io/ionos-cloud/archsight web --production
+
 # Run lint
 docker run -v "/path/to/resources:/resources" ghcr.io/ionos-cloud/archsight lint -r /resources
 
@@ -62,13 +65,31 @@ Access web interface at: <http://localhost:4567>
 ## CLI Commands
 
 ```bash
-archsight web [--resources PATH] [--port PORT]  # Start web server
-archsight lint [--resources PATH]               # Validate YAML and relations
-archsight template KIND                         # Generate YAML template for a resource type
-archsight console [--resources PATH]            # Interactive Ruby console
-archsight version                               # Show version
+archsight web [OPTIONS]      # Start web server
+archsight lint               # Validate YAML and relations
+archsight import             # Execute pending imports
+archsight analyze            # Execute analysis scripts
+archsight template KIND      # Generate YAML template for a resource type
+archsight console            # Interactive Ruby console
+archsight version            # Show version
+```
+
+### Web Server Options
+
+```bash
+archsight web [--resources PATH] [--port PORT] [--host HOST]
+              [--production] [--disable-reload] [--enable-logging]
 ```
 
+| Option | Description |
+|--------|-------------|
+| `-r, --resources PATH` | Path to resources directory |
+| `-p, --port PORT` | Port to listen on (default: 4567) |
+| `-H, --host HOST` | Host to bind to (default: localhost) |
+| `--production` | Run in production mode (quiet startup) |
+| `--disable-reload` | Disable the reload button in the UI |
+| `--enable-logging` | Enable request logging (default: false in dev, true in prod) |
+
 ## Features
 
 ### MCP Server

data/lib/archsight/analysis/executor.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "sandbox"
+require_relative "result"
+
+module Archsight
+  module Analysis
+    # Executor runs Analysis scripts in a sandboxed environment with timeout enforcement
+    class Executor
+      # Default timeout in seconds
+      DEFAULT_TIMEOUT = 30
+
+      # Duration parsing patterns
+      DURATION_PATTERNS = {
+        /^(\d+)s$/ => 1,
+        /^(\d+)m$/ => 60,
+        /^(\d+)h$/ => 3600
+      }.freeze
+
+      attr_reader :database
+
+      # @param database [Archsight::Database] Loaded database instance
+      def initialize(database)
+        @database = database
+      end
+
+      # Execute an Analysis resource
+      # @param analysis [Archsight::Resources::Analysis] Analysis to execute
+      # @return [Archsight::Analysis::Result] Execution result
+      def execute(analysis)
+        script = analysis.annotations["analysis/script"]
+        timeout_seconds = parse_timeout(analysis.annotations["analysis/timeout"])
+
+        return Result.new(analysis, success: false, error: "No script defined") if script.nil? || script.empty?
+
+        sandbox = Sandbox.new(@database)
+        sandbox._set_analysis(analysis)
+
+        start_time = Time.now
+        begin
+          Timeout.timeout(timeout_seconds) do
+            # Execute script in sandbox context
+            # Using instance_eval ensures script only has access to sandbox methods
+            sandbox.instance_eval(script, "analysis:#{analysis.name}", 1)
+          end
+
+          duration = Time.now - start_time
+          Result.new(
+            analysis,
+            success: true,
+            sections: sandbox.sections,
+            duration: duration
+          )
+        rescue Timeout::Error
+          Result.new(
+            analysis,
+            success: false,
+            error: "Execution timed out after #{timeout_seconds}s",
+            sections: sandbox.sections
+          )
+        rescue StandardError, SyntaxError => e
+          Result.new(
+            analysis,
+            success: false,
+            error: "#{e.class}: #{e.message}",
+            error_backtrace: e.backtrace&.first(5),
+            sections: sandbox.sections
+          )
+        end
+      end
+
+      # Execute all enabled Analysis resources
+      # @param filter [Regexp, nil] Optional filter for analysis names
+      # @return [Array<Archsight::Analysis::Result>] Array of results
+      def execute_all(filter: nil)
+        analyses = @database.instances_by_kind("Analysis").values
+
+        # Filter by name pattern if provided
+        analyses = analyses.select { |a| filter.match?(a.name) } if filter
+
+        # Filter to enabled analyses
+        analyses = analyses.select { |a| analysis_enabled?(a) }
+
+        analyses.map { |analysis| execute(analysis) }
+      end
+
+      private
+
+      # Parse timeout string to seconds
+      # @param timeout_str [String, nil] Timeout string (e.g., "30s", "5m")
+      # @return [Integer] Timeout in seconds
+      def parse_timeout(timeout_str)
+        return DEFAULT_TIMEOUT if timeout_str.nil? || timeout_str.empty?
+
+        DURATION_PATTERNS.each do |pattern, multiplier|
+          match = timeout_str.match(pattern)
+          return match[1].to_i * multiplier if match
+        end
+
+        DEFAULT_TIMEOUT
+      end
+
+      # Check if analysis is enabled
+      # @param analysis [Object] Analysis instance
+      # @return [Boolean] true if enabled
+      def analysis_enabled?(analysis)
+        analysis.annotations["analysis/enabled"] != "false"
+      end
+    end
+  end
+end

data/lib/archsight/analysis/result.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Analysis
+    # Result represents the outcome of an Analysis execution
+    class Result
+      attr_reader :analysis, :success, :error, :error_backtrace, :sections, :duration
+
+      # @param analysis [Object] The Analysis resource that was executed
+      # @param success [Boolean] Whether execution completed successfully
+      # @param error [String, nil] Error message if execution failed
+      # @param error_backtrace [Array<String>, nil] Backtrace if execution failed
+      # @param sections [Array<Hash>] Output sections generated during execution
+      # @param duration [Float, nil] Execution duration in seconds
+      def initialize(analysis, success:, error: nil, error_backtrace: nil, sections: [], duration: nil)
+        @analysis = analysis
+        @success = success
+        @error = error
+        @error_backtrace = error_backtrace
+        @sections = sections || []
+        @duration = duration
+      end
+
+      # @return [Boolean] true if execution succeeded
+      def success?
+        @success
+      end
+
+      # @return [Boolean] true if execution failed
+      def failed?
+        !@success
+      end
+
+      # @return [String] Analysis name
+      def name
+        @analysis.name
+      end
+
+      # @return [Boolean] true if any content sections exist (excluding messages)
+      def has_findings?
+        @sections.any? { |s| %i[table list text heading code].include?(s[:type]) }
+      end
+
+      # @return [Integer] Count of error-level messages
+      def error_count
+        @sections.count { |s| s[:type] == :message && s[:level] == :error }
+      end
+
+      # @return [Integer] Count of warning-level messages
+      def warning_count
+        @sections.count { |s| s[:type] == :message && s[:level] == :warning }
+      end
+
+      # Convert result to markdown (only script-generated content)
+      # @param verbose [Boolean] Include detailed output
+      # @return [String] Markdown formatted output
+      def to_markdown(verbose: false)
+        format_sections_markdown(verbose).compact.join("\n\n")
+      end
+
+      # Render markdown for CLI display using tty-markdown
+      # @param verbose [Boolean] Include detailed output
+      # @return [String] Rendered output for terminal
+      def render(verbose: false)
+        require "tty-markdown"
+        md = to_markdown(verbose: verbose)
+        md.empty? ? "" : TTY::Markdown.parse(md)
+      rescue LoadError
+        # Fallback to plain markdown if tty-markdown not available
+        to_markdown(verbose: verbose)
+      end
+
+      # Format result for console output (backward compatible)
+      # @param verbose [Boolean] Include detailed output
+      # @return [String] Formatted output
+      def to_s(verbose: false)
+        render(verbose: verbose)
+      end
+
+      # Status emoji for display
+      # @return [String] Status emoji
+      def status_emoji
+        return "❌" unless success?
+
+        has_findings? ? "⚠️" : "✅"
+      end
+
+      # Formatted duration string
+      # @return [String] Duration string or empty
+      def duration_str
+        @duration ? format("%.2fs", @duration) : ""
+      end
+
+      # Error details as markdown (for CLI to use if needed)
+      # @param verbose [Boolean] Include backtrace
+      # @return [String, nil] Error markdown or nil
+      def error_markdown(verbose: false)
+        return nil unless failed?
+
+        lines = ["**Error:** #{@error}"]
+        if verbose && @error_backtrace&.any?
+          lines << ""
+          lines << "```"
+          lines.concat(@error_backtrace)
+          lines << "```"
+        end
+        lines.join("\n")
+      end
+
+      private
+
+      def format_sections_markdown(verbose)
+        @sections.map { |section| format_section_markdown(section, verbose) }.compact
+      end
+
+      def format_section_markdown(section, verbose)
+        case section[:type]
+        when :message then format_message_markdown(section)
+        when :heading then format_heading_markdown(section)
+        when :text then section[:content]
+        when :table then format_table_markdown(section, verbose)
+        when :list then format_list_markdown(section, verbose)
+        when :code then format_code_markdown(section)
+        end
+      end
+
+      def format_message_markdown(section)
+        emoji = { error: "🔴", warning: "🟡", info: "🔵" }.fetch(section[:level], "ℹ️")
+        "#{emoji} #{section[:message]}"
+      end
+
+      def format_heading_markdown(section)
+        "#{"#" * (section[:level] + 1)} #{section[:text]}"
+      end
+
+      def format_table_markdown(section, verbose)
+        headers = section[:headers]
+        rows = section[:rows]
+
+        # Limit rows if not verbose
+        display_rows = verbose ? rows : rows.first(10)
+        truncated = !verbose && rows.size > 10
+
+        lines = []
+        lines << "| #{headers.join(" | ")} |"
+        lines << "| #{headers.map { "---" }.join(" | ")} |"
+        display_rows.each do |row|
+          lines << "| #{row.map { |cell| cell.to_s.gsub("|", "\\|") }.join(" | ")} |"
+        end
+        lines << "_...and #{rows.size - 10} more rows_" if truncated
+
+        lines.join("\n")
+      end
+
+      def format_list_markdown(section, verbose)
+        items = section[:items]
+
+        # Limit items if not verbose
+        display_items = verbose ? items : items.first(10)
+        truncated = !verbose && items.size > 10
+
+        lines = display_items.map { |item| "- #{item}" }
+        lines << "_...and #{items.size - 10} more items_" if truncated
+
+        lines.join("\n")
+      end
+
+      def format_code_markdown(section)
+        lang = section[:lang] || ""
+        "```#{lang}\n#{section[:content]}\n```"
+      end
+    end
+  end
+end

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",