diff --git a/.github/COPILOT_AGENT_README.md b/.github/COPILOT_AGENT_README.md index 4ef95a2a7..11f6cb5b6 100644 --- a/.github/COPILOT_AGENT_README.md +++ b/.github/COPILOT_AGENT_README.md @@ -3,11 +3,13 @@ This repository includes a minimal opt-in configuration and CI workflow to allow the GitHub Copilot coding agent to open and validate PRs. - .copilot-agent.yml: opt-in config for automated agents +- .github/agents/copilot-agent.yml: detailed agent policy configuration - .github/workflows/dotnetcore.yml: CI runs on PRs touching the solution, source, or tests to validate changes -- AGENTS.yml: general information for this project +- AGENTS.md: general instructions for Copilot coding agent with project-specific guidelines Maintainers can adjust the allowed paths or disable the agent by editing or removing .copilot-agent.yml. Notes: -- Do not change any other files in the repository. -- If build/test paths are different, update the workflow accordingly; this workflow targets SharpCompress.sln and the SharpCompress.Tests test project. +- The agent can create, modify, and delete files within the allowed paths (src, tests, README.md, AGENTS.md) +- All changes require review before merge +- If build/test paths are different, update the workflow accordingly; this workflow targets SharpCompress.sln and the SharpCompress.Test test project. diff --git a/AGENTS.md b/AGENTS.md index 62c8d4c10..8275b651f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,24 @@ --- -description: 'Guidelines for building C# applications' +description: 'Guidelines for building SharpCompress - A C# compression library' applyTo: '**/*.cs' --- -# C# Development +# SharpCompress Development + +## About SharpCompress +SharpCompress is a pure C# compression library supporting multiple archive formats (Zip, Tar, GZip, BZip2, 7Zip, Rar, LZip, XZ, ZStandard) for .NET Framework 4.62, .NET Standard 2.1, .NET 6.0, and .NET 8.0. The library provides both seekable Archive APIs and forward-only Reader/Writer APIs for streaming scenarios. ## C# Instructions - Always use the latest version C#, currently C# 13 features. - Write clear and concise comments for each function. +- Follow the existing code style and patterns in the codebase. ## General Instructions - Make only high confidence suggestions when reviewing code changes. - Write code with good maintainability practices, including comments on why certain design decisions were made. - Handle edge cases and write clear exception handling. - For libraries or external dependencies, mention their usage and purpose in comments. +- Preserve backward compatibility when making changes to public APIs. ## Naming Conventions @@ -23,21 +28,26 @@ applyTo: '**/*.cs' ## Code Formatting -- Use CSharpier for all code formatting to ensure consistent style across the project. -- Install CSharpier globally: `dotnet tool install -g csharpier` -- Format files with: `dotnet csharpier format .` -- **ALWAYS run `dotnet csharpier format .` after making code changes before committing.** -- Configure your IDE to format on save using CSharpier. -- CSharpier configuration can be customized via `.csharpierrc` file in the project root. -- Trust CSharpier's opinionated formatting decisions to maintain consistency. +- Use CSharpier for code formatting to ensure consistent style across the project +- CSharpier is configured as a local tool in `.config/dotnet-tools.json` +- Restore tools with: `dotnet tool restore` +- Format files from the project root with: `dotnet csharpier .` +- **Run `dotnet csharpier .` from the project root after making code changes before committing** +- Configure your IDE to format on save using CSharpier for the best experience +- The project also uses `.editorconfig` for editor settings (indentation, encoding, etc.) +- Let CSharpier handle code style while `.editorconfig` handles editor behavior ## Project Setup and Structure -- Guide users through creating a new .NET project with the appropriate templates. -- Explain the purpose of each generated file and folder to build understanding of the project structure. -- Demonstrate how to organize code using feature folders or domain-driven design principles. -- Show proper separation of concerns with models, services, and data access layers. -- Explain the Program.cs and configuration system in ASP.NET Core 9 including environment-specific settings. +- The project targets multiple frameworks: .NET Framework 4.62, .NET Standard 2.1, .NET 6.0, and .NET 8.0 +- Main library is in `src/SharpCompress/` +- Tests are in `tests/SharpCompress.Test/` +- Performance tests are in `tests/SharpCompress.Performance/` +- Test archives are in `tests/TestArchives/` +- Build project is in `build/` +- Use `dotnet build` to build the solution +- Use `dotnet test` to run tests +- Solution file: `SharpCompress.sln` ## Nullable Reference Types @@ -45,21 +55,64 @@ applyTo: '**/*.cs' - Always use `is null` or `is not null` instead of `== null` or `!= null`. - Trust the C# null annotations and don't add null checks when the type system says a value cannot be null. +## SharpCompress-Specific Guidelines + +### Supported Formats +SharpCompress supports multiple archive and compression formats: +- **Archive Formats**: Zip, Tar, 7Zip, Rar (read-only) +- **Compression**: DEFLATE, BZip2, LZMA/LZMA2, PPMd, ZStandard (decompress only), Deflate64 (decompress only) +- **Combined Formats**: Tar.GZip, Tar.BZip2, Tar.LZip, Tar.XZ, Tar.ZStandard +- See FORMATS.md for complete format support matrix + +### Stream Handling Rules +- **Disposal**: As of version 0.21, SharpCompress closes wrapped streams by default +- Use `ReaderOptions` or `WriterOptions` with `LeaveStreamOpen = true` to control stream disposal +- Use `NonDisposingStream` wrapper when working with compression streams directly to prevent disposal +- Always dispose of readers, writers, and archives in `using` blocks +- For forward-only operations, use Reader/Writer APIs; for random access, use Archive APIs + +### Async/Await Patterns +- All I/O operations support async/await with `CancellationToken` +- Async methods follow the naming convention: `MethodNameAsync` +- Key async methods: + - `WriteEntryToAsync` - Extract entry asynchronously + - `WriteAllToDirectoryAsync` - Extract all entries asynchronously + - `WriteAsync` - Write entry asynchronously + - `WriteAllAsync` - Write directory asynchronously + - `OpenEntryStreamAsync` - Open entry stream asynchronously +- Always provide `CancellationToken` parameter in async methods + +### Archive APIs vs Reader/Writer APIs +- **Archive API**: Use for random access with seekable streams (e.g., `ZipArchive`, `TarArchive`) +- **Reader API**: Use for forward-only reading on non-seekable streams (e.g., `ZipReader`, `TarReader`) +- **Writer API**: Use for forward-only writing on streams (e.g., `ZipWriter`, `TarWriter`) +- 7Zip only supports Archive API due to format limitations + +### Tar-Specific Considerations +- Tar format requires file size in the header +- If no size is specified to TarWriter and the stream is not seekable, an exception will be thrown +- Tar combined with compression (GZip, BZip2, LZip, XZ) is supported + +### Zip-Specific Considerations +- Supports Zip64 for large files (seekable streams only) +- Supports PKWare and WinZip AES encryption +- Multiple compression methods: None, Shrink, Reduce, Implode, DEFLATE, Deflate64, BZip2, LZMA, PPMd +- Encrypted LZMA is not supported + +### Performance Considerations +- For large files, use Reader/Writer APIs with non-seekable streams to avoid loading entire file in memory +- Leverage async I/O for better scalability +- Consider compression level trade-offs (speed vs. size) +- Use appropriate buffer sizes for stream operations + ## Testing - Always include test cases for critical paths of the application. -- Guide users through creating unit tests. +- Test with multiple archive formats when making changes to core functionality. +- Include tests for both Archive and Reader/Writer APIs when applicable. +- Test async operations with cancellation tokens. - Do not emit "Act", "Arrange" or "Assert" comments. - Copy existing style in nearby files for test method names and capitalization. -- Explain integration testing approaches for API endpoints. -- Demonstrate how to mock dependencies for effective testing. -- Show how to test authentication and authorization logic. -- Explain test-driven development principles as applied to API development. - -## Performance Optimization - -- Guide users on implementing caching strategies (in-memory, distributed, response caching). -- Explain asynchronous programming patterns and why they matter for API performance. -- Demonstrate pagination, filtering, and sorting for large data sets. -- Show how to implement compression and other performance optimizations. -- Explain how to measure and benchmark API performance. +- Use test archives from `tests/TestArchives` directory for consistency. +- Test stream disposal and `LeaveStreamOpen` behavior. +- Test edge cases: empty archives, large files, corrupted archives, encrypted archives. diff --git a/src/SharpCompress/packages.lock.json b/src/SharpCompress/packages.lock.json index 904860ce8..b85a38f73 100644 --- a/src/SharpCompress/packages.lock.json +++ b/src/SharpCompress/packages.lock.json @@ -335,9 +335,9 @@ "net8.0": { "Microsoft.NET.ILLink.Tasks": { "type": "Direct", - "requested": "[8.0.0, )", - "resolved": "8.0.0", - "contentHash": "B3etT5XQ2nlWkZGO2m/ytDYrOmSsQG1XNBaM6ZYlX5Ch/tDrMFadr0/mK6gjZwaQc55g+5+WZMw4Cz3m8VEF7g==" + "requested": "[8.0.20, )", + "resolved": "8.0.20", + "contentHash": "Rhcto2AjGvTO62+/VTmBpumBOmqIGp7nYEbTbmEXkCq4yPGxV8whju3/HsIA/bKyo2+DggaYk5+/8sxb1AbPTw==" }, "Microsoft.SourceLink.GitHub": { "type": "Direct",