Snippet isn't consistently being recognized

[heckj]

Description

I've been working to add the use of snippets to several projects, and one of them - swift-metrics - has the snippets, they're compiling, symbol graphs exist, but the @snippet directive is reporting an error attempting to read it.

The issue appears to be a regression specifically in release/6.2 - and works with both earlier versions (release/6.1, and the current main branch).

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

The command I'm using:

swift package --disable-sandbox plugin --allow-writing-to-package-directory preview-documentation --target CoreMetrics --verbose:

output:

Building for debugging...
[1/1] Write swift-version-53407C18AB967AC9.txt
Build of product 'snippet-extract' complete! (0.10s)
symbol graph options: 'SymbolGraphOptions(minimumAccessLevel: PackagePlugin.PackageManager.SymbolGraphOptions.AccessLevel.public, includeSynthesized: true, includeSPI: false, emitExtensionBlocks: true)'
Building for debugging...
[1/1] Write swift-version-53407C18AB967AC9.txt
Build of target: 'CoreMetrics' complete! (0.10s)
target symbol graph directory path: '/Users/joeheck/src/swift-metrics/.build/arm64-apple-macosx/extracted-symbols/swift-metrics/CoreMetrics'
snippet extractor provided, attempting to generate snippet symbol graph
snippet symbol graph file: '/Users/joeheck/src/swift-metrics/.build/plugins/Swift-DocC Preview/outputs/.build/symbol-graphs/snippet-symbol-graphs/swift-metrics-swift-metrics/swift-metrics-snippets.symbols.json'
unified symbol graphs directory path: '/Users/joeheck/src/swift-metrics/.build/plugins/Swift-DocC Preview/outputs/.build/symbol-graphs/unified-symbol-graphs/CoreMetrics-3'
docc invocation: '/Applications/Xcode-26beta6.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc preview /Users/joeheck/src/swift-metrics/Sources/CoreMetrics/Docs.docc --emit-lmdb-index --fallback-display-name CoreMetrics --fallback-bundle-identifier CoreMetrics --additional-symbol-graph-dir /Users/joeheck/src/swift-metrics/.build/plugins/Swift-DocC Preview/outputs/.build/symbol-graphs/unified-symbol-graphs/CoreMetrics-3 --output-path /Users/joeheck/src/swift-metrics/.build/plugins/Swift-DocC Preview/outputs/CoreMetrics.doccarchive'
Input: /Users/joeheck/src/swift-metrics/Sources/CoreMetrics/Docs.docc
Template: /Applications/Xcode-26beta6.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
warning: 'swift-metrics' doesn't exist at '/CoreMetrics'
  --> index.md:42:3-42:16
40 |
41 | something here \\/
42 + @Snippet(path: "swift-metrics/Snippets/basics")
   |   ╰─suggestion: Replace 'swift-metrics' with 'Swift-Metrics-Extras'
43 | something there /\
44 |

========================================
Starting Local Preview Server
	 Address: http://localhost:8080/documentation/coremetrics
========================================
Monitoring /Users/joeheck/src/swift-metrics/Sources/CoreMetrics/Docs.docc for changes...

Actual behavior

The snippet isn't showing

Steps To Reproduce

git clone -b snippets https://github.com/heckj/swift-metrics
cd swift-metrics
swift package --disable-sandbox plugin --allow-writing-to-package-directory preview-documentation --target CoreMetrics --verbose

Swift-DocC Version Information

Swift 6.2

Swift Compiler Version Information

swift-driver version: 1.127.14.1 Apple Swift version 6.2 (swiftlang-6.2.0.19.9 clang-1700.3.19.1)
Target: arm64-apple-macosx26.0

[heckj]

Verifying against main branch:

export DOCC_EXEC=/Users/joeheck/src/swift-project/swift-docc/.build/debug/docc
export DOCC_HTML_DIR=/Users/joeheck/src/swift-project/swift-docc-render/dist
swift package --disable-sandbox plugin --allow-writing-to-package-directory preview-documentation --target CoreMetrics --verbose

^ Does NOT exhibit the same issue with main

[heckj]

Verified it does happen when docc is built from the branch release/6.2, release/6.2.0, and release/6.2.1 - all of which terminate at commit 558118d

[heckj]

Verified it works correctly with release/6.1

[heckj]

I tracked back through the 6.2 release branch commits from where it branched from main, and while I found the breaking location, the reason isn't entirely clear.

log:

