From 05d7eadeccb921a5c1107f3203ebea1ae70a724d Mon Sep 17 00:00:00 2001 From: "codebelt-aicia[bot]" Date: Sun, 18 Oct 2026 17:40:28 +0000 Subject: [PATCH 1/9] V5.2.3/service update --- .../Codebelt.Bootstrapper.Console/PackageReleaseNotes.txt | 6 ++++++ .nuget/Codebelt.Bootstrapper.Web/PackageReleaseNotes.txt | 6 ++++++ .../Codebelt.Bootstrapper.Worker/PackageReleaseNotes.txt | 6 ++++++ .nuget/Codebelt.Bootstrapper/PackageReleaseNotes.txt | 6 ++++++ CHANGELOG.md | 4 ++++ Directory.Packages.props | 8 ++++---- 6 files changed, 32 insertions(+), 4 deletions(-) diff --git a/.nuget/Codebelt.Bootstrapper.Console/PackageReleaseNotes.txt b/.nuget/Codebelt.Bootstrapper.Console/PackageReleaseNotes.txt index 9da8450..cc72351 100644 --- a/.nuget/Codebelt.Bootstrapper.Console/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Bootstrapper.Console/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 5.2.3 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 5.2.2 Availability: .NET 10 and .NET 9 diff --git a/.nuget/Codebelt.Bootstrapper.Web/PackageReleaseNotes.txt b/.nuget/Codebelt.Bootstrapper.Web/PackageReleaseNotes.txt index b6317c8..1305c4f 100644 --- a/.nuget/Codebelt.Bootstrapper.Web/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Bootstrapper.Web/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 5.2.3 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 5.2.2 Availability: .NET 10 and .NET 9 diff --git a/.nuget/Codebelt.Bootstrapper.Worker/PackageReleaseNotes.txt b/.nuget/Codebelt.Bootstrapper.Worker/PackageReleaseNotes.txt index 3888b25..1f2dcd9 100644 --- a/.nuget/Codebelt.Bootstrapper.Worker/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Bootstrapper.Worker/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 5.2.3 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 5.2.2 Availability: .NET 10 and .NET 9 diff --git a/.nuget/Codebelt.Bootstrapper/PackageReleaseNotes.txt b/.nuget/Codebelt.Bootstrapper/PackageReleaseNotes.txt index ce93860..dbf32e3 100644 --- a/.nuget/Codebelt.Bootstrapper/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Bootstrapper/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 5.2.3 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 5.2.2 Availability: .NET 10 and .NET 9 diff --git a/CHANGELOG.md b/CHANGELOG.md index 5791262..190269a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), For more details, please refer to `PackageReleaseNotes.txt` on a per assembly basis in the `.nuget` folder. +## [5.2.3] - 2026-10-18 + +This is a service update that focuses on package dependencies. + ## [5.2.2] - 2026-09-15 This is a patch release focused on test infrastructure modernization, comprehensive dependency updates, and enhanced contributing guidelines. diff --git a/Directory.Packages.props b/Directory.Packages.props index a70ec7f..2248d9c 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -3,10 +3,10 @@ true - - - - + + + + From 5afb77f9829e46bbc890cfbfcec4d5a3f83eb4db Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:23 +0200 Subject: [PATCH 2/9] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20move=20copilot=20guida?= =?UTF-8?q?nce=20into=20agents.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Test, benchmark, and XML documentation guidance now lives in AGENTS.md so agents read one source of truth. The separate copilot-instructions file is retired and references point to AGENTS.md. --- .bot/README.md | 2 +- .github/copilot-instructions.md | 632 -------------------------------- AGENTS.md | 630 ++++++++++++++++++++++++++++++- 3 files changed, 628 insertions(+), 636 deletions(-) delete mode 100644 .github/copilot-instructions.md diff --git a/.bot/README.md b/.bot/README.md index 2cfca89..f7e13f0 100644 --- a/.bot/README.md +++ b/.bot/README.md @@ -7,4 +7,4 @@ This folder is reserved for local-only AI working material such as: - design alternatives - temporary agent state -Keep this folder out of source control. Move only finalized, non-confidential guidance into `AGENTS.md` or `.github/copilot-instructions.md`. +Keep this folder out of source control. Move only finalized, non-confidential guidance into `AGENTS.md`. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 4cd6ee6..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,632 +0,0 @@ ---- -description: 'Writing Unit Tests' -applyTo: "**/*.{cs,csproj}" ---- - -# Writing Unit Tests -This document provides instructions for writing unit tests for a project/solution. Please follow these guidelines to ensure consistency and maintainability. - -## 1. Base Class - -**Always inherit from the `Test` base class** for all unit test classes. -This ensures consistent setup, teardown, and output handling across all tests. - -> Important: Do NOT add `using Xunit.Abstractions`. xUnit v3 no longer exposes that namespace; including it is incorrect and will cause compilation errors. Use the `Codebelt.Extensions.Xunit` Test base class and `using Xunit;` as shown in the examples below. If you need access to test output, rely on the Test base class (which accepts the appropriate output helper) rather than importing `Xunit.Abstractions`. - -```csharp -using Codebelt.Extensions.Xunit; -using Xunit; - -namespace Your.Namespace -{ - public class YourTestClass : Test - { - public YourTestClass(ITestOutputHelper output) : base(output) - { - } - - // Your tests here - } -} -``` - -## 2. Test Method Attributes - -- Use `[Fact]` for standard unit tests. -- Use `[Theory]` with `[InlineData]` or other data sources for parameterized tests. - -## 3. Naming Conventions - -- **Test classes**: End with `Test` (e.g., `DateSpanTest`). -- **Test methods**: Use descriptive names that state the expected behavior (e.g., `ShouldReturnTrue_WhenConditionIsMet`). - -## 4. Assertions - -- Use `Assert` methods from xUnit for all assertions. -- Prefer explicit and expressive assertions (e.g., `Assert.Equal`, `Assert.NotNull`, `Assert.Contains`). - -## 5. File and Namespace Organization - -- Place test files in the appropriate test project and folder structure. -- Use namespaces that mirror the source code structure. The namespace of a test file MUST match the namespace of the System Under Test (SUT). Do NOT append ".Tests", ".Benchmarks" or similar suffixes to the namespace. Only the assembly/project name should indicate that the file is a test/benchmark (for example: YourProject.Foo.Tests assembly, but namespace YourProject.Foo). - - Example: If the SUT class is declared as: - ```csharp - namespace YourProject.Foo.Bar - { - public class Zoo { /* ... */ } - } - ``` - then the corresponding unit test class must use the exact same namespace: - ```csharp - namespace YourProject.Foo.Bar - { - public class ZooTest : Test { /* ... */ } - } - ``` - - Do NOT use: - ```csharp - namespace YourProject.Foo.Bar.Tests { /* ... */ } // ❌ - namespace YourProject.Foo.Bar.Benchmarks { /* ... */ } // ❌ - ``` - - The unit tests for the YourProject.Foo assembly live in the YourProject.Foo.Tests assembly. - - The functional tests for the YourProject.Foo assembly live in the YourProject.Foo.FunctionalTests assembly. - - Test class names end with Test and live in the same namespace as the class being tested, e.g., the unit tests for the Boo class that resides in the YourProject.Foo assembly would be named BooTest and placed in the YourProject.Foo namespace in the YourProject.Foo.Tests assembly. - - Modify the associated .csproj file to override the root namespace so the compiled namespace matches the SUT. Example: - ```xml - - YourProject.Foo - - ``` -- When generating test scaffolding automatically, resolve the SUT's namespace from the source file (or project/assembly metadata) and use that exact namespace in the test file header. - -- Notes: - - This rule ensures type discovery and XML doc links behave consistently and reduces confusion when reading tests. - - Keep folder structure aligned with the production code layout to make locating SUT <-> test pairs straightforward. - -## 6. Example Test - -```csharp -using System; -using System.Globalization; -using Codebelt.Extensions.Xunit; -using Xunit; - -namespace YourProject -{ - /// - /// Tests for the class. - /// - public class DateSpanTest : Test - { - public DateSpanTest(ITestOutputHelper output) : base(output) - { - } - - [Fact] - public void Parse_ShouldGetOneMonthOfDifference_UsingIso8601String() - { - var start = new DateTime(2021, 3, 5).ToString("O"); - var end = new DateTime(2021, 4, 5).ToString("O"); - - var span = DateSpan.Parse(start, end); - - Assert.Equal("0:01:31:00:00:00.0", span.ToString()); - Assert.Equal(0, span.Years); - Assert.Equal(1, span.Months); - Assert.Equal(31, span.Days); - Assert.Equal(0, span.Hours); - Assert.Equal(0, span.Minutes); - Assert.Equal(0, span.Seconds); - Assert.Equal(0, span.Milliseconds); - - Assert.Equal(0.08493150684931507, span.TotalYears); - Assert.Equal(1, span.TotalMonths); - Assert.Equal(31, span.TotalDays); - Assert.Equal(744, span.TotalHours); - Assert.Equal(44640, span.TotalMinutes); - Assert.Equal(2678400, span.TotalSeconds); - Assert.Equal(2678400000, span.TotalMilliseconds); - - Assert.Equal(6, span.GetWeeks()); - Assert.Equal(-1566296493, span.GetHashCode()); - - TestOutput.WriteLine(span.ToString()); - } - } -} -``` - -## 7. Additional Guidelines - -- Keep tests focused and isolated. -- Do not rely on external systems except for xUnit itself and Codebelt.Extensions.Xunit (and derived from this). -- Ensure tests are deterministic and repeatable. - -## 8. Test Doubles - -- Preferred test doubles include dummies, fakes, stubs and spies if and when the design allows it. -- Under special circumstances, mock can be used (using Moq library). -- Before overriding methods, verify that the method is virtual or abstract; this rule also applies to mocks. -- Never mock IMarshaller; always use a new instance of JsonMarshaller. - -## 9. Avoid `InternalsVisibleTo` in Tests - -- **Do not** use `InternalsVisibleTo` to access internal types or members from test projects. -- Prefer **indirect testing via public APIs** that depend on the internal implementation (public facades, public extension methods, or other public entry points). - -### Preferred Pattern - -**Pattern name:** Public Facade Testing (also referred to as *Public API Proxy Testing*) - -**Description:** -Internal classes and methods must be validated by exercising the public API that consumes them. Tests should assert observable behavior exposed by the public surface rather than targeting internal implementation details directly. - -### Example Mapping - -- **Internal helper:** `DelimitedString` (internal static class) -- **Public API:** `TestOutputHelperExtensions.WriteLines()` (public extension method) -- **Test strategy:** Write tests for `WriteLines()` and verify its public behavior. The internal call to `DelimitedString.Create()` is exercised implicitly. - -### Benefits - -- Avoids exposing internal types to test assemblies. -- Ensures tests reflect real-world usage patterns. -- Maintains strong encapsulation and a clean public API. -- Tests remain resilient to internal refactoring as long as public behavior is preserved. - -### When to Apply - -- Internal logic is fully exercised through existing public APIs. -- Public entry points provide sufficient coverage of internal code paths. -- The internal implementation exists solely as a helper or utility for public-facing functionality. - -## 10. ExcludeFromCodeCoverage Prohibition - -**Do not use `ExcludeFromCodeCoverage` attribute on any code.** This includes: - -- Test classes or test methods -- Production code -- Configuration code -- Any other code path - -### Rationale - -- Excluding code from coverage hides gaps and creates false confidence in test completeness. -- If a code path cannot or should not be tested, refactor the code to eliminate that path rather than hiding it from metrics. -- Every executable line should be covered by tests or be genuinely unreachable (dead code to be removed). - -### Alternative Approaches - -- **Untestable code paths**: Refactor to separate concerns and eliminate the untestable path. -- **External dependencies**: Use test doubles (fakes, stubs, spies) instead of excluding from coverage. -- **Configuration-only code**: Move to configuration files or extract into testable methods. -- **Generated or third-party code**: These should not be in the primary codebase; use NuGet packages or dedicated vendor folders if necessary. - ---- -description: 'Writing Performance Tests' -applyTo: "tuning/**, **/*Benchmark*.cs" ---- - -# Writing Performance Tests -This document provides guidance for writing performance tests (benchmarks) for a project/solution using BenchmarkDotNet. Follow these guidelines to keep benchmarks consistent, readable, and comparable. - -## 1. Naming and Placement - -- Place micro- and component-benchmarks under the `tuning/` folder or in projects named `*.Benchmarks`. -- Place benchmark files in the appropriate benchmark project and folder structure. -- Use namespaces that mirror the source code structure, e.g. do not suffix with `Benchmarks`. -Namespace rule: DO NOT append `.Benchmarks` to the namespace. Benchmarks must live in the same namespace as the production assembly. Example: if the production assembly uses `namespace YourProject.Security.Cryptography`, the benchmark file should also use: - ``` - namespace YourProject.Security.Cryptography - { - public class Sha512256Benchmark { /* ... */ } - } - ``` -The class name must end with `Benchmark`, but the namespace must match the assembly (no `.Benchmarks` suffix). -- The benchmarks for the YourProject.Bar assembly live in the YourProject.Bar.Benchmarks assembly. -- Benchmark class names end with Benchmark and live in the same namespace as the class being measured, e.g., the benchmarks for the Zoo class that resides in the YourProject.Bar assembly would be named ZooBenchmark and placed in the YourProject.Bar namespace in the YourProject.Bar.Benchmarks assembly. -- Modify the associated .csproj file to override the root namespace, e.g., YourProject.Bar. - -## 2. Attributes and Configuration - -- Use `BenchmarkDotNet` attributes to express intent and collect relevant metrics: - - `[MemoryDiagnoser]` to capture memory allocations. - - `[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]` to group related benchmarks. - - `[Params]` for input sizes or variations to exercise multiple scenarios. - - `[GlobalSetup]` for one-time initialization that's not part of measured work. - - `[Benchmark]` on methods representing measured operations; consider `Baseline = true` and `Description` to improve report clarity. -- Keep benchmark configuration minimal and explicit; prefer in-class attributes over large shared configs unless re-used widely. - -## 3. Structure and Best Practices - -- Keep benchmarks focused: each `Benchmark` method should measure a single logical operation. -- Avoid doing expensive setup work inside a measured method; use `[GlobalSetup]`, `[IterationSetup]`, or cached fields instead. -- Use `Params` to cover micro, mid and macro input sizes (for example: small, medium, large) and verify performance trends across them. -- Use small, deterministic data sets and avoid external systems (network, disk, DB). If external systems are necessary, mark them clearly and do not include them in CI benchmark runs by default. -- Capture results that are meaningful: time, allocations, and if needed custom counters. Prefer `MemoryDiagnoser` and descriptive `Description` values. - -## 4. Naming Conventions for Methods - -- Method names should be descriptive and indicate the scenario, e.g., `Parse_Short`, `ComputeHash_Large`. -- When comparing implementations, mark one method with `Baseline = true` and use similar names so reports are easy to read. - -## 5. Example Benchmark - -```csharp -using BenchmarkDotNet.Attributes; -using BenchmarkDotNet.Configs; - -namespace YourProject -{ - [MemoryDiagnoser] - [GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)] - public class SampleOperationBenchmark - { - [Params(8, 256, 4096)] - public int Count { get; set; } - - private byte[] _payload; - - [GlobalSetup] - public void Setup() - { - _payload = new byte[Count]; - // deterministic initialization - } - - [Benchmark(Baseline = true, Description = "Operation - baseline")] - public int Operation_Baseline() => SampleOperation.Process(_payload); - - [Benchmark(Description = "Operation - optimized")] - public int Operation_Optimized() => SampleOperation.ProcessOptimized(_payload); - } -} -``` - -## 6. Reporting and CI - -- Benchmarks are primarily for local and tuning runs; be cautious about running heavy BenchmarkDotNet workloads in CI. Prefer targeted runs or harnesses for CI where appropriate. -- Keep benchmark projects isolated (e.g., `tuning/*.csproj`) so they don't affect package builds or production artifacts. - -## 7. Additional Guidelines - -- Keep benchmarks readable and well-documented; add comments explaining non-obvious choices. -- If a benchmark exposes regressions or optimizations, add a short note in the benchmark file referencing the relevant issue or PR. -- For any shared helpers for benchmarking, prefer small utility classes inside the `tuning` projects rather than cross-cutting changes to production code. - -For further examples, refer to the benchmark files under the `tuning/` folder. - ---- -description: 'Writing XML documentation' -applyTo: "**/*.cs" ---- - -# Writing XML documentation -This document provides instructions for writing XML documentation. - -## 1. Documentation Style - -- Use the same documentation style as found throughout the codebase. -- Add XML doc comments to public and protected classes and methods where appropriate. -- Example: - -```csharp -using System; -using System.Collections.Generic; -using System.IO; -using Cuemon.Collections.Generic; -using Cuemon.Configuration; -using Cuemon.IO; -using Cuemon.Text; - -namespace Cuemon.Security -{ - /// - /// Represents the base class from which all implementations of hash algorithms and checksums should derive. - /// - /// The type of the configured options. - /// - /// - /// - public abstract class Hash : Hash, IConfigurable where TOptions : ConvertibleOptions, new() - { - /// - /// Initializes a new instance of the class. - /// - /// The which may be configured. - protected Hash(Action setup) - { - Options = Patterns.Configure(setup); - } - - /// - /// Gets the configured options of this instance. - /// - /// The configured options of this instance. - public TOptions Options { get; } - - - /// - /// The endian-initializer of this instance. - /// - /// An instance of the configured options. - protected sealed override void EndianInitializer(EndianOptions options) - { - options.ByteOrder = Options.ByteOrder; - } - } - - /// - /// Represents the base class that defines the public facing structure to expose. - /// - /// - public abstract class Hash : IHash - { - /// - /// Initializes a new instance of the class. - /// - protected Hash() - { - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(bool input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(byte input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(char input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(DateTime input) - { - return ComputeHash(Convertible.GetBytes(input)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(DBNull input) - { - return ComputeHash(Convertible.GetBytes(input)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(decimal input) - { - return ComputeHash(Convertible.GetBytes(input)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(double input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(short input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(int input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(long input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(sbyte input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(float input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(ushort input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(uint input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(ulong input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// The which may be configured. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(string input, Action setup = null) - { - return ComputeHash(Convertible.GetBytes(input, setup)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(Enum input) - { - return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(params IConvertible[] input) - { - return ComputeHash(Arguments.ToEnumerableOf(input)); - } - - /// - /// Computes the hash value for the specified sequence of . - /// - /// The sequence of to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(IEnumerable input) - { - return ComputeHash(Convertible.GetBytes(input)); - } - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public abstract HashResult ComputeHash(byte[] input); - - /// - /// Computes the hash value for the specified . - /// - /// The to compute the hash code for. - /// A containing the computed hash code of the specified . - public virtual HashResult ComputeHash(Stream input) - { - return ComputeHash(Patterns.SafeInvoke(() => new MemoryStream(), destination => - { - Decorator.Enclose(input).CopyStream(destination); - return destination; - }).ToArray()); - } - - /// - /// Defines the initializer that must implement. - /// - /// An instance of the configured options. - protected abstract void EndianInitializer(EndianOptions options); - } -} - -namespace Cuemon.Security -{ - /// - /// Configuration options for . - /// - public class FowlerNollVoOptions : ConvertibleOptions - { - /// - /// Initializes a new instance of the class. - /// - /// - /// The following table shows the initial property values for an instance of . - /// - /// - /// Property - /// Initial Value - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - public FowlerNollVoOptions() - { - Algorithm = FowlerNollVoAlgorithm.Fnv1a; - ByteOrder = Endianness.BigEndian; - } - - /// - /// Gets or sets the algorithm of the Fowler-Noll-Vo hash function. - /// - /// The algorithm of the Fowler-Noll-Vo hash function. - public FowlerNollVoAlgorithm Algorithm { get; set; } - } -} -``` diff --git a/AGENTS.md b/AGENTS.md index 387f64d..50153bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Codebelt.Bootstrapper is an open-source family of assemblies (MIT license) that - `test/` — Unit and functional tests (project names end with `Tests` or `FunctionalTests`) - `.nuget/` — Per-package NuGet metadata (icon, README, release notes) - `.docfx/` — DocFX documentation configuration -- `.github/` — CI/CD workflows, contributing guidelines, Copilot instructions +- `.github/` — CI/CD workflows and contributing guidelines ## Test Conventions @@ -43,7 +43,7 @@ Codebelt.Bootstrapper is an open-source family of assemblies (MIT license) that - Use `Microsoft.Testing.Platform` as the test runner (`UseMicrosoftTestingPlatformRunner=true`) - All tests are executable (`OutputType=Exe`) - Test namespaces must match the SUT namespace (System Under Test), without `.Tests` or `.FunctionalTests` suffix -- See `.github/copilot-instructions.md` for detailed test writing guidelines +- See [Writing Unit Tests](#writing-unit-tests) below for detailed test writing guidelines ## Build & CI @@ -58,7 +58,7 @@ Codebelt.Bootstrapper is an open-source family of assemblies (MIT license) that If a `.bot/` folder exists at the root, it contains **confidential, local-only** working material for AI agents — product requirement documents (PRDs), design proposals, agentic loop state, and brainstorming outputs. This folder is gitignored and never committed. -When starting creative or design work (new features, architecture decisions, PRD drafts), use the [brainstorming skill](https://skills.sh/obra/superpowers/brainstorming) and save outputs to `.bot/`. Only move finalized, non-confidential instructions into `AGENTS.md` or `.github/copilot-instructions.md`. +When starting creative or design work (new features, architecture decisions, PRD drafts), use the [brainstorming skill](https://skills.sh/obra/superpowers/brainstorming) and save outputs to `.bot/`. Only move finalized, non-confidential instructions into `AGENTS.md`. ## Git Operations Safeguards @@ -128,3 +128,627 @@ The final DocFX verification must run outside the working tree when possible. Th If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified. + +Scope: Writing Unit Tests applies to `**/*.{cs,csproj}`. + +# Writing Unit Tests +This document provides instructions for writing unit tests for a project/solution. Please follow these guidelines to ensure consistency and maintainability. + +## 1. Base Class + +**Always inherit from the `Test` base class** for all unit test classes. +This ensures consistent setup, teardown, and output handling across all tests. + +> Important: Do NOT add `using Xunit.Abstractions`. xUnit v3 no longer exposes that namespace; including it is incorrect and will cause compilation errors. Use the `Codebelt.Extensions.Xunit` Test base class and `using Xunit;` as shown in the examples below. If you need access to test output, rely on the Test base class (which accepts the appropriate output helper) rather than importing `Xunit.Abstractions`. + +```csharp +using Codebelt.Extensions.Xunit; +using Xunit; + +namespace Your.Namespace +{ + public class YourTestClass : Test + { + public YourTestClass(ITestOutputHelper output) : base(output) + { + } + + // Your tests here + } +} +``` + +## 2. Test Method Attributes + +- Use `[Fact]` for standard unit tests. +- Use `[Theory]` with `[InlineData]` or other data sources for parameterized tests. + +## 3. Naming Conventions + +- **Test classes**: End with `Test` (e.g., `DateSpanTest`). +- **Test methods**: Use descriptive names that state the expected behavior (e.g., `ShouldReturnTrue_WhenConditionIsMet`). + +## 4. Assertions + +- Use `Assert` methods from xUnit for all assertions. +- Prefer explicit and expressive assertions (e.g., `Assert.Equal`, `Assert.NotNull`, `Assert.Contains`). + +## 5. File and Namespace Organization + +- Place test files in the appropriate test project and folder structure. +- Use namespaces that mirror the source code structure. The namespace of a test file MUST match the namespace of the System Under Test (SUT). Do NOT append ".Tests", ".Benchmarks" or similar suffixes to the namespace. Only the assembly/project name should indicate that the file is a test/benchmark (for example: YourProject.Foo.Tests assembly, but namespace YourProject.Foo). + - Example: If the SUT class is declared as: + ```csharp + namespace YourProject.Foo.Bar + { + public class Zoo { /* ... */ } + } + ``` + then the corresponding unit test class must use the exact same namespace: + ```csharp + namespace YourProject.Foo.Bar + { + public class ZooTest : Test { /* ... */ } + } + ``` + - Do NOT use: + ```csharp + namespace YourProject.Foo.Bar.Tests { /* ... */ } // ❌ + namespace YourProject.Foo.Bar.Benchmarks { /* ... */ } // ❌ + ``` + - The unit tests for the YourProject.Foo assembly live in the YourProject.Foo.Tests assembly. + - The functional tests for the YourProject.Foo assembly live in the YourProject.Foo.FunctionalTests assembly. + - Test class names end with Test and live in the same namespace as the class being tested, e.g., the unit tests for the Boo class that resides in the YourProject.Foo assembly would be named BooTest and placed in the YourProject.Foo namespace in the YourProject.Foo.Tests assembly. + - Modify the associated .csproj file to override the root namespace so the compiled namespace matches the SUT. Example: + ```xml + + YourProject.Foo + + ``` +- When generating test scaffolding automatically, resolve the SUT's namespace from the source file (or project/assembly metadata) and use that exact namespace in the test file header. + +- Notes: + - This rule ensures type discovery and XML doc links behave consistently and reduces confusion when reading tests. + - Keep folder structure aligned with the production code layout to make locating SUT <-> test pairs straightforward. + +## 6. Example Test + +```csharp +using System; +using System.Globalization; +using Codebelt.Extensions.Xunit; +using Xunit; + +namespace YourProject +{ + /// + /// Tests for the class. + /// + public class DateSpanTest : Test + { + public DateSpanTest(ITestOutputHelper output) : base(output) + { + } + + [Fact] + public void Parse_ShouldGetOneMonthOfDifference_UsingIso8601String() + { + var start = new DateTime(2021, 3, 5).ToString("O"); + var end = new DateTime(2021, 4, 5).ToString("O"); + + var span = DateSpan.Parse(start, end); + + Assert.Equal("0:01:31:00:00:00.0", span.ToString()); + Assert.Equal(0, span.Years); + Assert.Equal(1, span.Months); + Assert.Equal(31, span.Days); + Assert.Equal(0, span.Hours); + Assert.Equal(0, span.Minutes); + Assert.Equal(0, span.Seconds); + Assert.Equal(0, span.Milliseconds); + + Assert.Equal(0.08493150684931507, span.TotalYears); + Assert.Equal(1, span.TotalMonths); + Assert.Equal(31, span.TotalDays); + Assert.Equal(744, span.TotalHours); + Assert.Equal(44640, span.TotalMinutes); + Assert.Equal(2678400, span.TotalSeconds); + Assert.Equal(2678400000, span.TotalMilliseconds); + + Assert.Equal(6, span.GetWeeks()); + Assert.Equal(-1566296493, span.GetHashCode()); + + TestOutput.WriteLine(span.ToString()); + } + } +} +``` + +## 7. Additional Guidelines + +- Keep tests focused and isolated. +- Do not rely on external systems except for xUnit itself and Codebelt.Extensions.Xunit (and derived from this). +- Ensure tests are deterministic and repeatable. + +## 8. Test Doubles + +- Preferred test doubles include dummies, fakes, stubs and spies if and when the design allows it. +- Under special circumstances, mock can be used (using Moq library). +- Before overriding methods, verify that the method is virtual or abstract; this rule also applies to mocks. +- Never mock IMarshaller; always use a new instance of JsonMarshaller. + +## 9. Avoid `InternalsVisibleTo` in Tests + +- **Do not** use `InternalsVisibleTo` to access internal types or members from test projects. +- Prefer **indirect testing via public APIs** that depend on the internal implementation (public facades, public extension methods, or other public entry points). + +### Preferred Pattern + +**Pattern name:** Public Facade Testing (also referred to as *Public API Proxy Testing*) + +**Description:** +Internal classes and methods must be validated by exercising the public API that consumes them. Tests should assert observable behavior exposed by the public surface rather than targeting internal implementation details directly. + +### Example Mapping + +- **Internal helper:** `DelimitedString` (internal static class) +- **Public API:** `TestOutputHelperExtensions.WriteLines()` (public extension method) +- **Test strategy:** Write tests for `WriteLines()` and verify its public behavior. The internal call to `DelimitedString.Create()` is exercised implicitly. + +### Benefits + +- Avoids exposing internal types to test assemblies. +- Ensures tests reflect real-world usage patterns. +- Maintains strong encapsulation and a clean public API. +- Tests remain resilient to internal refactoring as long as public behavior is preserved. + +### When to Apply + +- Internal logic is fully exercised through existing public APIs. +- Public entry points provide sufficient coverage of internal code paths. +- The internal implementation exists solely as a helper or utility for public-facing functionality. + +## 10. ExcludeFromCodeCoverage Prohibition + +**Do not use `ExcludeFromCodeCoverage` attribute on any code.** This includes: + +- Test classes or test methods +- Production code +- Configuration code +- Any other code path + +### Rationale + +- Excluding code from coverage hides gaps and creates false confidence in test completeness. +- If a code path cannot or should not be tested, refactor the code to eliminate that path rather than hiding it from metrics. +- Every executable line should be covered by tests or be genuinely unreachable (dead code to be removed). + +### Alternative Approaches + +- **Untestable code paths**: Refactor to separate concerns and eliminate the untestable path. +- **External dependencies**: Use test doubles (fakes, stubs, spies) instead of excluding from coverage. +- **Configuration-only code**: Move to configuration files or extract into testable methods. +- **Generated or third-party code**: These should not be in the primary codebase; use NuGet packages or dedicated vendor folders if necessary. + +Scope: Writing Performance Tests applies to `tuning/**` and `**/*Benchmark*.cs`. + +# Writing Performance Tests +This document provides guidance for writing performance tests (benchmarks) for a project/solution using BenchmarkDotNet. Follow these guidelines to keep benchmarks consistent, readable, and comparable. + +## 1. Naming and Placement + +- Place micro- and component-benchmarks under the `tuning/` folder or in projects named `*.Benchmarks`. +- Place benchmark files in the appropriate benchmark project and folder structure. +- Use namespaces that mirror the source code structure, e.g. do not suffix with `Benchmarks`. +Namespace rule: DO NOT append `.Benchmarks` to the namespace. Benchmarks must live in the same namespace as the production assembly. Example: if the production assembly uses `namespace YourProject.Security.Cryptography`, the benchmark file should also use: + ``` + namespace YourProject.Security.Cryptography + { + public class Sha512256Benchmark { /* ... */ } + } + ``` +The class name must end with `Benchmark`, but the namespace must match the assembly (no `.Benchmarks` suffix). +- The benchmarks for the YourProject.Bar assembly live in the YourProject.Bar.Benchmarks assembly. +- Benchmark class names end with Benchmark and live in the same namespace as the class being measured, e.g., the benchmarks for the Zoo class that resides in the YourProject.Bar assembly would be named ZooBenchmark and placed in the YourProject.Bar namespace in the YourProject.Bar.Benchmarks assembly. +- Modify the associated .csproj file to override the root namespace, e.g., YourProject.Bar. + +## 2. Attributes and Configuration + +- Use `BenchmarkDotNet` attributes to express intent and collect relevant metrics: + - `[MemoryDiagnoser]` to capture memory allocations. + - `[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]` to group related benchmarks. + - `[Params]` for input sizes or variations to exercise multiple scenarios. + - `[GlobalSetup]` for one-time initialization that's not part of measured work. + - `[Benchmark]` on methods representing measured operations; consider `Baseline = true` and `Description` to improve report clarity. +- Keep benchmark configuration minimal and explicit; prefer in-class attributes over large shared configs unless re-used widely. + +## 3. Structure and Best Practices + +- Keep benchmarks focused: each `Benchmark` method should measure a single logical operation. +- Avoid doing expensive setup work inside a measured method; use `[GlobalSetup]`, `[IterationSetup]`, or cached fields instead. +- Use `Params` to cover micro, mid and macro input sizes (for example: small, medium, large) and verify performance trends across them. +- Use small, deterministic data sets and avoid external systems (network, disk, DB). If external systems are necessary, mark them clearly and do not include them in CI benchmark runs by default. +- Capture results that are meaningful: time, allocations, and if needed custom counters. Prefer `MemoryDiagnoser` and descriptive `Description` values. + +## 4. Naming Conventions for Methods + +- Method names should be descriptive and indicate the scenario, e.g., `Parse_Short`, `ComputeHash_Large`. +- When comparing implementations, mark one method with `Baseline = true` and use similar names so reports are easy to read. + +## 5. Example Benchmark + +```csharp +using BenchmarkDotNet.Attributes; +using BenchmarkDotNet.Configs; + +namespace YourProject +{ + [MemoryDiagnoser] + [GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)] + public class SampleOperationBenchmark + { + [Params(8, 256, 4096)] + public int Count { get; set; } + + private byte[] _payload; + + [GlobalSetup] + public void Setup() + { + _payload = new byte[Count]; + // deterministic initialization + } + + [Benchmark(Baseline = true, Description = "Operation - baseline")] + public int Operation_Baseline() => SampleOperation.Process(_payload); + + [Benchmark(Description = "Operation - optimized")] + public int Operation_Optimized() => SampleOperation.ProcessOptimized(_payload); + } +} +``` + +## 6. Reporting and CI + +- Benchmarks are primarily for local and tuning runs; be cautious about running heavy BenchmarkDotNet workloads in CI. Prefer targeted runs or harnesses for CI where appropriate. +- Keep benchmark projects isolated (e.g., `tuning/*.csproj`) so they don't affect package builds or production artifacts. + +## 7. Additional Guidelines + +- Keep benchmarks readable and well-documented; add comments explaining non-obvious choices. +- If a benchmark exposes regressions or optimizations, add a short note in the benchmark file referencing the relevant issue or PR. +- For any shared helpers for benchmarking, prefer small utility classes inside the `tuning` projects rather than cross-cutting changes to production code. + +For further examples, refer to the benchmark files under the `tuning/` folder. + +Scope: Writing XML documentation applies to `**/*.cs`. + +# Writing XML documentation +This document provides instructions for writing XML documentation. + +## 1. Documentation Style + +- Use the same documentation style as found throughout the codebase. +- Add XML doc comments to public and protected classes and methods where appropriate. +- Example: + +```csharp +using System; +using System.Collections.Generic; +using System.IO; +using Cuemon.Collections.Generic; +using Cuemon.Configuration; +using Cuemon.IO; +using Cuemon.Text; + +namespace Cuemon.Security +{ + /// + /// Represents the base class from which all implementations of hash algorithms and checksums should derive. + /// + /// The type of the configured options. + /// + /// + /// + public abstract class Hash : Hash, IConfigurable where TOptions : ConvertibleOptions, new() + { + /// + /// Initializes a new instance of the class. + /// + /// The which may be configured. + protected Hash(Action setup) + { + Options = Patterns.Configure(setup); + } + + /// + /// Gets the configured options of this instance. + /// + /// The configured options of this instance. + public TOptions Options { get; } + + + /// + /// The endian-initializer of this instance. + /// + /// An instance of the configured options. + protected sealed override void EndianInitializer(EndianOptions options) + { + options.ByteOrder = Options.ByteOrder; + } + } + + /// + /// Represents the base class that defines the public facing structure to expose. + /// + /// + public abstract class Hash : IHash + { + /// + /// Initializes a new instance of the class. + /// + protected Hash() + { + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(bool input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(byte input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(char input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(DateTime input) + { + return ComputeHash(Convertible.GetBytes(input)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(DBNull input) + { + return ComputeHash(Convertible.GetBytes(input)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(decimal input) + { + return ComputeHash(Convertible.GetBytes(input)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(double input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(short input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(int input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(long input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(sbyte input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(float input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(ushort input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(uint input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(ulong input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// The which may be configured. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(string input, Action setup = null) + { + return ComputeHash(Convertible.GetBytes(input, setup)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(Enum input) + { + return ComputeHash(Convertible.GetBytes(input, EndianInitializer)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(params IConvertible[] input) + { + return ComputeHash(Arguments.ToEnumerableOf(input)); + } + + /// + /// Computes the hash value for the specified sequence of . + /// + /// The sequence of to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(IEnumerable input) + { + return ComputeHash(Convertible.GetBytes(input)); + } + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public abstract HashResult ComputeHash(byte[] input); + + /// + /// Computes the hash value for the specified . + /// + /// The to compute the hash code for. + /// A containing the computed hash code of the specified . + public virtual HashResult ComputeHash(Stream input) + { + return ComputeHash(Patterns.SafeInvoke(() => new MemoryStream(), destination => + { + Decorator.Enclose(input).CopyStream(destination); + return destination; + }).ToArray()); + } + + /// + /// Defines the initializer that must implement. + /// + /// An instance of the configured options. + protected abstract void EndianInitializer(EndianOptions options); + } +} + +namespace Cuemon.Security +{ + /// + /// Configuration options for . + /// + public class FowlerNollVoOptions : ConvertibleOptions + { + /// + /// Initializes a new instance of the class. + /// + /// + /// The following table shows the initial property values for an instance of . + /// + /// + /// Property + /// Initial Value + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + public FowlerNollVoOptions() + { + Algorithm = FowlerNollVoAlgorithm.Fnv1a; + ByteOrder = Endianness.BigEndian; + } + + /// + /// Gets or sets the algorithm of the Fowler-Noll-Vo hash function. + /// + /// The algorithm of the Fowler-Noll-Vo hash function. + public FowlerNollVoAlgorithm Algorithm { get; set; } + } +} +``` From ce8b4c2f154a0792f835af30af7d64dab5b22cff Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:28 +0200 Subject: [PATCH 3/9] =?UTF-8?q?=F0=9F=90=B3=20serve=20docfx=20site=20with?= =?UTF-8?q?=20nginx=20on=20port=208080?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The DocFX image now uses DHI nginx and copies a dedicated nginx configuration. Fingerprinted DocFX assets are cached immutably, while pages and navigation data keep stable URLs without stale validators. --- .docfx/Dockerfile.docfx | 11 +++++------ .docfx/nginx.conf | 31 +++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 6 deletions(-) create mode 100644 .docfx/nginx.conf diff --git a/.docfx/Dockerfile.docfx b/.docfx/Dockerfile.docfx index 7d97dde..e29eda1 100644 --- a/.docfx/Dockerfile.docfx +++ b/.docfx/Dockerfile.docfx @@ -1,17 +1,16 @@ -ARG NGINX_VERSION=1.31-alpine +ARG NGINX_VERSION=1.31-alpine -FROM --platform=$BUILDPLATFORM nginx:${NGINX_VERSION} AS base +FROM --platform=$BUILDPLATFORM dhi.io/nginx:${NGINX_VERSION} AS base RUN rm -rf /usr/share/nginx/html/* -FROM --platform=$BUILDPLATFORM codebeltnet/docfx:2.78.5 AS build +FROM --platform=$BUILDPLATFORM codebeltnet/docfx:2 AS build ADD [".", "docfx"] RUN cd docfx; \ docfx build -FROM nginx:${NGINX_VERSION} AS final +FROM dhi.io/nginx:${NGINX_VERSION} AS final WORKDIR /usr/share/nginx/html COPY --from=build /build/docfx/wwwroot /usr/share/nginx/html - -ENTRYPOINT ["nginx", "-g", "daemon off;"] +COPY nginx.conf /etc/nginx/conf.d/default.conf diff --git a/.docfx/nginx.conf b/.docfx/nginx.conf new file mode 100644 index 0000000..c95d1b1 --- /dev/null +++ b/.docfx/nginx.conf @@ -0,0 +1,31 @@ +server { + listen 8080; + server_name _; + # The ingress terminates TLS; keep redirects from exposing this container port. + absolute_redirect off; + + root /usr/share/nginx/html; + index index.html; + + # DocFX fingerprints these generated dependencies in their filenames. They can be + # cached permanently because changed content is published under a different URL. + location ~ "^/public/.+-[A-Z0-9]{8}(?:-[A-Z0-9]{8})?(?:\.min)?\.(?:(?:css|js)(?:\.map)?|woff2?)$" { + try_files $uri =404; + add_header Cache-Control "public, max-age=31536000, immutable" always; + add_header Vary "Accept-Encoding" always; + } + + # Pages, navigation data, images, and DocFX entry assets keep stable URLs. Do not + # retain them across deployments, and ignore validators cached under an old policy. + location / { + # Nginx derives ETags from modification time and file size. Those values can be + # reused by files copied from different image layers, producing a false 304. + etag off; + if_modified_since off; + try_files $uri $uri/ =404; + add_header Cache-Control "no-store, no-cache, must-revalidate, max-age=0" always; + add_header Expires "0" always; + add_header Pragma "no-cache" always; + add_header Vary "Accept-Encoding" always; + } +} From 680f3728f01bdfcb706f51854a8eb798294ce245 Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:32 +0200 Subject: [PATCH 4/9] =?UTF-8?q?=F0=9F=93=9A=20add=20ms-style=20template=20?= =?UTF-8?q?and=20sitemap=20to=20docfx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit API members now render on separate pages, the Microsoft-style template is included, and a monthly sitemap is generated for the published site. --- .docfx/docfx.json | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.docfx/docfx.json b/.docfx/docfx.json index 3f4e26e..a2a055c 100644 --- a/.docfx/docfx.json +++ b/.docfx/docfx.json @@ -13,6 +13,7 @@ } ], "dest": "api", + "memberLayout": "separatePages", "filter": "filterConfig.yml", "properties": { "TargetFramework": "net10.0" @@ -66,7 +67,8 @@ "fileMetadataFiles": [], "template": [ "default", - "modern" + "modern", + "templates/ms-style" ], "overwrite": [ { @@ -85,6 +87,10 @@ "noLangKeyword": false, "keepFileLink": false, "cleanupCacheHistory": false, - "disableGitFeatures": false + "disableGitFeatures": false, + "sitemap": { + "baseUrl": "https://bootstrapper.codebelt.net/", + "changefreq": "monthly" + } } } From 4307eb97da962c95c7bb87e265cdba41d5e4d145 Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:36 +0200 Subject: [PATCH 5/9] =?UTF-8?q?=F0=9F=91=B7=20derive=20service=20update=20?= =?UTF-8?q?version=20from=20git=20tags?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The service update workflow now reads the latest stable Git tag instead of the changelog heading. It reuses a pending TBD release and updates an existing matching changelog section rather than duplicating it. --- .github/workflows/service-update.yml | 93 ++++++++++++++++++++++++---- 1 file changed, 81 insertions(+), 12 deletions(-) diff --git a/.github/workflows/service-update.yml b/.github/workflows/service-update.yml index f9a235e..1f69586 100644 --- a/.github/workflows/service-update.yml +++ b/.github/workflows/service-update.yml @@ -31,6 +31,7 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 0 + fetch-tags: true - name: Resolve trigger inputs id: trigger @@ -42,13 +43,68 @@ jobs: - name: Determine new version for this repo id: newver + shell: bash run: | - CURRENT=$(grep -oP '(?<=## \[)[\d.]+(?=\])' CHANGELOG.md | head -1) - NEW=$(echo "$CURRENT" | awk -F. '{printf "%s.%s.%d", $1, $2, $3+1}') - BRANCH="v${NEW}/service-update" - echo "current=$CURRENT" >> $GITHUB_OUTPUT - echo "new=$NEW" >> $GITHUB_OUTPUT - echo "branch=$BRANCH" >> $GITHUB_OUTPUT + python3 - <<'PY' + import os + import re + import subprocess + import sys + + tag_pattern = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$") + tags = subprocess.check_output(["git", "tag", "--list"], text=True).splitlines() + stable_tags = [] + for tag in tags: + match = tag_pattern.fullmatch(tag) + if match: + version = tuple(int(part) for part in match.groups()) + stable_tags.append((version, tag)) + + if not stable_tags: + print("::error::No stable vMAJOR.MINOR.PATCH Git tag was found.") + sys.exit(1) + + _, latest_tag = max(stable_tags, key=lambda item: item[0]) + latest_version = latest_tag[1:] + major, minor, patch = (int(part) for part in latest_version.split(".")) + next_version = f"{major}.{minor}.{patch + 1}" + + with open("CHANGELOG.md", encoding="utf-8") as changelog_file: + changelog = changelog_file.read() + + heading = re.search(r"(?m)^## \[(\d+\.\d+\.\d+)\] - ([^\r\n]+)[ \t]*$", changelog) + if not heading: + print("::error::CHANGELOG.md has no versioned heading to compare with Git tags.") + sys.exit(1) + + current_version, current_status = heading.groups() + current_status = current_status.strip() + if current_status.upper() != "TBD" and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", current_status): + print(f"::error::Unsupported CHANGELOG.md version status: {current_status}") + sys.exit(1) + + if current_version == next_version and current_status.upper() == "TBD": + # Reuse an already pending next release, such as [5.0.13] - TBD. + new_version = next_version + elif current_version == latest_version and current_status.upper() != "TBD": + # The changelog is at the latest released tag; start the next patch release. + new_version = next_version + else: + print( + f"::error::CHANGELOG.md starts at {current_version} ({current_status}), " + f"but the latest stable Git tag is {latest_tag}. Expected either " + f"[{latest_version}] with a release date or [{next_version}] - TBD." + ) + sys.exit(1) + + branch = f"v{new_version}/service-update" + print(f"Latest stable Git tag: {latest_tag}") + print(f"Latest CHANGELOG.md version: {current_version} ({current_status})") + print(f"Service update version: {new_version}") + with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output: + output.write(f"current={current_version}\n") + output.write(f"new={new_version}\n") + output.write(f"branch={branch}\n") - name: Generate codebelt-aicia token id: app-token @@ -81,14 +137,27 @@ jobs: from datetime import date new_ver = os.environ['NEW_VERSION'] today = date.today().isoformat() - entry = f"## [{new_ver}] - {today}\n\nThis is a service update that focuses on package dependencies.\n\n" - with open("CHANGELOG.md") as f: + service_note = "This release also includes a service update focused on package dependencies." + with open("CHANGELOG.md", encoding="utf-8") as f: content = f.read() - idx = content.find("## [") - content = (content[:idx] + entry + content[idx:]) if idx != -1 else (content + entry) - with open("CHANGELOG.md", "w") as f: + heading = re.search(r"(?m)^## \[(\d+\.\d+\.\d+)\] - (TBD|\d{4}-\d{2}-\d{2})[ \t]*$", content) + if heading and heading.group(1) == new_ver: + if heading.group(2) == "TBD": + content = content[:heading.start(2)] + today + content[heading.end(2):] + heading = re.search(r"(?m)^## \[(\d+\.\d+\.\d+)\] - \d{4}-\d{2}-\d{2}[ \t]*$", content) + section_end = re.search(r"(?m)^## \[", content[heading.end():]) + end = heading.end() + section_end.start() if section_end else len(content) + if service_note not in content[heading.end():end]: + remainder = content[heading.end():] + content = content[:heading.end()] + "\n\n" + service_note + "\n\n" + remainder.lstrip("\r\n") + print(f"Updated existing CHANGELOG entry for v{new_ver}") + else: + entry = f"## [{new_ver}] - {today}\n\nThis is a service update that focuses on package dependencies.\n\n" + idx = content.find("## [") + content = (content[:idx] + entry + content[idx:]) if idx != -1 else (content + entry) + print(f"Added CHANGELOG entry for v{new_ver}") + with open("CHANGELOG.md", "w", encoding="utf-8") as f: f.write(content) - print(f"CHANGELOG updated for v{new_ver}") EOF env: NEW_VERSION: ${{ steps.newver.outputs.new }} From 3c2eecfeaf064693f3a53827245180f29a70f4eb Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:40 +0200 Subject: [PATCH 6/9] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20upgrade=20test=20packa?= =?UTF-8?q?ges=20and=20switch=20to=20coverlet=20mtp?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shared test projects now use Codebelt.Coverlet.MTP and Microsoft.Testing.Extensions.HangDump instead of the CodeCoverage package. Test SDK, xUnit, and .NET 9 and 10 framework baselines move to their latest stable releases. --- Directory.Build.props | 3 ++- Directory.Packages.props | 33 +++++++++++++++++---------------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/Directory.Build.props b/Directory.Build.props index 07bc162..ceca187 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -81,7 +81,7 @@ - + @@ -91,6 +91,7 @@ + diff --git a/Directory.Packages.props b/Directory.Packages.props index 2248d9c..97631a9 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -3,29 +3,30 @@ true + - - + + - - - + + + - - - - - + + + + + - - - - - + + + + + - \ No newline at end of file + From a033e408c65d9dae523d22e5da613fb9d64060c4 Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:44 +0200 Subject: [PATCH 7/9] =?UTF-8?q?=F0=9F=A9=B9=20correct=20test=20command=20i?= =?UTF-8?q?n=20contributing=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The per-project test loop passes the test project through the --project option so each project runs on its own. --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index bda1b61..ae37602 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -35,7 +35,7 @@ Run tests one project at a time so a failing or hanging project is attributable. ```powershell $testProjects = Get-ChildItem test -Filter *.csproj -Recurse foreach ($project in $testProjects) { - dotnet test $project.FullName --configuration Release --no-restore + dotnet test --project $project.FullName --configuration Release --no-restore } ``` From 494e53c1c79f79470063eb46d02233fd84eb68c2 Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:08:48 +0200 Subject: [PATCH 8/9] =?UTF-8?q?=F0=9F=92=AC=20document=205.2.3=20service?= =?UTF-8?q?=20update=20changes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 5.2.3 changelog entry now lists the dependency, DocFX hosting, and contributor guidance changes that shipped in this service update, and the Unreleased section is folded into the versioned release. --- CHANGELOG.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 190269a..6e19e2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,26 @@ For more details, please refer to `PackageReleaseNotes.txt` on a per assembly ba ## [5.2.3] - 2026-10-18 -This is a service update that focuses on package dependencies. +This patch release updates dependencies, aligns MTP coverage and hang diagnostics with the shared CI workflow, and refreshes documentation hosting and contributor guidance. + +### Added + +- Codebelt.Coverlet.MTP 10.1.0 and Microsoft.Testing.Extensions.HangDump 2.5.1 in the shared test dependencies for OpenCover coverage and hang diagnostics, +- DocFX nginx configuration on port 8080, with immutable caching for fingerprinted assets and disabled caching for stable URLs. + +### Changed + +- Codebelt.Extensions.Swashbuckle.AspNetCore from 10.2.6 to 10.3.0, Codebelt.Extensions.Xunit.App from 12.0.1 to 12.0.2, and Cuemon.Core and Cuemon.Extensions.Hosting from 10.7.1 to 10.8.1, +- Microsoft.NET.Test.Sdk from 18.10.1 to 18.11.0, xunit.v3 and xunit.v3.runner.console from 4.0.1 to 4.0.2, and xunit.runner.visualstudio from 4.0.0 to 4.0.1, +- Microsoft.AspNetCore.OpenApi, Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation, Microsoft.Extensions.Configuration, Microsoft.Extensions.DependencyInjection.Abstractions, and Microsoft.Extensions.Hosting from 9.0.20 to 9.0.21 for net9.0 and from 10.0.12 to 10.0.13 for net10.0, +- DocFX hosting uses DHI nginx images and the codebeltnet/docfx:2 image; API members use separate pages, the Microsoft-style template is included, and the site has a monthly sitemap, +- Detailed test, benchmark, and XML documentation instructions moved from .github/copilot-instructions.md into AGENTS.md with their scopes and examples preserved; active guidance references now point to AGENTS.md, +- Contributor test commands use the MTP --project option, +- Service-update version selection uses the latest stable Git tag, reuses a pending TBD release, and updates an existing matching changelog section. + +### Removed + +- Direct Microsoft.Testing.Extensions.CodeCoverage dependency from the shared MTP test configuration. ## [5.2.2] - 2026-09-15 @@ -25,8 +44,6 @@ This is a patch release focused on test infrastructure modernization, comprehens - coverlet.msbuild and coverlet.collector code coverage tools replaced by integrated Microsoft.Testing.Extensions.CodeCoverage. -## [Unreleased] - ## [5.2.1] - 2026-08-17 This is a patch release focused on repository-wide editorconfig conventions, compatible dependency upgrades, and a consolidated Docker test environment. @@ -315,7 +332,7 @@ Highlighted features included in this release: - WorkerProgram class in the Codebelt.Bootstrapper.Worker namespace that is the base entry point of an application responsible for registering its WorkerStartup partner, - WorkerStartup interface in the Codebelt.Bootstrapper.Worker namespace that provides the base class of a conventional based Startup class for a console application. -[Unreleased]: https://github.com/codebeltnet/bootstrapper/compare/v5.2.2...HEAD +[5.2.3]: https://github.com/codebeltnet/bootstrapper/compare/v5.2.2...v5.2.3 [5.2.2]: https://github.com/codebeltnet/bootstrapper/compare/v5.2.1...v5.2.2 [5.2.1]: https://github.com/codebeltnet/bootstrapper/compare/v5.2.0...v5.2.1 [5.2.0]: https://github.com/codebeltnet/bootstrapper/compare/v5.1.2...v5.2.0 From bf697b9f3857d289e122987276f4d052e35069cc Mon Sep 17 00:00:00 2001 From: aicia-bot Date: Sun, 18 Oct 2026 20:22:07 +0200 Subject: [PATCH 9/9] =?UTF-8?q?=F0=9F=94=A7=20stop=20caching=20missing=20d?= =?UTF-8?q?ocfx=20assets?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Missing fingerprinted DocFX assets were returned with the immutable one-year cache policy, so clients could keep a 404 cached for a year. Route those misses through a no-store error location and keep the immutable policy only for successful responses. --- .docfx/nginx.conf | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.docfx/nginx.conf b/.docfx/nginx.conf index c95d1b1..67c9e06 100644 --- a/.docfx/nginx.conf +++ b/.docfx/nginx.conf @@ -10,11 +10,17 @@ server { # DocFX fingerprints these generated dependencies in their filenames. They can be # cached permanently because changed content is published under a different URL. location ~ "^/public/.+-[A-Z0-9]{8}(?:-[A-Z0-9]{8})?(?:\.min)?\.(?:(?:css|js)(?:\.map)?|woff2?)$" { + error_page 404 = @not_found; try_files $uri =404; - add_header Cache-Control "public, max-age=31536000, immutable" always; + add_header Cache-Control "public, max-age=31536000, immutable"; add_header Vary "Accept-Encoding" always; } + location @not_found { + add_header Cache-Control "no-store" always; + return 404; + } + # Pages, navigation data, images, and DocFX entry assets keep stable URLs. Do not # retain them across deployments, and ignore validators cached under an old policy. location / {