Cherry-pick some post-4.2 changes into swift-4.2-branch

Sources/SwiftSyntax/AbsolutePosition.swift

@@ -0,0 +1,27 @@
+//===--------------- AbsolutePosition.swift - Source Positions ------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2017 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
+//
+//===----------------------------------------------------------------------===//
+
+/// An absolute position in a source file as text - the absolute utf8Offset from
+/// the start, line, and column.
+public struct AbsolutePosition {
+  public let utf8Offset: Int
+  public let line: Int
+  public let column: Int
+
+  static let startOfFile = AbsolutePosition(line: 1, column: 1, utf8Offset: 0)
+
+  public init(line: Int, column: Int, utf8Offset: Int) {
+    self.line = line
+    self.column = column
+    self.utf8Offset = utf8Offset
+  }
+}

Sources/SwiftSyntax/Diagnostic.swift

@@ -30,9 +30,8 @@ public struct SourceLocation: Codable {
   public let file: String
 
   public init(file: String, position: AbsolutePosition) {
-    assert(position is UTF8Position, "must be utf8 position")
     self.init(line: position.line, column: position.column,
-              offset: position.byteOffset, file: file)
+              offset: position.utf8Offset, file: file)
   }
 
   public init(line: Int, column: Int, offset: Int, file: String) {
@@ -88,7 +87,7 @@ public enum FixIt: Codable {
       let string = try container.decode(String.self, forKey: .string)
       let loc = try container.decode(SourceLocation.self, forKey: .location)
       self = .insert(loc, string)
-    case "replace": 
+    case "replace":
       let string = try container.decode(String.self, forKey: .string)
       let range = try container.decode(SourceRange.self, forKey: .range)
       self = .replace(range, string)
@@ -202,7 +201,11 @@ public struct Diagnostic: Codable {
   /// An array of possible FixIts to apply to this diagnostic.
   public let fixIts: [FixIt]
 
-  /// A diagnostic builder that 
+  /// A diagnostic builder that exposes mutating operations for notes,
+  /// highlights, and FixIts. When a Diagnostic is created, a builder
+  /// will be provided in a closure where the user can conditionally
+  /// add notes, highlights, and FixIts, that will then be wrapped
+  /// into the immutable Diagnostic object.
   public struct Builder {
     /// An in-flight array of notes.
     internal var notes = [Note]()
@@ -225,7 +228,7 @@ public struct Diagnostic: Codable {
     ///   - fixIts: Any FixIts that should be attached to this note.
     public mutating func note(_ message: Message,
                               location: SourceLocation? = nil,
-                              highlights: [SourceRange] = [], 
+                              highlights: [SourceRange] = [],
                               fixIts: [FixIt] = []) {
       self.notes.append(Note(message: message, location: location,
                              highlights: highlights, fixIts: fixIts))
@@ -252,7 +255,7 @@ public struct Diagnostic: Codable {
 
     /// Adds a FixIt to replace the contents of the source file corresponding
     /// to the provided SourceRange with the provided text.
-    public mutating 
+    public mutating
     func fixItReplace(_ sourceRange: SourceRange, with text: String) {
       fixIts.append(.replace(sourceRange, text))
     }