archsight 0.1.4 → 0.1.5

data/lib/archsight/editor.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "resources"
+require_relative "editor/file_writer"
+require_relative "editor/content_hasher"
+
+module Archsight
+  # Editor handles building and validating resources for the web editor
+  module Editor
+    module_function
+
+    # Build a resource hash from form params
+    # @param kind [String] Resource kind (e.g., "TechnologyArtifact")
+    # @param name [String] Resource name
+    # @param annotations [Hash] Annotation key-value pairs
+    # @param relations [Array<Hash>] Array of {verb:, kind:, names:[]} hashes
+    #   where kind is the target class name (e.g., "TechnologyArtifact")
+    # @return [Hash] Resource hash ready for YAML conversion
+    def build_resource(kind:, name:, annotations: {}, relations: [])
+      resource = {
+        "apiVersion" => "architecture/v1alpha1",
+        "kind" => kind,
+        "metadata" => {
+          "name" => name
+        }
+      }
+
+      # Add annotations if any non-empty values exist
+      filtered_annotations = filter_empty(annotations)
+      resource["metadata"]["annotations"] = filtered_annotations unless filtered_annotations.empty?
+
+      # Add spec with relations if any exist
+      spec = build_spec(kind, relations)
+      resource["spec"] = spec unless spec.empty?
+
+      resource
+    end
+
+    # Validate resource params using annotation definitions
+    # @param kind [String] Resource kind
+    # @param name [String] Resource name
+    # @param annotations [Hash] Annotation key-value pairs
+    # @return [Hash] { valid: Boolean, errors: { field => [messages] } }
+    def validate(kind, name:, annotations: {})
+      klass = Archsight::Resources[kind]
+      errors = {}
+
+      # Validate name
+      if name.nil? || name.strip.empty?
+        errors["name"] = ["Name is required"]
+      elsif name =~ /\s/
+        errors["name"] = ["Name cannot contain spaces"]
+      end
+
+      # Validate annotations against their definitions
+      klass.annotations.reject(&:pattern?).each do |ann|
+        value = annotations[ann.key]
+        next if value.nil? || value.to_s.strip.empty?
+
+        ann_errors = ann.validate(value)
+        errors[ann.key] = ann_errors if ann_errors.any?
+      end
+
+      { valid: errors.empty?, errors: errors }
+    end
+
+    # Generate YAML string from resource hash
+    # Uses custom YAML dump that formats multiline strings with literal block scalars
+    # @param resource_hash [Hash] Resource hash
+    # @return [String] YAML string
+    def to_yaml(resource_hash)
+      visitor = Psych::Visitors::YAMLTree.create
+      visitor << resource_hash
+
+      # Walk the AST and apply scalar style for multiline strings
+      ast = visitor.tree
+      apply_block_scalar_style(ast)
+
+      ast.yaml(nil, line_width: 80)
+    end
+
+    # Recursively apply literal block style for multiline strings in YAML AST
+    # @param node [Psych::Nodes::Node] YAML AST node
+    def apply_block_scalar_style(node)
+      case node
+      when Psych::Nodes::Scalar
+        if node.value.is_a?(String)
+          # Normalize Windows/old Mac line endings to Unix style
+          node.value = node.value.gsub("\r\n", "\n").gsub("\r", "\n") if node.value.include?("\r")
+          # Use literal block style for multiline strings
+          node.style = Psych::Nodes::Scalar::LITERAL if node.value.include?("\n")
+        end
+      when Psych::Nodes::Sequence, Psych::Nodes::Mapping, Psych::Nodes::Document, Psych::Nodes::Stream
+        node.children.each { |child| apply_block_scalar_style(child) }
+      end
+    end
+
+    # Get editable annotations for a resource kind
+    # Excludes pattern annotations, computed annotations, and annotations with editor: false
+    # @param kind [String] Resource kind
+    # @return [Array<Archsight::Annotations::Annotation>]
+    def editable_annotations(kind)
+      klass = Archsight::Resources[kind]
+      return [] unless klass
+
+      # Get all annotations except pattern annotations
+      annotations = klass.annotations.reject(&:pattern?)
+
+      # Filter out computed annotations
+      computed_keys = klass.computed_annotations.map(&:key)
+      annotations = annotations.reject { |a| computed_keys.include?(a.key) }
+
+      # Filter out non-editable annotations
+      annotations.reject { |a| a.editor == false }
+    end
+
+    # Get available relations for a resource kind
+    # @param kind [String] Resource kind
+    # @return [Array<Array>] Array of [verb, target_kind, target_class_name]
+    def available_relations(kind)
+      klass = Archsight::Resources[kind]
+      return [] unless klass
+
+      klass.relations
+    end
+
+    # Get unique verbs for a resource kind's relations
+    # @param kind [String] Resource kind
+    # @return [Array<String>]
+    def relation_verbs(kind)
+      available_relations(kind).map { |v, _, _| v.to_s }.uniq.sort
+    end
+
+    # Get valid target class names for a given verb (for UI display and instance lookup)
+    # @param kind [String] Resource kind
+    # @param verb [String] Relation verb
+    # @return [Array<String>] Target class names (e.g., "TechnologyArtifact")
+    def target_kinds_for_verb(kind, verb)
+      # Relations structure is [verb, relation_name, target_class_name]
+      available_relations(kind)
+        .select { |v, _, _| v.to_s == verb.to_s }
+        .map { |_, _, target_class| target_class.to_s }
+        .uniq
+        .sort
+    end
+
+    # Get relation name for a given verb and target class (for building spec)
+    # @param kind [String] Source resource kind
+    # @param verb [String] Relation verb
+    # @param target_class [String] Target class name
+    # @return [String, nil] Relation name (e.g., "technologyComponents")
+    def relation_name_for(kind, verb, target_class)
+      relation = available_relations(kind).find do |v, _, tc|
+        v.to_s == verb.to_s && tc.to_s == target_class.to_s
+      end
+      return nil unless relation
+
+      relation[1].to_s
+    end
+
+    # Get target class name for a given verb and relation name (reverse lookup)
+    # @param kind [String] Source resource kind
+    # @param verb [String] Relation verb
+    # @param relation_name [String] Relation name (e.g., "businessActors")
+    # @return [String, nil] Target class name (e.g., "BusinessActor")
+    def target_class_for_relation(kind, verb, relation_name)
+      relation = available_relations(kind).find do |v, rn, _|
+        v.to_s == verb.to_s && rn.to_s == relation_name.to_s
+      end
+      return nil unless relation
+
+      relation[2].to_s
+    end
+
+    # Filter out empty values from a hash and convert to plain Hash
+    # (avoids !ruby/hash:Sinatra::IndifferentHash in YAML output)
+    def filter_empty(hash)
+      return {} if hash.nil?
+
+      result = hash.reject { |_, v| v.nil? || v.to_s.strip.empty? }
+      # Convert to plain Hash to avoid Ruby-specific YAML tags
+      result.to_h
+    end
+
+    # Build spec hash from relations array
+    # @param source_kind [String] The source resource kind
+    # @param relations [Array<Hash>] Array of {verb:, kind:, names:[]} hashes
+    #   where kind is the target class name (e.g., "TechnologyArtifact")
+    # @return [Hash] Spec hash with proper relation_name keys
+    def build_spec(source_kind, relations)
+      return {} if relations.nil? || relations.empty?
+
+      spec = {}
+      relations.each { |rel| add_relation_to_spec(spec, source_kind, rel) }
+      deduplicate_spec_values(spec)
+    end
+
+    def add_relation_to_spec(spec, source_kind, rel)
+      verb, target_class, names = extract_relation_parts(rel)
+      return if invalid_relation?(verb, target_class, names)
+
+      rel_name = relation_name_for(source_kind, verb, target_class)
+      return unless rel_name
+
+      spec[verb.to_s] ||= {}
+      spec[verb.to_s][rel_name] ||= []
+      spec[verb.to_s][rel_name].concat(names)
+    end
+
+    def extract_relation_parts(rel)
+      verb = rel[:verb] || rel["verb"]
+      target_class = rel[:kind] || rel["kind"]
+      names = normalize_names(rel[:names] || rel["names"] || [])
+      [verb, target_class, names]
+    end
+
+    def normalize_names(names)
+      names = [names] unless names.is_a?(Array)
+      names.map(&:to_s).reject(&:empty?)
+    end
+
+    def invalid_relation?(verb, target_class, names)
+      verb.nil? || verb.to_s.strip.empty? ||
+        target_class.nil? || target_class.to_s.strip.empty? ||
+        names.empty?
+    end
+
+    def deduplicate_spec_values(spec)
+      spec.transform_values { |kinds| kinds.transform_values(&:uniq) }
+    end
+
+    private_class_method :filter_empty, :build_spec, :add_relation_to_spec,
+                         :extract_relation_parts, :normalize_names, :invalid_relation?,
+                         :deduplicate_spec_values
+  end
+end

