Add exit-on-failure flag (#43)

* Add --exit-on-failure (-E) flag for CI integration

Adds a new flag that causes xcsift to exit with a non-zero exit code
when the build status is not "success". This is useful for CI pipelines
that need to fail the job when the build fails.

* Test & documentation for exit-on-failure flag

- Add unit tests for exitOnFailure logic
- Add configuration decoding test to verify exit_on_failure parses correctly
- Add documentation for exit-on-failure flag

Author: webcoyote

CLAUDE.md

@@ -56,6 +56,15 @@ xcodebuild build 2>&1 | xcsift -q
 swift build 2>&1 | xcsift --Werror
 xcodebuild build 2>&1 | xcsift -W
 
+# Exit on failure - exit with non-zero code if build does not succeed
+swift build 2>&1 | xcsift --exit-on-failure
+xcodebuild build 2>&1 | xcsift -E
+
+# CI integration - combine --Werror and --exit-on-failure for strict CI builds
+# This fails the build if there are any errors, warnings, or test failures
+xcodebuild build 2>&1 | xcsift --Werror --exit-on-failure
+swift build 2>&1 | xcsift -W -E
+
 # Executable targets - output executable targets generated by the build
 # Parses RegisterWithLaunchServices lines from xcodebuild output
 xcodebuild build 2>&1 | xcsift --executable
@@ -664,6 +673,9 @@ coverage_path = ""       # Custom path to coverage data (empty = auto-detect)
 build_info = false       # Include per-target build phases and timing
 executable = false       # Include executable targets (-e)
 
+# Exit behavior
+exit_on_failure = false  # Exit with failure code if build does not succeed (-E)
+
 # TOON format configuration
 [toon]
 delimiter = "comma"      # "comma", "tab", or "pipe"

Sources/ConfigLoader.swift

@@ -103,6 +103,9 @@ struct ConfigLoader {
             # build_info = false      # Include per-target build phases and timing
             # executable = false      # Include executable targets (-e)
 
+            # Exit behavior
+            # exit_on_failure = false # Exit with failure code if build does not succeed (-E)
+
             # TOON format configuration
             # [toon]
             # delimiter = "comma"     # "comma", "tab", or "pipe"

Sources/ConfigMerger.swift

@@ -15,6 +15,7 @@ struct ResolvedConfig: Sendable {
     let slowThreshold: Double?
     let buildInfo: Bool
     let executable: Bool
+    let exitOnFailure: Bool
     let toonDelimiter: TOONDelimiterType
     let toonKeyFolding: TOONKeyFoldingType
     let toonFlattenDepth: Int?
@@ -39,6 +40,7 @@ enum ConfigMerger {
     ///   - cliSlowThreshold: Slow threshold from CLI (nil if not set)
     ///   - cliBuildInfo: Build info flag from CLI
     ///   - cliExecutable: Executable flag from CLI
+    ///   - cliExitOnFailure: Exit on failure flag from CLI
     ///   - cliToonDelimiter: TOON delimiter from CLI (nil if not explicitly set)
     ///   - cliToonKeyFolding: TOON key folding from CLI (nil if not explicitly set)
     ///   - cliToonFlattenDepth: TOON flatten depth from CLI (nil if not set)
@@ -55,6 +57,7 @@ enum ConfigMerger {
         cliSlowThreshold: Double?,
         cliBuildInfo: Bool,
         cliExecutable: Bool,
+        cliExitOnFailure: Bool,
         cliToonDelimiter: TOONDelimiterType?,
         cliToonKeyFolding: TOONKeyFoldingType?,
         cliToonFlattenDepth: Int?
@@ -82,6 +85,7 @@ enum ConfigMerger {
         let coverageDetails = cliCoverageDetails || (config.coverageDetails ?? false)
         let buildInfo = cliBuildInfo || (config.buildInfo ?? false)
         let executable = cliExecutable || (config.executable ?? false)
+        let exitOnFailure = cliExitOnFailure || (config.exitOnFailure ?? false)
 
         // Optional string/numeric values: CLI > config > nil
         let coveragePath = cliCoveragePath ?? nonEmptyString(config.coveragePath)
@@ -126,6 +130,7 @@ enum ConfigMerger {
             slowThreshold: slowThreshold,
             buildInfo: buildInfo,
             executable: executable,
+            exitOnFailure: exitOnFailure,
             toonDelimiter: toonDelimiter,
             toonKeyFolding: toonKeyFolding,
             toonFlattenDepth: toonFlattenDepth

Sources/Configuration.swift

@@ -16,6 +16,7 @@ struct Configuration: Codable, Sendable {
     var coveragePath: String?
     var buildInfo: Bool?
     var executable: Bool?
+    var exitOnFailure: Bool?
     var toon: TOONConfiguration?
 
     enum CodingKeys: String, CodingKey {
@@ -29,6 +30,7 @@ struct Configuration: Codable, Sendable {
         case coveragePath = "coverage_path"
         case buildInfo = "build_info"
         case executable
+        case exitOnFailure = "exit_on_failure"
         case toon
     }
 

Sources/main.swift

@@ -157,6 +157,12 @@ struct XCSift: ParsableCommand {
     @Flag(name: .long, help: "Include per-target build phases and timing")
     var buildInfo: Bool = false
 
+    @Flag(
+        name: [.customShort("E"), .customLong("exit-on-failure")],
+        help: "Exit with failure code if build does not succeed"
+    )
+    var exitOnFailure: Bool = false
+
     @Option(
         name: [.customShort("f"), .long],
         help: "Output format (json, toon, or github-actions). Default: json. On CI, annotations are auto-appended."
@@ -224,6 +230,7 @@ struct XCSift: ParsableCommand {
             cliSlowThreshold: slowThreshold,
             cliBuildInfo: buildInfo,
             cliExecutable: executable,
+            cliExitOnFailure: exitOnFailure,
             cliToonDelimiter: toonDelimiter,
             cliToonKeyFolding: toonKeyFolding,
             cliToonFlattenDepth: toonFlattenDepth
@@ -272,6 +279,11 @@ struct XCSift: ParsableCommand {
             printExecutables: resolved.executable
         )
         outputResult(result, resolved: resolved)
+
+        // Exit with failure if requested and build did not succeed
+        if resolved.exitOnFailure && result.status != "success" {
+            throw ExitCode.failure
+        }
     }
 
     private func generateConfigFile() throws {

Sources/xcsift.docc/Configuration.md

@@ -64,6 +64,9 @@ coverage_path = ""       # Custom path to coverage data (empty = auto-detect)
 build_info = false       # Include per-target build phases and timing
 executable = false       # Include executable targets (-e)
 
+# Exit behavior
+exit_on_failure = false  # Exit with failure code if build does not succeed (-E)
+
 # TOON format configuration
 [toon]
 delimiter = "comma"      # "comma", "tab", or "pipe"
@@ -113,6 +116,12 @@ flatten_depth = 0        # 0 = unlimited, or positive integer
 | `build_info` | bool | `false` | Include per-target build phases and timing |
 | `executable` | bool | `false` | Include executable targets |
 
+### Exit Behavior
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `exit_on_failure` | bool | `false` | Exit with failure code if build does not succeed |
+
 ### TOON Configuration
 
 Options in the `[toon]` section:
@@ -211,12 +220,15 @@ For CI, you might want different settings:
 # .xcsift.toml for CI
 format = "json"
 warnings = true
-werror = true           # Fail on warnings
+werror = true            # Fail on warnings
+exit_on_failure = true   # Return non-zero exit code on failure
 coverage = true
 coverage_details = true
 build_info = true
 ```
 
+**Tip:** Combining `werror = true` and `exit_on_failure = true` ensures your CI pipeline fails on any errors, warnings, or test failures. This is useful for enforcing code quality standards.
+
 ## Topics
 
 ### Related

Sources/xcsift.docc/Usage.md

@@ -71,6 +71,29 @@ xcodebuild build 2>&1 | xcsift --quiet
 swift build 2>&1 | xcsift -q
 ```
 
+## Exit Behavior
+
+### `--exit-on-failure`, `-E`
+
+Exit with non-zero code if build does not succeed. Useful for CI pipelines where you want the build step to fail based on xcsift's analysis.
+
+```bash
+# Exit with failure if build fails
+xcodebuild build 2>&1 | xcsift --exit-on-failure
+swift build 2>&1 | xcsift -E
+
+# CI integration: combine with --Werror for strict builds
+# Fails if there are any errors, warnings, or test failures
+xcodebuild build 2>&1 | xcsift --Werror --exit-on-failure
+swift build 2>&1 | xcsift -W -E
+```
+
+Build is considered failed when:
+- Compiler errors are present
+- Linker errors are present
+- Test failures are present
+- Warnings are present (when `--Werror` is also used)
+
 ## Test Analysis Options
 
 ### `--slow-threshold`
@@ -269,10 +292,16 @@ xcodebuild build 2>&1 | xcsift -e -w -f toon
 
 # Full build analysis
 xcodebuild build 2>&1 | xcsift -f toon -e -w --build-info
+
+# CI integration: strict builds that fail on any issues
+xcodebuild build 2>&1 | xcsift --Werror --exit-on-failure
+swift test 2>&1 | xcsift -W -E -f toon
 ```
 
 ## Exit Codes
 
-- `0` — Build succeeded
-- `1` — Build failed (errors, linker errors, or test failures)
-- `1` — Build has warnings (when `--Werror` is used)
+- `0` — Build succeeded (or xcsift completed normally without `--exit-on-failure`)
+- `1` — Build failed (errors, linker errors, or test failures) when `--exit-on-failure` is used
+- `1` — Build has warnings when both `--Werror` and `--exit-on-failure` are used
+
+**Note:** Without `--exit-on-failure`, xcsift always exits with `0` regardless of build status. The exit code reflects xcsift's own execution, not the build result. Use `--exit-on-failure` (`-E`) when you want xcsift's exit code to reflect the build status for CI integration.