aidp 0.28.0 → 0.30.0

data/lib/aidp/metadata/query.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "tool_metadata"
+require_relative "cache"
+
+module Aidp
+  module Metadata
+    # Query interface for tool-choosing agent
+    #
+    # Provides filtering, ranking, and dependency resolution for tools
+    # based on metadata criteria.
+    #
+    # @example Querying for tools
+    #   query = Query.new(cache: cache)
+    #   tools = query.find_by_tags(["ruby", "testing"])
+    #   ranked = query.rank_by_priority(tools)
+    class Query
+      # Initialize query interface
+      #
+      # @param cache [Cache] Metadata cache instance
+      def initialize(cache:)
+        @cache = cache
+        @directory = nil
+      end
+
+      # Load directory (lazy)
+      #
+      # @return [Hash] Tool directory
+      def directory
+        @directory ||= @cache.load
+      end
+
+      # Reload directory
+      def reload
+        @directory = @cache.reload
+      end
+
+      # Find tool by ID
+      #
+      # @param id [String] Tool ID
+      # @return [Hash, nil] Tool metadata or nil
+      def find_by_id(id)
+        tools = directory["tools"]
+        tools.find { |tool| tool["id"] == id }
+      end
+
+      # Find tools by type
+      #
+      # @param type [String] Tool type ("skill", "persona", "template")
+      # @return [Array<Hash>] Matching tools
+      def find_by_type(type)
+        indexes = directory["indexes"]["by_type"]
+        tool_ids = indexes[type] || []
+        tools_by_ids(tool_ids)
+      end
+
+      # Find tools by applies_to tags
+      #
+      # @param tags [Array<String>] Tags to filter by
+      # @param match_all [Boolean] Whether to match all tags (AND) or any tag (OR)
+      # @return [Array<Hash>] Matching tools
+      def find_by_tags(tags, match_all: false)
+        Aidp.log_debug("metadata", "Finding by tags", tags: tags, match_all: match_all)
+
+        tags = Array(tags).map(&:downcase)
+        indexes = directory["indexes"]["by_tag"]
+
+        if match_all
+          # Find tools that have ALL specified tags
+          tool_ids_sets = tags.map { |tag| indexes[tag] || [] }
+          tool_ids = tool_ids_sets.reduce(&:&) || []
+        else
+          # Find tools that have ANY specified tag
+          tool_ids = tags.flat_map { |tag| indexes[tag] || [] }.uniq
+        end
+
+        tools = tools_by_ids(tool_ids)
+
+        Aidp.log_debug("metadata", "Found tools by tags", count: tools.size)
+
+        tools
+      end
+
+      # Find tools by work unit type
+      #
+      # @param work_unit_type [String] Work unit type (e.g., "implementation", "analysis")
+      # @return [Array<Hash>] Matching tools
+      def find_by_work_unit_type(work_unit_type)
+        Aidp.log_debug("metadata", "Finding by work unit type", type: work_unit_type)
+
+        indexes = directory["indexes"]["by_work_unit_type"]
+        tool_ids = indexes[work_unit_type.downcase] || []
+        tools = tools_by_ids(tool_ids)
+
+        Aidp.log_debug("metadata", "Found tools by work unit type", count: tools.size)
+
+        tools
+      end
+
+      # Filter tools by multiple criteria
+      #
+      # @param type [String, nil] Tool type filter
+      # @param tags [Array<String>, nil] Tag filter
+      # @param work_unit_type [String, nil] Work unit type filter
+      # @param experimental [Boolean, nil] Experimental filter (true/false/nil for all)
+      # @return [Array<Hash>] Filtered tools
+      def filter(type: nil, tags: nil, work_unit_type: nil, experimental: nil)
+        Aidp.log_debug(
+          "metadata",
+          "Filtering tools",
+          type: type,
+          tags: tags,
+          work_unit_type: work_unit_type,
+          experimental: experimental
+        )
+
+        tools = directory["tools"]
+
+        # Filter by type
+        tools = tools.select { |t| t["type"] == type } if type
+
+        # Filter by tags
+        if tags && !tags.empty?
+          tags = Array(tags).map(&:downcase)
+          tools = tools.select do |t|
+            tool_tags = (t["applies_to"] || []).map(&:downcase)
+            (tool_tags & tags).any?
+          end
+        end
+
+        # Filter by work unit type
+        if work_unit_type
+          wut_lower = work_unit_type.downcase
+          tools = tools.select do |t|
+            (t["work_unit_types"] || []).map(&:downcase).include?(wut_lower)
+          end
+        end
+
+        # Filter by experimental flag
+        tools = tools.select { |t| t["experimental"] == experimental } unless experimental.nil?
+
+        Aidp.log_debug("metadata", "Filtered tools", count: tools.size)
+
+        tools
+      end
+
+      # Rank tools by priority (highest first)
+      #
+      # @param tools [Array<Hash>] Tools to rank
+      # @return [Array<Hash>] Ranked tools
+      def rank_by_priority(tools)
+        tools.sort_by { |t| -(t["priority"] || ToolMetadata::DEFAULT_PRIORITY) }
+      end
+
+      # Resolve dependencies for a tool
+      #
+      # Returns all dependencies recursively in dependency order (topological sort)
+      #
+      # @param tool_id [String] Tool ID
+      # @return [Array<String>] Ordered list of dependency IDs
+      # @raise [Aidp::Errors::ValidationError] if circular dependency detected
+      def resolve_dependencies(tool_id)
+        Aidp.log_debug("metadata", "Resolving dependencies", tool_id: tool_id)
+
+        graph = directory["dependency_graph"]
+        resolved = []
+        seen = Set.new
+
+        resolve_recursive(tool_id, graph, resolved, seen)
+
+        Aidp.log_debug("metadata", "Dependencies resolved", tool_id: tool_id, dependencies: resolved)
+
+        resolved
+      end
+
+      # Find dependents of a tool
+      #
+      # Returns all tools that depend on this tool (directly or indirectly)
+      #
+      # @param tool_id [String] Tool ID
+      # @return [Array<String>] List of dependent tool IDs
+      def find_dependents(tool_id)
+        graph = directory["dependency_graph"]
+        return [] unless graph[tool_id]
+
+        graph[tool_id]["dependents"] || []
+      end
+
+      # Get statistics about the tool directory
+      #
+      # @return [Hash] Statistics
+      def statistics
+        directory["statistics"]
+      end
+
+      private
+
+      # Get tools by IDs
+      #
+      # @param tool_ids [Array<String>] Tool IDs
+      # @return [Array<Hash>] Tools
+      def tools_by_ids(tool_ids)
+        all_tools = directory["tools"]
+        tool_ids.map { |id| all_tools.find { |t| t["id"] == id } }.compact
+      end
+
+      # Resolve dependencies recursively (topological sort)
+      #
+      # @param tool_id [String] Tool ID
+      # @param graph [Hash] Dependency graph
+      # @param resolved [Array<String>] Resolved dependencies (output)
+      # @param seen [Set<String>] Seen tools (for cycle detection)
+      # @raise [Aidp::Errors::ValidationError] if circular dependency detected
+      def resolve_recursive(tool_id, graph, resolved, seen)
+        return if resolved.include?(tool_id)
+
+        if seen.include?(tool_id)
+          raise Aidp::Errors::ValidationError, "Circular dependency detected: #{tool_id}"
+        end
+
+        seen.add(tool_id)
+
+        node = graph[tool_id]
+        if node
+          dependencies = node["dependencies"] || []
+          dependencies.each do |dep_id|
+            resolve_recursive(dep_id, graph, resolved, seen)
+          end
+        end
+
+        resolved << tool_id unless resolved.include?(tool_id)
+        seen.delete(tool_id)
+      end
+    end
+  end
+end

