implement autograph-based link disambiguation

tayloraswift · tayloraswift · commit 5d33d3d8bef2 · 2024-12-26T03:21:33.000Z
diff --git a/Package.swift b/Package.swift
@@ -415,6 +415,7 @@ let package:Package = .init(
         .target(name: "SymbolGraphParts",
             dependencies: [
                 .target(name: "LexicalPaths"),
+                .target(name: "LinkResolution"),
                 //  This is the point where the symbol graph compiler becomes infected with a
                 //  (non-macro) SwiftSyntax dependency.
                 //
diff --git a/Sources/LinkResolution/UCF.Autograph.swift b/Sources/LinkResolution/UCF.Autograph.swift
@@ -0,0 +1,75 @@
+import UCF
+
+extension UCF
+{
+    @frozen public
+    struct Autograph:Equatable, Sendable
+    {
+        public
+        let inputs:[String]
+        public
+        let output:[String]
+
+        @inlinable public
+        init(inputs:[String], output:[String])
+        {
+            self.inputs = inputs
+            self.output = output
+        }
+    }
+}
+extension UCF.Autograph
+{
+    static func ~= (predicate:UCF.PatternFilter, self:Self) -> Bool
+    {
+        if  let inputs:[String?] = predicate.inputs
+        {
+            guard self.inputs.count == inputs.count
+            else
+            {
+                return false
+            }
+            for case (let required, let provided?) in zip(self.inputs, inputs)
+            {
+                if  required != provided
+                {
+                    return false
+                }
+            }
+        }
+
+        switch predicate.output
+        {
+        case nil:
+            break
+
+        case .single(let output):
+            guard self.output.count == 1
+            else
+            {
+                return false
+            }
+
+            if  let output:String, output != self.output[0]
+            {
+                return false
+            }
+
+        case .tuple(let outputs):
+            guard self.output.count == outputs.count
+            else
+            {
+                return false
+            }
+            for case (let required, let provided?) in zip(self.output, outputs)
+            {
+                if  required != provided
+                {
+                    return false
+                }
+            }
+        }
+
+        return true
+    }
+}
diff --git a/Sources/LinkResolution/UCF.CausalOverload.swift b/Sources/LinkResolution/UCF.CausalOverload.swift
@@ -18,19 +18,23 @@ extension UCF
 
         public
         let documented:Bool
+        public
+        let autograph:Autograph?
 
         @inlinable public
         init(phylum:Phylum.Decl,
             decl:Symbol.Decl,
             heir:Symbol.Decl?,
             hash:FNV24,
-            documented:Bool)
+            documented:Bool,
+            autograph:Autograph?)
         {
             self.phylum = phylum
             self.decl = decl
             self.heir = heir
             self.hash = hash
             self.documented = documented
+            self.autograph = autograph
         }
     }
 }
diff --git a/Sources/LinkResolution/UCF.PackageOverload.swift b/Sources/LinkResolution/UCF.PackageOverload.swift
@@ -18,6 +18,8 @@ extension UCF
 
         public
         let documented:Bool
+        public
+        let autograph:Autograph?
         /// Used for display purposes. This is not necessarily the symbol from which the
         /// ``hash`` was computed.
         public
@@ -29,13 +31,15 @@ extension UCF
             heir:Int32?,
             hash:FNV24,
             documented:Bool,
+            autograph:Autograph?,
             id:Symbol.Decl)
         {
             self.phylum = phylum
             self.decl = decl
             self.heir = heir
             self.hash = hash
             self.documented = documented
+            self.autograph = autograph
             self.id = id
         }
     }
diff --git a/Sources/LinkResolution/UCF.ResolvableOverload.swift b/Sources/LinkResolution/UCF.ResolvableOverload.swift
@@ -7,6 +7,7 @@ extension UCF
     public
     protocol ResolvableOverload:Identifiable<Symbol.Decl>, Sendable
     {
+        var autograph:Autograph? { get }
         var phylum:Phylum.Decl { get }
         var hash:FNV24 { get }
 
@@ -71,12 +72,27 @@ extension UCF.ResolvableOverload
 
         switch suffix
         {
-        case .legacy(let filter, nil):      return filter ~= self.phylum
-        case .legacy(_, let hash?):         return hash == self.hash
-        case .hash(let hash):               return hash == self.hash
-        case .filter(let filter):           return filter ~= self.phylum
-        //  TODO: unimplemented
-        case .pattern:                      return true
+        case .legacy(let filter, nil):
+            return filter ~= self.phylum
+
+        case .legacy(_, let hash?):
+            return hash == self.hash
+
+        case .hash(let hash):
+            return hash == self.hash
+
+        case .filter(let filter):
+            return filter ~= self.phylum
+
+        case .pattern(let pattern):
+            if  let autograph:UCF.Autograph = self.autograph
+            {
+                return pattern ~= autograph
+            }
+            else
+            {
+                return false
+            }
         }
     }
 }
