Check out of order sections properly

Author: tothambrus11

Sources/DocExtractor/SourceFileDocumentor.swift

@@ -15,6 +15,27 @@ public struct SpecialSectionMoreThanOneListWarning {}
 public struct ListSpecialSectionHasNoListError {}
 @Diagnostify
 public struct UnexpectedSpecialSectionTitleError {}
+
+public struct OutOfOrderError: HDCDiagnostic {
+  public let level: HDCDiagnosticLevel
+  public let message: String
+  public let site: SourceRange
+  public let notes: [AnyHashable]
+  public let found: SpecialSectionType
+  public let expectedBefore: SpecialSectionType
+
+  public init(
+    _ level: HDCDiagnosticLevel, message: String, at site: SourceRange, notes: [AnyHashable] = [],
+    found: SpecialSectionType, expectedBefore: SpecialSectionType
+  ) {
+    self.level = level
+    self.message = message
+    self.site = site
+    self.notes = notes
+    self.found = found
+    self.expectedBefore = expectedBefore
+  }
+}
 @Diagnostify
 public struct InlineSpecialSectionTitleRemoveFailureWarning {}
 @Diagnostify
@@ -160,6 +181,11 @@ private func parseSeeAlsoSection(
   return Array(blocks)
 }
 
+let strictOrdering: [SpecialSectionType] = [
+  .fileLevel, .parameter, .generic, .precondition, .postcondition, .invariant, 
+  .returns, .throws, .yields, .projects, .complexity, .seeAlso,
+]
+
 public enum SpecialSectionType {
   case `parameter`
   case `returns`
@@ -298,6 +324,7 @@ private func validateAllowedSpecialSections(
     allowedSectionTitles = []
   }
 
+  // Check for unexpected special sections
   for section in comment.value.specialSections {
     if !allowedSectionTitles.contains(where: { section.name.lowercased().starts(with: $0) }) {
       diagnostics.insert(
@@ -307,6 +334,50 @@ private func validateAllowedSpecialSections(
       )
     }
   }
+
+  // Check if sections that are present are in the correct order
+  var highestSectionIndexFound = -1
+  for i in 0..<comment.value.specialSections.count {
+    let section = comment.value.specialSections[i]
+    let lowercasedName = section.name.lowercased()
+    guard
+      let sectionType = strictOrdering.first(where: {
+        lowercasedName.starts(with: $0.inlineName) || lowercasedName.starts(with: $0.headingName)
+      })
+    else {
+      continue  // invalid section title, already diagnosed
+    }
+
+    let expectedSectionIndex = strictOrdering.firstIndex(of: sectionType)!
+
+    if expectedSectionIndex < highestSectionIndexFound {
+      let earliestSectionPresentThatShouldBeStillAfterThis: Int = (0..<i).map { (sectionI: Int) in
+        let rawSection = comment.value.specialSections[sectionI]
+        let lowercasedName = rawSection.name.lowercased()
+        return strictOrdering.firstIndex { sectionType in
+          lowercasedName.starts(with: sectionType.inlineName)
+            || lowercasedName.starts(with: sectionType.headingName)
+        }!
+      }  // map to index of each section
+      .first { index in
+        return expectedSectionIndex < index
+      }!
+
+      diagnostics.insert(
+        OutOfOrderError.init(
+          .error,
+          message:
+            "'\(sectionType.inlineName)' expected before '\(strictOrdering[highestSectionIndexFound].inlineName)'.",
+          at: comment.site,
+          found: sectionType,
+          expectedBefore: strictOrdering[earliestSectionPresentThatShouldBeStillAfterThis]
+        )
+      )
+    } else {
+      highestSectionIndexFound = expectedSectionIndex
+    }
+  }
+
 }
 
 public struct DummySourceFileDocumentor: SourceFileDocumentor {

Sources/HDCUtils/HDCDiagnostic.swift

@@ -16,7 +16,7 @@ public enum HDCDiagnosticLevel: Hashable {
 
 extension HDCDiagnostic {
   public var description: String {
-    "\(site.gnuStandardText): \(level): \(message)"
+    "\(site.vscodeFriendlyDescription): \(level): \(message)"
   }
 }
 
@@ -34,3 +34,23 @@ extension HDCDiagnostic {
 )
 @attached(extension, conformances: HDCDiagnostic)
 public macro Diagnostify() = #externalMacro(module: "HDCMacros", type: "DiagnostifyMacro")
+
+extension SourceRange {
+
+  /// A textual representation per the
+  /// [Gnu-standard](https://www.gnu.org/prep/standards/html_node/Errors.html).
+  public var vscodeFriendlyDescription: String {
+    let start = self.start.lineAndColumn
+    let head = "\(file.url.relativePath):\(start.line):\(start.column)"
+    if regionOfFile.isEmpty { return head }
+
+    let end = file.position(endIndex).lineAndColumn
+    if end.line == start.line {
+      return head + "-\(end.column)"
+    }
+    return head + "-\(end.line):\(end.column)"
+  }
+
+  public var description: String { gnuStandardText }
+
+}

Tests/DocExtractorTests/SourceFileDocumentorTests/SimpleTests/ProductTypeExtractionTest.swift

@@ -17,8 +17,8 @@ final class ProductTypeExtractionTest: XCTestCase {
         /// Summary of the product type.
         ///
         /// This is the description of the product type.
-        /// # Invariant: x and y must always be positive.
         /// # Generic T: This is a generic.
+        /// # Invariant: x and y must always be positive.
         type A<T: D>{
           var x: Int
           var y: Int

Tests/DocExtractorTests/SourceFileDocumentorTests/SimpleTests/SpecialSectionOutOfOrderTest.swift

@@ -0,0 +1,119 @@
+import DocExtractor
+import DocumentationDB
+import FrontEnd
+import HDCUtils
+import TestUtils
+import XCTest
+
+final class SpecialSectionOutOfOrderTest: XCTestCase {
+
+  struct OutOfOrderErrorPayload {
+    let found: SpecialSectionType
+    let expectedBefore: SpecialSectionType
+  }
+  func testOutOfOrder(
+    in sourceFile: SourceFile, expectedErrors: [OutOfOrderErrorPayload], file: StaticString = #filePath, line: UInt = #line
+  ) throws {
+    let commentParser = RealCommentParser(lowLevelCommentParser: RealLowLevelCommentParser())
+    let sourceFileDocumentor = RealSourceFileDocumentor(
+      commentParser: commentParser, markdownParser: HyloDocMarkdownParser.standard)
+
+    let ast = try checkNoDiagnostic { d in
+      try AST(fromSingleSourceFile: sourceFile, diagnostics: &d)
+    }
+
+    var store = SymbolDocStore()
+
+    var d = HDCDiagnosticSet()
+    let _ = sourceFileDocumentor.document(
+      ast: ast,
+      translationUnitId: ast.resolveTranslationUnit(by: sourceFile.baseName)!,
+      into: &store,
+      diagnostics: &d
+    )
+
+    let outOfOrderDiagnostics = d.elements.filter { $0 is OutOfOrderError }
+    XCTAssertEqual(
+      expectedErrors.count, outOfOrderDiagnostics.count,
+      "The number of out of order diagnostics does not match the expected count. Diagnostic: \n\(outOfOrderDiagnostics.map { $0.description }.joined(separator: "\n"))",
+      file: file, line: line)
+
+    for expectedError in expectedErrors {
+      let match = outOfOrderDiagnostics.first { diagnostic in
+        let error = diagnostic as! OutOfOrderError
+        return error.found == expectedError.found && error.expectedBefore == expectedError.expectedBefore
+      }
+      XCTAssertNotNil(
+        match,
+        "Expected out of order error with found: \(expectedError.found) and expectedBefore: \(expectedError.expectedBefore) not found.",
+        file: file, line: line
+      )
+    }
+  }
+
+  func testOutOfOrder1() throws {
+    try testOutOfOrder(
+      in: """
+        /// Summary of function.
+        /// 
+        /// This is the description.
+        /// - Note: This is still the description.
+        /// # Generic T: This is a generic.
+        /// # Parameter x: This is a parameter.
+        fun id(x: Int) -> Int { x }
+        """,
+      expectedErrors: [
+        .init(found: .parameter, expectedBefore: .generic)
+      ])
+  }
+
+  func testOutOfOrder2() throws {
+    try testOutOfOrder(
+      in: """
+        /// Summary of function.
+        /// 
+        /// This is the description.
+        /// - Note: This is still the description.
+        /// # Returns: something.
+        /// # Parameter x: This is a parameter.
+        /// # Generic y: This is a generic parameter.
+        fun id(x: Int) -> Int { x }
+        """,
+      expectedErrors: [
+        .init(found: .parameter, expectedBefore: .returns),
+        .init(found: .generic, expectedBefore: .returns),
+      ])
+  }
+  func testOutOfOrder3() throws {
+    try testOutOfOrder(
+      in: """
+        /// Summary of subscript.
+        /// 
+        /// This is the description.
+        /// - Note: This is still the description.
+        /// # Parameter param: sample param desc
+        /// # Yields: some stuff.
+        /// # Projects:
+        ///   - Insecurity
+        /// # Complexity: O(2)
+        subscript foo(param: Int): T { }
+        """,
+      expectedErrors: [])
+  }
+
+  func testInOrder() throws {
+    try testOutOfOrder(
+      in: """
+        /// Summary of function.
+        /// 
+        /// This is the description.
+        /// - Note: This is still the description.
+        /// # Parameter x: This is a parameter.
+        /// # Generic y: This is a generic parameter.
+        /// # Returns: something.
+        fun id(x: Int) -> Int { x }
+        """,
+      expectedErrors: []
+    )
+  }
+}

Tests/DocExtractorTests/SourceFileDocumentorTests/SimpleTests/SubscriptExtractionTest.swift

@@ -10,8 +10,9 @@ final class SubscriptExtractionTest: XCTestCase {
     let sourceFileDocumentor = RealSourceFileDocumentor(
       commentParser: commentParser, markdownParser: HyloDocMarkdownParser.standard)
 
-    let sourceFile = SourceFile(
-      synthesizedText: """
+    // todo projects and yields should not be possible to add to a subscript at the same time.
+    let sourceFile: SourceFile = 
+     """
         /// # File-level:
         /// This is the summary of the file.
         /// 
@@ -26,23 +27,23 @@ final class SubscriptExtractionTest: XCTestCase {
         /// 
         /// This is the description.
         /// - Note: This is still the description.
-        /// # Yields: some stuff.
         /// # Parameter param: sample param desc
-        /// # Complexity: O(2)
+        /// # Yields: some stuff.
         /// # Projects:
         ///   - Insecurity
+        /// # Complexity: O(2)
         subscript foo(param: Int): T { 
           /// Summary of subscript implementation.
           /// 
           /// This is the description2.
           /// - Note: This is still the description2.
           /// # Yields: some other stuff.
-          /// # Complexity: O(2)
           /// # Projects:
           ///   - Insecurity
+          /// # Complexity: O(2)
           T() 
         }
-        """, named: "testFile11.hylo")
+        """
 
     let ast = try checkNoDiagnostic { d in
       try AST(fromSingleSourceFile: sourceFile, diagnostics: &d)
@@ -53,7 +54,7 @@ final class SubscriptExtractionTest: XCTestCase {
     let fileLevel = checkNoHDCDiagnostic { d in
       sourceFileDocumentor.document(
         ast: ast,
-        translationUnitId: ast.resolveTranslationUnit(by: "testFile11.hylo")!,
+        translationUnitId: ast.resolveTranslationUnit(by: sourceFile.baseName)!,
         into: &store,
         diagnostics: &d
       )

Tests/TestUtils/ASTExtension.swift

@@ -337,8 +337,6 @@ extension AST {
 
   /// - Parameter name: file name without extension
   public func resolveTranslationUnit(by name: String) -> TranslationUnit.ID? {
-    precondition(name.hasSuffix(".hylo"), "Name should be passed with extension.")
-
     struct ASTWalker: ASTWalkObserver {
       var result: TranslationUnit.ID?
       let targetName: String

Tests/TestUtils/DiagnosticChecks.swift

@@ -66,13 +66,13 @@ public func checkNoHDCDiagnostic<R>(
   var d = HDCDiagnosticSet()
   do {
     let r = try f(&d)
-    checkHDCEmpty(d)
+    checkHDCEmpty(d, file: testFile, line: line)
     return r
   } catch let d1 as HDCDiagnosticSet {
     XCTAssertEqual(
       d1, d, "thrown diagnostics don't match mutated diagnostics",
       file: testFile, line: line)
-    checkHDCEmpty(d)
+    checkHDCEmpty(d, file: testFile, line: line)
     throw d
   }
 }
@@ -110,10 +110,12 @@ public func expectHDCDiagnostic<R, D: HDCDiagnostic>(
 }
 
 /// Reports any diagnostics in `s` as XCTest issues.
-public func checkHDCEmpty(_ s: HDCDiagnosticSet) {
+public func checkHDCEmpty(_ s: HDCDiagnosticSet, file: StaticString = #filePath, line: UInt = #line)
+{
   if !s.elements.isEmpty {
     XCTFail(
-      "Unexpected diagnostics: \n\(s.elements.map{ "- " + $0.description }.joined(separator: "\n\n"))"
+      "Unexpected diagnostics: \n\(s.elements.map{ "- " + $0.description }.joined(separator: "\n\n"))",
+      file: file, line: line
     )
   }
 }

Tests/WebsiteGenTests/SimpleFullPipelineTest/ExampleModule/ModuleA/c.hylo

@@ -50,8 +50,8 @@ trait D {}
 /// Summary of the product type.
 ///
 /// This is the description of the product type.
-/// # Invariant: x and y must always be positive.
 /// # Generic T: This is a generic.
+/// # Invariant: x and y must always be positive.
 type A<T: D>{
   var x: Int
   var y: Int

Tests/WebsiteGenTests/SimpleFullPipelineTest/SimpleFullPipelineTest.swift

@@ -10,7 +10,9 @@ import XCTest
 
 @testable import WebsiteGen
 
-func runFullPipelineWithoutErrors(at sourceUrl: URL) throws {
+func runFullPipelineWithoutErrors(
+  at sourceUrl: URL, file: StaticString = #filePath, line: UInt = #line
+) throws {
   let outputURL = URL(fileURLWithPath: "./test-output/" + UUID.init().uuidString)
 
   let fileManager = FileManager.default
@@ -50,13 +52,11 @@ func runFullPipelineWithoutErrors(at sourceUrl: URL) throws {
         typedProgram: typedProgram,
         exportPath: outputURL
       )
-    else { return XCTFail("failed to generate documentation") }
-
-    print("Documentation successfully generated at \(outputURL).")
+    else {
+      return XCTFail("failed to generate documentation", file: file, line: line)
+    }
   case .failure(let error):
-    print("Failed to extract documentation: \(error)")
-
-    XCTFail()
+    XCTFail("Failed to extract documentation: \(error)", file: file, line: line)
   }
 }