data/lib/aidp/metadata/scanner.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "parser"
+
+module Aidp
+  module Metadata
+    # Scans directories for tool files and extracts metadata
+    #
+    # Recursively finds all .md files in configured directories,
+    # parses their metadata, and returns a collection of ToolMetadata objects.
+    #
+    # @example Scanning directories
+    #   scanner = Scanner.new([".aidp/skills", ".aidp/templates"])
+    #   tools = scanner.scan_all
+    class Scanner
+      # Initialize scanner with directory paths
+      #
+      # @param directories [Array<String>] Directories to scan
+      def initialize(directories = [])
+        @directories = Array(directories)
+      end
+
+      # Scan all configured directories
+      #
+      # @return [Array<ToolMetadata>] All discovered tool metadata
+      def scan_all
+        Aidp.log_debug("metadata", "Scanning directories", directories: @directories)
+
+        all_tools = []
+        @directories.each do |dir|
+          tools = scan_directory(dir)
+          all_tools.concat(tools)
+        end
+
+        Aidp.log_info(
+          "metadata",
+          "Scan complete",
+          directories: @directories.size,
+          tools_found: all_tools.size
+        )
+
+        all_tools
+      end
+
+      # Scan a single directory
+      #
+      # @param directory [String] Directory path to scan
+      # @param type [String, nil] Tool type filter or nil for all
+      # @return [Array<ToolMetadata>] Discovered tool metadata
+      def scan_directory(directory, type: nil)
+        unless Dir.exist?(directory)
+          Aidp.log_warn("metadata", "Directory not found", directory: directory)
+          return []
+        end
+
+        Aidp.log_debug("metadata", "Scanning directory", directory: directory, type: type)
+
+        tools = []
+        md_files = find_markdown_files(directory)
+
+        md_files.each do |file_path|
+          tool = Parser.parse_file(file_path, type: type)
+          tools << tool if type.nil? || tool.type == type
+        rescue Aidp::Errors::ValidationError => e
+          Aidp.log_warn(
+            "metadata",
+            "Failed to parse file",
+            file: file_path,
+            error: e.message
+          )
+        end
+
+        Aidp.log_debug(
+          "metadata",
+          "Directory scan complete",
+          directory: directory,
+          files_found: md_files.size,
+          tools_parsed: tools.size
+        )
+
+        tools
+      end
+
+      # Find all markdown files in directory recursively
+      #
+      # @param directory [String] Directory path
+      # @return [Array<String>] Paths to .md files
+      def find_markdown_files(directory)
+        pattern = File.join(directory, "**", "*.md")
+        files = Dir.glob(pattern)
+
+        Aidp.log_debug(
+          "metadata",
+          "Found markdown files",
+          directory: directory,
+          count: files.size
+        )
+
+        files
+      end
+
+      # Scan with file filtering
+      #
+      # @param directory [String] Directory path
+      # @param filter [Proc] Filter proc that receives file_path and returns boolean
+      # @return [Array<ToolMetadata>] Filtered tool metadata
+      def scan_with_filter(directory, &filter)
+        unless Dir.exist?(directory)
+          Aidp.log_warn("metadata", "Directory not found", directory: directory)
+          return []
+        end
+
+        tools = []
+        md_files = find_markdown_files(directory)
+
+        md_files.each do |file_path|
+          next unless filter.call(file_path)
+
+          begin
+            tool = Parser.parse_file(file_path)
+            tools << tool
+          rescue Aidp::Errors::ValidationError => e
+            Aidp.log_warn(
+              "metadata",
+              "Failed to parse file",
+              file: file_path,
+              error: e.message
+            )
+          end
+        end
+
+        tools
+      end
+
+      # Scan for changes since last scan
+      #
+      # Compares file hashes to detect changes
+      #
+      # @param directory [String] Directory path
+      # @param previous_hashes [Hash<String, String>] Map of file_path => file_hash
+      # @return [Hash] Hash with :added, :modified, :removed keys
+      def scan_changes(directory, previous_hashes = {})
+        Aidp.log_debug("metadata", "Scanning for changes", directory: directory)
+
+        current_files = find_markdown_files(directory)
+        current_hashes = {}
+
+        changes = {
+          added: [],
+          modified: [],
+          removed: [],
+          unchanged: []
+        }
+
+        # Check for added and modified files
+        current_files.each do |file_path|
+          content = File.read(file_path, encoding: "UTF-8")
+          file_hash = Parser.compute_file_hash(content)
+          current_hashes[file_path] = file_hash
+
+          if previous_hashes.key?(file_path)
+            if previous_hashes[file_path] != file_hash
+              changes[:modified] << file_path
+            else
+              changes[:unchanged] << file_path
+            end
+          else
+            changes[:added] << file_path
+          end
+        end
+
+        # Check for removed files
+        previous_hashes.keys.each do |file_path|
+          changes[:removed] << file_path unless current_hashes.key?(file_path)
+        end
+
+        Aidp.log_info(
+          "metadata",
+          "Change detection complete",
+          added: changes[:added].size,
+          modified: changes[:modified].size,
+          removed: changes[:removed].size,
+          unchanged: changes[:unchanged].size
+        )
+
+        changes
+      end
+    end
+  end
+end