data/lib/archsight/import/handlers/github.rb

@@ -14,6 +14,9 @@ require_relative "../registry"
 #   import/config/org - GitHub organization name
 #   import/config/repoOutputPath - Output path for repository handler results (e.g., "generated/repositories.yaml")
 #   import/config/childCacheTime - Cache time for generated child imports (e.g., "1h", "30m")
+#   import/config/fallbackTeam - Default team when no contributor match found (propagated to child imports)
+#   import/config/botTeam - Team for bot-only repositories (propagated to child imports)
+#   import/config/corporateAffixes - Comma-separated corporate username affixes for team matching (propagated to child imports)
 #
 # Environment:
 #   GITHUB_TOKEN - GitHub Personal Access Token (required)
@@ -136,15 +139,20 @@ class Archsight::Import::Handlers::Github < Archsight::Import::Handler
       child_annotations["import/outputPath"] = @repo_output_path if @repo_output_path
       child_annotations["import/cacheTime"] = @child_cache_time if @child_cache_time
 
+      child_config = {
+        "path" => repo_path,
+        "gitUrl" => git_url,
+        "archived" => repo["isArchived"].to_s,
+        "visibility" => visibility == "public" ? "open-source" : "internal"
+      }
+      child_config["fallbackTeam"] = config("fallbackTeam") if config("fallbackTeam")
+      child_config["botTeam"] = config("botTeam") if config("botTeam")
+      child_config["corporateAffixes"] = config("corporateAffixes") if config("corporateAffixes")
+
       import_yaml(
         name: "Import:Repo:github:#{@org}:#{repo_name}",
         handler: "repository",
-        config: {
-          "path" => repo_path,
-          "gitUrl" => git_url,
-          "archived" => repo["isArchived"].to_s,
-          "visibility" => visibility == "public" ? "open-source" : "internal"
-        },
+        config: child_config,
         annotations: child_annotations
       )
     end

