@probelabs/visor 0.1.106 → 0.1.111

package/dist/examples/sdk-manual-config.mjs

@@ -0,0 +1,65 @@
+/**
+ * Example: SDK with manually constructed config object
+ * This demonstrates using loadConfig() with a raw config object
+ * instead of loading from a file.
+ */
+
+import { loadConfig, runChecks } from '../dist/sdk/sdk.mjs';
+
+async function main() {
+  // Load and validate config from an object (not a file!)
+  // loadConfig() validates, applies defaults, and returns a complete config
+  const config = await loadConfig({
+    version: '1.0',
+    checks: {
+      'security-check': {
+        type: 'command',
+        exec: 'echo "Running security scan..."',
+      },
+      'lint-check': {
+        type: 'command',
+        exec: 'echo "Running linter..."',
+        depends_on: ['security-check'],
+      },
+    },
+  });
+
+  console.log('Running checks with manually constructed config...\n');
+
+  // Run all checks defined in the config
+  const result = await runChecks({
+    config,
+    checks: Object.keys(config.checks),
+    output: { format: 'json' },
+    debug: false,
+  });
+
+  // Display results
+  console.log('Execution summary:');
+  console.log(`  Total checks executed: ${result.checksExecuted.length}`);
+  console.log(`  Total issues found: ${result.reviewSummary.issues?.length || 0}`);
+  console.log(`  Execution time: ${result.executionTime}ms`);
+  console.log(`  Timestamp: ${result.timestamp}`);
+
+  // Display check results
+  console.log('\nCheck results:');
+  for (const checkName of result.checksExecuted) {
+    console.log(`  ✓ ${checkName}`);
+  }
+
+  // Display any issues found
+  if (result.reviewSummary.issues && result.reviewSummary.issues.length > 0) {
+    console.log('\nIssues found:');
+    result.reviewSummary.issues.forEach((issue, idx) => {
+      console.log(`  ${idx + 1}. [${issue.severity}] ${issue.message}`);
+      console.log(`     File: ${issue.file}:${issue.line}`);
+    });
+  }
+
+  return result;
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/dist/examples/sdk-typescript.js

@@ -0,0 +1,81 @@
+/**
+ * TypeScript SDK Example
+ *
+ * Demonstrates:
+ * - Type-safe config construction
+ * - TypeScript type inference
+ * - Compile-time type checking
+ * - Using exported types
+ */
+// Import from the package for full TypeScript type definitions
+// In a real project, you would use: '@probelabs/visor/sdk'
+// For this example, we import from the built SDK with type definitions
+import { loadConfig, runChecks } from '../dist/sdk/sdk.js';
+async function main() {
+    console.log('=== Visor SDK - TypeScript Example ===\n');
+    // Type-safe config construction (note: VisorConfig is exported from SDK)
+    const rawConfig = {
+        version: '1.0',
+        checks: {
+            'type-check': {
+                type: 'command',
+                exec: 'echo "Running TypeScript compiler..."',
+                tags: ['typescript', 'build'],
+            },
+            'unit-tests': {
+                type: 'command',
+                exec: 'echo "Running unit tests..."',
+                depends_on: ['type-check'],
+                tags: ['testing'],
+            },
+            'build': {
+                type: 'command',
+                exec: 'echo "Building application..."',
+                depends_on: ['type-check', 'unit-tests'],
+                tags: ['build'],
+            },
+        },
+        max_parallelism: 2,
+        fail_fast: false,
+    };
+    // Load and validate config with full type safety
+    const config = await loadConfig(rawConfig);
+    console.log('✅ Config validated and loaded');
+    console.log(`   Checks: ${Object.keys(config.checks).length}`);
+    console.log(`   Max parallelism: ${config.max_parallelism}\n`);
+    // Run checks with type-safe options
+    const result = await runChecks({
+        config,
+        checks: ['type-check', 'unit-tests', 'build'],
+        output: { format: 'json' },
+        maxParallelism: 2,
+        debug: false,
+        tagFilter: { include: ['typescript', 'testing', 'build'] },
+    });
+    // Type-safe result inspection
+    console.log('📊 Results:');
+    console.log(`   Checks executed: ${result.checksExecuted.length}`);
+    console.log(`   Execution time: ${result.executionTime}ms`);
+    console.log(`   Issues found: ${result.reviewSummary.issues?.length ?? 0}`);
+    console.log(`   Timestamp: ${result.timestamp}`);
+    // Type-safe iteration over results
+    console.log('\n   Executed checks:');
+    result.checksExecuted.forEach((checkName, index) => {
+        console.log(`     ${index + 1}. ${checkName}`);
+    });
+    // Demonstrate type checking with issues
+    if (result.reviewSummary.issues && result.reviewSummary.issues.length > 0) {
+        console.log('\n   Issues:');
+        result.reviewSummary.issues.forEach((issue) => {
+            // TypeScript knows the structure of issue
+            console.log(`     ${issue.file}:${issue.line} - ${issue.message}`);
+            console.log(`     Severity: ${issue.severity}`);
+        });
+    }
+    console.log('\n✅ TypeScript example complete!\n');
+}
+// Run with proper error handling
+main().catch((error) => {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+});

package/dist/examples/sdk-typescript.ts

@@ -0,0 +1,92 @@
+/**
+ * TypeScript SDK Example
+ *
+ * Demonstrates:
+ * - Type-safe config construction
+ * - TypeScript type inference
+ * - Compile-time type checking
+ * - Using exported types
+ */
+
+// Import from the package for full TypeScript type definitions
+// In a real project, you would use: '@probelabs/visor/sdk'
+// For this example, we import from the built SDK with type definitions
+import { loadConfig, runChecks, type VisorConfig, type RunOptions } from '../dist/sdk/sdk.js';
+
+async function main(): Promise<void> {
+  console.log('=== Visor SDK - TypeScript Example ===\n');
+
+  // Type-safe config construction (note: VisorConfig is exported from SDK)
+  const rawConfig: Partial<VisorConfig> = {
+    version: '1.0',
+    checks: {
+      'type-check': {
+        type: 'command',
+        exec: 'echo "Running TypeScript compiler..."',
+        tags: ['typescript', 'build'],
+      },
+      'unit-tests': {
+        type: 'command',
+        exec: 'echo "Running unit tests..."',
+        depends_on: ['type-check'],
+        tags: ['testing'],
+      },
+      'build': {
+        type: 'command',
+        exec: 'echo "Building application..."',
+        depends_on: ['type-check', 'unit-tests'],
+        tags: ['build'],
+      },
+    },
+    max_parallelism: 2,
+    fail_fast: false,
+  };
+
+  // Load and validate config with full type safety
+  const config = await loadConfig(rawConfig);
+
+  console.log('✅ Config validated and loaded');
+  console.log(`   Checks: ${Object.keys(config.checks).length}`);
+  console.log(`   Max parallelism: ${config.max_parallelism}\n`);
+
+  // Run checks with type-safe options
+  const result = await runChecks({
+    config,
+    checks: ['type-check', 'unit-tests', 'build'],
+    output: { format: 'json' },
+    maxParallelism: 2,
+    debug: false,
+    tagFilter: { include: ['typescript', 'testing', 'build'] },
+  });
+
+  // Type-safe result inspection
+  console.log('📊 Results:');
+  console.log(`   Checks executed: ${result.checksExecuted.length}`);
+  console.log(`   Execution time: ${result.executionTime}ms`);
+  console.log(`   Issues found: ${result.reviewSummary.issues?.length ?? 0}`);
+  console.log(`   Timestamp: ${result.timestamp}`);
+
+  // Type-safe iteration over results
+  console.log('\n   Executed checks:');
+  result.checksExecuted.forEach((checkName: string, index: number) => {
+    console.log(`     ${index + 1}. ${checkName}`);
+  });
+
+  // Demonstrate type checking with issues
+  if (result.reviewSummary.issues && result.reviewSummary.issues.length > 0) {
+    console.log('\n   Issues:');
+    result.reviewSummary.issues.forEach((issue) => {
+      // TypeScript knows the structure of issue
+      console.log(`     ${issue.file}:${issue.line} - ${issue.message}`);
+      console.log(`     Severity: ${issue.severity}`);
+    });
+  }
+
+  console.log('\n✅ TypeScript example complete!\n');
+}
+
+// Run with proper error handling
+main().catch((error: Error) => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});

