tsikol 0.1.0

data/docs/examples/code-assistant.md

@@ -0,0 +1,922 @@
+# Code Assistant Example
+
+An intelligent MCP server that provides code analysis, generation, and refactoring capabilities with AI-powered features.
+
+## Overview
+
+This example demonstrates:
+- File system operations
+- Code analysis and parsing
+- AI-powered code generation (sampling)
+- Syntax highlighting
+- Git integration
+- Code completion
+- Advanced prompt engineering
+
+## Implementation
+
+### server.rb
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'tsikol'
+require 'parser/current'
+require 'syntax_tree'
+require 'rugged'
+require 'rouge'
+
+# Code analysis tool
+class CodeAnalyzerTool < Tsikol::Tool
+  name "analyze_code"
+  description "Analyze code for quality, complexity, and potential issues"
+  
+  parameter :file_path do
+    type :string
+    required
+    description "Path to the file to analyze"
+    
+    complete do |partial|
+      Dir.glob("#{partial}*").select { |f| File.file?(f) }
+    end
+  end
+  
+  parameter :checks do
+    type :array
+    optional
+    default ["complexity", "style", "security"]
+    description "Types of checks to perform"
+  end
+  
+  def execute(file_path:, checks: ["complexity", "style", "security"])
+    unless File.exist?(file_path)
+      raise ArgumentError, "File not found: #{file_path}"
+    end
+    
+    content = File.read(file_path)
+    language = detect_language(file_path)
+    
+    results = {
+      file: file_path,
+      language: language,
+      metrics: analyze_metrics(content, language),
+      issues: []
+    }
+    
+    # Perform requested checks
+    checks.each do |check|
+      case check
+      when "complexity"
+        results[:issues].concat(check_complexity(content, language))
+      when "style"
+        results[:issues].concat(check_style(content, language))
+      when "security"
+        results[:issues].concat(check_security(content, language))
+      end
+    end
+    
+    format_analysis_results(results)
+  end
+  
+  private
+  
+  def detect_language(file_path)
+    case File.extname(file_path)
+    when ".rb" then "ruby"
+    when ".py" then "python"
+    when ".js" then "javascript"
+    when ".java" then "java"
+    when ".go" then "go"
+    else "unknown"
+    end
+  end
+  
+  def analyze_metrics(content, language)
+    lines = content.lines
+    
+    {
+      lines_of_code: lines.count,
+      blank_lines: lines.count(&:blank?),
+      comment_lines: count_comment_lines(lines, language),
+      average_line_length: lines.map(&:length).sum.to_f / lines.count
+    }
+  end
+  
+  def check_complexity(content, language)
+    issues = []
+    
+    if language == "ruby"
+      ast = Parser::CurrentRuby.parse(content)
+      
+      # Check method complexity
+      processor = ComplexityProcessor.new
+      processor.process(ast)
+      
+      processor.complex_methods.each do |method|
+        issues << {
+          type: "complexity",
+          severity: "warning",
+          line: method[:line],
+          message: "Method '#{method[:name]}' has cyclomatic complexity of #{method[:complexity]} (threshold: 10)"
+        }
+      end
+    end
+    
+    issues
+  end
+  
+  def format_analysis_results(results)
+    output = ["Code Analysis Results", "=" * 40, ""]
+    
+    output << "File: #{results[:file]}"
+    output << "Language: #{results[:language]}"
+    output << ""
+    output << "Metrics:"
+    results[:metrics].each do |key, value|
+      output << "  #{key.to_s.gsub('_', ' ').capitalize}: #{value.is_a?(Float) ? value.round(2) : value}"
+    end
+    
+    if results[:issues].any?
+      output << ""
+      output << "Issues Found:"
+      results[:issues].group_by { |i| i[:type] }.each do |type, issues|
+        output << ""
+        output << "  #{type.capitalize}:"
+        issues.each do |issue|
+          output << "    Line #{issue[:line]}: [#{issue[:severity]}] #{issue[:message]}"
+        end
+      end
+    else
+      output << ""
+      output << "No issues found!"
+    end
+    
+    output.join("\n")
+  end
+end
+
+# Code generation tool with sampling
+class CodeGeneratorTool < Tsikol::Tool
+  name "generate_code"
+  description "Generate code based on specifications using AI"
+  
+  # Enable sampling for this tool
+  sampling true
+  
+  parameter :specification do
+    type :string
+    required
+    description "Description of what code to generate"
+  end
+  
+  parameter :language do
+    type :string
+    required
+    enum ["ruby", "python", "javascript", "java", "go"]
+    description "Target programming language"
+  end
+  
+  parameter :style do
+    type :string
+    optional
+    default "clean"
+    enum ["clean", "documented", "compact", "enterprise"]
+    description "Code style preference"
+  end
+  
+  parameter :include_tests do
+    type :boolean
+    optional
+    default false
+    description "Include unit tests"
+  end
+  
+  def execute(specification:, language:, style: "clean", include_tests: false)
+    # Use AI sampling to generate code
+    messages = build_generation_messages(specification, language, style, include_tests)
+    
+    response = @server.sample_text(
+      messages: messages,
+      max_tokens: 2000,
+      temperature: 0.3  # Lower temperature for more consistent code
+    )
+    
+    if response[:error]
+      raise "Code generation failed: #{response[:error]}"
+    end
+    
+    generated_code = response[:text]
+    
+    # Format and validate generated code
+    formatted_code = format_code(generated_code, language)
+    
+    if include_tests
+      test_code = generate_tests(specification, formatted_code, language)
+      formatted_code += "\n\n" + test_code
+    end
+    
+    formatted_code
+  end
+  
+  private
+  
+  def build_generation_messages(spec, language, style, include_tests)
+    system_prompt = build_system_prompt(language, style)
+    
+    user_prompt = <<~PROMPT
+      Generate #{language} code for the following specification:
+      
+      #{spec}
+      
+      Requirements:
+      - Follow #{style} coding style
+      - Include error handling
+      - Add appropriate comments
+      #{include_tests ? "- Include comprehensive unit tests" : ""}
+    PROMPT
+    
+    [
+      {
+        role: "system",
+        content: { type: "text", text: system_prompt }
+      },
+      {
+        role: "user",
+        content: { type: "text", text: user_prompt }
+      }
+    ]
+  end
+  
+  def build_system_prompt(language, style)
+    base = "You are an expert #{language} developer. Generate high-quality, production-ready code."
+    
+    style_guides = {
+      "clean" => "Follow clean code principles: clear naming, small functions, minimal complexity.",
+      "documented" => "Include comprehensive documentation: docstrings, inline comments, usage examples.",
+      "compact" => "Write concise code while maintaining readability. Avoid unnecessary verbosity.",
+      "enterprise" => "Follow enterprise patterns: interfaces, dependency injection, comprehensive error handling."
+    }
+    
+    "#{base} #{style_guides[style]}"
+  end
+end
+
+# Code refactoring tool
+class CodeRefactorTool < Tsikol::Tool
+  name "refactor_code"
+  description "Refactor code to improve quality and maintainability"
+  
+  parameter :file_path do
+    type :string
+    required
+    description "Path to file to refactor"
+  end
+  
+  parameter :refactoring_type do
+    type :string
+    required
+    enum ["extract_method", "rename", "simplify", "dry", "modernize"]
+    description "Type of refactoring to perform"
+  end
+  
+  parameter :options do
+    type :object
+    optional
+    default {}
+    description "Refactoring-specific options"
+  end
+  
+  def execute(file_path:, refactoring_type:, options: {})
+    unless File.exist?(file_path)
+      raise ArgumentError, "File not found: #{file_path}"
+    end
+    
+    content = File.read(file_path)
+    language = detect_language(file_path)
+    
+    refactored = case refactoring_type
+    when "extract_method"
+      extract_method(content, language, options)
+    when "rename"
+      rename_symbols(content, language, options)
+    when "simplify"
+      simplify_code(content, language)
+    when "dry"
+      remove_duplication(content, language)
+    when "modernize"
+      modernize_code(content, language)
+    end
+    
+    # Show diff
+    format_refactoring_result(content, refactored, refactoring_type)
+  end
+  
+  private
+  
+  def extract_method(content, language, options)
+    start_line = options["start_line"] || raise("start_line required")
+    end_line = options["end_line"] || raise("end_line required")
+    method_name = options["method_name"] || "extracted_method"
+    
+    lines = content.lines
+    extracted = lines[start_line-1..end_line-1]
+    
+    # Simple extraction (real implementation would analyze variables)
+    new_method = "\ndef #{method_name}\n#{extracted.map { |l| "  #{l}" }.join}\nend\n"
+    
+    # Replace with method call
+    lines[start_line-1..end_line-1] = ["#{method_name}\n"]
+    
+    lines.join + new_method
+  end
+  
+  def format_refactoring_result(original, refactored, type)
+    <<~RESULT
+      Refactoring: #{type}
+      #{"=" * 40}
+      
+      Original:
+      #{original}
+      
+      #{"=" * 40}
+      
+      Refactored:
+      #{refactored}
+      
+      #{"=" * 40}
+      
+      Summary:
+      - Lines changed: #{count_changed_lines(original, refactored)}
+      - Size difference: #{refactored.length - original.length} chars
+    RESULT
+  end
+end
+
+# Git integration resource
+class GitResource < Tsikol::Resource
+  uri "git/:command/:path?"
+  description "Git repository information and operations"
+  
+  def read
+    command = params[:command]
+    path = params[:path] || "."
+    
+    repo = Rugged::Repository.new(path)
+    
+    case command
+    when "status"
+      git_status(repo)
+    when "log"
+      git_log(repo)
+    when "branches"
+      git_branches(repo)
+    when "diff"
+      git_diff(repo)
+    else
+      { error: "Unknown git command: #{command}" }.to_json
+    end
+  rescue Rugged::RepositoryError => e
+    { error: "Git error: #{e.message}" }.to_json
+  end
+  
+  private
+  
+  def git_status(repo)
+    status = {
+      branch: repo.head.name.sub('refs/heads/', ''),
+      ahead: 0,  # Would need to compare with upstream
+      behind: 0,
+      modified: [],
+      untracked: [],
+      staged: []
+    }
+    
+    repo.status_file_each do |file, status_flags|
+      if status_flags.include?(:worktree_modified)
+        status[:modified] << file
+      elsif status_flags.include?(:worktree_new)
+        status[:untracked] << file
+      elsif status_flags.include?(:index_modified) || status_flags.include?(:index_new)
+        status[:staged] << file
+      end
+    end
+    
+    status.to_json
+  end
+  
+  def git_log(repo, limit = 20)
+    walker = Rugged::Walker.new(repo)
+    walker.push(repo.head.target_id)
+    
+    commits = walker.take(limit).map do |commit|
+      {
+        sha: commit.oid[0..7],
+        message: commit.message.lines.first.strip,
+        author: commit.author[:name],
+        date: commit.author[:time].iso8601
+      }
+    end
+    
+    { commits: commits }.to_json
+  end
+end
+
+# Code completion provider
+class CodeCompletionResource < Tsikol::Resource
+  uri "completion/:language/:context"
+  description "Provide code completion suggestions"
+  
+  # Enable completion capability
+  completion true
+  
+  def complete
+    language = params[:language]
+    context = params[:context]
+    partial = params[:partial] || ""
+    
+    suggestions = case language
+    when "ruby"
+      ruby_completions(context, partial)
+    when "python"
+      python_completions(context, partial)
+    else
+      []
+    end
+    
+    {
+      completion: "completion",
+      values: suggestions.map { |s| { value: s[:text], label: s[:label] } }
+    }
+  end
+  
+  private
+  
+  def ruby_completions(context, partial)
+    case context
+    when "method"
+      %w[def private protected public attr_reader attr_writer attr_accessor].select { |m| m.start_with?(partial) }
+        .map { |m| { text: m, label: "#{m} (keyword)" } }
+    when "class"
+      %w[class module include extend prepend].select { |k| k.start_with?(partial) }
+        .map { |k| { text: k, label: "#{k} (keyword)" } }
+    else
+      []
+    end
+  end
+end
+
+# Code assistant prompt
+class CodeAssistantPrompt < Tsikol::Prompt
+  name "code_assistant"
+  description "Expert programming assistant with deep knowledge of multiple languages"
+  
+  argument :expertise do
+    type :string
+    required
+    enum ["general", "web", "systems", "data_science", "mobile", "devops"]
+    description "Area of expertise to focus on"
+  end
+  
+  argument :languages do
+    type :array
+    optional
+    default ["ruby", "python", "javascript"]
+    description "Preferred programming languages"
+  end
+  
+  argument :level do
+    type :string
+    optional
+    default "intermediate"
+    enum ["beginner", "intermediate", "advanced", "expert"]
+    description "User's skill level"
+  end
+  
+  def get_messages(expertise:, languages: ["ruby", "python", "javascript"], level: "intermediate")
+    system = build_system_message(expertise, languages, level)
+    
+    [
+      {
+        role: "system",
+        content: { type: "text", text: system }
+      },
+      {
+        role: "user",
+        content: { type: "text", text: "Initialize code assistant" }
+      },
+      {
+        role: "assistant",
+        content: { 
+          type: "text", 
+          text: "I'm ready to help with your #{expertise} programming needs. I specialize in #{languages.join(', ')} and will adjust my explanations for #{level} level understanding. I can analyze code, generate solutions, suggest refactorings, and help with debugging. What would you like to work on?"
+        }
+      }
+    ]
+  end
+  
+  private
+  
+  def build_system_message(expertise, languages, level)
+    base = <<~SYSTEM
+      You are an expert programming assistant specializing in #{expertise} development.
+      
+      Primary languages: #{languages.join(', ')}
+      User level: #{level}
+      
+      Available tools:
+      - analyze_code: Analyze code quality and find issues
+      - generate_code: Generate new code from specifications
+      - refactor_code: Improve existing code
+      
+      Key capabilities:
+      1. Write clean, efficient, and maintainable code
+      2. Explain complex concepts clearly
+      3. Debug issues systematically
+      4. Suggest best practices and patterns
+      5. Provide performance optimization advice
+      
+      Guidelines:
+      - Adjust explanations to #{level} level
+      - Always consider security implications
+      - Prefer readability over cleverness
+      - Include error handling in all code
+      - Follow language-specific conventions
+    SYSTEM
+    
+    base + expertise_specific_guidance(expertise)
+  end
+  
+  def expertise_specific_guidance(expertise)
+    case expertise
+    when "web"
+      "\nWeb Development Focus:\n- Modern frameworks and libraries\n- RESTful API design\n- Frontend/backend integration\n- Security (XSS, CSRF, etc.)\n- Performance optimization"
+    when "systems"
+      "\nSystems Programming Focus:\n- Memory management\n- Concurrency and parallelism\n- Low-level optimization\n- Operating system interfaces\n- Network programming"
+    when "data_science"
+      "\nData Science Focus:\n- Data manipulation and analysis\n- Machine learning algorithms\n- Statistical methods\n- Visualization techniques\n- Big data processing"
+    else
+      ""
+    end
+  end
+end
+
+# Syntax highlighting resource
+class SyntaxHighlightResource < Tsikol::Resource
+  uri "highlight/:file_path"
+  description "Syntax highlighted code"
+  
+  def read
+    file_path = params[:file_path]
+    theme = params[:theme] || "monokai"
+    
+    unless File.exist?(file_path)
+      return { error: "File not found" }.to_json
+    end
+    
+    content = File.read(file_path)
+    language = detect_language(file_path)
+    
+    lexer = Rouge::Lexer.find(language) || Rouge::Lexers::PlainText
+    formatter = Rouge::Formatters::HTML.new
+    
+    highlighted = formatter.format(lexer.lex(content))
+    
+    {
+      file: file_path,
+      language: language,
+      theme: theme,
+      html: highlighted,
+      css: Rouge::Themes::Monokai.render(scope: '.highlight')
+    }.to_json
+  end
+  
+  private
+  
+  def detect_language(file_path)
+    Rouge::Lexer.guess_by_filename(file_path)&.tag || "plaintext"
+  end
+end
+
+# Complexity analysis processor
+class ComplexityProcessor < Parser::AST::Processor
+  attr_reader :complex_methods
+  
+  def initialize
+    @complex_methods = []
+    @complexity_stack = []
+  end
+  
+  def on_def(node)
+    method_name = node.children[0]
+    @complexity_stack.push({ name: method_name, complexity: 1, line: node.location.line })
+    super
+    
+    method_info = @complexity_stack.pop
+    if method_info[:complexity] > 10
+      @complex_methods << method_info
+    end
+  end
+  
+  def on_if(node)
+    @complexity_stack.last[:complexity] += 1 if @complexity_stack.any?
+    super
+  end
+  
+  alias on_case on_if
+  alias on_when on_if
+  alias on_while on_if
+  alias on_until on_if
+  alias on_for on_if
+end
+
+# Start the server
+Tsikol.start(
+  name: "code-assistant",
+  version: "1.0.0",
+  description: "Intelligent code analysis and generation assistant"
+) do
+  # Enable all capabilities
+  logging true
+  prompts true
+  sampling true
+  completion true
+  
+  # Middleware
+  use Tsikol::LoggingMiddleware, level: :info
+  use Tsikol::AuthenticationMiddleware, 
+      type: :bearer,
+      validator: ->(token) { validate_api_token(token) }
+  
+  # Tools
+  tool CodeAnalyzerTool
+  tool CodeGeneratorTool
+  tool CodeRefactorTool
+  
+  # Resources
+  resource GitResource
+  resource CodeCompletionResource
+  resource SyntaxHighlightResource
+  
+  # Prompts
+  prompt CodeAssistantPrompt
+  
+  # Helper methods
+  def validate_api_token(token)
+    # In production, validate against database
+    return { user_id: "demo", tier: "premium" } if token == "demo-token"
+    nil
+  end
+end
+```
+
+### Testing
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class CodeAssistantTest < Minitest::Test
+  include Tsikol::TestHelpers
+  
+  def setup
+    @server = create_test_server
+    @client = TestClient.new(@server)
+    
+    # Create test files
+    setup_test_files
+  end
+  
+  def teardown
+    cleanup_test_files
+  end
+  
+  def test_code_analysis
+    response = @client.call_tool("analyze_code", {
+      "file_path" => "test_code.rb",
+      "checks" => ["complexity", "style"]
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /Code Analysis Results/, result
+    assert_match /Lines of code:/, result
+  end
+  
+  def test_code_generation
+    response = @client.call_tool("generate_code", {
+      "specification" => "Create a function to calculate fibonacci numbers",
+      "language" => "ruby",
+      "style" => "documented"
+    })
+    
+    assert_successful_response(response)
+    code = response.dig(:result, :content, 0, :text)
+    assert_match /def fibonacci/, code
+    assert_match /#/, code  # Should have comments
+  end
+  
+  def test_code_refactoring
+    response = @client.call_tool("refactor_code", {
+      "file_path" => "test_code.rb",
+      "refactoring_type" => "extract_method",
+      "options" => {
+        "start_line" => 3,
+        "end_line" => 5,
+        "method_name" => "calculate_sum"
+      }
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /def calculate_sum/, result
+  end
+  
+  def test_git_integration
+    response = @client.read_resource("git/status")
+    
+    assert_successful_response(response)
+    status = JSON.parse(response.dig(:result, :contents, 0, :text))
+    assert status.key?("branch")
+  end
+  
+  def test_code_completion
+    response = @client.complete_resource("completion/ruby/method", {
+      "partial" => "att"
+    })
+    
+    assert_successful_response(response)
+    completions = response.dig(:result, :completion, :values)
+    assert completions.any? { |c| c[:value] == "attr_reader" }
+  end
+  
+  private
+  
+  def setup_test_files
+    File.write("test_code.rb", <<~RUBY)
+      class Calculator
+        def complex_method(a, b, c)
+          if a > 0
+            if b > 0
+              if c > 0
+                a + b + c
+              else
+                a + b
+              end
+            else
+              a
+            end
+          else
+            0
+          end
+        end
+      end
+    RUBY
+    
+    # Initialize git repo
+    `git init . 2>/dev/null`
+  end
+  
+  def cleanup_test_files
+    File.delete("test_code.rb") if File.exist?("test_code.rb")
+    FileUtils.rm_rf(".git")
+  end
+  
+  def create_test_server
+    # Mock server for testing
+    Tsikol::Server.new(name: "test-code-assistant") do
+      sampling false  # Disable sampling for tests
+      
+      tool CodeAnalyzerTool
+      tool CodeGeneratorTool
+      tool CodeRefactorTool
+      resource GitResource
+      resource CodeCompletionResource
+    end
+  end
+end
+```
+
+## Advanced Features
+
+### IDE Integration
+
+```ruby
+# IDE server extension
+class IDEServer < Tsikol::Server
+  def initialize
+    super(name: "code-assistant-ide")
+    
+    # Language Server Protocol support
+    enable_lsp
+    
+    # Real-time diagnostics
+    enable_diagnostics
+    
+    # Workspace indexing
+    @workspace_index = WorkspaceIndex.new
+  end
+  
+  def on_file_change(file_path)
+    # Re-analyze on file change
+    analyze_file_async(file_path)
+    
+    # Update diagnostics
+    publish_diagnostics(file_path)
+  end
+  
+  def on_completion_request(file_path, position)
+    # Context-aware completion
+    context = analyze_context(file_path, position)
+    provide_completions(context)
+  end
+end
+```
+
+### AI-Powered Features
+
+```ruby
+# Advanced AI code review
+class AICodeReviewTool < Tsikol::Tool
+  name "ai_code_review"
+  description "Comprehensive AI-powered code review"
+  
+  sampling true
+  
+  def execute(file_path:, focus_areas: [])
+    content = File.read(file_path)
+    
+    # Get AI review
+    review = get_ai_review(content, focus_areas)
+    
+    # Parse and structure results
+    structure_review_results(review)
+  end
+  
+  private
+  
+  def get_ai_review(content, focus_areas)
+    messages = [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are an expert code reviewer. Review the following code for: #{focus_areas.join(', ')}"
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Review this code:\n\n#{content}"
+        }
+      }
+    ]
+    
+    response = @server.sample_text(
+      messages: messages,
+      max_tokens: 2000,
+      temperature: 0.2
+    )
+    
+    response[:text]
+  end
+end
+```
+
+## Best Practices Demonstrated
+
+1. **Modular Architecture** - Separate tools for different functions
+2. **AI Integration** - Smart use of sampling for code generation
+3. **Language Agnostic** - Support for multiple programming languages
+4. **Git Integration** - Version control awareness
+5. **Real-time Features** - Code completion and diagnostics
+6. **Security** - Authentication and input validation
+7. **Performance** - Efficient code analysis with AST parsing
+8. **Testing** - Comprehensive test coverage
+9. **Error Handling** - Graceful degradation
+10. **Documentation** - Self-documenting code with examples
+
+## Performance Considerations
+
+1. **AST Caching** - Cache parsed ASTs for repeated analysis
+2. **Incremental Analysis** - Only re-analyze changed parts
+3. **Background Processing** - Async analysis for large files
+4. **Index Optimization** - Pre-index workspace for fast search
+5. **Streaming Results** - Stream large analysis results
+
+## Security Notes
+
+1. **Sandboxed Execution** - Never execute untrusted code
+2. **Path Validation** - Prevent directory traversal
+3. **Rate Limiting** - Prevent DoS on expensive operations
+4. **Authentication** - Require auth for sensitive operations
+5. **Input Sanitization** - Clean all file paths and content
+
+## Next Steps
+
+- Add support for more languages
+- Implement debugging capabilities
+- Add code metrics dashboard
+- Create VS Code extension
+- Add collaborative features
+- Implement code search across repositories