SR-15316: Emit warning when topics section does not have 1+ subheading (#29)

* SR-15316: Emit warning when topics section does not have 1+ subheading

* SR-15316: Code changes

* SR-15316: Add isTopic computed property

* SR-15316: Rename checker for better clarity

* SR-15316: Move check into guard statement

* SR-15316: Add convenience initializer for problem

* SR-15316: Invert method

* SR-15316: Rename method

Author: maldahleh

Sources/SwiftDocC/Checker/Checker.swift

@@ -413,3 +413,12 @@ public struct CompositeChecker: Checker {
         descendInto(text)
     }
 }
+
+/*
+ A collection of `Heading` properties utilized by `Checker`s.
+ */
+extension Heading {
+    var isTopicsSection: Bool {
+        return level == 2 && title == "Topics"
+    }
+}

Sources/SwiftDocC/Checker/Checkers/DuplicateTopicsSection.swift

@@ -49,9 +49,8 @@ public struct DuplicateTopicsSections: Checker {
     }
 
     public mutating func visitHeading(_ heading: Heading) {
-        guard heading.level == 2,
-            heading.plainText == "Topics",
-            heading.parent is Document?  else {
+        guard heading.isTopicsSection,
+              heading.parent is Document? else {
                 return
         }
         foundTopicsHeadings.append(heading)

Sources/SwiftDocC/Checker/Checkers/NonOverviewHeadingChecker.swift

@@ -59,7 +59,7 @@ public struct NonOverviewHeadingChecker: Checker {
 
     public mutating func visitHeading(_ heading: Heading) {
         // We don't want to flag the Topics H2 and the See Also H2.
-        guard heading.level == 2, !["Topics", "See Also"].contains(heading.plainText) else {
+        guard heading.level == 2, !heading.isTopicsSection, heading.title != "See Also" else {
             return
         }
 

Sources/SwiftDocC/Checker/Checkers/TopicsSectionWithoutSubheading.swift

@@ -0,0 +1,52 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2021 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
+*/
+
+import Foundation
+import Markdown
+
+/**
+ A Topics section  should have at least one subheading.
+ */
+public struct TopicsSectionWithoutSubheading: Checker {
+    public var problems = [Problem]()
+
+    private var sourceFile: URL?
+
+    /// Creates a new checker that detects Topics sections without subheadings.
+    ///
+    /// - Parameter sourceFile: The URL to the documentation file that the checker checks.
+    public init(sourceFile: URL?) {
+        self.sourceFile = sourceFile
+    }
+
+    public mutating func visitDocument(_ document: Document) -> () {
+        let headings = document.children.compactMap { $0 as? Heading }
+        for (index, heading) in headings.enumerated() {
+            guard heading.isTopicsSection, isMissingSubheading(heading, remainingHeadings: headings.dropFirst(index + 1)) else {
+                continue
+            }
+
+            let explanation = """
+            A Topics section requires at least one topic, represented by a level-3 subheading. A Topics section without topics won’t render any content.”
+            """
+
+            let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: heading.range, identifier: "org.swift.docc.TopicsSectionWithoutSubheading", summary: "Missing required subheading for Topics section.", explanation: explanation)
+            problems.append(Problem(diagnostic: diagnostic))
+        }
+    }
+
+    private func isMissingSubheading(_ heading: Heading, remainingHeadings: ArraySlice<Heading>) -> Bool {
+        if let nextHeading = remainingHeadings.first {
+            return nextHeading.level <= heading.level
+        }
+
+        return true
+    }
+}

Sources/SwiftDocC/Infrastructure/Diagnostics/Problem.swift

@@ -21,6 +21,10 @@ public struct Problem {
         self.diagnostic = diagnostic
         self.possibleSolutions = Array(possibleSolutions)
     }
+
+    public init(diagnostic: Diagnostic) {
+        self.init(diagnostic: diagnostic, possibleSolutions: [])
+    }
 }
 
 extension Problem {

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -366,6 +366,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             MissingAbstract(sourceFile: source).any(),
             NonOverviewHeadingChecker(sourceFile: source).any(),
             SeeAlsoInTopicsHeadingChecker(sourceFile: source).any(),
+            TopicsSectionWithoutSubheading(sourceFile: source).any(),
         ])
         checker.visit(document)
         diagnosticEngine.emit(checker.problems)

Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/StaticAnalysis.md

@@ -19,5 +19,6 @@ Run static analysis checks on markup files.
 - ``NonInclusiveLanguageChecker``
 - ``NonOverviewHeadingChecker``
 - ``SeeAlsoInTopicsHeadingChecker``
+- ``TopicsSectionWithoutSubheading``
 
 <!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Checker/Checkers/TopicsSectionWithoutSubheadingTests.swift

@@ -0,0 +1,104 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2021 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
+*/
+
+import XCTest
+@testable import SwiftDocC
+import Markdown
+
+class TopicsSectionWithoutSubheadingTests: XCTestCase {
+    func testEmptyDocument() {
+        let checker = visitDocument(Document())
+        XCTAssertTrue(checker.problems.isEmpty)
+    }
+    
+    func testTopicsSectionHasSubheading() {
+        let markupSource = """
+# Title
+
+Testing One
+
+## Topics
+
+### Test 2
+
+Testing Two
+
+# Test
+"""
+        let checker = visitSource(markupSource)
+        XCTAssertTrue(checker.problems.isEmpty)
+    }
+    
+    func testTopicsSectionHasNoSubheading() {
+        let markupSource = """
+# Title
+
+Abstract.
+
+## Topics
+
+## Information
+
+### Topic B
+"""
+        
+        let document = Document(parsing: markupSource)
+        let checker = visitDocument(document)
+        XCTAssertEqual(1, checker.problems.count)
+        
+        let problem = checker.problems[0]
+        XCTAssertTrue(problem.possibleSolutions.isEmpty)
+        
+        let noSubheadingHeading = document.child(at: 2)! as! Heading
+        let diagnostic = problem.diagnostic
+        XCTAssertEqual("org.swift.docc.TopicsSectionWithoutSubheading", diagnostic.identifier)
+        XCTAssertEqual(noSubheadingHeading.range, diagnostic.range)
+    }
+
+    func testTopicsSectionIsFinalHeading() {
+        let markupSource = """
+# Title
+
+Abstract.
+
+## User
+
+## Information
+
+## Topics
+"""
+        
+        let document = Document(parsing: markupSource)
+        let checker = visitDocument(document)
+        XCTAssertEqual(1, checker.problems.count)
+        
+        let problem = checker.problems[0]
+        XCTAssertTrue(problem.possibleSolutions.isEmpty)
+        
+        let noSubheadingHeading = document.child(at: 4)! as! Heading
+        let diagnostic = problem.diagnostic
+        XCTAssertEqual("org.swift.docc.TopicsSectionWithoutSubheading", diagnostic.identifier)
+        XCTAssertEqual(noSubheadingHeading.range, diagnostic.range)
+    }
+}
+
+extension TopicsSectionWithoutSubheadingTests {
+    func visitSource(_ source: String) -> TopicsSectionWithoutSubheading {
+        let document = Document(parsing: source)
+        return visitDocument(document)
+    }
+    
+    func visitDocument(_ document: Document) -> TopicsSectionWithoutSubheading {
+        var checker = TopicsSectionWithoutSubheading(sourceFile: nil)
+        checker.visit(document)
+        
+        return checker
+    }
+}