archsight 0.1.0

data/lib/archsight/mcp/query_tool.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Archsight::MCP::QueryTool < FastMcp::Tool
+  tool_name "query"
+
+  description <<~DESC.gsub("\n", " ").strip
+    Search and filter architecture resources using a powerful query language.
+
+    QUERY SYNTAX:
+
+    • Name search: 'kubernetes' (shortcut for name =~ "kubernetes"), 'name == "ExactName"', 'name =~ "pattern"'
+
+    • Kind filter prefix: 'TechnologyArtifact: ...' restricts search to that resource type
+
+    • Annotation filters: 'activity/status == "active"', 'scc/language/Go/loc > 5000'
+      Operators: == (equals), != (not equals), =~ (regex match), >, <, >=, <=
+
+    • Relation queries:
+      -> Kind (has outgoing relation to kind), -> "Name" (to specific instance)
+      <- Kind (has incoming relation from kind), <- "Name" (from specific instance)
+      ~> Kind (transitively reaches), <~ Kind (transitively reached by)
+      -> none (no outgoing relations), <- none (no incoming relations / orphan detection)
+
+    • Sub-query targets: $(expression) - dynamic relation matching
+      -> $(expr) (relates to any resource matching expr)
+      ~> $(expr) (transitively reaches any matching resource)
+      <- $(expr) (incoming from any matching resource)
+
+    • Logical operators: AND/and/&, OR/or/|, NOT/not/!, parentheses for grouping
+
+    EXAMPLES:
+    'kubernetes' - resources with "kubernetes" in name
+    'TechnologyArtifact: activity/status == "active"' - active TechnologyArtifacts
+    '-> ApplicationInterface & repository/artifacts == "container"' - containerized services exposing APIs
+    '<- none' - resources not referenced by anything (potential orphans)
+    '-> none & <- none' - true orphans with no relations at all
+    '~> $(dcd-mf-dcxpress)' - transitively reaches instance matching "dcd-mf-dcxpress"
+    '<- $(TechnologyArtifact: activity/status == "active")' - referenced by active artifacts
+  DESC
+  arguments do
+    required(:query).filled(:string).description(
+      "Query string using the query language syntax. " \
+      'Examples: \'kubernetes\', \'TechnologyArtifact: activity/status == "active"\', ' \
+      "'-> ApplicationInterface', '<- none'"
+    )
+    optional(:output).filled(:string).description(
+      "Output format: " \
+      "'complete' = full resource details including annotations and relations (default), " \
+      "'brief' = minimal output with just kind and name for each resource, " \
+      "'count' = only totals grouped by kind, no individual resources returned"
+    )
+    optional(:limit).filled(:integer).description(
+      "Maximum results to return (1-500). Use with offset for pagination. Ignored when output='count'."
+    )
+    optional(:offset).filled(:integer).description(
+      "Number of results to skip. Use with limit for pagination (e.g., offset=50, limit=50 for page 2). " \
+      "Ignored when output='count'."
+    )
+  end
+
+  def call(query:, output: "complete", limit: 50, offset: 0)
+    db = Archsight::MCP.db
+
+    begin
+      parsed_query = Archsight::Query.parse(query)
+      results = parsed_query.filter(db)
+      total = results.length
+
+      # Omit kind from output when filtering by a specific kind (it's redundant)
+      omit_kind = !parsed_query.kind_filter.nil?
+
+      # Count-only mode: return totals grouped by kind
+      if output == "count"
+        by_kind = results.group_by { |r| r.class.to_s.split("::").last }
+                         .transform_values(&:length)
+
+        result = {
+          query: query,
+          total: total,
+          by_kind: by_kind
+        }
+      else
+        # Complete or brief mode: return paginated resources
+        paginated = results.sort_by(&:name).drop(offset).take(limit)
+        resources = case output
+                    when "brief"
+                      paginated.map { |r| Archsight::MCP.brief_summary(r, omit_kind: omit_kind) }
+                    else # "complete"
+                      paginated.map { |r| Archsight::MCP.complete_summary(r, omit_kind: omit_kind) }
+                    end
+
+        result = {
+          query: query,
+          total: total,
+          limit: limit,
+          offset: offset,
+          count: paginated.length,
+          resources: resources
+        }
+      end
+
+      JSON.pretty_generate(result)
+    rescue Archsight::Query::QueryError => e
+      JSON.pretty_generate({
+                             error: "Query error",
+                             message: e.message,
+                             query: query
+                           })
+    end
+  end
+end