data/lib/archsight/import/handlers/gitlab.rb

@@ -19,6 +19,9 @@ require_relative "../registry"
 #   import/config/sslFingerprint - SSL certificate fingerprint for pinning (SHA256, colon-separated hex)
 #   import/config/repoOutputPath - Output path for repository handler results (e.g., "generated/repositories.yaml")
 #   import/config/childCacheTime - Cache time for generated child imports (e.g., "1h", "30m")
+#   import/config/fallbackTeam - Default team when no contributor match found (propagated to child imports)
+#   import/config/botTeam - Team for bot-only repositories (propagated to child imports)
+#   import/config/corporateAffixes - Comma-separated corporate username affixes for team matching (propagated to child imports)
 #
 # Environment:
 #   GITLAB_TOKEN - GitLab personal access token (required)
@@ -177,15 +180,20 @@ class Archsight::Import::Handlers::Gitlab < Archsight::Import::Handler
       child_annotations["import/outputPath"] = @repo_output_path if @repo_output_path
       child_annotations["import/cacheTime"] = @child_cache_time if @child_cache_time
 
+      child_config = {
+        "path" => repo_path,
+        "gitUrl" => git_url,
+        "archived" => project["archived"].to_s,
+        "visibility" => project["visibility"] || "internal"
+      }
+      child_config["fallbackTeam"] = config("fallbackTeam") if config("fallbackTeam")
+      child_config["botTeam"] = config("botTeam") if config("botTeam")
+      child_config["corporateAffixes"] = config("corporateAffixes") if config("corporateAffixes")
+
       import_yaml(
         name: "Import:Repo:gitlab:#{dir_name}",
         handler: "repository",
-        config: {
-          "path" => repo_path,
-          "gitUrl" => git_url,
-          "archived" => project["archived"].to_s,
-          "visibility" => project["visibility"] || "internal"
-        },
+        config: child_config,
         annotations: child_annotations
       )
     end

