# cui-cui

A Rust TUI application for visualizing and debugging CI pipelines (GitLab CI, GitHub Actions).

## Build & Test Commands

```bash
cargo build              # Build the project
cargo test               # Run all tests
cargo test <test_name>   # Run a specific test
cargo fmt                # Format code (MUST be run before committing)
cargo fmt -- --check     # Check formatting without modifying files
cargo clippy -- -D warnings  # Run linter (CI enforces zero warnings)
cargo run -- <path>      # Run with a CI file or directory (auto-detects GitLab/GitHub)
cargo tarpaulin --skip-clean --out Stdout  # Test coverage (requires cargo-tarpaulin)
```

## Code Quality Rules

- **Always run `cargo fmt`** before committing. Unformatted code should not be committed.
- **Always run tests** after making changes. All tests must pass before committing.
- **Write tests** for new functionality. Integration tests go in `tests/`, unit tests go in the module file using `#[cfg(test)]` blocks.

## Architecture

```
src/
  main.rs              -- CLI entry point, terminal setup, event loop
  app.rs               -- Application state, navigation, reload logic
  lib.rs               -- Library re-exports for tests

  model/               -- Data structures
    raw.rs             -- Pre-resolution types (RawPipeline, RawJobConfig)
    job.rs             -- Resolved Job struct + local script builder
    pipeline.rs        -- Resolved Pipeline + Stage structs

  artifacts.rs         -- Artifact extraction (tar from volumes/dirs, --exclude)
  config.rs            -- TOML config loading (.cui-cui.toml, XDG user config)
  container.rs         -- Container runtime detection (podman/docker), launch logic
  dispatch.rs          -- Full pipeline dispatch loop (local + remote runners)
  expr.rs              -- Shared expression parser/evaluator (Moa expressions)
  git_utils.rs         -- Git context detection (remote URL, branch, commit)
  remote.rs            -- SSH remote runner execution, artifact upload/download

  parser/              -- YAML parsing
    gitlab/            -- GitLab CI parser
      loader.rs        -- File loading, all include types, !reference resolution
      merge.rs         -- Deep merge logic for extends/includes
    github/            -- GitHub Actions parser
      loader.rs        -- Workflow YAML parsing, matrix expansion, expression expansion
    gitlab_fetch.rs    -- GitLab API client, remote file fetching, caching

  resolve/             -- Pipeline resolution
    gitlab/            -- GitLab CI resolver
      extends.rs       -- extends chain walking, cycle detection, defaults
      variables.rs     -- GitContext, predefined CI variables, variable expansion
      pipeline.rs      -- Orchestrates raw -> resolved pipeline, parallel:matrix
    github/            -- GitHub Actions resolver
      pipeline.rs      -- Resolves workflow into Pipeline (stages, variables, steps)

  graph/               -- DAG construction
    mod.rs             -- Builds petgraph DiGraph, computes layout
    layout.rs          -- Node/edge positioning for TUI rendering

  ui/                  -- Terminal UI (ratatui)
    dag_view.rs        -- DAG visualization widget (box-drawing, edges)
    job_detail.rs      -- Job detail panel (Config/Script/Variables tabs)
    input.rs           -- Key bindings and input handling
    theme.rs           -- Dark/light theme color definitions
```

## Release Process

When creating annotated git tags with markdown release notes, use `--cleanup=verbatim` to preserve `#` heading lines (git's default cleanup strips them as comments):
```bash
git tag -a v0.X --cleanup=verbatim -m "..."
```

## Key Dependencies

- `ratatui` + `crossterm` — TUI framework
- `serde_yaml` — YAML parsing
- `petgraph` — DAG data structure
- `indexmap` — Order-preserving maps
- `clap` — CLI argument parsing
- `reqwest` — HTTP client for GitLab API (remote includes)
- `tempfile` — Temporary files for container scripts and logs
- `url` — URL parsing for git remote detection
