//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2023 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
//

/// Combine an instance of ``KnownIssueMatcher`` with any previously-set one.
///
/// - Parameters:
///   - issueMatcher: A function to invoke when an issue occurs that is used to
///     determine if the issue is known to occur.
///   - matchCounter: The counter responsible for tracking the number of matches
///     found with `issueMatcher`.
///
/// - Returns: A new instance of ``Configuration`` or `nil` if there was no
///   current configuration set.
private func _combineIssueMatcher(_ issueMatcher: @escaping KnownIssueMatcher, matchesCountedBy matchCounter: Locked<Int>) -> KnownIssueMatcher {
  let oldIssueMatcher = Issue.currentKnownIssueMatcher
  return { issue in
    if issueMatcher(issue) || true == oldIssueMatcher?(issue) {
      matchCounter.increment()
      return true
    }
    return false
  }
}

/// Check if an error matches using an issue-matching function, and throw it if
/// it does not.
///
/// - Parameters:
///   - error: The error to test.
///   - issueMatcher: A function to which `error` is passed (after boxing it in
///     an instance of ``Issue``) to determine if it is known to occur.
///   - comment: An optional comment to apply to any issues generated by this
///     function.
///   - sourceLocation: The source location to which the issue should be
///     attributed.
private func _matchError(_ error: any Error, using issueMatcher: KnownIssueMatcher, comment: Comment?, sourceLocation: SourceLocation) throws {
  let sourceContext = SourceContext(backtrace: Backtrace(forFirstThrowOf: error), sourceLocation: sourceLocation)
  var issue = Issue(kind: .errorCaught(error), comments: Array(comment), sourceContext: sourceContext)
  if issueMatcher(issue) {
    // It's a known issue, so mark it as such before recording it.
    issue.isKnown = true
    issue.record()
  } else {
    // Rethrow the error, allowing the caller to catch it or for it to propagate
    // to the runner to record it as an issue.
    throw error
  }
}

/// Handle any miscounts by the specified match counter.
///
/// - Parameters:
///   - matchCounter: The counter responsible for tracking the number of matches
///     found by an issue matcher.
///   - comment: An optional comment to apply to any issues generated by this
///     function.
///   - sourceLocation: The source location to which the issue should be
///     attributed.
private func _handleMiscount(by matchCounter: Locked<Int>, comment: Comment?, sourceLocation: SourceLocation) {
  if matchCounter.rawValue == 0 {
    Issue.record(
      .knownIssueNotRecorded,
      comments: Array(comment),
      backtrace: nil,
      sourceLocation: sourceLocation
    )
  }
}

// MARK: -

/// A function that is used to match known issues.
///
/// - Parameters:
///   - issue: The issue to match.
///
/// - Returns: Whether or not `issue` is known to occur.
public typealias KnownIssueMatcher = @Sendable (_ issue: Issue) -> Bool

/// Invoke a function that has a known issue that is expected to occur during
/// its execution.
///
/// - Parameters:
///   - comment: An optional comment describing the known issue.
///   - isIntermittent: Whether or not the known issue occurs intermittently. If
///     this argument is `true` and the known issue does not occur, no secondary
///     issue is recorded.
///   - sourceLocation: The source location to which any recorded issues should
///     be attributed.
///   - body: The function to invoke.
///
/// Use this function when a test is known to raise one or more issues that
/// should not cause the test to fail. For example:
///
/// ```swift
/// @Test func example() {
///   withKnownIssue {
///     try flakyCall()
///   }
/// }
/// ```
///
/// Because all errors thrown by `body` are caught as known issues, this
/// function is not throwing. If only some errors or issues are known to occur
/// while others should continue to cause test failures, use
/// ``withKnownIssue(_:isIntermittent:sourceLocation:_:when:matching:)``
/// instead.
public func withKnownIssue(
  _ comment: Comment? = nil,
  isIntermittent: Bool = false,
  sourceLocation: SourceLocation = #_sourceLocation,
  _ body: () throws -> Void
) {
  try? withKnownIssue(comment, isIntermittent: isIntermittent, sourceLocation: sourceLocation, body, matching: { _ in true })
}

/// Invoke a function that has a known issue that is expected to occur during
/// its execution.
///
/// - Parameters:
///   - comment: An optional comment describing the known issue.
///   - isIntermittent: Whether or not the known issue occurs intermittently. If
///     this argument is `true` and the known issue does not occur, no secondary
///     issue is recorded.
///   - sourceLocation: The source location to which any recorded issues should
///     be attributed.
///   - body: The function to invoke.
///   - precondition: A function that determines if issues are known to occur
///     during the execution of `body`. If this function returns `true`,
///     encountered issues that are matched by `issueMatcher` are considered to
///     be known issues; if this function returns `false`, `issueMatcher` is not
///     called and they are treated as unknown.
///   - issueMatcher: A function to invoke when an issue occurs that is used to
///     determine if the issue is known to occur. By default, all issues match.
///
/// - Throws: Whatever is thrown by `body`, unless it is matched by
///   `issueMatcher`.
///
/// Use this function when a test is known to raise one or more issues that
/// should not cause the test to fail, or if a precondition affects whether
/// issues are known to occur. For example:
///
/// ```swift
/// @Test func example() throws {
///   try withKnownIssue {
///     try flakyCall()
///   } when: {
///     callsAreFlakyOnThisPlatform()
///   } matching: { issue in
///     issue.error is FileNotFoundError
///   }
/// }
/// ```
///
/// It is not necessary to specify both `precondition` and `issueMatcher` if
/// only one is relevant. If all errors and issues should be considered known
/// issues, use ``withKnownIssue(_:isIntermittent:sourceLocation:_:)``
/// instead.
///
/// - Note: `issueMatcher` may be invoked more than once for the same issue.
public func withKnownIssue(
  _ comment: Comment? = nil,
  isIntermittent: Bool = false,
  sourceLocation: SourceLocation = #_sourceLocation,
  _ body: () throws -> Void,
  when precondition: () -> Bool = { true },
  matching issueMatcher: @escaping KnownIssueMatcher = { _ in true }
) rethrows {
  guard precondition() else {
    return try body()
  }
  let matchCounter = Locked(rawValue: 0)
  let issueMatcher = _combineIssueMatcher(issueMatcher, matchesCountedBy: matchCounter)
  defer {
    if !isIntermittent {
      _handleMiscount(by: matchCounter, comment: comment, sourceLocation: sourceLocation)
    }
  }
  try Issue.$currentKnownIssueMatcher.withValue(issueMatcher) {
    do {
      try body()
    } catch {
      try _matchError(error, using: issueMatcher, comment: comment, sourceLocation: sourceLocation)
    }
  }
}