data/lib/archsight/import/handlers/repository.rb

@@ -18,6 +18,7 @@ require_relative "../team_matcher"
 #   import/config/sccPath - Optional path to scc binary (default: scc)
 #   import/config/fallbackTeam - Optional team name when no contributor match found
 #   import/config/botTeam - Optional team name for bot-only repositories
+#   import/config/corporateAffixes - Optional comma-separated corporate username affixes for team matching (e.g., "ionos,1and1")
 class Archsight::Import::Handlers::Repository < Archsight::Import::Handler
   def execute
     @path = config("path")
@@ -256,7 +257,8 @@ class Archsight::Import::Handlers::Repository < Archsight::Import::Handler
   def match_teams(top_contributors, activity_status)
     return nil unless database && top_contributors&.any?
 
-    matcher = Archsight::Import::TeamMatcher.new(database)
+    affixes = config("corporateAffixes")&.split(",")&.map(&:strip) || []
+    matcher = Archsight::Import::TeamMatcher.new(database, corporate_affixes: affixes)
     result = matcher.analyze(top_contributors)
 
     # Apply fallbacks from config

data/lib/archsight/import/team_matcher.rb

@@ -15,11 +15,16 @@ class Archsight::Import::TeamMatcher
   # Teams to ignore when matching (bots, unknown, etc.)
   IGNORED_TEAMS = %w[Bot:Team No:Team Team:Unknown Team:Bot].freeze
 
-  def initialize(database)
+  # Team annotation keys that contain member/lead information
+  TEAM_ANNOTATION_KEYS = %w[team/members team/lead].freeze
+
+  def initialize(database, corporate_affixes: [])
     @database = database
+    @corporate_affixes = corporate_affixes
     @teams = load_teams
     @email_to_team = build_email_index
     @name_to_team = build_name_index
+    @member_identities = build_member_identities
   end
 
   # Analyze top contributors and return team assignments
@@ -72,6 +77,12 @@ class Archsight::Import::TeamMatcher
       return team if team
     end
 
+    # Try corporate username pattern match (e.g. jsmith-ionos -> John Smith)
+    if name
+      team = pattern_match_username(name)
+      return team if team
+    end
+
     nil
   end
 
@@ -87,21 +98,22 @@ class Archsight::Import::TeamMatcher
     end
   end
 
-  def build_email_index
-    index = {}
-
+  # Yields (team_name, annotation_value) for each team/members and team/lead annotation
+  def each_team_annotation
     @teams.each do |team|
       team_name = team.name
-
-      # Extract emails from team/members annotation
-      members = team.annotations["team/members"]
-      parse_email_list(members).each do |email|
-        index[email.downcase] = team_name
+      TEAM_ANNOTATION_KEYS.each do |key|
+        value = team.annotations[key]
+        yield team_name, value if value && !value.empty?
       end
+    end
+  end
+
+  def build_email_index
+    index = {}
 
-      # Extract email from team/lead annotation
-      lead = team.annotations["team/lead"]
-      parse_email_list(lead).each do |email|
+    each_team_annotation do |team_name, value|
+      parse_email_list(value).each do |email|
         index[email.downcase] = team_name
       end
     end
@@ -112,19 +124,8 @@ class Archsight::Import::TeamMatcher
   def build_name_index
     index = {}
 
-    @teams.each do |team|
-      team_name = team.name
-
-      # Extract names from team/members annotation
-      members = team.annotations["team/members"]
-      parse_name_list(members).each do |name|
-        normalized = normalize_name(name)
-        index[normalized] = team_name if normalized && !normalized.empty?
-      end
-
-      # Extract name from team/lead annotation
-      lead = team.annotations["team/lead"]
-      parse_name_list(lead).each do |name|
+    each_team_annotation do |team_name, value|
+      parse_name_list(value).each do |name|
         normalized = normalize_name(name)
         index[normalized] = team_name if normalized && !normalized.empty?
       end
