Release v0.2.0

Release v0.2.0 - Complete Dependency Management

Release Date: 2025-01-XX

🚀 What's New

This release completes the dependency management module with full resolution, querying, version comparison, and reverse dependency analysis capabilities. The deps feature is now production-ready for comprehensive Arch Linux package dependency management.

✨ New Features

Dependency Resolution

• Resolve dependencies for official, AUR, and local packages
• Configurable resolution (include optional, make, check dependencies)
• Batch dependency fetching for efficient queries
• Conflict detection and status determination
• Support for PKGBUILD cache callbacks

Reverse Dependency Analysis

• Find all packages that depend on packages being removed
• Distinguish direct vs transitive dependents
• Generate conflict status with detailed reasons
• Helper functions for quick dependency checks

Version Comparison

• Pacman-compatible version comparison algorithm
• Version requirement satisfaction checking
• Major version bump detection
• Extract major version components

Package Querying

• Query installed packages
• Query upgradable packages
• Get installed and available package versions
• Check if packages are installed or provided
• Graceful degradation when pacman is unavailable

Source Determination

• Determine package source (official, AUR, local)
• Identify core repository packages
• Detect critical system packages

📚 Examples

Seven comprehensive example files demonstrate all new functionality:

• examples/deps_example.rs - Complete dependency module overview
• examples/parse_example.rs - Dependency specification parsing
• examples/query_example.rs - Package querying examples
• examples/resolve_example.rs - Dependency resolution examples
• examples/reverse_example.rs - Reverse dependency analysis examples
• examples/source_example.rs - Source determination examples
• examples/version_example.rs - Version comparison examples

Quick Start

Dependency Resolution

use arch_toolkit::deps::DependencyResolver;
use arch_toolkit::{PackageRef, PackageSource};

let resolver = DependencyResolver::new();
let packages = vec![
    PackageRef {
        name: "firefox".into(),
        version: "121.0".into(),
        source: PackageSource::Official {
            repo: "extra".into(),
            arch: "x86_64".into(),
        },
    },
];

let result = resolver.resolve(&packages)?;
println!("Found {} dependencies", result.dependencies.len());

Reverse Dependency Analysis

use arch_toolkit::deps::ReverseDependencyAnalyzer;

let analyzer = ReverseDependencyAnalyzer::new();
let packages = vec![
    PackageRef {
        name: "wget".into(),
        version: "1.21.4".into(),
        source: PackageSource::Official {
            repo: "core".into(),
            arch: "x86_64".into(),
        },
    },
];

let report = analyzer.analyze(&packages)?;
println!("{} packages would be affected", report.dependents.len());

Version Comparison

use arch_toolkit::deps::{compare_versions, version_satisfies};
use std::cmp::Ordering;

assert_eq!(compare_versions("1.2.3", "1.2.4"), Ordering::Less);
assert!(version_satisfies("2.0", ">=1.5"));

Package Querying

use arch_toolkit::deps::{
    get_installed_packages, get_upgradable_packages,
    get_installed_version, get_available_version,
};

let installed = get_installed_packages()?;
println!("Found {} installed packages", installed.len());

if let Ok(version) = get_installed_version("pacman") {
    println!("Installed version: {}", version);
}

Source Determination

use arch_toolkit::deps::{determine_dependency_source, is_system_package};

let installed = get_installed_packages()?;
let (source, is_core) = determine_dependency_source("bash", &installed);
println!("Source: {:?}, Is core: {}", source, is_core);

if is_system_package("bash") {
    println!("Critical system package");
}

Installation

cargo add [email protected] --features deps

Or update your Cargo.toml:

[dependencies]
arch-toolkit = { version = "0.2.0", features = ["deps"] }

For AUR integration:

[dependencies]
arch-toolkit = { version = "0.2.0", features = ["deps", "aur"] }

Migration from v0.1.2

No breaking changes! This is a backward-compatible release. All existing code will continue to work.

New capabilities:

• Use DependencyResolver to resolve dependencies for packages
• Use ReverseDependencyAnalyzer to analyze reverse dependencies
• Use version comparison functions for package version checks
• Query installed and upgradable packages
• Determine package sources and system package status
• Check out the comprehensive example files for usage patterns

Documentation

• Full API Documentation
• GitHub Repository
• Examples

Feedback

Found a bug or have a feature request? Open an issue on GitHub!

---

Full Changelog: See CHANGELOG.md for detailed technical changes.

Release v0.1.2

Release v0.1.2 - Dependency Parsing

Release Date: 2025-12-22

🚀 What's New

This release introduces comprehensive dependency parsing capabilities, allowing you to extract and analyze dependencies from PKGBUILD files, .SRCINFO files, and pacman output.

✨ New Features

Dependency Parsing Module (deps feature)

