archsight 0.1.2 → 0.1.3

data/lib/archsight/import/team_matcher.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "archsight/import"
+
+# Matches git contributors to BusinessActor teams
+#
+# Uses team member email and name patterns from BusinessActor annotations
+# to match top contributors from git history to teams.
+#
+# @example
+#   matcher = Archsight::Import::TeamMatcher.new(database)
+#   result = matcher.analyze(top_contributors)
+#   # => { maintainer: "Team:Engineering", contributors: ["Team:QA", "Team:Ops"] }
+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)
+    @database = database
+    @teams = load_teams
+    @email_to_team = build_email_index
+    @name_to_team = build_name_index
+  end
+
+  # Analyze top contributors and return team assignments
+  #
+  # @param top_contributors [Array<Hash>] List of contributors with "name", "email", "commits" keys
+  # @return [Hash] { maintainer: String?, contributors: [String] }
+  def analyze(top_contributors)
+    return { maintainer: nil, contributors: [] } if top_contributors.nil? || top_contributors.empty?
+
+    team_commits = Hash.new(0)
+
+    top_contributors.each do |contributor|
+      team = match_contributor(contributor["name"], contributor["email"])
+      next unless team
+      next if IGNORED_TEAMS.include?(team)
+
+      team_commits[team] += contributor["commits"]
+    end
+
+    return { maintainer: nil, contributors: [] } if team_commits.empty?
+
+    # Sort by commits descending
+    sorted = team_commits.sort_by { |_, commits| -commits }
+
+    {
+      maintainer: sorted.first&.first,
+      contributors: sorted.drop(1).map(&:first)
+    }
+  end
+
+  # Match a single contributor to a team
+  #
+  # @param name [String] Contributor name
+  # @param email [String] Contributor email
+  # @return [String, nil] Team name or nil if no match
+  def match_contributor(name, email)
+    return nil if name.nil? && email.nil?
+
+    # Try exact email match first (most reliable)
+    if email
+      normalized_email = email.to_s.downcase.strip
+      team = @email_to_team[normalized_email]
+      return team if team
+    end
+
+    # Try name match (less reliable, but useful for LDAP-style names)
+    if name
+      normalized_name = normalize_name(name)
+      team = @name_to_team[normalized_name]
+      return team if team
+    end
+
+    nil
+  end
+
+  private
+
+  def load_teams
+    return {} unless @database
+
+    begin
+      @database.instances_by_kind("BusinessActor")&.values || []
+    rescue StandardError
+      []
+    end
+  end
+
+  def build_email_index
+    index = {}
+
+    @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
+      end
+
+      # Extract email from team/lead annotation
+      lead = team.annotations["team/lead"]
+      parse_email_list(lead).each do |email|
+        index[email.downcase] = team_name
+      end
+    end
+
+    index
+  end
+
+  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|
+        normalized = normalize_name(name)
+        index[normalized] = team_name if normalized && !normalized.empty?
+      end
+    end
+
+    index
+  end
+
+  # 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?
+
+    emails = []
+
+    # Split by comma or newline
+    value.split(/[,\n]/).each do |entry|
+      entry = entry.strip
+      next if entry.empty?
+
+      # Try to extract email from "Name <email>" format
+      if (match = entry.match(/<([^>]+)>/))
+        emails << match[1].strip
+      elsif entry.include?("@")
+        # Plain email address
+        emails << entry
+      end
+    end
+
+    emails
+  end
+
+  # Parse names from team annotation
+  # Supports formats: "Name <email>", "First Last", or comma/newline separated lists
+  def parse_name_list(value)
+    return [] if value.nil? || value.empty?
+
+    names = []
+
+    # 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 = match[1].strip
+        names << name unless name.empty?
+      elsif !entry.include?("@")
+        # Plain name (no email)
+        names << entry
+      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?
+
+    name.to_s
+        .downcase
+        .gsub(/\s+/, " ")
+        .strip
+  end
+end

data/lib/archsight/import.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Define import module namespaces
+module Archsight
+  module Import
+    module Handlers
+    end
+  end
+end
+
+require_relative "import/registry"
+require_relative "import/handler"
+require_relative "import/executor"
+# Handlers are loaded by CLI's require_import_handlers method

