@probelabs/visor 0.1.106 → 0.1.107

package/dist/examples/ai-with-mcp.yaml

@@ -0,0 +1,82 @@
+# Example Visor configuration demonstrating MCP support in AI checks
+version: "1.0"
+
+# Global AI provider configuration
+ai_provider: anthropic
+ai_model: claude-3-sonnet
+
+# Global MCP servers (available to all AI checks by default)
+ai_mcp_servers:
+  probe:
+    command: "npx"
+    args: ["-y", "@probelabs/probe@latest", "mcp"]
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
+
+steps:
+  # Example 1: Uses global MCP servers (inherits probe and filesystem)
+  basic_security_review:
+    type: ai
+    prompt: |
+      Review the code changes for security vulnerabilities using available tools.
+      Focus on common security issues like injection attacks and XSS.
+    on: ["pr_opened", "pr_updated"]
+    tags: ["security", "basic"]
+
+  # Example 2: Check-level MCP servers (overrides global)
+  performance_review:
+    type: ai
+    prompt: |
+      Analyze the code for performance issues using specialized tools.
+      Look for inefficient algorithms and potential bottlenecks.
+    ai_mcp_servers:
+      probe:
+        command: "npx"
+        args: ["-y", "@probelabs/probe@latest", "mcp"]
+      custom_profiler:
+        command: "python3"
+        args: ["./tools/performance-analyzer.py"]
+        env:
+          ANALYSIS_DEPTH: "comprehensive"
+    on: ["pr_opened"]
+    tags: ["performance", "mcp"]
+
+  # Example 3: AI object-level MCP servers (overrides all others)
+  comprehensive_review:
+    type: ai
+    prompt: |
+      Perform comprehensive code analysis using all available tools.
+      This check uses its own specific set of MCP servers.
+    ai:
+      provider: anthropic
+      model: claude-3-opus  # Override global model for this check
+      mcpServers:
+        probe:
+          command: "npx"
+          args: ["-y", "@probelabs/probe@latest", "mcp"]
+          env:
+            PROBE_DEBUG: "true"
+        filesystem:
+          command: "npx"
+          args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
+        github:
+          command: "npx"
+          args: ["-y", "@modelcontextprotocol/server-github"]
+          env:
+            GITHUB_TOKEN: "${GITHUB_TOKEN}"
+    on: ["pr_opened"]
+    tags: ["comprehensive", "mcp"]
+
+  # Example 4: No MCP servers (basic AI check)
+  simple_ai_check:
+    type: ai
+    prompt: "Review this code for basic issues without using external tools"
+    ai_mcp_servers: {}  # Explicitly disable global MCP servers for this check
+    on: ["pr_opened", "pr_updated"]
+    tags: ["basic", "simple"]
+
+output:
+  pr_comment:
+    enabled: true
+    group_by: check

package/dist/examples/basic-human-input.yaml

@@ -0,0 +1,15 @@
+version: '1.0'
+
+checks:
+  ask-user:
+    type: human-input
+    prompt: "What is your name?"
+    placeholder: "Enter your name..."
+    allow_empty: false
+
+  greet:
+    type: log
+    depends_on: [ask-user]
+    message: |
+      Hello, {{ outputs['ask-user'] }}!
+      Welcome to Visor.

package/dist/examples/bedrock-config.yaml