data/lib/archsight/mcp/resource_doc_tool.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Archsight::MCP::ResourceDocTool < FastMcp::Tool
+  tool_name "resource_doc"
+
+  description <<~DESC.gsub("\n", " ").strip
+    Get documentation for architecture resource kinds.
+
+    TWO MODES OF OPERATION:
+
+    1. LIST MODE (no kind specified): Returns a list of all available resource kinds with their descriptions.
+       Useful for discovering what types of resources exist in the architecture model.
+       Example: call with no parameters
+
+    2. DOCUMENTATION MODE (kind specified): Returns detailed documentation for a specific resource kind.
+       Includes description, available annotations, relations, and a YAML example template.
+       Example: kind="TechnologyArtifact"
+
+    COMMON RESOURCE KINDS:
+    • TechnologyArtifact - Code repositories, artifacts, and technology components
+    • ApplicationComponent - Services and application building blocks
+    • ApplicationInterface - APIs and interfaces exposed by components
+    • ApplicationService - Business services provided by applications
+    • BusinessRequirement - Compliance controls and business requirements
+    • ComplianceEvidence - Evidence linking artifacts to compliance requirements
+  DESC
+  arguments do
+    optional(:kind).filled(:string).description(
+      'Resource kind to get documentation for (e.g., "TechnologyArtifact", "ApplicationComponent"). ' \
+      "If not specified, returns a list of all available resource kinds."
+    )
+  end
+
+  def call(kind: nil)
+    if kind.nil? || kind.empty?
+      list_resource_kinds
+    else
+      get_resource_documentation(kind)
+    end
+  rescue StandardError => e
+    error_response(e.message, e.class.name)
+  end
+
+  private
+
+  def error_response(message, error_type = "Error")
+    JSON.pretty_generate({
+                           error: error_type,
+                           message: message
+                         })
+  end
+
+  def list_resource_kinds
+    kinds = []
+
+    Archsight::Resources.each do |kind_symbol|
+      klass = Archsight::Resources.const_get(kind_symbol)
+      kinds << {
+        kind: kind_symbol.to_s,
+        description: klass.description || "No description available",
+        annotation_count: klass.annotations.count,
+        relation_count: klass.relations.count
+      }
+    end
+
+    result = {
+      total: kinds.length,
+      resource_kinds: kinds
+    }
+
+    JSON.pretty_generate(result)
+  end
+
+  def get_resource_documentation(kind)
+    klass = Archsight::Resources[kind]
+    return error_response("Unknown resource kind: #{kind}") unless klass
+
+    content = Archsight::Documentation.generate(kind)
+
+    JSON.pretty_generate({
+                           kind: kind,
+                           documentation: content
+                         })
+  end
+end

data/lib/archsight/mcp.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "mcp/base"
+require_relative "mcp/query_tool"
+require_relative "mcp/analyze_resource_tool"
+require_relative "mcp/resource_doc_tool"

