track @_spi ness of declarations, and display the warning on the doc pages

Author: tayloraswift

Assets/css/Main.css

@@ -12,16 +12,23 @@ struct Signature<Scalar>:Equatable where Scalar:Hashable
     public
     var generics:Generics
 
+    /// Empty array means the declaration is gated by an SPI, but SymbolGraphGen doesn't know
+    /// which one.
+    public
+    var spis:[String]?
+
     @inlinable public
     init(availability:Availability = .init(),
         abridged:Abridged = .init(),
         expanded:Expanded = .init(),
-        generics:Generics = .init())
+        generics:Generics = .init(),
+        spis:[String]? = nil)
     {
         self.availability = availability
         self.expanded = expanded
         self.abridged = abridged
         self.generics = generics
+        self.spis = spis
     }
 }
 extension Signature:Sendable where Scalar:Sendable
@@ -35,6 +42,7 @@ extension Signature
         .init(availability: self.availability,
             abridged: .init(bytecode: self.abridged.bytecode),
             expanded: try self.expanded.map(transform),
-            generics: try self.generics.map(transform))
+            generics: try self.generics.map(transform),
+            spis: self.spis)
     }
 }

Assets/css/Main.css.map

@@ -94,15 +94,15 @@ enum Main:SyncTests
             let part:SymbolGraphPart = tests.load(
                 part: "TestModules/Symbolgraphs/SPI.symbols.json")
         {
-            for (symbol, interfaces):([String], SymbolDescription.Interfaces?) in
+            for (symbol, interfaces):([String], [String]?) in
             [
                 (["NoSPI"], nil),
-                (["SPI"], .init()),
+                (["SPI"], []),
             ]
             {
                 if  let symbol:SymbolDescription = tests.expect(symbol: symbol, in: part)
                 {
-                    tests.expect(symbol.interfaces ==? interfaces)
+                    tests.expect(symbol.signature.spis ==? interfaces)
                 }
             }
         }

Sources/Signatures/Signatures/Signature.swift

@@ -17,8 +17,6 @@ struct SymbolDescription:Equatable, Sendable
     public
     let doccomment:Doccomment?
     public
-    let interfaces:Interfaces?
-    public
     let visibility:Visibility
     public
     let `extension`:ExtensionContext
@@ -36,15 +34,13 @@ struct SymbolDescription:Equatable, Sendable
     init(_ usr:Symbol,
         phylum:Unidoc.Phylum,
         doccomment:Doccomment?,
-        interfaces:Interfaces?,
         visibility:Visibility,
         extension:ExtensionContext,
         signature:Signature<Symbol.Decl>,
         location:SourceLocation<String>?,
         path:UnqualifiedPath)
     {
         self.doccomment = doccomment
-        self.interfaces = interfaces
         self.visibility = visibility
         self.extension = `extension`
         self.signature = signature
@@ -94,11 +90,12 @@ extension SymbolDescription
         }
 
         //  SymbolGraphGen incorrectly prints the fragment as 'class' in
-        //  the abridged signature
+        //  the abridged signature.
         let signature:Signature<Symbol.Decl> = .init(availability: availability,
             abridged: .init(abridged, actor: phylum == .decl(.actor)),
             expanded: expanded,
-            generics: generics)
+            generics: generics,
+            spis: interfaces.map { _ in [] })
 
         //  strip empty parentheses from last path component
         let simplified:UnqualifiedPath
@@ -117,7 +114,6 @@ extension SymbolDescription
         self.init(usr,
             phylum: phylum,
             doccomment: doccomment.flatMap { $0.text.isEmpty ? nil : $0 },
-            interfaces: interfaces,
             visibility: visibility,
             extension: `extension`,
             signature: signature,

Sources/SymbolGraphPartTests/Main.swift

@@ -109,6 +109,7 @@ extension SymbolGraph.Decl
         case signature_expanded_scalars = "K"
         case signature_generics_constraints = "C"
         case signature_generics_parameters = "G"
+        case signature_spis = "I"
 
         case requirements = "R"
         case superforms = "S"
@@ -150,6 +151,9 @@ extension SymbolGraph.Decl:BSONDocumentEncodable
             self.signature.generics.parameters.isEmpty ? nil :
             self.signature.generics.parameters
 
+        /// Do *not* elide empty SPI arrays!
+        bson[.signature_spis] = self.signature.spis
+
         bson[.requirements] = SymbolGraph.Buffer.init(elidingEmpty: self.requirements)
         bson[.superforms] = SymbolGraph.Buffer.init(elidingEmpty: self.superforms)
         bson[.features] = SymbolGraph.Buffer.init(elidingEmpty: self.features)
@@ -182,7 +186,8 @@ extension SymbolGraph.Decl:BSONDocumentDecodable
                     scalars: try bson[.signature_expanded_scalars]?.decode() ?? []),
                 generics: Signature<Int32>.Generics.init(
                     constraints: try bson[.signature_generics_constraints]?.decode() ?? [],
-                    parameters: try bson[.signature_generics_parameters]?.decode() ?? [])),
+                    parameters: try bson[.signature_generics_parameters]?.decode() ?? []),
+                spis: try bson[.signature_spis]?.decode()),
 
             location: try bson[.location]?.decode(),
             article: try bson[.article]?.decode(),

