Add 'SwiftWarningControl' library for source-level lexical warning group behavior settings

This library provides support for a mechanism to control the behavior of specific diagnostic groups for a given declaration's lexical scope with the `@warn` attribute.

The syntax tree and its parser do not reason about warning group controls. The syntax tree produced by the parser reprsents the `@warn` attribute in a generic fashion, as it would any other basic attribute on a declaration. The per-declaration nature of the attribute means that for any given declaration's lexical scope, the behavior of a given diagnosic group can be queried by checking for the presence of this attribute in its parent declaration scope.

The `SwiftWarningControl` library provides a utility to determine, for a given source location and diagnostic group identifier, whether or not its behavior is affected by an `@warn` attribute of any of its parent declaration scope.

This utility relies on constructing a warning control tree data structure to represent all warning control lexical scopes in a given source file. This data structure all of the `@warn` diagnostic group behavior controls within the given syntax node, indicating each group's active behavior at a given position.

For example, given code like the following:
```
1:  @warn(Deprecate, as: error)
2:  func foo() {
3:     let a = dep
4:     @warn(Deprecate, as: warning)
5:     func bar() {
6:         let b = dep
7:         @warn(Deprecate, as: ignored)
8:         func baz() {
9:           let c = dep
10:        }
11:        @warn(Deprecate, as: error)
12:        @warn(OtherGroup, as: ignored)
13:        func qux() {
14:            let d = dep
15:            @warn(SomeOtherGroup, as: warning)
16:            func corge() {
17:              let e = dep
18:            }
19:        }
20:     }
21: }
22: func grault() {
23:   let f = dep
24: }
```
the result will be:
```
  - [`Deprecate`:`error`] region within `foo` lexical scope (lines 1-22)
    - [`Deprecate`:`warning`] region within `bar` lexical scope (lines 4-20)
      - [`Deprecate`:`ignored`] region within `baz` lexical scope (lines 7-10)
      - [`Deprecate`:`error`, `OtherGroup`:`ignored`] region within `qux` lexical scope (lines 12-19)
        - [`SomeOtherGroup`:`warning`] region within `corge` lexical scope (lines 15-18)
```

The data structure represents these regions and their nesting relationships as an interval tree where interval nodes can only be nested or disjoint, and where a given interval corresponds to a diagnostic control region for one or more diagnostic group, with a behavior specifier for each.

Intervals cannot partially overlap, and each node's child intervals are always kept sorted. The tree has multiple top-level nodes (roots) representing file-level warning control regions.

Once the tree is computed, lookup of a diagnostic group behavior at a given position is performed by recursively descending into the child node containing the given position (located with a binary search of child nodes of a given parent node). Once the position's depth in the interval tree is reached, we walk back the traversal until we find the first containing region which specifies warning behavior control for the given diagnostic group id.

Author: artemcm

.spi.yml

@@ -18,6 +18,7 @@ builder:
         - SwiftParser
         - SwiftParserDiagnostics
         - SwiftRefactor
+        - SwiftWarningControl
         - SwiftSyntaxBuilder
         - SwiftSyntaxMacros
         - SwiftSyntaxMacroExpansion

Package.swift

@@ -29,6 +29,7 @@ if buildDynamicLibrary {
     .library(name: "SwiftDiagnostics", targets: ["SwiftDiagnostics"]),
     .library(name: "SwiftIDEUtils", targets: ["SwiftIDEUtils"]),
     .library(name: "SwiftIfConfig", targets: ["SwiftIfConfig"]),
+    .library(name: "SwiftWarningControl", targets: ["SwiftWarningControl"]),
     .library(name: "SwiftLexicalLookup", targets: ["SwiftLexicalLookup"]),
     .library(name: "SwiftOperators", targets: ["SwiftOperators"]),
     .library(name: "SwiftParser", targets: ["SwiftParser"]),
@@ -180,6 +181,24 @@ let package = Package(
       ]
     ),
 
+    // MARK: SwiftWarningControl
+
+    .target(
+      name: "SwiftWarningControl",
+      dependencies: ["SwiftSyntax", "SwiftParser"],
+      exclude: ["CMakeLists.txt"]
+    ),
+
+    .testTarget(
+      name: "SwiftWarningControlTest",
+      dependencies: [
+        "_SwiftSyntaxTestSupport",
+        "SwiftWarningControl",
+        "SwiftParser",
+        "SwiftSyntaxMacrosGenericTestSupport",
+      ]
+    ),
+
     // MARK: SwiftLexicalLookup
 
     .target(

Sources/CMakeLists.txt

@@ -24,4 +24,5 @@ add_subdirectory(SwiftSyntaxMacroExpansion)
 add_subdirectory(SwiftCompilerPluginMessageHandling)
 add_subdirectory(SwiftIDEUtils)
 add_subdirectory(SwiftCompilerPlugin)
+add_subdirectory(SwiftWarningControl)
 add_subdirectory(VersionMarkerModules)

Sources/SwiftWarningControl/CMakeLists.txt

@@ -0,0 +1,19 @@
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2014 - 2025 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See http://swift.org/LICENSE.txt for license information
+# See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+add_swift_syntax_library(SwiftWarningControl
+  WarningGroupBehavior.swift
+  WarningControlDeclSyntax.swift
+  WarningControlRegionBuilder.swift
+  WarningControlRegions.swift
+  SyntaxProtocol+WarningControl.swift
+)
+
+target_link_swift_syntax_libraries(SwiftWarningControl PUBLIC
+  SwiftSyntax
+  SwiftParser)

Sources/SwiftWarningControl/SwiftWarningControl.md

