diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index da40ee0..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,263 +0,0 @@ -# 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 ci --ignore-scripts -``` - -**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 ci --ignore-scripts` 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. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 02dd134..0000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -.github/copilot-instructions.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2e3301b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +# setup-uv agent notes + +This repository is a TypeScript-based GitHub Action for installing `uv` in GitHub Actions workflows. It also supports restoring/saving the `uv` cache and optional managed-Python caching. + +- The published action runs the committed bundles in `dist/`, not the TypeScript in `src/`. After any code change, run `npm run package` and commit the resulting `dist/` updates. +- Standard local validation is: + 1. `npm ci --ignore-scripts` + 2. `npm run all` +- `npm run check` uses Biome (not ESLint/Prettier) and rewrites files in place. +- User-facing changes are usually multi-file changes. If you add or change inputs, outputs, or behavior, update `action.yml`, the implementation in `src/`, tests in `__tests__/`, relevant docs/README, and then re-package. +- The easiest areas to regress are version resolution and caching. When touching them, add or update tests for precedence, cache invalidation, and cross-platform path behavior. +- Workflow edits have extra CI-only checks (`actionlint` and `zizmor`); `npm run all` does not cover them. +- Before finishing, make sure validation does not leave generated or formatting-only diffs behind.