diff --git a/Sources/SymbolGraphCompiler/Declarations/SSGC.Decl.swift b/Sources/SymbolGraphCompiler/Declarations/SSGC.Decl.swift
@@ -1,9 +1,11 @@
 import Availability
+import LinkResolution
 import LexicalPaths
 import Signatures
 import Sources
 import SymbolGraphParts
 import Symbols
+import UCF
 
 extension SSGC
 {
@@ -17,6 +19,8 @@ extension SSGC
         public
         let signature:Signature<Symbol.Decl>
         public
+        let autograph:UCF.Autograph?
+        public
         let location:SourceLocation<Symbol.File>?
 
         public
@@ -58,6 +62,7 @@ extension SSGC
 
         init(id:Symbol.Decl,
             signature:Signature<Symbol.Decl>,
+            autograph:UCF.Autograph?,
             location:SourceLocation<Symbol.File>?,
             phylum:Phylum.Decl,
             path:UnqualifiedPath,
@@ -67,6 +72,7 @@ extension SSGC
             self.id = id
 
             self.signature = signature
+            self.autograph = autograph
             self.location = location
             self.phylum = phylum
             self.path = path
diff --git a/Sources/SymbolGraphCompiler/Declarations/SSGC.Declarations.swift b/Sources/SymbolGraphCompiler/Declarations/SSGC.Declarations.swift
@@ -80,6 +80,7 @@ extension SSGC.Declarations
                 access: vertex.acl,
                 value: .init(id: symbol,
                     signature: vertex.signature,
+                    autograph: vertex.autograph,
                     location: vertex.location,
                     phylum: phylum,
                     path: vertex.path,
diff --git a/Sources/SymbolGraphCompiler/Extensions/SSGC.ModuleIndex.Feature.swift b/Sources/SymbolGraphCompiler/Extensions/SSGC.ModuleIndex.Feature.swift
@@ -1,5 +1,7 @@
 import LexicalPaths
+import LinkResolution
 import Symbols
+import UCF
 
 extension SSGC.ModuleIndex
 {
@@ -13,19 +15,28 @@ extension SSGC.ModuleIndex
         let path:UnqualifiedPath
         public
         let documented:Bool
+        public
+        let autograph:UCF.Autograph?
 
-        init(phylum:Phylum.Decl, path:UnqualifiedPath, documented:Bool)
+        init(phylum:Phylum.Decl,
+            path:UnqualifiedPath,
+            documented:Bool,
+            autograph:UCF.Autograph?)
         {
             self.phylum = phylum
             self.path = path
             self.documented = documented
+            self.autograph = autograph
         }
     }
 }
 extension SSGC.ModuleIndex.Feature
 {
     init(from decl:borrowing SSGC.Decl)
     {
-        self.init(phylum: decl.phylum, path: decl.path, documented: decl.comment != nil)
+        self.init(phylum: decl.phylum,
+            path: decl.path,
+            documented: decl.comment != nil,
+            autograph: decl.autograph)
     }
 }
diff --git a/Sources/SymbolGraphCompiler/UCF.CausalOverload (ext).swift b/Sources/SymbolGraphCompiler/UCF.CausalOverload (ext).swift
@@ -10,7 +10,8 @@ extension UCF.CausalOverload
             decl: decl.id,
             heir: heir,
             hash: .decl(.init(decl.id, self: heir)),
-            documented: decl.comment != nil)
+            documented: decl.comment != nil,
+            autograph: decl.autograph)
     }
     static
     func decl(_ decl:SSGC.Decl) -> Self
@@ -19,6 +20,7 @@ extension UCF.CausalOverload
             decl: decl.id,
             heir: nil,
             hash: .decl(decl.id),
-            documented: decl.comment != nil)
+            documented: decl.comment != nil,
+            autograph: decl.autograph)
     }
 }
diff --git a/Sources/SymbolGraphLinker/SSGC.Linker.swift b/Sources/SymbolGraphLinker/SSGC.Linker.swift
@@ -239,6 +239,7 @@ extension SSGC.Linker
                         heir: nil,
                         hash: hash,
                         documented: decl.comment != nil,
