always outline external links

Author: tayloraswift

Sources/MarkdownRendering/HTML/HTML.OutputStreamableMarkdown.swift

@@ -20,9 +20,13 @@ protocol _HTMLOutputStreamableMarkdown:HTML.OutputStreamable
     /// Returns the value for an attribute identified by the given reference.
     /// If the witness returns nil, the renderer will omit the attribute.
     ///
+    /// The witness can change the attribute that will be rendered by modifying the argument.
+    /// This is useful for replacing ``Markdown.Bytecode.Attribute/href`` with
+    /// ``Markdown.Bytecode.Attribute/external``
+    ///
     /// This can be used to influence the behavior of the special syntax
     /// highlight contexts.
-    func load(_ reference:Int, for attribute:Markdown.Bytecode.Attribute) -> String?
+    func load(_ reference:Int, for attribute:inout Markdown.Bytecode.Attribute) -> String?
 
     /// Writes arbitrary content to the provided HTML output, identified by
     /// the given reference.
@@ -32,7 +36,7 @@ extension HTML.OutputStreamableMarkdown
 {
     /// Returns nil.
     @inlinable public
-    func load(_ reference:Int, for attribute:Markdown.Bytecode.Attribute) -> String?
+    func load(_ reference:Int, for attribute:inout Markdown.Bytecode.Attribute) -> String?
     {
         nil
     }
@@ -83,10 +87,10 @@ extension HTML.OutputStreamableMarkdown
             case .attribute(let attribute, nil):
                 attributes.flush(beginning: attribute)
 
-            case .attribute(let attribute, let reference?):
+            case .attribute(var attribute, let reference?):
                 attributes.flush()
 
-                if  let value:String = self.load(reference, for: attribute)
+                if  let value:String = self.load(reference, for: &attribute)
                 {
                     attributes.list.append(value: value, as: attribute)
                 }

Sources/SwiftinitPages/Sections/CodeSection.swift

@@ -22,7 +22,7 @@ struct CodeSection
 }
 extension CodeSection:HTML.OutputStreamableMarkdown
 {
-    func load(_ reference:Int, for attribute:Markdown.Bytecode.Attribute) -> String?
+    func load(_ reference:Int, for attribute:inout Markdown.Bytecode.Attribute) -> String?
     {
         switch attribute
         {

Sources/SwiftinitPages/Sections/ProseSection.swift

@@ -32,7 +32,7 @@ extension ProseSection
 }
 extension ProseSection:HTML.OutputStreamableMarkdown
 {
-    func load(_ reference:Int, for attribute:Markdown.Bytecode.Attribute) -> String?
+    func load(_ reference:Int, for attribute:inout Markdown.Bytecode.Attribute) -> String?
     {
         guard self.outlines.indices.contains(reference)
         else
@@ -45,6 +45,23 @@ extension ProseSection:HTML.OutputStreamableMarkdown
         case .text(let text):
             return text
 
+        case .link(https: let url, safe: let safe):
+            switch attribute
+            {
+            case .href:
+                if !safe
+                {
+                    attribute = .external
+                }
+                fallthrough
+
+            case .external:
+                return "https://\(url)"
+
+            default:
+                return nil
+            }
+
         case .path(_, let scalars):
             guard
             let target:Unidoc.Scalar = scalars.last
@@ -84,6 +101,10 @@ extension ProseSection:HTML.OutputStreamableMarkdown
 
         switch self.outlines[reference]
         {
+        case .link:
+            //  No reason this should ever appear here.
+            return
+
         case .text(let text):
             html[.code] = text
 
@@ -114,6 +135,10 @@ extension ProseSection:TextOutputStreamableMarkdown
         }
         switch self.outlines[reference]
         {
+        case .link:
+            //  No reason this should ever appear here.
+            return
+
         case .text(let text):
             utf8 += text.utf8
 

Sources/UnidocLinker/Resolver/Unidoc.Resolver.swift

@@ -110,6 +110,29 @@ extension Unidoc.Resolver
             }
 
         case    .unresolved(let unresolved):
+            if  case .web = unresolved.type
+            {
+                let domain:Substring = unresolved.link.prefix { $0 != "/" }
+                //  We will follow links to Apple, GitHub, and reputable open-source indexes.
+                let safe:Bool = switch domain
+                {
+                case "developer.apple.com":     true
+                case "www.freebsd.org":         true
+                case "github.com":              true
+                case "tools.ietf.org":          true
+                case "man7.org":                true
+                case "developer.mozilla.org":   true
+                case "docs.scala-lang.org":     true
+                case "swiftinit.org":           true
+                case "forums.swift.org":        true
+                case "swift.org":               true
+                case "en.wikipedia.org":        true
+                default:                        false
+                }
+
+                return .link(https: unresolved.link, safe: safe)
+            }
+
             guard
             let (codelink, resolution):
                 (Codelink, CodelinkResolver<Unidoc.Scalar>.Overload.Target?) =

Sources/UnidocRecords/Volumes/Passages/Unidoc.Outline.swift

@@ -6,6 +6,8 @@ extension Unidoc
     @frozen public
     enum Outline:Equatable, Sendable
     {
+        /// An external web link. The string does not contain the URL scheme.
+        case link(https:String, safe:Bool)
         case path(String, [Unidoc.Scalar])
         case text(String)
     }
@@ -15,6 +17,8 @@ extension Unidoc.Outline
     @frozen public
     enum CodingKey:String, Sendable
     {
+        case link_safe = "H"
+        case link_url = "U"
         case display = "T"
         case scalars = "s"
     }
@@ -26,6 +30,10 @@ extension Unidoc.Outline:BSONDocumentEncodable
     {
         switch self
         {
+        case .link(https: let url, let safe):
+            bson[.link_safe] = safe ? true : nil
+            bson[.link_url] = url
+
         case .path(let string, let scalars):
             bson[.scalars] = scalars
             bson[.display] = string
@@ -40,11 +48,18 @@ extension Unidoc.Outline:BSONDocumentDecodable
     @inlinable public
     init(bson:BSON.DocumentDecoder<CodingKey>) throws
     {
-        let display:String = try bson[.display].decode()
-        switch try bson[.scalars]?.decode(to: [Unidoc.Scalar].self)
+        if  let display:String = try bson[.display]?.decode()
+        {
+            switch try bson[.scalars]?.decode(to: [Unidoc.Scalar].self)
+            {
+            case let scalars?:  self = .path(display, scalars)
+            case nil:           self = .text(display)
+            }
+        }
+        else
         {
-        case let scalars?:  self = .path(display, scalars)
-        case nil:           self = .text(display)
+            self = .link(https: try bson[.link_url].decode(),
+                safe: try bson[.link_safe]?.decode() ?? false)
         }
     }
 }