Azqr Developer

Azure Quick Review (azqr) Development Skill

Expert guidance for autonomous agents and developers contributing to the Azure Quick Review (azqr) project.

Project Overview

Azure Quick Review (azqr) is a CLI tool written in Go that analyzes Azure resources for compliance with Azure's best practices and recommendations. The tool scans Azure resources using:

• Azure Resource Graph (ARG) queries from the Azure Proactive Resiliency Library v2 (APRL)
• Azure Resource Manager (ARM) rules built with the Azure Golang SDK

Quick Start

Prerequisites

• Go 1.23.3 or higher
• Valid Azure authentication (Service Principal, Managed Identity, or Azure CLI)

Essential Commands

# Build the project
make build

# Run all tests (REQUIRED before submitting pull requests)
make test

# Clean build artifacts
make clean

# View all available targets
make help

Project Structure

azqr/
├── cmd/azqr/               # Main CLI application entry point
│   ├── main.go            # Application entry point
│   └── commands/          # CLI command implementations (one file per Azure service)
├── cmd/server/            # Server mode implementation
├── internal/              # Internal packages
│   ├── scanner.go         # Main scanning logic
│   ├── models/            # Data models and filters
│   ├── renderers/         # Output formatters (Excel, CSV, JSON)
│   ├── scanners/          # Service-specific scanners (one per Azure service)
│   ├── graph/             # Azure Resource Graph queries
│   └── aigov/             # AI Governance utilities
├── data/                  # Static data files
│   └── recommendations.json # Generated recommendations data
├── examples/              # Example configurations and CI/CD pipelines
├── docs/                  # Documentation website (Hugo-based)
└── Makefile              # Build automation

Code Style and Standards

Naming Conventions

• Variables: Use camelCase for all variable names
• Functions: Use MixedCaps for exported functions, mixedCaps for unexported
• Packages: Use lowercase, single-word package names (avoid underscores)
• Interfaces: Name with -er suffix when possible (e.g., Scanner, Renderer)

Documentation

• Always add code comments using godoc style for exported functions
• Document why, not what, unless the what is complex
• Start comments with the name of the thing being described
• Write comments in complete sentences

Authentication

All code must support multiple authentication methods:

• Service Principal (environment variables: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
• Azure Managed Identity
• Azure CLI authentication

Error Handling

• Follow Go idiomatic error handling patterns
• Check errors immediately after the function call
• Wrap errors with context using fmt.Errorf with %w verb
• Keep error messages lowercase and don't end with punctuation
• Name error variables err

Development Workflow

1. Adding Support for New Azure Services

When adding a new Azure service, follow this systematic approach:

1. Create scanner in internal/scanners/<service>/

   • Implement the scanner interface
   • Support both ARM-based and ARG-based recommendations
   • Include appropriate error handling and logging

2. Add command in cmd/azqr/commands/<service>.go

   • Follow the existing command pattern
   • Use appropriate service abbreviation (see README.md)

3. Update models in internal/models/

   • Add service-specific models if needed
   • Ensure models support JSON serialization

4. Add comprehensive tests

   • Include unit tests for scanner logic
   • Test both success and error cases
   • Use table-driven tests for multiple scenarios

5. Update documentation

   • Add service to supported services list in README.md
   • Document any service-specific requirements

2. Testing Requirements

CRITICAL: Always run make test before submitting pull requests. This is non-negotiable.

The test command includes:

• Linting (golangci-lint) - Code quality checks
• Go vet checks - Static analysis
• Module tidiness verification - Dependency management
• Unit tests with race condition detection
• Coverage reporting

# Run the full test suite (ALWAYS run before PR)
make test

# Individual test components
make lint    # Run linter
make vet     # Run go vet
make tidy    # Check module tidiness

3. Building and Distribution

# Build for current platform
make build

# Build for specific OS/architecture
GOOS=linux GOARCH=amd64 make build
GOOS=windows GOARCH=amd64 make build

# Build Docker image
make build-image

# Build with version information
PRODUCT_VERSION=1.0.0 make build

# Update recommendations.json after adding rules
make json

Common Development Tasks

Adding a New Recommendation Rule

1. Identify the target Azure service
2. Locate the appropriate scanner in internal/scanners/<service>/
3. Add the rule logic following existing patterns:
   • Use consistent naming conventions
   • Include clear comments explaining the rule
   • Reference official Azure documentation
4. Update tests to cover the new rule
5. Run make json to update recommendations.json
6. Verify with make test

Fixing Bugs

1. Reproduce the issue with a minimal test case
2. Add regression test if missing
3. Implement fix following project patterns
4. Verify fix with make test
5. Update documentation if the bug revealed unclear behavior

Performance Optimization

1. Use the throttling utilities in internal/throttling/ for rate limiting
2. Implement concurrent scanning where appropriate (use goroutines wisely)
3. Cache expensive operations when possible
4. Profile using Go's built-in tools before optimizing
5. Focus on algorithmic improvements first

Scanner Implementation Patterns

Scanner Interface

// internal/scanners/<service>/<service>.go
package <service>

import (
    "context"
    "github.com/Azure/azqr/internal/models"
)

// Scanner implements the service scanner interface
type Scanner struct {
    // Scanner fields (config, client, etc.)
}

// Scan performs the compliance scan for the service
func (s *Scanner) Scan(ctx context.Context) ([]models.Recommendation, error) {
    // Implementation
    // 1. Fetch resources
    // 2. Apply recommendation rules
    // 3. Return findings
}

Command Implementation

// cmd/azqr/commands/<service>.go
package commands

import (
    "github.com/spf13/cobra"
)

func init() {
    // Register command with root command
}

var <service>Cmd = &cobra.Command{
    Use:   "<service>",
    Short: "Scan <Service Name>",
    Long:  "Detailed description of what this scanner does",
    Run:   <service>Run,
}

func <service>Run(cmd *cobra.Command, args []string) {
    // Command implementation
    // 1. Parse flags
    // 2. Initialize scanner
    // 3. Run scan
    // 4. Output results
}

Testing Patterns

Table-Driven Tests

func TestScanner_Scan(t *testing.T) {
    tests := []struct {
        name    string
        setup   func() // setup test environment
        want    int    // expected number of recommendations
        wantErr bool
    }{
        {
            name:    "success case",
            setup:   func() { /* setup */ },
            want:    5,
            wantErr: false,
        },
        {
            name:    "error case",
            setup:   func() { /* setup */ },
            want:    0,
            wantErr: true,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            tt.setup()
            // test implementation
        })
    }
}

Runtime Debugging and Troubleshooting

Enable Debug Mode

# Set environment variable for detailed logging
export AZURE_SDK_GO_LOGGING=all

# Run with debug flag
./azqr scan --debug