@@ -0,0 +1,77 @@
+# Example Visor configuration for AWS Bedrock
+# This demonstrates various ways to configure and use AWS Bedrock as your AI provider
+
+
+# Example GitHub Actions workflow to use this configuration:
+#
+# name: AI Code Review with AWS Bedrock
+# on: [pull_request]
+#
+# jobs:
+#   review:
+#     runs-on: ubuntu-latest
+#     steps:
+#       - uses: actions/checkout@v4
+#       - uses: probelabs/visor@v1
+#         with:
+#           ai-provider: bedrock
+#           ai-model: anthropic.claude-sonnet-4-20250514-v1:0
+#         env:
+#           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+#           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+#           AWS_REGION: us-east-1
+
+# As alternative to github action, you can also set it in config on various levels, or via following env vars:
+#
+# export AI_PROVIDER=bedrock  # This gets mapped internally
+# export AI_MODEL=anthropic.claude-sonnet-4-20250514-v1:0
+
+# Configuration version
+version: "1.0"
+
+# Global AI provider settings, via config
+# Set Bedrock as the default provider for all AI checks
+ai_provider: bedrock
+ai_model: anthropic.claude-sonnet-4-20250514-v1:0  # Default Bedrock model
+
+steps:
+  # Basic check using global Bedrock settings
+  security-analysis:
+    type: ai
+    prompt: |
+      Analyze the code changes for security vulnerabilities including:
+      - SQL injection risks
+      - XSS vulnerabilities
+      - Authentication/authorization issues
+      - Sensitive data exposure
+      - Input validation problems
+
+  # Check with explicit Bedrock configuration
+  performance-review:
+    type: ai
+    ai_provider: bedrock
+    ai_model: anthropic.claude-3-opus-20240229  # Use a different Bedrock model
+    prompt: |
+      Review code for performance issues:
+      - Inefficient algorithms (O(n²) or worse)
+      - Memory leaks or excessive allocations
+      - Database query optimization opportunities
+      - Caching opportunities
+    schema: code-review  # Use structured output
+
+  # Mixed provider example - use different providers for different checks
+  quick-style-check:
+    type: ai
+    ai_provider: google  # Override to use Google Gemini for this check
+    ai_model: gemini-2.0-flash-exp
+    prompt: "Quick style and formatting check"
+
+# Output configuration
+output:
+  pr_comment:
+    format: markdown
+    group_by: check
+    collapse: true
+  github_checks:
+    enabled: true
+    per_check: true  # Create separate GitHub check runs for each check

package/dist/examples/calculator-config.yaml

@@ -0,0 +1,133 @@
+version: "1.0"
+
+# Interactive Calculator Example
+# Demonstrates human-input + memory + JavaScript workflow
+#
+# Usage:
+#   visor --config examples/calculator-config.yaml
+#
+# Or with inline messages:
+#   visor --config examples/calculator-config.yaml \
+#     --message 42  # First run asks for number1
+#
+# The workflow will:
+# 1. Ask for first number
+# 2. Store it in memory
+# 3. Ask for second number
+# 4. Store it in memory
+# 5. Ask for operation (+, -, *, /)
+# 6. Calculate result using JavaScript
+# 7. Display formatted result
+
+memory:
+  storage: memory
+  namespace: calculator
+
+checks:
+  # Step 1: Get first number
+  get-number1:
+    type: human-input
+    prompt: "Enter the first number:"
+    placeholder: "e.g., 42"
+    allow_empty: false
+
+  # Step 2: Store first number in memory
+  store-number1:
+    type: memory
+    depends_on: [get-number1]
+    operation: set
+    namespace: calculator
+    key: number1
+    value_js: "parseFloat(outputs['get-number1'])"
+
+  # Step 3: Get second number
+  get-number2:
+    type: human-input
+    depends_on: [store-number1]
+    prompt: "Enter the second number:"
+    placeholder: "e.g., 7"
+    allow_empty: false
+
+  # Step 4: Store second number in memory
+  store-number2:
+    type: memory
+    depends_on: [get-number2]
+    operation: set
+    namespace: calculator
+    key: number2
+    value_js: "parseFloat(outputs['get-number2'])"
+
+  # Step 5: Get operation
+  get-operation:
+    type: human-input
+    depends_on: [store-number2]
+    prompt: "Select operation (+, -, *, /):"
+    placeholder: "Enter one of: + - * /"
+    allow_empty: false
+
+  # Step 6: Store operation in memory
+  store-operation:
+    type: memory
+    depends_on: [get-operation]
+    operation: set
+    namespace: calculator
+    key: operation
+    value_js: "outputs['get-operation'].trim()"
+
+  # Step 7: Perform calculation using memory and JavaScript
+  calculate:
+    type: script
+    depends_on: [store-operation]
+    content: |
+      // Get values from memory
+      const num1 = memory.get('number1', 'calculator');
+      const num2 = memory.get('number2', 'calculator');
+      const op = memory.get('operation', 'calculator');
+
+      // Log for debugging
+      log('Calculating:', num1, op, num2);
+
+      // Perform calculation
+      let result;
+      switch(op) {
+        case '+':
+          result = num1 + num2;
+          break;
+        case '-':
+          result = num1 - num2;
+          break;
+        case '*':
+          result = num1 * num2;
+          break;
+        case '/':
+          if (num2 === 0) {
+            throw new Error('Division by zero!');
+          }
+          result = num1 / num2;
+          break;
+        default:
+          throw new Error('Invalid operation: ' + op);
+      }
+
+      // Return result for output
+      return result;
+
+  # Step 8: Display the result
+  show-result:
+    type: log
+    depends_on: [calculate]
+    message: |
+
+      ╔════════════════════════════════════════╗
+      ║          CALCULATION RESULT            ║
+      ╠════════════════════════════════════════╣
+      ║                                        ║
+      ║  {{ outputs['get-number1'] }} {{ outputs['get-operation'] }} {{ outputs['get-number2'] }} = {{ outputs['calculate'] }}
+      ║                                        ║
+      ╚════════════════════════════════════════╝
+
+output:
+  pr_comment:
+    format: markdown
+    group_by: check
+    collapse: false