@@ -136,60 +137,109 @@ class Archsight::Import::TeamMatcher
   # Parse email addresses from team annotation
   # Supports formats: "Name <email>", "email", or comma/newline separated lists
   def parse_email_list(value)
-    return [] if value.nil? || value.empty?
+    parse_name_email_pairs(value).filter_map { |pair| pair[:email] }
+  end
 
-    emails = []
+  # Parse names from team annotation
+  # Supports formats: "Name <email>", "First Last", or comma/newline separated lists
+  def parse_name_list(value)
+    parse_name_email_pairs(value).filter_map { |pair| pair[:name] }
+  end
 
-    # Split by comma or newline
-    value.split(/[,\n]/).each do |entry|
-      entry = entry.strip
-      next if entry.empty?
+  # Normalize name for matching
+  # Converts to lowercase, removes extra spaces, handles common variations
+  def normalize_name(name)
+    return nil if name.nil?
 
-      # Try to extract email from "Name <email>" format
-      if (match = entry.match(/<([^>]+)>/))
-        emails << match[1].strip
-      elsif entry.include?("@")
-        # Plain email address
-        emails << entry
+    name.to_s
+        .downcase
+        .gsub(/\s+/, " ")
+        .strip
+  end
+
+  # Match git author name as corporate username pattern {first_initial}{lastname}[-affix] or [affix-]{first_initial}{lastname}
+  # e.g. "jsmith-ionos" or "ionos-jsmith" -> initial "j", lastname "smith" -> matches "John Smith"
+  #
+  # Limitations: Multi-part names (e.g. "Hans von Braun") only match by the last
+  # name part ("braun"), so "hvonbraun" would not match. Hyphenated lastnames
+  # (e.g. "Meyer-Schmidt") only match the full hyphenated form or the email lastname.
+  def pattern_match_username(name)
+    username = name.downcase.strip
+    return nil unless username.match?(/\A[a-z0-9][-a-z0-9]*\z/)
+    return nil if @corporate_affixes.empty?
+
+    @corporate_affixes.each do |affix|
+      clean = affix.delete_prefix("-").delete_suffix("-")
+      username = username.delete_suffix("-#{clean}")
+      username = username.delete_prefix("#{clean}-")
+    end
+    return nil if username.length < 3
+
+    initial = username[0]
+    lastname = username[1..]
+    return nil if lastname.length < 3
+
+    candidates = @member_identities.select do |member|
+      lastname_match = member[:lastname] == lastname || member[:email_lastname] == lastname
+      initial_match = member[:firstname]&.start_with?(initial)
+      lastname_match && initial_match
+    end
+
+    teams = candidates.map { |c| c[:team] }.uniq
+    return teams.first if teams.size == 1
+
+    nil
+  end
+
+  # Build identity records for corporate username pattern matching
+  def build_member_identities
+    identities = []
+
+    each_team_annotation do |team_name, value|
+      parse_name_email_pairs(value).each do |entry|
+        name_parts = entry[:name]&.downcase&.split(/\s+/)
+        next if name_parts.nil? || name_parts.size < 2
+
+        firstname = name_parts.first
+        lastname = name_parts.last
+
+        email_prefix = entry[:email]&.split("@")&.first
+        email_parts = email_prefix&.split(/[.-]/)
+        email_lastname = email_parts&.last&.downcase
+
+        identities << { team: team_name, firstname: firstname, lastname: lastname, email_lastname: email_lastname }
       end
     end
 
-    emails
+    identities
   end
 
-  # Parse names from team annotation
-  # Supports formats: "Name <email>", "First Last", or comma/newline separated lists
-  def parse_name_list(value)
+  # Parse name and email pairs from team annotation
+  # Returns array of { name:, email: } hashes from "Name <email>" format
+  def parse_name_email_pairs(value)
     return [] if value.nil? || value.empty?
 
-    names = []
+    pairs = []
 
-    # Split by comma or newline
     value.split(/[,\n]/).each do |entry|
       entry = entry.strip
       next if entry.empty?
 
