Add ArgumentMatcher for matching call arguments to function parameters

Sources/SwiftRefactor/ArgumentMatcher.swift

@@ -0,0 +1,247 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2026 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+#if compiler(>=6)
+public import SwiftSyntax
+#else
+import SwiftSyntax
+#endif
+
+/// An error produced by ``ArgumentMatcher`` when a call cannot be matched
+/// to the given parameter list.
+public enum ArgumentMatchError: Error, CustomStringConvertible {
+  /// A labeled argument was provided but no parameter with that external label
+  /// exists in the parameter list.
+  case unexpectedLabel(label: TokenSyntax, parameter: FunctionParameterSyntax)
+
+  /// A required argument (one with no default value) was not supplied by the
+  /// call. Default-parameter handling is not performed in this phase; callers
+  /// should handle the missing-argument case themselves, or use a later phase
+  /// that synthesises default values.
+  case missingArgument(parameter: FunctionParameterSyntax)
+
+  /// The call provides more arguments than the parameter list has parameters.
+  /// `from` is the zero-based index of the first extra argument.
+  case extraArguments(from: Int)
+
+  public var description: String {
+    switch self {
+    case .unexpectedLabel(let label, let parameter):
+      return
+        "unexpected argument label '\(label.text):' in call; parameter has label '\(parameter.firstName.text)'"
+    case .missingArgument(let parameter):
+      return "missing argument for parameter '\(parameter.firstName.text)' in call"
+    case .extraArguments(let index):
+      return "extra argument at position #\(index + 1) in call"
+    }
+  }
+}
+
+/// A resolved mapping between a single call-site argument and its corresponding
+/// function parameter.
+///
+/// Use ``ArgumentMatcher/match(call:parameters:)`` to produce an array of
+/// these from a ``FunctionCallExprSyntax`` and a ``FunctionParameterListSyntax``.
+///
+/// ## Example
+///
+/// Given:
+/// ```swift
+/// func move(to destination: CGPoint) { … }
+/// move(to: target)
+/// ```
+///
+/// The resolved ``ArgumentMatch`` has:
+/// - `parameter`: the `to destination: CGPoint` node
+/// - `argument`: the `target` expression
+/// - `internalName`: the token `destination` (used inside the function body)
+/// - `isLabeled`: `true` (matched by the external label `to`)
+public struct ArgumentMatch {
+  /// The function parameter this argument was matched to.
+  public let parameter: FunctionParameterSyntax
+
+  /// The expression at the call site that should be substituted for uses of
+  /// ``internalName`` in the function body.
+  public let argument: ExprSyntax
+
+  /// The name used to reference this parameter *inside* the function body.
+  ///
+  /// This is the parameter's second name when one is present (e.g.
+  /// `destination` in `to destination: CGPoint`), or its first name otherwise
+  /// (e.g. `width` in `width: Int`).
+  public let internalName: TokenSyntax
+
+  /// Whether this argument was matched to its parameter via a label (`true`)
+  /// or by its position in the argument list (`false`).
+  ///
+  /// An argument is positional when the parameter's external label is `_`.
+  public let isLabeled: Bool
+}
+
+/// A utility for matching the arguments of a function call to the corresponding
+/// parameters of a function declaration.
+///
+/// This type covers the first phase of argument resolution:
+/// - **Labeled arguments**: matched by external label name.
+/// - **Positional arguments**: matched in declaration order when the
+///   parameter's external label is `_`.
+/// - **External vs. internal names**: the ``ArgumentMatch/internalName``
+///   returned for each match reflects the name used inside the function body,
+///   not the label visible at the call site.
+///
+/// Later phases (default parameters, trailing closures, variadic parameters,
+/// `inout` and `@autoclosure` handling) are handled by separate extensions
+/// on this type.
+///
+/// ## Example — all labeled
+///
+/// ```swift
+/// func configure(width: Int, height: Int) { … }
+/// configure(width: 100, height: 200)
+/// // → [width → 100 (internalName: width), height → 200 (internalName: height)]
+/// ```
+///
+/// ## Example — positional
+///
+/// ```swift
+/// func greet(_ name: String) -> String { … }
+/// greet("World")
+/// // → [name → "World"  (internalName: name, isLabeled: false)]
+/// ```
+///
+/// ## Example — external / internal names
+///
+/// ```swift
+/// func move(to destination: CGPoint) { … }
+/// move(to: target)
+/// // → [internalName: destination, argument: target, isLabeled: true]
+/// ```
+public enum ArgumentMatcher {
+  /// Match the arguments of a call expression against the parameter list of a
+  /// function declaration.
+  ///
+  /// - Parameters:
+  ///   - call: The call expression whose arguments will be matched.
+  ///   - parameters: The parameter list of the function being called.
+  /// - Returns: An array of ``ArgumentMatch`` values, one per argument in
+  ///   `call.arguments`, in the order they appear at the call site.
+  /// - Throws: ``ArgumentMatchError`` if the arguments cannot be unambiguously
+  ///   matched to the parameter list.
+  public static func match(
+    call: FunctionCallExprSyntax,
+    parameters: FunctionParameterListSyntax
+  ) throws -> [ArgumentMatch] {
+    let arguments = Array(call.arguments)
+    let params = Array(parameters)
+
+    if arguments.isEmpty && params.isEmpty {
+      return []
+    }
+
+    // More arguments than parameters is always an error (variadic handling is
+    // deferred to a later phase).
+    if arguments.count > params.count {
+      throw ArgumentMatchError.extraArguments(from: params.count)
+    }
+
+    var matches: [ArgumentMatch] = []
+    matches.reserveCapacity(arguments.count)
+
+    // Tracks which parameter index to try next for positional (unlabeled)
+    // matching. Labeled arguments can match any parameter regardless of
+    // position, so we scan forward to find the right one.
+    var nextPositionalIndex = 0
+
+    // Records which parameter indices have been consumed by an argument.
+    // Used below to detect required parameters that were never supplied.
+    var matchedParamIndices = Set<Int>()
+
+    for (argIndex, argument) in arguments.enumerated() {
+      let paramIndex: Int
+      let isLabeled: Bool
+
+      if let label = argument.label {
+        // Labeled argument: find the parameter whose external label (firstName)
+        // matches the label at the call site.
+        guard
+          let foundIndex = params.indices.first(where: {
+            params[$0].firstName.text == label.text
+          })
+        else {
+          let nearestParam = params[min(argIndex, params.count - 1)]
+          throw ArgumentMatchError.unexpectedLabel(label: label, parameter: nearestParam)
+        }
+        paramIndex = foundIndex
+        isLabeled = true
+
+        // Advance the positional cursor past this parameter so that subsequent
+        // positional arguments do not attempt to consume it.
+        if paramIndex >= nextPositionalIndex {
+          nextPositionalIndex = paramIndex + 1
+        }
+      } else {
+        // Positional argument: consume the next parameter declared with `_` as
+        // its external label. Parameters with an explicit external label cannot
+        // be matched positionally.
+        guard
+          let foundIndex = (nextPositionalIndex..<params.count).first(where: {
+            params[$0].firstName.tokenKind == .wildcard
+          })
+        else {
+          throw ArgumentMatchError.extraArguments(from: argIndex)
+        }
+        paramIndex = foundIndex
+        isLabeled = false
+        nextPositionalIndex = paramIndex + 1
+      }
+
+      let param = params[paramIndex]
+      matchedParamIndices.insert(paramIndex)
+      matches.append(
+        ArgumentMatch(
+          parameter: param,
+          argument: argument.expression,
+          internalName: internalName(for: param),
+          isLabeled: isLabeled
+        )
+      )
+    }
+
+    // Verify every non-default parameter was supplied. Parameters with a
+    // default value may be omitted; default synthesis is handled in a later
+    // phase.
+    for (index, param) in params.enumerated() {
+      guard !matchedParamIndices.contains(index) else { continue }
+      if param.defaultValue != nil { continue }
+      throw ArgumentMatchError.missingArgument(parameter: param)
+    }
+
+    return matches
+  }
+}
+
+/// Returns the name used to reference `parameter` inside the function body.
+///
+/// Swift parameters have an optional second (internal) name:
+/// ```
+/// func move(to destination: CGPoint)
+///           ^^  ^^^^^^^^^^^
+///   external    internal
+/// ```
+/// When a second name is present it is the internal name; otherwise the first
+/// name serves as both external and internal name.
+private func internalName(for parameter: FunctionParameterSyntax) -> TokenSyntax {
+  if let secondName = parameter.secondName {
+    return secondName
+  }
+  return parameter.firstName
+}