DiscordChatExporter/.github/copilot-instructions.md

Copilot Instructions for DiscordChatExporter

Build, Test, and Lint Commands

Build

# Full build
dotnet build --configuration Release

# Quick build without formatting checks
dotnet build -p:CSharpier_Bypass=true

Test

# Run all tests
dotnet test --configuration Release

# Run a specific test file
dotnet test --configuration Release --filter "ClassName=HtmlContentSpecs"

# Run tests with code coverage
dotnet test -p:CSharpier_Bypass=true --configuration Release --collect:"XPlat Code Coverage"

Format and Lint

# Format code with CSharpier (integrated into CI)
dotnet build -t:CSharpierFormat --configuration Release

# Just verify formatting without applying fixes
dotnet build -p:CSharpier_Bypass=true --configuration Release

Note: CSharpier formatting is enforced in CI. Use dotnet build -t:CSharpierFormat before committing to avoid CI failures.

High-Level Architecture

DiscordChatExporter is a .NET 10.0 application with a layered architecture:

Layer 1: Core (DiscordChatExporter.Core)

• Discord - Discord API client and data models
  • DiscordClient - HTTP client for Discord API v10
  • Data models in Discord/Data/ (records like Channel, Message, Guild) with Parse() methods for JSON deserialization
  • Rate-limit handling with configurable preference
• Exporting - Multi-format export engines
  • ChannelExporter - Orchestrates the export process
  • Format writers: HtmlMessageWriter, JsonMessageWriter, CsvMessageWriter, PlainTextMessageWriter
  • Asset downloading and context building
• Markdown - Converts Discord markdown to target format (HTML or plaintext)
• Utils - Shared utilities for HTTP, validation, etc.

Layer 2: Interfaces

• Cli (DiscordChatExporter.Cli) - Command-line interface using CliFx
  • Commands in Commands/ subdirectory (follows command pattern)
• Gui (DiscordChatExporter.Gui) - Graphical interface using Avalonia
  • ViewModels with MVVM pattern
  • Services for state management
  • Localization support

Layer 3: Tests

• Cli.Tests (DiscordChatExporter.Cli.Tests) - Integration tests using xUnit
  • Specs/ - Scenario tests for export formats and features
  • Infra/ - Test infrastructure and helpers
  • Tests verify HTML/JSON/CSV/TXT exports against Discord test data

Data Flow

Discord API → DiscordClient (rate-limited)
           → ExportContext (loads channel/role/user data)
           → MessageExporter (fetches and writes messages)
           → Format-specific Writer (HTML/JSON/CSV/TXT)
           → File output

Key Conventions

C# Language Features

• File-scoped namespaces - Use namespace X; (not braces)
• Primary constructors - public class MyClass(string param) for injecting dependencies
• Nullable reference types - Enabled globally; use ? for nullable types, ! only when safe
• Treat warnings as errors - All warnings must be resolved before commit

Data Model Patterns

• Use record types for data classes (immutable by default)
• Implement IHasId interface for entities with ID fields
• Deserialization via public static T Parse(JsonElement json) method
• Partial records with separate Parse methods in distinct file sections
• Use Pipe() extension for method chaining transformations

// Example pattern:
public partial record Message(Snowflake Id, string Content) : IHasId { }

public partial record Message
{
    public static Message Parse(JsonElement json)
    {
        var id = json.GetProperty("id").GetNonWhiteSpaceString().Pipe(Snowflake.Parse);
        var content = json.GetProperty("content").GetNonWhiteSpaceString();
        return new(id, content);
    }
}

Exception Handling

• Custom exceptions inherit from DiscordChatExporterException
• Specific exception types for domain errors: ChannelEmptyException, InvalidStateException, etc.
• Exceptions include helpful context about the guild/channel where applicable

Discord API Integration

• All API URLs are relative to base URI https://discord.com/api/v10/
• Token authorization uses Authorization header (either Bot {token} or raw token)
• Rate limiting respects Discord advisory headers but can be configured to respect only hard limits
• Use Http.ResponseResiliencePipeline for retry logic (configured via Polly)

Export Format Implementation

• Each format has a dedicated *MessageWriter class
• Writers implement MessageWriter interface
• Template files (.cshtml) use RazorBlade for HTML/plaintext rendering
• Markdown conversion uses separate visitors: HtmlMarkdownVisitor, PlainTextMarkdownVisitor

Testing

• Tests in DiscordChatExporter.Cli.Tests/Specs/ follow naming pattern: [Format][Feature]Specs.cs
• Use xUnit [Fact] for individual tests
• Test infrastructure in Infra/ includes ExportWrapper for export orchestration
• Tests require Discord API access; sensitive tests need DISCORD_TOKEN secret
• Use FluentAssertions for readable assertions: .Should().Equal(...), .Should().Contain(...)

Dependencies and Injection

• Microsoft.Extensions.DependencyInjection for IoC
• Services typically injected via primary constructor
• Configuration loaded via Microsoft.Extensions.Configuration (supports env vars and user secrets)

Code Organization

• Folder structure mirrors namespace structure
• Data models organized under domain folder (e.g., Discord/Data/)
• Keep public methods at the top of the class
• Use async ValueTask for small async operations, async Task for larger ones

Architecture Details

Why This Structure?

• Separation of concerns: Core library independent from UI implementations
• Multi-UI support: CLI and GUI share identical core export logic
• Testability: Core is fully testable without UI dependencies
• Extensibility: New export formats are isolated to a single writer class

Important Flow Details

• Message export is stream-based to handle large channels efficiently
• Discord API client implements exponential backoff for rate limits
• Exports can be partitioned by size or date range to manage large channel history
• Assets (images, videos, etc.) can be selectively downloaded during export