package/dist/examples/session-reuse-config.yaml

@@ -0,0 +1,151 @@
+# Example configuration demonstrating AI session reuse functionality
+# This allows subsequent checks to continue conversations with AI models
+
+version: "1.0"
+
+# Example 1: Simple session reuse for follow-up analysis
+steps:
+  # Initial security analysis - creates a new AI session
+  security-analysis:
+    type: ai
+    prompt: |
+      You are a security expert reviewing code changes. Analyze the provided code for:
+
+      1. Authentication and authorization issues
+      2. Input validation vulnerabilities
+      3. Data exposure risks
+      4. Cryptographic weaknesses
+      5. Injection vulnerabilities
+
+      Provide specific examples and recommendations for each issue found.
+    on:
+      - pr_opened
+      - pr_updated
+    ai:
+      provider: anthropic  # or google, openai
+      model: claude-3-sonnet-20240229
+
+  # Follow-up check that reuses the previous AI session
+  security-remediation:
+    type: ai
+    prompt: |
+      Based on our previous security analysis discussion, now provide:
+
+      1. Detailed remediation steps for each identified security issue
+      2. Code examples showing secure implementations
+      3. Best practices specific to this codebase
+      4. Priority ranking of fixes needed
+
+      Build upon the context we established in our previous conversation.
+    on:
+      - pr_opened
+      - pr_updated
+    depends_on:
+      - security-analysis
+    reuse_ai_session: true  # This will reuse the AI session from security-analysis
+
+# Example 2: Multi-level session reuse chain
+  architecture-review:
+    type: ai
+    prompt: |
+      Analyze the architectural patterns and design decisions in this code.
+      Identify the main components, their interactions, and design quality.
+    on:
+      - pr_opened
+    ai:
+      provider: anthropic
+      model: claude-3-sonnet-20240229
+
+  performance-analysis:
+    type: ai
+    prompt: |
+      Continuing our architectural discussion, now focus on performance aspects.
+      Consider the architectural patterns we identified and analyze:
+
+      1. Performance bottlenecks
+      2. Scalability concerns
+      3. Resource usage efficiency
+      4. Optimization opportunities
+    on:
+      - pr_opened
+    depends_on:
+      - architecture-review
+    reuse_ai_session: true
+
+  recommendations-summary:
+    type: ai
+    prompt: |
+      Based on our complete analysis covering architecture and performance,
+      provide a prioritized summary of recommendations with:
+
+      1. Critical issues requiring immediate attention
+      2. Medium-term improvements
+      3. Long-term architectural considerations
+      4. Implementation roadmap
+    on:
+      - pr_opened
+    depends_on:
+      - performance-analysis
+    reuse_ai_session: true
+
+# Example 3: Mixed session reuse and independent checks
+  code-style:
+    type: ai
+    prompt: |
+      Review code style, formatting, and maintainability concerns.
+      Focus on readability, naming conventions, and code organization.
+    on:
+      - pr_opened
+    ai:
+      provider: openai
+      model: gpt-4
+
+  documentation-review:
+    type: ai
+    prompt: |
+      Review documentation quality including:
+      - Code comments
+      - README updates
+      - API documentation
+      - Inline documentation
+    on:
+      - pr_opened
+    # This runs independently - no session reuse
+
+  comprehensive-summary:
+    type: ai
+    prompt: |
+      Create a comprehensive summary combining insights from all previous analyses.
+      Provide an executive summary with key findings and recommendations.
+    on:
+      - pr_opened
+    depends_on:
+      - security-remediation
+      - recommendations-summary
+      - code-style
+      - documentation-review
+    reuse_ai_session: true  # Reuses session from security-remediation (first dependency)
+
+# Output configuration
+output:
+  pr_comment:
+    format: markdown
+    group_by: check
+    collapse: true
+    debug:
+      enabled: true
+      includePrompts: false
+      includeRawResponses: false
+      includeTiming: true
+      includeProviderInfo: true
+
+# Execution settings
+max_parallelism: 3  # Session reuse checks will still run sequentially when needed
+fail_fast: false
+
+# Notes:
+# 1. reuse_ai_session: true REQUIRES depends_on to be specified
+# 2. Checks with session reuse will force sequential execution within their dependency chain
+# 3. Session IDs are automatically managed and cleaned up after execution
+# 4. Sessions maintain conversation context, allowing for more sophisticated analysis
+# 5. Mix session reuse with independent checks for optimal performance and context

