@probelabs/visor 0.1.106 → 0.1.107

package/dist/docs/security.md

@@ -0,0 +1,7 @@
+## 🔐 Security Defaults
+
+- Prefer GitHub App for bot identity and granular org/repo permissions.
+- Lock remote extends with `--allowed-remote-patterns`; default is off.
+- No external network calls unless configured (providers, HTTP checks, etc.).
+- Document where tokens are used; rotate provider keys regularly.
+

package/dist/docs/suppressions.md

@@ -0,0 +1,89 @@
+## 🔇 Suppressing Warnings
+
+Visor supports suppressing specific warnings or all warnings in a file using special comments in your code. This is useful for false positives or intentional code patterns that should not trigger warnings.
+
+### Line-Level Suppression
+
+Add `visor-disable` in a comment within ±2 lines of the issue to suppress it:
+
+```javascript
+// Example: Suppress a specific warning
+function authenticate() {
+  const testPassword = "demo123"; // visor-disable
+  // This hardcoded password warning will be suppressed
+}
+```
+
+The suppression works with any comment style:
+- `// visor-disable` (JavaScript, TypeScript, C++, etc.)
+- `# visor-disable` (Python, Ruby, Shell, etc.)
+- `/* visor-disable */` (Multi-line comments)
+- `<!-- visor-disable -->` (HTML, XML)
+
+### File-Level Suppression
+
+To suppress all warnings in an entire file, add `visor-disable-file` in the first 5 lines:
+
+```javascript
+// visor-disable-file
+// All warnings in this file will be suppressed
+
+function insecureCode() {
+  eval("user input"); // No warning
+  const password = "hardcoded"; // No warning
+}
+```
+
+### Configuration
+
+The suppression feature is enabled by default. You can disable it in your configuration:
+
+```yaml
+# .visor.yaml
+version: "1.0"
+output:
+  suppressionEnabled: false  # Disable suppression comments
+  pr_comment:
+    format: markdown
+    group_by: check
+```
+
+### Important Notes
+
+- Suppression comments are case-insensitive (`visor-disable`, `VISOR-DISABLE`, `Visor-Disable`)
+- The comment just needs to contain the suppression keyword as a substring
+- When issues are suppressed, Visor logs a summary showing which files had suppressed issues
+- Use suppression judiciously - it's better to fix issues than suppress them
+
+### Examples
+
+```python
+# Python example
+def process_data():
+    api_key = "sk-12345"  # visor-disable
+    return api_key
+```
+
+```typescript
+// TypeScript example - suppress within range
+function riskyOperation() {
+  // visor-disable
+  const unsafe = eval(userInput); // Suppressed (within 2 lines)
+  processData(unsafe);             // Suppressed (within 2 lines)
+
+  doSomethingElse();
+  anotherOperation();              // NOT suppressed (> 2 lines away)
+}
+```
+
+```go
+// Go example - file-level suppression
+// visor-disable-file
+package main
+
+func main() {
+    password := "hardcoded" // All issues suppressed
+    fmt.Println(password)
+}
+```
+

package/dist/docs/tag-filtering.md