Sources/SymbolGraphParts/Descriptions/SymbolDescription.swift

@@ -141,6 +141,16 @@ extension Site.Docs.Decl:ApplicationPage
             }
         }
 
+        if  let _:[String] = self.master.signature.spis
+        {
+            main[.section, { $0.class = "spi" }]
+            {
+                $0[.p] = """
+                This declaration is gated by at least one @_spi attribute.
+                """
+            }
+        }
+
         let availability:Availability = self.master.signature.availability
         if  let notice:String = availability.notice
         {

Sources/SymbolGraphs/Declarations/Availability.CodingKeys.swift renamed to Sources/SymbolGraphs/Declarations/Availability.CodingKey.swift

@@ -136,7 +136,7 @@ extension Volume.Master
         /// This field is cheap (64-bit integer plus 3 bytes of keying overhead) and
         /// allows us to reuse compound indices for zone-bound queries by performing
         /// an equality match instead of a range match.
-        case zone = "I"
+        case zone = "Z"
 
         /// Appears in ``Decl`` and ``File``.
         case symbol = "Y"
@@ -161,7 +161,7 @@ extension Volume.Master
         case module = "M"
 
         /// Only appears in ``Decl``.
-        case flags = "Z"
+        case flags = "F"
         /// Only appears in ``Decl``.
         case signature_availability = "A"
         /// Only appears in ``Decl``.
@@ -175,6 +175,8 @@ extension Volume.Master
         case signature_generics_constraints = "g"
         /// Only appears in ``Decl``.
         case signature_generics_parameters = "G"
+        /// Only appears in ``Decl``.
+        case signature_spis = "I"
         /// Only appears in ``Decl``. The field contains a list of scalars.
         case requirements = "r"
         /// Only appears in ``Decl``. The field contains a list of scalars.
@@ -269,6 +271,8 @@ extension Volume.Master:BSONDocumentEncodable
                 self.signature.generics.parameters.isEmpty ? nil :
                 self.signature.generics.parameters
 
+            bson[.signature_spis] = self.signature.spis
+
             bson[.stem] = self.stem
 
             bson[.requirements] = self.requirements.isEmpty ? nil : self.requirements
@@ -359,7 +363,8 @@ extension Volume.Master:BSONDocumentDecodable
                         scalars: try bson[.signature_expanded_scalars]?.decode() ?? []),
                     generics: Signature<Unidoc.Scalar?>.Generics.init(
                         constraints: try bson[.signature_generics_constraints]?.decode() ?? [],
-                        parameters: try bson[.signature_generics_parameters]?.decode() ?? [])),
+                        parameters: try bson[.signature_generics_parameters]?.decode() ?? []),
+                    spis: try bson[.signature_spis]?.decode()),
                 symbol: try bson[.symbol].decode(),
                 stem: try bson[.stem].decode(),
                 requirements: try bson[.requirements]?.decode() ?? [],

Sources/SymbolGraphs/Declarations/SymbolGraph.Decl.swift

@@ -15,6 +15,8 @@ $light-snippet-line-number: rgb(192, 192, 192);
 $light-swift: rgb(134, 134, 134);
 $light-accent-comment: $light-foreground-semi;
 $light-accent-barbie-pink: rgb(255, 86, 158);
+$light-accent-barbie-pink-shadow: rgb(209, 23, 104);
+
 $light-accent-hot-pink: rgb(253, 39, 110);
 $light-accent-yellow: rgb(255, 123, 0);
 $light-accent-lavender: rgb(189, 108, 255);