@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/script.md

@@ -1,18 +1,69 @@
-## Script step (type: `script`)
+## Script Step (`type: script`)
 
-The `script` provider executes JavaScript in a secure sandbox with access to
-PR context, dependency outputs, and the Visor memory store.
+The `script` provider executes JavaScript in a secure sandbox with access to PR context, dependency outputs, workflow inputs, environment variables, and the Visor memory store.
 
-- Use `type: script` with a `content` block containing your code.
-- The sandbox exposes these objects:
-  - `pr`: basic PR metadata and file list.
-  - `outputs`: map of dependency outputs (plus `outputs.history`).
-  - `outputs_raw`: aggregated values from `-raw` dependencies.
-  - `outputs_history_stage`: per-stage output history slice for tests.
-  - `memory`: synchronous helpers `get`, `set`, `append`, `increment`, `delete`, `clear`.
-- The value you `return` becomes this step’s `output` (for `depends_on`).
+## Configuration
 
-Example:
+| Property | Required | Description |
+|----------|----------|-------------|
+| `type` | Yes | Must be `script` |
+| `content` | Yes | JavaScript code to execute (max 1MB) |
+| `depends_on` | No | Array of step IDs this step depends on |
+| `group` | No | Group name for organizing steps |
+| `on` | No | Event triggers for this step |
+| `if` | No | Condition to evaluate before running |
+| `fail_if` | No | Condition to fail the step |
+| `on_fail` | No | Routing configuration on failure |
+| `on_success` | No | Routing configuration on success |
+
+## Sandbox Context
+
+The secure sandbox exposes these objects and functions:
+
+### Data Objects
+
+| Object | Description |
+|--------|-------------|
+| `pr` | PR metadata: `number`, `title`, `body`, `author`, `base`, `head`, `totalAdditions`, `totalDeletions`, `files[]` |
+| `outputs` | Map of dependency outputs (current values). Access via `outputs['step-name']` |
+| `outputs.history` | Map of all historical outputs per step (arrays). See [Output History](./output-history.md) |
+| `outputs_history` | Alias for `outputs.history` (top-level access) |
+| `outputs_raw` | Aggregated values from `-raw` suffix dependencies |
+| `outputs_history_stage` | Per-stage output history slice (used by test framework) |
+| `inputs` | Workflow inputs (when running inside a workflow) |
+| `args` | Arguments passed via `with:` directive in `on_init` |
+| `env` | Environment variables (`process.env`) |
+
+### Memory Operations
+
+| Method | Description |
+|--------|-------------|
+| `memory.get(key, namespace?)` | Retrieve a value |
+| `memory.has(key, namespace?)` | Check if key exists |
+| `memory.list(namespace?)` | List all keys in namespace |
+| `memory.getAll(namespace?)` | Get all key-value pairs |
+| `memory.set(key, value, namespace?)` | Set a value |
+| `memory.append(key, value, namespace?)` | Append to an array |
+| `memory.increment(key, amount?, namespace?)` | Increment numeric value (default: 1) |
+| `memory.delete(key, namespace?)` | Delete a key |
+| `memory.clear(namespace?)` | Clear all keys in namespace |
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `log(...args)` | Debug logging (outputs with prefix for identification) |
+| `escapeXml(str)` | Escape string for XML output |
+| `btoa(str)` | Base64 encode a string |
+| `atob(str)` | Base64 decode a string |
+
+## Return Value
+
+The value you `return` from the script becomes the step's `output`, accessible to dependent steps via `outputs['step-name']`.
+
+## Examples
+
+### Basic Example
 
 ```yaml
 steps:
@@ -31,4 +82,102 @@ steps:
       return { total: memory.get('total_facts', 'fact-validation'), allValid };
 ```
 
-The script context and memory helpers mirror other providers’ contexts.
+### Using PR Context
+
+```yaml
+steps:
+  analyze-pr:
+    type: script
+    content: |
+      const largeFiles = pr.files.filter(f => f.additions > 100);
+      const totalChanges = pr.totalAdditions + pr.totalDeletions;
+
+      return {
+        largeFileCount: largeFiles.length,
+        totalChanges,
+        isLargePR: totalChanges > 500,
+        author: pr.author
+      };
+```
+
+### Using Output History
+
+```yaml
+steps:
+  track-retries:
+    type: script
+    depends_on: [some-check]
+    content: |
+      // Access all previous outputs from a check
+      const history = outputs.history['some-check'] || [];
+      const retryCount = history.length;
+
+      log('Retry count:', retryCount);
+      log('Previous outputs:', history);
+
+      return {
+        retryCount,
+        lastOutput: history[history.length - 1]
+      };
+```
+
+### Using Workflow Inputs
+
+```yaml
+# In a workflow file
+inputs:
+  - name: threshold
+    default: 10
+
+steps:
+  check-threshold:
+    type: script
+    content: |
+      const threshold = inputs.threshold || 10;
+      const count = outputs['counter'].value;
+
+      return {
+        passed: count < threshold,
+        message: count < threshold
+          ? 'Within threshold'
+          : `Exceeded threshold of ${threshold}`
+      };
+```
+
+### Complex Data Processing
+
+```yaml
+steps:
+  process-results:
+    type: script
+    depends_on: [run-tests]
+    content: |
+      const results = outputs['run-tests'];
+
+      // Calculate statistics
+      const stats = {
+        total: results.tests?.length || 0,
+        passed: results.tests?.filter(t => t.passed).length || 0,
+        failed: results.tests?.filter(t => !t.passed).length || 0
+      };
+
+      stats.passRate = stats.total > 0
+        ? ((stats.passed / stats.total) * 100).toFixed(2)
+        : 0;
+
+      // Store in memory for other steps
+      memory.set('test_stats', stats);
+
+      // Debug logging
+      log('Test stats:', stats);
+
+      return stats;
+```
+
+## Related Documentation
+
+- [Memory Provider](./memory.md) - Persistent key-value storage
+- [Output History](./output-history.md) - Tracking outputs across iterations
+- [Dependencies](./dependencies.md) - Step dependency system
+- [Liquid Templates](./liquid-templates.md) - Template syntax for other providers
+- [Debugging](./debugging.md) - Debugging techniques including the `log()` function

