Deprecate ByteSourceRange in favor of Range<AbsolutePosition>

While being a little more verbose, this has a few advantages:
- We only have a single type to represent ranges in SwiftSyntax instead of `Range<AbsolutePosition>` and `ByteSourceRange`, both of which we needed to use in sourcekit-lsp
- Unifying the convenience functions on the two results in a single type that has all the convenience functions, instead of spreading them to two distinct sets
- The use of `AbsolutePosition` and `SourceLength` makes type-system guarantees that these are UTF-8 byte positions / length, making it harder to accidentally add eg. UTF-16 lengths with UTF-8 lengths.

rdar://125624626

Author: ahoppen

Release Notes/600.md

@@ -75,6 +75,10 @@
   - Description: With the change to parse `#if canImport(MyModule, _version: 1.2.3)` as a function call instead of a dedicated syntax node, `1.2.3` natively gets parsed as a member access `3` to the `1.2` float literal. This property allows the reinterpretation of such an expression as a version tuple.
   - Pull request: https://github.com/apple/swift-syntax/pull/2025
 
+- `Range<AbsolutePosition>`
+  - Description: `Range<AbsolutePosition>` gained a few convenience functions inspirec from `ByteSourceRange`: `init(position:length:)`,  `length`, `intersectsOrTouches`, `intersects`, `intersecting`
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+
 ## API Behavior Changes
 
 ## Deprecations
@@ -108,6 +112,18 @@
   - Description: Instead of parsing `canImport` inside `#if` directives as a special expression node, parse it as a functionc call expression. This is in-line with how the `swift(>=6.0)` and `compiler(>=6.0)` directives are parsed.
   - Pull request: https://github.com/apple/swift-syntax/pull/2025
 
+- `SyntaxClassifiedRange.offset`, `length` and `endOffset`
+  - Description: Instead of providing these properties work with the replaced `range` instead.
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+
+- `SyntaxProtocol.totalByteRange` and `trimmedByteRange`
+  - Description: Renamed to `range` and `trimmedRange` with the deprecation of `ByteSourceRange` in favor of `Range<AbsolutePosition>`
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+
+- `ByteSourceRange` deprecated in favor of `Range<AbsolutePosition>`
+  - Description: Instead of having a dedicated range type in SwiftSyntax, use `Range<AbsolutePosition>` instead. `Range<AbsolutePosition>` has deprecated compatibility layers to make it API-compatible with `ByteSourceRange`
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+
 ## API-Incompatible Changes
 
 - `MacroDefinition` used for expanding macros:
@@ -156,6 +172,21 @@
   - Pull request: https://github.com/apple/swift-syntax/pull/2531
   - Migration steps: Use `if case .backslash = triviaPiece` instead
 
+- `ByteSourceRange.length` changed from `Int` to `SourceLength`
+  - Description: `ByteSourceRange` has been deprecated and declared as a typealias for `Range<AbsolutePosition>`. At the same time, `Range<AbsolutePosition>` gained `length: SourceLength` that provides type-system information about the kind of length (UTF-8 byte length).
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+
+- `IncrementalEdit.replacementLength` changed from `Int` to `SourceLength`
+  - Description: The type of `IncrementalEdit.replacementLength` has been changed from `Int` to `SourceLength` which provides type-system information about the kind of length (UTF-8 byte length).
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+
+## API-Behavior Changes
+
+- `SyntaxProtocol.classifications(in:)` and `SyntaxProtocol.classification(at:)` take positions relative to the root of the syntax tree instead of relative to the start of the node
+  - Description: With the deprecation of `ByteSourceRange` in favor of `Range<AbsolutePosition>`, the `AbsolutePosition`s passed as the range are measured from the start of the syntax tree instead of the start of the current node.
+  - Pull request: https://github.com/apple/swift-syntax/pull/2587
+  - Migration steps: Pass absolute positions measured from the root of the syntax tree instead of positions relative to the current node.
+
 ## Template
 
 - *Affected API or two word description*