@@ -0,0 +1,258 @@
+## 🏷️ Tag-Based Check Filtering
+
+Visor supports tagging checks to create flexible execution profiles. This lets you run different sets of checks in different environments (e.g., lightweight checks locally, comprehensive checks in CI).
+
+### How It Works
+
+1. Tag your checks with descriptive labels
+2. Filter execution using `--tags` and `--exclude-tags`
+3. Dependencies adapt intelligently based on what’s included
+
+Note on defaults
+- If you do NOT provide any tag filter (no `--tags`/`--exclude-tags` and no `tag_filter` in config), Visor only runs untagged checks. Any check that has `tags: [...]` is skipped by default. This keeps day‑to‑day runs lightweight and makes tagged groups opt‑in.
+- To run tagged checks, explicitly include their tags (for example, `--tags github,security`).
+
+### Basic Configuration
+
+```yaml
+# .visor.yaml
+version: "1.0"
+
+steps:
+  # Fast, local security check
+  security-quick:
+    type: ai
+    prompt: "Quick security scan for common vulnerabilities"
+    tags: ["local", "fast", "security"]
+    on: [pr_opened, pr_updated]
+
+  # Comprehensive security analysis (for CI)
+  security-comprehensive:
+    type: ai
+    prompt: "Deep security analysis with full vulnerability scanning"
+    tags: ["remote", "comprehensive", "security", "slow"]
+    on: [pr_opened]
+
+  # Performance check that runs everywhere
+  performance:
+    type: ai
+    prompt: "Analyze performance issues"
+    tags: ["local", "remote", "performance", "fast"]
+    on: [pr_opened, pr_updated]
+
+  # Experimental new check
+  ai-architecture:
+    type: ai
+    prompt: "AI-powered architecture review"
+    tags: ["experimental", "architecture", "slow"]
+    on: [manual]
+
+  # Report that depends on security checks
+  security-report:
+    type: noop
+    tags: ["reporting", "local", "remote"]
+    depends_on: [security-quick, security-comprehensive]
+    on: [pr_opened, pr_updated]
+```
+
+### CLI Usage
+
+```bash
+# Run only fast, local checks (great for pre-commit hooks)
+visor --tags local,fast
+
+# Run comprehensive remote checks (for CI/CD)
+visor --tags remote,comprehensive
+
+# Run all security-related checks
+visor --tags security
+
+# Run everything except slow checks
+visor --exclude-tags slow
+
+# Run everything except experimental features
+visor --exclude-tags experimental
+
+# Combine filters: Run fast security checks only
+visor --tags security,fast
+
+# Run local checks but skip experimental ones
+visor --tags local --exclude-tags experimental
+```
+
+### GitHub Action Usage
+
+```yaml
+name: Code Review with Tags
+on: pull_request
+
+jobs:
+  # Fast checks on every push
+  fast-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: probelabs/visor@v1
+        with:
+          tags: "local,fast"
+          exclude-tags: "experimental"
+        env:
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+
+  # Comprehensive checks only on main branch PRs
+  comprehensive-review:
+    if: github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: probelabs/visor@v1
+        with:
+          tags: "remote,comprehensive"
+        env:
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+```
+
+### Common Tag Patterns
+
+| Tag | Purpose | Example Use |
+|-----|---------|-------------|
+| `local` | Checks suitable for local development | Pre-commit hooks, developer testing |
+| `remote` | Checks designed for CI/CD environments | GitHub Actions, Jenkins |
+| `fast` | Quick checks (< 30 seconds) | Rapid feedback loops |
+| `slow` | Time-consuming checks | Nightly builds, release validation |
+| `security` | Security-related checks | Security audits |
+| `performance` | Performance analysis | Performance testing |
+| `style` | Code style and formatting | Linting, formatting |
+| `experimental` | Beta/testing features | Opt-in testing |
+| `critical` | Must-pass checks | Release gates |
+| `comprehensive` | Thorough analysis | Full PR reviews |
+
+### Advanced Examples
+
+#### Default behavior vs. explicit tags
+
+By default (no tag filter provided), only untagged checks execute. To include tagged checks, specify them explicitly:
+
+```bash
+# Default (no flags): only untagged checks
+visor
+
+# Include github-tagged checks (e.g., GitHub operations)
+visor --tags github
+
+# Include multiple tag groups
+visor --tags github,security
+```
+
+In the test runner, you can mirror this behavior with the tests DSL:
+
+```yaml
+# defaults/.visor.tests.yaml
+tests:
+  defaults:
+    # Run GitHub-tagged checks during tests
+    tags: "github"
+```
+
+#### Environment-Specific Execution
+
+```yaml
+# Development environment - fast feedback
+development:
+  extends: .visor.yaml
+  tag_filter:
+    include: ["local", "fast"]
+    exclude: ["experimental"]
+
+# Staging environment - balanced
+staging:
+  extends: .visor.yaml
+  tag_filter:
+    include: ["remote", "security", "performance"]
+    exclude: ["experimental"]
+
+# Production environment - comprehensive
+production:
+  extends: .visor.yaml
+  tag_filter:
+    include: ["remote", "comprehensive", "critical"]
+```
+
+#### Multi-Stage Pipeline
+
+```yaml
+# GitHub Actions workflow with progressive checks
+name: Progressive Code Review
+on: pull_request
+
+jobs:
+  stage-1-fast:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: probelabs/visor@v1
+        with:
+          tags: "fast,critical"
+          fail-fast: "true"  # Stop if critical issues found
+
+  stage-2-security:
+    needs: stage-1-fast
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: probelabs/visor@v1
+        with:
+          tags: "security"
+          exclude-tags: "fast"  # Run deeper security checks
+
+  stage-3-comprehensive:
+    needs: [stage-1-fast, stage-2-security]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: probelabs/visor@v1
+        with:
+          tags: "comprehensive"
+          exclude-tags: "fast,security"  # Run remaining checks
+```
+
+#### Dependency-Aware Filtering
+
+When using tags with dependencies, Visor intelligently handles missing dependencies:
+
+```yaml
+steps:
+  data-validation:
+    type: ai
+    prompt: "Validate data structures"
+    tags: ["local", "data"]
+
+  api-validation:
+    type: ai
+    prompt: "Validate API contracts"
+    tags: ["remote", "api"]
+
+  integration-report:
+    type: noop
+    tags: ["reporting"]
+    depends_on: [data-validation, api-validation]
+    # When filtered by "local" tag, only uses data-validation
+    # When filtered by "remote" tag, only uses api-validation
+    # With no filter, uses both dependencies
+```
+
+### Tag Validation Rules
+
+- Tags must start with an alphanumeric character
+- Can contain letters, numbers, hyphens, and underscores
+- Examples: `local`, `test-env`, `feature_flag`, `v2`
+- Invalid: `-invalid`, `@special`, `tag with spaces`
+
+### Best Practices
+
+1. Use consistent naming conventions across your organization
+2. Document your tag taxonomy in your team's wiki
+3. Start simple: begin with `local`/`remote` or `fast`/`slow`
+4. Avoid over-tagging to reduce confusion
+5. Use tag combinations for fine-grained control
+6. Test tag filters before deploying broadly

