Merge pull request #1 from diogot/feature/phase1-implementation

Implement Phase 1: XCResult parser library

Author: diogot

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Tests
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: macos-26
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check Swift version
+        run: swift --version
+
+      - name: Build
+        run: swift build
+
+      - name: Run Tests
+        run: swift test

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - Unreleased
+
+### Added
+
+- Initial release
+- `XCResultParser` for parsing xcresult bundles
+- Build results parsing (warnings, errors, analyzer warnings)
+- Test results parsing with failure extraction
+- Source location parsing from both build issues and test failures
+- Resilient enum decoding for forward compatibility with future Xcode versions
+- Comprehensive test suite with fixtures

CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Swift library for parsing Xcode `.xcresult` bundles. Extracts build warnings/errors and test failures in a structured, type-safe format. Zero external dependencies (uses only `xcrun xcresulttool` from Xcode).
+
+**Requirements:** Swift 6.2+, macOS 15+, Xcode 16+
+
+**Status:** Phase 1 implemented. Design document at `swift-xcresult-parser-plan.md`.
+
+## Build & Test Commands
+
+```bash
+swift build           # Build the package
+swift test            # Run unit tests
+swift test --filter IntegrationTests  # Integration tests (CI only)
+```
+
+## Architecture
+
+Three-layer design:
+
+1. **XCResultParser** (public API) - Main entry point for parsing xcresult bundles
+2. **XCResultTool** (internal actor) - Wraps `xcrun xcresulttool` commands
+3. **Models** - Strongly-typed Swift structs/enums with resilient decoding
+
+Data flow:
+```
+XCResultParser.parse(path:)
+    → XCResultTool (executes xcrun xcresulttool get build-results/test-results)
+    → JSON decoding into models
+    → XCResult (unified container)
+```
+
+## Key Design Principles
+
+- All types are `Sendable` for concurrency safety
+- Resilient enum decoding: unknown values captured as `.unknown(String)` for forward compatibility with future Xcode versions
+- Source location normalization from two xcresulttool formats:
+  - Build issues: `file:///path/File.swift#LineNumber`
+  - Test failures: parsed from failure message (`File.swift:42: message`)
+- Zero external dependencies (Foundation only)
+
+## Main Types
+
+| Type | Purpose |
+|------|---------|
+| `XCResult` | Combined build + test results container |
+| `BuildResults` / `BuildIssue` | Build warnings, errors, analyzer warnings |
+| `TestResults` / `TestNode` / `TestFailure` | Test execution tree and flattened failures |
+| `SourceLocation` | Normalized file location with path relativization |
+| `TestResult`, `TestNodeType`, `Severity` | Enums with resilient decoding |
+
+## Testing Strategy
+
+- Unit tests with mock JSON fixtures in `Tests/XCResultParserTests/Fixtures/`
+- Integration tests with real xcresult bundles (CI environment only)
+- Resilient decoding tests for unknown enum values and schema drift

Package.swift

@@ -0,0 +1,18 @@
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-xcresult-parser",
+    platforms: [.macOS(.v15)],
+    products: [
+        .library(name: "XCResultParser", targets: ["XCResultParser"])
+    ],
+    targets: [
+        .target(name: "XCResultParser"),
+        .testTarget(
+            name: "XCResultParserTests",
+            dependencies: ["XCResultParser"],
+            resources: [.copy("Fixtures")]
+        )
+    ]
+)

README.md