Sources/SwiftIDEUtils/Syntax+Classifications.swift

@@ -25,12 +25,11 @@ public extension SyntaxProtocol {
   /// consecutive tokens would have the same classification then a single classified
   /// range is provided for all of them.
   var classifications: SyntaxClassifications {
-    let fullRange = ByteSourceRange(offset: 0, length: totalLength.utf8Length)
-    return SyntaxClassifications(_syntaxNode, in: fullRange)
+    return SyntaxClassifications(_syntaxNode, in: self.range)
   }
 
   /// Sequence of ``SyntaxClassifiedRange``s contained in this syntax node within
-  /// a relative range.
+  /// a source range.
   ///
   /// The provided classified ranges may extend beyond the provided `range`.
   /// Active classifications (non-`none`) will extend the range to include the
@@ -41,30 +40,31 @@ public extension SyntaxProtocol {
   /// intersect the provided `range`.
   ///
   /// - Parameters:
-  ///   - in: The relative byte range to pull ``SyntaxClassifiedRange``s from.
+  ///   - in: The range to pull ``SyntaxClassifiedRange``s from.
   /// - Returns: Sequence of ``SyntaxClassifiedRange``s.
-  func classifications(in range: ByteSourceRange) -> SyntaxClassifications {
+  func classifications(in range: Range<AbsolutePosition>) -> SyntaxClassifications {
     return SyntaxClassifications(_syntaxNode, in: range)
   }
 
-  /// The ``SyntaxClassifiedRange`` for a relative byte offset.
+  /// The ``SyntaxClassifiedRange`` for an byte offset.
   /// - Parameters:
-  ///   - at: The relative to the node byte offset.
-  /// - Returns: The ``SyntaxClassifiedRange`` for the offset or nil if the source text
+  ///   - at: The byte offset measured relative to the syntax tree's root.
+  /// - Returns: The ``SyntaxClassifiedRange`` for the offset or `nil`` if the source text
   ///   at the given offset is unclassified.
+  @available(*, deprecated, message: "Use classification(at: AbsolutePosition) instead")
   func classification(at offset: Int) -> SyntaxClassifiedRange? {
-    let classifications = SyntaxClassifications(_syntaxNode, in: ByteSourceRange(offset: offset, length: 1))
-    var iterator = classifications.makeIterator()
-    return iterator.next()
+    return classification(at: AbsolutePosition(utf8Offset: offset))
   }
 
   /// The ``SyntaxClassifiedRange`` for an absolute position.
   /// - Parameters:
   ///   - at: The absolute position.
-  /// - Returns: The ``SyntaxClassifiedRange`` for the position or nil if the source text
+  /// - Returns: The ``SyntaxClassifiedRange`` for the position or `nil`` if the source text
   ///   at the given position is unclassified.
   func classification(at position: AbsolutePosition) -> SyntaxClassifiedRange? {
-    let relativeOffset = position.utf8Offset - self.position.utf8Offset
-    return self.classification(at: relativeOffset)
+    let range = Range(position: position, length: SourceLength(utf8Length: 1))
+    let classifications = SyntaxClassifications(_syntaxNode, in: range)
+    var iterator = classifications.makeIterator()
+    return iterator.next()
   }
 }

Sources/SwiftIDEUtils/SyntaxClassifier.swift

@@ -44,7 +44,7 @@ extension TokenSyntax {
 
 extension RawTriviaPiece {
   func classify(offset: Int) -> SyntaxClassifiedRange {
-    let range = ByteSourceRange(offset: offset, length: byteLength)
+    let range = AbsolutePosition(utf8Offset: offset)..<AbsolutePosition(utf8Offset: offset + byteLength)
     switch self {
     case .lineComment: return .init(kind: .lineComment, range: range)
     case .blockComment: return .init(kind: .blockComment, range: range)
@@ -63,7 +63,7 @@ fileprivate struct TokenKindAndText {
     offset: Int,
     contextualClassification: (SyntaxClassification, Bool)?
   ) -> SyntaxClassifiedRange {
-    let range = ByteSourceRange(offset: offset, length: text.count)
+    let range = AbsolutePosition(utf8Offset: offset)..<AbsolutePosition(utf8Offset: offset + text.count)
 
     if let contextualClassify = contextualClassification {
       let (classify, force) = contextualClassify
@@ -91,10 +91,15 @@ fileprivate struct TokenKindAndText {
 /// Represents a source range that is associated with a syntax classification.
 public struct SyntaxClassifiedRange: Equatable, Sendable {
   public var kind: SyntaxClassification
-  public var range: ByteSourceRange
+  public var range: Range<AbsolutePosition>
 
+  @available(*, deprecated, message: "Use range.lowerBound.utf8Offset instead")
   public var offset: Int { return range.offset }
-  public var length: Int { return range.length }
+
+  @available(*, deprecated, message: "Use range.utf8Length instead")
+  public var length: Int { return range.length.utf8Length }
+
+  @available(*, deprecated, message: "Use range.upperBound.utf8Offset instead")
   public var endOffset: Int { return range.endOffset }
 }
 
@@ -110,19 +115,14 @@ private struct ClassificationVisitor {
     var contextualClassification: (SyntaxClassification, Bool)?
   }
 
-  /// Only tokens within this absolute range will be classified. No
-  /// classifications will be reported for tokens out of this range.
-  private var targetRange: ByteSourceRange
+  /// Only tokens within this range will be classified.
+  /// No classifications will be reported for tokens out of this range.
+  private var targetRange: Range<AbsolutePosition>
 
   var classifications: [SyntaxClassifiedRange]
 
-  /// Only classify tokens in `relativeClassificationRange`, where the start
-  /// offset is relative to `node`.
-  init(node: Syntax, relativeClassificationRange: ByteSourceRange) {
-    let range = ByteSourceRange(
-      offset: node.position.utf8Offset + relativeClassificationRange.offset,
-      length: relativeClassificationRange.length
-    )
+  /// Only classify tokens in `range`.
+  init(node: Syntax, range: Range<AbsolutePosition>) {
     self.targetRange = range
     self.classifications = []
 
@@ -140,24 +140,22 @@ private struct ClassificationVisitor {
   }
 
   private mutating func report(range: SyntaxClassifiedRange) {
-    if range.kind == .none && range.length == 0 {
+    if range.kind == .none && range.range.isEmpty {
       return
     }
 
     // Merge consecutive classified ranges of the same kind.
     if let last = classifications.last,
       last.kind == range.kind,
-      last.endOffset == range.offset
+      last.range.upperBound == range.range.lowerBound
     {
-      classifications[classifications.count - 1].range = ByteSourceRange(
-        offset: last.offset,
-        length: last.length + range.length
-      )
+      classifications[classifications.count - 1].range =
+        last.range.lowerBound..<(last.range.upperBound + range.range.length)
       return
     }
 
-    guard range.offset <= targetRange.endOffset,
-      range.endOffset >= targetRange.offset
+    guard range.range.lowerBound <= targetRange.upperBound,
+      range.range.upperBound >= targetRange.lowerBound
     else {
       return
     }
@@ -219,10 +217,9 @@ private struct ClassificationVisitor {
         let layoutNodeTextLength = child.byteLength - child.leadingTriviaByteLength - child.trailingTriviaByteLength
         let range = SyntaxClassifiedRange(
           kind: classification.classification,
-          range: ByteSourceRange(
-            offset: byteOffset,
-            length: layoutNodeTextLength
-          )
+          range: AbsolutePosition(
+            utf8Offset: byteOffset
+          )..<AbsolutePosition(utf8Offset: byteOffset + layoutNodeTextLength)
         )
         report(range: range)
         byteOffset += layoutNodeTextLength
@@ -250,10 +247,10 @@ private struct ClassificationVisitor {
   }
 
   private mutating func visit(_ descriptor: ClassificationVisitor.Descriptor) -> VisitResult {
-    guard descriptor.byteOffset < targetRange.endOffset else {
+    guard descriptor.byteOffset < targetRange.upperBound.utf8Offset else {
       return .break
     }
-    guard descriptor.byteOffset + descriptor.node.byteLength > targetRange.offset else {
+    guard descriptor.byteOffset + descriptor.node.byteLength > targetRange.lowerBound.utf8Offset else {
       return .continue
     }
     guard SyntaxTreeViewMode.sourceAccurate.shouldTraverse(node: descriptor.node) else {
@@ -273,8 +270,8 @@ public struct SyntaxClassifications: Sequence, Sendable {
 
   var classifications: [SyntaxClassifiedRange]
 
-  public init(_ node: Syntax, in relRange: ByteSourceRange) {
-    let visitor = ClassificationVisitor(node: node, relativeClassificationRange: relRange)
+  public init(_ node: Syntax, in range: Range<AbsolutePosition>) {
+    let visitor = ClassificationVisitor(node: node, range: range)
     self.classifications = visitor.classifications
   }
 

Sources/SwiftParser/IncrementalParseTransition.swift

@@ -23,7 +23,7 @@ extension Parser {
     }
 
     let currentOffset = self.lexemes.offsetToStart(self.currentToken)
-    if let node = parseLookup!.lookUp(currentOffset, kind: kind) {
+    if let node = parseLookup!.lookUp(AbsolutePosition(utf8Offset: currentOffset), kind: kind) {
       self.lexemes.advance(by: node.totalLength.utf8Length, currentToken: &self.currentToken)
       return node
     }
@@ -117,16 +117,15 @@ struct IncrementalParseLookup {
   /// has invalidated the previous ``Syntax`` node.
   ///
   /// - Parameters:
-  ///   - offset: The byte offset of the source string that is currently parsed.
+  ///   - position: The position in the source string that is currently parsed.
   ///   - kind: The `CSyntaxKind` that the parser expects at this position.
   /// - Returns: A ``Syntax`` node from the previous parse invocation,
   ///            representing the contents of this region, if it is still valid
   ///            to re-use. `nil` otherwise.
-  fileprivate mutating func lookUp(_ newOffset: Int, kind: SyntaxKind) -> Syntax? {
-    guard let prevOffset = translateToPreEditOffset(newOffset) else {
+  fileprivate mutating func lookUp(_ newPosition: AbsolutePosition, kind: SyntaxKind) -> Syntax? {
+    guard let prevPosition = translateToPreEditPosition(newPosition) else {
       return nil
     }
-    let prevPosition = AbsolutePosition(utf8Offset: prevOffset)
     let node = cursorLookup(prevPosition: prevPosition, kind: kind)
     if let node {
       reusedCallback?(node)
@@ -162,7 +161,7 @@ struct IncrementalParseLookup {
 
     // Fast path check: if parser is past all the edits then any matching node
     // can be re-used.
-    if !edits.edits.isEmpty && edits.edits.last!.range.endOffset < node.position.utf8Offset {
+    if !edits.edits.isEmpty && edits.edits.last!.range.upperBound < node.position {
       return true
     }
 
@@ -172,15 +171,12 @@ struct IncrementalParseLookup {
       return false
     }
 
-    let nodeAffectRange = ByteSourceRange(
-      offset: node.position.utf8Offset,
-      length: nodeAffectRangeLength
-    )
+    let nodeAffectRange = node.position..<node.position.advanced(by: nodeAffectRangeLength)
 
     for edit in edits.edits {
       // Check if this node or the trivia of the next node has been edited. If
       // it has, we cannot reuse it.
-      if edit.range.offset > nodeAffectRange.endOffset {
+      if edit.range.lowerBound > nodeAffectRange.upperBound {
         // Remaining edits don't affect the node. (Edits are sorted)
         break
       }
@@ -192,19 +188,19 @@ struct IncrementalParseLookup {
     return true
   }
 
-  fileprivate func translateToPreEditOffset(_ postEditOffset: Int) -> Int? {
+  fileprivate func translateToPreEditPosition(_ postEditOffset: AbsolutePosition) -> AbsolutePosition? {
     var offset = postEditOffset
     for edit in edits.edits {
-      if edit.range.offset > offset {
+      if edit.range.lowerBound > offset {
         // Remaining edits doesn't affect the position. (Edits are sorted)
         break
       }
-      if edit.range.offset + edit.replacementLength > offset {
+      if edit.range.lowerBound + edit.replacementLength > offset {
         // This is a position inserted by the edit, and thus doesn't exist in
         // the pre-edit version of the file.
         return nil
       }
-      offset = offset - edit.replacementLength + edit.range.length
+      offset = offset + edit.range.length - edit.replacementLength
     }
     return offset
   }
@@ -354,22 +350,30 @@ public struct ConcurrentEdits: Sendable {
       for (index, existingEdit) in concurrentEdits.enumerated() {
         if existingEdit.replacementRange.intersectsOrTouches(editToAdd.range) {
           let intersectionLength =
-            existingEdit.replacementRange.intersected(editToAdd.range).length
+            existingEdit.replacementRange.intersecting(editToAdd.range)?.length ?? SourceLength(utf8Length: 0)
           let replacement: [UInt8]
           replacement =
-            existingEdit.replacement.prefix(max(0, editToAdd.offset - existingEdit.replacementRange.offset))
+            existingEdit.replacement.prefix(
+              max(0, editToAdd.range.lowerBound.utf8Offset - existingEdit.replacementRange.lowerBound.utf8Offset)
+            )
             + editToAdd.replacement
-            + existingEdit.replacement.suffix(max(0, existingEdit.replacementRange.endOffset - editToAdd.endOffset))
+            + existingEdit.replacement.suffix(
+              max(0, existingEdit.replacementRange.upperBound.utf8Offset - editToAdd.range.upperBound.utf8Offset)
+            )
           editToAdd = IncrementalEdit(
-            offset: Swift.min(existingEdit.offset, editToAdd.offset),
-            length: existingEdit.length + editToAdd.length - intersectionLength,
+            range: Range(
+              position: Swift.min(existingEdit.range.lowerBound, editToAdd.range.lowerBound),
+              length: existingEdit.range.length + editToAdd.range.length - intersectionLength
+            ),
             replacement: replacement
           )
           editIndicesMergedWithNewEdit.append(index)
-        } else if existingEdit.offset < editToAdd.endOffset {
+        } else if existingEdit.range.lowerBound < editToAdd.range.upperBound {
           editToAdd = IncrementalEdit(
-            offset: editToAdd.offset - existingEdit.replacementLength + existingEdit.length,
-            length: editToAdd.length,
+            range: Range(
+              position: editToAdd.range.lowerBound + existingEdit.range.length - existingEdit.replacementLength,
+              length: editToAdd.range.length
+            ),
             replacement: editToAdd.replacement
           )
         }
@@ -380,7 +384,7 @@ public struct ConcurrentEdits: Sendable {
       }
       let insertPos =
         concurrentEdits.firstIndex(where: { edit in
-          editToAdd.endOffset <= edit.offset
+          editToAdd.range.upperBound <= edit.range.lowerBound
         }) ?? concurrentEdits.count
       concurrentEdits.insert(editToAdd, at: insertPos)
       precondition(ConcurrentEdits.isValidConcurrentEditArray(concurrentEdits))
@@ -397,7 +401,7 @@ public struct ConcurrentEdits: Sendable {
     for i in 1..<edits.count {
       let prevEdit = edits[i - 1]
       let curEdit = edits[i]
-      if curEdit.range.offset < prevEdit.range.endOffset {
+      if curEdit.range.lowerBound < prevEdit.range.upperBound {
         return false
       }
       if curEdit.intersectsRange(prevEdit.range) {