@hivehub/rulebook 1.2.0

package/templates/languages/CSHARP.md

@@ -0,0 +1,417 @@
+<!-- CSHARP:START -->
+# C# Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+dotnet format --verify-no-changes  # Format check
+dotnet build              # Build + compile check
+dotnet test               # All tests (100% pass)
+dotnet test --collect:"XPlat Code Coverage"  # Coverage (95%+ required)
+
+# Security audit:
+dotnet list package --vulnerable  # Vulnerability scan
+dotnet list package --outdated    # Check outdated deps
+```
+
+## C# Configuration
+
+**CRITICAL**: Use .NET 8+ with C# 12+.
+
+- **Version**: .NET 8.0+
+- **C# Version**: 12+
+- **Target**: net8.0
+- **Nullable**: Enabled
+- **LangVersion**: latest
+
+### Project File Requirements
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AnalysisMode>All</AnalysisMode>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    
+    <!-- Package Metadata -->
+    <PackageId>Your.Package.Name</PackageId>
+    <Version>1.0.0</Version>
+    <Authors>Your Name</Authors>
+    <Company>Your Company</Company>
+    <Description>A short description of your package</Description>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/your-org/your-project</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/your-org/your-project</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageTags>your;tags</PackageTags>
+    
+    <!-- Documentation -->
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+</Project>
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use --verify-no-changes!)
+dotnet format --verify-no-changes
+
+# 2. Build (MUST pass with no warnings - matches workflow)
+dotnet build --no-incremental --warnaserror
+
+# 3. Run all tests (MUST pass 100% - matches workflow)
+dotnet test --no-build
+
+# 4. Check coverage (MUST meet threshold)
+dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- CI/CD failures happen when local commands differ from workflows
+- Example: Using `dotnet format` locally but `dotnet format --verify-no-changes` in CI = failure
+- Example: Missing `--warnaserror` flag = warnings pass locally but fail in CI
+
+### Code Style
+
+Use `.editorconfig` for consistent code style:
+
+```ini
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{cs,csx,vb,vbx}]
+indent_size = 4
+
+# C# Code Style Rules
+[*.cs]
+# Organize usings
+dotnet_sort_system_directives_first = true
+dotnet_separate_import_directive_groups = false
+
+# this. preferences
+dotnet_style_qualification_for_field = false:warning
+dotnet_style_qualification_for_property = false:warning
+dotnet_style_qualification_for_method = false:warning
+dotnet_style_qualification_for_event = false:warning
+
+# Language keywords vs BCL types preferences
+dotnet_style_predefined_type_for_locals_parameters_members = true:warning
+dotnet_style_predefined_type_for_member_access = true:warning
+
+# Modifier preferences
+dotnet_style_require_accessibility_modifiers = always:warning
+csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:warning
+
+# Expression preferences
+csharp_style_var_for_built_in_types = true:warning
+csharp_style_var_when_type_is_apparent = true:warning
+csharp_style_var_elsewhere = true:warning
+
+# Pattern matching
+csharp_style_pattern_matching_over_is_with_cast_check = true:warning
+csharp_style_pattern_matching_over_as_with_null_check = true:warning
+
+# Null-checking preferences
+csharp_style_throw_expression = true:warning
+csharp_style_conditional_delegate_call = true:warning
+
+# Code block preferences
+csharp_prefer_braces = true:warning
+csharp_prefer_simple_using_statement = true:warning
+
+# Naming conventions
+dotnet_naming_rule.interface_should_be_begins_with_i.severity = warning
+dotnet_naming_rule.interface_should_be_begins_with_i.symbols = interface
+dotnet_naming_rule.interface_should_be_begins_with_i.style = begins_with_i
+
+dotnet_naming_rule.types_should_be_pascal_case.severity = warning
+dotnet_naming_rule.types_should_be_pascal_case.symbols = types
+dotnet_naming_rule.types_should_be_pascal_case.style = pascal_case
+
+dotnet_naming_rule.non_field_members_should_be_pascal_case.severity = warning
+dotnet_naming_rule.non_field_members_should_be_pascal_case.symbols = non_field_members
+dotnet_naming_rule.non_field_members_should_be_pascal_case.style = pascal_case
+
+# Symbol specifications
+dotnet_naming_symbols.interface.applicable_kinds = interface
+dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
+
+dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum
+dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
+
+dotnet_naming_symbols.non_field_members.applicable_kinds = property, event, method
+dotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
+
+# Naming styles
+dotnet_naming_style.begins_with_i.required_prefix = I
+dotnet_naming_style.begins_with_i.required_suffix = 
+dotnet_naming_style.begins_with_i.word_separator = 
+dotnet_naming_style.begins_with_i.capitalization = pascal_case
+
+dotnet_naming_style.pascal_case.required_prefix = 
+dotnet_naming_style.pascal_case.required_suffix = 
+dotnet_naming_style.pascal_case.word_separator = 
+dotnet_naming_style.pascal_case.capitalization = pascal_case
+```
+
+### Testing
+
+- **Framework**: xUnit (recommended) or NUnit
+- **Location**: Separate test project
+- **Coverage**: Coverlet
+- **Coverage Threshold**: 95%+
+
+Example test structure:
+```csharp
+using Xunit;
+
+namespace YourProject.Tests;
+
+public class MyClassTests
+{
+    [Fact]
+    public void Process_ValidInput_ReturnsExpectedResult()
+    {
+        // Arrange
+        var sut = new MyClass();
+        var input = "test";
+
+        // Act
+        var result = sut.Process(input);
+
+        // Assert
+        Assert.Equal("TEST", result);
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData(null)]
+    public void Process_InvalidInput_ThrowsArgumentException(string input)
+    {
+        // Arrange
+        var sut = new MyClass();
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => sut.Process(input));
+    }
+}
+```
+
+### Documentation
+
+- Use XML documentation comments
+- Document all public APIs
+- Include `<summary>`, `<param>`, `<returns>`, `<exception>`
+
+Example:
+```csharp
+namespace YourProject;
+
+/// <summary>
+/// Provides functionality for processing data.
+/// </summary>
+public class MyClass
+{
+    /// <summary>
+    /// Processes the input string and converts it to uppercase.
+    /// </summary>
+    /// <param name="input">The input string to process.</param>
+    /// <returns>The processed string in uppercase.</returns>
+    /// <exception cref="ArgumentException">Thrown when input is null or empty.</exception>
+    /// <example>
+    /// <code>
+    /// var processor = new MyClass();
+    /// var result = processor.Process("hello");
+    /// // result is "HELLO"
+    /// </code>
+    /// </example>
+    public string Process(string input)
+    {
+        if (string.IsNullOrEmpty(input))
+        {
+            throw new ArgumentException("Input cannot be null or empty.", nameof(input));
+        }
+
+        return input.ToUpperInvariant();
+    }
+}
+```
+
+## Project Structure
+
+```
+project/
+├── src/
+│   └── YourProject/
+│       ├── YourProject.csproj
+│       ├── Class1.cs
+│       └── ...
+├── tests/
+│   └── YourProject.Tests/
+│       ├── YourProject.Tests.csproj
+│       ├── Class1Tests.cs
+│       └── ...
+├── docs/                    # Project documentation
+├── .editorconfig            # Code style configuration
+├── Directory.Build.props    # Shared MSBuild properties
+├── Directory.Packages.props # Central package management
+├── YourProject.sln          # Solution file
+├── README.md                # Project overview (allowed in root)
+├── CHANGELOG.md             # Version history (allowed in root)
+└── LICENSE                  # Project license (allowed in root)
+```
+
+## Nullable Reference Types
+
+- Enable nullable reference types
+- Use `?` for nullable types
+- Use null-forgiving operator `!` sparingly
+
+Example:
+```csharp
+public class UserService
+{
+    private readonly ILogger<UserService> _logger;
+
+    public UserService(ILogger<UserService> logger)
+    {
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public User? FindUser(string? username)
+    {
+        if (string.IsNullOrEmpty(username))
+        {
+            return null;
+        }
+
+        // Implementation
+        return new User { Username = username };
+    }
+
+    public User GetUser(string username)
+    {
+        var user = FindUser(username);
+        return user ?? throw new InvalidOperationException("User not found");
+    }
+}
+```
+
+## Async/Await Best Practices
+
+- Use `async`/`await` for I/O operations
+- Don't block on async code
+- Use `ConfigureAwait(false)` in libraries
+- Return `Task` or `ValueTask`
+
+Example:
+```csharp
+public class DataService
+{
+    private readonly HttpClient _httpClient;
+
+    public async Task<string> FetchDataAsync(string url, CancellationToken cancellationToken = default)
+    {
+        var response = await _httpClient.GetAsync(url, cancellationToken).ConfigureAwait(false);
+        response.EnsureSuccessStatusCode();
+        
+        return await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+    }
+}
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows for:
+
+1. **Testing** (`dotnet-test.yml`):
+   - Test on ubuntu-latest, windows-latest, macos-latest
+   - Test on .NET 8.0
+   - Upload coverage reports
+
+2. **Linting** (`dotnet-lint.yml`):
+   - Format check: `dotnet format --verify-no-changes`
+   - Build: `dotnet build --no-incremental`
+   - Analyzers enabled
+
+## Package Publication
+
+### Publishing to NuGet
+
+**Prerequisites:**
+1. Create account at https://www.nuget.org
+2. Generate API key from account settings
+3. Add `NUGET_API_KEY` to GitHub repository secrets
+
+**Publishing Workflow:**
+
+1. Update version in .csproj
+2. Update CHANGELOG.md
+3. Run quality checks:
+   ```bash
+   dotnet format --verify-no-changes
+   dotnet build --configuration Release
+   dotnet test --configuration Release
+   ```
+
+4. Pack: `dotnet pack --configuration Release`
+5. Create git tag: `git tag v1.0.0 && git push --tags`
+6. GitHub Actions automatically publishes to NuGet
+7. Or manual publish: `dotnet nuget push bin/Release/*.nupkg --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json`
+
+**Publishing Checklist:**
+
+- ✅ All tests passing
+- ✅ Code formatted (`dotnet format`)
+- ✅ No build warnings
+- ✅ Version updated in .csproj
+- ✅ CHANGELOG.md updated
+- ✅ README.md up to date
+- ✅ LICENSE file present
+- ✅ XML documentation generated
+- ✅ Package metadata complete
+- ✅ Verify with `dotnet pack`
+
+**Semantic Versioning:**
+
+Use `<Version>` in .csproj with SemVer:
+- **MAJOR**: Breaking API changes
+- **MINOR**: New features (backwards compatible)
+- **PATCH**: Bug fixes (backwards compatible)
+
+<!-- CSHARP:END -->
+