data/lib/archsight/resources/analysis.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Analysis represents a declarative analysis script that validates or reports on architecture resources
+class Archsight::Resources::Analysis < Archsight::Resources::Base
+  include_annotations :generated
+
+  description <<~MD
+    Represents a declarative analysis script for validating or reporting on architecture resources.
+
+    ## Definition
+
+    An Analysis is a tool-specific resource type that defines Ruby scripts to run
+    against the architecture database. Scripts execute in a sandboxed environment
+    with access to instance traversal, annotation access, and reporting methods.
+
+    ## Usage
+
+    Use Analysis to represent:
+
+    - Validation rules (team ownership, naming conventions)
+    - Architecture compliance checks
+    - Metrics collection and aggregation
+    - Custom reports and dashboards
+
+    ## Script Environment
+
+    Scripts have access to:
+
+    - `each_instance(kind)` - iterate over all instances of a kind
+    - `instances(kind)` - get array of instances
+    - `instance(kind, name)` - get specific instance
+    - `outgoing(inst, kind)` / `incoming(inst, kind)` - relation traversal
+    - `outgoing_transitive(inst, kind)` / `incoming_transitive(inst, kind)` - transitive relations
+    - `annotation(inst, key)` - get annotation value
+    - `name(inst)` / `kind(inst)` - get instance metadata
+    - `query(query_string)` - execute a query
+    - `report(data, title:)` - output findings
+    - `warning(msg)` / `error(msg)` / `info(msg)` - log messages
+  MD
+
+  icon "clipboard-check"
+  layer "other"
+
+  # Handler selection (for future extensibility)
+  annotation "analysis/handler",
+             description: "Script handler type (only 'ruby' currently supported)",
+             title: "Handler",
+             enum: %w[ruby]
+
+  # Script content
+  annotation "analysis/script",
+             description: "Ruby script to execute in sandboxed environment",
+             title: "Script",
+             sidebar: false
+
+  # Description
+  annotation "analysis/description",
+             description: "Human-readable description of what this analysis validates",
+             title: "Description"
+
+  # Execution configuration
+  annotation "analysis/timeout",
+             description: "Maximum execution time (e.g., '30s', '5m')",
+             title: "Timeout"
+
+  # Output configuration
+  annotation "analysis/output",
+             description: "Output mode for results",
+             title: "Output",
+             enum: %w[console file]
+
+  annotation "analysis/outputPath",
+             description: "File path for output (when output mode is 'file')",
+             title: "Output Path",
+             sidebar: false
+
+  # Enabled flag
+  annotation "analysis/enabled",
+             description: "Whether this analysis is enabled",
+             title: "Enabled",
+             enum: %w[true false]
+
+  # Pattern annotation for custom configuration
+  annotation "analysis/config/*",
+             description: "Custom configuration values for the analysis script",
+             sidebar: false
+
+  # Dependency relation (analyses can depend on other analyses or imports)
+  relation :dependsOn, :imports, :Import
+  relation :dependsOn, :analyses, :Analysis
+end

data/lib/archsight/resources/application_component.rb

@@ -182,9 +182,9 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   %w[scc/estimatedCost scc/estimatedScheduleMonths scc/estimatedPeople].each do |anno_key|
     computed_annotation anno_key,
                         title: "Total #{anno_key.split("/").last.split(/(?=[A-Z])/).map(&:capitalize).join(" ")}",
-                        description: "Total estimated #{anno_key.split("/").last} from related artifacts",
+                        description: "Total estimated #{anno_key.split("/").last} from related repositories",
                         type: Integer do
-      sum(outgoing_transitive(:TechnologyArtifact), anno_key)
+      sum(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'), anno_key)
     end
   end
 

data/lib/archsight/resources/application_service.rb

@@ -39,45 +39,45 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   # Computed Annotations
   computed_annotation "repository/artifacts/total",
                       title: "Total Git Repositories",
-                      description: "Number of related git repositories across all related application components",
+                      description: "Number of related git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationComponent), "repository/artifacts/total")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 
   computed_annotation "repository/artifacts/active",
                       title: "Active Git Repositories",
-                      description: "Number of related git repositories across all related application components",
+                      description: "Number of active git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationComponent), "repository/artifacts/active")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "active"'))
   end
 
   computed_annotation "repository/artifacts/abandoned",
                       title: "Abandoned Git Repositories",
-                      description: "Number of related git repositories across all related application components",
+                      description: "Number of abandoned git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationComponent), "repository/artifacts/abandoned")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "abandoned"'))
   end
 
   computed_annotation "repository/artifacts/highBusFactor",
                       title: "High Bus Factor Repositories",
-                      description: "Number of active git repositories with high bus factor across all related application components",
+                      description: "Number of active git repositories with high bus factor",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationComponent), "repository/artifacts/highBusFactor")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/busFactor == "high"'))
   end
 
   computed_annotation "repository/artifacts/archived",
                       title: "Archived Repositories",