• Parse dependencies from PKGBUILD files
  • Supports single-line and multi-line bash array syntax
  • Handles append syntax (depends+=) in PKGBUILD functions
  • Extracts depends, makedepends, checkdepends, and optdepends
  • Automatic filtering of virtual packages (.so files)
  • Automatic deduplication of dependencies
• Parse dependencies from .SRCINFO files
  • Extract structured data from .SRCINFO content
  • Handle architecture-specific dependencies
  • Support for split packages
  • Fetch .SRCINFO from AUR (requires aur feature)
• Parse dependency specifications
  • Parse dependency specs with version constraints (e.g., package>=1.2.3)
  • Parse pacman -Si output for dependencies and conflicts
  • Handle multi-line dependencies and deduplication

Dependency Types

• Comprehensive type system for dependency management
• Support for dependency status, sources, and specifications
• Ready for future dependency resolution features

📚 Examples

Two new example files demonstrate the parsing capabilities:

• examples/pkgbuild_example.rs - 16 usage examples for PKGBUILD parsing
• examples/srcinfo_example.rs - Comprehensive .SRCINFO parsing examples

Quick Start

Parsing PKGBUILD Files

use arch_toolkit::deps::parse_pkgbuild_deps;

let pkgbuild = r"
depends=('glibc' 'python>=3.10')
makedepends=('make' 'gcc')
";

let (depends, makedepends, checkdepends, optdepends) = parse_pkgbuild_deps(pkgbuild);
println!("Runtime dependencies: {:?}", depends);

Parsing .SRCINFO Files

use arch_toolkit::deps::{parse_srcinfo, parse_srcinfo_deps};

let srcinfo = r"
pkgbase = example-package
depends = glibc
depends = python>=3.10
makedepends = make
";

// Parse full .SRCINFO into structured data
let data = parse_srcinfo(srcinfo)?;

// Or just extract dependencies
let (depends, makedepends, checkdepends, optdepends) = parse_srcinfo_deps(srcinfo);

Fetching .SRCINFO from AUR

use arch_toolkit::deps::fetch_srcinfo;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let srcinfo = fetch_srcinfo("yay").await?;
    let data = parse_srcinfo(&srcinfo)?;
    println!("Package: {}", data.pkgbase);
    Ok(())
}

Parsing Dependency Specifications

use arch_toolkit::deps::parse_dep_spec;

let spec = "python>=3.10";
let dep = parse_dep_spec(spec)?;
println!("Package: {}, Version: {:?}", dep.name, dep.version);

Installation

cargo add [email protected] --features deps

Or update your Cargo.toml:

[dependencies]
arch-toolkit = { version = "0.1.2", features = ["deps"] }

For AUR integration (fetching .SRCINFO):

[dependencies]
arch-toolkit = { version = "0.1.2", features = ["deps", "aur"] }

Migration from v0.1.1

No breaking changes! This is a backward-compatible release. All existing code will continue to work.

New capabilities:

• Enable the deps feature to access dependency parsing functions
• Use parse_pkgbuild_deps() to extract dependencies from PKGBUILD files
• Use parse_srcinfo() or fetch_srcinfo() for .SRCINFO parsing
• Check out the example files for comprehensive usage patterns

Documentation

• Full API Documentation
• GitHub Repository
• Examples

Feedback

Found a bug or have a feature request? Open an issue on GitHub!

---

Full Changelog: See CHANGELOG.md for detailed technical changes.

Release v0.1.1

Release v0.1.1 - Developer Experience & Robustness

Release Date: 2025-12-21

🚀 What's New

This release focuses on improving developer experience, adding configuration flexibility, and enhancing robustness with input validation and health checks.

✨ New Features

Environment Variable Configuration

• Configure the client entirely via environment variables
• Support for ARCH_TOOLKIT_* variables:
  • ARCH_TOOLKIT_TIMEOUT - Request timeout
  • ARCH_TOOLKIT_USER_AGENT - Custom user agent
  • ARCH_TOOLKIT_MAX_RETRIES - Maximum retry attempts
  • ARCH_TOOLKIT_RETRY_ENABLED - Enable/disable retries
  • ARCH_TOOLKIT_VALIDATION_STRICT - Strict validation mode
  • ARCH_TOOLKIT_CACHE_SIZE - Cache size configuration
• Perfect for CI/CD and Docker environments
• Use ArchClientBuilder::from_env() for pure environment-based configuration
• Use ArchClientBuilder::with_env() to merge env vars into existing builder

Health Check Functionality

• Check AUR service status and latency
• client.health_check() - Quick health check
• client.health_status() - Detailed health status with latency
• Automatic status classification:
  • Healthy - Service responding quickly (< 2s)
  • Degraded - Service responding slowly (≥ 2s)
  • Unreachable - Service not responding
  • Timeout - Request timed out