-      # Try to extract name from "Name <email>" format
-      if (match = entry.match(/^([^<]+)</))
+      name = nil
+      email = nil
+
+      if (match = entry.match(/^([^<]+)<([^>]+)>/))
         name = match[1].strip
-        names << name unless name.empty?
-      elsif !entry.include?("@")
-        # Plain name (no email)
-        names << entry
+        email = match[2].strip
+      elsif entry.include?("@")
+        email = entry.strip
+      else
+        name = entry.strip
       end
-    end
-
-    names
-  end
 
-  # Normalize name for matching
-  # Converts to lowercase, removes extra spaces, handles common variations
-  def normalize_name(name)
-    return nil if name.nil?
+      pairs << { name: name, email: email } if name || email
+    end
 
-    name.to_s
-        .downcase
-        .gsub(/\s+/, " ")
-        .strip
+    pairs
   end
 end

data/lib/archsight/mcp/execute_analysis_tool.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Archsight::MCP::ExecuteAnalysisTool < FastMcp::Tool
+  tool_name "execute_analysis"
+
+  description <<~DESC.gsub("\n", " ").strip
+    Discover and execute Analysis resources that validate architecture data and produce reports.
+
+    TWO MODES OF OPERATION:
+
+    1. LIST MODE (no name): Returns all available Analysis resources with name, description,
+       handler, and timeout. Use this to discover what analyses exist before running them.
+
+    2. EXECUTE MODE (name provided): Runs the specified Analysis script in a sandboxed environment
+       and returns the results as markdown. The output includes structured findings like tables,
+       lists, warnings, and errors generated by the script.
+  DESC
+
+  arguments do
+    optional(:name).filled(:string).description(
+      "Analysis name to execute (e.g., 'Analysis:Service:TeamOwnership'). " \
+      "Omit to list all available analyses."
+    )
+    optional(:verbose).filled(:bool).description(
+      "When true, tables and lists in output are not truncated. Default: false."
+    )
+  end
+
+  def call(name: nil, verbose: false)
+    if name.nil?
+      list_analyses
+    else
+      execute_analysis(name, verbose: verbose)
+    end
+  rescue StandardError => e
+    error_response(e.message)
+  end
+
+  private
+
+  def list_analyses
+    db = Archsight::MCP.db
+    analyses = db.instances_by_kind("Analysis").values
+
+    resources = analyses.map do |analysis|
+      {
+        name: analysis.name,
+        description: analysis.annotations["analysis/description"] || analysis.annotations["architecture/description"],
+        handler: analysis.annotations["analysis/handler"] || "ruby",
+        timeout: analysis.annotations["analysis/timeout"] || "30s"
+      }
+    end
+
+    JSON.pretty_generate(
+      total: resources.size,
+      analyses: resources
+    )
+  end
+
+  def execute_analysis(name, verbose: false)
+    require "archsight/analysis"
+
+    db = Archsight::MCP.db
+    analysis = db.instance_by_kind("Analysis", name)
+    return error_response("Analysis not found: #{name}") unless analysis
+
+    executor = Archsight::Analysis::Executor.new(db)
+    result = executor.execute(analysis)
+
+    if result.success?
+      JSON.pretty_generate(
+        name: result.name,
+        success: true,
+        duration: result.duration,
+        output: result.to_markdown(verbose: verbose),
+        has_findings: result.has_findings?,
+        warning_count: result.warning_count,
+        error_count: result.error_count
+      )
+    else
+      response = {
+        name: result.name,
+        success: false,
+        error: result.error
+      }
+      partial = result.to_markdown(verbose: verbose)
+      response[:partial_output] = partial unless partial.empty?
+      JSON.pretty_generate(response)
+    end
+  end
+
+  def error_response(message)
+    JSON.pretty_generate(
+      error: "Error",
+      message: message
+    )
+  end
+end

data/lib/archsight/mcp.rb

@@ -4,3 +4,4 @@ require_relative "mcp/base"
 require_relative "mcp/query_tool"
 require_relative "mcp/analyze_resource_tool"
 require_relative "mcp/resource_doc_tool"
+require_relative "mcp/execute_analysis_tool"