> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Scanning

> AST-based static analysis of your AI codebase to detect features, extract prompts, and map workflows.

The Scanner module performs **AST-based static analysis** of your AI codebase — detecting features, extracting prompts, and mapping workflows. Scan results can be uploaded to the Valiqor backend for deeper analysis and attached to [Failure Analysis](/workflows/failure-analysis) runs.

***

## Quick start

```python theme={"system"}
from valiqor.scanner import ValiqorScanner

scanner = ValiqorScanner()  # Loads config from .valiqorrc
scanner.configure(
    api_key="vq_...",
    project_name="my-app",
)

result = scanner.scan(repo_path=".")

print(f"Status: {result.status}")
print(f"Scan ID: {result.scan_id}")
print(f"Files generated: {result.files_generated}")
print(f"Files uploaded: {result.files_uploaded}")
```

### Convenience function

For one-liner scans:

```python theme={"system"}
from valiqor.scanner import quick_scan

result = quick_scan(
    api_key="vq_...",
    project_name="my-app",
    repo_path=".",
)
```

***

## What the scanner does

The scanner runs a local pipeline:

<Steps>
  <Step title="AST analysis">
    Parses your Python codebase using abstract syntax trees to understand code structure.
  </Step>

  <Step title="Feature detection">
    Identifies AI features: LLM calls, retrieval functions, tool definitions, agent patterns.
  </Step>

  <Step title="Prompt extraction">
    Extracts prompt templates, system messages, and few-shot examples from your code.
  </Step>

  <Step title="Workflow mapping">
    Maps execution flow: which functions call which, how data flows through your pipeline.
  </Step>

  <Step title="Upload (optional)">
    If `valiqor_intelligence` is enabled, uploads results to the backend for deeper Stage 2+ analysis.
  </Step>
</Steps>

***

## Scanner configuration

The scanner uses the same `.valiqorrc` config file:

```json theme={"system"}
{
  "project_name": "my-app",
  "api_key": "vq_...",
  "scan_dir": "valiqor_output/scans",
  "valiqor_intelligence": true
}
```

| Config                 | Description                             | Default                |
| ---------------------- | --------------------------------------- | ---------------------- |
| `scan_dir`             | Local output directory for scan results | `valiqor_output/scans` |
| `valiqor_intelligence` | Upload results to Valiqor backend       | `true`                 |

***

## `scan()` method

```python theme={"system"}
result = scanner.scan(
    repo_path=".",           # Path to the repository to scan
    skip_upload=False,       # If True, only run local scan (no cloud upload)
)
```

### ScanResult fields

| Field              | Type        | Description                     |
| ------------------ | ----------- | ------------------------------- |
| `status`           | `str`       | `"success"` or `"error"`        |
| `project_name`     | `str`       | Project name used               |
| `scan_id`          | `str`       | Unique identifier for this scan |
| `local_output_dir` | `str`       | Path to generated files         |
| `files_generated`  | `list[str]` | Local files created             |
| `files_uploaded`   | `list[str]` | Files uploaded to backend       |
| `upload_response`  | `dict`      | Backend response (if uploaded)  |
| `error`            | `str`       | Error message (if failed)       |

***

## Local-only scanning

For environments without backend access:

```python theme={"system"}
result = scanner.scan(
    repo_path=".",
    skip_upload=True,  # Only run local analysis
)

# Results saved to valiqor_output/scans/latest/
print(f"Output: {result.local_output_dir}")
for f in result.files_generated:
    print(f"  {f}")
```

***

## Integration with Failure Analysis

When `run_scan=True` (default) in FA, scan data is automatically attached:

```python theme={"system"}
# FA automatically includes scan context
result = client.failure_analysis.run(
    dataset=my_data,
    run_scan=True,  # Default — attaches scan data if available
)
```

This gives FA additional context about your codebase structure for more accurate failure classification.

***

## CLI

```bash theme={"system"}
# Scan current directory
valiqor scan run --path .

# Scan with custom output
valiqor scan run --path /path/to/repo --output ./scan-output
```

***

<CardGroup cols={2}>
  <Card title="Failure Analysis →" icon="magnifying-glass-chart" href="/workflows/failure-analysis">
    Use scan data for deeper failure analysis.
  </Card>

  <Card title="Tracing →" icon="radar" href="/workflows/tracing">
    Combine scanning with runtime tracing.
  </Card>
</CardGroup>