Add validation to ensure that settings.configs values are dictionaries, in order to prevent misuse

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Next Version
 
+### Fixed
+- Added validation to ensure that all values in `settings.configs` are mappings. Previously, passing non-mapping values did not raise an error, making it difficult to detect misconfigurations. Now, `SpecParsingError.invalidConfigsMappingFormat` is thrown if misused. #1547 @Ryu0118
+
 ## 2.43.0
 
 ### Added

Sources/ProjectSpec/Project.swift

@@ -173,7 +173,17 @@ extension Project {
         let jsonDictionary = Project.resolveProject(jsonDictionary: jsonDictionary)
 
         name = try jsonDictionary.json(atKeyPath: "name")
-        settings = jsonDictionary.json(atKeyPath: "settings") ?? .empty
+
+        do {
+            settings = try jsonDictionary.json(atKeyPath: "settings")
+        } catch let specParsingError as SpecParsingError {
+            // Re-throw `SpecParsingError` to prevent the misuse of settings.configs.
+            throw specParsingError
+        } catch {
+            // Ignore all errors except `SpecParsingError`
+            settings = .empty
+        }
+
         settingGroups = jsonDictionary.json(atKeyPath: "settingGroups")
             ?? jsonDictionary.json(atKeyPath: "settingPresets") ?? [:]
         let configs: [String: String] = jsonDictionary.json(atKeyPath: "configs") ?? [:]

Sources/ProjectSpec/Settings.swift

@@ -28,14 +28,35 @@ public struct Settings: Equatable, JSONObjectConvertible, CustomStringConvertibl
             groups = jsonDictionary.json(atKeyPath: "groups") ?? jsonDictionary.json(atKeyPath: "presets") ?? []
             let buildSettingsDictionary: JSONDictionary = jsonDictionary.json(atKeyPath: "base") ?? [:]
             buildSettings = buildSettingsDictionary
-            configSettings = jsonDictionary.json(atKeyPath: "configs") ?? [:]
+
+            self.configSettings = try Self.extractValidConfigs(from: jsonDictionary)
         } else {
             buildSettings = jsonDictionary
             configSettings = [:]
             groups = []
         }
     }
 
+    /// Extracts and validates the `configs` mapping from the given JSON dictionary.
+    /// - Parameter jsonDictionary: The JSON dictionary to extract `configs` from.
+    /// - Returns: A dictionary mapping configuration names to `Settings` objects.
+    private static func extractValidConfigs(from jsonDictionary: JSONDictionary) throws -> [String: Settings] {
+        guard let configSettings = jsonDictionary["configs"] as? JSONDictionary else {
+            return [:]
+        }
+
+        let invalidConfigKeys = Set(
+            configSettings.filter { !($0.value is JSONDictionary) }
+                .map(\.key)
+        )
+
+        guard invalidConfigKeys.isEmpty else {
+            throw SpecParsingError.invalidConfigsMappingFormat(keys: invalidConfigKeys)
+        }
+
+        return try jsonDictionary.json(atKeyPath: "configs")
+    }
+
     public static func == (lhs: Settings, rhs: Settings) -> Bool {
         NSDictionary(dictionary: lhs.buildSettings).isEqual(to: rhs.buildSettings) &&
             lhs.configSettings == rhs.configSettings &&

Sources/ProjectSpec/SpecParsingError.swift

@@ -15,6 +15,7 @@ public enum SpecParsingError: Error, CustomStringConvertible {
     case unknownBreakpointActionType(String)
     case unknownBreakpointActionConveyanceType(String)
     case unknownBreakpointActionSoundName(String)
+    case invalidConfigsMappingFormat(keys: Set<String>)
 
     public var description: String {
         switch self {
@@ -46,6 +47,8 @@ public enum SpecParsingError: Error, CustomStringConvertible {
             return "Unknown Breakpoint Action conveyance type: \(type)"
         case let .unknownBreakpointActionSoundName(name):
             return "Unknown Breakpoint Action sound name: \(name)"
+        case let .invalidConfigsMappingFormat(keys):
+            return "Invalid format: The value for \"\(keys.sorted().joined(separator: ", "))\" in `configs` must be mapping format"
         }
     }
 }

Tests/Fixtures/invalid_configs_value_non_mapping.yml

@@ -0,0 +1,11 @@
+name: InvalidConfigsValueNonMapping
+
+# This fixture is used to test the validation that ensures all values under `settings.configs`
+# are mappings. `invalid_key0` and `invalid_key1` are not mapping,
+# which should cause a SpecParsingError.invalidConfigsMappingFormat to be thrown.
+settings:
+  configs:
+    invalid_key0: value0
+    debug:
+      valid_key: value1
+    invalid_key1: value2

Tests/ProjectSpecTests/InvalidConfigsFormatTests.swift

@@ -0,0 +1,18 @@
+import ProjectSpec
+import Testing
+import TestSupport
+import PathKit
+
+struct invalidConfigsMappingFormatTests {
+    @Test("throws invalidConfigsMappingFormat error for non-dictionary configs entries")
+    func testNonDictionaryConfigsEntries() throws {
+        let path = fixturePath + "invalid_configs_value_non_mapping.yml"
+        let expectedError = SpecParsingError.invalidConfigsMappingFormat(keys: ["invalid_key0", "invalid_key1"])
+
+        #expect {
+            try Project(path: path)
+        } throws: { actualError in
+            (actualError as any CustomStringConvertible).description == expectedError.description
+        }
+    }
+}