adnv 1.5.1

# Architecture

## High-level overview

adnv follows a layered architecture separating CLI concerns from business logic and data access.

```mermaid
graph TD
    CLI[CLI Layer<br/>src/commands/] --> OPS[Operations Layer<br/>src/ops/]
    OPS --> SRC[Sources Layer<br/>src/sources/]
    OPS --> PAR[Parsers Layer<br/>src/parsers/]
    SRC --> EXT[External APIs<br/>GitHub, GitLab, Registries]
    PAR --> FS[Filesystem<br/>.tf, Chart.yaml]
    
    subgraph "Cross-cutting"
        CFG[Config<br/>src/config/]
        ERR[Errors<br/>src/error.rs]
        UTL[Utilities<br/>src/util/]
    end
```

## Layer responsibilities

### CLI Layer (`src/commands/`)

Parses CLI arguments with `clap`, loads configuration, and delegates to operations. Each command maps to a submodule:

| Command | Module | Operation |
|---------|--------|-----------|
| `outdated` | `commands/outdated.rs` | `ops::outdated` |
| `update` | `commands/update.rs` | `ops::update` |
| `check` | `commands/check.rs` | `ops::check` |
| `run` | `commands/run.rs` | `ops::run` |

### Operations Layer (`src/ops/`)

Core business logic, independent of CLI:

```mermaid
graph LR
    subgraph ops
        OUT[outdated] --> |parse + list + resolve| DISPLAY[display]
        UPD[update] --> |parse + list + resolve| APPLY[apply]
        CHK[check] --> |fetch + filter| OUTPUT[output backends]
        RUN[run] --> |codegen pipeline| PIPE[actions + pipe]
    end
```

- **outdated/update**: Share the same parse → list → resolve pipeline. `update` adds an apply step.
- **check**: Fetches tags, filters by time/regex, sends to outputs.
- **run**: Executes workflow steps through a pipe-based action chain.

### Sources Layer (`src/sources/`)

Domain models and data access for all package ecosystems:

| Submodule | Purpose |
|-----------|---------|
| `data/` | Source type definitions (Terraform, Helm, Docker, Git, NPM) |
| `parse/` | File scanning to extract sources from `.tf` and `Chart.yaml` |
| `list/` | Registry API clients to fetch available versions |
| `resolve/` | Version comparison and constraint matching |

### Parsers Layer (`src/parsers/`)

Custom HCL parser using Pest grammar for Terraform file analysis. Produces an AST used by the parse module to extract sources.

## Data flow

### Outdated/Update flow

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Parse
    participant List
    participant Resolve
    participant Display/Apply

    User->>CLI: adnv outdated
    CLI->>Parse: scan .tf / Chart.yaml
    Parse-->>CLI: Vec<VersionedSource>
    CLI->>List: fetch tags (parallel)
    List-->>CLI: Vec<Tag> per source
    CLI->>Resolve: match versions
    Resolve-->>CLI: Vec<ResolvedSource>
    CLI->>Display/Apply: show table / modify files
```

### Workflow (run) flow

```mermaid
sequenceDiagram
    participant CLI
    participant Step
    participant Action
    participant Pipe

    CLI->>Step: iterate steps
    loop Each step
        Step->>Action: execute action
        Action->>Pipe: read input
        Action->>Pipe: write output
        Note over Pipe: temp directory flows<br/>between actions
    end
```

## Error handling strategy

adnv uses two error approaches:

1. **`Result<T, Error>`** - Standard error propagation for fatal errors
2. **`Results<T, E>`** - Collection type that accumulates both successes and errors, allowing partial failures (e.g., one source failing doesn't stop others)

Error types are defined with `thiserror` and displayed with `miette` for rich terminal output.

## Async runtime

All I/O operations use Tokio async/await. Registry queries for multiple sources run concurrently via `futures::future::join_all`.