git log main..release/6.2 --no-decorate

(ISSUE EXHIBITS)
commit 558118debe39d878012b985ffd76f558ff6a0a35
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Tue Aug 5 13:38:28 2025 +0200

commit 599ccba2f95466898da7dc64d07b21a5a8b478ba
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Fri Jun 27 14:11:27 2025 +0200

commit c0873cdbe42de789db0fc9ef15dd8383cac0cc60
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Jun 18 17:06:06 2025 +0200

commit 13bb4bac3309d473e2e68c473e5c740035c4e1bd
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Jun 18 14:38:58 2025 +0200

commit 886f9a1a602f048b8ff1e1e80b65991c3515939c
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Jun 18 14:27:22 2025 +0200

commit d1345489615b267ee4ddb481b7870b165d902d3b
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Thu Jun 12 18:09:39 2025 +0200

commit 5efe57c81a1ded160ebe85c4612bb31441ef10f1
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Tue Jun 3 10:54:17 2025 +0200

commit ef7e33cfc23be0e0393273c4805ec57f6f160f21
Author: Marcus Ortiz <marcus_ortiz@apple.com>
Date:   Tue May 20 15:59:20 2025 -0700

commit add78e5eb91d6dae525233c9d757a85f2b34d16f
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Tue May 20 18:55:31 2025 +0200

commit 5065f71080f7321066171f35dd71cb8f47a4b2b4
Author: Sofía Rodríguez <sofia_rodriguez@apple.com>
Date:   Thu May 15 17:59:55 2025 +0100

(ISSUE EXHIBITS)
commit 22f3d61e7b702d62a944b8bd4f89c00fd790e0ee
Author: QuietMisdreavus <QuietMisdreavus@users.noreply.github.com>
Date:   Fri May 9 15:52:22 2025 -0600

commit bc58ec268f2054c7646ad97625defee7b7807ce6
Author: Pat Shaughnessy <pat_shaughnessy@apple.com>
Date:   Fri May 2 07:38:49 2025 -1000

commit 03bf4d8bd11ec22f1cbb2fb298259dac84a7ea0c
Author: Sofía Rodríguez <sofia_rodriguez@apple.com>
Date:   Fri May 2 16:52:00 2025 +0100

commit 5ba3de2c2acf76b382e3a78de8aa3216a0d6d4ad
Author: QuietMisdreavus <QuietMisdreavus@users.noreply.github.com>
Date:   Tue Apr 29 15:12:15 2025 -0600

commit 10aaa0a93b889248a71f2497f5a1801a56a79cc2
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Apr 23 17:07:24 2025 +0200

commit 68bb59dc65d06a0fd07d99570a83db59cd6f40d6
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Apr 23 15:49:35 2025 +0200

commit 687bc8fb21ca41f495ce45547a2efa44c0624c38
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Apr 23 15:43:08 2025 +0200

commit 879158477e1433b6b99b9fdb9a6416682f9324ac
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Wed Apr 23 15:25:58 2025 +0200

commit ac9b204f7fa6ea4840de47b71fa80242912858f2
Author: QuietMisdreavus <QuietMisdreavus@users.noreply.github.com>
Date:   Tue Apr 15 10:57:14 2025 -0600

(ISSUE EXHIBITS)
commit 545d95180ab57a575c8321c15e045974e8b2ac1e
Author: Alex Hoppen <alex@alexhoppen.de>
Date:   Thu Apr 10 14:22:26 2025 -0700

(ISSUE DOESN’T EXHIBIT)
commit a253b4861ff76ad05cba7b6a8b1263db2d48cb27 (HEAD)
Author: David Rönnqvist <ronnqvist@apple.com>
Date:   Thu Apr 3 15:04:57 2025 +0200

The issue where this started exhibiting was in the initial branch to swift 6.2, which changed the following:

diff --git a/Package.swift b/Package.swift
index 2381b5df..5c5ac49c 100644
--- a/Package.swift
+++ b/Package.swift
@@ -134,10 +134,10 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
     // Building standalone, so fetch all dependencies remotely.
     package.dependencies += [
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.53.0"),
-        .package(url: "https://github.com/swiftlang/swift-markdown.git", branch: "main"),
-        .package(url: "https://github.com/swiftlang/swift-lmdb.git", branch: "main"),
+        .package(url: "https://github.com/swiftlang/swift-markdown.git", branch: "release/6.2"),
+        .package(url: "https://github.com/swiftlang/swift-lmdb.git", branch: "release/6.2"),
         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.2"),
-        .package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", branch: "main"),
+        .package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", branch: "release/6.2"),
         .package(url: "https://github.com/apple/swift-crypto.git", from: "3.0.0"),
         .package(url: "https://github.com/swiftlang/swift-docc-plugin.git", from: "1.2.0"),
     ]