-                      description: "Number of archived git repositories across all related application components",
+                      description: "Number of archived git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationComponent), "repository/artifacts/archived")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "archived"'))
   end
 
   %w[scc/estimatedCost scc/estimatedScheduleMonths scc/estimatedPeople].each do |anno_key|
     computed_annotation anno_key,
                         title: "Total #{anno_key.split("/").last.split(/(?=[A-Z])/).map(&:capitalize).join(" ")}",
-                        description: "Total estimated #{anno_key.split("/").last} from related artifacts across all related application components",
+                        description: "Total estimated #{anno_key.split("/").last} from related repositories",
                         type: Integer do
-      sum(outgoing_transitive(:ApplicationComponent), anno_key)
+      sum(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'), anno_key)
     end
   end
 

data/lib/archsight/resources/business_product.rb

@@ -32,45 +32,45 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
 
   computed_annotation "repository/artifacts/total",
                       title: "Total Git Repositories",
-                      description: "Number of related git repositories across all related application components",
+                      description: "Number of related git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationService), "repository/artifacts/total")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 
   computed_annotation "repository/artifacts/active",
                       title: "Active Git Repositories",
-                      description: "Number of related git repositories across all related application components",
+                      description: "Number of active git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationService), "repository/artifacts/active")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "active"'))
   end
 
   computed_annotation "repository/artifacts/abandoned",
                       title: "Abandoned Git Repositories",
-                      description: "Number of related git repositories across all related application components",
+                      description: "Number of abandoned git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationService), "repository/artifacts/abandoned")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "abandoned"'))
   end
 
   computed_annotation "repository/artifacts/highBusFactor",
                       title: "High Bus Factor Repositories",
-                      description: "Number of active git repositories with high bus factor across all related application components",
+                      description: "Number of active git repositories with high bus factor",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationService), "repository/artifacts/highBusFactor")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/busFactor == "high"'))
   end
 
   computed_annotation "repository/artifacts/archived",
                       title: "Archived Repositories",
-                      description: "Number of archived git repositories across all related application services",
+                      description: "Number of archived git repositories",
                       type: Integer do
-    sum(outgoing_transitive(:ApplicationService), "repository/artifacts/archived")
+    count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo" & activity/status == "archived"'))
   end
 
   %w[scc/estimatedCost scc/estimatedScheduleMonths scc/estimatedPeople].each do |anno_key|
     computed_annotation anno_key,
                         title: "Total #{anno_key.split("/").last.split(/(?=[A-Z])/).map(&:capitalize).join(" ")}",
-                        description: "Total estimated #{anno_key.split("/").last} from related artifacts across all related application components",
+                        description: "Total estimated #{anno_key.split("/").last} from related repositories",
                         type: Integer do