+                        autograph: decl.autograph,
                         id: decl.id))
                     //  Assign the decl a URI, and record the decl’s hash
                     //  so we will know if it has a hash collision.
@@ -337,6 +338,7 @@ extension SSGC.Linker
                     heir: extendee,
                     hash: .decl(.init(id, self: $0.extendee.id)),
                     documented: feature.documented,
+                    autograph: feature.autograph,
                     id: id)
 
                 self.tables.packageLinks[namespace, $0.extendee.path, feature.path.last]
diff --git a/Sources/SymbolGraphLinkerTests/Main.LinkResolution.swift b/Sources/SymbolGraphLinkerTests/Main.LinkResolution.swift
@@ -33,6 +33,7 @@ extension Main.LinkResolution:TestBattery
                 heir: nil,
                 hash: .init(hashing: "x"),
                 documented: true,
+                autograph: nil,
                 id: "x"))
 
             tables.packageLinks["ThisModule", .init(["A"], "c")].append(.init(
@@ -41,6 +42,7 @@ extension Main.LinkResolution:TestBattery
                 heir: nil,
                 hash: .init(hashing: "y"),
                 documented: true,
+                autograph: nil,
                 id: "y"))
 
             if  let tests:TestGroup = tests / "Unscoped"
@@ -95,6 +97,7 @@ extension Main.LinkResolution:TestBattery
                 heir: nil,
                 hash: .init(hashing: "x"),
                 documented: true,
+                autograph: nil,
                 id: "x"))
 
             tables.packageLinks["OtherModule", .init(["A"], "c")].append(.init(
@@ -103,6 +106,7 @@ extension Main.LinkResolution:TestBattery
                 heir: nil,
                 hash: .init(hashing: "y"),
                 documented: true,
+                autograph: nil,
                 id: "y"))
 
             if  let tests:TestGroup = tests / "Unscoped"
diff --git a/Sources/SymbolGraphParts/Vertices/SymbolGraphPart.Vertex.swift b/Sources/SymbolGraphParts/Vertices/SymbolGraphPart.Vertex.swift
@@ -1,10 +1,12 @@
 import Availability
 import JSONDecoding
 import LexicalPaths
+import LinkResolution
 import MarkdownPluginSwift
 import Signatures
 import Sources
 import Symbols
+import UCF
 
 extension SymbolGraphPart
 {
@@ -25,6 +27,8 @@ extension SymbolGraphPart
         public
         let signature:Signature<Symbol.Decl>
         public
+        let autograph:UCF.Autograph?
+        public
         let path:UnqualifiedPath
 
         public
@@ -42,6 +46,7 @@ extension SymbolGraphPart
             final:Bool,
             extension:ExtensionContext,
             signature:Signature<Symbol.Decl>,
+            autograph:UCF.Autograph?,
             path:UnqualifiedPath,
             doccomment:Doccomment?,
             location:SourceLocation<Symbol.File>?)
@@ -52,6 +57,7 @@ extension SymbolGraphPart
             self.final = final
             self.extension = `extension`
             self.signature = signature
+            self.autograph = autograph
             self.path = path
             self.doccomment = doccomment
             self.location = location
@@ -128,6 +134,17 @@ extension SymbolGraphPart.Vertex
             generics: generics,
             spis: interfaces.map { _ in [] })
 
+        let autograph:UCF.Autograph?
+
+        if  case .decl(let decl) = phylum, decl.isDirectlyOverloadable
+        {
+            autograph = .init(inputs: landmarks.inputs, output: landmarks.output)
+        }
+        else
+        {
+            autograph = nil
+        }
+
         //  strip empty parentheses from last path component
         let simplified:UnqualifiedPath
         if  let index:String.Index = path.last.index(path.last.endIndex,
@@ -150,6 +167,7 @@ extension SymbolGraphPart.Vertex
             final: landmarks.keywords.final,
             extension: `extension`,
             signature: signature,
+            autograph: autograph,
             path: simplified,
             doccomment: doccomment.flatMap { $0.text.isEmpty ? nil : $0 },
             location: location)
