Expose structured diff results (from `XCDiffCore`)

[kwridan]

Is your feature request related to a problem? Please describe.

Using XCDiffCore as library enables other tools and application to leverage xcdiff programatically to perform project comparisons and retrieve their results. This however is limited to textual results only rather than the structured results.

e.g. The main entry point is ProjectComparator

public protocol ProjectComparator {
    func compare(_ firstPath: Path,
                 _ secondPath: Path,
                 parameters: ComparatorParameters) throws -> Result
}

This returns Result which exposes the results as a raw String:

public struct Result {
    public let success: Bool
    public let output: String
}

Describe the solution you'd like

Expose another method or component that can return the underlying ProjectCompareResult (which is structured).

One option could be to add another method on ProjectComparator :

e.g. structuredCompare()

public protocol ProjectComparator {
    func compare(
        _ firstPath: Path,
        _ secondPath: Path,
        parameters: ComparatorParameters
    ) throws -> Result

    func structuredCompare(
        _ firstPath: Path,
        _ secondPath: Path,
        parameters: ComparatorParameters
    ) throws -> ProjectCompareResult
}

This however makes the API a little awkward as a ProjectComparator is obtained via ProjectComparatorFactory which requires specifying the list of comparators along with a Mode which specifies the output format that is not applicable when dealing with structured results.

Another option could be extend ProjectComparatorFactory to return a new type StructuredProjectComparator, the factory however will not require specifying Mode

e.g.

public protocol StructuredProjectComparator {
    func compare(
        _ firstPath: Path,
        _ secondPath: Path,
        parameters: ComparatorParameters
    ) throws -> ProjectCompareResult
}

public final class ProjectComparatorFactory {
    public static func create(
        comparators: [ComparatorType] = .allAvailableComparators,
        mode: Mode = .default
    ) -> ProjectComparator { 
        // ...
     }

    public static func createStructuredComparator(
        comparators: [ComparatorType] = .allAvailableComparators,
        verbose: Bool = false,
        differencesOnly: Bool = false
    ) -> StructuredProjectComparator { 
        // ...
     }
}

Describe alternatives you've considered

• An alternative could be to leverage json formatted results and manually re-create the ProjectCompareResult structure that is capable of decoding the raw json back into something more structured. This feels unnecessary seeing the ProjectCompareResult is already public (just not Decodable).
• Another could be to manually write a custom StructuredProjectComparator outside of XCDiffCore, this is a little challenging as there isn't any public mechanisms to create the built in comparators. Furthermore, requires clients to deal XCDiffCore dependencies (XcodeProj loading and PathKit) to recreate the project comparator.

[gino1312]

8aeb133fa0c2f0c6e6e8042b026c27cfa1c25b3b

[gino1312]

Is your feature request related to a problem? Please describe.

Using XCDiffCore as library enables other tools and application to leverage xcdiff programatically to perform project comparisons and retrieve their results. This however is limited to textual results only rather than the structured results.

e.g. The main entry point is ProjectComparator

public protocol ProjectComparator {
    func compare(_ firstPath: Path,
                 _ secondPath: Path,
                 parameters: ComparatorParameters) throws -> Result
}

This returns Result which exposes the results as a raw String:

public struct Result {
    public let success: Bool
    public let output: String
}

Describe the solution you'd like

Expose another method or component that can return the underlying ProjectCompareResult (which is structured).

One option could be to add another method on ProjectComparator :

e.g. structuredCompare()

public protocol ProjectComparator {
    func compare(
        _ firstPath: Path,
        _ secondPath: Path,
        parameters: ComparatorParameters
    ) throws -> Result

    func structuredCompare(
        _ firstPath: Path,
        _ secondPath: Path,
        parameters: ComparatorParameters
    ) throws -> ProjectCompareResult
}

This however makes the API a little awkward as a ProjectComparator is obtained via ProjectComparatorFactory which requires specifying the list of comparators along with a Mode which specifies the output format that is not applicable when dealing with structured results.

Another option could be extend ProjectComparatorFactory to return a new type StructuredProjectComparator, the factory however will not require specifying Mode

e.g.

public protocol StructuredProjectComparator {
    func compare(
        _ firstPath: Path,
        _ secondPath: Path,
        parameters: ComparatorParameters
    ) throws -> ProjectCompareResult
}

public final class ProjectComparatorFactory {
    public static func create(
        comparators: [ComparatorType] = .allAvailableComparators,
        mode: Mode = .default
    ) -> ProjectComparator { 
        // ...
     }

    public static func createStructuredComparator(
        comparators: [ComparatorType] = .allAvailableComparators,
        verbose: Bool = false,
        differencesOnly: Bool = false
    ) -> StructuredProjectComparator { 
        // ...
     }
}

Describe alternatives you've considered

• An alternative could be to leverage json formatted results and manually re-create the ProjectCompareResult structure that is capable of decoding the raw json back into something more structured. This feels unnecessary seeing the ProjectCompareResult is already public (just not Decodable).
• Another could be to manually write a custom StructuredProjectComparator outside of XCDiffCore, this is a little challenging as there isn't any public mechanisms to create the built in comparators. Furthermore, requires clients to deal XCDiffCore dependencies (XcodeProj loading and PathKit) to recreate the project comparator.