package/dist/examples/calculator-json-output-guide.md

@@ -0,0 +1,311 @@
+# Calculator SDK - JSON Output Guide
+
+This guide explains how to use the calculator examples with JSON output for programmatic processing.
+
+## Overview
+
+Three calculator variants are provided:
+
+1. **`calculator-sdk-real.ts`** - Interactive with table output (original)
+2. **`calculator-sdk-json.ts`** - Interactive with JSON output + custom visualization
+3. **`calculator-sdk-automated.ts`** - Non-interactive with pure JSON output
+
+## Quick Start
+
+### Interactive with JSON Output
+
+```bash
+bun examples/calculator-sdk-json.ts
+```
+
+**Features:**
+- Prompts for user input
+- Uses `outputFormat: 'json'`
+- Suppresses engine console output
+- Returns structured JSON
+- Custom visualization in script
+
+**Output:**
+```json
+{
+  "success": true,
+  "calculation": {
+    "number1": 10,
+    "number2": 5,
+    "operation": "+",
+    "result": 15,
+    "expression": "10 + 5 = 15"
+  },
+  "executionTime": 1234,
+  "issues": []
+}
+```
+
+### Fully Automated (No Interaction)
+
+```bash
+# With default values (10 + 5)
+bun examples/calculator-sdk-automated.ts
+
+# With custom values
+bun examples/calculator-sdk-automated.ts 100 25 -
+
+# Output is pure JSON
+bun examples/calculator-sdk-automated.ts 7 8 '*' --json
+```
+
+**Features:**
+- No user interaction required
+- Inputs provided programmatically
+- All console output suppressed
+- Perfect for testing & automation
+- Includes test suite
+
+## Key Techniques
+
+### 1. Using JSON Output Format
+
+```typescript
+const result = await engine.executeChecks({
+  checks: checksToRun,
+  config: calculatorConfig,
+  outputFormat: 'json',  // ← Instead of 'table'
+  maxParallelism: 1,
+  debug: false
+});
+```
+
+### 2. Suppressing Console Output
+
+```typescript
+function suppressAllOutput() {
+  const noop = () => {};
+  const originalLog = console.log;
+  // ... save all console methods
+
+  console.log = noop;
+  console.error = noop;
+  console.warn = noop;
+  // ... suppress all
+
+  return {
+    restore: () => {
+      console.log = originalLog;
+      // ... restore all
+    }
+  };
+}
+
+// Usage
+const suppressor = suppressAllOutput();
+const result = await engine.executeChecks({...});
+suppressor.restore();
+```
+
+### 3. Automated Input Provider
+
+```typescript
+function createAutomatedInputHandler(inputs: {
+  'get-number1': string;
+  'get-number2': string;
+  'get-operation': string;
+}) {
+  return async (request: HumanInputRequest): Promise<string> => {
+    return inputs[request.checkId];
+  };
+}
+
+// Set the hook
+HumanInputCheckProvider.setHooks({
+  onHumanInput: createAutomatedInputHandler({
+    'get-number1': '10',
+    'get-number2': '5',
+    'get-operation': '+'
+  })
+});
+```
+
+### 4. Accessing Memory Results
+
+```typescript
+const { MemoryStore } = await import('../src/memory-store');
+const memoryStore = MemoryStore.getInstance(config.memory);
+
+const result = memoryStore.get('result', 'calculator');
+const num1 = memoryStore.get('number1', 'calculator');
+```
+
+## JSON Output Structure
+
+The result from `executeChecks` with `outputFormat: 'json'` returns:
+
+```typescript
+interface ExecutionResult {
+  executionTime: number;
+  timestamp: string;
+  summary: {
+    issues: Array<{
+      file: string;
+      line: number;
+      ruleId: string;
+      message: string;
+      severity: 'info' | 'warning' | 'error' | 'critical';
+      category: string;
+    }>;
+  };
+  // Additional fields based on output format
+}
+```
+
+## Custom Result Structure
+
+You can transform this into your own structure:
+
+```typescript
+interface CalculationResult {
+  success: boolean;
+  calculation?: {
+    number1: number;
+    number2: number;
+    operation: string;
+    result: number;
+    expression: string;
+  };
+  executionTime?: number;
+  issues?: any[];
+  error?: string;
+}
+
+async function calculate(num1, num2, op): Promise<CalculationResult> {
+  // Suppress output
+  const suppressor = suppressAllOutput();
+
+  // Execute
+  const result = await engine.executeChecks({
+    outputFormat: 'json',
+    // ...
+  });
+
+  suppressor.restore();
+
+  // Extract from memory
+  const memoryStore = MemoryStore.getInstance();
+  const resultValue = memoryStore.get('result', 'calculator');
+
+  // Return custom structure
+  return {
+    success: true,
+    calculation: {
+      number1: parseFloat(num1),
+      number2: parseFloat(num2),
+      operation: op,
+      result: resultValue,
+      expression: `${num1} ${op} ${num2} = ${resultValue}`
+    },
+    executionTime: result.executionTime,
+    issues: result.summary?.issues || []
+  };
+}
+```
+
+## Testing Example
+
+```typescript
+// Run multiple calculations programmatically
+const testCases = [
+  { num1: '100', num2: '25', operation: '-', expected: 75 },
+  { num1: '7', num2: '8', operation: '*', expected: 56 },
+  { num1: '100', num2: '4', operation: '/', expected: 25 },
+];
+
+const results = await Promise.all(
+  testCases.map(tc =>
+    calculate(tc.num1, tc.num2, tc.operation, { suppressOutput: true })
+  )
+);
+
+// Verify results
+results.forEach((result, idx) => {
+  const tc = testCases[idx];
+  const passed = result.calculation?.result === tc.expected;
+  console.log(`${tc.num1} ${tc.operation} ${tc.num2} = ${result.calculation?.result} ${passed ? '✅' : '❌'}`);
+});
+```
+
+## Benefits
+
+### For Production Use
+- ✅ Clean JSON output for APIs
+- ✅ No stdout pollution
+- ✅ Easy to parse and process
+- ✅ Structured error handling
+
+### For Testing
+- ✅ Automated test suites
+- ✅ CI/CD integration
+- ✅ Reproducible results
+- ✅ No user interaction needed
+
+### For Monitoring
+- ✅ Log to files/databases
+- ✅ Metrics collection
+- ✅ Alerting on failures
+- ✅ Performance tracking
+
+## Integration Examples
+
+### Express API Endpoint
+
+```typescript
+app.post('/api/calculate', async (req, res) => {
+  const { num1, num2, operation } = req.body;
+
+  const result = await calculate(num1, num2, operation, {
+    suppressOutput: true
+  });
+
+  if (result.success) {
+    res.json(result);
+  } else {
+    res.status(400).json({ error: result.error });
+  }
+});
+```
+
+### CLI Tool with JSON Flag
+
+```typescript
+if (process.argv.includes('--json')) {
+  const result = await calculate(num1, num2, op, { suppressOutput: true });
+  console.log(JSON.stringify(result));
+} else {
+  // Interactive mode
+  await interactiveCalculator();
+}
+```
+
+### Background Job
+
+```typescript
+async function processCalculations(jobs: CalculationJob[]) {
+  const results = await Promise.all(
+    jobs.map(job =>
+      calculate(job.num1, job.num2, job.operation, {
+        suppressOutput: true
+      })
+    )
+  );
+
+  // Store results in database
+  await db.calculations.insertMany(results);
+
+  return results;
+}
+```
+
+## See Also
+
+- **SDK Documentation**: `docs/sdk.md`
+- **Human Input Feature**: `docs/human-input-feature-plan.md`
+- **Memory Provider**: `src/providers/memory-check-provider.ts`
+- **Examples**: `examples/calculator-*.ts`