package/dist/examples/session-reuse-self.yaml

@@ -0,0 +1,81 @@
+version: "2.0"
+
+# Session reuse example: reuse_ai_session: self
+# ---------------------------------------------
+# This example demonstrates how a single AI step can reuse its own
+# ProbeAgent session across multiple loops within the same engine run.
+#
+# Flow:
+#   seed (script) → convo (ai, reuse_ai_session: self, session_mode: append)
+#                  └─ on_success.goto_js: loops back to convo up to 3 times
+#
+# The first time `convo` runs, it creates a new AI session. On subsequent
+# iterations in the same run, `reuse_ai_session: self` causes the engine
+# to reuse that same session (with `session_mode: append`), so the model
+# keeps conversational context.
+
+steps:
+  # Simple seed step to provide deterministic input to the AI check.
+  seed:
+    type: script
+    criticality: info
+    content: |
+      return { text: "hello from seed" };
+
+  # AI step that loops back to itself while reusing its own session.
+  convo:
+    type: ai
+    depends_on: [seed]
+    criticality: info
+    reuse_ai_session: self
+    session_mode: append
+    # Keep schema simple here – we only care about call counts in tests.
+    ai:
+      provider: mock
+      model: mock
+      disableTools: true
+      allowedTools: []
+      system_prompt: |
+        You are a tiny echo assistant.
+        Answer concisely and keep track of how the conversation evolves.
+    prompt: |
+      You are in a small internal conversation used to test AI session reuse.
+
+      Seed message: {{ outputs['seed'].text }}
+
+      Past convo outputs for this run (if any):
+      {% assign hist = outputs_history['convo'] | default: empty %}
+      {% if hist and hist.size > 0 %}
+      {% for h in hist %}
+      - Previous reply {{ forloop.index }} seen in this run.
+      {% endfor %}
+      {% else %}
+      - No previous replies yet in this run.
+      {% endif %}
+    on_success:
+      # Loop this step a few times to exercise reuse_ai_session: self.
+      goto_js: |
+        // "attempt" is the 1-based execution count for this step in this run.
+        // Run convo exactly 3 times, then stop.
+        return attempt < 3 ? 'convo' : null;
+
+tests:
+  defaults:
+    strict: true
+    ai_provider: mock
+
+  cases:
+    - name: self-session-single-run
+      description: |
+        Basic smoke test: the workflow executes successfully and the
+        convo step runs exactly once. The config itself demonstrates
+        reuse_ai_session: self + session_mode: append for workflows
+        that route back to the same AI step.
+      event: manual
+      fixture: local.minimal
+      expect:
+        calls:
+          - step: seed
+            exactly: 1
+          - step: convo
+            exactly: 1