data/lib/aidp/metadata/tool_metadata.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Aidp
+  module Metadata
+    # Base class for tool metadata (skills, personas, templates)
+    #
+    # Represents metadata extracted from YAML frontmatter in .md files.
+    # Provides validation and query capabilities for the tool directory.
+    #
+    # @example Creating tool metadata
+    #   metadata = ToolMetadata.new(
+    #     type: "skill",
+    #     id: "ruby_rspec_tdd",
+    #     title: "Ruby RSpec TDD Implementer",
+    #     summary: "Expert in Test-Driven Development",
+    #     version: "1.0.0",
+    #     applies_to: ["ruby", "testing"],
+    #     work_unit_types: ["implementation", "testing"],
+    #     priority: 10,
+    #     content: "You are a TDD expert...",
+    #     source_path: "/path/to/SKILL.md"
+    #   )
+    class ToolMetadata
+      attr_reader :type, :id, :title, :summary, :version,
+        :applies_to, :work_unit_types, :priority,
+        :capabilities, :dependencies, :experimental,
+        :content, :source_path, :file_hash
+
+      # Valid tool types
+      VALID_TYPES = %w[skill persona template].freeze
+
+      # Default priority (medium)
+      DEFAULT_PRIORITY = 5
+
+      # Initialize new tool metadata
+      #
+      # @param type [String] Tool type: "skill", "persona", or "template"
+      # @param id [String] Unique identifier (lowercase, alphanumeric, underscores)
+      # @param title [String] Human-readable title
+      # @param summary [String] Brief one-line summary
+      # @param version [String] Semantic version (e.g., "1.0.0")
+      # @param applies_to [Array<String>] Tags indicating applicability
+      # @param work_unit_types [Array<String>] Work unit types this tool supports
+      # @param priority [Integer] Priority for ranking (1-10, default 5)
+      # @param capabilities [Array<String>] Capabilities provided by this tool
+      # @param dependencies [Array<String>] IDs of required tools
+      # @param experimental [Boolean] Whether this is experimental
+      # @param content [String] The tool content (markdown)
+      # @param source_path [String] Path to source .md file
+      # @param file_hash [String] SHA256 hash of source file for cache invalidation
+      def initialize(
+        type:,
+        id:,
+        title:,
+        summary:,
+        version:,
+        content:,
+        source_path:,
+        file_hash:,
+        applies_to: [],
+        work_unit_types: [],
+        priority: DEFAULT_PRIORITY,
+        capabilities: [],
+        dependencies: [],
+        experimental: false
+      )
+        @type = type
+        @id = id
+        @title = title
+        @summary = summary
+        @version = version
+        @applies_to = Array(applies_to)
+        @work_unit_types = Array(work_unit_types)
+        @priority = priority
+        @capabilities = Array(capabilities)
+        @dependencies = Array(dependencies)
+        @experimental = experimental
+        @content = content
+        @source_path = source_path
+        @file_hash = file_hash
+
+        validate!
+      end
+
+      # Check if this tool applies to given tags
+      #
+      # @param tags [Array<String>] Tags to check against
+      # @return [Boolean] True if any tag matches applies_to
+      def applies_to?(tags)
+        return true if applies_to.empty?
+        tags = Array(tags).map(&:downcase)
+        applies_to.map(&:downcase).any? { |tag| tags.include?(tag) }
+      end
+
+      # Check if this tool supports a given work unit type
+      #
+      # @param type [String] Work unit type (e.g., "implementation", "analysis")
+      # @return [Boolean] True if type is supported
+      def supports_work_unit?(type)
+        return true if work_unit_types.empty?
+        work_unit_types.map(&:downcase).include?(type.to_s.downcase)
+      end
+
+      # Get a summary of this tool for display
+      #
+      # @return [Hash] Summary with key metadata
+      def summary_hash
+        {
+          type: type,
+          id: id,
+          title: title,
+          summary: summary,
+          version: version,
+          priority: priority,
+          tags: applies_to,
+          experimental: experimental
+        }
+      end
+
+      # Get full details of this tool for display
+      #
+      # @return [Hash] Detailed tool information
+      def details
+        {
+          type: type,
+          id: id,
+          title: title,
+          summary: summary,
+          version: version,
+          applies_to: applies_to,
+          work_unit_types: work_unit_types,
+          priority: priority,
+          capabilities: capabilities,
+          dependencies: dependencies,
+          experimental: experimental,
+          source: source_path,
+          file_hash: file_hash,
+          content_length: content.length
+        }
+      end
+
+      # Convert to hash for serialization
+      #
+      # @return [Hash] Metadata as hash (for JSON)
+      def to_h
+        {
+          type: type,
+          id: id,
+          title: title,
+          summary: summary,
+          version: version,
+          applies_to: applies_to,
+          work_unit_types: work_unit_types,
+          priority: priority,
+          capabilities: capabilities,
+          dependencies: dependencies,
+          experimental: experimental,
+          source_path: source_path,
+          file_hash: file_hash
+        }
+      end
+
+      # Return string representation
+      #
+      # @return [String] Tool representation
+      def to_s
+        "#{type.capitalize}[#{id}](#{title} v#{version})"
+      end
+
+      # Return inspection string
+      #
+      # @return [String] Detailed inspection
+      def inspect
+        "#<Aidp::Metadata::ToolMetadata type=#{type} id=#{id} title=\"#{title}\" " \
+          "version=#{version} source=#{source_path}>"
+      end
+
+      private
+
+      # Validate required fields and types
+      #
+      # @raise [Aidp::Errors::ValidationError] if validation fails
+      def validate!
+        validate_required_fields!
+        validate_types!
+        validate_formats!
+        validate_ranges!
+      end
+
+      # Validate required fields are present
+      def validate_required_fields!
+        raise Aidp::Errors::ValidationError, "type is required" if type.nil? || type.strip.empty?
+        raise Aidp::Errors::ValidationError, "id is required" if id.nil? || id.strip.empty?
+        raise Aidp::Errors::ValidationError, "title is required" if title.nil? || title.strip.empty?
+        raise Aidp::Errors::ValidationError, "summary is required" if summary.nil? || summary.strip.empty?
+        raise Aidp::Errors::ValidationError, "version is required" if version.nil? || version.strip.empty?
+        raise Aidp::Errors::ValidationError, "content is required" if content.nil? || content.strip.empty?
+        raise Aidp::Errors::ValidationError, "source_path is required" if source_path.nil? || source_path.strip.empty?
+        raise Aidp::Errors::ValidationError, "file_hash is required" if file_hash.nil? || file_hash.strip.empty?
+      end
+
+      # Validate field types
+      def validate_types!
+        unless VALID_TYPES.include?(type)
+          raise Aidp::Errors::ValidationError, "type must be one of: #{VALID_TYPES.join(", ")}"
+        end
+
+        unless priority.is_a?(Integer)
+          raise Aidp::Errors::ValidationError, "priority must be an integer"
+        end
+
+        unless [true, false].include?(experimental)
+          raise Aidp::Errors::ValidationError, "experimental must be boolean"
+        end
+      end
+
+      # Validate field formats
+      def validate_formats!
+        # Validate version format (simple semantic version check)
+        unless version.match?(/^\d+\.\d+\.\d+/)
+          raise Aidp::Errors::ValidationError, "version must be in format X.Y.Z (e.g., 1.0.0)"
+        end
+
+        # Validate id format (lowercase, alphanumeric, underscores only)
+        unless id.match?(/^[a-z0-9_]+$/)
+          raise Aidp::Errors::ValidationError, "id must be lowercase alphanumeric with underscores only"
+        end
+
+        # Validate file_hash format (SHA256 hex)
+        unless file_hash.match?(/^[a-f0-9]{64}$/)
+          raise Aidp::Errors::ValidationError, "file_hash must be a valid SHA256 hex string"
+        end
+      end
+
+      # Validate value ranges
+      def validate_ranges!
+        unless priority.between?(1, 10)
+          raise Aidp::Errors::ValidationError, "priority must be between 1 and 10"
+        end
+      end
+    end
+  end
+end