Allow for emission of swift.extension symbols for extensions to external types in SymbolGraphGen

[theMomax]

This PR introduces a new mode to the Symbol Graph generation that changes how extensions to external types are handled. Since we are explicitly only talking about extensions to external types, all symbols and relationships under consideration live in Symbol Graph Files with names of the form [email protected].

Any symbols resulting from such an extension are no longer directly associated with the extended type (which does not exist in the same Symbol Graph File), but with a new kind of symbol, the swift.extension symbol. There is one such symbol for every extension block that extends an external type. This swift.extension symbol is also connected to the symbol of the type it extends via an extensionTo relationship.

These changes are directly related to this discussion about the Symbol Graph Format. This initial pitch motivates the feature and gives more context on why these changes are necessary.

List of changes:

• introduction of the swift.extension symbol and extensionTo relationship
• adding support for ExtensionDecl to the Symbol class
• adding a typeKind field to the symbol's extension mixin which indicates what kind of
  symbol was extended
• introduction of the -emit-extension-block-symbols flag, which enables the behavior
  outlined below
• adaptions to SymbolGraphASTWalker that ensure a swift.extension symbol is emitted
  for each extension to a type that does not exist in the local symbol graph
• adaptions to SymbolGraph and SymbolGraphASTWalker that ensure relationships are
  correctly associated with the swift.extension symbol instead of the original type
  declaration's (extended nominal's) symbol where applicable
• adaptions to SymbolGraphASTWalker that ensure swift.extension symbols are connected
  to their respective extended nominal's symbol using an extensionTo relationship

Overall, these changes should ensure that:

• documentation frameworks can access the documentation comments on top of extension blocks for extensions to external types
• documentation frameworks can reconstruct which members/conformances are associated with a certain extension block (and its documentation)
• documentation frameworks can know what kind of type was extended (struct/class/enum/protocol)
• legacy documentation frameworks don't observe a breaking change (as all breaking changes are hidden behind the CLI flag)

This PR can be seen as a first step to fixing SR-15410, but more changes to other repositories further up the stack will be necessary.

[QuietMisdreavus]

This looks really nice, thanks! I have a couple of minor comments. Was there anything you wanted to add to this implementation before building on it in SymbolKit and Swift-DocC?

Also, some of the test files in this PR are missing the end-of-file newline. GitHub labels this as a little ⛔ icon at the end of the file. This shouldn't affect the tests building and passing, but Git (and other tools that expect it, like Vim) will make a note of it when looking at them.

[theMomax]

@QuietMisdreavus thanks for your review! This PR is complete in terms of features. I will add/adapt a test in regards to the Clang modules and modify the conditions accordingly if necessary. Once you and @daniel-grumberg are happy with code style/quality this PR can be merged.

[QuietMisdreavus]

@swift-ci Please smoke test

[QuietMisdreavus]

@swift-ci Please smoke test

[daniel-grumberg]

@swift-ci Please smoke test

[QuietMisdreavus]

Thanks so much! This looks ready to go for me; all the comments i left are pretty minor.

...however, it does look like i introduced another merge conflict. 😭 It should be pretty straightforward to fix, and once that's done and tested, i think we can land this!

[theMomax]

Rebased, fixed conflicts, addressed your remaining comments, and squashed again. Thanks for the final review @QuietMisdreavus ! Can you please kick off the CI again?

[QuietMisdreavus]

@swift-ci Please smoke test

[QuietMisdreavus]

@theMomax Thanks so much! As soon as CI is green, i'll merge it.

[d-ronnqvist]

Apologies for the late comment. Can we also add a new element in lib/Option/features.json? That help build systems know when they have a version of the Swift compiler that supports this new flag so that they don't need to hard code what version numbers support what flags.

It doesn't have to be done in this PR if you prefer to land this now and open a new PR that update features.json.

[theMomax]

@d-ronnqvist if you don’t mind, I‘d prefer to update the features.json with my next PR, which will add support for default implementation relationships. Before that, the extension block symbol feature isn’t really „complete“ anyway. I cut that part out of this PR as the change set had become quite large already on this PR and the accompanying swift-docc PR. Don’t worry, though, the follow up PR won’t be large!

[QuietMisdreavus]

I'll go ahead and merge this, since it's all ready to go and doesn't affect anything unless you add the new flag.