• Configurable health check timeout

Input Validation

• Automatic validation of package names and search queries
• Validates against Arch Linux packaging standards
• Configurable validation behavior:
  • Strict mode: Returns errors for empty/invalid inputs
  • Lenient mode: Returns empty results for invalid inputs
• New error types:
  • EmptyInput - Empty input provided
  • InvalidPackageName - Invalid package name format
  • InvalidSearchQuery - Invalid search query
  • InputTooLong - Input exceeds maximum length

Prelude Module

• Convenient single-import module: use arch_toolkit::prelude::*;
• Re-exports all commonly used types and functions
• Cleaner imports for common use cases

Rich Error Context

• Enhanced error messages with more context
• Better error classification and reporting
• Improved debugging experience

Trait-Based Design

• AurApi trait for better testability
• Easier to mock and test AUR operations
• More flexible architecture

🔧 Improvements

• Better error messages with more context
• Improved testability with trait-based design
• Enhanced robustness with input validation
• MIT License added to project
• Various dev usability improvements

Quick Start

Using Environment Variables

export ARCH_TOOLKIT_TIMEOUT=60
export ARCH_TOOLKIT_USER_AGENT="my-app/1.0"
export ARCH_TOOLKIT_MAX_RETRIES=3

use arch_toolkit::ArchClient;

// Create client from environment variables
let client = ArchClient::builder()
    .from_env()
    .build()?;

Health Checks

use arch_toolkit::ArchClient;

let client = ArchClient::new()?;

// Quick health check
let is_healthy = client.health_check().await?;
println!("AUR is healthy: {}", is_healthy);

// Detailed health status
let status = client.health_status().await?;
println!("Status: {:?}, Latency: {:?}", status.status, status.latency);

Input Validation

use arch_toolkit::ArchClient;
use arch_toolkit::validation::ValidationConfig;

// Strict validation (default)
let client = ArchClient::new()?;
// Empty search will return an error
let result = client.aur().search("").await; // Returns Err(EmptyInput)

// Lenient validation
let config = ValidationConfig {
    strict_empty: false,
    ..Default::default()
};
let client = ArchClient::builder()
    .validation_config(config)
    .build()?;
// Empty search will return empty results
let result = client.aur().search("").await?; // Returns Ok(vec![])

Using Prelude

use arch_toolkit::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let client = ArchClient::new()?;
    let packages = client.aur().search("yay").await?;
    Ok(())
}

Migration from v0.1.0

No breaking changes! This is a backward-compatible release. All existing code will continue to work.

Optional upgrades:

• Consider using prelude::* for cleaner imports
• Add health checks to monitor AUR service status
• Use environment variables for configuration in CI/CD environments
• Enable input validation for better error handling

Installation

cargo add [email protected] --features aur

Or update your Cargo.toml:

[dependencies]
arch-toolkit = { version = "0.1.1", features = ["aur"] }

Documentation

• Full API Documentation
• GitHub Repository
• Examples

Feedback

Found a bug or have a feature request? Open an issue on GitHub!

---

Full Changelog: See CHANGELOG.md for detailed technical changes.

Release v0.1.0

Release v0.1.0 - Initial Release

Release Date: 2025-12-21

🎉 First Release!

This is the initial release of arch-toolkit, a comprehensive Rust library for Arch Linux package management. This release focuses on AUR (Arch User Repository) operations with a solid foundation for future expansion.

What's New

✨ AUR Operations

AUR Search

• Search for packages in the Arch User Repository by name
• Uses AUR RPC v5 search endpoint
• Returns up to 200 results per query
• Includes popularity scores, maintainer info, and out-of-date status

AUR Package Info

• Fetch detailed information for one or more AUR packages
• Batch query support (fetch multiple packages in a single request)
• Comprehensive package details including:
  • Dependencies, optional dependencies, and conflicts
  • Licenses, groups, provides, and replaces
  • Timestamps for first submission and last modification
  • Vote counts and popularity scores

AUR Comments

• Scrape and parse comments from AUR package pages
• HTML parsing with automatic date parsing and timezone conversion
• Pinned comment detection
• Markdown-like formatting for comment content
• Sorted by date (latest first)

PKGBUILD Fetching

• Retrieve PKGBUILD content for AUR packages
• Fetches from AUR cgit repository
• Dual-level rate limiting (200ms minimum interval + exponential backoff)
• 10-second timeout

Optional Caching Layer

• In-memory LRU cache with configurable TTL per operation
• Optional disk cache with JSON serialization for persistence
• Per-operation cache enable/disable flags (search, info, comments, pkgbuild)
• Configurable TTLs for each operation type
• Cache promotion from disk to memory on hit
• Thread-safe implementation

🛡️ Built-in Protection

Rate Limiting

