Package Based Matching for Inter-Package References when performing a Merge of JSON output

[taylorb-syd]

Search Terms

Merge, JSON, Separated, Declaration, Common Documentation, Inter-Package References

Problem

When merging generated JSON output for multiple repositories to create a common documentation using --merge inter-repo reflections do not resolve. This is despite the required information being in the symbolIdMap in the form of qualifiedName. I suspect this is because the sourceFileName does not match, that or merge functionality has not implemented this despite cross-package references working within packages according to the reference implementation. Either way there appears to be enough information to match the reflections.

Example:

To show what I mean I have taken (and redacted slightly) an example from one of the documentation merges I am seeing this problem in:

Within one package we can see the following reference for a parameter:

"type": {
   "type": "reference",
   "target": {
        "sourceFileName": "node_modules/@initech/core/lib/context.ts"
        "qualifiedName": "RequestContext"
   },
   "name": "RequestContext",
   "package": "@initech/core"
}

In the output for @initech/core we have the following in the symbolIdMap:

"316": {
  "sourceFileName": "lib/context.ts",
  "qualifiedName": "RequestContext"
},

And at the root of the object we can see that packageName is correctly set to @initech/core.

Suggested Solution

If the problem is in fact the mismatched sourceFileName. We can't rely on this, however we can instead match on the packageName, which means when merging we need to make sure we preserve the packageName inside the symbol mappings.

[taylorb-syd]

I think I have started to get a good idea of how things work. Please correct any misunderstandings:

It appears that when merging projects all reflections are put into a common StableKeyMap based upon the ReflectionSymbolId class. In order to make this work, we would need to modify the way ReflectionSymbolId works to encode the packageName into it when merging and/or serializing, then we need to modify the way targets are resolved. I'm stilling get my head around how this works under the hood, so I'm still a long way away from creating a PR.

[taylorb-syd]

Thanks @Gerrit0, I can confirm that the changes made for 0.28 beta solve the underlying issue and match the proposed PR I was working on to fix this issue.