diff --git a/Sources/Symbols/Declarations/Phylum.Decl.swift b/Sources/Symbols/Declarations/Phylum.Decl.swift
diff --git a/Sources/UCF/Codelinks/UCF.PatternFilter.Identifier.swift b/Sources/UCF/Codelinks/UCF.PatternFilter.Identifier.swift
diff --git a/Sources/UCF/Codelinks/UCF.PatternFilter.Output.swift b/Sources/UCF/Codelinks/UCF.PatternFilter.Output.swift
diff --git a/Sources/UCF/Codelinks/UCF.PatternFilter.swift b/Sources/UCF/Codelinks/UCF.PatternFilter.swift
diff --git a/Sources/UCFTests/UCF.PatternFilter.Identifier (ext).swift b/Sources/UCFTests/UCF.PatternFilter.Identifier (ext).swift

Original file line number	Diff line number	Diff line change
`@@ -18,19 +18,23 @@ extension UCF`
`18`	`18`
`19`	`19`	`public`
`20`	`20`	`let documented:Bool`
	`21`	`+ public`
	`22`	`+ let autograph:Autograph?`
`21`	`23`
`22`	`24`	`@inlinable public`
`23`	`25`	`init(phylum:Phylum.Decl,`
`24`	`26`	`decl:Symbol.Decl,`
`25`	`27`	`heir:Symbol.Decl?,`
`26`	`28`	`hash:FNV24,`
`27`		`- documented:Bool)`
	`29`	`+ documented:Bool,`
	`30`	`+ autograph:Autograph?)`
`28`	`31`	`{`
`29`	`32`	`self.phylum = phylum`
`30`	`33`	`self.decl = decl`
`31`	`34`	`self.heir = heir`
`32`	`35`	`self.hash = hash`
`33`	`36`	`self.documented = documented`
	`37`	`+ self.autograph = autograph`
`34`	`38`	`}`
`35`	`39`	`}`
`36`	`40`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`import LexicalPaths`
	`2`	`+import LinkResolution`
`2`	`3`	`import Symbols`
	`4`	`+import UCF`
`3`	`5`
`4`	`6`	`extension SSGC.ModuleIndex`
`5`	`7`	`{`
`@@ -13,19 +15,28 @@ extension SSGC.ModuleIndex`
`13`	`15`	`let path:UnqualifiedPath`
`14`	`16`	`public`
`15`	`17`	`let documented:Bool`
	`18`	`+ public`
	`19`	`+ let autograph:UCF.Autograph?`
`16`	`20`
`17`		`- init(phylum:Phylum.Decl, path:UnqualifiedPath, documented:Bool)`
	`21`	`+ init(phylum:Phylum.Decl,`
	`22`	`+ path:UnqualifiedPath,`
	`23`	`+ documented:Bool,`
	`24`	`+ autograph:UCF.Autograph?)`
`18`	`25`	`{`
`19`	`26`	`self.phylum = phylum`
`20`	`27`	`self.path = path`
`21`	`28`	`self.documented = documented`
	`29`	`+ self.autograph = autograph`
`22`	`30`	`}`
`23`	`31`	`}`
`24`	`32`	`}`
`25`	`33`	`extension SSGC.ModuleIndex.Feature`
`26`	`34`	`{`
`27`	`35`	`init(from decl:borrowing SSGC.Decl)`
`28`	`36`	`{`
`29`		`- self.init(phylum: decl.phylum, path: decl.path, documented: decl.comment != nil)`
	`37`	`+ self.init(phylum: decl.phylum,`
	`38`	`+ path: decl.path,`
	`39`	`+ documented: decl.comment != nil,`
	`40`	`+ autograph: decl.autograph)`
`30`	`41`	`}`
`31`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,8 @@ extension UCF.CausalOverload`
`10`	`10`	`decl: decl.id,`
`11`	`11`	`heir: heir,`
`12`	`12`	`hash: .decl(.init(decl.id, self: heir)),`
`13`		`- documented: decl.comment != nil)`
	`13`	`+ documented: decl.comment != nil,`
	`14`	`+ autograph: decl.autograph)`
`14`	`15`	`}`
`15`	`16`	`static`
`16`	`17`	`func decl(_ decl:SSGC.Decl) -> Self`
`@@ -19,6 +20,7 @@ extension UCF.CausalOverload`
`19`	`20`	`decl: decl.id,`
`20`	`21`	`heir: nil,`
`21`	`22`	`hash: .decl(decl.id),`
`22`		`- documented: decl.comment != nil)`
	`23`	`+ documented: decl.comment != nil,`
	`24`	`+ autograph: decl.autograph)`
`23`	`25`	`}`
`24`	`26`	`}`