Issue #2: explicit ConfigKeySource precedence contract

Make source precedence a stable, documented API instead of relying on
the undocumented CaseIterable declaration order.

- Add PrioritizedConfigKeySource protocol with `static var priority`
  (defaults to Array(allCases)); ConfigKeySource pins an explicit
  [.commandLine, .environment], decoupling precedence from case order.
- Add overridable `sourcePriority` to ConfigValueReading (defaults to
  ConfigKeySource.priority); resolvedString/Int/Double now iterate it
  instead of allCases.
- Tests: pin priority order + drift guard (priority covers every case),
  and a reversed-sourcePriority override resolving ENV over CLI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: leogdion

Sources/ConfigKeyKit/ConfigKeySource.swift

@@ -35,3 +35,13 @@ public enum ConfigKeySource: CaseIterable, Sendable {
   /// Environment variables (e.g., CLOUDKIT_CONTAINER_ID)
   case environment
 }
+
+extension ConfigKeySource: PrioritizedConfigKeySource {
+  /// Sources in precedence order, highest first: command line overrides
+  /// environment.
+  ///
+  /// This order is part of the public API. `ConfigValueReading` resolution
+  /// consults sources in this sequence, and it is pinned explicitly so it stays
+  /// independent of `case` declaration order.
+  public static let priority: [ConfigKeySource] = [.commandLine, .environment]
+}

Sources/ConfigKeyKit/ConfigValueReading.swift

@@ -55,6 +55,11 @@ public protocol ConfigValueReading {
   /// The reader's native key type (e.g. `Configuration.ConfigKey`).
   associatedtype Key
 
+  /// The sources consulted during resolution, in precedence order, highest
+  /// first. Defaults to ``ConfigKeySource/priority``; override to resolve a
+  /// reader with a different precedence (e.g. environment before command line).
+  var sourcePriority: [ConfigKeySource] { get }
+
   /// Builds a native ``Key`` from a resolved per-source key string.
   func makeConfigKey(_ string: String) -> Key
 
@@ -69,6 +74,10 @@ public protocol ConfigValueReading {
 }
 
 extension ConfigValueReading {
+  /// The sources consulted during resolution, defaulting to
+  /// ``ConfigKeySource/priority`` (command line, then environment).
+  public var sourcePriority: [ConfigKeySource] { ConfigKeySource.priority }
+
   /// Reads a required string value: CLI → ENV → the key's default.
   public func read(_ key: ConfigKey<String>) -> String {
     resolvedString(key) ?? key.defaultValue
@@ -127,7 +136,7 @@ extension ConfigValueReading {
   // MARK: - Source-precedence resolution
 
   private func resolvedString(_ key: any ConfigurationKey) -> String? {
-    for source in ConfigKeySource.allCases {
+    for source in sourcePriority {
       guard let keyString = key.key(for: source) else { continue }
       if let value = string(
         forKey: makeConfigKey(keyString), isSecret: false, fileID: #fileID, line: #line
@@ -139,7 +148,7 @@ extension ConfigValueReading {
   }
 
   private func resolvedInt(_ key: any ConfigurationKey) -> Int? {
-    for source in ConfigKeySource.allCases {
+    for source in sourcePriority {
       guard let keyString = key.key(for: source) else { continue }
       if let value = int(
         forKey: makeConfigKey(keyString), isSecret: false, fileID: #fileID, line: #line
@@ -151,7 +160,7 @@ extension ConfigValueReading {
   }
 
   private func resolvedDouble(_ key: any ConfigurationKey) -> Double? {
-    for source in ConfigKeySource.allCases {
+    for source in sourcePriority {
       guard let keyString = key.key(for: source) else { continue }
       if let value = double(
         forKey: makeConfigKey(keyString), isSecret: false, fileID: #fileID, line: #line

Sources/ConfigKeyKit/PrioritizedConfigKeySource.swift

@@ -0,0 +1,45 @@
+//
+//  PrioritizedConfigKeySource.swift
+//  ConfigKeyKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+/// A `CaseIterable` whose cases carry a precedence order, highest first.
+///
+/// Conformers expose ``priority`` as the authoritative ordering for resolution,
+/// decoupling precedence from the order in which `case`s happen to be declared.
+public protocol PrioritizedConfigKeySource: CaseIterable {
+  /// The cases in precedence order, highest priority first.
+  static var priority: [Self] { get }
+}
+
+extension PrioritizedConfigKeySource {
+  /// Defaults to declaration order (`Array(allCases)`).
+  ///
+  /// Conformers that want precedence to be independent of `case` declaration
+  /// order should override this with an explicit array.
+  public static var priority: [Self] { Array(allCases) }
+}

Tests/ConfigKeyKitTests/ConfigKeySourceTests.swift

@@ -40,4 +40,14 @@ internal struct ConfigKeySourceTests {
     #expect(sources.contains(.commandLine))
     #expect(sources.contains(.environment))
   }
+
+  @Test("Priority order is command line before environment")
+  internal func priorityOrder() {
+    #expect(ConfigKeySource.priority == [.commandLine, .environment])
+  }
+
+  @Test("Priority covers every case")
+  internal func priorityCoversEveryCase() {
+    #expect(Set(ConfigKeySource.priority) == Set(ConfigKeySource.allCases))
+  }
 }

Tests/ConfigKeyKitTests/ConfigValueReadingTests.swift

@@ -56,6 +56,17 @@ internal struct ConfigValueReadingTests {
     #expect(MockConfigValueReader().read(key) == "default-url")
   }
 
+  @Test("sourcePriority override: ENV wins over CLI when reversed")
+  internal func sourcePriorityOverride() throws {
+    let cli = try #require(key.key(for: .commandLine))
+    let env = try #require(key.key(for: .environment))
+    let reader = MockConfigValueReader(
+      strings: [cli: "from-cli", env: "from-env"],
+      sourcePriority: [.environment, .commandLine]
+    )
+    #expect(reader.read(key) == "from-env")
+  }
+
   @Test("Required bool: CLI flag presence is true")
   internal func boolCLIPresence() throws {
     let boolKey = ConfigKey("verbose", envPrefix: "BRIGHTDIGIT", default: false)

Tests/ConfigKeyKitTests/MockConfigValueReader.swift

@@ -36,6 +36,7 @@ internal struct MockConfigValueReader: ConfigValueReading {
   internal var strings: [String: String] = [:]
   internal var ints: [String: Int] = [:]
   internal var doubles: [String: Double] = [:]
+  internal var sourcePriority: [ConfigKeySource] = ConfigKeySource.priority
 
   internal func makeConfigKey(_ string: String) -> String { string }