From 60c3d12f39c8b71f3b206910eaa9db890405e881 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 11 Oct 2025 17:04:06 +0000
Subject: [PATCH] Add comprehensive Copilot instructions for setup-uv
 repository

Co-authored-by: eifinger <1481961+eifinger@users.noreply.github.com>
---
 .github/copilot-instructions.md               | 225 ++++++++++++++++++
 .../scripts/check-all-tests-passed-needs.js   |  16 ++
 2 files changed, 241 insertions(+)
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .github/scripts/check-all-tests-passed-needs.js

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..82d01b2
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,225 @@
+# 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**: ~20-30 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__/`
+- 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.
\ No newline at end of file
diff --git a/.github/scripts/check-all-tests-passed-needs.js b/.github/scripts/check-all-tests-passed-needs.js
new file mode 100644
index 0000000..30c2b92
--- /dev/null
+++ b/.github/scripts/check-all-tests-passed-needs.js
@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var fs = require("node:fs");
+var yaml = require("js-yaml");
+var workflow = yaml.load(fs.readFileSync("../workflows/test.yml", "utf8"));
+var jobs = Object.keys(workflow.jobs);
+var allTestsPassed = workflow.jobs["all-tests-passed"];
+var needs = allTestsPassed.needs || [];
+var expectedNeeds = jobs.filter(function (j) { return j !== "all-tests-passed"; });
+var missing = expectedNeeds.filter(function (j) { return !needs.includes(j); });
+if (missing.length > 0) {
+    console.error("Missing jobs in all-tests-passed needs: ".concat(missing.join(", ")));
+    console.info("Please add the missing jobs to the needs section of all-tests-passed in test.yml.");
+    process.exit(1);
+}
+console.log("All jobs in test.yml are in the needs section of all-tests-passed.");