archsight 0.1.0

data/lib/archsight/graph.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Archsight
+  # Graphvis implements a graphviz abstraction
+  class Graphvis
+    def initialize(name, renderer = :dot, attrs = {})
+      @name = name
+      @renderer = renderer.to_s
+      @attrs = { rankdir: :LR }.merge(attrs)
+    end
+
+    def draw_and_render_file(&block)
+      File.open("#{@name}.dot", "w") do |f|
+        render(f, &block)
+      end
+      system "#{@renderer} -Tpng #{@name}.dot -o #{@name}.png"
+    end
+
+    def draw_dot(&)
+      f = StringIO.new
+      render(f, &)
+      f.string
+    end
+
+    def draw_svg(&block)
+      IO.popen([@renderer, "-Tsvg"], "r+") do |pipe|
+        render(pipe, &block)
+        pipe.close_write
+        pipe.read
+      end
+    end
+
+    def render(file)
+      @file = file
+      file.puts "digraph G {"
+      @attrs.each do |k, v|
+        @file.puts " #{k.to_s.inspect} = #{value v};"
+      end
+      yield(self)
+      file.puts "}"
+    end
+
+    def node(name, attrs = {})
+      @file.print "  #{name.inspect} ["
+      attrs.each do |k, v|
+        @file.print " #{k.to_s.inspect} = #{value v}"
+      end
+      @file.puts " ];"
+    end
+
+    def edge(node_a, node_b, attrs = {})
+      @file.print "  #{node_a.inspect} -> #{node_b.inspect} ["
+      attrs.each do |k, v|
+        @file.print " #{k.to_s.inspect} = #{value v}"
+      end
+      @file.puts " ];"
+    end
+
+    def subgraph(name, attrs)
+      @file.puts "  subgraph #{name.inspect} {"
+      attrs.each do |k, v|
+        @file.puts " #{k.to_s.inspect} = #{value v};"
+      end
+      yield(self)
+      @file.puts "  }"
+    end
+
+    def value(val)
+      val = val.to_s
+      val =~ /^<.*>$/ ? "<#{val}>" : val.inspect
+    end
+
+    def same_rank
+      @file.puts "  { rank = same; "
+      yield(self)
+      @file.puts "  }"
+    end
+  end
+
+  # GraphvisHelper for generating graphs using javascript and wasm
+  module GraphvisHelper
+    def graphviz_svg(dot, element_id)
+      format(%{
+        <script type="module">
+          import { Graphviz } from "https://cdn.jsdelivr.net/npm/@hpcc-js/wasm/dist/index.js";
+          if (Graphviz) {
+            const re =/<svg width="([^"]+)pt" height="([^"]+)pt"/;
+            const graphviz = await Graphviz.load();
+            const dot = %s;
+            let svg = graphviz.layout(dot, "svg", "dot");
+            svg = svg.replace(re, "<svg");
+            svg = svg.replace(/<polygon fill="white"[^>]*>/, "");
+            svg = svg.replace(/fill="white"/g, 'fill="none"');
+
+            const parser = new DOMParser();
+            const svgDoc = parser.parseFromString(svg, "image/svg+xml");
+            const svgElement = svgDoc.querySelector("svg");
+
+            const cssResponse = await fetch("/css/graph.css?" + Date.now());
+            const cssText = await cssResponse.text();
+            const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
+            style.textContent = cssText;
+            svgElement.insertBefore(style, svgElement.firstChild);
+
+            document.getElementById(%s).innerHTML = svgElement.outerHTML;
+            // Dispatch event to notify GraphViewer that SVG is ready
+            document.dispatchEvent(new CustomEvent('graphviz:ready', { detail: { elementId: %s } }));
+          }
+        </script>
+      }, dot.inspect, element_id.inspect, element_id.inspect)
+    end
+  end
+end