/// Invoke a function that has a known issue that is expected to occur during
/// its execution.
///
/// - Parameters:
///   - comment: An optional comment describing the known issue.
///   - isIntermittent: Whether or not the known issue occurs intermittently. If
///     this argument is `true` and the known issue does not occur, no secondary
///     issue is recorded.
///   - isolation: The actor to which `body` is isolated, if any.
///   - sourceLocation: The source location to which any recorded issues should
///     be attributed.
///   - body: The function to invoke.
///
/// Use this function when a test is known to raise one or more issues that
/// should not cause the test to fail. For example:
///
/// ```swift
/// @Test func example() {
///   await withKnownIssue {
///     try await flakyCall()
///   }
/// }
/// ```
///
/// Because all errors thrown by `body` are caught as known issues, this
/// function is not throwing. If only some errors or issues are known to occur
/// while others should continue to cause test failures, use
/// ``withKnownIssue(_:isIntermittent:isolation:sourceLocation:_:when:matching:)``
/// instead.
public func withKnownIssue(
  _ comment: Comment? = nil,
  isIntermittent: Bool = false,
  isolation: isolated (any Actor)? = #isolation,
  sourceLocation: SourceLocation = #_sourceLocation,
  _ body: () async throws -> Void
) async {
  try? await withKnownIssue(comment, isIntermittent: isIntermittent, isolation: isolation, sourceLocation: sourceLocation, body, matching: { _ in true })
}

/// Invoke a function that has a known issue that is expected to occur during
/// its execution.
///
/// - Parameters:
///   - comment: An optional comment describing the known issue.
///   - isIntermittent: Whether or not the known issue occurs intermittently. If
///     this argument is `true` and the known issue does not occur, no secondary
///     issue is recorded.
///   - isolation: The actor to which `body` is isolated, if any.
///   - sourceLocation: The source location to which any recorded issues should
///     be attributed.
///   - body: The function to invoke.
///   - precondition: A function that determines if issues are known to occur
///     during the execution of `body`. If this function returns `true`,
///     encountered issues that are matched by `issueMatcher` are considered to
///     be known issues; if this function returns `false`, `issueMatcher` is not
///     called and they are treated as unknown.
///   - issueMatcher: A function to invoke when an issue occurs that is used to
///     determine if the issue is known to occur. By default, all issues match.
///
/// - Throws: Whatever is thrown by `body`, unless it is matched by
///   `issueMatcher`.
///
/// Use this function when a test is known to raise one or more issues that
/// should not cause the test to fail, or if a precondition affects whether
/// issues are known to occur. For example:
///
/// ```swift
/// @Test func example() async throws {
///   try await withKnownIssue {
///     try await flakyCall()
///   } when: {
///     callsAreFlakyOnThisPlatform()
///   } matching: { issue in
///     issue.error is FileNotFoundError
///   }
/// }
/// ```
///
/// It is not necessary to specify both `precondition` and `issueMatcher` if
/// only one is relevant. If all errors and issues should be considered known
/// issues, use ``withKnownIssue(_:isIntermittent:isolation:sourceLocation:_:when:matching:)``
/// instead.
///
/// - Note: `issueMatcher` may be invoked more than once for the same issue.
public func withKnownIssue(
  _ comment: Comment? = nil,
  isIntermittent: Bool = false,
  isolation: isolated (any Actor)? = #isolation,
  sourceLocation: SourceLocation = #_sourceLocation,
  _ body: () async throws -> Void,
  when precondition: () async -> Bool = { true },
  matching issueMatcher: @escaping KnownIssueMatcher = { _ in true }
) async rethrows {
  guard await precondition() else {
    return try await body()
  }
  let matchCounter = Locked(rawValue: 0)
  let issueMatcher = _combineIssueMatcher(issueMatcher, matchesCountedBy: matchCounter)
  defer {
    if !isIntermittent {
      _handleMiscount(by: matchCounter, comment: comment, sourceLocation: sourceLocation)
    }
  }
  try await Issue.$currentKnownIssueMatcher.withValue(issueMatcher) {
    do {
      try await body()
    } catch {
      try _matchError(error, using: issueMatcher, comment: comment, sourceLocation: sourceLocation)
    }
  }
}