data/lib/archsight/query/ast.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# AST module contains all Abstract Syntax Tree node types for the query language
+module Archsight::Query::AST
+  # Base class for all AST nodes
+  class Node
+    def accept(visitor)
+      raise NotImplementedError
+    end
+  end
+
+  # Root query node with optional kind filter
+  class QueryNode < Node
+    attr_reader :kind_filter, :expression
+
+    def initialize(kind_filter, expression)
+      @kind_filter = kind_filter # String or nil
+      @expression = expression   # Expression node
+    end
+
+    def accept(visitor)
+      visitor.visit_query(self)
+    end
+  end
+
+  # Binary logical operation (AND, OR)
+  class BinaryOp < Node
+    attr_reader :operator, :left, :right
+
+    def initialize(operator, left, right)
+      @operator = operator # :and, :or
+      @left = left
+      @right = right
+    end
+
+    def accept(visitor)
+      visitor.visit_binary_op(self)
+    end
+  end
+
+  # Unary NOT operation
+  class NotOp < Node
+    attr_reader :operand
+
+    def initialize(operand)
+      @operand = operand
+    end
+
+    def accept(visitor)
+      visitor.visit_not_op(self)
+    end
+  end
+
+  # Annotation condition: annotation_path op value
+  class AnnotationCondition < Node
+    attr_reader :path, :operator, :value
+
+    def initialize(path, operator, value)
+      @path = path         # String (e.g., "activity/status")
+      @operator = operator # String (==, !=, =~, >, <, >=, <=)
+      @value = value       # StringValue, NumberValue, or RegexValue
+    end
+
+    def accept(visitor)
+      visitor.visit_annotation_condition(self)
+    end
+  end
+
+  # Annotation existence condition: annotation_path? (checks if annotation exists)
+  class AnnotationExistsCondition < Node
+    attr_reader :path
+
+    def initialize(path)
+      @path = path # String (e.g., "activity/status")
+    end
+
+    def accept(visitor)
+      visitor.visit_annotation_exists_condition(self)
+    end
+  end
+
+  # Annotation "in" condition: annotation_path in (value1, value2, ...)
+  class AnnotationInCondition < Node
+    attr_reader :path, :values
+
+    def initialize(path, values)
+      @path = path     # String (e.g., "repository/artifacts")
+      @values = values # Array of StringValue
+    end
+
+    def accept(visitor)
+      visitor.visit_annotation_in_condition(self)
+    end
+  end
+
+  # Kind condition: kind == "SomeKind" or kind =~ "pattern"
+  class KindCondition < Node
+    attr_reader :operator, :value
+
+    def initialize(operator, value)
+      @operator = operator # String (==, =~)
+      @value = value       # StringValue or RegexValue
+    end
+
+    def accept(visitor)
+      visitor.visit_kind_condition(self)
+    end
+  end
+
+  # Kind "in" condition: kind in ("Kind1", "Kind2", ...)
+  class KindInCondition < Node
+    attr_reader :values
+
+    def initialize(values)
+      @values = values # Array of StringValue
+    end
+
+    def accept(visitor)
+      visitor.visit_kind_in_condition(self)
+    end
+  end
+
+  # Name condition: name == "value" or name =~ "pattern"
+  class NameCondition < Node
+    attr_reader :operator, :value
+
+    def initialize(operator, value)
+      @operator = operator # String (==, !=, =~)
+      @value = value       # StringValue or RegexValue
+    end
+
+    def accept(visitor)
+      visitor.visit_name_condition(self)
+    end
+  end
+
+  # Name "in" condition: name in ("name1", "name2", ...)
+  class NameInCondition < Node
+    attr_reader :values
+
+    def initialize(values)
+      @values = values # Array of StringValue
+    end
+
+    def accept(visitor)
+      visitor.visit_name_in_condition(self)
+    end
+  end
+
+  # Outgoing direct relation: -> Kind or -> "InstanceName"
+  # With optional verb filter: -{verb}> or -{!verb}>
+  class OutgoingDirectRelation < Node
+    attr_reader :target, :verbs, :exclude_verbs
+
+    def initialize(target, verbs = nil, exclude_verbs = false)
+      @target = target               # KindTarget or InstanceTarget
+      @verbs = verbs                 # Array of verb strings, or nil for "all verbs"
+      @exclude_verbs = exclude_verbs # true = denylist, false = allowlist
+    end
+
+    def accept(visitor)
+      visitor.visit_outgoing_direct_relation(self)
+    end
+  end
+
+  # Outgoing transitive relation: ~> Kind or ~> "InstanceName"
+  # With optional verb filter: ~{verb}> or ~{!verb}>
+  class OutgoingTransitiveRelation < Node
+    attr_reader :target, :max_depth, :verbs, :exclude_verbs
+
+    def initialize(target, verbs = nil, exclude_verbs = false, max_depth = 10)
+      @target = target
+      @verbs = verbs                 # Array of verb strings, or nil for "all verbs"
+      @exclude_verbs = exclude_verbs # true = denylist, false = allowlist
+      @max_depth = max_depth
+    end
+
+    def accept(visitor)
+      visitor.visit_outgoing_transitive_relation(self)
+    end
+  end
+
+  # Incoming direct relation: <- Kind or <- "InstanceName"
+  # With optional verb filter: <{verb}- or <{!verb}-
+  class IncomingDirectRelation < Node
+    attr_reader :target, :verbs, :exclude_verbs
+
+    def initialize(target, verbs = nil, exclude_verbs = false)
+      @target = target               # KindTarget or InstanceTarget
+      @verbs = verbs                 # Array of verb strings, or nil for "all verbs"
+      @exclude_verbs = exclude_verbs # true = denylist, false = allowlist
+    end
+
+    def accept(visitor)
+      visitor.visit_incoming_direct_relation(self)
+    end
+  end
+
+  # Incoming transitive relation: <~ Kind or <~ "InstanceName"
+  # With optional verb filter: <{verb}~ or <{!verb}~
+  class IncomingTransitiveRelation < Node
+    attr_reader :target, :max_depth, :verbs, :exclude_verbs
+
+    def initialize(target, verbs = nil, exclude_verbs = false, max_depth = 10)
+      @target = target
+      @verbs = verbs                 # Array of verb strings, or nil for "all verbs"
+      @exclude_verbs = exclude_verbs # true = denylist, false = allowlist
+      @max_depth = max_depth
+    end
+
+    def accept(visitor)
+      visitor.visit_incoming_transitive_relation(self)
+    end
+  end
+
+  # Relation target: a kind name (identifier)
+  class KindTarget
+    attr_reader :kind_name
+
+    def initialize(kind_name)
+      @kind_name = kind_name
+    end
+  end
+
+  # Relation target: a specific instance name (string)
+  class InstanceTarget
+    attr_reader :instance_name
+
+    def initialize(instance_name)
+      @instance_name = instance_name
+    end
+  end
+
+  # Relation target: nothing (no relations)
+  # Used with -> # (no outgoing) or <- # (no incoming)
+  class NothingTarget
+  end
+
+  # Relation target: sub-query result
+  # Used with -> $(expr) to match against query results
+  class SubqueryTarget
+    attr_reader :query
+
+    def initialize(query)
+      @query = query # QueryNode - the inner sub-query to evaluate
+    end
+  end
+
+  # Value types
+  class StringValue
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+  end
+
+  class NumberValue
+    attr_reader :value
+
+    def initialize(value)
+      @value = value.to_f
+    end
+  end
+
+  class RegexValue
+    attr_reader :pattern, :flags
+
+    def initialize(pattern, flags = "")
+      @pattern = pattern
+      @flags = flags
+    end
+
+    def to_regexp
+      options = @flags.include?("i") ? Regexp::IGNORECASE : 0
+      Regexp.new(@pattern, options)
+    end
+  end
+end

data/lib/archsight/query/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Base error class for all query-related errors
+class Archsight::Query::QueryError < StandardError
+  attr_reader :position, :source
+
+  def initialize(message, position: nil, source: nil)
+    @position = position
+    @source = source
+    super(message)
+  end
+
+  def to_s
+    if @position && @source
+      line_info = extract_line_info
+      "#{super}\n#{line_info}"
+    else
+      super
+    end
+  end
+
+  private
+
+  def extract_line_info
+    return "" unless @source && @position
+
+    pointer = "#{" " * @position}^"
+    "  #{@source}\n  #{pointer}"
+  end
+end
+
+# Error during lexical analysis (tokenization)
+class Archsight::Query::LexerError < Archsight::Query::QueryError; end
+
+# Error during parsing
+class Archsight::Query::ParseError < Archsight::Query::QueryError; end
+
+# Error during query evaluation
+class Archsight::Query::EvaluationError < Archsight::Query::QueryError; end