Tweaks and fixes throughout the project (#27)

This PR contains the work done to do a little bit of housekeeping pass across all packages and the Website service.

To provide further details about the work:
* Refreshed the READMEs and source documentation to match the current code;
* Tagged every test case consistently across the Infrastructure, Localization, Persistence, and Website test targets;
* Removed Website middleware tests now covered by Infrastructure's own suite;
* Conformed the `PrepareDB` method to Sendable;
* Relaxes the production Compose DATABASE_TLS default from require to prefer;
* Added Persistence test verifying the prefer posture falls back to plaintext connections.

Reviewed-on: rock-n-code/loud-amsterdam#27
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift

@@ -2,22 +2,19 @@ import Foundation
 
 /// A backend that resolves localized strings for an explicit locale and reports the languages it serves.
 ///
-/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored
-/// and resolved. The shipping implementation, ``StringCatalog``, reads a raw `.xcstrings` catalog so it
-/// behaves identically on Darwin and Linux. A future backend — for example one built on
-/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform
-/// without changing any caller.
+/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored and resolved. The shipping implementation,
+/// ``StringCatalog``, reads a raw `.xcstrings` catalog so it behaves identically on Darwin and Linux. A future backend — for example one built on
+/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform without changing any caller.
 ///
-/// Resolution never fails: an implementation returns the key itself when it has no localization for it,
-/// mirroring Foundation's `String(localized:)`. This is the contract both a dictionary lookup and the
-/// native API can honour, since the native API cannot distinguish a missing key from a translation that
+/// Resolution never fails: an implementation returns the key itself when it has no localization for it, mirroring Foundation's `String(localized:)`.
+/// This is the contract both a dictionary lookup and the native API can honour, since the native API cannot distinguish a missing key from a translation that
 /// happens to equal the key.
 protocol CatalogResolving: Sendable {
 
     // MARK: Properties
 
-    /// The source (development) language, used as the final fallback when a locale has no localization
-    /// and as the default language a ``LanguageList`` serves.
+    /// The source (development) language, used as the final fallback when a locale has no localization and as the default language a ``LanguageList``
+    /// serves.
     var sourceLanguage: String { get }
 
     /// The outcome of reading the backing catalog, for consumers to surface at startup.

Packages/Localization/Sources/Internal/Types/LanguageRange.swift

@@ -1,8 +1,7 @@
 /// A single language range parsed from an `Accept-Language` header entry.
 ///
-/// A range pairs the language tag a client asked for with the `q` weight expressing how much the
-/// client prefers it, as RFC 9110 defines them. ``Negotiate`` parses each comma-separated header
-/// entry into one of these, then orders the ranges by descending weight so the most preferred tag
+/// A range pairs the language tag a client asked for with the `q` weight expressing how much the client prefers it, as RFC 9110 defines them.
+/// ``Negotiate`` parses each comma-separated header entry into one of these, then orders the ranges by descending weight so the most preferred tag
 /// is matched first.
 struct LanguageRange {
 
@@ -11,8 +10,7 @@ struct LanguageRange {
     /// The language tag the client asked for, such as `de` or `de-AT`, or the `*` wildcard.
     let tag: String
 
-    /// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when
-    /// an entry names no weight).
+    /// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when an entry names no weight).
     let quality: Double
 
 }

Packages/Localization/Sources/Internal/Types/StringCatalog.swift

@@ -95,8 +95,8 @@ extension StringCatalog {
 
     /// Returns the catalog for the given bundle and table, decoding it on first access.
     ///
-    /// Catalogs are immutable at runtime, so every ``Localize``, ``Negotiate``, and ``LanguageList``
-    /// bound to the same bundle shares one decoded catalog instead of re-reading its JSON.
+    /// Catalogs are immutable at runtime, so every ``Localize``, ``Negotiate``, and ``LanguageList`` bound to the same bundle shares one
+    /// decoded catalog instead of re-reading its JSON.
     /// - Parameters:
     ///   - bundle: the bundle whose resources contain the String Catalog.
     ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
@@ -132,9 +132,8 @@ extension StringCatalog {
 
 extension StringCatalog: CatalogResolving {
 
-    /// Resolves a key by the most specific language tag first: the locale's full tag (`pt-BR`), then its
-    /// primary language code (`pt`), then the source language, then the key itself. Tags are matched
-    /// case-insensitively, so a regional catalog entry resolves for the locale ``Negotiate`` picked it for.
+    /// Resolves a key by the most specific language tag first: the locale's full tag (`pt-BR`), then its primary language code (`pt`), then the source
+    /// language, then the key itself. Tags are matched case-insensitively, so a regional catalog entry resolves for the locale ``Negotiate`` picked it for.
     func string(
         for key: String,
         in locale: Locale
@@ -162,8 +161,8 @@ private extension Locale {
 
     /// The language tags to resolve a catalog entry against, most specific first.
     ///
-    /// The locale's full identifier comes first, as a hyphenated, lowercased tag (`pt_BR` becomes
-    /// `pt-br`), followed by its primary language code when the two differ.
+    /// The locale's full identifier comes first, as a hyphenated, lowercased tag (`pt_BR` becomes `pt-br`), followed by its primary language code when
+    /// the two differ.
     var catalogTags: [String] {
         var tags: [String] = []
         let identifier = identifier

Packages/Localization/Sources/Public/Enumerations/CatalogState.swift

@@ -1,17 +1,12 @@
 /// The outcome of reading a String Catalog from its bundle.
 ///
-/// The package degrades gracefully when a catalog cannot be read — lookups return their keys and the
-/// language list falls back to the default language — so nothing fails at the call site. This state is
-/// the signal a server checks once at startup to warn before visitors ever see raw localization keys.
+/// The package degrades gracefully when a catalog cannot be read — lookups return their keys and the language list falls back to the default language — so
+/// nothing fails at the call site. This state is the signal a server checks once at startup to warn before visitors ever see raw localization keys.
 public enum CatalogState: Equatable, Sendable {
-
     /// The catalog was found and decoded; its entries are resolvable.
     case loaded
-
     /// No catalog resource exists in the bundle; every lookup returns its key.
     case missing
-
     /// The catalog resource exists but is not valid `.xcstrings` JSON; every lookup returns its key.
     case undecodable
-
 }

Packages/Localization/Sources/Public/Methods/Localize.swift

@@ -2,9 +2,8 @@ import Foundation
 
 /// A reusable, bundle-bound localizer that resolves String Catalog entries for an explicit locale.
 ///
-/// A server has no single "current" locale, so each lookup must name the locale to use. An instance
-/// is bound to the bundle whose catalog holds the strings, then invoked like a function to resolve a
-/// key in a chosen locale.
+/// A server has no single "current" locale, so each lookup must name the locale to use. An instance is bound to the bundle whose catalog holds the strings,
+/// then invoked like a function to resolve a key in a chosen locale.
 public struct Localize: Sendable {
 
     // MARK: Properties
@@ -16,8 +15,7 @@ public struct Localize: Sendable {
 
     /// The outcome of reading the bundle's String Catalog.
     ///
-    /// Resolution degrades to returning raw keys rather than failing, so check this once at startup
-    /// and warn when it is not ``CatalogState/loaded``.
+    /// Resolution degrades to returning raw keys rather than failing, so check this once at startup and warn when it is not ``CatalogState/loaded``.
     public var catalogState: CatalogState {
         resolver.state
     }
@@ -56,8 +54,8 @@ public struct Localize: Sendable {
     /// - Parameters:
     ///   - key: the String Catalog key to look up.
     ///   - locale: the locale to resolve the key in.
-    /// - Returns: the localized string for the locale, the source-language string when the locale has no
-    ///   entry, or the key itself when the catalog has no entry for it.
+    /// - Returns: the localized string for the locale, the source-language string when the locale has no entry, or the key itself when the catalog has no
+    ///   entry for it.
     public func callAsFunction(
         _ key: String,
         locale: Locale

Packages/Localization/Sources/Public/Methods/Negotiate.swift

@@ -2,10 +2,9 @@ import Foundation
 
 /// Negotiates the best supported language for a request from its `Accept-Language` header.
 ///
-/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a
-/// function — through ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a
-/// supported language identifier, honouring the header's `q` weights as RFC 9110 prescribes and
-/// falling back to the default language.
+/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a function — through
+/// ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a supported language identifier, honouring the header's `q` weights as
+/// RFC 9110 prescribes and falling back to the default language.
 public struct Negotiate: Sendable {
 
     // MARK: Properties
@@ -28,12 +27,10 @@ public struct Negotiate: Sendable {
     /// Picks the best supported language for the given `Accept-Language` header value.
     ///
     /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
-    /// The header is parsed into its language ranges, which are ordered by descending `q` weight as
-    /// RFC 9110 prescribes: an entry without a weight counts as 1, entries weighted 0 are
-    /// "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched
-    /// against the supported languages in turn — first by an exact match, then by its primary language
-    /// subtag, so `de-AT` resolves to a supported `de` — while the `*` wildcard accepts the default
-    /// language. When the header is absent or matches nothing, the default language is returned.
+    /// The header is parsed into its language ranges, which are ordered by descending `q` weight as RFC 9110 prescribes: an entry without a weight
+    /// counts as 1, entries weighted 0 are "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched against the
+    /// supported languages in turn — first by an exact match, then by its primary language subtag, so `de-AT` resolves to a supported `de` — while the
+    /// `*` wildcard accepts the default language. When the header is absent or matches nothing, the default language is returned.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
     /// - Returns: the identifier of the supported language to serve.
     public func callAsFunction(
@@ -74,9 +71,8 @@ private extension Negotiate {
 
     /// Parses an `Accept-Language` header value into its ``LanguageRange`` list, ordered by preference.
     ///
-    /// Each comma-separated entry yields its language tag and `q` weight. The ranges are sorted by
-    /// descending weight, entries weighted 0 are dropped as "not acceptable", and equally weighted
-    /// entries keep the header order.
+    /// Each comma-separated entry yields its language tag and `q` weight. The ranges are sorted by descending weight, entries weighted 0 are dropped
+    /// as "not acceptable", and equally weighted entries keep the header order.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value.
     /// - Returns: the language ranges, most preferred first.
     func ranges(
@@ -98,8 +94,7 @@ private extension Negotiate {
     /// Parses a single `Accept-Language` header entry into its ``LanguageRange``.
     ///
     /// The entry's language tag precedes the first `;`; a `q` parameter after it sets the weight.
-    /// A missing or malformed weight counts as 1, the highest preference, matching a tag sent
-    /// without one.
+    /// A missing or malformed weight counts as 1, the highest preference, matching a tag sent without one.
     /// - Parameter entry: a single comma-separated header entry.
     /// - Returns: the entry's language range, or `nil` when it has no language tag.
     func range(
@@ -139,8 +134,8 @@ private extension Negotiate {
 
     /// Finds the supported language that best matches a single `Accept-Language` tag.
     ///
-    /// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the
-    /// supported languages' primary subtags, so a regional tag such as `de-AT` resolves to `de`.
+    /// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the supported languages' primary subtags, so a
+    /// regional tag such as `de-AT` resolves to `de`.
     /// - Parameters:
     ///   - tag: a single language tag from the header.
     ///   - supported: the supported language identifiers.

Packages/Localization/Sources/Public/Types/LanguageList.swift

@@ -35,16 +35,14 @@ public struct LanguageList: Sendable {
 
     /// The outcome of reading the bundle's String Catalog.
     ///
-    /// The list degrades to the default language rather than failing, so check this once at startup
-    /// and warn when it is not ``CatalogState/loaded``.
+    /// The list degrades to the default language rather than failing, so check this once at startup and warn when it is not ``CatalogState/loaded``.
     public var catalogState: CatalogState {
         resolver.state
     }
 
     /// The language served when none of the supported languages match a request.
     ///
-    /// Always the catalog's source (development) language, so the default cannot drift from the
-    /// bundle the list is bound to.
+    /// Always the catalog's source (development) language, so the default cannot drift from the bundle the list is bound to.
     public var `default`: String {
         resolver.sourceLanguage
     }