@@ -0,0 +1,30 @@
+# SwiftWarningControl
+
+A library to evaluate `@warn` diagnostic group controls within a Swift syntax tree.
+
+## Overview
+
+Swift provides a mechanism to control the behavior of specific diagnostic groups for a given declaration's lexical scope with the `@warn` attribute.
+
+The syntax tree and its parser do not reason about warning group controls. The syntax tree produced by the parser represents the `@warn` attribute in a generic fashion, as it would any other basic attribute on a declaration. The per-declaration nature of the attribute means that for any given lexical scope, the behavior of a given diagnostic group can be queried by checking for the presence of this attribute in its parent declaration scope. 
+
+```swift
+@warn(Deprecate, as: error)
+func foo() {
+  ...
+  @warn(Deprecate, as: warning)
+  func bar() {
+    ...
+    @warn("Deprecate", as: ignored, reason: "Foo")
+    func baz() {
+      ...
+    }
+  }
+}
+```
+
+The `SwiftWarningControl` library provides a utility to determine, for a given source location and diagnostic group identifier, whether or not its behavior is affected by an `@warn` attribute of any of its parent declaration scope. 
+
+* `SyntaxProtocol.getWarningGroupControl(for diagnosticGroupIdentifier:)` produces the behavior specifier (`WarningGroupBehavior`: `error`, `warning`, `ignored`) which applies at this node.
+
+* `SyntaxProtocol.warningGroupControlRegionTree` holds a computed `WarningControlRegionTree` data structure value that can be used to efficiently test for the specified `WarningGroupBehavior` at a given source location and a given diagnostic group.

Sources/SwiftWarningControl/SyntaxProtocol+WarningControl.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftDiagnostics
+import SwiftSyntax
+
+extension SyntaxProtocol {
+  /// Get the warning emission behavior for the specified diagnostic group
+  /// by determining its containing `WarningControlRegion`, if one is present.
+  @_spi(ExperimentalLanguageFeatures)
+  public func warningGroupBehavior(
+    for diagnosticGroupIdentifier: DiagnosticGroupIdentifier
+  ) -> WarningGroupBehavior? {
+    let warningControlRegions = root.warningGroupControlRegionTree
+    return warningControlRegions.warningGroupBehavior(at: self.position, for: diagnosticGroupIdentifier)
+  }
+}

Sources/SwiftWarningControl/WarningControlDeclSyntax.swift

@@ -0,0 +1,56 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+
+extension WithAttributesSyntax {
+  /// Compute a dictionary of all `@warn` diagnostic group behaviors
+  /// specified on this warning control declaration scope.
+  var allWarningGroupControls: [DiagnosticGroupIdentifier: WarningGroupBehavior] {
+    attributes.reduce(into: [DiagnosticGroupIdentifier: WarningGroupBehavior]()) { result, attr in
+      // `@warn` attributes
+      guard case .attribute(let attributeSyntax) = attr,
+        attributeSyntax.attributeName.as(IdentifierTypeSyntax.self)?.name.text == "warn"
+      else {
+        return
+      }
+
+      // First argument is the unquoted diagnostic group identifier
+      guard
+        let diagnosticGroupID = attributeSyntax.arguments?
+          .as(LabeledExprListSyntax.self)?.first?.expression
+          .as(DeclReferenceExprSyntax.self)?.baseName.text
+      else {
+        return
+      }
+
+      // Second argument is the `as: ` behavior specifier
+      guard
+        let asParamExprSyntax = attributeSyntax
+          .arguments?.as(LabeledExprListSyntax.self)?
+          .dropFirst().first
+      else {
+        return
+      }
+      guard
+        asParamExprSyntax.label?.text == "as",
+        let behaviorText = asParamExprSyntax
+          .expression.as(DeclReferenceExprSyntax.self)?
+          .baseName.text,
+        let behavior = WarningGroupBehavior(rawValue: behaviorText)
+      else {
+        return
+      }
+      result[DiagnosticGroupIdentifier(diagnosticGroupID)] = behavior
+    }
+  }
+}

Sources/SwiftWarningControl/WarningControlRegionBuilder.swift

@@ -0,0 +1,55 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+
+/// Compute the full set of warning control regions in this syntax node
+extension SyntaxProtocol {
+  @_spi(ExperimentalLanguageFeatures)
+  public var warningGroupControlRegionTree: WarningControlRegionTree {
+    let visitor = WarningControlRegionVisitor(range: self.range)
+    visitor.walk(self)
+    return visitor.tree
+  }
+}
+
+/// Add this warning control decl syntax node warning group controls (as specified with `@warn`)
+/// to the tree.
+extension WarningControlRegionTree {
+  mutating func addWarningControlRegions(for syntax: some WithAttributesSyntax) {
+    for control in syntax.allWarningGroupControls {
+      addWarningGroupControl(
+        range: syntax.range,
+        for: control.key,
+        behavior: control.value
+      )
+    }
+  }
+}
+
+/// Helper class that walks a syntax tree looking for warning behavior control regions.
+private class WarningControlRegionVisitor: SyntaxAnyVisitor {
+  /// The tree of warning control regions we have found so far
+  var tree: WarningControlRegionTree
+
+  init(range: Range<AbsolutePosition>) {
+    self.tree = WarningControlRegionTree(range: range)
+    super.init(viewMode: .fixedUp)
+  }
+
+  override func visitAny(_ node: Syntax) -> SyntaxVisitorContinueKind {
+    if let withAttributesSyntax = node.asProtocol(WithAttributesSyntax.self) {
+      tree.addWarningControlRegions(for: withAttributesSyntax)
+    }
+    return .visitChildren
+  }
+}