package/dist/docs/sdk.md

@@ -119,6 +119,8 @@ try {
 
 ## API
 
+### Functions
+
 - `loadConfig(configOrPath?: string | Partial<VisorConfig>, options?: { strict?: boolean }): Promise<VisorConfig>`
   - Loads and validates a config from an object, file path, or discovers defaults
   - Accepts config objects (validates and applies defaults) or file paths
@@ -126,26 +128,58 @@ try {
   - Set `options.strict` to treat warnings as errors
 - `resolveChecks(checkIds: string[], config: VisorConfig | undefined): string[]`
   - Expands check IDs to include dependencies in the correct order.
+  - Detects and throws on circular dependencies.
 - `runChecks(options: RunOptions): Promise<AnalysisResult>`
   - Runs checks programmatically. Thin wrapper around the engine's `executeChecks`.
 
 ### Types
 
-- `RunOptions`
-  - `config?: VisorConfig` | `configPath?: string`
-  - `checks?: string[]`
-  - `cwd?: string`
-  - `timeoutMs?: number`
-  - `output?: { format?: 'table'|'json'|'markdown'|'sarif' }`
-  - `debug?: boolean`
-  - `maxParallelism?: number`
-  - `failFast?: boolean`
-  - `tagFilter?: { include?: string[]; exclude?: string[] }`
+All types below are exported from `@probelabs/visor/sdk`.
+
+- `VisorOptions` (base options used by `RunOptions`)
+  - `cwd?: string` - Working directory for execution
+  - `debug?: boolean` - Enable debug mode
+  - `maxParallelism?: number` - Maximum parallel checks
+  - `failFast?: boolean` - Stop on first failure
+  - `tagFilter?: TagFilter` - Filter checks by tags
+
+- `RunOptions` (extends `VisorOptions`)
+  - `config?: VisorConfig` - Config object (mutually exclusive with `configPath`)
+  - `configPath?: string` - Path to config file (mutually exclusive with `config`)
+  - `checks?: string[]` - Check IDs to run (default: all checks from config)
+  - `timeoutMs?: number` - Execution timeout in milliseconds
+  - `output?: { format?: 'table'|'json'|'markdown'|'sarif' }` - Output format
   - `strictValidation?: boolean` - Treat config warnings (unknown keys) as errors (default: false)
+  - `executionContext?: ExecutionContext` - Execution context for providers (hooks, CLI state, etc.)
 
 - `AnalysisResult`
-  - `reviewSummary.issues: Issue[]`
-  - `executionTime: number`, `timestamp: string`, `checksExecuted: string[]`
+  - `reviewSummary: ReviewSummary` - Contains `issues: Issue[]` and scoring
+  - `executionTime: number` - Total execution time in ms
+  - `timestamp: string` - ISO timestamp
+  - `checksExecuted: string[]` - List of executed check IDs
+  - `repositoryInfo: GitRepositoryInfo` - Repository metadata
+  - `executionStatistics?: ExecutionStatistics` - Detailed per-check statistics (optional)
+  - `debug?: DebugInfo` - Debug information when debug mode enabled (optional)
+  - `failureConditions?: FailureConditionResult[]` - Failure condition results (optional)
+
+- `ExecutionContext` - Context passed to check providers
+  - `cliMessage?: string` - CLI message value (from `--message` argument)
+  - `hooks?: VisorHooks` - SDK hooks for human input and check completion
+  - `workflowInputs?: Record<string, unknown>` - Inputs when executing within a workflow
+  - `args?: Record<string, unknown>` - Custom arguments from `on_init` directives
+
+- `HumanInputRequest` - Request object for human input hooks
+  - `checkId: string` - Check ID requesting input
+  - `prompt: string` - Prompt to display
+  - `placeholder?: string` - Placeholder text
+  - `allowEmpty: boolean` - Whether empty input is allowed
+  - `multiline: boolean` - Whether multiline input is supported
+  - `timeout?: number` - Timeout in milliseconds
+  - `default?: string` - Default value
+
+- `TagFilter` - Tag filtering configuration
+  - `include?: string[]` - Tags to include (ANY match)
+  - `exclude?: string[]` - Tags to exclude (ANY match)
 
 Refer to `src/types/config.ts` for `VisorConfig`, `Issue`, and related types.