data/lib/archsight/helpers.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Archsight
+  # Helpers provides utility functions for the architecture tool
+  module Helpers
+    module_function
+
+    # Make path relative to resources directory
+    def relative_error_path(path)
+      # Find 'resources/' in path and return from there
+      if (idx = path.index("resources/"))
+        path[idx..]
+      else
+        File.basename(path)
+      end
+    end
+
+    # Extract context lines around a YAML document containing an error
+    # Returns array of hashes with :line_no, :content, :selected keys
+    def error_context_lines(path, error_line_no, context_lines: 5)
+      return [] unless File.exist?(path)
+
+      lines = File.readlines(path, chomp: true)
+      error_idx = error_line_no - 1 # Convert to 0-indexed
+
+      # Find the start of the YAML document (--- separator at or before error line)
+      doc_start = error_idx
+      doc_start -= 1 while doc_start.positive? && lines[doc_start] != "---"
+
+      # Find the end of the YAML document (next --- or end of file)
+      doc_end = error_idx + 1
+      doc_end += 1 while doc_end < lines.length && lines[doc_end] != "---"
+      doc_end -= 1 # Don't include the next ---
+
+      # Show context_lines before doc start, full document, and context_lines after doc end
+      context_start = [doc_start - context_lines, 0].max
+      context_end = [doc_end + context_lines, lines.length - 1].min
+
+      (context_start..context_end).map do |i|
+        {
+          line_no: i + 1,
+          content: lines[i],
+          selected: (i + 1) == error_line_no
+        }
+      end
+    end
+
+    def classify(val)
+      val.to_s.split("-").map(&:capitalize).join
+    end
+
+    def deep_merge(hash1, hash2)
+      hash1.dup.merge(hash2) do |_, old_value, new_value|
+        if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+          deep_merge(old_value, new_value)
+        elsif old_value.is_a?(Array) && new_value.is_a?(Array)
+          (old_value + new_value).uniq
+        else
+          new_value
+        end
+      end
+    end
+
+    # Generate htmx attributes for a custom search query
+    def search_link_attrs(query)
+      search_url = "/search?#{URI.encode_www_form(q: query)}"
+      {
+        "href" => search_url,
+        "hx-post" => "/search",
+        "hx-vals" => { q: query }.to_json,
+        "hx-swap" => "innerHTML",
+        "hx-target" => ".content",
+        "hx-push-url" => search_url
+      }
+    end
+
+    # Generate htmx attributes for filtering by annotation (convenience wrapper)
+    def filter_link_attrs(tag, value, method = "==", kind = nil)
+      query = "#{tag} #{method} \"#{value}\""
+      query = "#{kind}: #{query}" if kind
+      search_link_attrs(query)
+    end
+
+    # Get icon class for a URL based on domain patterns
+    def icon_for_url(url)
+      case url
+      when %r{docs\.google\.com/(document|spreadsheets|presentation)}
+        "iconoir-google-docs"
+      when /github\.com/
+        "iconoir-github"
+      when /gitlab/
+        "iconoir-git-fork"
+      when /confluence\.|atlassian\.net/
+        "iconoir-page-edit"
+      when /jira\.|atlassian\.net.*jira/
+        "iconoir-list"
+      when /grafana/
+        "iconoir-graph-up"
+      when /prometheus/
+        "iconoir-database"
+      when /api\./
+        "iconoir-code"
+      when /docs\./
+        "iconoir-book"
+      else
+        "iconoir-internet"
+      end
+    end
+
+    # Convert a GitHub git URL to a raw.githubusercontent.com base URL
+    # @param git_url [String] Git URL like "git@github.com:owner/repo.git" or "https://github.com/owner/repo"
+    # @param branch [String] Branch name, defaults to "main"
+    # @return [String, nil] Base URL for raw content, or nil if not a GitHub URL
+    def github_raw_base_url(git_url, branch: "main")
+      return nil unless git_url
+
+      # Extract owner/repo from various GitHub URL formats
+      match = git_url.match(%r{github\.com[:/]([^/]+)/([^/.]+)})
+      return nil unless match
+
+      owner = match[1]
+      repo = match[2]
+      "https://raw.githubusercontent.com/#{owner}/#{repo}/#{branch}"
+    end
+
+    # Resolve relative paths in HTML/Markdown content to absolute URLs
+    # @param content [String] HTML content with potential relative paths
+    # @param base_url [String] Base URL to prepend to relative paths
+    # @return [String] Content with resolved URLs
+    def resolve_relative_urls(content, base_url)
+      return content unless base_url
+
+      # Match src="./path" or src="path" (not starting with http/https/data//)
+      content.gsub(%r{(\ssrc=["'])(\./)?((?!https?:|data:|//)[^"']+)(["'])}) do
+        prefix = ::Regexp.last_match(1)
+        _dot_slash = ::Regexp.last_match(2)
+        path = ::Regexp.last_match(3)
+        suffix = ::Regexp.last_match(4)
+        "#{prefix}#{base_url}/#{path}#{suffix}"
+      end
+    end
+
+    # Get category for a URL based on domain patterns
+    def category_for_url(url)
+      case url
+      when %r{docs\.google\.com/(document|spreadsheets|presentation)}
+        "Documentation"
+      when /github\.com|gitlab/
+        "Code Repository"
+      when /confluence\.|atlassian\.net/
+        "Documentation"
+      when /jira\.|atlassian\.net.*jira/
+        "Project Management"
+      when /grafana/
+        "Monitoring"
+      when /prometheus/
+        "Monitoring"
+      when /api\./
+        "API"
+      when /docs\./
+        "Documentation"
+      else
+        "Other"
+      end
+    end
+
+    # Sort instances by multiple fields
+    # @param instances [Array] Array of resource instances to sort
+    # @param sort_fields [Array<String>] Fields to sort by, prefix with '-' for descending
+    # @return [Array] Sorted instances
+    def sort_instances(instances, sort_fields)
+      return instances if sort_fields.empty?
+
+      instances.sort do |a, b|
+        cmp = 0
+        sort_fields.each do |sort_spec|
+          break if cmp != 0
+
+          desc = sort_spec.start_with?("-")
+          field = desc ? sort_spec[1..] : sort_spec
+
+          val_a = instance_sort_value(a, field)
+          val_b = instance_sort_value(b, field)
+
+          cmp = compare_values(val_a, val_b)
+          cmp = -cmp if desc
+        end
+        cmp
+      end
+    end
+
+    # Get the value of a field from an instance for sorting
+    def instance_sort_value(instance, field)
+      case field
+      when "name" then instance.name.to_s
+      when "kind" then instance.klass.to_s
+      else instance.annotations[field]
+      end
+    end
+
+    # Compare two values, using numeric comparison when both are integers
+    def compare_values(val_a, val_b)
+      if val_a.to_s.match?(/\A-?\d+\z/) && val_b.to_s.match?(/\A-?\d+\z/)
+        val_a.to_i <=> val_b.to_i
+      else
+        (val_a || "").to_s.downcase <=> (val_b || "").to_s.downcase
+      end
+    end
+  end
+end