@@ -1 +1,135 @@
-# swift-xcresult-parser
+# swift-xcresult-parser
+
+A type-safe Swift library for parsing Xcode `.xcresult` bundles and extracting build warnings, errors, and test failures in a structured format.
+
+[![Swift](https://img.shields.io/badge/Swift-6.2+-orange.svg)](https://swift.org)
+[![Platform](https://img.shields.io/badge/Platform-macOS%2015+-blue.svg)](https://developer.apple.com/macos)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Features
+
+- **Parse xcresult bundles**: Extract structured data from Xcode result bundles
+- **Zero external dependencies**: Uses only `xcrun xcresulttool` (ships with Xcode)
+- **Type-safe output**: Strongly-typed Swift models with resilient decoding
+- **Async/await support**: Modern Swift concurrency
+- **Forward compatible**: Handles unknown enum values gracefully for future Xcode versions
+
+## Requirements
+
+- Swift 6.2+
+- macOS 15+
+- Xcode 16+
+
+## Installation
+
+### Swift Package Manager
+
+Add the following to your `Package.swift`:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/diogot/swift-xcresult-parser.git", from: "1.0.0")
+]
+```
+
+Then add `XCResultParser` to your target dependencies:
+
+```swift
+.target(name: "YourTarget", dependencies: ["XCResultParser"])
+```
+
+## Usage
+
+### Basic Usage
+
+```swift
+import XCResultParser
+
+let parser = XCResultParser(path: "path/to/test.xcresult")
+let result = try await parser.parse()
+
+// Access build issues
+for issue in result.buildResults?.allIssues ?? [] {
+    print("\(issue.severity): \(issue.message)")
+    if let loc = issue.sourceLocation {
+        print("  at \(loc.file):\(loc.line)")
+    }
+}
+
+// Access test failures
+for failure in result.testResults?.failures ?? [] {
+    print("FAIL: \(failure.testClass).\(failure.testName)")
+    print("  \(failure.message)")
+}
+```
+
+### Parse Only Build Results
+
+```swift
+let parser = XCResultParser(path: "path/to/test.xcresult")
+let buildResults = try await parser.parseBuildResults()
+
+print("Warnings: \(buildResults.warningCount)")
+print("Errors: \(buildResults.errorCount)")
+```
+
+### Parse Only Test Results
+
+```swift
+let parser = XCResultParser(path: "path/to/test.xcresult")
+let testResults = try await parser.parseTestResults()
+
+let summary = testResults.summary
+print("Total: \(summary.totalCount)")
+print("Passed: \(summary.passedCount)")
+print("Failed: \(summary.failedCount)")
+```
+
+### Source Location Handling
+
+The library normalizes source locations from two different xcresulttool formats:
+
+```swift
+// Build issues provide absolute paths
+if let location = buildIssue.sourceLocation {
+    let relativePath = location.relativePath(from: "/path/to/repo")
+    print("\(relativePath):\(location.line)")
+}
+
+// Test failures provide filename and line
+for failure in testResults.failures {
+    if let location = failure.sourceLocation {
+        print("\(location.file):\(location.line)")
+    }
+}
+```
+
+## API Reference
+
+### XCResultParser
+
+```swift
+public final class XCResultParser: Sendable {
+    public init(path: String)
+    public func parse() async throws -> XCResult
+    public func parseBuildResults() async throws -> BuildResults
+    public func parseTestResults() async throws -> TestResults
+}
+```
+
+### Models
+
+- `XCResult` - Combined build and test results
+- `BuildResults` - Build action results with warnings, errors, analyzer warnings
+- `BuildIssue` - Individual build warning or error with source location
+- `TestResults` - Test execution results with device info and test node tree
+- `TestNode` - Hierarchical test node (test plan, bundle, suite, case, etc.)
+- `TestFailure` - Flattened test failure for easy reporting
+- `SourceLocation` - File path, line, and optional column
+- `TestResult` - Test outcome (passed, failed, skipped, expectedFailure)
+- `TestNodeType` - Node type in test hierarchy
+- `Severity` - Issue severity level (notice, warning, failure)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

Sources/XCResultParser/Models/BuildIssue.swift

@@ -0,0 +1,40 @@
+/// A build warning, error, or analyzer warning
+public struct BuildIssue: Sendable, Codable, Equatable {
+    public let issueType: String
+    public let message: String
+    public let targetName: String?
+    public let sourceURL: String?
+    public let className: String?
+
+    public init(
+        issueType: String,
+        message: String,
+        targetName: String? = nil,
+        sourceURL: String? = nil,
+        className: String? = nil
+    ) {
+        self.issueType = issueType
+        self.message = message
+        self.targetName = targetName
+        self.sourceURL = sourceURL
+        self.className = className
+    }
+
+    /// Parsed source location from sourceURL
+    public var sourceLocation: SourceLocation? {
+        guard let sourceURL else { return nil }
+        return SourceLocation.fromSourceURL(sourceURL)
+    }
+
+    /// Severity level for annotations based on issue type
+    public var severity: Severity {
+        let lowercased = issueType.lowercased()
+        if lowercased.contains("error") {
+            return .failure
+        } else if lowercased.contains("warning") {
+            return .warning
+        } else {
+            return .notice
+        }
+    }
+}

Sources/XCResultParser/Models/BuildResults.swift

@@ -0,0 +1,36 @@
+/// Build action results from xcresulttool
+public struct BuildResults: Sendable, Codable, Equatable {
+    public let actionTitle: String?
+    public let status: String?
+    public let warningCount: Int
+    public let errorCount: Int
+    public let analyzerWarningCount: Int
+    public let warnings: [BuildIssue]
+    public let errors: [BuildIssue]
+    public let analyzerWarnings: [BuildIssue]
+
+    public init(
+        actionTitle: String? = nil,
+        status: String? = nil,
+        warningCount: Int = 0,
+        errorCount: Int = 0,
+        analyzerWarningCount: Int = 0,
+        warnings: [BuildIssue] = [],
+        errors: [BuildIssue] = [],
+        analyzerWarnings: [BuildIssue] = []
+    ) {
+        self.actionTitle = actionTitle
+        self.status = status
+        self.warningCount = warningCount
+        self.errorCount = errorCount
+        self.analyzerWarningCount = analyzerWarningCount
+        self.warnings = warnings
+        self.errors = errors
+        self.analyzerWarnings = analyzerWarnings
+    }
+
+    /// All issues combined (errors, warnings, analyzer warnings)
+    public var allIssues: [BuildIssue] {
+        errors + warnings + analyzerWarnings
+    }
+}

Sources/XCResultParser/Models/Device.swift

@@ -0,0 +1,28 @@
+/// Device information from test results
+public struct Device: Sendable, Codable, Equatable {
+    public let architecture: String?
+    public let deviceId: String?
+    public let deviceName: String?
+    public let modelName: String?
+    public let osBuildNumber: String?
+    public let osVersion: String?
+    public let platform: String?
+
+    public init(
+        architecture: String? = nil,
+        deviceId: String? = nil,
+        deviceName: String? = nil,
+        modelName: String? = nil,
+        osBuildNumber: String? = nil,
+        osVersion: String? = nil,
+        platform: String? = nil
+    ) {
+        self.architecture = architecture
+        self.deviceId = deviceId
+        self.deviceName = deviceName
+        self.modelName = modelName
+        self.osBuildNumber = osBuildNumber
+        self.osVersion = osVersion
+        self.platform = platform
+    }
+}

Sources/XCResultParser/Models/Severity.swift

@@ -0,0 +1,6 @@
+/// Issue/annotation severity level
+public enum Severity: Sendable, Equatable {
+    case notice
+    case warning
+    case failure
+}