Stemming from debugging swiftlang/swift-docc#1084 -

When GraphCollector.mergeSymbolGraph(_ inputGraph: SymbolGraph, at url: URL, forceLoading: Bool = false) is called (from SymbolGraphLoader in swift-docc in my case), it uses some internal logic to determine if the symbolGraph being added is a primary source for the symbol graph symbols, or an extension.

This logic is contained in the private, static function moduleForName(_:at:), which uses the the logic of the URL having (or not) a @ symbol in it. If it does, then the symbolgraph is an extension - and if not, it's primary.

Unfortunately, this logic doesn't account for the concept of snippets - which have their own symbol graphs, and by this logic show up as "primary" in the collector. This limited logic, combined with a bit of "first one that matches" logic in swift-docc, is the heart of a non-deterministic lookup of the module name when a snippet exists, resulting in the module's isVirtual property being reported as true in the unified symbol graph, and because of that, the relevant files don't get written to disk and the preview fails to work as expected.

I believe the correct logic here would be to look for an '@' symbol, or the existence of snippet in the final path component of the URL string. Add on a double-check to look for the generator metadata of snippet extractor in the symbolgraph itself, and if it both contains snippet and is from the extractor, then report the module as an "extension" instead of "primary". (the metadata check would alleviate the corner case where the module name itself included the string snippet in it's name).