data/lib/archsight/linter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "kramdown"
+
+module Archsight
+  class Linter
+    # Available view components (partials in views/partials/components/)
+    VALID_COMPONENTS = %w[activity git jira languages owner repositories status].freeze
+
+    def initialize(database)
+      @database = database
+      @errors = []
+    end
+
+    def validate
+      @database.instances.each_value do |instances_hash|
+        instances_hash.each_value do |instance|
+          validate_instance_annotations(instance)
+          validate_view_fields(instance) if instance.klass == "View"
+        end
+      end
+
+      @errors
+    end
+
+    private
+
+    def validate_instance_annotations(instance)
+      instance.annotations.each do |key, value|
+        # Find matching annotation definition (handles both exact and pattern matches)
+        annotation = instance.class.annotation_matching(key)
+
+        if annotation.nil?
+          @errors << "#{instance.path_ref}: Unknown annotation '#{key}' for #{instance.klass}"
+          next
+        end
+
+        # Skip validation if annotation has no constraints (enum or type)
+        next unless annotation.has_validation?
+
+        # Validate value against annotation schema (type and enum constraints)
+        annotation.validate(value).each do |error|
+          @errors << "#{instance.path_ref}: Annotation '#{key}' #{error}"
+        end
+
+        # Check markdown syntax
+        validate_markdown(instance, key, value) if annotation.markdown?
+      end
+    end
+
+    def validate_markdown(instance, key, value)
+      # Skip markdown validation for generated files
+      return if instance.annotations.key?("generated/script")
+
+      begin
+        Kramdown::Document.new(value, input: "GFM")
+      rescue StandardError => e
+        @errors << "#{instance.path_ref}: Markdown syntax error in annotation '#{key}': #{e.message}"
+      end
+    end
+
+    def validate_view_fields(instance)
+      fields = instance.annotations["view/fields"]
+      return unless fields
+
+      fields.split(",").map(&:strip).each do |field|
+        next unless field.start_with?("@")
+
+        component_name = field[1..]
+        unless VALID_COMPONENTS.include?(component_name)
+          @errors << "#{instance.path_ref}: Unknown view component '@#{component_name}'. " \
+                     "Valid components: #{VALID_COMPONENTS.map { |c| "@#{c}" }.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/archsight/mcp/analyze_resource_tool.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Archsight::MCP::AnalyzeResourceTool < FastMcp::Tool
+  tool_name "analyze_resource"
+
+  description <<~DESC.gsub("\n", " ").strip
+    Get detailed information about a specific architecture resource by kind and name.
+
+    THREE MODES OF OPERATION:
+
+    1. BASIC MODE (default): Returns resource details including spec, annotations, and direct relations.
+       Example: kind="ApplicationComponent", name="MyService"
+
+    2. DEPENDENCY TREE MODE (depth > 0): Returns hierarchical view of all dependencies.
+       Shows both outgoing (what this resource depends on) and incoming (what depends on this resource)
+       relations recursively up to the specified depth.
+       Example: kind="ApplicationComponent", name="MyService", depth=3
+
+    3. IMPACT ANALYSIS MODE (impact=true): Analyzes what would break if this resource is deprecated.
+       Returns all resources that directly or transitively depend on this resource, grouped by
+       kind/verb/depth with summary statistics. Essential for change impact assessment.
+       Example: kind="ApplicationInterface", name="Kubernetes:RestAPI", impact=true
+
+    RESOURCE KINDS: TechnologyArtifact, ApplicationComponent, ApplicationInterface,
+    ApplicationService, BusinessRequirement, ComplianceEvidence, and more.
+  DESC
+  arguments do
+    required(:kind).filled(:string).description(
+      "Resource type to analyze. Common kinds: TechnologyArtifact (repos, code), " \
+      "ApplicationComponent (services), ApplicationInterface (APIs), " \
+      "BusinessRequirement (compliance controls), ComplianceEvidence (compliance proof)"
+    )
+    required(:name).filled(:string).description(
+      "Exact name of the resource (case-sensitive). Use QueryTool first if unsure of exact name."
+    )
+    optional(:depth).filled(:integer).description(
+      "Dependency tree depth (0-10). " \
+      "0 = show direct relations only (default), " \
+      "1+ = recursively expand dependencies to this depth. " \
+      "Higher values show more context but increase response size."
+    )
+    optional(:impact).filled(:bool).description(
+      "Enable impact analysis mode. When true, finds all resources that would be affected " \
+      "if this resource is deprecated or removed. Returns grouped results with statistics. " \
+      "Useful for change management and deprecation planning."
+    )
+    optional(:group_by).filled(:string).description(
+      "How to group impact analysis results: " \
+      "'kind' = group by resource type (default, good for understanding scope), " \
+      "'verb' = group by relationship type (exposes, realizes, etc.), " \
+      "'depth' = group by distance from target (1=direct, 2+=transitive)"
+    )
+  end
+
+  def call(kind:, name:, depth: 0, impact: false, group_by: "kind")
+    db = Archsight::MCP.db
+
+    klass = Archsight::Resources[kind]
+    return error_response("Unknown resource kind: #{kind}") unless klass
+
+    instance = db.instance_by_kind(kind, name)
+    return error_response("Resource not found: #{kind}/#{name}") unless instance
+
+    depth = [[depth.to_i, 0].max, 10].min # Clamp to 0-10
+
+    if impact
+      build_impact_analysis(db, instance, kind, name, depth, group_by)
+    else
+      build_resource_analysis(db, instance, kind, name, depth)
+    end
+  rescue StandardError => e
+    error_response(e.message, e.class.name, e.backtrace&.first(10))
+  end
+
+  private
+
+  def error_response(message, error_type = "Error", backtrace = nil)
+    result = {
+      error: error_type,
+      message: message
+    }
+    result[:backtrace] = backtrace if backtrace
+    JSON.pretty_generate(result)
+  end
+
+  def build_resource_analysis(db, instance, kind, name, depth)
+    result = {
+      kind: kind,
+      name: name,
+      spec: instance.spec,
+      annotations: instance.annotations
+    }
+
+    if depth.positive?
+      # Include dependency trees
+      visited = Set.new
+      result[:outgoing] = build_dependency_tree(db, instance, "outgoing", 0, depth, visited.dup)
+      result[:incoming] = build_dependency_tree(db, instance, "incoming", 0, depth, visited.dup)
+    else
+      # Just direct relations
+      result[:relations] = Archsight::MCP.extract_relations(instance)
+      result[:has_relations] = instance.has_relations?
+    end
+
+    JSON.pretty_generate(result)
+  end
+
+  def build_impact_analysis(db, instance, kind, name, max_depth, group_by)
+    max_depth = 5 if max_depth.zero? # Default depth for impact analysis
+
+    # Collect all impacted resources
+    impacted = []
+    visited = Set.new
+    collect_impact(db, instance, 0, max_depth, visited, impacted)
+
+    # Group results
+    grouped = case group_by
+              when "verb"
+                impacted.group_by { |i| i[:verb].to_s }
+              when "kind"
+                impacted.group_by { |i| i[:kind] }
+              when "depth"
+                impacted.group_by { |i| i[:depth] }
+              else
+                { "all" => impacted }
+              end
+
+    # Calculate summary statistics
+    summary = {
+      total_impacted: impacted.length,
+      unique_resources: impacted.map { |i| "#{i[:kind]}/#{i[:name]}" }.uniq.length,
+      by_kind: impacted.group_by { |i| i[:kind] }.transform_values(&:length),
+      max_depth_reached: impacted.map { |i| i[:depth] }.max || 0
+    }
+
+    result = {
+      target: { kind: kind, name: name },
+      analysis: "impact",
+      max_depth: max_depth,
+      group_by: group_by,
+      summary: summary,
+      impacted_resources: grouped
+    }
+
+    JSON.pretty_generate(result)
+  end
+
+  def collect_impact(db, resource, current_depth, max_depth, visited, collector)
+    return if current_depth >= max_depth
+
+    key = "#{resource.class.to_s.split("::").last}/#{resource.name}"
+    return if visited.include?(key)
+
+    visited.add(key)
+
+    db.instances.each_value do |instances_hash|
+      instances_hash.each_value do |other|
+        next if other == resource
+
+        other.class.relations.each do |verb, kind_name, _|
+          rels = other.relations(verb, kind_name)
+          next unless rels.include?(resource)
+
+          collector << {
+            kind: other.class.to_s.split("::").last,
+            name: other.name,
+            verb: verb,
+            depth: current_depth + 1
+          }
+
+          collect_impact(db, other, current_depth + 1, max_depth, visited.dup, collector)
+        end
+      end
+    end
+  end
+
+  def build_dependency_tree(db, resource, direction, current_depth, max_depth, visited)
+    return [] if current_depth >= max_depth
+
+    key = "#{resource.class.to_s.split("::").last}/#{resource.name}"
+    return [] if visited.include?(key)
+
+    visited.add(key)
+    deps = []
+
+    if direction == "outgoing"
+      resource.class.relations.each do |verb, kind_name, _|
+        rels = resource.relations(verb, kind_name)
+        rels.each do |rel|
+          deps << {
+            kind: rel.class.to_s.split("::").last,
+            name: rel.name,
+            verb: verb.to_s,
+            children: build_dependency_tree(db, rel, direction, current_depth + 1, max_depth, visited.dup)
+          }
+        end
+      end
+    elsif direction == "incoming"
+      db.instances.each_value do |instances_hash|
+        instances_hash.each_value do |other|
+          next if other == resource
+
+          other.class.relations.each do |verb, kind_name, _|
+            rels = other.relations(verb, kind_name)
+            next unless rels.include?(resource)
+
+            deps << {
+              kind: other.class.to_s.split("::").last,
+              name: other.name,
+              verb: verb.to_s,
+              children: build_dependency_tree(db, other, direction, current_depth + 1, max_depth, visited.dup)
+            }
+          end
+        end
+      end
+    end
+
+    deps
+  end
+end

data/lib/archsight/mcp/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require_relative "../database"
+require_relative "../resources"
+
+# Shared database and helper methods for MCP tools
+module Archsight::MCP
+  class << self
+    attr_accessor :db
+
+    def complete_summary(resource, omit_kind: false)
+      result = {
+        name: resource.name,
+        metadata: {
+          annotations: resource.annotations
+        },
+        spec: resource.spec
+      }
+      result[:kind] = resource.class.to_s.split("::").last unless omit_kind
+      result
+    end
+
+    def brief_summary(resource, omit_kind: false)
+      result = { name: resource.name }
+      result[:kind] = resource.class.to_s.split("::").last unless omit_kind
+      result
+    end
+
+    def extract_description(resource)
+      description = resource.annotations["architecture/description"]
+      return "No description" if description.nil?
+
+      description.split("\n").first
+    end
+
+    def extract_relations(instance)
+      relations = {}
+
+      instance.class.relations.each do |verb, kind_name, _|
+        relations[verb] ||= {}
+        relations[verb][kind_name] = instance.relations(verb, kind_name).map(&:name)
+      end
+
+      relations
+    end
+  end
+end