• Automatic rate limiting for archlinux.org requests
• Exponential backoff for archlinux.org requests (500ms base, max 60s)
• Semaphore-based request serialization
• Random jitter to prevent thundering herd
• Automatic backoff reset on successful requests

Retry Policy

• Configurable retry behavior for transient network failures
• Exponential backoff with configurable initial and max delays
• Random jitter to prevent thundering herd
• Per-operation retry enable/disable flags (search, info, comments, pkgbuild)
• Automatic retry-after header handling
• Error classification (timeouts, 5xx, 429 are retryable)

Error Handling

• Comprehensive ArchToolkitError enum with clear error variants:
  • Network errors (HTTP/network failures)
  • JSON parsing errors
  • Custom parsing errors
  • Rate limiting errors with retry-after information
  • Not found errors
  • Invalid input errors
  • Cache errors (serialization, I/O, expiration)
• Network error recovery
• Graceful handling of missing packages

Cache Invalidation API

• Manual cache management via CacheInvalidator builder
• Invalidate specific search queries
• Invalidate info/comments/pkgbuild cache for specific packages
• Invalidate all caches for a package
• Clear all caches

Client Builder Pattern

• ArchClientBuilder for flexible client configuration
• Custom timeout configuration
• User agent customization
• Retry policy configuration with exponential backoff
• Cache configuration support

Type System

• AurPackage: Minimal package info for search results
• AurPackageDetails: Full package details with all metadata
• AurComment: Comment structure with author, date, content, pinned status

AUR Operations Wrapper

• Aur struct providing fluent API for AUR operations
• Method chaining: client.aur().search(), client.aur().info(), etc.
• Automatic rate limiting and retry handling
• Integrated caching when configured

📚 Documentation

• Complete rustdoc documentation for all public APIs
• Usage examples for every function
• Clear What/Inputs/Output/Details format
• Crate-level documentation with examples for all AUR operations
• Example programs demonstrating AUR operations and caching layer

Quick Start

Add to your Cargo.toml:

[dependencies]
arch-toolkit = { version = "0.1.0", features = ["aur"] }
tokio = { version = "1", features = ["rt", "time"] }

Example usage:

use arch_toolkit::ArchClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with default settings
    let client = ArchClient::new()?;
    
    // Search for packages
    let packages = client.aur().search("yay").await?;
    println!("Found {} packages", packages.len());
    
    // Get package details
    let details = client.aur().info(&["yay", "paru"]).await?;
    for pkg in details {
        println!("{}: {}", pkg.name, pkg.description);
    }
    
    // Fetch comments
    let comments = client.aur().comments("yay").await?;
    for comment in comments.iter().take(5) {
        println!("{}: {}", comment.author, comment.content);
    }
    
    // Get PKGBUILD
    let pkgbuild = client.aur().pkgbuild("yay").await?;
    println!("PKGBUILD length: {} bytes", pkgbuild.len());
    
    Ok(())
}

Custom Configuration

use arch_toolkit::ArchClient;
use arch_toolkit::cache::CacheConfigBuilder;
use std::time::Duration;

// Create client with custom timeout and caching
let cache_config = CacheConfigBuilder::new()
    .enable_search(true)
    .search_ttl(Duration::from_secs(300))
    .enable_info(true)
    .info_ttl(Duration::from_secs(900))
    .build();

let client = ArchClient::builder()
    .timeout(Duration::from_secs(60))
    .user_agent("my-app/1.0")
    .cache_config(cache_config)
    .build()?;

Technical Highlights

• Async-first design: All I/O operations use tokio async/await
• Feature flags: Modular design with aur and cache-disk feature flags
• Zero dependencies by default: Minimal core dependencies (serde, thiserror, tracing)
• Optional dependencies: HTTP client, HTML parsing, date handling only when aur feature is enabled
• Caching dependencies: LRU cache and directory utilities only when caching is used
• Strict code quality: Clippy pedantic and nursery rules enabled
• Complexity thresholds: Cyclomatic and data flow complexity < 25
• Cache design: Generic Cache<K, V> trait for extensibility
• Well-tested: Unit tests and integration tests for cache implementations

What's Next

Future releases will add:

• Dependency resolution and SRCINFO parsing
• Package index queries (installed, official repos)
• Installation command building
• News feeds and security advisories
• PKGBUILD security analysis

Installation

cargo add arch-toolkit --features aur

Or add to Cargo.toml:

[dependencies]
arch-toolkit = { version = "0.1.0", features = ["aur"] }

To enable disk caching (optional):

[dependencies]
arch-toolkit = { version = "0.1.0", features = ["aur", "cache-disk"] }

Documentation

• Full API Documentation
• GitHub Repository
• Examples

Feedback

Found a bug or have a feature request? Open an issue on GitHub!

---

Full Changelog: See CHANGELOG.md for detailed technical changes.