package/dist/docs/telemetry-setup.md

@@ -0,0 +1,119 @@
+# Telemetry & Tracing — Setup Guide
+
+This guide shows how to enable Visor telemetry and tracing with OpenTelemetry, export traces/metrics, auto‑instrument Node libraries, and generate a static HTML trace report.
+
+## Quick Start (CLI)
+
+- Enable telemetry to serverless NDJSON traces:
+  - `VISOR_TELEMETRY_ENABLED=true`
+  - `VISOR_TELEMETRY_SINK=file`
+  - (optional) `VISOR_TRACE_DIR=output/traces`
+- Run:
+  - `visor --config ./.visor.yaml --output json`
+- Inspect traces:
+  - `ls output/traces/*.ndjson`
+
+## CLI Flags
+
+- `--telemetry` — enable telemetry (overrides config)
+- `--telemetry-sink <otlp|file|console>` — sink selection
+- `--telemetry-endpoint <url>` — OTLP endpoint (HTTP) for traces/metrics
+- `--trace-report` — write a static HTML trace report to output/traces
+- `--auto-instrumentations` — enable OpenTelemetry auto‑instrumentations
+
+Examples:
+- `visor --config ./.visor.yaml --telemetry --telemetry-sink otlp --telemetry-endpoint https://otel.example.com`
+- `visor --config ./.visor.yaml --telemetry --trace-report --auto-instrumentations`
+
+## Config (visor.yaml)
+
+```yaml
+version: "1.0"
+telemetry:
+  enabled: true
+  sink: file       # otlp|file|console
+  otlp:
+    protocol: http
+    endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT}
+    headers: ${OTEL_EXPORTER_OTLP_HEADERS}
+  file:
+    dir: output/traces
+    ndjson: true
+  tracing:
+    auto_instrumentations: true
+    trace_report:
+      enabled: true
+```
+
+ENV overrides (highest precedence):
+- `VISOR_TELEMETRY_ENABLED`, `VISOR_TELEMETRY_SINK`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `VISOR_TRACE_DIR`
+- `VISOR_TELEMETRY_AUTO_INSTRUMENTATIONS=true`
+- `VISOR_TRACE_REPORT=true`
+
+## Serverless Mode (NDJSON)
+
+- Visor writes NDJSON simplified spans to `output/traces/run-<id>-<ts>.ndjson`.
+- Ingest with OTel Collector `filelog` receiver + transform to OTLP.
+
+OTel Collector (example):
+```yaml
+receivers:
+  filelog:
+    include: [ "/work/output/traces/*.ndjson" ]
+    operators:
+      - type: json_parser
+        parse_from: body
+exporters:
+  otlphttp:
+    endpoint: http://tempo:4318
+service:
+  pipelines:
+    traces:
+      receivers: [filelog]
+      exporters: [otlphttp]
+```
+
+## Connected Mode (OTLP HTTP)
+
+- Set `VISOR_TELEMETRY_SINK=otlp` and `OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com`.
+- Metrics exporter is enabled automatically (optional dependency) — histograms/counters for checks, providers, foreach items, fail_if triggers, and diagram blocks.
+
+## Auto‑Instrumentations
+
+- Enable with `--auto-instrumentations` or `telemetry.tracing.auto_instrumentations: true`.
+- Adds `@opentelemetry/auto-instrumentations-node` (http/undici/child_process/etc.) and correlates with Visor spans via context.
+- Optional dependency; if not installed, Visor skips auto‑instrumentation gracefully.
+
+## Static Trace Report
+
+- Enable `--trace-report` or `telemetry.tracing.trace_report.enabled: true`.
+- Outputs two files per run:
+  - `*.trace.json` — simplified span JSON
+  - `*.report.html` — self‑contained HTML timeline (open locally)
+
+## Mermaid Telemetry
+
+- Visor emits full `diagram.block` events with Mermaid code from outputs and issue messages.
+- Metric: `visor.diagram.blocks{origin}` increments per diagram block.
+
+## Security & Redaction
+
+- Diagram events are sent verbatim by default (as requested). You can later opt‑in to redaction via `telemetry.redaction` (not enforced by default).
+
+## GitHub Actions
+
+- Visor wraps the Action run in a single root span (`visor.run`). Publish the `trace_id` in logs/checks for linking.
+- Example step:
+```yaml
+- name: Visor
+  run: |
+    export VISOR_TELEMETRY_ENABLED=true
+    export VISOR_TELEMETRY_SINK=otlp
+    export OTEL_EXPORTER_OTLP_ENDPOINT=${{ secrets.OTEL_ENDPOINT }}
+    export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${{ secrets.OTEL_TOKEN }}"
+    npx -y @probelabs/visor@latest --config ./.visor.yaml --output json
+```
+
+Troubleshooting:
+- No spans? Check `VISOR_TELEMETRY_ENABLED`, `VISOR_TELEMETRY_SINK`, and that optional deps resolved in the environment.
+- Huge mermaid outputs? Consider adding a soft length cap in Visor or pre-truncating in templates.