setup-uv/.github/copilot-instructions.md

# Copilot Instructions for setup-uv

This document provides essential information for GitHub Copilot coding agents working on the `astral-sh/setup-uv` repository.

## Repository Overview

**setup-uv** is a GitHub Action that sets up the [uv](https://docs.astral.sh/uv/)
Python package installer in GitHub Actions workflows.
It's a TypeScript-based action that downloads uv binaries, manages caching, handles version resolution,
and configures the environment for subsequent workflow steps.

### Key Features

- Downloads and installs specific uv versions from GitHub releases
- Supports version resolution from config files (pyproject.toml, uv.toml, .tool-versions)
- Implements intelligent caching for both uv cache and Python installations
- Provides cross-platform support (Linux, macOS, Windows, including ARM architectures)
- Includes problem matchers for Python error reporting
- Supports environment activation and custom tool directories

## Repository Structure

**Size**: Small-medium repository (~50 source files, ~400 total files including dependencies)
**Languages**: TypeScript (primary), JavaScript (compiled output), JSON (configuration)
**Runtime**: Node.js 24 (GitHub Actions runtime)
**Key Dependencies**: @actions/core, @actions/cache, @actions/tool-cache, @octokit/core

### Core Architecture

```
src/
├── setup-uv.ts          # Main entry point and orchestration
├── save-cache.ts        # Post-action cache saving logic
├── update-known-versions.ts  # Maintenance script for version updates
├── cache/               # Cache management functionality
├── download/            # Version resolution and binary downloading
├── utils/               # Input parsing, platform detection, configuration
└── version/             # Version resolution from various file formats
```

### Key Files and Locations

- **Action Definition**: `action.yml` - Defines all inputs/outputs and entry points
- **Main Source**: `src/setup-uv.ts` - Primary action logic
- **Configuration**: `biome.json` (linting), `tsconfig.json` (TypeScript), `jest.config.js` (testing)
- **Compiled Output**: `dist/` - Contains compiled Node.js bundles (auto-generated, committed)
- **Test Fixtures**: `__tests__/fixtures/` - Sample projects for different configuration scenarios
- **Workflows**: `.github/workflows/test.yml` - Comprehensive CI/CD pipeline

## Build and Development Process

### Prerequisites

- Node.js 24+ (matches GitHub Actions runtime)
- npm (included with Node.js)

### Essential Commands (ALWAYS run in this order)

#### 1. Install Dependencies

```bash
npm install
```

**Timing**: ~20-30 seconds
**Note**: Always run this first after cloning or when package.json changes

#### 2. Build TypeScript

```bash
npm run build
```

**Timing**: ~5-10 seconds
**Purpose**: Compiles TypeScript source to JavaScript in `lib/` directory

#### 3. Lint and Format Code

```bash
npm run check
```

**Timing**: ~2-5 seconds
**Tool**: Biome (replaces ESLint/Prettier)
**Auto-fixes**: Formatting, import organization, basic linting issues

#### 4. Package for Distribution

```bash
npm run package
```

**Timing**: ~20-30 seconds
**Purpose**: Creates bundled distributions in `dist/` using @vercel/ncc
**Critical**: This step MUST be run before committing - the `dist/` files are used by GitHub Actions

#### 5. Run Tests

```bash
npm test
```

**Timing**: ~10-15 seconds
**Framework**: Jest with TypeScript support
**Coverage**: Unit tests for version resolution, input parsing, checksum validation

#### 6. Complete Validation (Recommended)

```bash
npm run all
```

**Timing**: ~60-90 seconds
**Purpose**: Runs build → check → package → test in sequence
**Use**: Before making pull requests or when unsure about build state

### Important Build Notes

**CRITICAL**: Always run `npm run package` after making code changes. The `dist/` directory contains the compiled bundles that GitHub Actions actually executes. Forgetting this step will cause your changes to have no effect.

**TypeScript Warnings**: You may see ts-jest warnings about "isolatedModules" - these are harmless and don't affect functionality.

**Biome**: This project uses Biome instead of ESLint/Prettier. Run `npm run check` to fix formatting and linting issues automatically.

## Testing Strategy

### Unit Tests

- **Location**: `__tests__/` directory
- **Framework**: Jest with ts-jest transformer
- **Coverage**: Version resolution, input parsing, checksum validation, utility functions

### Integration Tests

- **Location**: `.github/workflows/test.yml`
- **Scope**: Full end-to-end testing across multiple platforms and scenarios
- **Key Test Categories**:
  - Version installation (specific, latest, semver ranges)
  - Cache behavior (setup, restore, invalidation)
  - Cross-platform compatibility (Ubuntu, macOS, Windows, ARM)
  - Configuration file parsing (pyproject.toml, uv.toml, requirements.txt)
  - Error handling and edge cases

### Test Fixtures

Located in `__tests__/fixtures/`, these provide sample projects with different configurations:
- `pyproject-toml-project/` - Standard Python project with uv version specification
- `uv-toml-project/` - Project using uv.toml configuration
- `requirements-txt-project/` - Legacy requirements.txt format
- `cache-dir-defined-project/` - Custom cache directory configuration

## Continuous Integration

### GitHub Workflows

#### Primary Test Suite (`.github/workflows/test.yml`)

- **Triggers**: PRs, pushes to main, manual dispatch
- **Matrix**: Multiple OS (Ubuntu, macOS, Windows), architecture (x64, ARM), and configuration combinations
- **Duration**: ~5 minutes for full matrix
- **Key Validations**:
  - Cross-platform installation and functionality
  - Cache behavior and performance
  - Version resolution from various sources
  - Tool directory configurations
  - Problem matcher functionality

#### Maintenance Workflows

- **CodeQL Analysis**: Security scanning on pushes/PRs
- **Update Known Versions**: Daily job to sync with latest uv releases
- **Dependabot**: Automated dependency updates

### Pre-commit Validation

The CI runs these checks that you should run locally:
1. `npm run all` - Complete build and test suite
2. ActionLint - GitHub Actions workflow validation
3. Change detection - Ensures no uncommitted build artifacts

## Key Configuration Files

### Action Configuration (`action.yml`)

Defines 20+ inputs including version specifications,
cache settings, tool directories, and environment options.
This file is the authoritative source for understanding available action parameters.

### TypeScript Configuration (`tsconfig.json`)

- Target: ES2024
- Module: nodenext (Node.js modules)
- Strict mode enabled
- Output directory: `lib/`

### Linting Configuration (`biome.json`)

- Formatter and linter combined
- Enforces consistent code style
- Automatically organizes imports and sorts object keys

## Common Development Patterns

### Making Code Changes

1. Edit TypeScript source files in `src/`
2. Run `npm run build` to compile
3. Run `npm run check` to format and lint
4. Run `npm run package` to update distribution bundles
5. Run `npm test` to verify functionality
6. Commit all changes including `dist/` files

### Adding New Features

- Follow existing patterns in `src/utils/inputs.ts` for new action inputs
- Update `action.yml` to declare new inputs/outputs
- Add corresponding tests in `__tests__/`
- Add a test in `.github/workflows/test.yml` if it affects integration
- Update README.md with usage examples

### Cache-Related Changes

- Cache logic is complex and affects performance significantly
- Test with multiple cache scenarios (hit, miss, invalidation)
- Consider impact on both GitHub-hosted and self-hosted runners
- Validate cache key generation and dependency detection

### Version Resolution Changes

- Version resolution supports multiple file formats and precedence rules
- Test with fixtures in `__tests__/fixtures/`
- Consider backward compatibility with existing projects
- Validate semver and PEP 440 specification handling

## Troubleshooting

### Build Failures

- **"Module not found"**: Run `npm install` to ensure dependencies are installed
- **TypeScript errors**: Check `tsconfig.json` and ensure all imports are valid
- **Test failures**: Check if test fixtures have been modified or if logic changes broke assumptions

### Action Failures in Workflows

- **Changes not taking effect**: Ensure `npm run package` was run and `dist/` files committed
- **Version resolution issues**: Check version specification format and file existence
- **Cache problems**: Verify cache key generation and dependency glob patterns

### Common Gotchas

- **Forgetting to package**: Code changes won't work without running `npm run package`
- **Platform differences**: Windows paths use backslashes, test cross-platform behavior
- **Cache invalidation**: Cache keys are sensitive to dependency file changes
- **Tool directory permissions**: Some platforms require specific directory setups

## Trust These Instructions

These instructions are comprehensive and current. Only search for additional information if:
- You encounter specific error messages not covered here
- You need to understand implementation details of specific functions
- The instructions appear outdated (check repository commit history)

For most development tasks, following the build process and development patterns outlined above will be sufficient.