azdolint 0.3.0

# Azure DevOps Pipeline Validator

[![Crates.io](https://img.shields.io/crates/v/azdolint.svg)](https://crates.io/crates/azdolint)

A command-line tool that validates Azure DevOps pipeline YAML files by checking that all referenced variable groups and variables actually exist in Azure DevOps.

## Features

- Parses Azure DevOps pipeline YAML files
- Extracts variable group references and variable usages
- Validates that variable groups exist in Azure DevOps
- Validates that referenced variables exist in the variable groups
- Validates pipeline definition variables (set via Azure DevOps UI) in addition to YAML-defined variables
- Resolves variable references from three sources (inline YAML, pipeline definition, variable groups)
- Supports template files with automatic detection and validation in parent context
- Handles variables at top-level, stage, and job scopes
- Supports template conditionals (`${{ if ... }}`) and map-syntax variables
- Provides clear, actionable error messages with suggestions
- Returns appropriate exit codes for CI/CD integration

## Prerequisites

### Personal Access Token (PAT)

This tool requires a Personal Access Token (PAT) from Azure DevOps with appropriate permissions.

1. **Create a PAT** in Azure DevOps:
   - Navigate to https://dev.azure.com/YOUR_ORG/_usersSettings/tokens
   - Click "New Token"
   - Give it a descriptive name (e.g., "azdolint")
   - Set the expiration as needed
   - Select the following scopes:
     - **Variable Groups**: Read
     - **Build**: Read (required for pipeline definition variable validation)

2. **Store the PAT securely**:
   - Set it as an environment variable: `export AZDO_PAT=your-token-here`
   - Or pass it directly via the `--pat` flag (not recommended for scripts)

## Installation

### From crates.io (Recommended)

```bash
cargo install azdolint
```

### From Source

```bash
# Clone the repository
git clone https://github.com/dariuszparys/azdo-linter.git
cd azdo-linter

# Build the project
cargo build --release

# The binary will be available at target/release/azdolint
```

### Using Cargo (local)

```bash
cargo install --path .
```

## Usage

```bash
azdolint --pipeline-file <PATH> --organization <ORG> --project <PROJECT> [OPTIONS]
```

### Arguments

| Argument | Short | Description |
|----------|-------|-------------|
| `--pipeline-file` | `-p` | Path to the Azure DevOps pipeline YAML file to validate |
| `--organization` | `-o` | Azure DevOps organization name or URL |
| `--project` | `-j` | Azure DevOps project name |
| `--pat` | `-t` | Personal Access Token for Azure DevOps API authentication (or set `AZDO_PAT` env var) |
| `--pipeline-name` | `-n` | Optional: Pipeline name in Azure DevOps (enables pipeline definition variable validation) |
| `--pipeline-id` | `-i` | Optional: Pipeline ID in Azure DevOps (more reliable than name, find it in URL as pipelineId=XXX) |
| `--verbose` | `-v` | Enable verbose output for debugging |

### Examples

**Using environment variable (recommended):**
```bash
export AZDO_PAT=your-personal-access-token
azdolint --pipeline-file azure-pipelines.yml --organization myorg --project myproject
```

**Using --pat flag:**
```bash
azdolint -p azure-pipelines.yml -o myorg -j myproject --pat $AZDO_PAT
```

**With full organization URL:**
```bash
azdolint -p azure-pipelines.yml -o https://dev.azure.com/myorg -j myproject
```

**Verbose output:**
```bash
azdolint -p azure-pipelines.yml -o myorg -j myproject --verbose
```

**With pipeline definition variable validation:**
```bash
azdolint -p azure-pipelines.yml -o myorg -j myproject --pipeline-id 42
```

Or using pipeline name:
```bash
azdolint -p azure-pipelines.yml -o myorg -j myproject --pipeline-name "My Pipeline"
```

## Exit Codes

The validator uses the following exit codes for CI/CD integration:

| Exit Code | Meaning |
|-----------|---------|
| `0` | Success - All variable groups and variables exist |
| `1` | Validation failure - Some variable groups or variables were not found |
| `2` | Error - Could not complete validation (e.g., authentication failed, file not found) |

### CI/CD Integration Example

```yaml
# Azure DevOps Pipeline
# Store your PAT as a secret variable named 'AZDO_PAT' in your pipeline or variable group
steps:
  - script: |
      azdolint --pipeline-file azure-pipelines.yml \
        --organization $(System.CollectionUri) \
        --project $(System.TeamProject) \
        --pat $(AZDO_PAT)
    displayName: 'Validate Pipeline Variables'
    env:
      AZDO_PAT: $(AZDO_PAT)
```

## Sample Output

### Successful Validation
```
Azure DevOps Pipeline Validator
================================

Variable Groups
---------------
  [PASS] Variable group 'ProductionSecrets' exists
  [PASS] Variable group 'DatabaseConfig' exists

Variable References
-------------------
  [PASS] Variable 'ConnectionString' found in group 'DatabaseConfig'
  [PASS] Variable 'ApiKey' found in group 'ProductionSecrets'

================================
RESULT: PASSED
All 4 check(s) passed successfully.
================================
```

### Failed Validation
```
Azure DevOps Pipeline Validator
================================

Variable Groups
---------------
  [PASS] Variable group 'ProductionSecrets' exists
  [FAIL] Variable group 'MissingGroup' not found
         Suggestion: Create the variable group in Azure DevOps at:
         https://dev.azure.com/myorg/myproject/_library?itemType=VariableGroups

Variable References
-------------------
  [PASS] Variable 'ApiKey' found in group 'ProductionSecrets'
  [FAIL] Variable 'UndefinedVar' not found in any referenced group
         Suggestion: Add this variable to one of the referenced variable groups,
         or verify the variable name is spelled correctly.

================================
RESULT: FAILED
2 of 4 check(s) failed.
================================
```

## Variable Resolution

When validating variable references, the tool checks three sources in priority order:

1. **Inline Variables** - Variables defined directly in the pipeline YAML file
2. **Pipeline Definition Variables** - Variables set on the pipeline definition in Azure DevOps (requires `--pipeline-id` or `--pipeline-name`)
3. **Variable Groups** - Variables defined in Azure DevOps library variable groups

This means if a variable is defined in multiple places, the tool will find it and consider it valid. To enable pipeline definition variable validation, provide either `--pipeline-id` (recommended) or `--pipeline-name`.

**Note:** Using `--pipeline-id` is more reliable than `--pipeline-name` as it avoids potential issues with special characters or duplicate pipeline names. You can find the pipeline ID in the Azure DevOps URL as `pipelineId=XXX`.

## Supported Pipeline Syntax

The validator supports the following variable definition formats in Azure DevOps YAML:

### Variable Groups
```yaml
variables:
  - group: 'MyVariableGroup'
```

### Inline Variables
```yaml
# List format
variables:
  - name: BuildConfiguration
    value: 'Release'

# Map format
variables:
  BuildConfiguration: 'Release'
```

### Variable References
The validator detects variable references using the `$(variableName)` syntax anywhere in the pipeline YAML.

### Template Conditionals
```yaml
variables:
  - ${{ if eq(parameters.environment, 'prod') }}:
    - group: 'ProductionSecrets'
  - ${{ else }}:
    - group: 'DevelopmentSecrets'
```

### Stage and Job Scoped Variables
Variables defined at stage or job level are properly scoped and validated:
```yaml
stages:
  - stage: Build
    variables:
      - group: 'BuildSecrets'
    jobs:
      - job: BuildJob
        variables:
          - name: JobVar
            value: 'value'
```

### Template Files
Template files are automatically detected (files with `parameters:` but no `trigger:`). When run against a template directly, the linter shows a warning and skips validation. Templates are validated in the context of the parent pipeline that includes them.

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.