[api-documenter] [api-extractor] Linking with multiple entrypoints is broken

[mscharley]

Summary

I know it's pretty early in experimentation, but I'm working to kludge together something that works for multiple entrypoints because the libraries we use often do have multiple entry points in practice. I'll document my experiences with that somewhere else, but this ticket is about one small discrepancy I've noticed while working through this.

1. According to TSDoc, EntryPoints should have an import path which doesn't include the leading /: https://github.com/microsoft/tsdoc/blob/main/tsdoc/src/beta/DeclarationReference.ts#L331-L333
2. But the import paths for things like {@link @mscharley/my-package/import-path#MyClass} have an import path of /import-path which breaks this check here: https://github.com/microsoft/rushstack/blob/main/libraries/api-extractor-model/src/model/ModelReferenceResolver.ts#L77-L83

These two pieces of code seem in conflict, but I don't know which is correct.

Repro steps

I can post a repro project if you want, but the only repro I have at the moment is a private project and this seems a pretty straightforward issue.

Details

The patch I'm running at the moment which seems to clear up all the issues I've run into so far is:

diff --git a/node_modules/@microsoft/api-extractor-model/lib/model/ModelReferenceResolver.js b/node_modules/@microsoft/api-extractor-model/lib/model/ModelReferenceResolver.js
index adeaaca..f23aa9c 100644
--- a/node_modules/@microsoft/api-extractor-model/lib/model/ModelReferenceResolver.js
+++ b/node_modules/@microsoft/api-extractor-model/lib/model/ModelReferenceResolver.js
@@ -45,7 +45,7 @@ class ModelReferenceResolver {
                 return result;
             }
         }
-        const importPath = declarationReference.importPath || '';
+        const importPath = declarationReference.importPath?.substring(1) || '';
         const foundEntryPoints = apiPackage.findEntryPointsByPath(importPath);
         if (foundEntryPoints.length !== 1) {
             result.errorMessage = `The import path "${importPath}" could not be resolved`;

This generates links correctly in the documentation that is generated.

More than happy to format this as a proper PR but I don't have the context for the project to know if this is the proper fix or not.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/api-extractor-model version?	7.28.14
@microsoft/tsdoc version?	0.14.2
Operating system?	Mac
Documentation target?	Hugo
Would you consider contributing a PR?	Yes
TypeScript compiler version?	5.4.5
Node.js version (node -v)?	20.12.2