[heckj]

I backed this up to the code in LinkResolver.resolve (https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/Infrastructure/Link%20Resolution/LinkResolver.swift#L101-L125) where the localResolver is throwing an error : PathHierarchy.Error

I splatted out some additional printf debugging for this scenario to see what I could see:

            print("unresolved reference: \(unresolvedReference) (path: \(unresolvedReference.path) (fragment: \(String(describing: unresolvedReference.fragment))) (title: \(String(describing: unresolvedReference.title)))")
            print("parent reference: \(parent) (path: \(parent.path))")
            print("resolve error: \(error)")

which is getting me the following output:

unresolved reference: swift-metrics/Snippets/basics (path: swift-metrics/Snippets/basics (fragment: nil) (title: nil)
parent reference: doc://CoreMetrics/documentation/CoreMetrics (path: /documentation/CoreMetrics)
resolve error: unknownName(partialResult: (node: SwiftDocC.PathHierarchy.Node, pathPrefix: ""), remaining: [SwiftDocC.PathHierarchy.PathComponent(full: "swift-metrics", name: "swift-metrics", disambiguation: nil), SwiftDocC.PathHierarchy.PathComponent(full: "Snippets", name: "Snippets", disambiguation: nil), SwiftDocC.PathHierarchy.PathComponent(full: "basics", name: "basics", disambiguation: nil)], availableChildren: Set(["Swift-Metrics-Extras", "RecorderHandler", "CounterHandler", "Adding-the-dependency", "Emitting-metrics-information", "Supporting-Types", "Metrics-Handlers", "Overview", "MultiplexMetricsHandler", "MetricsFactory", "Meter", "API-Architecture", "TimerHandler", "Counter", "Bootstraping", "Gauge", "Metric-types", "FloatingPointCounter", "MetricsSystem", "Recorder", "TimeUnit", "FloatingPointCounterHandler", "Selecting-a-metrics-backend-implementation-applications-only", "NOOPMetricsHandler", "Getting-started", "MeterHandler", "Timer"]))
unresolved reference: swift-metrics/Snippets/basics (path: swift-metrics/Snippets/basics (fragment: nil) (title: nil)
parent reference: doc://CoreMetrics/documentation/CoreMetrics (path: /documentation/CoreMetrics)
resolve error: unknownName(partialResult: (node: SwiftDocC.PathHierarchy.Node, pathPrefix: ""), remaining: [SwiftDocC.PathHierarchy.PathComponent(full: "swift-metrics", name: "swift-metrics", disambiguation: nil), SwiftDocC.PathHierarchy.PathComponent(full: "Snippets", name: "Snippets", disambiguation: nil), SwiftDocC.PathHierarchy.PathComponent(full: "basics", name: "basics", disambiguation: nil)], availableChildren: Set(["NOOPMetricsHandler", "Bootstraping", "CounterHandler", "Metric-types", "Overview", "Meter", "MetricsFactory", "Recorder", "MeterHandler", "Adding-the-dependency", "Supporting-Types", "Emitting-metrics-information", "FloatingPointCounter", "Metrics-Handlers", "RecorderHandler", "FloatingPointCounterHandler", "Timer", "API-Architecture", "Counter", "MetricsSystem", "MultiplexMetricsHandler", "Gauge", "TimeUnit", "Selecting-a-metrics-backend-implementation-applications-only", "TimerHandler", "Getting-started", "Swift-Metrics-Extras"]))
warning: 'swift-metrics' doesn't exist at '/CoreMetrics'
  --> index.md:42:3-42:16
40 |
41 | something here \\/
42 + @Snippet(path: "swift-metrics/Snippets/basics")
   |   ╰─suggestion: Replace 'swift-metrics' with 'Swift-Metrics-Extras'
43 | something there /\
44 |

Making that debugging output a little easier to read:

unresolved reference: swift-metrics/Snippets/basics (path: swift-metrics/Snippets/basics (fragment: nil) (title: nil)

parent reference: doc://CoreMetrics/documentation/CoreMetrics (path: /documentation/CoreMetrics)

resolve error: unknownName(
	partialResult: (node: SwiftDocC.PathHierarchy.Node, pathPrefix: ""), 
	remaining: [
		SwiftDocC.PathHierarchy.PathComponent(full: "swift-metrics", name: "swift-metrics", disambiguation: nil),
		SwiftDocC.PathHierarchy.PathComponent(full: "Snippets", name: "Snippets", disambiguation: nil),
		SwiftDocC.PathHierarchy.PathComponent(full: "basics", name: "basics", disambiguation: nil)
	],
	availableChildren: Set(["NOOPMetricsHandler", "Bootstraping", "CounterHandler", "Metric-types", "Overview","Meter", "MetricsFactory", "Recorder", "MeterHandler", "Adding-the-dependency", "Supporting-Types", "Emitting-metrics-information", "FloatingPointCounter", "Metrics-Handlers", "RecorderHandler", "FloatingPointCounterHandler", "Timer", "API-Architecture", "Counter", "MetricsSystem", "MultiplexMetricsHandler", "Gauge", "TimeUnit", "Selecting-a-metrics-backend-implementation-applications-only", "TimerHandler", "Getting-started", "Swift-Metrics-Extras"]))

[heckj]

Digging around in how the resolver processes - there's an initial pass using localResolver that looks like it should iterate through all the symbols available for that module. When I do a dump of that whole PathHierarchy structure, I noticed that it doesn't appear to include any snippets symbols. I'm unclear on if it's expected to, or not.

There's a follow up / backstop resolver that heuristically assembles sibling URLS and such, but the path that's being handed in (swift-metrics/Snippets/basics) looks like it should be expected to be found with the symbols

[d-ronnqvist]

Thanks for investing this.

Considering that the DocC commit only changes the SymbolKit branch I would try and look at what the differences are there.

Because the issue seems to be that the Snippets are never added to the link hierarchy, I would start by checking if swiftlang/swift-docc-symbolkit@d3cf1eb is included in both main and release/6.2. It looks like that was reverted the next day (swiftlang/swift-docc-symbolkit@b2eeb98) so it'd be good to check if that change is on each branch and if it's expected to be on each branch.

[heckj]

A reset of that same commit made it back in prior to the 6.2 release cut, and is included in both (swiftlang/swift-docc-symbolkit@340e83d)

Grabbing the commits there:

commit ebe89c7da4cf03ded04cd708f3399087c6f2dad7
Author: QuietMisdreavus <QuietMisdreavus@users.noreply.github.com>
Date:   Thu Jun 5 09:52:53 2025 -0600

commit ddacb655e2087fd722cb5ca2bcc49953ee267e37
Author: Alex Hoppen <alex@alexhoppen.de>
Date:   Fri Apr 25 17:16:52 2025 +0200

commit da2900bc5cbb9d194b629c31a28591441b68c452
Author: QuietMisdreavus <QuietMisdreavus@users.noreply.github.com>
Date:   Fri Apr 4 09:57:17 2025 -0600

(*) release/6.2 branch

commit 467084cd380d352abcd128b27927ecdc8cb5bae8
Author: Alex Hoppen <alex@alexhoppen.de>
Date:   Mon Mar 10 12:28:37 2025 -0700

commit 340e83dce323cba92f4bdfffb692df8aba2df102
Author: Joseph Heck <heckj@mac.com>
Date:   Mon Mar 3 07:42:23 2025 -0800

There is another commit that was included in 6.2 branch that looks like a workaround that was later reverted in the main branch, and includes the following comment with it:

-
-        userInfo[.relationshipMixinKey] = registeredMixins
+
+        // FIXME: Remove the `UserInfoValue` generic parameter when we no longer need to build swift-docc-symbolkit in
+        // a configuration that contains https://github.com/swiftlang/swift-foundation/pull/1169 but not
+        // https://github.com/swiftlang/swift/pull/79382.
+        userInfo[.relationshipMixinKey] = (registeredMixins as! UserInfoValue)```

within the register() function in SymbolKit for both Kind and Symbol. I'm don't have a sense of if this would impact loading symbols from a snippet or not, but it's something to track and potentially investigate.

[heckj]

Following up on an idea last from last night, since it's resolving correctly in main, I wanted to see where it was resolving from since there's multiple resolver paths - so that I could focus the investigation. A bit tricky doing this through a bank-shot (swift-docc-plugin invoking DocC, so it's hard to get a breakpoint slapped in there), so I temporarily added in some custom logic on main to dump the local path hierarchy for this specific reference:

        if unresolvedReference.path.contains("swift-metrics/Snippets/basics") {
            print("parent reference: \(parent) (path: \(parent.path))")
            print("unresolved reference: \(unresolvedReference) (path: \(unresolvedReference.path) (fragment: \(String(describing: unresolvedReference.fragment))) (title: \(String(describing: unresolvedReference.title)))")
            print("The local path hierarchy: ", localResolver.pathHierarchy.dump())

        }

And with that in place, the localResolver's pathHierarchy definitely includes the snippets:

│ ╰ TimerHandler
 │   ╰ protocol
 │     ╰ 947c5
 │       ╰ { s:11CoreMetrics12TimerHandlerP }
 │         ├ Implementation-requirements
 │         │ ╰ anchor
 │         │   ╰ _
 │         │     ╰ [ Implementation-requirements ]
 │         ├ Updating-a-timer
 │         │ ╰ anchor
 │         │   ╰ _
 │         │     ╰ [ Updating-a-timer ]
 │         ├ preferDisplayUnit(_:)
 │         │ ╰ method
 │         │   ├ 1ldza
 │         │   │ ╰ { s:11CoreMetrics12TimerHandlerP17preferDisplayUnityyAA04TimeG0VF : (TimeUnit) -> () }
 │         │   ╰ 8st88
 │         │     ╰ { s:11CoreMetrics12TimerHandlerPAAE17preferDisplayUnityyAA04TimeG0VF : (TimeUnit) -> () }
 │         ╰ recordNanoseconds(_:)
 │           ╰ method
 │             ╰ 12ern
 │               ╰ { s:11CoreMetrics12TimerHandlerP17recordNanosecondsyys5Int64VF : (Int64) -> () }
 ├ { swift-metrics }
 │ ╰ Snippets
 │   ╰ _
 │     ╰ _
 │       ╰ [ Snippets ]
 │         ╰ basics
 │           ╰ snippet
 │             ╰ 7bb3
 │               ╰ { $snippet__swift-metrics.basics }
 ├ [ CoreMetrics ]
 ╰ [ tutorials ]

Which is missing when I do the same code in the release/6.2 branch:

│ ╰ TimerHandler
 │   ╰ protocol
 │     ╰ 947c5
 │       ╰ { s:11CoreMetrics12TimerHandlerP }
 │         ├ Implementation-requirements
 │         │ ╰ anchor
 │         │   ╰ _
 │         │     ╰ [ Implementation-requirements ]
 │         ├ Updating-a-timer
 │         │ ╰ anchor
 │         │   ╰ _
 │         │     ╰ [ Updating-a-timer ]
 │         ├ preferDisplayUnit(_:)
 │         │ ╰ method
 │         │   ├ 1ldza
 │         │   │ ╰ { s:11CoreMetrics12TimerHandlerP17preferDisplayUnityyAA04TimeG0VF : (TimeUnit) -> () }
 │         │   ╰ 8st88
 │         │     ╰ { s:11CoreMetrics12TimerHandlerPAAE17preferDisplayUnityyAA04TimeG0VF : (TimeUnit) -> () }
 │         ╰ recordNanoseconds(_:)
 │           ╰ method
 │             ╰ 12ern
 │               ╰ { s:11CoreMetrics12TimerHandlerP17recordNanosecondsyys5Int64VF : (Int64) -> () }
 ├ [ CoreMetrics ]
 ╰ [ tutorials ]

[d-ronnqvist]

Just so that I follow; is the above comparing the same DocC commit but with different SymbolKit branches or is it comparing two different DocC branches?

[heckj]

Two different DocC branches - the first was main, the second was release/6.2. I added the same "temporary code" in the same location to each branch, built, and ran it to see what the difference would look like. I was pretty sure that the snippets should be in the localResolver, but by the end of the day yesterday I was second guessing everything.

[heckj]

I did just explore shifting around only the version symbolkit but to no effect. Using .revision to ping the version of symbol kit to exact commits, I jumped around to just before the commit that Alex did - and then advanced symbol kit up to main.

.package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", .revision("ebe89c7da4cf03ded04cd708f3399087c6f2dad7")),

Unfortunately, adjusting the commit/version of symbolkit used didn't impact whether the metrics were loaded into the local resolver or not, so I'm scratching that out as a dead end for now. I didn't see how Alex's change (later reverted) would have impacting the loading, but I suspect I'm down to tracking something else