-      sum(outgoing_transitive(:ApplicationService), anno_key)
+      sum(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'), anno_key)
     end
   end
 

data/lib/archsight/resources/data_object.rb

@@ -38,7 +38,7 @@ class Archsight::Resources::DataObject < Archsight::Resources::Base
   annotation "data/visibility",
              description: "API visibility level",
              title: "Visibility",
-             enum: %w[public private]
+             enum: %w[public private internal]
 
   annotation "generated/variants",
              description: "OpenAPI schema variants compacted into this DataObject",

data/lib/archsight/resources/import.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Import represents a data import task that generates architecture resources
+class Archsight::Resources::Import < Archsight::Resources::Base
+  include_annotations :generated
+
+  description <<~MD
+    Represents an import task that generates architecture resources.
+
+    ## Definition
+
+    An Import is a tool-specific resource type that defines how to synchronize
+    external data sources (GitLab, GitHub, ArgoCD, etc.) into the architecture
+    database. Imports can depend on other imports to ensure proper execution order.
+
+    ## Usage
+
+    Use Import to represent:
+
+    - Repository synchronization tasks
+    - API data imports
+    - Cluster discovery
+    - External system integration
+
+    ## Multi-Stage Imports
+
+    Imports can generate other Import resources, enabling multi-stage workflows:
+
+    1. GitLab import runs, discovers repositories
+    2. Generates Import resources for each repository
+    3. Repository imports run after GitLab import completes
+    4. Each repository import generates TechnologyArtifact resources
+  MD
+
+  icon "download"
+  layer "other"
+
+  # Handler selection
+  annotation "import/handler",
+             description: "Handler class name to execute this import",
+             title: "Handler", enum: %w[
+               gitlab github repository
+               rest-api rest-api-index
+               jira-discover jira-metrics
+             ]
+
+  # Output configuration
+  annotation "import/outputPath",
+             description: "Output file path relative to resources root (e.g., 'imports/generated/gitlab.yaml')",
+             title: "Output Path"
+
+  # Control flags
+  annotation "import/enabled",
+             description: "Whether this import is enabled",
+             title: "Enabled",
+             enum: %w[true false]
+
+  annotation "import/priority",
+             description: "Execution priority (lower runs first among ready imports)",
+             title: "Priority",
+             type: Integer
+
+  annotation "import/cacheTime",
+             description: "Cache duration (e.g., '30m', '1h', '24h', '7d'). Set to 'never' to always run.",
+             title: "Cache Time"
+
+  # Handler-specific configuration (pattern annotation)
+  annotation "import/config/*",
+             description: "Handler-specific configuration values",
+             sidebar: false
+
+  # Generated resources relations - auto-tracked by handlers
+  # Dependencies are derived from the inverse of generates - if A generates B, B depends on A
+  relation :generates, :technologyArtifacts, :TechnologyArtifact
+  relation :generates, :applicationInterfaces, :ApplicationInterface
+  relation :generates, :dataObjects, :DataObject
+  relation :generates, :imports, :Import
+  relation :generates, :businessActors, :BusinessActor
+end

data/lib/archsight/resources/technology_artifact.rb

@@ -72,8 +72,12 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   annotation "activity/status",
              description: "Repository activity status",
              title: "Activity Status",
-             enum: %w[active abandoned bot-only archived],
+             enum: %w[active abandoned bot-only archived inaccessible empty no-code],
              list: true
+  annotation "activity/reason",
+             description: "Reason for activity status (for non-standard statuses)",
+             title: "Status Reason",
+             sidebar: false
   annotation "activity/busFactor",
              description: "Bus factor assessment",
              title: "Bus Factor",
@@ -83,6 +87,10 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
              description: "Date of first commit (repository creation)",
              title: "Created",
              type: Time
+  annotation "activity/lastHumanCommit",
+             description: "Date of last human commit (last activity)",
+             title: "Last Human Commit",
+             type: Time
   annotation "agentic/tools",
              description: "Agentic tools detected in repository",
              title: "Agentic Tools",
@@ -121,7 +129,20 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   annotation "repository/visibility",
              description: "Repository visibility classification",
              title: "Visibility",
-             enum: %w[internal open-source public]
+             enum: %w[private internal open-source public]
+  annotation "repository/recentTags",
+             description: "Recent git tags (releases)",
+             title: "Recent Tags",
+             format: :tag_list,
+             sidebar: false
+  annotation "repository/accessible",
+             description: "Whether repository is accessible for cloning",
+             title: "Accessible",
+             enum: %w[true false]
+  annotation "repository/error",
+             description: "Error message if repository is not accessible",
+             title: "Access Error",
+             sidebar: false
   annotation "deployment/images",
              description: "OCI container image names published by this repository",
              title: "Container Images",

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/archsight/web/api/docs.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "sinatra/base"
+require "sinatra/extension"
+
+module Archsight; end
+module Archsight::Web; end
+module Archsight::Web::API; end
+
+# Documentation UI for the REST API
+module Archsight::Web::API::Docs
+  extend Sinatra::Extension
+
+  get "/api/docs" do
+    erb :api_docs
+  end
+end